@toolbaux/guardian 0.1.0

package/dist/commands/breaking-change-analyzer.js

@@ -0,0 +1,334 @@
+/**
+ * FEATURE 2: BREAKING CHANGE ANALYZER
+ *
+ * Detects when code changes will break dependent modules
+ * Analyzes endpoint signature changes, schema modifications, exports changes
+ *
+ * Benchmarking: Medium-High complexity
+ * Problem Domain: API Safety, Backwards Compatibility
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Main function: Analyze breaking changes between two versions
+ */
+export async function analyzeBreakingChanges(options) {
+    const { baselineDir, currentDir, output } = options;
+    const baselineFiles = await scanSourceFiles(baselineDir);
+    const currentFiles = await scanSourceFiles(currentDir);
+    const changes = [];
+    // Detect removed files (potential breaking changes)
+    for (const [filePath, _] of baselineFiles.entries()) {
+        if (!currentFiles.has(filePath)) {
+            changes.push({
+                type: "export_removed",
+                severity: "high",
+                location: filePath,
+                description: `File removed: ${filePath}`,
+                affectedModules: [filePath],
+            });
+        }
+    }
+    // Detect modified files
+    for (const [filePath, currentContent] of currentFiles.entries()) {
+        if (baselineFiles.has(filePath)) {
+            const baselineContent = baselineFiles.get(filePath);
+            const fileChanges = detectBreakingChangesInFile(filePath, baselineContent, currentContent);
+            changes.push(...fileChanges);
+        }
+    }
+    // Detect new required parameters
+    const newRequiredParams = detectNewRequiredParams(baselineFiles, currentFiles);
+    changes.push(...newRequiredParams);
+    // Calculate risk score
+    const riskScore = calculateRiskScore(changes);
+    const report = {
+        timestamp: new Date().toISOString(),
+        totalChanges: changes.length,
+        criticalChanges: changes.filter((c) => c.severity === "critical").length,
+        highChanges: changes.filter((c) => c.severity === "high").length,
+        changes,
+        riskScore,
+        recommendations: generateRecommendations(changes),
+    };
+    if (output) {
+        await writeReport(report, output);
+    }
+    return report;
+}
+/**
+ * Helper: Scan source files in directory
+ */
+async function scanSourceFiles(dir) {
+    const files = new Map();
+    async function walkDir(currentPath) {
+        try {
+            const entries = await fs.readdir(currentPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(currentPath, entry.name);
+                if (entry.isDirectory() &&
+                    [".git", "node_modules", "dist", "build"].includes(entry.name)) {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    await walkDir(fullPath);
+                }
+                else if (entry.isFile() &&
+                    [".ts", ".js", ".tsx"].some((ext) => entry.name.endsWith(ext))) {
+                    const content = await fs.readFile(fullPath, "utf8");
+                    const relPath = path.relative(dir, fullPath);
+                    files.set(relPath, content);
+                }
+            }
+        }
+        catch {
+            // Skip inaccessible directories
+        }
+    }
+    await walkDir(dir);
+    return files;
+}
+/**
+ * Helper: Detect breaking changes within a file
+ */
+function detectBreakingChangesInFile(filePath, baseline, current) {
+    const changes = [];
+    // Detect removed exports
+    const baselineExports = extractExports(baseline);
+    const currentExports = extractExports(current);
+    for (const exp of baselineExports) {
+        if (!currentExports.includes(exp)) {
+            changes.push({
+                type: "export_removed",
+                severity: "high",
+                location: `${filePath}:export:${exp}`,
+                description: `Exported symbol removed: ${exp}`,
+                affectedModules: [filePath],
+                suggestedFix: `Mark as deprecated instead of removing: @deprecated`,
+            });
+        }
+    }
+    // Detect endpoint removals (if applicable)
+    const baselineEndpoints = extractEndpoints(baseline);
+    const currentEndpoints = extractEndpoints(current);
+    for (const endpoint of baselineEndpoints) {
+        if (!currentEndpoints.includes(endpoint)) {
+            changes.push({
+                type: "endpoint_removed",
+                severity: "critical",
+                location: `${filePath}:endpoint:${endpoint}`,
+                description: `API endpoint removed: ${endpoint}`,
+                affectedModules: [filePath],
+                suggestedFix: `Maintain backwards compatibility with deprecation warnings`,
+            });
+        }
+    }
+    // Detect type changes
+    const typeChanges = detectTypeChanges(filePath, baseline, current);
+    changes.push(...typeChanges);
+    return changes;
+}
+/**
+ * Helper: Extract exported symbols
+ */
+function extractExports(content) {
+    const patterns = [
+        /export\s+(?:default\s+)?(?:class|function|interface|type|const)\s+(\w+)/g,
+        /export\s*\{\s*([^}]+)\s*\}/g,
+    ];
+    const exports = [];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            const names = match[1]
+                ?.split(",")
+                .map((n) => n.trim())
+                .filter((n) => n);
+            if (names) {
+                exports.push(...names);
+            }
+        }
+    }
+    return [...new Set(exports)];
+}
+/**
+ * Helper: Extract API endpoints
+ */
+function extractEndpoints(content) {
+    const patterns = [
+        /(?:router|app)\.(?:get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)/gi,
+        /route:\s*['"`]([^'"`]+)/gi,
+    ];
+    const endpoints = [];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            endpoints.push(match[1]);
+        }
+    }
+    return [...new Set(endpoints)];
+}
+/**
+ * Helper: Detect type signature changes
+ */
+function detectTypeChanges(filePath, baseline, current) {
+    const changes = [];
+    // Simple heuristic: check for interface/type field removals
+    const baselineInterfaces = extractInterfaces(baseline);
+    const currentInterfaces = extractInterfaces(current);
+    for (const [name, baselineFields] of baselineInterfaces.entries()) {
+        if (currentInterfaces.has(name)) {
+            const currentFields = currentInterfaces.get(name);
+            for (const field of baselineFields) {
+                if (!currentFields.includes(field)) {
+                    changes.push({
+                        type: "type_changed",
+                        severity: "high",
+                        location: `${filePath}:interface:${name}`,
+                        description: `Interface field removed: ${name}.${field}`,
+                        affectedModules: [filePath],
+                        suggestedFix: `Mark field as optional or deprecated: ${field}?`,
+                    });
+                }
+            }
+        }
+    }
+    return changes;
+}
+/**
+ * Helper: Extract interfaces and their fields
+ */
+function extractInterfaces(content) {
+    const interfaces = new Map();
+    // Simple regex to find interfaces
+    const pattern = /(?:interface|type)\s+(\w+)\s*(?:extends|=)?\s*\{([^}]+)\}/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const name = match[1];
+        const body = match[2];
+        // Extract field names
+        const fieldPattern = /\s*(\w+)\s*[?:]?/g;
+        const fields = [];
+        let fieldMatch;
+        while ((fieldMatch = fieldPattern.exec(body)) !== null) {
+            fields.push(fieldMatch[1]);
+        }
+        interfaces.set(name, fields);
+    }
+    return interfaces;
+}
+/**
+ * Helper: Detect new required parameters
+ */
+function detectNewRequiredParams(baseline, current) {
+    const changes = [];
+    // Look for function signatures that gained required params
+    for (const [filePath, currentContent] of current.entries()) {
+        if (!baseline.has(filePath))
+            continue;
+        const baselineContent = baseline.get(filePath);
+        const baseFunctions = extractFunctions(baselineContent);
+        const currentFunctions = extractFunctions(currentContent);
+        for (const [funcName, baselineParams] of baseFunctions.entries()) {
+            if (currentFunctions.has(funcName)) {
+                const currentParams = currentFunctions.get(funcName);
+                if (currentParams.length > baselineParams.length) {
+                    const newParams = currentParams.slice(baselineParams.length);
+                    changes.push({
+                        type: "required_parameter_added",
+                        severity: "high",
+                        location: `${filePath}:function:${funcName}`,
+                        description: `Required parameters added: ${newParams.join(", ")}`,
+                        affectedModules: [filePath],
+                        suggestedFix: `Make new parameters optional with defaults`,
+                    });
+                }
+            }
+        }
+    }
+    return changes;
+}
+/**
+ * Helper: Extract function signatures
+ */
+function extractFunctions(content) {
+    const functions = new Map();
+    const pattern = /(?:async\s+)?(?:export\s+)?function\s+(\w+)\s*\(([^)]*)\)/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const funcName = match[1];
+        const paramsStr = match[2];
+        const params = paramsStr
+            .split(",")
+            .map((p) => p.trim().split(":")[0])
+            .filter((p) => p);
+        functions.set(funcName, params);
+    }
+    return functions;
+}
+/**
+ * Helper: Calculate overall risk score
+ */
+function calculateRiskScore(changes) {
+    if (changes.length === 0)
+        return 0;
+    const criticalWeight = 25;
+    const highWeight = 10;
+    const mediumWeight = 5;
+    const lowWeight = 1;
+    const score = changes.filter((c) => c.severity === "critical").length * criticalWeight +
+        changes.filter((c) => c.severity === "high").length * highWeight +
+        changes.filter((c) => c.severity === "medium").length * mediumWeight +
+        changes.filter((c) => c.severity === "low").length * lowWeight;
+    return Math.min(score, 100);
+}
+/**
+ * Helper: Generate recommendations
+ */
+function generateRecommendations(changes) {
+    const recommendations = [];
+    if (changes.some((c) => c.severity === "critical")) {
+        recommendations.push("🚨 CRITICAL: Major breaking changes detected. Bump major version.");
+        recommendations.push("Consider deprecation period (3+ months) before removal.");
+    }
+    if (changes.some((c) => c.severity === "high")) {
+        recommendations.push("⚠️ HIGH: Multiple breaking changes. Request code review.");
+    }
+    if (changes.length > 5) {
+        recommendations.push("💡 Consider splitting this into multiple commits.");
+    }
+    if (changes.filter((c) => c.severity === "critical" || c.severity === "high")
+        .length === 0) {
+        recommendations.push("✅ No critical breaking changes detected.");
+    }
+    return recommendations;
+}
+/**
+ * Helper: Write report to markdown
+ */
+async function writeReport(report, outputPath) {
+    let md = `# Breaking Change Analysis Report\n\n`;
+    md += `Generated: ${report.timestamp}\n\n`;
+    md += `## Summary\n`;
+    md += `- **Total Changes:** ${report.totalChanges}\n`;
+    md += `- **Critical:** ${report.criticalChanges}\n`;
+    md += `- **High:** ${report.highChanges}\n`;
+    md += `- **Risk Score:** ${report.riskScore}/100\n\n`;
+    md += `## Changes\n`;
+    for (const change of report.changes) {
+        md += `### ${change.type} - ${change.severity}\n`;
+        md += `**Location:** ${change.location}\n`;
+        md += `${change.description}\n`;
+        if (change.suggestedFix) {
+            md += `**Fix:** ${change.suggestedFix}\n`;
+        }
+        md += `\n`;
+    }
+    md += `## Recommendations\n`;
+    for (const rec of report.recommendations) {
+        md += `- ${rec}\n`;
+    }
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, md, "utf8");
+}
+export default analyzeBreakingChanges;

