@portll/cobolwork 0.2.150 → 0.4.0

package/lib/control.mjs

@@ -1775,7 +1775,10 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
     const needs = [...new Set([lo && lo.bit, hi && hi.bit].filter((x) => x != null))].sort((x, y) => x - y);
     const from = lo ? lo.v : base.lo;
     const to = hi ? hi.v : base.hi;
-    return needs.length && from <= to ? [base, { needs, lo: from, hi: to }] : [base];
+    if (!needs.length || from > to) return [base];
+    // Each end alone as well, so a result that needs only one of them does not wait on the other.
+    const ends = lo && hi && lo.bit !== hi.bit ? [{ needs: [lo.bit], lo: lo.v, hi: base.hi }, { needs: [hi.bit], lo: base.lo, hi: hi.v }] : [];
+    return [base, { needs, lo: from, hi: to }, ...ends];
   };
   // A fact "the field holds a whole number from lo to hi" (either end may be open), one per field and interval.
   const derivedOf = new Map();
@@ -1815,6 +1818,10 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
   // is not among them: the interval is what the data holds, not a test that ran.
   const withLooser = (fact) => {
     const out = [fact.t];
+    if (fact.pair) {
+      for (const [k, other] of pairFacts.get(fact.pairKey)) if (k > fact.k && (fact.pair === 'span' || other.a === fact.a)) out.push(other.t);
+      return out;
+    }
     const own = fact.bounds;
     for (const c of factsByKey.get(fact.key) || []) {
       if (c === fact || !c.derived) continue;
@@ -2047,6 +2054,108 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
     relations.clear();
   }
 
+  // Facts over two whole-number fields, killed by a write to either: "A - B <= k" (an order) and
+  // "A + B <= k" (a span, which keeps a reference modification X(A:B) inside X). They are drawn
+  // only for the start and length of a reference modification and the fields a length is computed from.
+  const spanPairs = new Map();
+  for (const st of prog.statements) {
+    for (const x of st.indexes || []) {
+      if (x.kind !== 'refmod-length' || !x.from || !x.from.tok) continue;
+      const len = x.tok && x.tok.t === 'word' ? resolve(x.tok) : null;
+      const start = resolve(x.from.tok);
+      if (!len || !start || len === start || !rangeOfField(len) || !rangeOfField(start) || inTable(len) || inTable(start)) continue;
+      if (!spanPairs.has(len)) spanPairs.set(len, new Set());
+      spanPairs.get(len).add(start);
+    }
+  }
+  const starts = new Set([...spanPairs.values()].flatMap((s) => [...s]));
+  const pairIds = new Map();
+  const pairId = (f) => { if (!pairIds.has(f)) pairIds.set(f, pairIds.size); return pairIds.get(f); };
+  const pairFacts = new Map();
+  const pairKey = (kind, a, b) => (kind === 'span' && pairId(a) > pairId(b) ? `${kind}|${pairId(b)}|${pairId(a)}` : `${kind}|${pairId(a)}|${pairId(b)}`);
+  const pairFact = (kind, a, b, k, at) => {
+    const key = pairKey(kind, a, b);
+    if (!pairFacts.has(key)) pairFacts.set(key, new Map());
+    const mine = pairFacts.get(key);
+    if (mine.has(k)) return mine.get(k);
+    if (!arithBudget()) return null;
+    const fact = { pair: kind, pairKey: key, a, b, k, t: nFacts++, file: at.file, line: at.line };
+    for (const f of [a, b]) {
+      const fk = fieldKey(f);
+      noteField(fk, f);
+      checks.push({ pseudo: true, key: fk, field: f, x: null, t: fact.t, f: null });
+    }
+    mine.set(k, fact);
+    return fact;
+  };
+  // What an outcome makes true of two fields, as order and span facts: S <= E, S + L - 1 <= 80.
+  const pairsOf = (rel, pol) => {
+    const op = pol ? rel.op : NEGATE[rel.op];
+    if (!['<', '<=', '>', '>=', '='].includes(op)) return [];
+    const l = linearOf(rel.left), r = linearOf(rel.right);
+    const e = l && r ? linAdd(l, r, -1) : null;
+    if (!e || e.terms.size !== 2 || e.lo !== e.hi || !Number.isInteger(e.lo)) return [];
+    const out = [];
+    // e op 0 as one or two facts "sum <= k" over the terms, each with its signs.
+    const below = (sign, strict) => {
+      const terms = [...e.terms].map(([f, c]) => [f, sign * c]);
+      if (terms.some(([f, c]) => Math.abs(c) !== 1 || !rangeOfField(f) || inTable(f))) return;
+      const k = -sign * e.lo - (strict ? 1 : 0);
+      const [[a, ca], [b, cb]] = terms;
+      if (ca > 0 && cb > 0) { if ((spanPairs.get(a)?.has(b)) || (spanPairs.get(b)?.has(a))) out.push(['span', a, b, k]); }
+      else if (ca > 0 && cb < 0) { if (starts.has(a)) out.push(['order', a, b, k]); }
+      else if (ca < 0 && cb > 0) { if (starts.has(b)) out.push(['order', b, a, k]); }
+    };
+    if (op === '<' || op === '<=' || op === '=') below(1, op === '<');
+    if (op === '>' || op === '>=' || op === '=') below(-1, op === '>');
+    return out;
+  };
+  if (spanPairs.size) {
+    for (const id of tests) {
+      const n = nodes[id];
+      if (!n.tree) continue;
+      for (const o of [true, false]) {
+        const at = outcomeAt.get(`${id}|${o}`);
+        if (!at) continue;
+        for (const { rel, pol } of relationsOf(n.tree, o)) {
+          for (const [kind, a, b, k] of pairsOf(rel, pol)) {
+            const fact = pairFact(kind, a, b, k, n.at || n.st);
+            if (fact) derive(at, [], fact, String(o));
+          }
+        }
+      }
+    }
+  }
+  // The statements that only raise a field of a span, by at most `max`.
+  const spanRaisers = [];
+  if (spanPairs.size) {
+    const spanFields = new Set([...spanPairs.keys(), ...starts]);
+    nodes.forEach((n, id) => {
+      if (n.kind !== 'stmt' || !n.st || n.st.at == null) return;
+      const inc = increments(n.st);
+      if (inc && inc.fields.some((f) => spanFields.has(f))) spanRaisers.push({ id, inc, wrote: writtenBy(n) });
+    });
+  }
+  const spanLifted = new Set();
+  // An arithmetic tree as whole-number coefficients per plain field plus a whole constant, or null.
+  const linearTree = (t) => {
+    switch (t.k) {
+      case 'const': return t.v.d === 1n ? { terms: new Map(), c: Number(t.v.n) } : null;
+      case 'field': return t.plain ? { terms: new Map([[t.f, 1]]), c: 0 } : null;
+      case 'neg': { const a = linearTree(t.a); return a && { terms: new Map([...a.terms].map(([f, c]) => [f, -c])), c: -a.c }; }
+      case 'bin': {
+        if (t.op !== '+' && t.op !== '-') return null;
+        const a = linearTree(t.a), b = linearTree(t.b);
+        if (!a || !b) return null;
+        const sign = t.op === '+' ? 1 : -1;
+        const terms = new Map(a.terms);
+        for (const [f, c] of b.terms) { const v = (terms.get(f) || 0) + sign * c; if (v) terms.set(f, v); else terms.delete(f); }
+        return { terms, c: a.c + sign * b.c };
+      }
+      default: return null;
+    }
+  };
+
   // The fields that matter: those an index reads, and those that flow into them through the
   // statements above and the relations between fields.
   const relevant = new Set();
@@ -2092,16 +2201,59 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
       a.trees.forEach((tree, i) => {
         const r = a.targets[i];
         if (!tree || !r.f || !rangeOfField(r.f) || inTable(r.f) || !relevant.has(r.f)) return;
-        const fit = rangeOfField(r.f).fit;
+        const { fit, hold } = rangeOfField(r.f);
         heldBits = prev ? prev.get(a.n.id) || null : null;
         for (const c of candidates(tree, leafCands, 64)) {
           const s = storedRange(c.iv, r.rounded);
-          if (s.lo < fit.lo || s.hi > fit.hi || (s.lo === fit.lo && s.hi === fit.hi)) continue;
-          const fact = derivedFact(r.f, s.lo, s.hi, a.n.st);
+          if (s.lo === fit.lo && s.hi === fit.hi) continue;
+          // A result past one end of what the field keeps loses high digits and keeps its sign, and no
+          // result past what the storage holds is added, so the other end still bounds it.
+          const whole = s.lo >= fit.lo && s.hi <= fit.hi;
+          const top = whole || (s.lo >= hold.lo && s.hi <= fit.hi && (s.hi >= 0n || s.lo >= fit.lo));
+          const bottom = whole || (s.hi <= hold.hi && s.lo >= fit.lo && (s.lo <= 0n || s.hi <= fit.hi));
+          if (!top && !bottom) continue;
+          const fact = derivedFact(r.f, bottom ? s.lo : null, top ? s.hi : null, a.n.st);
           if (fact && derive(a.n, c.needs, fact)) grew = true;
         }
       });
     }
