@toolbaux/guardian 0.1.0

package/dist/extract/discrepancies.js

@@ -0,0 +1,233 @@
+/**
+ * Discrepancy Detection — diffs current codebase intelligence against a committed baseline.
+ *
+ * Answers: "what changed in the code that isn't reflected in our product docs or feature specs?"
+ *
+ * Checks:
+ *   1. untracked_endpoints   — endpoints in code but not in any feature spec
+ *   2. new_endpoints         — endpoints added since the baseline
+ *   3. removed_endpoints     — endpoints present in baseline but gone from code
+ *   4. drifted_models        — ORM models whose field count changed since baseline
+ *   5. new_models            — models added since baseline
+ *   6. removed_models        — models removed since baseline
+ *   7. new_tasks             — background tasks added since baseline
+ *   8. orphan_specs          — feature specs referencing endpoints that no longer exist
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { parseFeatureSpec } from "../schema/feature-spec.js";
+export function buildBaseline(intel) {
+    return {
+        generated_at: intel.meta.generated_at,
+        endpoints: Object.keys(intel.api_registry).sort(),
+        models: Object.fromEntries(Object.entries(intel.model_registry).map(([name, m]) => [name, m.fields.length])),
+        tasks: intel.background_tasks.map((t) => t.name).sort(),
+    };
+}
+export async function buildDiscrepancyReport(params) {
+    const { intel, baselinePath, featureSpecsDir } = params;
+    const currentEndpoints = new Set(Object.keys(intel.api_registry));
+    const currentModels = new Map(Object.entries(intel.model_registry).map(([name, m]) => [name, m.fields.length]));
+    const currentTasks = new Set(intel.background_tasks.map((t) => t.name));
+    // Load baseline
+    let baseline = null;
+    if (baselinePath) {
+        try {
+            const raw = await fs.readFile(baselinePath, "utf8");
+            baseline = JSON.parse(raw);
+        }
+        catch {
+            // No baseline yet — first run
+        }
+    }
+    const baselineEndpoints = new Set(baseline?.endpoints ?? []);
+    const baselineModels = new Map(Object.entries(baseline?.models ?? {}));
+    const baselineTasks = new Set(baseline?.tasks ?? []);
+    // Load feature specs to find covered endpoints
+    const coveredEndpoints = new Set();
+    const orphanSpecs = [];
+    if (featureSpecsDir) {
+        const specs = await loadFeatureSpecs(featureSpecsDir);
+        for (const { spec, file } of specs) {
+            const missing = [];
+            for (const ep of spec.affected_endpoints) {
+                coveredEndpoints.add(ep);
+                if (!currentEndpoints.has(ep)) {
+                    missing.push(ep);
+                }
+            }
+            if (missing.length > 0) {
+                orphanSpecs.push({ spec_file: file, missing_endpoints: missing });
+            }
+        }
+    }
+    // 1. Untracked endpoints (in code, not in any spec)
+    const untrackedEndpoints = Array.from(currentEndpoints)
+        .filter((ep) => !coveredEndpoints.has(ep))
+        .sort();
+    // 2. New endpoints since baseline
+    const newEndpoints = Array.from(currentEndpoints)
+        .filter((ep) => !baselineEndpoints.has(ep))
+        .sort();
+    // 3. Removed endpoints since baseline
+    const removedEndpoints = Array.from(baselineEndpoints)
+        .filter((ep) => !currentEndpoints.has(ep))
+        .sort();
+    // 4. Drifted models (field count changed)
+    const driftedModels = [];
+    for (const [name, currentCount] of currentModels) {
+        const baselineCount = baselineModels.get(name);
+        if (baselineCount !== undefined && baselineCount !== currentCount) {
+            driftedModels.push({
+                name,
+                baseline_field_count: baselineCount,
+                current_field_count: currentCount,
+                delta: currentCount - baselineCount,
+            });
+        }
+    }
+    driftedModels.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+    // 5. New models
+    const newModels = Array.from(currentModels.keys())
+        .filter((name) => !baselineModels.has(name))
+        .sort();
+    // 6. Removed models
+    const removedModels = Array.from(baselineModels.keys())
+        .filter((name) => !currentModels.has(name))
+        .sort();
+    // 7. New tasks
+    const newTasks = Array.from(currentTasks)
+        .filter((t) => !baselineTasks.has(t))
+        .sort();
+    const totalIssues = newEndpoints.length +
+        removedEndpoints.length +
+        driftedModels.length +
+        newModels.length +
+        removedModels.length +
+        newTasks.length +
+        orphanSpecs.length;
+    const hasCritical = removedEndpoints.length > 0 ||
+        removedModels.length > 0 ||
+        orphanSpecs.length > 0;
+    return {
+        generated_at: new Date().toISOString(),
+        baseline_at: baseline?.generated_at ?? null,
+        summary: { total_issues: totalIssues, has_critical: hasCritical },
+        untracked_endpoints: untrackedEndpoints,
+        new_endpoints: newEndpoints,
+        removed_endpoints: removedEndpoints,
+        drifted_models: driftedModels,
+        new_models: newModels,
+        removed_models: removedModels,
+        new_tasks: newTasks,
+        orphan_specs: orphanSpecs,
+    };
+}
+async function loadFeatureSpecs(dir) {
+    let entries;
+    try {
+        const dirEntries = await fs.readdir(dir);
+        entries = dirEntries
+            .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+            .map((f) => path.join(dir, f));
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        try {
+            const raw = await fs.readFile(entry, "utf8");
+            const parsed = yaml.load(raw);
+            results.push({ spec: parseFeatureSpec(parsed), file: path.basename(entry) });
+        }
+        catch {
+            // Skip malformed specs
+        }
+    }
+    return results;
+}
+/**
+ * Render a discrepancy report as human-readable Markdown.
+ */
+export function renderDiscrepancyMarkdown(report) {
+    const lines = [];
+    const since = report.baseline_at
+        ? `since baseline (${report.baseline_at.slice(0, 10)})`
+        : "(no baseline — first run)";
+    lines.push(`# Discrepancy Report`);
+    lines.push(`_Generated: ${report.generated_at.slice(0, 19).replace("T", " ")} UTC_`);
+    lines.push(`_Baseline: ${report.baseline_at ? report.baseline_at.slice(0, 10) : "none"}_`);
+    lines.push("");
+    lines.push(`**${report.summary.total_issues} issue(s) found**${report.summary.has_critical ? " — ⚠ critical changes detected" : ""}`);
+    lines.push("");
+    if (report.new_endpoints.length > 0) {
+        lines.push(`## New Endpoints ${since} (${report.new_endpoints.length})`);
+        lines.push("");
+        for (const ep of report.new_endpoints)
+            lines.push(`- \`${ep}\``);
+        lines.push("");
+    }
+    if (report.removed_endpoints.length > 0) {
+        lines.push(`## ⚠ Removed Endpoints ${since} (${report.removed_endpoints.length})`);
+        lines.push("");
+        for (const ep of report.removed_endpoints)
+            lines.push(`- \`${ep}\``);
+        lines.push("");
+    }
+    if (report.untracked_endpoints.length > 0) {
+        lines.push(`## Untracked Endpoints — not in any feature spec (${report.untracked_endpoints.length})`);
+        lines.push("");
+        for (const ep of report.untracked_endpoints.slice(0, 20))
+            lines.push(`- \`${ep}\``);
+        if (report.untracked_endpoints.length > 20) {
+            lines.push(`- _...and ${report.untracked_endpoints.length - 20} more_`);
+        }
+        lines.push("");
+    }
+    if (report.drifted_models.length > 0) {
+        lines.push(`## Drifted Models — field count changed (${report.drifted_models.length})`);
+        lines.push("");
+        lines.push("| Model | Baseline fields | Current fields | Delta |");
+        lines.push("|---|---|---|---|");
+        for (const m of report.drifted_models) {
+            const sign = m.delta > 0 ? "+" : "";
+            lines.push(`| ${m.name} | ${m.baseline_field_count} | ${m.current_field_count} | ${sign}${m.delta} |`);
+        }
+        lines.push("");
+    }
+    if (report.new_models.length > 0) {
+        lines.push(`## New Models ${since} (${report.new_models.length})`);
+        lines.push("");
+        for (const m of report.new_models)
+            lines.push(`- \`${m}\``);
+        lines.push("");
+    }
+    if (report.removed_models.length > 0) {
+        lines.push(`## ⚠ Removed Models ${since} (${report.removed_models.length})`);
+        lines.push("");
+        for (const m of report.removed_models)
+            lines.push(`- \`${m}\``);
+        lines.push("");
+    }
+    if (report.new_tasks.length > 0) {
+        lines.push(`## New Background Tasks ${since} (${report.new_tasks.length})`);
+        lines.push("");
+        for (const t of report.new_tasks)
+            lines.push(`- \`${t}\``);
+        lines.push("");
+    }
+    if (report.orphan_specs.length > 0) {
+        lines.push(`## ⚠ Orphan Feature Specs — reference endpoints that no longer exist (${report.orphan_specs.length})`);
+        lines.push("");
+        for (const s of report.orphan_specs) {
+            lines.push(`**${s.spec_file}**: ${s.missing_endpoints.map((e) => `\`${e}\``).join(", ")}`);
+        }
+        lines.push("");
+    }
+    if (report.summary.total_issues === 0) {
+        lines.push("No discrepancies found. Code and specs are in sync.");
+    }
+    return lines.join("\n");
+}

package/dist/extract/docs-loader.js

@@ -0,0 +1,110 @@
+/**
+ * Docs Loader — loads and parses sections from existing specguard doc files.
+ *
+ * Reads from specs-out/machine/docs/:
+ *   hld.md         → systemDiagram, couplingHeatmap, backendSubsystems, apiDomainMap
+ *   summary.md     → qualitySignals, systemScale
+ *   stakeholder.md → stakeholderMetrics
+ *   integration.md → integrationByDomain (full content, already domain-grouped)
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Load and parse existing docs from the machine docs directory.
+ * All fields are optional — missing files are silently skipped.
+ */
+export async function loadExistingDocs(machineDocsDir) {
+    const [hld, summary, stakeholder, integration] = await Promise.all([
+        readIfExists(path.join(machineDocsDir, "hld.md")),
+        readIfExists(path.join(machineDocsDir, "summary.md")),
+        readIfExists(path.join(machineDocsDir, "stakeholder.md")),
+        readIfExists(path.join(machineDocsDir, "integration.md")),
+    ]);
+    return {
+        systemDiagram: hld ? extractSection(hld, "System Block Diagram") : undefined,
+        couplingHeatmap: hld ? extractSection(hld, "Structural Coupling Heatmap (Top Functions)") : undefined,
+        driftSummary: hld ? extractSection(hld, "Drift Summary") : undefined,
+        backendSubsystems: hld ? extractSection(hld, "Backend Subsystems") : undefined,
+        apiDomainMap: hld ? extractSection(hld, "API Domain Map") : undefined,
+        qualitySignals: summary ? extractSection(summary, "Quality & Drift Signals") : undefined,
+        systemScale: summary ? extractSection(summary, "System Scale (Current State)") : undefined,
+        stakeholderMetrics: stakeholder ? extractStakeholderMetrics(stakeholder) : undefined,
+        integrationByDomain: integration ?? undefined,
+    };
+}
+/**
+ * Extract a named `## Heading` section from markdown.
+ * Returns content from just after the heading until the next `## ` heading (or EOF).
+ * Returns undefined if the heading is not found.
+ */
+export function extractSection(markdown, heading) {
+    const headingLine = `## ${heading}`;
+    const idx = markdown.indexOf(headingLine);
+    if (idx === -1)
+        return undefined;
+    const contentStart = idx + headingLine.length;
+    const nextHeading = markdown.indexOf("\n## ", contentStart);
+    const raw = nextHeading === -1
+        ? markdown.slice(contentStart)
+        : markdown.slice(contentStart, nextHeading);
+    return raw.trim() || undefined;
+}
+/**
+ * Extract the metrics table and health snapshot from stakeholder.md.
+ * Returns from the first `|` table up through the health snapshot section.
+ */
+function extractStakeholderMetrics(stakeholder) {
+    // Extract from first table line to end of "## Health Snapshot" section
+    const tableStart = stakeholder.indexOf("\n| ");
+    if (tableStart === -1)
+        return undefined;
+    // Find end of health snapshot section (next ## after it, or EOF)
+    const healthIdx = stakeholder.indexOf("## Health Snapshot");
+    if (healthIdx === -1) {
+        // Just return the metrics table
+        const tableEnd = stakeholder.indexOf("\n## ", tableStart + 1);
+        return tableEnd === -1
+            ? stakeholder.slice(tableStart).trim()
+            : stakeholder.slice(tableStart, tableEnd).trim();
+    }
+    const afterHealth = stakeholder.indexOf("\n## ", healthIdx + 1);
+    const end = afterHealth === -1 ? stakeholder.length : afterHealth;
+    return stakeholder.slice(tableStart, end).trim();
+}
+/**
+ * Parse integration.md into a map of domain → markdown table string.
+ * Domains are `## /domain-prefix` headings.
+ */
+export function parseIntegrationDomains(integration) {
+    const domains = new Map();
+    // Split on "## " headings
+    const sections = integration.split(/\n(?=## )/);
+    for (const section of sections) {
+        const headingMatch = section.match(/^## (.+)/);
+        if (!headingMatch)
+            continue;
+        const heading = headingMatch[1].trim();
+        // Normalise: "/api/auth" → "auth", "/" → "root", "/api/{project_id}" → "{project_id}"
+        const domain = normaliseIntegrationHeading(heading);
+        const content = section.slice(headingMatch[0].length).trim();
+        if (content) {
+            domains.set(domain, { heading, content });
+        }
+    }
+    return domains;
+}
+function normaliseIntegrationHeading(heading) {
+    // "/api/auth" → "auth"
+    // "/api/{project_id}" → "{project_id}"
+    // "/" → "root"
+    const stripped = heading.replace(/^\/api\//, "").replace(/^\//, "") || "root";
+    return stripped;
+}
+async function readIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}