sentinelayer-cli 0.8.0 → 0.8.1

package/src/agents/code-quality/tools/dep-graph.js

@@ -0,0 +1,196 @@
+// dep-graph — extract a module-level import graph from JS/TS sources (#A16).
+//
+// We use @babel/parser (already a dep) to collect every ImportDeclaration /
+// dynamic import / require call per file. Local imports (starting with
+// '.' or the repo's src root) are resolved against the filesystem so we
+// get a directed graph with fully-qualified node keys. External packages
+// are kept under a synthetic 'npm:<pkg>' / 'npm:@scope/pkg' key so the
+// graph isn't polluted by node_modules paths but still captures the fan-out.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "@babel/parser";
+
+import { toPosix, walkRepoFiles } from "./base.js";
+
+const DEFAULT_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+
+function pickBabelPlugins(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 collectSpecifiers(astRoot) {
+  const specifiers = new Set();
+  const queue = [astRoot];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+    if (Array.isArray(node)) {
+      for (const value of node) {
+        queue.push(value);
+      }
+      continue;
+    }
+    if (
+      (node.type === "ImportDeclaration" ||
+        node.type === "ExportAllDeclaration" ||
+        node.type === "ExportNamedDeclaration") &&
+      node.source &&
+      typeof node.source.value === "string"
+    ) {
+      specifiers.add(node.source.value);
+    }
+    if (
+      node.type === "CallExpression" &&
+      node.callee &&
+      node.callee.type === "Identifier" &&
+      node.callee.name === "require" &&
+      Array.isArray(node.arguments) &&
+      node.arguments[0]?.type === "StringLiteral"
+    ) {
+      specifiers.add(node.arguments[0].value);
+    }
+    if (
+      node.type === "CallExpression" &&
+      node.callee?.type === "Import" &&
+      Array.isArray(node.arguments) &&
+      node.arguments[0]?.type === "StringLiteral"
+    ) {
+      specifiers.add(node.arguments[0].value);
+    }
+    for (const value of Object.values(node)) {
+      if (value && typeof value === "object") {
+        queue.push(value);
+      }
+    }
+  }
+  return Array.from(specifiers);
+}
+
+function normalizeImportSpec(spec, sourceRelativePath) {
+  const raw = String(spec || "").trim();
+  if (!raw) {
+    return null;
+  }
+  if (raw.startsWith(".")) {
+    const sourceDir = path.posix.dirname(sourceRelativePath);
+    const resolved = path.posix.normalize(`${sourceDir}/${raw}`);
+    return { kind: "local", key: resolved };
+  }
+  if (raw.startsWith("/")) {
+    return { kind: "absolute", key: raw };
+  }
+  const parts = raw.split("/");
+  if (parts[0].startsWith("@") && parts.length > 1) {
+    return { kind: "npm", key: `npm:${parts[0]}/${parts[1]}` };
+  }
+  return { kind: "npm", key: `npm:${parts[0]}` };
+}
+
+export async function buildDependencyGraph({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: DEFAULT_EXTENSIONS });
+
+  const graph = {};
+  for await (const { fullPath, relativePath } of iterator) {
+    const relPos = toPosix(relativePath);
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let ast;
+    try {
+      ast = parse(content, {
+        sourceType: "unambiguous",
+        errorRecovery: true,
+        plugins: pickBabelPlugins(fullPath),
+      });
+    } catch {
+      continue;
+    }
+    const specifiers = collectSpecifiers(ast);
+    const edges = new Set();
+    for (const spec of specifiers) {
+      const normalized = normalizeImportSpec(spec, relPos);
+      if (!normalized) {
+        continue;
+      }
+      edges.add(normalized.key);
+    }
+    graph[relPos] = Array.from(edges).sort();
+  }
+  return graph;
+}
+
+// Thin wrapper so the tool conforms to the persona-tool contract (returns
+// Finding[]). The graph itself is returned on the single "report" finding's
+// rootCause payload — the LLM layer can reach in for detail.
+export async function runDepGraph({ rootPath, files = null } = {}) {
+  const graph = await buildDependencyGraph({ rootPath, files });
+  const moduleCount = Object.keys(graph).length;
+  const edgeCount = Object.values(graph).reduce(
+    (acc, list) => acc + list.length,
+    0
+  );
+  const densestFile = Object.entries(graph).reduce(
+    (acc, [file, edges]) => (edges.length > acc.edges ? { file, edges: edges.length } : acc),
+    { file: "", edges: 0 }
+  );
+  return [
+    {
+      persona: "code-quality",
+      tool: "dep-graph",
+      kind: "code-quality.dep-graph-report",
+      severity: "P3",
+      file: densestFile.file || "",
+      line: 0,
+      evidence: `modules=${moduleCount}, edges=${edgeCount}, densest=${densestFile.file || "n/a"} (${densestFile.edges} imports)`,
+      rootCause: "Module-level dependency graph summary",
+      recommendedFix:
+        "Inspect the densest modules first. Consider splitting or introducing an indirection layer if fan-out is > 20.",
+      confidence: 0.9,
+      graph,
+    },
+  ];
+}
+
+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 { collectSpecifiers, normalizeImportSpec };

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

