arkgate 4.8.24 → 4.8.25

package/bin/lib/orphan-modules.mjs

@@ -0,0 +1,251 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/orphanModules.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/orphan-modules.mjs). Zero Node I/O.
+ */
+
+const ARK_ORPHAN_MODULES_SCHEMA_VERSION = '1.0';
+/** Listed files per tier (agent-legible). The totals always carry the full count. */
+export const ORPHAN_LIST_CAP = 20;
+/** List cut when entry points were not recognised (ADR 0037 risk). */
+export const ORPHAN_UNRECOGNISED_LIST_CAP = 5;
+/** Share of governed files listed above which unrecognised entry points are assumed. */
+const UNRECOGNISED_SHARE = 0.25;
+/** A tiny tree with a few listed files is readable as is. */
+const UNRECOGNISED_MIN_FILES = 5;
+const TEST_ONLY_SAMPLE = 5;
+export const ORPHAN_MODULE_NEXT = 'Delete it through the write gate, or add it to .ark/entry-points.json if a framework loads it.';
+export const UNUSED_EXPORTS_COMMAND = 'arkgate-check --doctor --all';
+const CERTAINTY_ORDER = {
+    'no-importer': 0,
+    'maybe-unresolved': 1,
+    'maybe-dynamic': 2,
+};
+function byPath(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Last path segment without its extensions (`a/b/foo.test.ts` → `foo`). */
+export function moduleStem(rel) {
+    const segments = String(rel).replace(/\\/g, '/').split('/');
+    const last = segments[segments.length - 1] ?? '';
+    const dot = last.indexOf('.');
+    return dot > 0 ? last.slice(0, dot) : last;
+}
+function stemsFor(rel) {
+    const stem = moduleStem(rel);
+    if (stem !== 'index')
+        return [stem];
+    const segments = rel.split('/');
+    return segments.length > 1 ? [stem, segments[segments.length - 2] ?? stem] : [stem];
+}
+/** One human line per listed file. Shared by the terminal and the report. */
+export function orphanModuleLine(item) {
+    if (item.certainty === 'maybe-dynamic') {
+        const why = item.evidence[0] ?? 'a dynamic import may load it';
+        return `No static import reaches ${item.path}, but ${why}. It may still be loaded.`;
+    }
+    if (item.certainty === 'maybe-unresolved') {
+        return `Nothing imports ${item.path}, but an import that could not be followed has the same name. It may still be used.`;
+    }
+    return `Nothing imports ${item.path}, and no entry point covers it.`;
+}
+function unrecognisedFlood(listed, governed, frameworks) {
+    return (frameworks.length === 0 &&
+        listed >= UNRECOGNISED_MIN_FILES &&
+        governed > 0 &&
+        listed / governed > UNRECOGNISED_SHARE);
+}
+/**
+ * Tier 1: governed files with zero importers that no entry covers.
+ * Test-only and outside-only files are counted, never listed.
+ */
+export function findOrphanModules(input) {
+    const files = [...input.files];
+    const count = (index) => Number(input.importerCount[index] ?? 0) || 0;
+    let imported = 0;
+    let entries = 0;
+    const testOnly = [];
+    let outsideOnly = 0;
+    const listed = [];
+    for (let index = 0; index < files.length; index += 1) {
+        const path = files[index];
+        if (count(index) > 0) {
+            imported += 1;
+            continue;
+        }
+        if (input.entries.has(path)) {
+            entries += 1;
+            continue;
+        }
+        if ((input.testImporters.get(path) ?? 0) > 0) {
+            testOnly.push(path);
+            continue;
+        }
+        if ((input.outsideImporters.get(path) ?? 0) > 0) {
+            outsideOnly += 1;
+            continue;
+        }
+        const annotations = [...(input.annotations?.get(path) ?? [])];
+        const reach = input.dynamicReach.get(path);
+        if (reach) {
+            listed.push({
+                ruleId: 'ORPHAN_MODULE',
+                path,
+                certainty: 'maybe-dynamic',
+                evidence: [reach, ...annotations],
+            });
+            continue;
+        }
+        if (stemsFor(path).some((stem) => input.unresolvedStems.has(stem))) {
+            listed.push({
+                ruleId: 'ORPHAN_MODULE',
+                path,
+                certainty: 'maybe-unresolved',
+                evidence: ['an import that could not be followed has the same name', ...annotations],
+            });
+            continue;
+        }
+        listed.push({
+            ruleId: 'ORPHAN_MODULE',
+            path,
+            certainty: 'no-importer',
+            evidence: ['no governed file, test or project script imports it', ...annotations],
+        });
+    }
+    listed.sort((left, right) => CERTAINTY_ORDER[left.certainty] - CERTAINTY_ORDER[right.certainty] || byPath(left.path, right.path));
+    testOnly.sort(byPath);
+    const maybeDynamic = listed.filter((item) => item.certainty === 'maybe-dynamic').length;
+    const maybeUnresolved = listed.filter((item) => item.certainty === 'maybe-unresolved').length;
+    const honesty = [...input.partialReasons];
+    const flood = unrecognisedFlood(listed.length, files.length, input.frameworks);
+    if (flood) {
+        honesty.unshift(`${listed.length} of ${files.length} governed files have no importer and no framework was recognised. Entry points were probably not recognised, so the list may be wrong.`);
+    }
+    const partial = honesty.length > 0 || maybeDynamic > 0 || maybeUnresolved > 0;
+    const cap = flood ? ORPHAN_UNRECOGNISED_LIST_CAP : ORPHAN_LIST_CAP;
+    const shown = listed.slice(0, cap);
+    const headline = listed.length === 0
+        ? partial
+            ? 'No file without an importer was found, but some imports could not be followed.'
+            : 'Every governed file has an importer or an entry point.'
+        : flood
+            ? 'Entry points not recognised. The list of files nothing imports may be wrong.'
+            : `${listed.length} governed file${listed.length === 1 ? '' : 's'} nothing imports.`;
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        advisory: true,
+        notAScore: true,
+        status: partial ? 'partial' : 'complete',
+        headline,
+        orphans: shown,
+        truncated: listed.length - shown.length,
+        testOnly: { count: testOnly.length, sample: testOnly.slice(0, TEST_ONLY_SAMPLE) },
+        totals: {
+            governed: files.length,
+            entries,
+            imported,
+            testOnly: testOnly.length,
+            outsideOnly,
+            listed: listed.length,
+            maybeDynamic,
+            maybeUnresolved,
+        },
+        entryEvidence: {
+            bySource: sortedRecord(input.entryEvidence.bySource),
+            unmapped: input.entryEvidence.unmapped,
+        },
+        frameworks: [...input.frameworks].sort(byPath),
+        honesty: [...honesty, ...(input.notes ?? [])],
+        ...(listed.length > 0 ? { next: ORPHAN_MODULE_NEXT } : {}),
+    };
+}
+function sortedRecord(record) {
+    const out = {};
+    for (const key of Object.keys(record).sort(byPath))
+        out[key] = record[key];
+    return out;
+}
+/** Doctor without an importer index (no TypeScript, or a caller without facts). */
+export function unavailableOrphanModules(reason) {
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        advisory: true,
+        notAScore: true,
+        status: 'unavailable',
+        headline: 'Files nothing imports were not checked.',
+        orphans: [],
+        truncated: 0,
+        testOnly: { count: 0, sample: [] },
+        totals: {
+            governed: 0,
+            entries: 0,
+            imported: 0,
+            testOnly: 0,
+            outsideOnly: 0,
+            listed: 0,
+            maybeDynamic: 0,
+            maybeUnresolved: 0,
+        },
+        entryEvidence: { bySource: {}, unmapped: 0 },
+        frameworks: [],
+        honesty: [reason],
+    };
+}
+/** Tier 2 in the compact view: named, not run. */
+export function deferredUnusedExports() {
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        notAScore: true,
+        status: 'deferred',
+        files: [],
+        truncated: 0,
+        totals: { filesChecked: 0, filesSkipped: 0, unusedExports: 0 },
+        honesty: ['Unused exports are listed in the details view only.'],
+        next: UNUSED_EXPORTS_COMMAND,
+    };
+}
+/**
+ * Tier 2: exports no governed file or test imports by name.
+ * Entry files are exempt. A file with no named use at all is tier 1, not here.
+ */
+export function findUnusedExports(input) {
+    const rows = [];
+    let filesChecked = 0;
+    let filesSkipped = 0;
+    const paths = [...input.exportsByFile.keys()].sort(byPath);
+    for (const path of paths) {
+        const exported = input.exportsByFile.get(path);
+        const used = input.namedUse.get(path);
+        if (input.entries.has(path) || used === undefined || used === '*' || exported == null) {
+            filesSkipped += 1;
+            continue;
+        }
+        filesChecked += 1;
+        const unused = [...new Set(exported)].filter((name) => !used.has(name)).sort(byPath);
+        if (unused.length > 0)
+            rows.push({ ruleId: 'UNUSED_EXPORT', path, exports: unused });
+    }
+    const shown = rows.slice(0, ORPHAN_LIST_CAP);
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        notAScore: true,
+        status: input.partialReasons.length > 0 ? 'partial' : 'complete',
+        files: shown,
+        truncated: rows.length - shown.length,
+        totals: {
+            filesChecked,
+            filesSkipped,
+            unusedExports: rows.reduce((sum, row) => sum + row.exports.length, 0),
+        },
+        honesty: [...input.partialReasons],
+    };
+}
+/** One human line per file with unused exports. */
+export function unusedExportLine(row) {
+    const names = row.exports.join(', ');
+    return `${row.path} exports ${names}, and nothing imports ${row.exports.length === 1 ? 'it' : 'them'} by name.`;
+}

