@clear-capabilities/agentic-security-scanner 0.157.2 → 0.159.0

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

@@ -0,0 +1,194 @@
+// Live Hackage advisory feed (HS-009 follow-on). The matching logic in haskell-sca.js takes records from its caller and never fetches;
+// this module is the caller that can. It turns the OSV `Hackage` ecosystem (HSEC advisories and their aliases) into the same
+// hash-recorded snapshot the loader already verifies, and writes it where only the operator can: the per-user configuration
+// directory. A scanned project cannot supply or alter it (see trusted-inputs.js).
+//
+// Contract, in the order it matters:
+//   * Opt in. Nothing here touches the network unless AGENTIC_SECURITY_HACKAGE_ADVISORIES_LIVE=1, and never when
+//     AGENTIC_SECURITY_OFFLINE=1. An operator-pinned snapshot (AGENTIC_SECURITY_HACKAGE_ADVISORIES) always wins: it is not refreshed over.
+//   * Coverage is recorded, not assumed. The snapshot lists each package it actually queried and when. A package that was not queried,
+//     or whose query failed part-way, is NOT covered, and the matcher reports it `feed-incomplete` (unknown), never `no-advisories` (clean).
+//   * Failure degrades, it does not abort. An unreachable feed leaves the previous snapshot in place and the scan runs on it, with its age
+//     disclosed; with no previous snapshot the scan reports `feed-unavailable`, exactly as before this module existed.
+//   * Everything from the wire is untrusted: ids and package names are validated before they are placed in a URL or a path, sizes are
+//     bounded, and a record that does not parse as an OSV record is dropped and counted.
+
+import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildSnapshot, loadAdvisorySnapshot } from './haskell-sca.js';
+import { operatorConfigDir } from './trusted-inputs.js';
+
+export const FEED_ENV = 'AGENTIC_SECURITY_HACKAGE_ADVISORIES_LIVE';
+export const PINNED_ENV = 'AGENTIC_SECURITY_HACKAGE_ADVISORIES';
+export const SNAPSHOT_FILE = 'hackage-advisories.json';
+export const OSV_BASE = 'https://api.osv.dev';
+
+const DEFAULTS = Object.freeze({
+  ttlMs: 24 * 3600 * 1000,       // a covered package is not queried again inside this window
+  timeoutMs: 8000,
+  concurrency: 10,
+  batchSize: 500,
+  maxPackages: 500,
+  maxRecordBytes: 1 << 20,
+  maxSnapshotRecords: 20000,
+});
+
+const NAME_OK = /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/;   // Hackage package names
+const ID_OK = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$/;   // HSEC-2023-0001, GHSA-..., CVE-...
+
+let last = null;
+/** What the most recent refresh in this process did, so a "no feed" reason can say why. */
+export const getLastRefresh = () => last;
+export const _resetLastRefresh = () => { last = null; };
+
+export function liveFeedEnabled(env = process.env) {
+  return env[FEED_ENV] === '1' && env.AGENTIC_SECURITY_OFFLINE !== '1';
+}
+
+export function snapshotPath(env = process.env, dir = null) {
+  return join(dir || operatorConfigDir(env), SNAPSHOT_FILE);
+}
+
+function readCurrent(path, maxAgeDays) {
+  let raw;
+  try { raw = JSON.parse(readFileSync(path, 'utf8')); } catch { return { records: new Map(), covered: {}, problem: null }; }
+  // Integrity first: a cache whose records do not match their own hashes is discarded, not repaired.
+  const r = loadAdvisorySnapshot(raw, { maxAgeDays });
+  if (!r.ok) return { records: new Map(), covered: {}, problem: `the cached snapshot was discarded: ${r.reason}` };
+  const covered = raw.covered && typeof raw.covered === 'object' ? { ...raw.covered } : {};
+  return { records: new Map(raw.records.map((x) => [x.id, x])), covered, problem: null };
+}
+
+async function getJson(fetchImpl, url, init, timeoutMs, maxBytes) {
+  const resp = await fetchImpl(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+  if (!resp || resp.status !== 200) throw new Error(`HTTP ${resp ? resp.status : 'none'}`);
+  const text = await resp.text();
+  if (Buffer.byteLength(text) > maxBytes) throw new Error('response too large');
+  return JSON.parse(text);
+}
+
+async function pool(items, limit, worker) {
+  const out = new Array(items.length);
+  let i = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (i < items.length) { const k = i++; out[k] = await worker(items[k], k); }
+  }));
+  return out;
+}
+
+/**
+ * Refresh the operator's Hackage advisory snapshot for the given package names.
+ * Never throws. Returns a plain result describing what happened; the snapshot file is only rewritten when something changed.
+ *
+ * @param {string[]} names Hackage package names the scan is about to evaluate
+ * @param {{env?: object, fetchImpl?: Function, now?: number, dir?: string, ttlMs?: number, timeoutMs?: number}} [opts]
+ */
+export async function refreshHackageAdvisories(names, opts = {}) {
+  const env = opts.env || process.env;
+  const cfg = { ...DEFAULTS, ...Object.fromEntries(Object.entries(opts).filter(([k]) => k in DEFAULTS)) };
+  const now = opts.now ?? Date.now();
+  const done = (r) => { last = { ...r, at: new Date(now).toISOString() }; return last; };
+
+  if (env[PINNED_ENV]) return done({ status: 'pinned-snapshot-in-use', detail: `${PINNED_ENV} names an operator snapshot; it is used as given and is not refreshed` });
+  if (env[FEED_ENV] !== '1') return done({ status: 'disabled', detail: `set ${FEED_ENV}=1 to fetch Hackage advisories from the OSV feed` });
+  if (env.AGENTIC_SECURITY_OFFLINE === '1') return done({ status: 'offline', detail: 'AGENTIC_SECURITY_OFFLINE=1: no advisory data was fetched' });
+
+  const wanted = [...new Set((names || []).filter((n) => typeof n === 'string' && NAME_OK.test(n)))].sort().slice(0, cfg.maxPackages);
+  if (!wanted.length) return done({ status: 'nothing-to-do', detail: 'no Hackage packages to look up' });
+
+  const path = snapshotPath(env, opts.dir);
+  const cur = readCurrent(path, 36500);
+  const need = wanted.filter((n) => { const t = Date.parse(cur.covered[n]); return !Number.isFinite(t) || now - t > cfg.ttlMs || t > now + 3600000; });
+  if (!need.length) return done({ status: 'current', detail: `${wanted.length} package(s) covered within the last ${Math.round(cfg.ttlMs / 3600000)}h; no request made`, packages: wanted.length, requested: 0 });
+
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return done({ status: 'failed', detail: 'no fetch implementation is available in this runtime' });
+
+  const failures = [];
+  const ok = new Set();           // packages whose whole answer was obtained
+  const refs = new Map();         // package -> [{id, modified}]
+  // 1. which advisories does OSV hold for each package?
+  for (let i = 0; i < need.length; i += cfg.batchSize) {
+    const chunk = need.slice(i, i + cfg.batchSize);
+    try {
+      const data = await getJson(fetchImpl, `${OSV_BASE}/v1/querybatch`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ queries: chunk.map((name) => ({ package: { name, ecosystem: 'Hackage' } })) }),
+      }, cfg.timeoutMs, 8 << 20);
+      const results = Array.isArray(data && data.results) ? data.results : [];
+      chunk.forEach((name, k) => {
+        const res = results[k];
+        if (!res || typeof res !== 'object') { failures.push(`${name}: no result`); return; }
+        if (res.next_page_token) { failures.push(`${name}: more advisories than one page; not treated as covered`); return; }
+        refs.set(name, (Array.isArray(res.vulns) ? res.vulns : []).filter((v) => v && typeof v.id === 'string' && ID_OK.test(v.id)).map((v) => ({ id: v.id, modified: v.modified || null })));
+      });
+    } catch (e) { for (const n of chunk) failures.push(`${n}: ${String((e && e.message) || e).slice(0, 80)}`); }
+  }
+
+  // 2. fetch the records that are new or newer than the cached copy
+  const toFetch = new Map();
+  for (const list of refs.values()) for (const { id, modified } of list) {
+    const have = cur.records.get(id);
+    if (!have || (modified && have.modified && Date.parse(modified) > Date.parse(have.modified)) || (modified && !have.modified)) toFetch.set(id, modified);
+  }
+  const fetched = new Map();
+  const badIds = new Set();
+  await pool([...toFetch.keys()], cfg.concurrency, async (id) => {
+    try {
+      const rec = await getJson(fetchImpl, `${OSV_BASE}/v1/vulns/${encodeURIComponent(id)}`, {}, cfg.timeoutMs, cfg.maxRecordBytes);
+      if (!rec || typeof rec !== 'object' || rec.id !== id) throw new Error('not the requested record');
+      fetched.set(id, rec);
+    } catch (e) { badIds.add(id); failures.push(`${id}: ${String((e && e.message) || e).slice(0, 80)}`); }
+  });
+
+  // 3. a package is covered only if every advisory it references is in hand
+  const records = new Map(cur.records);
+  for (const [id, rec] of fetched) records.set(id, rec);
+  const covered = { ...cur.covered };
+  const iso = new Date(now).toISOString();
+  let newlyCovered = 0;
+  for (const [name, list] of refs) {
+    if (list.some((v) => badIds.has(v.id) || !records.has(v.id))) continue;
+    covered[name] = iso; ok.add(name); newlyCovered++;
+  }
+  const uncovered = need.filter((n) => !ok.has(n));
+
+  if (!ok.size && !fetched.size) {
+    return done({ status: 'failed', detail: `the OSV feed could not be read (${failures.slice(0, 2).join('; ') || 'no response'}); ${cur.records.size ? 'the previous snapshot is used and its age is disclosed' : 'no advisory data is available'}`, packages: wanted.length, requested: need.length, uncovered, failures: failures.slice(0, 10), cacheProblem: cur.problem });
+  }
+  if (records.size > cfg.maxSnapshotRecords) return done({ status: 'failed', detail: `the snapshot would exceed ${cfg.maxSnapshotRecords} records; refusing to write it`, packages: wanted.length, requested: need.length, uncovered });
+
+  // 4. write the snapshot atomically, readable by the operator only
+  const snap = buildSnapshot([...records.values()].sort((a, b) => (a.id < b.id ? -1 : 1)), iso);
+  snap.covered = Object.fromEntries(Object.entries(covered).sort(([a], [b]) => (a < b ? -1 : 1)));
+  try {
+    const dir = opts.dir || operatorConfigDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(snap), { mode: 0o600 });
+    try { chmodSync(tmp, 0o600); } catch { /* best effort on filesystems without modes */ }
+    renameSync(tmp, path);
+  } catch (e) {
+    return done({ status: 'failed', detail: `the snapshot could not be written: ${e.code || e.message}`, packages: wanted.length, requested: need.length, uncovered });
+  }
+  return done({
+    status: uncovered.length ? 'partial' : 'refreshed',
+    detail: `${newlyCovered} package(s) covered, ${fetched.size} advisory record(s) fetched${uncovered.length ? `; ${uncovered.length} package(s) NOT covered (${uncovered.slice(0, 3).join(', ')}${uncovered.length > 3 ? ', ...' : ''}) and will be reported as unknown` : ''}`,
+    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 };
+}