@toolbaux/guardian 0.1.0

package/dist/extract/context-block.js

@@ -0,0 +1,356 @@
+export function renderContextBlock(architecture, ux, options) {
+    const focusTokens = tokenize(options?.focusQuery ?? "");
+    const ormModels = architecture.data_models.filter((model) => model.framework !== "pydantic");
+    const schemaModels = architecture.data_models.length - ormModels.length;
+    const lines = [];
+    lines.push(`<!-- guardian:context generated=${new Date().toISOString()} -->`);
+    lines.push("## Codebase Map");
+    lines.push("");
+    lines.push(`**Backend:** ${ormModels.length} ORM models + ${schemaModels} schemas · ${architecture.endpoints.length} endpoints · ${architecture.modules.length} modules`);
+    lines.push(`**Frontend:** ${ux.components.length} components · ${ux.pages.length} pages`);
+    lines.push("");
+    const couplingFiles = pickTopCouplingFiles(architecture, options?.heatmap, 5);
+    if (couplingFiles.length > 0) {
+        lines.push("### High-Coupling Files");
+        for (const entry of couplingFiles) {
+            lines.push(`- ${entry.id} (score ${entry.score.toFixed(2)})`);
+        }
+        lines.push("");
+    }
+    const recentChanges = summarizeDiff(options?.diff);
+    if (recentChanges.length > 0) {
+        lines.push("### Recent Structural Changes");
+        for (const change of recentChanges) {
+            lines.push(`- ${change}`);
+        }
+        lines.push("");
+    }
+    const exportComponents = pickRelevantComponents(ux, focusTokens).slice(0, 8);
+    if (exportComponents.length > 0) {
+        lines.push("### Component Import Reference");
+        for (const component of exportComponents) {
+            const importExample = component.export_kind === "default"
+                ? `import ${component.name} from`
+                : `import { ${component.name} } from`;
+            lines.push(`- ${component.name} -> \`${importExample}\` (${component.export_kind ?? "unknown"})`);
+        }
+        lines.push("");
+    }
+    if (architecture.tests && architecture.tests.length > 0) {
+        const testsByFile = new Map();
+        for (const test of architecture.tests) {
+            if (!test.file)
+                continue;
+            if (!testsByFile.has(test.file))
+                testsByFile.set(test.file, []);
+            testsByFile.get(test.file).push(test);
+        }
+        const testFiles = Array.from(testsByFile.entries())
+            .sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]))
+            .slice(0, 5);
+        if (testFiles.length > 0) {
+            lines.push("### Behavioral Test Specifications");
+            for (const [file, tests] of testFiles) {
+                lines.push(`- \`${file}\` (${tests.length} tests)`);
+            }
+            lines.push("");
+        }
+    }
+    const siReports = (options?.structuralIntelligence ?? architecture.structural_intelligence ?? []).filter((r) => r.structure.nodes > 0).slice(0, 5);
+    if (siReports.length > 0) {
+        lines.push("### Structural Intelligence");
+        for (const r of siReports) {
+            const compressLabel = r.classification.compressible === "NON_COMPRESSIBLE"
+                ? "compressible=**no**"
+                : r.classification.compressible === "PARTIAL"
+                    ? "compressible=partial"
+                    : "compressible=yes";
+            lines.push(`- ${r.feature}: depth=${r.classification.depth_level} · propagation=${r.classification.propagation} · ${compressLabel} · pattern=${r.recommendation.primary.pattern} (confidence ${r.confidence.value.toFixed(2)})`);
+        }
+        lines.push("");
+        const highRisk = siReports.filter((r) => r.classification.compressible === "NON_COMPRESSIBLE" &&
+            r.confidence.value >= r.guardrails.enforce_if_confidence_above);
+        if (highRisk.length > 0) {
+            lines.push("### AI Reasoning Rules");
+            lines.push("> [!WARNING]");
+            lines.push("> The following features are HIGH complexity. Do NOT implement as a single function.");
+            lines.push("");
+            for (const r of highRisk) {
+                lines.push(`- **${r.feature}** (confidence ${r.confidence.value.toFixed(2)}): use ${r.recommendation.primary.pattern}`);
+                if (r.recommendation.avoid.length > 0) {
+                    lines.push(`  - Avoid: ${r.recommendation.avoid.join(", ")}`);
+                }
+            }
+            lines.push("");
+        }
+    }
+    const modelMap = buildModelEndpointMap(architecture, focusTokens);
+    if (modelMap.length > 0) {
+        lines.push("### Key Model -> Endpoint Map");
+        for (const entry of modelMap.slice(0, 8)) {
+            lines.push(`- ${entry.model} (${entry.endpoints.length} endpoints) -> ${formatEndpointPreview(entry.endpoints, 5)}`);
+        }
+        lines.push("");
+    }
+    if (focusTokens.length > 0) {
+        const focusMatches = buildFocusSummary(architecture, ux, focusTokens);
+        if (focusMatches.length > 0) {
+            lines.push(`### Focus: ${options?.focusQuery}`);
+            for (const match of focusMatches.slice(0, 10)) {
+                lines.push(`- ${match}`);
+            }
+            lines.push("");
+        }
+    }
+    lines.push("<!-- /guardian:context -->");
+    const maxLines = options?.maxLines ?? 120;
+    if (lines.length <= maxLines) {
+        return lines.join("\n");
+    }
+    return [...lines.slice(0, maxLines - 2), "- context truncated for line budget", "<!-- /guardian:context -->"].join("\n");
+}
+function tokenize(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9_/.{}-]+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+}
+function matchesFocus(tokens, values) {
+    if (tokens.length === 0) {
+        return true;
+    }
+    const haystack = values.join(" ").toLowerCase();
+    return tokens.some((token) => haystack.includes(token));
+}
+function pickTopCouplingFiles(architecture, heatmap, limit) {
+    const fileEntries = heatmap?.levels.find((level) => level.level === "file")?.entries ?? [];
+    if (fileEntries.length > 0) {
+        return fileEntries.slice(0, limit).map((entry) => ({
+            id: entry.id,
+            score: entry.score
+        }));
+    }
+    const degree = new Map();
+    for (const edge of architecture.dependencies.file_graph) {
+        degree.set(edge.from, (degree.get(edge.from) ?? 0) + 1);
+        degree.set(edge.to, (degree.get(edge.to) ?? 0) + 1);
+    }
+    const maxDegree = Math.max(...degree.values(), 1);
+    return Array.from(degree.entries())
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, limit)
+        .map(([id, score]) => ({ id, score: score / maxDegree }));
+}
+function summarizeDiff(diff) {
+    if (!diff) {
+        return [];
+    }
+    const changes = [];
+    for (const [kind, items] of Object.entries(diff.added)) {
+        for (const item of items.slice(0, 3)) {
+            changes.push(`${kind}: +${item}`);
+        }
+    }
+    for (const [kind, items] of Object.entries(diff.removed)) {
+        for (const item of items.slice(0, 2)) {
+            changes.push(`${kind}: -${item}`);
+        }
+    }
+    return changes.slice(0, 6);
+}
+function pickRelevantComponents(ux, focusTokens) {
+    const pageContext = buildComponentPageContext(ux);
+    const inDegree = buildComponentInDegree(ux);
+    return ux.components
+        .map((component) => {
+        const pages = pageContext.get(component.id) ?? [];
+        const values = [
+            component.name,
+            component.file,
+            component.export_kind ?? "unknown",
+            ...pages,
+            ...(component.props ?? []).map((prop) => `${prop.name}:${prop.type}`)
+        ];
+        const score = focusTokens.length === 0
+            ? (inDegree.get(component.id) ?? 0) * 0.5 +
+                pages.length * 0.2 +
+                (component.kind === "page" ? 0.1 : 0)
+            : scoreFocus(focusTokens, component.name, component.file, values);
+        return { component, pages, score };
+    })
+        .filter((entry) => focusTokens.length === 0 || entry.score > 0)
+        .sort((a, b) => b.score - a.score ||
+        b.pages.length - a.pages.length ||
+        a.component.name.localeCompare(b.component.name))
+        .map((entry) => entry.component);
+}
+function buildComponentInDegree(ux) {
+    const inDegree = new Map();
+    for (const edge of ux.component_graph) {
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+    }
+    return inDegree;
+}
+function buildComponentPageContext(ux) {
+    const pageContext = new Map();
+    for (const page of ux.pages) {
+        const targets = new Set([
+            page.component_id,
+            ...(page.components_direct_ids ?? []),
+            ...(page.components_descendants_ids ?? [])
+        ]);
+        for (const target of targets) {
+            if (!target) {
+                continue;
+            }
+            const pages = pageContext.get(target) ?? new Set();
+            pages.add(page.path);
+            pageContext.set(target, pages);
+        }
+    }
+    return new Map(Array.from(pageContext.entries()).map(([key, value]) => [
+        key,
+        Array.from(value).sort((a, b) => a.localeCompare(b))
+    ]));
+}
+function scoreFocus(tokens, name, file, values) {
+    if (tokens.length === 0) {
+        return 0;
+    }
+    const normalizedName = name.toLowerCase();
+    const normalizedFile = file.toLowerCase();
+    const haystack = values.map((value) => value.toLowerCase());
+    let score = 0;
+    for (const token of tokens) {
+        if (normalizedName === token) {
+            score += 1;
+            continue;
+        }
+        if (normalizedName.includes(token)) {
+            score += 0.8;
+            continue;
+        }
+        if (normalizedFile.includes(token)) {
+            score += 0.55;
+            continue;
+        }
+        if (haystack.some((value) => value.includes(token))) {
+            score += 0.4;
+        }
+    }
+    return score / tokens.length;
+}
+function buildModelEndpointMap(architecture, focusTokens) {
+    const endpointLabel = new Map(architecture.endpoints.map((endpoint) => [endpoint.id, `${endpoint.method} ${endpoint.path}`]));
+    const modelMap = new Map();
+    for (const usage of architecture.endpoint_model_usage) {
+        const endpoint = endpointLabel.get(usage.endpoint_id) ?? usage.endpoint;
+        for (const model of usage.models) {
+            const entry = modelMap.get(model.name) ?? new Set();
+            entry.add(endpoint);
+            modelMap.set(model.name, entry);
+        }
+    }
+    const rows = Array.from(modelMap.entries()).map(([model, endpoints]) => ({
+        model,
+        endpoints: Array.from(endpoints).sort((a, b) => a.localeCompare(b))
+    }));
+    const filtered = rows.filter((row) => matchesFocus(focusTokens, [row.model, ...row.endpoints]));
+    return (filtered.length > 0 ? filtered : rows).sort((a, b) => b.endpoints.length - a.endpoints.length || a.model.localeCompare(b.model));
+}
+function formatEndpointPreview(endpoints, limit) {
+    if (endpoints.length <= limit) {
+        return endpoints.join(", ");
+    }
+    const remaining = endpoints.length - limit;
+    return `${endpoints.slice(0, limit).join(", ")} +${remaining} more`;
+}
+function buildFocusSummary(architecture, ux, focusTokens) {
+    const summary = [];
+    const matchedModels = new Set();
+    const matchedEndpoints = new Set();
+    const matchedComponents = new Set();
+    const matchedModules = new Set();
+    // Pass 1: Direct Matching
+    for (const model of architecture.data_models) {
+        if (matchesFocus(focusTokens, [model.name, model.file, ...model.fields, ...model.relationships])) {
+            matchedModels.add(model.name);
+        }
+    }
+    for (const endpoint of architecture.endpoints) {
+        if (matchesFocus(focusTokens, [
+            endpoint.path,
+            endpoint.handler,
+            endpoint.file,
+            endpoint.module,
+            endpoint.request_schema ?? "",
+            endpoint.response_schema ?? ""
+        ])) {
+            matchedEndpoints.add(endpoint.id);
+        }
+    }
+    for (const component of ux.components) {
+        if (matchesFocus(focusTokens, [
+            component.name,
+            component.file,
+            component.export_kind ?? "unknown",
+            ...(component.props ?? []).map((prop) => `${prop.name}:${prop.type}`)
+        ])) {
+            matchedComponents.add(component.id);
+        }
+    }
+    for (const module of architecture.modules) {
+        if (matchesFocus(focusTokens, [module.id, module.path, ...module.files])) {
+            matchedModules.add(module.id);
+        }
+    }
+    // Pass 2: 1-Degree Graph Expansion
+    for (const usage of architecture.endpoint_model_usage) {
+        const usesMatchedModel = usage.models.some((m) => matchedModels.has(m.name));
+        if (usesMatchedModel) {
+            matchedEndpoints.add(usage.endpoint_id);
+        }
+        if (matchedEndpoints.has(usage.endpoint_id)) {
+            usage.models.forEach((m) => matchedModels.add(m.name));
+        }
+    }
+    for (const edge of ux.component_graph) {
+        if (matchedComponents.has(edge.from)) {
+            matchedComponents.add(edge.to);
+        }
+        if (matchedComponents.has(edge.to)) {
+            matchedComponents.add(edge.from);
+        }
+    }
+    for (const edge of architecture.dependencies.module_graph) {
+        if (matchedModules.has(edge.from)) {
+            matchedModules.add(edge.to);
+        }
+        if (matchedModules.has(edge.to)) {
+            matchedModules.add(edge.from);
+        }
+    }
+    // Format Output
+    for (const model of architecture.data_models) {
+        if (matchedModels.has(model.name)) {
+            summary.push(`model: ${model.name} (${model.file})`);
+        }
+    }
+    for (const endpoint of architecture.endpoints) {
+        if (matchedEndpoints.has(endpoint.id)) {
+            summary.push(`endpoint: ${endpoint.method} ${endpoint.path} -> ${endpoint.handler}`);
+        }
+    }
+    for (const component of ux.components) {
+        if (matchedComponents.has(component.id)) {
+            summary.push(`component: ${component.name} (${component.file})`);
+        }
+    }
+    for (const module of architecture.modules) {
+        if (matchedModules.has(module.id)) {
+            summary.push(`module: ${module.id} (${module.path})`);
+        }
+    }
+    return summary;
+}

