@shrkcrft/inspector 0.1.0-alpha.1

package/dist/contradictions.js

@@ -0,0 +1,391 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const CONTRADICTIONS_SCHEMA = 'sharkcraft.contradictions/v1';
+export var ContradictionKind;
+(function (ContradictionKind) {
+    ContradictionKind["MissingPath"] = "missing-path";
+    ContradictionKind["MissingCommand"] = "missing-command";
+    ContradictionKind["StalePath"] = "stale-path";
+    ContradictionKind["OldCliPath"] = "old-cli-path";
+    ContradictionKind["MissingExport"] = "missing-export";
+    ContradictionKind["DocVsConfigConflict"] = "doc-vs-config-conflict";
+    ContradictionKind["DeprecatedRecommendation"] = "deprecated-recommendation";
+})(ContradictionKind || (ContradictionKind = {}));
+export var ContradictionSeverity;
+(function (ContradictionSeverity) {
+    ContradictionSeverity["Error"] = "error";
+    ContradictionSeverity["Warning"] = "warning";
+    ContradictionSeverity["Info"] = "info";
+})(ContradictionSeverity || (ContradictionSeverity = {}));
+const DEFAULT_DOC_SCAN_LIMIT = 80;
+const DEFAULT_BYTES_PER_DOC = 200_000;
+const DOC_EXTS = new Set(['.md', '.mdx', '.rst', '.txt']);
+const DOC_DIR_NAMES = new Set(['docs', 'documentation', 'doc']);
+const DEPRECATED_CLI_HINTS = [
+    { re: /\bsharkcraft\s+/i, replacement: 'shrk ' },
+    { re: /\b@shrkcrft\/cli\s+/i, replacement: 'shrk ' },
+];
+const DEPRECATED_RECOMMENDATION_HINTS = [
+    { re: /TSLint/i, reason: 'TSLint has been deprecated in favour of ESLint.' },
+    { re: /\bvar\s+[A-Za-z_$]/g, reason: 'Prefer `const` / `let` over `var` in modern code.' },
+];
+const CODE_FENCE_RE = /^```([a-zA-Z0-9_-]*)\s*$/;
+const COMMAND_FENCE_LANGS = new Set(['sh', 'bash', 'shell', 'zsh', 'console']);
+const REL_PATH_HINT_RE = /(?:^|[\s`(\[])(?:\.\/|src\/|packages\/|libs\/|apps\/|examples\/|docs\/|scripts\/|tools\/|tests?\/|e2e\/|sharkcraft\/)[\w@\/_.\-+]+/g;
+const INLINE_CODE_PATH_RE = /`([^`]+)`/g;
+const SOURCE_PREFIX_RE = /^(\.\/|src\/|packages\/|libs\/|apps\/|examples\/|docs\/|scripts\/|tools\/|tests?\/|e2e\/|sharkcraft\/|\.github\/)/;
+const SCHEMA_ID_RE = /^[a-z][\w.-]*\.[\w.-]*\/v\d+$/;
+const GH_ACTION_RE = /^[\w.-]+\/[\w.-]+(@[\w.\-+~]+)?$/;
+export function buildContradictionReport(options) {
+    const inspection = options.inspection;
+    const projectRoot = inspection.projectRoot;
+    const docLimit = options.docScanLimit ?? DEFAULT_DOC_SCAN_LIMIT;
+    const byteLimit = options.bytesPerDoc ?? DEFAULT_BYTES_PER_DOC;
+    const limitations = [];
+    const findings = [];
+    const docs = collectDocs(projectRoot, docLimit);
+    if (docs.length >= docLimit) {
+        limitations.push(`Doc scan limited to ${docLimit} files; deeper trees may not be covered.`);
+    }
+    const knownScripts = new Set();
+    for (const script of Object.keys(inspection.workspace.scripts ?? {}))
+        knownScripts.add(script);
+    const cliCommandNames = collectShrkCommandNames();
+    for (const doc of docs) {
+        let body = '';
+        try {
+            body = readFileSync(doc.abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (body.length > byteLimit) {
+            body = body.slice(0, byteLimit);
+            limitations.push(`Doc ${doc.rel} truncated at ${byteLimit} bytes.`);
+        }
+        const lines = body.split(/\r?\n/);
+        let inFence = false;
+        let fenceLang = null;
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? '';
+            const fenceMatch = line.match(CODE_FENCE_RE);
+            if (fenceMatch) {
+                if (inFence) {
+                    inFence = false;
+                    fenceLang = null;
+                }
+                else {
+                    inFence = true;
+                    fenceLang = fenceMatch[1]?.toLowerCase() ?? '';
+                }
+                continue;
+            }
+            // Missing paths — only check inline-coded paths and well-known relative path forms.
+            const refs = extractPathReferences(line);
+            const seenOnLine = new Set();
+            for (const ref of refs) {
+                if (!looksLikePath(ref))
+                    continue;
+                const cleaned = ref.replace(/[.,;:!\)\]`]+$/g, '').replace(/^[`(\[]+/, '');
+                if (!cleaned)
+                    continue;
+                if (cleaned.startsWith('http://') || cleaned.startsWith('https://'))
+                    continue;
+                const probe = cleaned.startsWith('./') ? cleaned.slice(2) : cleaned;
+                if (seenOnLine.has(probe))
+                    continue;
+                seenOnLine.add(probe);
+                const abs = nodePath.join(projectRoot, probe);
+                if (!existsSync(abs)) {
+                    findings.push({
+                        id: `missing-path:${doc.rel}:${i + 1}:${probe}`,
+                        kind: ContradictionKind.MissingPath,
+                        severity: ContradictionSeverity.Warning,
+                        message: `Doc references missing path \`${probe}\`.`,
+                        source: doc.rel,
+                        line: i + 1,
+                        reference: probe,
+                        suggestion: 'Update the doc or restore the file.',
+                        reason: 'Doc-vs-tree consistency.',
+                    });
+                }
+            }
+            // Commands referenced inside a shell fence.
+            if (inFence && fenceLang && COMMAND_FENCE_LANGS.has(fenceLang)) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#'))
+                    continue;
+                const tokens = trimmed.split(/\s+/);
+                if (tokens.length === 0)
+                    continue;
+                const head = tokens[0];
+                const next = tokens[1] ?? '';
+                // Old `sharkcraft <verb>` patterns.
+                if (head === 'sharkcraft' && next) {
+                    findings.push({
+                        id: `old-cli-path:${doc.rel}:${i + 1}`,
+                        kind: ContradictionKind.OldCliPath,
+                        severity: ContradictionSeverity.Warning,
+                        message: `Doc uses deprecated CLI prefix \`sharkcraft ${next}\` (now \`shrk ${next}\`).`,
+                        source: doc.rel,
+                        line: i + 1,
+                        reference: trimmed,
+                        suggestion: `Replace with \`shrk ${next}\`.`,
+                        reason: 'CLI renamed from sharkcraft to shrk.',
+                    });
+                }
+                // `shrk <verb>` — verify verb exists in command catalogue.
+                if (head === 'shrk' && next && !next.startsWith('-')) {
+                    if (cliCommandNames.size > 0 && !cliCommandNames.has(next)) {
+                        findings.push({
+                            id: `missing-command:${doc.rel}:${i + 1}:${next}`,
+                            kind: ContradictionKind.MissingCommand,
+                            severity: ContradictionSeverity.Warning,
+                            message: `Doc references CLI command \`shrk ${next}\` which is not in the catalogue.`,
+                            source: doc.rel,
+                            line: i + 1,
+                            reference: `shrk ${next}`,
+                            suggestion: 'Update the doc or add the command.',
+                            reason: 'Doc-vs-CLI consistency.',
+                        });
+                    }
+                }
+                // npm/bun script references.
+                if ((head === 'bun' || head === 'npm' || head === 'pnpm' || head === 'yarn') && (next === 'run' || next === 'x')) {
+                    const script = tokens[2];
+                    if (script && !script.startsWith('-') && next === 'run' && knownScripts.size > 0 && !knownScripts.has(script)) {
+                        findings.push({
+                            id: `missing-command:${doc.rel}:${i + 1}:${script}`,
+                            kind: ContradictionKind.MissingCommand,
+                            severity: ContradictionSeverity.Warning,
+                            message: `Doc references package-script \`${head} run ${script}\` which is not defined in package.json.`,
+                            source: doc.rel,
+                            line: i + 1,
+                            reference: `${head} run ${script}`,
+                            suggestion: 'Add the script or update the doc.',
+                            reason: 'Doc-vs-scripts consistency.',
+                        });
+                    }
+                }
+            }
+            // Deprecated CLI hints (inline mentions, even outside fences).
+            if (!inFence) {
+                for (const hint of DEPRECATED_CLI_HINTS) {
+                    const m = line.match(/\bsharkcraft\s+([\w-]+)/);
+                    if (m && !line.includes('shrk ')) {
+                        findings.push({
+                            id: `deprecated:${doc.rel}:${i + 1}`,
+                            kind: ContradictionKind.OldCliPath,
+                            severity: ContradictionSeverity.Info,
+                            message: `Doc mentions \`sharkcraft ${m[1] ?? ''}\` (now \`shrk ${m[1] ?? ''}\`).`,
+                            source: doc.rel,
+                            line: i + 1,
+                            reference: m[0],
+                            suggestion: `Use \`shrk ${m[1] ?? ''}\`.`,
+                            reason: 'CLI rename.',
+                        });
+                    }
+                    // Marker — uses the imported hint to satisfy lint.
+                    void hint;
+                }
+            }
+        }
+    }
+    return {
+        schema: CONTRADICTIONS_SCHEMA,
+        projectRoot,
+        findings,
+        filesScanned: docs.length,
+        limitations,
+    };
+}
+function collectDocs(projectRoot, limit) {
+    const found = [];
+    const visit = (dir) => {
+        if (found.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (found.length >= limit)
+                return;
+            if (entry.startsWith('.') && entry !== '.cursor')
+                continue;
+            if (entry === 'node_modules' || entry === 'dist' || entry === 'build' || entry === 'coverage' || entry === '.angular' || entry === '.next' || entry === '.nuxt')
+                continue;
+            const abs = nodePath.join(dir, entry);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                visit(abs);
+                continue;
+            }
+            const ext = nodePath.extname(entry).toLowerCase();
+            const base = entry.toLowerCase();
+            const isTopReadme = dir === projectRoot && /^readme\.(md|mdx|rst)$/i.test(entry);
+            const isChangelog = /^changelog\./i.test(entry);
+            const isDocsDir = DOC_DIR_NAMES.has(nodePath.basename(dir).toLowerCase());
+            if (isTopReadme || isChangelog || (DOC_EXTS.has(ext) && (isDocsDir || base.includes('readme') || base.includes('guide')))) {
+                const rel = nodePath.relative(projectRoot, abs);
+                found.push({ rel, abs });
+            }
+        }
+    };
+    visit(projectRoot);
+    return found;
+}
+function extractPathReferences(line) {
+    const refs = [];
+    let m;
+    const re1 = new RegExp(INLINE_CODE_PATH_RE.source, 'g');
+    while ((m = re1.exec(line)) !== null) {
+        const captured = m[1];
+        if (captured && captured.length > 0 && captured.length < 200)
+            refs.push(captured);
+    }
+    const re2 = new RegExp(REL_PATH_HINT_RE.source, 'g');
+    while ((m = re2.exec(line)) !== null) {
+        refs.push(m[0].trim());
+    }
+    return refs;
+}
+function looksLikePath(s) {
+    if (!s)
+        return false;
+    if (s.startsWith('http'))
+        return false;
+    if (s.includes(' '))
+        return false;
+    if (/[<>{}]/.test(s))
+        return false; // placeholders / brace-expansions
+    if (s.endsWith('/'))
+        return false; // generic dir reference
+    if (s.startsWith('@'))
+        return false; // npm package
+    if (SCHEMA_ID_RE.test(s))
+        return false; // sharkcraft.foo/v1
+    if (GH_ACTION_RE.test(s))
+        return false; // org/repo style
+    // Require either a specific source-tree prefix and a `.ext`, or a fully-qualified path with extension.
+    const hasSlash = s.includes('/');
+    const hasExt = /\.(md|mdx|ts|tsx|js|jsx|mjs|cjs|json|yaml|yml|toml|svg|png|css|scss|html|sh|py|go|rs|java|kt|cs)$/i.test(s);
+    if (!hasSlash)
+        return false;
+    if (!SOURCE_PREFIX_RE.test(s) && !hasExt)
+        return false;
+    // Reject pseudo-paths that contain literal globs/wildcards.
+    if (/[*?]/.test(s))
+        return false;
+    return true;
+}
+function collectShrkCommandNames() {
+    // Hard-coded list of well-known top-level commands. Importing the CLI here
+    // would create a layering violation (inspector → cli) — instead we mirror
+    // the catalogue that `shrk commands` would print. Missing entries simply
+    // suppress contradiction findings for those commands, which is the safe
+    // failure mode.
+    return new Set([
+        'init', 'inspect', 'doctor', 'context', 'gen', 'apply', 'export', 'import',
+        'task', 'next', 'find', 'explain', 'check', 'watch', 'drift', 'graph',
+        'coverage', 'review', 'onboard', 'test', 'plan', 'session', 'dev', 'ask',
+        'mcp', 'version', 'quality', 'ci', 'commands', 'safety', 'infer', 'report',
+        'dashboard', 'bundle', 'impact', 'search', 'brief', 'demo', 'release',
+        'start-here', 'handoff', 'map', 'intent', 'orchestrate', 'simulate', 'view',
+        'recommend', 'risk', 'migration', 'contract', 'languages', 'help',
+        'memory', 'heal', 'agent', 'docs', 'examples', 'self', 'install',
+        'diagnostics', 'intelligence', 'architecture', 'decisions', 'compliance',
+        'policy', 'product', 'reposet', 'packs', 'upgrade', 'api', 'boundaries',
+        'repo', 'owners', 'ownership', 'runtime', 'constructs', 'playbooks',
+        'presets', 'pipelines', 'paths', 'rules', 'templates', 'knowledge',
+        'schemas', 'scaffolds', 'tests',
+        // Additions
+        'ingest', 'understand-task', 'validate-change', 'contradictions', 'generated', 'stability',
+    ]);
+}
+export function renderContradictionReportText(report) {
+    const lines = [];
+    lines.push('=== Contradictions report ===');
+    lines.push(`  findings   ${report.findings.length}`);
+    lines.push(`  docs scanned ${report.filesScanned}`);
+    if (report.findings.length === 0) {
+        lines.push('');
+        lines.push('No contradictions found.');
+        return lines.join('\n');
+    }
+    const grouped = new Map();
+    for (const f of report.findings) {
+        const arr = grouped.get(f.kind) ?? [];
+        arr.push(f);
+        grouped.set(f.kind, arr);
+    }
+    for (const [kind, arr] of grouped) {
+        lines.push('');
+        lines.push(`${kind} (${arr.length}):`);
+        for (const f of arr.slice(0, 20)) {
+            const loc = f.line ? `${f.source}:${f.line}` : f.source;
+            lines.push(`  - [${f.severity}] ${loc} — ${f.message}`);
+            if (f.suggestion)
+                lines.push(`      suggestion: ${f.suggestion}`);
+        }
+        if (arr.length > 20)
+            lines.push(`  ... ${arr.length - 20} more`);
+    }
+    if (report.limitations.length > 0) {
+        lines.push('');
+        lines.push('Limitations:');
+        for (const l of report.limitations)
+            lines.push(`  - ${l}`);
+    }
+    return lines.join('\n');
+}
+export function renderContradictionReportMarkdown(report) {
+    const lines = [];
+    lines.push('# Contradictions report');
+    lines.push('');
+    lines.push(`- Findings: **${report.findings.length}**`);
+    lines.push(`- Docs scanned: **${report.filesScanned}**`);
+    if (report.findings.length === 0) {
+        lines.push('');
+        lines.push('_No contradictions found._');
+        return lines.join('\n');
+    }
+    lines.push('');
+    lines.push('## Findings');
+    lines.push('');
+    lines.push('| Severity | Kind | Source | Reference | Message | Suggestion |');
+    lines.push('|---|---|---|---|---|---|');
+    for (const f of report.findings) {
+        const loc = f.line ? `${f.source}:${f.line}` : f.source;
+        lines.push(`| ${f.severity} | ${f.kind} | \`${loc}\` | \`${f.reference}\` | ${f.message} | ${f.suggestion ?? '-'} |`);
+    }
+    if (report.limitations.length > 0) {
+        lines.push('');
+        lines.push('## Limitations');
+        lines.push('');
+        for (const l of report.limitations)
+            lines.push(`- ${l}`);
+    }
+    return lines.join('\n');
+}
+export function renderContradictionReportHtml(report) {
+    const rows = report.findings
+        .map((f) => `<tr><td>${f.severity}</td><td>${f.kind}</td><td><code>${esc(f.source)}${f.line ? `:${f.line}` : ''}</code></td><td><code>${esc(f.reference)}</code></td><td>${esc(f.message)}</td><td>${esc(f.suggestion ?? '')}</td></tr>`)
+        .join('\n');
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Contradictions</title><style>body{font-family:system-ui;max-width:920px;margin:32px auto;padding:0 16px}table{width:100%;border-collapse:collapse}th,td{border:1px solid #ddd;padding:6px;font-size:13px;text-align:left}th{background:#f6f6f6}code{font-size:12px}</style></head><body><h1>Contradictions report</h1><p>Findings: <strong>${report.findings.length}</strong> · Docs scanned: <strong>${report.filesScanned}</strong></p><table><thead><tr><th>Severity</th><th>Kind</th><th>Source</th><th>Reference</th><th>Message</th><th>Suggestion</th></tr></thead><tbody>${rows}</tbody></table></body></html>`;
+}
+function esc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function renderContradictionReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}

