@safetnsr/vet 1.19.2 → 1.20.0

package/dist/checks/architecture.js

@@ -109,6 +109,116 @@ function findCycles(moduleGraph) {
         return true;
     });
 }
+function louvainCommunities(graph) {
+    const nodes = Array.from(graph.keys());
+    if (nodes.length < 2) {
+        return { modularity: 0, communities: new Map(), communityCount: 0 };
+    }
+    // Build undirected weighted adjacency (edge count = weight)
+    const adj = new Map();
+    for (const n of nodes) {
+        adj.set(n, new Map());
+    }
+    let totalEdges = 0;
+    for (const [from, deps] of graph) {
+        for (const to of deps) {
+            if (!adj.has(to)) {
+                adj.set(to, new Map());
+            }
+            // Undirected: add both directions
+            const w = (adj.get(from).get(to) || 0) + 1;
+            adj.get(from).set(to, w);
+            adj.get(to).set(from, w);
+            totalEdges++;
+        }
+    }
+    if (totalEdges === 0) {
+        return { modularity: 0, communities: new Map(), communityCount: 0 };
+    }
+    const m = totalEdges; // total edge weight
+    const m2 = 2 * m;
+    // Degree of each node (sum of edge weights)
+    const degree = new Map();
+    for (const [n, neighbors] of adj) {
+        let d = 0;
+        for (const w of neighbors.values())
+            d += w;
+        degree.set(n, d);
+    }
+    // Initialize: each node in its own community
+    const community = new Map();
+    nodes.forEach((n, i) => community.set(n, i));
+    // Community totals: sum of degrees in each community
+    const commDegree = new Map();
+    const commInternal = new Map(); // sum of internal edges × 2
+    for (const [n, c] of community) {
+        commDegree.set(c, degree.get(n) || 0);
+        commInternal.set(c, 0);
+    }
+    // Iterative optimization (1 pass — good enough for code graphs)
+    let moved = true;
+    let iterations = 0;
+    while (moved && iterations < 10) {
+        moved = false;
+        iterations++;
+        for (const node of nodes) {
+            const nodeDeg = degree.get(node) || 0;
+            const currentComm = community.get(node);
+            // Calculate edges to each neighboring community
+            const commEdges = new Map();
+            const neighbors = adj.get(node) || new Map();
+            for (const [neighbor, weight] of neighbors) {
+                const nc = community.get(neighbor);
+                if (nc !== undefined) {
+                    commEdges.set(nc, (commEdges.get(nc) || 0) + weight);
+                }
+            }
+            // Modularity gain for moving node to community c:
+            // ΔQ = [Σin + 2*ki,in] / 2m - [(Σtot + ki) / 2m]² - [Σin/2m - (Σtot/2m)² - (ki/2m)²]
+            let bestComm = currentComm;
+            let bestGain = 0;
+            // Remove node from current community
+            const edgesToCurrent = commEdges.get(currentComm) || 0;
+            for (const [targetComm, edgesToTarget] of commEdges) {
+                if (targetComm === currentComm)
+                    continue;
+                const sigmaTot = commDegree.get(targetComm) || 0;
+                const sigmaIn = commInternal.get(targetComm) || 0;
+                // Simplified modularity gain
+                const gain = (edgesToTarget / m) - (sigmaTot * nodeDeg) / (m2 * m);
+                if (gain > bestGain) {
+                    bestGain = gain;
+                    bestComm = targetComm;
+                }
+            }
+            if (bestComm !== currentComm) {
+                // Move node
+                commDegree.set(currentComm, (commDegree.get(currentComm) || 0) - nodeDeg);
+                commInternal.set(currentComm, (commInternal.get(currentComm) || 0) - 2 * edgesToCurrent);
+                commDegree.set(bestComm, (commDegree.get(bestComm) || 0) + nodeDeg);
+                const edgesToBest = commEdges.get(bestComm) || 0;
+                commInternal.set(bestComm, (commInternal.get(bestComm) || 0) + 2 * edgesToBest);
+                community.set(node, bestComm);
+                moved = true;
+            }
+        }
+    }
+    // Calculate final modularity Q
+    let Q = 0;
+    for (const [n1, neighbors] of adj) {
+        for (const [n2, w] of neighbors) {
+            if (community.get(n1) === community.get(n2)) {
+                const d1 = degree.get(n1) || 0;
+                const d2 = degree.get(n2) || 0;
+                Q += w - (d1 * d2) / m2;
+            }
+        }
+    }
+    Q /= m2;
+    // Count unique communities
+    const uniqueComms = new Set(community.values());
+    return { modularity: Q, communities: community, communityCount: uniqueComms.size };
+}
 // ── Main check ───────────────────────────────────────────────────────────────
 export function checkArchitecture(cwd) {
     const allFiles = walkFiles(cwd);
@@ -258,6 +368,28 @@ export function checkArchitecture(cwd) {
             fixHint: 'use barrel exports (index.ts) to define module boundaries',
         });
     }
+    // ── Louvain modularity ─────────────────────────────────────────────────
+    const louvain = louvainCommunities(moduleGraph);
+    if (moduleGraph.size >= 3) {
+        if (louvain.modularity < 0.3 && louvain.communityCount > 1) {
+            issues.push({
+                severity: 'warning',
+                message: `low modularity: Q=${louvain.modularity.toFixed(2)} (${louvain.communityCount} communities detected) — modules are too interconnected`,
+                file: '',
+                fixable: true,
+                fixHint: 'reduce cross-module dependencies, group related files into cohesive modules',
+            });
+        }
+        else if (louvain.communityCount <= 1 && moduleGraph.size > 5) {
+            issues.push({
+                severity: 'info',
+                message: `monolithic structure: all ${moduleGraph.size} modules form a single community — no clear architectural boundaries`,
+                file: '',
+                fixable: true,
+                fixHint: 'introduce module boundaries with clear interfaces (barrel exports)',
+            });
+        }
+    }
     // ── Scoring ───────────────────────────────────────────────────────────────
     const moduleCount = moduleGraph.size;
     const sizeScale = moduleCount <= 5 ? 1.0 : Math.max(0.3, 1.0 - Math.log10(moduleCount / 5) * 0.3);
@@ -266,11 +398,17 @@ export function checkArchitecture(cwd) {
     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;
+    // Modularity penalty: low Q on non-trivial graphs
+    if (moduleGraph.size >= 5 && louvain.modularity < 0.3) {
+        score -= Math.min(15, Math.round((0.3 - louvain.modularity) * 50));
+    }
     score = Math.max(25, Math.round(score));
     // ── Summary ───────────────────────────────────────────────────────────────
     const parts = [];
     parts.push(`${moduleGraph.size} modules`);
-    parts.push(`${edges.length} import edges`);
+    parts.push(`${edges.length} edges`);
+    if (louvain.communityCount > 0)
+        parts.push(`Q=${louvain.modularity.toFixed(2)} (${louvain.communityCount} communities)`);
     if (cycles.length > 0)
         parts.push(c.red + `${cycles.length} circular dep${cycles.length !== 1 ? 's' : ''}` + c.reset);
     if (godFiles.length > 0)

package/dist/checks/deep.js

@@ -110,6 +110,98 @@ function analyzeFunction(node, file, src) {
         cognitiveComplexity: cognitive,
     };
 }
+// ── Halstead metrics + Maintainability Index ────────────────────────────────
+const OPERATOR_KINDS = new Set([
+    ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken, ts.SyntaxKind.AsteriskToken,
+    ts.SyntaxKind.SlashToken, ts.SyntaxKind.PercentToken, ts.SyntaxKind.EqualsToken,
+    ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.MinusEqualsToken,
+    ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.SlashEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.LessThanToken, ts.SyntaxKind.GreaterThanToken,
+    ts.SyntaxKind.LessThanEqualsToken, ts.SyntaxKind.GreaterThanEqualsToken,
+    ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken,
+    ts.SyntaxKind.ExclamationToken, ts.SyntaxKind.QuestionQuestionToken,
+    ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken,
+    ts.SyntaxKind.AmpersandToken, ts.SyntaxKind.BarToken,
+    ts.SyntaxKind.CaretToken, ts.SyntaxKind.TildeToken,
+    ts.SyntaxKind.DotDotDotToken,
+]);
+const KEYWORD_OPERATOR_KINDS = new Set([
+    ts.SyntaxKind.IfStatement, ts.SyntaxKind.ElseKeyword,
+    ts.SyntaxKind.ForStatement, ts.SyntaxKind.ForInStatement, ts.SyntaxKind.ForOfStatement,
+    ts.SyntaxKind.WhileStatement, ts.SyntaxKind.DoStatement,
+    ts.SyntaxKind.SwitchStatement, ts.SyntaxKind.CaseClause,
+    ts.SyntaxKind.ReturnStatement, ts.SyntaxKind.ThrowStatement,
+    ts.SyntaxKind.TryStatement, ts.SyntaxKind.CatchClause,
+    ts.SyntaxKind.NewExpression, ts.SyntaxKind.DeleteExpression,
+    ts.SyntaxKind.TypeOfExpression, ts.SyntaxKind.VoidExpression,
+    ts.SyntaxKind.AwaitExpression, ts.SyntaxKind.YieldExpression,
+]);
+function computeHalstead(src) {
+    const operators = new Map();
+    const operands = new Map();
+    function countToken(map, key) {
+        map.set(key, (map.get(key) || 0) + 1);
+    }
+    function walk(node) {
+        // Operators: binary/unary/assignment operators + keyword operators
+        if (ts.isBinaryExpression(node)) {
+            countToken(operators, ts.SyntaxKind[node.operatorToken.kind]);
+        }
+        else if (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) {
+            countToken(operators, ts.SyntaxKind[node.operator]);
+        }
+        else if (KEYWORD_OPERATOR_KINDS.has(node.kind)) {
+            countToken(operators, ts.SyntaxKind[node.kind]);
+        }
+        else if (ts.isCallExpression(node)) {
+            countToken(operators, 'Call');
+        }
+        else if (ts.isPropertyAccessExpression(node)) {
+            countToken(operators, 'PropertyAccess');
+        }
+        // Operands: identifiers, literals
+        if (ts.isIdentifier(node)) {
+            countToken(operands, node.text);
+        }
+        else if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+            countToken(operands, `"${node.text.slice(0, 20)}"`);
+        }
+        else if (ts.isNumericLiteral(node)) {
+            countToken(operands, node.text);
+        }
+        ts.forEachChild(node, walk);
+    }
+    walk(src);
+    const n1 = operators.size;
+    const n2 = operands.size;
+    const N1 = Array.from(operators.values()).reduce((a, b) => a + b, 0);
+    const N2 = Array.from(operands.values()).reduce((a, b) => a + b, 0);
+    const n = n1 + n2;
+    const N = N1 + N2;
+    const volume = n > 0 ? N * Math.log2(n) : 0;
+    const difficulty = n2 > 0 ? (n1 / 2) * (N2 / n2) : 0;
+    const effort = difficulty * volume;
+    return {
+        operators: N1, operands: N2,
+        uniqueOperators: n1, uniqueOperands: n2,
+        vocabulary: n, length: N,
+        volume, difficulty, effort,
+    };
+}
+function computeMI(halsteadVolume, cyclomatic, sloc) {
+    // Standard Maintainability Index formula (SEI, 1992)
+    // MI = 171 - 5.2 × ln(V) - 0.23 × CC - 16.2 × ln(SLOC)
+    // Clamped to [0, 100]
+    if (halsteadVolume <= 0 || sloc <= 0)
+        return 100;
+    const mi = 171
+        - 5.2 * Math.log(halsteadVolume)
+        - 0.23 * cyclomatic
+        - 16.2 * Math.log(sloc);
+    return Math.max(0, Math.min(100, mi));
+}
 // ── Naming analysis (heuristic, no ML) ──────────────────────────────────────
 function isDescriptiveName(name) {
     if (name.startsWith('('))
@@ -130,6 +222,7 @@ export async function checkDeep(cwd) {
     }
     const issues = [];
     const allMetrics = [];
+    const allFileMetrics = [];
     const t0 = Date.now();
     for (const file of sourceFiles) {
         const content = readFile(join(cwd, file));
@@ -137,16 +230,25 @@ export async function checkDeep(cwd) {
             continue;
         try {
             const src = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+            // Per-function analysis
+            let fileCyclomatic = 1; // base complexity
             function visit(node) {
                 if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) ||
                     ts.isMethodDeclaration(node) || ts.isArrowFunction(node)) {
                     const metrics = analyzeFunction(node, file, src);
-                    if (metrics)
+                    if (metrics) {
                         allMetrics.push(metrics);
+                        fileCyclomatic += metrics.cyclomatic - 1; // add function's complexity
+                    }
                 }
                 ts.forEachChild(node, visit);
             }
             visit(src);
+            // Per-file: Halstead + MI
+            const halstead = computeHalstead(src);
+            const sloc = content.split('\n').filter(l => l.trim() && !l.trim().startsWith('//')).length;
+            const mi = computeMI(halstead.volume, fileCyclomatic, sloc);
+            allFileMetrics.push({ file, sloc, cyclomatic: fileCyclomatic, halstead, maintainabilityIndex: mi });
         }
         catch {
             // Skip files that can't be parsed
@@ -243,6 +345,27 @@ export async function checkDeep(cwd) {
             fixHint: 'use descriptive verb+noun function names (e.g., calculateTotal, validateUser)',
         });
     }
+    // ── Maintainability Index ──────────────────────────────────────────────────
+    const lowMI = allFileMetrics.filter(f => f.maintainabilityIndex < 20).sort((a, b) => a.maintainabilityIndex - b.maintainabilityIndex);
+    const mediumMI = allFileMetrics.filter(f => f.maintainabilityIndex >= 20 && f.maintainabilityIndex < 40);
+    for (const fm of lowMI.slice(0, 3)) {
+        issues.push({
+            severity: 'warning',
+            message: `low maintainability: ${fm.file} has MI=${fm.maintainabilityIndex.toFixed(0)} (halstead volume ${fm.halstead.volume.toFixed(0)}, CC ${fm.cyclomatic}, ${fm.sloc} SLOC)`,
+            file: fm.file,
+            fixable: true,
+            fixHint: 'reduce complexity and file size — split into smaller modules',
+        });
+    }
+    if (mediumMI.length > 5) {
+        issues.push({
+            severity: 'info',
+            message: `${mediumMI.length} files with moderate maintainability (MI 20-40)`,
+            file: mediumMI[0].file,
+            fixable: true,
+            fixHint: 'consider refactoring the most complex files',
+        });
+    }
     // ── Scoring ───────────────────────────────────────────────────────────────
     const total = allMetrics.length;
     // Complexity score: % of functions below threshold
@@ -257,13 +380,22 @@ export async function checkDeep(cwd) {
     // Naming score
     const namingOk = allMetrics.filter(f => isDescriptiveName(f.name) === 'good').length;
     const namingScore = Math.round((namingOk / total) * 100);
-    const score = Math.max(25, Math.round(complexityScore * 0.35 +
-        nestingScore * 0.25 +
-        errorScore * 0.25 +
-        namingScore * 0.15));
+    // Maintainability Index score: average MI across files, normalized to 0-100
+    const avgMI = allFileMetrics.length > 0
+        ? allFileMetrics.reduce((sum, f) => sum + f.maintainabilityIndex, 0) / allFileMetrics.length
+        : 100;
+    const miScore = Math.round(avgMI);
+    const score = Math.max(25, Math.round(complexityScore * 0.25 +
+        nestingScore * 0.20 +
+        errorScore * 0.20 +
+        namingScore * 0.10 +
+        miScore * 0.25));
     // ── Summary ───────────────────────────────────────────────────────────────
     const parts = [];
-    parts.push(`${total} functions analyzed in ${elapsed}ms`);
+    parts.push(`${total} functions, ${allFileMetrics.length} files in ${elapsed}ms`);
+    parts.push(`avg MI=${avgMI.toFixed(0)}`);
+    if (lowMI.length > 0)
+        parts.push(c.red + `${lowMI.length} unmaintainable` + c.reset);
     if (highComplexity.length > 0)
         parts.push(c.yellow + `${highComplexity.length} complex` + c.reset);
     if (deeplyNested.length > 0)

package/package.json

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