@shrkcrft/inspector 0.1.0-alpha.2

package/dist/area-explore.js

@@ -0,0 +1,438 @@
+/**
+ * Workspace-aware "explore this directory".
+ *
+ * Answers "explain this *specific* directory" with one deterministic
+ * call. Built on top of `buildAreaMap` (whole-repo) and the registries
+ * already in `ISharkcraftInspection`.
+ *
+ * Output:
+ *   - inferred area kind + role,
+ *   - key modules (largest / construct-defining),
+ *   - related commands (from the command catalog the caller injects),
+ *   - related MCP tools (id proximity to area name),
+ *   - tests under the dir,
+ *   - boundary rules / path conventions that mention the dir,
+ *   - common edit risks (generated files, signed/sensitive files,
+ *     dist/ subdir, etc.).
+ *
+ * Pure-data; no execution.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { AreaKind, buildAreaMap } from "./area-map.js";
+export const AREA_EXPLORE_SCHEMA = 'sharkcraft.area-explore/v1';
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.sharkcraft',
+    'dist',
+    'build',
+    '.cache',
+    '.turbo',
+    '.nx',
+    'coverage',
+    '.next',
+]);
+function classifyFileKind(file) {
+    if (/\.(test|spec)\.[tj]sx?$/.test(file) || file.includes('/__tests__/'))
+        return 'test';
+    if (/\.md$/.test(file))
+        return 'doc';
+    if (/\/dist\/|\.d\.ts$|\.map$|\/generated\//.test(file))
+        return 'generated';
+    if (/^(package\.json|tsconfig\.json|tsconfig\.[a-z]+\.json|\.eslintrc|\.prettierrc|\.editorconfig|bun\.lockb)$/.test(file.split('/').pop() ?? ''))
+        return 'config';
+    if (/\.(ts|tsx|js|jsx|mjs|cjs|json)$/.test(file))
+        return 'source';
+    return 'other';
+}
+function walkLimited(root, base, maxFiles = 4000) {
+    const out = [];
+    const stack = [base];
+    while (stack.length > 0 && out.length < maxFiles) {
+        const rel = stack.pop();
+        const abs = nodePath.join(root, rel);
+        let entries;
+        try {
+            entries = readdirSync(abs);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (name.startsWith('.') && !['.github', '.gitlab'].includes(name))
+                continue;
+            if (IGNORE_DIRS.has(name))
+                continue;
+            const childRel = rel ? `${rel}/${name}` : name;
+            const childAbs = nodePath.join(root, childRel);
+            let stat;
+            try {
+                stat = statSync(childAbs);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                stack.push(childRel);
+            }
+            else if (stat.isFile()) {
+                out.push(childRel);
+            }
+        }
+    }
+    return out;
+}
+function inferKindForPath(relPath, areaMap) {
+    for (const a of areaMap.areas) {
+        if (a.paths.some((p) => relPath === p || relPath.startsWith(p + '/')))
+            return a.kind;
+    }
+    // fallback heuristics: match against AreaPatterns through area-map
+    if (/^packages\//.test(relPath) || /^apps\//.test(relPath)) {
+        if (/\/__tests__\//.test(relPath))
+            return AreaKind.Tests;
+    }
+    return AreaKind.Unknown;
+}
+function describeRole(relPath, kind) {
+    const segs = relPath.split('/');
+    if (relPath.startsWith('packages/cli/src/commands')) {
+        return 'CLI command handlers (one .command.ts per shrk subcommand).';
+    }
+    if (relPath.startsWith('packages/mcp-server/src/tools')) {
+        return 'MCP read-only tools (must never write).';
+    }
+    if (/^packages\/[a-z-]+\/src\/__tests__/.test(relPath)) {
+        return 'Unit tests for the parent package.';
+    }
+    if (/^packages\/[a-z-]+\/src$/.test(relPath)) {
+        return `Source root for package ${segs[1]}.`;
+    }
+    if (relPath === 'docs' || relPath.startsWith('docs/')) {
+        return 'Authoritative docs (per-feature; cross-linked from docs/overview.md).';
+    }
+    if (relPath === 'sharkcraft' || relPath.startsWith('sharkcraft/')) {
+        return 'Local SharkCraft registries (rules / paths / templates / pipelines / config).';
+    }
+    if (relPath === 'scripts' || relPath.startsWith('scripts/')) {
+        return 'Repo-level shell/TS scripts (release, publish, preflight).';
+    }
+    if (relPath.startsWith('examples/')) {
+        return 'Dogfood / fixture target packages.';
+    }
+    switch (kind) {
+        case AreaKind.Core:
+            return 'Core building blocks (Result, errors, ids) — lowest in the layer order.';
+        case AreaKind.Tests:
+            return 'Tests.';
+        case AreaKind.Docs:
+            return 'Documentation.';
+        case AreaKind.Generated:
+            return 'Generated output — do not hand-edit.';
+        case AreaKind.Adapter:
+            return 'Framework / runtime adapter glue.';
+        case AreaKind.Plugin:
+            return 'Plugin / pack code.';
+        default:
+            return `${kind} area.`;
+    }
+}
+function detectRisks(opts) {
+    const risks = [];
+    const hasTests = opts.files.some((f) => f.kind === 'test');
+    const hasGenerated = opts.files.some((f) => f.kind === 'generated');
+    if (opts.relPath.startsWith('packages/mcp-server/src/tools')) {
+        risks.push({
+            kind: 'mcp-tool-dir',
+            severity: 'warning',
+            message: 'MCP tools must remain read-only — never add file writes. Returning a next-command hint is fine.',
+        });
+    }
+    if (opts.relPath.startsWith('packages/cli/src/commands') ||
+        opts.relPath.startsWith('packages/generator/src')) {
+        risks.push({
+            kind: 'cli-write-path',
+            severity: 'info',
+            message: 'CLI is the only write path. Apply requires --verify-signature on signed plans; do not weaken this.',
+        });
+    }
+    if (opts.relPath.startsWith('packages/packs/')) {
+        risks.push({
+            kind: 'signed-asset',
+            severity: 'warning',
+            message: 'Pack manifests are HMAC-signed. Re-sign with `shrk packs sign` after changing pack assets.',
+        });
+    }
+    if (/sharkcraft-pack|sharkcraft\/pack/.test(opts.relPath)) {
+        risks.push({
+            kind: 'pack-contribution',
+            severity: 'info',
+            message: 'Pack-contributed assets must not introduce project-specific logic into the engine — keep the adapter/pack boundary clean.',
+        });
+    }
+    if (hasGenerated) {
+        risks.push({
+            kind: 'generated-files',
+            severity: 'info',
+            message: 'Contains generated files (dist/ / .d.ts / .map) — do not hand-edit; rebuild via `bun run build:dist`.',
+        });
+    }
+    if (!hasTests &&
+        opts.files.length > 5 &&
+        opts.relPath.startsWith('packages/') &&
+        !opts.relPath.startsWith('packages/shared')) {
+        risks.push({
+            kind: 'no-tests',
+            severity: 'warning',
+            message: 'No tests detected in this directory — add one before extending public surface.',
+        });
+    }
+    return risks;
+}
+function commandRelevance(command, area) {
+    const tokens = area.toLowerCase().split(/[/\-_.]/).filter((t) => t.length >= 3);
+    let score = 0;
+    for (const t of tokens) {
+        if (command.toLowerCase().includes(t))
+            score += 1;
+    }
+    return score;
+}
+export function exploreArea(input) {
+    const root = input.inspection.projectRoot;
+    const rawPath = input.path;
+    const absPath = nodePath.isAbsolute(rawPath) ? rawPath : nodePath.resolve(root, rawPath);
+    const relPath = nodePath.relative(root, absPath).split(nodePath.sep).join('/');
+    const exists = existsSync(absPath);
+    if (!exists) {
+        return {
+            schema: AREA_EXPLORE_SCHEMA,
+            projectRoot: root,
+            path: rawPath,
+            resolvedPath: relPath,
+            exists: false,
+            inferredKind: AreaKind.Unknown,
+            role: `Path does not exist: ${relPath}`,
+            fileCount: 0,
+            testCount: 0,
+            keyFiles: [],
+            relatedCommands: [],
+            relatedMcpTools: [],
+            relatedTemplates: [],
+            relatedPipelines: [],
+            boundaryRuleIds: [],
+            pathConventionIds: [],
+            risks: [],
+            nextCommands: [`shrk map  # repo-wide map`],
+        };
+    }
+    const stat = statSync(absPath);
+    const isDir = stat.isDirectory();
+    const files = [];
+    if (isDir) {
+        const rels = walkLimited(root, relPath || '.');
+        for (const r of rels) {
+            let st;
+            try {
+                st = statSync(nodePath.join(root, r));
+            }
+            catch {
+                continue;
+            }
+            files.push({ relPath: r, sizeBytes: st.size, kind: classifyFileKind(r) });
+        }
+    }
+    else {
+        files.push({
+            relPath,
+            sizeBytes: stat.size,
+            kind: classifyFileKind(relPath),
+        });
+    }
+    files.sort((a, b) => b.sizeBytes - a.sizeBytes);
+    const areaMap = buildAreaMap(input.inspection);
+    const inferredKind = inferKindForPath(relPath, areaMap);
+    const role = describeRole(relPath, inferredKind);
+    const topFiles = input.topFiles ?? 10;
+    const keyFiles = files
+        .filter((f) => f.kind === 'source' || f.kind === 'config')
+        .slice(0, topFiles);
+    // Related commands by token overlap.
+    const commands = (input.commandCatalog ?? [])
+        .map((c) => ({ command: c.command, score: commandRelevance(c.command, relPath) }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 6)
+        .map((x) => x.command);
+    const mcpTools = (input.mcpToolNames ?? [])
+        .map((t) => ({ tool: t, score: commandRelevance(t, relPath) }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 6)
+        .map((x) => x.tool);
+    // Boundary rules and path conventions that reference this dir.
+    // Boundary rules carry `from` globs (file patterns) and import lists; we
+    // only match against `from` since that's the file-side.
+    const boundaryRules = input.inspection.boundaryRegistry.list();
+    const boundaryRuleIds = boundaryRules
+        .filter((r) => {
+        const from = r.from ?? [];
+        return from.some((p) => {
+            const stripped = String(p).replace(/[*?]/g, '');
+            return stripped.length > 0 && (relPath.includes(stripped) || stripped.includes(relPath));
+        });
+    })
+        .map((r) => r.id);
+    const pathConventions = (input.pathConventions ?? [])
+        .filter((p) => {
+        const pat = (p.pattern ?? p.path ?? '').replace(/[*?]/g, '');
+        return pat && (relPath.includes(pat) || pat.includes(relPath));
+    })
+        .map((p) => p.id);
+    // Related templates / pipelines from the registries (heuristic).
+    const templates = input.inspection.templateRegistry.list();
+    const relatedTemplates = templates
+        .filter((t) => {
+        const tp = t.targetPath;
+        return typeof tp === 'string' && relPath && tp.includes(relPath.split('/').pop() ?? '');
+    })
+        .map((t) => t.id);
+    const pipelines = input.inspection.pipelineRegistry.list();
+    const relatedPipelines = pipelines
+        .filter((p) => (p.steps ?? []).some((s) => JSON.stringify(s).toLowerCase().includes(relPath.toLowerCase())))
+        .map((p) => p.id);
+    const risks = detectRisks({ relPath, files, inferredKind });
+    const testCount = files.filter((f) => f.kind === 'test').length;
+    const nextCommands = [];
+    nextCommands.push(`shrk impact --files "${relPath}"`);
+    nextCommands.push(`shrk check boundaries --files "${relPath}"`);
+    if (testCount === 0 && isDir)
+        nextCommands.push(`shrk tests missing --area "${relPath}"`);
+    if (relPath.startsWith('packages/'))
+        nextCommands.push(`shrk architecture area packages/${relPath.split('/')[1]}`);
+    return {
+        schema: AREA_EXPLORE_SCHEMA,
+        projectRoot: root,
+        path: rawPath,
+        resolvedPath: relPath,
+        exists: true,
+        inferredKind,
+        role,
+        fileCount: files.length,
+        testCount,
+        keyFiles,
+        relatedCommands: commands,
+        relatedMcpTools: mcpTools,
+        relatedTemplates,
+        relatedPipelines,
+        boundaryRuleIds,
+        pathConventionIds: pathConventions,
+        risks,
+        nextCommands,
+    };
+}
+export function renderAreaExploreText(report) {
+    const lines = [];
+    lines.push(`=== Explore: ${report.resolvedPath || '(root)'} ===`);
+    if (!report.exists) {
+        lines.push(`  path does not exist.`);
+        return lines.join('\n') + '\n';
+    }
+    lines.push(`  kind:  ${report.inferredKind}`);
+    lines.push(`  role:  ${report.role}`);
+    lines.push(`  files: ${report.fileCount}  tests: ${report.testCount}`);
+    if (report.keyFiles.length > 0) {
+        lines.push('\nKey files:');
+        for (const f of report.keyFiles) {
+            lines.push(`  ${f.kind.padEnd(9)} ${f.relPath}  (${f.sizeBytes}B)`);
+        }
+    }
+    if (report.relatedCommands.length > 0) {
+        lines.push('\nRelated commands:');
+        for (const c of report.relatedCommands)
+            lines.push(`  $ shrk ${c}`);
+    }
+    if (report.relatedMcpTools.length > 0) {
+        lines.push('\nRelated MCP tools:');
+        for (const t of report.relatedMcpTools)
+            lines.push(`  • ${t}`);
+    }
+    if (report.relatedTemplates.length > 0) {
+        lines.push('\nRelated templates:');
+        for (const t of report.relatedTemplates)
+            lines.push(`  • ${t}`);
+    }
+    if (report.relatedPipelines.length > 0) {
+        lines.push('\nRelated pipelines:');
+        for (const p of report.relatedPipelines)
+            lines.push(`  • ${p}`);
+    }
+    if (report.boundaryRuleIds.length > 0) {
+        lines.push('\nBoundary rules covering this dir:');
+        for (const r of report.boundaryRuleIds)
+            lines.push(`  • ${r}`);
+    }
+    if (report.pathConventionIds.length > 0) {
+        lines.push('\nPath conventions covering this dir:');
+        for (const p of report.pathConventionIds)
+            lines.push(`  • ${p}`);
+    }
+    if (report.risks.length > 0) {
+        lines.push('\nCommon edit risks:');
+        for (const r of report.risks) {
+            const tag = r.severity === 'warning' ? 'WARN' : 'INFO';
+            lines.push(`  [${tag}] ${r.kind.padEnd(20)} ${r.message}`);
+        }
+    }
+    if (report.nextCommands.length > 0) {
+        lines.push('\nNext:');
+        for (const n of report.nextCommands)
+            lines.push(`  $ ${n}`);
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderAreaExploreMarkdown(report) {
+    const lines = [];
+    lines.push(`# Explore: \`${report.resolvedPath || '(root)'}\``);
+    lines.push('');
+    if (!report.exists) {
+        lines.push(`Path does not exist.`);
+        return lines.join('\n') + '\n';
+    }
+    lines.push(`- **Kind:** ${report.inferredKind}`);
+    lines.push(`- **Role:** ${report.role}`);
+    lines.push(`- **Files:** ${report.fileCount} (tests: ${report.testCount})`);
+    if (report.keyFiles.length > 0) {
+        lines.push('');
+        lines.push('## Key files');
+        for (const f of report.keyFiles)
+            lines.push(`- \`${f.relPath}\` _(${f.kind}, ${f.sizeBytes}B)_`);
+    }
+    if (report.relatedCommands.length > 0) {
+        lines.push('');
+        lines.push('## Related commands');
+        for (const c of report.relatedCommands)
+            lines.push(`- \`shrk ${c}\``);
+    }
+    if (report.relatedMcpTools.length > 0) {
+        lines.push('');
+        lines.push('## Related MCP tools');
+        for (const t of report.relatedMcpTools)
+            lines.push(`- \`${t}\``);
+    }
+    if (report.risks.length > 0) {
+        lines.push('');
+        lines.push('## Common edit risks');
+        for (const r of report.risks) {
+            lines.push(`- **${r.kind}** (_${r.severity}_) — ${r.message}`);
+        }
+    }
+    if (report.nextCommands.length > 0) {
+        lines.push('');
+        lines.push('## Next commands');
+        for (const n of report.nextCommands)
+            lines.push(`- \`${n}\``);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/area-map.d.ts

@@ -0,0 +1,43 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const AREA_MAP_SCHEMA = "sharkcraft.area-map/v1";
+export declare enum AreaKind {
+    Core = "core",
+    Common = "common",
+    Runtime = "runtime",
+    Kernel = "kernel",
+    Plugin = "plugin",
+    Adapter = "adapter",
+    Ui = "ui",
+    App = "app",
+    Api = "api",
+    Tests = "tests",
+    Docs = "docs",
+    Infra = "infra",
+    Generated = "generated",
+    Unknown = "unknown"
+}
+export interface IAreaMapEntry {
+    id: string;
+    kind: AreaKind;
+    paths: readonly string[];
+    fileCount: number;
+    /** Best-effort: import edges into this area (from import graph). */
+    importsIn: number;
+    /** Best-effort: import edges out of this area. */
+    importsOut: number;
+    boundaryRuleIds: readonly string[];
+    relatedTemplateIds: readonly string[];
+    relatedPipelineIds: readonly string[];
+    /** 0–100; high when an area has many fan-in edges with weak guard-rails. */
+    riskScore: number;
+}
+export interface IAreaMap {
+    schema: typeof AREA_MAP_SCHEMA;
+    projectRoot: string;
+    areas: readonly IAreaMapEntry[];
+    unclassifiedFiles: number;
+}
+export declare function buildAreaMap(inspection: ISharkcraftInspection): IAreaMap;
+export declare function renderAreaMapText(map: IAreaMap): string;
+export declare function renderAreaMapMarkdown(map: IAreaMap): string;
+//# sourceMappingURL=area-map.d.ts.map