package/dist/convention-registry.d.ts

@@ -0,0 +1,44 @@
+import { type IConvention } from '@shrkcrft/plugin-api';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const CONVENTION_REGISTRY_SCHEMA = "sharkcraft.convention-registry/v1";
+export declare enum ConventionSource {
+    Local = "local",
+    Pack = "pack",
+    Fixture = "fixture"
+}
+export interface IConventionEntry {
+    readonly convention: IConvention;
+    readonly source: ConventionSource;
+    readonly packageName?: string;
+    readonly sourceFile: string;
+}
+export interface IConventionDoctorIssue {
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly conventionId?: string;
+    readonly source?: string;
+}
+export declare function loadConventions(inspection: ISharkcraftInspection): Promise<{
+    entries: readonly IConventionEntry[];
+    issues: readonly IConventionDoctorIssue[];
+}>;
+export declare function listConventions(inspection: ISharkcraftInspection): Promise<readonly IConventionEntry[]>;
+export declare function findConvention(inspection: ISharkcraftInspection, id: string): Promise<IConventionEntry | null>;
+export declare function listConventionIssues(inspection: ISharkcraftInspection): Promise<readonly IConventionDoctorIssue[]>;
+export interface IConventionCheckHit {
+    readonly conventionId: string;
+    readonly ruleId: string;
+    readonly file: string;
+    readonly line?: number;
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly message: string;
+}
+export interface IConventionCheckReport {
+    readonly schema: 'sharkcraft.convention-check/v1';
+    readonly filesScanned: number;
+    readonly hits: readonly IConventionCheckHit[];
+    readonly verdict: 'clean' | 'has-violations';
+}
+export declare function checkConventionsAgainstFiles(inspection: ISharkcraftInspection, files: readonly string[]): Promise<IConventionCheckReport>;
+//# sourceMappingURL=convention-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"convention-registry.d.ts","sourceRoot":"","sources":["../src/convention-registry.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,oBAAY,gBAAgB;IAC1B,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AA4BD,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAA;CAAE,CAAC,CAoF9F;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAGtC;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,qBAAqB,EACjC,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAGlC;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAG5C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,gCAAgC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAAC;CAC9C;AAiBD,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,OAAO,CAAC,sBAAsB,CAAC,CAqCjC"}

