@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/knowledge/graph-adapter.js

@@ -0,0 +1,288 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+                     
+             
+                
+                
+                
+                
+ 
+
+                     
+                 
+                 
+                                                                                                  
+                  
+ 
+
+                       
+                                                               
+                                                                 
+                                                                   
+                                                          
+ 
+
+                                 
+                      
+                                                                    
+                                                                    
+                                
+                                                                                                
+               
+ 
+
+                                
+              
+                  
+                     
+                     
+            
+                       
+                         
+                          
+                       
+    
+                 
+ 
+
+function clampBounds(bounds                       )              {
+  const maxHops = Math.min(3, Math.max(1, bounds?.maxHops ?? 2));
+  const maxSeeds = Math.min(10, Math.max(1, bounds?.maxSeeds ?? 1));
+  const maxNodes = Math.min(100, Math.max(1, bounds?.maxNodes ?? 50));
+  return {
+    maxHops,
+    maxSeeds,
+    maxNodes,
+    edgeTypes: bounds?.edgeTypes,
+  };
+}
+
+async function traverseGraphRelationships(
+  options                       
+)                                {
+  const started = Number(process.hrtime.bigint() / 1000000n);
+  const bounds = clampBounds(options.bounds);
+  const direction = options.direction || 'both';
+  const fsImpl = options.fsImpl || fs;
+
+  let graphData                                            ;
+  if (options.graphData) {
+    graphData = options.graphData;
+  } else {
+    const graphFile = path.join(options.projectRoot, 'graphify-out', 'graph.json');
+    try {
+      if (!fsImpl.existsSync(graphFile)) {
+        return {
+          ok: false,
+          seeds: options.seeds,
+          nodes: [],
+          edges: [],
+          metrics: {
+            durationMs: Math.round(Number(process.hrtime.bigint() / 1000000n) - started),
+            nodesScanned: 0,
+            hopsTraversed: 0,
+            truncated: false,
+          },
+          error: `Graph file not found at ${graphFile}`,
+        };
+      }
+      const raw = fsImpl.readFileSync(graphFile, 'utf8');
+      graphData = JSON.parse(raw);
+    } catch (err     ) {
+      return {
+        ok: false,
+        seeds: options.seeds,
+        nodes: [],
+        edges: [],
+        metrics: {
+          durationMs: Math.round(Number(process.hrtime.bigint() / 1000000n) - started),
+          nodesScanned: 0,
+          hopsTraversed: 0,
+          truncated: false,
+        },
+        error: `Failed to load graph file: ${err.message}`,
+      };
+    }
+  }
+
+  const nodes              = Array.isArray(graphData.nodes) ? graphData.nodes : [];
+  const edges              = Array.isArray(graphData.edges) ? graphData.edges : [];
+
+  const nodeById = new Map                   ();
+  const nodesByLabel = new Map                     ();
+  const nodesByFile = new Map                     ();
+
+  for (const node of nodes) {
+    nodeById.set(node.id, node);
+    if (node.label) {
+      const list = nodesByLabel.get(node.label) || [];
+      list.push(node);
+      nodesByLabel.set(node.label, list);
+    }
+    if (node.file) {
+      const list = nodesByFile.get(node.file) || [];
+      list.push(node);
+      nodesByFile.set(node.file, list);
+    }
+  }
+
+  const outgoing = new Map                     ();
+  const incoming = new Map                     ();
+
+  for (const edge of edges) {
+    if (!edge.source || !edge.target) continue;
+    const outList = outgoing.get(edge.source) || [];
+    outList.push(edge);
+    outgoing.set(edge.source, outList);
+
+    const inList = incoming.get(edge.target) || [];
+    inList.push(edge);
+    incoming.set(edge.target, inList);
+  }
+
+  const inputSeeds = options.seeds.slice(0, bounds.maxSeeds);
+  const resolvedSeedNodes              = [];
+  const resolvedSeedIds = new Set        ();
+
+  for (const seed of inputSeeds) {
+    if (nodeById.has(seed)) {
+      const n = nodeById.get(seed) ;
+      if (!resolvedSeedIds.has(n.id)) {
+        resolvedSeedIds.add(n.id);
+        resolvedSeedNodes.push(n);
+      }
+    } else if (nodesByLabel.has(seed)) {
+      for (const n of nodesByLabel.get(seed) ) {
+        if (!resolvedSeedIds.has(n.id)) {
+          resolvedSeedIds.add(n.id);
+          resolvedSeedNodes.push(n);
+        }
+      }
+    } else if (nodesByFile.has(seed)) {
+      for (const n of nodesByFile.get(seed) ) {
+        if (!resolvedSeedIds.has(n.id)) {
+          resolvedSeedIds.add(n.id);
+          resolvedSeedNodes.push(n);
+        }
+      }
+    } else {
+      for (const node of nodes) {
+        if (
+          (node.file && node.file.includes(seed)) ||
+          (node.label && node.label.toLowerCase() === seed.toLowerCase())
+        ) {
+          if (!resolvedSeedIds.has(node.id)) {
+            resolvedSeedIds.add(node.id);
+            resolvedSeedNodes.push(node);
+          }
+        }
+      }
+    }
+  }
+
+  const visited = new Set        ();
+  const resultNodes              = [];
+  const resultEdges              = [];
+  const edgeSet = new Set        ();
+
+                       
+                   
+                
+   
+
+  const queue              = [];
+  let truncated = false;
+  let nodesScanned = 0;
+  let hopsTraversed = 0;
+
+  for (const seedNode of resolvedSeedNodes) {
+    if (resultNodes.length >= bounds.maxNodes) {
+      truncated = true;
+      break;
+    }
+    visited.add(seedNode.id);
+    resultNodes.push(seedNode);
+    queue.push({ nodeId: seedNode.id, hop: 0 });
+  }
+
+  const allowedEdgeTypes = bounds.edgeTypes ? new Set(bounds.edgeTypes) : null;
+
+  while (queue.length > 0) {
+    const { nodeId, hop } = queue.shift() ;
+    nodesScanned++;
+    if (hop > hopsTraversed) {
+      hopsTraversed = hop;
+    }
+
+    if (hop >= bounds.maxHops) {
+      continue;
+    }
+
+    const edgesToTraverse                                                 = [];
+
+    if (direction === 'downstream' || direction === 'both') {
+      const outEdges = outgoing.get(nodeId) || [];
+      for (const edge of outEdges) {
+        if (allowedEdgeTypes && !allowedEdgeTypes.has(edge.relation)) continue;
+        edgesToTraverse.push({ edge, neighborId: edge.target });
+      }
+    }
+
+    if (direction === 'upstream' || direction === 'both') {
+      const inEdges = incoming.get(nodeId) || [];
+      for (const edge of inEdges) {
+        if (allowedEdgeTypes && !allowedEdgeTypes.has(edge.relation)) continue;
+        edgesToTraverse.push({ edge, neighborId: edge.source });
+      }
+    }
+
+    for (const { edge, neighborId } of edgesToTraverse) {
+      const edgeKey = `${edge.source}->${edge.relation}->${edge.target}`;
+      if (!edgeSet.has(edgeKey)) {
+        edgeSet.add(edgeKey);
+        resultEdges.push(edge);
+      }
+
+      if (visited.has(neighborId)) {
+        continue;
+      }
+
+      const neighborNode = nodeById.get(neighborId);
+      if (!neighborNode) continue;
+
+      if (resultNodes.length >= bounds.maxNodes) {
+        truncated = true;
+        break;
+      }
+
+      visited.add(neighborId);
+      resultNodes.push(neighborNode);
+      queue.push({ nodeId: neighborId, hop: hop + 1 });
+    }
+
+    if (truncated) break;
+  }
+
+  const durationMs = Math.round(Number(process.hrtime.bigint() / 1000000n) - started);
+
+  return {
+    ok: true,
+    seeds: inputSeeds,
+    nodes: resultNodes,
+    edges: resultEdges,
+    metrics: {
+      durationMs,
+      nodesScanned,
+      hopsTraversed,
+      truncated,
+    },
+  };
+}
+
+module.exports = {
+  clampBounds,
+  traverseGraphRelationships,
+};

