@shrkcrft/inspector 0.1.0-alpha.2

package/dist/repository-knowledge-model.js

@@ -0,0 +1,939 @@
+import * as nodePath from 'node:path';
+import { recommendPresets, } from '@shrkcrft/presets';
+import { PackageManager } from '@shrkcrft/workspace';
+import { buildOnboardingPlan, } from "./onboarding.js";
+import { buildAreaMap, } from "./area-map.js";
+import { listConstructs, loadConstructs } from "./construct-registry.js";
+import { analyzeImportGraph } from "./import-graph-analysis.js";
+import { buildGeneratedCodeReport, } from "./generated-code.js";
+import { buildContradictionReport, } from "./contradictions.js";
+import { buildStabilityMap, StabilityKind, } from "./stability-map.js";
+import { GeneratedScanDepth, } from "./generated-code.js";
+import { buildPolyglotBoundaryReport, computePolyglotTestImpact, detectLanguageProfiles, buildLanguageCommandReport, scanPolyglotDependencies, suggestLanguageBoundaries, LanguageId, } from "./languages/index.js";
+export const REPOSITORY_KNOWLEDGE_MODEL_SCHEMA = 'sharkcraft.repository-knowledge-model/v1';
+export var IngestDepth;
+(function (IngestDepth) {
+    IngestDepth["Shallow"] = "shallow";
+    IngestDepth["Standard"] = "standard";
+    IngestDepth["Deep"] = "deep";
+    IngestDepth["Extreme"] = "extreme";
+})(IngestDepth || (IngestDepth = {}));
+export var IngestSection;
+(function (IngestSection) {
+    IngestSection["RepositoryOverview"] = "repositoryOverview";
+    IngestSection["ArchitectureModel"] = "architectureModel";
+    IngestSection["BusinessLogicModel"] = "businessLogicModel";
+    IngestSection["RulesAndConventions"] = "rulesAndConventions";
+    IngestSection["DependencyBoundaries"] = "dependencyBoundaries";
+    IngestSection["DomainMap"] = "domainMap";
+    IngestSection["WorkflowMap"] = "workflowMap";
+    IngestSection["ChangeProtocol"] = "changeProtocol";
+    IngestSection["RiskAreas"] = "riskAreas";
+    IngestSection["Contradictions"] = "contradictions";
+    IngestSection["OpenQuestions"] = "openQuestions";
+    IngestSection["GeneratedVsHandwritten"] = "generatedVsHandwritten";
+    IngestSection["StableExperimentalDeprecated"] = "stableExperimentalDeprecated";
+    IngestSection["TaskContextHints"] = "taskContextHints";
+    IngestSection["RecommendedSharkCraftFiles"] = "recommendedSharkCraftFiles";
+})(IngestSection || (IngestSection = {}));
+export const ALL_INGEST_SECTIONS = Object.values(IngestSection);
+export async function buildRepositoryKnowledgeModel(options) {
+    const inspection = options.inspection;
+    const projectRoot = inspection.projectRoot;
+    const depth = options.depth ?? IngestDepth.Standard;
+    const requested = new Set(options.selectedSections && options.selectedSections.length > 0
+        ? options.selectedSections
+        : ALL_INGEST_SECTIONS);
+    for (const ex of options.excludedSections ?? [])
+        requested.delete(ex);
+    const sectionsArr = ALL_INGEST_SECTIONS.filter((s) => requested.has(s));
+    const limitations = [];
+    // 1) Onboarding plan (existing) — gives us rules/paths/templates/boundaries/pipelines.
+    let onboarding;
+    try {
+        onboarding = buildOnboardingPlan(inspection, {});
+    }
+    catch (err) {
+        limitations.push(`onboarding plan build failed: ${err.message}`);
+        onboarding = emptyOnboardingPlan(projectRoot);
+    }
+    // 2) Forced presets — slot them ahead of recommendations and mark transformational intent.
+    const recRaw = recommendPresets(inspection.presetRegistry.list(), {
+        profiles: inspection.workspace.profiles ?? [],
+        limit: 20,
+    });
+    const transformationalIntents = [];
+    const presets = applyForcedPresets(recRaw, options.forcedPresetIds ?? [], inspection, transformationalIntents);
+    // 3) Architecture model.
+    const areaMap = buildAreaMap(inspection);
+    let importGraph;
+    if (depth !== IngestDepth.Shallow) {
+        try {
+            importGraph = analyzeImportGraph(projectRoot);
+        }
+        catch (err) {
+            limitations.push(`import graph analysis failed: ${err.message}`);
+        }
+    }
+    const architectureModel = buildArchitectureModel(inspection, areaMap, importGraph);
+    // 4) Business logic.
+    let constructs = listConstructs(inspection);
+    if (constructs.length === 0) {
+        try {
+            constructs = await loadConstructs(inspection);
+        }
+        catch (err) {
+            limitations.push(`construct load failed: ${err.message}`);
+        }
+    }
+    const businessLogicModel = buildBusinessLogicModel(inspection, constructs, areaMap);
+    // 5) Generated-code + stability + contradictions.
+    // Depth-aware generated-code scan + annotation-aware stability map.
+    let generatedDepth = GeneratedScanDepth.Standard;
+    if (depth === IngestDepth.Deep)
+        generatedDepth = GeneratedScanDepth.Deep;
+    if (depth === IngestDepth.Extreme)
+        generatedDepth = GeneratedScanDepth.Extreme;
+    const generatedReport = buildGeneratedCodeReport({ inspection, depth: generatedDepth });
+    const scanAnnotations = depth === IngestDepth.Deep || depth === IngestDepth.Extreme;
+    const annotationScanLimit = depth === IngestDepth.Extreme ? 5000 : 1500;
+    const stabilityMap = buildStabilityMap({
+        inspection,
+        areaMap,
+        importGraph,
+        generatedRoots: generatedReport.generatedRoots.map((r) => r.path),
+        scanAnnotations,
+        annotationScanLimit,
+    });
+    const contradictions = buildContradictionReport({ inspection });
+    // Language-aware sections. Detect language profiles once and reuse
+    // the result everywhere it is needed; on shallow/standard depth only
+    // profiles + commands are surfaced (cheap). Deep/extreme add the polyglot
+    // dependency summary, boundary report, suggestions and test-impact.
+    let languageProfiles;
+    let languageCommands;
+    let polyglotDependencySummary;
+    let polyglotTestImpactSummary;
+    let languageBoundarySuggestions;
+    let polyglotBoundaryReport;
+    let languageRiskNotes;
+    let languageGeneratedCodeSignals;
+    let languageStabilitySignals;
+    try {
+        languageProfiles = detectLanguageProfiles(projectRoot);
+        languageCommands = buildLanguageCommandReport(projectRoot, languageProfiles);
+        // Polyglot risk notes — extracted from each profile.
+        const polyglotLangs = languageProfiles.profiles.filter((p) => p.language !== LanguageId.TypeScript && p.language !== LanguageId.JavaScript);
+        languageRiskNotes = [];
+        for (const p of languageProfiles.profiles) {
+            for (const note of p.riskNotes) {
+                languageRiskNotes.push({ language: p.language, note });
+            }
+        }
+        if (polyglotLangs.length > 0 && (depth === IngestDepth.Deep || depth === IngestDepth.Extreme)) {
+            polyglotDependencySummary = scanPolyglotDependencies(projectRoot, {
+                languages: polyglotLangs.map((p) => p.language),
+            });
+            try {
+                polyglotBoundaryReport = buildPolyglotBoundaryReport({
+                    projectRoot,
+                    cached: languageProfiles,
+                    graph: polyglotDependencySummary,
+                });
+            }
+            catch (err) {
+                limitations.push(`polyglot boundary build failed: ${err.message}`);
+            }
+            try {
+                languageBoundarySuggestions = suggestLanguageBoundaries(projectRoot);
+            }
+            catch (err) {
+                limitations.push(`language boundary suggestions failed: ${err.message}`);
+            }
+            // Test impact uses an empty file list at the model build site — callers
+            // pass concrete files via `shrk understand-task`. We still surface the
+            // shape so downstream renderers know the language has impact data.
+            try {
+                polyglotTestImpactSummary = computePolyglotTestImpact(projectRoot, []);
+            }
+            catch (err) {
+                limitations.push(`polyglot test impact failed: ${err.message}`);
+            }
+        }
+        // Tag generated-code roots by language for the new section.
+        languageGeneratedCodeSignals = [];
+        for (const root of generatedReport.generatedRoots) {
+            let lang = 'unknown';
+            if (root.kind === 'java-generated')
+                lang = LanguageId.Java;
+            else if (root.kind === 'csharp-generated')
+                lang = LanguageId.CSharp;
+            else if (root.kind === 'python-generated')
+                lang = LanguageId.Python;
+            else if (root.kind === 'go-generated')
+                lang = LanguageId.Go;
+            else if (root.kind === 'rust-generated')
+                lang = LanguageId.Rust;
+            else if (root.kind === 'angular-environment' || root.kind === 'angular-router')
+                lang = LanguageId.TypeScript;
+            else if (root.kind === 'prisma-client')
+                lang = LanguageId.TypeScript;
+            else if (root.kind === 'openapi' || root.kind === 'graphql')
+                lang = 'multi';
+            if (lang !== 'unknown') {
+                languageGeneratedCodeSignals.push({ language: lang, signal: root.reason, paths: [root.path] });
+            }
+        }
+        // Tag stability areas by language guess (uses file-extension priors).
+        languageStabilitySignals = [];
+        for (const area of stabilityMap.areas) {
+            const langs = new Set();
+            for (const f of inspection.sourceFiles) {
+                if (!f.startsWith(area.path + '/') && f !== area.path)
+                    continue;
+                const ext = nodePath.extname(f).toLowerCase();
+                if (ext === '.ts' || ext === '.tsx')
+                    langs.add(LanguageId.TypeScript);
+                else if (ext === '.js' || ext === '.jsx')
+                    langs.add(LanguageId.JavaScript);
+                else if (ext === '.java')
+                    langs.add(LanguageId.Java);
+                else if (ext === '.cs')
+                    langs.add(LanguageId.CSharp);
+                else if (ext === '.py')
+                    langs.add(LanguageId.Python);
+                else if (ext === '.go')
+                    langs.add(LanguageId.Go);
+                else if (ext === '.rs')
+                    langs.add(LanguageId.Rust);
+            }
+            for (const l of langs) {
+                languageStabilitySignals.push({ language: l, kind: area.kind, paths: [area.path] });
+            }
+        }
+    }
+    catch (err) {
+        limitations.push(`language profiling failed: ${err.message}`);
+    }
+    // 6) Risk areas — high-fan-in or explicitly risky paths.
+    const riskAreas = buildRiskAreas(inspection, stabilityMap, importGraph);
+    // 7) Domain map.
+    const domainMap = {
+        areas: areaMap.areas.map((a) => ({
+            id: a.id,
+            paths: a.paths,
+            kind: a.kind,
+            fileCount: a.fileCount,
+        })),
+        constructs: constructs.map((c) => ({
+            id: c.id,
+            title: c.title,
+            paths: deriveConstructPaths(c),
+        })),
+    };
+    // 8) Workflow map — pulled from package scripts + pipelines + docs hints.
+    const workflowMap = buildWorkflowMap(inspection, onboarding);
+    // 9) Change protocol — built from rules + boundary fixes + safe-codegen.
+    const changeProtocol = buildChangeProtocol(inspection, onboarding);
+    // 10) Task context hints + open questions.
+    const taskContextHints = buildTaskContextHints(inspection, onboarding, generatedReport, contradictions, stabilityMap, options.task);
+    const openQuestions = buildOpenQuestions(onboarding, contradictions, generatedReport, stabilityMap);
+    // 11) Recommended SharkCraft files.
+    const recommendedSharkCraftFiles = buildRecommendedFiles({
+        onboarding,
+        generatedReport,
+        stabilityMap,
+        contradictions,
+        businessLogicModel,
+        domainMap,
+    });
+    // 12) Confidence.
+    const confidence = computeConfidence({
+        inspection,
+        onboarding,
+        generatedReport,
+        contradictions,
+        stabilityMap,
+        importGraph,
+        docsScanned: contradictions.filesScanned,
+    });
+    // 13) Repository overview.
+    const repositoryOverview = {
+        projectName: inspection.workspace.packageName ?? 'unknown-project',
+        ...(inspection.workspace.description ? { description: inspection.workspace.description } : {}),
+        packageManager: inspection.workspace.packageManager.manager,
+        frameworks: inspection.workspace.frameworks.map((f) => f.name),
+        topLevelDirs: inspection.workspace.topLevelDirs,
+        knownScripts: Object.keys(inspection.workspace.scripts ?? {}),
+        hasSharkcraftFolder: inspection.hasSharkcraftFolder,
+        monorepo: detectMonorepo(inspection),
+        detectedLanguages: detectLanguages(inspection),
+    };
+    return {
+        schema: REPOSITORY_KNOWLEDGE_MODEL_SCHEMA,
+        projectRoot,
+        depth,
+        presets,
+        forcedPresetIds: options.forcedPresetIds ?? [],
+        transformationalIntents,
+        selectedSections: sectionsArr,
+        repositoryOverview,
+        ...(languageProfiles ? { languageProfiles } : {}),
+        ...(languageCommands ? { languageCommands } : {}),
+        ...(polyglotDependencySummary ? { polyglotDependencySummary } : {}),
+        ...(polyglotTestImpactSummary ? { polyglotTestImpactSummary } : {}),
+        ...(languageBoundarySuggestions ? { languageBoundarySuggestions } : {}),
+        ...(polyglotBoundaryReport ? { polyglotBoundaryReport } : {}),
+        ...(languageRiskNotes ? { languageRiskNotes } : {}),
+        ...(languageGeneratedCodeSignals ? { languageGeneratedCodeSignals } : {}),
+        ...(languageStabilitySignals ? { languageStabilitySignals } : {}),
+        architectureModel,
+        businessLogicModel,
+        rulesAndConventions: {
+            rules: onboarding.inferredRules,
+            paths: onboarding.inferredPathConventions,
+            verificationCommands: onboarding.inferredVerificationCommands,
+        },
+        dependencyBoundaries: {
+            rules: onboarding.inferredBoundaryRules,
+            importGraphSummary: {
+                nodeCount: importGraph?.filesScanned ?? 0,
+                edgeCount: importGraph?.packageCount ?? 0,
+                cycles: (importGraph?.cycles ?? []).map((c) => c.nodes.join(' → ')),
+            },
+        },
+        domainMap,
+        workflowMap,
+        changeProtocol,
+        riskAreas,
+        contradictions,
+        openQuestions,
+        generatedVsHandwritten: generatedReport,
+        stableExperimentalDeprecated: stabilityMap,
+        taskContextHints,
+        recommendedSharkCraftFiles,
+        inferredPipelines: onboarding.inferredPipelines,
+        inferredTemplates: onboarding.inferredTemplateCandidates,
+        confidence,
+        limitations,
+        generatedAt: new Date().toISOString(),
+    };
+}
+function emptyOnboardingPlan(projectRoot) {
+    return {
+        projectSummary: {
+            projectRoot,
+            packageManager: PackageManager.Unknown,
+            profiles: [],
+            hasSharkcraftFolder: false,
+        },
+        recommendedPresets: [],
+        suggestedFiles: [],
+        inferredPathConventions: [],
+        inferredVerificationCommands: [],
+        inferredBoundaryRules: [],
+        inferredTemplateCandidates: [],
+        inferredRules: [],
+        inferredPipelines: [],
+        detectedInstructionFiles: [],
+        risks: [],
+        nextCommands: [],
+        readiness: {
+            current: 'poor',
+            expected: 'poor',
+            currentScore: 0,
+            expectedScore: 0,
+            topImprovements: [],
+        },
+        monorepoSummary: null,
+    };
+}
+function applyForcedPresets(raw, forced, inspection, transformationalIntents) {
+    if (forced.length === 0)
+        return raw;
+    const workspaceProfiles = new Set(inspection.workspace.profiles ?? []);
+    const byId = new Map(raw.map((r) => [r.preset.id, r]));
+    const out = [];
+    for (const id of forced) {
+        const found = byId.get(id);
+        if (found) {
+            out.push(found);
+            byId.delete(id);
+            // Even if the preset appears in the recommendation list, treat it as
+            // transformational intent when its `appliesTo` profiles do not overlap
+            // with the workspace's detected profiles.
+            const requirements = found.preset.appliesTo ?? [];
+            const matches = requirements.filter((p) => workspaceProfiles.has(p));
+            if (requirements.length > 0 && matches.length === 0) {
+                transformationalIntents.push(`forced preset "${id}" does not match repo profile yet — treat as adaptation guidance`);
+            }
+            continue;
+        }
+        const preset = inspection.presetRegistry.get(id);
+        if (preset) {
+            out.push({
+                preset,
+                score: 0,
+                confidence: 'low',
+                reasons: ['Forced preset — repo signals do not match yet (transformational intent).'],
+            });
+            transformationalIntents.push(`forced preset "${id}" does not match repo profile yet — treat as adaptation guidance`);
+        }
+        else {
+            transformationalIntents.push(`unknown forced preset "${id}" — ignored`);
+        }
+    }
+    for (const remaining of byId.values())
+        out.push(remaining);
+    return out;
+}
+function buildArchitectureModel(inspection, areaMap, importGraph) {
+    const layers = areaMap.areas.map((a) => ({
+        id: a.id,
+        description: `Area "${a.id}" detected from ${a.paths.length} path(s).`,
+        paths: a.paths,
+        fileCount: a.fileCount,
+    }));
+    const publicApis = inspection.sourceFiles
+        .filter((f) => /(^|\/)src\/index\.(ts|tsx|js)$/.test(f) || /(^|\/)packages\/[^\/]+\/src\/index\.(ts|tsx)$/.test(f))
+        .map((f) => nodePath.dirname(f));
+    const notes = [];
+    if (importGraph && importGraph.cycles.length > 0) {
+        notes.push(`${importGraph.cycles.length} import cycle(s) detected; review before layering changes.`);
+    }
+    return { layers, publicApis, notes };
+}
+function buildBusinessLogicModel(inspection, constructs, _areaMap) {
+    const entities = constructs
+        .filter((c) => /entity|model|domain|value-object|record/i.test(c.type) || hasFacetKindLike(c, /entity|model|domain/))
+        .map((c) => ({
+        id: c.id,
+        title: c.title,
+        source: 'construct',
+        summary: c.description ?? c.title,
+        paths: deriveConstructPaths(c),
+        relatedWorkflows: [],
+    }));
+    const workflows = constructs
+        .filter((c) => /workflow|service|pipeline|playbook|use-?case|saga|flow/i.test(c.type) || hasFacetKindLike(c, /workflow|service|pipeline|playbook|usecase/))
+        .map((c) => ({
+        id: c.id,
+        title: c.title,
+        source: 'construct',
+        summary: c.description ?? c.title,
+        paths: deriveConstructPaths(c),
+        relatedWorkflows: [],
+    }));
+    const invariants = [];
+    // Infer some invariants from package.json + frameworks.
+    if (inspection.workspace.frameworks.some((f) => /angular/i.test(f.name))) {
+        invariants.push('Components/services follow Angular DI — do not instantiate services directly outside the injector.');
+    }
+    if (inspection.workspace.hasTypeScript) {
+        invariants.push('TypeScript strict mode is the contract — no any in public surfaces.');
+    }
+    if (inspection.workspace.frameworks.some((f) => /nx/i.test(f.name))) {
+        invariants.push('Nx project boundaries are enforced — verify tags/scope before adding cross-project imports.');
+    }
+    return { entities, workflows, invariants };
+}
+function buildWorkflowMap(inspection, onboarding) {
+    const workflows = [];
+    // Package scripts.
+    for (const [name, cmd] of Object.entries(inspection.workspace.scripts ?? {})) {
+        workflows.push({
+            id: `script:${name}`,
+            title: name,
+            source: 'scripts',
+            steps: [cmd],
+        });
+    }
+    // Inferred pipelines.
+    for (const p of onboarding.inferredPipelines) {
+        workflows.push({
+            id: `pipeline:${p.id}`,
+            title: p.title,
+            source: 'inferred',
+            steps: p.steps,
+        });
+    }
+    return { workflows };
+}
+function buildChangeProtocol(inspection, onboarding) {
+    const entries = [];
+    entries.push({
+        id: 'change-protocol.feature',
+        title: 'Add a feature',
+        steps: [
+            'Read relevant rules + path conventions (`shrk context --task "<task>"`).',
+            'If a template exists for the construct, run `shrk gen <id> <name> --dry-run --save-plan`.',
+            'Review the plan (`shrk plan review`).',
+            'Apply with `shrk apply <plan> --verify-signature --validate`.',
+            'Run verification commands listed in the task packet.',
+        ],
+        recommendedCommands: ['shrk task', 'shrk gen', 'shrk plan review', 'shrk apply'],
+    });
+    entries.push({
+        id: 'change-protocol.refactor',
+        title: 'Refactor existing code',
+        steps: [
+            'Map impact via `shrk impact <path>`.',
+            'Check boundaries with `shrk check boundaries`.',
+            'Plan + dry-run, then apply.',
+            'Re-run tests + boundary check after.',
+        ],
+        recommendedCommands: ['shrk impact', 'shrk check boundaries', 'shrk gen', 'shrk apply'],
+    });
+    entries.push({
+        id: 'change-protocol.public-api',
+        title: 'Change a public API',
+        steps: [
+            'Verify export barrels (`packages/*/src/index.ts`).',
+            'Look up consumers via `shrk api report` and `shrk impact`.',
+            'Document the change in a decision record (`shrk decisions new`).',
+            'Run release-readiness + boundary checks.',
+        ],
+        recommendedCommands: ['shrk api report', 'shrk impact', 'shrk decisions new', 'shrk release readiness'],
+    });
+    if (inspection.workspace.frameworks.some((f) => /angular/i.test(f.name))) {
+        entries.push({
+            id: 'change-protocol.angular-component',
+            title: 'Add an Angular component / directive / service',
+            steps: [
+                'Run `shrk context --task "add angular <kind>"` to pick up Modern Angular rules.',
+                'Use signals or RxJS deliberately — do not mirror them.',
+                'Avoid deep imports across libraries.',
+                'Add tests under the same library; respect Nx tags / boundaries.',
+            ],
+            recommendedCommands: ['shrk context', 'shrk gen', 'shrk check boundaries'],
+        });
+    }
+    void onboarding;
+    return { entries };
+}
+function buildTaskContextHints(inspection, _onboarding, generatedReport, contradictions, stabilityMap, task) {
+    const hints = [];
+    hints.push({
+        trigger: 'before any task',
+        hint: 'Run `shrk understand-task "<task>"` to load relevant rules, paths, risks and recommended commands.',
+        recommendedCommand: 'shrk understand-task "<task>"',
+    });
+    hints.push({
+        trigger: 'when changing files',
+        hint: 'Run `shrk validate-change --staged` to detect missing tests, broken boundaries, and policy gates before submitting.',
+        recommendedCommand: 'shrk validate-change --staged',
+    });
+    if (generatedReport.generatedRoots.length > 0) {
+        hints.push({
+            trigger: 'when a task touches a generated root',
+            hint: `Generated roots detected (${generatedReport.generatedRoots.length}). Edit generator inputs, not the generated output.`,
+            recommendedCommand: 'shrk generated report',
+        });
+    }
+    if (stabilityMap.byKind[StabilityKind.Deprecated].length > 0 || stabilityMap.byKind[StabilityKind.Legacy].length > 0) {
+        hints.push({
+            trigger: 'when a task lands in deprecated/legacy areas',
+            hint: 'Deprecated or legacy areas exist — prefer the stable replacement when adding new code.',
+            recommendedCommand: 'shrk stability map',
+        });
+    }
+    if (contradictions.findings.length > 0) {
+        hints.push({
+            trigger: 'when documentation seems wrong',
+            hint: `${contradictions.findings.length} doc/code contradictions detected. Verify the doc before trusting it.`,
+            recommendedCommand: 'shrk contradictions',
+        });
+    }
+    if (task && /angular/i.test(task)) {
+        hints.push({
+            trigger: 'angular work',
+            hint: 'Use Modern Angular preset rules (signals/RxJS discipline, standalone components, OnPush).',
+            recommendedCommand: 'shrk presets get modern-angular',
+        });
+    }
+    if (inspection.workspace.hasTypeScript) {
+        hints.push({
+            trigger: 'before public API changes',
+            hint: 'Strict TypeScript: avoid any/unsafe assertions; prefer satisfies and discriminated unions.',
+            recommendedCommand: 'shrk presets get strict-typescript',
+        });
+    }
+    return hints;
+}
+function buildOpenQuestions(onboarding, contradictions, generatedReport, stabilityMap) {
+    const questions = [];
+    for (const r of onboarding.risks)
+        questions.push(`Onboarding risk — ${r}`);
+    if (contradictions.findings.length > 0) {
+        questions.push(`Resolve ${contradictions.findings.length} doc/code contradictions before relying on docs as authoritative.`);
+    }
+    if (generatedReport.generatedRoots.length === 0) {
+        questions.push('No generated roots were detected — is everything truly hand-written, or are markers missing?');
+    }
+    if (stabilityMap.byKind[StabilityKind.HighRisk].length > 0) {
+        questions.push(`${stabilityMap.byKind[StabilityKind.HighRisk].length} high-fan-in areas — confirm they are intentional.`);
+    }
+    return questions;
+}
+function buildRiskAreas(inspection, stabilityMap, importGraph) {
+    const out = [];
+    for (const area of stabilityMap.byKind[StabilityKind.HighRisk]) {
+        out.push({
+            id: `high-fan-in:${area.path}`,
+            path: area.path,
+            reason: area.note ?? 'High fan-in detected.',
+            recommendation: 'Add an explicit boundary or split the area before further large changes.',
+            score: 80,
+        });
+    }
+    for (const area of stabilityMap.byKind[StabilityKind.Deprecated]) {
+        out.push({
+            id: `deprecated:${area.path}`,
+            path: area.path,
+            reason: 'Folder marked deprecated.',
+            recommendation: 'Migrate consumers off and remove after deprecation window.',
+            score: 60,
+        });
+    }
+    void inspection;
+    void importGraph;
+    return out;
+}
+function deriveConstructPaths(c) {
+    const paths = [];
+    for (const file of c.files ?? [])
+        paths.push(file);
+    for (const api of c.publicApi ?? [])
+        paths.push(api);
+    for (const list of Object.values(c.facets ?? {})) {
+        for (const v of list) {
+            if (v.source && /[\\/.]/.test(v.source))
+                paths.push(v.source);
+        }
+    }
+    return Array.from(new Set(paths));
+}
+function hasFacetKindLike(c, re) {
+    for (const kind of Object.keys(c.facets ?? {})) {
+        if (re.test(kind))
+            return true;
+    }
+    return false;
+}
+function detectMonorepo(inspection) {
+    if (inspection.workspace.frameworks.some((f) => /nx|rush|lerna|turborepo|moon/i.test(f.name)))
+        return true;
+    if (inspection.workspace.topLevelDirs.includes('packages') && inspection.workspace.topLevelDirs.includes('apps'))
+        return true;
+    if (inspection.workspace.topLevelDirs.includes('packages'))
+        return true;
+    return false;
+}
+function detectLanguages(inspection) {
+    const langs = new Set();
+    if (inspection.workspace.hasTypeScript)
+        langs.add('typescript');
+    for (const f of inspection.sourceFiles) {
+        const ext = nodePath.extname(f).toLowerCase();
+        if (ext === '.ts' || ext === '.tsx')
+            langs.add('typescript');
+        if (ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs')
+            langs.add('javascript');
+        if (ext === '.py')
+            langs.add('python');
+        if (ext === '.go')
+            langs.add('go');
+        if (ext === '.rs')
+            langs.add('rust');
+        if (ext === '.java')
+            langs.add('java');
+        if (ext === '.kt')
+            langs.add('kotlin');
+        if (ext === '.cs')
+            langs.add('csharp');
+        if (ext === '.proto')
+            langs.add('protobuf');
+        if (ext === '.graphql' || ext === '.gql')
+            langs.add('graphql');
+    }
+    return Array.from(langs).sort();
+}
+function buildRecommendedFiles(input) {
+    const files = [];
+    files.push({
+        target: 'sharkcraft/knowledge.ts',
+        reason: 'Capture architecture/domain concepts and invariants surfaced by ingest.',
+        entries: [
+            ...input.businessLogicModel.entities.map((e) => ({
+                id: `concept.${e.id}`,
+                kind: 'knowledge-entry',
+                reason: `Domain entity surfaced from construct registry (${e.paths.length} path(s)).`,
+            })),
+            ...input.businessLogicModel.workflows.map((w) => ({
+                id: `workflow.${w.id}`,
+                kind: 'knowledge-entry',
+                reason: 'Workflow surfaced from construct registry.',
+            })),
+            ...input.businessLogicModel.invariants.map((inv, i) => ({
+                id: `invariant.${i}`,
+                kind: 'knowledge-entry',
+                reason: inv,
+            })),
+        ],
+    });
+    files.push({
+        target: 'sharkcraft/rules.ts',
+        reason: 'Persist inferred rules + preset-contributed rules as live SharkCraft rules.',
+        entries: input.onboarding.inferredRules.map((r) => ({
+            id: r.id,
+            kind: 'rule',
+            reason: r.reason,
+        })),
+    });
+    files.push({
+        target: 'sharkcraft/paths.ts',
+        reason: 'Persist inferred path conventions so the engine ranks correctly.',
+        entries: input.onboarding.inferredPathConventions.map((p) => ({
+            id: p.id,
+            kind: 'path',
+            reason: p.reason,
+        })),
+    });
+    files.push({
+        target: 'sharkcraft/boundaries.ts',
+        reason: 'Enforce dependency layers and forbid framework leaks.',
+        entries: input.onboarding.inferredBoundaryRules.map((b) => ({
+            id: b.id,
+            kind: 'boundary',
+            reason: b.reason,
+        })),
+    });
+    files.push({
+        target: 'sharkcraft/constructs.ts',
+        reason: 'Make discovered constructs first-class so templates/playbooks can reference them.',
+        entries: input.domainMap.constructs.map((c) => ({
+            id: c.id,
+            kind: 'construct',
+            reason: 'Construct discovered from source.',
+        })),
+    });
+    const policies = [];
+    if (input.generatedReport.recommendedPolicyRules.length > 0) {
+        for (const p of input.generatedReport.recommendedPolicyRules) {
+            policies.push({
+                id: p.suggestedId,
+                kind: 'policy',
+                reason: p.reason,
+            });
+        }
+    }
+    if (input.stabilityMap.byKind[StabilityKind.Deprecated].length > 0) {
+        policies.push({
+            id: 'policy.deprecated-readonly',
+            kind: 'policy',
+            reason: 'Deprecated areas should require explicit migration intent before being modified.',
+        });
+    }
+    files.push({
+        target: 'sharkcraft/policies.ts',
+        reason: 'Governance gates inferred from generated-code and stability signals.',
+        entries: policies,
+    });
+    files.push({
+        target: 'sharkcraft/playbooks.ts',
+        reason: 'Common development workflows (add feature / refactor / public-API change).',
+        entries: [
+            { id: 'add-feature', kind: 'playbook', reason: 'Standard add-feature flow.' },
+            { id: 'refactor', kind: 'playbook', reason: 'Refactor with impact + boundary checks.' },
+            { id: 'public-api-change', kind: 'playbook', reason: 'Gated public-API change flow.' },
+        ],
+    });
+    files.push({
+        target: 'sharkcraft/templates.ts',
+        reason: 'Safe, scaffold-pattern-backed templates inferred from siblings.',
+        entries: input.onboarding.inferredTemplateCandidates
+            .filter((t) => t.confidence !== 'low')
+            .map((t) => ({
+            id: t.id,
+            kind: 'template',
+            reason: t.reason,
+        })),
+    });
+    files.push({
+        target: 'sharkcraft/pipelines.ts',
+        reason: 'Inferred pipelines (context-only / feature-dev / unit-test / safe-refactor).',
+        entries: input.onboarding.inferredPipelines.map((p) => ({
+            id: p.id,
+            kind: 'pipeline',
+            reason: p.reason,
+        })),
+    });
+    files.push({
+        target: 'sharkcraft/presets.ts',
+        reason: 'Local preset bundle binding the chosen baseline presets.',
+        entries: [
+            { id: 'local.bundle', kind: 'preset', reason: 'Local preset bundle for this repo.' },
+        ],
+    });
+    return files;
+}
+function computeConfidence(input) {
+    const notes = [];
+    const perSection = {
+        [IngestSection.RepositoryOverview]: 90,
+        [IngestSection.ArchitectureModel]: input.importGraph ? 80 : 55,
+        [IngestSection.BusinessLogicModel]: input.inspection.sourceFiles.length > 0 ? 50 : 20,
+        [IngestSection.RulesAndConventions]: input.onboarding.inferredRules.length > 0 ? 75 : 30,
+        [IngestSection.DependencyBoundaries]: input.onboarding.inferredBoundaryRules.length > 0 ? 70 : 35,
+        [IngestSection.DomainMap]: 60,
+        [IngestSection.WorkflowMap]: 70,
+        [IngestSection.ChangeProtocol]: 80,
+        [IngestSection.RiskAreas]: input.stabilityMap.areas.length > 0 ? 65 : 30,
+        [IngestSection.Contradictions]: input.docsScanned > 0 ? 70 : 30,
+        [IngestSection.OpenQuestions]: 85,
+        [IngestSection.GeneratedVsHandwritten]: input.generatedReport.filesScanned > 0 ? 80 : 40,
+        [IngestSection.StableExperimentalDeprecated]: input.stabilityMap.areas.length > 0 ? 75 : 40,
+        [IngestSection.TaskContextHints]: 80,
+        [IngestSection.RecommendedSharkCraftFiles]: 85,
+    };
+    const values = Object.values(perSection);
+    const overall = Math.round(values.reduce((a, b) => a + b, 0) / values.length);
+    if (!input.importGraph)
+        notes.push('Import graph unavailable — architecture/risk numbers are heuristic only.');
+    if (input.docsScanned === 0)
+        notes.push('No docs scanned — contradiction detection is conservative.');
+    if (input.inspection.sourceFiles.length === 0)
+        notes.push('No source files visible — many sections fall back to onboarding inference only.');
+    return { overall, perSection, notes };
+}
+export function renderRepositoryKnowledgeModelText(model) {
+    const lines = [];
+    lines.push('=== Repository knowledge model ===');
+    lines.push(`  project       ${model.repositoryOverview.projectName}`);
+    lines.push(`  depth         ${model.depth}`);
+    lines.push(`  presets       ${model.presets.slice(0, 6).map((p) => p.preset.id).join(', ') || '(none)'}`);
+    if (model.transformationalIntents.length > 0) {
+        lines.push('');
+        lines.push('Transformational intents:');
+        for (const t of model.transformationalIntents)
+            lines.push(`  - ${t}`);
+    }
+    lines.push('');
+    lines.push('Sections:');
+    for (const s of model.selectedSections)
+        lines.push(`  • ${s}  (confidence ${model.confidence.perSection[s] ?? '-'})`);
+    lines.push('');
+    lines.push(`Risk areas: ${model.riskAreas.length}`);
+    lines.push(`Contradictions: ${model.contradictions.findings.length}`);
+    lines.push(`Generated roots: ${model.generatedVsHandwritten.generatedRoots.length}`);
+    lines.push(`Stability areas: ${model.stableExperimentalDeprecated.areas.length}`);
+    lines.push(`Open questions: ${model.openQuestions.length}`);
+    lines.push(`Confidence: ${model.confidence.overall}/100`);
+    if (model.languageProfiles && model.languageProfiles.profiles.length > 0) {
+        lines.push('');
+        lines.push(`Languages: ${model.languageProfiles.profiles.map((p) => `${p.language}(${p.fileCount})`).join(', ')}`);
+        if (model.polyglotBoundaryReport) {
+            lines.push(`Polyglot boundary violations: ${model.polyglotBoundaryReport.counts.violations} (errors=${model.polyglotBoundaryReport.counts.errors})`);
+        }
+    }
+    if (model.limitations.length > 0) {
+        lines.push('');
+        lines.push('Limitations:');
+        for (const l of model.limitations)
+            lines.push(`  - ${l}`);
+    }
+    return lines.join('\n');
+}
+export function renderRepositoryKnowledgeModelMarkdown(model) {
+    const lines = [];
+    lines.push(`# Repository knowledge model — ${model.repositoryOverview.projectName}`);
+    lines.push('');
+    lines.push(`- Depth: **${model.depth}**`);
+    lines.push(`- Generated at: ${model.generatedAt}`);
+    lines.push(`- Confidence: **${model.confidence.overall}/100**`);
+    if (model.transformationalIntents.length > 0) {
+        lines.push('');
+        lines.push('> Transformational intents:');
+        for (const t of model.transformationalIntents)
+            lines.push(`> - ${t}`);
+    }
+    lines.push('');
+    lines.push('## Selected sections');
+    lines.push('');
+    for (const s of model.selectedSections) {
+        lines.push(`- **${s}** — confidence ${model.confidence.perSection[s] ?? '-'}`);
+    }
+    lines.push('');
+    lines.push('## Risk areas');
+    lines.push('');
+    if (model.riskAreas.length === 0) {
+        lines.push('_None._');
+    }
+    else {
+        lines.push('| Path | Reason | Score |');
+        lines.push('|---|---|---|');
+        for (const r of model.riskAreas)
+            lines.push(`| \`${r.path}\` | ${r.reason} | ${r.score} |`);
+    }
+    lines.push('');
+    lines.push('## Recommended SharkCraft files');
+    lines.push('');
+    for (const f of model.recommendedSharkCraftFiles) {
+        lines.push(`### ${f.target}`);
+        lines.push('');
+        lines.push(f.reason);
+        lines.push('');
+        if (f.entries.length === 0) {
+            lines.push('_no entries_');
+        }
+        else {
+            lines.push('| Entry | Kind | Why this goes here |');
+            lines.push('|---|---|---|');
+            for (const e of f.entries)
+                lines.push(`| \`${e.id}\` | ${e.kind} | ${e.reason} |`);
+        }
+        lines.push('');
+    }
+    if (model.languageProfiles && model.languageProfiles.profiles.length > 0) {
+        lines.push('## Languages');
+        lines.push('');
+        lines.push('| Language | Files | Confidence | Build | Test framework(s) |');
+        lines.push('|---|---|---|---|---|');
+        for (const p of model.languageProfiles.profiles) {
+            lines.push(`| \`${p.language}\` | ${p.fileCount} | ${p.confidence} | ${p.buildTool ?? '-'} | ${p.testFrameworks.join(', ') || '-'} |`);
+        }
+        lines.push('');
+    }
+    if (model.polyglotBoundaryReport && model.polyglotBoundaryReport.counts.violations > 0) {
+        lines.push('## Polyglot boundary violations');
+        lines.push('');
+        lines.push('| Severity | Rule | From | Import |');
+        lines.push('|---|---|---|---|');
+        for (const v of model.polyglotBoundaryReport.violations.slice(0, 30)) {
+            lines.push(`| ${v.severity} | \`${v.ruleId}\` | \`${v.fromFile}\` | \`${v.importSpecifier}\` |`);
+        }
+        lines.push('');
+    }
+    if (model.openQuestions.length > 0) {
+        lines.push('## Open questions');
+        lines.push('');
+        for (const q of model.openQuestions)
+            lines.push(`- ${q}`);
+    }
+    if (model.limitations.length > 0) {
+        lines.push('');
+        lines.push('## Limitations');
+        lines.push('');
+        for (const l of model.limitations)
+            lines.push(`- ${l}`);
+    }
+    return lines.join('\n');
+}
+export function renderRepositoryKnowledgeModelJson(model) {
+    return JSON.stringify(model, null, 2);
+}
+export function renderRepositoryKnowledgeModelHtml(model) {
+    const md = renderRepositoryKnowledgeModelMarkdown(model);
+    const body = md.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Repository knowledge model</title><style>body{font-family:system-ui;max-width:960px;margin:32px auto;padding:0 16px}pre{white-space:pre-wrap}</style></head><body><pre>${body}</pre></body></html>`;
+}