@portll/cobolwork 0.2.76 → 0.2.140

package/lib/utilities.mjs

@@ -8,6 +8,9 @@
 // statements are not in the job - SYSIN naming a library member - says so, because its copies are
 // then only the ones its DD names decide on their own.
 
+import { ftpSession } from './ftp.mjs';
+import { statementCard } from './card.mjs';
+
 const upper = (s) => String(s).toUpperCase();
 
 // The DDs of a step by name, each followed by the datasets concatenated to it.
@@ -93,7 +96,7 @@ function commands(lines) {
   let comment = false;
   for (const { line, text } of lines) {
     let t = '';
-    const s = text.slice(0, 72);
+    const s = statementCard(text).text;
     for (let i = 0; i < s.length; i++) {
       if (comment) { if (s[i] === '*' && s[i + 1] === '/') { comment = false; i++; } continue; }
       if (s[i] === '/' && s[i + 1] === '*') { comment = true; i++; continue; }
@@ -129,6 +132,12 @@ const who = (step) => `step ${step.name || '(unnamed)'}`;
 // Control statements only edit records or split members, so the copy is the DDs' alone.
 //   https://www.ibm.com/docs/api/v1/content/zosbasics/com.ibm.zos.zdatamgmt/zsysprogc_utilities_IEBGENER.htm
 //   https://www.ibm.com/docs/en/zos/3.1.0?topic=performance-use-icegener-instead-iebgener
+// IEBPTPCH reads SYSUT1 and writes its print or punch output to SYSUT2, and IEBUPDTE reads its old
+// master from SYSUT1 and writes SYSUT2. IEBUPDTE's control data set may also carry input data for the
+// new master, which is not followed here.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.idau100/u1367.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.idau100/u1427.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.idau100/u1425.htm
 function generCopy(step, dds) {
   if (!dds.has('SYSUT1') || !dds.has('SYSUT2')) return { moves: [], notes: [] };
   return { moves: [{ from: [{ dd: 'SYSUT1' }], to: [{ dd: 'SYSUT2' }], line: step.line }], notes: [] };
@@ -174,29 +183,74 @@ function sortCopies(step, dds) {
 //   https://www.ibm.com/docs/en/zos/3.1.0?topic=commands-repro
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2253.htm
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.idai200/continu.htm
+// EXPORT writes the cluster its first parameter names, or the one INFILE(ddname) identifies, to the
+// portable data set OUTFILE(ddname) or OUTDATASET(entryname) gives, and may be abbreviated EXP.
+// IMPORT reads the portable data set INFILE(ddname) or INDATASET(entryname) names and writes the
+// cluster OUTFILE(ddname) or OUTDATASET(entryname) names.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/export.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2210.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i211.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/import.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2221.htm
+// PRINT reads INFILE(ddname) or INDATASET(entryname) and writes the listing to OUTFILE(ddname),
+// SYSPRINT when it names none, so a production data set printed to SYSOUT leaves by that DD.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/print.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2244.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2245.htm
+// ALTER entryname NEWNAME(newname), abbreviated NEWNM, gives the entry a new name, so the data the
+// old name held is read under the new one. A generic name (both must then be generic) or a member
+// of a partitioned data set leaves the data set where it was, and is not followed.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2052.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2055.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.3.0/com.ibm.zos.v2r3.idai200/da6i2056.htm
+function renamed(cmd) {
+  const m = /^ALTER\s+'?([^\s(),'*]+)'?(?=[\s,]|$)/i.exec(cmd.text);
+  const to = m && param(cmd.text, ['NEWNAME', 'NEWNM']);
+  if (!to || /[*(]/.test(to[0])) return null;
+  return { from: [{ dsn: upper(m[1]) }], to: [{ dsn: to[0] }], line: cmd.line };
+}
+
 function reproCopies(step, dds) {
   const { lines, unread } = cards(dds.get('SYSIN'));
-  const notes = unread ? [{ line: step.line, text: `${who(step)} runs IDCAMS with commands in ${unread}, which this reader cannot see, so any REPRO it runs is not known` }] : [];
+  const notes = unread ? [{ line: step.line, text: `${who(step)} runs IDCAMS with commands in ${unread}, which this reader cannot see, so any REPRO, EXPORT, IMPORT, PRINT or rename it runs is not known` }] : [];
   const moves = [];
   for (const cmd of commands(lines)) {
-    if (!/^REPRO\b/i.test(cmd.text)) continue;
-    const end = (ddNames, dsNames) => {
+    if (/^ALTER\b/i.test(cmd.text)) {
+      const move = renamed(cmd);
+      if (move) moves.push(move);
+      continue;
+    }
+    if (/^PRINT\b/i.test(cmd.text)) {
+      const input = param(cmd.text, ['INFILE', 'IFILE']);
+      const ds = !input && param(cmd.text, ['INDATASET', 'IDS']);
+      const out = param(cmd.text, ['OUTFILE', 'OFILE']);
+      const from = input ? [{ dd: input[0] }] : ds ? [{ dsn: ds[0] }] : [];
+      moves.push({ from, to: [{ dd: out ? out[0] : 'SYSPRINT' }], line: cmd.line });
+      continue;
+    }
+    const verb = /^(REPRO|EXPORT|EXP|IMPORT)\b/i.exec(cmd.text);
+    if (!verb) continue;
+    const entry = /^EXP/i.test(verb[1]) && /^\S+\s+([^\s(),]+)/.exec(cmd.text);
+    const end = (ddNames, dsNames, fallback) => {
       const dd = param(cmd.text, ddNames);
       if (dd) return [{ dd: dd[0] }];
       const ds = param(cmd.text, dsNames);
-      return ds ? [{ dsn: ds[0] }] : [];
+      if (ds) return [{ dsn: ds[0] }];
+      return fallback ? [{ dsn: upper(fallback.replace(/^'|'$/g, '')) }] : [];
     };
-    moves.push({ from: end(['INFILE', 'IFILE'], ['INDATASET', 'IDS']), to: end(['OUTFILE', 'OFILE'], ['OUTDATASET', 'ODS']), line: cmd.line });
+    moves.push({ from: end(['INFILE', 'IFILE'], ['INDATASET', 'IDS'], entry && entry[1]), to: end(['OUTFILE', 'OFILE'], ['OUTDATASET', 'ODS']), line: cmd.line });
   }
   return { moves, notes };
 }
 
-// IEBCOPY COPY and COPYGRP name their output with OUTDD and their inputs with INDD, where an input
+// IEBCOPY COPY, COPYGRP and COPYMOD name their output with OUTDD and their inputs with INDD, where an input
 // written (ddname,R) replaces members of the same name. An INDD= on a record of its own begins
 // another step of the COPY before it. A statement continues after a comma or a mark in column 72.
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.1.0/com.ibm.zos.v3r1.idau100/copy.htm
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.1.0/com.ibm.zos.v3r1.idau100/copygrp.htm
 //   https://www.ibm.com/docs/en/zos/2.4.0?topic=ie-example-15-copy-groups-from-pdse-pdse-replace
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.1.0/com.ibm.zos.v3r1.idau100/copymd.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.1.0/com.ibm.zos.v3r1.idau100/u1055.htm
 function iebcopyCopies(step, dds) {
   const { lines, unread } = cards(dds.get('SYSIN'));
   const notes = unread ? [{ line: step.line, text: `${who(step)} runs IEBCOPY with statements in ${unread}, which this reader cannot see, so what it copies is not known` }] : [];
@@ -206,7 +260,7 @@ function iebcopyCopies(step, dds) {
   for (const st of statements) {
     // A record holding only INDD= has no operation, so what reads as its operation is its operand.
     const alone = /^INDD=/.test(st.op);
-    if (st.op === 'COPY' || st.op === 'COPYGRP') out = null;
+    if (st.op === 'COPY' || st.op === 'COPYGRP' || st.op === 'COPYMOD') out = null;
     else if (!alone) {
       if (st.op !== 'SELECT' && st.op !== 'EXCLUDE') out = null;
       continue;
@@ -227,35 +281,103 @@ function iebcopyCopies(step, dds) {
 // each OUTDDNAME, up to 255 of them. RESTORE reads the dump data set INDDNAME names and writes the
 // OUTDDNAME volumes. With no input DD a logical dump chooses its datasets by filter, and with no
 // output DD a logical restore puts them where the catalogue says, neither of which the job shows.
+// COPY reads the volumes INDDNAME or LOGINDDNAME name and writes the DASD volumes OUTDDNAME names.
 //   https://www.ibm.com/docs/en/zos/3.1.0?topic=commands-command-syntax
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.4.0/com.ibm.zos.v2r4.adru000/r2319.htm
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.4.0/com.ibm.zos.v2r4.adru000/r2321.htm
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.4.0/com.ibm.zos.v2r4.adru000/r2327.htm
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.adru000/dgt3u2165.htm
 //   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.adru000/dgt3u2174.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.adru000/r2172.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.adru000/r2204.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.adru000/r2206.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.adru000/r2216.htm
 function dssCopies(step, dds) {
   const { lines, unread } = cards(dds.get('SYSIN'));
-  const notes = unread ? [{ line: step.line, text: `${who(step)} runs ADRDSSU with commands in ${unread}, which this reader cannot see, so what it dumps or restores is not known` }] : [];
+  const notes = unread ? [{ line: step.line, text: `${who(step)} runs ADRDSSU with commands in ${unread}, which this reader cannot see, so what it dumps, restores or copies is not known` }] : [];
   const moves = [];
   for (const cmd of commands(lines)) {
-    const op = /^(DUMP|RESTORE)\b/i.exec(cmd.text);
+    const op = /^(DUMP|RESTORE|COPY)\b/i.exec(cmd.text);
     if (!op) continue;
-    const dump = upper(op[1]) === 'DUMP';
-    const ins = param(cmd.text, ['INDDNAME', 'INDD', 'IDD']) || (dump && param(cmd.text, ['LOGINDDNAME', 'LOGINDD', 'LIDD'])) || [];
+    const verb = upper(op[1]);
+    const dump = verb === 'DUMP';
+    const ins = param(cmd.text, ['INDDNAME', 'INDD', 'IDD']) || (verb !== 'RESTORE' && param(cmd.text, ['LOGINDDNAME', 'LOGINDD', 'LIDD'])) || [];
     const outs = param(cmd.text, ['OUTDDNAME', 'OUTDD', 'ODD']) || [];
     if (dump && !ins.length) notes.push({ line: cmd.line, text: `${who(step)} dumps datasets chosen by filter from the catalogue, so which ones it copies is not known here` });
-    if (!dump && !outs.length) notes.push({ line: cmd.line, text: `${who(step)} restores datasets to where the catalogue puts them, so what it writes is not known here` });
+    if (verb === 'COPY' && !ins.length) notes.push({ line: cmd.line, text: `${who(step)} copies datasets whose input volume the command names no DD for, so where they come from is not known here` });
+    if (verb === 'COPY' && !outs.length) notes.push({ line: cmd.line, text: `${who(step)} copies datasets to an output volume the command names no DD for, so what it writes is not known here` });
+    if (verb === 'RESTORE' && !outs.length) notes.push({ line: cmd.line, text: `${who(step)} restores datasets to where the catalogue puts them, so what it writes is not known here` });
     moves.push({ from: ins.map((dd) => ({ dd })), to: outs.map((dd) => ({ dd })), line: cmd.line });
   }
   return { moves, notes };
 }
 
+// ICETOOL runs the operators in TOOLIN. COPY, SORT and MERGE read the DDs their FROM operands name
+// and write the DDs their TO operands name, several ddnames to an operand. A statement's operands
+// continue on the next line after a hyphen, and what follows the hyphen is ignored. USING(xxxx) reads
+// DFSORT control statements from the xxxxCNTL DD, whose OUTFIL statements can write further data sets.
+//   https://www.ibm.com/docs/en/zos/3.1.0?topic=icetool-copy-operator
+//   https://www.ibm.com/docs/en/zos/3.1.0?topic=icetool-sort-operator
+//   https://www.ibm.com/docs/en/zos/3.1.0?topic=icetool-merge-operator
+//   https://www.ibm.com/docs/en/zos/2.3.0?topic=icetool-job-control-language
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.1.0/com.ibm.zos.v3r1.icea100/ice2ca_General_coding_rules.htm
+function icetoolCopies(step, dds) {
+  const { lines, unread } = cards(dds.get('TOOLIN'));
+  const notes = unread ? [{ line: step.line, text: `${who(step)} runs ICETOOL with statements in ${unread}, which this reader cannot see, so what it copies is not known` }] : [];
+  const statements = [];
+  let cur = null;
+  for (const { line, text } of lines) {
+    const s = statementCard(text).text;
+    if (!cur && (/^\*/.test(s) || !s.trim())) continue;
+    const tokens = s.trim().split(/\s+/);
+    const hyphen = tokens.findIndex((t) => t.endsWith('-'));
+    const used = hyphen < 0 ? tokens : tokens.slice(0, hyphen + 1);
+    if (!cur) cur = { line, op: upper(used.shift()), operands: [] };
+    cur.operands.push(...used.map((t) => t.replace(/-$/, '')).filter(Boolean));
+    if (hyphen < 0) { statements.push(cur); cur = null; }
+  }
+  if (cur) statements.push(cur);
+  const moves = [];
+  for (const st of statements) {
+    if (!['COPY', 'SORT', 'MERGE'].includes(st.op)) continue;
+    const named = (kw) => st.operands.flatMap((o) => {
+      const m = new RegExp(`^${kw}\\((.*)\\)$`, 'i').exec(o);
+      return m ? m[1].split(',').map((n) => upper(n.trim())).filter(Boolean) : [];
+    });
+    moves.push({ from: named('FROM').map((dd) => ({ dd })), to: named('TO').map((dd) => ({ dd })), line: st.line });
+    for (const using of named('USING')) {
+      const control = cards(dds.get(`${using}CNTL`));
+      if (control.unread || utilityStatements(control.lines, (ops) => /[,;:]$/.test(ops)).some((c) => c.op === 'OUTFIL')) {
+        notes.push({ line: st.line, text: `${who(step)} runs ICETOOL ${st.op} with control statements in ${using}CNTL that may write OUTFIL data sets, which are not followed here` });
+      }
+    }
+  }
+  return { moves, notes };
+}
+
+// An FTP step's transfers, from the session lib/ftp.mjs reads: what PUt, MPut and APpend send leaves
+// for the remote host, and what Get and MGet fetch is written locally. The remote end names the host
+// and file, and the FILETYPE a SIte gave it.
+function ftpCopies(step, dds) {
+  const s = ftpSession(step, dds);
+  const localEnds = (x) => (x.dd ? [{ dd: x.dd }] : x.dsns.map((dsn) => ({ dsn })));
+  const remote = (name, x) => ({ remote: { host: s.host, name, ...(x.filetype ? { filetype: x.filetype } : {}) } });
+  const moves = [
+    ...s.sends.map((x) => ({ from: localEnds(x), to: [remote(x.foreign, x)], line: x.line })),
+    ...s.gets.map((x) => ({ from: [remote(x.name, x)], to: localEnds(x), line: x.line })),
+  ].sort((a, b) => a.line - b.line);
+  const notes = s.inputUnread ? [{ line: step.line, text: `${who(step)} runs FTP with subcommands in ${s.inputUnread}, which this reader cannot see, so what it sends or fetches is not known` }] : [];
+  return { moves, notes };
+}
+
 const TABLE = [
-  [['IEBGENER', 'ICEGENER'], generCopy],
+  [['IEBGENER', 'ICEGENER', 'IEBPTPCH', 'IEBUPDTE'], generCopy],
   [['SORT', 'ICEMAN', 'DFSORT', 'SYNCSORT'], sortCopies],
   [['IDCAMS'], reproCopies],
   [['IEBCOPY'], iebcopyCopies],
   [['ADRDSSU'], dssCopies],
+  [['ICETOOL'], icetoolCopies],
+  [['FTP'], ftpCopies],
 ];
 const BY_PROGRAM = new Map(TABLE.flatMap(([names, fn]) => names.map((n) => [n, fn])));
 
@@ -274,7 +396,7 @@ export function copiesOf(step) {
   // An end naming a DD stands for every dataset concatenated under that name. A DD the step does
   // not define is kept, with no dataset: a statement naming it still says where the data went.
   const expand = (end) => {
-    if (!end.dd) return [{ dd: null, dsn: end.dsn }];
+    if (!end.dd) return [{ dd: null, dsn: end.dsn ?? null, ...(end.remote ? { remote: end.remote } : {}) }];
     const group = dds.get(end.dd);
     if (!group) return [{ dd: end.dd, dsn: null }];
     return group.map((dd) => ({ dd: end.dd, dsn: dd.dsn || null, ...(dd.inStream ? { inStream: true } : {}) }));
@@ -294,3 +416,95 @@ export function copiesOf(step) {
   }
   return { copies, uses, notes };
 }
+
+// A TSO command's operands: KEYWORD(value) with the value's parentheses and quotes kept, a quoted
+// string, or a bare word, split on blanks and commas. Blanks may stand between a keyword and its
+// parenthesis, as in PROGRAM (GETTAB).
+function tsoOperands(text) {
+  const out = [];
+  let i = 0;
+  while (i < text.length) {
+    if (/[\s,]/.test(text[i])) { i++; continue; }
+    const start = i;
+    let depth = 0, quoted = false;
+    for (; i < text.length; i++) {
+      const c = text[i];
+      if (c === "'") quoted = !quoted;
+      else if (quoted) continue;
+      else if (c === '(') depth++;
+      else if (c === ')') depth = Math.max(0, depth - 1);
+      else if (depth === 0 && /[\s,]/.test(c)) {
+        const next = /^\s*\(/.exec(text.slice(i));
+        if (next && /^[A-Z][A-Z0-9$#@]*$/i.test(text.slice(start, i))) { text = text.slice(0, i) + text.slice(i + next[0].length - 1); i--; continue; }
+        break;
+      }
+    }
+    const tok = text.slice(start, i);
+    const kw = /^([A-Z][A-Z0-9$#@]*)\((.*)\)$/is.exec(tok);
+    out.push(kw ? { key: upper(kw[1]), value: kw[2] } : { word: tok });
+  }
+  return out;
+}
+
+const unquote = (s) => s.replace(/^'(.*)'$/s, '$1').replace(/''/g, "'");
+
+// ALLOCATE's keywords, abbreviated as far as IBM's rule allows: to any leading part that no other
+// ALLOCATE keyword shares. FILE shares F, FI and FIL with FILEDATA, FCB, FLASH and FORMS, and DSNAME
+// shares DS and DSN with DSNTYPE and DSORG.
+const ALLOC_DATASET = /^(DA|DAT|DATA|DATAS|DATASE|DATASET|DSNA|DSNAM|DSNAME)$/;
+const ALLOC_FILE = /^(FILE|DD|DDN|DDNA|DDNAM|DDNAME)$/;
+const ALLOC_STATUS = new Set(['OLD', 'SHR', 'MOD', 'NEW']);
+
+// What a TSO batch step (IKJEFT01, IKJEFT1A, IKJEFT1B) does in its commands, from the step's PARM,
+// which TSO runs as its first command, and the in-stream SYSTSIN:
+//   allocations: ALLOCATE's DDs, which the programs the step runs open as if the JCL defined them.
+//     A data set name in quotes is the whole name; one without has the user's prefix added, which
+//     the job does not say, so it is kept as written with no dsn.
+//   runs: the programs the step starts, by TSO CALL, whose parameter string reaches the program as
+//     EXEC PARM does, and by the DSN subcommand RUN PROGRAM, with PARMS.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.1.0/com.ibm.zos.v2r1.ikjc500/allocsyn.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.2.0/com.ibm.zos.v3r2.ikjc500/alloccmd.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.1.0/com.ibm.zos.v3r1.ikjp100/ikjp100114.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.5.0/com.ibm.zos.v2r5.ikjc200/ikj2o20039.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_3.1.0/com.ibm.zos.v3r1.ikjc500/ikj2l2_CALL_command_operands.htm
+//   https://www.ibm.com/docs/api/v1/content/SSEPEK_13.0.0/comref/src/tpc/db2z_cmd_run.html
+export const TSO_BATCH = new Set(['IKJEFT01', 'IKJEFT1A', 'IKJEFT1B']);
+
+export function tsoCommands(step) {
+  const out = { allocations: [], runs: [], notes: [] };
+  if (!step.pgm || !TSO_BATCH.has(upper(step.pgm))) return out;
+  const { lines, unread } = cards(ddGroups(step).get('SYSTSIN'));
+  if (unread) out.notes.push({ line: step.line, text: `${who(step)} runs TSO with commands in ${unread}, which this reader cannot see, so any ALLOCATE, CALL or RUN it runs is not known` });
+  // PARM keeps JCL's doubled apostrophes; TSO sees one.
+  const cmds = [...(step.parm ? [{ line: step.line, text: step.parm.replace(/''/g, "'") }] : []), ...commands(lines)];
+  for (const cmd of cmds) {
+    const verb = upper(/^\S*/.exec(cmd.text)[0]);
+    const ops = tsoOperands(cmd.text.slice(verb.length));
+    if (verb === 'ALLOC' || verb === 'ALLOCATE') {
+      const file = ops.find((o) => o.key && ALLOC_FILE.test(o.key));
+      if (!file) continue;
+      const names = ops.find((o) => o.key && ALLOC_DATASET.test(o.key));
+      const words = ops.filter((o) => o.word).map((o) => upper(o.word));
+      const sysout = ops.find((o) => o.key === 'SYSOUT') || (words.includes('SYSOUT') ? { value: '' } : null);
+      const datasets = names ? tsoOperands(names.value).map((o) => o.word).filter((w) => w && w !== '*') : [];
+      if (!datasets.length && !sysout) continue;
+      out.allocations.push({
+        dd: upper(unquote(file.value)), line: cmd.line,
+        status: words.find((w) => ALLOC_STATUS.has(w)) || null,
+        sysout: sysout ? upper(sysout.value) || '*' : null,
+        datasets: datasets.map((w) => ({ written: w, dsn: /^'.*'$/.test(w) ? upper(unquote(w)) : null })),
+      });
+    } else if (verb === 'CALL') {
+      const target = ops[0]?.word || (ops[0]?.key ? `${ops[0].key}(${ops[0].value})` : '');
+      const member = /\(([A-Z0-9$#@]{1,8})\)'?$/i.exec(target);
+      const parm = ops[1]?.word && /^'.*'$/s.test(ops[1].word) ? unquote(ops[1].word) : null;
+      out.runs.push({ program: member ? upper(member[1]) : 'TEMPNAME', parm, line: cmd.line, via: 'TSO CALL' });
+    } else if (verb === 'RUN') {
+      const program = ops.find((o) => o.key === 'PROGRAM');
+      if (!program || !/^[A-Z0-9$#@]{1,8}$/i.test(program.value.trim())) continue;
+      const parms = ops.find((o) => o.key === 'PARMS');
+      out.runs.push({ program: upper(program.value.trim()), parm: parms ? unquote(parms.value.trim()) : null, line: cmd.line, via: 'DSN RUN' });
+    }
+  }
+  return out;
+}

package/lib/verify.mjs

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// A verification plan for one path finding, for the estate to run in a test region it owns: the
+// entry to start, where the value goes in, a harmless value that shows the defect, and what to watch
+// for. Where letting the operation run would act - a command, a statement, a job, a connection - the
+// plan stops at the operation and reads a marker there, and never supplies a value that would run.
+// It is built only for `cobolwork explain`, never for a scan report. See docs/spec/reach.md §8.
+import { kindsOf } from './consequence.mjs';
+import { ALL_RULES } from './kernel/registry.mjs';
+import { entryName } from './reach.mjs';
+
+export const MARKER = 'CWVRFY01';
+
+const WHERE = 'a test region the estate owns, holding test data, under its own authorisation: never a production region, and never a system the estate does not own';
+
+const ABSENT = `${MARKER}, after checking that nothing by that name is defined where the program looks`;
+const END_TASK = 'end the task from CEDF or CEDX, or stop the program in the debugger, before the operation runs';
+
+// What goes in, and what reading it at the operation shows. `run` says what letting the operation run
+// shows; null means it would act on something, so the plan stops before it (`stopBefore`).
+const SINKS = {
+  arithmetic: (x) => ({ value: `a letter where ${x.item} expects a digit, such as A in its first position`, reads: `${x.item} holding the letter`, run: 'the task abends ASRA, a data exception (S0C7 in batch), at the operation' }),
+  subscript: (x) => bounds(x, `${x.table ? `${x.table + 1}, one more than the ${x.table} entries in the table` : 'one more than the entries in the table'}, or 0`),
+  'loop-bound': (x) => bounds(x, `${x.table ? `${x.table + 1}, one more than the ${x.table} entries in the table` : 'one more than the entries in the table'}`),
+  'reference-modification': (x) => bounds(x, 'one more than the length of the field, or 0'),
+  'occurs-depending-count': (x) => bounds(x, 'one more than the most entries the OCCURS clause allows, or 0'),
+  'storage-length': (x) => ({ value: 'a length above what the program means to acquire', reads: `the LENGTH or FLENGTH the command is given, from ${x.item}`, run: null, stopBefore: `acquiring that much storage can take the region short on storage: ${END_TASK}` }),
+  'record-key': (x) => ({ value: 'the key of a test record set up for a different test user', reads: `${x.item} holding that key`, run: 'the other user\'s test record comes back to the user who asked for it' }),
+  'record-update': (x) => ({ value: 'the key of a test record set up for a different test user', reads: `${x.item} holding that key`, run: 'the other user\'s test record is changed or deleted: set the record up for this test alone' }),
+  'dynamic-program-load': (x) => ({ value: ABSENT, reads: `${MARKER} as the program the CALL loads, from ${x.item}`, run: `the CALL fails to load ${MARKER} (an S806 abend in batch)` }),
+  'cics-dynamic-transfer': (x) => ({ value: ABSENT, reads: `${MARKER} as the program or transaction the command names, from ${x.item}`, run: `the command fails with PGMIDERR, or TRANSIDERR for a START` }),
+  'dynamic-file-path': (x) => ({ value: ABSENT, reads: `${MARKER} as the file the program assigns, from ${x.item}`, run: 'the OPEN fails with file status 35' }),
+  'cics-sysid': (x) => ({ value: ABSENT, reads: `${MARKER} as the SYSID the command is shipped to, from ${x.item}`, run: 'the command fails with SYSIDERR' }),
+  'queue-name': (x) => marker(x, 'as the queue the command acts on', 'the command would act on a queue the input chose'),
+  'web-response': (x) => ({ value: `${MARKER}<>`, reads: `${MARKER}<> in ${x.item}`, run: `the response body carries ${MARKER}<> as sent, not ${MARKER}&lt;&gt;` }),
+  screen: (x) => ({ value: MARKER, reads: `${MARKER} in ${x.item}`, run: `${MARKER} on the screen` }),
+  log: (x) => ({ value: MARKER, reads: `${MARKER} in ${x.item}`, run: `${MARKER} in the log as sent, which shows a line break would go in the same way` }),
+  'http-header': (x) => marker(x, 'in the header value', 'the header would go to the caller'),
+  'os-command': (x) => marker(x, 'in the command', 'the command would run'),
+  'dynamic-sql': (x) => marker(x, 'in the statement text', 'the statement would run'),
+  'internal-reader': (x) => marker(x, 'in the record written', 'the job would be submitted'),
+  'cics-system-resource': (x) => marker(x, 'as the resource the SET names', 'the command would change a region resource'),
+  'connection-target': (x) => marker(x, 'as the database or queue manager named', 'the connection would be made'),
+  'outbound-host': (x) => marker(x, 'as the host or path of the request', 'the request would go out'),
+  'outbound-http': (x) => marker(x, 'in what the request sends', 'the request would go out'),
+  'socket-send': (x) => marker(x, 'in what the socket sends', 'the data would leave the program'),
+  'message-queue': (x) => marker(x, 'in the message put', 'the message would be put'),
+  'extrapartition-queue': (x) => marker(x, 'in the record written', 'the record would leave the region through its DD'),
+  'xml-document': (x) => marker(x, 'in the document parsed', 'the parser would read it'),
+};
+
+function bounds(x, value) {
+  return {
+    value,
+    reads: `${x.item} out of range at the operation`,
+    ...(x.ssrange ? { run: 'the task abends with a Language Environment range message (IGZ0006S for a subscript), since the program is compiled with SSRANGE' }
+      : { run: null, stopBefore: `without SSRANGE the operation reaches the storage beside the table or field: ${END_TASK}` }),
+  };
+}
+
+function marker(x, where, acts) {
+  return { value: MARKER, reads: `${MARKER} ${where}, from ${x.item}`, run: null, stopBefore: `${acts}: ${END_TASK}` };
+}
+
+// Where the value goes in, by where the finding says the input comes from.
+function enterAt(source, f, src, loc) {
+  const field = f.screen ? `field ${f.screen.field} of map ${f.screen.map}${f.screen.mapset ? ` in mapset ${f.screen.mapset}` : ''}` : null;
+  switch (source) {
+    case 'cics-terminal': return field ? `${field}, received at ${loc}` : `the terminal input received at ${loc}`;
+    case 'cics-protected-field': return `${field || 'the protected field'}: the map protects it, so change it under CEDF in the data the RECEIVE MAP at ${loc} returns, not with a modified client`;
+    case 'cics-web': return `the web request read at ${loc}`;
+    case 'argv-or-env': return `the command line or environment of the run, read at ${loc}`;
+    case 'jcl-parm': return `${src?.detail || 'the PARM'}, in a copy of the job`;
+    case 'jcl-instream': return `${src?.detail || 'the in-stream data'}, in a copy of the job`;
+    case 'file-record': return `a test record in a test copy of the file read at ${loc}`;
+    case 'database': return `a test row in a test copy of the table read at ${loc}`;
+    default: return null;
+  }
+}
+
+// CEDF and CEDX stop at EXEC CICS and EXEC SQL; a CALL, a COMPUTE or a subscript needs a debugger.
+function toolFor(source, entries, program) {
+  const tran = entries.find((e) => e.transaction)?.transaction;
+  const debug = 'or a debugger such as z/OS Debugger where the operation is not an EXEC command';
+  if (source === 'cics-web') return `CEDX ${tran || `on the transaction that runs ${program}`}, since a web request has no terminal, ${debug}`;
+  if (tran || source === 'cics-terminal' || source === 'cics-protected-field') return `CEDF at the terminal that runs ${tran || program}, ${debug}`;
+  return 'a debugger such as z/OS Debugger';
+}
+
+export function verificationPlan(f) {
+  const kinds = ALL_RULES[f.rule]?.evidence === 'path' ? kindsOf(f.rule) : null;
+  if (!kinds || !SINKS[kinds.sink]) return null;
+  const entries = f.startedBy || [];
+  const src = f.related?.[0];
+  const loc = src ? `${src.path}:${src.line}` : 'the source';
+  const last = f.trace?.length ? f.trace[f.trace.length - 1] : null;
+  const table = Number(/a table of (\d+)$/.exec(f.detail || '')?.[1]) || null;
+  const x = { item: last?.item || 'the value', table, ssrange: !!f.ssrange };
+  const sink = `${f.path}:${f.line}`;
+  const tool = toolFor(kinds.source, entries, f.program || 'the program');
+  const start = entries.length
+    ? `${entries.map(entryName).join('; ')}${f.startedByMore ? `; or one of ${f.startedByMore} more not listed` : ''}`
+    : `nothing in this tree starts ${f.program || 'the program'}: start it the way the estate does`;
+
+  if (kinds.source === 'system-response') {
+    return {
+      where: WHERE, start, tool,
+      enter: `nothing: provoke the failure the program reports at ${loc}, such as a key that matches no test record`,
+      value: null,
+      observe: `stop at ${sink} and read ${x.item}: the response code or error text is in it`,
+      run: 'the code or error text reaches the caller in what the program sends back',
+      record: record(f),
+    };
+  }
+
+  const s = SINKS[kinds.sink](x);
+  return {
+    where: WHERE, start, tool,
+    enter: enterAt(kinds.source, f, src, loc),
+    value: s.value,
+    observe: `stop at ${sink} and read ${s.reads}: that is the defect, whatever the operation does next`,
+    run: s.run,
+    ...(s.stopBefore ? { stopBefore: s.stopBefore } : {}),
+    ...(f.guardedFrom && f.guard ? { check: `if the check on ${f.guard.item} at ${f.guard.file}:${f.guard.line} turns the value away first, record not-reproduced: the check stops it, and the finding can be judged a false positive` } : {}),
+    record: record(f),
+  };
+}
+
+const record = (f) => `bring the result in a COBOLWORK_WITNESS feed under "${f.fingerprint}": outcome "reproduced" or "not-reproduced", who ran it, the date and the system; what was entered is not recorded there`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portll/cobolwork",
-  "version": "0.2.76",
+  "version": "0.2.140",
   "description": "COBOL, JCL and CICS security analysis with zero runtime dependencies: reference-format parser, cross-program data flow, mainframe credential rules. Plugs into commitwork.",
   "license": "AGPL-3.0-or-later",
   "author": "Portll <john@portll.net>",