sentinelayer-cli 0.6.2 → 0.8.1

package/src/agents/data-layer/tools/index.js

@@ -0,0 +1,83 @@
+// Linh (data-layer persona) domain-tool registry (#A17).
+
+import { runIndexAudit } from "./index-audit.js";
+import { runMigrationScan } from "./migration-scan.js";
+import { runQueryExplain } from "./query-explain.js";
+import { runTenancyScan } from "./tenancy-scan.js";
+
+export const DATA_LAYER_TOOLS = Object.freeze({
+  "query-explain": {
+    id: "query-explain",
+    description:
+      "Scan source for query anti-patterns: SELECT without LIMIT, findAll in a loop (N+1), string-concatenated SQL, SELECT *.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runQueryExplain,
+  },
+  "migration-scan": {
+    id: "migration-scan",
+    description:
+      "Scan migration files (.sql, alembic, prisma, knex, Rails db/migrate) for unsafe patterns: DROP TABLE/COLUMN, ADD COLUMN NOT NULL w/o default, CREATE INDEX w/o CONCURRENTLY, unbatched UPDATE.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runMigrationScan,
+  },
+  "index-audit": {
+    id: "index-audit",
+    description:
+      "Cross-reference WHERE / JOIN columns in application code vs. CREATE INDEX / @Index / db_index declarations in migrations + models. Flag lookups with no matching index.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runIndexAudit,
+  },
+  "tenancy-scan": {
+    id: "tenancy-scan",
+    description:
+      "Identify tenancy-owning tables (those whose schema includes tenant_id / org_id / workspace_id) and flag application queries that touch them without a tenancy filter.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+        tenancyTables: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runTenancyScan,
+  },
+});
+
+export const DATA_LAYER_TOOL_IDS = Object.freeze(Object.keys(DATA_LAYER_TOOLS));
+
+export async function dispatchDataLayerTool(toolId, args = {}) {
+  const tool = DATA_LAYER_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown data-layer tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllDataLayerTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of DATA_LAYER_TOOL_IDS) {
+    const out = await dispatchDataLayerTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export { runIndexAudit, runMigrationScan, runQueryExplain, runTenancyScan };

package/src/agents/data-layer/tools/migration-scan.js

@@ -0,0 +1,135 @@
+// migration-scan — flag unsafe migration patterns (#A17).
+//
+// Migration reviews are where data-layer review adds the most value. We
+// scan .sql, alembic versions, prisma migrations, knex migrations for
+// patterns that lock the table, drop data, or block app writes during a
+// long backfill.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const MIGRATION_EXTENSIONS = new Set([".sql", ".py"]);
+
+function isMigrationPath(relPath) {
+  const p = toPosix(relPath);
+  return (
+    /(^|\/)migrations?\//i.test(p) ||
+    /(^|\/)alembic\/versions\//.test(p) ||
+    /(^|\/)prisma\/migrations\//.test(p) ||
+    /(^|\/)knex\/migrations?\//i.test(p) ||
+    /(^|\/)db\/migrate\//.test(p) // Rails
+  );
+}
+
+const RULES = [
+  {
+    id: "migration.drop-table",
+    pattern: /\bDROP\s+TABLE\b/i,
+    severity: "P0",
+    rootCause:
+      "DROP TABLE in a migration deletes data irreversibly. Even if the table seems unused, a rollback can't recover rows without a backup.",
+    recommendedFix:
+      "Phase the change: (1) stop writing to the table; (2) wait long enough for any in-flight reads to drain; (3) rename to `_<table>_deprecated` for N days; (4) then DROP once restoration is impossible.",
+    confidence: 0.95,
+  },
+  {
+    id: "migration.drop-column",
+    pattern: /\bDROP\s+COLUMN\b/i,
+    severity: "P1",
+    rootCause:
+      "DROP COLUMN blocks writers from rolling back gracefully (the app still references the column until redeployed).",
+    recommendedFix:
+      "Migrate in two phases: remove app reads/writes first, deploy, then drop the column in a follow-up migration.",
+    confidence: 0.85,
+  },
+  {
+    id: "migration.add-column-not-null-no-default",
+    pattern: /ALTER\s+TABLE[\s\S]{0,200}?ADD\s+(?:COLUMN\s+)?[`"]?\w+[`"]?\s+[\w()]+\s+NOT\s+NULL(?!\s+DEFAULT)/i,
+    severity: "P0",
+    rootCause:
+      "Adding a NOT NULL column with no DEFAULT rewrites every existing row at migration time — long AccessExclusiveLock on large tables, breaks writes.",
+    recommendedFix:
+      "Add the column nullable first, backfill in batches, then set NOT NULL (and DEFAULT) once the backfill is complete.",
+    confidence: 0.9,
+  },
+  {
+    id: "migration.no-concurrent-index",
+    // Postgres-specific: CREATE INDEX without CONCURRENTLY blocks writes
+    pattern: /CREATE\s+(?!UNIQUE\s+)INDEX\s+(?!CONCURRENTLY)\b/i,
+    severity: "P1",
+    rootCause:
+      "CREATE INDEX without CONCURRENTLY holds a ShareLock on the table — no writes while the index builds. On hot tables this is effectively an outage.",
+    recommendedFix:
+      "Use `CREATE INDEX CONCURRENTLY`. It takes longer and can't run inside a transaction, but writes proceed throughout.",
+    confidence: 0.7,
+  },
+  {
+    id: "migration.unbatched-update",
+    pattern: /\bUPDATE\s+[\w.`"]+\s+SET\b(?![\s\S]*?WHERE\s+[\s\S]{0,200}?\bLIMIT\b)/i,
+    severity: "P1",
+    rootCause:
+      "Unbatched UPDATE of an entire table — long transaction, large WAL / redo log, potential replication lag or disk fill.",
+    recommendedFix:
+      "Batch: `WHERE id BETWEEN :lo AND :hi LIMIT n` and commit per batch. For Postgres add pg_sleep between batches to give autovacuum time to catch up.",
+    confidence: 0.55,
+  },
+];
+
+export async function runMigrationScan({ 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) {
+    if (!isMigrationPath(relativePath)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const rule of RULES) {
+      for (const match of findLineMatches(content, rule.pattern)) {
+        findings.push(
+          createFinding({
+            tool: "migration-scan",
+            kind: rule.id,
+            severity: rule.severity,
+            file: toPosix(relativePath),
+            line: match.line,
+            evidence: getLineContent(content, match.line),
+            rootCause: rule.rootCause,
+            recommendedFix: rule.recommendedFix,
+            confidence: rule.confidence,
+          })
+        );
+      }
+    }
+  }
+  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 { RULES as MIGRATION_RULES, isMigrationPath };

package/src/agents/data-layer/tools/query-explain.js

@@ -0,0 +1,120 @@
+// query-explain — flag unbounded / N+1 query shapes (#A17).
+//
+// We scan code for common data-access anti-patterns. Real EXPLAIN output is
+// a database-side operation; this tool focuses on the source-level red
+// flags (missing LIMIT, findAll in loops, string-concatenated SQL) that
+// typically predict explosive queries before the DB actually runs them.
+
+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",
+  ".rb",
+]);
+
+const RULES = [
+  {
+    id: "data.query-no-limit",
+    pattern: /SELECT[\s\S]{0,200}?FROM\s+[\w.`"]+\s*(?!.*\b(LIMIT|FETCH FIRST)\b)(?:WHERE\s[^;]*)?;?\s*[`'"]/i,
+    severity: "P1",
+    rootCause:
+      "Raw SELECT without LIMIT / FETCH FIRST. On a growing table this returns more rows every day and will eventually OOM the caller.",
+    recommendedFix:
+      "Always paginate: add LIMIT with a configured page size, or switch to cursor-based iteration (`WHERE id > :lastId ORDER BY id LIMIT n`).",
+    confidence: 0.6,
+  },
+  {
+    id: "data.n-plus-one-findall-in-loop",
+    pattern: /for\s*\([^)]*\)\s*\{[\s\S]{0,400}?\b(?:findAll|findMany|find_one|find_all|objects\.all|objects\.filter|Model\.\w+|repository\.\w+|db\.[a-z_]+\.find)\s*\(/,
+    severity: "P1",
+    rootCause:
+      "Data-access call inside a for-loop body — classic N+1. Each iteration issues another round-trip to the database.",
+    recommendedFix:
+      "Batch the loop: fetch once with `WHERE id IN (…)` or an eager-loaded join; or use a dataloader (JS) / prefetch_related (Django) / bullet gem (Rails).",
+    confidence: 0.65,
+  },
+  {
+    id: "data.string-concat-sql",
+    pattern: /(?:query|execute|db\.raw|sequelize\.query|knex\.raw|\.exec)\s*\(\s*[`'"][^`'"]*[`'"]\s*\+/,
+    severity: "P0",
+    rootCause:
+      "SQL built via string concatenation — if any concatenated term is user input, this is a SQLi path.",
+    recommendedFix:
+      "Use parameterized queries / prepared statements. Every major driver supports `?` / `$1` / `:named` placeholders.",
+    confidence: 0.85,
+  },
+  {
+    id: "data.select-star",
+    pattern: /SELECT\s+\*\s+FROM\s+[\w.`"]+/i,
+    severity: "P3",
+    rootCause:
+      "`SELECT *` binds the caller to every column the table happens to have — a schema change (adding a BYTEA / LONGTEXT) can silently blow up payload size.",
+    recommendedFix:
+      "Enumerate the columns you actually need. If you really need everything, wrap in a view so the contract is explicit.",
+    confidence: 0.8,
+  },
+];
+
+export async function runQueryExplain({ 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;
+    }
+    for (const rule of RULES) {
+      for (const match of findLineMatches(content, rule.pattern)) {
+        findings.push(
+          createFinding({
+            tool: "query-explain",
+            kind: rule.id,
+            severity: rule.severity,
+            file: toPosix(relativePath),
+            line: match.line,
+            evidence: getLineContent(content, match.line),
+            rootCause: rule.rootCause,
+            recommendedFix: rule.recommendedFix,
+            confidence: rule.confidence,
+          })
+        );
+      }
+    }
+  }
+  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 { RULES as QUERY_RULES };

package/src/agents/data-layer/tools/tenancy-scan.js

@@ -0,0 +1,166 @@
+// tenancy-scan — flag queries that may leak across tenants (#A17).
+//
+// In a multi-tenant system every row-level query needs to constrain on
+// tenant_id / org_id / workspace_id (whatever the ambient tenancy column
+// is). Missing that filter is a cross-tenant data leak — classic P0.
+//
+// Heuristic: we look for "tenancy-table" signals (tables or models whose
+// schema mentions tenant_id / org_id / workspace_id) and then in application
+// code we flag queries against those tables that don't include the tenancy
+// column in the WHERE.
+
+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",
+  ".rb",
+  ".sql",
+]);
+
+const TENANCY_COLUMNS = ["tenant_id", "org_id", "organization_id", "workspace_id", "account_id"];
+
+function tenancyTableRegex() {
+  // Match a schema / model declaration (CREATE TABLE, @Column, JS class,
+  // Python class) that sits within ~2 KB of one of the tenancy column
+  // names.
+  return new RegExp(
+    `(?:CREATE\\s+TABLE\\s+[\\w.]+|@Column|class\\s+\\w+\\s*[({:]|class\\s+\\w+\\s*\\{|model\\s*:\\s*\\w+)[\\s\\S]{0,2000}?(${TENANCY_COLUMNS.join("|")})`,
+    "gi"
+  );
+}
+
+function queryRegex(tableName) {
+  // Match a SELECT / UPDATE / DELETE referencing the table name.
+  return new RegExp(
+    `(?:SELECT[\\s\\S]*?FROM|UPDATE|DELETE\\s+FROM)\\s+[\\w.\`"]*?\\b${tableName}\\b`,
+    "gi"
+  );
+}
+
+async function collectTenancyTables(rootPath) {
+  const tables = new Set();
+  for await (const { fullPath, relativePath } of walkRepoFiles({
+    rootPath,
+    extensions: CODE_EXTENSIONS,
+  })) {
+    const p = toPosix(relativePath);
+    const isSchemaFile =
+      /(^|\/)(schema|models?)\//i.test(p) ||
+      /(^|\/)migrations?\//i.test(p) ||
+      /(^|\/)alembic\/versions\//i.test(p) ||
+      /(^|\/)prisma\//i.test(p);
+    if (!isSchemaFile) {
+      continue;
+    }
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const regex = tenancyTableRegex();
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      // Pull the table / class name from the match prefix.
+      const prefix = match[0];
+      const tableMatch = prefix.match(/CREATE\s+TABLE\s+[`"]?(\w+)/i);
+      if (tableMatch) {
+        tables.add(tableMatch[1].toLowerCase());
+        continue;
+      }
+      const classMatch = prefix.match(/class\s+(\w+)/);
+      if (classMatch) {
+        // Convention: class Foo → table foos / foo. Keep both.
+        const name = classMatch[1].toLowerCase();
+        tables.add(name);
+        tables.add(`${name}s`);
+      }
+    }
+  }
+  return tables;
+}
+
+export async function runTenancyScan({ rootPath, files = null, tenancyTables = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const tables =
+    tenancyTables instanceof Set
+      ? tenancyTables
+      : await collectTenancyTables(resolvedRoot);
+  if (tables.size === 0) {
+    return [];
+  }
+
+  const findings = [];
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const table of tables) {
+      const regex = queryRegex(table);
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        // Look at a ~200-char window after the match for a tenancy column
+        // in the WHERE clause.
+        const window = content.slice(match.index, match.index + 400);
+        const hasTenancyFilter = TENANCY_COLUMNS.some((col) =>
+          new RegExp(`\\b${col}\\s*(?:=|IN|\\?)`).test(window)
+        );
+        if (hasTenancyFilter) {
+          continue;
+        }
+        const lineIndex = content.slice(0, match.index).split(/\r?\n/).length;
+        const lineContent = content.split(/\r?\n/)[lineIndex - 1] || "";
+        findings.push(
+          createFinding({
+            tool: "tenancy-scan",
+            kind: "data.missing-tenancy-filter",
+            severity: "P0",
+            file: toPosix(relativePath),
+            line: lineIndex,
+            evidence: lineContent.trim(),
+            rootCause: `Query against tenancy-owning table '${table}' has no tenant_id / org_id / workspace_id constraint in the WHERE.`,
+            recommendedFix: `Add a tenancy filter: "WHERE tenant_id = :tenantId" (or the equivalent tenancy column). Enforce with a database RLS policy when possible.`,
+            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 { TENANCY_COLUMNS, collectTenancyTables };

package/src/agents/documentation/index.js

@@ -0,0 +1,12 @@
+// Samir (documentation persona) — barrel export (#A23).
+
+export {
+  DOCUMENTATION_TOOLS,
+  DOCUMENTATION_TOOL_IDS,
+  dispatchDocumentationTool,
+  runAllDocumentationTools,
+  runApiDiff,
+  runDeadLinkCheck,
+  runDocstringCoverage,
+  runReadmeFreshness,
+} from "./tools/index.js";

package/src/agents/documentation/tools/api-diff.js

@@ -0,0 +1,91 @@
+// api-diff — flag API endpoints without corresponding doc coverage (#A23).
+
+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"]);
+const DOC_EXTENSIONS = new Set([".md", ".yaml", ".yml"]);
+
+const ROUTE_REGEX = /\b(?:app|router|server|fastify|hono)\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/g;
+const NEXT_REGEX = /^export\s+async\s+function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(/gm;
+
+async function collectEndpoints(rootPath) {
+  const endpoints = new Set();
+  for await (const { fullPath, relativePath } of walkRepoFiles({
+    rootPath,
+    extensions: CODE_EXTENSIONS,
+  })) {
+    const rel = toPosix(relativePath);
+    if (/(^|\/)(tests?|__tests__|specs?)\//.test(rel)) continue;
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let m;
+    while ((m = ROUTE_REGEX.exec(content)) !== null) {
+      endpoints.add(`${m[1].toUpperCase()} ${m[2]}`);
+    }
+    ROUTE_REGEX.lastIndex = 0;
+    if (/\/api\//.test(rel)) {
+      while ((m = NEXT_REGEX.exec(content)) !== null) {
+        const route = rel.replace(/^.*\/api\//, "/api/").replace(/\/route\.(ts|js)x?$/, "");
+        endpoints.add(`${m[1]} ${route}`);
+      }
+      NEXT_REGEX.lastIndex = 0;
+    }
+  }
+  return endpoints;
+}
+
+async function collectDocumentedEndpoints(rootPath) {
+  const documented = new Set();
+  for await (const { fullPath, relativePath } of walkRepoFiles({
+    rootPath,
+    extensions: DOC_EXTENSIONS,
+  })) {
+    const rel = toPosix(relativePath);
+    if (!/(^|\/)(docs?|api|spec)\//i.test(rel) && !/API\.md$/.test(rel) && !/openapi|swagger/i.test(rel)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const regex = /\b(GET|POST|PUT|PATCH|DELETE)\s+(\/[^\s`'"]*)/g;
+    let m;
+    while ((m = regex.exec(content)) !== null) {
+      documented.add(`${m[1]} ${m[2]}`);
+    }
+  }
+  return documented;
+}
+
+export async function runApiDiff({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const endpoints = await collectEndpoints(resolvedRoot);
+  const documented = await collectDocumentedEndpoints(resolvedRoot);
+  const findings = [];
+  for (const endpoint of endpoints) {
+    if (documented.has(endpoint)) continue;
+    findings.push(
+      createFinding({
+        tool: "api-diff",
+        kind: "documentation.undocumented-endpoint",
+        severity: "P3",
+        file: "",
+        line: 0,
+        evidence: `${endpoint} — no matching entry found in docs/, openapi*, swagger*, API.md`,
+        rootCause: "Endpoints that ship without docs can't be discovered by downstream clients and bit-rot silently.",
+        recommendedFix: "Add the endpoint to openapi.yaml / API.md / docs/api.md with request + response shape and auth requirements.",
+        confidence: 0.45,
+      })
+    );
+  }
+  return findings;
+}