@toolbaux/guardian 0.1.0

package/dist/commands/constraints.js

@@ -0,0 +1,221 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { analyzeBackend } from "../extract/analyzers/backend.js";
+import { analyzeFrontend } from "../extract/analyzers/frontend.js";
+import { analyzeRuntime } from "../extract/runtime.js";
+import { computeDriftReport } from "../extract/drift.js";
+import { buildArchitectureSummary } from "../extract/compress.js";
+import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
+export async function runConstraints(options) {
+    const resolved = await resolveProjectPaths({
+        projectRoot: options.projectRoot,
+        backendRoot: options.backendRoot,
+        frontendRoot: options.frontendRoot,
+        configPath: options.configPath
+    });
+    const resolvedBackendRoot = resolved.backendRoot;
+    const resolvedFrontendRoot = resolved.frontendRoot;
+    const config = resolved.config;
+    logResolvedProjectPaths(resolved);
+    const backend = await analyzeBackend(resolvedBackendRoot, config);
+    const frontend = await analyzeFrontend(resolvedFrontendRoot, config);
+    const projectRoot = resolved.workspaceRoot;
+    const runtime = await analyzeRuntime(projectRoot, config);
+    const drift = await computeDriftReport({
+        backendRoot: resolvedBackendRoot,
+        modules: backend.modules,
+        moduleGraph: backend.moduleGraph,
+        fileGraph: backend.fileGraph,
+        circularDependencies: backend.circularDependencies,
+        config,
+        projectRoot
+    });
+    const architectureSummary = buildArchitectureSummary({
+        version: "1.0",
+        metadata: {
+            generated_at: new Date().toISOString(),
+            duration_ms: 0,
+            target_backend: resolvedBackendRoot,
+            target_frontend: resolvedFrontendRoot
+        },
+        project: {
+            name: deriveProjectName(resolvedBackendRoot),
+            workspace_root: resolved.workspaceRoot,
+            backend_root: resolvedBackendRoot,
+            frontend_root: resolvedFrontendRoot,
+            resolution_source: resolved.resolutionSource,
+            entrypoints: backend.entrypoints
+        },
+        modules: backend.modules,
+        frontend_files: frontend.files,
+        frontend: {
+            pages: frontend.pages,
+            api_calls: frontend.apiCalls
+        },
+        endpoints: backend.endpoints,
+        data_models: backend.dataModels,
+        enums: backend.enums,
+        constants: backend.constants,
+        endpoint_model_usage: backend.endpointModelUsage,
+        cross_stack_contracts: [],
+        tasks: backend.tasks,
+        runtime,
+        data_flows: [],
+        tests: [...backend.tests, ...frontend.tests],
+        dependencies: {
+            module_graph: backend.moduleGraph,
+            file_graph: []
+        },
+        drift,
+        analysis: {
+            circular_dependencies: backend.circularDependencies,
+            orphan_modules: backend.orphanModules,
+            orphan_files: backend.orphanFiles,
+            frontend_orphan_files: frontend.orphanFiles,
+            module_usage: backend.moduleUsage,
+            unused_exports: backend.unusedExports,
+            frontend_unused_exports: frontend.unusedExports,
+            unused_endpoints: [],
+            frontend_unused_api_calls: [],
+            duplicate_functions: backend.duplicateFunctions,
+            similar_functions: backend.similarFunctions,
+            test_coverage: {
+                untested_source_files: [],
+                test_files_missing_source: [],
+                coverage_map: []
+            },
+            endpoint_test_coverage: [],
+            function_test_coverage: []
+        }
+    }, {
+        version: "0.2",
+        components: frontend.components,
+        component_graph: frontend.componentGraph,
+        pages: frontend.uxPages
+    });
+    const cycleModules = Array.from(new Set(backend.circularDependencies.flatMap((cycle) => cycle)));
+    const constraints = {
+        version: "0.1",
+        generated_at: new Date().toISOString(),
+        project: {
+            name: deriveProjectName(resolvedBackendRoot)
+        },
+        drift: {
+            delta: drift.delta,
+            D_t: drift.D_t,
+            K_t: drift.K_t,
+            status: drift.status,
+            graph_level: drift.graph_level,
+            alerts: drift.alerts
+        },
+        capacity: drift.capacity,
+        growth: drift.growth,
+        cross_layer_edges: drift.details.cross_layer_edges,
+        allowed_dependencies: config.drift?.layers ?? {},
+        capacity_budgets: config.drift?.capacity ?? {},
+        cycle_risk_modules: cycleModules,
+        duplicate_functions: backend.duplicateFunctions.slice(0, 20),
+        similar_functions: backend.similarFunctions.slice(0, 20),
+        related_endpoints: findRelatedEndpoints(backend.endpoints.map((endpoint) => `${endpoint.method} ${endpoint.path}`)),
+        modules: backend.modules.map((module) => module.id),
+        endpoints: backend.endpoints.map((endpoint) => `${endpoint.method} ${endpoint.path}`),
+        models: backend.dataModels.map((model) => model.name),
+        architecture_fingerprint: architectureSummary.fingerprint,
+        shape_fingerprint: architectureSummary.shape_fingerprint,
+        prompt: renderPrompt({
+            drift,
+            cycleModules,
+            allowed: config.drift?.layers ?? {},
+            capacity: drift.capacity
+        })
+    };
+    const outputPath = path.resolve(options.output ?? "specs-out/constraints.json");
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, JSON.stringify(constraints, null, 2));
+    console.log(`Wrote ${outputPath}`);
+}
+function renderPrompt(params) {
+    const lines = [];
+    lines.push("SYSTEM:");
+    lines.push("You are operating inside a bounded architectural system.");
+    lines.push("");
+    lines.push("Constraints:");
+    lines.push(`- Current delta: ${params.drift.delta.toFixed(4)} (${params.drift.status})`);
+    if (params.capacity.total?.budget) {
+        lines.push(`- Total capacity: ${params.capacity.total.used}/${params.capacity.total.budget}`);
+    }
+    if (params.cycleModules.length > 0) {
+        lines.push(`- Avoid cycle-risk modules: ${params.cycleModules.join(", ")}`);
+    }
+    if (Object.keys(params.allowed).length > 0) {
+        lines.push("- Allowed dependency flow:");
+        for (const [layer, allowed] of Object.entries(params.allowed)) {
+            lines.push(`  - ${layer} -> ${allowed.join(", ") || "none"}`);
+        }
+    }
+    lines.push("");
+    lines.push("Your task:");
+    lines.push("- Implement the requested change without increasing cross-layer coupling.");
+    lines.push("- Prefer refactoring or reuse over new module creation.");
+    lines.push("- Do not introduce new cycles.");
+    lines.push("- Return a patch only.");
+    return lines.join("\n");
+}
+function findRelatedEndpoints(endpoints) {
+    const pairs = [];
+    const tokenized = endpoints.map((endpoint) => ({
+        endpoint,
+        tokens: tokenizeEndpoint(endpoint)
+    }));
+    const threshold = 0.8;
+    const maxPairs = 20;
+    for (let i = 0; i < tokenized.length; i += 1) {
+        for (let j = i + 1; j < tokenized.length; j += 1) {
+            const sim = jaccard(tokenized[i].tokens, tokenized[j].tokens);
+            if (sim >= threshold) {
+                pairs.push({
+                    similarity: round(sim, 2),
+                    endpoints: [tokenized[i].endpoint, tokenized[j].endpoint]
+                });
+                if (pairs.length >= maxPairs) {
+                    return pairs;
+                }
+            }
+        }
+    }
+    return pairs;
+}
+function tokenizeEndpoint(endpoint) {
+    return endpoint
+        .toLowerCase()
+        .replace(/[^a-z0-9/]+/g, " ")
+        .split(/[\\/\\s]+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+}
+function jaccard(a, b) {
+    const setA = new Set(a);
+    const setB = new Set(b);
+    if (setA.size === 0 || setB.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const entry of setA) {
+        if (setB.has(entry)) {
+            intersection += 1;
+        }
+    }
+    const union = setA.size + setB.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+function round(value, precision) {
+    const factor = 10 ** precision;
+    return Math.round(value * factor) / factor;
+}
+function deriveProjectName(backendRoot) {
+    const base = path.basename(path.resolve(backendRoot));
+    if (base.toLowerCase() === "backend" || base.toLowerCase() === "src") {
+        return path.basename(path.dirname(path.resolve(backendRoot)));
+    }
+    return base || "unknown";
+}

package/dist/commands/context.js

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { loadArchitectureDiff, loadHeatmap } from "../extract/compress.js";
+import { renderContextBlock } from "../extract/context-block.js";
+import { resolveMachineInputDir } from "../output-layout.js";
+export async function runContext(options) {
+    const inputDir = await resolveMachineInputDir(options.input || "specs-out");
+    const { architecture, ux } = await loadSnapshots(inputDir);
+    const [diff, heatmap] = await Promise.all([
+        loadArchitectureDiff(inputDir),
+        loadHeatmap(inputDir)
+    ]);
+    const content = renderContextBlock(architecture, ux, {
+        focusQuery: options.focus,
+        maxLines: normalizeMaxLines(options.maxLines),
+        diff,
+        heatmap
+    });
+    if (!options.output) {
+        console.log(content);
+        return;
+    }
+    const outputPath = path.resolve(options.output);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    const existing = await readIfExists(outputPath);
+    const next = injectIntoAutoContext(existing, content);
+    await fs.writeFile(outputPath, next, "utf8");
+    console.log(`Wrote ${outputPath}`);
+}
+async function loadSnapshots(inputDir) {
+    const architecturePath = path.join(inputDir, "architecture.snapshot.yaml");
+    const uxPath = path.join(inputDir, "ux.snapshot.yaml");
+    let architectureRaw;
+    let uxRaw;
+    try {
+        [architectureRaw, uxRaw] = await Promise.all([
+            fs.readFile(architecturePath, "utf8"),
+            fs.readFile(uxPath, "utf8")
+        ]);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Could not find snapshots in ${inputDir}. Run \`specguard extract\` first.`);
+        }
+        throw error;
+    }
+    return {
+        architecture: yaml.load(architectureRaw),
+        ux: yaml.load(uxRaw)
+    };
+}
+async function readIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function stripExistingSpecGuardBlocks(content) {
+    return content
+        .replace(/\n?<!-- guardian:ai-context -->[\s\S]*?<!-- \/guardian:ai-context -->\n?/g, "\n")
+        .replace(/\n?<!-- guardian:context generated=.*?-->[\s\S]*?<!-- \/guardian:context -->\n?/g, "\n")
+        .replace(/<!-- guardian:auto-context -->[\s\S]*?<!-- \/guardian:auto-context -->/g, "<!-- guardian:auto-context -->\n<!-- /guardian:auto-context -->")
+        .replace(/\n{3,}/g, "\n\n");
+}
+/**
+ * Inject context into a file that has <!-- guardian:auto-context --> markers.
+ * Replaces content between the markers instead of appending.
+ */
+function injectIntoAutoContext(existing, contextBlock) {
+    const marker = "<!-- guardian:auto-context -->";
+    const endMarker = "<!-- /guardian:auto-context -->";
+    if (!existing.includes(marker)) {
+        // No auto-context markers — fall back to append behavior
+        const cleaned = stripExistingSpecGuardBlocks(existing).trim();
+        return cleaned.length > 0 ? `${cleaned}\n\n${contextBlock}\n` : `${contextBlock}\n`;
+    }
+    // Replace content between markers
+    const startIdx = existing.indexOf(marker);
+    const endIdx = existing.indexOf(endMarker);
+    if (startIdx === -1 || endIdx === -1) {
+        return existing;
+    }
+    const before = existing.slice(0, startIdx + marker.length);
+    const after = existing.slice(endIdx);
+    return `${before}\n${contextBlock}\n${after}`;
+}
+function normalizeMaxLines(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return undefined;
+}

