hereby 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Jake Bailey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# hereby
+
+`hereby` is a simple task runner.
+
+# Herebyfile.mjs
+
+Tasks are defined in `Herebyfile.mjs`, like:
+
+```js
+import { execa } from "execa";
+import { task } from "hereby";
+
+export const build = task({
+    name: "build",
+    run: async () => {
+        await execa("tsc", ["-b", "./src"]);
+    },
+});
+
+export const test = task({
+    name: "test",
+    dependencies: [build],
+    run: async () => {
+        await execa("node", ["./out/test.js"]);
+    },
+});
+
+export const lint = task({
+    name: "lint",
+    run: async () => {
+        await runLinter(...);
+    },
+})
+
+export const testAndLint = task({
+    name: "testAndLint",
+    dependencies: [test, lint],
+})
+
+export default testAndLint;
+```
+
+# 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.
+```
+
+# 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. 
+```
+
+# 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.
+
+If your package already sets `"type": "module"`, `Herebyfile.js` will work
+as well.

package/dist/cli/formatTasks.js

@@ -0,0 +1,28 @@
+import chalk from "chalk";
+import commandLineUsage from "command-line-usage";
+import { stringSorter, taskSorter } from "./utils.js";
+export function formatTasks(tasks, defaultTask) {
+    tasks = tasks.slice(0).sort(taskSorter);
+    const sections = [];
+    sections.push({
+        header: "Available tasks",
+        content: tasks.map((task) => {
+            const blueName = chalk.blue(task.options.name);
+            const name = task !== defaultTask ? blueName : `${blueName} (default)`;
+            const descriptionParts = [];
+            if (task.options.description) {
+                descriptionParts.push(task.options.description);
+            }
+            if (task.options.dependencies && task.options.dependencies.length > 0) {
+                const deps = task.options.dependencies
+                    .map((task) => task.options.name)
+                    .sort(stringSorter)
+                    .map((v) => chalk.blue(v));
+                descriptionParts.push(`Depends on: ${deps.join(", ")}`);
+            }
+            return { name, description: descriptionParts.join("\n") };
+        }),
+    });
+    return commandLineUsage(sections);
+}
+//# sourceMappingURL=formatTasks.js.map

package/dist/cli/index.js