@@ -0,0 +1,89 @@
+// Ethan (code-quality persona) domain-tool registry (#A16).
+
+import { runComplexityMeasure } from "./complexity-measure.js";
+import { runCouplingAnalysis } from "./coupling-analysis.js";
+import { runCycleDetect } from "./cycle-detect.js";
+import { runDepGraph } from "./dep-graph.js";
+
+export const CODE_QUALITY_TOOLS = Object.freeze({
+  "dep-graph": {
+    id: "dep-graph",
+    description:
+      "Build the module-level import graph (local modules + npm: synthetic nodes for external packages). Returns a summary Finding; the graph is available on the finding's `graph` field.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runDepGraph,
+  },
+  "coupling-analysis": {
+    id: "coupling-analysis",
+    description:
+      "Flag files with high fan-out (many imports) or high fan-in (many importers). Uses the dep-graph under the hood.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runCouplingAnalysis,
+  },
+  "cycle-detect": {
+    id: "cycle-detect",
+    description:
+      "Find import cycles between local modules (npm: and absolute nodes are stripped before SCC).",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runCycleDetect,
+  },
+  "complexity-measure": {
+    id: "complexity-measure",
+    description:
+      "Estimate per-function cyclomatic complexity via AST branching-node count. Defaults: P2 at CC ≥ 15, P1 at CC ≥ 30.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        p1Threshold: { type: "number" },
+        p2Threshold: { type: "number" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runComplexityMeasure,
+  },
+});
+
+export const CODE_QUALITY_TOOL_IDS = Object.freeze(Object.keys(CODE_QUALITY_TOOLS));
+
+export async function dispatchCodeQualityTool(toolId, args = {}) {
+  const tool = CODE_QUALITY_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown code-quality tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllCodeQualityTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of CODE_QUALITY_TOOL_IDS) {
+    const out = await dispatchCodeQualityTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export {
+  runComplexityMeasure,
+  runCouplingAnalysis,
+  runCycleDetect,
+  runDepGraph,
+};

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

@@ -0,0 +1,12 @@
+// Linh (data-layer persona) — barrel export (#A17).
+
+export {
+  DATA_LAYER_TOOLS,
+  DATA_LAYER_TOOL_IDS,
+  dispatchDataLayerTool,
+  runAllDataLayerTools,
+  runIndexAudit,
+  runMigrationScan,
+  runQueryExplain,
+  runTenancyScan,
+} from "./tools/index.js";

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

@@ -0,0 +1,181 @@
+// Shared helpers for Linh's (data-layer) domain tools (#A17).
+
+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 = "data-layer",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "data-layer",
+    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/data-layer/tools/index-audit.js

@@ -0,0 +1,165 @@
+// index-audit — flag WHERE / JOIN columns that probably lack indexes (#A17).
+//
+// Without DB access we can't know what's actually indexed, but we can
+// cross-reference source-level migrations:
+//   - Find every `WHERE col = :x` and `JOIN t ON a.col = b.col` in source.
+//   - Collect every `CREATE INDEX` / `@Index` / `db_index=True` declaration
+//     in the repo.
+//   - Flag WHERE / JOIN columns that don't appear in an index declaration.
+//
+// Conservative: we only consider columns that appear under standard
+// migration directories so we don't cross-pollute with JS variable names
+// that coincidentally look SQL-ish.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+import { isMigrationPath } from "./migration-scan.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rb",
+  ".sql",
+]);
+
+function collectIndexDecls(content) {
+  const declared = new Set();
+  const patterns = [
+    /CREATE\s+(?:UNIQUE\s+)?INDEX\s+[`"]?\w*[`"]?\s+ON\s+[`"]?\w+[`"]?\s*\(\s*[`"]?(\w+)[`"]?/gi,
+    /@Index\s*\(\s*[`"]?(\w+)[`"]?/g, // TypeORM
+    /db_index\s*=\s*True/g, // Django: presence implies indexed
+    /index=True/g, // SQLAlchemy: per-column index
+    /\.index\s*\(\s*['"`](\w+)['"`]/g, // Knex migrations
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const name = match[1];
+      if (name) {
+        declared.add(name);
+      }
+    }
+  }
+  return declared;
+}
+
+function collectLookupColumns(content) {
+  const columns = new Map(); // col -> first line
+  const whereRegex = /WHERE\s+(?:[\w.`"]+\.)?[`"]?(\w+)[`"]?\s*(?:=|IN|LIKE|>|<|>=|<=|BETWEEN)/gi;
+  const joinRegex = /JOIN\s+[\w.]+\s+(?:AS\s+\w+\s+)?ON\s+[\w.`"]+\.[`"]?(\w+)[`"]?\s*=/gi;
+  const knexRegex = /\.(?:where|orWhere|join)\(\s*['"`](\w+)['"`]/g;
+  const lines = content.split(/\r?\n/);
+  for (const regex of [whereRegex, joinRegex, knexRegex]) {
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const name = match[1];
+      if (!name) {
+        continue;
+      }
+      const lineIndex = content.slice(0, match.index).split(/\r?\n/).length;
+      if (!columns.has(name)) {
+        columns.set(name, { line: lineIndex, lineContent: (lines[lineIndex - 1] || "").trim() });
+      }
+    }
+  }
+  return columns;
+}
+
+export async function runIndexAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const declared = new Set();
+  // Pass 1: collect index declarations from migrations + schema files.
+  for await (const { fullPath, relativePath } of walkRepoFiles({
+    rootPath: resolvedRoot,
+    extensions: CODE_EXTENSIONS,
+  })) {
+    const isMigration = isMigrationPath(relativePath);
+    const isOrmModel = /\/models?\/|schema\.(?:prisma|ts|js|py)$/i.test(
+      toPosix(relativePath)
+    );
+    if (!isMigration && !isOrmModel) {
+      continue;
+    }
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const name of collectIndexDecls(content)) {
+      declared.add(name);
+    }
+  }
+
+  // Pass 2: collect lookup columns from application code.
+  const findings = [];
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const reported = new Set();
+  for await (const { fullPath, relativePath } of iterator) {
+    const relPos = toPosix(relativePath);
+    if (isMigrationPath(relPos)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const lookups = collectLookupColumns(content);
+    for (const [name, meta] of lookups) {
+      if (declared.has(name)) {
+        continue;
+      }
+      const key = `${relPos}#${name}`;
+      if (reported.has(key)) {
+        continue;
+      }
+      reported.add(key);
+      findings.push(
+        createFinding({
+          tool: "index-audit",
+          kind: "data.missing-index",
+          severity: "P2",
+          file: relPos,
+          line: meta.line,
+          evidence: meta.lineContent,
+          rootCause: `Column '${name}' is used in a WHERE / JOIN predicate but no matching CREATE INDEX / @Index / db_index=True declaration was found in migrations or models.`,
+          recommendedFix: `Add an index on ${name} in the next migration. Test with EXPLAIN on production-like data before merging.`,
+          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 };
+  }
+}
+
+export { collectIndexDecls, collectLookupColumns };