@harness-engineering/core 0.13.1 → 0.15.0

package/README.md

@@ -10,6 +10,29 @@ pnpm add @harness-engineering/core
 
 ## Modules
 
+### Modules Overview
+
+| Module           | Description                                                                                                                                         |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **validation**   | Cross-cutting validation for file structure, configuration, and commit messages                                                                     |
+| **context**      | AGENTS.md knowledge maps, documentation coverage analysis, token budgets, and context filtering                                                     |
+| **constraints**  | Architectural layer enforcement, circular dependency detection, and boundary validation                                                             |
+| **entropy**      | Documentation drift, dead code detection, pattern violations, and auto-fix                                                                          |
+| **architecture** | Metric collection via multiple collectors (circular deps, layer violations, complexity, coupling, forbidden imports, module size, dependency depth) |
+| **review**       | Code review pipeline with mechanical checks, fan-out agents (compliance, bugs, security, architecture), and deduplication                           |
+| **feedback**     | Agent feedback loops with self-review, peer review, telemetry, logging, and action tracking                                                         |
+| **performance**  | Benchmarking, baseline management, regression detection, and critical path analysis                                                                 |
+| **security**     | Security scanning with secret detection, injection detection, XSS, crypto, path traversal, and stack-specific rules (Node.js, Express, React, Go)   |
+| **ci**           | CI/CD check orchestration for running automated checks in continuous integration pipelines                                                          |
+| **code-nav**     | Code navigation: file parsing, symbol extraction/outlines, symbol search, and code range unfolding by language                                      |
+| **state**        | State persistence including learnings, failures, handoffs, gates, streams, sessions, and event logging                                              |
+| **roadmap**      | Roadmap parsing, serialization, and synchronization with codebase and issue tracking                                                                |
+| **pipeline**     | Skill pipeline orchestration for sequential and multi-turn skill execution                                                                          |
+| **workflow**     | Workflow execution engine for structured multi-step workflows                                                                                       |
+| **interaction**  | Types and schemas for agent-to-human interactions (questions, confirmations, transitions)                                                           |
+| **blueprint**    | HTML documentation generation from module data using EJS templates                                                                                  |
+| **shared**       | Error types, Result pattern for error handling, file system utilities, and language parsers                                                         |
+
 ### Validation Module
 
 Cross-cutting validation utilities used by all other modules.

package/dist/architecture/matchers.d.mts

@@ -1,2 +1,2 @@
-export { h as ArchHandle, j as ArchitectureOptions, s as archMatchers, t as archModule, u as architecture } from '../matchers-D20x48U9.mjs';
+export { h as ArchHandle, j as ArchitectureOptions, s as archMatchers, t as archModule, u as architecture } from '../matchers-Dj1t5vpg.mjs';
 import 'zod';

package/dist/architecture/matchers.d.ts

@@ -1,2 +1,2 @@
-export { h as ArchHandle, j as ArchitectureOptions, s as archMatchers, t as archModule, u as architecture } from '../matchers-D20x48U9.js';
+export { h as ArchHandle, j as ArchitectureOptions, s as archMatchers, t as archModule, u as architecture } from '../matchers-Dj1t5vpg.js';
 import 'zod';

package/dist/architecture/matchers.js

@@ -294,65 +294,71 @@ async function validateDependencies(config) {
 }
 
 // src/constraints/circular-deps.ts
