hereby 1.4.2 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +71 -21
  2. package/dist/cli/formatTasks.js +3 -1
  3. package/dist/cli/index.js +15 -8
  4. package/dist/cli/runner.js +10 -14
  5. package/dist/cli/utils.js +2 -1
  6. package/package.json +8 -10
package/README.md CHANGED
@@ -6,12 +6,19 @@
6
6
  [![ci](https://github.com/jakebailey/hereby/actions/workflows/ci.yml/badge.svg)](https://github.com/jakebailey/hereby/actions/workflows/ci.yml)
7
7
  [![codecov](https://codecov.io/gh/jakebailey/hereby/branch/main/graph/badge.svg?token=YL2Z1uk5dh)](https://codecov.io/gh/jakebailey/hereby)
8
8
 
9
+ > _I hereby declare thee built._
10
+
9
11
  `hereby` is a simple task runner.
10
12
 
11
- # Herebyfile.mjs
13
+ ```
14
+ $ npm i -D hereby
15
+ $ yarn add -D hereby
16
+ ```
17
+
18
+ ## Herebyfile.mjs
12
19
 
13
- Tasks are defined in `Herebyfile.mjs`. Exported tasks are available to run
14
- at the CLI, with support for `export default`.
20
+ Tasks are defined in `Herebyfile.mjs`. Exported tasks are available to run at
21
+ the CLI, with support for `export default`.
15
22
 
16
23
  For example:
17
24
 
@@ -39,43 +46,86 @@ export const lint = task({
39
46
  run: async () => {
40
47
  await runLinter(...);
41
48
  },
42
- })
49
+ });
43
50
 
44
51
  export const testAndLint = task({
45
52
  name: "testAndLint",
46
53
  dependencies: [test, lint],
47
- })
54
+ });
48
55
 
49
56
  export default testAndLint;
57
+
58
+ export const bundle = task({
59
+ name: "bundle",
60
+ dependencies: [build],
61
+ run: async () => {
62
+ await execa("esbuild", [
63
+ "--bundle",
64
+ "./out/index.js",
65
+ "--outfile=./out/bundled.js",
66
+ ]);
67
+ },
68
+ });
50
69
  ```
51
70
 
52
- # Running tasks
71
+ ## Running tasks
53
72
 
54
73
  Given the above Herebyfile:
55
74
 
56
75
  ```
57
- $ hereby build # Run only build
58
- $ hereby test # Run test, which depends on build.
59
- $ hereby # Run the default exported task.
76
+ $ hereby build # Run the "build" task
77
+ $ hereby test # Run the "test" task, which depends on "build".
78
+ $ hereby # Run the default exported task.
79
+ $ hereby test bundle # Run the "test" and "bundle" tasks in parallel.
60
80
  ```
61
81
 
62
- # Flags
82
+ ## Flags
63
83
 
64
84
  `hereby` also supports a handful of flags:
65
85
 
66
86
  ```
