spec-controller 0.1.0-alpha.9 → 0.1.0

package/dist/ingest/gherkinValidation.js

@@ -1,51 +1,6 @@
-/**
- * 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 v1 contract surface downstream consumers
- * build on. Since 3F-3449 nothing reds when a symbol is added there — the guard that reconciled it
- * both directions is gone — so keeping it narrow is a discipline rather than a gate. This validator
- * is an INGEST concern (it decides whether an input can be read at all), not part of the
- * reconciliation contract, so it belongs with the other readers at the app edge and the v1 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).
- */
+import { APP_MESSAGES, AppMessage } from "../messages.js";
 export function parseErrorsIn(file, source) {
     const parser = new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher());
     try {
@@ -53,59 +8,25 @@ export function parseErrorsIn(file, 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:",
+            APP_MESSAGES[AppMessage.FeatureCorpusUnparseable](),
             ...errors.map(({ file, message }) => `${file}\n${message}`),
         ].join("\n"));
         this.name = "UnreadableFeatureCorpusError";
         this.errors = errors;
     }
 }
-/**
- * The corpus-level ABSENCE refusal (@SCN-CLI-017, 3F-3345) — sibling to the parse refusal above,
- * and deliberately the same shape: the reader refuses ONCE, and each command decides what the
- * refusal means for it.
- *
- * WHY A TYPED ERROR RATHER THAN AN EMPTY CORPUS. The obvious fix is for `discoverFeatures` to hand
- * back `[]` when the directory is not there. Measured, that would ship a NEW false green in a
- * second command: `spec-controller tags` reaches the same reader through `readCorpusInputs`, whose
- * GENERIC catch is the only thing turning an absent corpus — and, since `tags` carries no
- * `checkInputsExist`, a supplied-but-absent `--features` too — into `The corpus could not be
- * read: …` at exit 2. Tolerance at the reader turns both into `tags: OK …` at exit 0, inside the
- * slice whose whole purpose is killing a vacuous certification. Typed, both survive untouched:
- * this IS an `Error`, so it still lands in that generic catch.
- *
- * IT CARRIES THE DIRECTORY because the report is owed the name of what it examined — "I found no
- * record" and "I found no regression" must never wear one word (3F-2947), and a consumer told
- * their corpus is empty deserves to know which directory was read to reach that.
- */
 export class MissingFeatureCorpusError extends Error {
-    /** The directory that is not there — as resolved, so a reader can print the path examined. */
     directory;
     constructor(directory) {
-        super(`The feature corpus directory does not exist: ${directory}`);
+        super(APP_MESSAGES[AppMessage.FeatureCorpusDirectoryMissing](directory));
         this.name = "MissingFeatureCorpusError";
         this.directory = directory;
     }

package/dist/ingest/gherkinValidation.js.map

@@ -1 +1 @@
-{"version":3,"file":"gherkinValidation.js","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,8FAA8F;IACrF,SAAS,CAAS;IAE3B,YAAY,SAAiB;QAC3B,KAAK,CAAC,gDAAgD,SAAS,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF"}
+{"version":3,"file":"gherkinValidation.js","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAO1D,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,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,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAC5C,MAAM,CAA+B;IAE9C,YAAY,MAAoC;QAC9C,KAAK,CACH;YACE,YAAY,CAAC,UAAU,CAAC,wBAAwB,CAAC,EAAE;YACnD,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;AAED,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,SAAS,CAAS;IAE3B,YAAY,SAAiB;QAC3B,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,6BAA6B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF"}

package/dist/ingest/ingestQualityChecks.d.ts

@@ -1,109 +1,24 @@
-/**
- * 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";
-/**
- * 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
- * static-check 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 CI RUN'S OWN RECORD of what each of its steps did (@SCN-LNT-021, @SCN-LNT-028) — the credit
-     * side of every CONVERTED fitness check, written by the consumer's own pipeline and by neither
-     * party to this reconciliation.
-     *
-     * KEPT APART FROM `ci` BECAUSE THE TWO DOCUMENTS ANSWER DIFFERENT QUESTIONS. The workflow FILE
-     * says a check is wired into this pipeline and which row its step cites — a fact about a
-     * repository, true between runs. This is one RUN's record: did it run this time, and what did it
-     * find. Optional like the other result files: a consumer whose pipeline dumps no record, or a
-     * local run with no pipeline at all, hands none, and the converted rows it would have answered
-     * read `missing`.
-     */
     ciSteps?: 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 const DEFAULT_CI_PATH = ".github/workflows";
+export declare const DEFAULT_PACKAGE_JSON = "package.json";
 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 (`corpusFaults` raises `duplicate-feature-code`, @SCN-STG-010), so the map is
- * unambiguous. That invariant was `lintFeatureCodes`' until 3F-3313; it is the shipped command's
- * now, which is the first time a CONSUMER of this reader has it too.
- */
+export interface InputReadFault {
+    readonly path: string;
+    readonly reason: string;
+}
+export declare function corpusReadFault(featuresDir: string | undefined): InputReadFault | null;
+export declare function ciReadFault(ciPath: string | undefined): InputReadFault | null;
 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

@@ -1 +1 @@
-{"version":3,"file":"ingestQualityChecks.d.ts","sourceRoot":"","sources":["../../src/ingest/ingestQualityChecks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,qCAAqC,CAAC;AAkB7C,OAAO,KAAK,EAIV,sBAAsB,EACvB,MAAM,qCAAqC,CAAC;AA6B7C;;;;;;;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;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,EAAE,CAQ7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAStF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAqB9E;AA0CD,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,sBAAsB,CA2D3E"}
+{"version":3,"file":"ingestQualityChecks.d.ts","sourceRoot":"","sources":["../../src/ingest/ingestQualityChecks.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,qCAAqC,CAAC;AAY7C,OAAO,KAAK,EAGV,sBAAsB,EACvB,MAAM,qCAAqC,CAAC;AAO7C,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,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,eAAe,sBAAsB,CAAC;AAEnD,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AAuBnD,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,EAAE,CAQ7F;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAQD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAUtF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAU7E;AAYD,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM1E;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAmB9E;AAmBD,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,sBAAsB,CA2B3E"}

package/dist/ingest/ingestQualityChecks.js

@@ -1,94 +1,28 @@
-/**
- * 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 { readFileSync, existsSync } from "node:fs";
 import { basename } from "node:path";
 import { ciSourcePathsOf } from "./ciSourcePaths.js";
 import { discoverFeatures } from "./ingestScenarios.js";
-import { parseScenarios, countScnOccurrences, parseUntaggedScenarios, proseOnlyCodes, } from "@3f-consulting/spec-controller-core";
+import { parseScenarios, countScnOccurrences, parseUntaggedScenarios, sharedScnCodesOf, untaggedScenarioId, } from "@3f-consulting/spec-controller-core";
 import { MissingFeatureCorpusError, UnreadableFeatureCorpusError, } from "./gherkinValidation.js";
 import { DEFAULT_DEFERRAL_TAGS } from "../deferralTags.js";
 import { evidenceObligations, } from "@3f-consulting/spec-controller-core";
 import { parseVitestEvidenceObservations, } from "@3f-consulting/spec-controller-core";
 import { parseCucumberEvidenceObservations, } from "@3f-consulting/spec-controller-core";
-// THE WHOLE COMPOSITION, THROUGH THE PUBLIC BARREL AND NOTHING ELSE (3F-3086). This module travels
-// in the tarball, and until 3F-3089 it reached nine core symbols through the UNPUBLISHED
-// `./internal` subpath to assemble the reconciliation itself — which is why an installed
-// `spec-controller balance --help` threw ERR_PACKAGE_PATH_NOT_EXPORTED while every gate in this
-// workspace stayed green. The nine are still internal (3F-2837 stands, unamended); what moved is
-// their CALLER. What is left here is the reads: this edge opens the files and hands the bytes over.
 import { evidenceReconciliationFromSources } from "@3f-consulting/spec-controller-core";
 import { resolveTargetRoot } from "../run-management/resolveRunInputs.js";
-/**
- * The per-input FALLBACK quality-check for each JS-ecosystem result source — the
- * source→quality-check mapping, SET at the CLI edge rather than hardcoded in the core
- * parsers / countRuntimeEvidenceObservationKinds. A second ecosystem (pytest / JUnit) sets its own here (or
- * via an adapter); the core never assumes a mapping. No CLI override flag yet — that
- * earns its place at the second ecosystem, not now.
- */
 const VITEST_QUALITY_CHECK = "unit";
 const CUCUMBER_QUALITY_CHECK = "integration";
-/**
- * THIS TOOL, RUN TO RECONCILE (@SCN-USG-014, 3F-3343) — the invocation whose step is the
- * reconciler rather than one of the reconciled rows, SET at the CLI edge and injected into the
- * core like the prefixes above and the workflow names below.
- *
- * HOW THIS PRODUCT IS INVOKED IS THIS LAYER'S FACT. `spec-controller` is the `bin` this package
- * publishes and `balance` is the command that reconciles; the engine holds neither, and a core
- * that assumed them would be asserting something about a command line it never sees.
- *
- * BOTH TOKENS, AND THE SECOND IS NOT DECORATION. This repository's own pipeline runs
- * `pnpm spec-controller tags` beside its balance step — the same binary, doing something that is
- * an ordinary step of the pipeline being reconciled — so an invocation naming the binary alone
- * would take that step off the books. The comparison is whole, adjacent shell tokens
- * (`parse/commandRuns`), so this names the reconciliation and nothing else the tool can do.
- */
 const RECONCILER_INVOCATION = "spec-controller balance";
-/** Read + JSON-parse a file if present, else return undefined. */
+export const DEFAULT_CI_PATH = ".github/workflows";
+export const DEFAULT_PACKAGE_JSON = "package.json";
 function readJsonIfPresent(path) {
     if (!path || !existsSync(path))
         return undefined;
     return JSON.parse(readFileSync(path, "utf8"));
 }
-/**
- * THE CORPUS `balance` READS — the shared discovery, with an ABSENT directory read as NO CORPUS
- * (@SCN-CLI-017, 3F-3345). The single place this command opts in.
- *
- * `new-client` is a supported adoption state, not a degraded one, and most targets have no
- * `features/` directory at all — so an absent DEFAULT corpus is the target's honest shape and
- * `balance` reports on it. Left to escape it was a raw `ENOENT` landing on Node's default exit 1,
- * the OUT-OF-BALANCE code, which is exactly the collision @SCN-CLI-014/015/016 closed on every
- * other input, alive on the one path each new consumer is guaranteed to take.
- *
- * ONE HELPER, NOT FIVE CATCHES, and that is the whole reason it exists: five readers each doing
- * this by hand is five chances for one to stay intolerant, and a run that reports on a corpus for
- * four of its readings and throws on the fifth is worse than one that throws. The translation is
- * also why `discoverFeatures` is not the place to be tolerant — see its own note, and
- * `MissingFeatureCorpusError`'s: `tags` reaches the same reader and keeps refusing.
- *
- * IT IS `[]`, NOT A VERDICT. Zero rows is what @SCN-CLI-019 reads as NOTHING TO RECONCILE, and a
- * corpus-less target that still has uncited credits keeps its suspense row and its exit 1
- * (@SCN-CLI-020) — this reader says what it found, never what the run means.
- *
- * A supplied-but-absent `--features` never arrives here: `checkInputsExist` refuses it at the CLI
- * edge, exit 2 (@SCN-CLI-002). The precedent is `ciSourcePathsOf`, which already answers an absent
- * DEFAULT `.github/workflows` with `[]` for the same reason — the default finding nothing is a fact
- * about the target, not a mistake by its author.
- */
 function balanceCorpus(featuresDir) {
     try {
-        return featuresDir !== undefined ? discoverFeatures(featuresDir) : discoverFeatures();
+        return discoverFeatures(featuresDir);
     }
     catch (err) {
         if (err instanceof MissingFeatureCorpusError)
@@ -96,49 +30,9 @@ function balanceCorpus(featuresDir) {
         throw err;
     }
 }
-/**
- * The discovered feature corpus's SOURCES — read once so the two readings a citing run needs (the
- * obligations, and the corpus hop's `check tag → @SCN`) are taken from the same bytes. Two
- * discoveries could disagree about the corpus, and a citation resolved against a corpus the ledger
- * was not built from is exactly the phantom-row fault (@SCN-LNT-009).
- */
-function featureSources(featuresDir) {
-    return balanceCorpus(featuresDir).map((f) => readFileSync(f.path, "utf8"));
-}
-function scenariosFromFeatures(featuresDir, deferralTags = DEFAULT_DEFERRAL_TAGS) {
-    return featureSources(featuresDir).flatMap((source) => parseScenarios(source, deferralTags));
-}
-/**
- * The feature corpus's UNTAGGED half (@SCN-LDG-021, 3F-1774) — the scenarios `parseScenarios`
- * discards because they carry no `@SCN`. They are REAL scenarios: cucumber runs them, so each
- * owns a real Evidence Obligation — but the obligation has no code for an Evidence Observation to
- * link to, so it can never be discharged. `reconcile` gives each its own out-of-balance row
- * (`no-scn-code`); before this read they were invisible to the ledger, and a run whose only fault
- * was an untagged scenario printed "N scenario(s) carry no @SCN tag" and exited 0 BALANCED.
- *
- * Each is handled by its `<feature> : <scenario>` locator — the SAME locator the untagged warning
- * prints — because a bare scenario name is not unique across the corpus, and the row must say
- * where to go.
- */
 function untaggedScenariosFromFeatures(featuresDir) {
-    return balanceCorpus(featuresDir).flatMap((f) => parseUntaggedScenarios(readFileSync(f.path, "utf8")).map((scenario) => `${f.slug}.feature : ${scenario}`));
+    return balanceCorpus(featuresDir).flatMap((f) => parseUntaggedScenarios(readFileSync(f.path, "utf8")).map((scenario) => untaggedScenarioId({ feature: `${f.slug}.feature`, scenario })));
 }
-/**
- * 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 function featureCorpusParseErrors(featuresDir) {
     try {
         balanceCorpus(featuresDir);
@@ -150,48 +44,50 @@ export function featureCorpusParseErrors(featuresDir) {
         throw err;
     }
 }
-/**
- * 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 function featureCorpusDuplicateScnIds(featuresDir) {
-    const seen = new Set();
-    const duplicates = new Set();
-    for (const scenario of scenariosFromFeatures(featuresDir)) {
-        if (seen.has(scenario.scnId))
-            duplicates.add(scenario.scnId);
-        seen.add(scenario.scnId);
+function readFaultOf(err, path) {
+    const errno = err;
+    if (!(err instanceof Error) || typeof errno.code !== "string")
+        return null;
+    return { path: errno.path ?? path, reason: err.message };
+}
+export function corpusReadFault(featuresDir) {
+    try {
+        balanceCorpus(featuresDir);
+        return null;
+    }
+    catch (err) {
+        if (err instanceof UnreadableFeatureCorpusError)
+            return null;
+        const fault = readFaultOf(err, featuresDir ?? "features");
+        if (fault === null)
+            throw err;
+        return fault;
+    }
+}
+export function ciReadFault(ciPath) {
+    const path = ciPath ?? DEFAULT_CI_PATH;
+    try {
+        for (const source of ciSourcePathsOf(path))
+            readCiSource(source);
+        return null;
+    }
+    catch (err) {
+        const fault = readFaultOf(err, path);
+        if (fault === null)
+            throw err;
+        return fault;
+    }
+}
+function readCiSource(source) {
+    try {
+        readFileSync(source);
+    }
+    catch (err) {
+        const errno = err;
+        errno.path ??= source;
+        throw err;
     }
-    return [...duplicates].sort();
 }
-/**
- * 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 (`corpusFaults` raises `duplicate-feature-code`, @SCN-STG-010), so the map is
- * unambiguous. That invariant was `lintFeatureCodes`' until 3F-3313; it is the shipped command's
- * now, which is the first time a CONSUMER of this reader has it too.
- */
 export function readFeatureNames(featuresDir) {
     const map = new Map();
     for (const f of balanceCorpus(featuresDir)) {
@@ -200,25 +96,15 @@ export function readFeatureNames(featuresDir) {
     }
     return map;
 }
-/**
- * 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 function readEvidenceObligations(features) {
     const featureFiles = balanceCorpus(features);
     let raw = 0;
     let scenarioCount = 0;
     const untagged = [];
-    const sources = [];
+    const files = [];
     for (const f of featureFiles) {
         const source = readFileSync(f.path, "utf8");
-        sources.push(source);
+        files.push({ feature: `${f.slug}.feature`, source });
         raw += countScnOccurrences(source);
         scenarioCount += parseScenarios(source).length;
         for (const scenario of parseUntaggedScenarios(source)) {
@@ -226,19 +112,9 @@ export function readEvidenceObligations(features) {
         }
     }
     untagged.sort((a, b) => a.feature.localeCompare(b.feature) || a.scenario.localeCompare(b.scenario));
-    // The prose-only codes are a CROSS-CORPUS difference (a code tagged in any file isn't
-    // dangling), so it reads all sources at once — not per-file like the others.
-    return evidenceObligations(raw, scenarioCount, untagged, proseOnlyCodes(sources));
+    return evidenceObligations(raw, scenarioCount, untagged, sharedScnCodesOf(files));
 }
-/**
- * Parse the target's RUNTIME observations ONCE — the tag-derived, per-tier observation set
- * (@SCN-RPT-017 / 3F-1452 FULL UNIFY) fed to BOTH the reconciler and the runtime census, so the
- * two can never disagree. Each source's FALLBACK quality-check is set at the CLI edge
- * (vitest⇒unit, cucumber⇒integration); the parsers DERIVE the level from the cited scenario's tier
- * tag (@SCN-LDG-011 / 3F-1434), using the fallback only for an untagged scenario. A missing report
- * contributes nothing. Root-relative so a phantom-scenario row's where-to-fix stays portable.
- */
-function parseRuntimeObservations(opts, root) {
+function parseBehaviouralObservations(opts, root) {
     const out = [];
     const vitestReport = readJsonIfPresent(opts.vitest);
     if (vitestReport)
@@ -249,66 +125,27 @@ function parseRuntimeObservations(opts, root) {
     return out;
 }
 export function runReconcile(opts) {
-    // Read the target's package.json ONCE — its `specController.*` config supplies the deferral-tag
-    // extension (@SCN-PND-021) and the configured fitness rows, and its `scripts` back the `exists`
-    // read. The disk read stays at this impure edge; the engine takes the resolved values as
-    // injected params, staying pure.
-    const pkgPath = opts.packageJson ?? "package.json";
+    const pkgPath = opts.packageJson ?? DEFAULT_PACKAGE_JSON;
     const packageJson = readJsonIfPresent(pkgPath) ?? {};
-    // The TARGET repo root — the credit locators are made relative to it, so a phantom-scenario row's
-    // where-to-fix (ruling Q5) stays portable in a banked artefact. Resolved ONCE here and threaded,
-    // which is also what keeps `execFileSync` and `process.cwd()` out of the engine.
     const root = resolveTargetRoot({ features: opts.features });
-    // `--ci` names a workflow FILE or a DIRECTORY of them, and defaults to the directory
-    // (@SCN-USG-006, 3F-2238): a pipeline split across files enforces its checks just as one
-    // file does, and reading only ci.yml both invents watermelons for named checks enforced
-    // elsewhere and drops uncited ones off the books entirely. Path semantics carry the
-    // file-vs-directory distinction, so one flag stays one flag and an explicit file is still
-    // a narrowing (@SCN-USG-008).
-    const ciPath = opts.ci ?? ".github/workflows";
-    // RESOLVED ONCE, READ TWICE (@SCN-USG-015). The engine takes anonymous source strings and holds
-    // no filesystem, so the mapping from a step's source index back to the workflow file it came
-    // from is made HERE, where the paths are already in hand — `ciSourcePaths.ts` is explicit that
-    // keeping the core that way is the point. Resolving the list twice would be two chances for the
-    // bytes and the names to fall out of the order they are paired by.
+    const ciPath = opts.ci ?? DEFAULT_CI_PATH;
     const ciPaths = ciSourcePathsOf(ciPath);
+    const corpusFiles = balanceCorpus(opts.features).map((f) => ({
+        slug: f.slug,
+        featureCode: f.featureCode,
+        source: readFileSync(f.path, "utf8"),
+    }));
     return evidenceReconciliationFromSources({
-        // The corpus's bytes, read ONCE at this impure edge (3F-3088). The engine composes the three
-        // readings a citing run needs from this one array, so they cannot be assembled from two
-        // discoveries that disagree about the corpus (@SCN-LNT-009).
-        featureSources: featureSources(opts.features),
-        // The untagged half by its `<feature> : <scenario>` locator — parsed here because the locator
-        // names the FILE, which the discovery knows and a source string does not.
+        featureSources: corpusFiles.map((f) => f.source),
+        featureFiles: corpusFiles.map(({ slug, featureCode }) => ({ slug, featureCode })),
         untaggedScenarios: untaggedScenariosFromFeatures(opts.features),
         packageJson,
         ciSources: ciPaths.map((path) => readFileSync(path, "utf8")),
-        // THE FILE, NOT THE PATH. A `notChecks` entry opens with the workflow's own name — `ci.yml`,
-        // `release.yml` — which is what a consumer reads at the head of their run log and the only
-        // half of the entry that does not come out of the workflow's own text. The directory it sits
-        // in is the caller's `--ci`, not the consumer's subject, so it is not part of what they write.
         ciSourceNames: ciPaths.map((path) => basename(path)),
-        // The CONVERTED checks' credit stream, read at this edge like every other report. Absent it is
-        // undefined rather than empty, and that distinction reaches the reader (@SCN-LNT-027): "no
-        // record" is a run nobody recorded, "a record holding nothing" is a run that recorded none of
-        // these steps, and those are opposite facts.
-        // STRUCTURALLY, NOT BY NAME: this module travels in the tarball and reaches core through the PUBLIC barrel alone (3F-3086), and
-        // `CiStepRecord` is not on it. The shape is the document's, which is the consumer's, so what is
-        // written here is what the file holds rather than a contract owed to anyone.
         ciStepRecord: readJsonIfPresent(opts.ciSteps),
-        runtimeObservations: parseRuntimeObservations(opts, root),
-        // The two things the engine's resolvers cannot hold, and each for its own reason: the
-        // starter deferral set is the application layer's own policy, and how this tool is invoked to
-        // reconcile is a fact about this product's command line. THE PREFIX SET USED TO SIT HERE AND IS GONE (@SCN-USG-004, 3F-3343): the
-        // engine no longer decides a check's membership by its name, so there is no convention left
-        // for this edge to own.
+        behaviouralObservations: parseBehaviouralObservations(opts, root),
         deferralTags: DEFAULT_DEFERRAL_TAGS,
         reconcilerInvocation: RECONCILER_INVOCATION,
     });
 }
-// The static-check kind-counts are no longer read as a parallel census (@SCN-USG-001 / 3F-2118):
-// the former `readStaticEvidenceObservationCounts` re-built the static check observations and
-// re-derived the running / uncited split from a second read of the CI config. That counting now
-// FOLDS onto the Ledger the reconciler already produced (`staticObservationTally`, an internal
-// domain fold the renderers apply), so it cannot drift from the verdict — it counts the SAME posted
-// static-check credits `runReconcile` banked. The census read is deleted, not relocated.
 //# sourceMappingURL=ingestQualityChecks.js.map