@intentius/chant 0.79.0 → 0.81.0

package/dist/workspace/trust/ssh-commit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The first attestor: ssh-signed commits, checked against the signers the
+ * base policy lists (#2524 D5, ws-001).
+ *
+ * It does not ask `git verify-commit`. That would read `gpg.ssh.program`,
+ * `gpg.ssh.allowedSignersFile` and the rest from git config, which whoever
+ * controls the machine can set, and it passes the commit's own date to
+ * ssh-keygen as the verification time. Instead it takes the signature and the
+ * signed payload out of the commit object itself and hands them to
+ * `ssh-keygen -Y verify` with a signers file built from the base policy, in
+ * the `git` namespace.
+ */
+import type { CommitAttestor } from "./attestor.js";
+import { type Signer } from "./policy.js";
+/** A commit object split into its signed payload and its signature. */
+export interface SignedCommit {
+    /** The bytes the signature covers: the commit object without its signature header. */
+    payload: Buffer;
+    /** The armored signature, or undefined when the commit is unsigned. */
+    signature?: string;
+}
+/**
+ * Split a raw commit object. `header` is `gpgsig` in a SHA-1 repository and
+ * `gpgsig-sha256` in a SHA-256 one; git removes exactly that header, with its
+ * continuation lines, to get the bytes it signed.
+ */
+export declare function splitSignedCommit(raw: Buffer, header?: string): SignedCommit;
+/**
+ * Check a detached ssh signature over `payload` in `namespace` against
+ * `signers`. Shared with the rotation check (#2553), which signs signer sets
+ * in their own namespace so a commit signature can never stand in for one.
+ */
+export declare function verifySshSignature(signers: Signer[], payload: Buffer, signature: string, namespace: string): {
+    ok: true;
+    principal: string;
+    key?: string;
+} | {
+    ok: false;
+    missing: boolean;
+    reason: string;
+};
+export declare const sshCommitAttestor: CommitAttestor;
+//# sourceMappingURL=ssh-commit.d.ts.map

package/dist/workspace/trust/ssh-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh-commit.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/ssh-commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAsC,cAAc,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAwB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAI7D,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAW,GAAG,YAAY,CAsB9E;AAmBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAuBjG;AAED,eAAO,MAAM,iBAAiB,EAAE,cAW/B,CAAC"}

package/dist/workspace/trust/test-repo.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Test support for the trust modules: throwaway git repositories whose commits
+ * are signed with throwaway ssh keys. Isolated from the user's git config, so a
+ * developer's own signing setup never leaks into a test.
+ */
+export declare const hasSshKeygen: boolean;
+export interface Key {
+    name: string;
+    /** Private key file. */
+    file: string;
+    /** `ssh-ed25519 AAAA...`, no comment. */
+    pub: string;
+}
+export declare class TestRepo {
+    readonly dir: string;
+    private readonly home;
+    private readonly scratch;
+    constructor(label: string);
+    env(extra?: Record<string, string>): NodeJS.ProcessEnv;
+    git(args: string[], opts?: {
+        env?: Record<string, string>;
+        input?: string | Buffer;
+    }): string;
+    key(name: string): Key;
+    write(path: string, text: string): void;
+    /** Stage everything and commit, signed with `key` when given. Returns the commit id. */
+    commit(message: string, key?: Key, env?: Record<string, string>): string;
+    head(): string;
+    /**
+     * Write a commit object by hand: the current index's tree, `HEAD` as parent,
+     * and `signature` spliced in as the gpgsig header. Returns the new commit,
+     * which HEAD then points at.
+     */
+    forgeCommit(message: string, sign: (payload: Buffer) => string): string;
+    /** An ssh signature over `payload` in `namespace`, by `key`. */
+    sshSign(key: Key, payload: Buffer, namespace: string): string;
+    cleanup(): void;
+}
+/** A record kind reading `records/*.md`, and its schema, written into `repo`. */
+export declare function writeRecordKind(repo: TestRepo): string;
+export declare function note(id: string, body?: string): string;
+//# sourceMappingURL=test-repo.d.ts.map

package/dist/workspace/trust/test-repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-repo.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/test-repo.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,eAAO,MAAM,YAAY,SAA2E,CAAC;AAErG,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,QAAQ;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,KAAK,EAAE,MAAM;IASzB,GAAG,CAAC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,CAAC,UAAU;IAc1D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAO,GAAG,MAAM;IAIjG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAOtB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKvC,wFAAwF;IACxF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM;IAO5E,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM;IAgBvE,gEAAgE;IAChE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAO7D,OAAO,IAAI,IAAI;CAGhB;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAqBtD;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CAElD"}

package/dist/workspace/trust/verify-cli.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `chant workspace verify [--base <rev>] [--head <rev>] [--require attested] [--json]`
+ * (#2547): check a change against the trust policy at its base. See ./verify.ts.
+ *
+ * Exit 0 when the change passes, 1 when it does not or cannot be checked.
+ */
+import type { CommandContext } from "../../cli/registry.js";
+export declare function runWorkspaceVerify(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=verify-cli.d.ts.map

package/dist/workspace/trust/verify-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-cli.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/verify-cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAOzD,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB7E"}

package/dist/workspace/trust/verify.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Verify a change against the policy at its base (#2524 D5, Threat model).
+ *
+ * This is what CI runs on a protected branch: every commit in `base..head` is
+ * asked of the attestors with the policy read at base, so nothing the change
+ * does to its own copy of the policy counts. A change that edits the policy
+ * (the signers file or `.chant/trust.json`) is a protected write: every commit
+ * that touches those files must be attested by a signer the base policy
+ * trusts, and by an admin when the base policy grants the admin role.
+ *
+ * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
+ * check passes and says so, unless `--require attested` asks for more.
+ */
+import { type CommitAttestor, type ProvenanceLevel } from "./attestor.js";
+import { type BaseSource, type RecordProvenance } from "./provenance.js";
+import { type ExcludedSigner } from "./policy.js";
+export interface CommitVerdict extends RecordProvenance {
+    commit: string;
+    subject: string;
+    /** A merge that changes nothing of its own; its parents are checked instead. */
+    skipped?: string;
+}
+export interface ProtectedWrite {
+    commit: string;
+    paths: string[];
+    level: ProvenanceLevel;
+    principal?: string;
+    allowed: boolean;
+    reason: string;
+}
+export interface ChangeReport {
+    base: string | null;
+    baseFrom: BaseSource | null;
+    head: string | null;
+    policy: {
+        active: boolean;
+        signersPath: string;
+        principals: string[];
+        excluded: ExcludedSigner[];
+        writers: string[];
+        problems: string[];
+    };
+    require: ProvenanceLevel | null;
+    commits: CommitVerdict[];
+    protectedPaths: string[];
+    /** Protected paths whose content differs between the merge base and head. */
+    protectedChanged: string[];
+    protectedWrites: ProtectedWrite[];
+    notes: string[];
+    failures: string[];
+    ok: boolean;
+}
+export interface VerifyOptions {
+    repo: string;
+    base?: string;
+    head?: string;
+    require?: ProvenanceLevel;
+    attestors: readonly CommitAttestor[];
+}
+/**
+ * Commits in `range` that change any of `paths`, each with the paths it
+ * changes. Merges count only for what they change beyond every parent.
+ */
+export declare function commitsTouching(repo: string, range: string, paths: string[]): Map<string, string[]>;
+export declare function verifyChange(opts: VerifyOptions): ChangeReport;
+//# sourceMappingURL=verify.d.ts.map

package/dist/workspace/trust/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAA+C,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACnH,OAAO,EAAiC,KAAK,cAAc,EAAoB,MAAM,UAAU,CAAC;AAEhG,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE;QACN,MAAM,EAAE,OAAO,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAUnG;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAqG9D"}

package/dist/workspace/which-chant.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Where a workspace read starts, and which chant does it (#2536; #2524 D15,
+ * ws-016, ws-021).
+ *
+ * {@link locateWorkspace} finds the declaration from a directory, in the
+ * working tree or in one commit's git objects (`--at <rev>`), and gives the
+ * tree every read-contract command reads from.
+ *
+ * Which chant reads the declaration: the root's. The root names its chant by
+ * pinning `@intentius/chant` in the declaration's `pins`. When it pins one,
+ * that version reads the declaration, and any other chant refuses with
+ * `root-chant-required` (`parseDeclaration`'s `rootChant` option). The CLI
+ * first hands the whole command to the pinned chant when the root has it
+ * installed ({@link handToRootChant}), so a user sees the refusal only when
+ * it isn't. When the root pins no chant, the reader's own chant reads the
+ * declaration if it meets `minReader`, and refuses with `reader-too-old`
+ * otherwise. Members are always read by their own toolchains.
+ */
+import { type WorkspaceTree } from "./tree.js";
+export interface LocatedWorkspace {
+    /** The files, rooted at the workspace root. */
+    tree: WorkspaceTree;
+    /** The workspace root relative to the git root, `"."` for the git root itself. Absolute outside git. */
+    root: string;
+    /** The workspace root on disk, where pinned packages and toolchains are installed. Also for `--at`. */
+    rootOnDisk: string;
+    /** The full commit id for `--at`, or null for the working tree. */
+    at: string | null;
+    /** The top of the git repository, when there is one. */
+    top: string | undefined;
+}
+/**
+ * Find the workspace whose declaration is nearest above `cwd`, in the working
+ * tree or at revision `at`. Throws a {@link WorkspaceReadError}:
+ * `declaration-missing`, or for `--at`, `not-a-git-repository` and
+ * `revision-unknown`.
+ */
+export declare function locateWorkspace(cwd: string, at?: string): LocatedWorkspace;
+/**
+ * The `bin/chant` of `@intentius/chant` at `version`, installed where the
+ * workspace root resolves packages. Undefined when it isn't installed there,
+ * or is installed at another version.
+ */
+export declare function rootChantBin(rootOnDisk: string, version: string): string | undefined;
+/** Set in the environment of a command handed to the root's chant, so it is handed on once at most. */
+export declare const HANDED_TO_ROOT_ENV = "CHANT_WORKSPACE_ROOT_CHANT";
+/** The version the declaration at `located` pins for `@intentius/chant`, or undefined. Never throws. */
+export declare function declaredChantPin(located: LocatedWorkspace): string | undefined;
+/**
+ * Hand a read-contract command to the root's chant (ws-021). When the
+ * declaration above `cwd` (at `at`, for `--at`) pins a chant other than this
+ * one, and the root has that chant installed, run the same command line
+ * under it and return its exit code. Otherwise return undefined, and this
+ * chant runs the command: it reads the declaration itself, or refuses with
+ * `root-chant-required` when the pinned chant isn't installed.
+ */
+export declare function handToRootChant(cwd: string, at: string | undefined, argv?: string[]): Promise<number | undefined>;
+//# sourceMappingURL=which-chant.d.ts.map

package/dist/workspace/which-chant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"which-chant.d.ts","sourceRoot":"","sources":["../../src/workspace/which-chant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,OAAO,EAA+C,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEzF,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,IAAI,EAAE,aAAa,CAAC;IACpB,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,wDAAwD;IACxD,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAgC1E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcpF;AAED,uGAAuG;AACvG,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAE/D,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAY9E;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoB9I"}

package/dist/workspace/workspace-kinds.schema.json

@@ -0,0 +1,133 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://intentius.io/chant/schemas/workspace/kinds/v1/workspace-kinds.schema.json",
+    "title": "workspace-kinds.json",
+    "description": "Member kinds a plugin supplies (#2524 D3, #2535, ws-031). A package publishes this file as data at its ./workspace-kinds subpath. chant reads it with the file system and never imports the package, so reading kinds never loads a lexicon.",
+    "type": "object",
+    "required": [
+        "schema",
+        "kinds"
+    ],
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "description": "An editor hint. chant ignores it."
+        },
+        "$comment": {
+            "type": "string",
+            "description": "A note for people. chant ignores it."
+        },
+        "schema": {
+            "const": 1,
+            "description": "The kinds format version."
+        },
+        "kinds": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "$ref": "#/$defs/kind"
+            }
+        }
+    },
+    "patternProperties": {
+        "^x-": true
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "kind": {
+            "type": "object",
+            "required": [
+                "name",
+                "description",
+                "precedence",
+                "probe"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]{0,39}$",
+                    "description": "The kind's name, as a member's kind field names it. chant, workspace, other and examples are built in and can't be supplied."
+                },
+                "description": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "One line saying what the member's directory holds, for listings and error messages."
+                },
+                "precedence": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 999,
+                    "description": "When the probes of several kinds claim one directory, the highest precedence decides. Two claiming kinds with the same highest precedence are a tie, and a tie fails. The built-in chant kind has 500 and workspace has 1000."
+                },
+                "probe": {
+                    "$ref": "#/$defs/probe"
+                },
+                "outputs": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "description": "The outputs every member of this kind exposes as link targets (#2524 D6, #2539). A member entry of the kind may list more in its own outputs field. Without this field the kind exposes only what each entry lists.",
+                    "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 255,
+                        "pattern": "^[^\\u0000-\\u001f]+$"
+                    }
+                }
+            },
+            "patternProperties": {
+                "^x-": true
+            },
+            "additionalProperties": false
+        },
+        "probe": {
+            "type": "object",
+            "description": "What the probe checks in a member's directory. It runs no code. It passes when any of its clauses does, and it needs at least one.",
+            "minProperties": 1,
+            "properties": {
+                "anyFile": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "description": "The directory passes when a file matching one of these names sits directly in it. A * in a name matches any run of characters, so *.tf matches every Terraform file.",
+                    "items": {
+                        "$ref": "#/$defs/fileName"
+                    }
+                },
+                "anyBlock": {
+                    "type": "object",
+                    "description": "The directory passes when a file directly in it, whose name matches one of in, has a line opening an unlabelled block named in blocks: leading space, the name, optional space, then {. No file is parsed.",
+                    "required": [
+                        "in",
+                        "blocks"
+                    ],
+                    "properties": {
+                        "in": {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "items": {
+                                "$ref": "#/$defs/fileName"
+                            }
+                        },
+                        "blocks": {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "items": {
+                                "type": "string",
+                                "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$"
+                            }
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "fileName": {
+            "type": "string",
+            "description": "A file name, with no directory part. A * matches any run of characters.",
+            "pattern": "^(?!\\.\\.?$)[^/\\\\]+$"
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.79.0",
+  "version": "0.81.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -49,6 +49,7 @@
       "types": "./dist/cli/index.d.ts",
       "default": "./src/cli/index.ts"
     },
+    "./workspace/*.schema.json": "./src/workspace/*.schema.json",
     "./cli/*": {
       "development": "./src/cli/*.ts",
       "types": "./dist/cli/*.d.ts",
@@ -91,6 +92,7 @@
   },
   "dependencies": {
     "@dagrejs/dagre": "^3.0.0",
+    "ajv": "^8.20.0",
     "esbuild": "^0.28.1",
     "fflate": "^0.8.2",
     "js-yaml": "^4.3.1",
@@ -100,8 +102,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cdktn/hcl2json": "^0.24.0",
-    "ajv": "^8.20.0"
+    "@cdktn/hcl2json": "^0.24.0"
   },
   "overrides": {
     "esbuild": "^0.28.1"

package/src/audit/core.ts

@@ -27,6 +27,7 @@ import { applyInlineSuppressions, type SuppressionMetaFinding } from "../lint/su
 import type { SerializerResult } from "../serializer";
 import type { AuditEntitiesInput, LexiconPlugin } from "../lexicon";
 import type { Declarable } from "../declarable";
+import { lexiconModulePath, lexiconPackagesToInstall, lexiconSourceLabel } from "../lexicon-module";
 
 /**
  * The lexicon whose post-synth checks run against an audited file. Any lexicon
@@ -155,9 +156,19 @@ async function load(names: string[]): Promise<LexiconPlugin[]> {
     const { loadPlugins } = await import("../cli/plugins");
     return await loadPlugins(names);
   } catch (err) {
-    const pkgs = names.map((n) => `@intentius/chant-lexicon-${n}`).join(" ");
+    const detail = err instanceof Error ? err.message : String(err);
+    // chant#2578 — a lexicon declared by path in chant.config.ts has no
+    // package: name its module and print no install line for it.
+    const pkgs = lexiconPackagesToInstall(names);
+    const paths = names.filter((n) => lexiconModulePath(n) !== undefined).map((n) => lexiconSourceLabel(n));
+    if (pkgs.length === 0) {
+      throw new MissingLexiconError(
+        `Could not load the lexicon module ${paths.join(", ")} needed to audit ${names.join("/")} workflows.\n(${detail})`,
+      );
+    }
+    const fromPath = paths.length > 0 ? ` The lexicon module ${paths.join(", ")} is declared by path and has nothing to install.` : "";
     throw new MissingLexiconError(
-      `Missing lexicon package needed to audit ${names.join("/")} workflows. Install it with: npm i ${pkgs}\n(${err instanceof Error ? err.message : String(err)})`,
+      `Missing lexicon package needed to audit ${names.join("/")} workflows. Install it with: npm i ${pkgs.join(" ")}${fromPath}\n(${detail})`,
     );
   }
 }

package/src/audit/discover.ts

@@ -34,13 +34,16 @@
  *     normalized to a JSON string here.
  */
 
-import { readdirSync, readFileSync, statSync } from "fs";
+import { readFileSync, statSync } from "fs";
 import { basename, join, relative, resolve } from "path";
 import { parseYAML } from "../yaml";
 import type { LexiconPlugin } from "../lexicon";
 import type { AuditInput, AuditLexicon } from "./core";
 import { isNginxConfigPath } from "./nginx";
-import { gitignoreCoversTerraformState, isTerraformStatePath } from "./terraform-state";
+import { walkDiscovery } from "../discovery/walk";
+import { findProjectConfig } from "../project-root";
+import type { DiscoveryGlobs } from "../config";
+import { gitignoreCoversTerraformState, isTerraformStatePath, nestedGitignoreCovering } from "./terraform-state";
 
 /** Lexicons the auditor knows how to detect and run checks for. */
 export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm", "fountain", "terraform"] as const;
@@ -69,40 +72,65 @@ export async function loadAuditPlugins(names: readonly string[] = AUDIT_LEXICONS
   return plugins;
 }
 
-const WALK_SKIP = new Set(["node_modules", ".git", "dist"]);
 /** Terraform's local working directory: recorded by the walk, never entered (TF023). */
 const TERRAFORM_WORK_DIR = ".terraform";
-/** Dot-directories the walk descends into anyway (CI lives here). */
-const WALK_DOT_DIRS = new Set([".github", ".forgejo"]);
-const MAX_WALK_FILES = 1000;
+/**
+ * How many files the local walk takes before it stops. Every file it reaches
+ * counts, candidate or not, so a tree with a large `docs/` or `assets/` can hit
+ * it long before a thousand auditable files. `--max-files` raises it (#2528).
+ */
+export const DEFAULT_MAX_WALK_FILES = 1000;
 /** Skip absurdly large files before parsing — mirrors the fetch layer's caps. */
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 
-/** Recursively collect file paths under a root, skipping noise dirs. */
-function walkFiles(dir: string, out: string[]): void {
-  if (out.length >= MAX_WALK_FILES) return;
-  let entries;
+/**
+ * The project's `exclude`/`include` globs for the audit walk, read from a
+ * `chant.config.json` only. The audit reads repositories it has no reason to
+ * trust, so it never runs a `chant.config.ts` to find them.
+ */
+function auditGlobs(root: string): DiscoveryGlobs | undefined {
+  const { dir, configPath } = findProjectConfig(root);
+  if (!configPath?.endsWith(".json")) return undefined;
+  let raw: unknown;
   try {
-    entries = readdirSync(dir, { withFileTypes: true });
+    raw = JSON.parse(readFileSync(configPath, "utf-8"));
   } catch {
-    return;
-  }
-  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
-    if (out.length >= MAX_WALK_FILES) return;
-    if (e.name.startsWith(".") && e.isDirectory() && !WALK_DOT_DIRS.has(e.name)) {
-      // `.terraform/` is never descended into: it is machine-generated,
-      // routinely hundreds of megabytes of provider binaries, and nothing in
-      // it is worth reading. Its presence is itself the finding (TF023), so
-      // the directory path alone is recorded and `collectCandidates` hands it
-      // on with no content.
-      if (e.name === TERRAFORM_WORK_DIR) out.push(join(dir, e.name));
-      continue;
-    }
-    if (WALK_SKIP.has(e.name)) continue;
-    const full = join(dir, e.name);
-    if (e.isDirectory()) walkFiles(full, out);
-    else out.push(full);
+    return undefined;
   }
+  const list = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string" && x !== "") : []);
+  const exclude = list((raw as Record<string, unknown>)?.exclude);
+  const include = list((raw as Record<string, unknown>)?.include);
+  return exclude.length === 0 && include.length === 0 ? undefined : { root: dir, exclude, include };
+}
+
+/**
+ * Collect file paths under a root through the one discovery walk
+ * (`../discovery/walk.ts`, #2527), sorted per directory.
+ *
+ * The audit's own departures from the other walkers: `.github` and `.forgejo`
+ * are entered, since they hold the CI files it audits; `.terraform/` is
+ * recorded but never entered, since it is machine-generated, routinely
+ * hundreds of megabytes of provider binaries, and its presence is itself the
+ * finding (TF023); and Terraform state paths are left to TF023's own
+ * `.gitignore` reading rather than dropped for being git-ignored.
+ *
+ * Stops at `state.max` paths. Once full it keeps looking only until it meets
+ * one more path it would have taken, which is what sets `truncated`: a tree of
+ * exactly `max` files, or one whose remaining entries are all skipped
+ * directories, was not truncated.
+ */
+function walkFiles(root: string, state: { max: number; truncated: boolean }, excludeDirs?: readonly string[]): string[] {
+  return walkDiscovery({
+    walker: "audit",
+    root,
+    excludeDirs,
+    globs: auditGlobs(root),
+    sorted: true,
+    limit: state,
+    takeSkippedDir: (name) => name === TERRAFORM_WORK_DIR,
+    keepIgnored: (full) => isTerraformStatePath(relative(root, full)),
+    accept: () => true,
+  });
 }
 
 function readSafe(full: string): string | undefined {
@@ -594,23 +622,61 @@ export function discoverByDetection(root: string, plugins: DetectPlugin[]): Audi
   return classifyFiles(collectCandidates(root), plugins, { baseDir: root });
 }
 
+/** Options for the local walk. */
+export interface CandidateWalkOptions {
+  /** Files the walk takes before it stops, counting every file. Defaults to {@link DEFAULT_MAX_WALK_FILES}. */
+  maxFiles?: number;
+  /**
+   * Directories the walk leaves out, absolute: the workspace members and
+   * example-group matches below the root, from `workspaceMemberDirs`. The
+   * caller resolves them, since that is async and this walk is not.
+   */
+  excludeDirs?: readonly string[];
+}
+
+/** What the local walk read, plus what it knows about its own limits. */
+export interface CandidateWalk {
+  files: RepoFile[];
+  /** The limit the walk ran with. */
+  maxFiles: number;
+  /** True when the walk stopped at `maxFiles` with files left unread. */
+  truncated: boolean;
+}
+
 /** The walk half of `discoverByDetection`: candidate files read into memory, paths relative to the root. */
 export function collectCandidates(root: string): RepoFile[] {
-  const all: string[] = [];
-  walkFiles(root, all);
+  return walkCandidates(root).files;
+}
+
+/**
+ * `collectCandidates` plus whether the walk stopped at its limit with files
+ * left unread, which the audit report states (#2528).
+ */
+export function walkCandidates(root: string, opts: CandidateWalkOptions = {}): CandidateWalk {
+  const state = { max: opts.maxFiles ?? DEFAULT_MAX_WALK_FILES, truncated: false };
+  const all = walkFiles(root, state, opts.excludeDirs);
   // TF023 reads paths, not content: a `.tfstate` can be tens of megabytes of
   // machine-generated JSON, and the finding is that it is in the repository at
-  // all. The root `.gitignore` is what separates "committed" from "merely on
-  // disk" here — a Terraform working tree almost always has an ignored
+  // all. The `.gitignore` files are what separate "committed" from "merely on
+  // disk" here. A Terraform working tree almost always has an ignored
   // `.terraform/` in it, and reporting that would make TF023 fire on every
-  // local audit. A fetched repository has no such ambiguity (its file list is
-  // the tracked files) and is not filtered.
+  // local audit. Every `.gitignore` from the scan root down to the file's own
+  // directory is read (#2528), so auditing from the root and from a
+  // subdirectory agree. A fetched repository has no such ambiguity (its file
+  // list is the tracked files) and is not filtered.
   const gitignore = readSafe(join(root, ".gitignore")) ?? "";
+  const nestedBodies = new Map<string, string | undefined>();
+  const nestedGitignoreAt = (dir: string): string | undefined => {
+    if (!nestedBodies.has(dir)) nestedBodies.set(dir, readSafe(join(root, dir, ".gitignore")));
+    return nestedBodies.get(dir);
+  };
   const files: RepoFile[] = [];
   for (const full of all) {
     const path = relative(root, full);
     if (isTerraformStatePath(path)) {
-      if (!gitignoreCoversTerraformState(gitignore, path)) files.push({ path, content: "" });
+      const ignored =
+        gitignoreCoversTerraformState(gitignore, path) || nestedGitignoreCovering(path, nestedGitignoreAt) !== undefined;
+      if (!ignored) files.push({ path, content: "" });
       continue;
     }
     // `.tf` is read locally so `classifyTerraform` can bundle real content.
@@ -624,5 +690,5 @@ export function collectCandidates(root: string): RepoFile[] {
     const content = readSafe(full);
     if (content !== undefined) files.push({ path, content });
   }
-  return files;
+  return { files, maxFiles: state.max, truncated: state.truncated };
 }

package/src/audit/report-html.ts

@@ -31,6 +31,8 @@ export interface RenderHtmlOptions extends BuildModelOptions {
   /** Full template override; `{{title}} {{accent}} {{logo}} {{meta}} {{body}} {{footer}}` slots. */
   template?: string;
   notes?: string[];
+  /** A truncated local walk (#2528), carried into the embedded JSON report. */
+  truncated?: { limit: number; flag: string };
 }
 
 const DEFAULT_ACCENT = "#7c3aed";
@@ -194,7 +196,7 @@ export function renderHtml(findings: AuditFinding[], opts: RenderHtmlOptions = {
 
   // Machine-readable data embedded so the HTML report is also parseable.
   // `<` escaped so the JSON can't break out of the <script> element.
-  const dataJson = JSON.stringify(buildReportJson(findings, { snapshot: opts.snapshot }), null, 0).replace(/</g, "\\u003c");
+  const dataJson = JSON.stringify(buildReportJson(findings, { snapshot: opts.snapshot, truncated: opts.truncated }), null, 0).replace(/</g, "\\u003c");
   const dataScript = `<script type="application/json" id="chant-audit-report">${dataJson}</script>`;
 
   let body: string;