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

package/dist/gates/run-gate-planes.js

@@ -0,0 +1,261 @@
+import { resolveSourceGlobs } from '@shrkcrft/core';
+import { checkDocReferences } from '@shrkcrft/inspector';
+import { buildRegistrationGraph, matchesAny, registrationOrphans, registrationUnprovided, registryDuplicates, runPolicyLint, runWiring, scanRegistry, } from '@shrkcrft/boundaries';
+import { evaluateBaselineRule } from "../commands/baseline.command.js";
+import { evaluateGeneratedRule, generatedHintFor } from "../commands/generated.command.js";
+/** Evaluate the given rules, dispatching each to its plane's real engine. */
+export function runGatePlanes(rules, options) {
+    const results = [];
+    const diagnostics = [];
+    const byPlane = (plane) => rules.filter((r) => r.plane === plane).map((r) => r.raw);
+    results.push(...runWiringPlane(byPlane('wiring'), options, diagnostics));
+    results.push(...runPolicyPlane(byPlane('policy'), options));
+    results.push(...runRegistryPlane(byPlane('registry'), options));
+    results.push(...runRegistrationPlane(byPlane('registration'), options));
+    results.push(...runBaselinePlane(byPlane('baseline'), options));
+    results.push(...runGeneratedPlane(byPlane('generated'), options));
+    results.push(...runDocReferencePlane(byPlane('doc-reference'), options));
+    return { results, diagnostics };
+}
+function runWiringPlane(rules, options, diagnostics) {
+    if (rules.length === 0)
+        return [];
+    const report = runWiring(options.cwd, rules, { excludeDirs: options.excludeDirs });
+    diagnostics.push(...report.diagnostics);
+    return report.rules.map((r) => {
+        const skip = report.skipped.find((s) => s.ruleId === r.ruleId);
+        return {
+            id: r.ruleId,
+            type: 'wiring',
+            status: r.status,
+            severity: r.severity,
+            counts: { declared: r.declaredCount, registered: r.registeredCount },
+            violations: r.violations.map((v) => ({
+                id: v.token,
+                ...(v.file ? { file: v.file } : {}),
+                ...(v.line !== undefined ? { line: v.line } : {}),
+                ...(v.message ? { message: v.message } : {}),
+                ...(v.hint ? { hint: v.hint } : {}),
+            })),
+            ...(skip ? { skipReason: skip.reason } : {}),
+            ...(r.error ? { error: r.error } : {}),
+        };
+    });
+}
+function runPolicyPlane(rules, options) {
+    if (rules.length === 0)
+        return [];
+    const report = runPolicyLint(options.cwd, rules, { excludeDirs: options.excludeDirs });
+    return report.rules.map((r) => {
+        const rule = rules.find((x) => x.id === r.ruleId);
+        const findings = report.findings.filter((f) => f.ruleId === r.ruleId);
+        const skip = report.skipped.find((s) => s.ruleId === r.ruleId);
+        return {
+            id: r.ruleId,
+            type: 'policy',
+            status: r.status,
+            severity: r.severity,
+            counts: { units: r.unitsScanned, findings: r.findingCount, suppressed: r.suppressedCount },
+            violations: findings.map((f) => ({
+                id: f.file,
+                file: f.file,
+                line: f.line,
+                message: f.message,
+                ...(f.suggest ?? rule?.suggest ? { hint: f.suggest ?? rule.suggest } : {}),
+            })),
+            ...(skip ? { skipReason: skip.reason } : {}),
+            ...(r.error ? { error: r.error } : {}),
+        };
+    });
+}
+/**
+ * The registry plane's violation check is DUPLICATES: two roots claiming one id
+ * compile fine, and whichever registration wins at runtime is an accident of
+ * load order. (Presence queries are lookups, not gates, so they are not run.)
+ */
+function runRegistryPlane(decls, options) {
+    return decls.map((decl) => {
+        const inventory = scanRegistry(options.cwd, decl, { excludeDirs: options.excludeDirs });
+        const dupes = registryDuplicates(inventory);
+        const empty = inventory.entries.length === 0;
+        return {
+            id: decl.name,
+            type: 'registry',
+            status: empty ? 'skipped' : dupes.length > 0 ? 'failed' : 'passed',
+            severity: 'warning',
+            counts: { ids: inventory.entries.length, duplicates: dupes.length },
+            violations: dupes.map((d) => ({
+                id: d.id,
+                ...(d.sites[0] ? { file: d.sites[0].file, line: d.sites[0].line } : {}),
+                message: `declared in ${d.sites.length} places: ${d.sites.map((s) => `${s.file}:${s.line}`).join(', ')}`,
+                hint: 'remove the duplicate declaration — which one wins is load-order roulette',
+            })),
+            ...(empty ? { skipReason: 'matched 0 ids — the source selector is probably stale' } : {}),
+        };
+    });
+}
+/**
+ * The registration plane's violation check is UNPROVIDED: a token declared or
+ * consumed but provided by nothing resolves to nothing at runtime — invisible
+ * to the compiler, which is the entire reason this plane exists. Orphans (a
+ * provider nothing consumes) are COUNTED but do not fail: a registration ahead
+ * of its consumer is a normal intermediate state, not a defect.
+ */
+function runRegistrationPlane(idioms, options) {
+    if (idioms.length === 0)
+        return [];
+    // The graph is built from EVERY idiom at once (that is what makes a
+    // declared→provided→consumed chain traceable across them), so a finding has
+    // to be attributed back by matching its sites against each idiom's own globs.
+    // Dumping every finding on the first idiom would leave the others reading
+    // `passed` while their tokens resolve to nothing — a green that means nothing.
+    const graph = buildRegistrationGraph(options.cwd, idioms, { excludeDirs: options.excludeDirs });
+    const unprovided = registrationUnprovided(graph, options.changedFiles);
+    const orphans = registrationOrphans(graph, options.changedFiles);
+    const ownsFile = (idiom, file) => matchesAny(file, [
+        ...resolveSourceGlobs(idiom.declared),
+        ...resolveSourceGlobs(idiom.consumed),
+        ...resolveSourceGlobs(idiom.provided),
+    ]);
+    return idioms.map((idiom) => {
+        const mine = unprovided.filter((t) => [...t.declared, ...t.consumed].some((site) => ownsFile(idiom, site.file)));
+        const myOrphans = orphans.filter((t) => t.provided.some((site) => ownsFile(idiom, site.file)));
+        const empty = graph.tokens.length === 0;
+        return {
+            id: idiom.name,
+            type: 'registration',
+            status: empty
+                ? 'skipped'
+                : mine.length > 0
+                    ? 'failed'
+                    : 'passed',
+            severity: 'warning',
+            counts: { tokens: graph.tokens.length, unprovided: mine.length, orphans: myOrphans.length },
+            violations: mine.map((t) => ({
+                id: t.token,
+                ...(t.declared[0] ? { file: t.declared[0].file, line: t.declared[0].line } : {}),
+                message: 'declared/consumed but provided by nothing — resolves to nothing at runtime',
+                hint: `trace it with \`shrk wiring chain ${t.token}\``,
+            })),
+            ...(empty ? { skipReason: 'registration graph matched 0 tokens' } : {}),
+        };
+    });
+}
+function runBaselinePlane(rules, options) {
+    return rules.map((rule) => {
+        // A `command` compute spawns a shell. Under --no-spawn it is reported as
+        // skipped WITH the reason, never silently treated as clean.
+        if (options.noSpawn && rule.compute.kind === 'command') {
+            return {
+                id: rule.id,
+                type: 'baseline',
+                status: 'skipped',
+                severity: rule.severity ?? 'error',
+                counts: { committed: 0, current: 0 },
+                violations: [],
+                skipReason: '`command` compute skipped by --no-spawn',
+            };
+        }
+        const o = evaluateBaselineRule(options.cwd, rule, options.excludeDirs, options.changedFiles);
+        return {
+            id: o.rule.id,
+            type: 'baseline',
+            status: o.status,
+            severity: o.rule.severity ?? 'error',
+            counts: { committed: o.committedCount, current: o.currentCount },
+            violations: [
+                ...(o.diff?.added ?? []).map((e) => ({ id: e, message: 'gained since the baseline was blessed' })),
+                ...(o.diff?.removed ?? []).map((e) => ({ id: e, message: 'LOST since the baseline was blessed' })),
+            ].map((v) => ({ ...v, hint: rule.hint ?? `bless with \`shrk baseline update --id ${rule.id}\`` })),
+            ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+            ...(o.error ? { error: o.error } : {}),
+        };
+    });
+}
+/**
+ * The doc-reference plane's violation check: an id cited in prose that resolves
+ * to nothing. Skipped honestly when the registries were not loaded — claiming a
+ * pass without having checked is the failure mode this whole surface exists to
+ * prevent.
+ */
+function runDocReferencePlane(rules, options) {
+    if (rules.length === 0)
+        return [];
+    const inspection = options.inspection;
+    if (!inspection) {
+        return rules.map((rule) => ({
+            id: rule.id,
+            type: 'doc-reference',
+            status: 'skipped',
+            severity: rule.severity ?? 'error',
+            counts: { files: 0, tokens: 0 },
+            violations: [],
+            skipReason: 'registries not loaded — doc references were not resolved',
+        }));
+    }
+    return rules.map((rule) => {
+        const res = checkDocReferences(options.cwd, rule, inspection, options.excludeDirs);
+        return {
+            id: res.ruleId,
+            type: 'doc-reference',
+            status: res.status,
+            severity: res.severity,
+            counts: { files: res.filesScanned, tokens: res.tokensChecked, skipped: res.tokensSkipped },
+            violations: res.findings.map((f) => ({
+                id: f.token,
+                file: f.file,
+                line: f.line,
+                message: f.message,
+                ...(f.didYouMean.length > 0 ? { hint: `did you mean: ${f.didYouMean.join(', ')}` } : {}),
+            })),
+            ...(res.skipReason ? { skipReason: res.skipReason } : {}),
+            ...(res.error ? { error: res.error } : {}),
+        };
+    });
+}
+function runGeneratedPlane(rules, options) {
+    return rules.map((rule) => {
+        // --no-spawn keeps the header + classification halves (pure reads) and
+        // drops only the regen diff, which is reported as a partial run.
+        const headersOnly = options.noSpawn === true;
+        const o = evaluateGeneratedRule(options.cwd, rule, options.excludeDirs, headersOnly);
+        const spawnSkipped = headersOnly && (rule.regen !== undefined || (rule.sources?.length ?? 0) > 0);
+        // A rule whose DRIFT half was skipped has not passed — it partially ran. A
+        // header contract holding proves nothing about whether the file was
+        // hand-edited, so reporting `passed` here would be the exact false green
+        // this plane exists to prevent. Findings still fail; the clean case
+        // downgrades to `skipped` so the aggregate exit is 2, not 0.
+        const status = spawnSkipped && o.status === 'passed' ? 'skipped' : o.status;
+        return {
+            id: o.rule.id,
+            type: 'generated',
+            status,
+            severity: o.rule.severity ?? 'error',
+            counts: {
+                files: o.committedCount,
+                differences: o.treeDiff?.differences.length ?? 0,
+                provenance: o.provenance.length,
+            },
+            violations: [
+                ...(o.treeDiff?.differences ?? []).map((d) => ({
+                    id: d.file,
+                    file: d.file,
+                    message: d.kind,
+                    hint: generatedHintFor(o.rule),
+                })),
+                ...o.provenance.map((f) => ({
+                    id: f.file,
+                    file: f.file,
+                    message: f.message,
+                    hint: generatedHintFor(o.rule),
+                })),
+            ],
+            ...(o.skipReason
+                ? { skipReason: o.skipReason }
+                : spawnSkipped
+                    ? { skipReason: 'regen drift check skipped by --no-spawn (headers + classification still ran)' }
+                    : {}),
+            ...(o.error ? { error: o.error } : {}),
+        };
+    });
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AAoZ/B,wBAAgB,aAAa,IAAI,eAAe,CAqZ/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CrE;AAwID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AA6Z/B,wBAAgB,aAAa,IAAI,eAAe,CAwZ/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgDrE;AAwID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { loadDotenv } from "./env/load-dotenv.js";
 import { CommandRegistry, extractGlobalCompress, extractGlobalCwd, extractGlobalExitTrailer, parseArgs, } from "./command-registry.js";
-import { argvHasExitTrailer, argvHasStrict, emitPipeExitSignal, promoteForStrict } from "./exit-codes.js";
+import { argvHasExitTrailer, argvHasNoHints, argvHasStrict, emitPipeExitSignal, promoteForStrict, } from "./exit-codes.js";
 import { runCommandWithCompression } from "./output/output-compression.js";
 import { initCommand } from "./commands/init.command.js";
 import { inspectCommand } from "./commands/inspect.command.js";
@@ -37,7 +37,7 @@ import { gateCommand } from "./commands/gate.command.js";
 import { policyLintCommand, policyLintExplainCommand } from "./commands/policy-lint.command.js";
 import { baselineCheckCommand, baselineCommand, baselineDiffCommand, baselineExplainCommand, baselineListCommand, baselineUpdateCommand, } from "./commands/baseline.command.js";
 import { generatedCheckCommand, generatedExplainCommand, generatedListCommand, generatedUpdateCommand, } from "./commands/generated.command.js";
-import { gatesCommand, gatesCoverageCommand, gatesExplainCommand, gatesListCommand, } from "./commands/gates.command.js";
+import { gatesCheckCommand, gatesCommand, gatesCoverageCommand, gatesExplainCommand, gatesListCommand, gatesTryCommand, } from "./commands/gates.command.js";
 import { wiringCommand } from "./commands/wiring.command.js";
 import { reuseCommand } from "./commands/reuse.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
@@ -106,6 +106,7 @@ import { briefCommand } from "./commands/brief.command.js";
 import { releaseCommand, installSmokeCommand } from "./commands/release.command.js";
 import { startHereCommand } from "./commands/start-here.command.js";
 import { docsCheckCommand, examplesCheckCommand } from "./commands/docs.command.js";
+import { docsReferencesCommand } from "./commands/docs-references.command.js";
 import { selfAuditCommand } from "./commands/self.command.js";
 import { diagnosticsListCommand } from "./commands/diagnostics.command.js";
 import { architectureMapCommand } from "./commands/architecture.command.js";
@@ -227,8 +228,10 @@ export function buildRegistry() {
     registry.registerSubcommand('generated', generatedExplainCommand);
     registry.register(gatesCommand);
     registry.registerSubcommand('gates', gatesListCommand);
+    registry.registerSubcommand('gates', gatesCheckCommand);
     registry.registerSubcommand('gates', gatesCoverageCommand);
     registry.registerSubcommand('gates', gatesExplainCommand);
+    registry.registerSubcommand('gates', gatesTryCommand);
     registry.register(wiringCommand);
     registry.register(reuseCommand);
     registry.register(migrateCommand);
@@ -339,6 +342,7 @@ export function buildRegistry() {
     registry.registerSubcommand('memory', memorySnapshotsCommand);
     registry.register(languagesCommand);
     registry.registerSubcommand('docs', docsCheckCommand);
+    registry.registerSubcommand('docs', docsReferencesCommand);
     registry.registerSubcommand('examples', examplesCheckCommand);
     registry.registerSubcommand('self', selfAuditCommand);
     registry.registerSubcommand('install', installSmokeCommand);
@@ -555,6 +559,7 @@ export async function runCli(argv) {
             emitPipeExitSignal(command, exitCode, {
                 piped: !process.stdout.isTTY,
                 trailer: argvHasExitTrailer(argv),
+                noHints: argvHasNoHints(argv),
             });
         }
         return exitCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.28",
+  "version": "0.1.0-alpha.30",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -47,38 +47,38 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.28",
-    "@shrkcrft/compress": "^0.1.0-alpha.28",
-    "@shrkcrft/config": "^0.1.0-alpha.28",
-    "@shrkcrft/workspace": "^0.1.0-alpha.28",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.28",
-    "@shrkcrft/context": "^0.1.0-alpha.28",
-    "@shrkcrft/rules": "^0.1.0-alpha.28",
-    "@shrkcrft/paths": "^0.1.0-alpha.28",
-    "@shrkcrft/templates": "^0.1.0-alpha.28",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.28",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.28",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.28",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.28",
-    "@shrkcrft/presets": "^0.1.0-alpha.28",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.28",
-    "@shrkcrft/graph": "^0.1.0-alpha.28",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.28",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.28",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.28",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.28",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.28",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.28",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.28",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.28",
-    "@shrkcrft/migrate": "^0.1.0-alpha.28",
-    "@shrkcrft/generator": "^0.1.0-alpha.28",
-    "@shrkcrft/importer": "^0.1.0-alpha.28",
-    "@shrkcrft/inspector": "^0.1.0-alpha.28",
-    "@shrkcrft/ai": "^0.1.0-alpha.28",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.28",
-    "@shrkcrft/shared": "^0.1.0-alpha.28",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.28",
+    "@shrkcrft/core": "^0.1.0-alpha.30",
+    "@shrkcrft/compress": "^0.1.0-alpha.30",
+    "@shrkcrft/config": "^0.1.0-alpha.30",
+    "@shrkcrft/workspace": "^0.1.0-alpha.30",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.30",
+    "@shrkcrft/context": "^0.1.0-alpha.30",
+    "@shrkcrft/rules": "^0.1.0-alpha.30",
+    "@shrkcrft/paths": "^0.1.0-alpha.30",
+    "@shrkcrft/templates": "^0.1.0-alpha.30",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.30",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.30",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.30",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.30",
+    "@shrkcrft/presets": "^0.1.0-alpha.30",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.30",
+    "@shrkcrft/graph": "^0.1.0-alpha.30",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.30",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.30",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.30",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.30",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.30",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.30",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.30",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.30",
+    "@shrkcrft/migrate": "^0.1.0-alpha.30",
+    "@shrkcrft/generator": "^0.1.0-alpha.30",
+    "@shrkcrft/importer": "^0.1.0-alpha.30",
+    "@shrkcrft/inspector": "^0.1.0-alpha.30",
+    "@shrkcrft/ai": "^0.1.0-alpha.30",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.30",
+    "@shrkcrft/shared": "^0.1.0-alpha.30",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.30",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {