@shrkcrft/cli 0.1.0-alpha.26 → 0.1.0-alpha.28

package/dist/commands/check.command.js

@@ -686,7 +686,32 @@ async function checkWiring(args) {
         for (const d of report.diagnostics)
             process.stdout.write(`  ! ${d}\n`);
     }
+    // Rules that checked NOTHING, reported per-rule. `matchedNothing` gives the
+    // count; this names them, because "which rule went stale" is the actionable
+    // half. A `failOnEmpty` rule turns its own skip into a hard failure.
+    if (report.skipped.length > 0) {
+        process.stdout.write('\nRules that checked nothing:\n');
+        for (const sk of report.skipped) {
+            process.stdout.write(`  ${sk.failed ? '✗' : '–'} ${sk.ruleId} ${sk.failed ? 'FAILED' : 'SKIPPED'} — ${sk.reason}\n`);
+        }
+        if (report.skipped.some((sk) => !sk.failed)) {
+            process.stdout.write('  Fix the selector, or set `failOnEmpty: true` once the rule is known to have\n' +
+                '  real subjects. Run `shrk gates coverage` to audit every plane at once.\n');
+        }
+    }
+    // A sink that extracted 0 ids while the source had some is a real failure, but
+    // almost always a stale SINK glob — say so instead of listing N "unwired"
+    // tokens with no explanation.
+    for (const r of report.rules) {
+        if (!r.emptySink)
+            continue;
+        process.stdout.write(`\n  ! ${r.ruleId}: the registered side extracted 0 ids while ${r.declaredCount} were declared —\n` +
+            `    every declared token "fails". Check the registered glob before chasing the tokens.\n`);
+    }
     if (report.violations.length === 0 && report.diagnostics.length === 0) {
+        // A failOnEmpty skip produces no violation object but IS a failure.
+        if (report.verdict === 'errors')
+            return ExitCode.Failure;
         if (allEvaluated) {
             // Every configured rule ran — the earned full green.
             process.stdout.write('\nNo wiring violations — every declared token is registered. ✓\n');
@@ -709,7 +734,9 @@ async function checkWiring(args) {
         process.stdout.write(`\n[${r.severity}] ${r.ruleId}${r.description ? ' — ' + r.description : ''}\n`);
         process.stdout.write(`  declared ${r.declaredCount} / registered ${r.registeredCount} — ${r.violations.length} not wired:\n`);
         for (const v of r.violations.slice(0, 50)) {
-            process.stdout.write(`    • ${v.token}  (${v.file}:${v.line})\n`);
+            const where = `(${v.file}:${v.line})`;
+            const hop = v.hop !== undefined ? ` [hop ${v.hop}]` : '';
+            process.stdout.write(v.message ? `    • ${v.message}  ${where}${hop}\n` : `    • ${v.token}  ${where}${hop}\n`);
         }
         if (r.violations.length > 50) {
             process.stdout.write(`    … (${r.violations.length - 50} more)\n`);

package/dist/commands/command-catalog.d.ts.map

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

package/dist/commands/command-catalog.js

@@ -406,6 +406,118 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'policy-lint explain',
+        description: 'Dry-run ONE policyRule and print every hit with file:line — INCLUDING the hits an exemption (exemptFiles / exemptLines) or the lexical scan zone dropped, each labelled with which one applied. The author-loop view of what the gate sees. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'registry duplicates',
+        description: 'Ids declared more than once across roots in a config-defined registry — a latent bug the compiler cannot see (whichever registration wins at runtime is an accident of load order). Every declaration site is reported. Exit 1 on duplicates, 2 when the registry matched 0 ids. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'gates list',
+        description: 'Every data-defined rule across every plane (wiring / policy / registry / registration / baseline / generated) with its severity and empty-match policy. [--plane <p>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'gates coverage',
+        description: 'The stale-selector detector: what every data-defined rule actually MATCHED against the live tree, flagging each rule that matched 0 files/ids (a rule matching nothing is a bug in the rule, never a pass) and running each rule\'s declared selfTest expectations. Run it in CI so a rule quietly dying is itself a failure. Exit 2 when a rule matched nothing, 1 when it set failOnEmpty. [--plane <p>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'gates explain',
+        description: 'Universal rule introspection: for a rule of ANY plane, print the concrete inputs it resolved — files matched, ids extracted with file:line, and the computed diff. Dispatches to the plane-specific explainer. [--plane <p>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'baseline list',
+        description: 'Every declared baseline: what it pins, how it recomputes, and which direction of drift fails. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'baseline check',
+        description: 'Recompute every committed baseline (adoption ledger / API digest / coverage ratchet / allow-list) and fail on drift. TWO-WAY by default: a silently LOST entry fails exactly like a gained one. Rules from sharkcraft.config.ts baselines[]. Runs the declared compute command for `kind: "command"` rules. [--id X] [--changed-only] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'baseline diff',
+        description: 'Human-readable +added / −removed for each baseline, without a verdict — the inspection verb. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'baseline update',
+        description: 'Rewrite a committed baseline from the current value — the explicit, reviewable bless step (deliberately a separate verb from `check` so a drift can never be blessed by accident). Writes files. [--id X] [--dry-run] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Apply,
+    }),
+    entry({
+        command: 'baseline explain',
+        description: 'What ONE baseline computes and compares — the command or extractor, the canonical form, both entry counts, and the diff — without turning it into a verdict. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'generated list',
+        description: 'Every declared generated-artifact rule: its globs, regen command, and "do not edit" header contract. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'generated check',
+        description: 'Regenerate into a temp dir and diff BOTH ways — catching a hand-edited generated file AND a regen that writes a subset — plus the provenance-header contract (missing header on a generated file, header on a hand-written one). `--headers-only` never spawns. Rules from sharkcraft.config.ts generatedArtifacts[]. [--id X] [--headers-only] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'generated update',
+        description: 'Run the declared regen command in place — the one-command bless step after an intentional source change. Writes files. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Apply,
+    }),
+    entry({
+        command: 'generated explain',
+        description: 'What ONE generated-artifact rule sees right now: files matched, header-contract results, mislabel candidates — without running the regen. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
     entry({
         command: 'wiring explain',
         description: 'Dry-run ONE configured wiringRule and print the declared set + registered set it extracts (token + file:line), the alias-resolved set-difference, and the verdict — the author-loop view of what `check wiring` sees, without re-running the gate. [--json]',

package/dist/commands/delegate.command.d.ts

@@ -1,5 +1,6 @@
-import { type IAiProvider } from '@shrkcrft/ai';
+import { type IAiProvider, type IQueryDescriptor, type QueryExecutor } from '@shrkcrft/ai';
 import { type IDelegateRecipe } from '@shrkcrft/config';
+import { type IDelegateAnalysisReport, type IDelegateFailureContext, type IGroundingFacts, type IResolvedDelegateRecipe, type ISharkcraftInspection } from '@shrkcrft/inspector';
 import { type IDroppedOp } from '@shrkcrft/generator';
 import { type ICommandHandler } from '../command-registry.js';
 export type DelegateRunStatus = 'no-provider' | 'generate-failed' | 'guardrail-refused' | 'package-error' | 'conflicts' | 'sign-failed' | 'no-verification' | 'generated' | 'applied' | 'apply-failed' | 'verify-failed';
@@ -16,6 +17,14 @@ export interface IExecuteDelegateRunInput {
     planSecret?: string;
     /** Validation report dir. Default `.sharkcraft/delegate/reports`. */
     reportDir?: string;
+    /**
+     * Optional retry advisor (Phase 2, `--assisted-retry`). Between retryable
+     * failures it may return a corrected-instruction string, appended to the
+     * deterministic retry feedback. Best-effort: a null return / throw is ignored,
+     * so the deterministic loop is never blocked by the advisor. Injectable for
+     * tests; the cli wires one from a `retry-analysis` recipe.
+     */
+    retryAdvisor?: (failure: IDelegateFailureContext, attempt: number) => Promise<string | null>;
 }
 export interface IExecuteDelegateRunResult {
     status: DelegateRunStatus;
@@ -61,5 +70,71 @@ export declare function gatherRecipeContext(projectRoot: string, recipe: IDelega
  * retried. Takes an already-resolved recipe + provider so tests inject a fake.
  */
 export declare function executeDelegateRun(input: IExecuteDelegateRunInput): Promise<IExecuteDelegateRunResult>;
+export type DelegateAnalyzeStatus = 'no-provider' | 'analyze-failed' | 'analyzed';
+export interface IExecuteDelegateAnalyzeInput {
+    task: string;
+    /** An analysis recipe (mode === 'analysis'); its provider/model are folded. */
+    recipe: IResolvedDelegateRecipe;
+    /** The deterministic ground truth produced by `runGroundingReport`. */
+    facts: IGroundingFacts;
+    /** Injectable for tests; `null` means no local LLM is reachable. */
+    provider: IAiProvider | null;
+    /** Drop non-grounded findings instead of keeping+flagging them. */
+    strict?: boolean;
+    /**
+     * Read-only query executor for the bounded query loop (Phase 3). Injected by
+     * the cli from the inspection; absent (or a recipe with no `allowedQueries` /
+     * `maxQueryRounds`) ⇒ single-shot analysis. Tests inject a fake.
+     */
+    queryExecutor?: QueryExecutor;
+    /** Human-readable provider label for the report when no model id is returned. */
+    providerLabel: string;
+    /** Timestamp source (kept out of the core so tests are deterministic). */
+    generatedAt: string;
+}
+/** Human descriptions of the read-only queries shown to the model in the loop. */
+export declare const DELEGATE_QUERY_CATALOG: readonly IQueryDescriptor[];
+/**
+ * Build the read-only query executor: maps each `DELEGATE_QUERY_IDS` value to a
+ * deterministic inspector function. Every query is read-only — there is no
+ * write/apply query. Returns compact text + the entities it surfaced (merged
+ * into the analysis ground truth so a finding citing a pulled fact is grounded).
+ */
+export declare function buildAnalysisQueryExecutor(inspection: ISharkcraftInspection, task: string): QueryExecutor;
+export interface IExecuteDelegateAnalyzeResult {
+    status: DelegateAnalyzeStatus;
+    recipeId: string;
+    report: IDelegateAnalysisReport;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    retried?: boolean;
+}
+/**
+ * The testable analysis core (no I/O beyond the injected provider). Runs the
+ * model on the deterministic ground truth, cross-checks its findings, and
+ * assembles the advisory report. NEVER writes — analysis mode is read-only.
+ * `provider === null` degrades to a deterministic grounding-only report (ok).
+ */
+export declare function executeDelegateAnalyze(input: IExecuteDelegateAnalyzeInput): Promise<IExecuteDelegateAnalyzeResult>;
+/** The single corrected instruction to feed back: a grounded finding wins. */
+export declare function correctedInstruction(report: IDelegateAnalysisReport): string | null;
+export interface IRetryAdvisorDeps {
+    /** A `mode: 'analysis'`, `groundedOn: 'delegate-failure'` recipe. */
+    retryRecipe: IResolvedDelegateRecipe;
+    provider: IAiProvider | null;
+    providerLabel: string;
+    /** The patch recipe being retried (named in the advisor prompt). */
+    patchRecipeId: string;
+}
+/**
+ * Build a retry advisor from a `retry-analysis` recipe: it grounds on the failed
+ * attempt (`buildDelegateFailureFacts`), runs the analysis model, and returns the
+ * single corrected instruction. Read-only — it never writes; a null provider or
+ * an empty analysis yields `null` (no enrichment). The corrected instruction is
+ * cross-checked against the failure ground truth just like any analysis finding.
+ */
+export declare function buildRetryAnalysisAdvisor(deps: IRetryAdvisorDeps): (failure: IDelegateFailureContext, attempt: number) => Promise<string | null>;
 export declare const delegateCommand: ICommandHandler;
 //# sourceMappingURL=delegate.command.d.ts.map

package/dist/commands/delegate.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delegate.command.d.ts","sourceRoot":"","sources":["../../src/commands/delegate.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAqB,KAAK,eAAe,EAA0B,MAAM,kBAAkB,CAAC;AASnG,OAAO,EAOL,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,WAAW,GACX,aAAa,GACb,iBAAiB,GACjB,WAAW,GACX,SAAS,GACT,cAAc,GACd,eAAe,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACnC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IACtE,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAwBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAsBxF;AA6BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,yBAAyB,CAAC,CA4BpC;AA2gBD,eAAO,MAAM,eAAe,EAAE,eAmB7B,CAAC"}
+{"version":3,"file":"delegate.command.d.ts","sourceRoot":"","sources":["../../src/commands/delegate.command.ts"],"names":[],"mappings":"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"}