@portll/cobolwork 0.3.0 → 0.5.0

package/lib/constants.mjs

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The literals that can be in a data item when a statement reads it, from the program's text: its
+// VALUE clause and its subordinates', each MOVE and STRING into it or into a group holding it, and a
+// hop or two back through an item those name. Anything else that can write it - a computation, a
+// READ or ACCEPT INTO, a CALL it is passed to by reference, a MOVE from a field with no constant -
+// leaves it open, which a caller reads as "and something this cannot see".
+const FIGURATIVE = /^(LOW-VALUES?|HIGH-VALUES?|SPACES?|ZEROS?|ZEROES|QUOTES?|NULLS?)$/;
+const WRITERS = new Set(['COMPUTE', 'ADD', 'SUBTRACT', 'MULTIPLY', 'DIVIDE', 'READ', 'ACCEPT', 'UNSTRING', 'INITIALIZE', 'SET', 'RETURN', 'INSPECT']);
+const NOT_OPERANDS = new Set(['TO', 'INTO', 'DELIMITED', 'BY', 'SIZE', 'OF', 'IN', 'ALL']);
+
+// The item, its subordinates and the groups that hold it.
+function family(p, name) {
+  const self = p.items.find((x) => x.name === name);
+  if (!self) return null;
+  const under = [];
+  const down = (it) => { for (const c of it.children || []) { if (c.level === 88) continue; under.push(c); down(c); } };
+  down(self);
+  const over = [];
+  for (let up = self.parent; up; up = up.parent) over.push(up);
+  return { self, under, over };
+}
+
+const nameOf = (t) => (typeof t === 'string' ? t : t && t.u);
+
+const valuesOf = (item) => (item.values || []).map((v) => (v.t === 'lit' ? String(v.v) : FIGURATIVE.test(v.u || '') ? v.u : null)).filter((v) => v !== null);
+
+// `ignoreCall(call)` names calls that read the item and do not write it, such as the one being judged.
+export function constantsReaching(p, name, { depth = 2, ignoreCall = () => false } = {}, seen = new Set()) {
+  const out = { values: [], open: false };
+  if (seen.has(name)) return out;
+  seen.add(name);
+  const f = family(p, name);
+  if (!f) return { values: [], open: true };
+  const names = new Set([name, ...f.under.map((x) => x.name), ...f.over.map((x) => x.name)]);
+  out.values.push(...valuesOf(f.self), ...f.under.flatMap(valuesOf));
+  for (const st of p.statements || []) {
+    if (!(st.targets || []).some((t) => names.has(nameOf(t)))) continue;
+    if (st.verb === 'MOVE' || st.verb === 'STRING') {
+      for (const t of st.sources || []) if (t && t.t === 'lit') out.values.push(String(t.v));
+      for (const l of st.literals || []) out.values.push(String(l && l.v !== undefined ? l.v : l));
+      for (const w of (st.sources || []).filter((t) => !(t && t.t === 'lit')).map(nameOf).filter((x) => x && !NOT_OPERANDS.has(x))) {
+        if (FIGURATIVE.test(w) || /^[+-]?\d/.test(w) || names.has(w)) { if (FIGURATIVE.test(w)) out.values.push(w); continue; }
+        if (depth === 0) { out.open = true; continue; }
+        const r = constantsReaching(p, w, { depth: depth - 1, ignoreCall }, seen);
+        out.values.push(...r.values);
+        if (r.open || !r.values.length) out.open = true;
+      }
+      continue;
+    }
+    if (WRITERS.has(st.verb)) out.open = true;
+  }
+  for (const c of p.calls || []) {
+    if (ignoreCall(c)) continue;
+    if ((c.using || []).some((u) => names.has(u.word) && u.mode !== 'CONTENT' && u.mode !== 'VALUE')) out.open = true;
+  }
+  return out;
+}
+
+// A rule array is eight-byte keywords side by side; one held in several fields reads the same.
+export const keywordsOf = (values) => new Set(values.flatMap((v) => (FIGURATIVE.test(v) ? [] : String(v).match(/.{1,8}/g) || []).map((k) => k.trim().toUpperCase()).filter(Boolean)));

package/lib/control.mjs

@@ -622,10 +622,14 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
 
   // ---- checks ----
   // The storage an item lies in: its record, or the record an 01 REDEFINES lays itself over.
