@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/dispatch/refuse-sibling-valve-flags.d.ts

@@ -0,0 +1,30 @@
+import type { ICommandHandler, ParsedArgs } from '../command-registry.js';
+import type { ICommandIndex } from '../surface/i-command-index.js';
+import type { IInvocationRejection } from './invocation-rejection.js';
+/**
+ * THE pre-run refusal of a VERDICT-VALVE flag ({@link VerdictValveFlag}) the
+ * resolved subverb does not document (round 13, K1) — part of the one
+ * `judgeInvocation`, so the dispatcher and the command-string resolver refuse
+ * the same string.
+ *
+ * `shrk check --fail-on-dead-units` ran the whole sweep and only then exited 3
+ * (the post-run judgement of a sibling-only flag): only `check boundaries`
+ * documents the flag. A valve changes what the exit MEANS, so a run that
+ * ignored one must not print a verdict first. The invocation's documentation
+ * is {@link invocationFlagDocumentation} — its walked usages, the index entries
+ * its path passes through and the handler's `UNDOCUMENTED_FLAG_READS` row — and
+ * the message names the subverbs that do accept the flag. Exits
+ * `usageExitFor(path)`: 3 on a verdict verb, 2 elsewhere.
+ *
+ * The group-level refusal (`refuseUndocumentedFlags`) has already refused a
+ * flag no documentation of the group names, so every flag judged here is one
+ * a SIBLING documents. The index is built only when the walked usages leave a
+ * supplied valve flag unexplained.
+ */
+export declare function refuseSiblingValveFlags(input: {
+    readonly handler: ICommandHandler;
+    readonly matchedPath: readonly string[];
+    readonly parsed: ParsedArgs;
+    readonly index: () => ICommandIndex;
+}): IInvocationRejection | undefined;
+//# sourceMappingURL=refuse-sibling-valve-flags.d.ts.map

package/dist/dispatch/refuse-sibling-valve-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refuse-sibling-valve-flags.d.ts","sourceRoot":"","sources":["../../src/dispatch/refuse-sibling-valve-flags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AActE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,aAAa,CAAC;CACrC,GAAG,oBAAoB,GAAG,SAAS,CAgCnC"}

package/dist/dispatch/refuse-sibling-valve-flags.js

@@ -0,0 +1,65 @@
+import { usageExitFor } from "../exit-codes.js";
+import { GLOBAL_FLAGS } from "./global-flags.js";
+import { unknownFlagRefusal } from "./unknown-flag-refusal.js";
+import { UnknownFlagRefusalMode } from "./unknown-flag-refusal-mode.js";
+import { documentedFlagNames, invocationFlagDocumentation, isFlagDocumented, siblingsDocumenting, } from "./unread-flags.js";
+import { VerdictValveFlag } from "./verdict-valve-flag.js";
+import { walkDeclaredSubverbs } from "./walk-declared-subverbs.js";
+const VALVE_FLAGS = new Set(Object.values(VerdictValveFlag));
+/**
+ * THE pre-run refusal of a VERDICT-VALVE flag ({@link VerdictValveFlag}) the
+ * resolved subverb does not document (round 13, K1) — part of the one
+ * `judgeInvocation`, so the dispatcher and the command-string resolver refuse
+ * the same string.
+ *
+ * `shrk check --fail-on-dead-units` ran the whole sweep and only then exited 3
+ * (the post-run judgement of a sibling-only flag): only `check boundaries`
+ * documents the flag. A valve changes what the exit MEANS, so a run that
+ * ignored one must not print a verdict first. The invocation's documentation
+ * is {@link invocationFlagDocumentation} — its walked usages, the index entries
+ * its path passes through and the handler's `UNDOCUMENTED_FLAG_READS` row — and
+ * the message names the subverbs that do accept the flag. Exits
+ * `usageExitFor(path)`: 3 on a verdict verb, 2 elsewhere.
+ *
+ * The group-level refusal (`refuseUndocumentedFlags`) has already refused a
+ * flag no documentation of the group names, so every flag judged here is one
+ * a SIBLING documents. The index is built only when the walked usages leave a
+ * supplied valve flag unexplained.
+ */
+export function refuseSiblingValveFlags(input) {
+    const supplied = [...input.parsed.flags.keys()].filter((key) => VALVE_FLAGS.has(key) && !GLOBAL_FLAGS.has(key));
+    if (supplied.length === 0)
+        return undefined;
+    const walk = walkDeclaredSubverbs(input.handler, input.matchedPath, input.parsed.positional);
+    // The cheap path: the handler's own usage and the walked level's usage.
+    const own = [input.handler.usage, walk.level.usage];
+    const unsure = supplied.filter((key) => !isFlagDocumented(key, own));
+    if (unsure.length === 0)
+        return undefined;
+    const index = input.index();
+    const docs = invocationFlagDocumentation({
+        handler: input.handler,
+        matchedPath: input.matchedPath,
+        positional: input.parsed.positional,
+        index,
+    });
+    const refused = unsure.filter((key) => !isFlagDocumented(key, docs));
+    if (refused.length === 0)
+        return undefined;
+    const label = walk.path.join(' ');
+    const documentedOn = {};
+    for (const key of refused) {
+        const owners = siblingsDocumenting(key, input.matchedPath, walk.path, index);
+        if (owners.length > 0)
+            documentedOn[key] = owners;
+    }
+    return unknownFlagRefusal({
+        label,
+        flags: refused,
+        known: documentedFlagNames(docs),
+        documentedOn,
+        ...(input.parsed.argv !== undefined ? { argv: input.parsed.argv } : {}),
+        exitCode: usageExitFor(label),
+        mode: UnknownFlagRefusalMode.BeforeRun,
+    });
+}

