@agent-native/core 0.96.0 → 0.98.0

package/corpus/core/src/guards/db-tool-scoping.ts

@@ -0,0 +1,129 @@
+/**
+ * scanDbToolScoping — ported from `scripts/guard-db-tool-scoping.mjs`.
+ *
+ * The agent's raw DB tools (`db-query`, `db-exec`, `db-patch`) can only
+ * safely expose tables with an explicit tenant scope (`owner_email` and/or
+ * `org_id`) or a documented, reviewed exception. This guard keeps schema
+ * drift visible: any table without raw-DB scope must either add
+ * `owner_email`/`org_id`, or be added to the denylist with a
+ * reviewer-readable reason.
+ *
+ * Conditional guard — per report 005's V1 guard set table: the original
+ * walks every `templates/*\/server/db/schema.ts` and keys its denylist
+ * `"<template>:<table>"`. A generated app has exactly one
+ * `server/db/schema.ts` (confirmed convention), so this port scans that
+ * single file and uses bare `"<table>"` denylist keys. The denylist itself
+ * comes from `agent-native.json`'s `doctor.dbToolScopingDenylist` (see
+ * `../cli/doctor.ts`) — empty by default; app authors add entries with the
+ * same reviewer-readable-reason convention as the original constant.
+ *
+ * Not ported: the original also resolves `export * from
+ * "@agent-native/<pkg>/schema"` re-exports back to that package's
+ * `packages/<pkg>/src/schema/*.ts` monorepo source, so template schemas
+ * that re-export scheduling/dispatch tables get scanned too. In a
+ * generated app those packages are compiled `node_modules` output (no
+ * `.ts` source to brace-parse), and report 005's parameterization note
+ * doesn't cover that case, so re-export resolution is intentionally
+ * dropped for app mode: a re-exported table from an `@agent-native/*`
+ * package is not scanned here (false-negative, not false-positive) — see
+ * the plan's STOP-condition guidance ("report rather than invent new
+ * detection logic").
+ */
+
+import { readFileSafe, relPosix, walk } from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+export interface DbToolScopingOptions extends GuardScanOptions {
+  /** Table name -> reviewer-readable reason. Default `{}`. */
+  denylist?: Record<string, string>;
+}
+
+interface TableCall {
+  exportName: string;
+  sqlName: string;
+  body: string;
+}
+
+function extractTableCalls(contents: string): TableCall[] {
+  const out: TableCall[] = [];
+  const headerRegex =
+    /export\s+const\s+([a-zA-Z_$][\w$]*)\s*=\s*(?:[a-zA-Z_$][\w$]*Table|table)\s*\(\s*"([^"]+)"\s*,\s*\{/gm;
+  let match: RegExpExecArray | null;
+  while ((match = headerRegex.exec(contents)) !== null) {
+    const exportName = match[1];
+    const sqlName = match[2];
+    const start = headerRegex.lastIndex - 1;
+    let depth = 0;
+    let inStr: string | null = null;
+    let bodyEnd = -1;
+    for (let i = start; i < contents.length; i++) {
+      const c = contents[i];
+      const prev = contents[i - 1];
+      if (inStr) {
+        if (c === inStr && prev !== "\\") inStr = null;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === "`") {
+        inStr = c;
+        continue;
+      }
+      if (c === "{") depth++;
+      else if (c === "}") {
+        depth--;
+        if (depth === 0) {
+          bodyEnd = i;
+          break;
+        }
+      }
+    }
+    if (bodyEnd === -1) continue;
+    out.push({ exportName, sqlName, body: contents.slice(start + 1, bodyEnd) });
+  }
+  return out;
+}
+
+function hasRawDbScope(tableBody: string): boolean {
+  return (
+    /\.\.\.ownableColumns\s*\(/.test(tableBody) ||
+    /\b[\w$]+\s*:\s*text\s*\(\s*["']owner_email["']/.test(tableBody) ||
+    /\b[\w$]+\s*:\s*text\s*\(\s*["']org_id["']/.test(tableBody)
+  );
+}
+
+export function scanDbToolScoping(options: DbToolScopingOptions): GuardResult {
+  const { root, denylist = {} } = options;
+  const findings: GuardFinding[] = [];
+  const seenAllowed = new Set<string>();
+
+  for (const file of walk(root)) {
+    if (!file.endsWith("/server/db/schema.ts")) continue;
+    const contents = readFileSafe(file);
+    if (contents === null) continue;
+    const rel = relPosix(root, file);
+    const tables = extractTableCalls(contents);
+    for (const table of tables) {
+      if (hasRawDbScope(table.body)) continue;
+      if (Object.hasOwn(denylist, table.sqlName)) {
+        seenAllowed.add(table.sqlName);
+        continue;
+      }
+      findings.push({
+        file: rel,
+        line: 1,
+        message: `Table "${table.sqlName}" (export ${table.exportName}) has no owner_email/org_id scope and is not on the doctor.dbToolScopingDenylist — add tenant scope, or add it to agent-native.json's "doctor.dbToolScopingDenylist" with a reason.`,
+      });
+    }
+  }
+
+  for (const key of Object.keys(denylist)) {
+    if (!seenAllowed.has(key)) {
+      findings.push({
+        file: "agent-native.json",
+        line: 1,
+        message: `Stale doctor.dbToolScopingDenylist entry "${key}" — no matching table found in server/db/schema.ts. Remove it.`,
+      });
+    }
+  }
+
+  return { name: "db-tool-scoping", findings };
+}

package/corpus/core/src/guards/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `agent-native doctor`'s guard functions — the source-code safety
+ * invariants ported from this monorepo's `scripts/guard-*.mjs` CI guards
+ * (see report `advisor-plans/reports/005-doctor-design.md` for the
+ * classification and per-guard parameterization). Each guard is a pure,
+ * synchronous function that scans an app root and returns a `GuardResult`.
+ *
+ * `../cli/doctor.ts` is the only in-package caller; this module is also
+ * published under the `./guards` export subpath for advanced/CI use
+ * outside the CLI.
+ */
+
+export { scanDbToolScoping } from "./db-tool-scoping.js";
+export type { DbToolScopingOptions } from "./db-tool-scoping.js";
+export { scanDrizzlePush } from "./no-drizzle-push.js";
+export { scanEnvCredentials } from "./no-env-credentials.js";
+export { scanEnvMutation } from "./no-env-mutation.js";
+export { scanLocalhostFallback } from "./no-localhost-fallback.js";
+export type { LocalhostFallbackOptions } from "./no-localhost-fallback.js";
+export { scanUnscopedCredentials } from "./no-unscoped-credentials.js";
+export { scanUnscopedQueries } from "./no-unscoped-queries.js";
+export type { UnscopedQueriesOptions } from "./no-unscoped-queries.js";
+export type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";

package/corpus/core/src/guards/no-drizzle-push.ts

@@ -0,0 +1,116 @@
+/**
+ * scanDrizzlePush — ported from `scripts/guard-no-drizzle-push.mjs`.
+ *
+ * Refuse to let `drizzle-kit push` (or `drizzle push`) get wired into any
+ * build/deploy path (`netlify.toml`, or a `package.json` build/deploy
+ * script). Generic guard — no monorepo-specific path assumption in the
+ * original, ported as-is.
+ *
+ * Standalone `db:push` / `db:push:*` npm scripts are intentionally NOT
+ * flagged — those are explicit, human-invoked commands, not build hooks.
+ */
+
+import {
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+const DANGEROUS_SCRIPT_HOOKS = new Set([
+  "build",
+  "prebuild",
+  "postbuild",
+  "install",
+  "preinstall",
+  "postinstall",
+  "deploy",
+  "predeploy",
+  "postdeploy",
+  "start",
+  "prestart",
+  "poststart",
+  "ci",
+  "release",
+  "prerelease",
+  "postrelease",
+]);
+
+const PATTERNS = [/\bdrizzle-kit\s+push\b/, /\bdrizzle\s+push\b/];
+
+function matchesForbidden(str: unknown): str is string {
+  if (!str || typeof str !== "string") return false;
+  return PATTERNS.some((p) => p.test(str));
+}
+
+interface PackageJsonLike {
+  scripts?: Record<string, unknown>;
+}
+
+export function scanDrizzlePush(options: GuardScanOptions): GuardResult {
+  const { root } = options;
+  const findings: GuardFinding[] = [];
+
+  for (const file of walk(root)) {
+    const base = file.split("/").pop() ?? file;
+    if (base === "netlify.toml") {
+      scanNetlifyToml(root, file, findings);
+    } else if (base === "package.json") {
+      scanPackageJson(root, file, findings);
+    }
+  }
+
+  return { name: "no-drizzle-push", findings };
+}
+
+function scanNetlifyToml(
+  root: string,
+  file: string,
+  findings: GuardFinding[],
+): void {
+  const contents = readFileSafe(file);
+  if (contents === null || !matchesForbidden(contents)) return;
+  const lines = contents.split("\n");
+  const rel = relPosix(root, file);
+  for (let i = 0; i < lines.length; i++) {
+    if (matchesForbidden(lines[i])) {
+      findings.push({
+        file: rel,
+        line: i + 1,
+        message: `forbidden \`drizzle-kit push\` in netlify.toml: ${lines[i].trim()}`,
+      });
+    }
+  }
+}
+
+function scanPackageJson(
+  root: string,
+  file: string,
+  findings: GuardFinding[],
+): void {
+  const contents = readFileSafe(file);
+  if (contents === null) return;
+  let json: PackageJsonLike;
+  try {
+    json = JSON.parse(contents) as PackageJsonLike;
+  } catch {
+    return;
+  }
+  const scripts = json.scripts;
+  if (!scripts || typeof scripts !== "object") return;
+  const rel = relPosix(root, file);
+  for (const [name, cmd] of Object.entries(scripts)) {
+    if (!DANGEROUS_SCRIPT_HOOKS.has(name)) continue;
+    if (matchesForbidden(cmd)) {
+      // Locate the line for a readable finding; fall back to line 1.
+      const idx = contents.indexOf(`"${name}"`);
+      const line = idx >= 0 ? lineColForOffset(contents, idx).line : 1;
+      findings.push({
+        file: rel,
+        line,
+        message: `forbidden \`drizzle-kit push\` in scripts.${name}: ${String(cmd)}`,
+      });
+    }
+  }
+}

package/corpus/core/src/guards/no-env-credentials.ts

@@ -0,0 +1,229 @@
+/**
+ * scanEnvCredentials — ported from `scripts/guard-no-env-credentials.mjs`.
+ *
+ * User credentials are per-user (or per-org) data. They MUST live in SQL,
+ * scoped by `userEmail` / `orgId`, never in `process.env` — a deployment's
+ * env vars are shared by every signed-in user. This guard flags any
+ * `process.env.<KEY>` / `process.env["KEY"]` read whose key is not on the
+ * deploy-level allowlist (`DATABASE_URL`, `BETTER_AUTH_SECRET`, etc.), plus
+ * any dynamic `process.env[key]` read (the key is only known at runtime, so
+ * it can never be allowlisted safely).
+ *
+ * Conditional guard — per report 005's V1 guard set table, this is "the big
+ * one": the original only scans a curated set of monorepo subtrees
+ * (`packages/core/src/{credentials,secrets,vault,agent}/`, template
+ * credential libs/routes) via `FORBIDDEN_PATH_PREDICATES` — none of which
+ * exist in a generated app, so nothing would ever be scanned. This port
+ * replaces that default-allow-outside-a-curated-subtree behavior with
+ * default-deny across the whole app source tree: every `process.env.<KEY>`
+ * read anywhere in app source must be on the deploy-var allowlist (kept
+ * verbatim) or carry the opt-out marker. `HIGH_RISK_ENV_KEY_ALLOWLIST`,
+ * `HIGH_RISK_PROCESS_ENV_ALLOWLIST`, and `HIGH_RISK_ENV_VARS_WRITE_ALLOWLIST`
+ * — the three monorepo-file-keyed exception maps for specific template
+ * platform-adapter files — are dropped entirely per the report; with
+ * default-deny scanning already covering every `process.env` read
+ * everywhere, the narrower `env-config.ts`/`core-routes.ts`-specific
+ * registration checks those maps supported become redundant (any
+ * high-risk key would already be caught by the general scan) and are
+ * dropped along with them. The per-line `// guard:allow-env-credential`
+ * marker remains the only escape hatch.
+ *
+ * Opt-out (same line, or the line immediately above):
+ *   process.env.SOMETHING // guard:allow-env-credential — short reason
+ */
+
+import {
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+const ALLOWLIST_EXACT = new Set([
+  "DATABASE_URL",
+  "DATABASE_AUTH_TOKEN",
+  "NODE_ENV",
+  "CI",
+  "DEBUG",
+  "NETLIFY",
+  "VERCEL",
+  "RENDER",
+  "FLY_APP_NAME",
+  "K_SERVICE",
+  "AWS_LAMBDA_FUNCTION_NAME",
+  "BETTER_AUTH_SECRET",
+  "BETTER_AUTH_URL",
+  "NOTION_CLIENT_ID",
+  "NOTION_CLIENT_SECRET",
+  "NOTION_STATE_SECRET",
+  "GOOGLE_SIGN_IN_CLIENT_ID",
+  "GOOGLE_SIGN_IN_CLIENT_SECRET",
+  "AUTH_SECRET",
+  "A2A_SECRET",
+  "ACCESS_TOKEN",
+  "PORT",
+  "HOST",
+  "SECRETS_ENCRYPTION_KEY",
+]);
+
+const ALLOWLIST_PREFIX = [
+  "npm_",
+  "AGENT_NATIVE_",
+  "AGENT_",
+  "NETLIFY_",
+  "VERCEL_",
+  "CF_",
+];
+
+/** Dev-only paths where ANTHROPIC_API_KEY etc. may legitimately be read
+ * from env (local dev tooling, scripts, tests). Portable subset of the
+ * original — the monorepo-only `packages/core/src/dev` predicate is
+ * dropped (see report 005's V1 guard set table). */
+const DEV_ONLY_PATH_PATTERNS = [
+  /\.spec\.[tj]sx?$/,
+  /\.test\.[tj]sx?$/,
+  /^scripts\//,
+];
+
+const DEV_ONLY_KEYS = new Set(["ANTHROPIC_API_KEY"]);
+
+const OPT_OUT_MARKER = /\/\/\s*guard:allow-env-credential\b[^\n]*/;
+const OPT_OUT_REQUIRES_REASON = /\/\/\s*guard:allow-env-credential\s*[—-]\s*\S/;
+
+const ENV_READ_REGEX =
+  /process\.env(?:\.([A-Z][A-Z0-9_]*)|\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\])/g;
+
+const ENV_DYNAMIC_READ_REGEX =
+  /process\.env(?:\?\.)?\s*\[\s*(?!["'])([^\]\n]+?)\s*\]/g;
+
+function isAllowlistedKey(key: string): boolean {
+  if (ALLOWLIST_EXACT.has(key)) return true;
+  return ALLOWLIST_PREFIX.some((prefix) => key.startsWith(prefix));
+}
+
+function isDevOnlyPath(rel: string): boolean {
+  return DEV_ONLY_PATH_PATTERNS.some((re) => re.test(rel));
+}
+
+function hasOptOutOnLine(lines: string[], lineIdx: number): boolean {
+  const cur = lines[lineIdx] ?? "";
+  if (OPT_OUT_MARKER.test(cur)) return true;
+  const prev = lines[lineIdx - 1] ?? "";
+  if (/^\s*\/\//.test(prev) && OPT_OUT_MARKER.test(prev)) return true;
+  return false;
+}
+
+function optOutOnLineIsValid(
+  lines: string[],
+  lineIdx: number,
+  key: string,
+  rel: string,
+): { ok: boolean; why?: string } {
+  const cur = lines[lineIdx] ?? "";
+  const prev = lines[lineIdx - 1] ?? "";
+  const candidate = OPT_OUT_REQUIRES_REASON.test(cur)
+    ? cur
+    : OPT_OUT_REQUIRES_REASON.test(prev)
+      ? prev
+      : null;
+  if (!candidate) return { ok: false, why: "missing or empty reason" };
+
+  if (/dev-only\b/i.test(candidate)) {
+    if (!DEV_ONLY_KEYS.has(key)) {
+      return {
+        ok: false,
+        why: `key "${key}" is not in the dev-only credential allowlist`,
+      };
+    }
+    if (!isDevOnlyPath(rel)) {
+      return {
+        ok: false,
+        why: "dev-only opt-out used outside dev / scripts / test paths",
+      };
+    }
+  }
+  return { ok: true };
+}
+
+export function scanEnvCredentials(options: GuardScanOptions): GuardResult {
+  const { root } = options;
+  const findings: GuardFinding[] = [];
+
+  for (const file of walk(root)) {
+    if (!/\.(ts|tsx|mts|cts|js|mjs|cjs)$/.test(file)) continue;
+    if (file.endsWith(".d.ts")) continue;
+    const rel = relPosix(root, file);
+
+    const contents = readFileSafe(file);
+    if (contents === null || !contents.includes("process.env")) continue;
+
+    const lines = contents.split("\n");
+
+    ENV_READ_REGEX.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = ENV_READ_REGEX.exec(contents)) !== null) {
+      const key = m[1] ?? m[2];
+      if (!key) continue;
+      const { line } = lineColForOffset(contents, m.index);
+      const lineIdx = line - 1;
+      const lineText = lines[lineIdx] ?? "";
+      const trimmed = lineText.trimStart();
+      if (
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("//") ||
+        trimmed.startsWith("/*")
+      ) {
+        continue;
+      }
+      if (isAllowlistedKey(key)) continue;
+      if (hasOptOutOnLine(lines, lineIdx)) {
+        const verdict = optOutOnLineIsValid(lines, lineIdx, key, rel);
+        if (verdict.ok) continue;
+        findings.push({
+          file: rel,
+          line,
+          message: `process.env.${key} opt-out invalid: ${verdict.why}`,
+        });
+        continue;
+      }
+      findings.push({
+        file: rel,
+        line,
+        message: `process.env.${key} read — not a deploy-level allowlisted key. User credentials must be read via resolveCredential(key, { userEmail, orgId }), never process.env.`,
+      });
+    }
+
+    ENV_DYNAMIC_READ_REGEX.lastIndex = 0;
+    while ((m = ENV_DYNAMIC_READ_REGEX.exec(contents)) !== null) {
+      const { line } = lineColForOffset(contents, m.index);
+      const lineIdx = line - 1;
+      const lineText = lines[lineIdx] ?? "";
+      const trimmed = lineText.trimStart();
+      if (
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("//") ||
+        trimmed.startsWith("/*")
+      ) {
+        continue;
+      }
+      if (hasOptOutOnLine(lines, lineIdx)) {
+        const verdict = optOutOnLineIsValid(lines, lineIdx, "<dynamic>", rel);
+        if (verdict.ok) continue;
+        findings.push({
+          file: rel,
+          line,
+          message: `process.env[<dynamic>] opt-out invalid: ${verdict.why}`,
+        });
+        continue;
+      }
+      findings.push({
+        file: rel,
+        line,
+        message: `process.env[<dynamic key>] read — dynamic keys can never be allowlisted safely.`,
+      });
+    }
+  }
+
+  return { name: "no-env-credentials", findings };
+}

package/corpus/core/src/guards/no-env-mutation.ts

@@ -0,0 +1,114 @@
+/**
+ * scanEnvMutation — ported from `scripts/guard-no-env-mutation.mjs`.
+ *
+ * Refuse to let production code MUTATE `process.env` (e.g.
+ * `process.env.AGENT_USER_EMAIL = userEmail`). `process.env` is
+ * process-scoped, not request-scoped — on serverless, every warm container
+ * handles many concurrent requests in one Node process, so mutating
+ * `process.env` in a request handler leaks state across requests. Use
+ * `runWithRequestContext` instead.
+ *
+ * Conditional guard — per report 005's V1 guard set table: the original
+ * has 9 `ALLOWED_PATH_PREDICATES`; 4 are monorepo-only
+ * (`packages/core/src/dev`, `templates/*\/test(s)/`, `packages/cli/`,
+ * `packages/create-agent-native/`) and dropped here. The 5 portable ones
+ * (`scripts/**`, `*.spec.*`, `*.test.*`, `/cli/`, `/scaffold/`) are kept
+ * verbatim — they already work unmodified for a generated app.
+ *
+ * Opt-out (same line, or the line immediately above):
+ *   process.env.X = y // guard:allow-env-mutation — short reason
+ */
+
+import {
+  isCommentLine,
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+const ALLOWED_PATH_PREDICATES: Array<(rel: string) => boolean> = [
+  (rel) => /^scripts\//.test(rel),
+  (rel) => /\.spec\.[tj]sx?$/.test(rel),
+  (rel) => /\.test\.[tj]sx?$/.test(rel),
+  (rel) => /\/cli\//.test(rel),
+  (rel) => /\/scaffold\//.test(rel),
+];
+
+const OPT_OUT_MARKER = /\/\/\s*guard:allow-env-mutation\b[^\n]*/;
+const OPT_OUT_REQUIRES_REASON = /\/\/\s*guard:allow-env-mutation\s*[—-]\s*\S/;
+
+const ASSIGN_TAIL = String.raw`(?:\s*(?:=(?!=)|\+=|-=|\*=|/=|\?\?=|\|\|=|&&=))`;
+const MEMBER_FORM = new RegExp(
+  String.raw`process\.env\.[A-Z_][A-Z0-9_]*${ASSIGN_TAIL}`,
+  "g",
+);
+const BRACKET_FORM = new RegExp(
+  String.raw`process\.env\[\s*["'][A-Z_][A-Z0-9_]+["']\s*\]${ASSIGN_TAIL}`,
+  "g",
+);
+const DELETE_MEMBER_FORM = new RegExp(
+  String.raw`\bdelete\s+process\.env\.[A-Z_][A-Z0-9_]*\b`,
+  "g",
+);
+const DELETE_BRACKET_FORM = new RegExp(
+  String.raw`\bdelete\s+process\.env\[\s*["'][A-Z_][A-Z0-9_]+["']\s*\]`,
+  "g",
+);
+
+function isAllowedPath(rel: string): boolean {
+  return ALLOWED_PATH_PREDICATES.some((p) => p(rel));
+}
+
+function hasValidOptOut(lines: string[], lineIdx: number): boolean {
+  const cur = lines[lineIdx] ?? "";
+  if (OPT_OUT_MARKER.test(cur)) {
+    return OPT_OUT_REQUIRES_REASON.test(cur);
+  }
+  const prev = lines[lineIdx - 1] ?? "";
+  if (/^\s*\/\//.test(prev) && OPT_OUT_MARKER.test(prev)) {
+    return OPT_OUT_REQUIRES_REASON.test(prev);
+  }
+  return false;
+}
+
+export function scanEnvMutation(options: GuardScanOptions): GuardResult {
+  const { root } = options;
+  const findings: GuardFinding[] = [];
+
+  for (const file of walk(root)) {
+    if (!/\.(ts|tsx|mts|cts|js|mjs|cjs)$/.test(file)) continue;
+    if (file.endsWith(".d.ts")) continue;
+    const rel = relPosix(root, file);
+    if (isAllowedPath(rel)) continue;
+
+    const contents = readFileSafe(file);
+    if (contents === null || !contents.includes("process.env")) continue;
+
+    const lines = contents.split("\n");
+
+    for (const re of [
+      MEMBER_FORM,
+      BRACKET_FORM,
+      DELETE_MEMBER_FORM,
+      DELETE_BRACKET_FORM,
+    ]) {
+      re.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = re.exec(contents)) !== null) {
+        const { line } = lineColForOffset(contents, m.index);
+        const lineText = lines[line - 1] ?? "";
+        if (isCommentLine(lineText)) continue;
+        if (hasValidOptOut(lines, line - 1)) continue;
+        findings.push({
+          file: rel,
+          line,
+          message: `process.env mutated in production code: ${lineText.trim()}. process.env is process-scoped, not request-scoped — use runWithRequestContext instead.`,
+        });
+      }
+    }
+  }
+
+  return { name: "no-env-mutation", findings };
+}