@safetnsr/vet 1.17.1 → 1.18.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/explain.d.ts

@@ -0,0 +1,15 @@
+import type { CheckResult } from '../types.js';
+export type RiskTier = 'RISKY' | 'REVIEW' | 'SAFE';
+interface FileRisk {
+    file: string;
+    tier: RiskTier;
+    reason: string;
+}
+export declare function classifyFile(filePath: string): {
+    tier: RiskTier;
+    reason: string;
+};
+export declare function analyzeFiles(cwd: string, since?: string): FileRisk[];
+export declare function checkExplain(cwd: string, since?: string): CheckResult;
+export declare function runExplainCommand(format: 'json' | 'ascii', cwd: string, since?: string, useAI?: boolean, verbose?: boolean): Promise<void>;
+export {};

package/dist/checks/explain.js

@@ -0,0 +1,208 @@
+import { execSync } from 'node:child_process';
+import { c } from '../util.js';
+const RISKY_PATTERNS = [
+    /^auth/i, /^session/i, /^payment/i, /^billing/i, /^credential/i,
+    /^token/i, /^jwt/i, /^password/i, /^secret/i, /^env/i,
+];
+const RISKY_PATH_PATTERNS = [
+    /config\/prod/i, /migrations\//i, /\.env/i,
+];
+const REVIEW_PATH_PATTERNS = [
+    /^api\//i, /^routes\//i, /^middleware\//i, /^db\//i,
+    /^schema/i, /^hooks\//i, /^controllers\//i,
+];
+const RISKY_REMOVED_KEYWORDS = ['DELETE', 'DROP', 'destroy', 'removeAll', 'truncate', 'rm -rf', 'unlink'];
+const REVIEW_ADDED_KEYWORDS = ['TODO', 'FIXME', 'HACK'];
+function basename(filePath) {
+    const parts = filePath.split('/');
+    return parts[parts.length - 1];
+}
+export function classifyFile(filePath) {
+    const base = basename(filePath).toLowerCase();
+    const lower = filePath.toLowerCase();
+    for (const pat of RISKY_PATTERNS) {
+        if (pat.test(base))
+            return { tier: 'RISKY', reason: `basename matches ${pat.source}` };
+    }
+    for (const pat of RISKY_PATH_PATTERNS) {
+        if (pat.test(lower))
+            return { tier: 'RISKY', reason: `path matches ${pat.source}` };
+    }
+    for (const pat of REVIEW_PATH_PATTERNS) {
+        if (pat.test(lower))
+            return { tier: 'REVIEW', reason: `path matches ${pat.source}` };
+    }
+    return { tier: 'SAFE', reason: 'no risk patterns matched' };
+}
+function gitCmd(args, cwd) {
+    try {
+        return execSync(`git ${args}`, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function getChangedFiles(cwd, since) {
+    // Try git diff first
+    const ref = since || 'HEAD~1';
+    const nameStatus = gitCmd(`diff ${ref} --name-status`, cwd);
+    if (nameStatus) {
+        return nameStatus.split('\n')
+            .filter(l => l.trim())
+            .map(l => l.split('\t').slice(1).pop())
+            .filter(Boolean);
+    }
+    // Fallback: git status for repos with no history
+    const status = gitCmd('status --porcelain', cwd);
+    if (status) {
+        return status.split('\n')
+            .filter(l => l.trim())
+            .map(l => l.trim().replace(/^[A-Z?!]+\s+/, ''))
+            .filter(Boolean);
+    }
+    return [];
+}
+function getHunkKeywords(cwd, since) {
+    const ref = since || 'HEAD~1';
+    const riskyFiles = new Set();
+    const reviewFiles = new Set();
+    const diff = gitCmd(`diff ${ref} -U0`, cwd);
+    if (!diff)
+        return { riskyFiles, reviewFiles };
+    let currentFile = '';
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('diff --git')) {
+            const match = line.match(/b\/(.+)$/);
+            if (match)
+                currentFile = match[1];
+            continue;
+        }
+        // Removed lines (start with - but not ---)
+        if (line.startsWith('-') && !line.startsWith('---')) {
+            for (const kw of RISKY_REMOVED_KEYWORDS) {
+                if (line.includes(kw)) {
+                    riskyFiles.add(currentFile);
+                    break;
+                }
+            }
+        }
+        // Added lines (start with + but not +++)
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            for (const kw of REVIEW_ADDED_KEYWORDS) {
+                if (line.includes(kw)) {
+                    reviewFiles.add(currentFile);
+                    break;
+                }
+            }
+        }
+    }
+    return { riskyFiles, reviewFiles };
+}
+export function analyzeFiles(cwd, since) {
+    const files = getChangedFiles(cwd, since);
+    if (files.length === 0)
+        return [];
+    const { riskyFiles, reviewFiles } = getHunkKeywords(cwd, since);
+    const results = [];
+    for (const file of files) {
+        let { tier, reason } = classifyFile(file);
+        // Hunk-based bumps
+        if (riskyFiles.has(file) && tier !== 'RISKY') {
+            tier = 'RISKY';
+            reason = 'destructive keyword in removed line';
+        }
+        else if (reviewFiles.has(file) && tier === 'SAFE') {
+            tier = 'REVIEW';
+            reason = 'TODO/FIXME/HACK in added line';
+        }
+        results.push({ file, tier, reason });
+    }
+    return results;
+}
+// ── checkExplain (for full scan integration) ─────────────────────────────────
+export function checkExplain(cwd, since) {
+    const files = analyzeFiles(cwd, since);
+    const risky = files.filter(f => f.tier === 'RISKY');
+    const review = files.filter(f => f.tier === 'REVIEW');
+    const rawScore = 100 - (risky.length * 15) - (review.length * 5);
+    const finalScore = Math.max(0, Math.min(100, rawScore));
+    const issues = [];
+    for (const f of risky) {
+        issues.push({
+            severity: 'error',
+            message: `RISKY: ${f.file} — ${f.reason}`,
+            file: f.file,
+            fixable: false,
+        });
+    }
+    for (const f of review) {
+        issues.push({
+            severity: 'warning',
+            message: `REVIEW: ${f.file} — ${f.reason}`,
+            file: f.file,
+            fixable: false,
+        });
+    }
+    return {
+        name: 'explain',
+        score: finalScore,
+        maxScore: 100,
+        issues,
+        summary: `${risky.length} risky, ${review.length} review, ${files.length - risky.length - review.length} safe`,
+    };
+}
+// ── runExplainCommand (standalone CLI) ───────────────────────────────────────
+export async function runExplainCommand(format, cwd, since, useAI, verbose) {
+    if (useAI) {
+        console.log(`\n  ${c.dim}LLM classification coming in v2${c.reset}\n`);
+        return;
+    }
+    const files = analyzeFiles(cwd, since);
+    const risky = files.filter(f => f.tier === 'RISKY');
+    const review = files.filter(f => f.tier === 'REVIEW');
+    const safe = files.filter(f => f.tier === 'SAFE');
+    if (format === 'json') {
+        const output = {
+            risky: risky.map(f => ({ file: f.file, reason: f.reason })),
+            review: review.map(f => ({ file: f.file, reason: f.reason })),
+            safe: safe.map(f => ({ file: f.file, reason: f.reason })),
+            summary: {
+                risky: risky.length,
+                review: review.length,
+                safe: safe.length,
+                total: files.length,
+            },
+        };
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    // ASCII output
+    console.log(`\n  ${c.bold}vet explain${c.reset} — risk-tier analysis\n`);
+    if (files.length === 0) {
+        console.log(`  ${c.dim}no changed files found${c.reset}\n`);
+        return;
+    }
+    if (risky.length > 0) {
+        console.log(`  ${c.red}${c.bold}RISKY${c.reset} ${c.dim}(${risky.length})${c.reset}`);
+        for (const f of risky) {
+            console.log(`  ${c.red}✗${c.reset} ${f.file} ${c.dim}— ${f.reason}${c.reset}`);
+        }
+        console.log('');
+    }
+    if (review.length > 0) {
+        console.log(`  ${c.yellow}${c.bold}REVIEW${c.reset} ${c.dim}(${review.length})${c.reset}`);
+        for (const f of review) {
+            console.log(`  ${c.yellow}⚠${c.reset} ${f.file} ${c.dim}— ${f.reason}${c.reset}`);
+        }
+        console.log('');
+    }
+    if (verbose && safe.length > 0) {
+        console.log(`  ${c.green}${c.bold}SAFE${c.reset} ${c.dim}(${safe.length})${c.reset}`);
+        for (const f of safe) {
+            console.log(`  ${c.green}✓${c.reset} ${f.file}`);
+        }
+        console.log('');
+    }
+    const total = files.length;
+    console.log(`  ${c.dim}total: ${total} files — ${risky.length} risky, ${review.length} review, ${safe.length} safe${c.reset}\n`);
+}

package/dist/cli.js

@@ -13,6 +13,8 @@ import { checkOwasp } from './checks/owasp.js';
 import { checkDeps } from './checks/deps.js';
 import { checkDebt } from './checks/debt.js';
 import { checkIntegrity } from './checks/integrity.js';
+import { checkArchitecture } from './checks/architecture.js';
+import { checkAIReady } from './checks/aiready.js';
 import { checkReceipt, runReceiptCommand } from './checks/receipt.js';
 import { checkMemory } from './checks/memory.js';
 import { checkVerify } from './checks/verify.js';
@@ -24,6 +26,7 @@ import { checkSubsidy, runSubsidyCommand } from './checks/subsidy.js';
 import { checkLoop, runLoopCommand } from './checks/loop.js';
 import { checkBloat, runBloatCommand } from './checks/bloat.js';
 import { checkGuard, runGuardCommand } from './checks/guard.js';
+import { checkExplain, runExplainCommand } from './checks/explain.js';
 import { checkCompleteness } from './checks/completeness.js';
 import { score } from './scorer.js';
 import { reportPretty, reportJSON, reportBadge } from './reporter.js';
@@ -77,6 +80,7 @@ if (flags.has('--help') || flags.has('-h')) {
     npx @safetnsr/vet loop [log]         /loop session forensics — per-iteration timeline
     npx @safetnsr/vet bloat              detect agent-generated code bloat
     npx @safetnsr/vet guard [dir]        scan for destructive operation bomb sites
+    npx @safetnsr/vet explain [--since REF] [--verbose] [--json]  risk-tier agent changes
 
   ${c.dim}categories:${c.reset}
     security   (30%)  scan, secrets, config, model usage
@@ -112,7 +116,7 @@ if (flags.has('--version') || flags.has('-v')) {
     }
     process.exit(0);
 }
-const COMMANDS = ['init', 'receipt', 'map', 'permissions', 'compact', 'subsidy', 'loop', 'bloat', 'guard'];
+const COMMANDS = ['init', 'receipt', 'map', 'permissions', 'compact', 'subsidy', 'loop', 'bloat', 'guard', 'explain'];
 const command = COMMANDS.includes(positional[0]) ? positional[0] : undefined;
 const cwd = resolve(positional.find(p => !COMMANDS.includes(p)) || '.');
 const isCI = flags.has('--ci');
@@ -254,6 +258,19 @@ if (command === 'guard') {
     }
     process.exit(0);
 }
+if (command === 'explain') {
+    try {
+        const format = isJSON ? 'json' : 'ascii';
+        const useAI = flags.has('--ai');
+        const verbose = flags.has('--verbose');
+        await runExplainCommand(format, cwd, since, useAI, verbose);
+    }
+    catch (e) {
+        console.error(`${c.red}explain failed:${c.reset}`, e instanceof Error ? e.message : e);
+        process.exit(1);
+    }
+    process.exit(0);
+}
 if (!isGitRepo(cwd)) {
     console.error(`${c.red}not a git repository${c.reset}. vet operates on git repos.`);
     process.exit(1);
@@ -305,7 +322,7 @@ async function runChecks() {
             }
         }
         // Run ALL independent checks in parallel
-        const [scanResult, secretsResult, configResult, modelsResult, owaspResult, permissionsResult, integrityResult, readyResult, debtResult, depsResult, receiptResult, compactResult, subsidyResult, memoryResult, verifyResult, testsResult, loopResult, completenessResult, bloatResult, guardResult,] = await Promise.all([
+        const [scanResult, secretsResult, configResult, modelsResult, owaspResult, permissionsResult, integrityResult, readyResult, debtResult, depsResult, receiptResult, compactResult, subsidyResult, memoryResult, verifyResult, testsResult, loopResult, completenessResult, bloatResult, guardResult, explainResult, architectureResult, aireadyResult,] = await Promise.all([
             withTimeout('scan', () => checkScan(cwd)),
             withTimeout('secrets', () => checkSecrets(cwd)),
             withTimeout('config', () => checkConfig(cwd, ignore)),
@@ -326,6 +343,9 @@ async function runChecks() {
             withTimeout('completeness', () => checkCompleteness(cwd, ignore)),
             withTimeout('bloat', () => checkBloat(cwd)),
             withTimeout('guard', () => checkGuard(cwd)),
+            withTimeout('explain', () => checkExplain(cwd, since)),
+            withTimeout('architecture', () => checkArchitecture(cwd)),
+            withTimeout('aiready', () => checkAIReady(cwd)),
         ]);
         // Git-dependent checks (diff + history) — parallel with each other
         const [diffResult, historyResult] = await Promise.all([
@@ -336,9 +356,11 @@ async function runChecks() {
         clearCache();
         return score(cwd, {
             security: [scanResult, secretsResult, configResult, modelsResult, owaspResult, permissionsResult, subsidyResult, guardResult],
-            integrity: [diffResult, integrityResult, receiptResult, compactResult, memoryResult, verifyResult, testsResult, loopResult, completenessResult],
+            integrity: [diffResult, integrityResult, receiptResult, compactResult, memoryResult, verifyResult, testsResult, loopResult, completenessResult, explainResult],
             debt: [readyResult, historyResult, debtResult, bloatResult],
             deps: [depsResult],
+            architecture: [architectureResult],
+            aiready: [aireadyResult],
         });
     }
     catch (e) {

package/dist/scorer.d.ts

@@ -4,5 +4,7 @@ export interface CheckMap {
     integrity: CheckResult[];
     debt: CheckResult[];
     deps: CheckResult[];
+    architecture: CheckResult[];
+    aiready: CheckResult[];
 }
 export declare function score(project: string, checkMap: CheckMap): VetResult;

package/dist/types.d.ts

@@ -14,7 +14,7 @@ export interface Issue {
     fixHint?: string;
 }
 export interface CategoryResult {
-    name: 'security' | 'integrity' | 'debt' | 'deps';
+    name: 'security' | 'integrity' | 'debt' | 'deps' | 'architecture' | 'aiready';
     score: number;
     weight: number;
     checks: CheckResult[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safetnsr/vet",
-  "version": "1.17.1",
+  "version": "1.18.0",
   "description": "vet your AI-generated code — one command, one score card, one letter grade",
   "type": "module",
   "bin": {