simplebuild - npm Package Compare versions

Comparing version 0.3.0 to 0.4.0

build.js

@@ -0,10 +1,12 @@
+#!/usr/local/bin/node
+
 // Copyright (c) 2013 Titanium I.T. LLC. All rights reserved. See LICENSE.TXT for details.
 "use strict";
 
-var promisify = require("./extensions/simplebuild-ext-promisify.js")
-	.map("../mappers/simplebuild-map-header.js")
+var promisify = require("./examples/extensions/simplebuild-ext-promisify.js")
+	.map("../examples/mappers/simplebuild-map-header.js")
 	.map;
 
-var jshint = promisify("../tasks/simplebuild-jshint.js");
-var mocha = promisify("../tasks/simplebuild-mocha.js");
+var jshint = promisify("../examples/tasks/simplebuild-jshint.js");
+var mocha = promisify("../examples/tasks/simplebuild-mocha.js");
 
@@ -11,0 +13,0 @@ jshint.validate({

examples/run-barebones.js

@@ -5,7 +5,4 @@ // Copyright (c) 2013 Titanium I.T. LLC. All rights reserved. See LICENSE.TXT for details.
 
-	var extensions = require("../mappers/simplebuild-map-header.js")
-		.map("../mappers/simplebuild-map-running.js");
+	var barebones = require("./tasks/simplebuild-barebones.js");
 
-	var barebones = extensions.map("../examples/simplebuild-barebones.js");
-
 	barebones.succeed({}, success, failure);
@@ -17,8 +14,10 @@ barebones.fail({}, success, failure);
 		console.log("Succeeded!");
+		console.log();
 	}
 
 	function failure(message) {
-		console.log("Failed! " + message);
+		console.log("Failed! Message: [" + message + "]");
+		console.log();
 	}
 
 }());

Gruntfile.js

@@ -6,3 +6,3 @@ // Copyright (c) 2013 Titanium I.T. LLC. All rights reserved. See LICENSE.TXT for details.
 
-	var simplebuild = require("./extensions/simplebuild-ext-gruntify.js")(grunt);
+	var simplebuild = require("./examples/extensions/simplebuild-ext-gruntify.js")(grunt);
 
