@getripple/core 1.0.4 → 1.0.6

package/dist/graph.js

@@ -57,15 +57,12 @@ const ts_morph_1 = require("ts-morph");
 const types_1 = require("./types");
 const normalizer_1 = require("./normalizer");
 const adapters_1 = require("./adapters");
-// ────────────────────────────────────────────────────────────────────────────
-// PERSISTENCE AND GENERATED CONTEXT
-// ────────────────────────────────────────────────────────────────────────────
 /**
  * Handles durable project state:
  * - .ripple/history.json for human-auditable change history
  * - .ripple/.cache/graph.cache.json for fast startup
- * - .ripple/.cache/context*.json and focus files for AI agents
- * - .ripple/WORKFLOW.md for agent operating rules
+ * - optional .ripple/.cache/context*.json and focus files for file-based agents
+ * - optional .ripple/WORKFLOW.md for agent operating rules
  */
 class GraphPersistence {
     /**
@@ -76,7 +73,7 @@ class GraphPersistence {
         this.patternCache = null;
     }
     constructor(workspaceRoot) {
-        this.contextGenerationEnabled = true;
+        this.contextGenerationMode = "full";
         this.patternCache = null;
         this.workspaceRoot = workspaceRoot;
         const rippleDir = path.join(workspaceRoot, ".ripple");
@@ -189,34 +186,20 @@ class GraphPersistence {
      * Restores graph nodes from cache and returns files whose content hash changed
      * since the cache was written. Stale files are repaired by the scan phase.
      */
-    loadCache(graph) {
+    loadCache(graph, options = {}) {
         try {
             if (!fs.existsSync(this.cachePath)) {
                 return [];
             }
             const raw = fs.readFileSync(this.cachePath, "utf8");
             const data = JSON.parse(raw);
+            const checkHashes = options.checkHashes ?? true;
             const staleFiles = [];
             const loadedFilePaths = new Set();
             Object.entries(data.files).forEach(([filePath, node]) => {
                 if (!fs.existsSync(filePath)) {
                     return;
                 }
-                const currentContent = (() => {
-                    try {
-                        return fs.readFileSync(filePath, "utf8");
-                    }
-                    catch {
-                        return null;
-                    }
-                })();
-                if (currentContent === null) {
-                    return;
-                }
-                const currentHash = crypto
-                    .createHash("sha1")
-                    .update(currentContent)
-                    .digest("hex");
                 const fileNode = {
                     path: node.path,
                     imports: new Set(node.imports),
@@ -230,7 +213,7 @@ class GraphPersistence {
                 };
                 graph.files.set(filePath, fileNode);
                 loadedFilePaths.add(filePath);
-                if (currentHash !== node.hash) {
+                if (checkHashes && this.cachedFileIsStale(filePath, node.hash)) {
                     staleFiles.push(filePath);
                 }
             });
@@ -263,6 +246,18 @@ class GraphPersistence {
             return [];
         }
     }
+    cachedFileIsStale(filePath, cachedHash) {
+        try {
+            const currentHash = crypto
+                .createHash("sha1")
+                .update(fs.readFileSync(filePath, "utf8"))
+                .digest("hex");
+            return currentHash !== cachedHash;
+        }
+        catch {
+            return false;
+        }
+    }
     toProjectPath(filePath) {
         return path.relative(this.workspaceRoot, filePath).split(path.sep).join("/");
     }
@@ -582,7 +577,7 @@ class GraphPersistence {
      * - focus files and WORKFLOW.md for targeted agent workflows
      */
     generateContext(graph, history) {
-        if (!this.contextGenerationEnabled) {
+        if (this.contextGenerationMode !== "full") {
             return;
         }
         try {
@@ -1509,7 +1504,7 @@ ${ambiguousBasenameExamples.map(e => `- ${e}`).join("\n")}` : ""}
      * debounced separately, but the target focus file should be fresh immediately.
      */
     generateSingleFocus(graph, filePath) {
-        if (!this.contextGenerationEnabled) {
+        if (this.contextGenerationMode === "lean") {
             return;
         }
         try {
@@ -1617,11 +1612,20 @@ function isPythonIdentifier(value) {
 // ────────────────────────────────────────────────────────────────────────────
 class GraphEngine {
     /**
-     * Disables writing .ripple/ context files while keeping the in-memory graph
-     * available for editor features.
+     * Chooses how much file-based context Ripple writes for the active interface.
+     *
+     * full      — VS Code/file-based agent mode; writes WORKFLOW.md and focus files.
+     * lean      — CLI gate/check mode; writes only durable history and graph cache.
+     * on-demand — MCP mode; skips broad dumps but allows targeted focus writes.
+     */
+    setContextGenerationMode(mode) {
+        this.persistence.contextGenerationMode = mode;
+    }
+    /**
+     * Backwards-compatible switch used by older callers and tests.
      */
     setContextGeneration(enabled) {
-        this.persistence.contextGenerationEnabled = enabled;
+        this.setContextGenerationMode(enabled ? "full" : "lean");
     }
     constructor(workspaceRoot) {
         // Scans rebuild a large part of the graph. File-system events that arrive
@@ -1632,6 +1636,7 @@ class GraphEngine {
         this.pendingDeletes = new Set();
         this.pendingFullRescan = false;
         this.sessionNewFiles = new Set();
+        this.focusKeyCache = new Map();
         this.workspaceRoot = workspaceRoot;
         this.graph = new types_1.SystemGraph();
         this.history = new types_1.HistoryLog();
@@ -1648,6 +1653,29 @@ class GraphEngine {
     invalidateAdapterSupport() {
         this.adapterSupportCache = undefined;
     }
+    invalidateFocusKeyCache() {
+        this.focusKeyCache.clear();
+        this.focusBaseKeyCounts = undefined;
+    }
+    focusKeyForPath(filePath) {
+        const cached = this.focusKeyCache.get(filePath);
+        if (cached) {
+            return cached;
+        }
+        if (!this.focusBaseKeyCounts) {
+            this.focusBaseKeyCounts = new Map();
+            this.graph.files.forEach((_, graphFilePath) => {
+                const baseKey = getBaseKey(graphFilePath);
+                this.focusBaseKeyCounts.set(baseKey, (this.focusBaseKeyCounts.get(baseKey) ?? 0) + 1);
+            });
+        }
+        const baseKey = getBaseKey(filePath);
+        const focusKey = (this.focusBaseKeyCounts.get(baseKey) ?? 0) > 1
+            ? `${baseKey}-${crypto.createHash("sha1").update(filePath).digest("hex").slice(0, 6)}`
+            : baseKey;
+        this.focusKeyCache.set(filePath, focusKey);
+        return focusKey;
+    }
     createProject() {
         return new ts_morph_1.Project({
             compilerOptions: {
@@ -1745,6 +1773,7 @@ class GraphEngine {
             this.graph.files.clear();
             this.graph.symbols.clear();
             this.project = this.createProject();
+            this.invalidateFocusKeyCache();
             this.sessionNewFiles.clear();
             let scanned = 0;
             const total = validFiles.length * 2;
@@ -1794,6 +1823,61 @@ class GraphEngine {
             await this.rebuildFromDisk(onProgress, priorityFile);
         }
     }
+    /**
+     * Fast path for live agent gates. It trusts the existing graph cache instead
+     * of hash-checking every source file, then only parses candidate files that
+     * are missing from the cache. If no cache exists, it falls back to the normal
+     * scan so first-time use remains correct.
+     */
+    async fastCheckScan(candidateFiles = [], onProgress) {
+        this.isScanning = true;
+        this.invalidateAdapterSupport();
+        this.graph.files.clear();
+        this.graph.symbols.clear();
+        this.project = this.createProject();
+        this.invalidateFocusKeyCache();
+        const normalizedCandidates = candidateFiles
+            .map((filePath) => this.resolveFilePath(filePath))
+            .filter((filePath, index, values) => values.indexOf(filePath) === index &&
+            !shouldIgnore(filePath) &&
+            fs.existsSync(filePath) &&
+            /\.(ts|tsx|js|jsx|py)$/i.test(filePath) &&
+            !filePath.endsWith(".d.ts"));
+        this.persistence.loadCache(this.graph, { checkHashes: false });
+        this.isScanning = false;
+        if (this.graph.files.size === 0) {
+            await this.initialScan(onProgress, normalizedCandidates[0]);
+            return;
+        }
+        let scanned = 0;
+        const total = normalizedCandidates.length * 2;
+        normalizedCandidates
+            .filter((filePath) => !this.graph.files.has(filePath))
+            .forEach((filePath) => {
+            try {
+                this.ensureFileNode(filePath);
+                this.parseImportsAndExports(filePath, false);
+            }
+            catch {
+                console.warn("[Ripple] Fast check parse error:", filePath);
+            }
+            scanned++;
+            onProgress?.(scanned, total);
+        });
+        normalizedCandidates
+            .filter((filePath) => this.graph.files.has(filePath))
+            .forEach((filePath) => {
+            try {
+                this.parseCallsOnly(filePath);
+            }
+            catch {
+                console.warn("[Ripple] Fast check call parse error:", filePath);
+            }
+            scanned++;
+            onProgress?.(scanned, total);
+        });
+        this.processPendingChanges();
+    }
     // ── INITIAL SCAN ──────────────────────────────────────────────────────────
     /**
      * Starts from cache when possible and repairs only stale or newly discovered
@@ -3067,6 +3151,7 @@ class GraphEngine {
                 changeCount: 0,
                 hash: "",
             });
+            this.invalidateFocusKeyCache();
         }
         return this.graph.files.get(filePath);
     }
@@ -3118,7 +3203,7 @@ class GraphEngine {
         return "safe";
     }
     focusPathFor(filePath) {
-        return `.ripple/.cache/focus/${makeFocusKey(filePath, this.graph)}.json`;
+        return `.ripple/.cache/focus/${this.focusKeyForPath(filePath)}.json`;
     }
     dependencyLinkFor(filePath) {
         const node = this.graph.files.get(filePath);
@@ -3241,7 +3326,10 @@ class GraphEngine {
         return Array.from(this.graph.files.get(filePath)?.imports ?? []);
     }
     focusKeyForFile(filePath) {
-        return makeFocusKey(filePath, this.graph);
+        return this.focusKeyForPath(filePath);
+    }
+    writeFileFocus(filePath) {
+        this.persistence.generateSingleFocus(this.graph, this.resolveFilePath(filePath));
     }
     symbolImpact(symbolId) {
         return Array.from(this.graph.symbols.get(symbolId)?.calledBy ?? []);
@@ -4059,7 +4147,7 @@ class GraphEngine {
         return {
             filePath: resolvedPath,
             projectPath: this.toProjectPath(resolvedPath),
-            focusKey: makeFocusKey(resolvedPath, this.graph),
+            focusKey: this.focusKeyForPath(resolvedPath),
             focusPath: this.focusPathFor(resolvedPath),
             modificationRisk: this.modificationRiskFor(node),
             imports,