+    // A length computed as E - S + c from its start S, where S <= E + d held, is at least c - d, which
+    // intervals alone cannot see; and S + L is then E + c, at most what E could hold plus c.
+    for (const a of arith) {
+      a.trees.forEach((tree, i) => {
+        const r = a.targets[i];
+        const mates = r.f && spanPairs.get(r.f);
+        const lin = mates && tree ? linearTree(tree) : null;
+        if (!lin) return;
+        const fit = rangeOfField(r.f).fit;
+        heldBits = prev ? prev.get(a.n.id) || null : null;
+        for (const [s, cs] of lin.terms) {
+          if (cs !== -1 || !mates.has(s) || s === r.f) continue;
+          const rest = [...lin.terms].filter(([f]) => f !== s);
+          if (rest.length > 1 || (rest.length && (rest[0][1] !== 1 || rest[0][0] === r.f))) continue;
+          const e = rest.length ? rest[0][0] : null;
+          const orders = e ? [...(pairFacts.get(pairKey('order', s, e))?.values() || [])] : [];
+          const eCands = e ? leafCands({ f: e, tok: null, plain: true }) : [{ needs: [], lo: 0n, hi: 0n }];
+          const sCands = leafCands({ f: s, tok: null, plain: true });
+          // With no E, the lowest L is c less S's highest, which an interval of S already gives.
+          const floors = e ? orders.map((o) => ({ needs: [o.t], lo: BigInt(lin.c - o.k) })) : sCands.map((sc) => ({ needs: sc.needs, lo: BigInt(lin.c) - sc.hi }));
+          for (const fl of floors) {
+            if (fl.lo < fit.lo) continue;
+            for (const ec of eCands) {
+              for (const sc of sCands) {
+                const hi = ec.hi - sc.lo + BigInt(lin.c);
+                if (hi > fit.hi || hi < fl.lo) continue;
+                const needs = [...new Set([...fl.needs, ...ec.needs, ...sc.needs])].sort((x, y) => x - y);
+                const fact = derivedFact(r.f, fl.lo, hi, a.n.st);
+                if (fact && derive(a.n, needs, fact)) grew = true;
+                const span = pairFact('span', s, r.f, Number(ec.hi) + lin.c, a.n.st);
+                if (span && derive(a.n, needs, span)) grew = true;
+              }
+            }
+          }
+        }
+      });
+    }
     for (const rel of relations.values()) {
       if (!relevant.has(rel.f) && !relevant.has(rel.g)) continue;
       const at = nodes[rel.test].at || nodes[rel.test].st;
@@ -2124,6 +2276,24 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
         }
       }
     }