package/dist/dispatch/subverb-spec.d.ts

@@ -0,0 +1,26 @@
+import type { PositionalMode } from './positional-mode.js';
+/**
+ * One internally-dispatched subverb a handler accepts on `positional[0]`
+ * (`shrk check wiring`, `shrk self-config doctor`).
+ *
+ * Declared on {@link ICommandHandler.subverbs}. The command index lists every
+ * declared subverb as a first-class command, so `surface list`, `help` and the
+ * command-string resolver see it without a catalog row having to vouch for it.
+ */
+export interface ISubverbSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly usage: string;
+    readonly aliases?: readonly string[];
+    /** The complete accepted flag set for this subverb, when declared. */
+    readonly flags?: ReadonlySet<string>;
+    /** What this subverb's own positional[0] means (see {@link PositionalMode}). */
+    readonly positionals?: PositionalMode;
+    /**
+     * Subverbs this subverb dispatches from ITS next positional (`search tuning
+     * list|doctor|explain`, `onboard adopt status|…`). Indexed as first-class
+     * commands and walked by the dispatcher guard exactly like the top level.
+     */
+    readonly subverbs?: readonly ISubverbSpec[];
+}
+//# sourceMappingURL=subverb-spec.d.ts.map

package/dist/dispatch/subverb-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subverb-spec.d.ts","sourceRoot":"","sources":["../../src/dispatch/subverb-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC7C"}

package/dist/dispatch/subverb-spec.js

@@ -0,0 +1 @@
+export {};

package/dist/dispatch/undocumented-flag-reads.d.ts

@@ -0,0 +1,22 @@
+/**
+ * THE ledger of flags a command's code READS that its usage does not show yet
+ * — keyed by the registered (trie) path, flags sorted.
+ *
+ * The post-run unknown-flag detector (`unread-flags.ts`) turns a `0` into
+ * `usageExitFor(path)` when a supplied flag was never read and is not a flag
+ * of the command. "A flag of the command" is its usage documentation PLUS this
+ * ledger: many flags are read only behind a branch (`--force` only when the
+ * output already exists, `--plan-format` only with `--plan`), so a run that
+ * skipped the branch left a real flag unread — and without this ledger, a real
+ * flag no usage names read as dropped input (`export claude-md --write
+ * --force` wrote the file, then exited 2).
+ *
+ * Locked two-way against the code by `r75-flag-read-ledger`: every flag
+ * literal a tracked handler can reach is documented or listed here, and every
+ * entry here is still read and still undocumented. It is a RATCHET — the fix
+ * for an entry is to document the flag in the command's usage, after which the
+ * lock fails until the entry is deleted. On drift the lock prints the entries
+ * as they should read.
+ */
+export declare const UNDOCUMENTED_FLAG_READS: ReadonlyMap<string, readonly string[]>;
+//# sourceMappingURL=undocumented-flag-reads.d.ts.map

