sentinelayer-cli 0.8.0 → 0.8.1

package/src/review/investor-dd-file-loop.js

@@ -0,0 +1,303 @@
+/**
+ * Per-file agentic review loop for investor-DD.
+ *
+ * Given a persona config, a list of files in scope, and an LLM-backed client,
+ * iterate file-by-file, running a bounded multi-turn tool-using loop per file.
+ * Emits structured events for session streaming and accumulates structured
+ * findings plus coverage proof (every file visited, how many turns, which
+ * tools were invoked).
+ *
+ * No fix-cycle path — review personas never mutate source. Tools are
+ * constrained to the caller-supplied list; the library does not import any
+ * edit/write tools.
+ *
+ * Budget: caller supplies a shared budget accumulator that is decremented
+ * on every tool call and LLM call. When the budget trips, the loop stops
+ * cleanly at the current file boundary so a partial-report generator can
+ * still emit what was finished.
+ */
+
+import { runEnvelopeLoop } from "../agents/envelope/index.js";
+
+export const INVESTOR_DD_DEFAULT_MAX_TURNS_PER_FILE = 6;
+export const INVESTOR_DD_DEFAULT_STUCK_THRESHOLD = 2;
+
+/**
+ * @typedef {object} InvestorDdBudgetState
+ * @property {number} spentUsd     - Running USD spend.
+ * @property {number} maxUsd       - Hard cap.
+ * @property {number} startedAtMs  - Epoch ms when the run began.
+ * @property {number} maxRuntimeMs - Hard cap on runtime.
+ * @property {number} toolCalls    - Running count of tool invocations.
+ * @property {number} llmCalls     - Running count of LLM invocations.
+ */
+
+/**
+ * @typedef {object} InvestorDdFileLoopEvent
+ * @property {string}  type
+ * @property {string}  personaId
+ * @property {string}  file
+ * @property {number}  [turn]
+ * @property {string}  [tool]
+ * @property {object}  [finding]
+ * @property {string}  [stopReason]
+ * @property {number}  [turnsUsed]
+ */
+
+/**
+ * @typedef {object} InvestorDdFileLoopResult
+ * @property {string}   personaId
+ * @property {Array<{file: string, findings: Array<object>, turnsUsed: number, stopReason: string|null, toolInvocations: Array<object>}>} perFile
+ * @property {Array<object>} findings                 - Flat list of all findings.
+ * @property {Array<string>} visited                  - Files the loop actually visited.
+ * @property {Array<string>} skipped                  - Files skipped because budget was exhausted.
+ * @property {"ok"|"budget-cost-exhausted"|"budget-runtime-exhausted"|"client-error"} terminationReason
+ */
+
+/**
+ * Check whether the shared budget still permits further work. When false,
+ * the loop stops at the current file boundary and reports the remaining
+ * files as `skipped` so the caller can emit a partial report.
+ *
+ * @param {InvestorDdBudgetState} budget
+ * @returns {{ ok: true } | { ok: false, reason: "budget-cost-exhausted" | "budget-runtime-exhausted" }}
+ */
+export function checkBudget(budget) {
+  if (!budget) return { ok: true };
+  if (Number.isFinite(budget.maxUsd) && budget.spentUsd >= budget.maxUsd) {
+    return { ok: false, reason: "budget-cost-exhausted" };
+  }
+  if (Number.isFinite(budget.maxRuntimeMs) && Number.isFinite(budget.startedAtMs)) {
+    const elapsed = Date.now() - budget.startedAtMs;
+    if (elapsed >= budget.maxRuntimeMs) {
+      return { ok: false, reason: "budget-runtime-exhausted" };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Instantiate a fresh budget state from caller-supplied caps.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.maxUsd]
+ * @param {number} [opts.maxRuntimeMs]
+ * @returns {InvestorDdBudgetState}
+ */
+export function createBudgetState({ maxUsd = Infinity, maxRuntimeMs = Infinity } = {}) {
+  return {
+    spentUsd: 0,
+    maxUsd,
+    startedAtMs: Date.now(),
+    maxRuntimeMs,
+    toolCalls: 0,
+    llmCalls: 0,
+  };
+}
+
+/**
+ * Wrap the caller's tool array so every invocation increments the shared
+ * budget counters. The wrapping does not alter tool contract; it only
+ * observes + accounts.
+ *
+ * @param {Array<{name: string, invoke: Function, costUsd?: number}>} tools
+ * @param {InvestorDdBudgetState} budget
+ * @param {Function} onToolCall - (name, input) => void
+ */
+function meterTools(tools, budget, onToolCall) {
+  return tools.map((tool) => ({
+    ...tool,
+    invoke: async (input) => {
+      budget.toolCalls += 1;
+      if (Number.isFinite(tool.costUsd)) {
+        budget.spentUsd += tool.costUsd;
+      }
+      try {
+        onToolCall(tool.name, input);
+      } catch {
+        // observer errors never break review
+      }
+      return tool.invoke(input);
+    },
+  }));
+}
+
+/**
+ * Wrap the caller's LLM client so every generatePlan call increments the
+ * llmCalls counter. Cost accounting for LLM calls is the client's
+ * responsibility (it knows the model and tokens), so the client adds to
+ * `budget.spentUsd` directly.
+ *
+ * @param {object} client
+ * @param {InvestorDdBudgetState} budget
+ */
+function meterClient(client, budget) {
+  return {
+    ...client,
+    generatePlan: async (messages, options) => {
+      budget.llmCalls += 1;
+      return client.generatePlan(messages, options);
+    },
+  };
+}
+
+/**
+ * Run the per-file agentic review loop for a single persona.
+ *
+ * @param {object} params
+ * @param {string} params.personaId
+ * @param {Array<string>} params.files                - Files in scope for this persona.
+ * @param {object} params.client                      - Must implement generatePlan().
+ * @param {(file: string) => Array<{name: string, invoke: Function, costUsd?: number}>} params.buildTools
+ *        Factory that returns the tool list scoped to a single file. Called once per file.
+ * @param {(file: string) => Array<object>} params.buildInitialMessages
+ *        Factory that returns the LLM messages to seed the loop for this file.
+ * @param {InvestorDdBudgetState} params.budget       - Shared budget state.
+ * @param {(event: InvestorDdFileLoopEvent) => void} [params.onEvent] - Event sink.
+ * @param {object} [params.options]
+ * @param {number} [params.options.maxTurnsPerFile]
+ * @param {number} [params.options.stuckThreshold]
+ * @returns {Promise<InvestorDdFileLoopResult>}
+ */
+export async function runPerFileReviewLoop({
+  personaId,
+  files,
+  client,
+  buildTools,
+  buildInitialMessages,
+  budget,
+  onEvent = () => {},
+  options = {},
+} = {}) {
+  if (!personaId || typeof personaId !== "string") {
+    throw new TypeError("runPerFileReviewLoop requires a personaId string");
+  }
+  if (!Array.isArray(files)) {
+    throw new TypeError("runPerFileReviewLoop requires a files array");
+  }
+  if (typeof buildTools !== "function") {
+    throw new TypeError("runPerFileReviewLoop requires buildTools(file) factory");
+  }
+  if (typeof buildInitialMessages !== "function") {
+    throw new TypeError("runPerFileReviewLoop requires buildInitialMessages(file) factory");
+  }
+  if (!client || typeof client.generatePlan !== "function") {
+    throw new TypeError("runPerFileReviewLoop requires a client with generatePlan()");
+  }
+
+  const maxTurns = Number.isInteger(options.maxTurnsPerFile)
+    ? options.maxTurnsPerFile
+    : INVESTOR_DD_DEFAULT_MAX_TURNS_PER_FILE;
+  const stuckThreshold = Number.isInteger(options.stuckThreshold)
+    ? options.stuckThreshold
+    : INVESTOR_DD_DEFAULT_STUCK_THRESHOLD;
+
+  const safeBudget = budget || createBudgetState();
+  const meteredClient = meterClient(client, safeBudget);
+
+  const perFile = [];
+  const allFindings = [];
+  const visited = [];
+  const skipped = [];
+  let terminationReason = "ok";
+
+  const emit = (event) => {
+    try {
+      onEvent(event);
+    } catch {
+      // sinks never break review
+    }
+  };
+
+  for (const file of files) {
+    const budgetCheck = checkBudget(safeBudget);
+    if (!budgetCheck.ok) {
+      terminationReason = budgetCheck.reason;
+      skipped.push(file);
+      emit({ type: "persona_file_skipped", personaId, file, stopReason: budgetCheck.reason });
+      continue;
+    }
+
+    emit({ type: "persona_file_start", personaId, file });
+
+    const fileTools = buildTools(file);
+    const meteredTools = meterTools(fileTools, safeBudget, (tool, input) => {
+      emit({ type: "persona_file_tool_call", personaId, file, tool, input });
+    });
+    const initialMessages = buildInitialMessages(file);
+
+    let loopResult;
+    try {
+      loopResult = await runEnvelopeLoop({
+        client: meteredClient,
+        initialMessages,
+        tools: meteredTools,
+        options: {
+          maxTurns,
+          stuckThreshold,
+          shouldAllowCall: () => {
+            const check = checkBudget(safeBudget);
+            return { allow: check.ok };
+          },
+          onTurn: ({ turn, plan }) => {
+            emit({
+              type: "persona_file_turn",
+              personaId,
+              file,
+              turn,
+              stopReason: plan?.stopReason ?? null,
+            });
+            const findings = Array.isArray(plan?.findings) ? plan.findings : [];
+            for (const f of findings) {
+              const decorated = { ...f, personaId, file };
+              allFindings.push(decorated);
+              emit({ type: "persona_finding", personaId, file, finding: decorated });
+            }
+          },
+        },
+      });
+    } catch (err) {
+      terminationReason = "client-error";
+      emit({
+        type: "persona_file_error",
+        personaId,
+        file,
+        stopReason: err instanceof Error ? err.message : String(err),
+      });
+      perFile.push({
+        file,
+        findings: [],
+        turnsUsed: 0,
+        stopReason: "client-error",
+        toolInvocations: [],
+      });
+      continue;
+    }
+
+    visited.push(file);
+    perFile.push({
+      file,
+      findings: Array.isArray(loopResult.findings) ? loopResult.findings : [],
+      turnsUsed: loopResult.turnsUsed ?? 0,
+      stopReason: loopResult.stuckReason ?? null,
+      toolInvocations: Array.isArray(loopResult.toolInvocations) ? loopResult.toolInvocations : [],
+    });
+
+    emit({
+      type: "persona_file_complete",
+      personaId,
+      file,
+      turnsUsed: loopResult.turnsUsed ?? 0,
+      stopReason: loopResult.stuckReason ?? null,
+    });
+  }
+
+  return {
+    personaId,
+    perFile,
+    findings: allFindings,
+    visited,
+    skipped,
+    terminationReason,
+  };
+}

package/src/review/investor-dd-file-router.js

@@ -0,0 +1,406 @@
+/**
+ * Deterministic file routing engine for investor-DD.
+ *
+ * Given the full list of files in a target repo and the persona roster,
+ * produce a routing table `{ personaId: filesInScope[] }` based on
+ * domain-specific include/exclude patterns. The router is deterministic
+ * (same inputs → same routing) so a run is replayable, and overlap is
+ * allowed — a single file can land in multiple persona queues if the
+ * patterns match.
+ *
+ * When a persona has NO matches after pattern filtering, the router
+ * falls back to a capped subset of "risk-surface" files (entry points,
+ * config, routes) so the persona still has something to look at rather
+ * than silently reporting empty coverage.
+ */
+
+const POSIX_SEP = "/";
+
+/**
+ * Per-persona include/exclude rules. Rules are substring checks against
+ * POSIX-normalized relative paths (so they survive Windows/linux). Glob
+ * matchers are intentionally avoided here — every rule is a simple
+ * includes() check so the routing is easy to reason about and unit-test.
+ */
+export const INVESTOR_DD_PERSONA_RULES = Object.freeze({
+  security: {
+    include: [
+      "/auth",
+      "/security",
+      "/crypto",
+      "/token",
+      "/password",
+      "/session",
+      "/login",
+      "/oauth",
+      "/permission",
+      "/role",
+      "/sanitiz",
+      "/escape",
+      "/middleware",
+    ],
+    extensions: [".js", ".ts", ".tsx", ".jsx", ".py", ".go", ".rs", ".java"],
+    exclude: ["/__fixtures__/", "/test-data/"],
+  },
+  backend: {
+    include: [
+      "/server",
+      "/api",
+      "/handler",
+      "/route",
+      "/controller",
+      "/service",
+      "/worker",
+      "/queue",
+      "/job",
+      "/middleware",
+    ],
+    extensions: [".js", ".ts", ".py", ".go", ".rs", ".java"],
+    exclude: ["/__fixtures__/", "/test-data/", "/web/", "/frontend/"],
+  },
+  "code-quality": {
+    include: [
+      "/src/",
+      "/lib/",
+      "/app/",
+      "/packages/",
+    ],
+    extensions: [".js", ".ts", ".tsx", ".jsx", ".py", ".go", ".rs", ".java"],
+    exclude: ["/node_modules/", "/dist/", "/build/", "/__snapshots__/", "/vendor/"],
+  },
+  testing: {
+    include: [
+      "/test/",
+      "/tests/",
+      "/__tests__/",
+      ".test.",
+      ".spec.",
+      "_test.",
+      "/conftest.py",
+    ],
+    extensions: [".js", ".ts", ".tsx", ".jsx", ".mjs", ".py", ".go", ".rs", ".java"],
+    exclude: ["/node_modules/", "/dist/"],
+  },
+  "data-layer": {
+    include: [
+      "/db/",
+      "/database/",
+      "/models/",
+      "/schema",
+      "/migration",
+      "/query",
+      "/repository",
+      "/repositories/",
+      "/dao",
+      ".sql",
+      "/prisma/",
+      "/sequelize/",
+      "/orm/",
+    ],
+    extensions: [".js", ".ts", ".py", ".sql", ".prisma"],
+    exclude: ["/node_modules/"],
+  },
+  reliability: {
+    include: [
+      "/health",
+      "/readiness",
+      "/liveness",
+      "/retry",
+      "/circuit",
+      "/fallback",
+      "/backpressure",
+      "/rate-limit",
+      "/degradation",
+    ],
+    extensions: [".js", ".ts", ".py", ".go"],
+    exclude: ["/node_modules/"],
+  },
+  release: {
+    include: [
+      ".github/workflows/",
+      "/ci/",
+      "CHANGELOG",
+      "/release",
+      "/deploy",
+      "/rollout",
+      "/version",
+      "/feature-flag",
+      "/feature_flag",
+      "/flags",
+    ],
+    extensions: [".yml", ".yaml", ".js", ".ts", ".py", ".md"],
+    exclude: [],
+  },
+  observability: {
+    include: [
+      "/logger",
+      "/logging",
+      "/metric",
+      "/trace",
+      "/telemetry",
+      "/span",
+      "/dashboard",
+      "/grafana",
+      "/alert",
+      "/monitor",
+    ],
+    extensions: [".js", ".ts", ".py", ".go", ".yml", ".yaml", ".json"],
+    exclude: [],
+  },
+  infrastructure: {
+    include: [
+      "/terraform/",
+      ".tf",
+      ".tfvars",
+      "/kubernetes/",
+      "/k8s/",
+      "/manifests/",
+      "/helm/",
+      "/docker",
+      "Dockerfile",
+      ".github/workflows/",
+      "/cdk/",
+      "/pulumi/",
+      "/serverless",
+    ],
+    extensions: [".tf", ".yaml", ".yml", ".json", ".hcl"],
+    exclude: [],
+  },
+  "supply-chain": {
+    include: [
+      "package.json",
+      "package-lock.json",
+      "yarn.lock",
+      "pnpm-lock.yaml",
+      "requirements.txt",
+      "pyproject.toml",
+      "Pipfile.lock",
+      "go.mod",
+      "go.sum",
+      "Cargo.toml",
+      "Cargo.lock",
+      "Gemfile",
+      "Gemfile.lock",
+      ".github/workflows/",
+      "SBOM",
+      "sbom",
+    ],
+    extensions: [],
+    exclude: ["/node_modules/"],
+  },
+  frontend: {
+    include: [
+      "/frontend/",
+      "/web/",
+      "/client/",
+      "/pages/",
+      "/components/",
+      "/app/",
+      "/ui/",
+      "/views/",
+      "/templates/",
+      ".vue",
+      ".svelte",
+      ".astro",
+    ],
+    extensions: [".tsx", ".jsx", ".ts", ".js", ".vue", ".svelte", ".html", ".css", ".scss"],
+    exclude: ["/server/", "/api/", "/node_modules/"],
+  },
+  documentation: {
+    include: [
+      "README",
+      "CHANGELOG",
+      "CONTRIBUTING",
+      "SECURITY",
+      "CODE_OF_CONDUCT",
+      "/docs/",
+      ".md",
+      ".mdx",
+      ".rst",
+    ],
+    extensions: [".md", ".mdx", ".rst", ".txt"],
+    exclude: ["/node_modules/"],
+  },
+  "ai-governance": {
+    include: [
+      "/prompt",
+      "/prompts/",
+      "/llm/",
+      "/ai/",
+      "/agent",
+      "/eval",
+      "/evals/",
+      "/guardrail",
+      "/safety",
+      "/completion",
+      "/inference",
+      "/embeddings",
+      "/rag",
+    ],
+    extensions: [".py", ".js", ".ts", ".yaml", ".yml", ".json", ".md"],
+    exclude: [],
+  },
+});
+
+const DEFAULT_FALLBACK_CAP = 20;
+
+const RISK_SURFACE_HINTS = Object.freeze([
+  "/server",
+  "/api",
+  "/main",
+  "/index",
+  "/app",
+  "/route",
+  "/handler",
+  "/auth",
+  "Dockerfile",
+  "/.github/workflows/",
+]);
+
+/**
+ * Normalize a path to POSIX separators so the substring rules are
+ * portable across OSes.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function toPosix(p) {
+  return String(p || "").split(/[\\/]/).join(POSIX_SEP);
+}
+
+/**
+ * Return true if `file` matches the persona rule: includes any of the
+ * include substrings AND (extensions empty OR matches an extension) AND
+ * excludes none of the exclude substrings.
+ *
+ * @param {string} file           - POSIX-normalized path.
+ * @param {object} rule
+ * @param {string[]} rule.include
+ * @param {string[]} rule.exclude
+ * @param {string[]} rule.extensions
+ * @returns {boolean}
+ */
+export function matchesRule(file, rule) {
+  if (!rule) return false;
+  const include = rule.include || [];
+  const exclude = rule.exclude || [];
+  const extensions = rule.extensions || [];
+
+  for (const pattern of exclude) {
+    if (file.includes(pattern)) return false;
+  }
+
+  let includeMatch = false;
+  for (const pattern of include) {
+    if (file.includes(pattern)) {
+      includeMatch = true;
+      break;
+    }
+  }
+  if (!includeMatch) return false;
+
+  if (extensions.length === 0) return true;
+
+  for (const ext of extensions) {
+    if (file.endsWith(ext)) return true;
+  }
+
+  // Files with no extension (e.g. Dockerfile, Makefile, Procfile) should
+  // still match when the rule's include pattern explicitly names them —
+  // the include hit already proved domain relevance.
+  const basename = file.split(POSIX_SEP).pop() || "";
+  if (!basename.includes(".")) {
+    for (const pattern of include) {
+      if (basename === pattern || basename.includes(pattern)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Simple heuristic scoring for fallback ranking. Higher = more risk-
+ * surface-like. Path segments known to harbor crosscutting concerns
+ * (auth/server/api/middleware/index/main) score higher.
+ *
+ * @param {string} file
+ * @returns {number}
+ */
+export function scoreRiskSurface(file) {
+  let score = 0;
+  for (const hint of RISK_SURFACE_HINTS) {
+    if (file.includes(hint)) score += 10;
+  }
+  // Prefer shallower files (closer to repo root → more likely entry points)
+  const depth = file.split(POSIX_SEP).length;
+  score += Math.max(0, 10 - depth);
+  return score;
+}
+
+/**
+ * Route the full file list to each persona's queue.
+ *
+ * @param {object} params
+ * @param {string[]} params.files          - All candidate files (relative POSIX paths or raw).
+ * @param {string[]} params.personas       - Persona IDs to route to.
+ * @param {object}   [params.rules]        - Custom rule map (defaults to INVESTOR_DD_PERSONA_RULES).
+ * @param {number}   [params.fallbackCap]  - Max fallback files when rule yields 0 (default 20).
+ * @returns {Record<string, string[]>}     - { personaId: filesInScope[] }
+ */
+export function routeFilesToPersonas({
+  files = [],
+  personas = [],
+  rules = INVESTOR_DD_PERSONA_RULES,
+  fallbackCap = DEFAULT_FALLBACK_CAP,
+} = {}) {
+  const normalized = files.map(toPosix);
+  const routing = {};
+
+  // Pre-compute fallback list once: risk-surface-sorted, capped.
+  const fallbackPool = [...normalized]
+    .sort((a, b) => scoreRiskSurface(b) - scoreRiskSurface(a))
+    .slice(0, fallbackCap);
+
+  for (const personaId of personas) {
+    const rule = rules[personaId];
+    if (!rule) {
+      routing[personaId] = [];
+      continue;
+    }
+
+    const matched = normalized.filter((f) => matchesRule(f, rule));
+    routing[personaId] = matched.length > 0 ? matched : [...fallbackPool];
+  }
+
+  return routing;
+}
+
+/**
+ * Produce a dense coverage summary suitable for persisting as part of a
+ * run's `plan.json` artifact.
+ *
+ * @param {Record<string, string[]>} routing
+ * @returns {{ totalFilesByPersona: Record<string, number>, uniqueFiles: number, dedupIndex: Record<string, string[]> }}
+ */
+export function summarizeRouting(routing) {
+  const totalFilesByPersona = {};
+  const fileToPersonas = new Map();
+
+  for (const [personaId, files] of Object.entries(routing || {})) {
+    totalFilesByPersona[personaId] = files.length;
+    for (const file of files) {
+      if (!fileToPersonas.has(file)) fileToPersonas.set(file, []);
+      fileToPersonas.get(file).push(personaId);
+    }
+  }
+
+  const dedupIndex = {};
+  for (const [file, personas] of fileToPersonas.entries()) {
+    dedupIndex[file] = [...personas];
+  }
+
+  return {
+    totalFilesByPersona,
+    uniqueFiles: fileToPersonas.size,
+    dedupIndex,
+  };
+}