spec-controller 0.1.0-alpha.5 → 0.1.0-alpha.50

package/dist/host.d.ts

@@ -1,50 +1,19 @@
-/**
- * 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. */
+import { type CommandSpec, type FlagSpec } from "./cli-registry.js";
 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[];
+    refusal?: 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 parseHostInvocation(argv: readonly string[], globalFlags?: readonly FlagSpec[], commands?: readonly string[]): HostInvocation;
 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;
+export interface UnknownCommandAnswer {
+    exitCode: number;
+    stderr: string;
+}
+export declare function answerUnknownCommand(command: string, help: string): UnknownCommandAnswer;
+export declare function modifiersNotTakenRefusal(inv: HostInvocation, commands?: readonly CommandSpec[]): string | undefined;
+export declare function formatFilePaths(argv: readonly string[]): string[];
 //# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AASA,OAAO,EAAe,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEjF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,WAAW,GAAE,SAAS,QAAQ,EAAuB,EACrD,QAAQ,GAAE,SAAS,MAAM,EAAwD,GAChF,cAAc,CAIhB;AAmGD,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAExG;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASlF;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAKxF;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,cAAc,EACnB,QAAQ,GAAE,SAAS,WAAW,EAAyB,GACtD,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CASjE"}

package/dist/host.js

