@clear-capabilities/agentic-security-scanner 0.184.0 → 0.186.1

package/src/graph/view.js

@@ -0,0 +1,254 @@
+//
+// view.js: the read-only typed graph view contract (DAG-06 R06.1) and the
+// shared adjacency-index cache (R06.6).
+//
+// A GraphView is a READ-ONLY lens over one existing graph. It never replaces
+// the graph's own schema: every node and edge keeps its original object in
+// `native`, every original id is preserved, and `reconstruct()` hands back the
+// source graph so an adapter round trip loses nothing.
+//
+// The contract (every adapter exposes exactly this):
+//   identity            { graphKind, repository, graphDigest, adapterVersion }
+//   metadata()          adapter/graph facts: counts, schema versions, sources
+//   completion()        { status: 'complete'|'partial'|'unknown', reasons[], coverage }
+//   has(ref)            boolean, never throws on a well-formed ref
+//   node(ref)           the entity, or throws DANGLING_REF / WRONG_GRAPH
+//   incoming(ref, f)    edges ending at ref, restricted by the relation filter
+//   outgoing(ref, f)    edges starting at ref, restricted by the relation filter
+//   reconstruct()       the original source graph (round trip)
+//
+// Adjacency indexes are built once per immutable (graphKind, digest, adapter
+// version) and shared by every view over the same content. The index is
+// keyed by LOCAL ids and references are rebuilt per view, so two repositories
+// that happen to share content never share each other's identity.
+
+import { createHash } from 'node:crypto';
+import {
+  GraphViewError, GRAPH_KINDS, makeRef, refKey, validateRef, REF_VERSION,
+} from './refs.js';
+import { normalizeFilter, edgeMatches, RELATION_KINDS, EDGE_ORIGINS } from './relations.js';
+
+const localKey = (entityKind, localId) => `${entityKind}\u0000${localId}`;
+
+// ---- adjacency cache -------------------------------------------------------------------------------------------------------
+
+const CACHE_LIMIT = 64;
+const _cache = new Map(); // cacheKey -> { fingerprint, index }
+const _stats = { builds: 0, hits: 0, evictions: 0 };
+
+export function adjacencyCacheStats() { return { ..._stats, size: _cache.size }; }
+export function clearAdjacencyCache() { _cache.clear(); _stats.builds = 0; _stats.hits = 0; _stats.evictions = 0; }
+
+function buildIndex(templates) {
+  const out = new Map();
+  const inn = new Map();
+  const push = (m, k, e) => { const a = m.get(k); if (a) a.push(e); else m.set(k, [e]); };
+  const endKey = (end) => (end.local ? localKey(end.entityKind, end.localId) : refKey(end.ref));
+  for (const t of templates) {
+    push(out, endKey(t.from), t);
+    push(inn, endKey(t.to), t);
+  }
+  return { out, in: inn };
+}
+
+function sharedIndex({ graphKind, graphDigest, adapterVersion }, templates, fingerprint) {
+  const key = `${graphKind}|${graphDigest}|${adapterVersion}`;
+  const hit = _cache.get(key);
+  if (hit) {
+    if (hit.fingerprint !== fingerprint) {
+      // The digest is the cache key because a graph with that digest is immutable.
+      // Different content under the same digest means the digest was not computed
+      // from the content, and serving the cached index would be a silent wrong answer.
+      throw new GraphViewError('DIGEST_CONFLICT', `graph digest ${graphDigest} was seen with different content`, { key });
+    }
+    _stats.hits += 1;
+    _cache.delete(key); _cache.set(key, hit); // LRU touch
+    return hit.index;
+  }
+  const index = buildIndex(templates);
+  _stats.builds += 1;
+  _cache.set(key, { fingerprint, index });
+  if (_cache.size > CACHE_LIMIT) {
+    _cache.delete(_cache.keys().next().value);
+    _stats.evictions += 1;
+  }
+  return index;
+}
+
+// ---- edge templates --------------------------------------------------------------------------------------------------------
+
+/**
+ * Adapters describe edges with `local(entityKind, localId)` endpoints for
+ * entities of their own graph, or `foreign(ref)` for an endpoint that lives in
+ * another graph (cross-repository declarations).
+ */
+export const local = (entityKind, localId) => ({ local: true, entityKind, localId });
+export const foreign = (ref) => {
+  const bad = validateRef(ref);
+  if (bad) throw new GraphViewError('BAD_REF', bad);
+  return { local: false, ref };
+};
+
+function checkTemplate(t) {
+  if (!t || typeof t.id !== 'string' || !t.id) throw new GraphViewError('BAD_EDGE', 'an edge needs an id');
+  if (!RELATION_KINDS.includes(t.relation)) throw new GraphViewError('BAD_EDGE', `edge ${t.id}: unknown relation ${JSON.stringify(t.relation)}`);
+  if (!EDGE_ORIGINS.includes(t.origin)) throw new GraphViewError('BAD_EDGE', `edge ${t.id}: unknown origin ${JSON.stringify(t.origin)}`);
+  if (!t.from || !t.to) throw new GraphViewError('BAD_EDGE', `edge ${t.id}: both endpoints are required`);
+}
+
+// ---- the view --------------------------------------------------------------------------------------------------------------
+
+export class IndexedGraphView {
+  /**
+   * @param {object} spec
+   * @param {string} spec.graphKind
+   * @param {string} spec.adapterVersion  semver of the adapter, not of the graph schema
+   * @param {string} spec.repository
+   * @param {string} spec.graphDigest     digest of the SOURCE graph, preserved as given
+   * @param {object} spec.metadata
+   * @param {object} spec.completion      { status, reasons, coverage }
+   * @param {{entityKind:string, localId:string, native:any, summary?:object}[]} spec.nodes
+   * @param {object[]} spec.edges         edge templates (see local()/foreign())
+   * @param {() => any} spec.reconstruct  returns the original source graph
+   * @param {boolean} [spec.allowForeign] endpoints may live in other graphs
+   */
+  constructor(spec) {
+    if (!GRAPH_KINDS.includes(spec.graphKind)) throw new GraphViewError('BAD_REF', `unknown graph kind ${spec.graphKind}`);
+    if (!/^\d+\.\d+\.\d+$/.test(spec.adapterVersion || '')) throw new GraphViewError('BAD_VERSION', 'adapterVersion must be a semantic version');
+    for (const f of ['repository', 'graphDigest']) {
+      if (typeof spec[f] !== 'string' || !spec[f]) throw new GraphViewError('BAD_REF', `${f} is required`);
+    }
+    this.graphKind = spec.graphKind;
+    this.adapterVersion = spec.adapterVersion;
+    this.repository = spec.repository;
+    this.graphDigest = spec.graphDigest;
+    this._metadata = spec.metadata ?? {};
+    this._completion = spec.completion ?? { status: 'unknown', reasons: ['adapter supplied no completion record'], coverage: null };
+    this._reconstruct = spec.reconstruct;
+    this._allowForeign = !!spec.allowForeign;
+
+    this._nodes = new Map();
+    for (const n of spec.nodes) {
+      const k = localKey(n.entityKind, n.localId);
+      if (this._nodes.has(k)) throw new GraphViewError('DUPLICATE_ID', `${this.graphKind} graph has two ${n.entityKind} entities with id ${n.localId}`, { entityKind: n.entityKind, localId: n.localId });
+      this._nodes.set(k, n);
+    }
+    this._templates = [];
+    const seen = new Set();
+    for (const t of spec.edges) {
+      checkTemplate(t);
+      if (seen.has(t.id)) throw new GraphViewError('DUPLICATE_ID', `${this.graphKind} graph has two edges with id ${t.id}`, { edgeId: t.id });
+      seen.add(t.id);
+      for (const end of [t.from, t.to]) {
+        if (end.local && !this._nodes.has(localKey(end.entityKind, end.localId))) {
+          throw new GraphViewError('DANGLING_REF', `edge ${t.id} points at ${end.entityKind} ${end.localId}, which is not in the graph`, { edgeId: t.id });
+        }
+        if (!end.local && !this._allowForeign) throw new GraphViewError('BAD_EDGE', `edge ${t.id}: foreign endpoints are only allowed in declaration views`);
+      }
+      this._templates.push(t);
+    }
+    // Content fingerprint over every entity key and edge id (order-insensitive). A
+    // digest names one immutable graph; the fingerprint is how a digest that does
+    // NOT match its content is caught instead of served from the shared index.
+    const h = createHash('sha256');
+    for (const k of [...this._nodes.keys()].sort()) h.update(k).update('\u0001');
+    h.update('\u0002');
+    for (const t of [...this._templates].map((x) => x.id).sort()) h.update(t).update('\u0001');
+    this.fingerprint = h.digest('hex');
+    this._index = sharedIndex(this.identity, this._templates, this.fingerprint);
+  }
+
+  get identity() {
+    return { graphKind: this.graphKind, repository: this.repository, graphDigest: this.graphDigest, adapterVersion: this.adapterVersion };
+  }
+
+  /** Reference to one of this graph's own entities. Throws DANGLING_REF if it is not there. */
+  ref(entityKind, localId) {
+    if (!this._nodes.has(localKey(entityKind, localId))) {
+      throw new GraphViewError('DANGLING_REF', `no ${entityKind} ${localId} in this ${this.graphKind} graph`, { entityKind, localId });
+    }
+    return makeRef({ graphKind: this.graphKind, repository: this.repository, graphDigest: this.graphDigest, entityKind, localId });
+  }
+
+  owns(ref) {
+    return ref.graphKind === this.graphKind && ref.repository === this.repository && ref.graphDigest === this.graphDigest;
+  }
+
+  _checkRef(ref) {
+    const bad = validateRef(ref);
+    if (bad) {
+      throw new GraphViewError(ref && ref.v !== undefined && ref.v !== REF_VERSION ? 'VERSION_INCOMPATIBLE' : 'BAD_REF', bad, { ref });
+    }
+  }
+
+  has(ref) {
+    this._checkRef(ref);
+    return this.owns(ref) && this._nodes.has(localKey(ref.entityKind, ref.localId));
+  }
+
+  node(ref) {
+    this._checkRef(ref);
+    if (!this.owns(ref)) {
+      throw new GraphViewError('WRONG_GRAPH', `reference points into ${ref.graphKind}/${ref.repository}/${ref.graphDigest.slice(0, 12)}, not this view`, { ref });
+    }
+    const n = this._nodes.get(localKey(ref.entityKind, ref.localId));
+    if (!n) throw new GraphViewError('DANGLING_REF', `no ${ref.entityKind} ${ref.localId} in this ${this.graphKind} graph`, { ref });
+    return { ref, entityKind: n.entityKind, localId: n.localId, summary: n.summary ?? null, native: n.native };
+  }
+
+  _lookup(map, ref) {
+    this._checkRef(ref);
+    let key;
+    if (this.owns(ref)) {
+      key = localKey(ref.entityKind, ref.localId);
+      if (!this._nodes.has(key)) throw new GraphViewError('DANGLING_REF', `no ${ref.entityKind} ${ref.localId} in this ${this.graphKind} graph`, { ref });
+    } else if (this._allowForeign) {
+      key = refKey(ref);
+    } else {
+      throw new GraphViewError('WRONG_GRAPH', 'reference points into a different graph', { ref });
+    }
+    return map.get(key) ?? [];
+  }
+
+  _materialize(t) {
+    const end = (e) => (e.local ? this.ref(e.entityKind, e.localId) : e.ref);
+    return {
+      id: t.id, relation: t.relation, origin: t.origin,
+      from: end(t.from), to: end(t.to),
+      evidence: t.evidence ?? { grade: 'none', source: null },
+      unknowns: t.unknowns ?? [],
+      attrs: t.attrs ?? {},
+      native: t.native,
+    };
+  }
+
+  outgoing(ref, filter) {
+    const nf = normalizeFilter(filter);
+    return this._lookup(this._index.out, ref).filter((t) => edgeMatches(t, nf)).map((t) => this._materialize(t));
+  }
+
+  incoming(ref, filter) {
+    const nf = normalizeFilter(filter);
+    return this._lookup(this._index.in, ref).filter((t) => edgeMatches(t, nf)).map((t) => this._materialize(t));
+  }
+
+  /** Entities in insertion order, optionally of one kind. */
+  entities(entityKind) {
+    const out = [];
+    for (const n of this._nodes.values()) if (!entityKind || n.entityKind === entityKind) out.push(this.node(this.ref(n.entityKind, n.localId)));
+    return out;
+  }
+
+  edges() { return this._templates.map((t) => this._materialize(t)); }
+
+  metadata() {
+    return { ...this._metadata, graphKind: this.graphKind, repository: this.repository, graphDigest: this.graphDigest, adapterVersion: this.adapterVersion, nodeCount: this._nodes.size, edgeCount: this._templates.length };
+  }
+
+  completion() {
+    const c = this._completion;
+    return { status: c.status, reasons: [...(c.reasons ?? [])], coverage: c.coverage ?? null };
+  }
+
+  reconstruct() { return this._reconstruct(); }
+}

