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

package/dist/commands/self-config-xrefs.command.js

@@ -0,0 +1,170 @@
+/**
+ * `shrk self-config resolve <id>` and `shrk self-config xrefs` — the lookup and
+ * listing verbs over THE declared cross-reference collector.
+ *
+ * Ids carry no namespace prefix, so "is this `related` id live, and what is
+ * it?" used to mean grepping several asset sources in turn. `resolve` answers
+ * it for one id: every registry that has it (most specific first, with the verb
+ * that shows it) and every declared field pointing at it. `xrefs` prints the
+ * extracted set — the contract `gates explain` honours for gate rules. Both are
+ * thin renderers: the answers come from `buildDeclaredXrefReport` and the
+ * reference registry, never from a walk of their own.
+ */
+import { ALL_ID_REFERENCE_KINDS, buildDeclaredXrefReport, DECLARED_XREF_FIELDS, declaredXrefSummaryLine, DeclaredXrefStatus, inspectSharkcraft, isBrokenXref, nearestIds, referenceIdPool, referenceKindsOf, reverseXrefs, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
+import { asJson, header } from "../output/format-output.js";
+/**
+ * The verb that shows an id of each kind. Every entry must resolve through the
+ * live command index (`r75-xrefs-cli.test.ts` locks it), so a renamed verb
+ * fails the day it is renamed instead of being printed as a dead command. A
+ * kind with no show / list verb is absent — never guessed.
+ */
+export const REFERENCE_KIND_VERBS = Object.freeze({
+    template: 'shrk templates get <id>',
+    pipeline: 'shrk pipelines get <id>',
+    playbook: 'shrk playbooks get <id>',
+    policy: 'shrk policy get <id>',
+    construct: 'shrk constructs get <id>',
+    helper: 'shrk helper get <id>',
+    'boundary-rule': 'shrk boundaries list',
+    'path-convention': 'shrk paths get <id>',
+    rule: 'shrk rules get <id>',
+    knowledge: 'shrk knowledge get <id>',
+    convention: 'shrk conventions get <id>',
+    'migration-profile': 'shrk profiles get <id>',
+    'registration-hint': 'shrk registrations get <id>',
+    'scaffold-pattern': 'shrk scaffolds get <id>',
+});
+function verbFor(kind, id) {
+    return REFERENCE_KIND_VERBS[kind]?.replace('<id>', id);
+}
+function rowLabel(r) {
+    return `${r.sourceKind}:${r.sourceId} ${r.field}${r.facetId ? ` [${r.facetId}]` : ''}`;
+}
+function statusText(r) {
+    switch (r.status) {
+        case DeclaredXrefStatus.Ok:
+            return `→ ${r.resolvedAs.join(' | ')}`;
+        case DeclaredXrefStatus.Dangling:
+            return `UNRESOLVED — no registry has this id${r.didYouMean.length > 0 ? ` (did you mean "${r.didYouMean[0]}"?)` : ''}`;
+        case DeclaredXrefStatus.WrongKind:
+            return `WRONG KIND — resolves as ${r.resolvedAs.join(' | ')}; the field accepts ${r.accepts === 'any' ? 'any kind' : r.accepts.join(' | ')}`;
+        default:
+            return 'NOT VERIFIED — its registry was not warmed, or is empty';
+    }
+}
+export const selfConfigResolveCommand = {
+    name: 'resolve',
+    description: 'Which registry an id resolves in — every kind, most specific first, with the verb that shows it — and every declared cross-reference pointing at it; did-you-mean when it resolves nowhere. Exit 0 resolved · 1 unresolved · 3 no id.',
+    usage: 'shrk self-config resolve <id> [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const id = args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk self-config resolve <id> [--json]\n');
+            return ExitCode.UsageError;
+        }
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        // Warms every registry, so a construct / playbook id resolves like any other.
+        const report = await buildDeclaredXrefReport(inspection);
+        const kinds = referenceKindsOf(inspection, id);
+        const pointedAtBy = reverseXrefs(report, id);
+        const didYouMean = kinds.length === 0 ? nearestIds(id, referenceIdPool(inspection, ALL_ID_REFERENCE_KINDS)).map((n) => n.id) : [];
+        const exit = kinds.length > 0 ? ExitCode.VerifiedPass : ExitCode.Failure;
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                id,
+                resolved: kinds.length > 0,
+                resolvedAs: kinds.map((kind) => ({ kind, ...(verbFor(kind, id) ? { verb: verbFor(kind, id) } : {}) })),
+                pointedAtBy: pointedAtBy.map((r) => ({
+                    sourceKind: r.sourceKind,
+                    sourceId: r.sourceId,
+                    field: r.field,
+                    ...(r.facetId ? { facetId: r.facetId } : {}),
+                    status: r.status,
+                    ...(r.file ? { file: r.file } : {}),
+                })),
+                didYouMean,
+                exitCode: exit,
+            }) + '\n');
+            return exit;
+        }
+        process.stdout.write(header(`Resolve: ${id}`));
+        if (kinds.length > 0) {
+            process.stdout.write('  resolves as (most specific first):\n');
+            for (const kind of kinds) {
+                const verb = verbFor(kind, id);
+                process.stdout.write(`    • ${kind.padEnd(18)}${verb ? `  ${verb}` : ''}\n`);
+            }
+        }
+        else {
+            process.stdout.write(`  UNRESOLVED — no registry has "${id}" (checked ${ALL_ID_REFERENCE_KINDS.length} kinds).\n`);
+            if (didYouMean.length > 0)
+                process.stdout.write(`  did you mean: ${didYouMean.join(', ')}\n`);
+        }
+        process.stdout.write(`\n  pointed at by (${pointedAtBy.length}):\n`);
+        if (pointedAtBy.length === 0)
+            process.stdout.write('    (no declared cross-reference names it)\n');
+        for (const r of pointedAtBy) {
+            process.stdout.write(`    • ${rowLabel(r)}${r.status === DeclaredXrefStatus.Ok ? '' : `  (${r.status})`}${r.file ? `  — ${r.file}` : ''}\n`);
+        }
+        return exit;
+    },
+};
+/** The source kinds the collector walks — the only valid `--source <kind>:` prefixes. */
+const SOURCE_KINDS = [...new Set(DECLARED_XREF_FIELDS.map((f) => f.sourceKind))];
+export const selfConfigXrefsCommand = {
+    name: 'xrefs',
+    description: 'Every declared cross-reference id — knowledge related / seeAlso / supersededBy / action hints, construct related* + facets that declare resolvesAs, boundary related*, template related — with the namespace(s) it resolved into and its status. `--source <kind>:<id>` narrows to one asset, `--dangling-only` keeps the broken ones. Exit 0 (a listing); 3 on a malformed --source.',
+    usage: 'shrk self-config xrefs [--source <kind>:<id>] [--dangling-only] [--json]',
+    booleanFlags: new Set(['json', 'dangling-only']),
+    async run(args) {
+        let source;
+        if (args.flags.has('source')) {
+            const raw = flagString(args, 'source') ?? '';
+            const at = raw.indexOf(':');
+            const kind = at > 0 ? raw.slice(0, at) : '';
+            const id = at > 0 ? raw.slice(at + 1) : '';
+            if (!kind || !id || !SOURCE_KINDS.includes(kind)) {
+                process.stderr.write(`--source must be <kind>:<id> with <kind> one of: ${SOURCE_KINDS.join(', ')} (got "${raw}").\n`);
+                return ExitCode.UsageError;
+            }
+            source = { kind, id };
+        }
+        const danglingOnly = flagBool(args, 'dangling-only');
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const report = await buildDeclaredXrefReport(inspection);
+        const inScope = (r) => !source || (r.sourceKind === source.kind && r.sourceId === source.id);
+        const rows = report.rows.filter((r) => inScope(r) && (!danglingOnly || isBrokenXref(r)));
+        const issues = report.issues.filter(inScope);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                schema: report.schema,
+                ...(source ? { source: `${source.kind}:${source.id}` } : {}),
+                danglingOnly,
+                shown: rows.length,
+                counts: report.counts,
+                examined: report.examined,
+                rows,
+                issues,
+            }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        const scope = source ? ` — ${source.kind}:${source.id}` : '';
+        process.stdout.write(header(`Declared cross-references${scope} (${rows.length})`));
+        process.stdout.write(`  ${declaredXrefSummaryLine(report)}\n\n`);
+        if (rows.length === 0) {
+            process.stdout.write(`  (${danglingOnly ? 'no dangling or wrong-kind id' : 'no declared cross-reference id'}${source ? ' on this asset' : ''})\n`);
+        }
+        for (const r of rows) {
+            process.stdout.write(`  • ${rowLabel(r)} → ${r.targetId}  ${statusText(r)}\n`);
+        }
+        if (issues.length > 0) {
+            process.stdout.write(`\n  declaration issues (${issues.length}):\n`);
+            for (const i of issues)
+                process.stdout.write(`    ${i.severity.padEnd(7)} [${i.code}] ${i.message}\n`);
+        }
+        return ExitCode.VerifiedPass;
+    },
+};

