hereby 1.4.2 → 1.5.0

package/README.md

@@ -8,10 +8,15 @@
 
 `hereby` is a simple task runner.
 
-# Herebyfile.mjs
+```
+$ npm i -D hereby
+$ yarn add -D hereby
+```
+
+## Herebyfile.mjs
 
-Tasks are defined in `Herebyfile.mjs`. Exported tasks are available to run
-at the CLI, with support for `export default`.
+Tasks are defined in `Herebyfile.mjs`. Exported tasks are available to run at
+the CLI, with support for `export default`.
 
 For example:
 
@@ -39,43 +44,86 @@ export const lint = task({
     run: async () => {
         await runLinter(...);
     },
-})
+});
 
 export const testAndLint = task({
     name: "testAndLint",
     dependencies: [test, lint],
-})
+});
 
 export default testAndLint;
+
+export const bundle = task({
+    name: "bundle",
+    dependencies: [build],
+    run: async () => {
+        await execa("esbuild", [
+            "--bundle",
+            "./out/index.js",
+            "--outfile", "./out/bundled.js",
+        ]);
+    },
+});
 ```
 
-# Running tasks
+## Running tasks
 
 Given the above Herebyfile:
 
 ```
-$ hereby build  # Run only build
-$ hereby test   # Run test, which depends on build.
-$ hereby        # Run the default exported task.
+$ hereby build        # Run the "build" task
+$ hereby test         # Run the "test" task, which depends on "build".
+$ hereby              # Run the default exported task.
+$ hereby test bundle  # Run the "test" and "bundle" tasks in parallel.
 ```
 
-# Flags
+## Flags
 
 `hereby` also supports a handful of flags:
 
 ```
