@shrkcrft/inspector 0.1.0-alpha.2

package/dist/registration-hint-registry.js

@@ -0,0 +1,327 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Registration hint registry. Pack- and local-contributed hints
+ * surface downstream registration steps that constructs typically need
+ * (composer wiring, route table entries, capability registration, etc.).
+ *
+ * The engine ships zero hints; every entry comes from a contribution.
+ *
+ * Read-only: hints can be listed, fetched by id, validated, and previewed
+ * against the live file system, but the engine never auto-applies them.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { validateRegistrationHint, } from '@shrkcrft/plugin-api';
+export const REGISTRATION_HINT_REGISTRY_SCHEMA = 'sharkcraft.registration-hint-registry/v1';
+export var RegistrationHintSource;
+(function (RegistrationHintSource) {
+    RegistrationHintSource["Local"] = "local";
+    RegistrationHintSource["Pack"] = "pack";
+    RegistrationHintSource["Fixture"] = "fixture";
+})(RegistrationHintSource || (RegistrationHintSource = {}));
+async function importDefault(file) {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    if (Array.isArray(mod.default))
+        return mod.default;
+    if (mod.default && typeof mod.default === 'object')
+        return [mod.default];
+    if (Array.isArray(mod.registrationHints))
+        return mod.registrationHints;
+    return [];
+}
+function localFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    for (const name of ['registration-hints.ts', 'registration-hints/index.ts']) {
+        const abs = nodePath.join(dir, name);
+        if (existsSync(abs))
+            out.push(abs);
+    }
+    const cfg = inspection.config;
+    for (const rel of cfg?.registrationHintFiles ?? []) {
+        out.push(nodePath.isAbsolute(rel) ? rel : nodePath.join(dir, rel));
+    }
+    return out;
+}
+export async function loadRegistrationHints(inspection) {
+    const entries = [];
+    const issues = [];
+    const seen = new Set();
+    const ingest = (raw, source, packageName, sourceFile) => {
+        const v = validateRegistrationHint(raw);
+        if (!v.valid) {
+            for (const i of v.issues) {
+                issues.push({
+                    severity: 'error',
+                    code: 'invalid-hint',
+                    message: `${i.field}: ${i.message}`,
+                    hintId: typeof raw.id === 'string' ? raw.id : undefined,
+                    source: sourceFile,
+                });
+            }
+            return;
+        }
+        if (seen.has(raw.id)) {
+            issues.push({
+                severity: 'error',
+                code: 'duplicate-id',
+                message: `Registration hint "${raw.id}" already loaded; skipping ${sourceFile}.`,
+                hintId: raw.id,
+                source: sourceFile,
+            });
+            return;
+        }
+        seen.add(raw.id);
+        entries.push({
+            hint: raw,
+            source,
+            ...(packageName ? { packageName } : {}),
+            sourceFile,
+        });
+    };
+    for (const file of localFiles(inspection)) {
+        try {
+            const list = await importDefault(file);
+            const rel = nodePath.relative(inspection.projectRoot, file) || file;
+            for (const h of list)
+                ingest(h, RegistrationHintSource.Local, undefined, rel);
+        }
+        catch (e) {
+            issues.push({
+                severity: 'warning',
+                code: 'load-failed',
+                message: `Failed to load ${file}: ${e.message}`,
+                source: file,
+            });
+        }
+    }
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const rel of contributions.registrationHintFiles ?? []) {
+            const file = nodePath.resolve(pack.packageRoot, rel);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'missing-file',
+                    message: `Pack ${pack.packageName} declares ${rel} but file is missing.`,
+                    source: file,
+                });
+                continue;
+            }
+            try {
+                const list = await importDefault(file);
+                for (const h of list)
+                    ingest(h, RegistrationHintSource.Pack, pack.packageName, rel);
+            }
+            catch (e) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'load-failed',
+                    message: `Pack ${pack.packageName} (${rel}): ${e.message}`,
+                    source: file,
+                });
+            }
+        }
+    }
+    return { entries, issues };
+}
+export async function listRegistrationHints(inspection) {
+    const { entries } = await loadRegistrationHints(inspection);
+    return entries;
+}
+export async function getRegistrationHint(inspection, hintId) {
+    const entries = await listRegistrationHints(inspection);
+    return entries.find((e) => e.hint.id === hintId) ?? null;
+}
+export async function previewRegistrationHint(inspection, hintId, options = {}) {
+    const entry = await getRegistrationHint(inspection, hintId);
+    if (!entry)
+        return null;
+    const { hint } = entry;
+    const variables = options.variables ?? {};
+    const missingVariables = (hint.variables ?? [])
+        .filter((v) => v.required && variables[v.name] === undefined && v.defaultValue === undefined)
+        .map((v) => v.name);
+    // Discovery: prefer fixed targetFile when present, otherwise enumerate
+    // candidates from globs on the live file system.
+    let targetFile = null;
+    let candidates = [];
+    if (hint.discovery.targetFile) {
+        targetFile = hint.discovery.targetFile;
+        candidates = [hint.discovery.targetFile];
+    }
+    else if (hint.discovery.targetGlobs && hint.discovery.targetGlobs.length > 0) {
+        candidates = await resolveGlobsAgainstRoot(inspection.projectRoot, hint.discovery.targetGlobs);
+        if (candidates.length === 1)
+            targetFile = candidates[0];
+    }
+    const ambiguous = candidates.length !== 1;
+    const requiresHumanReview = hint.requiresHumanReview === true || ambiguous;
+    const renderedOps = hint.operations.map((op) => {
+        const description = describeOp(op);
+        const out = { kind: op.kind, description };
+        if (op.anchor)
+            out.anchor = op.anchor;
+        if (op.snippet)
+            out.snippet = substituteVars(op.snippet, variables);
+        return out;
+    });
+    return {
+        schema: 'sharkcraft.registration-hint-preview/v1',
+        hintId,
+        title: hint.title,
+        targetFile,
+        candidates,
+        ambiguous,
+        requiresHumanReview,
+        operations: renderedOps,
+        missingVariables,
+        safetyNotes: hint.safetyNotes ?? [],
+        validationCommands: hint.validationCommands ?? [],
+        nextCommand: ambiguous
+            ? `# Multiple candidates — pick one and apply manually.`
+            : `# Preview only. Apply manually after human review.`,
+    };
+}
+async function resolveGlobsAgainstRoot(projectRoot, globs) {
+    const out = [];
+    for (const glob of globs) {
+        // Crude glob: only `*` and `**` recognized; fallback to literal.
+        if (!glob.includes('*')) {
+            const abs = nodePath.join(projectRoot, glob);
+            if (existsSync(abs))
+                out.push(glob);
+            continue;
+        }
+        const baseSegments = [];
+        for (const seg of glob.split('/')) {
+            if (seg.includes('*'))
+                break;
+            baseSegments.push(seg);
+        }
+        const base = baseSegments.length > 0 ? nodePath.join(projectRoot, ...baseSegments) : projectRoot;
+        // Replace `**` with `___DOUBLESTAR___` BEFORE escaping; then
+        // escape special chars; then convert single `*` and the placeholder.
+        const escaped = glob
+            .replace(/\*\*/g, '___DOUBLESTAR___')
+            .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '[^/]*')
+            .replace(/___DOUBLESTAR___/g, '.*');
+        let re;
+        try {
+            re = new RegExp('^' + escaped + '$');
+        }
+        catch {
+            // Malformed glob — skip.
+            continue;
+        }
+        if (!existsSync(base))
+            continue;
+        // Walk the base directory looking for matches (capped, deterministic).
+        const stack = [base];
+        let safety = 0;
+        while (stack.length > 0 && safety < 5000) {
+            const dir = stack.pop();
+            safety += 1;
+            try {
+                const { readdirSync } = await import('node:fs');
+                const entries = readdirSync(dir, { withFileTypes: true });
+                for (const e of entries) {
+                    const next = nodePath.join(dir, String(e.name));
+                    if (e.isDirectory())
+                        stack.push(next);
+                    else if (e.isFile()) {
+                        const rel = nodePath.relative(projectRoot, next);
+                        if (re.test(rel))
+                            out.push(rel);
+                    }
+                }
+            }
+            catch {
+                // ignore traversal errors
+            }
+        }
+    }
+    return Array.from(new Set(out));
+}
+function describeOp(op) {
+    switch (op.kind) {
+        case 'ensure-import':
+            return `ensure-import from "${op.from ?? '?'}"${op.symbols ? ` { ${op.symbols.join(', ')} }` : ''}`;
+        case 'insert-enum-entry':
+            return `insert-enum-entry ${op.enumName ?? '?'}`;
+        case 'insert-object-entry':
+            return `insert-object-entry ${op.objectName ?? '?'}`;
+        case 'insert-before-closing-brace':
+            return `insert-before-closing-brace of "${op.containerName ?? '?'}"`;
+        case 'insert-between-anchors':
+            return `insert-between-anchors "${op.beginAnchor ?? '?'}" .. "${op.endAnchor ?? '?'}"`;
+        case 'insert-after':
+            return `insert-after anchor "${op.anchor ?? '?'}"`;
+        case 'insert-before':
+            return `insert-before anchor "${op.anchor ?? '?'}"`;
+        case 'append':
+            return `append snippet`;
+        case 'export':
+            return `export${op.symbols ? ` { ${op.symbols.join(', ')} }` : ''} from "${op.from ?? '?'}"`;
+    }
+}
+function substituteVars(snippet, vars) {
+    return snippet.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (_m, key) => vars[key] !== undefined ? vars[key] : `{{${key}}}`);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Doctor
+// ─────────────────────────────────────────────────────────────────────────────
+export async function listRegistrationHintIssues(inspection) {
+    const { issues, entries } = await loadRegistrationHints(inspection);
+    const out = [...issues];
+    // Cross-validate: target files referenced by hints with a fixed
+    // `targetFile` must currently exist; report missing as warning.
+    for (const e of entries) {
+        if (e.hint.discovery.targetFile) {
+            const abs = nodePath.join(inspection.projectRoot, e.hint.discovery.targetFile);
+            if (!existsSync(abs)) {
+                out.push({
+                    severity: 'warning',
+                    code: 'target-file-missing',
+                    message: `Registration hint "${e.hint.id}" targets ${e.hint.discovery.targetFile} but the file is missing.`,
+                    hintId: e.hint.id,
+                    source: e.sourceFile,
+                });
+            }
+            else {
+                // Sanity: if the hint uses an anchor, verify the anchor exists.
+                for (const op of e.hint.operations) {
+                    if (op.anchor) {
+                        try {
+                            const content = readFileSync(abs, 'utf8');
+                            if (!content.includes(op.anchor)) {
+                                out.push({
+                                    severity: 'info',
+                                    code: 'anchor-not-present',
+                                    message: `Hint "${e.hint.id}" expects anchor "${op.anchor}" in ${e.hint.discovery.targetFile} but it is missing today.`,
+                                    hintId: e.hint.id,
+                                    source: e.sourceFile,
+                                });
+                            }
+                        }
+                        catch {
+                            // ignore read errors
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/registry-lifecycle.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Registry lifecycle symmetry rule.
+ *
+ * Scans the workspace for `register*` APIs (functions or methods) and checks
+ * that a matching `remove*` / `unregister*` / `clear*` exists in the same file,
+ * with optional scope-aware naming (e.g. `registerXByScope` ↔ `removeXByScope`).
+ *
+ * Ignored: generated files (.generated.*, .d.ts), files containing
+ * `@shrkcrft lifecycle-ignore <reason>`. Sites with `@shrkcrft lifecycle-managed-by <name>`
+ * are reported under `ignored` with the managed-by reference.
+ */
+export interface IRegistryPair {
+    registerName: string;
+    removerName: string;
+    file: string;
+    registerLine: number;
+    removerLine: number;
+}
+export interface IRegistryMissingRemover {
+    registerName: string;
+    expectedRemoverNames: ReadonlyArray<string>;
+    file: string;
+    line: number;
+    suggestion: string;
+}
+export interface IRegistryIgnored {
+    registerName: string;
+    file: string;
+    line: number;
+    reason: string;
+    managedBy?: string;
+}
+export interface IRegistryLifecycleReport {
+    schema: 'sharkcraft.registry-lifecycle/v1';
+    filesScanned: number;
+    registersFound: number;
+    matchedPairs: ReadonlyArray<IRegistryPair>;
+    missingRemovers: ReadonlyArray<IRegistryMissingRemover>;
+    ignored: ReadonlyArray<IRegistryIgnored>;
+    recommendations: ReadonlyArray<string>;
+}
+export declare function buildRegistryLifecycleReport(input: {
+    projectRoot: string;
+    limit?: number;
+}): IRegistryLifecycleReport;
+export declare function renderRegistryLifecycleReportText(report: IRegistryLifecycleReport): string;
+//# sourceMappingURL=registry-lifecycle.d.ts.map

package/dist/registry-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-lifecycle.d.ts","sourceRoot":"","sources":["../src/registry-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,kCAAkC,CAAC;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAC3C,eAAe,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;IACxD,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACzC,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACxC;AAyHD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,wBAAwB,CAoE3B;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CA6B1F"}

package/dist/registry-lifecycle.js

@@ -0,0 +1,214 @@
+/**
+ * Registry lifecycle symmetry rule.
+ *
+ * Scans the workspace for `register*` APIs (functions or methods) and checks
+ * that a matching `remove*` / `unregister*` / `clear*` exists in the same file,
+ * with optional scope-aware naming (e.g. `registerXByScope` ↔ `removeXByScope`).
+ *
+ * Ignored: generated files (.generated.*, .d.ts), files containing
+ * `@shrkcrft lifecycle-ignore <reason>`. Sites with `@shrkcrft lifecycle-managed-by <name>`
+ * are reported under `ignored` with the managed-by reference.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    '.git',
+    '.sharkcraft',
+    'coverage',
+    '.nx',
+    'build',
+    'out',
+]);
+const SCAN_EXTENSIONS = new Set(['.ts', '.tsx']);
+function isGeneratedFile(file, content) {
+    if (file.endsWith('.d.ts'))
+        return true;
+    if (/\.generated\.(ts|tsx)$/.test(file))
+        return true;
+    if (/^\/\/ @generated\b/m.test(content))
+        return true;
+    return false;
+}
+function walk(dir, projectRoot, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (SKIP_DIRS.has(e.name))
+            continue;
+        if (e.name.startsWith('.') && e.name !== '.sharkcraft') {
+            // skip hidden dotfiles
+            if (e.name !== '.')
+                continue;
+        }
+        const abs = join(dir, e.name);
+        if (e.isDirectory()) {
+            walk(abs, projectRoot, out);
+        }
+        else if (e.isFile() && SCAN_EXTENSIONS.has(extname(e.name))) {
+            out.push(abs);
+        }
+    }
+}
+const REGISTER_PATTERNS = Object.freeze([
+    // export function registerX(
+    /(?:export\s+)?(?:async\s+)?function\s+(register[A-Z]\w*)\s*\(/g,
+    // public/private registerX(
+    /(?:public|private|protected)?\s*(?:async\s+)?(register[A-Z]\w*)\s*\(/g,
+    // someRegistry.registerX = (...) =>
+    /\b(register[A-Z]\w*)\s*=\s*\(/g,
+]);
+function findRegistersInFile(content) {
+    const out = [];
+    const seen = new Set();
+    for (const re of REGISTER_PATTERNS) {
+        let m;
+        re.lastIndex = 0;
+        while ((m = re.exec(content)) !== null) {
+            const name = m[1];
+            if (seen.has(`${name}@${m.index}`))
+                continue;
+            seen.add(`${name}@${m.index}`);
+            const line = content.slice(0, m.index).split('\n').length;
+            out.push({ name, line });
+        }
+    }
+    return out;
+}
+function findIgnoreAnnotations(content, registerName) {
+    const ignoreRe = new RegExp(`@shrkcrft\\s+lifecycle-ignore(?:\\s+([^\\n]+))?[\\s\\S]{0,200}?\\b${registerName}\\b`, 'm');
+    const managedRe = new RegExp(`@shrkcrft\\s+lifecycle-managed-by\\s+([\\w.-]+)[\\s\\S]{0,200}?\\b${registerName}\\b`, 'm');
+    const ignoreMatch = content.match(ignoreRe);
+    if (ignoreMatch) {
+        return { ignore: true, reason: ignoreMatch[1]?.trim() ?? 'no reason given' };
+    }
+    const managedMatch = content.match(managedRe);
+    if (managedMatch) {
+        return { ignore: true, managedBy: managedMatch[1], reason: 'managed-by directive' };
+    }
+    return { ignore: false };
+}
+function expectedRemoverNames(registerName) {
+    // registerX → removeX / unregisterX / clearX
+    // registerXByScope → removeXByScope / unregisterXByScope / clearXByScope
+    const stem = registerName.slice('register'.length);
+    return [`remove${stem}`, `unregister${stem}`, `clear${stem}`];
+}
+function findRemoverInContent(content, candidates) {
+    for (const name of candidates) {
+        const re = new RegExp(`(?:export\\s+)?(?:async\\s+)?function\\s+${name}\\s*\\(|\\b${name}\\s*=\\s*\\(|(?:public|private|protected)?\\s*(?:async\\s+)?${name}\\s*\\(`);
+        const m = content.match(re);
+        if (m && typeof m.index === 'number') {
+            const line = content.slice(0, m.index).split('\n').length;
+            return { name, line };
+        }
+    }
+    return null;
+}
+export function buildRegistryLifecycleReport(input) {
+    const { projectRoot } = input;
+    const files = [];
+    walk(projectRoot, projectRoot, files);
+    const limit = input.limit ?? 2000;
+    const scanFiles = files.slice(0, limit);
+    const matchedPairs = [];
+    const missingRemovers = [];
+    const ignored = [];
+    let registersFound = 0;
+    for (const file of scanFiles) {
+        let content;
+        try {
+            content = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (isGeneratedFile(file, content))
+            continue;
+        const registers = findRegistersInFile(content);
+        for (const reg of registers) {
+            registersFound += 1;
+            const ann = findIgnoreAnnotations(content, reg.name);
+            if (ann.ignore) {
+                ignored.push({
+                    registerName: reg.name,
+                    file: relative(projectRoot, file),
+                    line: reg.line,
+                    reason: ann.reason ?? 'ignored',
+                    ...(ann.managedBy ? { managedBy: ann.managedBy } : {}),
+                });
+                continue;
+            }
+            const candidates = expectedRemoverNames(reg.name);
+            const remover = findRemoverInContent(content, candidates);
+            if (remover) {
+                matchedPairs.push({
+                    registerName: reg.name,
+                    removerName: remover.name,
+                    file: relative(projectRoot, file),
+                    registerLine: reg.line,
+                    removerLine: remover.line,
+                });
+            }
+            else {
+                missingRemovers.push({
+                    registerName: reg.name,
+                    expectedRemoverNames: candidates,
+                    file: relative(projectRoot, file),
+                    line: reg.line,
+                    suggestion: `Add ${candidates[0]}() / ${candidates[1]}() / ${candidates[2]}() — or annotate with \`@shrkcrft lifecycle-ignore <reason>\` / \`@shrkcrft lifecycle-managed-by <name>\` if cleanup is owned elsewhere.`,
+                });
+            }
+        }
+    }
+    const recommendations = [];
+    if (missingRemovers.length > 0) {
+        recommendations.push(`Run \`shrk check registry-lifecycle --json\` and add the matching remover(s), or document why not via a \`@shrkcrft lifecycle-ignore\` / \`@shrkcrft lifecycle-managed-by\` annotation.`);
+    }
+    return {
+        schema: 'sharkcraft.registry-lifecycle/v1',
+        filesScanned: scanFiles.length,
+        registersFound,
+        matchedPairs,
+        missingRemovers,
+        ignored,
+        recommendations,
+    };
+}
+export function renderRegistryLifecycleReportText(report) {
+    const lines = [];
+    lines.push('=== Registry lifecycle ===');
+    lines.push(`  files scanned     ${report.filesScanned}`);
+    lines.push(`  registers found   ${report.registersFound}`);
+    lines.push(`  matched pairs     ${report.matchedPairs.length}`);
+    lines.push(`  missing removers  ${report.missingRemovers.length}`);
+    lines.push(`  ignored           ${report.ignored.length}`);
+    lines.push('');
+    if (report.missingRemovers.length > 0) {
+        lines.push('Missing removers:');
+        for (const m of report.missingRemovers.slice(0, 50)) {
+            lines.push(`  ${m.file}:${m.line}  ${m.registerName}`);
+            lines.push(`      ↳ ${m.suggestion}`);
+        }
+    }
+    if (report.ignored.length > 0) {
+        lines.push('');
+        lines.push('Ignored:');
+        for (const i of report.ignored.slice(0, 20)) {
+            lines.push(`  ${i.file}:${i.line}  ${i.registerName}  (${i.reason}${i.managedBy ? `; managed-by ${i.managedBy}` : ''})`);
+        }
+    }
+    if (report.recommendations.length > 0) {
+        lines.push('');
+        lines.push('Recommendations:');
+        for (const r of report.recommendations)
+            lines.push(`  • ${r}`);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/release-readiness.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Aggregated release-readiness gate. Composes the existing read-only audits
+ * into one verdict so reviewers can answer "is this safe to tag?" without
+ * remembering every individual command.
+ *
+ * Pure read-only: never writes, never publishes, never invokes shells.
+ */
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/** Max age in days for a preflight summary file before it's flagged stale. */
+export declare const PREFLIGHT_STALE_AFTER_DAYS = 7;
+export declare const RELEASE_READINESS_SCHEMA = "sharkcraft.release-readiness/v1";
+export declare enum ReleaseReadinessSeverity {
+    Info = "info",
+    Warning = "warning",
+    Error = "error"
+}
+export interface IReleaseReadinessCheck {
+    id: string;
+    title: string;
+    status: 'pass' | 'warn' | 'fail' | 'skipped';
+    severity: ReleaseReadinessSeverity;
+    message: string;
+    suggestion?: string;
+}
+export interface IReleaseReadinessReport {
+    schema: typeof RELEASE_READINESS_SCHEMA;
+    generatedAt: string;
+    projectRoot: string;
+    ready: boolean;
+    strict: boolean;
+    blockers: readonly IReleaseReadinessCheck[];
+    warnings: readonly IReleaseReadinessCheck[];
+    passed: readonly IReleaseReadinessCheck[];
+    skipped: readonly IReleaseReadinessCheck[];
+    checklist: readonly string[];
+}
+export interface IReleaseReadinessOptions {
+    /** Treat warnings as blockers. Default: false. */
+    strict?: boolean;
+    /** Optional path to a release:preflight summary JSON. May be a directory
+     *  (newest file wins) or the literal string 'auto' to search known
+     *  locations. */
+    preflightSummaryFile?: string;
+    /** Optional list of pack paths to include in release-check. */
+    packPaths?: readonly string[];
+    /** Include suggested fixes for each blocker/warning. */
+    includeFixSuggestions?: boolean;
+    /** Include docs/examples checks (already independently runnable). */
+    includeDocsCheck?: boolean;
+    /** Include examples check. */
+    includeExamplesCheck?: boolean;
+}
+/** Auto-discover the newest preflight summary file. */
+export declare function findNewestPreflightSummary(projectRoot: string): string | null;
+export declare function buildReleaseReadiness(inspection: ISharkcraftInspection, options?: IReleaseReadinessOptions): Promise<IReleaseReadinessReport>;
+/** Render a release readiness report as JS-free HTML. */
+export declare function renderReleaseReadinessHtml(report: IReleaseReadinessReport): string;
+/**
+ * Extract the pack-signature release gate so it can be unit-tested
+ * without invoking the full release-readiness pipeline (which runs doctor +
+ * coverage and needs a full inspection shape).
+ */
+export declare function buildPackSignatureReleaseGate(inspection: ISharkcraftInspection): IReleaseReadinessCheck;
+//# sourceMappingURL=release-readiness.d.ts.map

package/dist/release-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-readiness.d.ts","sourceRoot":"","sources":["../src/release-readiness.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAE1E,oBAAY,wBAAwB;IAClC,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,wBAAwB,CAAC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC5C,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC5C,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC1C,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC3C,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;qBAEiB;IACjB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,wDAAwD;IACxD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,8BAA8B;IAC9B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,uDAAuD;AACvD,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgC7E;AA2MD,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA4PlC;AAED,yDAAyD;AACzD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAyClF;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,qBAAqB,GAChC,sBAAsB,CAyBxB"}