@clear-capabilities/agentic-security-scanner 0.195.12 → 0.195.14

package/src/language/haskell-parser.js

@@ -40,21 +40,90 @@ export const DEFAULT_PARSE_BUDGETS = Object.freeze({
 
 // Boundaries that are disclosed but do not make a file incomplete: the content was either parsed (cpp, ffi) or matched
 // by a closed, sound pattern and stated as an assumption (see haskell-boundaries.js).
-export const NON_OPAQUE_BOUNDARIES = new Set(['cpp', 'ffi', 'th-safe-splice', 'quasiquote-inert', 'quasiquote-hamlet']);
+export const NON_OPAQUE_BOUNDARIES = new Set(['cpp', 'ffi', 'th-safe-splice', 'quasiquote-inert', 'quasiquote-hamlet', 'quasiquote-interp']);
 
 // Shakespeare's HTML template quoters: the interpolations are Haskell expressions of the enclosing scope (see absorbSafeBoundaries).
 const HAMLET_QUOTERS = new Set(['hamlet', 'whamlet', 'shamlet', 'xhamlet', 'ihamlet', 'xshamlet']);
 
+// String-interpolating quoters: the body is TEXT with Haskell expressions spliced in, so `[i|SELECT .. '#{name}'|]` is a concatenation of the
+// text and `name`. Each is accepted only under an import of its documented module (a project quoter that borrows the name stays opaque),
+// and the interpolation syntax is the quoter's own: `#{e}` (string-interpolate, interpolate, shakespeare-text), `$name` / `${e}`
+// (neat-interpolation, `$$` escapes), `{e}` / `{e:spec}` (PyF, `{{` escapes). Names read from each package's Haddock index.
+const INTERP_QUOTERS = {
+  'Data.String.Interpolate': { syntax: 'hash', quoters: ['i', '__i', 'iii', "__i'E", "__i'L", "iii'E", "iii'L"] },
+  'Data.String.Interpolate.IsString': { syntax: 'hash', quoters: ['i'] },
+  'Text.Shakespeare.Text': { syntax: 'hash', quoters: ['st', 'lt', 'sbt', 'lbt', 'stext', 'ltext', 'text'] },
+  'NeatInterpolation': { syntax: 'dollar', quoters: ['text', 'trimming', 'untrimming'] },
+  'PyF': { syntax: 'brace', quoters: ['fmt', 'fmtTrim', 'str', 'strTrim'] },
+};
+
+/** The interpolations of a string-interpolating quoter's body (see INTERP_QUOTERS): `{open, exprStart, exprEnd, close, bare}` offsets. */
+export function interpolationsOf(seg, from, to, syntax) {
+  if (syntax === 'hash') return hamletInterpolations(seg, from, to, '#').map((it) => ({ ...it, exprEnd: it.close }));
+  const out = [];
+  const closeOf = (j) => {   // the index of the `}` matching the `{` before j, brace-nesting and string-aware; -1 when unclosed
+    let depth = 1, k = j, inStr = false;
+    for (; k < to && depth > 0; k++) {
+      const c = seg[k];
+      if (inStr) { if (c === '\\') k++; else if (c === '"') inStr = false; continue; }
+      if (c === '"') inStr = true;
+      else if (c === '{') depth++;
+      else if (c === '}') { depth--; if (depth === 0) return k; }
+    }
+    return -1;
+  };
+  if (syntax === 'dollar') {
+    for (let i = from; i < to; i++) {
+      if (seg[i] !== '$') continue;
+      if (seg[i + 1] === '$') { i++; continue; }
+      if (seg[i + 1] === '{') {
+        const close = closeOf(i + 2);
+        if (close < 0) continue;
+        if (close > i + 2) out.push({ open: i, exprStart: i + 2, exprEnd: close, close, bare: false });
+        i = close;
+      } else if (/[a-z_]/.test(seg[i + 1] || '')) {
+        let k = i + 1;
+        while (k < to && /[A-Za-z0-9_']/.test(seg[k])) k++;
+        out.push({ open: i, exprStart: i + 1, exprEnd: k, close: -1, bare: true });
+        i = k - 1;
+      }
+    }
+    return out;
+  }
+  if (syntax === 'brace') {
+    for (let i = from; i < to; i++) {
+      if (seg[i] !== '{') continue;
+      if (seg[i + 1] === '{') { i++; continue; }
+      const close = closeOf(i + 1);
+      if (close < 0) continue;
+      // `{expr:spec}`: the format spec after a top-level `:` is not an expression (a `:` inside brackets or quotes is part of the expression)
+      let exprEnd = close, depth = 0, inStr = false;
+      for (let k = i + 1; k < close; k++) {
+        const c = seg[k];
+        if (inStr) { if (c === '\\') k++; else if (c === '"') inStr = false; continue; }
+        if (c === '"') inStr = true;
+        else if (c === '(' || c === '[' || c === '{') depth++;
+        else if (c === ')' || c === ']' || c === '}') depth--;
+        else if (c === ':' && depth === 0) { exprEnd = k; break; }
+      }
+      if (exprEnd > i + 1) out.push({ open: i, exprStart: i + 1, exprEnd, close, bare: false });
+      i = close;
+    }
+    return out;
+  }
+  return out;
+}
+
 /**
  * The interpolations of a hamlet body, in order: `#{e}` (escaped value), `^{e}` (embedded template or widget), `@{r}` / `@?{r}` (route) and `_{m}`
  * (message). Braces nest (a record or a lambda inside), and a string literal may contain `}`. Returns offsets into the segment: the opener's
  * first character, the expression's first character, and the closing brace.
  */
-export function hamletInterpolations(seg, from, to) {
+export function hamletInterpolations(seg, from, to, markers = '#^@_') {
   const out = [];
   for (let i = from; i < to; i++) {
     const ch = seg[i];
-    if (!(ch === '#' || ch === '^' || ch === '@' || ch === '_')) continue;
+    if (!markers.includes(ch)) continue;
     let j = i + 1;
     if (ch === '@' && seg[j] === '?') j++;
     if (seg[j] !== '{') continue;
@@ -645,10 +714,18 @@ function analyze(source, file, dialect, ctx, res) {
     const items = [];
     let start = a;
     let i = a;
+    let lineCol = indent;   // column of the first token on the current line (the block's own indent on the line it opened on)
+    let nestedOnLine = false;   // a layout keyword opened a nested implicit block earlier on this line
     while (i < b) {
       ctx.tick();
       const t = T[i];
+      if (t.fol) { lineCol = t.lcol; nestedOnLine = false; }
+      if (t.k === 'kw' && (t.v === 'do' || t.v === 'of' || t.v === 'let' || t.v === 'where')) nestedOnLine = true;
       if (OPENERS[t.k] && match[i] > i) { i = match[i] + 1; continue; }
+      // In an implicit block a `;` separates items only on a line that starts at the block's own indent and opened no nested block before
+      // it: `s <- act pay; pure s` on one line of a nested `do` belongs to that `do`, and `remod t = do (a,_) <- f t; pure a` keeps its `;`
+      // in the `do` (hoogle; the same rule as haskell-syntax.js's splitItems).
+      if (t.k === ';' && indent !== null && (lineCol !== indent || nestedOnLine)) { i++; continue; }
       if (t.k === ';') {
         if (i > start) items.push({ a: start, b: i });
         start = i + 1;
@@ -678,6 +755,9 @@ function analyze(source, file, dialect, ctx, res) {
       ctx.tick();
       const t = T[j];
       if (j > a && t.fol && t.lcol < indent) break;
+      // Haskell's parse-error(t) rule: a `where` that starts a line at the block's own indent cannot begin an item, so it closes the
+      // implicit block (a function whose body is a `case` with its `where` at the alternatives' column; hoogle's request handler).
+      if (j > a && t.fol && t.lcol === indent && t.k === 'kw' && t.v === 'where') break;
       if (OPENERS[t.k] && match[j] > j) { j = match[j]; continue; }
       if (CLOSERS.has(t.k)) break;
       if (t.k === ',' && termComma) break;
@@ -1142,6 +1222,37 @@ function analyze(source, file, dialect, ctx, res) {
       b.assumption = 'upstream-quoter';
       res.blankRanges.push({ kind: 'quasiquote-hamlet', startOffset: b.span.startOffset, endOffset: b.span.endOffset, text });
     }
+    // String-interpolating quoters (`[i|SELECT .. '#{name}'|]`, INTERP_QUOTERS): rewritten in place, same length, same newlines, as
+    // `(iQ (e1) (e2))`, an application the IR lowers to a CONCATENATION of the interpolated expressions (haskell-ir.js), so text reaching a
+    // sink through the quoter is followed. The template text itself is not modelled (a text sink that needs a markup literal, `putStrLn`,
+    // does not fire through a quoter: a stated limit). A quoter of an unimported module, or an unknown quoter, stays an opaque boundary.
+    const interpModules = res.imports.map((im) => im.module).filter((m) => INTERP_QUOTERS[m]);
+    for (const b of res.boundaries) {
+      if (b.kind !== 'quasiquote' || !interpModules.length) continue;
+      const mod = interpModules.find((m) => INTERP_QUOTERS[m].quoters.includes(b.quoter));
+      if (!mod) continue;
+      const seg = source.slice(b.span.startOffset, b.span.endOffset);
+      const bar = seg.indexOf('|');
+      if (bar < 0 || !seg.endsWith('|]')) continue;
+      const interps = interpolationsOf(seg, bar + 1, seg.length - 2, INTERP_QUOTERS[mod].syntax);
+      if (!interps.length) continue;   // a literal-only body is left to the inert rule above
+      const chars = seg.split('').map((ch) => (ch === '\n' || ch === '\r' ? ch : ' '));
+      const put = (at, s) => { for (let i = 0; i < s.length; i++) if (chars[at + i] !== '\n' && chars[at + i] !== '\r') chars[at + i] = s[i]; };
+      put(0, '(iQ'.padEnd(bar + 1));
+      for (const it of interps) {
+        if (it.bare) { put(it.open, ' '); put(it.exprStart, seg.slice(it.exprStart, it.exprEnd)); continue; }   // `$name`: the name at its offset
+        put(it.open, ' ('.slice(-(it.exprStart - it.open)).padStart(it.exprStart - it.open));   // `#{`, `${` become ` (`; `{` becomes `(`
+        put(it.exprStart, seg.slice(it.exprStart, it.exprEnd));
+        put(it.close, ')');
+      }
+      put(seg.length - 2, ')');
+      const text = chars.join('');
+      if (text.length !== seg.length) continue;
+      b.kind = 'quasiquote-interp';
+      b.detail = `quasi-quote [${b.quoter}|...|] with ${interps.length} interpolation(s), read as the concatenation of the interpolated expressions (analysed in the enclosing scope); the template text is not modelled; ASSUMED to be the ${mod} quoter`;
+      b.assumption = 'upstream-quoter';
+      res.blankRanges.push({ kind: 'quasiquote-interp', startOffset: b.span.startOffset, endOffset: b.span.endOffset, text });
+    }
   }
 
   // ── errors → withheld calls ──
@@ -1229,7 +1340,7 @@ export function preprocessForSyntaxInfo(source, opts = {}) {
     const seg = out.slice(b.startOffset, b.endOffset);
     let repl = blank(seg);
     if (b.kind === 'quasiquote-inert' && repl.length >= 2) repl = `"${repl.slice(1, -1)}"`;
-    if (b.kind === 'quasiquote-hamlet' && typeof b.text === 'string' && b.text.length === seg.length) repl = b.text;   // the interpolations, at their offsets
+    if ((b.kind === 'quasiquote-hamlet' || b.kind === 'quasiquote-interp') && typeof b.text === 'string' && b.text.length === seg.length) repl = b.text;   // the interpolations, at their offsets
     out = out.slice(0, b.startOffset) + repl + out.slice(b.endOffset);
   }
   return { text: out, opaque };

package/src/language/haskell-syntax.js

@@ -18,6 +18,11 @@ const KW = new Set(['case', 'class', 'data', 'default', 'deriving', 'do', 'else'
 const NUMERIC_TYPE = /^\(?\s*(?:(?:Maybe|IO|ActionM|Handler|Either\s+String)\s+)?\(?\s*(?:Int|Integer|Int(?:8|16|32|64)|Word|Word(?:8|16|32|64)|Double|Float|Natural|Bool|Scientific)\s*\)?\s*\)?$/;
 // The module enables Template Haskell (a LANGUAGE pragma; a cabal `default-extensions` entry is not seen here, a stated limit).
 const TH_PRAGMA = /\{-#\s*LANGUAGE\b[^#]*\bTemplateHaskell\b/;
+// OverloadedRecordDot: `r.field` (no spaces, lowercase field) is a field selection, `(.field)` a selector section. OverloadedLabels: `#field`
+// in prefix position is a label value (IHP's `get #name r`, `set #name v r`). Both read from the LANGUAGE pragma only, as above.
+const RECORD_DOT_PRAGMA = /\{-#\s*LANGUAGE\b[^#]*\bOverloadedRecordDot\b/;
+const LABELS_PRAGMA = /\{-#\s*LANGUAGE\b[^#]*\bOverloadedLabels\b/;
+const RECDO_PRAGMA = /\{-#\s*LANGUAGE\b[^#]*\bRecursiveDo\b/;
 const RESERVED_OPS = new Set(['=', '|', '->', '<-', '::', '=>', '\\', '@', '~', '..']);
 const SYM = new Set('!#$%&*+./<=>?@\\^|-~:'.split(''));
 const OPEN = { '(': ')', '[': ']', '{': '}' };
@@ -36,6 +41,9 @@ export function lexHs(src, opts = {}) {
   const T = [];
   const n = src.length;
   const thSplices = !!opts.th;
+  const recordDot = !!opts.recordDot;
+  const labels = !!opts.labels;
+  const recursiveDo = !!opts.recursiveDo;
   let i = 0;
   let line = 1;
   let col = 0;
@@ -138,7 +146,9 @@ export function lexHs(src, opts = {}) {
       let k = i;
       while (isIdChar(src[k])) k++;
       const v = src.slice(i, k);
-      push(KW.has(v) ? 'kw' : 'var', v, {}, k - i);
+      // `mdo` (RecursiveDo) is a `do` whose statements may refer to later ones; for the lowering that is a `do`. (`rec` blocks are not read.)
+      if (v === 'mdo' && recursiveDo) push('kw', 'do', {}, k - i);
+      else push(KW.has(v) ? 'kw' : 'var', v, {}, k - i);
       continue;
     }
     if (c === '(' || c === ')' || c === '[' || c === ']' || c === ',' || c === ';' || c === '`' || c === '{' || c === '}') {
@@ -153,6 +163,22 @@ export function lexHs(src, opts = {}) {
       const prefix = !(isIdChar(prev) || isSym(prev) || prev === ')' || prev === ']' || prev === '}' || prev === '"' || prev === "'");
       if (prefix && (src[k] === '(' || (isIdStart(src[k]) && !isUpper(src[k])))) { push('splice', src.slice(i, k), {}, k - i); continue; }
     }
+    // `r.field` / `(e).field` / `r.a.b` with OverloadedRecordDot: a `.` touching an identifier, `)` or `}` on its left and a lowercase name on
+    // its right is a field selection (`sel` token), never composition (GHC reads it the same way under the extension). `(.field)` is the
+    // selector section: a `.` touching `(` on its left.
+    if (c === '.' && recordDot && isIdStart(src[i + 1]) && !isUpper(src[i + 1]) && i > 0 && (isIdChar(src[i - 1]) || src[i - 1] === ')' || src[i - 1] === '}' || src[i - 1] === '(')) {
+      let m = i + 1;
+      while (isIdChar(src[m])) m++;
+      push('sel', src.slice(i + 1, m), { section: src[i - 1] === '(' }, m - i);
+      continue;
+    }
+    // `#field` with OverloadedLabels, in prefix position: a label value.
+    if (c === '#' && labels && isIdStart(src[i + 1]) && !isUpper(src[i + 1]) && (i === 0 || !(isIdChar(src[i - 1]) || isSym(src[i - 1]) || src[i - 1] === ')' || src[i - 1] === ']'))) {
+      let m = i + 1;
+      while (isIdChar(src[m])) m++;
+      push('label', src.slice(i + 1, m), {}, m - i);
+      continue;
+    }
     if (isSym(c)) {
       let j = i;
       while (isSym(src[j])) j++;
@@ -196,7 +222,7 @@ const BT_FIX = { elem: [4, 'l'], notElem: [4, 'l'], div: [7, 'l'], mod: [7, 'l']
  * @returns {{tokens:object[], module:object|null, imports:object[], decls:object[], sigs:object[], data:object[], classes:object[], instances:object[], errors:object[], boundaries:object[]}}
  */
 export function parseSyntax(src, opts = {}) {
-  const T = lexHs(src, { th: TH_PRAGMA.test(src) });
+  const T = lexHs(src, { th: TH_PRAGMA.test(src), recordDot: RECORD_DOT_PRAGMA.test(src), labels: LABELS_PRAGMA.test(src), recursiveDo: RECDO_PRAGMA.test(src) });
   const mate = matchBrackets(T);
   const N = T.length;
   const errors = [];
@@ -255,9 +281,15 @@ export function parseSyntax(src, opts = {}) {
     const items = [];
     let start = a;
     let i = a;
+    // A `;` separates items of THIS block only when the line starts at the block's indent (or is the line the block opened on) and no
+    // layout keyword opened a nested implicit block earlier on that line: `remod t = do (a,_) <- f t; pure a` keeps the `;` in the `do`.
+    let lineCol = indent;
+    let nestedOnLine = false;
     while (i < b) {
       tick();
       const t = T[i];
+      if (t.first) { lineCol = t.col; nestedOnLine = false; }
+      if ((t.t === 'kw' && (t.v === 'do' || t.v === 'of' || t.v === 'let' || t.v === 'where')) || (isRop(t, '\\') && isKw(T[i + 1], 'case'))) nestedOnLine = true;
       // A new line at the block's indent starts a new item EVEN when that line opens a bracket
       // (`("GET", ["a"]) -> ...`): the boundary test must run before the bracket is skipped.
       if (indent !== null && i > start && t.first && t.col === indent && !isSp(t, ';')) {
@@ -265,6 +297,10 @@ export function parseSyntax(src, opts = {}) {
         start = i;
       }
       if (t.t === 'sp' && OPEN[t.v] && mate[i] > i) { i = mate[i] + 1; continue; }
+      // `s <- act pay; bs <- evaluate s; pure (s, bs)` on one line of a nested `do`: those semicolons separate the statements of the
+      // nested block, not the items of an enclosing implicit block (the module's top level split on them and read `bs <- ..` as a
+      // declaration; real code, hoogle). In an implicit block a `;` counts only on a line that starts at the block's own indent.
+      if (isSp(t, ';') && indent !== null && (lineCol !== indent || nestedOnLine)) { i++; continue; }
       if (isSp(t, ';')) {
         if (i > start) items.push([start, i]);
         start = i + 1;
@@ -459,6 +495,19 @@ export function parseSyntax(src, opts = {}) {
         pos = blk.b;
         return { t: 'lamcase', alts: withIndent(blk.indent, () => blk.items.map(([a, b]) => parseAlt(a, b))), line: t.line };
       }
+      // `\cases` (GHC 9.4): alternatives with SEVERAL patterns each, `0 y -> ..; x y -> ..`.
+      if (peek() && peek().t === 'var' && peek().v === 'cases') {
+        const blk = blockAfter(pos, lim, layoutIndent);
+        pos = blk.b;
+        const parseAltMulti = (a, b) => {
+          const k = findTop(a, b, (x) => isRop(x, '->') || isRop(x, '|'));
+          if (k < 0) { err('expected-arrow', T[a], 'case alternative has no `->`'); return { pats: [{ t: 'pwild' }], rhs: { guards: null, body: { t: 'unknown' }, where: [] }, line: T[a].line, bad: true }; }
+          const pats = [];
+          for (let q = a; q < k;) { const r = apatAt(q, k); if (!r) break; pats.push(r[0]); q = r[1]; }
+          return { pats, rhs: parseRhs(k, b, '->'), line: T[a].line };
+        };
+        return { t: 'lamcases', alts: withIndent(blk.indent, () => blk.items.map(([a, b]) => parseAltMulti(a, b))), line: t.line };
+      }
       const params = [];
       while (pos < lim && !isRop(T[pos], '->')) {
         const r = apatAt(pos, lim);
@@ -522,7 +571,7 @@ export function parseSyntax(src, opts = {}) {
   function startsAexp() {
     const t = peek();
     if (!t) return false;
-    if (t.t === 'var' || t.t === 'con' || t.t === 'int' || t.t === 'float' || t.t === 'str' || t.t === 'chr' || t.t === 'splice') return true;
+    if (t.t === 'var' || t.t === 'con' || t.t === 'int' || t.t === 'float' || t.t === 'str' || t.t === 'chr' || t.t === 'splice' || t.t === 'label') return true;
     return isSp(t, '(') || isSp(t, '[');
   }
   function fexp() {
@@ -555,6 +604,7 @@ export function parseSyntax(src, opts = {}) {
       else if (peek() && peek().t === 'var') pos++;
       return { t: 'splice', line: t.line };
     }
+    else if (t.t === 'label') { pos++; e = { t: 'label', name: t.v, line: t.line }; }
     else { err('unexpected-token', t, `unexpected token ${t.v}`); pos++; return { t: 'unknown', line: t.line }; }
     while (isSp(peek(), '{') && mate[pos] > pos && mate[pos] < lim && (e.t === 'con' || e.t === 'var' || e.t === 'rec' || e.t === 'paren')) {
       const close = mate[pos];
@@ -570,6 +620,8 @@ export function parseSyntax(src, opts = {}) {
       e = e.t === 'con' ? { t: 'rec', con: e, fields, line: t.line } : { t: 'recupd', base: e, fields, line: t.line };
       pos = close + 1;
     }
+    // `e.field` (OverloadedRecordDot): the field selector applied to `e`, which the IR lowers to a member read of a known record field.
+    while (peek() && peek().t === 'sel' && !peek().section) { const s = peek(); pos++; e = { t: 'app', f: { t: 'var', name: s.v, qual: null, line: s.line }, args: [e], line: s.line, recordDot: true }; }
     return e;
   }
   const isOpTok = (x) => x && x.t === 'op';
@@ -584,6 +636,8 @@ export function parseSyntax(src, opts = {}) {
     }
     const [s, e] = parts[0];
     const first = T[s];
+    // `(.field)` (OverloadedRecordDot): the selector function itself.
+    if (first && first.t === 'sel' && first.section && e - s === 1) return { t: 'var', name: first.v, qual: null, line };
     if (isOpTok(first) && e - s === 1) return { t: 'var', name: first.v, qual: first.q || null, op: true, line };
     if (isOpTok(first) && first.v !== '-') return { t: 'rsec', op: first.v, qual: first.q || null, e: sub(s + 1, e, expr0), line };
     if (isSp(first, '`') && T[s + 2] && isSp(T[s + 2], '`') && e - s > 3) return { t: 'rsec', op: T[s + 1].v, qual: T[s + 1].q || null, e: sub(s + 3, e, expr0), line, backtick: true };
@@ -690,6 +744,9 @@ export function parseSyntax(src, opts = {}) {
     return out;
   }
   function parseDecl(a, b) {
+    // `pattern P :: T` / `pattern P x = ..` (PatternSynonyms): a synonym, recorded by name, not a function called `pattern`. Its right-hand
+    // side is not modelled (a match on `P` is a constructor pattern to the IR, which is sound for taint: it binds what it binds).
+    if (T[a].t === 'var' && T[a].v === 'pattern' && T[a + 1] && T[a + 1].t === 'con' && a + 1 < b) return { t: 'patsyn', name: T[a + 1].v, line: T[a].line };
     const mark = findTop(a, b, (x) => x.t === 'rop' && (x.v === '=' || x.v === '|' || x.v === '::'));
     if (mark < 0) { err('expected-declaration', T[a], 'item is neither a binding nor a signature'); return null; }
     if (T[mark].v === '::') {
@@ -744,7 +801,39 @@ export function parseSyntax(src, opts = {}) {
     let nameTok = null;
     for (let q = a + 1; q < (eq < 0 ? b : eq); q++) if (T[q].t === 'con') { nameTok = T[q]; break; }
     const decl = { t: 'data', newtype: isNewtype, name: nameTok ? nameTok.v : null, constructors: [], line: T[a].line };
-    if (eq < 0) return decl;
+    if (eq < 0) {
+      // GADT syntax: `data T where { A :: Int -> T; B :: { fld :: String } -> T }`. Each item names one or more constructors, their record
+      // fields when written with braces, else an arity of one per top-level arrow; the result type is not read (no type checking).
+      const w = findTop(a, b, (x) => isKw(x, 'where'));
+      if (w < 0) return decl;
+      const blk = blockAfter(w, b, layoutIndent);
+      for (const [s, e] of blk.items) {
+        const names = [];
+        let i = s;
+        while (i < e && T[i].t === 'con') { names.push(T[i].v); i++; if (isSp(T[i], ',')) i++; else break; }
+        if (!names.length || !isRop(T[i], '::')) continue;
+        i++;
+        while (i < e && ((T[i].t === 'var' && T[i].v === 'forall') || T[i].t === 'op' || isRop(T[i], '=>'))) i = findTop(i, e, (x) => isRop(x, '=>')) >= 0 ? findTop(i, e, (x) => isRop(x, '=>')) + 1 : e;
+        let fields = null;
+        let arity = 0;
+        if (isSp(T[i], '{') && mate[i] > i) {
+          fields = [];
+          const close = mate[i];
+          let j = i + 1;
+          while (j < close) {
+            const ns = [];
+            while (j < close && T[j].t === 'var') { ns.push(T[j].v); j++; if (isSp(T[j], ',')) j++; else break; }
+            if (isRop(T[j], '::')) { j++; while (j < close && !isSp(T[j], ',')) j = Math.min(close, groupEnd(j)); j++; } else break;
+            fields.push(...ns);
+          }
+          arity = fields.length;
+        } else {
+          for (let j = i; j < e;) { if (isRop(T[j], '->')) arity++; j = Math.min(e, groupEnd(j)); }
+        }
+        for (const n of names) decl.constructors.push({ name: n, fields, arity });
+      }
+      return decl;
+    }
     let end = findTop(eq + 1, b, (x) => isKw(x, 'deriving'));
     if (end < 0) end = b;
     for (const [s0, e] of splitTop(eq + 1, end, (x) => isRop(x, '|'))) {

package/src/posture/CLAUDE.md

@@ -129,6 +129,11 @@ is also true of a scan that read zero files — so when nothing was examined eve
 mapped control degrades to `engine-gap` instead of reporting as satisfied. That
 one was caught by the module's own test, not in review.
 
+**API contract diff** — `api-contract.js`. Cross-references OpenAPI/GraphQL contract files against the detected routes. A contract found
+inside one package of a monorepo governs that package's routes only (`contractScope`: the nearest ancestor of the file with a package
+manifest, else the scan root); two example OpenAPI files in a servant monorepo had produced 78 "implemented but not declared"
+routes across every other package. `test/api-contract-scope.test.js`.
+
 **Posture artifacts** — `sbom.js`, `aibom.js`, `api-inventory.js`, `threat-model.js`, `trust-boundary-diagram.js`, `stack-playbook.js`, `deploy-platform.js`, `license-policy.js`, `material-change.js`, `mttr.js`, `streak.js`, `accuracy-scorecard.js` (see "Published accuracy scorecard (R3)" above — this line previously named a bare "scorecard" module that never existed under that filename), `security-trend.js`.
 
 **Why this fired** — `why-fired.js`. Runs LAST so it reflects every annotation. Customer-facing provenance.

package/src/posture/api-contract.js

@@ -185,9 +185,47 @@ export function runApiContractScan(scanRoot, codeRoutes) {
     if (c.kind === 'openapi') contractRoutes = parseOpenAPI(c.doc);
     else if (c.kind === 'graphql') contractRoutes = parseGraphQL(c.doc);
     contractRoutes.forEach(r => { r.contractFile = c.path; });
-    findings.push(...diffRoutes(contractRoutes, codeRoutes || []));
+    findings.push(...diffRoutes(contractRoutes, routesGovernedBy(c.path, scanRoot, codeRoutes || [])));
   }
   return findings;
 }
 
+// A manifest that makes a directory a package of its own: the contract found inside such a package describes that package's API.
+const PACKAGE_MANIFEST = /^(?:package\.json|pyproject\.toml|setup\.py|setup\.cfg|go\.mod|pom\.xml|build\.gradle(?:\.kts)?|Cargo\.toml|composer\.json|Gemfile|mix\.exs|package\.yaml|[^/]+\.cabal|[^/]+\.csproj|[^/]+\.fsproj)$/i;
+
+function hasPackageManifest(dir) {
+  try { return fs.readdirSync(dir).some((n) => PACKAGE_MANIFEST.test(n)); } catch { return false; }
+}
+
+/**
+ * The directory a contract file governs: the nearest ancestor of the file (up to the scan root) that holds a package manifest. A contract at
+ * the scan root's own package, or in a directory with no package above it, governs every route as before.
+ *
+ * Why: a monorepo's packages each carry their own API; an example `swagger.json` three packages away does not declare the routes of the
+ * others. Scanned over a servant monorepo, two example contracts in `servant-swagger/example` and `servant-openapi3/example` produced 78
+ * "implemented but not declared" routes across every other package, each twice. Scoping by package keeps the single-package case unchanged.
+ */
+export function contractScope(contractPath, scanRoot) {
+  const top = path.resolve(scanRoot);
+  let dir = path.dirname(path.resolve(contractPath));
+  while (true) {
+    if (dir === top) return top;
+    if (!dir.startsWith(top + path.sep)) return top;   // outside the scan root: no narrower scope can be claimed
+    if (hasPackageManifest(dir)) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return top;
+    dir = up;
+  }
+}
+
+function routesGovernedBy(contractPath, scanRoot, codeRoutes) {
+  const scope = contractScope(contractPath, scanRoot);
+  if (scope === path.resolve(scanRoot)) return codeRoutes;
+  return codeRoutes.filter((r) => {
+    if (!r || typeof r.file !== 'string') return false;
+    const abs = path.resolve(scanRoot, r.file);
+    return abs === scope || abs.startsWith(scope + path.sep);
+  });
+}
+
 export const _internals = { CONTRACT_FILE_PATTERNS, parseOpenAPI, parseGraphQL };