-  -h, --help          Display this usage guide.               
-  --herebyfile path   A path to a Herebyfile. Optional.       
-  -T, --tasks         Print a listing of the available tasks. 
+-h, --help          Display this usage guide.
+--herebyfile path   A path to a Herebyfile. Optional.
+-T, --tasks         Print a listing of the available tasks.
 ```
 
-# ESM
+## ESM
 
-`hereby` is implemented in ES modules. But, don't fret! This does not mean
-that your project must be ESM-only, only that your `Herebyfile` must be ESM
-module so that `hereby`'s `task` function can be imported. It's recommended
-to use the filename `Herebyfile.mjs` to ensure that it is treated as ESM. This
-will work in a CommonJS project; ES modules can import CommonJS modules.
+`hereby` is implemented in ES modules. But, don't fret! This does not mean that
+your project must be ESM-only, only that your `Herebyfile` must be ESM module so
+that `hereby`'s `task` function can be imported. It's recommended to use the
+filename `Herebyfile.mjs` to ensure that it is treated as ESM. This will work in
+a CommonJS project; ES modules can import CommonJS modules.
 
-If your package already sets `"type": "module"`, `Herebyfile.js` will work
-as well.
+If your package already sets `"type": "module"`, `Herebyfile.js` will work as
+well.
+
+## Caveats
+
+### No serial tasks
+
+`hereby` does not support running tasks in series; specifying multiple tasks at
+the CLI or as dependencies of another task will run them in parallel. This
+matches the behavior of tools like `make`, which like `hereby` intend to encode
+a dedpendency graph of tasks, not act as a script.
+
+In general, if you're trying to emulate a serial task, you will likely be better
+served by writing out explicit dependencies for your tasks.
+
+### Tasks only run once
+
+`hereby` will only run each task once during its execution. This means that
+tasks which consist of other tasks run in order like a script cannot be
+constructed. For example, it's not possible to run "build", then "clean", then
+"build" again within the same invocation of `hereby`, since "build" will only be
+executed once (and the lack of serial tasks prevents such a construction
+anyway).
+
+To run tasks in a specific order and more than once, run `hereby` multiple
+times:
+
+```
+$ hereby build
+$ hereby clean
+$ hereby build
+```

package/dist/cli/formatTasks.js

@@ -13,7 +13,9 @@ export function formatTasks(format, tasks, defaultTask) {
     sections.push({
         header: "Available tasks",
         content: tasks.map((task) => {
-            const name = task !== defaultTask ? chalk.blue(task.options.name) : `${chalk.green(task.options.name)} (default)`;
+            const name = task !== defaultTask
+                ? chalk.blue(task.options.name)
+                : `${chalk.green(task.options.name)} (default)`;
             const descriptionParts = [];
             if (task.options.description) {
                 descriptionParts.push(task.options.description);

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { findHerebyfile, loadHerebyfile } from "./loadHerebyfile.js";
 import { getUsage, parseArgs } from "./parseArgs.js";
 import { reexec } from "./reexec.js";
 import { Runner } from "./runner.js";
-import { ExitCodeError, simplifyPath, UserError } from "./utils.js";
+import { ExitCodeError, UserError } from "./utils.js";
 export async function main(d) {
     try {
         await mainWorker(d);
@@ -40,27 +40,34 @@ async function mainWorker(d) {
         return;
     }
     d.chdir(path.dirname(herebyfilePath));
-    if (!args.printTasks) {
-        d.log(`Using ${simplifyPath(herebyfilePath)}`);
-    }
     const herebyfile = await loadHerebyfile(herebyfilePath);
     if (args.printTasks) {
         d.log(formatTasks(args.printTasks, herebyfile.tasks, herebyfile.defaultTask));
         return;
     }
-    const tasks = selectTasks(herebyfile, args.run);
+    const tasks = selectTasks(d, herebyfile, herebyfilePath, args.run);
+    const taskNames = tasks.map((t) => t.options.name).sort().map((name) => chalk.blue(name)).join(", ");
+    d.log(`Using ${chalk.yellow(d.simplifyPath(herebyfilePath))} to run ${taskNames}`);
+    const start = Date.now();
+    let errored = false;
     try {
         const runner = new Runner(d);
         await runner.runTasks(...tasks);
     }
     catch (e) {
+        errored = true;
         // We will have already printed some message here.
         // Set the error code and let the process run to completion,
         // so we don't end up with an unflushed output.
         throw new ExitCodeError(1, e);
     }
+    finally {
+        const took = Date.now() - start;
+        d.log(`Completed ${taskNames}${errored ? chalk.red(" with errors") : ""} in ${d.prettyMilliseconds(took)}`);
+    }
 }
-export function selectTasks(herebyfile, taskNames) {
+// Exported for testing.
+export function selectTasks(d, herebyfile, herebyfilePath, taskNames) {
     const allTasks = new Map();
     for (const task of herebyfile.tasks) {
         allTasks.set(task.options.name, task);
@@ -69,7 +76,7 @@ export function selectTasks(herebyfile, taskNames) {
         return taskNames.map((name) => {
             const task = allTasks.get(name);
             if (!task) {
-                let message = `Task "${name}" does not exist or is not exported in the Herebyfile.`;
+                let message = `Task "${name}" does not exist or is not exported from ${d.simplifyPath(herebyfilePath)}.`;
                 const candidate = closest(name, Array.from(allTasks.keys()));
                 if (distance(name, candidate) < name.length * 0.4) {
                     message += ` Did you mean "${candidate}"?`;
@@ -80,7 +87,7 @@ export function selectTasks(herebyfile, taskNames) {
         });
     }
     if (!herebyfile.defaultTask) {
-        throw new UserError("No default task defined; please specify a task name.");
+        throw new UserError(`No default task has been exported from ${d.simplifyPath(herebyfilePath)}; please specify a task name.`);
     }
     return [herebyfile.defaultTask];
 }

package/dist/cli/utils.js

@@ -8,6 +8,7 @@ export function taskSorter(a, b) {
 export function stringSorter(a, b) {
     return a.localeCompare(b);
 }
+// Exported for testing.
 export function simplifyPath(p) {
     let homedir = os.homedir();
     if (!p.endsWith(path.sep)) {
@@ -53,6 +54,7 @@ export async function real() {
         cwd: process.cwd,
         // eslint-disable-next-line @typescript-eslint/unbound-method
         chdir: process.chdir,
+        simplifyPath,
         argv: process.argv,
         execArgv: process.execArgv,
         execPath: process.execPath,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "hereby",
-    "version": "1.4.2",
+    "version": "1.5.0",
     "description": "A simple task runner",
     "repository": "github:jakebailey/hereby",
     "type": "module",
@@ -53,18 +53,17 @@
         "@types/command-line-args": "^5.2.0",
         "@types/command-line-usage": "^5.0.2",
         "@types/node": "^14.18.31",
-        "@typescript-eslint/eslint-plugin": "^5.38.1",
-        "@typescript-eslint/parser": "^5.38.1",
+        "@typescript-eslint/eslint-plugin": "^5.39.0",
+        "@typescript-eslint/parser": "^5.39.0",
         "ava": "^4.3.3",
         "c8": "^7.12.0",
+        "dprint": "^0.32.1",
         "eslint": "^8.24.0",
-        "eslint-config-prettier": "^8.5.0",
         "eslint-plugin-ava": "^13.2.0",
         "eslint-plugin-simple-import-sort": "^8.0.0",
         "execa": "^6.1.0",
         "moq.ts": "^9.0.2",
-        "prettier": "^2.7.1",
-        "release-it": "^15.4.2",
+        "release-it": "^15.4.3",
         "rimraf": "^3.0.2",
         "tempy": "^3.0.0",
         "typescript": "~4.8.4"