@clear-capabilities/agentic-security-scanner 0.158.0 → 0.160.0

package/src/language/fix-lifecycle.js

@@ -10,8 +10,9 @@
 // Preview never writes. Apply writes a backup first and refuses a file that changed since planning.
 // Undo restores the backup byte for byte.
 
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
 import { statePath } from '../posture/state-dir.js';
 import { maybeEncryptForWrite, maybeDecryptForRead } from '../posture/encryption-provider.js';
 import { recordExternalFix, markRevertedByBackup } from '../posture/fix-history.js';
@@ -30,31 +31,102 @@ export function unifiedDiff(file, a, b) {
 }
 const safeRel = (root, rel) => { const p = join(root, rel); if (!p.startsWith(join(root) + '/')) throw new Error(`path escapes the root: ${rel}`); return p; };
 
-export function writeWithBackup(root, rel, before, after) {
+/** Save the pre-image of `rel` (customer source: it follows the encryption policy) and return its backup. Writes nothing to the target. */
+function saveBackup(root, rel, before, after) {
   const target = safeRel(root, rel);
-  const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const id = `${Date.now().toString(36)}-${randomBytes(5).toString('hex')}`;
   const dir = statePath(root, 'fix-backups', id);
   const disk = existsSync(target) ? readFileSync(target, 'utf8') : null;
   if (disk !== before) throw new Error('the file changed on disk since the fix was planned; refusing to overwrite');
-  // The pre-image is customer source: it follows the project's encryption policy for confidential state, and a policy
-  // that REQUIRES encryption with no working provider refuses the fix before anything is written.
+  // A policy that REQUIRES encryption with no working provider refuses the fix before anything is written.
   const enc = maybeEncryptForWrite(root, 'fix-backups', before);
   if (!enc.ok) throw new Error(enc.reason);
   mkdirSync(dir, { recursive: true });
   writeFileSync(join(dir, 'original'), enc.content);
   writeFileSync(join(dir, 'meta.json'), JSON.stringify({ file: rel, appliedAt: new Date().toISOString(), sizeBefore: before.length, sizeAfter: after.length }));
+  return { id, dir, target };
+}
+
+export function writeWithBackup(root, rel, before, after) {
+  const { id, dir, target } = saveBackup(root, rel, before, after);
   writeFileSync(target, after);
   return { id, dir };
 }
 
-export function undoFix(root, backupId) {
-  const _afterUndo = () => { try { markRevertedByBackup(root, backupId); } catch { /* history is best effort */ } };
+/**
+ * Apply several file edits as ONE unit. Nothing is written until every file has been checked (inside the root, unchanged
+ * since planning) and every pre-image is backed up. If a write then fails, every file already written (and the one that
+ * failed, which may be truncated) is put back, and the error says whether that rollback was complete.
+ * @param {string} root
+ * @param {Array<{file:string,before:string,after:string}>} edits
+ * @param {{writeFile?:Function}} [hooks]  test seam for the file writer
+ * @returns {{id:string, dir:string, members:Array<{id:string,dir:string,file:string}>}}
+ */
+export function writeManyWithBackup(root, edits, hooks = {}) {
+  const write = hooks.writeFile || writeFileSync;
+  const seen = new Set();
+  for (const e of edits) { if (seen.has(e.file)) throw new Error(`the same file is edited twice in one fix: ${e.file}`); seen.add(e.file); safeRel(root, e.file); }
+  const members = [];
+  const cleanup = () => { for (const m of members) { try { rmSync(m.dir, { recursive: true, force: true }); } catch { /* best effort */ } } };
+  try { for (const e of edits) { const b = saveBackup(root, e.file, e.before, e.after); members.push({ id: b.id, dir: b.dir, file: e.file, target: b.target, before: e.before, after: e.after }); } }
+  catch (err) { cleanup(); throw new Error(`${err.message} (no file was written)`); }
+  const written = [];
+  for (const m of members) {
+    written.push(m);
+    try { write(m.target, m.after); } catch (err) {
+      const failed = [];
+      for (const w of written.slice().reverse()) { try { write(w.target, w.before); } catch { failed.push(w.file); } }
+      if (!failed.length) cleanup();
+      const e = new Error(failed.length
+        ? `write to ${m.file} failed (${err.message}); ROLLBACK INCOMPLETE, restore these from the backups under .agentic-security/fix-backups: ${failed.join(', ')}`
+        : `write to ${m.file} failed (${err.message}); every file in this fix was restored to its original content`);
+      e.rolledBack = failed.length === 0; e.rollbackFailed = failed; e.failedFile = m.file;
+      throw e;
+    }
+  }
+  const groupId = `g${Date.now().toString(36)}-${randomBytes(5).toString('hex')}`;
+  const dir = statePath(root, 'fix-backups', groupId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'meta.json'), JSON.stringify({ file: members[0].file, group: members.map((m) => ({ id: m.id, file: m.file })), appliedAt: new Date().toISOString() }));
+  return { id: groupId, dir, members: members.map((m) => ({ id: m.id, dir: m.dir, file: m.file })) };
+}
+
+/**
+ * Undo a fix. A multi-file fix is restored as a unit: every pre-image is read and every target resolved before the first
+ * write, and if a restore fails the files already restored are put back to the content they had, so a partial undo is
+ * never left behind.
+ */
+export function undoFix(root, backupId, hooks = {}) {
+  const write = hooks.writeFile || writeFileSync;
   const dir = statePath(root, 'fix-backups', backupId);
   const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
-  const target = safeRel(root, meta.file);
-  writeFileSync(target, maybeDecryptForRead(readFileSync(join(dir, 'original'), 'utf8')));
-  _afterUndo();
-  return { ok: true, file: meta.file };
+  if (!Array.isArray(meta.group)) {
+    const target = safeRel(root, meta.file);
+    writeFileSync(target, maybeDecryptForRead(readFileSync(join(dir, 'original'), 'utf8')));
+    try { markRevertedByBackup(root, backupId); } catch { /* history is best effort */ }
+    return { ok: true, file: meta.file, files: [meta.file] };
+  }
+  const items = meta.group.map((m) => {
+    const mdir = statePath(root, 'fix-backups', m.id);
+    const md = JSON.parse(readFileSync(join(mdir, 'meta.json'), 'utf8'));
+    return { file: md.file, target: safeRel(root, md.file), original: maybeDecryptForRead(readFileSync(join(mdir, 'original'), 'utf8')), id: m.id };
+  });
+  const current = items.map((it) => (existsSync(it.target) ? readFileSync(it.target, 'utf8') : null));
+  const touched = [];
+  for (let i = 0; i < items.length; i++) {
+    touched.push(i);
+    try { write(items[i].target, items[i].original); } catch (err) {
+      const failed = [];
+      for (const j of touched.slice().reverse()) { try { if (current[j] !== null) write(items[j].target, current[j]); } catch { failed.push(items[j].file); } }
+      const e = new Error(failed.length
+        ? `undo failed at ${items[i].file} (${err.message}); ROLLBACK INCOMPLETE for: ${failed.join(', ')}`
+        : `undo failed at ${items[i].file} (${err.message}); no file was changed`);
+      e.rolledBack = failed.length === 0; e.rollbackFailed = failed;
+      throw e;
+    }
+  }
+  for (const id of [backupId, ...items.map((it) => it.id)]) { try { markRevertedByBackup(root, id); } catch { /* history is best effort */ } }
+  return { ok: true, file: items[0].file, files: items.map((it) => it.file) };
 }
 
 /**
@@ -75,10 +147,14 @@ export async function runFixLifecycle(o) {
   const { plan, files, finding } = o;
   const gates = {};
   // A patch may only touch a file inside the project: a target that escapes the root is refused before anything else runs.
-  gates.path = { ok: isRootRelativePath(plan.file), detail: plan.file };
-  if (!gates.path.ok) return { status: 'blocked', applied: false, reason: `path-escape: ${String(plan.file).slice(0, 120)} is outside the project root`, plan, gates, label: plan.label };
+  // A plan may carry `edits` (several files, one logical fix); a plan without them is the single edit of `plan.file`.
+  const edits = Array.isArray(plan.edits) && plan.edits.length ? plan.edits : [{ file: plan.file, before: plan.before, after: plan.after }];
+  const escaping = edits.filter((e) => !isRootRelativePath(e.file));
+  gates.path = { ok: escaping.length === 0, detail: edits.map((e) => e.file).join(', ') };
+  if (!gates.path.ok) return { status: 'blocked', applied: false, reason: `path-escape: ${escaping.map((e) => String(e.file).slice(0, 120)).join(', ')} is outside the project root`, plan, gates, label: plan.label };
   gates.syntax = o.syntax(plan);
-  const patched = { ...files, [plan.file]: plan.after };
+  const patched = { ...files };
+  for (const e of edits) patched[e.file] = e.after;
   const blocked = (why) => ({ status: 'blocked', applied: false, reason: why, plan, gates, label: plan.label });
   if (!gates.syntax.ok) return blocked(`syntax: ${gates.syntax.detail}`);
   if (o.behaviorCheck) { gates.behavior = o.behaviorCheck(plan); if (gates.behavior && gates.behavior.ok === false) return blocked(`behavior: ${gates.behavior.detail || 'unrelated behavior change'}`); }
@@ -94,6 +170,12 @@ export async function runFixLifecycle(o) {
   gates.rescan = { ok: gone && added.length === 0, originalGone: gone, newMediumOrHigher: [...new Set(added.map((f) => `${f.cwe || f.vuln}@${f.file}:${f.line}`))] };
   if (!gone) return blocked('the original finding is still reported after the patch');
   if (added.length) return blocked(`the patch introduces ${added.length} new medium-or-higher finding(s)`);
+  // Optional effective-configuration gate: the rescan above only proves a finding stopped being REPORTED, which a patch that
+  // turns the option into a module-system conflict also achieves. The check says whether the option now HAS the intended value.
+  if (o.effectiveCheck) {
+    gates.effective = o.effectiveCheck(plan, patched, files) || { ok: false, detail: 'no effective-configuration result' };
+    if (gates.effective.ok === false) return blocked(`effective: ${gates.effective.detail}`);
+  }
   // Optional controlled-witness gate (X-009): the hook returns judgeFixWitness(before, after). A patch that STILL
   // reproduces the effect is blocked; a witness that could not be judged (unsupported, invalid, unavailable) verifies
   // nothing and, unless `requireWitness` is set, does not block (it is recorded as not-verified).
@@ -106,15 +188,26 @@ export async function runFixLifecycle(o) {
   if (gates.compile.ran && !gates.compile.ok) return blocked(`compile: ${gates.compile.detail}`);
   if (o.requireCompile && !gates.compile.ran) return blocked(`compile verification required but ${gates.compile.detail}`);
   const verified = { syntax: true, rescan: true, compile: gates.compile.ran ? 'passed' : 'not-run', witness: gates.witness ? (gates.witness.verified ? 'passed' : 'not-verified') : 'not-run' };
-  const res = { status: 'verified', applied: false, plan, gates, label: plan.label, verified, preview: unifiedDiff(plan.file, plan.before, plan.after) };
+  const res = { status: 'verified', applied: false, plan, gates, label: plan.label, verified, preview: edits.map((e) => unifiedDiff(e.file, e.before, e.after)).join('\n'), files: edits.map((e) => e.file) };
   if (o.apply) {
     if (!o.root) return blocked('apply requires a root directory');
-    res.backup = writeWithBackup(o.root, plan.file, plan.before, plan.after);
-    res.applied = true; res.status = 'applied';
-    // One ledger: the same fix-history `agentic-security undo` reads, with the tier and the gates that passed.
-    try {
-      res.history = await recordExternalFix({ scanRoot: o.root, file: plan.file, originalContent: plan.before, newContent: plan.after, findingId: finding.id || `${finding.file}:${finding.line}`, ruleId: finding.rule || null, vuln: finding.vuln || null, stableId: finding.stableId || null, fixLabel: plan.label || null, verification: verified, backup: res.backup, findingProvenance: finding.findingProvenance || null });
-    } catch { res.history = null; }
+    const base = { scanRoot: o.root, findingId: finding.id || `${finding.file}:${finding.line}`, ruleId: finding.rule || null, vuln: finding.vuln || null, stableId: finding.stableId || null, fixLabel: plan.label || null, verification: verified, findingProvenance: finding.findingProvenance || null };
+    if (edits.length === 1) {
+      res.backup = writeWithBackup(o.root, plan.file, plan.before, plan.after);
+      res.applied = true; res.status = 'applied';
+      // One ledger: the same fix-history `agentic-security undo` reads, with the tier and the gates that passed.
+      try { res.history = await recordExternalFix({ ...base, file: plan.file, originalContent: plan.before, newContent: plan.after, backup: res.backup }); } catch { res.history = null; }
+    } else {
+      try { res.backup = writeManyWithBackup(o.root, edits, { writeFile: o.writeFile }); } catch (err) {
+        return { ...blocked(`apply failed, nothing was left changed: ${err.message}`), rolledBack: err.rolledBack !== false, rollbackFailed: err.rollbackFailed || [] };
+      }
+      res.applied = true; res.status = 'applied';
+      // One ledger entry per touched file, all carrying the group id so `undo` reverts them together.
+      res.history = [];
+      for (let i = 0; i < edits.length; i++) {
+        try { res.history.push(await recordExternalFix({ ...base, file: edits[i].file, originalContent: edits[i].before, newContent: edits[i].after, backup: res.backup.members[i], languageGroupId: res.backup.id })); } catch { res.history.push(null); }
+      }
+    }
   }
   return res;
 }

package/src/language/haskell-adapter.js

@@ -13,7 +13,8 @@ export const HASKELL_PARSE_PRODUCER = 'language:haskell-parse';
 
 // Boundaries whose content the parser could not see. cpp and ffi are disclosed on
 // the parse result but do not make the file unresolved: both CPP branches are
-// parsed and a foreign declaration's own Haskell signature is.
+// parsed and a foreign declaration's own Haskell signature is. `th-safe-splice` and `quasiquote-inert` are matched by a
+// closed, sound pattern (haskell-boundaries.js) and stay disclosed as assumptions; every other TH/quasi-quote boundary is opaque.
 const OPAQUE_BOUNDARIES = new Set(['th-splice', 'th-quote', 'th-name-quote', 'th-top-level-splice', 'quasiquote', 'hsc', 'generated']);
 
 export function ensureHaskellParseProducer() {
@@ -24,7 +25,7 @@ export function ensureHaskellParseProducer() {
 }
 
 /**
- * @param {{grammarSource?:Function, budgets?:object, mode?:string, onParse?:(file:string, parse:object)=>void}} [opts]
+ * @param {{grammarSource?:Function, budgets?:object, mode?:string, cpp?:object, onParse?:(file:string, parse:object)=>void}} [opts]
  */
 export function createHaskellAdapter(opts = {}) {
   ensureHaskellParseProducer();
@@ -33,7 +34,7 @@ export function createHaskellAdapter(opts = {}) {
     language: 'haskell',
     hasGrammar: () => loadHaskellGrammar({ grammarSource: opts.grammarSource }).available,
     analyze(file, content) {
-      const parse = parseHaskell(content, { file, grammarSource: opts.grammarSource, budgets: opts.budgets, mode: opts.mode });
+      const parse = parseHaskell(content, { file, grammarSource: opts.grammarSource, budgets: opts.budgets, mode: opts.mode, cpp: opts.cpp });
       if (typeof opts.onParse === 'function') opts.onParse(file, parse);
       if (parse.status === 'budget_exceeded' && parse.budget && parse.budget.name === 'deadlineMs') {
         throw Object.assign(new Error(`Haskell parser deadline exceeded for ${file}`), { code: 'LANG_TIMEOUT' });

package/src/language/haskell-advisory-feed.js

@@ -177,3 +177,18 @@ export async function refreshHackageAdvisories(names, opts = {}) {
     packages: wanted.length, requested: need.length, fetched: fetched.size, records: records.size, uncovered, failures: failures.slice(0, 10), path, cacheProblem: cur.problem,
   });
 }
+
+/**
+ * The scan-health view of this feed, in the shape language/assurance.js takes for an optional mode: `selected` is whether the operator
+ * opted in, `result` is what the refresh did (absent when none happened, which assurance reports as "selected but did not run").
+ * Outcomes that mean the feed answered are `ok`; a partial refresh is `partial` (some packages stay unknown) and is not dressed as success.
+ */
+export function liveFeedOptionalState(env = process.env, refresh = getLastRefresh()) {
+  if (env[FEED_ENV] !== '1') return { selected: false };
+  if (!refresh) return { selected: true, result: undefined };
+  const ok = new Set(['refreshed', 'current', 'nothing-to-do']);
+  if (ok.has(refresh.status)) return { selected: true, result: { status: 'ok' } };
+  if (refresh.status === 'partial') return { selected: true, result: { status: 'partial', reason: refresh.detail } };
+  if (refresh.status === 'failed') return { selected: true, result: { status: 'failed', reason: refresh.detail } };
+  return { selected: true, result: { status: refresh.status, ran: false, reason: refresh.detail } };
+}

package/src/language/haskell-boundaries.js

@@ -0,0 +1,220 @@
+// Safe Template Haskell declarations and inert quasi-quotes (HS boundaries).
+//
+// The parser treats a Template Haskell splice or a quasi-quote as an opaque boundary: it cannot see the code the
+// compiler will generate, so the file is `unresolved` in scan health. A small, closed set of constructs is different:
+// a well-known generator applied to nothing but NAMES and LITERALS (`makeLenses ''T`, `deriveJSON defaultOptions ''T`,
+// `share [mkPersist sqlSettings] [persistLowerCase| ... |]`) defines names, executes no project-controlled string and
+// introduces no source, sink or sanitizer; and a raw-string quasi-quote (`[r|...|]`, or `[i|...|]` with no
+// interpolation) is a string literal. Those are recognised here and reported as a DISCLOSED ASSUMPTION instead of an
+// opaque boundary.
+//
+// Soundness rules (each one is pinned by a test in both directions):
+//   - The generator must be IMPORTED from the upstream module that defines it, with the import actually exposing the name,
+//     and must not be defined in the file. A local `makeLenses` stays opaque.
+//   - Every token of the declaration must be accounted for. An argument that is a variable, a call, a lambda, a string
+//     built from an expression, a nested splice or any other quasi-quote leaves the whole declaration opaque.
+//   - Nothing here executes anything. This is a closed-form match over tokens, not an evaluation.
+//   - The assumption is stated on the boundary: the generator is taken to be the upstream package's, and what it
+//     generates (lenses, instances, persistent entities) is not modelled.
+
+// generator name -> modules that export it
+const GENERATORS = new Map([
+  ['makeLenses', ['Control.Lens', 'Control.Lens.TH', 'Lens.Micro.TH', 'Lens.Micro.Platform']],
+  ['makeLensesWith', ['Control.Lens', 'Control.Lens.TH']],
+  ['makeClassy', ['Control.Lens', 'Control.Lens.TH', 'Lens.Micro.TH', 'Lens.Micro.Platform']],
+  ['makeClassyPrisms', ['Control.Lens', 'Control.Lens.TH']],
+  ['makePrisms', ['Control.Lens', 'Control.Lens.TH']],
+  ['makeFields', ['Control.Lens', 'Control.Lens.TH']],
+  ['makeWrapped', ['Control.Lens', 'Control.Lens.TH', 'Control.Lens.Wrapped']],
+  ['deriveJSON', ['Data.Aeson.TH']],
+  ['deriveToJSON', ['Data.Aeson.TH']],
+  ['deriveFromJSON', ['Data.Aeson.TH']],
+  ['deriveSafeCopy', ['Data.SafeCopy']],
+  ['deriveSafeCopySimple', ['Data.SafeCopy']],
+  ['mkPersist', ['Database.Persist.TH']],
+  ['mkMigrate', ['Database.Persist.TH']],
+  ['mkSave', ['Database.Persist.TH']],
+  ['mkDeleteCascade', ['Database.Persist.TH']],
+  ['share', ['Database.Persist.TH']],
+  ['makeAcidic', ['Data.Acid', 'Data.Acid.TH']],
+]);
+
+// plain identifiers that may appear as an argument: option records and settings values the generators document
+const SAFE_VALUES = new Map([
+  ['defaultOptions', ['Data.Aeson.TH', 'Data.Aeson']],
+  ['lensRules', ['Control.Lens', 'Control.Lens.TH']],
+  ['camelCaseFields', ['Control.Lens', 'Control.Lens.TH']],
+  ['abbreviatedFields', ['Control.Lens', 'Control.Lens.TH']],
+  ['underscoreFields', ['Control.Lens', 'Control.Lens.TH']],
+  ['sqlSettings', ['Database.Persist.TH']],
+  ['mkPersistSettings', ['Database.Persist.TH']],
+]);
+
+// quasi-quoters accepted inside a safe declaration
+const SAFE_DECL_QUOTERS = new Map([
+  ['persistLowerCase', ['Database.Persist.TH']],
+  ['persistUpperCase', ['Database.Persist.TH']],
+]);
+
+// Option-record update (`defaultOptions { fieldLabelModifier = drop 4 }`): field names and the pure helpers a value may use.
+const OPTION_FIELDS = new Set(['fieldLabelModifier', 'constructorTagModifier', 'omitNothingFields', 'allNullaryToStringTag', 'sumEncoding', 'unwrapUnaryRecords', 'tagSingleConstructors', 'rejectUnknownFields']);
+const PURE_HELPERS = new Set(['drop', 'take', 'map', 'toLower', 'toUpper', 'id', 'camelTo2', 'tail', 'init']);
+
+// inert quasi-quoters: name -> { modules, interpolating }. `interpolating` quoters are inert only when the body has no
+// interpolation marker; a raw-string quoter is inert whatever the body says.
+const INERT_QUOTERS = new Map([
+  ['r', { modules: ['Text.RawString.QQ'], check: false }],
+  ['here', { modules: ['Data.String.Here', 'Data.String.Here.Uninterpolated', 'Data.String.Here.Interpolated'], check: true }],
+  ['hereLit', { modules: ['Data.String.Here', 'Data.String.Here.Uninterpolated'], check: true }],
+  ['i', { modules: ['Data.String.Interpolate', 'Data.String.Interpolate.IsString', 'Data.String.Here', 'Data.String.Here.Interpolated'], check: true }],
+  ['iii', { modules: ['Data.String.Interpolate'], check: true }],
+  ['__i', { modules: ['Data.String.Interpolate'], check: true }],
+  ['iTrim', { modules: ['Data.String.Here', 'Data.String.Here.Interpolated'], check: true }],
+]);
+const INTERPOLATION_MARK = /#\{|\$\{|\$\(|\$[A-Za-z_]/;
+
+function splitQuoter(q) {
+  const i = q.lastIndexOf('.');
+  return i < 0 ? { qual: null, name: q } : { qual: q.slice(0, i), name: q.slice(i + 1) };
+}
+
+/** Is `name` (optionally qualified by `qual`) exported by one of `modules` through a visible import, and not shadowed locally? */
+function importedFrom(name, qual, modules, imports, defined) {
+  if (defined.has(name) && !qual) return false;
+  for (const imp of imports) {
+    if (!imp || !imp.module || !modules.includes(imp.module)) continue;
+    if (qual) { if ((imp.as || imp.module) !== qual) continue; }
+    else if (imp.qualified) continue;
+    if (imp.items) {
+      const listed = imp.items.includes(name);
+      if (imp.hiding ? listed : !listed) continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Classify one top-level splice item as a safe generative declaration.
+ * @returns {{generators:string[], modules:string[]}|null}  null leaves it opaque
+ */
+export function classifySafeSplice(T, a, b, match, imports, defined) {
+  const generators = [];
+  const modules = new Set();
+  const tok = (i) => T[i];
+  const sameWord = (t) => t.k === 'varid' || t.k === 'qvarid';
+
+  // value: a single argument starting at p, returns the next index or -1
+  const parseValue = (p, end) => {
+    const t = tok(p);
+    if (!t) return -1;
+    if (t.k === 'thname' || t.k === 'string' || t.k === 'int' || t.k === 'conid' || t.k === 'qconid') {
+      let q = p + 1;
+      // a record update right after an atom: defaultOptions { field = value, ... }
+      if (q < end && tok(q).k === '{' && match[q] > q && match[q] < end) {
+        if (!parseRecordUpdate(q, match[q])) return -1;
+        q = match[q] + 1;
+      }
+      return q;
+    }
+    if (sameWord(t)) {
+      const sv = SAFE_VALUES.get(t.name || t.v);
+      if (!sv || !importedFrom(t.name || t.v, t.qual || null, sv, imports, defined)) return -1;
+      let q = p + 1;
+      if (q < end && tok(q).k === '{' && match[q] > q && match[q] < end) {
+        if (!parseRecordUpdate(q, match[q])) return -1;
+        q = match[q] + 1;
+      }
+      return q;
+    }
+    if (t.k === 'quasiquote') {
+      const { qual, name } = splitQuoter(t.quoter || '');
+      const mods = SAFE_DECL_QUOTERS.get(name);
+      if (!mods || !importedFrom(name, qual, mods, imports, defined)) return -1;
+      return p + 1;
+    }
+    if (t.k === '(' && match[p] > p && match[p] < end) {
+      if (!parseApp(p + 1, match[p], true)) return -1;
+      return match[p] + 1;
+    }
+    if (t.k === '[' && match[p] > p && match[p] < end) {
+      // a list of applications or atoms, separated by top-level commas
+      let q = p + 1;
+      const close = match[p];
+      if (q === close) return close + 1;
+      for (;;) {
+        let e = q;
+        while (e < close && tok(e).k !== ',') e = (['(', '[', '{'].includes(tok(e).k) && match[e] > e) ? match[e] + 1 : e + 1;
+        if (e === q) return -1;
+        if (!parseApp(q, e, true)) return -1;
+        if (e >= close) break;
+        q = e + 1;
+      }
+      return close + 1;
+    }
+    return -1;
+  };
+
+  const parseRecordUpdate = (open, close) => {
+    let p = open + 1;
+    if (p === close) return true;
+    for (;;) {
+      const f = tok(p);
+      if (!f || f.k !== 'varid' || !OPTION_FIELDS.has(f.v)) return false;
+      if (!tok(p + 1) || tok(p + 1).k !== 'rop' || tok(p + 1).v !== '=') return false;
+      p += 2;
+      let valueEnd = p;
+      while (valueEnd < close && tok(valueEnd).k !== ',') valueEnd++;
+      if (valueEnd === p) return false;
+      for (let q = p; q < valueEnd; q++) {
+        const t = tok(q);
+        const ok = t.k === 'int' || t.k === 'string' || t.k === 'conid' || t.k === 'qconid' || t.k === '(' || t.k === ')'
+          || (t.k === 'op' && t.v === '.') || (t.k === 'varid' && PURE_HELPERS.has(t.v));
+        if (!ok) return false;
+      }
+      if (valueEnd >= close) return true;
+      p = valueEnd + 1;
+    }
+  };
+
+  // application: generator followed by values. `nested` allows a generator head inside parentheses or lists.
+  const parseApp = (p, end, nested) => {
+    const h = tok(p);
+    if (!h || !sameWord(h)) {
+      // a bare value inside a list (`[mkPersist sqlSettings, mkMigrate "m"]` elements are applications, but a quoter or name may stand alone)
+      if (nested && p < end) { const n = parseValue(p, end); return n === end; }
+      return false;
+    }
+    const name = h.name || h.v;
+    const mods = GENERATORS.get(name);
+    if (!mods && nested) return parseValue(p, end) === end;
+    if (!mods || !importedFrom(name, h.qual || null, mods, imports, defined)) return false;
+    generators.push(name);
+    for (const m of mods) modules.add(m);
+    let q = p + 1;
+    while (q < end) {
+      const n = parseValue(q, end);
+      if (n < 0) return false;
+      q = n;
+    }
+    return q === end;
+  };
+
+  // optional outer splice wrapper: $( ... )
+  let s = a;
+  let e = b;
+  if (tok(a).k === 'op' && tok(a).v === '$' && tok(a + 1) && tok(a + 1).k === '(' && tok(a).e === tok(a + 1).s && match[a + 1] === b - 1) { s = a + 2; e = b - 1; }
+  if (s >= e) return null;
+  if (!parseApp(s, e, false)) return null;
+  return { generators, modules: [...modules].sort() };
+}
+
+/** Classify one quasi-quote token as an inert string. @returns {{quoter:string, module:string}|null} */
+export function classifyInertQuasiQuote(quoter, body, imports, defined) {
+  if (!quoter) return null;
+  const { qual, name } = splitQuoter(quoter);
+  const q = INERT_QUOTERS.get(name);
+  if (!q || !importedFrom(name, qual, q.modules, imports, defined)) return null;
+  if (q.check && INTERPOLATION_MARK.test(body)) return null;
+  return { quoter: name, modules: q.modules };
+}