67
- -h, --help Display this usage guide.
68
- --herebyfile path A path to a Herebyfile. Optional.
69
- -T, --tasks Print a listing of the available tasks.
87
+ -h, --help Display this usage guide.
88
+ --herebyfile path A path to a Herebyfile. Optional.
89
+ -T, --tasks Print a listing of the available tasks.
70
90
  ```
71
91
 
72
- # ESM
92
+ ## ESM
73
93
 
74
- `hereby` is implemented in ES modules. But, don't fret! This does not mean
75
- that your project must be ESM-only, only that your `Herebyfile` must be ESM
76
- module so that `hereby`'s `task` function can be imported. It's recommended
77
- to use the filename `Herebyfile.mjs` to ensure that it is treated as ESM. This
78
- will work in a CommonJS project; ES modules can import CommonJS modules.
94
+ `hereby` is implemented in ES modules. But, don't fret! This does not mean that
95
+ your project must be ESM-only, only that your `Herebyfile` must be ESM module so
96
+ that `hereby`'s `task` function can be imported. It's recommended to use the
97
+ filename `Herebyfile.mjs` to ensure that it is treated as ESM. This will work in
98
+ a CommonJS project; ES modules can import CommonJS modules.
79
99
 
80
- If your package already sets `"type": "module"`, `Herebyfile.js` will work
81
- as well.
100
+ If your package already sets `"type": "module"`, `Herebyfile.js` will work as
101
+ well.
102
+
103
+ ## Caveats
104
+
105
+ ### No serial tasks
106
+
107
+ `hereby` does not support running tasks in series; specifying multiple tasks at
108
+ the CLI or as dependencies of another task will run them in parallel. This
109
+ matches the behavior of tools like `make`, which like `hereby` intend to encode
110
+ a dedpendency graph of tasks, not act as a script.
111
+
112
+ In general, if you're trying to emulate a serial task, you will likely be better
113
+ served by writing out explicit dependencies for your tasks.
114
+
115
+ ### Tasks only run once
116
+
117
+ `hereby` will only run each task once during its execution. This means that
118
+ tasks which consist of other tasks run in order like a script cannot be
119
+ constructed. For example, it's not possible to run "build", then "clean", then
120
+ "build" again within the same invocation of `hereby`, since "build" will only be
121
+ executed once (and the lack of serial tasks prevents such a construction
122
+ anyway).
123
+
124
+ To run tasks in a specific order and more than once, run `hereby` multiple
125
+ times:
126
+
127
+ ```
128
+ $ hereby build
129
+ $ hereby clean
130
+ $ hereby build
131
+ ```
package/dist/cli/formatTasks.js CHANGED
@@ -13,7 +13,9 @@ export function formatTasks(format, tasks, defaultTask) {
13
13
  sections.push({
14
14
  header: "Available tasks",
15
15
  content: tasks.map((task) => {
16
- const name = task !== defaultTask ? chalk.blue(task.options.name) : `${chalk.green(task.options.name)} (default)`;
16
+ const name = task !== defaultTask
17
+ ? chalk.blue(task.options.name)
18
+ : `${chalk.green(task.options.name)} (default)`;
17
19
  const descriptionParts = [];
18
20
  if (task.options.description) {
19
21
  descriptionParts.push(task.options.description);
package/dist/cli/index.js CHANGED
@@ -6,7 +6,7 @@ import { findHerebyfile, loadHerebyfile } from "./loadHerebyfile.js";
6
6
  import { getUsage, parseArgs } from "./parseArgs.js";
7
7
  import { reexec } from "./reexec.js";
8
8
  import { Runner } from "./runner.js";
9
- import { ExitCodeError, simplifyPath, UserError } from "./utils.js";
9
+ import { ExitCodeError, UserError } from "./utils.js";
10
10
  export async function main(d) {
11
11
  try {
12
12
  await mainWorker(d);
@@ -40,27 +40,34 @@ async function mainWorker(d) {
40
40
  return;
41
41
  }
42
42
  d.chdir(path.dirname(herebyfilePath));
43
- if (!args.printTasks) {
44
- d.log(`Using ${simplifyPath(herebyfilePath)}`);
45
- }
46
43
  const herebyfile = await loadHerebyfile(herebyfilePath);
47
44
  if (args.printTasks) {
48
45
  d.log(formatTasks(args.printTasks, herebyfile.tasks, herebyfile.defaultTask));
49
46
  return;
50
47
  }
51
- const tasks = selectTasks(herebyfile, args.run);
48
+ const tasks = selectTasks(d, herebyfile, herebyfilePath, args.run);
49
+ const taskNames = tasks.map((t) => t.options.name).sort().map((name) => chalk.blue(name)).join(", ");
50
+ d.log(`Using ${chalk.yellow(d.simplifyPath(herebyfilePath))} to run ${taskNames}`);
51
+ const start = Date.now();
52
+ let errored = false;
52
53
  try {
53
54
  const runner = new Runner(d);
54
55
  await runner.runTasks(...tasks);
55
56
  }
56
57
  catch (e) {
58
+ errored = true;
57
59
  // We will have already printed some message here.
58
60
  // Set the error code and let the process run to completion,
59
61
  // so we don't end up with an unflushed output.
60
62
  throw new ExitCodeError(1, e);
61
63
  }
64
+ finally {
65
+ const took = Date.now() - start;
66
+ d.log(`Completed ${taskNames}${errored ? chalk.red(" with errors") : ""} in ${d.prettyMilliseconds(took)}`);
67
+ }
62
68
  }
63
- export function selectTasks(herebyfile, taskNames) {
69
+ // Exported for testing.
70
+ export function selectTasks(d, herebyfile, herebyfilePath, taskNames) {
64
71
  const allTasks = new Map();
65
72
  for (const task of herebyfile.tasks) {
66
73
  allTasks.set(task.options.name, task);
@@ -69,7 +76,7 @@ export function selectTasks(herebyfile, taskNames) {
69
76
  return taskNames.map((name) => {
70
77
  const task = allTasks.get(name);
71
78
  if (!task) {
72
- let message = `Task "${name}" does not exist or is not exported in the Herebyfile.`;
79
+ let message = `Task "${name}" does not exist or is not exported from ${d.simplifyPath(herebyfilePath)}.`;
73
80
  const candidate = closest(name, Array.from(allTasks.keys()));
74
81
  if (distance(name, candidate) < name.length * 0.4) {
75
82
  message += ` Did you mean "${candidate}"?`;
@@ -80,7 +87,7 @@ export function selectTasks(herebyfile, taskNames) {
80
87
  });
81
88
  }
82
89
  if (!herebyfile.defaultTask) {
83
- throw new UserError("No default task defined; please specify a task name.");
90
+ throw new UserError(`No default task has been exported from ${d.simplifyPath(herebyfilePath)}; please specify a task name.`);
84
91
  }
85
92
  return [herebyfile.defaultTask];
86
93
  }
package/dist/cli/runner.js CHANGED
@@ -1,12 +1,10 @@
1
1
  import assert from "assert";
2
2
  import chalk from "chalk";
3
- import pLimit from "p-limit";
4
3
  export class Runner {
5
- constructor(d, limiter) {
4
+ constructor(d) {
6
5
  this._addedTasks = new WeakMap();
7
6
  this._errored = false;
8
7
  this._startTimes = new WeakMap();
9
- this._limiter = limiter ?? pLimit(d.numCPUs);
10
8
  this._d = d;
11
9
  }
12
10
  async runTasks(...tasks) {
@@ -28,17 +26,15 @@ export class Runner {
28
26
  if (!run) {
29
27
  return;
30
28
  }
31
- return this._limiter(async () => {
32
- try {
33
- this.onTaskStart(task);
34
- await run();
35
- this.onTaskFinish(task);
36
- }
37
- catch (e) {
38
- this.onTaskError(task, e);
39
- throw e;
40
- }
41
- });
29
+ try {
30
+ this.onTaskStart(task);
31
+ await run();
32
+ this.onTaskFinish(task);
33
+ }
34
+ catch (e) {
35
+ this.onTaskError(task, e);
36
+ throw e;
37
+ }
42
38
  }
43
39
  onTaskStart(task) {
44
40
  this._startTimes.set(task, Date.now());
package/dist/cli/utils.js CHANGED
@@ -8,6 +8,7 @@ export function taskSorter(a, b) {
8
8
  export function stringSorter(a, b) {
9
9
  return a.localeCompare(b);
10
10
  }
11
+ // Exported for testing.
11
12
  export function simplifyPath(p) {
12
13
  let homedir = os.homedir();
13
14
  if (!p.endsWith(path.sep)) {
@@ -53,13 +54,13 @@ export async function real() {
53
54
  cwd: process.cwd,
54
55
  // eslint-disable-next-line @typescript-eslint/unbound-method
55
56
  chdir: process.chdir,
57
+ simplifyPath,
56
58
  argv: process.argv,
57
59
  execArgv: process.execArgv,
58
60
  execPath: process.execPath,
59
61
  setExitCode: (code) => {
60
62
  process.exitCode = code;
61
63
  },
62
- numCPUs: os.cpus().length,
63
64
  version,
64
65
  foregroundChild,
65
66
  resolve,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hereby",
3
- "version": "1.4.2",
3
+ "version": "1.6.0",
4
4
  "description": "A simple task runner",
5
5
  "repository": "github:jakebailey/hereby",
6
6
  "type": "module",
@@ -38,13 +38,12 @@
38
38
  "./dist/index.d.ts"
39
39
  ],
40
40
  "dependencies": {
41
- "chalk": "^5.0.1",
41
+ "chalk": "^5.1.2",
42
42
  "command-line-args": "^5.2.1",
43
43
  "command-line-usage": "^6.1.3",
44
44
  "fastest-levenshtein": "^1.0.16",
45
45
  "foreground-child": "^2.0.0",
46
46
  "import-meta-resolve": "^2.1.0",
47
- "p-limit": "^4.0.0",
48
47
  "pretty-ms": "^8.0.0"
49
48
  },
50
49
  "devDependencies": {
@@ -52,19 +51,18 @@
52
51
  "@tsconfig/node14": "^1.0.3",
53
52
  "@types/command-line-args": "^5.2.0",
54
53
  "@types/command-line-usage": "^5.0.2",
55
- "@types/node": "^14.18.31",
56
- "@typescript-eslint/eslint-plugin": "^5.38.1",
57
- "@typescript-eslint/parser": "^5.38.1",
54
+ "@types/node": "^14.18.32",
55
+ "@typescript-eslint/eslint-plugin": "^5.40.0",
56
+ "@typescript-eslint/parser": "^5.40.0",
58
57
  "ava": "^4.3.3",
59
58
  "c8": "^7.12.0",
60
- "eslint": "^8.24.0",
61
- "eslint-config-prettier": "^8.5.0",
59
+ "dprint": "^0.32.1",
60
+ "eslint": "^8.25.0",
62
61
  "eslint-plugin-ava": "^13.2.0",
63
62
  "eslint-plugin-simple-import-sort": "^8.0.0",
64
63
  "execa": "^6.1.0",
65
64
  "moq.ts": "^9.0.2",
66
- "prettier": "^2.7.1",
67
- "release-it": "^15.4.2",
65
+ "release-it": "^15.5.0",
68
66
  "rimraf": "^3.0.2",
69
67
  "tempy": "^3.0.0",
70
68
  "typescript": "~4.8.4"