package/dist/commands/data-flow-tracer.js

@@ -0,0 +1,291 @@
+/**
+ * FEATURE 5: DATA FLOW TRACER
+ *
+ * Follow a single data entity from user input → storage → retrieval → response
+ * Visualize complete flow across all layers
+ * Identify race conditions, lost updates, missing validation
+ *
+ * Benchmarking: High complexity
+ * Problem Domain: Debugging, Data Integrity, Performance Analysis
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Main function: Trace data flow through codebase
+ */
+export async function traceDataFlow(options) {
+    const { srcRoot, startPattern, dataEntityName, maxDepth = 10, output } = options;
+    // Scan all source files
+    const sourceFiles = await scanAllSourceFiles(srcRoot);
+    // Find entry points matching pattern
+    const entryPoints = findEntryPoints(sourceFiles, startPattern);
+    if (entryPoints.length === 0) {
+        throw new Error(`No entry points found matching pattern: ${startPattern}`);
+    }
+    // Build data flow graph from first entry point
+    const trace = buildDataFlowGraph(entryPoints[0], dataEntityName, sourceFiles, maxDepth);
+    // Analyze for issues
+    const issues = analyzeForIssues(trace, sourceFiles);
+    trace.issues = issues;
+    if (output) {
+        await writeTraceReport(trace, output);
+    }
+    return trace;
+}
+/**
+ * Helper: Scan all source files
+ */
+async function scanAllSourceFiles(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: Find entry points in code
+ */
+function findEntryPoints(sourceFiles, pattern) {
+    const entryPoints = [];
+    const regex = new RegExp(pattern, "gmi");
+    for (const [file, content] of sourceFiles.entries()) {
+        const lines = content.split("\n");
+        lines.forEach((line, idx) => {
+            if (regex.test(line)) {
+                entryPoints.push({ file, line: idx + 1 });
+            }
+        });
+    }
+    return entryPoints;
+}
+/**
+ * Helper: Build complete data flow graph
+ */
+function buildDataFlowGraph(entryPoint, dataEntity, sourceFiles, maxDepth) {
+    const nodes = [];
+    const edges = [];
+    const visited = new Set();
+    // Start node
+    nodes.push({
+        id: "entry_0",
+        type: "input",
+        name: `${dataEntity} Input`,
+        file: entryPoint.file,
+        lineNumber: entryPoint.line,
+        operation: "Receive request",
+    });
+    // Build graph by following data references
+    let depth = 0;
+    const queue = [
+        { nodeId: "entry_0", file: entryPoint.file, entity: dataEntity },
+    ];
+    while (queue.length > 0 && depth < maxDepth) {
+        const { nodeId, file, entity } = queue.shift();
+        const key = `${file}:${entity}`;
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        const content = sourceFiles.get(file);
+        if (!content)
+            continue;
+        // Find references to this data entity in this file
+        const references = findDataReferences(content, entity);
+        for (const ref of references) {
+            const newNodeId = `node_${nodes.length}`;
+            nodes.push({
+                id: newNodeId,
+                type: ref.type,
+                name: ref.name,
+                file,
+                lineNumber: ref.line,
+                operation: ref.operation,
+            });
+            edges.push({
+                from: nodeId,
+                to: newNodeId,
+                dataType: ref.dataType || entity,
+                transformation: ref.transformation,
+            });
+            // Find next file to follow
+            const nextFile = findNextFile(content, ref.operation, sourceFiles);
+            if (nextFile && !visited.has(`${nextFile}:${entity}`)) {
+                queue.push({ nodeId: newNodeId, file: nextFile, entity });
+            }
+        }
+        depth++;
+    }
+    // Calculate complexity
+    const complexity = Math.min(10, Math.ceil((nodes.length + edges.length) / 5));
+    return {
+        startPoint: entryPoint.file,
+        endPoint: nodes[nodes.length - 1]?.file || entryPoint.file,
+        nodes,
+        edges,
+        issues: [],
+        depth,
+        complexity,
+    };
+}
+/**
+ * Helper: Find references to data entity
+ */
+function findDataReferences(content, entity) {
+    const references = [];
+    const lines = content.split("\n");
+    const entityRegex = new RegExp(`\\b${entity}\\b`, "gi");
+    lines.forEach((line, idx) => {
+        if (!entityRegex.test(line))
+            return;
+        let type = "processor";
+        let operation = "Process";
+        if (line.includes("await") || line.includes(".then")) {
+            type = "processor";
+            operation = "Async operation";
+        }
+        if (line.match(/(?:insert|save|store|create)\s*\(/)) {
+            type = "storage";
+            operation = "Save to storage";
+        }
+        if (line.match(/(?:find|get|select|fetch|retrieve)\s*\(/)) {
+            type = "retrieval";
+            operation = "Retrieve from storage";
+        }
+        if (line.match(/return\s+.*\b${entity}\b/)) {
+            type = "output";
+            operation = "Return response";
+        }
+        references.push({
+            type,
+            name: `${type}: ${line.trim().substring(0, 40)}...`,
+            line: idx + 1,
+            operation,
+        });
+    });
+    return references;
+}
+/**
+ * Helper: Find next file to follow
+ */
+function findNextFile(content, operation, sourceFiles) {
+    // Look for imports of related modules
+    const importRegex = /import\s+.*\s+from\s+['"](.+?)['"]/g;
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+        const modulePath = match[1];
+        // Try to find matching file
+        for (const file of sourceFiles.keys()) {
+            if (file.includes(modulePath)) {
+                return file;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Helper: Analyze data flow for issues
+ */
+function analyzeForIssues(trace, sourceFiles) {
+    const issues = [];
+    // Check for missing validation
+    const hasValidation = trace.nodes.some((n) => n.operation.toLowerCase().includes("validat")) ||
+        trace.edges.some((e) => e.transformation?.toLowerCase().includes("validat"));
+    if (!hasValidation) {
+        issues.push({
+            type: "missing_validation",
+            severity: "high",
+            location: trace.startPoint,
+            description: "Data flow lacks explicit validation step",
+            suggestion: "Add validation at input boundary",
+        });
+    }
+    // Check for error handling
+    const storageNodes = trace.nodes.filter((n) => n.type.includes("storage"));
+    for (const node of storageNodes) {
+        const file = sourceFiles.get(node.file);
+        if (file && !file.includes("catch") && !file.includes("try")) {
+            issues.push({
+                type: "unhandled_error",
+                severity: "high",
+                location: `${node.file}:${node.lineNumber}`,
+                description: `Storage operation lacks error handling: ${node.operation}`,
+                suggestion: "Wrap storage operation in try-catch block",
+            });
+        }
+    }
+    // Check for race conditions in asynchronous flow
+    const asyncNodes = trace.nodes.filter((n) => n.operation.toLowerCase().includes("async"));
+    if (asyncNodes.length > 1) {
+        issues.push({
+            type: "race_condition",
+            severity: "medium",
+            location: trace.nodes[0].file,
+            description: "Multiple async operations on same data entity",
+            suggestion: "Use locks or atomic operations to prevent race conditions",
+        });
+    }
+    // Check for data mutations
+    const edges = trace.edges.filter((e) => e.transformation?.toLowerCase().includes("mutate"));
+    if (edges.length > 0) {
+        issues.push({
+            type: "data_mutation",
+            severity: "medium",
+            location: trace.nodes[0].file,
+            description: "Direct data mutation detected in flow",
+            suggestion: "Use immutable patterns (shallow copy, Object.assign)",
+        });
+    }
+    return issues;
+}
+/**
+ * Helper: Write trace report to markdown
+ */
+async function writeTraceReport(trace, outputPath) {
+    let md = `# Data Flow Trace Report\n\n`;
+    md += `Start: ${trace.startPoint}\n`;
+    md += `End: ${trace.endPoint}\n`;
+    md += `Nodes: ${trace.nodes.length} | Edges: ${trace.edges.length}\n`;
+    md += `Depth: ${trace.depth} | Complexity: ${trace.complexity}/10\n\n`;
+    // Flow diagram
+    md += `## Data Flow\n`;
+    md += "```\n";
+    for (let i = 0; i < trace.nodes.length; i++) {
+        const node = trace.nodes[i];
+        md += `${i > 0 ? "        ↓\n" : ""}${node.type.toUpperCase()}: ${node.operation}`;
+        md += ` (${path.basename(node.file)}:${node.lineNumber})\n`;
+    }
+    md += "```\n\n";
+    // Issues
+    if (trace.issues.length > 0) {
+        md += `## Issues Found (${trace.issues.length})\n`;
+        for (const issue of trace.issues) {
+            md += `### ${issue.type} - ${issue.severity}\n`;
+            md += `${issue.description}\n`;
+            md += `**Suggestion:** ${issue.suggestion}\n\n`;
+        }
+    }
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, md, "utf8");
+}
+export default traceDataFlow;

package/dist/commands/dependency-impact-analyzer.js

@@ -0,0 +1,27 @@
+import fs from 'fs';
+import path from 'path';
+export async function run() {
+    const root = process.cwd();
+    const pkgPath = path.join(root, 'package.json');
+    let pkg = {};
+    try {
+        pkg = JSON.parse(await fs.promises.readFile(pkgPath, 'utf8'));
+    }
+    catch (err) {
+        console.warn('No package.json found; using empty');
+    }
+    const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+    const result = {
+        totalDependencies: Object.keys(deps).length,
+        dependencies: Object.keys(deps).map(name => ({ name, version: deps[name], impactScore: Math.round(Math.random() * 100) }))
+    };
+    const out = path.join(root, 'out', 'dependency-impact.json');
+    await fs.promises.mkdir(path.dirname(out), { recursive: true });
+    await fs.promises.writeFile(out, JSON.stringify(result, null, 2), 'utf8');
+    console.log('Wrote dependency impact to', out);
+    return result;
+}
+const _isMain = (typeof require !== 'undefined' && (require.main === module)) || (process.argv[1] && process.argv[1].endsWith('dependency-impact-analyzer.ts'));
+if (_isMain) {
+    run().catch(err => { console.error(err); process.exit(1); });
+}