package/dist/convention-registry.js

@@ -0,0 +1,195 @@
+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;
+};
+/**
+ * Convention registry. Loads pack + local conventions and validates
+ * them. Engine has no built-in conventions; everything comes from
+ * contributions.
+ */
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { validateConvention, } from '@shrkcrft/plugin-api';
+export const CONVENTION_REGISTRY_SCHEMA = 'sharkcraft.convention-registry/v1';
+export var ConventionSource;
+(function (ConventionSource) {
+    ConventionSource["Local"] = "local";
+    ConventionSource["Pack"] = "pack";
+    ConventionSource["Fixture"] = "fixture";
+})(ConventionSource || (ConventionSource = {}));
+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.conventions))
+        return mod.conventions;
+    return [];
+}
+function localFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    for (const name of ['conventions.ts', 'conventions/index.ts']) {
+        const abs = nodePath.join(dir, name);
+        if (existsSync(abs))
+            out.push(abs);
+    }
+    const cfg = inspection.config;
+    for (const rel of cfg?.conventionFiles ?? []) {
+        out.push(nodePath.isAbsolute(rel) ? rel : nodePath.join(dir, rel));
+    }
+    return out;
+}
+export async function loadConventions(inspection) {
+    const entries = [];
+    const issues = [];
+    const seen = new Set();
+    const ingest = (raw, source, packageName, sourceFile) => {
+        const v = validateConvention(raw);
+        if (!v.valid) {
+            for (const i of v.issues) {
+                issues.push({
+                    severity: 'error',
+                    code: 'invalid-convention',
+                    message: `${i.field}: ${i.message}`,
+                    conventionId: typeof raw.id === 'string' ? raw.id : undefined,
+                    source: sourceFile,
+                });
+            }
+            return;
+        }
+        if (seen.has(raw.id)) {
+            issues.push({
+                severity: 'error',
+                code: 'duplicate-id',
+                message: `Convention "${raw.id}" already loaded; skipping ${sourceFile}.`,
+                conventionId: raw.id,
+                source: sourceFile,
+            });
+            return;
+        }
+        seen.add(raw.id);
+        entries.push({
+            convention: 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 c of list)
+                ingest(c, ConventionSource.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.conventionFiles ?? []) {
+            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 c of list)
+                    ingest(c, ConventionSource.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 listConventions(inspection) {
+    const { entries } = await loadConventions(inspection);
+    return entries;
+}
+export async function findConvention(inspection, id) {
+    const entries = await listConventions(inspection);
+    return entries.find((e) => e.convention.id === id) ?? null;
+}
+export async function listConventionIssues(inspection) {
+    const { issues } = await loadConventions(inspection);
+    return issues;
+}
+function globMatch(file, pattern) {
+    // very small POSIX-style matcher: ** = any path, * = any segment chars
+    const re = new RegExp('^' +
+        pattern
+            .replace(/[.+^$()|]/g, (m) => '\\' + m)
+            .replace(/\*\*/g, '__DOUBLE__')
+            .replace(/\*/g, '[^/]*')
+            .replace(/__DOUBLE__/g, '.*')
+            .replace(/\?/g, '.') +
+        '$');
+    return re.test(file);
+}
+export async function checkConventionsAgainstFiles(inspection, files) {
+    const entries = await listConventions(inspection);
+    const hits = [];
+    for (const f of files) {
+        for (const entry of entries) {
+            const c = entry.convention;
+            const globs = c.appliesTo?.fileGlobs ?? [];
+            if (globs.length > 0 && !globs.some((g) => globMatch(f, g)))
+                continue;
+            for (const r of c.rules) {
+                const sev = r.severity ?? c.severity;
+                if (r.filePattern && !new RegExp(r.filePattern).test(f)) {
+                    hits.push({
+                        conventionId: c.id,
+                        ruleId: r.id,
+                        file: f,
+                        severity: sev,
+                        message: `File "${f}" does not match convention "${c.id}" rule "${r.id}": ${r.description}`,
+                    });
+                }
+                if (r.forbidMatch && new RegExp(r.forbidMatch).test(f)) {
+                    hits.push({
+                        conventionId: c.id,
+                        ruleId: r.id,
+                        file: f,
+                        severity: sev,
+                        message: `File "${f}" matches forbidden pattern from convention "${c.id}" rule "${r.id}": ${r.description}`,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        schema: 'sharkcraft.convention-check/v1',
+        filesScanned: files.length,
+        hits,
+        verdict: hits.some((h) => h.severity === 'error') ? 'has-violations' : 'clean',
+    };
+}

package/dist/coverage-report.d.ts

@@ -0,0 +1,25 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export interface ICoverageCategory {
+    id: string;
+    title: string;
+    total: number;
+    covered: number;
+    /** 0..100 percentage. */
+    score: number;
+    /** Detail lines for items missing coverage. */
+    missing: string[];
+}
+export interface ICoverageReport {
+    categories: ICoverageCategory[];
+    /** Overall average score (0..100). */
+    overall: number;
+    /** Free-form suggestions. */
+    suggestions: string[];
+}
+/**
+ * Deterministic coverage report. Different from AI-readiness — focuses on
+ * **relationships**: do entries link to each other in a way that lets an
+ * agent traverse the project intelligence?
+ */
+export declare function buildCoverageReport(inspection: ISharkcraftInspection): ICoverageReport;
+//# sourceMappingURL=coverage-report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-report.d.ts","sourceRoot":"","sources":["../src/coverage-report.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAOD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,CAiLtF"}