@toolbaux/guardian 0.1.0

package/dist/extract/api-usage-tracker.js

@@ -0,0 +1,19 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { analyzeFrontend } from "./analyzers/frontend.js";
+export async function trackApiUsage(frontendRoot) {
+    const frontendAnalysis = await analyzeFrontend(frontendRoot, {});
+    const apiCalls = frontendAnalysis.apiCalls;
+    const usageSummary = apiCalls.reduce((summary, call) => {
+        const key = `${call.method} ${call.path}`;
+        if (!summary[key]) {
+            summary[key] = { count: 0, sources: [] };
+        }
+        summary[key].count += 1;
+        summary[key].sources.push(call.source);
+        return summary;
+    }, {});
+    const reportPath = path.join(frontendRoot, "api-usage-report.json");
+    await fs.writeFile(reportPath, JSON.stringify(usageSummary, null, 2));
+    console.log(`API usage report generated at: ${reportPath}`);
+}

package/dist/extract/cache.js

@@ -0,0 +1,53 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+const BACKEND_CACHE_VERSION = "specguard-backend-cache-v4";
+export async function loadBackendExtractionCache(params) {
+    const cachePath = path.join(params.projectRoot, "specs-out", ".cache", "file-hashes.json");
+    const configHash = hashObject(params.config);
+    try {
+        const raw = await fs.readFile(cachePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            parsed.version === BACKEND_CACHE_VERSION &&
+            parsed.configHash === configHash &&
+            parsed.files &&
+            typeof parsed.files === "object") {
+            return { cachePath, cache: parsed };
+        }
+    }
+    catch {
+        // ignore
+    }
+    return {
+        cachePath,
+        cache: {
+            version: BACKEND_CACHE_VERSION,
+            configHash,
+            files: {}
+        }
+    };
+}
+export async function saveBackendExtractionCache(cachePath, cache) {
+    await fs.mkdir(path.dirname(cachePath), { recursive: true });
+    await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), "utf8");
+}
+export function hashContent(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function hashObject(value) {
+    return crypto.createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record)
+        .sort((a, b) => a.localeCompare(b))
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(",")}}`;
+}

package/dist/extract/codebase-intel.js

@@ -0,0 +1,190 @@
+/**
+ * Codebase Intelligence — assembles a frozen cross-feature packet from architecture snapshots.
+ *
+ * Analogous to series-intelligence.json in the book workflow:
+ * a single self-contained JSON file that any downstream command can read without
+ * touching source code. Contains:
+ *
+ *   api_registry      — every endpoint keyed by "METHOD /path"
+ *   model_registry    — every ORM model with fields and relationships
+ *   enum_registry     — every enum with its values
+ *   pattern_registry  — detected implementation patterns (P1–P8)
+ *   background_tasks  — all background/celery tasks
+ *   service_map       — modules with their endpoint counts and dependencies
+ *   frontend_pages    — pages with their component trees and API calls
+ *   meta              — project name, counts, generated_at
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { buildPatternRegistry } from "./pattern-registry.js";
+import { resolveMachineInputDir } from "../output-layout.js";
+export function buildCodebaseIntelligence(architecture, ux) {
+    const patternRegistry = buildPatternRegistry(architecture);
+    // Build a per-endpoint pattern index
+    const endpointPatterns = new Map();
+    for (const pattern of patternRegistry.patterns) {
+        for (const epStr of pattern.example_endpoints) {
+            // example_endpoints are "METHOD /path" — match by id
+        }
+    }
+    // More precise: recompute per-endpoint patterns from the architecture
+    const epPatternMap = buildEndpointPatternMap(architecture);
+    // api_registry
+    const apiRegistry = {};
+    for (const ep of architecture.endpoints) {
+        const key = `${ep.method} ${ep.path}`;
+        apiRegistry[key] = {
+            method: ep.method,
+            path: ep.path,
+            handler: ep.handler,
+            file: ep.file,
+            module: ep.module,
+            request_schema: ep.request_schema ?? null,
+            response_schema: ep.response_schema ?? null,
+            service_calls: ep.service_calls,
+            ai_operations: ep.ai_operations,
+            patterns: epPatternMap.get(ep.id) ?? [],
+        };
+    }
+    // model_registry
+    const modelRegistry = {};
+    for (const model of architecture.data_models) {
+        modelRegistry[model.name] = {
+            name: model.name,
+            file: model.file,
+            framework: model.framework,
+            fields: model.fields,
+            relationships: model.relationships,
+            field_details: model.field_details ?? [],
+        };
+    }
+    // enum_registry
+    const enumRegistry = {};
+    for (const en of architecture.enums) {
+        enumRegistry[en.name] = {
+            name: en.name,
+            file: en.file,
+            values: en.values,
+        };
+    }
+    // service_map
+    const serviceMap = architecture.modules.map((m) => ({
+        id: m.id,
+        path: m.path,
+        type: m.type,
+        layer: m.layer,
+        file_count: m.files.length,
+        endpoint_count: m.endpoints.length,
+        imports: m.imports,
+    }));
+    // frontend_pages
+    const frontendPages = ux.pages.map((p) => ({
+        path: p.path,
+        component: p.component,
+        api_calls: p.api_calls,
+        direct_components: p.components_direct,
+    }));
+    return {
+        meta: {
+            project: architecture.project.name,
+            generated_at: new Date().toISOString(),
+            counts: {
+                endpoints: architecture.endpoints.length,
+                models: architecture.data_models.length,
+                enums: architecture.enums.length,
+                tasks: architecture.tasks.length,
+                modules: architecture.modules.length,
+                pages: ux.pages.length,
+                patterns_detected: patternRegistry.patterns.filter((p) => p.occurrences > 0).length,
+            },
+        },
+        api_registry: apiRegistry,
+        model_registry: modelRegistry,
+        enum_registry: enumRegistry,
+        pattern_registry: patternRegistry,
+        background_tasks: architecture.tasks,
+        service_map: serviceMap,
+        frontend_pages: frontendPages,
+    };
+}
+/**
+ * Build a map from endpoint id → list of pattern IDs that apply.
+ * This mirrors the pattern detection logic in pattern-registry.ts but keyed by id.
+ */
+function buildEndpointPatternMap(architecture) {
+    const result = new Map();
+    const modelWriteMap = new Map();
+    for (const usage of architecture.endpoint_model_usage) {
+        const writes = usage.models.filter((m) => m.access === "write" || m.access === "read_write").length;
+        modelWriteMap.set(usage.endpoint_id, writes);
+    }
+    const crossStackVerified = new Set((architecture.cross_stack_contracts ?? [])
+        .filter((c) => c.status === "ok")
+        .map((c) => c.endpoint_id));
+    const resourceMethods = new Map();
+    for (const ep of architecture.endpoints) {
+        const resource = ep.path.replace(/\/\{[^}]+\}$/, "").replace(/\/:[^/]+$/, "");
+        const entry = resourceMethods.get(resource) ?? new Set();
+        entry.add(ep.method.toUpperCase());
+        resourceMethods.set(resource, entry);
+    }
+    const crudResources = new Set();
+    for (const [resource, methods] of resourceMethods) {
+        if (methods.has("GET") && methods.has("POST") && (methods.has("PATCH") || methods.has("PUT"))) {
+            crudResources.add(resource);
+        }
+    }
+    for (const ep of architecture.endpoints) {
+        const patterns = [];
+        const lower = (ep.file + ep.handler).toLowerCase();
+        if (ep.service_calls.length > 0)
+            patterns.push("P1");
+        if (lower.includes("auth") ||
+            lower.includes("permission") ||
+            lower.includes("require_") ||
+            lower.includes("depends(get_current"))
+            patterns.push("P2");
+        if (ep.ai_operations && ep.ai_operations.length > 0)
+            patterns.push("P3");
+        if (ep.service_calls.some((s) => {
+            const sl = s.toLowerCase();
+            return sl.includes("task") || sl.includes(".delay(") || sl.includes("background");
+        }))
+            patterns.push("P4");
+        const resource = ep.path.replace(/\/\{[^}]+\}$/, "").replace(/\/:[^/]+$/, "");
+        if (crudResources.has(resource))
+            patterns.push("P5");
+        if ((modelWriteMap.get(ep.id) ?? 0) >= 3)
+            patterns.push("P6");
+        if (crossStackVerified.has(ep.id))
+            patterns.push("P7");
+        if (ep.method.toUpperCase() === "GET" &&
+            (ep.path + ep.handler).toLowerCase().match(/list|page|paginate/))
+            patterns.push("P8");
+        result.set(ep.id, patterns);
+    }
+    return result;
+}
+/**
+ * Load snapshots and build CodebaseIntelligence, then write to disk.
+ */
+export async function writeCodebaseIntelligence(specsDir, outputPath) {
+    const machineDir = await resolveMachineInputDir(specsDir);
+    const [archRaw, uxRaw] = await Promise.all([
+        fs.readFile(path.join(machineDir, "architecture.snapshot.yaml"), "utf8"),
+        fs.readFile(path.join(machineDir, "ux.snapshot.yaml"), "utf8"),
+    ]);
+    const architecture = yaml.load(archRaw);
+    const ux = yaml.load(uxRaw);
+    const intel = buildCodebaseIntelligence(architecture, ux);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, JSON.stringify(intel, null, 2), "utf8");
+}
+/**
+ * Load an existing codebase-intelligence.json from disk.
+ */
+export async function loadCodebaseIntelligence(intelPath) {
+    const raw = await fs.readFile(intelPath, "utf8");
+    return JSON.parse(raw);
+}