package/dist/extract/contracts.js

@@ -0,0 +1,183 @@
+export function buildCrossStackContracts(params) {
+    const { endpoints, apiCalls, ux, dataModels } = params;
+    const endpointByKey = new Map();
+    for (const endpoint of endpoints) {
+        const key = `${normalizeMethod(endpoint.method)} ${normalizePathPattern(endpoint.path)}`;
+        const entry = endpointByKey.get(key) ?? [];
+        entry.push(endpoint);
+        endpointByKey.set(key, entry);
+    }
+    const dataModelsByName = new Map(dataModels.map((model) => [model.name, model]));
+    const componentById = new Map(ux.components.map((component) => [component.id, component]));
+    const callersByEndpoint = buildCallerIndex(ux, componentById, apiCalls);
+    const groupedCalls = new Map();
+    for (const call of apiCalls) {
+        const key = `${normalizeMethod(call.method)} ${normalizePathPattern(call.path)}`;
+        const entry = groupedCalls.get(key) ?? [];
+        entry.push(call);
+        groupedCalls.set(key, entry);
+    }
+    const contracts = [];
+    const seen = new Set();
+    for (const [key, calls] of groupedCalls) {
+        const [method, ...pathParts] = key.split(" ");
+        const pathValue = pathParts.join(" ");
+        const candidates = findMatchingEndpoints({
+            endpoints,
+            endpointByKey,
+            method,
+            pathValue
+        });
+        for (const endpoint of candidates) {
+            const contractKey = endpoint.id;
+            if (seen.has(contractKey)) {
+                continue;
+            }
+            seen.add(contractKey);
+            const backendRequestModel = endpoint.request_schema
+                ? dataModelsByName.get(endpoint.request_schema)
+                : null;
+            const backendRequestFields = backendRequestModel?.fields ?? [];
+            const frontendRequestFields = Array.from(new Set(calls.flatMap((call) => call.request_fields ?? []))).sort((a, b) => a.localeCompare(b));
+            const callers = callersByEndpoint.get(key) ?? callersByEndpoint.get(`ANY ${pathValue}`) ?? [];
+            const issues = [];
+            if (endpoint.request_schema && !backendRequestModel) {
+                issues.push(`backend request schema '${endpoint.request_schema}' not extracted`);
+            }
+            if (backendRequestFields.length > 0 && frontendRequestFields.length === 0) {
+                issues.push("frontend request fields not inferred");
+            }
+            if (backendRequestFields.length > 0 && frontendRequestFields.length > 0) {
+                const backendOnly = backendRequestFields.filter((field) => !frontendRequestFields.includes(field));
+                const frontendOnly = frontendRequestFields.filter((field) => !backendRequestFields.includes(field));
+                for (const field of backendOnly) {
+                    issues.push(`frontend missing field '${field}'`);
+                }
+                for (const field of frontendOnly) {
+                    issues.push(`frontend extra field '${field}'`);
+                }
+            }
+            let status = "ok";
+            if (issues.length > 0 && issues.some((issue) => issue.startsWith("frontend"))) {
+                status = "mismatched";
+            }
+            else if (endpoint.request_schema ||
+                endpoint.response_schema ||
+                frontendRequestFields.length > 0) {
+                status =
+                    backendRequestFields.length > 0 && issues.length === 0 ? "ok" : "unverified";
+            }
+            contracts.push({
+                endpoint_id: endpoint.id,
+                method: endpoint.method,
+                path: endpoint.path,
+                backend_request_schema: endpoint.request_schema ?? null,
+                backend_response_schema: endpoint.response_schema ?? null,
+                backend_request_fields: backendRequestFields,
+                frontend_request_fields: frontendRequestFields,
+                frontend_callers: callers,
+                status,
+                issues
+            });
+        }
+    }
+    contracts.sort((a, b) => {
+        const path = a.path.localeCompare(b.path);
+        if (path !== 0) {
+            return path;
+        }
+        return a.method.localeCompare(b.method);
+    });
+    return contracts;
+}
+function buildCallerIndex(ux, componentById, apiCalls) {
+    const callers = new Map();
+    for (const page of ux.pages) {
+        for (const entry of page.component_api_calls) {
+            for (const call of entry.api_calls) {
+                const key = normalizeApiCallKey(call);
+                if (!key) {
+                    continue;
+                }
+                const file = componentById.get(entry.component_id)?.file ?? "unknown";
+                const existing = callers.get(key) ?? new Map();
+                existing.set(`${entry.component}|${file}`, {
+                    component: entry.component,
+                    file
+                });
+                callers.set(key, existing);
+            }
+        }
+    }
+    const componentsByFile = new Map();
+    for (const component of ux.components) {
+        const entry = componentsByFile.get(component.file) ?? [];
+        entry.push({ component: component.name, file: component.file });
+        componentsByFile.set(component.file, entry);
+    }
+    for (const call of apiCalls) {
+        const key = `${normalizeMethod(call.method)} ${normalizePathPattern(call.path)}`;
+        if (callers.has(key)) {
+            continue;
+        }
+        const components = componentsByFile.get(call.source) ?? [];
+        if (components.length === 0) {
+            continue;
+        }
+        callers.set(key, new Map(components.map((component) => [`${component.component}|${component.file}`, component])));
+    }
+    return new Map(Array.from(callers.entries()).map(([key, value]) => [
+        key,
+        Array.from(value.values()).sort((a, b) => {
+            const component = a.component.localeCompare(b.component);
+            if (component !== 0) {
+                return component;
+            }
+            return a.file.localeCompare(b.file);
+        })
+    ]));
+}
+function findMatchingEndpoints(params) {
+    const exact = params.endpointByKey.get(`${params.method} ${params.pathValue}`) ??
+        params.endpointByKey.get(`ANY ${params.pathValue}`);
+    if (exact && exact.length > 0) {
+        return exact;
+    }
+    return params.endpoints.filter((endpoint) => {
+        const endpointMethod = normalizeMethod(endpoint.method);
+        if (endpointMethod !== "ANY" && endpointMethod !== params.method) {
+            return false;
+        }
+        const endpointPath = normalizePathPattern(endpoint.path);
+        return pathsCompatible(endpointPath, params.pathValue);
+    });
+}
+function pathsCompatible(a, b) {
+    if (a === b) {
+        return true;
+    }
+    return a.endsWith(b) || b.endsWith(a);
+}
+function normalizeApiCallKey(value) {
+    const parts = value.split(" ");
+    if (parts.length < 2) {
+        return null;
+    }
+    return `${normalizeMethod(parts[0])} ${normalizePathPattern(parts.slice(1).join(" "))}`;
+}
+function normalizeMethod(method) {
+    return method ? method.toUpperCase() : "GET";
+}
+function normalizePathPattern(value) {
+    if (!value) {
+        return "/";
+    }
+    const withoutQuery = value.split("?")[0] ?? value;
+    return withoutQuery
+        .replace(/\$\{[^}]+\}/g, ":param")
+        .replace(/\{[^}]+\}/g, ":param")
+        .replace(/<[^>]+>/g, ":param")
+        .replace(/:\w+/g, ":param")
+        .replace(/\/+/g, "/")
+        .replace(/\/$/, "") || "/";
+}