package/dist/commands/config-compliance.js

@@ -0,0 +1,219 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Primary function: Scan config and check compliance
+ */
+export async function checkConfigCompliance(options) {
+    const { configPath, srcRoot, environments = ["dev", "test", "prod"], output } = options;
+    // Load config
+    let configContent;
+    try {
+        configContent = await fs.readFile(configPath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`Failed to read config at ${configPath}: ${err}`);
+    }
+    const config = parseConfigFile(configContent);
+    const configFields = flattenConfig(config);
+    // Scan source files for usage
+    const usageMap = await scanSourceFiles(srcRoot);
+    // Mark which fields are used
+    const checkedFields = configFields.map((field) => ({
+        ...field,
+        used: hasAnyUsage(field, usageMap),
+        usageCount: countUsage(field, usageMap),
+    }));
+    // Find dead config
+    const deadFields = checkedFields.filter((f) => !f.used);
+    // Find env inconsistencies
+    const envInconsistencies = findEnvironmentInconsistencies(configContent, environments);
+    const result = {
+        totalFields: configFields.length,
+        usedFields: checkedFields.filter((f) => f.used).length,
+        deadFields,
+        inconsistentAcrossEnv: envInconsistencies,
+        stats: {
+            usage: checkedFields.filter((f) => f.used).length,
+            deadConfig: deadFields.length,
+            envInconsistency: envInconsistencies.length,
+        },
+    };
+    if (output) {
+        await writeComplianceReport(result, output);
+    }
+    return result;
+}
+/**
+ * Helper: Parse config file (supports .ts, .json, .yaml)
+ */
+function parseConfigFile(content) {
+    // Simplified parser - in real impl would support YAML/TS as well
+    try {
+        // Try JSON first
+        return JSON.parse(content);
+    }
+    catch {
+        // Fallback to object literal extraction from TypeScript
+        const match = content.match(/const\s+DEFAULT_CONFIG[^=]*=\s*({[\s\S]*?})\s*;/);
+        if (match) {
+            // This is a simplified extraction - real implementation would use AST
+            return parseObjectLiteral(match[1]);
+        }
+        return {};
+    }
+}
+/**
+ * Helper: Flatten nested config into dot-notation paths
+ */
+function flattenConfig(obj, prefix = "") {
+    const result = [];
+    for (const [key, value] of Object.entries(obj)) {
+        const fullPath = prefix ? `${prefix}.${key}` : key;
+        if (value === null || value === undefined) {
+            continue;
+        }
+        if (typeof value === "object" && !Array.isArray(value)) {
+            result.push(...flattenConfig(value, fullPath));
+        }
+        else {
+            result.push({
+                path: fullPath,
+                value,
+                type: getType(value),
+                used: false,
+                usageCount: 0,
+                environments: new Set(),
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Helper: Scan all source files for config usage
+ */
+async function scanSourceFiles(srcRoot) {
+    const usageMap = new Map();
+    async function walkDir(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            // Skip common non-source directories
+            if (entry.isDirectory() &&
+                [".git", "node_modules", "dist", "build", ".next"].includes(entry.name)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await walkDir(fullPath);
+            }
+            else if (entry.isFile() &&
+                [".ts", ".js", ".tsx", ".jsx"].some((ext) => entry.name.endsWith(ext))) {
+                const content = await fs.readFile(fullPath, "utf8");
+                const matches = content.match(/config\.\w+/g) || [];
+                matches.forEach((match) => {
+                    const key = match.replace("config.", "");
+                    usageMap.set(key, (usageMap.get(key) ?? 0) + 1);
+                });
+            }
+        }
+    }
+    await walkDir(srcRoot);
+    return usageMap;
+}
+/**
+ * Helper: Check if a config field is used anywhere
+ */
+function hasAnyUsage(field, usageMap) {
+    // Check exact path
+    if (usageMap.has(field.path))
+        return true;
+    // Check prefix matches (e.g., "drift" for "drift.weights.entropy")
+    const prefix = field.path.split(".")[0];
+    return usageMap.has(prefix);
+}
+/**
+ * Helper: Count usages of a config field
+ */
+function countUsage(field, usageMap) {
+    return usageMap.get(field.path) ?? usageMap.get(field.path.split(".")[0]) ?? 0;
+}
+/**
+ * Helper: Find environment-specific inconsistencies
+ */
+function findEnvironmentInconsistencies(configContent, environments) {
+    // Simplified implementation - look for env-specific overrides
+    const inconsistencies = [];
+    // In real implementation, would parse env-specific configs and compare
+    for (const env of environments) {
+        const envRegex = new RegExp(`(${env}|process\\.env\\.${env.toUpperCase()})`, "gi");
+        if (envRegex.test(configContent)) {
+            // Found env-specific logic
+            // TODO: Compare values across envs for consistency
+        }
+    }
+    return inconsistencies;
+}
+/**
+ * Helper: Get type of a value
+ */
+function getType(value) {
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "object")
+        return "object";
+    if (typeof value === "string")
+        return "string";
+    if (typeof value === "number")
+        return "number";
+    if (typeof value === "boolean")
+        return "boolean";
+    return "unknown";
+}
+/**
+ * Helper: Parse object literal (simplified)
+ */
+function parseObjectLiteral(str) {
+    // This is a very simplified parser - real impl would use proper AST parsing
+    try {
+        // Wrap in object constructor syntax
+        const sanitized = str
+            .replace(/'/g, '"') // Convert single quotes to double
+            .replace(/,\s*}/g, "}") // Remove trailing commas
+            .replace(/,\s*]/g, "]");
+        return JSON.parse(`{${sanitized}}`);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Helper: Generate compliance report
+ */
+async function writeComplianceReport(result, outputPath) {
+    const timestamp = new Date().toISOString();
+    let report = `# Configuration Compliance Report\n\n`;
+    report += `Generated: ${timestamp}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Config Fields: ${result.totalFields}\n`;
+    report += `- Used Fields: ${result.usedFields} (${((result.usedFields / result.totalFields) * 100).toFixed(1)}%)\n`;
+    report += `- Dead Config: ${result.stats.deadConfig}\n`;
+    report += `- Environment Inconsistencies: ${result.stats.envInconsistency}\n\n`;
+    if (result.deadFields.length > 0) {
+        report += `## ⚠️ Dead Configuration Fields\n`;
+        report += `These fields are defined but never used:\n\n`;
+        result.deadFields.forEach((field) => {
+            report += `- \`${field.path}\` = ${JSON.stringify(field.value)}\n`;
+        });
+        report += `\n`;
+    }
+    if (result.inconsistentAcrossEnv.length > 0) {
+        report += `## ⚠️ Environment Inconsistencies\n`;
+        result.inconsistentAcrossEnv.forEach((field) => {
+            report += `- \`${field.path}\` differs across environments\n`;
+        });
+        report += `\n`;
+    }
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, report, "utf8");
+    console.log(`📋 Config compliance report written to ${outputPath}`);
+}
+export default checkConfigCompliance;