package/src/runtime/knowledge/graph-fallback.js

@@ -0,0 +1,394 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { traverseGraphRelationships, clampBounds } = require('./graph-adapter.js');
+const { resolveRolloutProfile } = require('../profiles/resolve.js');
+
+                                                                      
+
+                              
+                               
+                    
+                              
+                                     
+                 
+ 
+
+                                    
+                      
+                 
+                                                       
+               
+                                         
+ 
+
+                            
+               
+                
+                   
+                  
+ 
+
+                             
+                            
+               
+                
+                                         
+                    
+ 
+
+                                  
+                
+                 
+                                           
+                                                 
+                                  
+                                                                                                                             
+                                  
+                     
+                         
+ 
+
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  'graphify-out',
+  '.doflow',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  '.venv',
+  'venv',
+  '__pycache__',
+]);
+
+function findNewestSourceMtime(
+  dir        ,
+  fsImpl      = fs,
+  limit         = 2000
+)                                            {
+  let newest                = null;
+  let count = 0;
+  const queue = [dir];
+
+  while (queue.length > 0 && count < limit) {
+    const current = queue.shift() ;
+    let entries        = [];
+    try {
+      entries = fsImpl.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const name = typeof entry === 'string' ? entry : entry.name;
+      const isDir = typeof entry === 'string' ? fsImpl.statSync(path.join(current, name)).isDirectory() : entry.isDirectory();
+
+      if (name.startsWith('.') && isDir) continue;
+      if (SKIP_DIRS.has(name)) continue;
+
+      const fullPath = path.join(current, name);
+      if (isDir) {
+        queue.push(fullPath);
+      } else {
+        const isFile = typeof entry === 'string' ? fsImpl.statSync(fullPath).isFile() : entry.isFile();
+        if (isFile) {
+          count++;
+          try {
+            const stat = fsImpl.statSync(fullPath);
+            if (newest === null || stat.mtimeMs > newest) {
+              newest = stat.mtimeMs;
+            }
+          } catch {
+            // ignore vanishing files
+          }
+        }
+      }
+    }
+  }
+
+  return { mtimeMs: newest, count };
+}
+
+function evaluateGraphFreshness(
+  projectRoot        ,
+  fsImpl      = fs
+)                     {
+  const graphPath = path.join(projectRoot, 'graphify-out', 'graph.json');
+
+  let stat     ;
+  try {
+    stat = fsImpl.statSync(graphPath);
+  } catch {
+    const sourceInfo = findNewestSourceMtime(projectRoot, fsImpl);
+    return {
+      status: 'MISSING',
+      graphPath,
+      graphMtimeMs: null,
+      newestSourceMtimeMs: sourceInfo.mtimeMs,
+      detail: `Graph file not found at ${graphPath}`,
+    };
+  }
+
+  const graphMtimeMs = stat.mtimeMs;
+
+  try {
+    const raw = fsImpl.readFileSync(graphPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.nodes) || !Array.isArray(parsed.edges)) {
+      return {
+        status: 'CORRUPT',
+        graphPath,
+        graphMtimeMs,
+        newestSourceMtimeMs: null,
+        detail: 'Graph JSON does not conform to expected schema (missing nodes/edges arrays)',
+      };
+    }
+  } catch (err     ) {
+    return {
+      status: 'CORRUPT',
+      graphPath,
+      graphMtimeMs,
+      newestSourceMtimeMs: null,
+      detail: `Graph JSON is corrupt or unparseable: ${err.message}`,
+    };
+  }
+
+  const sourceInfo = findNewestSourceMtime(projectRoot, fsImpl);
+  const newestSourceMtimeMs = sourceInfo.mtimeMs;
+
+  const behindMs = newestSourceMtimeMs !== null ? Math.floor(newestSourceMtimeMs - graphMtimeMs) : 0;
+
+  if (behindMs > 50) {
+    return {
+      status: 'STALE',
+      graphPath,
+      graphMtimeMs,
+      newestSourceMtimeMs,
+      detail: `Graph index (${new Date(graphMtimeMs).toISOString()}) is older than newest source (${new Date(newestSourceMtimeMs ).toISOString()})`,
+    };
+  }
+
+  return {
+    status: 'FRESH',
+    graphPath,
+    graphMtimeMs,
+    newestSourceMtimeMs,
+    detail: 'Graph index is fresh and up-to-date with source repository',
+  };
+}
+
+async function executeLexicalSearch(
+  symbol        ,
+  projectRoot        ,
+  options                         
+)                                                                                                             {
+  if (options?.rgSearchImpl) {
+    try {
+      const matches = await options.rgSearchImpl(symbol, projectRoot);
+      return Array.isArray(matches) ? { ok: true, matches } : { ok: false, matches: [], reason: 'lexical-search-returned-invalid-results' };
+    }
+    catch (error     ) { return { ok: false, matches: [], reason: error?.message || 'lexical-search-failed' }; }
+  }
+
+  let stdout        ;
+  try {
+    stdout = execFileSync('rg', ['--no-heading', '-n', '-w', symbol, '.'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (error     ) {
+    if (error?.status === 1) return { ok: true, matches: [] };
+    // rg exits 2 when a path is unreadable even though it printed matches: keep them, fail only on empty output.
+    const partial = error?.status === 2 && typeof error.stdout === 'string' ? error.stdout : '';
+    if (!partial) return { ok: false, matches: [], reason: error?.message || error?.code || 'lexical-search-failed' };
+    stdout = partial;
+  }
+
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  const results                                                         = [];
+  for (const line of lines) {
+    const parts = line.split(':');
+    if (parts.length >= 3) {
+      const file = parts[0].replace(/^\.\//, '');
+      const lineNum = parseInt(parts[1], 10) || 1;
+      const content = parts.slice(2).join(':').trim();
+      results.push({ file, line: lineNum, content });
+    }
+  }
+  return { ok: true, matches: results };
+}
+
+async function resolveRelationshipQuery(
+  options                          ,
+  services                                                                      
+)                                  {
+  const fsImpl = services?.fsImpl || fs;
+  const freshness = evaluateGraphFreshness(options.projectRoot, fsImpl);
+  const allowStale = options.allowStale === true;
+
+  // The rollout profile turns the graph off only when one was chosen (env or settings), a rollback is active or
+  // the value is invalid; a project that sets no profile (origin registry-default) keeps the graph.
+  const profile = resolveRolloutProfile({
+    projectRoot: options.projectRoot, fsImpl: typeof fsImpl.readFileSync === 'function' ? fsImpl : undefined,
+  });
+  const profileChosen = !(profile.origin.source === 'default' && profile.origin.detail === 'registry-default');
+  const graphOff = profileChosen && profile.capabilities.graph === 'off';
+
+  const isGraphUsable = !graphOff
+    && (freshness.status === 'FRESH' || (allowStale && freshness.status === 'STALE'));
+
+  if (isGraphUsable) {
+    const direction = options.intent === 'estimate-blast-radius' ? 'upstream' : 'both';
+    const traversal = await traverseGraphRelationships({
+      projectRoot: options.projectRoot,
+      seeds: [options.symbol],
+      direction,
+      bounds: options.bounds,
+      graphData: services?.graphData,
+      fsImpl,
+    });
+
+    if (traversal.ok && traversal.nodes.length > 0) {
+      const candidates                      = traversal.nodes.map((node     , index        ) => {
+        let file = node.file ? node.file : node.id;
+        if (path.isAbsolute(file)) {
+          file = path.relative(options.projectRoot, file);
+        }
+        return {
+          locator: {
+            file,
+            line: node.line,
+            symbol: node.label || node.id,
+          },
+          rank: index + 1,
+          score: Math.max(0.1, Number((1.0 - index * 0.05).toFixed(2))),
+          source: 'graphify.query',
+          relation: node.kind,
+        };
+      });
+
+      return {
+        query: options.symbol,
+        intent: options.intent,
+        provider: 'graphify.query',
+        status: 'HEALTHY',
+        freshness: freshness.status,
+        candidates,
+        isAbsence: false,
+      };
+    }
+
+    const lexical = await executeLexicalSearch(options.symbol, options.projectRoot, {
+      rgSearchImpl: services?.rgSearchImpl,
+    });
+    if (!lexical.ok) return {
+      query: options.symbol, intent: options.intent, provider: 'native.rg', status: 'UNAVAILABLE',
+      freshness: freshness.status, fallbackReason: 'lexical-failed', candidates: [], isAbsence: false,
+      absenceReason: `Lexical fallback failed: ${lexical.reason}`,
+    };
+    const lexMatches = lexical.matches;
+
+    if (lexMatches.length > 0) {
+      const candidates                      = lexMatches.slice(0, 50).map((match, index) => ({
+        locator: {
+          file: match.file,
+          line: match.line,
+          symbol: options.symbol,
+        },
+        rank: index + 1,
+        score: Math.max(0.1, Number((0.8 - index * 0.02).toFixed(2))),
+        source: 'native.rg',
+      }));
+
+      return {
+        query: options.symbol,
+        intent: options.intent,
+        provider: 'native.rg',
+        status: 'FALLBACK',
+        freshness: freshness.status,
+        fallbackReason: 'graph-empty',
+        candidates,
+        isAbsence: false,
+      };
+    }
+
+    return {
+      query: options.symbol,
+      intent: options.intent,
+      provider: 'native.rg',
+      status: 'FALLBACK',
+      freshness: freshness.status,
+      fallbackReason: 'graph-empty',
+      candidates: [],
+      isAbsence: true,
+      absenceReason: `Both graph traversal and lexical search confirmed zero occurrences of '${options.symbol}'`,
+    };
+  }
+
+  const fallbackReason                                                                         = graphOff
+    ? 'profile-disabled'
+    : freshness.status === 'STALE'
+      ? 'index-stale'
+      : freshness.status === 'MISSING'
+      ? 'index-missing'
+      : 'index-corrupt';
+
+  const lexical = await executeLexicalSearch(options.symbol, options.projectRoot, {
+    rgSearchImpl: services?.rgSearchImpl,
+  });
+  if (!lexical.ok) return {
+    query: options.symbol, intent: options.intent, provider: 'native.rg', status: 'UNAVAILABLE',
+    freshness: freshness.status, fallbackReason: 'lexical-failed', candidates: [], isAbsence: false,
+    absenceReason: `Lexical fallback failed: ${lexical.reason}`,
+  };
+  const lexMatches = lexical.matches;
+
+  if (lexMatches.length > 0) {
+    const candidates                      = lexMatches.slice(0, 50).map((match, index) => ({
+      locator: {
+        file: match.file,
+        line: match.line,
+        symbol: options.symbol,
+      },
+      rank: index + 1,
+      score: Math.max(0.1, Number((0.8 - index * 0.02).toFixed(2))),
+      source: 'native.rg',
+    }));
+
+    return {
+      query: options.symbol,
+      intent: options.intent,
+      provider: 'native.rg',
+      status: 'FALLBACK',
+      freshness: freshness.status,
+      fallbackReason,
+      candidates,
+      isAbsence: false,
+    };
+  }
+
+  return {
+    query: options.symbol,
+    intent: options.intent,
+    provider: 'native.rg',
+    status: 'FALLBACK',
+    freshness: freshness.status,
+    fallbackReason,
+    candidates: [],
+    isAbsence: true,
+    absenceReason: `Lexical search confirmed zero occurrences of '${options.symbol}' across repository`,
+  };
+}
+
+module.exports = {
+  findNewestSourceMtime,
+  evaluateGraphFreshness,
+  executeLexicalSearch,
+  resolveRelationshipQuery,
+};