@harness-engineering/graph 0.3.5 → 0.4.0

package/dist/index.mjs

@@ -35,7 +35,9 @@ var NODE_TYPES = [
   // Design
   "design_token",
   "aesthetic_intent",
-  "design_constraint"
+  "design_constraint",
+  // Traceability
+  "requirement"
 ];
 var EDGE_TYPES = [
   // Code relationships
@@ -64,7 +66,11 @@ var EDGE_TYPES = [
   "uses_token",
   "declares_intent",
   "violates_design",
-  "platform_binding"
+  "platform_binding",
+  // Traceability relationships
+  "requires",
+  "verified_by",
+  "tested_by"
 ];
 var OBSERVABILITY_TYPES = /* @__PURE__ */ new Set(["span", "metric", "log"]);
 var CURRENT_SCHEMA_VERSION = 1;
@@ -598,6 +604,7 @@ var CodeIngestor = class {
       this.store.addEdge(edge);
       edgesAdded++;
     }
+    edgesAdded += this.extractReqAnnotations(fileContents, rootDir);
     return {
       nodesAdded,
       nodesUpdated: 0,
@@ -956,6 +963,48 @@ var CodeIngestor = class {
     if (/\.jsx?$/.test(filePath)) return "javascript";
     return "unknown";
   }
+  /**
+   * Scan file contents for @req annotations and create verified_by edges
+   * linking requirement nodes to the annotated files.
+   * Format: // @req <feature-name>#<index>
+   */
+  extractReqAnnotations(fileContents, rootDir) {
+    const REQ_TAG = /\/\/\s*@req\s+([\w-]+)#(\d+)/g;
+    const reqNodes = this.store.findNodes({ type: "requirement" });
+    let edgesAdded = 0;
+    for (const [filePath, content] of fileContents) {
+      let match;
+      REQ_TAG.lastIndex = 0;
+      while ((match = REQ_TAG.exec(content)) !== null) {
+        const featureName = match[1];
+        const reqIndex = parseInt(match[2], 10);
+        const reqNode = reqNodes.find(
+          (n) => n.metadata.featureName === featureName && n.metadata.index === reqIndex
+        );
+        if (!reqNode) {
+          console.warn(
+            `@req annotation references non-existent requirement: ${featureName}#${reqIndex} in ${filePath}`
+          );
+          continue;
+        }
+        const relPath = path.relative(rootDir, filePath).replace(/\\/g, "/");
+        const fileNodeId = `file:${relPath}`;
+        this.store.addEdge({
+          from: reqNode.id,
+          to: fileNodeId,
+          type: "verified_by",
+          confidence: 1,
+          metadata: {
+            method: "annotation",
+            tag: `@req ${featureName}#${reqIndex}`,
+            confidence: 1
+          }
+        });
+        edgesAdded++;
+      }
+    }
+    return edgesAdded;
+  }
 };
 
 // src/ingest/GitIngestor.ts
@@ -1432,8 +1481,218 @@ var KnowledgeIngestor = class {
   }
 };
 
-// src/ingest/connectors/ConnectorUtils.ts
+// src/ingest/RequirementIngestor.ts
+import * as fs3 from "fs/promises";
+import * as path4 from "path";
+var REQUIREMENT_SECTIONS = [
+  "Observable Truths",
+  "Success Criteria",
+  "Acceptance Criteria"
+];
+var SECTION_HEADING_RE = /^#{2,3}\s+(.+)$/;
+var NUMBERED_ITEM_RE = /^\s*(\d+)\.\s+(.+)$/;
+function detectEarsPattern(text) {
+  const lower = text.toLowerCase();
+  if (/^if\b.+\bthen\b.+\bshall not\b/.test(lower)) return "unwanted";
+  if (/^when\b/.test(lower)) return "event-driven";
+  if (/^while\b/.test(lower)) return "state-driven";
+  if (/^where\b/.test(lower)) return "optional";
+  if (/^the\s+\w+\s+shall\b/.test(lower)) return "ubiquitous";
+  return void 0;
+}
 var CODE_NODE_TYPES2 = ["file", "function", "class", "method", "interface", "variable"];