+  const recordOf = new Map();
   const itemsInRecord = (item) => {
-    let top = item;
+    let top = recordOf.get(item);
+    if (top) return top;
+    top = item;
     while (top.parent) top = top.parent;
     for (let hops = 0; top.redefinesItem && hops < 64; hops++) top = top.redefinesItem;
+    if (item.parent) recordOf.set(item, top);
     return top;
   };
   const fieldKey = (f) => (f.index ? `IX:${f.index}` : f);
@@ -639,6 +643,33 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
     const fEnd = f.offset + (f.contributes || f.size);
     return w.offset < fEnd && f.offset < wEnd;
   };
+  // Entries grouped by the storage their item lies in, so a lookup tries only what `overlaps` can
+  // accept: the same record, the same index, or a 66-level item, which overlaps any field.
+  const byStorage = (entries, itemOf) => {
+    const byRecord = new Map();
+    const byIndex = new Map();
+    const renames = [];
+    const plain = [];
+    const add = (map, k, e) => { const list = map.get(k); if (list) list.push(e); else map.set(k, [e]); };
+    for (const e of entries) {
+      const it = itemOf(e);
+      if (it.index) { add(byIndex, it.index, e); continue; }
+      plain.push(e);
+      if (it.level === 66) renames.push(e);
+      else add(byRecord, itemsInRecord(it), e);
+    }
+    return {
+      mayOverlap: (it) => {
+        if (it.index) return byIndex.get(it.index) || [];
+        if (it.level === 66) return plain;
+        const same = byRecord.get(itemsInRecord(it));
+        return same ? (renames.length ? same.concat(renames) : same) : renames;
+      },
+    };
+  };
+  // Arguments the CICS API documents as data-values, which the command reads and never fills: the
+  // program or transaction it transfers to or starts, and the system it ships the request to.
+  const CICS_READS = { LINK: ['PROGRAM', 'TRANSID', 'SYSID'], XCTL: ['PROGRAM'], START: ['TRANSID', 'SYSID'], RETURN: ['TRANSID'], LOAD: ['PROGRAM'], RELEASE: ['PROGRAM'] };
   const writtenBy = (n) => {
     const out = [];
     const add = (tok) => { const f = tok ? resolve(tok) : null; if (f) out.push(f.level === 88 && f.parent ? f.parent : f); };
@@ -667,28 +698,31 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
         }
       }
     } else if (n.e) {
-      // A command may fill what any option is given directly, except what it sends FROM. A name
-      // inside that argument's own parentheses - a subscript, a reference modification - is read.
+      // A command may fill what any option is given directly, except what it sends FROM and the
+      // data-values it reads. A name inside that argument's own parentheses - a subscript, a
+      // reference modification - is read.
+      const reads = (n.e.kind === 'CICS' && CICS_READS[n.e.toks[0]?.u]) || [];
       let depth = 0;
       let option = null;
       for (let i = 0; i < n.e.toks.length; i++) {
         const t = n.e.toks[i];
         if (t.t === 'sep') { depth += t.v === '(' ? 1 : -1; continue; }
         if (depth === 0) { option = t.t === 'word' ? t.u : option; continue; }
-        if (depth === 1 && t.t === 'word' && option !== 'FROM') add(t);
+        if (depth === 1 && t.t === 'word' && option !== 'FROM' && !reads.includes(option)) add(t);
       }
     }
     return out;
   };
   // A VALUE holds for the whole run only if no statement writes storage that overlaps the item.