package/bin/lib/outside-importers.mjs

@@ -0,0 +1,197 @@
+/**
+ * Importers that live outside the governed graph — Tooling.
+ *
+ * Shared by files nothing imports (ADR 0037), which counts test and outside
+ * importers, and the invariant mutation probe (ADR 0039), which needs the
+ * test files that import a symbol file to pick covering tests. One walk, one
+ * test classifier, one lexical resolver, so the two never disagree on which
+ * test imports what.
+ *
+ * Bounded: at most 5000 non-governed files of 256 KB each, depth 8.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { namedModuleBindings } from './ast-scan.mjs';
+import { probeGoverned } from './entry-points-io.mjs';
+import { readTsconfigAliases, resolveSpecifierToRel } from './import-resolve.mjs';
+import { coverageOptionsFromConfig, matchSimpleGlob } from './invariant-coverage-io.mjs';
+
+export const MAX_EXTERNAL_IMPORTER_FILES = 5000;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_WALK_DEPTH = 8;
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+const TEST_FILE = /\.(?:test|spec)(?:-d)?\.[cm]?[jt]sx?$|(?:^|\/)(?:tests?|__tests__|__mocks__|e2e)\//i;
+/** Data trees and build output: never importers of product source. */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'fixture',
+  'fixtures',
+  '__fixtures__',
+  'testdata',
+  'docs',
+  'documentation',
+]);
+
+export function readSource(absolute) {
+  try {
+    const stat = fs.statSync(absolute);
+    if (!stat.isFile()) return { skip: true };
+    if (stat.size > MAX_FILE_BYTES) return { oversize: true };
+    return { text: fs.readFileSync(absolute, 'utf8') };
+  } catch {
+    return { skip: true };
+  }
+}
+
+export function dirOf(rel) {
+  const at = rel.lastIndexOf('/');
+  return at === -1 ? '' : rel.slice(0, at);
+}
+
+export function stripExt(rel) {
+  return rel.replace(DECLARATION_FILE, '').replace(SOURCE_FILE, '');
+}
+
+/** The default test-path heuristic plus the project's `coverage.testGlobs`. */
+export function testPathMatcher(config) {
+  const testGlobs = coverageOptionsFromConfig(config).testGlobs ?? [];
+  return (rel) => TEST_FILE.test(rel) || testGlobs.some((glob) => matchSimpleGlob(glob, rel));
+}
+
+/** Non-governed project files (tests and other source), sorted, bounded. */
+export function walkExternalSources(root, governed) {
+  const files = [];
+  let capped = 0;
+  const visit = (dirRel, depth) => {
+    if (depth > MAX_WALK_DEPTH) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dirRel ? path.join(root, dirRel) : root, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) visit(rel, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !SOURCE_FILE.test(entry.name) || DECLARATION_FILE.test(entry.name)) continue;
+      if (governed.has(rel)) continue;
+      if (files.length >= MAX_EXTERNAL_IMPORTER_FILES) capped += 1;
+      else files.push(rel);
+    }
+  };
+  visit('', 0);
+  return { files, capped };
+}
+
+/** Module specifiers of a file. With bindings, named imports keep their names. */
+export function fileImports(ts, rel, text, withBindings) {
+  const imports = [];
+  // Static declarations per specifier. preProcessFile also lists dynamic
+  // import() / require() sites: any occurrence past the static ones uses the
+  // whole module, so it counts as '*'.
+  const statics = new Map();
+  if (withBindings) {
+    const sourceFile = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, false);
+    for (const statement of sourceFile.statements) {
+      const specifier = statement.moduleSpecifier;
+      if (!specifier || !ts.isStringLiteralLike(specifier)) continue;
+      if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement)) continue;
+      imports.push({ specifier: specifier.text, names: namedModuleBindings(ts, statement) ?? '*' });
+      statics.set(specifier.text, (statics.get(specifier.text) ?? 0) + 1);
+    }
+  }
+  const pre = ts.preProcessFile(text, true, true);
+  for (const item of [...pre.importedFiles, ...pre.referencedFiles]) {
+    const left = statics.get(item.fileName) ?? 0;
+    if (left > 0) statics.set(item.fileName, left - 1);
+    else imports.push({ specifier: item.fileName, names: '*' });
+  }
+  return imports;
+}
+
+/**
+ * Relative and tsconfig-alias specifiers → a governed file (same lexical
+ * resolver as the flat-parent graph and the write hook). Bare packages are
+ * never project files.
+ */
+export function createResolver(ts, root, governed) {
+  const aliases = readTsconfigAliases(ts, root);
+  const memo = new Map();
+  return (specifier, fromRel) => {
+    const key = `${dirOf(fromRel)}\0${specifier}`;
+    if (memo.has(key)) return memo.get(key);
+    let hit = null;
+    try {
+      const rel = resolveSpecifierToRel(specifier, fromRel, root, aliases);
+      hit = rel ? (governed.has(rel) ? rel : probeGoverned(stripExt(rel), governed)) : null;
+    } catch {
+      hit = null;
+    }
+    memo.set(key, hit);
+    return hit;
+  };
+}
+
+/** Governed files a barrel re-exports from (`export … from`), resolved. */
+function reExportTargets(ts, root, rel, resolve) {
+  const read = readSource(path.join(root, rel));
+  if (read.text == null) return [];
+  const sourceFile = ts.createSourceFile(rel, read.text, ts.ScriptTarget.Latest, false);
+  const out = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExportDeclaration(statement)) continue;
+    const specifier = statement.moduleSpecifier;
+    if (!specifier || !ts.isStringLiteralLike(specifier)) continue;
+    const target = resolve(specifier.text, rel);
+    if (target) out.push(target);
+  }
+  return out;
+}
+
+/**
+ * Test files that import each target directly, or through one re-exporting
+ * barrel. Same walk, test classifier and resolver as the files-nothing-imports
+ * pass. Returns target → sorted test paths (targets nothing imports map to []).
+ *
+ * @param {{ root: string, ts: object, config?: object, governed: Set<string>, targets: string[] }} input
+ * @returns {{ byTarget: Map<string, string[]>, capped: number }}
+ */
+export function testImportersOf({ root, ts, config, governed, targets }) {
+  const byTarget = new Map(targets.map((target) => [target, new Set()]));
+  if (!ts || typeof ts.preProcessFile !== 'function' || targets.length === 0) {
+    return { byTarget: new Map(targets.map((target) => [target, []])), capped: 0 };
+  }
+  const isTest = testPathMatcher(config);
+  const resolve = createResolver(ts, root, governed);
+  const barrels = new Map();
+  const { files, capped } = walkExternalSources(root, governed);
+  for (const rel of files) {
+    if (!isTest(rel)) continue;
+    const read = readSource(path.join(root, rel));
+    if (read.text == null) continue;
+    for (const { specifier } of fileImports(ts, rel, read.text, false)) {
+      const hit = resolve(specifier, rel);
+      if (!hit) continue;
+      if (byTarget.has(hit)) {
+        byTarget.get(hit).add(rel);
+        continue;
+      }
+      if (!barrels.has(hit)) barrels.set(hit, reExportTargets(ts, root, hit, resolve));
+      for (const target of barrels.get(hit)) byTarget.get(target)?.add(rel);
+    }
+  }
+  return {
+    byTarget: new Map([...byTarget].map(([target, tests]) => [target, [...tests].sort()])),
+    capped,
+  };
+}

