sentinelayer-cli 0.8.0 → 0.8.1

package/src/agents/reliability/index.js

@@ -0,0 +1,12 @@
+// Noah (reliability persona) — barrel export (#A18).
+
+export {
+  RELIABILITY_TOOLS,
+  RELIABILITY_TOOL_IDS,
+  dispatchReliabilityTool,
+  runAllReliabilityTools,
+  runBackpressureCheck,
+  runChaosProbe,
+  runGracefulDegradationCheck,
+  runHealthCheckAudit,
+} from "./tools/index.js";

package/src/agents/reliability/tools/backpressure-check.js

@@ -0,0 +1,129 @@
+// backpressure-check — flag queue / worker patterns without backpressure or DLQ (#A18).
+//
+// When a consumer can outrun its queue the system degrades silently (memory
+// balloons, latency spikes, and eventual OOM). We look for queue consumers
+// and flag those missing:
+//   - a bounded concurrency / queue size (backpressure)
+//   - a dead-letter queue / DLQ signal for poison messages
+//   - explicit retry limits
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+]);
+
+const QUEUE_CONSUMER_PATTERNS = [
+  /bull(?:mq)?\.\w+|new\s+Queue\s*\(/,
+  /kafka\w*\.consumer\s*\(/,
+  /sqs\w*\.receiveMessage\s*\(/,
+  /rabbit\w*\.consume\s*\(/,
+  /redis\w*\.subscribe\s*\(/,
+  /celery\.task\s*\(/,
+  /@task\s*\(/,
+  /@app\.task\s*\(/,
+  /\b(?:worker|consumer|processor)\s*=\s*(?:new\s+)?\w+/,
+];
+
+const BACKPRESSURE_SIGNALS = [
+  /concurrency\s*[:=]\s*\d+/,
+  /maxConcurrent/i,
+  /prefetch[_-]?count/i,
+  /max_queue_size|maxQueueSize/,
+  /rate[_-]?limit/i,
+  /drop[_-]?on[_-]?full/i,
+  /visibility[_-]?timeout/i,
+];
+
+const DLQ_SIGNALS = [
+  /dead[_-]?letter|DLQ/i,
+  /retry[_-]?policy|max[_-]?retries|retry_limit/i,
+  /poison[_-]?pill|poison[_-]?message/i,
+];
+
+export async function runBackpressureCheck({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const consumerMatch = QUEUE_CONSUMER_PATTERNS.find((p) => p.test(content));
+    if (!consumerMatch) {
+      continue;
+    }
+    const hasBackpressure = BACKPRESSURE_SIGNALS.some((p) => p.test(content));
+    const hasDlq = DLQ_SIGNALS.some((p) => p.test(content));
+
+    const line = findLineMatches(content, consumerMatch)[0]?.line || 1;
+    if (!hasBackpressure) {
+      findings.push(
+        createFinding({
+          tool: "backpressure-check",
+          kind: "reliability.no-backpressure",
+          severity: "P1",
+          file: toPosix(relativePath),
+          line,
+          evidence: getLineContent(content, line),
+          rootCause:
+            "Queue consumer declared without a concurrency limit, prefetch count, or queue-full handling. A faster producer will balloon the in-memory queue or downstream pool.",
+          recommendedFix:
+            "Bound concurrency: BullMQ `concurrency` option, Kafka `max.poll.records`, SQS `MaxNumberOfMessages`, Celery `worker_prefetch_multiplier`. Pair with a 1-2 second visibility timeout.",
+          confidence: 0.55,
+        })
+      );
+    }
+    if (!hasDlq) {
+      findings.push(
+        createFinding({
+          tool: "backpressure-check",
+          kind: "reliability.no-dlq",
+          severity: "P1",
+          file: toPosix(relativePath),
+          line,
+          evidence: getLineContent(content, line),
+          rootCause:
+            "No dead-letter queue / retry-limit / poison-pill handling. A bad message will loop forever until the worker is manually killed.",
+          recommendedFix:
+            "Configure a DLQ with max-receive-count (SQS), delivery-limit (Bull), or max_retries (Celery). Alert on DLQ depth > 0 so operators see poison messages.",
+          confidence: 0.6,
+        })
+      );
+    }
+  }
+  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/reliability/tools/base.js

@@ -0,0 +1,181 @@
+// Shared helpers for Noah's (reliability) domain tools (#A18).
+
+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 = "reliability",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "reliability",
+    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 function findLineMatches(content, pattern) {
+  const text = String(content || "");
+  if (!pattern) {
+    return [];
+  }
+  const global = new RegExp(
+    pattern.source,
+    pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
+  );
+  const matches = [];
+  let match;
+  while ((match = global.exec(text)) !== null) {
+    const lineIndex = text.slice(0, match.index).split(/\r?\n/).length;
+    matches.push({ index: match.index, line: lineIndex, match: match[0] });
+  }
+  return matches;
+}
+
+export function getLineContent(content, line) {
+  const lines = String(content || "").split(/\r?\n/);
+  return (lines[Math.max(0, (Number(line) || 1) - 1)] || "").trim();
+}
+
+export { DEFAULT_IGNORED_DIRS, MAX_FILE_SIZE_BYTES, SEVERITIES };

package/src/agents/reliability/tools/chaos-probe.js

@@ -0,0 +1,109 @@
+// chaos-probe — verify that chaos testing / fault injection exists (#A18).
+//
+// Production-grade services should exercise failure paths, not just happy
+// paths. We look for signals that chaos-style tests are wired up:
+// - JS: chaos-monkey-js, gremlin, LitmusChaos configs
+// - Python: chaostoolkit config or chaos_engineering markers
+// - General: test files with `inject_failure` / `kill_dependency` /
+//   `simulate_outage` shapes
+// Absence on a repo that has more than a handful of outbound deps → P3 advisory.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".yaml",
+  ".yml",
+]);
+
+const CHAOS_SIGNALS = [
+  /chaos[-_]?monkey/i,
+  /litmus(chaos)?/i,
+  /gremlin\.(?:io|engine)/i,
+  /chaostoolkit|chaos_toolkit/i,
+  /@fault_injection|fault_injection\(/,
+  /simulate[_-]outage|inject[_-]failure|kill[_-]dependency/i,
+  /(^|\/)chaos\/[^/]+\.(yml|yaml|json)$/,
+];
+
+const OUTBOUND_SIGNALS = [
+  /\bfetch\s*\(/,
+  /\baxios(?:\.[a-z]+)?\s*\(/,
+  /\brequests\.(?:get|post|put|patch|delete|request)\s*\(/,
+  /\bhttpx\.(?:get|post|put|patch|delete|request)\s*\(/,
+];
+
+export async function runChaosProbe({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  let foundChaos = false;
+  const outboundFiles = new Set();
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    if (CHAOS_SIGNALS.some((p) => p.test(content) || p.test(toPosix(relativePath)))) {
+      foundChaos = true;
+      // Don't break — continue tallying outbound files so we still produce
+      // an accurate summary if requested elsewhere.
+    }
+    if (OUTBOUND_SIGNALS.some((p) => p.test(content))) {
+      outboundFiles.add(toPosix(relativePath));
+    }
+  }
+
+  const findings = [];
+  // Only advise when the repo actually talks to anything outside — a pure
+  // library without outbound deps doesn't need chaos.
+  if (!foundChaos && outboundFiles.size >= 3) {
+    findings.push(
+      createFinding({
+        tool: "chaos-probe",
+        kind: "reliability.no-chaos-testing",
+        severity: "P3",
+        file: "",
+        line: 0,
+        evidence: `${outboundFiles.size} file(s) make outbound HTTP calls, no chaos-testing signals found`,
+        rootCause:
+          "Services with multiple external dependencies can fail in novel ways that happy-path tests miss. Absent fault injection / chaos testing means those modes will first surface in production.",
+        recommendedFix:
+          "Wire up chaostoolkit (Python) or chaos-monkey-js (Node) with scenarios for each critical dependency (DB, payment processor, auth provider). Run weekly in staging.",
+        confidence: 0.45,
+      })
+    );
+  }
+  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/reliability/tools/graceful-degradation-check.js

@@ -0,0 +1,114 @@
+// graceful-degradation-check — flag call sites that fail hard when a
+// non-critical dependency errors (#A18).
+//
+// Heuristic: find files that call external deps but contain no try/catch
+// around them and no "fallback" / "default" / "cache" signal. Those files
+// propagate any dependency failure up to the user. A P2 advisory — it's
+// common and not always wrong — but worth a human look.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+]);
+
+const OUTBOUND_PATTERNS = [
+  /\bfetch\s*\(/,
+  /\baxios(?:\.[a-z]+)?\s*\(/,
+  /\bgot(?:\.[a-z]+)?\s*\(/,
+  /\brequests\.(?:get|post|put|patch|delete|request)\s*\(/,
+  /\bhttpx\.(?:get|post|put|patch|delete|request)\s*\(/,
+];
+
+const DEGRADATION_SIGNALS = [
+  /try\s*\{[\s\S]{0,600}?catch\s*\(/,
+  /\?\?\s*(?:cache|default|fallback)/i,
+  /try\s*:[\s\S]{0,600}?except\b/,
+  /\bif\s+cached/i,
+  /stale[-_]while[-_]revalidate/i,
+  /feature[_-]flag/,
+  /circuit[_-]?breaker/i,
+];
+
+export async function runGracefulDegradationCheck({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const findings = [];
+  const reportedFiles = new Set();
+  for await (const { fullPath, relativePath } of iterator) {
+    const rel = toPosix(relativePath);
+    if (reportedFiles.has(rel)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const hasOutbound = OUTBOUND_PATTERNS.some((p) => p.test(content));
+    if (!hasOutbound) {
+      continue;
+    }
+    const hasDegradation = DEGRADATION_SIGNALS.some((p) => p.test(content));
+    if (hasDegradation) {
+      continue;
+    }
+
+    const firstMatch =
+      findLineMatches(content, OUTBOUND_PATTERNS[0])[0] ||
+      findLineMatches(content, OUTBOUND_PATTERNS[1])[0] ||
+      findLineMatches(content, OUTBOUND_PATTERNS[2])[0] ||
+      findLineMatches(content, OUTBOUND_PATTERNS[3])[0] ||
+      findLineMatches(content, OUTBOUND_PATTERNS[4])[0];
+    if (!firstMatch) {
+      continue;
+    }
+    reportedFiles.add(rel);
+    findings.push(
+      createFinding({
+        tool: "graceful-degradation-check",
+        kind: "reliability.no-graceful-degradation",
+        severity: "P2",
+        file: rel,
+        line: firstMatch.line,
+        evidence: getLineContent(content, firstMatch.line),
+        rootCause:
+          "External call has no try/catch, cached fallback, feature flag, or circuit breaker in scope — failure in the dependency bubbles straight to the caller.",
+        recommendedFix:
+          "Wrap with a fallback: cached value, default response, or fail-silent for non-critical calls. Use a feature flag to cut over to degraded mode during incidents.",
+        confidence: 0.45,
+      })
+    );
+  }
+  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/reliability/tools/health-check-audit.js

@@ -0,0 +1,111 @@
+// health-check-audit — flag services without health / readiness endpoints (#A18).
+//
+// Any service behind a load balancer or deployed to k8s needs a health
+// endpoint so the platform can remove unhealthy instances from rotation.
+// We flag route-declaring files that don't expose a /health or /ready
+// endpoint.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+]);
+
+const ROUTE_DECLARATION = /\b(?:app|router|server|fastify|hono)\.(get|post|put|patch|delete)\s*\(|@(?:app|router|api_router)\.(?:get|post|put|patch|delete)\s*\(|func\s+\w+\(\s*w\s+http\.ResponseWriter/;
+const HEALTH_SIGNALS = [
+  /\/health(z)?\b/i,
+  /\/ready(z)?\b/i,
+  /\/live(ness)?\b/i,
+  /\/_status\b/,
+  /healthCheck\s*:/,
+];
+
+export async function runHealthCheckAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const findings = [];
+  const perService = new Map(); // dirKey -> { hasRoutes, hasHealth }
+
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const dirKey = toPosix(path.dirname(relativePath)) || ".";
+    const existing = perService.get(dirKey) || { hasRoutes: false, hasHealth: false, sampleFile: "" };
+    if (ROUTE_DECLARATION.test(content)) {
+      existing.hasRoutes = true;
+      if (!existing.sampleFile) {
+        existing.sampleFile = toPosix(relativePath);
+      }
+    }
+    if (HEALTH_SIGNALS.some((p) => p.test(content))) {
+      existing.hasHealth = true;
+    }
+    perService.set(dirKey, existing);
+  }
+
+  // Roll up per "service-ish" directory: if a route-declaring directory has
+  // no health endpoint anywhere under it, flag it.
+  for (const [dirKey, info] of perService.entries()) {
+    if (!info.hasRoutes || info.hasHealth) {
+      continue;
+    }
+    // Check if a sibling dir under the same service root has a health endpoint.
+    const parent = toPosix(path.posix.dirname(dirKey)) || ".";
+    const siblingHasHealth = Array.from(perService.entries()).some(
+      ([k, v]) => v.hasHealth && (toPosix(path.posix.dirname(k)) === parent || k === parent)
+    );
+    if (siblingHasHealth) {
+      continue;
+    }
+    findings.push(
+      createFinding({
+        tool: "health-check-audit",
+        kind: "reliability.no-health-endpoint",
+        severity: "P2",
+        file: info.sampleFile,
+        line: 0,
+        evidence: `Routes declared in ${dirKey}/ but no /health /ready /live endpoint detected`,
+        rootCause:
+          "Load balancers and orchestrators rely on health checks to route around failing instances. No health endpoint means failures propagate as user-facing errors.",
+        recommendedFix:
+          "Add a `/healthz` endpoint that returns HTTP 200 when dependencies (DB, cache, queue) respond within SLO; otherwise return 503.",
+        confidence: 0.55,
+      })
+    );
+  }
+  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 };
+  }
+}