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

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 };
+}

package/src/language/haskell-cpp.js

@@ -0,0 +1,460 @@
+// CPP conditional evaluation for Haskell sources (HS boundaries).
+//
+// Static and dependency-free: it never runs cpp, GHC or Cabal. It evaluates `#if` / `#ifdef` / `#ifndef` / `#elif` /
+// `#else` chains with THREE-valued logic (true, false, unknown) so that:
+//   - a decidable conditional keeps only its live branch (the dead branch is overwritten with same-length spaces by the
+//     caller, so locations stay exact),
+//   - an undecidable one keeps EVERY possible branch (the union) and is reported as undecided,
+//   - nothing is ever invented: a macro that the file does not define and the project does not state is `unknown`, never 0.
+//
+// What decides a condition, and on what basis (each decision records its basis):
+//   file            `#define` / `#undef` in the same file, integer literals, `#if 0` / `#if 1`, `defined(X)`.
+//   compiler:pinned __GLASGOW_HASKELL__, MIN_VERSION_GLASGOW_HASKELL and the boot-package MIN_VERSION_base, when the
+//                   project PINS a compiler (`with-compiler: ghc-X` in cabal.project). Pinned means "this is what builds".
+//   compiler:tested-with   the same, from `tested-with: GHC == X` lines. That is a claim by the project, not a pin, so a
+//                   decision on this basis is only taken when EVERY listed version agrees, and it is disclosed as an assumption.
+//   cabal-bounds    MIN_VERSION_<pkg>(a,b,c) judged against the hull of the `build-depends` ranges of every component in the
+//                   project: a built version must satisfy its component's range, so it lies inside the hull.
+
+import { parseCabalFile, parseVersion, compareVersions } from './haskell-manifests.js';
+
+const UNKNOWN = null;
+
+// ── tri-state helpers ──────────────────────────────────────────────────────
+
+const truthy = (v) => (v === UNKNOWN ? UNKNOWN : v !== 0);
+
+// ── versions ───────────────────────────────────────────────────────────────
+
+const toNums = (v) => v.map((x) => Number(x));
+
+/**
+ * Three-valued `v >= t` where `v` may have an unknown tail (a wildcard such as 9.6.* has no patch level): undefined
+ * components of v are unknown, so the answer is decided only by the components that exist.
+ */
+function triGte(v, t) {
+  for (let i = 0; i < Math.max(v.length, t.length); i++) {
+    const p = v[i];
+    const q = t[i] ?? 0;
+    if (p === undefined) return t.slice(i).every((x) => x === 0) ? true : UNKNOWN;
+    if (p > q) return true;
+    if (p < q) return false;
+  }
+  return true;
+}
+
+// GHC ships a fixed `base`. Only major.minor is recorded: a patch level of base varies inside one GHC series.
+const GHC_BASE = new Map([['8.6', [4, 12]], ['8.8', [4, 13]], ['8.10', [4, 14]], ['9.0', [4, 15]], ['9.2', [4, 16]], ['9.4', [4, 17]], ['9.6', [4, 18]], ['9.8', [4, 19]], ['9.10', [4, 20]], ['9.12', [4, 21]]]);
+
+function baseRangeOf(ghc) {
+  const b = GHC_BASE.get(`${ghc[0]}.${ghc[1]}`);
+  return b ? { lo: b, hiExcl: [b[0], b[1] + 1] } : null;
+}
+
+/** Hull {lo, hiExcl, hiIncl} of a parsed version-range AST (null bounds are open). Over-approximates, never under. */
+export function rangeHull(ast) {
+  const inter = (a, b) => ({
+    lo: !a.lo ? b.lo : !b.lo ? a.lo : (compareVersions(a.lo, b.lo) >= 0 ? a.lo : b.lo),
+    hiExcl: !a.hiExcl ? b.hiExcl : !b.hiExcl ? a.hiExcl : (compareVersions(a.hiExcl, b.hiExcl) <= 0 ? a.hiExcl : b.hiExcl),
+    hiIncl: !a.hiIncl ? b.hiIncl : !b.hiIncl ? a.hiIncl : (compareVersions(a.hiIncl, b.hiIncl) <= 0 ? a.hiIncl : b.hiIncl),
+  });
+  const open = { lo: null, hiExcl: null, hiIncl: null };
+  const walk = (n) => {
+    if (!n) return open;
+    switch (n.t) {
+      case 'and': return inter(walk(n.l), walk(n.r));
+      case 'or': {
+        const a = walk(n.l); const b = walk(n.r);
+        const hiOf = (x) => (x.hiExcl || x.hiIncl);
+        const unbounded = (x) => !x.hiExcl && !x.hiIncl;
+        let hi = { hiExcl: null, hiIncl: null };
+        if (!unbounded(a) && !unbounded(b)) {
+          // the larger of the two upper bounds; an inclusive bound outranks an exclusive one at the same version
+          const ha = hiOf(a); const hb = hiOf(b);
+          const c = compareVersions(ha, hb);
+          const pick = c > 0 ? a : c < 0 ? b : (a.hiIncl ? a : b);
+          hi = { hiExcl: pick.hiExcl && !pick.hiIncl ? pick.hiExcl : null, hiIncl: pick.hiIncl || null };
+        }
+        return { lo: !a.lo || !b.lo ? null : (compareVersions(a.lo, b.lo) <= 0 ? a.lo : b.lo), ...hi };
+      }
+      case 'cmp': {
+        const v = n.version;
+        if (n.op === '>=' || n.op === '>') return { ...open, lo: v };
+        if (n.op === '<') return { ...open, hiExcl: v };
+        if (n.op === '<=') return { ...open, hiIncl: v };
+        if (n.op === '^>=') { const up = [v[0], (v[1] ?? 0n) + 1n]; return { lo: v, hiExcl: up, hiIncl: null }; }
+        if (n.op === '==') {
+          if (n.wildcard) { const up = v.slice(); up[up.length - 1] += 1n; return { lo: v, hiExcl: up, hiIncl: null }; }
+          return { lo: v, hiExcl: null, hiIncl: v };
+        }
+        return open;
+      }
+      case 'none': return { lo: [1n], hiExcl: [0n], hiIncl: null };
+      default: return open;
+    }
+  };
+  return walk(ast);
+}
+
+/** Three-valued MIN_VERSION_x(a,b,c): is the installed version >= target, given that it lies in `r`? */
+function minVersion(r, target) {
+  if (!r) return UNKNOWN;
+  const t = target.map((x) => BigInt(x));
+  if (r.lo && compareVersions(r.lo, t) >= 0) return true;
+  if (r.hiExcl && compareVersions(r.hiExcl, t) <= 0) return false;
+  if (r.hiIncl && compareVersions(r.hiIncl, t) < 0) return false;
+  return UNKNOWN;
+}
+
+const intersectHull = (a, b) => {
+  if (!a) return b; if (!b) return a;
+  return {
+    lo: !a.lo ? b.lo : !b.lo ? a.lo : (compareVersions(a.lo, b.lo) >= 0 ? a.lo : b.lo),
+    hiExcl: !a.hiExcl ? b.hiExcl : !b.hiExcl ? a.hiExcl : (compareVersions(a.hiExcl, b.hiExcl) <= 0 ? a.hiExcl : b.hiExcl),
+    hiIncl: !a.hiIncl ? b.hiIncl : !b.hiIncl ? a.hiIncl : (compareVersions(a.hiIncl, b.hiIncl) <= 0 ? a.hiIncl : b.hiIncl),
+  };
+};
+
+// ── project context ────────────────────────────────────────────────────────
+
+/**
+ * Derive what the project itself states, from manifest files in `files` (path -> text). Returns
+ * { ghc: {versions:number[][], basis:'pinned'|'tested-with'}|null, packages: Map<name, hull> }. Never throws.
+ */
+export function deriveCppContext(files = {}) {
+  const ctx = { ghc: null, packages: new Map() };
+  const pinned = [];
+  const tested = [];
+  let testedUsable = true;
+  const hulls = new Map();
+  for (const [file, text] of Object.entries(files || {})) {
+    if (typeof text !== 'string') continue;
+    try {
+      if (/(?:^|\/)cabal\.project(?:\.local)?$/i.test(file)) {
+        const m = /^\s*with-compiler\s*:\s*ghc-(\d+(?:\.\d+)+)\s*$/im.exec(text);
+        if (m) pinned.push(toNums(parseVersion(m[1])));
+      } else if (/\.cabal$/i.test(file)) {
+        const tw = /^tested-with\s*:([^\n]*(?:\n[ \t]+[^\n]*)*)/im.exec(text);
+        if (tw) {
+          const body = tw[1];
+          for (const part of body.split(',').map((s) => s.trim()).filter(Boolean)) {
+            const m = /^GHC\s*==\s*(\d+(?:\.\d+)*)(\.\*)?$/i.exec(part);
+            if (m) tested.push(toNums(parseVersion(m[1])));
+            else if (/^GHC\b/i.test(part)) testedUsable = false;   // a range or an unparsable item: never guess a version from it
+          }
+        }
+        const parsed = parseCabalFile(text, { file });
+        for (const comp of parsed.components || []) {
+          for (const d of comp.dependencies || []) {
+            if (!d || !d.name) continue;
+            const h = d.range ? rangeHull(d.range) : { lo: null, hiExcl: null, hiIncl: null };
+            const prior = hulls.get(d.name);
+            // union of components: the lower of the lows, the larger of the highs; an open end stays open
+            hulls.set(d.name, !prior ? h : {
+              lo: !prior.lo || !h.lo ? null : (compareVersions(prior.lo, h.lo) <= 0 ? prior.lo : h.lo),
+              ...((!prior.hiExcl && !prior.hiIncl) || (!h.hiExcl && !h.hiIncl) ? { hiExcl: null, hiIncl: null } : (() => {
+                const pa = prior.hiExcl || prior.hiIncl; const pb = h.hiExcl || h.hiIncl;
+                const c = compareVersions(pa, pb);
+                const pick = c > 0 ? prior : c < 0 ? h : (prior.hiIncl ? prior : h);
+                return { hiExcl: pick.hiIncl ? null : pick.hiExcl, hiIncl: pick.hiIncl || null };
+              })()),
+            });
+          }
+        }
+      }
+    } catch { /* an unreadable manifest states nothing */ }
+  }
+  if (pinned.length) ctx.ghc = { versions: pinned, basis: 'pinned' };
+  else if (tested.length && testedUsable) ctx.ghc = { versions: tested, basis: 'tested-with' };
+  ctx.packages = hulls;
+  return ctx;
+}
+
+// ── expression evaluation ──────────────────────────────────────────────────
+
+const TOKEN = /\s*(0[xX][0-9a-fA-F]+[uUlL]*|\d+[uUlL]*|[A-Za-z_]\w*|&&|\|\||==|!=|<=|>=|<<|>>|[-+*/%()!<>,~&|^?:])/y;
+
+function tokenize(text) {
+  const s = text.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/.*$/, ' ').trim();
+  const out = [];
+  let pos = 0;
+  while (pos < s.length) {
+    TOKEN.lastIndex = pos;
+    const m = TOKEN.exec(s);
+    if (!m) return null;
+    out.push(m[1]);
+    pos = TOKEN.lastIndex;
+    if (out.length > 400) return null;
+  }
+  return out;
+}
+
+const isIdent = (t) => /^[A-Za-z_]/.test(t);
+
+/**
+ * Evaluate an `#if` expression to a number, or UNKNOWN. `env` = { macros: Map, ghc: number[]|null, packages: Map }.
+ * `used` collects the bases the answer depended on.
+ */
+function evalExpression(text, env, used) {
+  const toks = tokenize(text);
+  if (!toks || !toks.length) return UNKNOWN;
+  let i = 0;
+  let bad = false;
+  const macroValue = (name, depth) => {
+    const m = env.macros.get(name);
+    if (m === undefined) return UNKNOWN;
+    if (m.state === 'undefined') return 0;
+    if (m.state !== 'defined' || m.fn) return UNKNOWN;
+    if (m.value === '') return UNKNOWN;
+    if (depth > 8) return UNKNOWN;
+    const t2 = tokenize(m.value);
+    if (!t2 || t2.length !== 1) return UNKNOWN;
+    if (/^\d/.test(t2[0])) return parseInt(t2[0], /^0[xX]/.test(t2[0]) ? 16 : 10);
+    if (isIdent(t2[0])) return macroValue(t2[0], depth + 1);
+    return UNKNOWN;
+  };
+  const definedState = (name) => {
+    const m = env.macros.get(name);
+    if (m) return m.state === 'defined' ? true : m.state === 'undefined' ? false : UNKNOWN;
+    if (name === '__GLASGOW_HASKELL__' && env.ghc) { used.add(`compiler:${env.basis}`); return true; }
+    return UNKNOWN;
+  };
+  const num = () => {
+    const t = toks[i++];
+    if (t === undefined) { bad = true; return UNKNOWN; }
+    if (t === '(') { const v = ternary(); if (toks[i++] !== ')') bad = true; return v; }
+    if (t === '!') { const v = unary(); return v === UNKNOWN ? UNKNOWN : (v === 0 ? 1 : 0); }
+    if (t === '-') { const v = unary(); return v === UNKNOWN ? UNKNOWN : -v; }
+    if (t === '+') return unary();
+    if (t === '~') { const v = unary(); return v === UNKNOWN ? UNKNOWN : ~v; }
+    if (/^\d/.test(t)) return parseInt(t, /^0[xX]/.test(t) ? 16 : 10);
+    if (!isIdent(t)) { bad = true; return UNKNOWN; }
+    if (t === 'defined') {
+      let paren = false;
+      if (toks[i] === '(') { paren = true; i++; }
+      const name = toks[i++];
+      if (paren && toks[i++] !== ')') bad = true;
+      if (!name || !isIdent(name)) { bad = true; return UNKNOWN; }
+      const d = definedState(name);
+      return d === UNKNOWN ? UNKNOWN : (d ? 1 : 0);
+    }
+    if (toks[i] === '(') {
+      // function-like macro call: MIN_VERSION_*(a,b,c) is modelled, every other call is unknown
+      const args = [];
+      i++;
+      if (toks[i] !== ')') {
+        for (;;) {
+          const a = ternary();
+          args.push(a);
+          if (toks[i] === ',') { i++; continue; }
+          break;
+        }
+      }
+      if (toks[i++] !== ')') { bad = true; return UNKNOWN; }
+      const fnMacro = env.macros.get(t);
+      if (fnMacro) return UNKNOWN;   // defined (or possibly defined) in the file: its body is not expanded
+      return minVersionCall(t, args);
+    }
+    if (t === '__GLASGOW_HASKELL__') {
+      const m = env.macros.get(t);
+      if (m) return macroValue(t, 0);
+      if (!env.ghc) return UNKNOWN;
+      used.add(`compiler:${env.basis}`);
+      return env.ghc[0] * 100 + (env.ghc[1] ?? 0);
+    }
+    return macroValue(t, 0);
+  };
+  const minVersionCall = (name, args) => {
+    const m = /^MIN_VERSION_(.+)$/.exec(name);
+    if (!m || args.some((a) => a === UNKNOWN || a < 0)) return UNKNOWN;
+    if (m[1] === 'GLASGOW_HASKELL') {
+      if (!env.ghc || args.length !== 4) return UNKNOWN;
+      used.add(`compiler:${env.basis}`);
+      const r = triGte(env.ghc, args);
+      return r === UNKNOWN ? UNKNOWN : (r ? 1 : 0);
+    }
+    if (args.length !== 3) return UNKNOWN;
+    const pkg = m[1].replace(/_/g, '-');
+    let hull = env.packages.get(pkg) || env.packages.get(m[1]) || null;
+    if (hull) used.add('cabal-bounds');
+    if (pkg === 'base' && env.ghc) {
+      const bt = baseRangeOf(env.ghc);
+      if (bt) {
+        used.add(`compiler:${env.basis}`);
+        hull = intersectHull(hull, { lo: bt.lo.map((x) => BigInt(x)), hiExcl: bt.hiExcl.map((x) => BigInt(x)), hiIncl: null });
+      }
+    }
+    const r = minVersion(hull, args);
+    return r === UNKNOWN ? UNKNOWN : (r ? 1 : 0);
+  };
+  const unary = () => num();
+  const bin = (next, ops) => () => {
+    let l = next();
+    while (ops.includes(toks[i])) {
+      const op = toks[i++];
+      const r = next();
+      l = apply(op, l, r);
+    }
+    return l;
+  };
+  const apply = (op, l, r) => {
+    if (op === '&&') { if (l === 0 || r === 0) return 0; if (l === UNKNOWN || r === UNKNOWN) return UNKNOWN; return 1; }
+    if (op === '||') { if ((l !== UNKNOWN && l !== 0) || (r !== UNKNOWN && r !== 0)) return 1; if (l === UNKNOWN || r === UNKNOWN) return UNKNOWN; return 0; }
+    if (l === UNKNOWN || r === UNKNOWN) return UNKNOWN;
+    switch (op) {
+      case '*': return l * r;
+      case '/': return r === 0 ? UNKNOWN : Math.trunc(l / r);
+      case '%': return r === 0 ? UNKNOWN : l % r;
+      case '+': return l + r;
+      case '-': return l - r;
+      case '<<': return r < 0 || r > 30 ? UNKNOWN : l << r;
+      case '>>': return r < 0 || r > 30 ? UNKNOWN : l >> r;
+      case '<': return l < r ? 1 : 0;
+      case '>': return l > r ? 1 : 0;
+      case '<=': return l <= r ? 1 : 0;
+      case '>=': return l >= r ? 1 : 0;
+      case '==': return l === r ? 1 : 0;
+      case '!=': return l !== r ? 1 : 0;
+      case '&': return l & r;
+      case '^': return l ^ r;
+      case '|': return l | r;
+      default: return UNKNOWN;
+    }
+  };
+  const mul = bin(unary, ['*', '/', '%']);
+  const add = bin(mul, ['+', '-']);
+  const shift = bin(add, ['<<', '>>']);
+  const rel = bin(shift, ['<', '>', '<=', '>=']);
+  const eq = bin(rel, ['==', '!=']);
+  const band = bin(eq, ['&']);
+  const bxor = bin(band, ['^']);
+  const bor = bin(bxor, ['|']);
+  const land = bin(bor, ['&&']);
+  const lor = bin(land, ['||']);
+  const ternary = () => {
+    const c = lor();
+    if (toks[i] === '?') {
+      i++;
+      const a = ternary();
+      if (toks[i++] !== ':') { bad = true; return UNKNOWN; }
+      const b = ternary();
+      if (c === UNKNOWN) return a === b ? a : UNKNOWN;
+      return c !== 0 ? a : b;
+    }
+    return c;
+  };
+  const v = ternary();
+  if (bad || i < toks.length) return UNKNOWN;
+  return v;
+}
+
+/** Tri-state truth of an `#if` expression, across every candidate compiler version (they must all agree). */
+function decide(text, state, ctx) {
+  const ghcs = ctx && ctx.ghc && ctx.ghc.versions.length ? ctx.ghc.versions : [null];
+  const results = [];
+  const used = new Set();
+  for (const g of ghcs) {
+    const env = { macros: state.macros, ghc: g, basis: ctx && ctx.ghc ? ctx.ghc.basis : null, packages: (ctx && ctx.packages) || new Map() };
+    results.push(truthy(evalExpression(text, env, used)));
+  }
+  const first = results[0];
+  const value = results.every((r) => r === first) ? first : UNKNOWN;
+  return { value, basis: value === UNKNOWN ? null : (used.size ? [...used].sort() : ['file']) };
+}
+
+function decideDefined(name, state, ctx) {
+  const m = state.macros.get(name);
+  if (m) return { value: m.state === 'defined' ? true : m.state === 'undefined' ? false : UNKNOWN, basis: ['file'] };
+  if (name === '__GLASGOW_HASKELL__' && ctx && ctx.ghc) return { value: true, basis: [`compiler:${ctx.ghc.basis}`] };
+  return { value: UNKNOWN, basis: null };
+}
+
+const blank = (s) => s.replace(/[^\r\n]/g, ' ');
+
+/**
+ * Evaluate the CPP conditionals of `code` line by line.
+ * @param {string[]} lines  the source split on '\n' (modified copies are returned, lengths preserved)
+ * @param {{ghc?:object, packages?:Map, defines?:object}} [ctx]
+ * @returns {{lines:string[], maybeDepth:Int32Array, decided:object[], undecided:object[], deadLines:number}}
+ */
+export function evaluateCppLines(lines, isDirective, ctx = {}) {
+  const state = { macros: new Map() };
+  for (const [k, v] of Object.entries((ctx && ctx.defines) || {})) state.macros.set(k, { state: 'defined', value: String(v), fn: false });
+  const out = lines.slice();
+  const maybeDepth = new Int32Array(lines.length + 2);
+  const stack = [];
+  const decided = [];
+  const undecided = [];
+  let deadLines = 0;
+  const region = () => {
+    let r = 'live';
+    for (const f of stack) { if (f.cur === 'dead') return 'dead'; if (f.cur === 'maybe') r = 'maybe'; }
+    return r;
+  };
+  const maybeCount = () => stack.filter((f) => f.cur === 'maybe').length;
+
+  for (let i = 0; i < lines.length; i++) {
+    const info = isDirective(i);
+    if (!info) {
+      // an ordinary line: a dead region is overwritten, a live or possible one is kept
+      if (region() === 'dead') { out[i] = blank(out[i]); deadLines++; }
+      maybeDepth[i + 1] = maybeCount();
+      continue;
+    }
+    // directive logical line (continuations already joined by the caller in info.text); the physical lines it spans
+    const { name, text, last } = info;
+    const parentRegion = region();
+    const rest = text.replace(/^#\s*[A-Za-z]+/, '').trim();
+    const lineNo = i + 1;
+    const note = (kind, value, basis) => {
+      const rec = { line: lineNo, directive: name, outcome: value === UNKNOWN ? 'undecided' : (value ? 'true' : 'false'), basis };
+      if (kind === 'decided') decided.push(rec); else undecided.push(rec);
+    };
+    if (name === 'if' || name === 'ifdef' || name === 'ifndef') {
+      if (parentRegion === 'dead') stack.push({ cur: 'dead', taken: 'yes', parentDead: true });
+      else {
+        let d;
+        if (name === 'if') d = decide(rest, state, ctx);
+        else {
+          const id = /^[A-Za-z_]\w*/.exec(rest);
+          d = id ? decideDefined(id[0], state, ctx) : { value: UNKNOWN, basis: null };
+          if (name === 'ifndef' && d.value !== UNKNOWN) d = { ...d, value: !d.value };
+        }
+        const cur = d.value === UNKNOWN ? 'maybe' : (d.value ? 'live' : 'dead');
+        stack.push({ cur, taken: cur === 'live' ? 'yes' : cur === 'maybe' ? 'maybe' : 'no', parentDead: false });
+        if (d.value === UNKNOWN) note('undecided', d.value, null); else note('decided', d.value, d.basis);
+      }
+    } else if (name === 'elif' || name === 'else') {
+      const f = stack[stack.length - 1];
+      if (f && !f.parentDead) {
+        let c;
+        let basis = null;
+        if (name === 'else') c = true;
+        else if (f.taken === 'yes') c = false;   // an earlier branch was taken for certain: this one is dead whatever it says
+        else { const d = decide(rest, state, ctx); c = d.value; basis = d.basis; }
+        let cur;
+        if (f.taken === 'yes' || c === false) cur = 'dead';
+        else if (c === true) cur = f.taken === 'no' ? 'live' : 'maybe';
+        else cur = 'maybe';
+        if (cur === 'live') f.taken = 'yes'; else if (cur === 'maybe' && f.taken === 'no') f.taken = 'maybe';
+        f.cur = cur;
+        if (name === 'elif' && f.taken !== 'yes') { if (c === UNKNOWN) note('undecided', c, null); else note('decided', c, basis); }
+      }
+    } else if (name === 'endif') {
+      stack.pop();
+    } else if (name === 'define' || name === 'undef') {
+      const m = /^([A-Za-z_]\w*)(\()?\s*(.*)$/.exec(rest);
+      if (m && parentRegion !== 'dead') {
+        const maybe = parentRegion === 'maybe';
+        if (name === 'undef') state.macros.set(m[1], { state: maybe ? 'maybe' : 'undefined', value: '', fn: false });
+        else state.macros.set(m[1], { state: maybe ? 'maybe' : 'defined', value: m[2] ? '' : m[3].replace(/\\\s*$/, '').trim(), fn: !!m[2] });
+      }
+    }
+    // the directive lines themselves are always blanked by the caller; mark whether they sat in a possible region
+    const rg = region();
+    void rg;
+    for (let q = i; q <= last; q++) maybeDepth[q + 1] = maybeCount();
+    i = last;
+  }
+  return { lines: out, maybeDepth, decided, undecided, deadLines, unbalanced: stack.length > 0 };
+}