package/dist/dispatch/undocumented-flag-reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undocumented-flag-reads.d.ts","sourceRoot":"","sources":["../../src/dispatch/undocumented-flag-reads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAsQzE,CAAC"}

package/dist/dispatch/undocumented-flag-reads.js

@@ -0,0 +1,283 @@
+/**
+ * THE ledger of flags a command's code READS that its usage does not show yet
+ * — keyed by the registered (trie) path, flags sorted.
+ *
+ * The post-run unknown-flag detector (`unread-flags.ts`) turns a `0` into
+ * `usageExitFor(path)` when a supplied flag was never read and is not a flag
+ * of the command. "A flag of the command" is its usage documentation PLUS this
+ * ledger: many flags are read only behind a branch (`--force` only when the
+ * output already exists, `--plan-format` only with `--plan`), so a run that
+ * skipped the branch left a real flag unread — and without this ledger, a real
+ * flag no usage names read as dropped input (`export claude-md --write
+ * --force` wrote the file, then exited 2).
+ *
+ * Locked two-way against the code by `r75-flag-read-ledger`: every flag
+ * literal a tracked handler can reach is documented or listed here, and every
+ * entry here is still read and still undocumented. It is a RATCHET — the fix
+ * for an entry is to document the flag in the command's usage, after which the
+ * lock fails until the entry is deleted. On drift the lock prints the entries
+ * as they should read.
+ */
+export const UNDOCUMENTED_FLAG_READS = new Map([
+    [
+        'apply',
+        [
+            'all-verifications', 'allow-delete-folder', 'allow-folder-ops', 'allow-pack-commands', 'approval',
+            'command', 'contract', 'validate-strict', 'verification',
+        ],
+    ],
+    ['architecture map', ['json']],
+    ['architecture violations', ['json']],
+    ['audit project-coupling', ['fail-on', 'format', 'json', 'no-word-boundary', 'output']],
+    ['baseline diff', ['changed-only', 'since']],
+    ['baseline explain', ['changed-only', 'since']],
+    ['baseline list', ['changed-only', 'id', 'since']],
+    ['baseline update', ['changed-only', 'since']],
+    ['boundaries enforce', ['json']],
+    ['brief', ['chunked']],
+    [
+        'bundle',
+        [
+            'agent-tests', 'all-suggested', 'all-verifications', 'boundaries', 'context-tests', 'coverage', 'drift',
+            'from-pipeline', 'html', 'name', 'report', 'session', 'since', 'template', 'test-impact',
+            'validate-after-group', 'validate-final', 'var', 'verification', 'write-script',
+        ],
+    ],
+    ['changes', ['json', 'label']],
+    [
+        'ci',
+        [
+            'changed-only', 'polyglot', 'pr-comment', 'preset', 'quickstart', 'with-agent-tests', 'with-doctor',
+            'with-pack-signature-status', 'with-pr-checks', 'with-self-config-doctor',
+        ],
+    ],
+    ['codemod', ['top']],
+    ['completion', ['shell']],
+    [
+        'context',
+        [
+            'brief', 'commands-first', 'force', 'format', 'include-commands', 'include-docs', 'machine-json',
+            'maxTokens', 'no-examples', 'no-paths', 'no-rules', 'no-templates', 'preset', 'scope', 'summary', 'tag',
+        ],
+    ],
+    ['contract', ['approval', 'expires', 'expires-at', 'expires-in', 'gates', 'intent', 'plan', 'secret-env']],
+    ['dashboard diff', ['json']],
+    ['dashboard export', ['json']],
+    [
+        'dev',
+        [
+            'all', 'all-verifications', 'allow-pack-commands', 'brief', 'command', 'name', 'open', 'sign',
+            'template', 'var', 'verification',
+        ],
+    ],
+    [
+        'doctor',
+        [
+            'debug', 'fail-on-expired-acknowledgement', 'hide-acknowledged', 'loader-timeout', 'no-cache', 'paths',
+            'show-na', 'strict-all', 'strict-errors', 'strict-warnings', 'verbose',
+        ],
+    ],
+    ['drift', ['changed-only', 'files', 'since', 'staged']],
+    ['explain', ['changed-only', 'id', 'no-cache', 'plane', 'since']],
+    ['explore', ['json']],
+    ['feedback', ['legacy']],
+    [
+        'fix',
+        [
+            'all', 'boundary', 'broken-agent-test-reference', 'broken-helper-reference',
+            'broken-playbook-reference', 'broken-routing-hint-reference', 'convention', 'doctor', 'list',
+            'missing-command-hint', 'missing-convention-reference', 'missing-template-reference', 'pack-conflicts',
+            'self-config', 'stale-pack-signature',
+        ],
+    ],
+    ['framework', ['no-packs']],
+    ['gates explain', ['changed-only', 'id', 'no-cache', 'plane', 'since']],
+    ['gates list', ['no-cache']],
+    ['gates scaffold-selftest', ['no-cache']],
+    ['gen', ['overwrite', 'sign']],
+    ['generated list', ['id']],
+    ['graph', ['compact', 'has-unresolved-imports', 'table']],
+    ['help', ['full-help', 'verbose']],
+    ['helper', ['output', 'save-plan', 'sign', 'source']],
+    [
+        'impact',
+        [
+            'language', 'no-persist', 'no-polyglot', 'plan-format', 'polyglot-mode', 'polyglot-only', 'task',
+            'via-graph', 'write-starter',
+        ],
+    ],
+    ['import', ['out']],
+    [
+        'ingest',
+        [
+            'adopt', 'depth', 'docs-first', 'dry-run', 'exclude', 'include', 'json', 'output', 'preset', 'profile',
+            'task', 'write-patch',
+        ],
+    ],
+    ['init', ['with-skill']],
+    ['install smoke', ['temp-dir']],
+    [
+        'knowledge add',
+        [
+            'add-applies-when', 'add-forbidden-path', 'add-related', 'add-required-profile', 'add-scope', 'add-tag',
+            'remove-anchor-id', 'remove-applies-when', 'remove-forbidden-path', 'remove-reference',
+            'remove-related', 'remove-required-profile', 'remove-scope', 'remove-tag',
+        ],
+    ],
+    ['knowledge remove', ['id']],
+    ['knowledge search', ['appliesWhen', 'tag']],
+    ['knowledge stale-check', ['paths']],
+    [
+        'knowledge update',
+        [
+            'add-applies-when', 'add-forbidden-path', 'add-required-profile', 'add-scope', 'add-tag',
+            'applies-when', 'id', 'related', 'remove-applies-when', 'remove-forbidden-path',
+            'remove-required-profile', 'remove-scope', 'remove-tag', 'scope', 'tag',
+        ],
+    ],
+    ['knowledge verify', ['paths']],
+    ['languages', ['explain-policy']],
+    ['memory diff', ['json']],
+    ['memory drift', ['json']],
+    ['memory reset', ['json']],
+    ['onboard', ['diff-format', 'force', 'format', 'no-auto-regenerate', 'output']],
+    ['owners impact', ['json']],
+    ['owners match', ['json']],
+    ['ownership for', ['files']],
+    [
+        'pack author preview',
+        [
+            'applies-when', 'bad', 'description', 'forbidden', 'forbidden-path', 'good', 'owner', 'produced-anchor',
+            'rationale', 'registration-hint', 'required-anchor', 'required-helper', 'required-profile', 'scope',
+            'tag', 'verification',
+        ],
+    ],
+    ['packs conflicts', ['json']],
+    ['packs contributions', ['json']],
+    ['packs sign', ['out']],
+    ['packs signature-status', ['json']],
+    ['packs watch', ['consumer', 'json']],
+    ['paths best', ['json']],
+    ['paths search', ['json']],
+    ['pipelines context', ['maxTokens', 'scope']],
+    ['plan simulate', ['json']],
+    [
+        'policy check',
+        [
+            'changed-only', 'explain-overrides', 'files', 'local-files', 'no-pack-policies',
+            'record-override-audit', 'require-signed-policy-packs', 'since', 'staged',
+        ],
+    ],
+    [
+        'policy get',
+        [
+            'bundle', 'local-files', 'no-pack-policies', 'plan', 'require-signed-policy-packs', 'session',
+        ],
+    ],
+    ['policy list', ['bundle', 'local-files', 'plan', 'session']],
+    ['policy run', ['local-files', 'session']],
+    ['policy-lint explain', ['id']],
+    ['pr', ['from-bundle', 'from-session', 'full', 'json', 'verbose']],
+    ['provenance show', ['id']],
+    ['recommend', ['actions-only', 'full', 'include-gated', 'machine-json', 'top']],
+    [
+        'release',
+        [
+            'consumer-root', 'include-docs-check', 'include-examples-check', 'no-assertions', 'target',
+            'with-knowledge-check', 'with-product-check',
+        ],
+    ],
+    [
+        'report',
+        [
+            'bundle', 'bundle-diff', 'impact-dir', 'include-boundaries', 'include-memory', 'review',
+            'runtime-compat', 'safety-matrix',
+        ],
+    ],
+    ['review', ['bundle', 'quality-baseline', 'v2', 'v3']],
+    ['risk', ['include-memory']],
+    ['rounds show', ['id']],
+    [
+        'rules add',
+        [
+            'add-applies-when', 'add-forbidden-path', 'add-related', 'add-required-profile', 'add-scope', 'add-tag',
+            'remove-anchor-id', 'remove-applies-when', 'remove-forbidden-path', 'remove-reference',
+            'remove-related', 'remove-required-profile', 'remove-scope', 'remove-tag', 'type',
+        ],
+    ],
+    ['rules relevant', ['appliesWhen', 'tag']],
+    ['rules remove', ['id']],
+    ['rules scaffold', ['reason']],
+    [
+        'rules update',
+        [
+            'add-applies-when', 'add-forbidden-path', 'add-required-profile', 'add-scope', 'add-tag',
+            'applies-when', 'id', 'related', 'remove-anchor-id', 'remove-applies-when', 'remove-forbidden-path',
+            'remove-required-profile', 'remove-scope', 'remove-tag', 'scope', 'tag',
+        ],
+    ],
+    ['schemas inventory', ['json']],
+    ['schemas write', ['json']],
+    ['search', ['full', 'json', 'top', 'type', 'verbose']],
+    ['search-structural', ['description', 'force', 'id', 'title']],
+    ['self-config', ['source']],
+    [
+        'smart-context plan-ahead',
+        [
+            'ai-plan', 'budget', 'cache-reference-threshold', 'cache-replay-threshold', 'debug', 'enhance',
+            'enhance-passes', 'expansion-limit', 'expansion-tokens', 'focused', 'log-prompt', 'no-cache',
+            'no-enhance', 'no-instructions', 'no-polish', 'no-refresh-index', 'plan', 'plus', 'refresh', 'save',
+            'save-conversation', 'seed-tokens', 'since', 'stage1-max-tokens', 'stream', 'task-type', 'tiny-only',
+        ],
+    ],
+    [
+        'spec',
+        [
+            'all-verifications', 'allow-delete-folder', 'allow-folder-ops', 'allow-pack-commands',
+            'allow-unknown-target', 'approval', 'asset-preview', 'batch', 'command', 'contract', 'explain-dispatch',
+            'no-verify-signature', 'report', 'require-signature', 'session', 'target', 'trace', 'validate',
+            'validate-strict', 'verification', 'verify-signature',
+        ],
+    ],
+    [
+        'spec implement',
+        [
+            'all-verifications', 'allow-delete-folder', 'allow-folder-ops', 'allow-pack-commands',
+            'allow-unknown-target', 'approval', 'asset-preview', 'batch', 'command', 'contract', 'explain-dispatch',
+            'force', 'no-verify-signature', 'reason', 'report', 'require-signature', 'session', 'target', 'trace',
+            'validate', 'validate-strict', 'verification', 'verify-signature', 'write',
+        ],
+    ],
+    ['spec verify', ['apply']],
+    [
+        'task',
+        [
+            'actions-only', 'brief', 'commands-first', 'compact', 'show-coverage-gaps', 'summary', 'verbose',
+        ],
+    ],
+    ['templates drift', ['paths']],
+    ['templates preview', ['json']],
+    ['templates remove', ['id']],
+    ['templates search', ['json']],
+    [
+        'templates smoke',
+        [
+            'ci', 'debounce', 'format', 'hide', 'llm-recommendations', 'min-severity', 'once', 'output', 'pack',
+            'paths', 'provider', 'report', 'template', 'var', 'watch',
+        ],
+    ],
+    ['templates snapshot', ['json']],
+    [
+        'templates update',
+        [
+            'applies-when', 'id', 'reference', 'related', 'remove-anchor-id', 'remove-reference', 'scope', 'tag',
+        ],
+    ],
+    ['test', ['debounce', 'once', 'paths', 'pipeline', 'rule', 'template']],
+    ['tests impact', ['json']],
+    ['tests missing', ['json']],
+    ['trace', ['language']],
+    ['understand-task', ['explain', 'task']],
+    ['validate-change', ['json']],
+    ['watch', ['replace']],
+]);

