@toolbaux/guardian 0.1.22 → 0.2.0

package/dist/extract/codebase-intel.js

@@ -171,8 +171,10 @@ function buildEndpointPatternMap(architecture) {
     }
     return result;
 }
+// ── File-based IO (original implementation — unchanged) ────────────────────
 /**
- * Load snapshots and build CodebaseIntelligence, then write to disk.
+ * Load snapshots and write codebase-intelligence.json to disk.
+ * This is the original file-based implementation, kept intact.
  */
 export async function writeCodebaseIntelligence(specsDir, outputPath) {
     const machineDir = await resolveMachineInputDir(specsDir);
@@ -187,9 +189,36 @@ export async function writeCodebaseIntelligence(specsDir, outputPath) {
     await fs.writeFile(outputPath, JSON.stringify(intel, null, 2), "utf8");
 }
 /**
- * Load an existing codebase-intelligence.json from disk.
+ * Load an existing codebase-intelligence.json from a file path.
+ * Original file-based implementation, kept intact.
  */
 export async function loadCodebaseIntelligence(intelPath) {
     const raw = await fs.readFile(intelPath, "utf8");
     return JSON.parse(raw);
 }
+// ── Store-based IO (new — works with both FileSpecsStore and SqliteSpecsStore) ─
+/**
+ * Build CodebaseIntelligence and write it via a SpecsStore.
+ * Use this when operating on a guardian.db or when you already have a store open.
+ */
+export async function writeCodebaseIntelligenceViaStore(store) {
+    const archEntry = await store.readSpec("architecture.snapshot");
+    const uxEntry = await store.readSpec("ux.snapshot");
+    if (!archEntry || !uxEntry) {
+        throw new Error("architecture.snapshot or ux.snapshot not found in store. Run `guardian extract` first.");
+    }
+    const architecture = yaml.load(archEntry.content);
+    const ux = yaml.load(uxEntry.content);
+    const intel = buildCodebaseIntelligence(architecture, ux);
+    await store.writeSpec("codebase-intelligence", JSON.stringify(intel, null, 2), "json");
+}
+/**
+ * Load CodebaseIntelligence from a SpecsStore.
+ * Returns null if not yet built.
+ */
+export async function loadCodebaseIntelligenceViaStore(store) {
+    const entry = await store.readSpec("codebase-intelligence");
+    if (!entry)
+        return null;
+    return JSON.parse(entry.content);
+}

package/dist/extract/compress.js

@@ -319,6 +319,7 @@ function buildHeatmapFromGraph(level, nodes, edges, nodeLayers) {
         }
     }
     const cycleNodes = findCycleNodes(nodes, adjacency, reverse);