-  let writtenItems = null;
+  let written = null;
   const neverWritten = (it) => {
     if (it.external) return false;
-    if (!writtenItems) {
-      writtenItems = [];
-      for (const n of nodes) if (n.kind === 'stmt' || n.kind === 'exec' || n.kind === 'step' || n.kind === 'call') writtenItems.push(...writtenBy(n));
+    if (!written) {
+      const all = [];
+      for (const n of nodes) if (n.kind === 'stmt' || n.kind === 'exec' || n.kind === 'step' || n.kind === 'call') all.push(...writtenBy(n));
+      written = byStorage(all, (w) => w);
     }
-    return !writtenItems.some((w) => overlaps(w, it));
+    return !written.mayOverlap(it).some((w) => overlaps(w, it));
   };
   const constValue = (toks) => {
     if (toks.length === 3 && WORD(toks[0], 'LENGTH') && WORD(toks[1], 'OF')) {
@@ -2373,17 +2407,17 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
     for (const f of [c.x, c.t, c.f, c.rt, c.rf]) if (f != null) list.push(f);
     factsOfKey.set(c.key, list);
   }
+  const checkedFields = byStorage([...factsOfKey.keys()].filter((key) => fields.get(key)), (key) => fields.get(key));
   const killCache = new Map();
   const killOf = (w) => {
     if (!w) return null;
     let bits = killCache.get(w);
     if (bits !== undefined) return bits;
     bits = null;
-    for (const [key, list] of factsOfKey) {
-      const f = fields.get(key);
-      if (!f || !overlaps(w, f)) continue;
+    for (const key of checkedFields.mayOverlap(w)) {
+      if (!overlaps(w, fields.get(key))) continue;
       bits ||= new Uint32Array(words);
-      for (const x of list) bits[x >>> 5] |= 1 << (x & 31);
+      for (const x of factsOfKey.get(key)) bits[x >>> 5] |= 1 << (x & 31);
     }
     killCache.set(w, bits);
     return bits;
@@ -2629,10 +2663,15 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
   // Every route from `entry` that reaches `stopAt` or the program's end, meeting at joins. A call
   // whose range never returns ends the route, as a STOP RUN does. `calls` collects the ranges the
   // routes perform, for whoever needs to know what depends on what.
+  // A run holds a bitset per node it reaches. Those of a run nobody reads any more are handed back
+  // and reused, since allocating them afresh for every run was most of the analysis's collection time.
+  const spare = [];
+  const copyOf = (bits) => { const a = spare.pop(); if (!a) return bits.slice(); a.set(bits); return a; };
+  const release = (IN) => { for (const a of IN.values()) spare.push(a); };
   function run(entry, input, stopAt, calls = null) {
     const IN = new Map();
     let exitOut = null;
-    IN.set(entry, input.slice());
+    IN.set(entry, copyOf(input));
     push(entry);
     while (heap.length) {
       const id = pop();
@@ -2643,7 +2682,7 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
       if (id === stopAt) { if (exitOut) meetInto(exitOut, out); else exitOut = out.slice(); continue; }
       for (const s of n.succ) {
         const cur = IN.get(s);
-        if (!cur) { IN.set(s, out.slice()); push(s); } else if (meetInto(cur, out)) push(s);
+        if (!cur) { IN.set(s, copyOf(out)); push(s); } else if (meetInto(cur, out)) push(s);
       }
     }
     return { IN, exitOut };
@@ -2675,7 +2714,10 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
       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;
+    release(fromNone.IN);
+    const fromAll = run(r.entry, ONES, r.end, calls);
+    const top = fromAll.exitOut;
+    release(fromAll.IN);
     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);
@@ -2704,7 +2746,9 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
     waiting.delete(c.key);
     const input = c.stopAt == null ? ZERO : rangeIn.get(c.key);
     const res = run(c.entry, input, c.stopAt);
+    const superseded = results.get(c.key);
     results.set(c.key, res.IN);
+    if (superseded) release(superseded);
     for (const [id, bits] of res.IN) {
       const n = nodes[id];
       if (n.kind !== 'call' || !byKey.has(n.range.key)) continue;
@@ -2723,7 +2767,7 @@ export function buildControl(prog, resolve, { extra = null } = {}) {
   for (const IN of results.values()) {
     for (const [id, bits] of IN) {
       const had = facts.get(id);
-      if (had) meetInto(had, bits); else facts.set(id, bits.slice());
+      if (had) meetInto(had, bits); else facts.set(id, bits);
     }
   }
   };

package/lib/csd.mjs

@@ -14,7 +14,7 @@ const COMMAND = /^\s*(DEFINE|ADD|ALTER|APPEND|COPY|DELETE|INITIALIZE|LIST|REMOVE
 // { tdqueues: Map(name -> { type, ddname, indirect, line }),
 //   transactions: Map(name -> { program, cmdsec, ressec, line }),
 //   tcpipservices: Map(name -> { port, protocol, ssl, authenticate, transaction, line }),
-//   urimaps: Map(name -> { usage, path, program, transaction, tcpipservice, line }) }
+//   urimaps: Map(name -> { usage, path, program, transaction, tcpipservice, scheme, host, attls, line }) }
 export function parseCsd(text) {
   const tdqueues = new Map();
   const transactions = new Map();
@@ -64,6 +64,11 @@ export function parseCsd(text) {
         program: attrs.get('PROGRAM') || null,
         transaction: attrs.get('TRANSACTION') || null,
         tcpipservice: attrs.get('TCPIPSERVICE') || null,
+        // A client URIMAP's scheme decides whether WEB OPEN URIMAP(name) asks for TLS; ATTLS(AWARE)
+        // has AT-TLS secure an HTTP scheme outside CICS.
+        scheme: attrs.get('SCHEME') || null,
+        host: attrs.get('HOST') || null,
+        attls: attrs.get('ATTLS') || null,
         line: b.line,
       });
     } else if (kind === 'TDQUEUE') {

package/lib/dataflow.mjs

@@ -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];
   }
@@ -188,6 +189,9 @@ export function analyze(root, opts = {}) {
   // Every hop of every trace, for the reader who is following one chain rather than counting
   // findings. Off by default: a chain-shaped program turns this quadratic in the chain length.
   const fullTrace = opts.fullTrace === true;
+  // Every statement on any route from a finding's source to its sink, not only the route the trace
+  // names: what a run must have executed before it can show a value does not arrive (reach.md §9.8).
+  const allRoutes = opts.allRoutes === true;
   let held = 0;
 
   // Which files, not just how many. A count names nothing to go and look at, and it cannot tell
@@ -215,11 +219,14 @@ 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 }), and
+  // `stmt` names the statement that carries an edge whose `why` is text.
+  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 +243,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.
@@ -792,7 +801,7 @@ export function analyze(root, opts = {}) {
         if (verb === 'PUT' && o.has('CONTAINER')) {
           const name = optionName(o, 'CONTAINER');
           const from = nodeOfToken((o.get('FROM') || [])[0]);
-          if (name && from) edge(from, containerNode(name), `EXEC CICS PUT CONTAINER(${name})`, undefined, at.point);
+          if (name && from) edge(from, containerNode(name), `EXEC CICS PUT CONTAINER(${name})`, undefined, at.point, { stmt: { verb: 'EXEC CICS PUT', file: rel(at.file), line: at.line } });
           if (name) channelOf.set(name, optionName(o, 'CHANNEL'));
         }
         // A service call sends every container on its channel, and its URI decides where they go.
@@ -806,7 +815,7 @@ export function analyze(root, opts = {}) {
         if (verb === 'GET' && o.has('CONTAINER')) {
           const name = optionName(o, 'CONTAINER');
           const into = nodeOfToken((o.get('INTO') || o.get('SET') || [])[0]);
-          if (name && into) edge(containerNode(name), into, `EXEC CICS GET CONTAINER(${name})`, undefined, at.point);
+          if (name && into) edge(containerNode(name), into, `EXEC CICS GET CONTAINER(${name})`, undefined, at.point, { stmt: { verb: 'EXEC CICS GET', file: rel(at.file), line: at.line } });
         }
         // CONVERSE is always a client call; SEND is one only on a session this program opened. A
         // plain WEB SEND answers the request that started the program, which is its job.
@@ -896,9 +905,9 @@ export function analyze(root, opts = {}) {
           }
           const commarea = (o.get('COMMAREA') || o.get('FROM') || [])[0];
           const argNode = commarea ? nodeOfToken(commarea) : null;
-          if (pgm && pgm.t === 'lit' && argNode) transfers.push({ verb, callee: pgm.v.toUpperCase(), argNode, point: at.point });
+          if (pgm && pgm.t === 'lit' && argNode) transfers.push({ verb, callee: pgm.v.toUpperCase(), argNode, point: at.point, file: at.file, line: at.line });
           else if (pgm && pgm.t === 'word' && argNode && o.has('PROGRAM')) {
-            for (const callee of programsNamed(pgm, e)) { transfers.push({ verb, callee, argNode, point: at.point, through: pgm.u }); transfersTo.add(callee); }
+            for (const callee of programsNamed(pgm, e)) { transfers.push({ verb, callee, argNode, point: at.point, file: at.file, line: at.line, through: pgm.u }); transfersTo.add(callee); }
           }
           if (pgm && pgm.t === 'lit') (o.has('TRANSID') && !o.has('PROGRAM') ? startsTransactions : transfersTo).add(String(pgm.v).trim().toUpperCase());
         }
@@ -1040,21 +1049,25 @@ 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;
+      const stmt = { verb: `EXEC CICS ${t.verb}`, file: rel(t.file), line: t.line };
       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, stmt });
+        if (t.verb === 'LINK') edge(callee.commarea, t.argNode, `COMMAREA returned from ${t.callee}${ofN(r, t.callee)}`, undefined, undefined, { ret: site, stmt });
       }
     }
     for (const c of p.callSites) {
       const r = calleesOf(c.name, p.file);
+      const site = ++callSites;
+      const stmt = { verb: 'CALL', file: rel(c.file), line: c.line };
       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, stmt });