@@ -0,0 +1,74 @@
+import chalk from "chalk";
+import path from "path";
+import { formatTasks } from "./formatTasks.js";
+import { findHerebyfile, loadHerebyfile } from "./loadHerebyfile.js";
+import { getUsage, parseArgs } from "./parseArgs.js";
+import { reexec } from "./reexec.js";
+import { runTasksWithCLIRunner } from "./runner.js";
+import { ExitCodeError, simplifyPath, UserError } from "./utils.js";
+export async function main(system) {
+    try {
+        await mainWorker(system);
+    }
+    catch (e) {
+        if (e instanceof ExitCodeError) {
+            system.process.exitCode = e.exitCode;
+        }
+        else if (e instanceof UserError) {
+            system.error(`${chalk.red("Error")}: ${e.message}`);
+            system.process.exitCode = 1;
+        }
+        else {
+            throw e;
+        }
+    }
+}
+async function mainWorker(system) {
+    const args = parseArgs(system.process.argv.slice(2));
+    if (args.help) {
+        system.log(getUsage());
+        return;
+    }
+    let herebyfilePath = args.herebyfile ?? (await findHerebyfile(system.process.cwd()));
+    herebyfilePath = path.resolve(system.process.cwd(), herebyfilePath);
+    if (await reexec(system, herebyfilePath)) {
+        return;
+    }
+    system.process.chdir(path.dirname(herebyfilePath));
+    const herebyfile = await loadHerebyfile(herebyfilePath);
+    if (args.printTasks) {
+        system.log(formatTasks(herebyfile.tasks, herebyfile.defaultTask));
+        return;
+    }
+    const allTasks = new Map();
+    for (const task of herebyfile.tasks) {
+        allTasks.set(task.options.name, task);
+    }
+    let tasks;
+    if (args.run && args.run.length > 0) {
+        tasks = args.run.map((name) => {
+            const task = allTasks.get(name);
+            if (!task) {
+                throw new UserError(`Task ${name} does not exist or is not exported in the Herebyfile.`);
+            }
+            return task;
+        });
+    }
+    else {
+        if (!herebyfile.defaultTask) {
+            throw new UserError("No default task defined; please specify a task name.");
+        }
+        tasks = [herebyfile.defaultTask];
+    }
+    system.log(`Using ${simplifyPath(herebyfilePath)}`);
+    try {
+        await runTasksWithCLIRunner(system, ...tasks);
+    }
+    catch {
+        // 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);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/loadHerebyfile.js

@@ -0,0 +1,74 @@
+import chalk from "chalk";
+import fs from "fs/promises";
+import path from "path";
+import { Task } from "../index.js";
+import { forEachTask } from "../utils.js";
+import { UserError } from "./utils.js";
+const filenames = ["Herebyfile", "herebyfile"];
+const extensions = ["mjs", "js"];
+const allFilenames = new Set(extensions.map((e) => filenames.map((f) => `${f}.${e}`)).flat());
+export async function findHerebyfile(dir) {
+    const root = path.parse(dir).root;
+    for (; dir !== root; dir = path.dirname(dir)) {
+        const entries = await fs.readdir(dir);
+        const matching = entries.filter((e) => allFilenames.has(e));
+        if (matching.length > 1) {
+            throw new UserError(`Found more than one Herebyfile: ${matching.join(", ")}`);
+        }
+        if (matching.length === 1) {
+            const candidate = path.join(dir, matching[0]);
+            const stat = await fs.stat(candidate);
+            if (!stat.isFile()) {
+                throw new UserError(`${matching[0]} is not a file.`);
+            }
+            return candidate;
+        }
+        if (entries.includes("package.json")) {
+            break;
+        }
+    }
+    throw new UserError("Unable to find Herebyfile.");
+}
+export async function loadHerebyfile(herebyfilePath) {
+    const herebyfile = await import(herebyfilePath);
+    const exportedTasks = new Set();
+    let defaultTask;
+    for (const [key, value] of Object.entries(herebyfile)) {
+        if (value instanceof Task) {
+            if (key === "default") {
+                defaultTask = value;
+            }
+            else if (exportedTasks.has(value)) {
+                throw new UserError(`Task "${chalk.blue(value.options.name)}" has been exported twice.`);
+            }
+            else {
+                exportedTasks.add(value);
+            }
+        }
+    }
+    if (defaultTask) {
+        exportedTasks.add(defaultTask);
+    }
+    if (exportedTasks.size === 0) {
+        throw new UserError("No tasks found. Did you forget to export your tasks?");
+    }
+    const tasks = Array.from(exportedTasks.values());
+    // We check this here by walking the DAG, as some dependencies may not be
+    // exported and therefore would not be seen by the above loop.
+    assertUniqueNames(tasks);
+    return {
+        tasks,
+        defaultTask,
+    };
+}
+function assertUniqueNames(tasks) {
+    const names = new Set();
+    forEachTask(tasks, (task) => {
+        const name = task.options.name;
+        if (names.has(name)) {
+            throw new UserError(`Task "${chalk.blue(name)}" was declared twice.`);
+        }
+        names.add(name);
+    });
+}
+//# sourceMappingURL=loadHerebyfile.js.map

package/dist/cli/parseArgs.js

@@ -0,0 +1,70 @@
+import commandLineArgs from "command-line-args";
+import commandLineUsage from "command-line-usage";
+export function parseArgs(argv) {
+    const idx = argv.indexOf("--");
+    if (idx !== -1) {
+        argv = argv.slice(0, idx);
+    }
+    const options = commandLineArgs([
+        { name: "run", multiple: true, defaultOption: true, type: String },
+        { name: "herebyfile", type: String },
+        { name: "tasks", alias: "T", type: Boolean },
+        { name: "help", alias: "h", type: Boolean },
+    ], {
+        argv,
+        stopAtFirstUnknown: true,
+    });
+    return {
+        help: options["help"],
+        run: options["run"],
+        herebyfile: options["herebyfile"],
+        printTasks: options["tasks"],
+    };
+}
+export function getUsage() {
+    const usage = commandLineUsage([
+        {
+            header: "hereby",
+            content: "A simple task runner.",
+        },
+        {
+            header: "Synopsis",
+            content: "$ hereby <task>",
+        },
+        {
+            header: "Options",
+            optionList: [
+                {
+                    name: "help",
+                    description: "Display this usage guide.",
+                    alias: "h",
+                    type: Boolean,
+                },
+                {
+                    name: "herebyfile",
+                    description: "A path to a Herebyfile. Optional.",
+                    type: String,
+                    defaultOption: true,
+                    typeLabel: "{underline path}",
+                },
+                {
+                    name: "tasks",
+                    description: "Print a listing of the available tasks.",
+                    alias: "T",
+                    type: Boolean,
+                },
+            ],
+        },
+        {
+            header: "Example usage",
+            content: [
+                "$ hereby build",
+                "$ hereby build lint",
+                "$ hereby test --skip someTest --lint=false",
+                "$ hereby --tasks",
+            ],
+        },
+    ]);
+    return usage;
+}
+//# sourceMappingURL=parseArgs.js.map

package/dist/cli/reexec.js

@@ -0,0 +1,31 @@
+import chalk from "chalk";
+import foregroundChild from "foreground-child";
+import { resolve } from "import-meta-resolve";
+import { fileURLToPath, pathToFileURL } from "url";
+export async function reexec(system, herebyfilePath) {
+    // If hereby is installed globally, but run against a Herebyfile in some
+    // other package, that Herebyfile's import will resolve to a different
+    // installation of the hereby package. There's no guarantee that the two
+    // are compatible (in fact, are guaranteed not to be as Task is a class).
+    //
+    // Rather than trying to fix this by messing around with Node's resolution
+    // (which won't work in ESM anyway), instead opt to figure out the location
+    // of hereby as imported by the Herebyfile, and fork to execute it instead.
+    //
+    // TODO: Rather than spawning a child process, perhaps we could instead
+    // import the CLI from the other version and run it.
+    const thisCLI = await resolveToPath("hereby/cli", new URL(import.meta.url));
+    const otherCLI = await resolveToPath("hereby/cli", pathToFileURL(herebyfilePath));
+    if (thisCLI === otherCLI) {
+        return false;
+    }
+    // TODO: If this turns out to be common, remove this warning.
+    system.error(`${chalk.yellow("Warning")}: re-running hereby as imported by the Herebyfile.`);
+    const args = [...system.process.execArgv, otherCLI, ...system.process.argv.slice(2)];
+    foregroundChild(system.process.execPath, args);
+    return true;
+}
+async function resolveToPath(specifier, url) {
+    return fileURLToPath(new URL(await resolve(specifier, url.toString())));
+}
+//# sourceMappingURL=reexec.js.map

package/dist/cli/runner.js

@@ -0,0 +1,42 @@
+import assert from "assert";
+import chalk from "chalk";
+import prettyMilliseconds from "pretty-ms";
+import { Runner } from "../runner.js";
+export function runTasksWithCLIRunner(system, ...tasks) {
+    return new CLIRunner({ system, concurrency: system.numCPUs }).runTasks(...tasks);
+}
+class CLIRunner extends Runner {
+    constructor(options) {
+        super(options);
+        this._errored = false;
+        this._startTimes = new WeakMap();
+        this._system = options.system;
+    }
+    onTaskStart(task) {
+        this._startTimes.set(task, Date.now());
+        if (this._errored) {
+            return; // Skip logging.
+        }
+        this._system.log(`Starting ${chalk.blue(task.options.name)}`);
+    }
+    onTaskFinish(task) {
+        if (this._errored) {
+            return; // Skip logging.
+        }
+        const took = Date.now() - checkDefined(this._startTimes.get(task));
+        this._system.log(`Finished ${chalk.green(task.options.name)} in ${prettyMilliseconds(took)}`);
+    }
+    onTaskError(task, e) {
+        if (this._errored) {
+            return; // Skip logging.
+        }
+        this._errored = true;
+        this._system.error(`Error in ${chalk.red(task.options.name)}`);
+        this._system.error(`${e}`);
+    }
+}
+function checkDefined(value) {
+    assert(value);
+    return value;
+}
+//# sourceMappingURL=runner.js.map

package/dist/cli/utils.js

@@ -0,0 +1,50 @@
+import os from "os";
+import path from "path";
+export function taskSorter(a, b) {
+    return stringSorter(a.options.name, b.options.name);
+}
+export function stringSorter(a, b) {
+    return a.localeCompare(b);
+}
+export function simplifyPath(p) {
+    let homedir = os.homedir();
+    if (!p.endsWith(path.sep)) {
+        homedir += path.sep;
+    }
+    if (p.startsWith(homedir)) {
+        p = p.slice(homedir.length);
+        return `~${path.sep}${p}`;
+    }
+    return p;
+}
+/**
+ * UserError is a special error that, when caught in the CLI will be printed
+ * as a message only, without stacktrace. Use this instead of process.exit.
+ */
+export class UserError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * When thrown, ExitCodeError causes the process to exit with a specific error code,
+ * without logging anything.
+ */
+export class ExitCodeError {
+    constructor(exitCode) {
+        this.exitCode = exitCode;
+    }
+}
+export function createSystem(process) {
+    return {
+        log(message) {
+            process.stdout.write(message + "\n");
+        },
+        error(message) {
+            process.stderr.write(message + "\n");
+        },
+        process,
+        numCPUs: os.cpus().length,
+    };
+}
+//# sourceMappingURL=utils.js.map

package/dist/cli.js

@@ -0,0 +1,5 @@
+import { main } from "./cli/index.js";
+import { createSystem } from "./cli/utils.js";
+// eslint-disable-next-line no-restricted-globals
+await main(createSystem(process));
+//# sourceMappingURL=cli.js.map

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export interface TaskOptions {
+    /**
+     * The name of the task, as referenced in logs and the CLI.
+     *
+     * This name must not start with a "-" in order to prevent conflicts
+     * with flags.
+     */
+    name: string;
+    /**
+     * A description of the task, for display in the CLI.
+     */
+    description?: string | undefined;
+    /**
+     * A list of tasks that must has been run to completion before
+     * this task can execute.
+     */
+    dependencies?: Task[] | undefined;
+    /**
+     * A function to execute when this task is run.
+     */
+    run?: (() => void | Promise<void>) | undefined;
+}
+/**
+ * A hereby Task. To get an instance, call `test`.
+ */
+export declare class Task {
+    private constructor();
+}
+/**
+ * Creates a new Task.
+ */
+export declare function task(options: TaskOptions): Task;

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * A hereby Task. To get an instance, call `test`.
+ */
+export class Task {
+    constructor(options) {
+        if (!options.name) {
+            throw new Error("Task name must not be empty.");
+        }
+        if (options.name.startsWith("-")) {
+            throw new Error('Task name must not start with "-".');
+        }
+        if (!options.dependencies?.length && !options.run) {
+            throw new Error("Task must have at run function or dependencies.");
+        }
+        this.options = options;
+    }
+    /* @internal */
+    static create(options) {
+        return new Task(options);
+    }
+}
+/**
+ * Creates a new Task.
+ */
+export function task(options) {
+    return Task.create(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/runner.js

@@ -0,0 +1,40 @@
+import PQueue from "p-queue";
+export class Runner {
+    constructor(options) {
+        this._addedTasks = new WeakMap();
+        this._queue = new PQueue({ concurrency: options?.concurrency ?? Infinity });
+    }
+    async runTasks(...tasks) {
+        await Promise.all(tasks.map((task) => {
+            const cached = this._addedTasks.get(task);
+            if (cached) {
+                return cached;
+            }
+            const promise = this._runTask(task);
+            this._addedTasks.set(task, promise);
+            return promise;
+        }));
+    }
+    async _runTask(task) {
+        this.onTaskAdd?.(task);
+        const { dependencies, run } = task.options;
+        if (dependencies) {
+            await this.runTasks(...dependencies);
+        }
+        if (!run) {
+            return;
+        }
+        return this._queue.add(async () => {
+            try {
+                this.onTaskStart?.(task);
+                await run();
+                this.onTaskFinish?.(task);
+            }
+            catch (e) {
+                this.onTaskError?.(task, e);
+                throw e;
+            }
+        });
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/utils.js

@@ -0,0 +1,13 @@
+export function forEachTask(tasks, fn, seen = new Set()) {
+    tasks.forEach(visit);
+    return;
+    function visit(task) {
+        if (seen.has(task)) {
+            return;
+        }
+        seen.add(task);
+        fn(task);
+        task.options.dependencies?.forEach(visit);
+    }
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,117 @@
+{
+    "name": "hereby",
+    "version": "1.0.0",
+    "description": "A simple task runner",
+    "repository": "github:jakebailey/hereby",
+    "type": "module",
+    "bin": "./dist/cli.js",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./cli": "./dist/cli.js",
+        "./package.json": "./package.json"
+    },
+    "author": "Jake Bailey",
+    "license": "MIT",
+    "keywords": [
+        "hereby",
+        "herebyfile",
+        "task",
+        "runner",
+        "build",
+        "gulp",
+        "make",
+        "makefile"
+    ],
+    "engines": {
+        "node": ">= 14.16"
+    },
+    "files": [
+        "README.md",
+        "LICENSE",
+        "./dist/**/*.js",
+        "!**/__tests__/**",
+        "./dist/index.d.ts",
+        "!./dist/testUtils.js"
+    ],
+    "dependencies": {
+        "chalk": "^5.0.1",
+        "command-line-args": "^5.2.1",
+        "command-line-usage": "^6.1.3",
+        "foreground-child": "^2.0.0",
+        "import-meta-resolve": "^2.1.0",
+        "p-queue": "^7.3.0",
+        "pretty-ms": "^8.0.0"
+    },
+    "devDependencies": {
+        "@ava/typescript": "^3.0.1",
+        "@tsconfig/node14": "^1.0.3",
+        "@types/command-line-args": "^5.2.0",
+        "@types/command-line-usage": "^5.0.2",
+        "@types/node": "^14.18.24",
+        "@typescript-eslint/eslint-plugin": "^5.33.1",
+        "@typescript-eslint/parser": "^5.33.1",
+        "ava": "^4.3.1",
+        "c8": "^7.12.0",
+        "cross-env": "^7.0.3",
+        "eslint": "^8.22.0",
+        "eslint-config-prettier": "^8.5.0",
+        "eslint-plugin-ava": "^13.2.0",
+        "eslint-plugin-simple-import-sort": "^7.0.0",
+        "esmock": "^1.9.4",
+        "execa": "^6.1.0",
+        "moq.ts": "^9.0.2",
+        "prettier": "^2.7.1",
+        "release-it": "^15.3.0",
+        "rimraf": "^3.0.2",
+        "tempy": "^3.0.0",
+        "typescript": "^4.7.4"
+    },
+    "packageManager": "npm@8.17.0",
+    "volta": {
+        "node": "14.20.0",
+        "npm": "8.17.0"
+    },
+    "scripts": {
+        "build": "tsc",
+        "watch": "tsc --watch",
+        "test": "ava",
+        "coverage": "c8 ava",
+        "prepack": "rimraf dist && npm run build"
+    },
+    "ava": {
+        "typescript": {
+            "rewritePaths": {
+                "src/": "dist/"
+            },
+            "compile": false
+        },
+        "environmentVariables": {
+            "NODE_OPTIONS": "--loader=esmock",
+            "NODE_NO_WARNINGS": "1",
+            "FORCE_COLOR": "0"
+        }
+    },
+    "c8": {
+        "all": true,
+        "include": "dist",
+        "reporter": [
+            "text",
+            "html",
+            "lcov"
+        ]
+    },
+    "release-it": {
+        "git": {
+            "commitMessage": "Release v${version}",
+            "tagName": "v${version}"
+        },
+        "hooks": {
+            "before:init": "npm run test"
+        }
+    }
+}