+    const pageRank = computePageRank(nodes, adjacency, reverse);
     const degreeValues = nodes.map((node) => (outbound.get(node) ?? 0) + (inbound.get(node) ?? 0));
     const maxDegree = Math.max(1, ...degreeValues);
     const maxCrossRatio = Math.max(1, ...nodes.map((node) => {
@@ -332,15 +333,22 @@ function buildHeatmapFromGraph(level, nodes, edges, nodeLayers) {
         const out = outbound.get(node) ?? 0;
         const crossRatio = out === 0 ? 0 : crossOut / out;
         const cycleFlag = cycleNodes.has(node) ? 1 : 0;
-        const score = 0.5 * (degree / maxDegree) +
-            0.3 * (crossRatio / maxCrossRatio) +
-            0.2 * cycleFlag;
+        const pr = pageRank.get(node) ?? 0;
+        // PageRank (40%) — importance by what depends on this node
+        // Degree   (30%) — raw connectivity (fallback signal)
+        // Cross-layer (20%) — architectural violation risk
+        // Cycle    (10%) — circular dependency penalty
+        const score = 0.4 * pr +
+            0.3 * (degree / maxDegree) +
+            0.2 * (crossRatio / maxCrossRatio) +
+            0.1 * cycleFlag;
         return {
             id: node,
             layer: nodeLayers.get(node) ?? "unknown",
             score: round(score, 4),
             components: {
                 degree,
+                pagerank: round(pr, 4),
                 cross_layer_ratio: round(crossRatio, 4),
                 cycle: cycleFlag
             }
@@ -368,6 +376,65 @@ function resolveDomainForModule(moduleId, domainMap) {
     }
     return null;
 }
+/**
+ * Iterative PageRank over a directed graph.
+ * Returns a map of node → normalized score in [0, 1].
+ *
+ * Semantics: a node is important if many important nodes import/depend on it.
+ * Damping factor α=0.85 (web-standard). Converges in ~20 iterations for
+ * codebases with <10K files.
+ *
+ * Edge direction follows dependency arrows (A imports B → edge A→B).
+ * Rank flows *backward*: B gains rank because A depends on it, meaning
+ * files that many other files rely on get high scores — exactly what we
+ * want to surface in AI context.
+ */
+function computePageRank(nodes, adjacency, // forward edges (importer → imported)
+reverse // backward edges (imported → importers)
+) {
+    const N = nodes.length;
+    if (N === 0)
+        return new Map();
+    const DAMPING = 0.85;
+    const ITERATIONS = 30;
+    const BASE = (1 - DAMPING) / N;
+    // Initialize uniform rank
+    const rank = new Map();
+    for (const node of nodes)
+        rank.set(node, 1 / N);
+    // Precompute out-degrees (how many nodes each node imports)
+    const outDeg = new Map();
+    for (const node of nodes)
+        outDeg.set(node, (adjacency.get(node) ?? []).length);
+    // Dangling nodes (no outgoing edges) distribute rank uniformly
+    for (let iter = 0; iter < ITERATIONS; iter++) {
+        const next = new Map();
+        // Dangling mass: sum of ranks of sink nodes spread across all nodes
+        let danglingMass = 0;
+        for (const node of nodes) {
+            if ((outDeg.get(node) ?? 0) === 0) {
+                danglingMass += (rank.get(node) ?? 0);
+            }
+        }
+        const danglingContrib = DAMPING * danglingMass / N;
+        for (const node of nodes) {
+            let incoming = 0;
+            for (const importer of (reverse.get(node) ?? [])) {
+                const d = outDeg.get(importer) ?? 1;
+                incoming += (rank.get(importer) ?? 0) / d;
+            }
+            next.set(node, BASE + danglingContrib + DAMPING * incoming);
+        }
+        for (const node of nodes)
+            rank.set(node, next.get(node) ?? 0);
+    }
+    // Normalize to [0, 1] relative to max
+    const max = Math.max(1e-10, ...Array.from(rank.values()));
+    const normalized = new Map();
+    for (const [node, r] of rank.entries())
+        normalized.set(node, r / max);
+    return normalized;
+}
 function findCycleNodes(nodes, adjacency, reverse) {
     const visited = new Set();
     const order = [];

package/dist/extract/context-block.js

@@ -29,8 +29,17 @@ export function renderContextBlock(architecture, ux, options) {
         }
         lines.push("");
     }
-    // Cross-module dependencies
-    const crossEdges = architecture.dependencies.module_graph.filter(e => e.from !== e.to);
+    // Cross-module dependencies (deduplicated)
+    const seenEdges = new Set();
+    const crossEdges = architecture.dependencies.module_graph.filter(e => {
+        if (e.from === e.to)
+            return false;
+        const key = `${e.from}→${e.to}`;
+        if (seenEdges.has(key))
+            return false;
+        seenEdges.add(key);
+        return true;
+    });
     if (crossEdges.length > 0) {
         lines.push("### Module Dependencies");
         for (const edge of crossEdges.slice(0, 10)) {

package/dist/extract/function-intel.js

@@ -160,8 +160,10 @@ async function listSourceFiles(dir, config, results = []) {
  * Scan one or more project roots, run adapters on every source file, and
  * return the aggregated FunctionIntelligence index.
  */
-export async function buildFunctionIntelligenceFromRoots(roots, config) {
+export async function buildFunctionIntelligenceFromRoots(roots, config, projectRoot) {
     const allFunctions = [];
+    // Relativize against project root if provided; otherwise fall back to the scan root
+    const baseDir = projectRoot ?? roots[0];
     for (const root of roots) {
         const files = await listSourceFiles(root, config);
         await Promise.all(files.map(async (filePath) => {
@@ -177,7 +179,8 @@ export async function buildFunctionIntelligenceFromRoots(roots, config) {
             }
             try {
                 const result = runAdapter(adapter, filePath, source);
-                allFunctions.push(...result.functions);
+                const relPath = path.relative(baseDir, filePath);
+                allFunctions.push(...result.functions.map(fn => ({ ...fn, file: relPath })));
             }
             catch {
                 // Skip files that fail to parse (malformed source, encoding issues)

package/dist/extract/index.js

@@ -191,8 +191,7 @@ export async function extractProject(options) {
     // Generate Function Intelligence — call graph, literal index across all languages.
     // Runs as an additive second pass; never modifies the architecture snapshot.
     try {
-        const allRoots = (architecture.project.roots ?? [projectRoot]).map((r) => path.isAbsolute(r) ? r : path.join(projectRoot, r));
-        const funcIntel = await buildFunctionIntelligenceFromRoots(allRoots, config);
+        const funcIntel = await buildFunctionIntelligenceFromRoots([projectRoot], config, projectRoot);
         await writeFunctionIntelligence(layout.machineDir, funcIntel);
     }
     catch (err) {
@@ -421,27 +420,6 @@ function mergeFrontendAnalyses(results, _roots, _workspaceRoot) {
         tests: results.flatMap(r => r.tests)
     };
 }
-function findCommonRoot(paths) {
-    if (paths.length === 0) {
-        return process.cwd();
-    }
-    const splitPaths = paths.map((entry) => path.resolve(entry).split(path.sep));
-    const minLength = Math.min(...splitPaths.map((parts) => parts.length));
-    const shared = [];
-    for (let i = 0; i < minLength; i += 1) {
-        const segment = splitPaths[0][i];
-        if (splitPaths.every((parts) => parts[i] === segment)) {
-            shared.push(segment);
-        }
-        else {
-            break;
-        }
-    }
-    if (shared.length === 0) {
-        return path.parse(paths[0]).root;
-    }
-    return shared.join(path.sep);
-}
 async function loadPreviousSnapshots(machineDir, rootDir) {
     const result = {};
     const candidates = [

package/dist/extract/writer.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import yaml from "js-yaml";
+// ── File-based (original, unchanged) ─────────────────────────────────────────
 export async function writeSnapshots(outputDir, architecture, ux) {
     await fs.mkdir(outputDir, { recursive: true });
     const architecturePath = path.join(outputDir, "architecture.snapshot.yaml");
@@ -9,3 +10,8 @@ export async function writeSnapshots(outputDir, architecture, ux) {
     await fs.writeFile(uxPath, yaml.dump(ux, { noRefs: true, lineWidth: 120 }));
     return { architecturePath, uxPath };
 }
+// ── Store-based (new — works with FileSpecsStore or SqliteSpecsStore) ─────────
+export async function writeSnapshotsViaStore(store, architecture, ux) {
+    await store.writeSpec("architecture.snapshot", yaml.dump(architecture, { noRefs: true, lineWidth: 120 }), "yaml");
+    await store.writeSpec("ux.snapshot", yaml.dump(ux, { noRefs: true, lineWidth: 120 }), "yaml");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolbaux/guardian",
-  "version": "0.1.22",
+  "version": "0.2.0",
   "type": "module",
   "description": "Architectural intelligence for codebases. Verify that AI-generated code matches your architectural intent.",
   "keywords": [
@@ -53,6 +53,8 @@
     "benchmark:llm": "tsx scripts/benchmark-llm-context/index.ts"
   },
   "dependencies": {
+    "@xenova/transformers": "^2.17.2",
+    "better-sqlite3": "^12.8.0",
     "commander": "^12.1.0",
     "dotenv": "^17.3.1",
     "js-yaml": "^4.1.0",
@@ -67,6 +69,7 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.11.30",
     "@vitest/coverage-v8": "^4.1.0",