+          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, stmt });
         });
       }
       const callee = r.list.length === 1 ? r.list[0] : null;
@@ -1347,6 +1360,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.
@@ -1380,17 +1394,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); }
@@ -1409,6 +1421,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
@@ -1425,9 +1447,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') {
@@ -1464,7 +1502,45 @@ 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 };
+  }
+  // The statement that carries an edge: null for storage that overlays storage, which runs nothing,
+  // and undefined where the engine does not know which statement it is.
+  const OVERLAYS = new Set(['group', 'redefines', 'renames']);
+  const statementOf = (e) => {
+    if (e.stmt) return e.stmt;
+    if (e.why && typeof e.why === 'object') return { verb: e.why.verb, file: e.why.file, line: e.why.line };
+    return OVERLAYS.has(e.why) ? null : undefined;
+  };
+  // Every route from one walk's source to each sink it reached: the edges the walk could cross that
+  // lead on to the sink, taken or not, by node rather than by call context or bytes. That lists a
+  // statement no route needs sooner than it leaves out one a route does.
+  function attachRoutes(awaiting, crossed, src, cut) {
+    const into = new Map();
+    for (const c of crossed) {
+      const list = into.get(c.to);
+      if (list) list.push(c); else into.set(c.to, [c]);
+    }
+    for (const { finding, at } of awaiting) {
+      const onRoute = new Set([at]);
+      const stack = [at];
+      const statements = new Map();
+      let unplaced = 0;
+      while (stack.length) {
+        for (const c of into.get(stack.pop()) || []) {
+          const s = statementOf(c.e);
+          if (s) statements.set(`${s.file}:${s.line}:${s.verb}`, s);
+          else if (s === undefined) unplaced++;
+          if (!onRoute.has(c.from)) { onRoute.add(c.from); stack.push(c.from); }
+        }
+      }
+      finding.routes = {
+        sources: [{ kind: src.kind, file: rel(src.file), line: src.line }],
+        statements: [...statements.values()].sort((a, b) => byText(a.file, b.file) || a.line - b.line || byText(a.verb, b.verb)),
+        ...(unplaced ? { unplaced } : {}),
+        complete: !cut && !unplaced,
+      };
+    }
   }
   for (const start of nodes) {
     if (!start.sources.length || !canReach[start.id]) continue;
@@ -1473,6 +1549,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,
@@ -1482,6 +1559,8 @@ export function analyze(root, opts = {}) {
       // without a layout) partial taint does not descend at all.
       const queue = [{ node: start, partial: false, lo: 0, hi: 0, vague: false, prev: null, why: 'source' }];
       const partSeen = new Map();
+      const crossedEdges = allRoutes ? [] : null;
+      const awaiting = allRoutes ? [] : null;
       stampWhole[start.id] = walk;
       let cut = false;
       const began = edgesWalked;
@@ -1530,6 +1609,7 @@ export function analyze(root, opts = {}) {
             ...(best.level ? { guard: { program: by.program, item: by.name, file: rel(best.check.file), line: best.check.line, ...(best.level === 2 ? { stops: true } : {}) } } : {}),
             ...(!best.level && missed ? { checkElsewhere: { program: missed.node.program, item: missed.node.name, file: rel(missed.check.file), line: missed.check.line } } : {}),
           });
+          if (awaiting) awaiting.push({ finding: findings[findings.length - 1], at: cur.id });
           if (best.level && !own) credited.push({ finding: findings[findings.length - 1], node: cur, sink, level: best.level });
           if (sink.group) useGroup.set(findings[findings.length - 1], `${src.kind}|${src.file}:${src.line}|${sink.kind}|${sink.group}`);
         }
@@ -1539,19 +1619,19 @@ export function analyze(root, opts = {}) {
           const to = e.to;
           const crossed = cross(state, e);
           if (!crossed) continue;
-          const { partial, lo, hi, vague } = crossed;
+          if (crossedEdges) crossedEdges.push({ from: cur.id, to: to.id, e });
+          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++;
+      if (awaiting?.length) attachRoutes(awaiting, crossedEdges, src, cut);
       // The walk keeps the shortest route to each sink, and credit on that route says nothing if
       // another reaches the sink without it. So the walk runs again, refusing to let the value leave
       // a node where the credit holds, and a sink it still reaches loses the credit: first for any

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