@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/commands/gate.command.js

@@ -0,0 +1,300 @@
+import { QualityGateReportStore, renderGateReportMarkdown, runQualityGates, } from '@shrkcrft/quality-gates';
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk gate` — run all code-intelligence quality gates and emit one
+ * pass/fail report. Designed as the single command CI should call
+ * before merge.
+ *
+ * Exit codes:
+ *   - 0 if overall status is `pass` (no failures, no warnings)
+ *   - 0 if overall is `warn` (default — opt-in to fail via --strict)
+ *   - 1 if overall is `fail`
+ *
+ * Pass `--strict` to treat `warn` as failure.
+ */
+export const gateCommand = {
+    name: 'gate',
+    description: 'Aggregator: runs the code-intelligence quality gates (graph freshness, architecture, impact-since-ref) and reports a single pass/fail.',
+    usage: 'shrk gate [--since <gitref>] [--fail-on critical,high] [--arch-all] [--disable arch,impact,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative by default once a baseline is frozen — fails only on NEW errors; --arch-all fails on total)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
+    async run(args) {
+        if (args.positional[0] === 'scaffold-ci') {
+            const sliced = { ...args, positional: args.positional.slice(1) };
+            return runGateScaffoldCi(sliced);
+        }
+        if (args.positional[0] === 'scaffold-hook') {
+            const sliced = { ...args, positional: args.positional.slice(1) };
+            return runGateScaffoldHook(sliced);
+        }
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const wantMarkdown = flagBool(args, 'markdown');
+        const outputPath = flagString(args, 'output');
+        const strict = flagBool(args, 'strict');
+        const sinceRef = flagString(args, 'since');
+        const failOnRaw = flagString(args, 'fail-on');
+        const disableRaw = flagString(args, 'disable');
+        const apiBaseline = flagString(args, 'api-baseline');
+        const noFailOnBreaking = flagBool(args, 'no-fail-on-breaking');
+        const failOn = failOnRaw
+            ? failOnRaw.split(',').map((s) => s.trim()).filter(Boolean)
+            : undefined;
+        const disable = disableRaw ? disableRaw.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+        // --arch-all: fail on TOTAL architecture errors (ignore the frozen baseline).
+        // By default the arch gate is baseline-relative — it fails only on NEW errors.
+        const archAll = flagBool(args, 'arch-all');
+        const report = runQualityGates({
+            projectRoot: cwd,
+            ...(archAll ? { arch: { baselineRelative: false } } : {}),
+            impact: {
+                ...(sinceRef ? { sinceRef } : {}),
+                ...(failOn ? { failOn } : {}),
+            },
+            ...(apiBaseline
+                ? {
+                    apiDiff: {
+                        baselinePath: apiBaseline,
+                        failOnBreaking: !noFailOnBreaking,
+                    },
+                }
+                : {}),
+            ...(disable ? { disable } : {}),
+        });
+        // Persist the report so dashboards and follow-up tooling can read
+        // it without re-running every gate. Opt out with `--no-persist`.
+        if (!flagBool(args, 'no-persist')) {
+            try {
+                new QualityGateReportStore(cwd).write(report);
+            }
+            catch {
+                // Persistence is best-effort; never fail the gate on a
+                // disk-write error.
+            }
+        }
+        if (wantMarkdown) {
+            const md = renderGateReportMarkdown(report);
+            if (outputPath) {
+                const abs = nodePath.isAbsolute(outputPath)
+                    ? outputPath
+                    : nodePath.resolve(cwd, outputPath);
+                writeFileSync(abs, md, 'utf8');
+                process.stdout.write(`Markdown report written → ${abs}\n`);
+            }
+            else {
+                process.stdout.write(md);
+            }
+            return exitCode(report.overall, strict);
+        }
+        if (wantJson) {
+            process.stdout.write(asJson(report) + '\n');
+            return exitCode(report.overall, strict);
+        }
+        process.stdout.write(header(`Quality gates: ${report.overall.toUpperCase()}`));
+        process.stdout.write(kv('total duration', `${report.totalDurationMs}ms`) + '\n');
+        process.stdout.write(kv('summary', `pass=${report.counts.pass} warn=${report.counts.warn} fail=${report.counts.fail} skipped=${report.counts.skipped}`) + '\n');
+        process.stdout.write('\nGates:\n');
+        for (const g of report.gates) {
+            const status = g.status.padEnd(8);
+            process.stdout.write(`  [${status}] ${g.label}  (${g.durationMs}ms)\n`);
+            process.stdout.write(`            ${g.message}\n`);
+            if (g.nextCommands && g.nextCommands.length > 0) {
+                for (const c of g.nextCommands)
+                    process.stdout.write(`              → ${c}\n`);
+            }
+        }
+        return exitCode(report.overall, strict);
+    },
+};
+function exitCode(overall, strict) {
+    if (overall === 'fail')
+        return 1;
+    if (overall === 'warn' && strict)
+        return 1;
+    return 0;
+}
+const GITHUB_WORKFLOW = `name: shrk gate
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history so 'shrk impact --since main' works
+
+      - name: Setup bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Index code-intelligence graph
+        run: bunx shrk graph index
+
+      - name: Run shrk gate
+        run: bunx shrk gate --since origin/main --strict --markdown --output gate-report.md
+
+      - name: Upload gate report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: shrk-gate-report
+          path: |
+            gate-report.md
+            .sharkcraft/quality-gates/last.json
+
+      - name: Comment on PR
+        if: github.event_name == 'pull_request' && always()
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: shrk-gate
+          path: gate-report.md
+`;
+const HUSKY_PRE_COMMIT = `#!/usr/bin/env sh
+# shrk gate pre-commit hook (husky-compatible).
+#
+# Re-indexes the code graph from staged files only, then runs the
+# default gate set against the change. Add or remove --disable flags
+# to narrow the gate set if a particular check is too slow at this
+# point in the loop.
+. "$(dirname -- "$0")/_/husky.sh"
+
+set -e
+
+bunx shrk graph index --changed
+bunx shrk gate --strict
+`;
+const RAW_PRE_COMMIT = `#!/usr/bin/env sh
+# shrk gate pre-commit hook (raw .git/hooks variant).
+#
+# Symlink or copy this file into .git/hooks/pre-commit:
+#   ln -s ../../scripts/pre-commit .git/hooks/pre-commit
+# (or just \`cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit\`).
+set -e
+
+bunx shrk graph index --changed
+bunx shrk gate --strict
+`;
+const GENERIC_SCRIPT = `#!/usr/bin/env bash
+# Generic CI runner for shrk gate. Copy / adapt for your provider.
+#
+# Usage:
+#   ./scripts/shrk-gate.sh
+#
+# Exit codes:
+#   0 — gate pass or warn (non-strict)
+#   1 — gate fail (or warn under --strict)
+set -euo pipefail
+
+# Ensure the code-intelligence graph is fresh.
+bunx shrk graph index
+
+# Run the aggregator. --strict turns warn into fail; drop it if you
+# prefer to surface warnings without blocking merge.
+bunx shrk gate \\
+  --since "\${BASE_REF:-origin/main}" \\
+  --strict \\
+  --markdown \\
+  --output gate-report.md
+`;
+async function runGateScaffoldHook(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const provider = flagString(args, 'provider') ?? 'husky';
+    const force = flagBool(args, 'force');
+    let target;
+    let body;
+    switch (provider) {
+        case 'husky':
+            target = nodePath.join(cwd, '.husky', 'pre-commit');
+            body = HUSKY_PRE_COMMIT;
+            break;
+        case 'raw':
+            target = nodePath.join(cwd, 'scripts', 'pre-commit');
+            body = RAW_PRE_COMMIT;
+            break;
+        default:
+            process.stderr.write(`Unknown --provider "${provider}". Use husky | raw.\n`);
+            return 2;
+    }
+    if (existsSync(target) && !force) {
+        const msg = `${target} already exists. Use --force to overwrite.\n`;
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'exists', path: target }) + '\n');
+            return 1;
+        }
+        process.stderr.write(msg);
+        return 1;
+    }
+    mkdirSync(nodePath.dirname(target), { recursive: true });
+    writeFileSync(target, body, 'utf8');
+    try {
+        chmodSync(target, 0o755);
+    }
+    catch {
+        // ignore — Windows / strict FS.
+    }
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, provider, wrote: target, bytes: body.length }) + '\n');
+        return 0;
+    }
+    process.stdout.write(`Scaffolded ${provider} pre-commit hook → ${target}\n`);
+    if (provider === 'raw') {
+        process.stdout.write(`Activate it with:\n  ln -s ../../scripts/pre-commit .git/hooks/pre-commit\n`);
+    }
+    return 0;
+}
+async function runGateScaffoldCi(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const provider = flagString(args, 'provider') ?? 'github';
+    const force = flagBool(args, 'force');
+    let target;
+    let body;
+    switch (provider) {
+        case 'github':
+            target = nodePath.join(cwd, '.github', 'workflows', 'shrk-gate.yml');
+            body = GITHUB_WORKFLOW;
+            break;
+        case 'generic':
+            target = nodePath.join(cwd, 'scripts', 'shrk-gate.sh');
+            body = GENERIC_SCRIPT;
+            break;
+        default:
+            process.stderr.write(`Unknown --provider "${provider}". Use github | generic.\n`);
+            return 2;
+    }
+    if (existsSync(target) && !force) {
+        const msg = `${target} already exists. Use --force to overwrite.\n`;
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'exists', path: target }) + '\n');
+            return 1;
+        }
+        process.stderr.write(msg);
+        return 1;
+    }
+    mkdirSync(nodePath.dirname(target), { recursive: true });
+    writeFileSync(target, body, 'utf8');
+    if (provider === 'generic') {
+        try {
+            chmodSync(target, 0o755);
+        }
+        catch {
+            // ignore — Windows or stricter FS.
+        }
+    }
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, provider, wrote: target, bytes: body.length }) + '\n');
+        return 0;
+    }
+    process.stdout.write(`Scaffolded ${provider} CI runner → ${target}\n`);
+    return 0;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"gen.command.d.ts","sourceRoot":"","sources":["../../src/commands/gen.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC,eAAO,MAAM,UAAU,EAAE,eAmJxB,CAAC"}
+{"version":3,"file":"gen.command.d.ts","sourceRoot":"","sources":["../../src/commands/gen.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC,eAAO,MAAM,UAAU,EAAE,eA+JxB,CAAC"}

package/dist/commands/gen.command.js

@@ -19,7 +19,7 @@ const CHANGE_LABEL = {
 export const genCommand = {
     name: 'gen',
     description: 'Generate code from a template. Defaults to dry-run.',
-    usage: 'shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--force] [--save-plan <file>] [--json]',
+    usage: 'shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--force] [--save-plan <file>] [--show-content] [--json]',
     async run(args) {
         const templateId = args.positional[0];
         const name = args.positional[1];
@@ -114,6 +114,18 @@ export const genCommand = {
         for (const change of plan.changes) {
             process.stdout.write(`${CHANGE_LABEL[change.type]} ${change.relativePath} (${change.sizeBytes} bytes) — ${change.reason}\n`);
         }
+        // --show-content: print the already-computed virtual file content so an
+        // agent can review what a template would generate WITHOUT writing to disk
+        // (the saved plan stays content-free). The bytes are identical in dry-run
+        // and --write; this is purely additive.
+        if (flagBool(args, 'show-content')) {
+            process.stdout.write('\nVirtual content (not written to disk):\n');
+            for (const change of plan.changes) {
+                const body = change.contents ?? '';
+                process.stdout.write(`\n----- ${change.relativePath} (${change.sizeBytes} bytes) -----\n`);
+                process.stdout.write(body.endsWith('\n') ? body : body + '\n');
+            }
+        }
         if (plan.postGenerationNotes.length) {
             process.stdout.write('\nPost-generation notes:\n');
             for (const note of plan.postGenerationNotes)

package/dist/commands/graph-code-subverbs.d.ts

@@ -0,0 +1,33 @@
+import { type ParsedArgs } from '../command-registry.js';
+export declare function runGraphIndex(args: ParsedArgs): Promise<number>;
+export declare function runGraphCycles(args: ParsedArgs): Promise<number>;
+export declare function runGraphUnresolved(args: ParsedArgs): Promise<number>;
+export declare function runGraphDeps(args: ParsedArgs): Promise<number>;
+export declare function runGraphStatus(args: ParsedArgs): Promise<number>;
+export declare function runGraphSearch(args: ParsedArgs): Promise<number>;
+export declare function runGraphContext(args: ParsedArgs): Promise<number>;
+export declare function runGraphImpact(args: ParsedArgs): Promise<number>;
+/**
+ * `shrk graph hubs` — the most-depended-on code: symbols ranked by how many
+ * DISTINCT files reference them, files by how many import them. The
+ * "load-bearing code" an agent should change most carefully and a human should
+ * understand first — the natural companion to `graph impact` (impact = blast
+ * radius of ONE node; hubs = the nodes with the biggest blast radius).
+ */
+export declare function runGraphHubs(args: ParsedArgs): Promise<number>;
+export declare function runGraphCallers(args: ParsedArgs): Promise<number>;
+/**
+ * `shrk graph path <from> <to>` — does code A actually reach code B?
+ *
+ * The question the original feedback fell back to grep for ("is billing
+ * actually WIRED to checkout?"). `callers` = direct callers, `impact` =
+ * reverse closure, `graph why` = the KNOWLEDGE graph — none answers the
+ * forward CODE path between two symbols/files. This BFS does, over the
+ * import/call/reference/declare/re-export/extends/implements edges, and
+ * prints each hop with its edge kind (and call-site line) so the answer
+ * shows HOW they are wired, not just that they are. When A→B has no path it
+ * also checks B→A so "the dependency runs the other way" is reported instead
+ * of a bare "no".
+ */
+export declare function runGraphPath(args: ParsedArgs): Promise<number>;
+//# sourceMappingURL=graph-code-subverbs.d.ts.map

package/dist/commands/graph-code-subverbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAiI3F,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgMvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}