sentinelayer-cli 0.8.0 → 0.8.1

package/src/agents/backend/tools/timeout-audit.js

@@ -0,0 +1,144 @@
+// timeout-audit — flag outbound calls without explicit timeout (#A14).
+//
+// Default timeouts in every major HTTP client are too long:
+//   - Node fetch: no timeout by default — a hung downstream ties up a
+//     handler indefinitely
+//   - axios: no timeout by default
+//   - requests: no connect/read timeout by default
+//   - urllib: no timeout
+// We flag outbound calls that don't carry an explicit `timeout` / `signal` /
+// AbortSignal within the call arguments.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const JS_TS_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+const PY_EXTENSIONS = new Set([".py"]);
+
+function extractCallArgs(content, callIndex) {
+  // Very small bracket matcher — pulls the argument substring between the
+  // `(` following `callIndex` and the matching `)` (tracking nested
+  // parens / template literals at a simple level).
+  let depth = 0;
+  let inString = null;
+  let start = -1;
+  for (let i = callIndex; i < content.length; i += 1) {
+    const ch = content[i];
+    if (inString) {
+      if (ch === "\\") {
+        i += 1;
+        continue;
+      }
+      if (ch === inString) {
+        inString = null;
+      }
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      inString = ch;
+      continue;
+    }
+    if (ch === "(") {
+      depth += 1;
+      if (depth === 1) {
+        start = i + 1;
+      }
+    } else if (ch === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return content.slice(start, i);
+      }
+    }
+  }
+  return "";
+}
+
+function hasTimeoutInArgs(argString) {
+  return /timeout\s*[:=]\s*[^,)}\]]+|signal\s*:\s*[^,)}\]]+|AbortSignal\.timeout\s*\(/i.test(
+    argString || ""
+  );
+}
+
+const JS_CALLS = [
+  { pattern: /\bfetch\s*\(/, label: "fetch" },
+  { pattern: /\baxios(?:\.[a-z]+)?\s*\(/, label: "axios" },
+  { pattern: /\bgot(?:\.[a-z]+)?\s*\(/, label: "got" },
+  { pattern: /\bhttp\.(?:request|get|post)\s*\(/, label: "http" },
+  { pattern: /\bhttps\.(?:request|get|post)\s*\(/, label: "https" },
+];
+
+const PY_CALLS = [
+  { pattern: /\brequests\.(?:get|post|put|patch|delete|request)\s*\(/, label: "requests" },
+  { pattern: /\burllib\.request\.urlopen\s*\(/, label: "urllib" },
+  { pattern: /\bhttpx\.(?:get|post|put|patch|delete|request)\s*\(/, label: "httpx" },
+];
+
+export async function runTimeoutAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const extensions = new Set([...JS_TS_EXTENSIONS, ...PY_EXTENSIONS]);
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const ext = path.extname(fullPath).toLowerCase();
+    const calls = PY_EXTENSIONS.has(ext) ? PY_CALLS : JS_CALLS;
+
+    for (const call of calls) {
+      for (const match of findLineMatches(content, call.pattern)) {
+        const argString = extractCallArgs(content, match.index);
+        if (hasTimeoutInArgs(argString)) {
+          continue;
+        }
+        findings.push(
+          createFinding({
+            tool: "timeout-audit",
+            kind: "backend.no-timeout",
+            severity: "P1",
+            file: toPosix(relativePath),
+            line: match.line,
+            evidence: getLineContent(content, match.line),
+            rootCause: `${call.label} call has no explicit timeout — a slow downstream can stall the handler indefinitely.`,
+            recommendedFix:
+              "Always pass an explicit timeout: AbortSignal.timeout(ms) for fetch, { timeout } for axios / got / requests / httpx. Pick a value that's shorter than your request SLO.",
+            confidence: 0.7,
+          })
+        );
+      }
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) {
+      continue;
+    }
+    const fullPath = path.isAbsolute(trimmed)
+      ? trimmed
+      : path.join(resolvedRoot, trimmed);
+    const relativePath = path
+      .relative(resolvedRoot, fullPath)
+      .replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}

package/src/agents/code-quality/index.js

@@ -0,0 +1,12 @@
+// Ethan (code-quality persona) — barrel export (#A16).
+
+export {
+  CODE_QUALITY_TOOLS,
+  CODE_QUALITY_TOOL_IDS,
+  dispatchCodeQualityTool,
+  runAllCodeQualityTools,
+  runComplexityMeasure,
+  runCouplingAnalysis,
+  runCycleDetect,
+  runDepGraph,
+} from "./tools/index.js";

package/src/agents/code-quality/tools/base.js

@@ -0,0 +1,159 @@
+// Shared helpers for Ethan's (code-quality) domain tools (#A16).
+// Same per-persona base pattern as security / backend / testing.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import ignore from "ignore";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".sentinelayer",
+  ".sentinel",
+  ".turbo",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".cache",
+]);
+const MAX_FILE_SIZE_BYTES = 1024 * 1024;
+const SEVERITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
+
+export function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+export function normalizeSeverity(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (SEVERITIES.includes(normalized)) {
+    return normalized;
+  }
+  return "P2";
+}
+
+export function createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "code-quality",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "code-quality",
+    severity: normalizeSeverity(severity),
+    file: toPosix(file || ""),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence:
+      confidence === null || confidence === undefined
+        ? null
+        : Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+async function readIgnorePatterns(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return String(raw || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+async function createIgnoreMatcher(rootPath) {
+  const matcher = ignore();
+  const gitignore = await readIgnorePatterns(path.join(rootPath, ".gitignore"));
+  const sentinel = await readIgnorePatterns(
+    path.join(rootPath, ".sentinelayerignore")
+  );
+  matcher.add([...gitignore, ...sentinel]);
+  return (relativePath, isDirectory) => {
+    const normalized = toPosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    const candidate = isDirectory ? `${normalized}/` : normalized;
+    return matcher.ignores(candidate);
+  };
+}
+
+export async function* walkRepoFiles({
+  rootPath = process.cwd(),
+  extensions = new Set(),
+  maxFileSize = MAX_FILE_SIZE_BYTES,
+} = {}) {
+  const resolvedRoot = path.resolve(rootPath);
+  const ignoreMatcher = await createIgnoreMatcher(resolvedRoot);
+  const wantedExtensions =
+    extensions instanceof Set
+      ? extensions
+      : new Set(Array.isArray(extensions) ? extensions : []);
+  const stack = [resolvedRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = toPosix(path.relative(resolvedRoot, fullPath));
+      if (entry.isDirectory()) {
+        if (!relativePath || DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (ignoreMatcher(relativePath, true)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (ignoreMatcher(relativePath, false)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (wantedExtensions.size > 0 && !wantedExtensions.has(ext) && !wantedExtensions.has("")) {
+        continue;
+      }
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      if (!stat || stat.size > maxFileSize) {
+        continue;
+      }
+      yield { fullPath, relativePath };
+    }
+  }
+}
+
+export { DEFAULT_IGNORED_DIRS, MAX_FILE_SIZE_BYTES, SEVERITIES };

package/src/agents/code-quality/tools/complexity-measure.js

@@ -0,0 +1,197 @@
+// complexity-measure — simple cyclomatic complexity estimate per function (#A16).
+//
+// We don't try to be ESLint-strict — we estimate cyclomatic complexity by
+// counting branching keywords within each function body. It's an
+// approximation (it doesn't handle labeled break / conditional short-circuit
+// perfectly) but it's enough to surface the worst offenders.
+//
+// Threshold defaults: P1 at CC >= 30, P2 at CC >= 15. Tune via options.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "@babel/parser";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const DEFAULT_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+
+const BRANCHING_NODE_TYPES = new Set([
+  "IfStatement",
+  "ForStatement",
+  "ForInStatement",
+  "ForOfStatement",
+  "WhileStatement",
+  "DoWhileStatement",
+  "SwitchCase",
+  "CatchClause",
+  "ConditionalExpression",
+  "LogicalExpression", // &&, ||, ??
+]);
+
+function pickPlugins(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const plugins = ["importAttributes", "dynamicImport"];
+  if (ext === ".ts" || ext === ".tsx" || ext === ".mts" || ext === ".cts") {
+    plugins.push("typescript");
+  }
+  if (ext === ".jsx" || ext === ".tsx") {
+    plugins.push("jsx");
+  }
+  return plugins;
+}
+
+function estimateComplexity(bodyNode) {
+  if (!bodyNode || typeof bodyNode !== "object") {
+    return 1;
+  }
+  let count = 1; // Minimum CC = 1 (straight-line function)
+  const queue = [bodyNode];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+    if (BRANCHING_NODE_TYPES.has(node.type)) {
+      count += 1;
+    }
+    for (const value of Object.values(node)) {
+      if (value && typeof value === "object") {
+        if (Array.isArray(value)) {
+          queue.push(...value);
+        } else {
+          queue.push(value);
+        }
+      }
+    }
+  }
+  return count;
+}
+
+function functionName(node) {
+  if (!node) {
+    return "<anonymous>";
+  }
+  if (node.id?.name) {
+    return node.id.name;
+  }
+  return "<anonymous>";
+}
+
+function collectFunctions(astRoot, filePath) {
+  const results = [];
+  const queue = [astRoot];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+    if (Array.isArray(node)) {
+      for (const v of node) {
+        queue.push(v);
+      }
+      continue;
+    }
+    if (
+      node.type === "FunctionDeclaration" ||
+      node.type === "FunctionExpression" ||
+      node.type === "ArrowFunctionExpression" ||
+      node.type === "ClassMethod" ||
+      node.type === "ObjectMethod"
+    ) {
+      results.push({
+        name: functionName(node),
+        line: node.loc?.start?.line ?? 0,
+        complexity: estimateComplexity(node.body),
+        file: filePath,
+      });
+    }
+    for (const value of Object.values(node)) {
+      if (value && typeof value === "object") {
+        queue.push(value);
+      }
+    }
+  }
+  return results;
+}
+
+export async function runComplexityMeasure({
+  rootPath,
+  files = null,
+  p1Threshold = 30,
+  p2Threshold = 15,
+} = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: DEFAULT_EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let ast;
+    try {
+      ast = parse(content, {
+        sourceType: "unambiguous",
+        errorRecovery: true,
+        plugins: pickPlugins(fullPath),
+      });
+    } catch {
+      continue;
+    }
+    const functions = collectFunctions(ast, toPosix(relativePath));
+    for (const fn of functions) {
+      if (fn.complexity < p2Threshold) {
+        continue;
+      }
+      const severity = fn.complexity >= p1Threshold ? "P1" : "P2";
+      findings.push(
+        createFinding({
+          tool: "complexity-measure",
+          kind: "code-quality.high-complexity",
+          severity,
+          file: fn.file,
+          line: fn.line,
+          evidence: `function '${fn.name}' has estimated CC=${fn.complexity}`,
+          rootCause:
+            "High cyclomatic complexity means many independent paths through the function — hard to test exhaustively and easy to break on edits.",
+          recommendedFix:
+            "Split on the dominant branch axis (early-return guards, extract-method on nested conditionals, or convert a long switch into a dispatch table).",
+          confidence: 0.7,
+        })
+      );
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) {
+      continue;
+    }
+    const fullPath = path.isAbsolute(trimmed)
+      ? trimmed
+      : path.join(resolvedRoot, trimmed);
+    const relativePath = path
+      .relative(resolvedRoot, fullPath)
+      .replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}
+
+export { BRANCHING_NODE_TYPES, estimateComplexity };

package/src/agents/code-quality/tools/coupling-analysis.js

@@ -0,0 +1,81 @@
+// coupling-analysis — flag high fan-out / fan-in modules (#A16).
+//
+// Fan-out: how many distinct modules does THIS file import? Very high
+// fan-out suggests an anti-pattern — the file knows too much about the
+// rest of the system.
+//
+// Fan-in: how many modules import THIS file? Very high fan-in marks a
+// "god module" that many sites depend on; risk is concentrated here.
+
+import path from "node:path";
+
+import { createFinding } from "./base.js";
+import { buildDependencyGraph } from "./dep-graph.js";
+
+const FAN_OUT_THRESHOLD = 20;
+const FAN_IN_THRESHOLD = 15;
+
+export async function runCouplingAnalysis({ rootPath, files = null, graph = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const dependencyGraph =
+    graph && typeof graph === "object"
+      ? graph
+      : await buildDependencyGraph({ rootPath: resolvedRoot, files });
+
+  const fanOut = {};
+  const fanIn = {};
+  for (const [file, edges] of Object.entries(dependencyGraph)) {
+    fanOut[file] = edges.length;
+    for (const edge of edges) {
+      if (edge.startsWith("npm:") || edge.startsWith("/")) {
+        continue;
+      }
+      fanIn[edge] = (fanIn[edge] || 0) + 1;
+    }
+  }
+
+  const findings = [];
+  for (const [file, count] of Object.entries(fanOut)) {
+    if (count < FAN_OUT_THRESHOLD) {
+      continue;
+    }
+    findings.push(
+      createFinding({
+        tool: "coupling-analysis",
+        kind: "code-quality.high-fan-out",
+        severity: count >= FAN_OUT_THRESHOLD * 2 ? "P1" : "P2",
+        file,
+        line: 0,
+        evidence: `fan-out = ${count} (threshold ${FAN_OUT_THRESHOLD})`,
+        rootCause:
+          "High fan-out: this module imports from many other modules, which is a sign it's doing too much and is brittle to downstream changes.",
+        recommendedFix:
+          "Split by responsibility. A Facade / Mediator can reduce the breadth of imports if the file is legitimately a coordinator.",
+        confidence: 0.7,
+      })
+    );
+  }
+  for (const [file, count] of Object.entries(fanIn)) {
+    if (count < FAN_IN_THRESHOLD) {
+      continue;
+    }
+    findings.push(
+      createFinding({
+        tool: "coupling-analysis",
+        kind: "code-quality.high-fan-in",
+        severity: count >= FAN_IN_THRESHOLD * 2 ? "P1" : "P2",
+        file,
+        line: 0,
+        evidence: `fan-in = ${count} (threshold ${FAN_IN_THRESHOLD})`,
+        rootCause:
+          "High fan-in: many modules depend on this file, so any behavior change risks a broad blast radius.",
+        recommendedFix:
+          "Stabilize the surface (consider making this module an interface / contract) and move implementation details behind it.",
+        confidence: 0.65,
+      })
+    );
+  }
+  return findings;
+}
+
+export { FAN_IN_THRESHOLD, FAN_OUT_THRESHOLD };

package/src/agents/code-quality/tools/cycle-detect.js

@@ -0,0 +1,49 @@
+// cycle-detect — find import cycles in the module graph (#A16).
+//
+// Reuses findCycles() from src/coord/tarjan.js so we don't ship a second
+// SCC implementation. Returns one Finding per cycle so the orchestrator
+// can rank and prioritize; the cycle's component list is embedded in the
+// finding's evidence + rootCause for review.
+
+import path from "node:path";
+
+import { findCycles } from "../../../coord/tarjan.js";
+
+import { createFinding } from "./base.js";
+import { buildDependencyGraph } from "./dep-graph.js";
+
+export async function runCycleDetect({ rootPath, files = null, graph = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const dependencyGraph =
+    graph && typeof graph === "object"
+      ? graph
+      : await buildDependencyGraph({ rootPath: resolvedRoot, files });
+
+  // Strip npm:* nodes from the graph — they're sinks, not cycle participants.
+  const localGraph = {};
+  for (const [file, edges] of Object.entries(dependencyGraph)) {
+    localGraph[file] = edges.filter((edge) => !edge.startsWith("npm:") && !edge.startsWith("/"));
+  }
+
+  const cycles = findCycles(localGraph);
+  const findings = [];
+  for (const cycle of cycles) {
+    const primary = cycle.slice().sort()[0];
+    findings.push(
+      createFinding({
+        tool: "cycle-detect",
+        kind: "code-quality.import-cycle",
+        severity: cycle.length > 3 ? "P1" : "P2",
+        file: primary,
+        line: 0,
+        evidence: `Cycle of ${cycle.length} modules: ${cycle.join(" → ")}`,
+        rootCause:
+          "Import cycle forces the module loader to resolve modules out of order — causes TDZ errors, half-initialized exports, and refactor-proof coupling.",
+        recommendedFix:
+          "Break the cycle by extracting shared types / interfaces into a new module that both sides can depend on, or move the behavior that creates the back-edge into a callback injected at call time.",
+        confidence: 0.85,
+      })
+    );
+  }
+  return findings;
+}