package/dist/dispatch/unknown-flag-refusal-mode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * When a flag is refused — which decides the one sentence after the `! …`
+ * lines of {@link unknownFlagRefusal} (round 13: one format, three moments).
+ */
+export declare enum UnknownFlagRefusalMode {
+    /** Refused before anything ran (the pre-run judgement, or a verb's own allow-list). */
+    BeforeRun = "before-run",
+    /** The run ignored it and its result is refused — the exit becomes `usageExitFor(path)`. */
+    RefusedAfterRun = "refused-after-run",
+    /** The run ignored it; the exit is kept (a found failure, a presentation flag, a non-verdict verb). */
+    WarnedAfterRun = "warned-after-run"
+}
+//# sourceMappingURL=unknown-flag-refusal-mode.d.ts.map

package/dist/dispatch/unknown-flag-refusal-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-flag-refusal-mode.d.ts","sourceRoot":"","sources":["../../src/dispatch/unknown-flag-refusal-mode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,sBAAsB;IAChC,uFAAuF;IACvF,SAAS,eAAe;IACxB,4FAA4F;IAC5F,eAAe,sBAAsB;IACrC,uGAAuG;IACvG,cAAc,qBAAqB;CACpC"}

package/dist/dispatch/unknown-flag-refusal-mode.js

