@shrkcrft/cli 0.1.0-alpha.23 → 0.1.0-alpha.25

package/dist/finish/run-finish.d.ts

@@ -0,0 +1,62 @@
+import { type IChangedScopeOptions } from '@shrkcrft/inspector';
+export declare const FINISH_SCHEMA: "sharkcraft.finish/v1";
+/** Outcome of one sub-gate. `skipped` = nothing to evaluate (loud, never silent green). */
+export type FinishGateStatus = 'pass' | 'fail' | 'skipped';
+/** One failing/relevant item, with file:line where the engine provides it. */
+export interface IFinishItem {
+    readonly file?: string;
+    readonly line?: number;
+    readonly message: string;
+}
+export interface IFinishGate {
+    readonly name: 'boundaries' | 'imports' | 'wiring' | 'policy' | 'orphans';
+    readonly status: FinishGateStatus;
+    /** One-line reason (e.g. why skipped, or the error/warning counts). */
+    readonly detail: string;
+    readonly errors: number;
+    readonly warnings: number;
+    /** Failing/notable items (capped by the renderer, full in JSON). */
+    readonly items: readonly IFinishItem[];
+}
+export interface IFinishImpact {
+    readonly ran: boolean;
+    readonly risk?: string;
+    readonly directDependents?: number;
+    readonly transitiveDependents?: number;
+    /** Why the summary could not run (no graph index / no changed files). */
+    readonly note?: string;
+}
+export interface IFinishReport {
+    readonly schema: typeof FINISH_SCHEMA;
+    readonly scope: {
+        readonly mode: 'worktree' | 'staged' | 'since' | 'files';
+        readonly files: readonly string[];
+        readonly fileCount: number;
+    };
+    readonly gates: readonly IFinishGate[];
+    readonly impact: IFinishImpact;
+    /** `fail` iff any gate failed OR the config could not load; else `pass`. */
+    readonly verdict: 'pass' | 'fail';
+    /** Total warning-severity findings across gates (non-blocking). */
+    readonly warnings: number;
+    /** Set when sharkcraft.config.ts could not be loaded — forces a `fail`. */
+    readonly configError?: string;
+    readonly summary: string;
+    readonly nextAction: string;
+}
+export interface IRunFinishInput {
+    readonly cwd: string;
+    readonly mode: 'worktree' | 'staged' | 'since' | 'files';
+    readonly scope: IChangedScopeOptions;
+}
+/**
+ * The composite "is this changeset safe to finish?" orchestrator. Runs every
+ * deterministic CHANGED-ONLY gate inline — boundaries + import-hygiene + wiring
+ * + policy + deleted-orphans — plus a best-effort impact summary, and folds
+ * them into ONE pass/fail. This is the single trustworthy "done?" call an
+ * autonomous agent needs and can't reliably assemble by hand (only shrk can run
+ * the alias-resolved layer/wiring gates). Honors the `0-rules → skipped`
+ * semantics so a no-op sub-check is reported, never silently passed. Read-only.
+ */
+export declare function runFinishGates(input: IRunFinishInput): Promise<IFinishReport>;
+//# sourceMappingURL=run-finish.d.ts.map

package/dist/finish/run-finish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAa7B,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAYD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAkHnF"}

package/dist/finish/run-finish.js