package/dist/commands/self-config.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-config.command.d.ts","sourceRoot":"","sources":["../../src/commands/self-config.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,uBAAuB,EAAE,eAwCrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA6BpC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAsB1C,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuCrC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAc/B,CAAC"}
+{"version":3,"file":"self-config.command.d.ts","sourceRoot":"","sources":["../../src/commands/self-config.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA+KhC,eAAO,MAAM,uBAAuB,EAAE,eA0CrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA6BpC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eA2C1C,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAwDrC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAyC/B,CAAC"}

package/dist/commands/self-config.command.js

@@ -4,50 +4,185 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { buildSelfConfigDoctorReport, buildSelfConfigDoctorReportV2, buildSelfConfigGraph, inspectSharkcraft, renderSelfConfigDoctorMarkdown, renderSelfConfigDoctorText, renderSelfConfigDoctorV2Markdown, renderSelfConfigDoctorV2Text, } from '@shrkcrft/inspector';
+import { DEAD_SELECTOR_CAUSES, UnitLivenessState } from '@shrkcrft/core';
+import { assetDoctorProposedExit, buildDeclaredXrefReport, buildSelfConfigDoctorReportV2, buildSelfConfigGraph, declaredXrefCoverage, inspectSharkcraft, isUnresolvedReferenceFinding, isWrongKindReferenceFinding, SelfConfigSeverityV2, withDeclaredXrefEdges, projectSelfConfigDoctorV2ToV1, renderSelfConfigDoctorMarkdown, renderSelfConfigDoctorText, renderSelfConfigDoctorV2Markdown, renderSelfConfigDoctorV2Text, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson } from "../output/format-output.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { assetDoctorFailingUnits } from "../gates/asset-doctor-failing-units.js";
+import { assetDoctorFailureLine } from "../gates/asset-doctor-failure-line.js";
+import { warmCliReferenceRegistries } from "../surface/cli-command-resolver.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
+import { selfConfigResolveCommand, selfConfigXrefsCommand } from "./self-config-xrefs.command.js";
+/**
+ * The self-config graph plus one edge per declared cross-reference id, from THE
+ * collector the doctor reads — so `graph`, `broken-links` and `report` show the
+ * same dangling ids as `doctor` (the v1 graph alone saw only file references).
+ */
+async function selfConfigGraphWithXrefs(inspection) {
+    const xrefs = await buildDeclaredXrefReport(inspection);
+    const base = await buildSelfConfigGraph(inspection);
+    return { graph: withDeclaredXrefEdges(base, xrefs), base, xrefs };
+}
+/**
+ * THE coverage `self-config broken-links` settles on (round 11 review
+ * R11-GAP-4): the references it examined of the references declared — every
+ * file reference of the graph (each checked on disk) plus every declared
+ * cross-reference id (`declaredXrefCoverage`: one that could not be looked up
+ * is unexamined). Nothing declared is `expected: 0` — NOT VERIFIED (2) unless
+ * `--allow-empty` accepts it, as every sibling doctor settles "nothing to
+ * examine". It used to settle against NO record over an empty config and print
+ * "No broken references. ✓" at 0.
+ */
+function brokenLinksCoverage(base, xrefs, args) {
+    const ids = declaredXrefCoverage(xrefs);
+    const fileRefs = base.edges.filter((e) => e.to.kind === 'file').length;
+    const expected = fileRefs + ids.expected;
+    return {
+        unit: 'references',
+        expected,
+        examined: fileRefs + ids.examined,
+        ...(ids.unexamined !== undefined
+            ? { unexamined: ids.unexamined, unexaminedTotal: ids.unexaminedTotal ?? ids.unexamined.length, reason: ids.reason ?? 'not examined' }
+            : {}),
+        ...(expected === 0 ? { reason: 'no file reference and no declared cross-reference id to examine' } : {}),
+        ...allowEmptyValve(args, expected),
+    };
+}
+/** The shared dead-selector valve (boundary, gate and asset planes spell it the same). */
+const FAIL_ON_DEAD_UNITS_FLAG = 'fail-on-dead-units';
+const DOCTOR_FLAGS = new Set(['json', 'strict', FAIL_ON_DEAD_UNITS_FLAG]);
+/**
+ * THE self-config verdict — one settle for `--schema v1` and v2 alike (v1 is a
+ * projection of the same report), for `self-config doctor` and `self-config
+ * report`, through THE asset-doctor proposal MCP `get_self_config_doctor`
+ * reads too (round 13): 1 on errors, on warnings under `--strict`, or on a
+ * settled selector unit THE `--fail-on-dead-units` predicate fails (a dead
+ * unit, or a stale LOCAL expectEmpty marker); else 0. The engine's coverage
+ * (command strings, tuning keys + triggers, routing hints + their ids,
+ * registration discovery, scaffold globs) settles it: a dead or unverifiable
+ * unit turns 0 into 2, never a pass; an intended-empty unit is a printed
+ * acceptance.
+ */
+function settleSelfConfig(report, args) {
+    const proposed = assetDoctorProposedExit({ errors: report.totals.error, warnings: report.totals.warning, units: report.selectorUnits }, { strict: flagBool(args, 'strict'), failOnDeadUnits: flagBool(args, FAIL_ON_DEAD_UNITS_FLAG) });
+    return settleVerdict(proposed, report.coverage);
+}
+/**
+ * THE units that fail the self-config verdict (round 13 review) — the
+ * predicate `settleSelfConfig` proposes from — so the verbs can say why a
+ * `--fail-on-dead-units` run exited 1 (its header read `verdict OK` and no line
+ * named the failure).
+ */
+function selfConfigFailing(report, args) {
+    return assetDoctorFailingUnits(report.selectorUnits, {
+        failOnDeadUnits: flagBool(args, FAIL_ON_DEAD_UNITS_FLAG),
+        strict: flagBool(args, 'strict'),
+    });
+}
+/** The settled verdict's fields on `--json` — the vocabulary the sibling doctors use (`verdict` stays the report's own). */
+function settledJson(settled, failing = []) {
+    return {
+        exitCode: settled.exit,
+        settledVerdict: settled.verdict,
+        shortfalls: settled.shortfalls,
+        accepted: settled.accepted,
+        failingUnits: failing.map((u) => ({ list: u.list, unit: u.unit, state: u.state, message: u.message })),
+    };
+}
+/**
+ * What the command probes did NOT prove, said out loud in the clean line: a
+ * `prefix-only` tail (verb proven, internally-dispatched tail not) and a
+ * `not-shrk` string (never checked — narrowed out of the coverage) are not
+ * "resolved".
+ */
+function commandProbeCaveats(report) {
+    const c = report.probes.command;
+    const parts = [];
+    if (c.prefixOnly > 0)
+        parts.push(`${c.prefixOnly} prefix-only tail(s) unproven`);
+    if (c.notShrk > 0)
+        parts.push(`${c.notShrk} non-shrk command string(s) not checked`);
+    return parts.length > 0 ? ` (${parts.join('; ')})` : '';
+}
+/**
+ * The exit-0 sentence. "every checked probe resolved ✓" is printed only when
+ * it is true: an INFO-severity unresolved reference (a routing / registration
+ * hint's related id, a convention's applicability profile id, a pipeline step
+ * reference — THE doctor's `isUnresolvedReferenceFinding`) never fails the
+ * run, but it is not "resolved", so it is counted instead of certified. So is
+ * an info-severity WRONG-KIND reference (`isWrongKindReferenceFinding`: a
+ * pipeline step naming a construct) — it resolves, but not as its field
+ * accepts (round 12, 12.4 split it out of `pipeline-reference-missing`).
+ */
+function cleanSentence(report) {
+    const caveats = commandProbeCaveats(report);
+    const info = report.findings.filter((f) => f.severity === SelfConfigSeverityV2.Info);
+    const unresolvedInfo = info.filter(isUnresolvedReferenceFinding).length;
+    const wrongKindInfo = info.filter(isWrongKindReferenceFinding).length;
+    // A stale LOCAL expectEmpty marker is not "resolved" either (round 13): it is
+    // counted, never certified (a pack's is INFO — the consumer cannot edit it).
+    const staleMarkers = report.selectorUnits.filter((u) => u.state === UnitLivenessState.WentLive && u.mark?.packageName === undefined).length;
+    const reported = [
+        ...(report.totals.warning > 0 ? [`${report.totals.warning} warning(s)`] : []),
+        ...(unresolvedInfo > 0 ? [`${unresolvedInfo} unresolved reference(s)`] : []),
+        ...(wrongKindInfo > 0 ? [`${wrongKindInfo} wrong-kind reference(s)`] : []),
+        ...(staleMarkers > 0 ? [`${staleMarkers} stale expectEmpty marker(s)`] : []),
+    ];
+    if (reported.length === 0)
+        return `No cross-reference issues — every checked probe resolved${caveats}. ✓`;
+    const where = report.totals.warning > 0 ? 'reported above' : 'reported as info above';
+    const listed = reported.length > 1 ? `${reported.slice(0, -1).join(', ')} and ${reported[reported.length - 1]}` : reported[0];
+    return `No blocking cross-reference issues${caveats} — ${listed} ${where}.`;
+}
+async function buildDoctorReport(args) {
+    const cwd = resolveCwd(args);
+    const inspection = await inspectSharkcraft({ cwd });
+    // Warm WITH the command resolver so every prescribed command string resolves
+    // against the live command index — for both schemas.
+    await warmCliReferenceRegistries(inspection);
+    return { cwd, inspection, report: await buildSelfConfigDoctorReportV2(inspection) };
+}
 export const selfConfigDoctorCommand = {
     name: 'doctor',
-    description: 'Self-config cross-reference doctor — validates the graph of refs. Defaults to v2 schema; pass --schema v1 for the legacy shape.',
-    usage: 'shrk self-config doctor [--schema v1|v2] [--format text|markdown|json] [--strict]',
+    description: 'Self-config cross-reference doctor — validates the graph of refs, with per-unit coverage (exit 0 pass · 1 errors · 2 a dead or unverified unit). Defaults to v2 schema; pass --schema v1 for the legacy shape (same checks).',
+    usage: 'shrk self-config doctor [--schema v1|v2] [--format text|markdown|json] [--strict] [--fail-on-dead-units]',
+    booleanFlags: DOCTOR_FLAGS,
     async run(args) {
-        const cwd = resolveCwd(args);
-        const inspection = await inspectSharkcraft({ cwd });
-        const strict = flagBool(args, 'strict');
         const format = flagString(args, 'format') ?? 'text';
         const wantJson = flagBool(args, 'json') || format === 'json';
-        const schemaArg = flagString(args, 'schema');
-        const useV1 = schemaArg === 'v1';
-        if (useV1) {
-            const report = await buildSelfConfigDoctorReport(inspection);
-            if (wantJson) {
-                process.stdout.write(asJson(report) + '\n');
-            }
-            else if (format === 'markdown') {
-                process.stdout.write(renderSelfConfigDoctorMarkdown(report));
-            }
-            else {
-                process.stdout.write(renderSelfConfigDoctorText(report));
-            }
-            if (strict && (report.verdict === 'warnings' || report.verdict === 'errors'))
-                return 1;
-            return report.verdict === 'errors' ? 1 : 0;
-        }
-        // Default: v2 graph validation.
-        const report = await buildSelfConfigDoctorReportV2(inspection);
+        const useV1 = flagString(args, 'schema') === 'v1';
+        const { report } = await buildDoctorReport(args);
+        const settled = settleSelfConfig(report, args);
+        const failing = selfConfigFailing(report, args);
         if (wantJson) {
-            process.stdout.write(asJson(report) + '\n');
+            const payload = useV1 ? projectSelfConfigDoctorV2ToV1(report) : report;
+            process.stdout.write(asJson({ ...payload, ...settledJson(settled, failing) }) + '\n');
+            return settled.exit;
         }
-        else if (format === 'markdown') {
-            process.stdout.write(renderSelfConfigDoctorV2Markdown(report));
+        if (useV1) {
+            const v1 = projectSelfConfigDoctorV2ToV1(report);
+            process.stdout.write(format === 'markdown' ? renderSelfConfigDoctorMarkdown(v1) : renderSelfConfigDoctorText(v1));
         }
         else {
-            process.stdout.write(renderSelfConfigDoctorV2Text(report));
+            process.stdout.write(format === 'markdown' ? renderSelfConfigDoctorV2Markdown(report) : renderSelfConfigDoctorV2Text(report));
         }
-        if (strict && (report.verdict === 'warnings' || report.verdict === 'errors'))
-            return 1;
-        return report.verdict === 'errors' ? 1 : 0;
+        const line = verdictLine(settled, cleanSentence(report));
+        if (line)
+            process.stdout.write(line + '\n');
+        // Round 13 review: a 1 from --fail-on-dead-units names its units — the
+        // header above reads the REPORT's own verdict (`verdict OK`).
+        if (settled.exit === 1) {
+            const failure = assetDoctorFailureLine('self-config doctor', failing);
+            if (failure)
+                process.stdout.write(failure + '\n');
+        }
+        if (settled.exit !== 0 && report.deadUnits.length > 0 && !flagBool(args, FAIL_ON_DEAD_UNITS_FLAG)) {
+            process.stdout.write(`Fix each dead unit (${report.deadUnits.length}) — ${DEAD_SELECTOR_CAUSES}; pass --${FAIL_ON_DEAD_UNITS_FLAG} to fail on them.\n`);
+        }
+        return settled.exit;
     },
 };
 export const selfConfigGraphCommand = {
@@ -57,7 +192,7 @@ export const selfConfigGraphCommand = {
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const graph = await buildSelfConfigGraph(inspection);
+        const { graph } = await selfConfigGraphWithXrefs(inspection);
         const format = flagString(args, 'format') ?? 'json';
         if (format === 'mermaid') {
             const lines = ['graph TD'];
@@ -82,63 +217,120 @@ export const selfConfigGraphCommand = {
 };
 export const selfConfigBrokenLinksCommand = {
     name: 'broken-links',
-    description: 'List only the broken (unresolved) references.',
-    usage: 'shrk self-config broken-links [--json]',
+    description: 'List only the broken references — missing referenced files AND every dangling / wrong-kind declared cross-reference id (the rows `self-config doctor` reports). Exit 0 none · 1 broken · 2 an id could not be looked up, or nothing to examine (--allow-empty accepts that).',
+    usage: 'shrk self-config broken-links [--allow-empty] [--json]',
+    booleanFlags: new Set(['json', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const graph = await buildSelfConfigGraph(inspection);
+        const { graph, base, xrefs } = await selfConfigGraphWithXrefs(inspection);
+        // Always settled against what was examined: an id that could not be looked
+        // up, or nothing to examine at all, is never "no broken references".
+        const coverage = brokenLinksCoverage(base, xrefs, args);
+        const settled = settleVerdict(graph.brokenEdges.length === 0 ? 0 : 1, [coverage]);
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ brokenEdges: graph.brokenEdges }) + '\n');
-            return graph.brokenEdges.length === 0 ? 0 : 1;
-        }
-        if (graph.brokenEdges.length === 0) {
-            process.stdout.write('No broken references. ✓\n');
-            return 0;
+            process.stdout.write(asJson({
+                brokenEdges: graph.brokenEdges,
+                coverage,
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
+            }) + '\n');
+            return settled.exit;
         }
-        process.stdout.write(`=== Broken self-config references (${graph.brokenEdges.length}) ===\n`);
-        for (const e of graph.brokenEdges.slice(0, 100)) {
-            process.stdout.write(`  • ${e.from.kind}:${e.from.id} -> ${e.to.kind}:${e.to.id}\n`);
+        if (graph.brokenEdges.length > 0) {
+            process.stdout.write(`=== Broken self-config references (${graph.brokenEdges.length}) ===\n`);
+            for (const e of graph.brokenEdges.slice(0, 100)) {
+                process.stdout.write(`  • ${e.from.kind}:${e.from.id} -> ${e.to.kind}:${e.to.id}  (${e.relation})\n`);
+            }
         }
-        return 1;
+        const line = verdictLine(settled, 'No broken references. ✓', coverage.expected === 0
+            ? `NOT VERIFIED — nothing to examine: no file reference and no declared cross-reference id. Pass --${ALLOW_EMPTY_FLAG} to accept that.`
+            : undefined);
+        if (line)
+            process.stdout.write(line + '\n');
+        return settled.exit;
     },
 };
 export const selfConfigReportCommand = {
     name: 'report',
-    description: 'Write the self-config doctor + graph reports under .sharkcraft/reports/.',
-    usage: 'shrk self-config report [--output <dir>]',
+    description: 'Write the self-config doctor + graph reports under .sharkcraft/reports/, and settle the doctor verdict (exit 0 pass · 1 errors · 2 a dead or unverified unit), the same as `self-config doctor`.',
+    usage: 'shrk self-config report [--schema v1|v2] [--output <dir>] [--strict] [--fail-on-dead-units] [--json]',
+    booleanFlags: DOCTOR_FLAGS,
     async run(args) {
-        const cwd = resolveCwd(args);
-        const inspection = await inspectSharkcraft({ cwd });
-        const schemaArg = flagString(args, 'schema');
-        const useV1 = schemaArg === 'v1';
-        const graph = await buildSelfConfigGraph(inspection);
+        const useV1 = flagString(args, 'schema') === 'v1';
+        const { cwd, inspection, report } = await buildDoctorReport(args);
+        const { graph } = await selfConfigGraphWithXrefs(inspection);
         const outArg = flagString(args, 'output');
         const outDir = outArg
             ? (nodePath.isAbsolute(outArg) ? outArg : nodePath.resolve(cwd, outArg))
             : nodePath.join(cwd, '.sharkcraft', 'reports');
         mkdirSync(outDir, { recursive: true });
         const base = 'self-config-doctor';
+        const settled = settleSelfConfig(report, args);
         if (useV1) {
-            const report = await buildSelfConfigDoctorReport(inspection);
+            const v1 = projectSelfConfigDoctorV2ToV1(report);
+            writeFileSync(nodePath.join(outDir, `${base}.json`), JSON.stringify(v1, null, 2) + '\n', 'utf8');
+            writeFileSync(nodePath.join(outDir, `${base}.md`), renderSelfConfigDoctorMarkdown(v1), 'utf8');
+        }
+        else {
             writeFileSync(nodePath.join(outDir, `${base}.json`), JSON.stringify(report, null, 2) + '\n', 'utf8');
-            writeFileSync(nodePath.join(outDir, `${base}.md`), renderSelfConfigDoctorMarkdown(report), 'utf8');
-            writeFileSync(nodePath.join(outDir, `${base}-graph.json`), JSON.stringify(graph, null, 2) + '\n', 'utf8');
-            process.stdout.write(`Wrote ${nodePath.relative(cwd, outDir)}/${base}.{json,md} (v1) and ${base}-graph.json\n`);
-            return report.verdict === 'errors' ? 1 : 0;
+            writeFileSync(nodePath.join(outDir, `${base}.md`), renderSelfConfigDoctorV2Markdown(report), 'utf8');
         }
-        const report = await buildSelfConfigDoctorReportV2(inspection);
-        writeFileSync(nodePath.join(outDir, `${base}.json`), JSON.stringify(report, null, 2) + '\n', 'utf8');
-        writeFileSync(nodePath.join(outDir, `${base}.md`), renderSelfConfigDoctorV2Markdown(report), 'utf8');
         writeFileSync(nodePath.join(outDir, `${base}-graph.json`), JSON.stringify(graph, null, 2) + '\n', 'utf8');
-        process.stdout.write(`Wrote ${nodePath.relative(cwd, outDir)}/${base}.{json,md} (v2) and ${base}-graph.json\n`);
-        return report.verdict === 'errors' ? 1 : 0;
+        if (flagBool(args, 'json')) {
+            // The same settled fields as `self-config doctor --json` (round 13): a
+            // registered verdict verb, so its 2 survives a pipe and a bad flag is 3.
+            const rel = (name) => nodePath.relative(cwd, nodePath.join(outDir, name)) || name;
+            process.stdout.write(asJson({
+                written: [rel(`${base}.json`), rel(`${base}.md`), rel(`${base}-graph.json`)],
+                schema: useV1 ? 'v1' : 'v2',
+                verdict: report.verdict,
+                ...settledJson(settled, selfConfigFailing(report, args)),
+            }) + '\n');
+            return settled.exit;
+        }
+        process.stdout.write(`Wrote ${nodePath.relative(cwd, outDir)}/${base}.{json,md} (${useV1 ? 'v1' : 'v2'}) and ${base}-graph.json\n`);
+        const line = verdictLine(settled, cleanSentence(report));
+        if (line)
+            process.stdout.write(line + '\n');
+        // Round 13 review: a 1 from --fail-on-dead-units names its units.
+        if (settled.exit === 1) {
+            const failure = assetDoctorFailureLine('self-config report', selfConfigFailing(report, args));
+            if (failure)
+                process.stdout.write(failure + '\n');
+        }
+        return settled.exit;
     },
 };
 export const selfConfigCommand = {
     name: 'self-config',
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'doctor',
+            description: 'Cross-reference doctor over the self-config + pack contributions.',
+            usage: 'shrk self-config doctor [--schema v1|v2] [--format text|markdown|json] [--strict] [--fail-on-dead-units] [--json]',
+        },
+        { name: 'graph', description: 'The self-config reference graph.', usage: 'shrk self-config graph [--dangling-only] [--json]' },
+        {
+            name: 'broken-links',
+            description: 'References that resolve to nothing (exit 2 when nothing could be examined; --allow-empty accepts that).',
+            usage: 'shrk self-config broken-links [--allow-empty] [--json]',
+        },
+        {
+            name: 'report',
+            description: 'Write the self-config report, settling the doctor verdict (exit 0 pass · 1 errors · 2 a dead or unverified unit).',
+            usage: 'shrk self-config report [--schema v1|v2] [--output <dir>] [--strict] [--fail-on-dead-units] [--json]',
+        },
+        { name: 'resolve', description: 'Resolve one id across every kind.', usage: 'shrk self-config resolve <id> [--json]', positionals: PositionalMode.Free },
+        { name: 'xrefs', description: 'Declared cross-references between assets.', usage: 'shrk self-config xrefs [--json]' },
+    ],
     description: 'Cross-reference doctor over SharkCraft self-config + pack contributions.',
-    usage: 'shrk self-config doctor|graph|broken-links|report ...',
+    usage: 'shrk self-config doctor|graph|broken-links|report|resolve|xrefs ...',
+    // The group parses every subverb's argv, so the subverbs' boolean flags live here too.
+    booleanFlags: new Set([...DOCTOR_FLAGS, 'dangling-only', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const sub = args.positional[0];
         args.positional = args.positional.slice(1);
@@ -150,7 +342,11 @@ export const selfConfigCommand = {
             return selfConfigBrokenLinksCommand.run(args);
         if (sub === 'report')
             return selfConfigReportCommand.run(args);
-        process.stderr.write('Usage: shrk self-config doctor|graph|broken-links|report ...\n');
+        if (sub === 'resolve')
+            return selfConfigResolveCommand.run(args);
+        if (sub === 'xrefs')
+            return selfConfigXrefsCommand.run(args);
+        process.stderr.write('Usage: shrk self-config doctor|graph|broken-links|report|resolve|xrefs ...\n');
         return 2;
     },
 };

package/dist/commands/smart-context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AA2BA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmFhC,eAAO,MAAM,mBAAmB,EAAE,eAiQjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAsF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC;AAqJF,UAAU,eAAe;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWzF"}
+{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AA2BA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqGhC,eAAO,MAAM,mBAAmB,EAAE,eAwQjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAsF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAsH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAwH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eA4HhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC;AAqJF,UAAU,eAAe;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWzF"}