package/src/ir/CLAUDE.md

@@ -267,6 +267,10 @@ down enterprise runners sometimes don't. Targets for retirement:
   interprocedural analysis, not just the older, vaguer "some constructs get
   dropped" cost.
 
+## Cross-scan IR cache and node ids
+
+`buildProjectIR(files, { irCache })` and `buildProjectIRAsync` accept an optional cache object (`dataflow/ir-cache.js`, opened by `engine.js` only when the cross-scan cache is on): an unchanged JavaScript or TypeScript file is read back instead of parsed, and a new parse is stored. With no cache the behaviour is exactly as before. Node ids (`n123`) come from a process-global counter in `parser-js.js`; a restored file is renumbered from the same counter through `reserveNodeIds(count)` so ids stay unique across the process. The ids sit in `cfg.entry`, `cfg.exit`, the `cfg.nodes` keys and each node's `id`/`succ`/`pred`, `fn.returns`, `fn.calls[].site`, `fn.writes[*][].node` and `fn.reads[*][]`; if a parser change puts an id anywhere else, the store-time check refuses to cache that file (it counts as `skipped` in the cache's `stats()`, and the file is parsed on every scan), so a new id-bearing field costs speed, never correctness. Name resolution in `callgraph.js` is answered from a name-to-candidates index (`qidsByName`, built in the order the per-file tables were built), so a name that no file defines is a lookup, not a scan of every file.
+
 ## Semantic graph (`semantic-graph.js`, engineering-excellence E2-01)
 
 An additive, typed, versioned view over this IR: `Symbol`, `CallSite`, `Allocation`, `FieldAccess`, `ValueOrigin`, plus the schema-only lists `ServiceBoundary`, `StorageEdge`, `Sanitizer`, `Guard`. Ids are content-derived and never include a line, so a blank line above a function moves no id. It reads the CFG (the one structure every language's IR shares; `writes` exists for JavaScript only). Nothing on the scan path imports it, so findings and `chain[]` cannot change; a test pins that. Columns are `null` (the IR has lines only) and say `locationPrecision: "line"`. Contract and the measured per-language construct matrix: `docs/engineering-excellence/IR_CONTRACT.md` (regenerate with `node scripts/engineering-excellence/ir-matrix.mjs`). Do not add a `site` field: IR site ids come from a process-global counter and are not stable across builds.

package/src/ir/callgraph.js

@@ -272,6 +272,32 @@ export function buildCallGraph(perFileIR, fileContents) {
   // `File::read` in C++): a fabricated cross-language edge, reached through
   // these older, coarser lookups BEFORE the qname-specific gate further down
   // is ever consulted.
+  // Name -> candidate qids across all files, in the order the file tables were
+  // built. The permissive lookups below used to walk EVERY file's table for each
+  // name that was not found locally, which is every call to a library method
+  // (`push`, `get`, `map`): thousands of names times hundreds of files. Visiting
+  // only the tables that hold the name, in the same order, returns the same
+  // first usable candidate.
+  const qidsByName = new Map();
+  for (const m of byNameInFile.values()) {
+    for (const [nm, q] of m) {
+      let l = qidsByName.get(nm);
+      if (!l) { l = []; qidsByName.set(nm, l); }
+      l.push(q);
+    }
+  }
+  // Re-export entries that can match a name (the key ends with `::<name>`, or the
+  // source name equals it), by index into the insertion order.
+  const reexportEntries = [...reexportMap];
+  const reexportCandidates = new Map();
+  if (reexportEntries.length) {
+    const addCand = (nm, i) => { let l = reexportCandidates.get(nm); if (!l) { l = new Set(); reexportCandidates.set(nm, l); } l.add(i); };
+    reexportEntries.forEach(([key, v], i) => {
+      let at = key.indexOf('::');
+      while (at >= 0) { addCand(key.slice(at + 2), i); at = key.indexOf('::', at + 1); }
+      addCand(v.sourceName, i);
+    });
+  }
   function isCrossLanguageUnsafe(qid, callerFile) {
     const cand = qid && functions.get(qid);
     if (!cand || !cand.qname) return false;
@@ -339,23 +365,25 @@ export function buildCallGraph(perFileIR, fileContents) {
         if (viaThis) return viaThis;
       }
     }
-    for (const m of byNameInFile.values()) {
-      if (m.has(name) && !isCrossLanguageUnsafe(m.get(name), callerFile)) return m.get(name);
+    for (const q of qidsByName.get(name) || []) {
+      if (!isCrossLanguageUnsafe(q, callerFile)) return q;
     }
     if (classMethods.has(name) && !isCrossLanguageUnsafe(classMethods.get(name), callerFile)) {
       return classMethods.get(name);
     }
     if (allowTailGuess && name.includes('.')) {
       const tail = name.split('.').slice(-1)[0];
-      for (const m of byNameInFile.values()) {
-        if (m.has(tail) && !isCrossLanguageUnsafe(m.get(tail), callerFile)) return m.get(tail);
+      for (const q of qidsByName.get(tail) || []) {
+        if (!isCrossLanguageUnsafe(q, callerFile)) return q;
       }
     }
     // Follow re-exports: if name was re-exported from another file, resolve there
-    for (const [key, { sourceName }] of reexportMap) {
-      if (key.endsWith(`::${name}`) || (sourceName === name)) {
-        for (const m of byNameInFile.values()) {
-          if (m.has(sourceName) && !isCrossLanguageUnsafe(m.get(sourceName), callerFile)) return m.get(sourceName);
+    const reCands = reexportCandidates.get(name);
+    if (reCands) {
+      for (const i of [...reCands].sort((a, b) => a - b)) {
+        const { sourceName } = reexportEntries[i][1];
+        for (const q of qidsByName.get(sourceName) || []) {
+          if (!isCrossLanguageUnsafe(q, callerFile)) return q;
         }
       }
     }

package/src/ir/index.js

@@ -132,10 +132,23 @@ function _parsePythonFiles(pyEntries) {
   return pyEntries.map(({ file, content }) => parsePythonFileRegex(file, content)).filter(Boolean);
 }
 
+// JavaScript / TypeScript parse through the optional cross-scan IR cache (dataflow/ir-cache.js): an unchanged
+// file is read back with fresh node ids instead of parsed again, and a new parse is stored. `irCache` is an
+// injected object ({load, store}); with none, this is exactly parseJsFile.
+function parseJsCached(file, code, irCache) {
+  if (!irCache) return parseJsFile(file, code);
+  const hit = irCache.load(file, code);
+  if (hit) return hit;
+  const ir = parseJsFile(file, code);
+  if (ir) irCache.store(file, code, ir);
+  return ir;
+}
+
 // Synchronous default — JS/TS + Python only. Engine.js calls this directly.
 // Java IR requires async import of java-parser; callers who want it can use
 // buildProjectIRAsync instead.
-export function buildProjectIR(fileContents) {
+export function buildProjectIR(fileContents, opts = {}) {
+  const irCache = opts && opts.irCache ? opts.irCache : null;
   const perFile = {};
   const pyBatch = [];
   const hsFiles = {};
@@ -148,7 +161,7 @@ export function buildProjectIR(fileContents) {
     // null — it does not zero out every other language's coverage.
     try {
       if (/\.(?:js|jsx|ts|tsx|mjs|cjs)$/i.test(file)) {
-        const ir = parseJsFile(file, code);
+        const ir = parseJsCached(file, code, irCache);
         if (ir) perFile[file] = ir;
       } else if (/\.hs$/i.test(file)) {
         hsFiles[file] = code;   // lowered together: Haskell resolution is whole-program (imports, re-exports)
@@ -238,7 +251,8 @@ function withHaskellCallGraph(cg, hsCg) {
 }
 
 // Async variant — includes Java IR via java-parser.
-export async function buildProjectIRAsync(fileContents) {
+export async function buildProjectIRAsync(fileContents, opts = {}) {
+  const irCache = opts && opts.irCache ? opts.irCache : null;
   const perFile = {};
   const pyBatch = [];
   const hsFiles = {};
@@ -247,7 +261,7 @@ export async function buildProjectIRAsync(fileContents) {
     // file can't abort IR construction for the whole project.
     try {
       if (/\.(?:js|jsx|ts|tsx|mjs|cjs)$/i.test(file)) {
-        const ir = parseJsFile(file, code);
+        const ir = parseJsCached(file, code, irCache);
         if (ir) perFile[file] = ir;
       } else if (/\.hs$/i.test(file)) {
         hsFiles[file] = code;

package/src/ir/parser-js.js

@@ -46,6 +46,16 @@ import presetTypescript from '@babel/preset-typescript';
 
 let _nodeIdSeq = 0;
 function nextNodeId() { return 'n' + (++_nodeIdSeq); }
+/**
+ * Reserve `count` consecutive node ids and return the sequence value before them
+ * (the first reserved id is `n<base + 1>`). A cached IR is given fresh ids from
+ * here, so an id is as unique across the whole process as one the parser made.
+ */
+export function reserveNodeIds(count) {
+  const base = _nodeIdSeq;
+  _nodeIdSeq += count;
+  return base;
+}
 
 // Round-5 lineage-engine finding, generalized in round 6: resolve a Babel
 // object-property-shaped node's key (`ObjectProperty` from either an

package/src/language/CLAUDE.md

@@ -96,6 +96,19 @@ Related, outside this directory: `dataflow/catalog-haskell.js`, `lineage/haskell
 - **Bounded**: `maxEvaluations`, `maxExprDepth`, `maxValueSize` are caps that surface as `truncated`, not as a guess.
 - Assumption stated, not proven: `lib` is nixpkgs' `lib` whenever the module declares a `lib` parameter and the file does not rebind it.
 
+## Declared option types (`nix-option-types.js`)
+
+`buildOptionTypeIndex` reads `mkOption { type = ...; }`, `mkEnableOption` and `mkPackageOption` declarations from the files in scope and
+records, per dotted option path, whether the declared type BOUNDS the value (bool, int and `ints.*`, port, float, number, package, a
+literal-word `enum`, and `nullOr`/`either`/`uniq` of bounded types). `nix-script-taint.js` `Evaluator.refine` turns a reference to a
+bounded option into a constant, so a shell interpolation of an `int` option is not an injection and a `bool` option called `forwardPass`
+is not a credential. Rules to keep: only options DECLARED in scope are known (an upstream option keeps its origin, except that the
+module-system convention for a package option, `package`/`finalPackage`/`fooPackage`, is a store path and a declared option of that name
+with an unbounded type is NOT); two declarations of one option are bounded only if both are; `str`, `path`, `lines`, `listOf`,
+`submodule` and anything computed are unbounded. `nix-secrets.js` skips documentation attributes of `mkOption` (`example`,
+`description`, `defaultText`; `default` is configuration and is not skipped) and does not treat a set-valued binding as a credential.
+Pinned both ways in `test/nix/nix-option-types.test.js`.
+
 ## Tests and benches
 
 | Scope | Command | Notes |

package/src/language/nix-option-types.js

@@ -0,0 +1,170 @@
+// Declared option types, read from the module sources that are in scope.
+//
+// A NixOS or Home Manager option is declared with `mkOption { type = ...; }`
+// (or `mkEnableOption`, `mkPackageOption`). The module system checks a value
+// against that type before the module's `config` is used, so the TYPE bounds
+// what a reference to the option can contain, whatever the name suggests:
+//
+//   bool, int, ints.*, port, float, number   digits, `0`/`1`, a sign or a dot
+//   package, shellPackage                    a store path (`/nix/store/<hash>-<name>`),
+//                                            whose name part is restricted by Nix to
+//                                            [A-Za-z0-9+._?=-]
+//   enum [ "a" "b" ]                         one of the listed literals
+//   nullOr T, either A B, uniq T             only when every member is itself bounded
+//
+// `str`, `path`, `lines`, `attrs`, `listOf`, `submodule`, an unknown or computed
+// type are all UNBOUNDED here: they can carry any characters, so nothing is
+// inferred from them.
+//
+// Two consumers use the answer in opposite directions, and both are sound for
+// the same reason:
+//   * the script-injection analysis treats a reference to a bounded option as
+//     a constant, because no value of that type contains a shell metacharacter;
+//   * the secret analysis does not treat a reference to a bounded option as a
+//     credential, because a bool, a number, a package path or a choice among
+//     listed words does not hold a secret, whatever the option is called
+//     (`cacheCredentials`, `forwardPass`, `wheelNeedsPassword`).
+//
+// Only options DECLARED in the files handed to the analyzer are known. An
+// option declared elsewhere (upstream NixOS) has no entry, so it keeps the
+// previous behaviour: unknown stays conservative.
+
+const unparen = (n) => { let x = n; while (x && x.type === 'paren') x = x.expr; return x; };
+const segName = (s) => (s && s.kind === 'static' ? s.name : null);
+const attrKey = (path) => (path || []).map(segName);
+
+const BOUNDED_LEAF = new Set(['bool', 'int', 'float', 'number', 'port', 'package', 'shellPackage', 'unsigned', 'positive', 'u8', 'u16', 'u32', 's8', 's16', 's32', 'between']);
+const BOUNDED_NAMESPACES = new Set(['ints', 'numbers']);
+const SAFE_ENUM_MEMBER = /^[A-Za-z0-9_.+-]*$/;
+
+function flatten(n) {
+  const args = []; let fn = unparen(n);
+  while (fn && fn.type === 'app') { args.unshift(fn.arg); fn = unparen(fn.fn); }
+  return { fn, args };
+}
+
+function calleeName(fn) {
+  const f = unparen(fn);
+  if (!f) return null;
+  if (f.type === 'ident') return f.name;
+  if (f.type === 'select') { const segs = f.attrpath.map(segName); return segs[segs.length - 1] || null; }
+  return null;
+}
+
+function selectSegments(n) {
+  const segs = n.attrpath.map(segName);
+  return segs.every((s) => s !== null) ? segs : null;
+}
+
+/** Classify a `type = ...` expression. Returns { kind, bounded }. */
+export function classifyOptionType(expr, depth = 0) {
+  const n = unparen(expr);
+  if (!n || depth > 8) return { kind: 'unknown', bounded: false };
+  if (n.type === 'ident') return { kind: n.name, bounded: BOUNDED_LEAF.has(n.name) };
+  if (n.type === 'select') {
+    const segs = selectSegments(n);
+    if (!segs) return { kind: 'unknown', bounded: false };
+    const last = segs[segs.length - 1];
+    if (segs.some((s) => BOUNDED_NAMESPACES.has(s))) return { kind: `${segs.slice(-2).join('.')}`, bounded: true };
+    return { kind: last, bounded: BOUNDED_LEAF.has(last) };
+  }
+  if (n.type === 'app') {
+    const { fn, args } = flatten(n);
+    const name = calleeName(fn);
+    const fnSel = unparen(fn);
+    if (fnSel && fnSel.type === 'select') {
+      const segs = selectSegments(fnSel);
+      if (segs && segs.some((s) => BOUNDED_NAMESPACES.has(s))) return { kind: segs.slice(-2).join('.'), bounded: true };
+    }
+    if (name === 'nullOr' || name === 'uniq' || name === 'unique') return args[0] ? classifyOptionType(args[0], depth + 1) : { kind: name, bounded: false };
+    if (name === 'either') {
+      const parts = args.slice(0, 2).map((a) => classifyOptionType(a, depth + 1));
+      return { kind: 'either', bounded: parts.length === 2 && parts.every((p) => p.bounded) };
+    }
+    if (name === 'enum') {
+      const list = unparen(args[0]);
+      if (list && list.type === 'list') {
+        const members = list.items.map((i) => unparen(i));
+        const ok = members.length > 0 && members.every((m) => m && m.type === 'string' && !m.interpolated && SAFE_ENUM_MEMBER.test(m.literal || ''));
+        return { kind: 'enum', bounded: ok };
+      }
+      return { kind: 'enum', bounded: false };
+    }
+    return { kind: name || 'unknown', bounded: false };
+  }
+  return { kind: 'unknown', bounded: false };
+}
+
+function declarationOf(valueNode) {
+  const v = unparen(valueNode);
+  if (!v || v.type !== 'app') return null;
+  const { fn, args } = flatten(v);
+  const name = calleeName(fn);
+  if (name === 'mkEnableOption') return { kind: 'bool', bounded: true };
+  if (name === 'mkPackageOption' || name === 'mkPackageOptionMD') return { kind: 'package', bounded: true };
+  if (name === 'mkOption') {
+    const a = unparen(args[0]);
+    if (!a || a.type !== 'attrset') return { kind: 'unknown', bounded: false };
+    for (const b of a.bindings || []) {
+      if (b.kind !== 'attr') continue;
+      const k = attrKey(b.path);
+      if (k.length === 1 && k[0] === 'type') return classifyOptionType(b.value);
+    }
+    return { kind: 'untyped', bounded: false };
+  }
+  return null;
+}
+
+function record(index, key, decl) {
+  const prev = index.get(key);
+  // two declarations of one option: bounded only if every declaration is
+  index.set(key, prev ? { kind: prev.kind, bounded: prev.bounded && decl.bounded } : decl);
+}
+
+function collect(node, prefix, index, depth) {
+  if (!node || typeof node !== 'object' || depth > 200) return;
+  if (Array.isArray(node)) { for (const x of node) collect(x, prefix, index, depth + 1); return; }
+  if (node.type === 'attrset') {
+    for (const b of node.bindings || []) {
+      if (b.kind !== 'attr' || !b.value) continue;
+      const keys = attrKey(b.path);
+      if (keys.some((k) => k === null)) { collect(b.value, null, index, depth + 1); continue; }
+      let full = null;
+      if (prefix !== null) full = [...prefix, ...keys];
+      else if (keys[0] === 'options') full = keys.slice(1);
+      if (full === null) { collect(b.value, null, index, depth + 1); continue; }
+      const decl = full.length ? declarationOf(b.value) : null;
+      if (decl) { record(index, full.join('.'), decl); continue; }
+      const v = unparen(b.value);
+      if (v && v.type === 'attrset') collect(v, full, index, depth + 1);
+      else collect(b.value, null, index, depth + 1);
+    }
+    return;
+  }
+  for (const [k, c] of Object.entries(node)) {
+    if (k === 'span' || k === 'loc') continue;
+    if (c && typeof c === 'object') collect(c, prefix === null ? null : null, index, depth + 1);
+  }
+}
+
+/**
+ * Index every option declared in the parsed files: dotted path -> { kind, bounded }.
+ * `parsed` is an iterable of ASTs.
+ */
+export function buildOptionTypeIndex(parsed) {
+  const index = new Map();
+  for (const ast of parsed) collect(ast, null, index, 0);
+  return index;
+}
+
+/**
+ * Is the option behind an origin detail (`option config.a.b.c`) declared with a
+ * bounded type? Returns the declaration, or null when it is unknown or unbounded.
+ */
+export function boundedOptionFor(index, detail) {
+  if (!index || typeof detail !== 'string') return null;
+  const m = /^option (?:config|osConfig)\.(.+)$/.exec(detail);
+  if (!m) return null;
+  const d = index.get(m[1]);
+  return d && d.bounded ? d : null;
+}