+    // An increment of a span's field by at most n leaves the span n looser: the sum grows by n at most,
+    // and a sum that wraps or is cut short is only lower.
+    for (const { id, inc, wrote } of spanRaisers) {
+      const held = prev ? prev.get(id) : null;
+      if (!held) continue;
+      for (const mine of pairFacts.values()) {
+        for (const f of [...mine.values()]) {
+          if (f.pair !== 'span' || !hasFact(held, f.t)) continue;
+          const count = [f.a, f.b].filter((x) => inc.fields.includes(x)).length;
+          if (!count || wrote.some((w) => !inc.fields.includes(w) && (overlaps(w, f.a) || overlaps(w, f.b)))) continue;
+          const to = pairFact('span', f.a, f.b, f.k + count * inc.max, nodes[id].st);
+          if (!to || spanLifted.has(`${id}|${f.t}|${to.t}`)) continue;
+          spanLifted.add(`${id}|${f.t}|${to.t}`);
+          (nodes[id].spanLifts ||= []).push([f.t, to.t]);
+          grew = true;
+        }
+      }
+    }
     // A bound over an expression in one other field, X <= G - 1, takes the interval G holds at the test.
     for (const c of checks) {
       if (c.pseudo || c.test == null || !relevant.has(c.field) || !rangeOfField(c.field) || inTable(c.field)) continue;
@@ -2340,6 +2510,10 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
   const killScratch = new Uint32Array(words);
   // A summary is joined to whatever enters the range, so it cannot assume a guard the caller lacks.
   let summarising = false;
+  // While summarising, a fact that depends on others is taken only where the range's own statements
+  // make those others on every route: then it holds whatever the caller brings.
+  let approved = null;
+  const has = (bits, x) => (bits[x >>> 5] & (1 << (x & 31))) !== 0;
   // What holds after a node, in a buffer reused by every call: the caller merges it into the next
   // node's facts before calling again. Null where the route ends here.
   const transfer = (n, input) => {
@@ -2362,7 +2536,7 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
         kill = killScratch;
         kill.set(n.kill);
         for (const k of n.keeps) {
-          if (k.guards && (summarising || !k.guards.some((g) => input[g >>> 5] & (1 << (g & 31))))) continue;
+          if (k.guards && (summarising ? !approved.has(k) : !k.guards.some((g) => has(input, g)))) continue;
           for (let i = 0; i < words; i++) kill[i] &= ~k.bits[i];
         }
       }
@@ -2377,26 +2551,36 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
     // An increment that cannot wrap raises the lower bounds that held before it.
     if (n.lifts) {
       for (const { pairs, guards } of n.lifts) {
-        if (summarising || !guards.some((g) => input[g >>> 5] & (1 << (g & 31)))) continue;
-        for (const [from, to] of pairs) {
-          if (!(input[from >>> 5] & (1 << (from & 31)))) continue;
+        if (!summarising && !guards.some((g) => has(input, g))) continue;
+        for (const pair of pairs) {
+          const [from, to] = pair;
+          if (summarising ? !approved.has(pair) : !has(input, from)) continue;
           if (out === input) { scratch.set(input); out = scratch; }
           out[to >>> 5] |= 1 << (to & 31);
         }
       }
     }
+    if (n.spanLifts) {
+      for (const pair of n.spanLifts) {
+        const [from, to] = pair;
+        if (summarising ? !approved.has(pair) : !has(input, from)) continue;
+        if (out === input) { scratch.set(input); out = scratch; }
+        out[to >>> 5] |= 1 << (to & 31);
+      }
+    }
     // What a statement or a test leaves in a field, where the facts its operands needed held before it.
-    if (n.derive && !summarising) {
+    if (n.derive) {
       for (const d of n.derive) {
-        if (!d.needs.every((x) => input[x >>> 5] & (1 << (x & 31)))) continue;
+        if (summarising ? !approved.has(d) : !d.needs.every((x) => has(input, x))) continue;
         if (out === input) { scratch.set(input); out = scratch; }
         for (const t of d.to) out[t >>> 5] |= 1 << (t & 31);
       }
     }
     // A flag test's outcome turns what held before it into the bound the flag stood for.
     if (n.implies) {
-      for (const [from, to, soft] of n.implies) {
-        if (soft && summarising) continue;
+      for (const entry of n.implies) {
+        const [from, to, soft] = entry;
+        if (soft && summarising && !approved.has(entry)) continue;
         if (!(input[from >>> 5] & (1 << (from & 31)))) continue;
         if (out === input) { scratch.set(input); out = scratch; }
         out[to >>> 5] |= 1 << (to & 31);
@@ -2477,8 +2661,22 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
     const r = pending.shift();
     queued.delete(r.key);
     const calls = new Set();
+    // From no facts, every fact the run holds was made inside the range, so what depends on it is sound as it stands.
+    summarising = false;
+    const fromNone = run(r.entry, ZERO, r.end);
+    summarising = true;
+    const bot = fromNone.exitOut;
+    approved = new Set();
+    for (const [id, bits] of fromNone.IN) {
+      const n = nodes[id];
+      for (const k of n.keeps || []) if (k.guards && k.guards.some((g) => has(bits, g))) approved.add(k);
+      for (const { pairs, guards } of n.lifts || []) if (guards.some((g) => has(bits, g))) for (const pair of pairs) if (has(bits, pair[0])) approved.add(pair);
+      for (const pair of n.spanLifts || []) if (has(bits, pair[0])) approved.add(pair);
+      for (const d of n.derive || []) if (d.needs.every((x) => has(bits, x))) approved.add(d);
+      for (const entry of n.implies || []) if (entry[2] && has(bits, entry[0])) approved.add(entry);
+    }
     const top = run(r.entry, ONES, r.end, calls).exitOut;
-    const bot = run(r.entry, ZERO, r.end).exitOut;
+    approved = null;
     for (const k of calls) { if (!callers.has(k)) callers.set(k, new Set()); callers.get(k).add(r); }
     const old = summaries.get(r.key);
     const nextS = top && bot ? { top, bot } : { top: null, bot: null };
@@ -2673,7 +2871,20 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
   // the caller has let the parse tree go. A statement no context reaches has no facts, and credits
   // nothing. One `reached` does not mark does not run, unless `partial` says the analysis stopped
   // short or met a paragraph the parse did not find.
-  return { loopBody, nodeOf, posOf, checks: checks.filter((c) => !c.pseudo), words, nodes: nodes.length, facts, reached: reachedAt, extraFacts, partial };
+  const spans = [];
+  for (const mine of pairFacts.values()) for (const f of mine.values()) if (f.pair === 'span') spans.push({ a: f.a, b: f.b, k: f.k, t: f.t });
+  return { loopBody, nodeOf, posOf, checks: checks.filter((c) => !c.pseudo), spans, words, nodes: nodes.length, facts, reached: reachedAt, extraFacts, partial };
+}
+
+// The most the facts at a point let a node's value be, as a whole number, or null for no upper end.
+export function topOf(checks, bits) {
+  let cons = null;
+  for (const c of checks || []) for (const [bit, said] of [[c.t, c.tCons], [c.f, c.fCons]]) if (hasFact(bits, bit)) cons = meet(cons, said);
+  return cons ? wholeTop(cons) : null;
+}
+export function wholeTop(said) {
+  const r = asRange(said);
+  return r.hi == null ? null : r.hiInc ? Math.floor(r.hi) : Math.ceil(r.hi) - 1;
 }
 
 // For each token a condition reads, what each reading of it waits on: the operands to its left at

package/lib/dataflow.mjs

@@ -15,7 +15,7 @@ import { eachWithinMemory, watchMemoryBuffer } from './kernel/memory.mjs';
 // A flow finding is located by source and sink rather than by one path and line, so it keeps its
 // own comparator. The text comparison underneath it is the shared one.
 import { byText } from './kernel/findings.mjs';
-import { buildControl, creditOf, hasFact, within } from './control.mjs';
+import { buildControl, creditOf, hasFact, topOf, within, wholeTop } from './control.mjs';
 import { directoryTree } from './kernel/source-tree.mjs';
 
 const OS_COMMAND_ROUTINE = /^(SYSTEM|C\$SYSTEM|CBL_EXEC_RUN_UNIT|CBL_GC_HOSTED|BXPSYSTM)$/i;
@@ -87,6 +87,7 @@ function literalNames(prog) {
 // The value of the last NAME(value) option in a list: the last one wins, at either level.
 function lastOption(name, list) {
   for (let k = (list || []).length - 1; k >= 0; k--) {
+    // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp -- name is a literal option name
     const m = new RegExp(`^${name}\\(([A-Z]+)\\)$`).exec(list[k]);
     if (m) return m[1];
   }
@@ -215,11 +216,13 @@ export function analyze(root, opts = {}) {
   const rel = (p) => { let r = relOf.get(p); if (r === undefined) { r = relPath(root, p); relOf.set(p, r); } return r; };
   // `at` is the statement an edge that is not a statement's own is read at: the CALL or LINK that
   // passes an argument, the PUT or GET of a container.
-  const edge = (a, b, why, dir, at) => {
+  // `link` marks an edge into a callee at a call site ({ call }) or back out to it ({ ret }).
+  const edge = (a, b, why, dir, at, link) => {
     if (!a || !b || a === b) return;
-    a.edgesOut.push(at != null ? { to: b, why, dir, at } : { to: b, why, dir });
+    a.edgesOut.push({ to: b, why, dir, ...(at != null ? { at } : {}), ...link });
     stats.edges++;
   };
+  let callSites = 0;
 
   // Everything the graph needs from one program is taken while its parse tree is in hand, and the
   // tree is then released. Holding every tree until the end is what exhausted a 4 GB heap on an
@@ -236,7 +239,9 @@ export function analyze(root, opts = {}) {
         let repeats = false;
         let table = null;
         for (let a = item; a; a = a.parent) if ((a.occurs || 1) > 1) { repeats = true; table = a; }
-        n = { id: nodes.length, pk, program: prog.id, file, name: item.name, off: item.offset ?? null, size: item.size ?? null, repeats, edgesOut: [], sources: [], sinks: [] };
+        let top = item;
+        while (top.parent) top = top.parent;
+        n = { id: nodes.length, pk, program: prog.id, file, name: item.name, off: item.offset ?? null, size: item.size ?? null, repeats, edgesOut: [], sources: [], sinks: [], ...(top.section === 'LINKAGE' ? { linkage: true } : {}) };
         // Where the outermost table holding this item sits in the record: every occurrence of the
         // item is somewhere inside it. A group's size already counts its occurrences; an
         // elementary item's is one element.
@@ -406,6 +411,13 @@ export function analyze(root, opts = {}) {
     // A whole number no sign is written on, which no value put in it can leave below 0.
     const unsignedWhole = (it) => it.level !== 88 && !it.index && !(it.children || []).length
       && /^9+$/.test(String(it.picture || '').toUpperCase().replace(/(\w)\((\d+)\)/g, (_, ch, n) => ch.repeat(Number(n))));
+    // Where a length's reference starts: the start's node, a constant it is moved by, and the span
+    // facts that keep start and length together inside the item.
+    const startOf = (from, len, size) => {
+      const s = from.tok ? itemOfToken(from.tok) : null;
+      const spans = ctl && ctl.spans && s && len ? ctl.spans.filter((f) => ((f.a === s && f.b === len) || (f.a === len && f.b === s)) && f.k + from.offset <= size + 1).map((f) => f.t) : [];
+      return { node: from.tok ? nodeOfToken(from.tok) : null, offset: from.offset, size, spans };
+    };
     const indexed = new Set();
     const subscripting = new Map();
     // Each subscript use of a name, with the other indices of the same reference: the loop-bound
@@ -438,8 +450,9 @@ export function analyze(root, opts = {}) {
         const use = `${key}|${point ?? `s${st.at}`}|${offset}`;
         if (indexed.has(use)) continue;
         indexed.add(use);
+        const start = kind === 'reference-modification' && x.from && base != null ? startOf(x.from, idx, base) : null;
         at.sinks.push({
-          kind, onlyFrom: FROM_OUTSIDE, file: st.file, line: st.line, point, group: `${pk}|${key}`, limit, ...(offset ? { offset } : {}), ...(offset > 0 && idx && unsignedWhole(idx) ? { nonNeg: true } : {}), ...(ssrange ? { ssrange } : {}),
+          kind, onlyFrom: FROM_OUTSIDE, file: st.file, line: st.line, point, group: `${pk}|${key}`, limit, ...(start ? { start } : {}), ...(offset ? { offset } : {}), ...(offset > 0 && idx && unsignedWhole(idx) ? { nonNeg: true } : {}), ...(ssrange ? { ssrange } : {}),
           detail: kind === 'subscript'
             ? `${at.name} subscripts ${host.name}, a table of ${table.occurs}`
             : `${at.name} sets the ${x.kind === 'refmod-offset' ? 'start' : 'length'} of a reference to ${host.name}, which is ${host.size} bytes`,
@@ -1032,21 +1045,23 @@ export function analyze(root, opts = {}) {
   for (const p of programs) {
     for (const t of p.transfers) {
       const r = calleesOf(t.callee, p.file);
+      const site = ++callSites;
       for (const callee of r.list) {
         if (!callee.commarea) continue;
-        edge(t.argNode, callee.commarea, `EXEC CICS ${t.verb} COMMAREA to ${t.callee}${t.through ? `, the program ${t.through} names` : ''}${ofN(r, t.callee)}`, undefined, t.point);
-        if (t.verb === 'LINK') edge(callee.commarea, t.argNode, `COMMAREA returned from ${t.callee}${ofN(r, t.callee)}`);
+        edge(t.argNode, callee.commarea, `EXEC CICS ${t.verb} COMMAREA to ${t.callee}${t.through ? `, the program ${t.through} names` : ''}${ofN(r, t.callee)}`, undefined, t.point, { call: site });
+        if (t.verb === 'LINK') edge(callee.commarea, t.argNode, `COMMAREA returned from ${t.callee}${ofN(r, t.callee)}`, undefined, undefined, { ret: site });
       }
     }
     for (const c of p.callSites) {
       const r = calleesOf(c.name, p.file);
+      const site = ++callSites;
       for (const callee of r.list) {
         if (!callee.params) continue;
         c.args.forEach((arg, i) => {
           const param = callee.params[i];
           if (!param || !arg.node || !param.node) return;
-          edge(arg.node, param.node, `CALL '${c.display}' argument ${i + 1} at ${rel(c.file)}:${c.line}${ofN(r, c.display)}`, undefined, c.point);
-          if (arg.mode === 'REFERENCE' && param.mode === 'REFERENCE') edge(param.node, arg.node, `CALL '${c.display}' argument ${i + 1} written back${ofN(r, c.display)}`);
+          edge(arg.node, param.node, `CALL '${c.display}' argument ${i + 1} at ${rel(c.file)}:${c.line}${ofN(r, c.display)}`, undefined, c.point, { call: site });
+          if (arg.mode === 'REFERENCE' && param.mode === 'REFERENCE') edge(param.node, arg.node, `CALL '${c.display}' argument ${i + 1} written back${ofN(r, c.display)}`, undefined, undefined, { ret: site });
         });
       }
       const callee = r.list.length === 1 ? r.list[0] : null;
@@ -1283,6 +1298,18 @@ export function analyze(root, opts = {}) {
     const bits = p.facts.get(point);
     return bits ? creditOf(n.checks, bits, kind, limit, offset, nonNeg) : NONE;
   }
+  // A length is judged with its start: the last byte, S + L - 1, stays inside the item where the
+  // start at its highest leaves room for the length, or where a fact bounds the two together.
+  function spanned(c, sink, n) {
+    if (c.level < 2 || !sink.start) return c;
+    const p = programs[n.pk];
+    const bits = p && p.ordered && sink.point != null ? p.facts.get(sink.point) : null;
+    const s = sink.start;
+    if (bits && s.spans.some((t) => hasFact(bits, t))) return c;
+    const top = bits && s.node ? topOf(s.node.checks, bits) : null;
+    const len = c.cons ? wholeTop(c.cons) : null;
+    return top != null && len != null && top + s.offset + len - 1 <= s.size ? c : { level: 1, check: c.check };
+  }
   // A loop bound cannot push its counter out of the table when the loop's own condition or the
   // body's checks keep every subscript the counter makes, and each index beside it, in range.
   // That holds whatever the bound is, so it does not depend on the route the input took.
@@ -1312,7 +1339,7 @@ export function analyze(root, opts = {}) {
     let point = sink.point;
     for (let h = hops.length - 1; h >= 0; h--) {
       const n = hops[h].node;
-      let c = creditAt(n, point, sink.kind, sink.limit, sink.offset, sink.nonNeg);
+      let c = spanned(creditAt(n, point, sink.kind, sink.limit, sink.offset, sink.nonNeg), sink, n);
       // A count checked against a number above the table's maximum has been checked, not kept in range.
       if (c.level === 2 && sink.top != null && !within(c.cons, sink.top, false)) c = { level: 1, check: c.check };
       if (c.level > best.level) { best = c; by = n; }
@@ -1327,6 +1354,7 @@ export function analyze(root, opts = {}) {
   // last moved - at a point where the credit reaches `level`.
   function refuse(start, reach, credited, level, kind, shift = 0) {
     walk++;
+    stampCtx.clear();
     const want = credited.filter((c) => c.level >= level && c.sink.kind === kind && (c.sink.offset || 0) === shift);
     // Past the budget no route can be ruled out, so every credit in question is lost: a finding
     // may be reported unchecked, never dropped.
@@ -1334,7 +1362,10 @@ export function analyze(root, opts = {}) {
     const at = new Map();
     for (const c of want) { if (!at.has(c.node.id)) at.set(c.node.id, []); at.get(c.node.id).push(c); }
     // Along the way no sink's limit applies, so a bound that holds only against one blocks nothing.
-    const holds = (since, point, k, limit = null, offset = 0, nonNeg = false) => since.some((n) => creditAt(n, point, k, limit, offset, nonNeg).level >= level);
+    const holds = (since, point, k, limit = null, offset = 0, nonNeg = false, sink = null) => since.some((n) => {
+      const c = creditAt(n, point, k, limit, offset, nonNeg);
+      return (sink ? spanned(c, sink, n) : c).level >= level;
+    });
     const lost = new Set();
     const dirty = new Map();
     const parts = new Map();
@@ -1343,7 +1374,7 @@ export function analyze(root, opts = {}) {
     const began = edgesWalked;
     for (let i = 0; i < open.length; i++) {
       const st = open[i];
-      for (const c of at.get(st.node.id) || []) if (!holds(st.since, c.sink.point, c.sink.kind, c.sink.limit, c.sink.offset, c.sink.nonNeg)) lost.add(c);
+      for (const c of at.get(st.node.id) || []) if (!holds(st.since, c.sink.point, c.sink.kind, c.sink.limit, c.sink.offset, c.sink.nonNeg, c.sink)) lost.add(c);
       for (const e of st.node.edgesOut) {
         edgesWalked++;
         const to = e.to;
@@ -1357,17 +1388,15 @@ export function analyze(root, opts = {}) {
         // stand in for it.
         const guarded = since.some((n) => n.checks || n.guard);
         if (t.partial) {
-          const key = `${to.id}|${guarded}`;
+          const key = `${to.id}|${guarded}|${t.ctx}`;
           const held = parts.get(key);
           if (held && held.some((r) => (r[2] ? t.vague : !t.vague && r[0] <= t.lo && t.hi <= r[1]))) continue;
           if (held) held.push([t.lo, t.hi, t.vague]); else parts.set(key, [[t.lo, t.hi, t.vague]]);
         } else if (guarded) {
-          if (stampWhole[to.id] === walk || dirty.get(to.id) === walk) continue;
-          dirty.set(to.id, walk);
-        } else {
-          if (stampWhole[to.id] === walk) continue;
-          stampWhole[to.id] = walk;
-        }
+          const dk = `${to.id}|${t.ctx}`;
+          if (stampWhole[to.id] === walk || dirty.get(dk) === walk) continue;
+          dirty.set(dk, walk);
+        } else if (!firstVisit(to.id, t.ctx)) continue;
         open.push({ node: to, ...t, since });
       }
       if (edgesWalked - began > walkBudget) { stats.creditUndecided++; return new Set(want); }
@@ -1386,6 +1415,16 @@ export function analyze(root, opts = {}) {
   // Visit stamps instead of a per-walk Set: one walk per source, and a Set of string keys per walk
   // was most of the time spent on large repositories.
   const stampWhole = new Int32Array(nodes.length);
+  // A whole node reached with a call context, per walk. Reached with none, it stands in for every context.
+  const stampCtx = new Map();
+  const firstVisit = (id, ctx) => {
+    if (stampWhole[id] === walk) return false;
+    if (!ctx) { stampWhole[id] = walk; return true; }
+    const key = `${id}|${ctx}`;
+    if (stampCtx.get(key) === walk) return false;
+    stampCtx.set(key, walk);
+    return true;
+  };
   let walk = 0;
   // Every walk is bounded, and so is the analysis. One source of an estate whose programs share
   // their records through thousands of copybooks reached millions of nodes, and 22,905 such walks
@@ -1402,9 +1441,25 @@ export function analyze(root, opts = {}) {
   // it does not. Both walks below cross edges through this, so neither can take a route the other
   // would refuse.
   const known = (n) => n.off != null && n.size != null && !n.repeats;
+  // The call sites a value entered its callees through, innermost last, as a string; empty where any
+  // caller may be returned to: a value born in the callee, or one that rested in storage a program
+  // keeps between calls, which a later call from any caller can read.
+  const CONTEXT_DEPTH = 4;
+  function contextOver(state, e) {
+    const ctx = state.ctx || '';
+    if (e.ret != null) {
+      if (!ctx) return '';
+      const sites = ctx.split('/');
+      return Number(sites[sites.length - 1]) === e.ret ? sites.slice(0, -1).join('/') : null;
+    }
+    if (e.call != null) return [...(ctx ? ctx.split('/') : []), String(e.call)].slice(-CONTEXT_DEPTH).join('/');
+    return e.to.linkage ? ctx : '';
+  }
   function cross(state, e) {
     const cur = state.node;
     const to = e.to;
+    const ctx = contextOver(state, e);
+    if (ctx === null) return null;
     let partial = false, lo = 0, hi = 0, vague = false;
     if (opts.legacyGroupEdges) { /* every edge carries the whole item */ }
     else if (e.dir === 'up') {
@@ -1441,7 +1496,7 @@ export function analyze(root, opts = {}) {
         if (!vague && to.size != null) { hi = Math.min(hi, to.size); if (hi <= lo) return null; }
       }
     }
-    return { partial, lo, hi, vague };
+    return { partial, lo, hi, vague, ctx };
   }
   for (const start of nodes) {
     if (!start.sources.length || !canReach[start.id]) continue;
@@ -1450,6 +1505,7 @@ export function analyze(root, opts = {}) {
       if (!(canReach[start.id] & reach)) continue;
       if (edgesWalked >= totalBudget) { stats.sourcesNotWalked++; continue; }
       walk++;
+      stampCtx.clear();
       const credited = [];
       // A state is a node plus which of its bytes are tainted. Going up from a child taints only
       // that child's bytes of the group; going down reaches a child only if those bytes overlap it,
@@ -1516,16 +1572,14 @@ export function analyze(root, opts = {}) {
           const to = e.to;
           const crossed = cross(state, e);
           if (!crossed) continue;
-          const { partial, lo, hi, vague } = crossed;
+          const { partial, lo, hi, vague, ctx } = crossed;
           if (partial) {
-            const held = partSeen.get(to.id);
+            const pk = `${to.id}|${ctx}`;
+            const held = partSeen.get(pk);
             if (held && held.some(r => (r[2] ? vague : !vague && r[0] <= lo && hi <= r[1]))) continue;
-            if (held) held.push([lo, hi, vague]); else partSeen.set(to.id, [[lo, hi, vague]]);
-          } else {
-            if (stampWhole[to.id] === walk) continue;
-            stampWhole[to.id] = walk;
-          }
-          queue.push({ node: to, partial, lo, hi, vague, prev: state, why: e.why, dir: e.dir, point: pointOfEdge(e), moves: moves(e) });
+            if (held) held.push([lo, hi, vague]); else partSeen.set(pk, [[lo, hi, vague]]);
+          } else if (!firstVisit(to.id, ctx)) continue;
+          queue.push({ node: to, partial, lo, hi, vague, ctx, prev: state, why: e.why, dir: e.dir, point: pointOfEdge(e), moves: moves(e) });
         }
       }
       if (cut) stats.walksCut++;

package/lib/explain.mjs

@@ -2,7 +2,7 @@
 import { resolve, relative, sep, dirname } from 'node:path';
 import { realpathSync } from 'node:fs';
 import { readSource, isProgram, isCopybook, isJcl } from './sources.mjs';
-import { parseFile, buildFileIndex, detectFormat } from './parser.mjs';
+import { parseFile, buildFileIndex, detectFormat, normalize, tokenize, segmentEnd } from './parser.mjs';
 import { EVIDENCE } from './kernel/findings.mjs';
 import { REGISTRY } from './kernel/registry.mjs';
 import { WHO_ACTS } from './tui/model.mjs';
@@ -34,6 +34,21 @@ function contained(root, rel) {
   return { abs };
 }
 
+// The last line of the COBOL statement that starts on `line`, its period or END- terminator included,
+// so a drafter shown one line of a statement knows where the statement ends. Past MAX_EXTENT lines
+// nothing is claimed.
+const MAX_EXTENT = 30;
+function statementEnd(file, line) {
+  file.tokens ??= (() => { try { return tokenize(normalize(file.text, file.format), '').tokens; } catch { return []; } })();
+  const t = file.tokens;
+  const i = t.findIndex((x) => x.line === line);
+  if (i < 0 || t[i].t !== 'word') return line;
+  const e = segmentEnd(t, i, t.length);
+  const next = t[e];
+  const end = next && next.line >= line && (next.t === 'period' || (next.t === 'word' && next.u === `END-${t[i].u}`)) ? next.line : t[e - 1].line;
+  return end > line && end - line < MAX_EXTENT ? end : line;
+}
+
 // A hop's location: from `via` ("MOVE at pos/P1.cbl:9"), else the related entry for its file.
 function hopAt(hop, finding) {
   const m = /\bat (.+):(\d+)$/.exec(hop.via || '');
@@ -62,7 +77,7 @@ export function explainFinding(report, fingerprint, { root }) {
     else {
       try {
         const text = readSource(c.abs).text;
-        file = { kind: kindOf(c.abs), format: detectFormat(text), lines: text.split(/\r?\n/) };
+        file = { kind: kindOf(c.abs), format: detectFormat(text), text, lines: text.split(/\r?\n/) };
       } catch (e) { unread.push({ path, why: `it could not be read: ${e.message}` }); }
     }
     files.set(path, file);
@@ -72,15 +87,26 @@ export function explainFinding(report, fingerprint, { root }) {
   for (const x of [...report.findings, ...(report.suppressed || [])]) {
     if (HIDDEN_RULES.has(x.rule) && x.path && x.line) flagged.set(`${x.path}:${x.line}`, x.rule);
   }
-  const quote = (path, line) => {
+  const quoteLine = (path, file, line) => {
     const withheld = flagged.get(`${path}:${line}`);
     if (withheld) return { code: null, withheld };
-    const file = fileOf(path);
-    if (!file || !(line > 0 && line <= file.lines.length)) return { code: null };
     const area = codeArea(file.lines[line - 1], file.kind, file.format);
     const dropped = area.rest.trim() !== '' || /[^\d\s]/.test(area.seq);
     return { code: area.text.trimEnd(), ...(dropped ? { dropped } : {}) };
   };
+  // A statement that runs on past its first line carries endLine and the lines after the first.
+  const quote = (path, line) => {
+    const withheld = flagged.get(`${path}:${line}`);
+    if (withheld) return { code: null, withheld };
+    const file = fileOf(path);
+    if (!file || !(line > 0 && line <= file.lines.length)) return { code: null };
+    const first = quoteLine(path, file, line);
+    const endLine = file.kind === 'cobol' ? statementEnd(file, line) : line;
+    if (endLine === line) return first;
+    const rest = [];
+    for (let n = line + 1; n <= endLine; n++) rest.push({ line: n, ...quoteLine(path, file, n) });
+    return { ...first, endLine, rest };
+  };
 
   const hops = (f.trace || []).map((h, i) => {
     if (h.elided) return { n: i + 1, elided: h.elided, via: h.via };