@@ -0,0 +1,13 @@
+/**
+ * When a flag is refused — which decides the one sentence after the `! …`
+ * lines of {@link unknownFlagRefusal} (round 13: one format, three moments).
+ */
+export var UnknownFlagRefusalMode;
+(function (UnknownFlagRefusalMode) {
+    /** Refused before anything ran (the pre-run judgement, or a verb's own allow-list). */
+    UnknownFlagRefusalMode["BeforeRun"] = "before-run";
+    /** The run ignored it and its result is refused — the exit becomes `usageExitFor(path)`. */
+    UnknownFlagRefusalMode["RefusedAfterRun"] = "refused-after-run";
+    /** The run ignored it; the exit is kept (a found failure, a presentation flag, a non-verdict verb). */
+    UnknownFlagRefusalMode["WarnedAfterRun"] = "warned-after-run";
+})(UnknownFlagRefusalMode || (UnknownFlagRefusalMode = {}));

package/dist/dispatch/unknown-flag-refusal.d.ts

@@ -0,0 +1,22 @@
+import type { IInvocationRejection } from './invocation-rejection.js';
+import type { IUnknownFlagRefusalInput } from './i-unknown-flag-refusal-input.js';
+/**
+ * THE wording of a refused flag (round 13) — one format on every path that
+ * refuses one:
+ *
+ *   ! `shrk gates check`: --fail-on-dead-units is not a flag of this command. Did you mean --allow-empty?
+ *     Accepts: --json, --margin, …            (only when the command declares its complete flag set)
+ *     Refused before anything ran — a result that ignored --fail-on-dead-units would not be a pass (exit 3). Run `shrk help gates check` for the flags it accepts.
+ *
+ * There were two: the declared-flag guard printed `Unknown flag "--x" for
+ * \`shrk gates check\`. Accepts: …` while the documentation refusal printed
+ * `! \`shrk policy-lint\`: --x is not a flag of this command.` — two refusal
+ * paths for one judgement (`judgeInvocation`), and `check boundaries` / `reuse
+ * coverage` kept a third inside their bodies. Every one now builds its message
+ * here; only the closing sentence says WHEN (the {@link UnknownFlagRefusalMode}):
+ * before the run, or after a run that ignored the flag. A flag a sibling
+ * subverb documents says which (`— only \`shrk check boundaries\` documents
+ * it`). A `--offset -1` misread names the flag the number was meant for.
+ */
+export declare function unknownFlagRefusal(input: IUnknownFlagRefusalInput): IInvocationRejection;
+//# sourceMappingURL=unknown-flag-refusal.d.ts.map

