spec-controller 0.1.0-alpha.1

package/dist/deferralTags.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The single-sourced STARTER set of recognised community deferral tags — bare names
+ * (the `@` is tag-line syntax). A scenario whose tag block carries one of these DEFERS
+ * every obligation it raises to a Pending Item (scenario-scope). These are the
+ * established Cucumber deferral conventions.
+ *
+ * This is **product policy, not a core-domain invariant** — an evolvable list of tag
+ * strings, so it lives in the application layer, NOT on the frozen v1 core barrel
+ * (@SCN-API-001). The core `parseScenarios` recognises only the deferral set it is
+ * handed (its default is `[]`, a policy-free pure core); the app is the single source
+ * of the starter policy and always passes the resolved set (starter ∪ configured) into
+ * the parser at the ingest edge. Both `resolveDeferralTags` (the `@SCN-PND-021` config
+ * union) and `renderBalanceHelp`'s `--help` listing source this constant.
+ */
+export declare const DEFAULT_DEFERRAL_TAGS: readonly string[];
+//# sourceMappingURL=deferralTags.d.ts.map

package/dist/deferralTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferralTags.d.ts","sourceRoot":"","sources":["../src/deferralTags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAMlD,CAAC"}

package/dist/deferralTags.js

@@ -0,0 +1,22 @@
+/**
+ * The single-sourced STARTER set of recognised community deferral tags — bare names
+ * (the `@` is tag-line syntax). A scenario whose tag block carries one of these DEFERS
+ * every obligation it raises to a Pending Item (scenario-scope). These are the
+ * established Cucumber deferral conventions.
+ *
+ * This is **product policy, not a core-domain invariant** — an evolvable list of tag
+ * strings, so it lives in the application layer, NOT on the frozen v1 core barrel
+ * (@SCN-API-001). The core `parseScenarios` recognises only the deferral set it is
+ * handed (its default is `[]`, a policy-free pure core); the app is the single source
+ * of the starter policy and always passes the resolved set (starter ∪ configured) into
+ * the parser at the ingest edge. Both `resolveDeferralTags` (the `@SCN-PND-021` config
+ * union) and `renderBalanceHelp`'s `--help` listing source this constant.
+ */
+export const DEFAULT_DEFERRAL_TAGS = [
+    "wip",
+    "ignore",
+    "skip",
+    "todo",
+    "pending",
+];
+//# sourceMappingURL=deferralTags.js.map

package/dist/deferralTags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferralTags.js","sourceRoot":"","sources":["../src/deferralTags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,KAAK;IACL,QAAQ;IACR,MAAM;IACN,MAAM;IACN,SAAS;CACV,CAAC"}

package/dist/host.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The host-invocation parse — the pure half of the `spec-controller` command host.
+ *
+ * The shipped binary is `spec-controller [--store <root>] [--run-id <id>] <command>
+ * [command-args]`. `--store` / `--run-id` are CROSS-CUTTING host options recognised
+ * ONLY in leading position, before the command: storage applies across balance /
+ * analyse / migrate, so it belongs at the host (wrapping any command via the kept-run
+ * scaffold), not as a peer command and never as a flag inside `balance`. This module
+ * holds the pure rules the impure dispatcher (`cli.ts`) drives — parsing the leading
+ * options, building the wrapped command argv, and peeking the conventional provenance
+ * flags — so the whole host contract is `@unit`-testable with no IO.
+ *
+ * @SCN-RMG-004 — features/run-management.feature.
+ */
+/** A parsed host invocation: leading global options, then the command and its clean args. */
+export interface HostInvocation {
+    /** The injected store root from a leading `--store <root>`, or undefined (no store). */
+    store?: string;
+    /** The mnemonic from a leading `--run-id <id>`, or undefined (→ the timestamp default). */
+    runId?: string;
+    /** The command token (e.g. "balance"), or undefined when none was given. */
+    command?: string;
+    /** The command's own args — everything after the command token, verbatim. */
+    commandArgs: string[];
+}
+/**
+ * Parse the host argv into its leading global options (`--store`, `--run-id`) and the
+ * command + its clean args. Global options are recognised ONLY before the command: the
+ * first token that is not a consumed global option (or its value) is the command, and
+ * everything after it is the command's own args, verbatim. So `--store /s balance
+ * --features f` yields the store + `balance` + `[--features, f]`, while `balance --store
+ * /s` leaves `--store` in the command's args (a `--store` AFTER the command is the
+ * command's own arg, never a host store directive) — the "global before command" contract.
+ */
+export declare function parseHostInvocation(argv: readonly string[]): HostInvocation;
+/**
+ * Build the wrapped command argv: the command's clean args followed by a repeated
+ * `--format <spec>` per store-dir output spec. Pure — the impure runner hands the result
+ * straight to the command, so the command's OWN writer produces the stored artefacts
+ * (byte-identical to a bare `--format` run; no writer duplication).
+ */
+export declare function wrapCommandArgv(commandArgs: readonly string[], formatSpecs: readonly string[]): string[];
+/**
+ * Read a `--<name> <value>` flag's value from an arg list WITHOUT consuming it — the host
+ * peeks the conventional cross-cutting provenance flags (`--target`, `--features`,
+ * `--source-sha`) to name the run dir + stamp run.yaml, while the command still receives
+ * them in its own args. Returns undefined when the flag is absent or has no value.
+ */
+export declare function peekFlag(argv: readonly string[], name: string): string | undefined;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAmB3E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAExG;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASlF"}

