@zukhruf/git-hooks 0.0.0-stage → 0.3.42

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+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

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# @zukhruf/git-hooks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Git hooks written in TypeScript. A pre-commit hook runs steps in order against the staged commit. The steps check the staged copy of each file with Prettier and change nothing, run `nx sync` and stage only the files that sync wrote, and build generated files when nx says that their projects are affected. A pre-push hook runs steps in order against the push. Its build step builds each pushed commit in a snapshot, never the working tree. A repo adds a step of its own as a class.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Install the hook
+
+Add the package and the repo's own Prettier:
+
+```sh
+npm install --save-dev @zukhruf/git-hooks prettier
+```
+
+Write the hook in `.husky/pre-commit.ts`, and make it executable:
+
+```ts
+#!/usr/bin/env node
+import { Format, preCommit } from '@zukhruf/git-hooks';
+
+await preCommit([new Format()]);
+```
+
+Git runs a hook by its name, and Node runs a TypeScript file only when its name ends in `.ts`. So `.husky/pre-commit` is a link to the TypeScript file. Commit the link:
+
+```sh
+chmod +x .husky/pre-commit.ts
+ln -s pre-commit.ts .husky/pre-commit
+```
+
+The hook uses `await` at the top level, so Node must read it as a module. When `package.json` has no `"type": "module"`, name the file `pre-commit.mts`, and link `.husky/pre-commit` to that name.
+
+Tell git where the hooks are, in the `prepare` script of `package.json`:
+
+```json
+{ "scripts": { "prepare": "git config core.hooksPath .husky || exit 0" } }
+```
+
+## Check the format of the staged files
+
+`Format` checks the staged copy of each staged file with the Prettier config of the repo. It skips the files that `.prettierignore` names, the files that Prettier has no parser for, and links, because the staged copy of a link is the path that it points to. When a file is not formatted, or Prettier cannot parse it, the commit stops and the hook names each file:
+
+```text
+format    2 staged files are not formatted:
+            src/app.ts
+            docs/notes.md (SyntaxError: Unexpected token (3:1))
+          Run `npx prettier --write src/app.ts docs/notes.md`, stage them, and commit again.
+✖ commit stopped by the pre-commit hook
+```
+
+The step changes no file and stages nothing. A file that is partly staged is judged as the commit holds it.
+
+## Stage the files that nx sync writes
+
+`Sync` runs `nx sync` and stages the files that it changed. The option `stage` names the files that the sync generators of the repo write. The default is `**/tsconfig*.json`. A repo with the Tailwind sync generator adds its style sheets:
+
+```ts
+import { Format, Sync, preCommit } from '@zukhruf/git-hooks';
+
+await preCommit([
+  new Sync({ stage: ['**/tsconfig*.json', '**/styles.css'] }),
+  new Format(),
+]);
+```
+
+The step does not stage a file that was changed before the hook ran, or a changed file that `stage` does not name: another session can edit the same working tree. When `nx sync` fails, the commit stops, and the hook shows the reason that nx gave.
+
+## Build generated files
+
+`Codegen` runs nx targets that write generated files, and stages those files. With `when`, it builds only when nx says that the staged files affect one of those projects:
+
+```ts
+import { Codegen, Format, Sync, preCommit } from '@zukhruf/git-hooks';
+
+await preCommit([
+  new Sync(),
+  new Codegen({
+    when: ['backend', 'frontend'],
+    run: ['backend:build', 'frontend:build'],
+    stage: ['openapi.json', 'packages/client/src'],
+  }),
+  new Format(),
+]);
+```
+
+The targets run in the order that `run` gives. When a target fails, the commit stops, and the hook shows the reason that the target gave. Put `Format` after `Codegen`, so that the generated files are checked too.
+
+## Add a step of your own
+
+A pre-commit step is a subclass of `Step<Commit>`. It names itself and gives an outcome: `this.pass()`, `this.skip(why)` or `this.fail(why)`. A fail stops the commit. `Commit` reads the staged commit: `staged()`, `files()` (the staged paths that hold file content, without links and submodules), `blob(path)`, `touches(globs)`, and `inSnapshot(work)`, which runs `work` on a copy of the staged tree in a temporary folder:
+
+```ts
+import { type Commit, Step } from '@zukhruf/git-hooks';
+
+export class DesignCheck extends Step<Commit> {
+  readonly name = 'design';
+
+  async run(commit: Commit) {
+    if (!(await commit.touches(['DESIGN.md', 'apps/**/*.css'])))
+      return this.skip('no design files staged');
+    const valid = await commit.inSnapshot((folder) => checkDesign(folder));
+    return valid
+      ? this.pass()
+      : this.fail('DESIGN.md disagrees with the styles');
+  }
+}
+```
+
+## Install the pre-push hook
+
+Git runs the pre-push hook before `git push` sends commits to a remote. Write the hook in `.husky/pre-push.ts`:
+
+```ts
+#!/usr/bin/env node
+import { Build, prePush } from '@zukhruf/git-hooks';
+
+await prePush([new Build()]);
+```
+
+Make it executable, and commit a link to it, as for the pre-commit hook:
+
+```sh
+chmod +x .husky/pre-push.ts
+ln -s pre-push.ts .husky/pre-push
+```
+
+The hook uses `await` at the top level, so Node must read it as a module. When `package.json` has no `"type": "module"`, name the file `pre-push.mts`, and link to that name. The `prepare` script in [Install the hook](#install-the-hook) tells git where both hooks are.
+
+Git gives the hook the name and the URL of the remote, and one line for each ref that the push changes. `prePush` reads them into a `Push`. It runs the steps in order and prints the outcome of each step. At the first fail, the push stops.
+
+## Build the pushed commits
+
+`Build` builds each pushed commit with the production configuration of nx. It does not build the working tree. Another session can edit the working tree while you push. An edit that is not committed is not in the push, so it cannot stop a good push, and it cannot hide a broken one.
+
+```ts
+import { Build, prePush } from '@zukhruf/git-hooks';
+
+await prePush([
+  new Build({
+    targets: ['lint', 'build'],
+    parallel: 1,
+    env: { NODE_ENV: 'production' },
+  }),
+]);
+```
+
+- `targets` are the nx targets to run on all projects. The default is `['build']`.
+- `parallel` is the number of tasks that nx runs at the same time. Without it, nx uses its own default.
+- `env` holds more environment variables for nx.
+
+Build runs `nx run-many` with `--configuration=production` and with `NX_DAEMON=false`. `env` goes to nx only, never to `npm ci`: with `NODE_ENV=production`, npm does not install the devDependencies. Build builds each pushed commit one time, also when the push sends it to more than one ref. Build gives one line for each pushed commit: built, skipped or failed. Each line names the commit:
+
+```text
+build     a1b2c3d: built 19 projects, 17 of 20 tasks from cache
+          d4e5f6a: built 19 projects, 20 of 20 tasks from cache
+          skipped: the remote already has 0b1c2d3
+```
+
+When a task fails, the push stops. The hook names the failed tasks and shows up to 20 lines of the error output of each failed task. When the output has more lines, the last line gives their number, such as `… 12 more lines`:
+
+```text
+build     a1b2c3d: 1 of 20 tasks failed: elements:build
+            packages/elements/src/lib/define.ts(34,14): error TS2322: Type 'string' is not assignable to type 'number'.
+✖ push stopped by the pre-push hook
+```
+
+A push that only deletes refs has no commit to build:
+
+```text
+build     skipped: the push only deletes refs
+```
+
+Build builds a pushed commit only when the push sends at least one commit that the remote does not have. A push of a commit that the remote has already, for example to a new branch, has nothing new to build:
+
+```text
+build     skipped: the remote already has a1b2c3d
+```
+
+Build works with npm workspaces. A pushed commit without `package-lock.json` stops the push at once. This is a setup error, so the first push shows it:
+
+```text
+build     a1b2c3d has no package-lock.json; Build works with npm workspaces
+✖ push stopped by the pre-push hook
+```
+
+In one repo, one pre-push build runs at a time. A second push waits for the first build to end, and does not fail:
+
+```text
+build     waiting for another pre-push build in this repo
+```
+
+## Where a pre-push build runs
+
+Each pushed commit is built in a snapshot: a copy of the files of that commit in a temporary folder outside the repo. The files come from the object store of git, so the snapshot holds what the commit holds, and nothing that is only in the working tree. A file that `.gitignore` names, such as `.env`, is not in the snapshot.
+
+nx runs in the snapshot, and git commands in nx work there. The hook sets `GIT_DIR` to the git folder of the repo, `GIT_WORK_TREE` to the snapshot, and `GIT_INDEX_FILE` to a temporary index that it makes from the pushed commit. Thus git sees the snapshot as a clean checkout of that commit, with no changed and no untracked files, and `nx affected --base --head` works.
+
+The snapshot uses the packages that the repo installed when they match the `package-lock.json` of the commit. Then the setup takes about 1 s. A workspace package resolves to its folder in the snapshot, not in the working tree.
+
+When the installed packages do not match the `package-lock.json` of the commit, the hook installs that lockfile in a folder of its own, and the snapshot uses that install. This is install drift: a package that the lockfile names is missing or has a different version, or a package is installed that the lockfile does not name. An extra package is drift too, because code that imports it builds here and fails in CI. Install drift occurs when a peer changed the dependencies but did not commit the change, or when the push sends a commit with other dependencies. The hook prints a line before the install, because a full install takes some time:
+
+```text
+build     a1b2c3d: the installed packages differ from package-lock.json; installing it with npm ci (first time for this lockfile)
+```
+
+The install runs `npm ci --ignore-scripts`, and then `npm rebuild` with the names of the dependencies that have install scripts. The lockfile marks these dependencies with `hasInstallScript`. Thus the install scripts of the dependencies run, such as those of esbuild and prisma. The scripts of the repo and of its workspace packages, such as `prepare`, do not run. The first push with a new lockfile waits for a full install. The next pushes with that lockfile use the same install. The hook keeps the two installs that it used last. A repo with no `node_modules` gets its install the same way.
+
+The hook keeps the installs and the nx cache of the pre-push builds in its state folder: `git-hooks` in the common git folder of the repo (`git rev-parse --git-common-dir`). Linked worktrees use the same state folder. The nx cache of the working tree (`.nx`) is not used, and the hook does not write to it. A file lock in the state folder lets one pre-push build run at a time. The hook deletes each snapshot after its build.
+
+On Windows, the snapshot links to folders with junctions, which need no administrator rights.
+
+## Add a pre-push step of your own
+
+A pre-push step is a subclass of `Step<Push>`. A step of `Step<Commit>`, such as `Format`, cannot go into `prePush`: at push time there is no staged commit.
+
+`Push` has the `remote` (`name` and `url`) and the `updates`. Each ref update has `localRef`, `localSha`, `remoteRef`, `remoteSha` and a `kind`:
+
+- `create`: the remote does not have the ref.
+- `update`: the remote has the ref, and the push changes it.
+- `delete`: the push deletes the ref from the remote.
+
+A create or an update also has a `head` and a `base`. The `head` is the local commit. The `base` is the newest commit that the remote has:
+
+- For an update, the `base` is the remote sha.
+- For a create, the `base` is the parent of the first commit that no ref of the remote has. An update gets its `base` in the same way when the remote sha is not in the local repo, for example in a force push over commits that were never fetched.
+- When the remote has the `head` already, the `base` is the `head`, and the range is empty.
+- When the remote has no commit of that history, there is no `base`, and the step must check the whole history.
+
+`push.inSnapshot(sha, work)` runs `work` on the snapshot of one commit. `work` gets the folder of the snapshot and an environment for the tools that it runs there: the git environment above, `NX_DAEMON=false`, and the nx cache of the state folder. `push.nx(sha, ...args)` runs nx in the snapshot of one commit, with the git environment above, and gives its standard output. When nx exits with a code other than 0, it throws.
+
+This step runs the tests of the projects that each pushed range affects:
+
+```ts
+import { type Push, Step } from '@zukhruf/git-hooks';
+
+export class AffectedTest extends Step<Push> {
+  readonly name = 'test';
+
+  async run(push: Push) {
+    const updates = push.updates.filter((update) => update.kind !== 'delete');
+    if (updates.length === 0) return this.skip('the push only deletes refs');
+    try {
+      for (const { base, head } of updates)
+        await push.nx(
+          head,
+          ...(base === undefined
+            ? ['run-many', '-t', 'test']
+            : ['affected', '-t', 'test', `--base=${base}`, `--head=${head}`]),
+        );
+    } catch (error) {
+      if (!(error instanceof Error)) throw error;
+      return this.fail(error.message.trimEnd());
+    }
+    return this.pass();
+  }
+}
+```
+
+Use the `base` and the `head` of each update, not `--base=origin/main --head=HEAD`. That pair checks the branch that is checked out, and a push can send other refs.

package/dist/build.d.ts

@@ -0,0 +1,15 @@
+import { type Push } from './push.ts';
+import { type Outcome, Step } from './step.ts';
+interface BuildOptions {
+    readonly targets?: readonly string[];
+    readonly parallel?: number;
+    readonly env?: Readonly<Record<string, string>>;
+}
+export declare class Build extends Step<Push> {
+    #private;
+    readonly name = "build";
+    constructor({ targets, parallel, env }?: BuildOptions);
+    run(push: Push): Promise<Outcome>;
+}
+export {};
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwB,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE/C,UAAU,YAAY;IAEpB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAG3B,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAuBD,qBAAa,KAAM,SAAQ,IAAI,CAAC,IAAI,CAAC;;IACnC,QAAQ,CAAC,IAAI,WAAW;gBAKZ,EAAE,OAAmB,EAAE,QAAQ,EAAE,GAAQ,EAAE,GAAE,YAAiB;IAOpE,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;CAgGxC"}

package/dist/build.js

@@ -0,0 +1,163 @@
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+import { MissingLockfileError } from "./push.js";
+import { runNx } from "./snapshot/nx.js";
+import { Step } from "./step.js";
+// The lines of error output that a fail shows for each failed task.
+const shownLines = 20;
+// Builds each pushed commit with the production configuration of nx, in a
+// snapshot of the commit, never in the working tree: an edit that is not
+// committed is not in the push, so it cannot stop a good push or hide a
+// broken one. A commit is built one time, also when the push sends it to more
+// than one ref, and only when the remote does not have it.
+export class Build extends Step {
+    name = 'build';
+    #targets;
+    #parallel;
+    #env;
+    constructor({ targets = ['build'], parallel, env = {} } = {}) {
+        super();
+        this.#targets = targets;
+        this.#parallel = parallel;
+        this.#env = env;
+    }
+    async run(push) {
+        const fresh = new Map();
+        for (const update of push.updates)
+            if (update.kind !== 'delete')
+                fresh.set(update.head, (fresh.get(update.head) ?? false) || update.base !== update.head);
+        if (fresh.size === 0)
+            return this.skip('skipped: the push only deletes refs');
+        const lines = [];
+        let built = false;
+        for (const [head, isNew] of fresh) {
+            if (!isNew) {
+                lines.push(`skipped: the remote already has ${head.slice(0, 7)}`);
+                continue;
+            }
+            const result = await this.#build(push, head);
+            if (result.kind === 'failed')
+                return this.fail([...lines, ...result.lines].join('\n'));
+            lines.push(result.line);
+            built = true;
+        }
+        return built ? this.pass(lines.join('\n')) : this.skip(lines.join('\n'));
+    }
+    async #build(push, head) {
+        const short = head.slice(0, 7);
+        try {
+            return await push.inSnapshot(head, async (folder, environment) => {
+                const cache = environment.NX_CACHE_DIRECTORY ?? '';
+                // A run that ends before its tasks writes no summary, so the summary
+                // of an older run must not stay.
+                await rm(join(cache, 'run.json'), { force: true });
+                const { code, stdout, stderr } = await runNx(folder, { ...environment, ...this.#env }, [
+                    'run-many',
+                    `--targets=${this.#targets.join(',')}`,
+                    '--configuration=production',
+                    ...(this.#parallel === undefined
+                        ? []
+                        : [`--parallel=${this.#parallel}`]),
+                ]);
+                const tasks = await lastRun(cache);
+                if (code === 0) {
+                    const projects = new Set(tasks.map((task) => task.projectName));
+                    const cached = tasks.filter((task) => task.cacheStatus !== 'cache-miss');
+                    return {
+                        kind: 'built',
+                        line: `${short}: built ${projects.size} projects, ${cached.length} of ${tasks.length} tasks from cache`,
+                    };
+                }
+                // nx exits with 130 when a task fails, so each code other than 0 is a
+                // fail.
+                const failed = tasks.filter((task) => task.status !== 0);
+                if (failed.length === 0)
+                    return {
+                        kind: 'failed',
+                        lines: [
+                            `${short}: nx exited with ${code}`,
+                            ...shown(`${stdout}\n${stderr}`),
+                        ],
+                    };
+                const lines = [
+                    `${short}: ${failed.length} of ${tasks.length} tasks failed: ${failed.map(taskName).join(', ')}`,
+                ];
+                for (const task of failed) {
+                    if (failed.length > 1)
+                        lines.push(`  ${taskName(task)}`);
+                    const output = await readFile(join(cache, 'terminalOutputs', task.hash), 'utf8').catch(() => '');
+                    lines.push(...shown(output, true));
+                }
+                return { kind: 'failed', lines };
+            });
+        }
+        catch (error) {
+            if (error instanceof MissingLockfileError)
+                return {
+                    kind: 'failed',
+                    lines: [
+                        `${short} has no package-lock.json; Build works with npm workspaces`,
+                    ],
+                };
+            if (!(error instanceof Error))
+                throw error;
+            return {
+                kind: 'failed',
+                lines: [`${short}: ${error.message.trimEnd()}`],
+            };
+        }
+    }
+}
+// Up to 20 lines of output, indented, and the number of the other lines. The
+// first line of a task's output is the command that nx echoes.
+function shown(output, echoed = false) {
+    const lines = stripVTControlCharacters(output)
+        .split(/\r?\n/)
+        .filter((line, index) => line.trim() !== '' && !(echoed && index === 0 && line.startsWith('> ')));
+    const more = lines.length - shownLines;
+    return [
+        ...lines.slice(0, shownLines).map((line) => `  ${line}`),
+        ...(more > 0 ? [`  … ${more} more lines`] : []),
+    ];
+}
+async function lastRun(cache) {
+    let summary;
+    try {
+        summary = JSON.parse(await readFile(join(cache, 'run.json'), 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const tasks = typeof summary === 'object' && summary !== null && 'tasks' in summary
+        ? summary.tasks
+        : undefined;
+    if (!Array.isArray(tasks))
+        throw new TypeError(`nx wrote a run.json without tasks: ${JSON.stringify(summary)}`);
+    return tasks.map((task) => {
+        if (!isTask(task))
+            throw new TypeError(`nx wrote a task that is not known: ${JSON.stringify(task)}`);
+        return task;
+    });
+}
+function isTask(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'projectName' in value &&
+        typeof value.projectName === 'string' &&
+        'target' in value &&
+        typeof value.target === 'string' &&
+        'hash' in value &&
+        typeof value.hash === 'string' &&
+        'cacheStatus' in value &&
+        typeof value.cacheStatus === 'string' &&
+        'status' in value &&
+        typeof value.status === 'number');
+}
+// The task as a person runs it: nx's task id also holds the configuration.
+function taskName(task) {
+    return `${task.projectName}:${task.target}`;
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,oBAAoB,EAAa,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAgB,IAAI,EAAE,MAAM,WAAW,CAAC;AAY/C,oEAAoE;AACpE,MAAM,UAAU,GAAG,EAAE,CAAC;AAetB,0EAA0E;AAC1E,yEAAyE;AACzE,wEAAwE;AACxE,8EAA8E;AAC9E,2DAA2D;AAC3D,MAAM,OAAO,KAAM,SAAQ,IAAU;IAC1B,IAAI,GAAG,OAAO,CAAC;IACf,QAAQ,CAAoB;IAC5B,SAAS,CAAqB;IAC9B,IAAI,CAAmC;IAEhD,YAAY,EAAE,OAAO,GAAG,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,GAAG,GAAG,EAAE,KAAmB,EAAE;QACxE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAU;QAClB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;QACzC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO;YAC/B,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;gBAC1B,KAAK,CAAC,GAAG,CACP,MAAM,CAAC,IAAI,EACX,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CACjE,CAAC;QACN,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;YAClB,OAAO,IAAI,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,CAAC,IAAI,CAAC,mCAAmC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;gBAClE,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC7C,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;gBAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3D,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACxB,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QACD,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAU,EAAE,IAAY;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE;gBAC/D,MAAM,KAAK,GAAG,WAAW,CAAC,kBAAkB,IAAI,EAAE,CAAC;gBACnD,qEAAqE;gBACrE,iCAAiC;gBACjC,MAAM,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAC1C,MAAM,EACN,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAChC;oBACE,UAAU;oBACV,aAAa,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;oBACtC,4BAA4B;oBAC5B,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS;wBAC9B,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;iBACtC,CACF,CAAC;gBACF,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;oBACf,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;oBAChE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CACzB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,KAAK,YAAY,CAC5C,CAAC;oBACF,OAAO;wBACL,IAAI,EAAE,OAAO;wBACb,IAAI,EAAE,GAAG,KAAK,WAAW,QAAQ,CAAC,IAAI,cAAc,MAAM,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,mBAAmB;qBACxG,CAAC;gBACJ,CAAC;gBACD,sEAAsE;gBACtE,QAAQ;gBACR,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;gBACzD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;oBACrB,OAAO;wBACL,IAAI,EAAE,QAAQ;wBACd,KAAK,EAAE;4BACL,GAAG,KAAK,oBAAoB,IAAI,EAAE;4BAClC,GAAG,KAAK,CAAC,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC;yBACjC;qBACF,CAAC;gBACJ,MAAM,KAAK,GAAG;oBACZ,GAAG,KAAK,KAAK,MAAM,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,kBAAkB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;iBACjG,CAAC;gBACF,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;oBAC1B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;wBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACzD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAC3B,IAAI,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,CAAC,IAAI,CAAC,EACzC,MAAM,CACP,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;oBAClB,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;gBACrC,CAAC;gBACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACnC,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,oBAAoB;gBACvC,OAAO;oBACL,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE;wBACL,GAAG,KAAK,4DAA4D;qBACrE;iBACF,CAAC;YACJ,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC3C,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;aAChD,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED,6EAA6E;AAC7E,+DAA+D;AAC/D,SAAS,KAAK,CAAC,MAAc,EAAE,MAAM,GAAG,KAAK;IAC3C,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC;SAC3C,KAAK,CAAC,OAAO,CAAC;SACd,MAAM,CACL,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACd,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAC1E,CAAC;IACJ,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC;IACvC,OAAO;QACL,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;QACxD,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,KAAa;IAClC,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YACtE,OAAO,EAAE,CAAC;QACZ,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GACT,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,IAAI,OAAO;QACnE,CAAC,CAAC,OAAO,CAAC,KAAK;QACf,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACvB,MAAM,IAAI,SAAS,CACjB,sCAAsC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAChE,CAAC;IACJ,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE;QACjC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,MAAM,IAAI,SAAS,CACjB,sCAAsC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAC7D,CAAC;QACJ,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,aAAa,IAAI,KAAK;QACtB,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;QACrC,QAAQ,IAAI,KAAK;QACjB,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAChC,MAAM,IAAI,KAAK;QACf,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAC9B,aAAa,IAAI,KAAK;QACtB,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;QACrC,QAAQ,IAAI,KAAK;QACjB,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CACjC,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,SAAS,QAAQ,CAAC,IAAU;IAC1B,OAAO,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;AAC9C,CAAC"}

package/dist/codegen.d.ts

@@ -0,0 +1,15 @@
+import type { Commit } from './commit.ts';
+import { type Outcome, Step } from './step.ts';
+interface CodegenOptions {
+    readonly when?: readonly string[];
+    readonly run: readonly string[];
+    readonly stage: readonly string[];
+}
+export declare class Codegen extends Step<Commit> {
+    #private;
+    readonly name = "codegen";
+    constructor({ when, run, stage }: CodegenOptions);
+    run(commit: Commit): Promise<Outcome>;
+}
+export {};
+//# sourceMappingURL=codegen.d.ts.map

package/dist/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE/C,UAAU,cAAc;IAGtB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAEhC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAMD,qBAAa,OAAQ,SAAQ,IAAI,CAAC,MAAM,CAAC;;IACvC,QAAQ,CAAC,IAAI,aAAa;gBAKd,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,cAAc;IAO1C,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAmB5C"}

package/dist/codegen.js

@@ -0,0 +1,38 @@
+import { Step } from "./step.js";
+// Builds generated files, such as an OpenAPI spec and the client made from it,
+// and stages them. With `when`, it builds only when nx says that one of those
+// projects is affected by the staged files: a hand-kept list of inputs would
+// miss a file, and an edit that is not staged is not part of the commit.
+export class Codegen extends Step {
+    name = 'codegen';
+    #when;
+    #run;
+    #stage;
+    constructor({ when, run, stage }) {
+        super();
+        this.#when = when;
+        this.#run = run;
+        this.#stage = stage;
+    }
+    async run(commit) {
+        if (this.#when !== undefined) {
+            const affected = new Set(await commit.affected());
+            if (!this.#when.some((project) => affected.has(project)))
+                return this.skip(`none of ${this.#when.join(', ')} is affected`);
+        }
+        try {
+            for (const target of this.#run)
+                await commit.nx('run', target);
+        }
+        catch (error) {
+            // A failed build is the step's outcome: the author reads the reason that
+            // the target gave, not a stack trace of the hook.
+            if (!(error instanceof Error))
+                throw error;
+            return this.fail(error.message.trimEnd());
+        }
+        await commit.stage(this.#stage);
+        return this.pass(`ran ${this.#run.join(', ')}; staged ${this.#stage.join(', ')}`);
+    }
+}
+//# sourceMappingURL=codegen.js.map

package/dist/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,IAAI,EAAE,MAAM,WAAW,CAAC;AAY/C,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,yEAAyE;AACzE,MAAM,OAAO,OAAQ,SAAQ,IAAY;IAC9B,IAAI,GAAG,SAAS,CAAC;IACjB,KAAK,CAAgC;IACrC,IAAI,CAAoB;IACxB,MAAM,CAAoB;IAEnC,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAkB;QAC9C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc;QACtB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;YAClD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACtD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,CAAC;YACH,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,IAAI;gBAAE,MAAM,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,yEAAyE;YACzE,kDAAkD;YAClD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,IAAI,CACd,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAChE,CAAC;IACJ,CAAC;CACF"}

package/dist/commit.d.ts

@@ -0,0 +1,15 @@
+export declare class Commit {
+    #private;
+    readonly root: string;
+    constructor(root: string, environment: NodeJS.ProcessEnv);
+    staged(): Promise<string[]>;
+    files(): Promise<string[]>;
+    blob(path: string): Promise<string>;
+    touches(globs: readonly string[]): Promise<boolean>;
+    inSnapshot<T>(work: (folder: string) => Promise<T>): Promise<T>;
+    modified(): Promise<string[]>;
+    stage(paths: readonly string[]): Promise<void>;
+    nx(...args: string[]): Promise<string>;
+    affected(): Promise<string[]>;
+}
+//# sourceMappingURL=commit.d.ts.map

package/dist/commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.d.ts","sourceRoot":"","sources":["../src/commit.ts"],"names":[],"mappings":"AAaA,qBAAa,MAAM;;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGV,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,UAAU;IAMlD,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAc3B,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAYhC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK7B,OAAO,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAOnD,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAU/D,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAM7B,KAAK,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBtC,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAiCpC"}