sentinelayer-cli 0.6.2 → 0.8.1

package/src/agents/release/tools/feature-flag-audit.js

@@ -0,0 +1,126 @@
+// feature-flag-audit — find stale feature flags (#A19).
+//
+// Flag debt: a flag that's been "temporary" for six months is now load-
+// bearing architecture. We walk the repo for `flag.isEnabled("foo")` /
+// `useFlag("foo")` / `featureFlag("foo")` calls and flag flags that:
+//   1. Have been referenced for a long time (file mtime > 90 days)
+//   2. Have no corresponding cleanup date in a comment near the call site
+
+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 FLAG_PATTERNS = [
+  /flag(?:s)?\.isEnabled\s*\(\s*['"`]([^'"`]+)['"`]/g,
+  /useFlag\s*\(\s*['"`]([^'"`]+)['"`]/g,
+  /useFeatureFlag\s*\(\s*['"`]([^'"`]+)['"`]/g,
+  /launchdarkly\.variation\s*\(\s*['"`]([^'"`]+)['"`]/g,
+  /optimizely\.isFeatureEnabled\s*\(\s*['"`]([^'"`]+)['"`]/g,
+  /unleash\.isEnabled\s*\(\s*['"`]([^'"`]+)['"`]/g,
+  /growthbook\.isOn\s*\(\s*['"`]([^'"`]+)['"`]/g,
+];
+
+const STALE_DAYS = 90;
+
+function hasCleanupAnnotation(contextLines) {
+  return /remove[_-]?by|cleanup[_-]?by|expires?[_-]?on|retire[_-]?by/i.test(
+    contextLines.join("\n")
+  );
+}
+
+export async function runFeatureFlagAudit({
+  rootPath,
+  files = null,
+  staleDays = STALE_DAYS,
+} = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const now = Date.now();
+  const staleThreshold = now - staleDays * 24 * 60 * 60 * 1000;
+  const findings = [];
+
+  for await (const { fullPath, relativePath, stat } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const mtime = stat ? Number(stat.mtimeMs || 0) : now;
+    const isOld = mtime && mtime < staleThreshold;
+    const lines = content.split(/\r?\n/);
+
+    for (const pattern of FLAG_PATTERNS) {
+      for (const match of findLineMatches(content, pattern)) {
+        const flagName =
+          match.match.match(/['"`]([^'"`]+)['"`]/)?.[1] || "<unknown>";
+        const contextStart = Math.max(0, match.line - 3);
+        const contextEnd = Math.min(lines.length, match.line + 2);
+        const contextLines = lines.slice(contextStart, contextEnd);
+        if (hasCleanupAnnotation(contextLines)) {
+          continue;
+        }
+        if (!isOld) {
+          continue;
+        }
+        const ageDays = Math.floor((now - mtime) / (24 * 60 * 60 * 1000));
+        findings.push(
+          createFinding({
+            tool: "feature-flag-audit",
+            kind: "release.stale-flag",
+            severity: "P3",
+            file: toPosix(relativePath),
+            line: match.line,
+            evidence: `${getLineContent(content, match.line)} (file unchanged ${ageDays} days)`,
+            rootCause: `Flag '${flagName}' has been referenced for ≥ ${staleDays} days with no cleanup-by annotation.`,
+            recommendedFix:
+              "Add a `// cleanup-by: YYYY-MM-DD` comment near the call, or inline the chosen branch and delete the flag.",
+            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, "/");
+    const fsp = await import("node:fs/promises");
+    let stat = null;
+    try {
+      stat = await fsp.stat(fullPath);
+    } catch {
+      /* ignore */
+    }
+    yield { fullPath, relativePath, stat };
+  }
+}
+
+export { STALE_DAYS };

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

@@ -0,0 +1,61 @@
+// Omar (release persona) domain-tool registry (#A19).
+
+import { runChangelogDiff } from "./changelog-diff.js";
+import { runFeatureFlagAudit } from "./feature-flag-audit.js";
+import { runRollbackVerify } from "./rollback-verify.js";
+import { runSemverCheck } from "./semver-check.js";
+
+export const RELEASE_TOOLS = Object.freeze({
+  "semver-check": {
+    id: "semver-check",
+    description: "Verify every non-private package.json has a valid semver version and a colocated changelog.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runSemverCheck,
+  },
+  "changelog-diff": {
+    id: "changelog-diff",
+    description: "Verify the current version in package.json has a matching heading in the colocated CHANGELOG.md.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runChangelogDiff,
+  },
+  "rollback-verify": {
+    id: "rollback-verify",
+    description: "Ensure Alembic / Rails / Knex migrations define a down / downgrade / change path so `db:rollback` isn't a no-op.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runRollbackVerify,
+  },
+  "feature-flag-audit": {
+    id: "feature-flag-audit",
+    description: "Flag feature-flag call sites in files not touched in ≥ 90 days, with no cleanup-by annotation nearby.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        staleDays: { type: "number" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runFeatureFlagAudit,
+  },
+});
+
+export const RELEASE_TOOL_IDS = Object.freeze(Object.keys(RELEASE_TOOLS));
+
+export async function dispatchReleaseTool(toolId, args = {}) {
+  const tool = RELEASE_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown release tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllReleaseTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of RELEASE_TOOL_IDS) {
+    const out = await dispatchReleaseTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export { runChangelogDiff, runFeatureFlagAudit, runRollbackVerify, runSemverCheck };

package/src/agents/release/tools/rollback-verify.js

@@ -0,0 +1,129 @@
+// rollback-verify — ensure recent migrations + deploy configs support rollback (#A19).
+//
+// We check:
+//   - Alembic versions have a downgrade() body (not just pass)
+//   - Rails migrations have a `def down` or `reversible` block
+//   - Infrastructure / deploy configs mention rollback / revert strategies
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const MIGRATION_EXTENSIONS = new Set([".py", ".rb", ".sql", ".js", ".ts"]);
+
+function isAlembicFile(relPath) {
+  return /(^|\/)alembic\/versions\//.test(toPosix(relPath));
+}
+
+function isRailsMigrationFile(relPath) {
+  return /(^|\/)db\/migrate\/[^/]+\.rb$/.test(toPosix(relPath));
+}
+
+function isKnexMigrationFile(relPath) {
+  return /(^|\/)knex\/migrations?\//i.test(toPosix(relPath));
+}
+
+export async function runRollbackVerify({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: MIGRATION_EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    const rel = toPosix(relativePath);
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    if (isAlembicFile(rel)) {
+      const downgradeMatch = content.match(
+        /def\s+downgrade\s*\(\s*\)\s*(?:->[\s\S]*?)?\s*:\s*([\s\S]*?)(?=\ndef|\Z)/
+      );
+      const body = downgradeMatch ? downgradeMatch[1].trim() : "";
+      if (!downgradeMatch || body === "" || body === "pass" || /^\s*pass\s*$/.test(body)) {
+        findings.push(
+          createFinding({
+            tool: "rollback-verify",
+            kind: "release.empty-downgrade",
+            severity: "P1",
+            file: rel,
+            line: 0,
+            evidence: downgradeMatch ? "downgrade() body is empty / pass" : "no downgrade() defined",
+            rootCause:
+              "Alembic migration has no downgrade path. If the upgrade breaks production, we have no clean rollback.",
+            recommendedFix:
+              "Implement downgrade() that reverses upgrade() exactly. If data loss is inevitable, document it explicitly and gate upgrade() on a confirmation flag.",
+            confidence: 0.85,
+          })
+        );
+      }
+    }
+
+    if (isRailsMigrationFile(rel)) {
+      const hasDown = /\bdef\s+down\b/.test(content);
+      const hasReversible = /\breversible\b/.test(content);
+      const hasChange = /\bdef\s+change\b/.test(content);
+      if (!hasDown && !hasReversible && !hasChange) {
+        findings.push(
+          createFinding({
+            tool: "rollback-verify",
+            kind: "release.no-rails-down",
+            severity: "P1",
+            file: rel,
+            line: 0,
+            evidence: "No `def change`, `def down`, or `reversible` block",
+            rootCause:
+              "Rails migration without a reversible path. `rails db:rollback` will not undo this.",
+            recommendedFix:
+              "Use `def change` (Rails 4+ auto-reversible) or define an explicit `def down`.",
+            confidence: 0.85,
+          })
+        );
+      }
+    }
+
+    if (isKnexMigrationFile(rel)) {
+      const hasDown = /exports\.down\s*=|export\s+(?:async\s+)?function\s+down\b/.test(content);
+      if (!hasDown) {
+        findings.push(
+          createFinding({
+            tool: "rollback-verify",
+            kind: "release.no-knex-down",
+            severity: "P1",
+            file: rel,
+            line: 0,
+            evidence: "No exports.down / export function down in Knex migration",
+            rootCause:
+              "Knex migration without a down step — `knex migrate:rollback` will fail.",
+            recommendedFix:
+              "Pair every `exports.up` with an `exports.down` that reverses it.",
+            confidence: 0.85,
+          })
+        );
+      }
+    }
+  }
+  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/release/tools/semver-check.js

@@ -0,0 +1,109 @@
+// semver-check — verify package.json version follows semver + matches the
+// scope of its last release (#A19).
+//
+// Heuristic: look at every package.json the repo publishes and:
+//  1. Verify the version literal parses as semver (N.N.N or N.N.N-prerelease)
+//  2. Verify a CHANGELOG.md / CHANGES.md exists alongside it — having a
+//     versioned artifact without a changelog is a release-discipline miss
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const PKG_EXTENSIONS = new Set([".json"]);
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export async function runSemverCheck({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: PKG_EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    if (!/(^|\/)package\.json$/.test(toPosix(relativePath))) {
+      continue;
+    }
+    let raw;
+    try {
+      raw = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!parsed?.version || parsed.private === true) {
+      continue;
+    }
+    if (!SEMVER_PATTERN.test(String(parsed.version))) {
+      findings.push(
+        createFinding({
+          tool: "semver-check",
+          kind: "release.invalid-semver",
+          severity: "P1",
+          file: toPosix(relativePath),
+          line: 0,
+          evidence: `version = "${parsed.version}"`,
+          rootCause:
+            "package.json version doesn't parse as semver. npm / Yarn / pnpm tooling and npm registry itself rely on strict semver.",
+          recommendedFix: "Use the form MAJOR.MINOR.PATCH (optionally with -prerelease or +buildmeta).",
+          confidence: 0.95,
+        })
+      );
+    }
+
+    // Look for a changelog next to the package.json.
+    const dir = path.dirname(fullPath);
+    const candidates = ["CHANGELOG.md", "CHANGES.md", "CHANGELOG.txt"];
+    let hasChangelog = false;
+    for (const candidate of candidates) {
+      try {
+        await fsp.stat(path.join(dir, candidate));
+        hasChangelog = true;
+        break;
+      } catch {
+        /* missing — try next */
+      }
+    }
+    if (!hasChangelog) {
+      findings.push(
+        createFinding({
+          tool: "semver-check",
+          kind: "release.no-changelog",
+          severity: "P2",
+          file: toPosix(relativePath),
+          line: 0,
+          evidence: `No CHANGELOG.md / CHANGES.md next to ${toPosix(relativePath)}`,
+          rootCause:
+            "A published package without a changelog leaves consumers guessing what changed between versions.",
+          recommendedFix:
+            "Add CHANGELOG.md (Keep-a-Changelog format) and wire it to release-please / changesets so version bumps and entries stay in sync.",
+          confidence: 0.75,
+        })
+      );
+    }
+  }
+  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/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 };
+  }
+}