package/bin/lib/package-manager.mjs

@@ -88,7 +88,7 @@ export function execRunner(root) {
 }
 
 /** The exact arkgate version that ships this CLI (the package.json next to bin/). */
-export function shippedArkgateVersion() {
+function shippedArkgateVersion() {
   try {
     const pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
     return typeof pkg.version === 'string' && pkg.version ? pkg.version : null;
@@ -114,7 +114,7 @@ export function arkgateIsProjectDependency(root) {
 }
 
 /** `arkgate@<exact shipped version>` — the package an unpinned project runs through npx. */
-export function pinnedArkgateSpec(version = shippedArkgateVersion()) {
+function pinnedArkgateSpec(version = shippedArkgateVersion()) {
   return version ? `arkgate@${version}` : 'arkgate';
 }
 
@@ -199,7 +199,7 @@ export function isNpmYarnWorkspaceRoot(root) {
  * Normalize a version/range/spec into an installable package argument for arkgate.
  * Accepts `latest`, `^3.8.2`, `arkgate@latest`, or a full package name.
  */
-export function normalizeArkgateInstallSpec(versionSpec) {
+function normalizeArkgateInstallSpec(versionSpec) {
   const raw = typeof versionSpec === 'string' && versionSpec.trim() ? versionSpec.trim() : 'latest';
   if (raw.startsWith('arkgate@') || raw === 'arkgate') return raw === 'arkgate' ? 'arkgate@latest' : raw;
   if (raw.includes('/') || raw.startsWith('file:') || raw.startsWith('link:')) return raw;

package/bin/lib/parse-health.mjs

@@ -4,7 +4,7 @@
  * governed files to a partial analysis verdict.
  */
 
-export const PARSE_HEALTH_FILE_CAP = 12;
+const PARSE_HEALTH_FILE_CAP = 12;
 
 function unavailableParseHealth(scannedFiles = 0) {
   return {

package/bin/lib/persistence-write-hint.mjs

@@ -9,13 +9,13 @@
  */
 
 /** IO / ORM import evidence. postgres and drizzle-orm include package subpaths. */
-export const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm(?:\/[^'"]+)?|postgres(?:\/[^'"]+)?|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|postgres(?:\/[^'"]+)?|drizzle-orm(?:\/[^'"]+)?|knex|typeorm|mongoose)/;
+const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm(?:\/[^'"]+)?|postgres(?:\/[^'"]+)?|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|postgres(?:\/[^'"]+)?|drizzle-orm(?:\/[^'"]+)?|knex|typeorm|mongoose)/;
 /** Path-alias / local db module (`@/lib/db`) without resolving tsconfig. */
-export const IO_ALIAS_IMPORT_RE = /\bfrom\s+['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)(?:\.[cm]?[jt]sx?)?['"]|require\(\s*['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)/;
+const IO_ALIAS_IMPORT_RE = /\bfrom\s+['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)(?:\.[cm]?[jt]sx?)?['"]|require\(\s*['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)/;
 /** Named imports from a local persistence module (same module names as IO_ALIAS_IMPORT_RE). */
 const LOCAL_CLIENT_IMPORT_RE = /\bimport\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)(?:\.[cm]?[jt]sx?)?['"]/g;
 /** Conventional client identifiers (PrismaClient included via the /i flag). */
-export const PERSISTENCE_CLIENT_NAMES = [
+const PERSISTENCE_CLIENT_NAMES = [
     'db',
     'tx',
     'client',
@@ -24,7 +24,10 @@ export const PERSISTENCE_CLIENT_NAMES = [
     'drizzle',
 ];
 const WRITE_VERB_SOURCE = '(?:insert(?:One|Many)?|update(?:One|Many)?|upsert|delete(?:One|Many)?|createMany|create|replaceOne|findOneAnd(?:Update|Delete|Replace))';
-const SQL_WRITE_SOURCE = '\\bINSERT\\s+INTO\\b|\\bUPDATE\\s+[A-Za-z_][\\w.]*\\s+SET\\b|\\bDELETE\\s+FROM\\b';
+const SQL_WRITE_RE = /\b(?:INSERT\s+INTO|(?<!\b(?:FOR(?:\s+NO\s+KEY)?|DO)\s)UPDATE(?:\s+ONLY)?(?!\s+(?:OF|SET)\b)|DELETE\s+FROM(?:\s+ONLY)?|MERGE\s+INTO|TRUNCATE(?:\s+TABLE)?(?:\s+ONLY)?)\s+(?:(?:(?:"[^"]*"|[A-Za-z_][\w$]*)\s*\.\s*)?(?:"[^"]*"|[A-Za-z_][\w$]*)|\$\{[^}]+\})/i;
+const NOT_A_SQL_TAG = /^(?:await|return|throw|yield|new|typeof|void|delete|if|else|case|of|in|instanceof|async|function|class|const|let|var|import|export|from|as|default|type)$/;
+const TAGGED_SQL_RE = /(^|[^\w$])([A-Za-z_$][\w$]*)\s*`((?:[^`\\]|\\[\s\S])*)`/g;
+const UPSERT_RE = /\bINSERT\s+INTO\b[\s\S]*?\bON\s+CONFLICT\b[\s\S]*?\bDO\s+UPDATE\s+SET\b[^;`]*/gi;
 /** Call arguments with one level of nested parentheses: `({ log: fn() })`. */
 const CALL_ARGS_SOURCE = '\\((?:[^()]|\\([^()]*\\))*\\)';
 /** Receivers built inline: `new PrismaClient(...)` / `drizzle(...)`. */
@@ -55,7 +58,7 @@ function collectFirstGroup(re, content, names) {
  * driver constructor, annotated with a driver client type, or imported by name from a
  * local persistence module.
  */
-export function persistenceClientBindings(content) {
+function persistenceClientBindings(content) {
     const names = new Set();
     collectFirstGroup(DRIVER_BINDING_RE, content, names);
     collectFirstGroup(DRIVER_ANNOTATION_RE, content, names);
@@ -71,11 +74,33 @@ export function persistenceClientBindings(content) {
     }
     return [...names].sort();
 }
+function blankPersistenceComments(content) {
+    return content.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|`(?:[^`\\]|\\[\s\S])*`|'(?:[^'\\]|\\[\s\S])*'|"(?:[^"\\]|\\[\s\S])*"/g, (token) => token.charCodeAt(0) === 47
+        ? token.replace(/[^\n]/g, ' ')
+        : token.charCodeAt(0) === 96
+            ? token.replace(/--[^\n`]*/g, (comment) => ' '.repeat(comment.length))
+            : token);
+}
+export function sourceHasTaggedSqlWrite(content) {
+    const text = blankPersistenceComments(content);
+    TAGGED_SQL_RE.lastIndex = 0;
+    let match;
+    while ((match = TAGGED_SQL_RE.exec(text)) !== null) {
+        if (NOT_A_SQL_TAG.test(match[2] ?? ''))
+            continue;
+        if (SQL_WRITE_RE.test((match[3] ?? '').replace(UPSERT_RE, ' ')))
+            return true;
+    }
+    return false;
+}
 /** Receiver-bound write evidence (ORM verb on a persistence client, or raw SQL write). */
 export function sourceHasPersistenceWrite(content) {
-    const receivers = [...PERSISTENCE_CLIENT_NAMES, ...persistenceClientBindings(content)]
+    const text = blankPersistenceComments(content);
+    const receivers = [...PERSISTENCE_CLIENT_NAMES, ...persistenceClientBindings(text)]
         .map(escapeRegExp)
         .join('|');
-    const re = new RegExp(`(?:\\b(?:${receivers})(?![\\w$])|${INLINE_CLIENT_SOURCE})(?:\\s*\\.\\s*[A-Za-z_]\\w*)*\\s*\\.\\s*${WRITE_VERB_SOURCE}\\s*\\(|${SQL_WRITE_SOURCE}`, 'i');
-    return re.test(content);
+    const re = new RegExp(`(?:\\b(?:${receivers})(?![\\w$])|${INLINE_CLIENT_SOURCE})(?:\\s*\\.\\s*[A-Za-z_]\\w*)*\\s*\\.\\s*${WRITE_VERB_SOURCE}\\s*\\(`, 'i');
+    if (re.test(text))
+        return true;
+    return SQL_WRITE_RE.test(text);
 }

package/bin/lib/pin-dependent-gates.mjs

@@ -16,7 +16,7 @@ const LOCAL_RUNNER_TEXT =
 const TOML_SERVER = /command\s*=\s*"([^"]*)"\s*\r?\nargs\s*=\s*\[([^\]]*)\]/g;
 
 /** Host hooks, package scripts, and MCP registrations Ark generates. */
-export const PIN_DEPENDENT_CANDIDATES = [
+const PIN_DEPENDENT_CANDIDATES = [
   '.claude/settings.json',
   '.codex/hooks.json',
   '.cursor/hooks.json',
@@ -40,7 +40,7 @@ function readText(file) {
 }
 
 /** True when this argv runs an Ark bin through a runner that needs the local pin. */
-export function argvDependsOnArkgatePin(command, args) {
+function argvDependsOnArkgatePin(command, args) {
   if (typeof command !== 'string' || !Array.isArray(args)) return false;
   const runner = path.basename(command.trim().replace(/\\/g, '/')).replace(/\.(?:cmd|exe)$/i, '');
   if (runner === 'npx') return npxArkgatePrefixLength(args) === 0 && ARK_BIN.test(args[0] ?? '');