@safetnsr/vet 1.17.1 → 1.19.0

package/dist/categories.d.ts

@@ -7,5 +7,7 @@ export declare function buildCategories(checkMap: {
     integrity: CheckResult[];
     debt: CheckResult[];
     deps: CheckResult[];
+    architecture: CheckResult[];
+    aiready: CheckResult[];
 }): CategoryResult[];
 export declare function buildVetResult(project: string, categories: CategoryResult[]): VetResult;

package/dist/categories.js

@@ -17,9 +17,11 @@ export function toGrade(score) {
 // ── Category weights ─────────────────────────────────────────────────────────
 const WEIGHTS = {
     security: 0.25,
-    integrity: 0.35,
-    debt: 0.30,
+    integrity: 0.25,
+    debt: 0.20,
     deps: 0.10,
+    architecture: 0.10,
+    aiready: 0.10,
 };
 // ── Scoring floor for non-security checks ────────────────────────────────────
 const SECURITY_CHECKS = new Set(['scan', 'secrets', 'permissions', 'owasp']);
@@ -66,14 +68,16 @@ function completenessMultiplier(categories) {
 // ── Group checks into categories ─────────────────────────────────────────────
 export function buildCategories(checkMap) {
     const categories = [];
-    for (const name of ['security', 'integrity', 'debt', 'deps']) {
+    for (const name of ['security', 'integrity', 'debt', 'deps', 'architecture', 'aiready']) {
         const checks = checkMap[name];
+        if (!checks || checks.length === 0)
+            continue;
         const score = averageScore(checks);
         const issues = checks.flatMap(c => c.issues);
         categories.push({
             name,
             score,
-            weight: WEIGHTS[name],
+            weight: WEIGHTS[name] || 0.10,
             checks,
             issues,
         });

package/dist/checks/aiready.d.ts

@@ -0,0 +1,2 @@
+import type { CheckResult } from '../types.js';
+export declare function checkAIReady(cwd: string): CheckResult;

package/dist/checks/aiready.js

@@ -0,0 +1,311 @@
+import { join } from 'node:path';
+import { walkFiles, readFile, c } from '../util.js';
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs']);
+function isSourceFile(f) {
+    const dot = f.lastIndexOf('.');
+    return dot !== -1 && SOURCE_EXTS.has(f.substring(dot));
+}
+function isTestFile(f) {
+    return /\.(test|spec)\.[jt]sx?$/.test(f) || f.includes('__tests__') || /(?:^|[/\\])tests?[/\\]/.test(f);
+}
+function isTsFile(f) {
+    return /\.[mc]?tsx?$/.test(f);
+}
+function extractFunctions(file, content) {
+    const funcs = [];
+    const lines = content.split('\n');
+    const isTs = isTsFile(file);
+    // Match function declarations, arrow functions, methods
+    const funcStartRe = /^(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?:<[^>]*>)?\s*\(([^)]*)\)(?:\s*:\s*[^{]+)?\s*\{/;
+    const arrowRe = /^(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+)?\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+)?\s*=>/;
+    const methodRe = /^\s+(?:async\s+)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(([^)]*)\)(?:\s*:\s*[^{]+)?\s*\{/;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        let match = line.match(funcStartRe) || line.match(arrowRe) || line.match(methodRe);
+        if (!match)
+            continue;
+        const name = match[1];
+        if (!name || name === 'if' || name === 'for' || name === 'while' || name === 'switch')
+            continue;
+        const params = match[2] || '';
+        const paramCount = params.trim() === '' ? 0 : params.split(',').length;
+        const hasReturnType = /\)\s*:\s*[^{]/.test(line);
+        // Count function body lines (find matching closing brace)
+        let depth = 0;
+        let started = false;
+        let endLine = i;
+        for (let j = i; j < lines.length && j < i + 500; j++) {
+            for (const ch of lines[j]) {
+                if (ch === '{') {
+                    depth++;
+                    started = true;
+                }
+                if (ch === '}')
+                    depth--;
+            }
+            if (started && depth <= 0) {
+                endLine = j;
+                break;
+            }
+        }
+        funcs.push({
+            name,
+            file,
+            line: i + 1,
+            lineCount: endLine - i + 1,
+            paramCount,
+            hasReturnType,
+            isTyped: isTs,
+        });
+    }
+    return funcs;
+}
+// ── Import graph for context load ────────────────────────────────────────────
+function buildImportCounts(cwd, sourceFiles) {
+    const importCounts = new Map(); // file → number of local imports
+    const importRe = /(?:import\s+(?:[\s\S]*?\s+from\s+)?['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\))/g;
+    for (const file of sourceFiles) {
+        const content = readFile(join(cwd, file));
+        if (!content)
+            continue;
+        let count = 0;
+        let match;
+        importRe.lastIndex = 0;
+        while ((match = importRe.exec(content)) !== null) {
+            const spec = match[1] || match[2];
+            if (spec && spec.startsWith('.'))
+                count++;
+        }
+        importCounts.set(file, count);
+    }
+    return importCounts;
+}
+function analyzeStructure(files) {
+    const dirs = new Map(); // dir → file count
+    let totalDepth = 0;
+    let maxDepth = 0;
+    // Naming conventions
+    let camelCase = 0;
+    let kebabCase = 0;
+    let snakeCase = 0;
+    let pascalCase = 0;
+    for (const file of files) {
+        const parts = file.split(/[/\\]/);
+        const depth = parts.length - 1;
+        totalDepth += depth;
+        if (depth > maxDepth)
+            maxDepth = depth;
+        const dir = parts.slice(0, -1).join('/') || '.';
+        dirs.set(dir, (dirs.get(dir) || 0) + 1);
+        // Check file naming convention (without extension)
+        const name = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+        if (/^[a-z][a-zA-Z0-9]*$/.test(name) && /[A-Z]/.test(name))
+            camelCase++;
+        else if (/^[a-z][a-z0-9-]*$/.test(name) && name.includes('-'))
+            kebabCase++;
+        else if (/^[a-z][a-z0-9_]*$/.test(name) && name.includes('_'))
+            snakeCase++;
+        else if (/^[A-Z][a-zA-Z0-9]*$/.test(name))
+            pascalCase++;
+    }
+    const total = camelCase + kebabCase + snakeCase + pascalCase;
+    const dominant = Math.max(camelCase, kebabCase, snakeCase, pascalCase);
+    const namingConsistency = total > 0 ? dominant / total : 1;
+    const dirCounts = Array.from(dirs.values());
+    const avgFilesPerDir = dirCounts.length > 0 ? dirCounts.reduce((a, b) => a + b, 0) / dirCounts.length : 0;
+    return {
+        maxDepth,
+        avgDepth: files.length > 0 ? totalDepth / files.length : 0,
+        avgFilesPerDir,
+        namingConsistency,
+    };
+}
+// ── Main check ───────────────────────────────────────────────────────────────
+export function checkAIReady(cwd) {
+    const allFiles = walkFiles(cwd);
+    const sourceFiles = allFiles.filter(f => isSourceFile(f) && !isTestFile(f));
+    if (sourceFiles.length < 3) {
+        return {
+            maxScore: 100,
+            name: 'aiready',
+            score: 100,
+            summary: 'too few source files for AI-readiness analysis',
+            issues: [],
+        };
+    }
+    const issues = [];
+    // ── 1. Context load ───────────────────────────────────────────────────────
+    const importCounts = buildImportCounts(cwd, sourceFiles);
+    const counts = Array.from(importCounts.values());
+    const avgContextLoad = counts.length > 0 ? counts.reduce((a, b) => a + b, 0) / counts.length : 0;
+    // Score: <2 = great (100), 2-4 = good (80), 4-6 = okay (60), 6-8 = poor (40), >8 = bad (20)
+    const contextScore = avgContextLoad <= 2 ? 100
+        : avgContextLoad <= 4 ? 100 - (avgContextLoad - 2) * 10
+            : avgContextLoad <= 6 ? 80 - (avgContextLoad - 4) * 10
+                : avgContextLoad <= 8 ? 60 - (avgContextLoad - 6) * 10
+                    : Math.max(20, 40 - (avgContextLoad - 8) * 5);
+    if (avgContextLoad > 5) {
+        issues.push({
+            severity: 'warning',
+            message: `high context load: files import ${avgContextLoad.toFixed(1)} local modules on average — AI agents need to load many files to understand changes`,
+            file: '',
+            fixable: true,
+            fixHint: 'reduce coupling between modules, use dependency injection or barrel exports',
+        });
+    }
+    // ── 2. Function clarity ───────────────────────────────────────────────────
+    const allFuncs = [];
+    for (const file of sourceFiles) {
+        const content = readFile(join(cwd, file));
+        if (!content)
+            continue;
+        allFuncs.push(...extractFunctions(file, content));
+    }
+    const clearFuncs = allFuncs.filter(f => f.lineCount <= 25 && f.paramCount < 5);
+    const clarityPct = allFuncs.length > 0 ? clearFuncs.length / allFuncs.length : 1;
+    const clarityScore = Math.round(clarityPct * 100);
+    const longFuncs = allFuncs.filter(f => f.lineCount > 50);
+    if (longFuncs.length > 0) {
+        const worst = longFuncs.sort((a, b) => b.lineCount - a.lineCount).slice(0, 3);
+        issues.push({
+            severity: 'warning',
+            message: `${longFuncs.length} function${longFuncs.length !== 1 ? 's' : ''} >50 lines — AI agents will struggle to modify these safely. Worst: ${worst.map(f => `${f.name} (${f.lineCount} lines)`).join(', ')}`,
+            file: worst[0]?.file || '',
+            line: worst[0]?.line,
+            fixable: true,
+            fixHint: 'break into smaller, single-responsibility functions',
+        });
+    }
+    const manyParams = allFuncs.filter(f => f.paramCount >= 5);
+    if (manyParams.length > 0) {
+        issues.push({
+            severity: 'info',
+            message: `${manyParams.length} function${manyParams.length !== 1 ? 's' : ''} with 5+ parameters — hard for agents to call correctly`,
+            file: manyParams[0]?.file || '',
+            fixable: true,
+            fixHint: 'use an options object parameter instead',
+        });
+    }
+    // ── 3. Type safety ────────────────────────────────────────────────────────
+    const tsFiles = sourceFiles.filter(f => isTsFile(f));
+    const tsRatio = sourceFiles.length > 0 ? tsFiles.length / sourceFiles.length : 0;
+    // Count `any` usage in TS files
+    let anyCount = 0;
+    let totalTsLines = 0;
+    for (const file of tsFiles) {
+        const content = readFile(join(cwd, file));
+        if (!content)
+            continue;
+        const lines = content.split('\n');
+        totalTsLines += lines.length;
+        for (const line of lines) {
+            // Match `: any`, `as any`, `<any>`, but not in comments
+            if (line.trimStart().startsWith('//') || line.trimStart().startsWith('*'))
+                continue;
+            const anyMatches = line.match(/(?::\s*any\b|as\s+any\b|<any>)/g);
+            if (anyMatches)
+                anyCount += anyMatches.length;
+        }
+    }
+    const anyDensity = totalTsLines > 0 ? anyCount / totalTsLines : 0;
+    const typeSafetyScore = Math.round(tsRatio * 100 * (1 - Math.min(1, anyDensity * 50)));
+    if (tsRatio < 0.5 && sourceFiles.length > 5) {
+        issues.push({
+            severity: 'warning',
+            message: `low type coverage: ${Math.round(tsRatio * 100)}% TypeScript — AI agents can't verify their changes in untyped code`,
+            file: '',
+            fixable: true,
+            fixHint: 'migrate JavaScript files to TypeScript incrementally',
+        });
+    }
+    if (anyCount > 5) {
+        issues.push({
+            severity: 'info',
+            message: `${anyCount} \`any\` type usages — weakens type safety that agents rely on`,
+            file: '',
+            fixable: true,
+            fixHint: 'replace `any` with specific types',
+        });
+    }
+    // ── 4. File discoverability ───────────────────────────────────────────────
+    const structure = analyzeStructure(sourceFiles);
+    let discoverScore = 100;
+    // Penalize deep nesting
+    if (structure.maxDepth > 6)
+        discoverScore -= Math.min(20, (structure.maxDepth - 6) * 5);
+    // Penalize inconsistent naming
+    discoverScore -= Math.round((1 - structure.namingConsistency) * 30);
+    // Penalize very large directories (>30 files)
+    if (structure.avgFilesPerDir > 20)
+        discoverScore -= Math.min(15, (structure.avgFilesPerDir - 20) * 2);
+    discoverScore = Math.max(20, discoverScore);
+    if (structure.namingConsistency < 0.6) {
+        issues.push({
+            severity: 'info',
+            message: `mixed file naming conventions — AI agents work best with consistent naming (pick camelCase or kebab-case)`,
+            file: '',
+            fixable: true,
+            fixHint: 'standardize file naming convention across the project',
+        });
+    }
+    if (structure.maxDepth > 7) {
+        issues.push({
+            severity: 'info',
+            message: `deeply nested file structure (max ${structure.maxDepth} levels) — agents struggle to navigate deep hierarchies`,
+            file: '',
+            fixable: true,
+            fixHint: 'flatten directory structure where possible',
+        });
+    }
+    // ── 5. Modification safety ────────────────────────────────────────────────
+    // % of functions that are typed (in .ts files with return type)
+    const typedFuncs = allFuncs.filter(f => f.isTyped && f.hasReturnType);
+    const modSafetyPct = allFuncs.length > 0 ? typedFuncs.length / allFuncs.length : 0;
+    const modSafetyScore = Math.round(modSafetyPct * 100);
+    // ── 6. Context window fit ─────────────────────────────────────────────────
+    let totalChars = 0;
+    for (const file of sourceFiles) {
+        const content = readFile(join(cwd, file));
+        if (content)
+            totalChars += content.length;
+    }
+    const estimatedTokens = totalChars / 4;
+    const contextWindowSize = 128_000;
+    const fitRatio = Math.min(1, contextWindowSize / estimatedTokens);
+    const fitScore = fitRatio >= 1 ? 100
+        : fitRatio >= 0.5 ? 70 + fitRatio * 30
+            : fitRatio >= 0.25 ? 40 + fitRatio * 60
+                : Math.max(10, Math.round(fitRatio * 160));
+    if (fitRatio < 0.25) {
+        issues.push({
+            severity: 'info',
+            message: `only ${Math.round(fitRatio * 100)}% of source fits in a 128k context window (${Math.round(estimatedTokens / 1000)}k tokens) — agents need careful file selection`,
+            file: '',
+            fixable: false,
+            fixHint: 'maintain clear module boundaries so agents can work on isolated sections',
+        });
+    }
+    // ── Weighted score ────────────────────────────────────────────────────────
+    const score = Math.max(25, Math.round(contextScore * 0.25 +
+        clarityScore * 0.20 +
+        typeSafetyScore * 0.20 +
+        discoverScore * 0.15 +
+        modSafetyScore * 0.10 +
+        fitScore * 0.10));
+    // ── Summary ───────────────────────────────────────────────────────────────
+    const parts = [];
+    parts.push(`context load ${avgContextLoad.toFixed(1)} files`);
+    parts.push(`${Math.round(clarityPct * 100)}% clear functions`);
+    parts.push(`${Math.round(tsRatio * 100)}% typed`);
+    if (fitRatio < 0.5)
+        parts.push(c.yellow + `${Math.round(fitRatio * 100)}% fits in 128k` + c.reset);
+    if (longFuncs.length > 0)
+        parts.push(c.yellow + `${longFuncs.length} long functions` + c.reset);
+    return {
+        maxScore: 100,
+        name: 'aiready',
+        score,
+        summary: parts.join(', '),
+        issues,
+    };
+}

package/dist/checks/architecture.d.ts

@@ -0,0 +1,2 @@
+import type { CheckResult } from '../types.js';
+export declare function checkArchitecture(cwd: string): CheckResult;

package/dist/checks/architecture.js

@@ -0,0 +1,285 @@
+import { join, dirname } from 'node:path';
+import { walkFiles, readFile, c } from '../util.js';
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs']);
+function isSourceFile(f) {
+    const dot = f.lastIndexOf('.');
+    return dot !== -1 && SOURCE_EXTS.has(f.substring(dot));
+}
+function isTestFile(f) {
+    return /\.(test|spec)\.[jt]sx?$/.test(f) || f.includes('__tests__') || /(?:^|[/\\])tests?[/\\]/.test(f);
+}
+function resolveImport(fromFile, specifier, allFiles) {
+    if (!specifier.startsWith('.'))
+        return null; // only resolve relative imports
+    const dir = dirname(fromFile);
+    const base = join(dir, specifier).replace(/\\/g, '/');
+    // Try exact, then with extensions, then as directory index
+    const candidates = [
+        base,
+        ...Array.from(SOURCE_EXTS).map(ext => base + ext),
+        ...Array.from(SOURCE_EXTS).map(ext => base + '/index' + ext),
+    ];
+    for (const c of candidates) {
+        if (allFiles.has(c))
+            return c;
+    }
+    return null;
+}
+function buildImportGraph(cwd, files) {
+    const sourceFiles = files.filter(f => isSourceFile(f) && !isTestFile(f));
+    const fileSet = new Set(sourceFiles);
+    const edges = [];
+    const importRe = /(?:import\s+(?:[\s\S]*?\s+from\s+)?['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\))/g;
+    for (const file of sourceFiles) {
+        const content = readFile(join(cwd, file));
+        if (!content)
+            continue;
+        let match;
+        importRe.lastIndex = 0;
+        while ((match = importRe.exec(content)) !== null) {
+            const specifier = match[1] || match[2];
+            if (!specifier || !specifier.startsWith('.'))
+                continue;
+            const resolved = resolveImport(file, specifier, fileSet);
+            if (resolved) {
+                edges.push({ from: file, to: resolved });
+            }
+        }
+    }
+    return edges;
+}
+// ── Module detection ─────────────────────────────────────────────────────────
+function getModule(file) {
+    // First directory under src/, lib/, app/, or root
+    const parts = file.split(/[/\\]/);
+    // Find the "source root" (src/, lib/, app/, packages/*)
+    let start = 0;
+    for (let i = 0; i < parts.length - 1; i++) {
+        if (['src', 'lib', 'app', 'source'].includes(parts[i])) {
+            start = i + 1;
+            break;
+        }
+    }
+    if (start < parts.length - 1) {
+        return parts.slice(0, start + 1).join('/');
+    }
+    // Fallback: use first directory
+    return parts.length > 1 ? parts[0] : '(root)';
+}
+// ── Cycle detection (DFS) ────────────────────────────────────────────────────
+function findCycles(moduleGraph) {
+    const cycles = [];
+    const visited = new Set();
+    const inStack = new Set();
+    const path = [];
+    function dfs(node) {
+        if (inStack.has(node)) {
+            // Found cycle — extract it
+            const cycleStart = path.indexOf(node);
+            if (cycleStart !== -1) {
+                cycles.push([...path.slice(cycleStart), node]);
+            }
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        inStack.add(node);
+        path.push(node);
+        const deps = moduleGraph.get(node);
+        if (deps) {
+            for (const dep of deps) {
+                if (dep !== node)
+                    dfs(dep); // skip self-imports
+            }
+        }
+        path.pop();
+        inStack.delete(node);
+    }
+    for (const node of moduleGraph.keys()) {
+        dfs(node);
+    }
+    // Deduplicate cycles (same cycle can be found from different start nodes)
+    const seen = new Set();
+    return cycles.filter(cycle => {
+        const sorted = [...cycle.slice(0, -1)].sort().join('|');
+        if (seen.has(sorted))
+            return false;
+        seen.add(sorted);
+        return true;
+    });
+}
+// ── Main check ───────────────────────────────────────────────────────────────
+export function checkArchitecture(cwd) {
+    const allFiles = walkFiles(cwd);
+    const sourceFiles = allFiles.filter(f => isSourceFile(f) && !isTestFile(f));
+    if (sourceFiles.length < 5) {
+        return {
+            maxScore: 100,
+            name: 'architecture',
+            score: 100,
+            summary: 'too few source files for architecture analysis',
+            issues: [],
+        };
+    }
+    const edges = buildImportGraph(cwd, allFiles);
+    const issues = [];
+    // ── Build module-level graph ───────────────────────────────────────────────
+    const moduleGraph = new Map(); // module → set of imported modules
+    const moduleFiles = new Map(); // module → files in it
+    for (const file of sourceFiles) {
+        const mod = getModule(file);
+        if (!moduleFiles.has(mod))
+            moduleFiles.set(mod, new Set());
+        moduleFiles.get(mod).add(file);
+        if (!moduleGraph.has(mod))
+            moduleGraph.set(mod, new Set());
+    }
+    for (const edge of edges) {
+        const fromMod = getModule(edge.from);
+        const toMod = getModule(edge.to);
+        if (fromMod !== toMod) {
+            moduleGraph.get(fromMod)?.add(toMod);
+        }
+    }
+    // ── Coupling metrics ──────────────────────────────────────────────────────
+    const afferent = new Map(); // Ca: who depends on me
+    const efferent = new Map(); // Ce: who do I depend on
+    for (const [mod, deps] of moduleGraph) {
+        efferent.set(mod, deps.size);
+        for (const dep of deps) {
+            afferent.set(dep, (afferent.get(dep) || 0) + 1);
+        }
+    }
+    // Instability: Ce / (Ca + Ce). 0 = stable (many dependents), 1 = unstable
+    const instability = new Map();
+    for (const mod of moduleGraph.keys()) {
+        const ca = afferent.get(mod) || 0;
+        const ce = efferent.get(mod) || 0;
+        instability.set(mod, ca + ce > 0 ? ce / (ca + ce) : 0.5);
+    }
+    // ── God files ──────────────────────────────────────────────────────────────
+    const fileImporters = new Map(); // file → files that import it
+    for (const edge of edges) {
+        if (!fileImporters.has(edge.to))
+            fileImporters.set(edge.to, new Set());
+        fileImporters.get(edge.to).add(edge.from);
+    }
+    const GOD_FILE_THRESHOLD = 10;
+    const godFiles = [];
+    for (const [file, importers] of fileImporters) {
+        if (importers.size >= GOD_FILE_THRESHOLD) {
+            godFiles.push({ file, importers: importers.size });
+        }
+    }
+    godFiles.sort((a, b) => b.importers - a.importers);
+    for (const gf of godFiles) {
+        issues.push({
+            severity: 'warning',
+            message: `god file: ${gf.file} is imported by ${gf.importers} files — consider splitting by domain`,
+            file: gf.file,
+            fixable: true,
+            fixHint: 'split into smaller, domain-specific modules',
+        });
+    }
+    // ── Circular dependencies ─────────────────────────────────────────────────
+    const cycles = findCycles(moduleGraph);
+    for (const cycle of cycles.slice(0, 5)) { // cap at 5 reported cycles
+        const cycleStr = cycle.join(' → ');
+        issues.push({
+            severity: 'warning',
+            message: `circular dependency: ${cycleStr}`,
+            file: cycle[0],
+            fixable: true,
+            fixHint: 'extract shared types/interfaces into a separate module to break the cycle',
+        });
+    }
+    // ── Unstable modules with high dependents (worst pattern) ──────────────────
+    for (const [mod, inst] of instability) {
+        const ca = afferent.get(mod) || 0;
+        if (inst > 0.8 && ca >= 3) {
+            issues.push({
+                severity: 'warning',
+                message: `unstable dependency: ${mod} has instability ${inst.toFixed(2)} but ${ca} modules depend on it — changes here break downstream`,
+                file: mod,
+                fixable: true,
+                fixHint: 'reduce dependencies or add an abstraction layer',
+            });
+        }
+    }
+    // ── Orphan modules ────────────────────────────────────────────────────────
+    for (const mod of moduleGraph.keys()) {
+        const ca = afferent.get(mod) || 0;
+        const ce = efferent.get(mod) || 0;
+        const files = moduleFiles.get(mod);
+        if (ca === 0 && ce === 0 && files && files.size > 2) {
+            // Skip entry point modules
+            const hasEntry = Array.from(files).some(f => /(?:^|[/\\])(?:index|main|cli|app|server)\.[jt]sx?$/.test(f));
+            if (!hasEntry) {
+                issues.push({
+                    severity: 'info',
+                    message: `orphan module: ${mod} (${files.size} files) is not imported by any other module`,
+                    file: mod,
+                    fixable: false,
+                    fixHint: 'may be dead code — verify if still needed',
+                });
+            }
+        }
+    }
+    // ── Boundary violations ───────────────────────────────────────────────────
+    // Files importing deep into another module (>2 levels) instead of from its index
+    let boundaryViolations = 0;
+    for (const edge of edges) {
+        const fromMod = getModule(edge.from);
+        const toMod = getModule(edge.to);
+        if (fromMod === toMod)
+            continue;
+        // Check if target file is deep inside the module (not the index)
+        const toRelative = edge.to.replace(toMod + '/', '');
+        if (toRelative.includes('/') && !/^index\.[jt]sx?$/.test(toRelative)) {
+            boundaryViolations++;
+            if (boundaryViolations <= 3) { // only report first 3
+                issues.push({
+                    severity: 'info',
+                    message: `boundary violation: ${edge.from} imports ${edge.to} directly — prefer importing from ${toMod}/index`,
+                    file: edge.from,
+                    fixable: true,
+                    fixHint: `re-export from ${toMod}/index.ts and import from there`,
+                });
+            }
+        }
+    }
+    if (boundaryViolations > 3) {
+        issues.push({
+            severity: 'info',
+            message: `${boundaryViolations - 3} more boundary violations (importing deep into other modules)`,
+            file: '',
+            fixable: false,
+            fixHint: 'use barrel exports (index.ts) to define module boundaries',
+        });
+    }
+    // ── Scoring ───────────────────────────────────────────────────────────────
+    const moduleCount = moduleGraph.size;
+    const sizeScale = moduleCount <= 5 ? 1.0 : Math.max(0.3, 1.0 - Math.log10(moduleCount / 5) * 0.3);
+    let score = 100;
+    score -= Math.min(30, cycles.length * 15) * sizeScale;
+    score -= Math.min(20, godFiles.length * 10) * sizeScale;
+    score -= Math.min(15, Array.from(instability.values()).filter(i => i > 0.8).length * 5) * sizeScale;
+    score -= Math.min(10, Math.floor(boundaryViolations / 3) * 3) * sizeScale;
+    score = Math.max(25, Math.round(score));
+    // ── Summary ───────────────────────────────────────────────────────────────
+    const parts = [];
+    parts.push(`${moduleGraph.size} modules`);
+    parts.push(`${edges.length} import edges`);
+    if (cycles.length > 0)
+        parts.push(c.red + `${cycles.length} circular dep${cycles.length !== 1 ? 's' : ''}` + c.reset);
+    if (godFiles.length > 0)
+        parts.push(c.yellow + `${godFiles.length} god file${godFiles.length !== 1 ? 's' : ''}` + c.reset);
+    return {
+        maxScore: 100,
+        name: 'architecture',
+        score,
+        summary: parts.join(', '),
+        issues,
+    };
+}

package/dist/checks/deep.d.ts

@@ -0,0 +1,2 @@
+import type { CheckResult } from '../types.js';
+export declare function checkDeep(cwd: string): Promise<CheckResult>;