package/dist/host.js

@@ -0,0 +1,69 @@
+/**
+ * The host-invocation parse — the pure half of the `spec-controller` command host.
+ *
+ * The shipped binary is `spec-controller [--store <root>] [--run-id <id>] <command>
+ * [command-args]`. `--store` / `--run-id` are CROSS-CUTTING host options recognised
+ * ONLY in leading position, before the command: storage applies across balance /
+ * analyse / migrate, so it belongs at the host (wrapping any command via the kept-run
+ * scaffold), not as a peer command and never as a flag inside `balance`. This module
+ * holds the pure rules the impure dispatcher (`cli.ts`) drives — parsing the leading
+ * options, building the wrapped command argv, and peeking the conventional provenance
+ * flags — so the whole host contract is `@unit`-testable with no IO.
+ *
+ * @SCN-RMG-004 — features/run-management.feature.
+ */
+/**
+ * Parse the host argv into its leading global options (`--store`, `--run-id`) and the
+ * command + its clean args. Global options are recognised ONLY before the command: the
+ * first token that is not a consumed global option (or its value) is the command, and
+ * everything after it is the command's own args, verbatim. So `--store /s balance
+ * --features f` yields the store + `balance` + `[--features, f]`, while `balance --store
+ * /s` leaves `--store` in the command's args (a `--store` AFTER the command is the
+ * command's own arg, never a host store directive) — the "global before command" contract.
+ */
+export function parseHostInvocation(argv) {
+    let store;
+    let runId;
+    let i = 0;
+    for (; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--store" && i + 1 < argv.length) {
+            store = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (token === "--run-id" && i + 1 < argv.length) {
+            runId = argv[i + 1];
+            i++;
+            continue;
+        }
+        break; // first non-global-option token is the command
+    }
+    return { store, runId, command: argv[i], commandArgs: argv.slice(i + 1) };
+}
+/**
+ * Build the wrapped command argv: the command's clean args followed by a repeated
+ * `--format <spec>` per store-dir output spec. Pure — the impure runner hands the result
+ * straight to the command, so the command's OWN writer produces the stored artefacts
+ * (byte-identical to a bare `--format` run; no writer duplication).
+ */
+export function wrapCommandArgv(commandArgs, formatSpecs) {
+    return [...commandArgs, ...formatSpecs.flatMap((spec) => ["--format", spec])];
+}
+/**
+ * Read a `--<name> <value>` flag's value from an arg list WITHOUT consuming it — the host
+ * peeks the conventional cross-cutting provenance flags (`--target`, `--features`,
+ * `--source-sha`) to name the run dir + stamp run.yaml, while the command still receives
+ * them in its own args. Returns undefined when the flag is absent or has no value.
+ */
+export function peekFlag(argv, name) {
+    const flag = `--${name}`;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === flag) {
+            const value = argv[i + 1];
+            return value !== undefined && !value.startsWith("--") ? value : undefined;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,IAAI,KAAyB,CAAC;IAC9B,IAAI,KAAyB,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC/C,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACpB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,IAAI,KAAK,KAAK,UAAU,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAChD,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACpB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,MAAM,CAAC,+CAA+C;IACxD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,WAA8B,EAAE,WAA8B;IAC5F,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAuB,EAAE,IAAY;IAC5D,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,OAAO,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/ingest/ciSourcePaths.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Resolve a CI input to the workflow files it names (@SCN-USG-006, 3F-2497).
+ *
+ * A target's pipeline is routinely split across files — a nightly sweep, a security
+ * scan — and reading one of them scores the rest against the target twice over: a
+ * NAMED check enforced elsewhere is called a watermelon it is not, an UNNAMED one
+ * never reaches the books at all (3F-2238).
+ *
+ * THIS IS THE ONLY PLACE THAT KNOWS A CI INPUT CAN BE A DIRECTORY. The core takes
+ * anonymous source strings so a second ecosystem can supply its own; teaching it to
+ * walk a folder would import a filesystem and one provider's layout into a pure
+ * parser and close that seam for good. So the walk lives here, at the edge that
+ * already resolved `.github/workflows/ci.yml`, and the edge knows exactly as much
+ * about GitHub after this slice as it did before.
+ *
+ * Pure, with the filesystem injected — the resolution rules are the part worth
+ * asserting directly, and a fixture tree can only show one of them going wrong at a
+ * time.
+ */
+/** The filesystem reads the resolution needs, injected so the rules stay pure. */
+export interface CiPathReader {
+    exists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    readDir(path: string): string[];
+}
+/** The real filesystem, for the CLI edge. */
+export declare const NODE_CI_PATH_READER: CiPathReader;
+/**
+ * The workflow files a CI input names: every workflow in a directory, or the single
+ * file itself.
+ *
+ * Sorted, so two runs over one tree cannot differ and a diff of two reports never
+ * turns on `readdir` ordering.
+ *
+ * A FILE RESOLVES TO ITSELF ALONE. Sweeping its parent directory would silently widen
+ * a caller's deliberate scope, which is the promise @SCN-USG-008 pins at the report level.
+ *
+ * An absent path resolves to nothing — no sources, no commands, every static check
+ * read as unenforced. That over-reports gaps and hides none, the same fail-safe
+ * direction `ciRunCommands` takes on a document it cannot parse. The HARD error for a
+ * path the caller SUPPLIED and that does not exist is @SCN-CLI-002's, raised upstream;
+ * reaching here with nothing means the DEFAULT found no workflows, which is a fact
+ * about the target rather than a mistake by its author.
+ */
+export declare function ciSourcePathsOf(ciPath: string, reader?: CiPathReader): string[];
+//# sourceMappingURL=ciSourcePaths.d.ts.map

package/dist/ingest/ciSourcePaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ciSourcePaths.d.ts","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,EAAE,YAIjC,CAAC;AAKF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,YAAkC,GACzC,MAAM,EAAE,CAQV"}

package/dist/ingest/ciSourcePaths.js

@@ -0,0 +1,58 @@
+/**
+ * Resolve a CI input to the workflow files it names (@SCN-USG-006, 3F-2497).
+ *
+ * A target's pipeline is routinely split across files — a nightly sweep, a security
+ * scan — and reading one of them scores the rest against the target twice over: a
+ * NAMED check enforced elsewhere is called a watermelon it is not, an UNNAMED one
+ * never reaches the books at all (3F-2238).
+ *
+ * THIS IS THE ONLY PLACE THAT KNOWS A CI INPUT CAN BE A DIRECTORY. The core takes
+ * anonymous source strings so a second ecosystem can supply its own; teaching it to
+ * walk a folder would import a filesystem and one provider's layout into a pure
+ * parser and close that seam for good. So the walk lives here, at the edge that
+ * already resolved `.github/workflows/ci.yml`, and the edge knows exactly as much
+ * about GitHub after this slice as it did before.
+ *
+ * Pure, with the filesystem injected — the resolution rules are the part worth
+ * asserting directly, and a fixture tree can only show one of them going wrong at a
+ * time.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** The real filesystem, for the CLI edge. */
+export const NODE_CI_PATH_READER = {
+    exists: existsSync,
+    isDirectory: (path) => statSync(path).isDirectory(),
+    readDir: readdirSync,
+};
+/** Both YAML spellings: a target picks one, and the tool does not get to mind which. */
+const WORKFLOW_EXTENSIONS = [".yml", ".yaml"];
+/**
+ * The workflow files a CI input names: every workflow in a directory, or the single
+ * file itself.
+ *
+ * Sorted, so two runs over one tree cannot differ and a diff of two reports never
+ * turns on `readdir` ordering.
+ *
+ * A FILE RESOLVES TO ITSELF ALONE. Sweeping its parent directory would silently widen
+ * a caller's deliberate scope, which is the promise @SCN-USG-008 pins at the report level.
+ *
+ * An absent path resolves to nothing — no sources, no commands, every static check
+ * read as unenforced. That over-reports gaps and hides none, the same fail-safe
+ * direction `ciRunCommands` takes on a document it cannot parse. The HARD error for a
+ * path the caller SUPPLIED and that does not exist is @SCN-CLI-002's, raised upstream;
+ * reaching here with nothing means the DEFAULT found no workflows, which is a fact
+ * about the target rather than a mistake by its author.
+ */
+export function ciSourcePathsOf(ciPath, reader = NODE_CI_PATH_READER) {
+    if (!reader.exists(ciPath))
+        return [];
+    if (!reader.isDirectory(ciPath))
+        return [ciPath];
+    return reader
+        .readDir(ciPath)
+        .filter((name) => WORKFLOW_EXTENSIONS.some((ext) => name.endsWith(ext)))
+        .sort()
+        .map((name) => join(ciPath, name));
+}
+//# sourceMappingURL=ciSourcePaths.js.map

package/dist/ingest/ciSourcePaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ciSourcePaths.js","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AASjC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAiB;IAC/C,MAAM,EAAE,UAAU;IAClB,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;IACnD,OAAO,EAAE,WAAW;CACrB,CAAC;AAEF,wFAAwF;AACxF,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,SAAuB,mBAAmB;IAE1C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,MAAM;SACV,OAAO,CAAC,MAAM,CAAC;SACf,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;SACvE,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/ingest/gherkinValidation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The Gherkin VALIDATOR — the feature corpus's integrity checkpoint (@SCN-CLI-016, 3F-1767).
+ *
+ * WHY THIS EXISTS. The feature corpus is the ledger's DEBIT side, and it was read by a
+ * hand-rolled TAG-LINE SCAN (`parseScenarios`) that never looked for a `Scenario:` header at
+ * all: a scenario EXISTED purely because an `@SCN-FFF-NNN` tag line did. So a
+ * malformed tag line simply STOPPED BEING A TAG LINE, and its scenario ceased to exist —
+ * silently. One stray character, in a file cucumber itself rejects, deleted a failing row and
+ * turned an out-of-balance run (exit 1) into a clean BALANCED (exit 0). A dropped scenario
+ * cannot even reconcile `missing`, because it was never raised to be missing: the run reads
+ * CLEANER THAN REALITY. That is the false-green this tool exists to prevent, aimed at itself.
+ *
+ * THE FIX (this slice). VALIDATE every feature file with the REAL Gherkin parser — the same one
+ * cucumber uses. A file the parser rejects is an input the tool CANNOT READ, and the CLI refuses
+ * it: exit 2, halting before reconciling (@SCN-CLI-014/015's Rule — "an input the tool cannot read
+ * is a usage error, never a verdict" — extended from the OBSERVATION side to the OBLIGATION side).
+ *
+ * VALIDATION IS HALF THE STORY. This decides whether a feature file can be READ at all; the corpus
+ * is then EXTRACTED from the same real AST by `parseScenarios` (@SCN-LDG-020, 3F-1775), so the
+ * scenarios spec-controller reconciles carry exactly the tags cucumber gives them — Feature/Rule
+ * tag inheritance included. One reading of the file, not two.
+ *
+ * PURE: `string → parse errors`. No fs, no process — the file READ lives beside it at the ingest
+ * edge, as it does for every other input.
+ *
+ * WHY IT LIVES IN THE APP, NOT CORE. Core's barrel is the FROZEN v1 contract surface, guarded
+ * both directions by @SCN-API-001 — a symbol added there reds CI. This validator is an INGEST
+ * concern (it decides whether an input can be read at all), not part of the reconciliation
+ * contract downstream consumers build on, so it belongs with the other readers at the app edge
+ * and the frozen surface stays untouched.
+ */
+/** A Gherkin parse failure: the file could not be read as Gherkin at all. */
+export interface GherkinParseError {
+    /** The offending file, as supplied (the operator's locator — what to go and fix). */
+    file: string;
+    /** The parser's own message, verbatim — WHAT broke, in the parser's words. */
+    message: string;
+}
+/**
+ * Validate one `.feature` source with the real Gherkin parser. Returns the parse errors it
+ * reports — empty when the file is well-formed Gherkin.
+ *
+ * The parser is authoritative BY CONSTRUCTION: it is cucumber's own. A file it rejects is one
+ * cucumber would refuse to RUN, so a scenario corpus built from it would be a FICTION — which is
+ * precisely how a corrupt spec used to read balanced.
+ *
+ * A parse failure is reported, never thrown: the CLI edge routes it to stderr + exit 2 (the
+ * shared typed-error surface), so it can never reach Node's default exit 1 and masquerade as an
+ * out-of-balance verdict (@SCN-CLI-014's collision, on the obligation side).
+ *
+ * @SCN-CLI-016 (3F-1773).
+ */
+export declare function parseErrorsIn(file: string, source: string): GherkinParseError[];
+/**
+ * The corpus-level REFUSAL (@SCN-GPG-001, 3F-2817). A parse failure is reported per file by
+ * `parseErrorsIn` above; this is how a reader of the WHOLE corpus says no.
+ *
+ * WHY IT CARRIES EVERY FILE. The balance CLI already names every unparseable file it found
+ * (@SCN-CLI-016), and a refusal raised at the first bad one would silently narrow that message —
+ * a behaviour change dressed as an implementation detail. So the discovery collects the corpus
+ * and refuses ONCE, carrying the lot in discovery order.
+ *
+ * The rendered message is the parser's words, per file, verbatim: a reader must be told WHAT
+ * broke by the parser rather than by our paraphrase of it.
+ */
+export declare class UnreadableFeatureCorpusError extends Error {
+    readonly errors: readonly GherkinParseError[];
+    constructor(errors: readonly GherkinParseError[]);
+}
+//# sourceMappingURL=gherkinValidation.d.ts.map

package/dist/ingest/gherkinValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkinValidation.d.ts","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAa/E;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;gBAElC,MAAM,EAAE,SAAS,iBAAiB,EAAE;CAUjD"}

package/dist/ingest/gherkinValidation.js

@@ -0,0 +1,85 @@
+/**
+ * The Gherkin VALIDATOR — the feature corpus's integrity checkpoint (@SCN-CLI-016, 3F-1767).
+ *
+ * WHY THIS EXISTS. The feature corpus is the ledger's DEBIT side, and it was read by a
+ * hand-rolled TAG-LINE SCAN (`parseScenarios`) that never looked for a `Scenario:` header at
+ * all: a scenario EXISTED purely because an `@SCN-FFF-NNN` tag line did. So a
+ * malformed tag line simply STOPPED BEING A TAG LINE, and its scenario ceased to exist —
+ * silently. One stray character, in a file cucumber itself rejects, deleted a failing row and
+ * turned an out-of-balance run (exit 1) into a clean BALANCED (exit 0). A dropped scenario
+ * cannot even reconcile `missing`, because it was never raised to be missing: the run reads
+ * CLEANER THAN REALITY. That is the false-green this tool exists to prevent, aimed at itself.
+ *
+ * THE FIX (this slice). VALIDATE every feature file with the REAL Gherkin parser — the same one
+ * cucumber uses. A file the parser rejects is an input the tool CANNOT READ, and the CLI refuses
+ * it: exit 2, halting before reconciling (@SCN-CLI-014/015's Rule — "an input the tool cannot read
+ * is a usage error, never a verdict" — extended from the OBSERVATION side to the OBLIGATION side).
+ *
+ * VALIDATION IS HALF THE STORY. This decides whether a feature file can be READ at all; the corpus
+ * is then EXTRACTED from the same real AST by `parseScenarios` (@SCN-LDG-020, 3F-1775), so the
+ * scenarios spec-controller reconciles carry exactly the tags cucumber gives them — Feature/Rule
+ * tag inheritance included. One reading of the file, not two.
+ *
+ * PURE: `string → parse errors`. No fs, no process — the file READ lives beside it at the ingest
+ * edge, as it does for every other input.
+ *
+ * WHY IT LIVES IN THE APP, NOT CORE. Core's barrel is the FROZEN v1 contract surface, guarded
+ * both directions by @SCN-API-001 — a symbol added there reds CI. This validator is an INGEST
+ * concern (it decides whether an input can be read at all), not part of the reconciliation
+ * contract downstream consumers build on, so it belongs with the other readers at the app edge
+ * and the frozen surface stays untouched.
+ */
+import { AstBuilder, GherkinClassicTokenMatcher, Parser } from "@cucumber/gherkin";
+import { IdGenerator } from "@cucumber/messages";
+/**
+ * Validate one `.feature` source with the real Gherkin parser. Returns the parse errors it
+ * reports — empty when the file is well-formed Gherkin.
+ *
+ * The parser is authoritative BY CONSTRUCTION: it is cucumber's own. A file it rejects is one
+ * cucumber would refuse to RUN, so a scenario corpus built from it would be a FICTION — which is
+ * precisely how a corrupt spec used to read balanced.
+ *
+ * A parse failure is reported, never thrown: the CLI edge routes it to stderr + exit 2 (the
+ * shared typed-error surface), so it can never reach Node's default exit 1 and masquerade as an
+ * out-of-balance verdict (@SCN-CLI-014's collision, on the obligation side).
+ *
+ * @SCN-CLI-016 (3F-1773).
+ */
+export function parseErrorsIn(file, source) {
+    const parser = new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher());
+    try {
+        parser.parse(source);
+        return [];
+    }
+    catch (err) {
+        // The parser raises a CompositeParserException carrying every error it found; its message
+        // is the operator's actionable payload (line, column, and what it expected). Reported
+        // verbatim — the tool must not paraphrase the parser and risk describing a fault wrongly.
+        const message = err instanceof Error ? err.message : String(err);
+        return [{ file, message }];
+    }
+}
+/**
+ * The corpus-level REFUSAL (@SCN-GPG-001, 3F-2817). A parse failure is reported per file by
+ * `parseErrorsIn` above; this is how a reader of the WHOLE corpus says no.
+ *
+ * WHY IT CARRIES EVERY FILE. The balance CLI already names every unparseable file it found
+ * (@SCN-CLI-016), and a refusal raised at the first bad one would silently narrow that message —
+ * a behaviour change dressed as an implementation detail. So the discovery collects the corpus
+ * and refuses ONCE, carrying the lot in discovery order.
+ *
+ * The rendered message is the parser's words, per file, verbatim: a reader must be told WHAT
+ * broke by the parser rather than by our paraphrase of it.
+ */
+export class UnreadableFeatureCorpusError extends Error {
+    errors;
+    constructor(errors) {
+        super([
+            "The feature corpus contains a file that could not be parsed as Gherkin:",
+            ...errors.map(({ file, message }) => `${file}\n${message}`),
+        ].join("\n"));
+        this.name = "UnreadableFeatureCorpusError";
+        this.errors = errors;
+    }
+}
+//# sourceMappingURL=gherkinValidation.js.map

package/dist/ingest/gherkinValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkinValidation.js","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAUjD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,MAAc;IACxD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,0BAA0B,EAAE,CAAC,CAAC;IAEhG,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0FAA0F;QAC1F,sFAAsF;QACtF,0FAA0F;QAC1F,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAC5C,MAAM,CAA+B;IAE9C,YAAY,MAAoC;QAC9C,KAAK,CACH;YACE,yEAAyE;YACzE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC;SAC5D,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/ingest/ingestQualityChecks.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Ingest the target's quality-check inputs — the IMPURE reads behind the balance
+ * command (split out of the old cli.ts). Reads evidence
+ * obligations from the repo's feature files, observed evidence from the Vitest +
+ * Cucumber result JSON, and the static-check evidence from the CI config + package.json,
+ * turning each into the engine's in-memory model. The orchestration (arg parsing, the
+ * output plan/write, main) stays in cli-balance/cli.ts; these are the file reads it calls.
+ *
+ * Configurable input paths (no adapter registry in v1 — the readers are named, not
+ * registered). Missing result files are tolerated: their evidence is simply absent
+ * (the scenario reconciles as missing for that level). The static check kind reads
+ * `--ci` (a workflow file or a directory of them, default `.github/workflows`) +
+ * `package.json` to observe each fitness check the corpus cites.
+ */
+import { type GherkinParseError } from "./gherkinValidation.js";
+import { type EvidenceObligations } from "@3f-consulting/spec-controller-core";
+import type { EvidenceReconciliation } from "@3f-consulting/spec-controller-core";
+/**
+ * A reader over ONE resolution pass's records.
+ *
+ * EACH RECORD IS OPENED ONCE, WHICH IS WHY THIS IS A CLOSURE AND NOT A FUNCTION PER REFERENCE. A
+ * manifest may name several gates of one record, and a reader opening it per entry would let two
+ * references answer for two different states of the same file — a rewrite landing mid-pass, a gate
+ * present for one and gone for the next. One read makes the pass's bars one reading of one record.
+ *
+ * THE REFUSAL IS REMEMBERED TOO. Cacheing only the successes would re-open an absent or unreadable
+ * record per reference, which is the same disagreement by the other door — and the likelier door,
+ * since a record being rewritten is unreadable for exactly the window that matters.
+ *
+ * THE SUBTRACTION IS THE RECORD'S, NOT THIS EDGE'S. `killFloorOf` spends the allowance; an edge
+ * computing `detected - slack` itself would be a second place holding a fact about the record.
+ */
+export declare function killFloorReaderFor(root: string): (reference: {
+    readonly mutationGate: string;
+    readonly recordFile?: string;
+}) => number | null;
+/**
+ * The reconciler's resolved input paths — the CLI options threaded to the readers.
+ * Every path is optional; a missing result file is tolerated (its evidence is
+ * simply absent). `packageJson` is the EXTERNALLY-SPECIFIED package.json the static
+ * (guard) reader reads `exists` from (the --package-json seam, @SCN-LNT-005):
+ * default the tool's own cwd `package.json`; set it to reconcile ANOTHER repo's
+ * static checks — required to render the historical watermelon correctly.
+ */
+export interface ReconcileOptions {
+    features?: string;
+    vitest?: string;
+    cucumber?: string;
+    ci?: string;
+    packageJson?: string;
+    /**
+     * The measurement artefact (@SCN-CIP-003) — the number each measured check posted, and
+     * the credit side of every measured fitness check. Optional like the other result files: absent,
+     * it contributes nothing, and each measured obligation it would have answered reads `missing`.
+     */
+    measurements?: string;
+}
+/**
+ * The feature corpus's INTEGRITY CHECKPOINT (@SCN-CLI-016, 3F-1767) — validate every discovered
+ * `.feature` with the REAL Gherkin parser and report the files it cannot read.
+ *
+ * The feature corpus is the ledger's DEBIT side, and it used to be read by a tag-line scan that
+ * never consulted a parser — so a malformed tag line silently deleted its scenario, and a corrupt
+ * spec could read BALANCED. A file the parser rejects is one cucumber would refuse to run: the
+ * CLI halts on it (exit 2) rather than reconciling a corpus that is a fiction.
+ *
+ * THIS IS NOW THE CATCH SITE, NOT THE CALL SITE (@SCN-GPG-001, 3F-2817). The validation moved
+ * into `discoverFeatures`, which REFUSES an unreadable corpus rather than returning one, so every
+ * corpus reader inherits the refusal instead of each restating it. What is left here is the
+ * translation back into the list this CLI edge already prints — same files, same order, same
+ * verbatim parser messages, so `balance`'s behaviour is unchanged. Anything that is not a corpus
+ * refusal is not ours to interpret and rethrows.
+ */
+export declare function featureCorpusParseErrors(featuresDir: string | undefined): GherkinParseError[];
+/**
+ * The `@SCN` ids the feature corpus CARRIES MORE THAN ONCE (@SCN-LDG-020's guardrail, 3F-1775).
+ *
+ * An `@SCN` identifies exactly ONE scenario — that is the whole basis of attributing evidence to
+ * it. If two scenarios carry the same id, a test citing it could be proving EITHER, and the tool
+ * cannot know which: the corpus is ambiguous, and any verdict over it is a guess.
+ *
+ * WHY THIS EXISTS. Tag inheritance made this reachable: an `@SCN` hoisted to a `Feature:`/`Rule:`
+ * is inherited by every scenario beneath it (cucumber does this, so we do — parity). Left
+ * unhandled, ONE passing test then marked EVERY scenario sharing that id `balanced`, including
+ * scenarios nothing proves — a BALANCED-WHEN-BROKEN run, exit 0. A new silent false-green,
+ * introduced by the very fix that closed the last one.
+ *
+ * Refused at the edge (exit 2) rather than reconciled, under the Rule already shipped for the
+ * observed side and the corrupt corpus (@SCN-CLI-014/015/016): an input the tool cannot read is a
+ * usage error, never a verdict. Whether hoisting an `@SCN` is an authoring fault worth a richer
+ * diagnostic is the deferred policy question (3F-1774's sibling); refusing to reconcile a corpus we
+ * cannot read is not a policy — it is the floor.
+ */
+export declare function featureCorpusDuplicateScnIds(featuresDir: string | undefined): string[];
+/**
+ * Read the target's `feature-code → slug` map over the same `discoverFeatures` corpus
+ * (@SCN-RPT-006) — each coded feature file's `@<FFF>` header (`featureCode`)
+ * mapped to its filename `slug`, the full feature name. This is the mapping
+ * `scenariosFromFeatures` discards (it keeps only the parsed scenarios). A sibling read to
+ * the balance, threaded to `renderMarkdown` (via `writeOutputs`) as the 5th sibling arg
+ * (markdown-only — the by-feature cut is markdown-only, so it is NOT serialised to JSON).
+ * Uncoded files (`featureCode === null`) are omitted, so the by-feature emitter falls
+ * back to the bare `FFF` for any id whose code no file registers. One-prefix-one-file holds
+ * by invariant (`lintFeatureCodes` flags a duplicate code), so the map is unambiguous.
+ */
+export declare function readFeatureNames(featuresDir?: string): Map<string, string>;
+/**
+ * Read the scenario-corpus census over the discovered feature files (the same
+ * `discoverFeatures` corpus `scenariosFromFeatures` reads): sum the raw @SCN
+ * occurrences (`countScnOccurrences`) and the scenario count
+ * (`parseScenarios(...).length`) across every file, and build the `EvidenceObligations`
+ * sibling (@SCN-RPT-008). Also collects the UNTAGGED scenarios
+ * (@SCN-RPT-014) — `parseUntaggedScenarios` per file, each paired with its feature-file
+ * locator, sorted by (feature, scenario). Read alongside the balance in `main()` and
+ * threaded to the renderers via `writeOutputs`; `runReconcile` stays unchanged.
+ */
+export declare function readEvidenceObligations(features?: string): EvidenceObligations;
+export declare function runReconcile(opts: ReconcileOptions): EvidenceReconciliation;
+//# sourceMappingURL=ingestQualityChecks.d.ts.map

package/dist/ingest/ingestQualityChecks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingestQualityChecks.d.ts","sourceRoot":"","sources":["../../src/ingest/ingestQualityChecks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,OAAO,EAAgC,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE9F,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,qCAAqC,CAAC;AA6B7C,OAAO,KAAK,EAIV,sBAAsB,EACvB,MAAM,qCAAqC,CAAC;AAyD7C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GAMX,CAAC,SAAS,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,GAAG,IAAI,CAc/F;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAgDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,EAAE,CAS7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAStF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAsB9E;AA0CD,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,sBAAsB,CAuC3E"}