package/dist/area-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"area-map.d.ts","sourceRoot":"","sources":["../src/area-map.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAExD,oBAAY,QAAQ;IAClB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,EAAE,OAAO;IACT,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,KAAK,UAAU;IACf,IAAI,SAAS;IACb,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAyED,wBAAgB,YAAY,CAAC,UAAU,EAAE,qBAAqB,GAAG,QAAQ,CA4ExE;AA0BD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CASvD;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAc3D"}

package/dist/area-map.js

@@ -0,0 +1,197 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const AREA_MAP_SCHEMA = 'sharkcraft.area-map/v1';
+export var AreaKind;
+(function (AreaKind) {
+    AreaKind["Core"] = "core";
+    AreaKind["Common"] = "common";
+    AreaKind["Runtime"] = "runtime";
+    AreaKind["Kernel"] = "kernel";
+    AreaKind["Plugin"] = "plugin";
+    AreaKind["Adapter"] = "adapter";
+    AreaKind["Ui"] = "ui";
+    AreaKind["App"] = "app";
+    AreaKind["Api"] = "api";
+    AreaKind["Tests"] = "tests";
+    AreaKind["Docs"] = "docs";
+    AreaKind["Infra"] = "infra";
+    AreaKind["Generated"] = "generated";
+    AreaKind["Unknown"] = "unknown";
+})(AreaKind || (AreaKind = {}));
+const AREA_PATTERNS = [
+    { kind: AreaKind.Core, match: [/^packages\/core(\/|$)/, /^src\/core(\/|$)/], idHint: 'core' },
+    { kind: AreaKind.Common, match: [/^packages\/(common|shared)(\/|$)/, /^src\/(common|shared)(\/|$)/], idHint: 'common' },
+    { kind: AreaKind.Runtime, match: [/^packages\/runtime(\/|$)/, /^src\/runtime(\/|$)/], idHint: 'runtime' },
+    { kind: AreaKind.Kernel, match: [/^packages\/kernel(\/|$)/, /^src\/kernel(\/|$)/], idHint: 'kernel' },
+    { kind: AreaKind.Plugin, match: [/plugins?(\/|$)/, /^packages\/plugin-/], idHint: 'plugin' },
+    { kind: AreaKind.Adapter, match: [/adapters?(\/|$)/, /^packages\/adapter-/], idHint: 'adapter' },
+    { kind: AreaKind.Ui, match: [/^packages\/(ui|dashboard|web)(\/|$)/, /^(src|app)\/(ui|components|pages|views)(\/|$)/], idHint: 'ui' },
+    { kind: AreaKind.App, match: [/^apps?\//, /^packages\/app(\/|$)/], idHint: 'app' },
+    { kind: AreaKind.Api, match: [/^packages\/api(\/|$)/, /\/api\//, /\/routes\//, /\/controllers\//], idHint: 'api' },
+    { kind: AreaKind.Tests, match: [/^tests?\//, /\.spec\.[tj]sx?$/, /\.test\.[tj]sx?$/, /\/__tests__\//], idHint: 'tests' },
+    { kind: AreaKind.Docs, match: [/^docs?\//, /\.md$/], idHint: 'docs' },
+    { kind: AreaKind.Infra, match: [/^(\.github|scripts|infra|docker|deploy)\//, /^Dockerfile/], idHint: 'infra' },
+    { kind: AreaKind.Generated, match: [/\/dist\//, /\/generated\//, /\/build\//, /\.d\.ts$/], idHint: 'generated' },
+];
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.sharkcraft',
+    'dist',
+    'build',
+    '.cache',
+    '.turbo',
+    '.nx',
+    'coverage',
+    '.next',
+]);
+function walk(root, base = '') {
+    const out = [];
+    const target = base ? nodePath.join(root, base) : root;
+    let entries;
+    try {
+        entries = readdirSync(target);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.') && !['.github', '.gitlab'].includes(name))
+            continue;
+        if (IGNORE_DIRS.has(name))
+            continue;
+        const rel = base ? `${base}/${name}` : name;
+        let stat;
+        try {
+            stat = statSync(nodePath.join(root, rel));
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            out.push(...walk(root, rel));
+        }
+        else if (stat.isFile()) {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+function classify(file) {
+    for (const p of AREA_PATTERNS) {
+        if (p.match.some((re) => re.test(file)))
+            return p.kind;
+    }
+    return AreaKind.Unknown;
+}
+function packageOrTopSegment(file) {
+    const segs = file.split('/');
+    if (segs[0] === 'packages' && segs[1])
+        return `packages/${segs[1]}`;
+    if (segs[0] === 'apps' && segs[1])
+        return `apps/${segs[1]}`;
+    return segs[0] ?? '';
+}
+export function buildAreaMap(inspection) {
+    const root = inspection.projectRoot;
+    const allFiles = existsSync(root) ? walk(root) : [];
+    const byKey = new Map();
+    let unclassified = 0;
+    for (const f of allFiles) {
+        const kind = classify(f);
+        if (kind === AreaKind.Unknown)
+            unclassified += 1;
+        const seg = packageOrTopSegment(f);
+        const key = `${kind}:${seg}`;
+        let entry = byKey.get(key);
+        if (!entry) {
+            entry = { kind, paths: new Set(), fileCount: 0 };
+            byKey.set(key, entry);
+        }
+        entry.paths.add(seg);
+        entry.fileCount += 1;
+    }
+    const boundaryRules = inspection.boundaryRegistry.list();
+    const templates = inspection.templateRegistry.list();
+    const pipelines = inspection.pipelineRegistry.list();
+    const areas = [];
+    for (const [key, info] of byKey) {
+        const paths = [...info.paths].sort();
+        const boundaryRuleIds = boundaryRules
+            .filter((r) => paths.some((p) => (r.from ?? []).some((g) => p.includes(stripGlob(g)))))
+            .map((r) => r.id);
+        const relatedTemplateIds = templates
+            .filter((t) => paths.some((p) => targetPathString(t).includes(p.split('/').pop() ?? '')))
+            .map((t) => t.id);
+        const relatedPipelineIds = pipelines
+            .filter((p) => paths.some((path) => (p.steps ?? []).some((s) => JSON.stringify(s).toLowerCase().includes(path.toLowerCase()))))
+            .map((p) => p.id);
+        areas.push({
+            id: key,
+            kind: info.kind,
+            paths,
+            fileCount: info.fileCount,
+            importsIn: 0,
+            importsOut: 0,
+            boundaryRuleIds,
+            relatedTemplateIds,
+            relatedPipelineIds,
+            riskScore: computeRiskScore({
+                kind: info.kind,
+                fileCount: info.fileCount,
+                boundaryRules: boundaryRuleIds.length,
+            }),
+        });
+    }
+    areas.sort((a, b) => b.fileCount - a.fileCount);
+    return {
+        schema: AREA_MAP_SCHEMA,
+        projectRoot: root,
+        areas,
+        unclassifiedFiles: unclassified,
+    };
+}
+function stripGlob(s) {
+    return s.replace(/[*?]/g, '');
+}
+function targetPathString(t) {
+    const tp = t.targetPath;
+    if (typeof tp === 'string')
+        return tp;
+    return '';
+}
+function computeRiskScore(input) {
+    let score = 0;
+    if (input.kind === AreaKind.Unknown)
+        score += 30;
+    if (input.kind === AreaKind.Generated)
+        score -= 10;
+    if (input.fileCount > 100)
+        score += 15;
+    if (input.fileCount > 25 && input.boundaryRules === 0)
+        score += 20;
+    if (input.boundaryRules > 3)
+        score -= 10;
+    return Math.max(0, Math.min(100, 30 + score));
+}
+export function renderAreaMapText(map) {
+    const lines = [];
+    lines.push(`Area map (${map.areas.length} areas, ${map.unclassifiedFiles} unclassified files)`);
+    for (const a of map.areas.slice(0, 50)) {
+        lines.push(`  ${a.kind.padEnd(10)} ${String(a.fileCount).padStart(5)} files  paths=${a.paths.join(', ')}  risk=${a.riskScore}`);
+    }
+    return lines.join('\n');
+}
+export function renderAreaMapMarkdown(map) {
+    const lines = [];
+    lines.push(`# Repository area map`);
+    lines.push('');
+    lines.push(`Total areas: **${map.areas.length}** — unclassified files: ${map.unclassifiedFiles}.`);
+    lines.push('');
+    lines.push('| Kind | Files | Paths | Boundary rules | Risk |');
+    lines.push('| --- | ---: | --- | ---: | ---: |');
+    for (const a of map.areas) {
+        lines.push(`| ${a.kind} | ${a.fileCount} | ${a.paths.join(', ')} | ${a.boundaryRuleIds.length} | ${a.riskScore} |`);
+    }
+    return lines.join('\n') + '\n';
+}