sentinelayer-cli 0.6.2 → 0.8.1

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 };
+  }
+}

package/src/agents/reliability/tools/index.js

@@ -0,0 +1,87 @@
+// Noah (reliability persona) domain-tool registry (#A18).
+
+import { runBackpressureCheck } from "./backpressure-check.js";
+import { runChaosProbe } from "./chaos-probe.js";
+import { runGracefulDegradationCheck } from "./graceful-degradation-check.js";
+import { runHealthCheckAudit } from "./health-check-audit.js";
+
+export const RELIABILITY_TOOLS = Object.freeze({
+  "chaos-probe": {
+    id: "chaos-probe",
+    description:
+      "Report whether the repo has any chaos-testing / fault-injection signals (chaostoolkit, chaos-monkey-js, LitmusChaos, gremlin). Only advises when the repo has ≥3 outbound-HTTP call sites.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runChaosProbe,
+  },
+  "health-check-audit": {
+    id: "health-check-audit",
+    description:
+      "Flag service directories that declare HTTP routes but don't expose /health /healthz /ready /live / _status.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runHealthCheckAudit,
+  },
+  "graceful-degradation-check": {
+    id: "graceful-degradation-check",
+    description:
+      "Flag files that make outbound HTTP calls without try/catch, cached fallback, feature-flag, or circuit-breaker in scope.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runGracefulDegradationCheck,
+  },
+  "backpressure-check": {
+    id: "backpressure-check",
+    description:
+      "Find queue/worker consumers (Bull, Kafka, SQS, RabbitMQ, Redis pub/sub, Celery) and flag those missing concurrency caps or DLQ / retry-limit configuration.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runBackpressureCheck,
+  },
+});
+
+export const RELIABILITY_TOOL_IDS = Object.freeze(Object.keys(RELIABILITY_TOOLS));
+
+export async function dispatchReliabilityTool(toolId, args = {}) {
+  const tool = RELIABILITY_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown reliability tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllReliabilityTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of RELIABILITY_TOOL_IDS) {
+    const out = await dispatchReliabilityTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export {
+  runBackpressureCheck,
+  runChaosProbe,
+  runGracefulDegradationCheck,
+  runHealthCheckAudit,
+};