+var RequirementIngestor = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  /**
+   * Scan a specs directory for `<feature>/proposal.md` files,
+   * extract numbered requirements from recognized sections,
+   * and create requirement nodes with convention-based edges.
+   */
+  async ingestSpecs(specsDir) {
+    const start = Date.now();
+    const errors = [];
+    let nodesAdded = 0;
+    let edgesAdded = 0;
+    let featureDirs;
+    try {
+      const entries = await fs3.readdir(specsDir, { withFileTypes: true });
+      featureDirs = entries.filter((e) => e.isDirectory()).map((e) => path4.join(specsDir, e.name));
+    } catch {
+      return emptyResult(Date.now() - start);
+    }
+    for (const featureDir of featureDirs) {
+      const featureName = path4.basename(featureDir);
+      const specPath = path4.join(featureDir, "proposal.md");
+      let content;
+      try {
+        content = await fs3.readFile(specPath, "utf-8");
+      } catch {
+        continue;
+      }
+      try {
+        const specHash = hash(specPath);
+        const specNodeId = `file:${specPath}`;
+        this.store.addNode({
+          id: specNodeId,
+          type: "document",
+          name: path4.basename(specPath),
+          path: specPath,
+          metadata: { featureName }
+        });
+        const requirements = this.extractRequirements(content, specPath, specHash, featureName);
+        for (const req of requirements) {
+          this.store.addNode(req.node);
+          nodesAdded++;
+          this.store.addEdge({
+            from: req.node.id,
+            to: specNodeId,
+            type: "specifies"
+          });
+          edgesAdded++;
+          edgesAdded += this.linkByPathPattern(req.node.id, featureName);
+          edgesAdded += this.linkByKeywordOverlap(req.node.id, req.node.name);
+        }
+      } catch (err) {
+        errors.push(`${specPath}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    return {
+      nodesAdded,
+      nodesUpdated: 0,
+      edgesAdded,
+      edgesUpdated: 0,
+      errors,
+      durationMs: Date.now() - start
+    };
+  }
+  /**
+   * Parse markdown content and extract numbered items from recognized sections.
+   */
+  extractRequirements(content, specPath, specHash, featureName) {
+    const lines = content.split("\n");
+    const results = [];
+    let currentSection;
+    let inRequirementSection = false;
+    let globalIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const headingMatch = line.match(SECTION_HEADING_RE);
+      if (headingMatch) {
+        const heading = headingMatch[1].trim();
+        const isReqSection = REQUIREMENT_SECTIONS.some(
+          (s) => heading.toLowerCase() === s.toLowerCase()
+        );
+        if (isReqSection) {
+          currentSection = heading;
+          inRequirementSection = true;
+        } else {
+          inRequirementSection = false;
+        }
+        continue;
+      }
+      if (!inRequirementSection) continue;
+      const itemMatch = line.match(NUMBERED_ITEM_RE);
+      if (!itemMatch) continue;
+      const index = parseInt(itemMatch[1], 10);
+      const text = itemMatch[2].trim();
+      const rawText = line.trim();
+      const lineNumber = i + 1;
+      globalIndex++;
+      const nodeId = `req:${specHash}:${globalIndex}`;
+      const earsPattern = detectEarsPattern(text);
+      results.push({
+        node: {
+          id: nodeId,
+          type: "requirement",
+          name: text,
+          path: specPath,
+          location: {
+            fileId: `file:${specPath}`,
+            startLine: lineNumber,
+            endLine: lineNumber
+          },
+          metadata: {
+            specPath,
+            index,
+            section: currentSection,
+            rawText,
+            earsPattern,
+            featureName
+          }
+        }
+      });
+    }
+    return results;
+  }
+  /**
+   * Convention-based linking: match requirement to code/test files
+   * by feature name in their path.
+   */
+  linkByPathPattern(reqId, featureName) {
+    let count = 0;
+    const fileNodes = this.store.findNodes({ type: "file" });
+    for (const node of fileNodes) {
+      if (!node.path) continue;
+      const normalizedPath = node.path.replace(/\\/g, "/");
+      const isCodeMatch = normalizedPath.includes("packages/") && path4.basename(normalizedPath).includes(featureName);
+      const isTestMatch = normalizedPath.includes("/tests/") && // platform-safe
+      path4.basename(normalizedPath).includes(featureName);
+      if (isCodeMatch && !isTestMatch) {
+        this.store.addEdge({
+          from: reqId,
+          to: node.id,
+          type: "requires",
+          confidence: 0.5,
+          metadata: { method: "convention", matchReason: "path-pattern" }
+        });
+        count++;
+      } else if (isTestMatch) {
+        this.store.addEdge({
+          from: reqId,
+          to: node.id,
+          type: "verified_by",
+          confidence: 0.5,
+          metadata: { method: "convention", matchReason: "path-pattern" }
+        });
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Convention-based linking: match requirement text to code nodes
+   * by keyword overlap (function/class names appearing in requirement text).
+   */
+  linkByKeywordOverlap(reqId, reqText) {
+    let count = 0;
+    for (const nodeType of CODE_NODE_TYPES2) {
+      const codeNodes = this.store.findNodes({ type: nodeType });
+      for (const node of codeNodes) {
+        if (node.name.length < 3) continue;
+        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";
+          this.store.addEdge({
+            from: reqId,
+            to: node.id,
+            type: edgeType,
+            confidence: 0.6,
+            metadata: { method: "convention", matchReason: "keyword-overlap" }
+          });
+          count++;
+        }
+      }
+    }
+    return count;
+  }
+};
+
+// src/ingest/connectors/ConnectorUtils.ts
+var CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
 var SANITIZE_RULES = [
   // Strip XML/HTML-like instruction tags that could be interpreted as system prompts
   {
@@ -1468,7 +1727,7 @@ function sanitizeExternalText(text, maxLength = 2e3) {
 }
 function linkToCode(store, content, sourceNodeId, edgeType, options) {
   let edgesCreated = 0;
-  for (const type of CODE_NODE_TYPES2) {
+  for (const type of CODE_NODE_TYPES3) {
     const nodes = store.findNodes({ type });
     for (const node of nodes) {
       if (node.name.length < 3) continue;
@@ -1488,12 +1747,12 @@ function linkToCode(store, content, sourceNodeId, edgeType, options) {
 }
 
 // src/ingest/connectors/SyncManager.ts
-import * as fs3 from "fs/promises";
-import * as path4 from "path";
+import * as fs4 from "fs/promises";
+import * as path5 from "path";
 var SyncManager = class {
   constructor(store, graphDir) {
     this.store = store;
-    this.metadataPath = path4.join(graphDir, "sync-metadata.json");
+    this.metadataPath = path5.join(graphDir, "sync-metadata.json");
   }
   store;
   registrations = /* @__PURE__ */ new Map();
@@ -1548,15 +1807,15 @@ var SyncManager = class {
   }
   async loadMetadata() {
     try {
-      const raw = await fs3.readFile(this.metadataPath, "utf-8");
+      const raw = await fs4.readFile(this.metadataPath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return { connectors: {} };
     }
   }
   async saveMetadata(metadata) {
-    await fs3.mkdir(path4.dirname(this.metadataPath), { recursive: true });
-    await fs3.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+    await fs4.mkdir(path5.dirname(this.metadataPath), { recursive: true });
+    await fs4.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
   }
 };
 
@@ -2085,7 +2344,7 @@ var FusionLayer = class {
 };
 
 // src/entropy/GraphEntropyAdapter.ts
-var CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
+var CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
 var GraphEntropyAdapter = class {
   constructor(store) {
     this.store = store;
@@ -2152,7 +2411,7 @@ var GraphEntropyAdapter = class {
   }
   findEntryPoints() {
     const entryPoints = [];
-    for (const nodeType of CODE_NODE_TYPES3) {
+    for (const nodeType of CODE_NODE_TYPES4) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         const isIndexFile = nodeType === "file" && node.name === "index.ts";
@@ -2188,7 +2447,7 @@ var GraphEntropyAdapter = class {
   }
   collectUnreachableNodes(visited) {
     const unreachableNodes = [];
-    for (const nodeType of CODE_NODE_TYPES3) {
+    for (const nodeType of CODE_NODE_TYPES4) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         if (!visited.has(node.id)) {
@@ -3008,9 +3267,9 @@ var EntityExtractor = class {
     }
     const pathConsumed = /* @__PURE__ */ new Set();
     for (const match of trimmed.matchAll(FILE_PATH_RE)) {
-      const path6 = match[0];
-      add(path6);
-      pathConsumed.add(path6);
+      const path7 = match[0];
+      add(path7);
+      pathConsumed.add(path7);
     }
     const allConsumed = buildConsumedSet(quotedConsumed, casingConsumed, pathConsumed);
     const words = trimmed.split(/\s+/);
@@ -3081,8 +3340,8 @@ var EntityResolver = class {
       if (isPathLike && node.path.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
-      const basename4 = node.path.split("/").pop() ?? "";
-      if (basename4.includes(raw)) {
+      const basename5 = node.path.split("/").pop() ?? "";
+      if (basename5.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
       if (raw.length >= 4 && node.path.includes(raw)) {
@@ -3157,13 +3416,13 @@ var ResponseFormatter = class {
     const context = Array.isArray(d?.context) ? d.context : [];
     const firstEntity = entities[0];
     const nodeType = firstEntity?.node.type ?? "node";
-    const path6 = firstEntity?.node.path ?? "unknown";
+    const path7 = firstEntity?.node.path ?? "unknown";
     let neighborCount = 0;
     const firstContext = context[0];
     if (firstContext && Array.isArray(firstContext.nodes)) {
       neighborCount = firstContext.nodes.length;
     }
-    return `**${entityName}** is a ${nodeType} at \`${path6}\`. Connected to ${neighborCount} nodes.`;
+    return `**${entityName}** is a ${nodeType} at \`${path7}\`. Connected to ${neighborCount} nodes.`;
   }
   formatAnomaly(data) {
     const d = data;
@@ -3304,7 +3563,7 @@ var PHASE_NODE_TYPES = {
   debug: ["failure", "learning", "function", "method"],
   plan: ["adr", "document", "module", "layer"]
 };
-var CODE_NODE_TYPES4 = /* @__PURE__ */ new Set([
+var CODE_NODE_TYPES5 = /* @__PURE__ */ new Set([
   "file",
   "function",
   "class",
@@ -3519,7 +3778,7 @@ var Assembler = class {
    */
   checkCoverage() {
     const codeNodes = [];
-    for (const type of CODE_NODE_TYPES4) {
+    for (const type of CODE_NODE_TYPES5) {
       codeNodes.push(...this.store.findNodes({ type }));
     }
     const documented = [];
@@ -3543,6 +3802,89 @@ var Assembler = class {
   }
 };
 
+// src/query/Traceability.ts
+function queryTraceability(store, options) {
+  const allRequirements = store.findNodes({ type: "requirement" });
+  const filtered = allRequirements.filter((node) => {
+    if (options?.specPath && node.metadata?.specPath !== options.specPath) return false;
+    if (options?.featureName && node.metadata?.featureName !== options.featureName) return false;
+    return true;
+  });
+  if (filtered.length === 0) return [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const req of filtered) {
+    const meta = req.metadata;
+    const specPath = meta?.specPath ?? "";
+    const featureName = meta?.featureName ?? "";
+    const key = `${specPath}\0${featureName}`;
+    const list = groups.get(key);
+    if (list) {
+      list.push(req);
+    } else {
+      groups.set(key, [req]);
+    }
+  }
+  const results = [];
+  for (const [, reqs] of groups) {
+    const firstReq = reqs[0];
+    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
+      });
+    }
+    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 }
+    });
+  }
+  return results;
+}
+
 // src/constraints/GraphConstraintAdapter.ts
 import { minimatch } from "minimatch";
 import { relative as relative2 } from "path";
@@ -3602,14 +3944,14 @@ var GraphConstraintAdapter = class {
 };
 
 // src/ingest/DesignIngestor.ts
-import * as fs4 from "fs/promises";
-import * as path5 from "path";
+import * as fs5 from "fs/promises";
+import * as path6 from "path";
 function isDTCGToken(obj) {
   return typeof obj === "object" && obj !== null && "$value" in obj && "$type" in obj;
 }
 async function readFileOrNull(filePath) {
   try {
-    return await fs4.readFile(filePath, "utf-8");
+    return await fs5.readFile(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -3755,8 +4097,8 @@ var DesignIngestor = class {
   async ingestAll(designDir) {
     const start = Date.now();
     const [tokensResult, intentResult] = await Promise.all([
-      this.ingestTokens(path5.join(designDir, "tokens.json")),
-      this.ingestDesignIntent(path5.join(designDir, "DESIGN.md"))
+      this.ingestTokens(path6.join(designDir, "tokens.json")),
+      this.ingestDesignIntent(path6.join(designDir, "DESIGN.md"))
     ]);
     const merged = mergeResults(tokensResult, intentResult);
     return { ...merged, durationMs: Date.now() - start };
@@ -4005,10 +4347,10 @@ var TaskIndependenceAnalyzer = class {
         includeTypes: ["file"]
       });
       for (const n of queryResult.nodes) {
-        const path6 = n.path ?? n.id.replace(/^file:/, "");
-        if (!fileSet.has(path6)) {
-          if (!result.has(path6)) {
-            result.set(path6, file);
+        const path7 = n.path ?? n.id.replace(/^file:/, "");
+        if (!fileSet.has(path7)) {
+          if (!result.has(path7)) {
+            result.set(path7, file);
           }
         }
       }
@@ -4392,6 +4734,7 @@ export {
   KnowledgeIngestor,
   NODE_TYPES,
   OBSERVABILITY_TYPES,
+  RequirementIngestor,
   ResponseFormatter,
   SlackConnector,
   SyncManager,
@@ -4404,5 +4747,6 @@ export {
   linkToCode,
   loadGraph,
   project,
+  queryTraceability,
   saveGraph
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-engineering/graph",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Knowledge graph for context assembly in Harness Engineering",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   "dependencies": {
     "minimatch": "^10.2.5",
     "zod": "^3.25.76",
-    "@harness-engineering/types": "0.7.0"
+    "@harness-engineering/types": "0.8.1"
   },
   "optionalDependencies": {
     "tree-sitter": "^0.22.4",