@@ -9,0 +9,0 @@ grunt.initConfig({

Jakefile.js

@@ -6,8 +6,8 @@ // Copyright (c) 2013 Titanium I.T. LLC. All rights reserved. See LICENSE.TXT for details.
 
-var jakeify = require("./extensions/simplebuild-ext-jakeify.js")
-	.map("../mappers/simplebuild-map-header.js")
+var jakeify = require("./examples/extensions/simplebuild-ext-jakeify.js")
+	.map("../examples/mappers/simplebuild-map-header.js")
 	.map;
 
-var jshint = jakeify("../tasks/simplebuild-jshint.js");
-var mocha = jakeify("../tasks/simplebuild-mocha.js");
+var jshint = jakeify("../examples/tasks/simplebuild-jshint.js");
+var mocha = jakeify("../examples/tasks/simplebuild-mocha.js");
 
@@ -14,0 +14,0 @@

package.json

 {
   "name": "simplebuild",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Universal task automation",
@@ -5,0 +5,0 @@ "main": "lib/simplebuild.js",

README.md

@@ -1,3 +0,2 @@
-Simplebuild - Universal Task Automation for Node.js
-====================
+# Simplebuild - Universal Task Automation for Node.js
 
@@ -13,4 +12,3 @@ Tools like [Grunt](http://www.gruntjs.com) have powerful and flexible plugin ecosystems, but they only work within their walled garden. If you want to use Grunt plugins in [Jake](https://github.com/mde/jake), Jake tasks in Grunt, or write your own tool using an existing plugin... you're out of luck.
 
-Design Goals
--------
+## Design Goals
 
@@ -24,4 +22,3 @@ *Simple.* Simple to use, simple to create, and simple to extend.
 
-Examples
--------
+## Examples
 
@@ -120,4 +117,3 @@ The following examples use Simplebuild modules to lint and test some code. Note how Simplebuild adapts to provide clean, idiomatic solutions for each tool.
 
-Composability
--------
+## Composability
 
@@ -149,3 +145,3 @@ Simplebuild tasks can be used in any Node.js program, so it's easy to create tasks that depend on other tasks. If there's a module that does just what you need, no worries--just `require()` it and use it!
     ⋮                           Jakefile.js ok
-								build.js ok
+                                build.js ok
   ․․․․․․․․․․․․․․․․․․․               ⋮
@@ -165,31 +161,62 @@
 
-How It Works
--------
+## How It Works
 
 Simplebuild's magic is based on standardized, composable function signatures and a very small supporting library. There are three kinds of Simplebuild modules:
 
-* *Task modules* do the heavy lifting of task automation. For example, the `simplebuild-jshint` module uses JSHint to check files for errors. Task modules export functions that follow a standard format: `exports.taskFunction = function(options, successCallback, failureCallback) {...}`. This is the only requirement for Simplebuild tasks, other than some recommended documentation, so they're very easy to create.
+* *Task modules* do the heavy lifting of task automation. For example, the `simplebuild-jshint` module uses JSHint to check files for errors. Task modules export functions that follow a standard format: `exports.taskFunction = function(options, successCallback, failureCallback) {...}`.
 
-* *Mapper modules* take a task module as input and provide a task module as output. (They can also convert other mapper modules, which allows them to be chained together.) They're programmed to provide a generally-useful improvement to task modules. For example, the `simplebuild-map-header` module adds a header to each task. The `createMapFunction()` call in the simplebuild library makes mapper modules easy to create.
+* *Mapper modules* augment task modules in some way. For example, the `simplebuild-map-header` module adds a header to each task. Mappers output task modules, so they can be added to a build script without requiring individual tasks to be changed. Multiple mapper modules may be chained together.
 
-* *Extension modules* are like mapper modules, except that they don't have any restrictions on their input or output. They're most often used for compatibility with other coding styles. For example, `simplebuild-ext-promsify` turns Simplebuild tasks into promises, and `simplebuild-ext-gruntify` loads Simplebuild modules into Grunt.
+* *Extension modules* are like mapper modules, except that they don't have any restrictions on their input or output. They're most often used for compatibility with other coding styles or build tools. For example, `simplebuild-ext-promsify` turns Simplebuild tasks into promises, and `simplebuild-ext-gruntify` loads Simplebuild modules into Grunt.
 
 
-Creating Modules
-------
+## API
 
-For now, the easiest way to create a Simplebuild module is to copy one of the existing examples:
+In addition to the Simplebuild spec, this npm module is also a library for use by Simplebuild module authors.
 
-* Examples of task modules are in the [tasks/](tasks/) directory.
+Task module authors may wish to use this function:
+ 
+* `deglobSync(globs)`: Convert file globs into files.
 
-* Examples of mapper modules are in the [mappers/](mappers/) directory.
+Mapper and extension module authors may wish to use these functions:
 
-* Examples of extension modules are in the [stuff/](extensions/) directory. ...Nah, I'm just shitting you. They're in the [extensions/](extensions/) directory.
+* `createMapFunction(mapperFn)`: Create the `map` function required for a mapper module.
+* `mapTaskModule(module, mapperFn)`: Modify every function in a module.
 
-Eventually, the example modules will be released as standalone npm modules, but that's still in the future.
 
+### `deglobSync(globs)`
 
-Contributions
--------
+Convert file globs into files. Given an array or string, this function returns an array of filenames. Any glob (*) or globstar (**) in the `globs` parameter is converted to the actual names of files in the filesystem. If any entry in the `globs` parameter starts with an exclamation mark (!), then those files will be excluded from the result.
 
+* `globs`: A string or array containing file globs. 
+
+* **Returns**: An array of filename strings.
+
+
+### `createMapFunction(mapperFn)`
+
+Create the `map` function required for a mapper module. Use it like this:
+
+```javascript
+exports.map = createMapFunction(myMapper);
+```
+
+* `mapperFn(taskFn)`: A function that returns a task function, presumably by operating on `taskFn` in some way. 
+
+* **Returns**: A `map` function satisfying the mapper module specification.
+
+
+### `mapTaskModule(module, mapperFn)`
+
+Create a new task module based on an existing task module. Similar to `createMapFunction`, except lower level.
+
+* `module`: The task module to map.
+
+* `mapperFn(taskFn)`: A function that returns a task function, presumably by operating on `taskFn` in some way. 
+
+* **Returns**: The new task module.
+
+
+## Contributions
+
 Contributions, feedback, and discussions are welcome. Please use Github's issue tracker to open issues or pull requests.
@@ -200,4 +227,4 @@
 
-Formal Specification
--------
+## Formal Specification
+
 **[Stability](http://nodejs.org/api/documentation.html#documentation_stability_index): 1 - Experimental**
@@ -215,7 +242,7 @@
 
-`options` (REQUIRED): Configuration information. Any type of variable may be used, but an object is recommended. Each exported function MAY use this variable to determine what to do.
+`options` (REQUIRED): Configuration information. Any type of variable may be used, but an object is recommended. If a task function has no configuration, this variable is still required, but may be ignored.
 
-`success()` (REQUIRED): Callback function. Each exported function MUST call success() with no parameters when it finishes successfully.
+`success()` (REQUIRED): Callback function. Each task function MUST call success() with no parameters when it finishes successfully.
 
-`failure(messageString)` (REQUIRED): Callback function. Each exported function MUST call failure() with a brief human-readable explanation when it fails. The explanation SHOULD be less than 50 characters.
+`failure(messageString)` (REQUIRED): Callback function. Each task function MUST call failure() with a brief human-readable explanation when it fails. The explanation SHOULD be less than 50 characters.
 
@@ -225,3 +252,3 @@
 
-Task functions MUST NOT return values or throw exceptions. Instead, either the `success()` or `failure()` callback MUST be called exactly once when the task is complete. The callback MAY be called synchronously or asynchronously.
+Task functions MUST NOT return values or throw exceptions. Instead, either the `success()` or `failure()` callback MUST be called exactly once when the task is complete. The callback may be called synchronously or asynchronously.
 
@@ -232,3 +259,3 @@ Tasks that fail SHOULD provide a detailed explanation suitable for debugging the problem. If the explanation is too long to fit in the 50-character failure mesage, the task SHOULD write the details to `process.stdout` before failing. (Note that calling `console.log()` is a convenient way of writing to `process.stdout`.)
 
-Tasks that are slow or long-running MAY provide minimalistic progress output (such as periods) but SHOULD NOT provide more detailed information by default. They MAY write more if configured to do so with the `options` parameter.
+Tasks that are slow or long-running MAY provide minimalistic progress output (such as periods) but SHOULD NOT provide more detailed information by default. They MAY provide more if configured to do so with the `options` parameter.
 
@@ -238,26 +265,2 @@ Tasks SHOULD NOT write to `process.stderr` under any circumstances.
 
-#### Task Descriptors
-
-Each task function SHOULD also a `descriptors` object attached, as follows:
-
-    exports.yourFunction.descriptors = {
-        title: "The Task Name",
-        description: "A detailed description of the task function. Markdown may be used.",
-        options: { ... }  // see below
-    };
-
-`title`: A human-readable name for the function. It SHOULD be written in title case. It SHOULD be less than 22 characters. It MUST NOT be written in Markdown or any other markup language.
-
-`description`: A detailed, human-readable description of the function. The first sentence SHOULD be less than 50 characters and provide a summary description of the function. The rest of the description may be of any length and SHOULD completely describe the function. It MUST be written in Github-flavored Markdown.
-
-`options`: An object describing the possible values for the task's `options` parameter. Every property that is permitted in the `options` parameter should have a corresponding property in this descriptor. The key MUST be identical to the key used in the actual options parameter, and the value MUST be an object, as follows:
-
-    exports.yourFunction.descriptors.options.<key> = {
-        description: "A detailed description of the option. Markdown may be used."
-        // Note: future versions of this specification are likely to add additional option descriptors.
-    };
-
-`options.<key>.description`: A detailed, human-readable description of the option. The first sentence SHOULD be less than 50 characters and provide a summary description of the option. The rest of the description may be of any length and SHOULD completely describe the option. It MUST be written in Github-flavored Markdown.
-
-
 ### Mapper Modules
@@ -267,3 +270,3 @@
 
-Mapper modules SHOULD use the `createMapFunction()` API call, defined in the `simplebuild` module, to create the `map()` function. Mapper modules MUST export only one function, named `map()`. The `map()` function call itself SHOULD NOT have any side effects, but the functions `map()` returns MAY have side effects.
+Mapper modules MUST export only one function, named `map()`. The `map()` function call itself SHOULD NOT have any side effects, but the functions `map()` returns may. Mapper modules SHOULD use the `createMapFunction()` API call defined in the `simplebuild` module to create the `map()` function. 
 
@@ -274,5 +277,5 @@ The `map()` function MUST take a single parameter and return an object, as follows. These requirements are handled automatically by `createMapFunction()`.
 
-* When the parameter is any other object, it will be considered to be a task module. In this case, the `map()` function MUST return a task module object. The returned task module SHOULD have different functions and/or behavior than the provided task module.
+* When the parameter is any other object, it will be considered to be a task module. In this case, the `map()` function MUST return a task module. The returned task module SHOULD have different functions and/or behavior than the provided task module.
 
-* When the parameter is a string, it will be considered to be an npm module. In this case, the `map()` function MUST use the Node.js `require()` API call to load the module, then apply the above rules.
+* When the parameter is a string, it will be considered to be an Node.js module. In this case, the `map()` function MUST use the Node.js `require()` API call to load the module, then apply the above rules.
 
@@ -284,20 +287,18 @@
 
-Extension modules MAY export any number of functions with any signature. Exported functions MAY do anything, including accepting other Simplebuild modules as parameters. When a function supports loading task modules by name, it SHOULD also support mapper modules as well. The `createMapFunction` API call defined in the `simplebuild` module may be helpful here.
+Extension modules are unrestricted. They may export any number of functions, with any signatures, that do anything. When a function supports loading task modules by name, it SHOULD also support mapper modules as well. The `createMapFunction` API call defined in the `simplebuild` module may be helpful here.
 
 
-To Do
------
+## To Do
+
 Things that still need work:
-
-Change before release:
-- Modify examples to use new descriptor spec
-
 - When creating a module, the options and parameters need a lot of checking in `index.js`. Writing tests for this behavior is particularly tedious and repetitive. Create helper methods for this that take advantage of descriptors.
-- Should messages be written to stderr instead of stdout?
-- Could creation of modules' readme file be automated, particularly the "usage" and "examples" sections?
+- Should messages be written to stderr instead of stdout? Or perhaps some sort of 'reporter' spec
 - Pull `__test_files.js` out of simplebuild-jshint into its own module or helper
 - Pull `expectSuccess()` and `expectFailure()` out of simplebuild-jshint (_index_test.js)
+- The examples use an out-of-date version of the spec. In particular, they rely on descriptors, which have been removed from the spec for now.
 
-Version History
----------------
+
+## Version History
+
+* 0.4.0: Removed descriptors for now, updated documentation
 * 0.3.0: Reworked descriptors
@@ -307,12 +308,22 @@ * 0.2.0: Fleshed out spec further, made library work as proper npm module
 
-Credits
--------
+
+## Credits
+
 Simplebuild is a project of [Let's Code: Test-Driven JavaScript](http://www.letscodejavascript.com), a screencast on professional, rigorous JavaScript development. Created by James Shore.
 
 
-License
--------
+### Release Process
+
+1. Update version history in readme and check in
+2. Ensure clean build using all examples: `./jake.sh && ./grunt.sh && node build.js`
+3. Update npm version: `npm version [major|minor|patch]`
+4. Release to npm: `npm publish`
+5. Release to github: `git push && git push --tags`
+
+
+## License
+
 The MIT License (MIT)
 
-Copyright (c) 2013-2014 James Shore
+Copyright (c) 2013-2015 James Shore
 
@@ -319,0 +330,0 @@ Permission is hereby granted, free of charge, to any person obtaining a copy

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Number of package files

22

increased by4.76%

Lines of code

549

increased by0.18%

Number of lines in readme file

334

increased by3.41%

Worsened metrics

Total package byte prevSize

33891

decreased by-0.5%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes