@shrkcrft/inspector 0.1.0-alpha.1

package/dist/ai-readiness.js

@@ -0,0 +1,279 @@
+import { KnowledgeType, hasActionHints } from '@shrkcrft/knowledge';
+import { diagnoseActionHints } from "./action-hint-diagnostics.js";
+import { runDoctor } from "./sharkcraft-inspector.js";
+function gradeOf(score) {
+    if (score >= 85)
+        return 'excellent';
+    if (score >= 70)
+        return 'good';
+    if (score >= 50)
+        return 'partial';
+    return 'poor';
+}
+/**
+ * Map a count into a 0..10 score with a soft cap. Once the count reaches
+ * `softCap`, further increases yield diminishing returns; the score levels
+ * off at `softCap * 1.5` so a repo with 1000 entries doesn't outscore one
+ * with focused 30.
+ */
+function softCapScore(count, softCap) {
+    if (count <= 0)
+        return 0;
+    if (count >= softCap * 1.5)
+        return 10;
+    if (count >= softCap) {
+        const extra = count - softCap;
+        const slack = softCap * 0.5;
+        return Math.min(10, 8 + Math.round((extra / slack) * 2));
+    }
+    return Math.min(8, Math.round((count / softCap) * 8));
+}
+const PLACEHOLDER_MARKERS = [/\bTODO\b/i, /\bTBD\b/i, /\bplaceholder\b/i, /\bfill\s*in\b/i];
+const WORKFLOW_TYPES = new Set(['workflow', 'decision', 'convention']);
+function isCriticalOrHighWorkflow(entry) {
+    if (!WORKFLOW_TYPES.has(String(entry.type)))
+        return false;
+    const p = String(entry.priority);
+    return p === 'critical' || p === 'high';
+}
+/**
+ * Deterministic 0..100 AI-readiness score. Penalties are explicit:
+ *  - Quantity-only "stuff a registry full of entries" is capped via softCap.
+ *  - Duplicate-id warnings reduce data-quality dimension.
+ *  - Placeholder docs (TODO / TBD / "fill in") reduce docs dimension.
+ *  - Critical/high workflow entries missing actionHints reduce safety dim.
+ *  - Doctor health stays a hard gate.
+ */
+export function buildAiReadinessReport(inspection) {
+    const dims = [];
+    const recs = [];
+    // 1) Config present
+    dims.push({
+        id: 'config',
+        title: 'sharkcraft.config.ts present',
+        weight: 0.5,
+        score: inspection.configFile ? 10 : 0,
+        note: inspection.configFile
+            ? `loaded from ${inspection.configFile}`
+            : 'missing — using defaults',
+    });
+    if (!inspection.configFile) {
+        recs.push('Create sharkcraft/sharkcraft.config.ts to opt in to project-specific config.');
+    }
+    // 2) Knowledge entries — softcap at 15 (focused) and full at 22.
+    const k = inspection.knowledgeEntries.length;
+    dims.push({
+        id: 'knowledge',
+        title: 'Knowledge entries loaded',
+        weight: 1.0,
+        score: softCapScore(k, 15),
+        note: `${k} entries (softcap 15, full at 22)`,
+    });
+    if (k < 10)
+        recs.push('Add more structured knowledge entries (target: 10+).');
+    // 3) Rules — softcap at 8.
+    const rules = inspection.knowledgeEntries.filter((e) => String(e.type) === KnowledgeType.Rule);
+    dims.push({
+        id: 'rules',
+        title: 'Rules',
+        weight: 1.0,
+        score: softCapScore(rules.length, 8),
+        note: `${rules.length} rules (softcap 8)`,
+    });
+    if (rules.length < 5)
+        recs.push('Add at least 5 rules describing coding/architecture conventions.');
+    // 4) Path conventions — softcap at 6.
+    const paths = inspection.pathService.list();
+    dims.push({
+        id: 'paths',
+        title: 'Path conventions',
+        weight: 0.8,
+        score: softCapScore(paths.length, 6),
+        note: `${paths.length} path conventions (softcap 6)`,
+    });
+    if (paths.length < 4)
+        recs.push('Add path conventions for src/, services/, utils/, tests/ etc.');
+    // 5) Templates — softcap at 4.
+    const t = inspection.templates.length;
+    dims.push({
+        id: 'templates',
+        title: 'Templates',
+        weight: 0.8,
+        score: softCapScore(t, 4),
+        note: `${t} templates (softcap 4)`,
+    });
+    if (t < 3)
+        recs.push('Define templates for the constructs you generate most often.');
+    // 6) Pipelines — softcap at 3.
+    const p = inspection.pipelines.length;
+    dims.push({
+        id: 'pipelines',
+        title: 'Pipelines',
+        weight: 0.8,
+        score: softCapScore(p, 3),
+        note: `${p} pipelines (softcap 3)`,
+    });
+    if (p < 2)
+        recs.push('Add at least one feature-dev or safe-generation pipeline.');
+    // 7) Action-hint coverage — fraction of entries that carry hints.
+    const withHints = inspection.knowledgeEntries.filter((e) => hasActionHints(e)).length;
+    const hintsScore = k === 0 ? 0 : Math.min(10, Math.round((withHints / Math.max(k, 1)) * 20));
+    dims.push({
+        id: 'action-hints',
+        title: 'Entries with action hints',
+        weight: 1.2,
+        score: hintsScore,
+        note: `${withHints} of ${k} entries carry actionHints`,
+    });
+    if (hintsScore < 7)
+        recs.push('Add actionHints to high-priority rules (commands, mcpTools, forbiddenActions).');
+    // 8) Verification commands
+    const haveVerify = inspection.knowledgeEntries.some((e) => (e.actionHints?.verificationCommands?.length ?? 0) > 0);
+    dims.push({
+        id: 'verification',
+        title: 'Verification commands defined',
+        weight: 0.6,
+        score: haveVerify ? 10 : 0,
+        note: haveVerify ? 'at least one entry lists verification commands' : 'no entry lists verification commands',
+    });
+    if (!haveVerify)
+        recs.push('Add verificationCommands to safety/generation rules (e.g. typecheck + tests).');
+    // 9) Forbidden actions
+    const haveForbidden = inspection.knowledgeEntries.some((e) => (e.actionHints?.forbiddenActions?.length ?? 0) > 0);
+    dims.push({
+        id: 'forbidden',
+        title: 'Forbidden actions declared',
+        weight: 0.6,
+        score: haveForbidden ? 10 : 0,
+        note: haveForbidden ? 'at least one entry lists forbiddenActions' : 'no entry lists forbiddenActions',
+    });
+    if (!haveForbidden)
+        recs.push('Add forbiddenActions to clarify what agents must NOT do.');
+    // 10) Docs — softcap at 4. Penalize placeholder docs.
+    const docFiles = inspection.sourceFiles.filter((s) => s.endsWith('.md'));
+    let placeholderDocCount = 0;
+    for (const entry of inspection.knowledgeEntries) {
+        if (!entry.source?.origin?.endsWith('.md'))
+            continue;
+        if (PLACEHOLDER_MARKERS.some((re) => re.test(entry.content))) {
+            placeholderDocCount += 1;
+        }
+    }
+    const docsRaw = softCapScore(docFiles.length, 4);
+    const docsPenalty = Math.min(docsRaw, placeholderDocCount * 2);
+    dims.push({
+        id: 'docs',
+        title: 'Docs / task files',
+        weight: 0.4,
+        score: Math.max(0, docsRaw - docsPenalty),
+        note: placeholderDocCount > 0
+            ? `${docFiles.length} markdown files (-${docsPenalty} for ${placeholderDocCount} placeholder markers)`
+            : `${docFiles.length} markdown files`,
+    });
+    if (placeholderDocCount > 0) {
+        recs.push(`Replace TODO/placeholder markers in ${placeholderDocCount} doc/task file(s).`);
+    }
+    // 11) Doctor health — passes is a near-required gate.
+    //
+    // Action-hint quality warnings are also surfaced by the doctor, but the
+    // dedicated `hint-quality` dimension below already scores them. Counting
+    // them here too would punish the same warning twice and crush the score
+    // once a repo crosses ten hint warnings. Exclude them from this dimension.
+    const doctor = runDoctor(inspection);
+    const structuralWarnings = doctor.checks.filter((c) => c.severity === 'warning' &&
+        !c.id.startsWith('actionhints-')).length;
+    const doctorScore = doctor.passed ? Math.max(0, 10 - structuralWarnings) : 0;
+    dims.push({
+        id: 'doctor',
+        title: 'Doctor health',
+        weight: 1.0,
+        score: doctorScore,
+        note: doctor.passed
+            ? `passed (${structuralWarnings} structural warnings, ${doctor.summary.warnings} total)`
+            : `${doctor.summary.errors} errors`,
+    });
+    if (!doctor.passed)
+        recs.push('Fix doctor errors before relying on agent workflows.');
+    // 12) Pack discovery health
+    const packs = inspection.packs;
+    const packsScore = packs.discoveredPacks.length === 0
+        ? 5 // neutral when no packs are installed
+        : packs.invalidPacks.length === 0
+            ? 10
+            : 4;
+    dims.push({
+        id: 'packs',
+        title: 'Pack discovery health',
+        weight: 0.4,
+        score: packsScore,
+        note: packs.discoveredPacks.length === 0
+            ? 'no packs discovered'
+            : `${packs.validPacks.length}/${packs.discoveredPacks.length} packs valid`,
+    });
+    if (packs.invalidPacks.length > 0) {
+        recs.push('Fix invalid pack manifests (see `shrk packs doctor`).');
+    }
+    // 13) Generation safety — flagship cli-only write policy rule required.
+    const hasDryRunDefault = inspection.knowledgeEntries.some((e) => e.actionHints?.writePolicy === 'cli-only' ||
+        (e.actionHints?.forbiddenActions ?? []).some((f) => /write through mcp/i.test(f)));
+    // Additionally penalize when any critical/high workflow entry lacks hints.
+    const workflowMissingHints = inspection.knowledgeEntries.filter((e) => isCriticalOrHighWorkflow(e) && !hasActionHints(e)).length;
+    let safetyScore = hasDryRunDefault ? 10 : 3;
+    if (workflowMissingHints > 0) {
+        safetyScore = Math.max(0, safetyScore - Math.min(safetyScore, workflowMissingHints * 2));
+    }
+    dims.push({
+        id: 'safety',
+        title: 'Generation safety readiness',
+        weight: 1.0,
+        score: safetyScore,
+        note: hasDryRunDefault
+            ? workflowMissingHints > 0
+                ? `cli-only write policy present, but ${workflowMissingHints} critical/high workflow entry/entries lack actionHints`
+                : 'cli-only write policy + forbidden-actions present'
+            : 'no entry declares cli-only write policy',
+    });
+    if (!hasDryRunDefault) {
+        recs.push('Add a critical safety rule with writePolicy:"cli-only" and "do not write through MCP".');
+    }
+    if (workflowMissingHints > 0) {
+        recs.push(`Add actionHints to ${workflowMissingHints} critical/high workflow entry/entries.`);
+    }
+    // 14) Action-hint quality (delegates to diagnostics).
+    const hintReport = diagnoseActionHints(inspection.knowledgeEntries);
+    const hintIssueScore = hintReport.evaluatedEntryCount === 0
+        ? 5
+        : Math.max(0, 10 -
+            Math.min(10, Math.round((hintReport.issues.length / hintReport.evaluatedEntryCount) * 5)));
+    dims.push({
+        id: 'hint-quality',
+        title: 'Action-hint quality',
+        weight: 0.6,
+        score: hintIssueScore,
+        note: `${hintReport.issues.length} quality warnings across ${hintReport.evaluatedEntryCount} relevant entries`,
+    });
+    // 15) Data quality — duplicate ids surface as warnings.
+    const dupCount = inspection.validationIssues.filter((v) => v.code === 'duplicate-id').length;
+    const dataQualityScore = Math.max(0, 10 - Math.min(10, dupCount * 2));
+    dims.push({
+        id: 'data-quality',
+        title: 'Data quality (no duplicates)',
+        weight: 0.5,
+        score: dataQualityScore,
+        note: dupCount === 0
+            ? 'no duplicate knowledge ids'
+            : `${dupCount} duplicate id(s) — first occurrence kept`,
+    });
+    if (dupCount > 0)
+        recs.push(`Resolve ${dupCount} duplicate knowledge id(s).`);
+    // Aggregate.
+    const totalWeight = dims.reduce((sum, d) => sum + d.weight, 0);
+    const weightedSum = dims.reduce((sum, d) => sum + d.score * d.weight, 0);
+    const score = Math.round((weightedSum / totalWeight) * 10);
+    return {
+        score,
+        grade: gradeOf(score),
+        dimensions: dims,
+        topRecommendations: recs.slice(0, 5),
+    };
+}

package/dist/api-report.d.ts

@@ -0,0 +1,51 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const API_REPORT_SCHEMA = "sharkcraft.api-report/v1";
+export interface IPackageApiEntry {
+    name: string;
+    version: string;
+    packageRoot: string;
+    hasReadme: boolean;
+    main?: string;
+    types?: string;
+    bin?: Record<string, string>;
+    exports?: Record<string, unknown>;
+    deprecatedReexports: readonly string[];
+    exportedSymbols: readonly string[];
+    notes: readonly string[];
+}
+export interface IApiReport {
+    schema: typeof API_REPORT_SCHEMA;
+    generatedAt: string;
+    packages: readonly IPackageApiEntry[];
+}
+export interface IApiDiffEntry {
+    package: string;
+    added: readonly string[];
+    removed: readonly string[];
+    /** package metadata changes (version, bin, types, etc.) */
+    metadataChanges: readonly {
+        field: string;
+        from: unknown;
+        to: unknown;
+    }[];
+    /** Symbols that look like breaking-change suspects (removed from a public surface). */
+    breakingSuspects: readonly string[];
+}
+export interface IApiDiffReport {
+    schema: 'sharkcraft.api-report-diff/v1';
+    generatedAt: string;
+    oldGeneratedAt?: string;
+    newGeneratedAt: string;
+    addedPackages: readonly string[];
+    removedPackages: readonly string[];
+    entries: readonly IApiDiffEntry[];
+    /** delta of total public-surface size across all packages. */
+    publicSurfaceDelta: number;
+}
+export declare function diffApiReports(oldReport: IApiReport, newReport: IApiReport): IApiDiffReport;
+export declare function renderApiDiffMarkdown(diff: IApiDiffReport): string;
+export declare function renderApiDiffHtml(diff: IApiDiffReport): string;
+export declare function buildApiReport(inspection: ISharkcraftInspection, options?: {
+    packageFilter?: string;
+}): IApiReport;
+//# sourceMappingURL=api-report.d.ts.map

package/dist/api-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-report.d.ts","sourceRoot":"","sources":["../src/api-report.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACvC;AAsED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,eAAe,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC1E,uFAAuF;IACvF,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,+BAA+B,CAAC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,cAAc,CAsD3F;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CA6BlE;AAMD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAgB9D;AAED,wBAAgB,cAAc,CAC5B,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,UAAU,CA4CZ"}

package/dist/api-report.js

@@ -0,0 +1,254 @@
+/**
+ * Public API / package API report.
+ *
+ * For each @shrkcrft/* package, surface: name, version, main, types,
+ * exports, bin, README presence, deprecated re-exports if detectable.
+ *
+ * Read-only — just reads package.json + index files.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const API_REPORT_SCHEMA = 'sharkcraft.api-report/v1';
+function readPkg(dir) {
+    const pkgJson = nodePath.join(dir, 'package.json');
+    if (!existsSync(pkgJson))
+        return { meta: null, root: dir };
+    try {
+        return { meta: JSON.parse(readFileSync(pkgJson, 'utf8')), root: dir };
+    }
+    catch {
+        return { meta: null, root: dir };
+    }
+}
+function listPackageDirs(projectRoot) {
+    const packagesDir = nodePath.join(projectRoot, 'packages');
+    if (!existsSync(packagesDir))
+        return [];
+    const out = [];
+    for (const d of readdirSync(packagesDir)) {
+        const full = nodePath.join(packagesDir, d);
+        try {
+            if (statSync(full).isDirectory())
+                out.push(full);
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+function scanIndexExports(indexFile) {
+    if (!existsSync(indexFile))
+        return [];
+    try {
+        const t = readFileSync(indexFile, 'utf8');
+        const out = new Set();
+        const reExport = /export\s+(?:type\s+)?\*\s+from\s+['"]([^'"]+)['"]/g;
+        const namedExport = /export\s+(?:type\s+)?\{([^}]+)\}\s+from/g;
+        const inlineDecl = /export\s+(?:async\s+)?(?:const|let|var|function|class|interface|type|enum)\s+([A-Za-z0-9_$]+)/g;
+        let m;
+        while ((m = reExport.exec(t)) !== null) {
+            const ref = m[1] ?? '';
+            if (ref)
+                out.add(`re-export:${ref}`);
+        }
+        while ((m = namedExport.exec(t)) !== null) {
+            const body = m[1] ?? '';
+            for (const sym of body.split(',').map((s) => s.trim().split(/\s+as\s+/)[0] ?? '')) {
+                if (sym)
+                    out.add(sym);
+            }
+        }
+        while ((m = inlineDecl.exec(t)) !== null) {
+            const id = m[1] ?? '';
+            if (id)
+                out.add(id);
+        }
+        return [...out];
+    }
+    catch {
+        return [];
+    }
+}
+function detectDeprecated(indexFile) {
+    if (!existsSync(indexFile))
+        return [];
+    try {
+        const t = readFileSync(indexFile, 'utf8');
+        const out = [];
+        const re = /@deprecated\s+([^\n]*)/g;
+        let m;
+        while ((m = re.exec(t)) !== null)
+            out.push((m[1] ?? '').trim());
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+export function diffApiReports(oldReport, newReport) {
+    const oldByName = new Map(oldReport.packages.map((p) => [p.name, p]));
+    const newByName = new Map(newReport.packages.map((p) => [p.name, p]));
+    const addedPackages = [];
+    const removedPackages = [];
+    for (const name of newByName.keys())
+        if (!oldByName.has(name))
+            addedPackages.push(name);
+    for (const name of oldByName.keys())
+        if (!newByName.has(name))
+            removedPackages.push(name);
+    const entries = [];
+    let oldSize = 0;
+    let newSize = 0;
+    for (const p of oldReport.packages)
+        oldSize += p.exportedSymbols.length;
+    for (const p of newReport.packages)
+        newSize += p.exportedSymbols.length;
+    for (const [name, newPkg] of newByName.entries()) {
+        const oldPkg = oldByName.get(name);
+        if (!oldPkg) {
+            // newly added package
+            entries.push({
+                package: name,
+                added: newPkg.exportedSymbols,
+                removed: [],
+                metadataChanges: [],
+                breakingSuspects: [],
+            });
+            continue;
+        }
+        const oldSet = new Set(oldPkg.exportedSymbols);
+        const newSet = new Set(newPkg.exportedSymbols);
+        const added = [...newSet].filter((s) => !oldSet.has(s));
+        const removed = [...oldSet].filter((s) => !newSet.has(s));
+        const metadataChanges = [];
+        if (oldPkg.version !== newPkg.version)
+            metadataChanges.push({ field: 'version', from: oldPkg.version, to: newPkg.version });
+        if (JSON.stringify(oldPkg.bin ?? {}) !== JSON.stringify(newPkg.bin ?? {}))
+            metadataChanges.push({ field: 'bin', from: oldPkg.bin ?? {}, to: newPkg.bin ?? {} });
+        if ((oldPkg.types ?? '') !== (newPkg.types ?? ''))
+            metadataChanges.push({ field: 'types', from: oldPkg.types ?? '', to: newPkg.types ?? '' });
+        if ((oldPkg.main ?? '') !== (newPkg.main ?? ''))
+            metadataChanges.push({ field: 'main', from: oldPkg.main ?? '', to: newPkg.main ?? '' });
+        const breakingSuspects = removed.filter((sym) => !sym.startsWith('re-export:') && !sym.startsWith('_'));
+        if (added.length === 0 && removed.length === 0 && metadataChanges.length === 0)
+            continue;
+        entries.push({ package: name, added, removed, metadataChanges, breakingSuspects });
+    }
+    return {
+        schema: 'sharkcraft.api-report-diff/v1',
+        generatedAt: new Date().toISOString(),
+        ...(oldReport.generatedAt ? { oldGeneratedAt: oldReport.generatedAt } : {}),
+        newGeneratedAt: newReport.generatedAt,
+        addedPackages,
+        removedPackages,
+        entries,
+        publicSurfaceDelta: newSize - oldSize,
+    };
+}
+export function renderApiDiffMarkdown(diff) {
+    const lines = [];
+    lines.push('# API report diff');
+    lines.push('');
+    lines.push(`- public surface delta: **${diff.publicSurfaceDelta >= 0 ? '+' : ''}${diff.publicSurfaceDelta}**`);
+    if (diff.addedPackages.length > 0)
+        lines.push(`- packages added: ${diff.addedPackages.join(', ')}`);
+    if (diff.removedPackages.length > 0)
+        lines.push(`- packages removed: ${diff.removedPackages.join(', ')}`);
+    for (const e of diff.entries) {
+        lines.push('');
+        lines.push(`## ${e.package}`);
+        if (e.added.length > 0) {
+            lines.push('### Added');
+            for (const s of e.added)
+                lines.push(`- \`${s}\``);
+        }
+        if (e.removed.length > 0) {
+            lines.push('### Removed');
+            for (const s of e.removed)
+                lines.push(`- \`${s}\``);
+        }
+        if (e.metadataChanges.length > 0) {
+            lines.push('### Metadata');
+            for (const m of e.metadataChanges)
+                lines.push(`- \`${m.field}\`: \`${JSON.stringify(m.from)}\` → \`${JSON.stringify(m.to)}\``);
+        }
+        if (e.breakingSuspects.length > 0) {
+            lines.push('### Breaking-change suspects');
+            for (const s of e.breakingSuspects)
+                lines.push(`- \`${s}\``);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+export function renderApiDiffHtml(diff) {
+    const body = [];
+    body.push('<h1>API report diff</h1>');
+    body.push(`<p>Public surface delta: <strong>${diff.publicSurfaceDelta}</strong></p>`);
+    if (diff.addedPackages.length > 0)
+        body.push(`<p>Added: ${escapeHtml(diff.addedPackages.join(', '))}</p>`);
+    if (diff.removedPackages.length > 0)
+        body.push(`<p>Removed: ${escapeHtml(diff.removedPackages.join(', '))}</p>`);
+    for (const e of diff.entries) {
+        body.push(`<h2>${escapeHtml(e.package)}</h2>`);
+        if (e.added.length > 0)
+            body.push('<p>Added: ' + e.added.map((s) => `<code>${escapeHtml(s)}</code>`).join(', ') + '</p>');
+        if (e.removed.length > 0)
+            body.push('<p>Removed: ' + e.removed.map((s) => `<code>${escapeHtml(s)}</code>`).join(', ') + '</p>');
+        if (e.breakingSuspects.length > 0)
+            body.push('<p>Breaking-change suspects: ' + e.breakingSuspects.map((s) => `<code>${escapeHtml(s)}</code>`).join(', ') + '</p>');
+    }
+    return `<!doctype html><meta charset="utf-8"><title>API diff</title>${body.join('\n')}`;
+}
+export function buildApiReport(inspection, options = {}) {
+    const dirs = listPackageDirs(inspection.projectRoot);
+    const packages = [];
+    for (const dir of dirs) {
+        const { meta } = readPkg(dir);
+        if (!meta)
+            continue;
+        const name = String(meta.name ?? '');
+        if (options.packageFilter && name !== options.packageFilter)
+            continue;
+        const version = String(meta.version ?? '0.0.0');
+        const main = typeof meta.main === 'string' ? meta.main : undefined;
+        const types = typeof meta.types === 'string' ? meta.types : undefined;
+        const bin = meta.bin && typeof meta.bin === 'object' ? meta.bin : undefined;
+        const exportsField = meta.exports && typeof meta.exports === 'object' ? meta.exports : undefined;
+        const indexCandidates = [
+            main && nodePath.resolve(dir, main),
+            nodePath.resolve(dir, 'src/index.ts'),
+            nodePath.resolve(dir, 'src/main.ts'),
+        ].filter((s) => typeof s === 'string');
+        const indexFile = indexCandidates.find((f) => existsSync(f)) ?? indexCandidates[0];
+        const exportedSymbols = indexFile ? scanIndexExports(indexFile) : [];
+        const deprecatedReexports = indexFile ? detectDeprecated(indexFile) : [];
+        const readmeAbs = nodePath.join(dir, 'README.md');
+        const notes = [];
+        if (!existsSync(readmeAbs))
+            notes.push('README.md missing.');
+        if (!indexFile)
+            notes.push('No src/index.ts entry detected.');
+        packages.push({
+            name,
+            version,
+            packageRoot: dir,
+            hasReadme: existsSync(readmeAbs),
+            ...(main ? { main } : {}),
+            ...(types ? { types } : {}),
+            ...(bin ? { bin } : {}),
+            ...(exportsField ? { exports: exportsField } : {}),
+            exportedSymbols,
+            deprecatedReexports,
+            notes,
+        });
+    }
+    return {
+        schema: API_REPORT_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        packages,
+    };
+}

package/dist/apply-dispatch-trace.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Apply dispatch trace.
+ *
+ * Builds an explanation of which dispatch path an apply / plan-review will
+ * take for a given saved plan: which kind of plan it is (template, helper,
+ * plugin-lifecycle, registration-hint, synthetic, unknown), which handler
+ * module would run, how many file/folder ops are involved, and which
+ * safety gates apply.
+ *
+ * Read-only. Never spawns the actual apply.
+ */
+import type { ISavedPlan } from '@shrkcrft/generator';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const APPLY_DISPATCH_TRACE_SCHEMA = "sharkcraft.apply-dispatch-trace/v1";
+export declare enum DispatchKind {
+    Template = "template",
+    Helper = "helper",
+    PluginLifecycle = "plugin-lifecycle",
+    RegistrationHint = "registration-hint",
+    Synthetic = "synthetic",
+    Unknown = "unknown"
+}
+export type DispatchSource = 'registry/template' | 'registry/helper' | 'registry/plugin-lifecycle-profile' | 'registry/registration-hint' | 'synthetic' | 'unknown';
+export interface IDispatchFileOpCounts {
+    readonly create: number;
+    readonly update: number;
+    readonly append: number;
+    readonly insertBefore: number;
+    readonly insertAfter: number;
+    readonly replace: number;
+    readonly exportLine: number;
+    readonly skip: number;
+    readonly conflict: number;
+}
+export interface IDispatchFolderOpCounts {
+    readonly renameFolder: number;
+    readonly deleteFolder: number;
+}
+export interface IDispatchSafetyGate {
+    readonly id: 'signature' | 'divergence' | 'folder-ops-allow-flag' | 'folder-ops-safety' | 'delete-folder-allow-flag' | 'contract-gate';
+    readonly status: 'not-checked' | 'will-pass' | 'will-block' | 'requires-flag';
+    readonly detail?: string;
+}
+export interface IApplyDispatchTrace {
+    readonly schema: typeof APPLY_DISPATCH_TRACE_SCHEMA;
+    readonly templateId: string;
+    readonly dispatchKind: DispatchKind;
+    readonly source: DispatchSource;
+    /** Best-effort handler description (module + symbol). */
+    readonly handler: string;
+    /** Whether the plan uses a synthetic templateId (prefix `__`). */
+    readonly synthetic: boolean;
+    /** Total file changes carried by the saved plan's expectedChanges. */
+    readonly totalFileOps: number;
+    /** Total folder operations carried by the saved plan. */
+    readonly totalFolderOps: number;
+    readonly fileOpCounts: IDispatchFileOpCounts;
+    readonly folderOpCounts: IDispatchFolderOpCounts;
+    /** Plan-v2 operation kinds (PlannedOperation.kind). */
+    readonly plannedOperationKinds: ReadonlyArray<string>;
+    /** Signature status as it would be after `--verify-signature`. */
+    readonly signatureStatus: 'not-checked' | 'verified' | 'unsigned' | 'invalid';
+    readonly signatureMessage?: string;
+    /** Gates the apply CLI would evaluate before writing. */
+    readonly safetyGates: ReadonlyArray<IDispatchSafetyGate>;
+    /** Flags the operator must pass for the apply to succeed. */
+    readonly requiredFlags: ReadonlyArray<string>;
+    /** Final action the apply would take in the current state. */
+    readonly finalAction: 'dry-run' | 'blocked' | 'would-apply';
+    /** When `blocked`, the reason(s). */
+    readonly blockReasons: ReadonlyArray<string>;
+}
+export interface IBuildDispatchTraceOptions {
+    /** Saved plan to trace. */
+    readonly plan: ISavedPlan;
+    /** Workspace inspection — used to look up template/helper/profile. */
+    readonly inspection: ISharkcraftInspection;
+    /** Pass `true` when the operator intends to use --dry-run. */
+    readonly dryRun?: boolean;
+    /** Pass `true` when --allow-folder-ops will be set. */
+    readonly allowFolderOps?: boolean;
+    /** Pass `true` when --allow-delete-folder will be set. */
+    readonly allowDeleteFolder?: boolean;
+    /** Pass `true` when --verify-signature will be set. */
+    readonly verifySignature?: boolean;
+    /** Pass `true` when the plan diverges from the live template output. */
+    readonly diverged?: boolean;
+    /** Optional contract gate status — when supplied, included as a gate. */
+    readonly contractGate?: 'pass' | 'fail' | 'not-applicable';
+}
+export declare function buildApplyDispatchTrace(options: IBuildDispatchTraceOptions): IApplyDispatchTrace;
+export declare function renderApplyDispatchTraceText(trace: IApplyDispatchTrace): string;
+//# sourceMappingURL=apply-dispatch-trace.d.ts.map