-function tarjanSCC(graph) {
-  const nodeMap = /* @__PURE__ */ new Map();
-  const stack = [];
-  const sccs = [];
-  let index = 0;
+function buildAdjacencyList(graph) {
   const adjacency = /* @__PURE__ */ new Map();
+  const nodeSet = new Set(graph.nodes);
   for (const node of graph.nodes) {
     adjacency.set(node, []);
   }
   for (const edge of graph.edges) {
     const neighbors = adjacency.get(edge.from);
-    if (neighbors && graph.nodes.includes(edge.to)) {
+    if (neighbors && nodeSet.has(edge.to)) {
       neighbors.push(edge.to);
     }
   }
-  function strongConnect(node) {
-    nodeMap.set(node, {
-      index,
-      lowlink: index,
-      onStack: true
-    });
-    index++;
-    stack.push(node);
-    const neighbors = adjacency.get(node) ?? [];
-    for (const neighbor of neighbors) {
-      const neighborData = nodeMap.get(neighbor);
-      if (!neighborData) {
-        strongConnect(neighbor);
-        const nodeData2 = nodeMap.get(node);
-        const updatedNeighborData = nodeMap.get(neighbor);
-        nodeData2.lowlink = Math.min(nodeData2.lowlink, updatedNeighborData.lowlink);
-      } else if (neighborData.onStack) {
-        const nodeData2 = nodeMap.get(node);
-        nodeData2.lowlink = Math.min(nodeData2.lowlink, neighborData.index);
-      }
+  return adjacency;
+}
+function isCyclicSCC(scc, adjacency) {
+  if (scc.length > 1) return true;
+  if (scc.length === 1) {
+    const selfNode = scc[0];
+    const selfNeighbors = adjacency.get(selfNode) ?? [];
+    return selfNeighbors.includes(selfNode);
+  }
+  return false;
+}
+function processNeighbors(node, neighbors, nodeMap, stack, adjacency, sccs, indexRef) {
+  for (const neighbor of neighbors) {
+    const neighborData = nodeMap.get(neighbor);
+    if (!neighborData) {
+      strongConnectImpl(neighbor, nodeMap, stack, adjacency, sccs, indexRef);
+      const nodeData = nodeMap.get(node);
+      const updatedNeighborData = nodeMap.get(neighbor);
+      nodeData.lowlink = Math.min(nodeData.lowlink, updatedNeighborData.lowlink);
+    } else if (neighborData.onStack) {
+      const nodeData = nodeMap.get(node);
+      nodeData.lowlink = Math.min(nodeData.lowlink, neighborData.index);
     }
-    const nodeData = nodeMap.get(node);
-    if (nodeData.lowlink === nodeData.index) {
-      const scc = [];
-      let w;
-      do {
-        w = stack.pop();
-        nodeMap.get(w).onStack = false;
-        scc.push(w);
-      } while (w !== node);
-      if (scc.length > 1) {
-        sccs.push(scc);
-      } else if (scc.length === 1) {
-        const selfNode = scc[0];
-        const selfNeighbors = adjacency.get(selfNode) ?? [];
-        if (selfNeighbors.includes(selfNode)) {
-          sccs.push(scc);
-        }
-      }
+  }
+}
+function strongConnectImpl(node, nodeMap, stack, adjacency, sccs, indexRef) {
+  nodeMap.set(node, { index: indexRef.value, lowlink: indexRef.value, onStack: true });
+  indexRef.value++;
+  stack.push(node);
+  processNeighbors(node, adjacency.get(node) ?? [], nodeMap, stack, adjacency, sccs, indexRef);
+  const nodeData = nodeMap.get(node);
+  if (nodeData.lowlink === nodeData.index) {
+    const scc = [];
+    let w;
+    do {
+      w = stack.pop();
+      nodeMap.get(w).onStack = false;
+      scc.push(w);
+    } while (w !== node);
+    if (isCyclicSCC(scc, adjacency)) {
+      sccs.push(scc);
     }
   }
+}
+function tarjanSCC(graph) {
+  const nodeMap = /* @__PURE__ */ new Map();
+  const stack = [];
+  const sccs = [];
+  const indexRef = { value: 0 };
+  const adjacency = buildAdjacencyList(graph);
   for (const node of graph.nodes) {
     if (!nodeMap.has(node)) {
-      strongConnect(node);
+      strongConnectImpl(node, nodeMap, stack, adjacency, sccs, indexRef);
     }
   }
   return sccs;
@@ -615,6 +621,31 @@ function aggregateByCategory(results) {
   }
   return map;
 }
+function classifyViolations(violations, baselineViolationIds) {
+  const newViolations = [];
+  const preExisting = [];
+  for (const violation of violations) {
+    if (baselineViolationIds.has(violation.id)) {
+      preExisting.push(violation.id);
+    } else {
+      newViolations.push(violation);
+    }
+  }
+  return { newViolations, preExisting };
+}
+function findResolvedViolations(baselineCategory, currentViolationIds) {
+  if (!baselineCategory) return [];
+  return baselineCategory.violationIds.filter((id) => !currentViolationIds.has(id));
+}
+function collectOrphanedBaselineViolations(baseline, visitedCategories) {
+  const resolved = [];
+  for (const [category, baselineCategory] of Object.entries(baseline.metrics)) {
+    if (!visitedCategories.has(category) && baselineCategory) {
+      resolved.push(...baselineCategory.violationIds);
+    }
+  }
+  return resolved;
+}
 function diff(current, baseline) {
   const aggregated = aggregateByCategory(current);
   const newViolations = [];
@@ -627,21 +658,11 @@ function diff(current, baseline) {
     const baselineCategory = baseline.metrics[category];
     const baselineViolationIds = new Set(baselineCategory?.violationIds ?? []);
     const baselineValue = baselineCategory?.value ?? 0;
-    for (const violation of agg.violations) {
-      if (baselineViolationIds.has(violation.id)) {
-        preExisting.push(violation.id);
-      } else {
-        newViolations.push(violation);
-      }
-    }
+    const classified = classifyViolations(agg.violations, baselineViolationIds);
+    newViolations.push(...classified.newViolations);
+    preExisting.push(...classified.preExisting);
     const currentViolationIds = new Set(agg.violations.map((v) => v.id));
-    if (baselineCategory) {
-      for (const id of baselineCategory.violationIds) {
-        if (!currentViolationIds.has(id)) {
-          resolvedViolations.push(id);
-        }
-      }
-    }
+    resolvedViolations.push(...findResolvedViolations(baselineCategory, currentViolationIds));
     if (baselineCategory && agg.value > baselineValue) {
       regressions.push({
         category,
@@ -651,16 +672,9 @@ function diff(current, baseline) {
       });
     }
   }
-  for (const [category, baselineCategory] of Object.entries(baseline.metrics)) {
-    if (!visitedCategories.has(category) && baselineCategory) {
-      for (const id of baselineCategory.violationIds) {
-        resolvedViolations.push(id);
-      }
-    }
-  }
-  const passed = newViolations.length === 0 && regressions.length === 0;
+  resolvedViolations.push(...collectOrphanedBaselineViolations(baseline, visitedCategories));
   return {
-    passed,
+    passed: newViolations.length === 0 && regressions.length === 0,
     newViolations,
     resolvedViolations,
     preExisting,
@@ -678,22 +692,22 @@ var DEFAULT_THRESHOLDS = {
   fileLength: { info: 300 },
   hotspotPercentile: { error: 95 }
 };
+var FUNCTION_PATTERNS = [
+  // function declarations: function name(params) {
+  /^\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/,
+  // method declarations: name(params) {
+  /^\s*(?:async\s+)?(\w+)\s*\(([^)]*)\)\s*(?::\s*[^{]+)?\s*\{/,
+  // arrow functions assigned to const/let/var: const name = (params) =>
+  /^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*[^=]+)?\s*=>/,
+  // arrow functions assigned to const/let/var with single param: const name = param =>
+  /^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(\w+)\s*=>/
+];
 function extractFunctions(content) {
   const functions = [];
   const lines = content.split("\n");
-  const patterns = [
-    // function declarations: function name(params) {
-    /^\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/,
-    // method declarations: name(params) {
-    /^\s*(?:async\s+)?(\w+)\s*\(([^)]*)\)\s*(?::\s*[^{]+)?\s*\{/,
-    // arrow functions assigned to const/let/var: const name = (params) =>
-    /^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*[^=]+)?\s*=>/,
-    // arrow functions assigned to const/let/var with single param: const name = param =>
-    /^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(\w+)\s*=>/
-  ];
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    for (const pattern of patterns) {
+    for (const pattern of FUNCTION_PATTERNS) {
       const match = line.match(pattern);
       if (match) {
         const name = match[1] ?? "anonymous";
@@ -782,26 +796,155 @@ function computeNestingDepth(body) {
   }
   return maxDepth;
 }
-async function detectComplexityViolations(snapshot, config, graphData) {
-  const violations = [];
-  const thresholds = {
+function resolveThresholds(config) {
+  const userThresholds = config?.thresholds;
+  if (!userThresholds) return { ...DEFAULT_THRESHOLDS };
+  return {
     cyclomaticComplexity: {
-      error: config?.thresholds?.cyclomaticComplexity?.error ?? DEFAULT_THRESHOLDS.cyclomaticComplexity.error,
-      warn: config?.thresholds?.cyclomaticComplexity?.warn ?? DEFAULT_THRESHOLDS.cyclomaticComplexity.warn
+      ...DEFAULT_THRESHOLDS.cyclomaticComplexity,
+      ...stripUndefined(userThresholds.cyclomaticComplexity)
     },
     nestingDepth: {
-      warn: config?.thresholds?.nestingDepth?.warn ?? DEFAULT_THRESHOLDS.nestingDepth.warn
+      ...DEFAULT_THRESHOLDS.nestingDepth,
+      ...stripUndefined(userThresholds.nestingDepth)
     },
     functionLength: {
-      warn: config?.thresholds?.functionLength?.warn ?? DEFAULT_THRESHOLDS.functionLength.warn
+      ...DEFAULT_THRESHOLDS.functionLength,
+      ...stripUndefined(userThresholds.functionLength)
     },
     parameterCount: {
-      warn: config?.thresholds?.parameterCount?.warn ?? DEFAULT_THRESHOLDS.parameterCount.warn
+      ...DEFAULT_THRESHOLDS.parameterCount,
+      ...stripUndefined(userThresholds.parameterCount)
     },
-    fileLength: {
-      info: config?.thresholds?.fileLength?.info ?? DEFAULT_THRESHOLDS.fileLength.info
-    }
+    fileLength: { ...DEFAULT_THRESHOLDS.fileLength, ...stripUndefined(userThresholds.fileLength) }
   };
+}
+function stripUndefined(obj) {
+  if (!obj) return {};
+  const result = {};
+  for (const [key, val] of Object.entries(obj)) {
+    if (val !== void 0) result[key] = val;
+  }
+  return result;
+}
+function checkFileLengthViolation(filePath, lineCount, threshold) {
+  if (lineCount <= threshold) return null;
+  return {
+    file: filePath,
+    function: "<file>",
+    line: 1,
+    metric: "fileLength",
+    value: lineCount,
+    threshold,
+    tier: 3,
+    severity: "info",
+    message: `File has ${lineCount} lines (threshold: ${threshold})`
+  };
+}
+function checkCyclomaticComplexity(filePath, fn, thresholds) {
+  const complexity = computeCyclomaticComplexity(fn.body);
+  if (complexity > thresholds.error) {
+    return {
+      file: filePath,
+      function: fn.name,
+      line: fn.line,
+      metric: "cyclomaticComplexity",
+      value: complexity,
+      threshold: thresholds.error,
+      tier: 1,
+      severity: "error",
+      message: `Function "${fn.name}" has cyclomatic complexity of ${complexity} (error threshold: ${thresholds.error})`
+    };
+  }
+  if (complexity > thresholds.warn) {
+    return {
+      file: filePath,
+      function: fn.name,
+      line: fn.line,
+      metric: "cyclomaticComplexity",
+      value: complexity,
+      threshold: thresholds.warn,
+      tier: 2,
+      severity: "warning",
+      message: `Function "${fn.name}" has cyclomatic complexity of ${complexity} (warning threshold: ${thresholds.warn})`
+    };
+  }
+  return null;
+}
+function checkNestingDepth(filePath, fn, threshold) {
+  const depth = computeNestingDepth(fn.body);
+  if (depth <= threshold) return null;
+  return {
+    file: filePath,
+    function: fn.name,
+    line: fn.line,
+    metric: "nestingDepth",
+    value: depth,
+    threshold,
+    tier: 2,
+    severity: "warning",
+    message: `Function "${fn.name}" has nesting depth of ${depth} (threshold: ${threshold})`
+  };
+}
+function checkFunctionLength(filePath, fn, threshold) {
+  const fnLength = fn.endLine - fn.startLine + 1;
+  if (fnLength <= threshold) return null;
+  return {
+    file: filePath,
+    function: fn.name,
+    line: fn.line,
+    metric: "functionLength",
+    value: fnLength,
+    threshold,
+    tier: 2,
+    severity: "warning",
+    message: `Function "${fn.name}" is ${fnLength} lines long (threshold: ${threshold})`
+  };
+}
+function checkParameterCount(filePath, fn, threshold) {
+  if (fn.params <= threshold) return null;
+  return {
+    file: filePath,
+    function: fn.name,
+    line: fn.line,
+    metric: "parameterCount",
+    value: fn.params,
+    threshold,
+    tier: 2,
+    severity: "warning",
+    message: `Function "${fn.name}" has ${fn.params} parameters (threshold: ${threshold})`
+  };
+}
+function checkHotspot(filePath, fn, graphData) {
+  const hotspot = graphData.hotspots.find((h) => h.file === filePath && h.function === fn.name);
+  if (!hotspot || hotspot.hotspotScore <= graphData.percentile95Score) return null;
+  return {
+    file: filePath,
+    function: fn.name,
+    line: fn.line,
+    metric: "hotspotScore",
+    value: hotspot.hotspotScore,
+    threshold: graphData.percentile95Score,
+    tier: 1,
+    severity: "error",
+    message: `Function "${fn.name}" is a complexity hotspot (score: ${hotspot.hotspotScore}, p95: ${graphData.percentile95Score})`
+  };
+}
+function collectFunctionViolations(filePath, fn, thresholds, graphData) {
+  const checks = [
+    checkCyclomaticComplexity(filePath, fn, thresholds.cyclomaticComplexity),
+    checkNestingDepth(filePath, fn, thresholds.nestingDepth.warn),
+    checkFunctionLength(filePath, fn, thresholds.functionLength.warn),
+    checkParameterCount(filePath, fn, thresholds.parameterCount.warn)
+  ];
+  if (graphData) {
+    checks.push(checkHotspot(filePath, fn, graphData));
+  }
+  return checks.filter((v) => v !== null);
+}
+async function detectComplexityViolations(snapshot, config, graphData) {
+  const violations = [];
+  const thresholds = resolveThresholds(config);
   let totalFunctions = 0;
   for (const file of snapshot.files) {
     let content;
@@ -811,107 +954,16 @@ async function detectComplexityViolations(snapshot, config, graphData) {
       continue;
     }
     const lines = content.split("\n");
-    if (lines.length > thresholds.fileLength.info) {
-      violations.push({
-        file: file.path,
-        function: "<file>",
-        line: 1,
-        metric: "fileLength",
-        value: lines.length,
-        threshold: thresholds.fileLength.info,
-        tier: 3,
-        severity: "info",
-        message: `File has ${lines.length} lines (threshold: ${thresholds.fileLength.info})`
-      });
-    }
+    const fileLenViolation = checkFileLengthViolation(
+      file.path,
+      lines.length,
+      thresholds.fileLength.info
+    );
+    if (fileLenViolation) violations.push(fileLenViolation);
     const functions = extractFunctions(content);
     totalFunctions += functions.length;
     for (const fn of functions) {
-      const complexity = computeCyclomaticComplexity(fn.body);
-      if (complexity > thresholds.cyclomaticComplexity.error) {
-        violations.push({
-          file: file.path,
-          function: fn.name,
-          line: fn.line,
-          metric: "cyclomaticComplexity",
-          value: complexity,
-          threshold: thresholds.cyclomaticComplexity.error,
-          tier: 1,
-          severity: "error",
-          message: `Function "${fn.name}" has cyclomatic complexity of ${complexity} (error threshold: ${thresholds.cyclomaticComplexity.error})`
-        });
-      } else if (complexity > thresholds.cyclomaticComplexity.warn) {
-        violations.push({
-          file: file.path,
-          function: fn.name,
-          line: fn.line,
-          metric: "cyclomaticComplexity",
-          value: complexity,
-          threshold: thresholds.cyclomaticComplexity.warn,
-          tier: 2,
-          severity: "warning",
-          message: `Function "${fn.name}" has cyclomatic complexity of ${complexity} (warning threshold: ${thresholds.cyclomaticComplexity.warn})`
-        });
-      }
-      const nestingDepth = computeNestingDepth(fn.body);
-      if (nestingDepth > thresholds.nestingDepth.warn) {
-        violations.push({
-          file: file.path,
-          function: fn.name,
-          line: fn.line,
-          metric: "nestingDepth",
-          value: nestingDepth,
-          threshold: thresholds.nestingDepth.warn,
-          tier: 2,
-          severity: "warning",
-          message: `Function "${fn.name}" has nesting depth of ${nestingDepth} (threshold: ${thresholds.nestingDepth.warn})`
-        });
-      }
-      const fnLength = fn.endLine - fn.startLine + 1;
-      if (fnLength > thresholds.functionLength.warn) {
-        violations.push({
-          file: file.path,
-          function: fn.name,
-          line: fn.line,
-          metric: "functionLength",
-          value: fnLength,
-          threshold: thresholds.functionLength.warn,
-          tier: 2,
-          severity: "warning",
-          message: `Function "${fn.name}" is ${fnLength} lines long (threshold: ${thresholds.functionLength.warn})`
-        });
-      }
-      if (fn.params > thresholds.parameterCount.warn) {
-        violations.push({
-          file: file.path,
-          function: fn.name,
-          line: fn.line,
-          metric: "parameterCount",
-          value: fn.params,
-          threshold: thresholds.parameterCount.warn,
-          tier: 2,
-          severity: "warning",
-          message: `Function "${fn.name}" has ${fn.params} parameters (threshold: ${thresholds.parameterCount.warn})`
-        });
-      }
-      if (graphData) {
-        const hotspot = graphData.hotspots.find(
-          (h) => h.file === file.path && h.function === fn.name
-        );
-        if (hotspot && hotspot.hotspotScore > graphData.percentile95Score) {
-          violations.push({
-            file: file.path,
-            function: fn.name,
-            line: fn.line,
-            metric: "hotspotScore",
-            value: hotspot.hotspotScore,
-            threshold: graphData.percentile95Score,
-            tier: 1,
-            severity: "error",
-            message: `Function "${fn.name}" is a complexity hotspot (score: ${hotspot.hotspotScore}, p95: ${graphData.percentile95Score})`
-          });
-        }
-      }
+      violations.push(...collectFunctionViolations(file.path, fn, thresholds, graphData));
     }
   }
   const errorCount = violations.filter((v) => v.severity === "error").length;

package/dist/architecture/matchers.mjs

@@ -2,7 +2,7 @@ import {
   archMatchers,
   archModule,
   architecture
-} from "../chunk-D6VFA6AS.mjs";
+} from "../chunk-BQUWXBGR.mjs";
 export {
   archMatchers,
   archModule,