@harness-engineering/graph 0.9.0 → 0.11.0

package/dist/index.mjs

@@ -2212,6 +2212,23 @@ var CODE_NODE_TYPES2 = [
   "variable"
 ];
 var MEASURABLE_TYPES = /* @__PURE__ */ new Set(["business_process", "business_concept"]);
+var STRATEGY_REQUIRED_SECTIONS = [
+  "Target problem",
+  "Our approach",
+  "Who it's for",
+  "Key metrics",
+  "Tracks"
+];
+var STRATEGY_OPTIONAL_SECTIONS = [
+  "Milestones",
+  "Not working on",
+  "Marketing"
+];
+var STRATEGY_KNOWN_SECTIONS = /* @__PURE__ */ new Set([
+  ...STRATEGY_REQUIRED_SECTIONS,
+  ...STRATEGY_OPTIONAL_SECTIONS
+]);
+var STRATEGY_PLACEHOLDER_RE = /^<[^>]+>\s*$/;
 var BusinessKnowledgeIngestor = class {
   constructor(store) {
     this.store = store;
@@ -2296,6 +2313,75 @@ var BusinessKnowledgeIngestor = class {
       durationMs: Date.now() - start
     };
   }
+  /**
+   * Ingest the repo-root STRATEGY.md anchor as `business_fact` nodes — one per
+   * non-empty section. Soft-fails when the file is absent (returns empty result
+   * with no errors) so existing projects without a strategy doc keep working.
+   *
+   * Each emitted node carries `metadata.domain === 'strategy'` and
+   * `metadata.source === 'STRATEGY.md'`, making the strategy domain
+   * discoverable through the same filters as other business-knowledge nodes.
+   */
+  async ingestStrategy(strategyPath) {
+    const start = Date.now();
+    const errors = [];
+    let raw;
+    try {
+      raw = await fs3.readFile(strategyPath, "utf-8");
+    } catch {
+      return emptyResult(Date.now() - start);
+    }
+    const parsed = parseStrategyMarkdown(raw);
+    if (!parsed) {
+      errors.push(`${strategyPath}: no frontmatter found`);
+      return { ...emptyResult(Date.now() - start), errors };
+    }
+    const relPath = path4.basename(strategyPath);
+    let nodesAdded = 0;
+    for (const section of parsed.sections) {
+      const node = this.buildStrategyNode(section, parsed.frontmatter, relPath);
+      if (node === null) continue;
+      this.store.addNode(node);
+      nodesAdded++;
+    }
+    return {
+      nodesAdded,
+      nodesUpdated: 0,
+      edgesAdded: 0,
+      edgesUpdated: 0,
+      errors,
+      durationMs: Date.now() - start
+    };
+  }
+  /**
+   * Build a single STRATEGY.md `business_fact` node from a parsed section.
+   * Returns null when the section is unknown, empty, or carries unfilled
+   * template placeholder text — callers iterate and skip nulls.
+   */
+  buildStrategyNode(section, frontmatter, relPath) {
+    if (!STRATEGY_KNOWN_SECTIONS.has(section.name)) return null;
+    const body = section.body.trim();
+    if (body.length === 0) return null;
+    if (STRATEGY_PLACEHOLDER_RE.test(body)) return null;
+    const productName = typeof frontmatter.name === "string" ? frontmatter.name : "unnamed-product";
+    return {
+      id: `bk:strategy:${slugifyStrategySection(section.name)}`,
+      type: "business_fact",
+      name: section.name,
+      path: relPath,
+      content: body,
+      metadata: {
+        domain: "strategy",
+        source: "STRATEGY.md",
+        section_name: section.name,
+        product_name: productName,
+        ...typeof frontmatter.last_updated === "string" && {
+          last_updated: frontmatter.last_updated
+        },
+        ...typeof frontmatter.version === "number" && { version: frontmatter.version }
+      }
+    };
+  }
   async createNodes(files, knowledgeDir, errors) {
     const entries = [];
     for (const filePath of files) {
@@ -2418,6 +2504,49 @@ function parseFrontmatter(raw) {
     body
   };
 }
+function slugifyStrategySection(name) {
+  return name.toLowerCase().replace(/'/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function parseStrategyMarkdown(raw) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) return null;
+  const yamlBlock = match[1];
+  const body = match[2];
+  const frontmatter = {};
+  for (const line of yamlBlock.split(/\r?\n/)) {
+    const kvMatch = line.match(/^(\w+):\s*(.+)$/);
+    if (!kvMatch) continue;
+    const key = kvMatch[1];
+    const rawValue = kvMatch[2].trim();
+    const unquoted = rawValue.replace(/^["']|["']$/g, "");
+    const asNumber = Number(unquoted);
+    if (unquoted !== "" && !Number.isNaN(asNumber) && /^-?\d+(?:\.\d+)?$/.test(unquoted)) {
+      frontmatter[key] = asNumber;
+    } else {
+      frontmatter[key] = unquoted;
+    }
+  }
+  const sections = [];
+  const h2Re = /^##[ \t]+(.+?)[ \t]*$/gm;
+  const matches = [];
+  let m;
+  while ((m = h2Re.exec(body)) !== null) {
+    matches.push({
+      name: (m[1] ?? "").trim(),
+      headingStart: m.index,
+      bodyStart: m.index + m[0].length
+    });
+  }
+  for (let i = 0; i < matches.length; i++) {
+    const current = matches[i];
+    const sliceEnd = matches[i + 1]?.headingStart ?? body.length;
+    sections.push({
+      name: current.name,
+      body: body.slice(current.bodyStart, sliceEnd).trim()
+    });
+  }
+  return { frontmatter, sections };
+}
 function parseSolutionFrontmatter(raw) {
   const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
   if (!match) return null;
@@ -2449,6 +2578,12 @@ var CODE_NODE_TYPES3 = [
   "interface",
   "variable"
 ];
+var ARCHITECTURE_ADR_H1 = /^\s*#\s+ADR[-\s]*(\d+)\s*[:\-—]\s*(.+?)\s*$/im;
+function matchField(body, field) {
+  const re = new RegExp(`\\*\\*${field}:\\*\\*\\s*(.+)`, "i");
+  const m = body.match(re);
+  return m ? m[1].trim() : void 0;
+}
 var DecisionIngestor = class {
   constructor(store) {
     this.store = store;
@@ -2505,6 +2640,71 @@ var DecisionIngestor = class {
       durationMs: Date.now() - start
     };
   }
+  /**
+   * Ingest ADRs written by `harness-architecture-advisor` from
+   * `docs/architecture/<topic>/ADR-<n>.md`. These files do not carry YAML
+   * frontmatter — the canonical format is:
+   *
+   * ```
+   * # ADR-<n>: <Title>
+   *
+   * **Date:** <date>
+   * **Status:** Accepted | Proposed | Superseded | Deprecated
+   * **Deciders:** <who>
+   * ```
+   *
+   * The first directory under `architectureDir` becomes `metadata.domain`
+   * (the "topic"), so projects whose only knowledge substrate is ADRs surface
+   * `architecture/<topic>` as a documented domain rather than reporting empty.
+   *
+   * Soft-fails when the directory is absent (the common case for projects that
+   * do not use the architecture-advisor convention).
+   */
+  async ingestArchitecture(architectureDir) {
+    const start = Date.now();
+    const errors = [];
+    let files;
+    try {
+      files = await this.findArchitectureAdrFiles(architectureDir);
+    } catch {
+      return emptyResult(Date.now() - start);
+    }
+    let nodesAdded = 0;
+    let edgesAdded = 0;
+    for (const filePath of files) {
+      const delta = await this.processArchitectureAdrFile(filePath, architectureDir, errors);
+      nodesAdded += delta.nodesAdded;
+      edgesAdded += delta.edgesAdded;
+    }
+    return {
+      nodesAdded,
+      nodesUpdated: 0,
+      edgesAdded,
+      edgesUpdated: 0,
+      errors,
+      durationMs: Date.now() - start
+    };
+  }
+  /**
+   * Read, parse, and add a single architecture-advisor ADR. Returns the delta
+   * the caller should fold into the aggregate counts. Errors are appended to
+   * the shared `errors` array rather than thrown, matching the soft-fail
+   * contract of `ingest()`.
+   */
+  async processArchitectureAdrFile(filePath, architectureDir, errors) {
+    try {
+      const raw = await fs4.readFile(filePath, "utf-8");
+      const parsed = parseArchitectureAdr(raw);
+      if (!parsed) return { nodesAdded: 0, edgesAdded: 0 };
+      const node = buildArchitectureAdrNode(parsed, filePath, architectureDir);
+      this.store.addNode(node);
+      const edgesAdded = this.linkToCode(parsed.body, node.id);
+      return { nodesAdded: 1, edgesAdded };
+    } catch (err) {
+      errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+      return { nodesAdded: 0, edgesAdded: 0 };
+    }
+  }
   parseFrontmatter(raw) {
     const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
     if (!match) return null;
@@ -2546,7 +2746,63 @@ var DecisionIngestor = class {
     const entries = await fs4.readdir(dir, { withFileTypes: true });
     return entries.filter((e) => e.isFile() && e.name.endsWith(".md") && e.name !== "README.md").map((e) => path5.join(dir, e.name));
   }
+  /**
+   * Recursively find `ADR-*.md` files under `dir`. Skips default skip dirs
+   * (node_modules etc.) to keep the scan bounded on large repos.
+   */
+  async findArchitectureAdrFiles(dir) {
+    const results = [];
+    const entries = await fs4.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path5.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (DEFAULT_SKIP_DIRS.has(entry.name)) continue;
+        results.push(...await this.findArchitectureAdrFiles(full));
+      } else if (entry.isFile() && entry.name.endsWith(".md") && /^ADR[-_]?\d/i.test(entry.name)) {
+        results.push(full);
+      }
+    }
+    return results;
+  }
 };
+function buildArchitectureAdrNode(parsed, filePath, architectureDir) {
+  const filename = path5.basename(filePath, ".md");
+  const relFromArch = path5.relative(architectureDir, filePath).replaceAll("\\", "/");
+  const topic = relFromArch.includes("/") ? relFromArch.split("/")[0] : "";
+  const nodeId = topic ? `decision:architecture:${topic}:${filename}` : `decision:architecture:${filename}`;
+  return {
+    id: nodeId,
+    type: "decision",
+    name: parsed.title,
+    path: filePath,
+    content: parsed.body.trim(),
+    metadata: {
+      number: parsed.number,
+      ...topic && { domain: topic },
+      source: "architecture",
+      ...parsed.date && { date: parsed.date },
+      ...parsed.status && { status: parsed.status },
+      ...parsed.deciders && { deciders: parsed.deciders }
+    }
+  };
+}
+function parseArchitectureAdr(raw) {
+  const h1 = raw.match(ARCHITECTURE_ADR_H1);
+  if (!h1) return null;
+  const number = h1[1];
+  const title = h1[2].trim();
+  const date = matchField(raw, "Date");
+  const status = matchField(raw, "Status");
+  const deciders = matchField(raw, "Deciders");
+  return {
+    number,
+    title,
+    body: raw,
+    ...date && { date },
+    ...status && { status },
+    ...deciders && { deciders }
+  };
+}
 
 // src/ingest/RequirementIngestor.ts
 import * as fs5 from "fs/promises";
@@ -2896,7 +3152,7 @@ function emptyResult2(diagramType = "unknown") {
 function detectDiagramType(content) {
   for (const line of content.split("\n")) {
     const trimmed = line.trim();
-    if (!trimmed) continue;
+    if (!trimmed || trimmed.startsWith("%%")) continue;
     if (/^(?:graph|flowchart)\b/i.test(trimmed)) return "flowchart";
     if (/^sequenceDiagram\b/.test(trimmed)) return "sequence";
     if (/^classDiagram\b/.test(trimmed)) return "class";
@@ -5668,6 +5924,16 @@ var SNAPSHOT_NODE_TYPES = [
   "aesthetic_intent",
   "image_annotation"
 ];
+function emptyIngestResult() {
+  return {
+    nodesAdded: 0,
+    nodesUpdated: 0,
+    edgesAdded: 0,
+    edgesUpdated: 0,
+    errors: [],
+    durationMs: 0
+  };
+}
 var KnowledgePipelineRunner = class {
   constructor(store) {
     this.store = store;
@@ -5678,8 +5944,10 @@ var KnowledgePipelineRunner = class {
   async run(options) {
     this.inferenceOptions = options.inferenceOptions ?? {};
     const remediations = [];
+    const ingestErrors = [];
     const preSnapshot = this.buildSnapshot(options.domain);
     const extraction = await this.extract(options);
+    ingestErrors.push(...extraction.errors);
     const postSnapshot = this.buildSnapshot(options.domain);
     let driftResult = this.reconcile(preSnapshot, postSnapshot);
     const contradictions = new ContradictionDetector().detect(this.store);
@@ -5692,7 +5960,8 @@ var KnowledgePipelineRunner = class {
         options,
         driftResult,
         gapReport,
-        remediations
+        remediations,
+        ingestErrors
       );
       iterations = loopResult.iterations;
       materialization = loopResult.materialization;
@@ -5706,7 +5975,8 @@ var KnowledgePipelineRunner = class {
     return this.buildResult(
       driftResult,
       iterations,
-      extraction,
+      extraction.counts,
+      ingestErrors,
       gapReport,
       remediations,
       contradictions,
@@ -5715,7 +5985,7 @@ var KnowledgePipelineRunner = class {
     );
   }
   /** Run the remediation convergence loop; returns iteration count and accumulated materialization. */
-  async runRemediationLoop(options, driftResult, gapReport, remediations) {
+  async runRemediationLoop(options, driftResult, gapReport, remediations, ingestErrors) {
     const maxIterations = options.maxIterations ?? 5;
     let iterations = 1;
     let currentDrift = driftResult;
@@ -5736,7 +6006,8 @@ var KnowledgePipelineRunner = class {
         }
       }
       const preSnapshot = this.buildSnapshot(options.domain);
-      await this.extract(options);
+      const reExtract = await this.extract(options);
+      ingestErrors.push(...reExtract.errors);
       const postSnapshot = this.buildSnapshot(options.domain);
       currentDrift = this.reconcile(preSnapshot, postSnapshot);
       currentGapReport = await this.detect(options);
@@ -5751,13 +6022,14 @@ var KnowledgePipelineRunner = class {
     };
   }
   /** Assemble the final pipeline result. */
-  buildResult(driftResult, iterations, extraction, gaps, remediations, contradictions, coverage, materialization) {
+  buildResult(driftResult, iterations, extraction, errors, gaps, remediations, contradictions, coverage, materialization) {
     return {
       verdict: this.computeVerdict(driftResult),
       driftScore: driftResult.driftScore,
       iterations,
       findings: driftResult.summary,
       extraction,
+      errors: Array.from(new Set(errors)),
       gaps,
       remediations,
       contradictions,
@@ -5788,58 +6060,60 @@ var KnowledgePipelineRunner = class {
     try {
       bkResult = await bkIngestor.ingest(knowledgeDir);
     } catch {
-      bkResult = {
-        nodesAdded: 0,
-        nodesUpdated: 0,
-        edgesAdded: 0,
-        edgesUpdated: 0,
-        errors: [],
-        durationMs: 0
-      };
+      bkResult = emptyIngestResult();
     }
     const solutionsDir = path12.join(options.projectDir, "docs", "solutions");
     let solutionsResult;
     try {
       solutionsResult = await bkIngestor.ingestSolutions(solutionsDir);
     } catch {
-      solutionsResult = {
-        nodesAdded: 0,
-        nodesUpdated: 0,
-        edgesAdded: 0,
-        edgesUpdated: 0,
-        errors: [],
-        durationMs: 0
-      };
+      solutionsResult = emptyIngestResult();
+    }
+    const strategyPath = path12.join(options.projectDir, "STRATEGY.md");
+    let strategyResult;
+    try {
+      strategyResult = await bkIngestor.ingestStrategy(strategyPath);
+    } catch {
+      strategyResult = emptyIngestResult();
     }
     bkResult = {
       ...bkResult,
-      nodesAdded: bkResult.nodesAdded + solutionsResult.nodesAdded,
-      errors: [...bkResult.errors, ...solutionsResult.errors]
+      nodesAdded: bkResult.nodesAdded + solutionsResult.nodesAdded + strategyResult.nodesAdded,
+      errors: [...bkResult.errors, ...solutionsResult.errors, ...strategyResult.errors]
     };
     const decisionsDir = path12.join(options.projectDir, "docs", "knowledge", "decisions");
+    const architectureDir = path12.join(options.projectDir, "docs", "architecture");
     const decisionIngestor = new DecisionIngestor(this.store);
     let decisionResult;
     try {
       decisionResult = await decisionIngestor.ingest(decisionsDir);
     } catch {
-      decisionResult = {
-        nodesAdded: 0,
-        nodesUpdated: 0,
-        edgesAdded: 0,
-        edgesUpdated: 0,
-        errors: [],
-        durationMs: 0
-      };
+      decisionResult = emptyIngestResult();
     }
+    let architectureResult;
+    try {
+      architectureResult = await decisionIngestor.ingestArchitecture(architectureDir);
+    } catch {
+      architectureResult = emptyIngestResult();
+    }
+    decisionResult = {
+      ...decisionResult,
+      nodesAdded: decisionResult.nodesAdded + architectureResult.nodesAdded,
+      edgesAdded: decisionResult.edgesAdded + architectureResult.edgesAdded,
+      errors: [...decisionResult.errors, ...architectureResult.errors]
+    };
     const linker = new KnowledgeLinker(this.store, extractedDir);
     const linkResult = await linker.link();
     return {
-      codeSignals: extractionResult.nodesAdded,
-      diagrams: diagramResult.nodesAdded,
-      linkerFacts: linkResult.factsCreated,
-      businessKnowledge: bkResult.nodesAdded,
-      decisions: decisionResult.nodesAdded,
-      images: imageCount
+      counts: {
+        codeSignals: extractionResult.nodesAdded,
+        diagrams: diagramResult.nodesAdded,
+        linkerFacts: linkResult.factsCreated,
+        businessKnowledge: bkResult.nodesAdded,
+        decisions: decisionResult.nodesAdded,
+        images: imageCount
+      },
+      errors: [...bkResult.errors, ...decisionResult.errors]
     };
   }
   // ── Phase 2: RECONCILE ────────────────────────────────────────────────────
@@ -9045,7 +9319,7 @@ function queryTraceability(store, options) {
 
 // src/constraints/GraphConstraintAdapter.ts
 import { minimatch as minimatch2 } from "minimatch";
-import { relative as relative6 } from "path";
+import { relative as relative7 } from "path";
 var GraphConstraintAdapter = class {
   constructor(store) {
     this.store = store;
@@ -9074,8 +9348,8 @@ var GraphConstraintAdapter = class {
     const { edges } = this.computeDependencyGraph();
     const violations = [];
     for (const edge of edges) {
-      const fromRelative = relative6(rootDir, edge.from).replaceAll("\\", "/");
-      const toRelative = relative6(rootDir, edge.to).replaceAll("\\", "/");
+      const fromRelative = relative7(rootDir, edge.from).replaceAll("\\", "/");
+      const toRelative = relative7(rootDir, edge.to).replaceAll("\\", "/");
       const fromLayer = this.resolveLayer(fromRelative, layers);
       const toLayer = this.resolveLayer(toRelative, layers);
       if (!fromLayer || !toLayer) continue;
@@ -9268,6 +9542,16 @@ var DesignIngestor = class {
 };
 
 // src/constraints/DesignConstraintAdapter.ts
+var CODE_PREFIX_LABELS = {
+  "ANAT-D": "Component anatomy (definition)",
+  "ANAT-P": "Component anatomy (pattern presence)",
+  "ANAT-U": "Component anatomy (usage)",
+  "CRAFT-C": "Design craft (critique)",
+  "CRAFT-P": "Design craft (polish)",
+  "CRAFT-B": "Design craft (benchmark)",
+  "DESIGN-": "Design constraint (legacy)",
+  "A11Y-": "Accessibility"
+};
 var DesignConstraintAdapter = class {
   constructor(store) {
     this.store = store;
@@ -9349,6 +9633,76 @@ var DesignConstraintAdapter = class {
         return "error";
     }
   }
+  /**
+   * Record externally-computed craft findings (audit-component-anatomy,
+   * harness-design-craft, etc.) as graph state. Idempotent — re-running on
+   * the same findings produces no duplicate nodes or edges thanks to
+   * GraphStore's keyed merge semantics.
+   *
+   * Each finding becomes:
+   *   • a `design_constraint` node keyed by finding code (created lazily
+   *     if absent; metadata merged on re-record so the most recent message
+   *     / severity wins)
+   *   • a `violates_design` edge from the source file (id = file path) to
+   *     the constraint node, with per-finding metadata (line, severity,
+   *     message, evidence, runId)
+   *
+   * The file node is NOT created here — it's assumed to already exist in
+   * the graph from a prior ingest. If it does not, the edge will still be
+   * created (graph stores edges by key, not by referential integrity) and
+   * a subsequent ingest will populate the file node.
+   */
+  recordFindings(findings) {
+    let constraintsAdded = 0;
+    let edgesAdded = 0;
+    const seenConstraintIds = /* @__PURE__ */ new Set();
+    for (const finding of findings) {
+      const constraintId = `design_constraint:${finding.code}`;
+      if (!seenConstraintIds.has(finding.code)) {
+        const existing = this.store.getNode(constraintId);
+        if (!existing) constraintsAdded += 1;
+        this.store.addNode({
+          id: constraintId,
+          type: "design_constraint",
+          name: finding.code,
+          metadata: {
+            code: finding.code,
+            label: this.labelForCode(finding.code),
+            mostRecentMessage: finding.message,
+            mostRecentSeverity: finding.severity
+          }
+        });
+        seenConstraintIds.add(finding.code);
+      }
+      const fileId = finding.file;
+      const edgeMetadata = {
+        message: finding.message,
+        severity: finding.severity
+      };
+      if (finding.line !== void 0) edgeMetadata.line = finding.line;
+      if (finding.evidence !== void 0) edgeMetadata.evidence = finding.evidence;
+      if (finding.runId !== void 0) edgeMetadata.runId = finding.runId;
+      const before = this.store.getEdges({
+        from: fileId,
+        to: constraintId,
+        type: "violates_design"
+      });
+      this.store.addEdge({
+        from: fileId,
+        to: constraintId,
+        type: "violates_design",
+        metadata: edgeMetadata
+      });
+      if (before.length === 0) edgesAdded += 1;
+    }
+    return { constraintsAdded, edgesAdded };
+  }
+  labelForCode(code) {
+    for (const prefix of Object.keys(CODE_PREFIX_LABELS)) {
+      if (code.startsWith(prefix)) return CODE_PREFIX_LABELS[prefix];
+    }
+    return "Design constraint";
+  }
 };
 
 // src/feedback/GraphFeedbackAdapter.ts
@@ -9876,7 +10230,7 @@ var ConflictPredictor = class {
 };
 
 // src/index.ts
-var VERSION = "0.6.0";
+var VERSION = "0.9.0";
 export {
   ALL_EXTRACTORS,
   ApiPathExtractor,

package/package.json

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