@@ -1,61 +1,85 @@
-/**
- * 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;
+import { asksForHelp, equalsFormRefusal, givenTwiceRefusal, isEqualsForm, isMissingValue, missingValueRefusal, valueFlagsOf, } from "./cli-args.js";
+import { cliRegistry } from "./cli-registry.js";
+export function parseHostInvocation(argv, globalFlags = cliRegistry.global, commands = cliRegistry.commands.map((command) => command.name)) {
+    const read = readHostTokens(argv, globalFlags, commands);
+    const help = argv.slice(0, hostTokenCount(argv, read)).find((token) => TOP_LEVEL_HELP.has(token));
+    return help === undefined ? read : { command: help, commandArgs: [] };
+}
+function hostTokenCount(argv, read) {
+    if (read.refusal !== undefined || read.command === undefined)
+        return argv.length;
+    return argv.length - read.commandArgs.length - 1;
+}
+function readHostTokens(argv, globalFlags, commands) {
+    const modifiers = valueFlagsOf(globalFlags);
+    const values = new Map();
     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;
+        const token = argv[i] ?? "";
+        const modifier = modifiers.get(token);
+        if (modifier === undefined) {
+            const refusal = leadingFlagRefusal(token, modifiers, globalFlags);
+            if (refusal !== undefined)
+                return { commandArgs: [], refusal };
+            break;
         }
-        if (token === "--run-id" && i + 1 < argv.length) {
-            runId = argv[i + 1];
-            i++;
-            continue;
-        }
-        break; // first non-global-option token is the command
+        const value = argv[i + 1];
+        const refusal = modifierRefusal(token, modifier, argv.slice(i + 1, i + 3), { values, commands });
+        if (refusal !== undefined)
+            return { commandArgs: [], refusal };
+        values.set(modifier.name, value ?? "");
+        i++;
+    }
+    if (i === argv.length && values.size > 0)
+        return { commandArgs: [], refusal: noCommandRefusal([...values.keys()]) };
+    return {
+        store: values.get("--store"),
+        runId: values.get("--run-id"),
+        command: argv[i],
+        commandArgs: argv.slice(i + 1),
+    };
+}
+function modifierRefusal(token, modifier, [value, after], read) {
+    if (read.values.has(modifier.name))
+        return givenTwiceRefusal(token, "spec-controller");
+    if (isMissingValue(value))
+        return missingValueRefusal(token, modifier, "spec-controller");
+    if (read.commands.includes(value ?? "") && (after === undefined || after.startsWith("-"))) {
+        return commandAsValueRefusal(token, modifier, value ?? "");
     }
-    return { store, runId, command: argv[i], commandArgs: argv.slice(i + 1) };
+    return undefined;
+}
+function noCommandRefusal(given) {
+    return (`No command followed the host modifiers given (${given.join(", ")}), so nothing ran: ` +
+        `a host modifier needs a command after it, or --help.\n` +
+        `Run 'spec-controller --help' to see the commands and host modifiers this version accepts.`);
+}
+function commandAsValueRefusal(token, modifier, command) {
+    return (`The ${token} host modifier took '${command}', a command, as its value, and left no command to run.\n` +
+        `Give ${token} its own value, as in 'spec-controller ${token} ${modifier.arg ?? ""} ${command} …'. ` +
+        `Run 'spec-controller --help' to see the commands and host modifiers this version accepts.`);
+}
+function leadingFlagRefusal(token, modifiers, globalFlags) {
+    if (isEqualsForm(token))
+        return equalsFormRefusal(token, modifiers, "spec-controller");
+    if (isFlagOutOfPlace(token))
+        return flagBeforeCommandRefusal(token, globalFlags);
+    return undefined;
+}
+const TOP_LEVEL_HELP = new Set(["--help", "-h"]);
+function isFlagOutOfPlace(token) {
+    return token.length > 1 && token.startsWith("-") && !TOP_LEVEL_HELP.has(token);
+}
+function flagBeforeCommandRefusal(flag, globalFlags) {
+    const modifiers = globalFlags.map((modifier) => modifier.name).join(", ");
+    return (`The ${flag} flag was given before the command. Before the command, spec-controller takes ` +
+        `only its host modifiers (${modifiers}); a command's own flags go after it, as in ` +
+        `'spec-controller <command> ${flag}'.\n` +
+        `Run 'spec-controller --help' to see the commands and host modifiers this version accepts.`);
 }
-/**
- * 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++) {
@@ -66,4 +90,33 @@ export function peekFlag(argv, name) {
     }
     return undefined;
 }
+export function answerUnknownCommand(command, help) {
+    return {
+        exitCode: 2,
+        stderr: `spec-controller: unknown command "${command}".\n\n${help}\n`,
+    };
+}
+export function modifiersNotTakenRefusal(inv, commands = cliRegistry.commands) {
+    const entry = commands.find((command) => command.name === inv.command);
+    if (entry?.acceptsHostModifiers !== false || asksForHelp(inv.commandArgs))
+        return undefined;
+    const given = [inv.store === undefined ? [] : ["--store"], inv.runId === undefined ? [] : ["--run-id"]].flat();
+    if (given.length === 0)
+        return undefined;
+    return (`spec-controller: usage error — '${entry.name}' takes no host modifier, and was given ${given.join(", ")}: ` +
+        `it answers a query and keeps no run.\n` +
+        `Run 'spec-controller ${entry.name} …' without them.`);
+}
+export function formatFilePaths(argv) {
+    const paths = [];
+    argv.forEach((token, index) => {
+        const value = argv[index + 1];
+        if (token !== "--format" || value === undefined)
+            return;
+        const colon = value.indexOf(":");
+        if (colon !== -1)
+            paths.push(value.slice(colon + 1));
+    });
+    return paths;
+}
 //# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -1 +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"}
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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"}

package/dist/ingest/ciSourcePaths.d.ts

@@ -1,46 +1,8 @@
-/**
- * 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

@@ -1 +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"}
+{"version":3,"file":"ciSourcePaths.d.ts","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAGA,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,eAAO,MAAM,mBAAmB,EAAE,YAIjC,CAAC;AAIF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,YAAkC,GACzC,MAAM,EAAE,CAQV"}

package/dist/ingest/ciSourcePaths.js

@@ -1,49 +1,11 @@
-/**
- * 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 [];

package/dist/ingest/ciSourcePaths.js.map

@@ -1 +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"}
+{"version":3,"file":"ciSourcePaths.js","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,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,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,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

@@ -1,93 +1,13 @@
-/**
- * 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.
- */
-/** 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[]);
 }
-/**
- * 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 declare class MissingFeatureCorpusError extends Error {
-    /** The directory that is not there — as resolved, so a reader can print the path examined. */
     readonly directory: string;
     constructor(directory: string);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"gherkinValidation.d.ts","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAK9B"}
+{"version":3,"file":"gherkinValidation.d.ts","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAU/E;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;gBAElC,MAAM,EAAE,SAAS,iBAAiB,EAAE;CAUjD;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAK9B"}

package/dist/ingest/gherkinValidation.js

@@ -1,51 +1,5 @@
-/**
- * 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).
- */
 export function parseErrorsIn(file, source) {
     const parser = new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher());
     try {
@@ -53,25 +7,10 @@ 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) {
@@ -83,26 +22,7 @@ export class UnreadableFeatureCorpusError extends Error {
         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}`);

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;AAOjD,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,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,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,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"}