@harness-engineering/graph 0.4.0 → 0.4.1

package/dist/index.js

@@ -33,7 +33,9 @@ __export(index_exports, {
   Assembler: () => Assembler,
   CIConnector: () => CIConnector,
   CURRENT_SCHEMA_VERSION: () => CURRENT_SCHEMA_VERSION,
+  CascadeSimulator: () => CascadeSimulator,
   CodeIngestor: () => CodeIngestor,
+  CompositeProbabilityStrategy: () => CompositeProbabilityStrategy,
   ConflictPredictor: () => ConflictPredictor,
   ConfluenceConnector: () => ConfluenceConnector,
   ContextQL: () => ContextQL,
@@ -68,6 +70,7 @@ __export(index_exports, {
   VERSION: () => VERSION,
   VectorStore: () => VectorStore,
   askGraph: () => askGraph,
+  classifyNodeCategory: () => classifyNodeCategory,
   groupNodesByImpact: () => groupNodesByImpact,
   linkToCode: () => linkToCode,
   loadGraph: () => loadGraph,
@@ -241,6 +244,16 @@ function removeFromIndex(index, key, edge) {
   if (idx !== -1) list.splice(idx, 1);
   if (list.length === 0) index.delete(key);
 }
+function filterEdges(candidates, query) {
+  const results = [];
+  for (const edge of candidates) {
+    if (query.from !== void 0 && edge.from !== query.from) continue;
+    if (query.to !== void 0 && edge.to !== query.to) continue;
+    if (query.type !== void 0 && edge.type !== query.type) continue;
+    results.push({ ...edge });
+  }
+  return results;
+}
 var GraphStore = class {
   nodeMap = /* @__PURE__ */ new Map();
   edgeMap = /* @__PURE__ */ new Map();
@@ -308,27 +321,25 @@ var GraphStore = class {
     }
   }
   getEdges(query) {
-    let candidates;
     if (query.from !== void 0 && query.to !== void 0 && query.type !== void 0) {
       const edge = this.edgeMap.get(edgeKey(query.from, query.to, query.type));
       return edge ? [{ ...edge }] : [];
-    } else if (query.from !== void 0) {
-      candidates = this.edgesByFrom.get(query.from) ?? [];
-    } else if (query.to !== void 0) {
-      candidates = this.edgesByTo.get(query.to) ?? [];
-    } else if (query.type !== void 0) {
-      candidates = this.edgesByType.get(query.type) ?? [];
-    } else {
-      candidates = this.edgeMap.values();
     }
-    const results = [];
-    for (const edge of candidates) {
-      if (query.from !== void 0 && edge.from !== query.from) continue;
-      if (query.to !== void 0 && edge.to !== query.to) continue;
-      if (query.type !== void 0 && edge.type !== query.type) continue;
-      results.push({ ...edge });
+    const candidates = this.selectCandidates(query);
+    return filterEdges(candidates, query);
+  }
+  /** Pick the most selective index to start from. */
+  selectCandidates(query) {
+    if (query.from !== void 0) {
+      return this.edgesByFrom.get(query.from) ?? [];
     }
-    return results;
+    if (query.to !== void 0) {
+      return this.edgesByTo.get(query.to) ?? [];
+    }
+    if (query.type !== void 0) {
+      return this.edgesByType.get(query.type) ?? [];
+    }
+    return this.edgeMap.values();
   }
   getNeighbors(nodeId, direction = "both") {
     const neighborIds = /* @__PURE__ */ new Set();
@@ -624,6 +635,12 @@ var CODE_TYPES = /* @__PURE__ */ new Set([
   "method",
   "variable"
 ]);
+function classifyNodeCategory(node) {
+  if (TEST_TYPES.has(node.type)) return "tests";
+  if (DOC_TYPES.has(node.type)) return "docs";
+  if (CODE_TYPES.has(node.type)) return "code";
+  return "other";
+}
 function groupNodesByImpact(nodes, excludeId) {
   const tests = [];
   const docs = [];
@@ -631,15 +648,11 @@ function groupNodesByImpact(nodes, excludeId) {
   const other = [];
   for (const node of nodes) {
     if (excludeId && node.id === excludeId) continue;
-    if (TEST_TYPES.has(node.type)) {
-      tests.push(node);
-    } else if (DOC_TYPES.has(node.type)) {
-      docs.push(node);
-    } else if (CODE_TYPES.has(node.type)) {
-      code.push(node);
-    } else {
-      other.push(node);
-    }
+    const category = classifyNodeCategory(node);
+    if (category === "tests") tests.push(node);
+    else if (category === "docs") docs.push(node);
+    else if (category === "code") code.push(node);
+    else other.push(node);
   }
   return { tests, docs, code, other };
 }
@@ -1604,7 +1617,7 @@ var RequirementIngestor = class {
     }
     for (const featureDir of featureDirs) {
       const featureName = path4.basename(featureDir);
-      const specPath = path4.join(featureDir, "proposal.md");
+      const specPath = path4.join(featureDir, "proposal.md").replaceAll("\\", "/");
       let content;
       try {
         content = await fs3.readFile(specPath, "utf-8");
@@ -1754,7 +1767,7 @@ var RequirementIngestor = class {
         const escaped = node.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
         const namePattern = new RegExp(`\\b${escaped}\\b`, "i");
         if (namePattern.test(reqText)) {
-          const edgeType = node.path && node.path.replace(/\\/g, "/").includes("/tests/") ? "verified_by" : "requires";
+          const edgeType = node.path?.replace(/\\/g, "/").includes("/tests/") ? "verified_by" : "requires";
           this.store.addEdge({
             from: reqId,
             to: node.id,
@@ -2971,6 +2984,7 @@ var INTENT_SIGNALS = {
       "depend",
       "blast",
       "radius",
+      "cascade",
       "risk",
       "delete",
       "remove"
@@ -2980,6 +2994,7 @@ var INTENT_SIGNALS = {
       /what\s+(breaks|happens|is affected)/,
       /if\s+i\s+(change|modify|remove|delete)/,
       /blast\s+radius/,
+      /cascad/,
       /what\s+(depend|relies)/
     ]
   },
@@ -3465,6 +3480,10 @@ var ResponseFormatter = class {
   }
   formatImpact(entityName, data) {
     const d = data;
+    if ("sourceNodeId" in d && "summary" in d) {
+      const summary = d.summary;
+      return `Blast radius of **${entityName}**: ${summary.totalAffected} affected nodes (${summary.highRisk} high risk, ${summary.mediumRisk} medium, ${summary.lowRisk} low).`;
+    }
     const code = this.safeArrayLength(d?.code);
     const tests = this.safeArrayLength(d?.tests);
     const docs = this.safeArrayLength(d?.docs);
@@ -3526,6 +3545,246 @@ var ResponseFormatter = class {
   }
 };
 
+// src/blast-radius/CompositeProbabilityStrategy.ts
+var CompositeProbabilityStrategy = class _CompositeProbabilityStrategy {
+  constructor(changeFreqMap, couplingMap) {
+    this.changeFreqMap = changeFreqMap;
+    this.couplingMap = couplingMap;
+  }
+  changeFreqMap;
+  couplingMap;
+  static BASE_WEIGHTS = {
+    imports: 0.7,
+    calls: 0.5,
+    implements: 0.6,
+    inherits: 0.6,
+    co_changes_with: 0.4,
+    references: 0.2,
+    contains: 0.3
+  };
+  static FALLBACK_WEIGHT = 0.1;
+  static EDGE_TYPE_BLEND = 0.5;
+  static CHANGE_FREQ_BLEND = 0.3;
+  static COUPLING_BLEND = 0.2;
+  getEdgeProbability(edge, _fromNode, toNode) {
+    const base = _CompositeProbabilityStrategy.BASE_WEIGHTS[edge.type] ?? _CompositeProbabilityStrategy.FALLBACK_WEIGHT;
+    const changeFreq = this.changeFreqMap.get(toNode.id) ?? 0;
+    const coupling = this.couplingMap.get(toNode.id) ?? 0;
+    return Math.min(
+      1,
+      base * _CompositeProbabilityStrategy.EDGE_TYPE_BLEND + changeFreq * _CompositeProbabilityStrategy.CHANGE_FREQ_BLEND + coupling * _CompositeProbabilityStrategy.COUPLING_BLEND
+    );
+  }
+};
+
+// src/blast-radius/CascadeSimulator.ts
+var DEFAULT_PROBABILITY_FLOOR = 0.05;
+var DEFAULT_MAX_DEPTH = 10;
+var CascadeSimulator = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  simulate(sourceNodeId, options = {}) {
+    const sourceNode = this.store.getNode(sourceNodeId);
+    if (!sourceNode) {
+      throw new Error(`Node not found: ${sourceNodeId}. Ensure the file has been ingested.`);
+    }
+    const probabilityFloor = options.probabilityFloor ?? DEFAULT_PROBABILITY_FLOOR;
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const edgeTypeFilter = options.edgeTypes ? new Set(options.edgeTypes) : null;
+    const strategy = options.strategy ?? this.buildDefaultStrategy();
+    const visited = /* @__PURE__ */ new Map();
+    const queue = [];
+    const fanOutCount = /* @__PURE__ */ new Map();
+    this.seedQueue(
+      sourceNodeId,
+      sourceNode,
+      strategy,
+      edgeTypeFilter,
+      probabilityFloor,
+      queue,
+      fanOutCount
+    );
+    const truncated = this.runBfs(
+      queue,
+      visited,
+      fanOutCount,
+      sourceNodeId,
+      strategy,
+      edgeTypeFilter,
+      probabilityFloor,
+      maxDepth
+    );
+    return this.buildResult(sourceNodeId, sourceNode.name, visited, fanOutCount, truncated);
+  }
+  seedQueue(sourceNodeId, sourceNode, strategy, edgeTypeFilter, probabilityFloor, queue, fanOutCount) {
+    const sourceEdges = this.store.getEdges({ from: sourceNodeId });
+    for (const edge of sourceEdges) {
+      if (edge.to === sourceNodeId) continue;
+      if (edgeTypeFilter && !edgeTypeFilter.has(edge.type)) continue;
+      const targetNode = this.store.getNode(edge.to);
+      if (!targetNode) continue;
+      const cumProb = strategy.getEdgeProbability(edge, sourceNode, targetNode);
+      if (cumProb < probabilityFloor) continue;
+      queue.push({
+        nodeId: edge.to,
+        cumProb,
+        depth: 1,
+        parentId: sourceNodeId,
+        incomingEdge: edge.type
+      });
+    }
+    fanOutCount.set(
+      sourceNodeId,
+      sourceEdges.filter(
+        (e) => e.to !== sourceNodeId && (!edgeTypeFilter || edgeTypeFilter.has(e.type))
+      ).length
+    );
+  }
+  runBfs(queue, visited, fanOutCount, sourceNodeId, strategy, edgeTypeFilter, probabilityFloor, maxDepth) {
+    const MAX_QUEUE_SIZE = 1e4;
+    let head = 0;
+    while (head < queue.length) {
+      if (queue.length > MAX_QUEUE_SIZE) return true;
+      const entry = queue[head++];
+      const existing = visited.get(entry.nodeId);
+      if (existing && existing.cumulativeProbability >= entry.cumProb) continue;
+      const targetNode = this.store.getNode(entry.nodeId);
+      if (!targetNode) continue;
+      visited.set(entry.nodeId, {
+        nodeId: entry.nodeId,
+        name: targetNode.name,
+        ...targetNode.path !== void 0 && { path: targetNode.path },
+        type: targetNode.type,
+        cumulativeProbability: entry.cumProb,
+        depth: entry.depth,
+        incomingEdge: entry.incomingEdge,
+        parentId: entry.parentId
+      });
+      if (entry.depth < maxDepth) {
+        const childCount = this.expandNode(
+          entry,
+          targetNode,
+          sourceNodeId,
+          strategy,
+          edgeTypeFilter,
+          probabilityFloor,
+          queue
+        );
+        fanOutCount.set(entry.nodeId, (fanOutCount.get(entry.nodeId) ?? 0) + childCount);
+      }
+    }
+    return false;
+  }
+  expandNode(entry, fromNode, sourceNodeId, strategy, edgeTypeFilter, probabilityFloor, queue) {
+    const outEdges = this.store.getEdges({ from: entry.nodeId });
+    let childCount = 0;
+    for (const edge of outEdges) {
+      if (edgeTypeFilter && !edgeTypeFilter.has(edge.type)) continue;
+      if (edge.to === sourceNodeId) continue;
+      const childNode = this.store.getNode(edge.to);
+      if (!childNode) continue;
+      const newCumProb = entry.cumProb * strategy.getEdgeProbability(edge, fromNode, childNode);
+      if (newCumProb < probabilityFloor) continue;
+      childCount++;
+      queue.push({
+        nodeId: edge.to,
+        cumProb: newCumProb,
+        depth: entry.depth + 1,
+        parentId: entry.nodeId,
+        incomingEdge: edge.type
+      });
+    }
+    return childCount;
+  }
+  buildDefaultStrategy() {
+    return new CompositeProbabilityStrategy(/* @__PURE__ */ new Map(), /* @__PURE__ */ new Map());
+  }
+  buildResult(sourceNodeId, sourceName, visited, fanOutCount, truncated = false) {
+    if (visited.size === 0) {
+      return {
+        sourceNodeId,
+        sourceName,
+        layers: [],
+        flatSummary: [],
+        summary: {
+          totalAffected: 0,
+          maxDepthReached: 0,
+          highRisk: 0,
+          mediumRisk: 0,
+          lowRisk: 0,
+          categoryBreakdown: { code: 0, tests: 0, docs: 0, other: 0 },
+          amplificationPoints: [],
+          truncated
+        }
+      };
+    }
+    const allNodes = Array.from(visited.values());
+    const flatSummary = [...allNodes].sort(
+      (a, b) => b.cumulativeProbability - a.cumulativeProbability
+    );
+    const depthMap = /* @__PURE__ */ new Map();
+    for (const node of allNodes) {
+      let list = depthMap.get(node.depth);
+      if (!list) {
+        list = [];
+        depthMap.set(node.depth, list);
+      }
+      list.push(node);
+    }
+    const layers = [];
+    const depths = Array.from(depthMap.keys()).sort((a, b) => a - b);
+    for (const depth of depths) {
+      const nodes = depthMap.get(depth);
+      const breakdown = { code: 0, tests: 0, docs: 0, other: 0 };
+      for (const n of nodes) {
+        const graphNode = this.store.getNode(n.nodeId);
+        if (graphNode) {
+          breakdown[classifyNodeCategory(graphNode)]++;
+        }
+      }
+      layers.push({ depth, nodes, categoryBreakdown: breakdown });
+    }
+    let highRisk = 0;
+    let mediumRisk = 0;
+    let lowRisk = 0;
+    const catBreakdown = { code: 0, tests: 0, docs: 0, other: 0 };
+    for (const node of allNodes) {
+      if (node.cumulativeProbability >= 0.5) highRisk++;
+      else if (node.cumulativeProbability >= 0.2) mediumRisk++;
+      else lowRisk++;
+      const graphNode = this.store.getNode(node.nodeId);
+      if (graphNode) {
+        catBreakdown[classifyNodeCategory(graphNode)]++;
+      }
+    }
+    const amplificationPoints = [];
+    for (const [nodeId, count] of fanOutCount) {
+      if (count > 3) {
+        amplificationPoints.push(nodeId);
+      }
+    }
+    const maxDepthReached = allNodes.reduce((max, n) => Math.max(max, n.depth), 0);
+    return {
+      sourceNodeId,
+      sourceName,
+      layers,
+      flatSummary,
+      summary: {
+        totalAffected: allNodes.length,
+        maxDepthReached,
+        highRisk,
+        mediumRisk,
+        lowRisk,
+        categoryBreakdown: catBreakdown,
+        amplificationPoints,
+        truncated
+      }
+    };
+  }
+};
+
 // src/nlq/index.ts
 var ENTITY_REQUIRED_INTENTS = /* @__PURE__ */ new Set(["impact", "relationships", "explain"]);
 var classifier = new IntentClassifier();
@@ -3588,6 +3847,11 @@ function executeOperation(store, intent, entities, question, fusion) {
   switch (intent) {
     case "impact": {
       const rootId = entities[0].nodeId;
+      const lowerQuestion = question.toLowerCase();
+      if (lowerQuestion.includes("blast radius") || lowerQuestion.includes("cascade")) {
+        const simulator = new CascadeSimulator(store);
+        return simulator.simulate(rootId);
+      }
       const result = cql.execute({
         rootNodeIds: [rootId],
         bidirectional: true,
@@ -3882,6 +4146,59 @@ var Assembler = class {
 };
 
 // src/query/Traceability.ts
+function extractConfidence(edge) {
+  return edge.confidence ?? edge.metadata?.confidence ?? 0;
+}
+function extractMethod(edge) {
+  return edge.metadata?.method ?? "convention";
+}
+function edgesToTracedFiles(store, edges) {
+  return edges.map((edge) => ({
+    path: store.getNode(edge.to)?.path ?? edge.to,
+    confidence: extractConfidence(edge),
+    method: extractMethod(edge)
+  }));
+}
+function determineCoverageStatus(hasCode, hasTests) {
+  if (hasCode && hasTests) return "full";
+  if (hasCode) return "code-only";
+  if (hasTests) return "test-only";
+  return "none";
+}
+function computeMaxConfidence(codeFiles, testFiles) {
+  const allConfidences = [
+    ...codeFiles.map((f) => f.confidence),
+    ...testFiles.map((f) => f.confidence)
+  ];
+  return allConfidences.length > 0 ? Math.max(...allConfidences) : 0;
+}
+function buildRequirementCoverage(store, req) {
+  const codeFiles = edgesToTracedFiles(store, store.getEdges({ from: req.id, type: "requires" }));
+  const testFiles = edgesToTracedFiles(
+    store,
+    store.getEdges({ from: req.id, type: "verified_by" })
+  );
+  const hasCode = codeFiles.length > 0;
+  const hasTests = testFiles.length > 0;
+  return {
+    requirementId: req.id,
+    requirementName: req.name,
+    index: req.metadata?.index ?? 0,
+    codeFiles,
+    testFiles,
+    status: determineCoverageStatus(hasCode, hasTests),
+    maxConfidence: computeMaxConfidence(codeFiles, testFiles)
+  };
+}
+function computeSummary(requirements) {
+  const total = requirements.length;
+  const withCode = requirements.filter((r) => r.codeFiles.length > 0).length;
+  const withTests = requirements.filter((r) => r.testFiles.length > 0).length;
+  const fullyTraced = requirements.filter((r) => r.status === "full").length;
+  const untraceable = requirements.filter((r) => r.status === "none").length;
+  const coveragePercent = total > 0 ? Math.round(fullyTraced / total * 100) : 0;
+  return { total, withCode, withTests, fullyTraced, untraceable, coveragePercent };
+}
 function queryTraceability(store, options) {
   const allRequirements = store.findNodes({ type: "requirement" });
   const filtered = allRequirements.filter((node) => {
@@ -3909,56 +4226,13 @@ function queryTraceability(store, options) {
     const firstMeta = firstReq.metadata;
     const specPath = firstMeta?.specPath ?? "";
     const featureName = firstMeta?.featureName ?? "";
-    const requirements = [];
-    for (const req of reqs) {
-      const requiresEdges = store.getEdges({ from: req.id, type: "requires" });
-      const codeFiles = requiresEdges.map((edge) => {
-        const targetNode = store.getNode(edge.to);
-        return {
-          path: targetNode?.path ?? edge.to,
-          confidence: edge.confidence ?? edge.metadata?.confidence ?? 0,
-          method: edge.metadata?.method ?? "convention"
-        };
-      });
-      const verifiedByEdges = store.getEdges({ from: req.id, type: "verified_by" });
-      const testFiles = verifiedByEdges.map((edge) => {
-        const targetNode = store.getNode(edge.to);
-        return {
-          path: targetNode?.path ?? edge.to,
-          confidence: edge.confidence ?? edge.metadata?.confidence ?? 0,
-          method: edge.metadata?.method ?? "convention"
-        };
-      });
-      const hasCode = codeFiles.length > 0;
-      const hasTests = testFiles.length > 0;
-      const status = hasCode && hasTests ? "full" : hasCode ? "code-only" : hasTests ? "test-only" : "none";
-      const allConfidences = [
-        ...codeFiles.map((f) => f.confidence),
-        ...testFiles.map((f) => f.confidence)
-      ];
-      const maxConfidence = allConfidences.length > 0 ? Math.max(...allConfidences) : 0;
-      requirements.push({
-        requirementId: req.id,
-        requirementName: req.name,
-        index: req.metadata?.index ?? 0,
-        codeFiles,
-        testFiles,
-        status,
-        maxConfidence
-      });
-    }
+    const requirements = reqs.map((req) => buildRequirementCoverage(store, req));
     requirements.sort((a, b) => a.index - b.index);
-    const total = requirements.length;
-    const withCode = requirements.filter((r) => r.codeFiles.length > 0).length;
-    const withTests = requirements.filter((r) => r.testFiles.length > 0).length;
-    const fullyTraced = requirements.filter((r) => r.status === "full").length;
-    const untraceable = requirements.filter((r) => r.status === "none").length;
-    const coveragePercent = total > 0 ? Math.round(fullyTraced / total * 100) : 0;
     results.push({
       specPath,
       featureName,
       requirements,
-      summary: { total, withCode, withTests, fullyTraced, untraceable, coveragePercent }
+      summary: computeSummary(requirements)
     });
   }
   return results;
@@ -4782,13 +5056,15 @@ var ConflictPredictor = class {
 };
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Assembler,
   CIConnector,
   CURRENT_SCHEMA_VERSION,
+  CascadeSimulator,
   CodeIngestor,
+  CompositeProbabilityStrategy,
   ConflictPredictor,
   ConfluenceConnector,
   ContextQL,
@@ -4823,6 +5099,7 @@ var VERSION = "0.2.0";
   VERSION,
   VectorStore,
   askGraph,
+  classifyNodeCategory,
   groupNodesByImpact,
   linkToCode,
   loadGraph,