@@ -0,0 +1,239 @@
+import { buildImportHygieneReport, filterViolationsToChangedScope, inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { evaluateBoundaries, loadTsconfigPaths, runPolicyLint, runWiring, scanImports, } from '@shrkcrft/boundaries';
+import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+export const FINISH_SCHEMA = 'sharkcraft.finish/v1';
+/** Map the changed-scope onto the orphan check's diff inputs. */
+function orphanOptsFor(input) {
+    if (input.mode === 'files')
+        return undefined; // a file list has no diff to read deletions from
+    if (input.mode === 'staged')
+        return { staged: true };
+    if (input.mode === 'since' && input.scope.since)
+        return { since: input.scope.since };
+    // Worktree mode: diff deletions vs HEAD so the orphan gate's "deleted" set
+    // matches the working-tree scope the other gates use (not the whole branch).
+    return { since: 'HEAD' };
+}
+/**
+ * The composite "is this changeset safe to finish?" orchestrator. Runs every
+ * deterministic CHANGED-ONLY gate inline — boundaries + import-hygiene + wiring
+ * + policy + deleted-orphans — plus a best-effort impact summary, and folds
+ * them into ONE pass/fail. This is the single trustworthy "done?" call an
+ * autonomous agent needs and can't reliably assemble by hand (only shrk can run
+ * the alias-resolved layer/wiring gates). Honors the `0-rules → skipped`
+ * semantics so a no-op sub-check is reported, never silently passed. Read-only.
+ */
+export async function runFinishGates(input) {
+    const { cwd } = input;
+    const changed = resolveChangedFiles(input.scope);
+    const changedFiles = changed.files;
+    const gates = [];
+    // ── boundaries (changed-only) ────────────────────────────────────────
+    const inspection = await inspectSharkcraft({ cwd });
+    const boundaryRules = inspection.boundaryRegistry.list();
+    if (boundaryRules.length === 0) {
+        gates.push(skip('boundaries', 'no boundary rules configured'));
+    }
+    else if (changedFiles.length === 0) {
+        gates.push(skip('boundaries', 'no files in changed scope'));
+    }
+    else {
+        const scan = scanImports({ projectRoot: cwd });
+        const tsconfigPaths = loadTsconfigPaths(cwd);
+        const evalResult = evaluateBoundaries(scan, boundaryRules, {
+            ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
+        });
+        const filtered = filterViolationsToChangedScope(evalResult.violations, input.scope);
+        const errors = filtered.includedViolations.filter((v) => v.severity === 'error');
+        const warnings = filtered.includedViolations.filter((v) => v.severity === 'warning');
+        gates.push({
+            name: 'boundaries',
+            status: errors.length > 0 ? 'fail' : 'pass',
+            detail: `${errors.length} error(s), ${warnings.length} warning(s) across ${changedFiles.length} changed file(s)`,
+            errors: errors.length,
+            warnings: warnings.length,
+            items: [...errors, ...warnings].map((v) => ({
+                file: v.file,
+                line: v.line,
+                message: `[${v.severity}] ${v.ruleId}: ${v.message}`,
+            })),
+        });
+    }
+    // ── import hygiene (changed-only) ────────────────────────────────────
+    if (changedFiles.length === 0) {
+        gates.push(skip('imports', 'no files in changed scope'));
+    }
+    else {
+        const report = buildImportHygieneReport(cwd, { files: changedFiles });
+        const errors = report.counts?.['error'] ?? (report.verdict === 'errors' ? report.findings.length : 0);
+        const warnings = report.counts?.['warning'] ?? (report.verdict === 'warnings' ? report.findings.length : 0);
+        gates.push({
+            name: 'imports',
+            status: report.verdict === 'errors' ? 'fail' : 'pass',
+            detail: `verdict=${report.verdict} (${report.findings.length} finding(s))`,
+            errors,
+            warnings,
+            items: report.findings.map((f) => ({
+                file: f.file,
+                line: f.line,
+                message: `${f.kind}: ${f.suggestedFix || f.reason || f.snippet}`.trim(),
+            })),
+        });
+    }
+    // ── wiring + policy (changed-only, from resolved config) ─────────────
+    const loaded = await resolveProjectConfig(cwd);
+    let configError;
+    if (!loaded.ok) {
+        // A MALFORMED config in a real sharkcraft project is a fail (the wiring/
+        // policy gates can't be trusted). The mere ABSENCE of a sharkcraft/ folder
+        // is not — those gates simply don't apply, so skip them without failing.
+        const isSharkcraftProject = existsSync(nodePath.join(cwd, 'sharkcraft'));
+        if (isSharkcraftProject)
+            configError = loaded.error.message;
+        const detail = isSharkcraftProject
+            ? `config did not load: ${loaded.error.message}`
+            : 'no sharkcraft config (gate not applicable)';
+        gates.push(skip('wiring', detail));
+        gates.push(skip('policy', detail));
+    }
+    else {
+        gates.push(wiringGate(cwd, loaded.value.config.wiringRules ?? [], changedFiles), policyGate(cwd, loaded.value.config.policyRules ?? [], changedFiles));
+    }
+    // ── deleted-orphans (write-safety) ───────────────────────────────────
+    gates.push(await orphansGate(input));
+    // ── impact summary (informational, best-effort) ──────────────────────
+    const impact = await impactSummary(cwd, changedFiles);
+    // ── fold into one verdict ────────────────────────────────────────────
+    const failed = gates.filter((g) => g.status === 'fail');
+    const warnings = gates.reduce((n, g) => n + g.warnings, 0);
+    const verdict = failed.length > 0 || configError ? 'fail' : 'pass';
+    const skipped = gates.filter((g) => g.status === 'skipped').map((g) => g.name);
+    const summary = verdict === 'fail'
+        ? `Not safe to finish: ${configError ? 'config failed to load; ' : ''}${failed.map((g) => `${g.name} (${g.errors} error(s))`).join(', ') || 'see gates'}.`
+        : changedFiles.length === 0 && input.mode !== 'files'
+            ? 'No files in the changed scope — nothing to gate.'
+            : `Safe to finish: every applicable gate passed${warnings > 0 ? ` (${warnings} non-blocking warning(s))` : ''}${skipped.length > 0 ? `; skipped: ${skipped.join(', ')}` : ''}.`;
+    const nextAction = verdict === 'fail'
+        ? 'Fix every failing gate item (each carries file:line), then re-run `shrk finish`.'
+        : 'Safe to declare done.';
+    return {
+        schema: FINISH_SCHEMA,
+        scope: { mode: input.mode, files: changedFiles, fileCount: changedFiles.length },
+        gates,
+        impact,
+        verdict,
+        warnings,
+        ...(configError ? { configError } : {}),
+        summary,
+        nextAction,
+    };
+}
+function skip(name, detail) {
+    return { name, status: 'skipped', detail, errors: 0, warnings: 0, items: [] };
+}
+function wiringGate(cwd, rules, changedFiles) {
+    if (rules.length === 0)
+        return skip('wiring', 'no wiring rules configured');
+    const report = runWiring(cwd, rules, { changedOnly: true, changedFiles });
+    if (report.evaluated === 0) {
+        return skip('wiring', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    }
+    const errors = report.violations.filter((v) => v.severity === 'error');
+    const warnings = report.violations.filter((v) => v.severity === 'warning');
+    // A misconfigured rule (bad regex / no capture group) yields a diagnostic +
+    // rule-level error but NO violation — it must FAIL the gate, never read as a
+    // silent green ("loud, never silent green").
+    const diag = report.diagnostics;
+    return {
+        name: 'wiring',
+        status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
+        errors: errors.length + diag.length,
+        warnings: warnings.length,
+        items: [
+            ...report.violations.map((v) => ({
+                file: v.file,
+                line: v.line,
+                message: `[${v.severity}] ${v.ruleId}: "${v.token}" ${v.direction === 'registered-missing' ? 'registered but not declared' : 'declared but not registered'}`,
+            })),
+            ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+        ],
+    };
+}
+function policyGate(cwd, rules, changedFiles) {
+    if (rules.length === 0)
+        return skip('policy', 'no policy rules configured');
+    const report = runPolicyLint(cwd, rules, { changedOnly: true, changedFiles });
+    if (report.evaluated === 0) {
+        return skip('policy', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    }
+    const errors = report.findings.filter((f) => f.severity === 'error');
+    const warnings = report.findings.filter((f) => f.severity === 'warning');
+    const diag = report.diagnostics;
+    return {
+        name: 'policy',
+        status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
+        errors: errors.length + diag.length,
+        warnings: warnings.length,
+        items: [
+            ...report.findings.map((f) => ({
+                file: f.file,
+                line: f.line,
+                message: `[${f.severity}] ${f.ruleId}: ${f.message ?? ''}`.trim(),
+            })),
+            ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+        ],
+    };
+}
+async function orphansGate(input) {
+    const opts = orphanOptsFor(input);
+    if (!opts)
+        return skip('orphans', 'explicit --files scope has no diff to read deletions from');
+    const scan = await computeDeletedOrphans(input.cwd, opts);
+    if (!scan.ok) {
+        return skip('orphans', scan.reason === 'graph-missing'
+            ? 'code-graph index missing — run `shrk graph index` to enable the orphan check'
+            : `diff unavailable: ${scan.error ?? 'unknown'}`);
+    }
+    if (scan.deleted.length === 0)
+        return skip('orphans', `nothing deleted (vs ${scan.ref})`);
+    const orphans = scan.report?.orphans ?? [];
+    return {
+        name: 'orphans',
+        status: orphans.length > 0 ? 'fail' : 'pass',
+        detail: `${scan.deleted.length} deleted file(s) (vs ${scan.ref}) — ${orphans.length} surviving importer(s)`,
+        errors: orphans.length,
+        warnings: 0,
+        items: orphans.map((o) => ({
+            file: o.path ?? o.id,
+            ...(typeof o.line === 'number' ? { line: o.line } : {}),
+            message: o.via === 'reference' && o.symbol
+                ? `references \`${o.symbol}\` from deleted ${o.deletedFile}`
+                : `imports deleted ${o.deletedFile}`,
+        })),
+    };
+}
+async function impactSummary(cwd, changedFiles) {
+    if (changedFiles.length === 0)
+        return { ran: false, note: 'no changed files' };
+    try {
+        const { GraphStore } = await import('@shrkcrft/graph');
+        if (!new GraphStore(cwd).exists()) {
+            return { ran: false, note: 'code-graph index missing — run `shrk graph index`' };
+        }
+        const { analyzeGraphImpact } = await import('@shrkcrft/impact-engine');
+        const analysis = analyzeGraphImpact({ kind: 'files', files: [...changedFiles] }, { projectRoot: cwd, maxDepth: 5, limit: 200 });
+        return {
+            ran: true,
+            risk: analysis.risk,
+            directDependents: analysis.directDependents.length,
+            transitiveDependents: analysis.transitiveDependents.length,
+        };
+    }
+    catch (e) {
+        return { ran: false, note: `impact summary unavailable: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}

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,EAKhB,MAAM,uBAAuB,CAAC;AA0X/B,wBAAgB,aAAa,IAAI,eAAe,CA8X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAqID;;;;;;;;;;;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,EAKhB,MAAM,uBAAuB,CAAC;AA6X/B,wBAAgB,aAAa,IAAI,eAAe,CAiY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -22,6 +22,7 @@ import { presetsListCommand, presetsGetCommand, presetsExplainCommand, presetsRe
 import { taskCommand } from "./commands/task.command.js";
 import { preflightCommand } from "./commands/preflight.command.js";
 import { checkCommand } from "./commands/check.command.js";
+import { finishCommand } from "./commands/finish.command.js";
 import { diffCheckCommand } from "./commands/diff-check.command.js";
 import { driftCommand } from "./commands/drift.command.js";
 import { graphCommand } from "./commands/graph.command.js";
@@ -33,6 +34,7 @@ import { frameworkCommand } from "./commands/framework.command.js";
 import { apiDiffCommand } from "./commands/api-diff.command.js";
 import { gateCommand } from "./commands/gate.command.js";
 import { policyLintCommand } from "./commands/policy-lint.command.js";
+import { wiringCommand } from "./commands/wiring.command.js";
 import { reuseCommand } from "./commands/reuse.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
 import { coverageCommand } from "./commands/coverage.command.js";
@@ -71,6 +73,7 @@ import { movePlanCommand } from "./commands/move-plan.command.js";
 import { watchCommand, watchListCommand, watchPruneCommand, watchStopCommand } from "./commands/watch.command.js";
 import { mcpCommand } from "./commands/mcp.command.js";
 import { versionCommand } from "./commands/version.command.js";
+import { changelogCommand } from "./commands/changelog.command.js";
 import { makeHelpCommand } from "./commands/help.command.js";
 import { qualityCommand } from "./commands/quality.command.js";
 import { ciCommand } from "./commands/ci.command.js";
@@ -189,6 +192,7 @@ export function buildRegistry() {
     registry.register(explainCommand);
     registry.register(checkCommand);
     registry.register(diffCheckCommand);
+    registry.register(finishCommand);
     // changed-only preflight orchestrator.
     registry.register(preflightCommand);
     registry.register(driftCommand);
@@ -201,6 +205,7 @@ export function buildRegistry() {
     registry.register(apiDiffCommand);
     registry.register(gateCommand);
     registry.register(policyLintCommand);
+    registry.register(wiringCommand);
     registry.register(reuseCommand);
     registry.register(migrateCommand);
     registry.register(coverageCommand);
@@ -245,6 +250,7 @@ export function buildRegistry() {
     registry.registerSubcommand('watch', watchPruneCommand);
     registry.register(mcpCommand);
     registry.register(versionCommand);
+    registry.register(changelogCommand);
     registry.register(qualityCommand);
     registry.register(ciCommand);
     registry.register(eslintCommand);

package/dist/validation/typecheck-emitted.d.ts

@@ -0,0 +1,36 @@
+/** A file the generator would emit, with its rendered (in-memory) contents. */
+export interface IEmittedFile {
+    /** Absolute path the file would land at. */
+    absPath: string;
+    /** Rendered body (never written to disk by the typecheck). */
+    contents: string;
+}
+/** A single typecheck error located in an emitted file. */
+export interface IEmittedTypecheckError {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+}
+export interface IEmittedTypecheckResult {
+    /** False when there were no TS/TSX files to check (e.g. a docs-only template). */
+    ran: boolean;
+    errors: readonly IEmittedTypecheckError[];
+    /** Human note (why it didn't run, or which tsconfig it used). */
+    note?: string;
+}
+/**
+ * Typecheck a set of EMITTED (not-yet-written) files against the project's
+ * detected tsconfig, without touching disk. Builds a `ts.Program` whose root
+ * names are the emitted files, over a compiler host that overlays the rendered
+ * bodies for those paths and reads everything else (imports, lib) from disk — so
+ * a scaffold that references a real project symbol resolves, and a template bug
+ * (bad syntax, a dangling import, a type mismatch) surfaces BEFORE apply instead
+ * of at the human's next build.
+ *
+ * Only diagnostics located IN the emitted files are reported; pre-existing
+ * errors elsewhere in the project are ignored (this is a generation gate, not a
+ * whole-repo typecheck).
+ */
+export declare function typecheckEmittedFiles(projectRoot: string, files: readonly IEmittedFile[]): IEmittedTypecheckResult;
+//# sourceMappingURL=typecheck-emitted.d.ts.map

package/dist/validation/typecheck-emitted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typecheck-emitted.d.ts","sourceRoot":"","sources":["../../src/validation/typecheck-emitted.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC1C,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,uBAAuB,CAmFzB"}

package/dist/validation/typecheck-emitted.js

@@ -0,0 +1,109 @@
+import * as ts from 'typescript';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const TSCONFIG_NAMES = ['tsconfig.json', 'tsconfig.base.json'];
+function findTsconfig(projectRoot) {
+    for (const name of TSCONFIG_NAMES) {
+        const p = resolve(projectRoot, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Typecheck a set of EMITTED (not-yet-written) files against the project's
+ * detected tsconfig, without touching disk. Builds a `ts.Program` whose root
+ * names are the emitted files, over a compiler host that overlays the rendered
+ * bodies for those paths and reads everything else (imports, lib) from disk — so
+ * a scaffold that references a real project symbol resolves, and a template bug
+ * (bad syntax, a dangling import, a type mismatch) surfaces BEFORE apply instead
+ * of at the human's next build.
+ *
+ * Only diagnostics located IN the emitted files are reported; pre-existing
+ * errors elsewhere in the project are ignored (this is a generation gate, not a
+ * whole-repo typecheck).
+ */
+export function typecheckEmittedFiles(projectRoot, files) {
+    const tsFiles = files.filter((f) => /\.tsx?$/.test(f.absPath));
+    if (tsFiles.length === 0) {
+        return { ran: false, errors: [], note: 'no TS/TSX files in the emit set' };
+    }
+    let options = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true,
+        esModuleInterop: true,
+    };
+    const tsconfigPath = findTsconfig(projectRoot);
+    if (tsconfigPath) {
+        const read = ts.readConfigFile(tsconfigPath, (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        });
+        if (!read.error) {
+            const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(tsconfigPath));
+            options = parsed.options;
+        }
+    }
+    // Force a non-emitting, lib-skipping check regardless of the project's config.
+    options.noEmit = true;
+    options.skipLibCheck = true;
+    options.incremental = false;
+    delete options.composite;
+    delete options.outDir;
+    delete options.declaration;
+    const overlay = new Map(tsFiles.map((f) => [resolve(f.absPath), f.contents]));
+    const host = ts.createCompilerHost(options, true);
+    const origGetSourceFile = host.getSourceFile.bind(host);
+    const origReadFile = host.readFile.bind(host);
+    const origFileExists = host.fileExists.bind(host);
+    host.readFile = (fileName) => {
+        const k = resolve(fileName);
+        return overlay.has(k) ? overlay.get(k) : origReadFile(fileName);
+    };
+    host.fileExists = (fileName) => overlay.has(resolve(fileName)) || origFileExists(fileName);
+    host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreate) => {
+        const k = resolve(fileName);
+        const body = overlay.get(k);
+        if (body !== undefined) {
+            return ts.createSourceFile(fileName, body, languageVersionOrOptions, true);
+        }
+        return origGetSourceFile(fileName, languageVersionOrOptions, onError, shouldCreate);
+    };
+    const rootNames = tsFiles.map((f) => resolve(f.absPath));
+    const program = ts.createProgram({ rootNames, options, host });
+    const errors = [];
+    for (const rn of rootNames) {
+        const sf = program.getSourceFile(rn);
+        if (!sf)
+            continue;
+        const diags = [...program.getSyntacticDiagnostics(sf), ...program.getSemanticDiagnostics(sf)];
+        for (const d of diags) {
+            if (d.category !== ts.DiagnosticCategory.Error)
+                continue;
+            let line = 0;
+            let column = 0;
+            if (d.file && typeof d.start === 'number') {
+                const lc = d.file.getLineAndCharacterOfPosition(d.start);
+                line = lc.line + 1;
+                column = lc.character + 1;
+            }
+            errors.push({
+                file: resolve(d.file?.fileName ?? rn),
+                line,
+                column,
+                message: ts.flattenDiagnosticMessageText(d.messageText, '\n'),
+            });
+        }
+    }
+    return {
+        ran: true,
+        errors,
+        ...(tsconfigPath ? { note: `checked against ${tsconfigPath}` } : { note: 'no tsconfig found — used defaults' }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "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.23",
-    "@shrkcrft/compress": "^0.1.0-alpha.23",
-    "@shrkcrft/config": "^0.1.0-alpha.23",
-    "@shrkcrft/workspace": "^0.1.0-alpha.23",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.23",
-    "@shrkcrft/context": "^0.1.0-alpha.23",
-    "@shrkcrft/rules": "^0.1.0-alpha.23",
-    "@shrkcrft/paths": "^0.1.0-alpha.23",
-    "@shrkcrft/templates": "^0.1.0-alpha.23",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.23",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.23",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.23",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.23",
-    "@shrkcrft/presets": "^0.1.0-alpha.23",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.23",
-    "@shrkcrft/graph": "^0.1.0-alpha.23",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.23",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.23",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.23",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.23",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.23",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.23",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.23",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.23",
-    "@shrkcrft/migrate": "^0.1.0-alpha.23",
-    "@shrkcrft/generator": "^0.1.0-alpha.23",
-    "@shrkcrft/importer": "^0.1.0-alpha.23",
-    "@shrkcrft/inspector": "^0.1.0-alpha.23",
-    "@shrkcrft/ai": "^0.1.0-alpha.23",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.23",
-    "@shrkcrft/shared": "^0.1.0-alpha.23",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.23",
+    "@shrkcrft/core": "^0.1.0-alpha.25",
+    "@shrkcrft/compress": "^0.1.0-alpha.25",
+    "@shrkcrft/config": "^0.1.0-alpha.25",
+    "@shrkcrft/workspace": "^0.1.0-alpha.25",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.25",
+    "@shrkcrft/context": "^0.1.0-alpha.25",
+    "@shrkcrft/rules": "^0.1.0-alpha.25",
+    "@shrkcrft/paths": "^0.1.0-alpha.25",
+    "@shrkcrft/templates": "^0.1.0-alpha.25",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.25",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.25",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.25",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.25",
+    "@shrkcrft/presets": "^0.1.0-alpha.25",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.25",
+    "@shrkcrft/graph": "^0.1.0-alpha.25",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.25",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.25",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.25",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.25",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.25",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.25",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.25",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.25",
+    "@shrkcrft/migrate": "^0.1.0-alpha.25",
+    "@shrkcrft/generator": "^0.1.0-alpha.25",
+    "@shrkcrft/importer": "^0.1.0-alpha.25",
+    "@shrkcrft/inspector": "^0.1.0-alpha.25",
+    "@shrkcrft/ai": "^0.1.0-alpha.25",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.25",
+    "@shrkcrft/shared": "^0.1.0-alpha.25",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.25",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {