@toolbaux/guardian 0.1.0

package/dist/commands/test-coverage-mapper.js

@@ -0,0 +1,264 @@
+/**
+ * FEATURE 3: TEST COVERAGE MAPPER
+ *
+ * Visual heatmap showing test coverage per module, endpoint, and data flow
+ * Identifies untested high-coupling files and recommends tests
+ *
+ * Benchmarking: Medium complexity
+ * Problem Domain: Quality Assurance, Test Planning
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Main function: Generate coverage heatmap
+ */
+export async function generateCoverageHeatmap(options) {
+    const { srcRoot, testRoot, output, highCouplingThreshold = 0.5 } = options;
+    // Scan source files
+    const sourceFiles = await scanSourceFiles(srcRoot);
+    // Scan test files
+    const testFiles = await scanTestFiles(testRoot);
+    // Map tests to source files
+    const coverage = mapTestCoverage(sourceFiles, testFiles);
+    // Identify high-coupling files (from coupling scores in architecture context)
+    const highCouplingFiles = identifyHighCouplingFiles(sourceFiles, highCouplingThreshold);
+    // Find gaps
+    const gaps = identifyGaps(coverage, highCouplingFiles);
+    // Calculate overall metrics
+    const totalLines = coverage.reduce((sum, c) => sum + c.totalLines, 0);
+    const coveredLines = coverage.reduce((sum, c) => sum + c.linesCovered, 0);
+    const overallCoverage = totalLines > 0 ? (coveredLines / totalLines) * 100 : 0;
+    const heatmap = {
+        modules: coverage,
+        timestamp: new Date().toISOString(),
+        overallCoverage,
+        criticalGaps: gaps.filter((g) => g.severity === "critical").length,
+        riskScore: calculateRiskScore(coverage, overallCoverage),
+        recommendations: generateRecommendations(coverage, gaps),
+    };
+    if (output) {
+        await writeHeatmapReport(heatmap, output);
+    }
+    return heatmap;
+}
+/**
+ * Helper: Scan source files
+ */
+async function scanSourceFiles(srcRoot) {
+    const files = new Map();
+    async function walkDir(dir) {
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory() &&
+                    [".git", "node_modules", "dist", "build", "coverage"].includes(entry.name)) {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    await walkDir(fullPath);
+                }
+                else if (entry.isFile() &&
+                    [".ts", ".tsx", ".js", ".jsx"].some((ext) => entry.name.endsWith(ext))) {
+                    const content = await fs.readFile(fullPath, "utf8");
+                    const relPath = path.relative(srcRoot, fullPath);
+                    files.set(relPath, content);
+                }
+            }
+        }
+        catch {
+            // Skip inaccessible directories
+        }
+    }
+    await walkDir(srcRoot);
+    return files;
+}
+/**
+ * Helper: Scan test files
+ */
+async function scanTestFiles(testRoot) {
+    const files = new Map();
+    async function walkDir(dir) {
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory() && [".git", "node_modules"].includes(entry.name)) {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    await walkDir(fullPath);
+                }
+                else if (entry.isFile() &&
+                    (entry.name.endsWith(".test.ts") ||
+                        entry.name.endsWith(".test.js") ||
+                        entry.name.endsWith(".spec.ts") ||
+                        entry.name.endsWith(".spec.js"))) {
+                    const content = await fs.readFile(fullPath, "utf8");
+                    const relPath = path.relative(testRoot, fullPath);
+                    files.set(relPath, content);
+                }
+            }
+        }
+        catch {
+            // Skip inaccessible directories
+        }
+    }
+    await walkDir(testRoot);
+    return files;
+}
+/**
+ * Helper: Map test coverage to source files
+ */
+function mapTestCoverage(sourceFiles, testFiles) {
+    const coverage = [];
+    for (const [sourcePath, sourceContent] of sourceFiles.entries()) {
+        const lineCount = sourceContent.split("\n").length;
+        const testers = [];
+        // Find tests that reference this file
+        for (const [testPath, testContent] of testFiles.entries()) {
+            const sourceFileName = path.basename(sourcePath, path.extname(sourcePath));
+            if (testContent.includes(sourceFileName) ||
+                testContent.includes(sourcePath) ||
+                testPath.includes(sourceFileName)) {
+                testers.push(testPath);
+            }
+        }
+        // Estimate coverage based on test presence
+        const estimatedCoverage = testers.length > 0 ? calculateEstimatedCoverage(sourceContent) : 0;
+        coverage.push({
+            module: sourcePath,
+            linesCovered: Math.floor((estimatedCoverage / 100) * lineCount),
+            totalLines: lineCount,
+            coverage: estimatedCoverage,
+            level: getCoverageLevel(estimatedCoverage),
+            testers,
+            gaps: [],
+        });
+    }
+    return coverage;
+}
+/**
+ * Helper: Calculate estimated coverage by analysing function complexity
+ */
+function calculateEstimatedCoverage(content) {
+    // Simple heuristic: count exported functions/classes
+    const exports = (content.match(/export\s+(function|class|interface|type)/g) || [])
+        .length;
+    const complexFunctions = (content.match(/function\s+\w+\s*\([^)]*\)\s*\{[^}]*if|for|switch/g) || []).length;
+    // If we have exports, assume 60% base coverage + complexity bonus
+    if (exports > 0) {
+        return Math.min(90, 60 + complexFunctions * 5);
+    }
+    return Math.min(60, complexFunctions * 10);
+}
+/**
+ * Helper: Determine coverage level
+ */
+function getCoverageLevel(coverage) {
+    if (coverage >= 80)
+        return "full";
+    if (coverage >= 60)
+        return "partial";
+    if (coverage >= 30)
+        return "minimal";
+    return "none";
+}
+/**
+ * Helper: Identify high-coupling files
+ */
+function identifyHighCouplingFiles(sourceFiles, threshold) {
+    // Known high-coupling patterns
+    const highCouplingPatterns = /extract|adapter|index|types|config/i;
+    const highCoupling = new Set();
+    for (const filePath of sourceFiles.keys()) {
+        if (highCouplingPatterns.test(filePath)) {
+            highCoupling.add(filePath);
+        }
+    }
+    return highCoupling;
+}
+/**
+ * Helper: Identify coverage gaps
+ */
+function identifyGaps(coverage, highCouplingFiles) {
+    const gaps = [];
+    for (const metrics of coverage) {
+        const isHighCoupling = highCouplingFiles.has(metrics.module);
+        if (metrics.coverage < 50) {
+            gaps.push({
+                location: metrics.module,
+                severity: isHighCoupling ? "critical" : "high",
+                reason: `Low coverage on ${isHighCoupling ? "high-coupling" : "important"} module`,
+                suggestedTest: `Add integration tests for ${path.basename(metrics.module)}`,
+            });
+        }
+        else if (metrics.coverage < 70 && isHighCoupling) {
+            gaps.push({
+                location: metrics.module,
+                severity: "high",
+                reason: `Partial coverage on high-coupling file`,
+                suggestedTest: `Increase coverage: add edge case tests`,
+            });
+        }
+    }
+    return gaps;
+}
+/**
+ * Helper: Calculate risk score (0-100)
+ */
+function calculateRiskScore(coverage, overallCoverage) {
+    // Find untested high-coupling files
+    const untested = coverage.filter((c) => c.coverage === 0 && c.module.match(/extract|adapter|index|types/i)).length;
+    // Score based on overall coverage + untested critical files
+    let score = Math.max(0, 100 - overallCoverage + untested * 10);
+    return Math.min(100, score);
+}
+/**
+ * Helper: Generate recommendations
+ */
+function generateRecommendations(coverage, gaps) {
+    const recommendations = [];
+    const criticalGapsCount = gaps.filter((g) => g.severity === "critical").length;
+    if (criticalGapsCount > 0) {
+        recommendations.push(`🚨 ${criticalGapsCount} critical test gaps: High-coupling files lack tests`);
+    }
+    const untestedCount = coverage.filter((c) => c.coverage === 0).length;
+    if (untestedCount > 0) {
+        recommendations.push(`⚠️ ${untestedCount} modules with zero test coverage`);
+    }
+    const avgCoverage = coverage.reduce((sum, c) => sum + c.coverage, 0) / coverage.length;
+    if (avgCoverage < 60) {
+        recommendations.push(`💡 Average coverage ${avgCoverage.toFixed(1)}% is below 60%`);
+    }
+    if (gaps.length === 0) {
+        recommendations.push(`✅ No major test coverage gaps detected`);
+    }
+    return recommendations;
+}
+/**
+ * Helper: Write heatmap report to markdown
+ */
+async function writeHeatmapReport(heatmap, outputPath) {
+    let md = `# Test Coverage Heatmap Report\n\n`;
+    md += `Generated: ${heatmap.timestamp}\n\n`;
+    md += `## Summary\n`;
+    md += `- **Overall Coverage:** ${heatmap.overallCoverage.toFixed(1)}%\n`;
+    md += `- **Critical Gaps:** ${heatmap.criticalGaps}\n`;
+    md += `- **Risk Score:** ${heatmap.riskScore}/100\n\n`;
+    // Coverage heatmap
+    md += `## Coverage Heatmap\n`;
+    md += `| Module | Coverage | Level | Tests |\n`;
+    md += `|--------|----------|-------|-------|\n`;
+    for (const m of heatmap.modules) {
+        const heat = m.coverage >= 80 ? "🟢" : m.coverage >= 60 ? "🟡" : m.coverage >= 30 ? "🟠" : "🔴";
+        md += `| ${m.module} | ${m.coverage.toFixed(1)}% | ${heat} ${m.level} | ${m.testers.length} |\n`;
+    }
+    md += `\n## Recommendations\n`;
+    for (const rec of heatmap.recommendations) {
+        md += `- ${rec}\n`;
+    }
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, md, "utf8");
+}
+export default generateCoverageHeatmap;

package/dist/commands/verify-drift.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { computeProjectDrift } from "../extract/drift.js";
+import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
+export async function runVerifyDrift(options) {
+    const resolved = await resolveProjectPaths({
+        projectRoot: options.projectRoot,
+        backendRoot: options.backendRoot,
+        frontendRoot: options.frontendRoot,
+        configPath: options.configPath
+    });
+    logResolvedProjectPaths(resolved);
+    const drift = await computeProjectDrift({
+        backendRoot: resolved.backendRoot,
+        frontendRoot: resolved.frontendRoot,
+        configPath: options.configPath
+    });
+    const config = resolved.config;
+    const projectRoot = resolved.workspaceRoot;
+    const baselinePath = options.baseline || config.drift?.baselinePath || "specs-out/baseline.json";
+    const resolvedBaseline = path.isAbsolute(baselinePath)
+        ? baselinePath
+        : path.resolve(projectRoot, baselinePath);
+    let baselinePayload = null;
+    try {
+        const raw = await fs.readFile(resolvedBaseline, "utf8");
+        baselinePayload = JSON.parse(raw);
+    }
+    catch (error) {
+        console.log(`[Warning] Could not load baseline at ${resolvedBaseline}`);
+    }
+    const threshold = options.strictThreshold ? parseFloat(options.strictThreshold) : 0.15;
+    console.log("=========================================");
+    console.log("SpecGuard Drift Verification");
+    console.log("=========================================\n");
+    console.log(`Current Status: ${drift.status}`);
+    console.log(`Current Delta:  ${drift.delta.toFixed(4)}`);
+    console.log(`Current K_t:    ${drift.K_t.toFixed(4)}`);
+    let failed = false;
+    if (drift.status === "critical") {
+        console.error(`\n[ERROR] Drift status is "critical". Reached critical capacity limits.`);
+        failed = true;
+    }
+    if (baselinePayload && baselinePayload.drift) {
+        const baselineDelta = baselinePayload.drift.delta ?? 0;
+        const shift = Math.abs(drift.delta - baselineDelta);
+        console.log(`\nBaseline Delta: ${baselineDelta.toFixed(4)}`);
+        console.log(`Coupling Shift: ${shift.toFixed(4)} (Threshold: ${threshold})`);
+        if (shift > threshold) {
+            console.error(`\n[ERROR] Architectural coupling shift (${shift.toFixed(4)}) exceeded strict threshold (${threshold}).`);
+            failed = true;
+        }
+    }
+    console.log("=========================================");
+    if (failed) {
+        console.error("Verification FAILED. Architectural drift guardrails breached.");
+        process.exit(1);
+    }
+    else {
+        console.log("Verification PASSED. Architecture remains within acceptable limits.");
+    }
+}