package/dist/dispatch/unknown-flag-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-flag-refusal.d.ts","sourceRoot":"","sources":["../../src/dispatch/unknown-flag-refusal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAGlF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,GAAG,oBAAoB,CAkCxF"}

package/dist/dispatch/unknown-flag-refusal.js

@@ -0,0 +1,57 @@
+import { misreadValueHint, spellFlagAsTyped } from "../command-registry.js";
+import { closestMatches } from "./closest-match.js";
+import { InvocationRejectionKind } from "./invocation-rejection-kind.js";
+import { UnknownFlagRefusalMode } from "./unknown-flag-refusal-mode.js";
+/**
+ * THE wording of a refused flag (round 13) — one format on every path that
+ * refuses one:
+ *
+ *   ! `shrk gates check`: --fail-on-dead-units is not a flag of this command. Did you mean --allow-empty?
+ *     Accepts: --json, --margin, …            (only when the command declares its complete flag set)
+ *     Refused before anything ran — a result that ignored --fail-on-dead-units would not be a pass (exit 3). Run `shrk help gates check` for the flags it accepts.
+ *
+ * There were two: the declared-flag guard printed `Unknown flag "--x" for
+ * \`shrk gates check\`. Accepts: …` while the documentation refusal printed
+ * `! \`shrk policy-lint\`: --x is not a flag of this command.` — two refusal
+ * paths for one judgement (`judgeInvocation`), and `check boundaries` / `reuse
+ * coverage` kept a third inside their bodies. Every one now builds its message
+ * here; only the closing sentence says WHEN (the {@link UnknownFlagRefusalMode}):
+ * before the run, or after a run that ignored the flag. A flag a sibling
+ * subverb documents says which (`— only \`shrk check boundaries\` documents
+ * it`). A `--offset -1` misread names the flag the number was meant for.
+ */
+export function unknownFlagRefusal(input) {
+    const closest = [];
+    let message = '';
+    for (const key of input.flags) {
+        const misread = misreadValueHint(key, input.argv);
+        const near = misread === undefined ? closestMatches(key, input.known, 1)[0] : undefined;
+        if (near !== undefined)
+            closest.push(`shrk ${input.label} --${near}`);
+        const owners = input.documentedOn?.[key] ?? [];
+        const only = owners.length > 0 ? ` — only ${owners.map((p) => `\`shrk ${p}\``).join(' and ')} document${owners.length > 1 ? '' : 's'} it` : '';
+        message +=
+            misread !== undefined
+                ? `! \`shrk ${input.label}\`: ${misread}.\n`
+                : `! \`shrk ${input.label}\`: ${spellFlagAsTyped(key, input.argv)} is not a flag of this command${only}.` +
+                    `${near !== undefined ? ` Did you mean --${near}?` : ''}\n`;
+    }
+    if (input.accepts !== undefined && input.accepts.length > 0) {
+        message += `  Accepts: ${input.accepts.map((f) => `--${f}`).join(', ')}.\n`;
+    }
+    const spelled = input.flags.map((key) => spellFlagAsTyped(key, input.argv)).join(', ');
+    const help = `Run \`shrk help ${input.label}\` for the flags it accepts.`;
+    const mode = input.mode ?? UnknownFlagRefusalMode.BeforeRun;
+    message +=
+        mode === UnknownFlagRefusalMode.BeforeRun
+            ? `  Refused before anything ran — a result that ignored ${spelled} would not be a pass (exit ${input.exitCode}). ${help}\n`
+            : mode === UnknownFlagRefusalMode.RefusedAfterRun
+                ? `  The run ignored ${spelled}, so its result is refused — not a pass (exit ${input.exitCode}). ${help}\n`
+                : `  The run ignored ${spelled} (exit ${input.exitCode} kept). ${help}\n`;
+    return {
+        message,
+        exitCode: input.exitCode,
+        kind: InvocationRejectionKind.UnknownFlag,
+        ...(closest.length > 0 ? { closest } : {}),
+    };
+}