@portll/cobolwork 0.2.76 → 0.2.140

package/lib/ftp.mjs

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { statementCard } from './card.mjs';
+
+// IBM's batch FTP client takes the host and its options on PARM, or the host as the first line of
+// its input, reads subcommands from INPUT, and logs on from NETRC or from its input. CardDemo's job
+// gives the same lines on SYSIN, which is read here when there is no INPUT, though the page below
+// does not say the client falls back to it.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.4.0/com.ibm.zos.v2r4.halu001/ftpreq.htm
+// A session is in cleartext unless something asks for TLS: -a TLS or -r TLS on PARM, or
+// SECURE_MECHANISM TLS in an in-stream SYSFTPD. A SYSFTPD naming a data set is configuration this
+// reader cannot see, so that step is not called cleartext either way.
+//   https://www.ibm.com/docs/en/zos/2.1.0?topic=commands-ftp-command
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.4.0/com.ibm.zos.v2r4.halz002/ftp_cust_client_for_tls.htm
+// PUT, MPUT and APPEND send local files, and IBM's capitals - PUt, MPut, APpend, LCd - are the
+// shortest spellings. A local name in quotes is a whole data set name, //DD: names a DD of the
+// step, and anything else hangs off the local working directory, which only a quoted LCD fixes.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/ftpsubcmd.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/put.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/mput.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/append.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/lcd.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/dd_name_support.htm
+// Get and MGet copy remote files in, each to the local name given or, with none, to the foreign
+// file's own name, placed as a sent name is. SIte FILETYPE=JES makes the remote host submit what
+// is sent as a job and return job output to a Get; FILETYPE=SQL makes it run a query. Either holds
+// for the transfers after it, until another FILETYPE.
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/get.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/mget.htm
+//   https://www.ibm.com/docs/api/v1/content/SSLTBW_2.2.0/com.ibm.zos.v2r2.halu001/site.htm
+const FTP_SENDS = [[/^PUT?$/i, 'PUT'], [/^MP(?:UT?)?$/i, 'MPUT'], [/^AP(?:P(?:E(?:ND?)?)?)?$/i, 'APPEND']];
+
+// Every subcommand on the page above, in IBM's spelling.
+const FTP_SUBCOMMANDS = ['?', '!', 'ACCount', 'APpend', 'AUth', 'AScii', 'BIG5', 'BINary', 'BLock', 'CCc', 'CD',
+  'CDUp', 'CLEar', 'CLose', 'COMpress', 'CProtect', 'CWd', 'DEBug', 'DELEte', 'DELImit', 'DIr', 'DUMP', 'EBcdic',
+  'EUckanji', 'FEature', 'FIle', 'Get', 'GLob', 'HAngeul', 'HElp', 'Ibmkanji', 'JIS78kj', 'JIS83kj', 'Ksc5601',
+  'LANGuage', 'LCd', 'LOCSIte', 'LOCSTat', 'LMkdir', 'LPwd', 'LS', 'MDelete', 'MGet', 'MKdir', 'MKFifo', 'MOde',
+  'MPut', 'MVSGet', 'MVSPut', 'NOop', 'Open', 'PAss', 'PRIvate', 'PROMpt', 'PROTect', 'PROXy', 'PUt', 'PWd', 'QUIt',
+  'QUOte', 'RECord', 'REName', 'REStart', 'RMdir', 'SAfe', 'SChinese', 'SENDPort', 'SENDSite', 'SIte', 'SJiskanji',
+  'SRestart', 'STAtus', 'STREam', 'STRucture', 'SUnique', 'SYstem', 'TChinese', 'TSO', 'TYpe', 'UCs2', 'User', 'Verbose']
+  .map((name) => ({ full: name.toUpperCase(), min: name.match(/^[^a-z]*/)[0].length }));
+const subcommandOf = (word) => {
+  const w = word.toUpperCase();
+  const hit = FTP_SUBCOMMANDS.find((c) => w.length >= c.min && c.full.startsWith(w));
+  return hit ? hit.full : null;
+};
+// A value that stands for a password rather than being one: a symbolic, a mask, or the word itself.
+const PLACEHOLDER = /^(&.*|\*+|X+|\?+|<.*>|\{.*\}|PASSWORD|PASSWD|PWD|PASS|SECRET)$/i;
+
+// The session one FTP step runs, from its DDs grouped by name (ddGroups in lib/utilities.mjs).
+export function ftpSession(step, dds) {
+  let host = null, tls = null;
+  const words = (step.parm || '').split('(')[0].trim().split(/\s+/).filter(Boolean);
+  for (let i = 0; i < words.length; i++) {
+    if (/^-[ar]$/i.test(words[i])) {
+      const mechanism = (words[++i] || '').toUpperCase();
+      if (mechanism === 'TLS') tls = 'asked';
+      else if (mechanism === 'NEVER' && !tls) tls = 'never';
+    } else if (!words[i].startsWith('-') && !host) host = words[i];
+  }
+  let configUnread = null;
+  for (const dd of dds.get('SYSFTPD') || []) {
+    if (dd.inStream) { if (tls !== 'never' && dd.inStream.some((l) => /^\s*SECURE_MECHANISM\s+TLS\b/i.test(l.text))) tls = 'asked'; }
+    else if (dd.dsn && !configUnread) configUnread = dd.dsn;
+  }
+
+  const input = dds.get('INPUT') || dds.get('SYSIN') || [];
+  const hostLine = !host && input[0]?.inStream;
+  let inputUnread = null, lcd = null, unixDir = false;
+  const sends = [], gets = [];
+  let filetype = null;
+  // With no NETRC to answer for it, the client asks for a user ID and a password and in batch reads
+  // them from its input after the host: "user password" on one line, or each on its own. A first
+  // line that is a subcommand means something else answered, a NETRC the client found for itself.
+  // USER and PASS give the same answers later in a session.
+  let expect = dds.has('NETRC') ? null : 'logon', user = null;
+  const passwords = [];
+  const password = (dd, line, value) => { if (!PLACEHOLDER.test(value)) passwords.push({ dd, line, user }); };
+  const local = (name) => {
+    const dd = /^\/\/DD:([A-Z$#@][A-Z0-9$#@]{0,7})$/i.exec(name);
+    if (dd) return { dd: dd[1].toUpperCase(), dsns: (dds.get(dd[1].toUpperCase()) || []).map((d) => d.dsn).filter(Boolean) };
+    const quoted = /^'(.+)'$/.exec(name);
+    if (quoted) return { dsns: [quoted[1].toUpperCase()] };
+    if (name.startsWith('/') || unixDir) return { dsns: [] };
+    return lcd ? { dsns: [`${lcd}.${name.toUpperCase()}`] } : { dsns: [], relative: name };
+  };
+  for (const dd of input) {
+    if (!dd.inStream) { if (dd.dsn && !inputUnread) inputUnread = dd.dsn; continue; }
+    for (const { line, text } of dd.inStream) {
+      const [verb, ...args] = statementCard(text).text.trim().split(/\s+/);
+      if (!verb) continue;
+      if (hostLine && !host) { host = verb; continue; }
+      const sub = subcommandOf(verb);
+      if (expect && !sub) {
+        if (expect === 'logon') user = verb;
+        if (expect === 'password') password(dd, line, verb);
+        else if (args[0]) password(dd, line, args[0]);
+        expect = expect === 'logon' && !args[0] ? 'password' : null;
+        continue;
+      }
+      expect = null;
+      if (sub === 'USER' && args[0]) {
+        user = args[0];
+        if (args[1]) password(dd, line, args[1]); else expect = 'password';
+        continue;
+      }
+      if (sub === 'PASS' && args[0]) { password(dd, line, args[0]); continue; }
+      if (/^LCD?$/i.test(verb) && args[0]) {
+        const quoted = /^'(.+)'$/.exec(args[0]);
+        unixDir = args[0].startsWith('/');
+        lcd = quoted ? quoted[1].toUpperCase() : lcd && !unixDir ? `${lcd}.${args[0].toUpperCase()}` : null;
+        continue;
+      }
+      const site = sub === 'SITE' ? args : sub === 'QUOTE' && subcommandOf(args[0] || '') === 'SITE' ? args.slice(1) : null;
+      if (site) {
+        for (const a of site) { const t = /^FILE(?:T(?:Y(?:P(?:E)?)?)?)?=(\w+)$/i.exec(a); if (t) filetype = t[1].toUpperCase() === 'SEQ' ? null : t[1].toUpperCase(); }
+        continue;
+      }
+      const typed = filetype ? { filetype } : {};
+      if (sub === 'GET' && args[0]) {
+        const to = args[1] && !args[1].startsWith('(') ? args[1] : args[0];
+        gets.push({ line, verb: 'GET', name: args[0], ...typed, ...local(to) });
+        continue;
+      }
+      if (sub === 'MGET') {
+        for (const name of args.filter((a) => !a.startsWith('(') && !/[*?]/.test(a))) gets.push({ line, verb: 'MGET', name, ...typed, ...local(name) });
+        continue;
+      }
+      const sent = FTP_SENDS.find(([re]) => re.test(verb));
+      if (!sent) continue;
+      const foreign = sent[1] !== 'MPUT' && args[1] && !args[1].startsWith('(') ? args[1] : null;
+      for (const name of sent[1] === 'MPUT' ? args : args.slice(0, 1)) sends.push({ line, verb: sent[1], name, foreign: foreign || name, ...typed, ...local(name) });
+    }
+  }
+  const cleartext = tls === 'never' || (!tls && !configUnread);
+  return { host, cleartext, configUnread, inputUnread, logon: dds.has('NETRC') ? 'NETRC' : null, sends, gets, passwords, input };
+}

package/lib/ironwork.mjs

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// `ironwork check` over every program in a tree: IBM Enterprise COBOL's front end as ironwork models
+// it, for an estate whose compile step runs on z/OS and so never meets the build gate otherwise.
+// ironwork is run as a separate program, as cobc is; nothing here links it.
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { directoryTree } from './kernel/source-tree.mjs';
+import { printable } from './kernel/printable.mjs';
+import { buildFileIndex } from './parser.mjs';
+import { isProgram, relPath } from './sources.mjs';
+import { EIB_FIELDS, DIB_FIELDS, SQLCA_FIELDS } from './words.mjs';
+
+// ironwork check exits with IBM's highest return code: 0 clean, 4 warnings only (compiled), 8 E,
+// 12 S, 16 U. Only 0 and 4 produce a program.
+const COMPILED = new Set([0, 4]);
+const REJECTED = new Set([8, 12, 16]);
+// Warnings and informational lines follow the errors, and say nothing about why a program failed.
+const NOT_AN_ERROR = /^(?:informational:|.*?: warning: )/;
+const PER_PROGRAM_MS = 60000;
+const MAX_LISTED = 10;
+
+// ironwork refuses by name what it does not model yet; that says nothing about the program. A name
+// the CICS, DL/I or SQL translator declares it reports as undefined, without saying so, and that is
+// read as its gap, not the program's.
+const NOT_SUPPORTED = /\bnot supported\b/i;
+const TRANSLATOR_NAMES = [EIB_FIELDS, DIB_FIELDS, SQLCA_FIELDS];
+function notModelled(message) {
+  if (NOT_SUPPORTED.test(message)) return true;
+  const name = /^([A-Z][A-Z0-9-]*) is not defined$/.exec(message);
+  return !!name && TRANSLATOR_NAMES.some((s) => s.has(name[1]));
+}
+// A copy library the tree does not hold leaves the program unread, as it does for the scan.
+const UNRESOLVED = /\bno such member in the copy libraries\b/i;
+// A diagnostic can quote a literal from the program, and no output of the gate carries source text.
+const redact = (s) => String(s).replace(/'[^']*'|"[^"]*"/g, "'…'");
+
+// `file:line:col: message` or `file: message`, as ironwork's Error::place writes them. `file` is the
+// program as it was passed, or the COPY member the position is in.
+function diagnostic(line, programPath, rel) {
+  const m = /^(.*?):(\d+):(\d+): (.*)$/.exec(line) || /^(.*?): (.*)$/.exec(line);
+  if (!m) return { path: rel, message: printable(redact(line), 200) };
+  const [file, ln, col, text] = m.length === 5 ? [m[1], Number(m[2]), Number(m[3]), m[4]] : [m[1], null, null, m[2]];
+  const inProgram = resolve(file) === programPath;
+  return {
+    path: rel, ...(ln ? { line: ln, col } : {}), ...(inProgram ? {} : { member: printable(file, 80) }),
+    message: printable(redact(text), 200),
+  };
+}
+
+export function ironworkVersion(path, { env = process.env } = {}) {
+  const r = spawnSync(path, ['--version'], { cwd: tmpdir(), env, encoding: 'utf8', timeout: 10000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+  return r.status === 0 ? printable(String(r.stdout).trim(), 80) || null : null;
+}
+
+// Runs `ironwork check` on each program under `root`, with the tree's copy directories and the
+// estate's copy libraries as -I, and sorts the programs into those it accepts, those it rejects,
+// and those it could not decide: a construct it does not model, a copybook the tree lacks, or a
+// run that ended some other way.
+export function checkWithIronwork(path, root, { allow = null, copylibs = [], env = process.env } = {}) {
+  const programs = [...new Set(directoryTree(root).list())].filter((p) => isProgram(p) && (!allow || allow.has(p))).sort();
+  const libraries = [...buildFileIndex(root).copyDirs, ...copylibs].flatMap((d) => ['-I', d]);
+  const out = { programs: programs.length, accepted: 0, warned: 0, failed: [], notModelled: [], unresolved: [], unrun: [] };
+  for (const file of programs) {
+    const rel = relPath(root, file);
+    const r = spawnSync(path, ['check', file, ...libraries], {
+      cwd: tmpdir(), env, encoding: 'utf8', timeout: PER_PROGRAM_MS, maxBuffer: 1 << 20, windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    if (COMPILED.has(r.status)) { out.accepted++; if (r.status === 4) out.warned++; continue; }
+    if (!REJECTED.has(r.status)) {
+      const why = r.error ? (r.error.code === 'ETIMEDOUT' ? `no answer in ${PER_PROGRAM_MS / 1000}s` : r.error.message) : `ironwork exited ${r.status ?? r.signal}`;
+      out.unrun.push({ path: rel, why: printable(why, 200) });
+      continue;
+    }
+    const found = String(r.stderr || '').split(/\r?\n/).filter((l) => l && !NOT_AN_ERROR.test(l)).map((l) => diagnostic(l, resolve(file), rel));
+    const errors = found.filter((d) => !notModelled(d.message) && !UNRESOLVED.test(d.message));
+    if (errors.length) out.failed.push({ ...errors[0], errors: errors.length });
+    else if (found.some((d) => UNRESOLVED.test(d.message))) out.unresolved.push(found.find((d) => UNRESOLVED.test(d.message)));
+    else out.notModelled.push(found[0] || { path: rel, message: `ironwork exited ${r.status} and gave no error` });
+  }
+  return out;
+}
+
+// The compile check from a checkWithIronwork result: false where a program does not compile, null
+// where every program that did not pass is one ironwork could not decide, true otherwise.
+export function ironworkVerdict(result) {
+  if (result.failed.length) return false;
+  return result.notModelled.length || result.unresolved.length || result.unrun.length ? null : true;
+}
+
+export function ironworkReasons(result) {
+  const reasons = [];
+  const at = (d) => `${d.path}${d.line ? `:${d.line}:${d.col}` : ''}${d.member ? ` (in ${d.member})` : ''}`;
+  if (result.failed.length) {
+    reasons.push(`ironwork check: ${result.failed.length} of ${result.programs} program(s) do not compile as Enterprise COBOL`);
+    for (const d of result.failed.slice(0, MAX_LISTED)) reasons.push(`${at(d)}: ${d.message}`);
+  }
+  if (result.notModelled.length) reasons.push(`ironwork check: ${result.notModelled.length} program(s) use what ironwork does not model yet, so whether they compile is not decided; the first is ${at(result.notModelled[0])}: ${result.notModelled[0].message}`);
+  if (result.unresolved.length) reasons.push(`ironwork check: ${result.unresolved.length} program(s) copy a member the copy libraries do not hold; name the estate's with --copylib`);
+  if (result.unrun.length) reasons.push(`ironwork check: ${result.unrun.length} program(s) were not checked; the first, ${result.unrun[0].path}: ${result.unrun[0].why}`);
+  return reasons;
+}
+
+export const listed = (result) => ({
+  programs: result.programs, accepted: result.accepted, warned: result.warned,
+  failed: result.failed.slice(0, MAX_LISTED), notModelled: result.notModelled.slice(0, MAX_LISTED),
+  unresolved: result.unresolved.slice(0, MAX_LISTED), unrun: result.unrun.slice(0, MAX_LISTED),
+  counts: { failed: result.failed.length, notModelled: result.notModelled.length, unresolved: result.unresolved.length, unrun: result.unrun.length },
+});

package/lib/jcl.mjs

@@ -12,17 +12,14 @@
 // output as `unreadable`, never dropped, because a step nobody parsed is not a step that is not
 // there.
 import { readSource } from './sources.mjs';
-import { copiesOf } from './utilities.mjs';
+import { copiesOf, tsoCommands } from './utilities.mjs';
+import { statementCard } from './card.mjs';
 
 // The operations a statement may carry. Anything else in the operation field is a statement this
 // reader does not know, which is a diagnostic rather than a silent skip.
 export const OPERATIONS = new Set(['JOB', 'EXEC', 'DD', 'PROC', 'PEND', 'SET', 'IF', 'THEN',
   'ELSE', 'ENDIF', 'INCLUDE', 'JCLLIB', 'OUTPUT', 'CNTL', 'ENDCNTL', 'XMIT', 'COMMAND', 'NOTIFY', 'EXPORT']);
 
-// Columns 73 to 80 are the sequence area. They are not the statement, and a payload hidden there
-// is the hidden-content rules' business, not this reader's.
-const STATEMENT_COLUMNS = 72;
-
 // A continued operand resumes in these columns. Outside them it is not a continuation, whatever
 // the previous line ended with.
 const CONTINUE_FROM = 4;
@@ -146,8 +143,10 @@ export function foldStatements(src) {
     const line = i + 1;
     const raw = phys[i];
     if (raw.length > 80) diags.push({ sev: 'warn', line, text: 'line is longer than 80 columns' });
-    const text = raw.slice(0, STATEMENT_COLUMNS).replace(/\s+$/, '');
-    const sequence = raw.slice(STATEMENT_COLUMNS);
+    // The sequence area is not the statement; a payload hidden there is the hidden-content rules' business.
+    const card = statementCard(raw);
+    const text = card.text.replace(/\s+$/, '');
+    const sequence = card.sequence;
 
     if (stream) {
       // A custom DLM ends the stream and nothing else does. The default ends at /* or at the next
@@ -402,6 +401,27 @@ export function parseJcl(src, file, opts = {}) {
     else diags.push({ sev: 'warn', line: 0, text: `symbolic parameter &${s} has no value, so the operands using it were read unsubstituted` });
   }
 
+  // A TSO batch step's ALLOCATE commands define DDs its JCL does not show. Each is kept as a DD of the
+  // step, marked `allocated`, with the datasets of a list concatenated under it as JCL would.
+  for (const s of steps) {
+    const tso = tsoCommands(s);
+    for (const n of tso.notes) diags.push({ sev: 'info', ...n });
+    for (const a of tso.allocations) {
+      const ends = a.datasets.length ? a.datasets : [{ written: null, dsn: null }];
+      ends.forEach((d, i) => {
+        const dd = {
+          name: i === 0 ? a.dd : null, procStep: null, dsn: d.dsn, rawDsn: d.written, referback: null,
+          disp: a.status, access: accessOf(a.status), temporary: false, sysout: a.sysout,
+          inStream: null, dlm: null, concatenated: i > 0, keywords: new Map(), line: a.line, endLine: a.line,
+          step: s.name, allocated: true,
+        };
+        dds.push(dd);
+        s.dds.push(dd);
+        stepOf.set(dd, s);
+      });
+    }
+  }
+
   // What each step's program copies, from lib/utilities.mjs. A program that table does not know
   // copies nothing here, which is not the same as copying nothing.
   const copies = [];

package/lib/kernel/findings.mjs

@@ -42,6 +42,17 @@ export const EVIDENCE = Object.freeze({
   context: 'describes the estate - an entry point, a product in use - and asserts no defect',
 });
 
+// Whether an attacker can use a path finding, most urgent first. lib/exploitability.mjs decides it.
+export const EXPLOITABILITY = Object.freeze({
+  confirmed: 'the estate reproduced it on a system it owns and brought the result as a witness feed',
+  exploitable: 'input an attacker supplies reaches the operation with no check on every route, and the estate declares an entry that carries it open to any user',
+  'attacker-driven': 'input whoever runs an entry supplies reaches the operation with no check on every route; the estate has not declared who may run that entry',
+  restricted: 'input reaches the operation with no check on every route, and every entry that carries it is behind a control the estate named',
+  mitigated: 'input reaches the operation, but a check runs first on every route, or SSRANGE turns an overrun into an abend',
+  upstream: 'the value comes from a file record or a database row, so whoever can write that data drives it',
+  refuted: 'no harmful value arrives: a check leaves only values the operation can take, or no route reaches it',
+});
+
 export const WHO_ACTS = Object.freeze({
   path: "the program's owner",
   construct: 'the owner, or whoever can rotate a credential',

package/lib/kernel/registry.mjs

@@ -25,6 +25,8 @@ import { scanWeb, WEB_RULES } from '../sets/web.mjs';
 import { scanPriv, PRIV_RULES } from '../sets/priv.mjs';
 import { scanLog, LOG_RULES } from '../sets/log.mjs';
 import { scanCompile, COMPILE_RULES } from '../sets/compile.mjs';
+import { scanSemantics, SEMANTICS_RULES } from '../sets/semantics.mjs';
+import { scanZowe, ZOWE_RULES } from '../sets/zowe.mjs';
 import { toolName } from './ruleset.mjs';
 
 // The order is the order a scan runs them and the order --only lists them. It is not significant
@@ -43,6 +45,8 @@ export const REGISTRY = [
   { name: 'compile', scan: scanCompile, rules: COMPILE_RULES },
   { name: 'priv', scan: scanPriv, rules: PRIV_RULES },
   { name: 'log', scan: scanLog, rules: LOG_RULES },
+  { name: 'semantics', scan: scanSemantics, rules: SEMANTICS_RULES },
+  { name: 'zowe', scan: scanZowe, rules: ZOWE_RULES },
 ];
 
 // Re-exported from the kernel's ruleset module, which is where it has to live: this file imports

package/lib/layout.mjs

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// How a data description is laid out in storage: the bytes a PICTURE and USAGE take, where each item
+// starts within its record, and how wide a report group prints. Items are { level, occurs, redefines,
+// sync, children, ... } as lib/parser.mjs builds them.
+
+// The binary sizes a dialect gives COMP by digit count.
+export const BINARY_SIZE = { default: '1-2-4-8', ibm: '2-4-8', mf: '1--8' };
+
+function picInfo(pic, constants) {
+  const info = { digits: 0, display: 0, signed: false, alphanumeric: false, national: false };
+  const re = /(.)\(([A-Za-z0-9_-]+)\)|(.)/g;
+  let m;
+  while ((m = re.exec(pic))) {
+    const ch = (m[1] || m[3]).toUpperCase();
+    let n = 1;
+    if (m[1]) {
+      const raw = m[2];
+      n = /^\d+$/.test(raw) ? Number(raw) : Number(constants && constants.get(raw.toUpperCase()));
+      if (!Number.isFinite(n) || n < 0) n = 0;
+    }
+    if (ch === 'S') { info.signed = true; continue; }
+    if (ch === 'V' || ch === 'P') continue;
+    if (ch === '9') { info.digits += n; info.display += n; continue; }
+    if (ch === 'N' || ch === 'G') { info.national = true; info.display += 2 * n; continue; }
+    if (ch === 'X' || ch === 'A') info.alphanumeric = true;
+    info.display += n;
+  }
+  return info;
+}
+
+// Storage bytes of a literal: hexadecimal literals hold one byte per two digits, a Z literal adds a
+// terminating null, a national literal holds two bytes per character.
+export function literalBytes(tok) {
+  const prefix = tok.prefix || '';
+  if (prefix === 'X' || prefix === 'BX' || prefix === 'NX') return Math.floor(tok.v.length / (prefix === 'NX' ? 4 : 2)) * (prefix === 'NX' ? 2 : 1);
+  if (prefix === 'Z') return tok.v.length + 1;
+  if (prefix === 'N' || prefix === 'NC' || prefix === 'U') return tok.v.length * 2;
+  return tok.v.length;
+}
+
+function binaryBytes(digits, scheme) {
+  if (scheme === '2-4-8') return digits <= 4 ? 2 : digits <= 9 ? 4 : 8;
+  if (scheme === '1--8') return [1, 1, 1, 2, 2, 3, 3, 4, 4, 4, 5, 5, 6, 6, 6, 7, 7, 8, 8][Math.min(digits, 18)] || 8;
+  return digits <= 2 ? 1 : digits <= 4 ? 2 : digits <= 9 ? 4 : 8;
+}
+
+function elementarySize(item, scheme, constants) {
+  if (!item.picture && !item.usage) {
+    const constBytes = constants && constants.textBytes;
+    const fromValue = item.values.reduce((n, v) => n + (v.t === 'lit' ? literalBytes(v) : v.t === 'word' && constBytes && constBytes.has(v.u) ? constBytes.get(v.u) : 0), 0);
+    if (item.section === 'SCREEN' && !fromValue && item.screenRefItem) return item.screenRefItem.size || 0;
+    if (item.section === 'SCREEN') return Math.max(1, fromValue);
+    if (fromValue) return fromValue;
+  }
+  if (item.section === 'SCREEN' && !item.picture) return 1;
+  const usage = item.effectiveUsage || 'DISPLAY';
+  const p = item.picture ? picInfo(item.picture, constants) : null;
+  const digits = p ? p.digits : 0;
+  const u = usage.replace('COMPUTATIONAL', 'COMP');
+  if (u === 'COMP-1' || u === 'FLOAT-SHORT') return 4;
+  if (u === 'COMP-2' || u === 'FLOAT-LONG' || u === 'FLOAT-DECIMAL-16') return 8;
+  if (u === 'FLOAT-DECIMAL-34') return 16;
+  if (u === 'INDEX') return 4;
+  if (u === 'POINTER' || u === 'PROGRAM-POINTER' || u === 'FUNCTION-POINTER' || u === 'PROCEDURE-POINTER') return 8;
+  if (u === 'BINARY-CHAR') return 1;
+  if (u === 'BINARY-SHORT' || u === 'SIGNED-SHORT' || u === 'UNSIGNED-SHORT') return 2;
+  if (u === 'BINARY-LONG' || u === 'BINARY-INT' || u === 'SIGNED-INT' || u === 'UNSIGNED-INT') return 4;
+  if (u === 'BINARY-DOUBLE' || u === 'BINARY-LONG-LONG' || u === 'BINARY-C-LONG' || u === 'SIGNED-LONG' || u === 'UNSIGNED-LONG') return 8;
+  if (u === 'COMP-3' || u === 'PACKED-DECIMAL') return Math.floor(digits / 2) + 1;
+  if (u === 'COMP-6') return Math.ceil(digits / 2);
+  if (u === 'COMP-X' || u === 'COMP-N' || (u === 'COMP-5' && p && p.alphanumeric)) {
+    if (p && p.alphanumeric) return p.display;
+    return Math.max(1, Math.ceil((digits * Math.log(10)) / Math.log(256)));
+  }
+  if (u === 'COMP' || u === 'COMP-4' || u === 'COMP-5' || u === 'BINARY') return binaryBytes(digits, scheme);
+  let len = p ? p.display : 0;
+  if (item.signSeparate && p && p.signed) len++;
+  return len;
+}
+
+// SYNCHRONIZED aligns a binary, floating-point, pointer or index item to its own length; packed,
+// COMP-X and display items are not moved.
+const ALIGNED_USAGE = /^(COMP|COMP-[1245]|BINARY(-[A-Z-]+)?|FLOAT-[A-Z0-9-]+|(PROGRAM-|FUNCTION-|PROCEDURE-)?POINTER|INDEX|(UN)?SIGNED-[A-Z]+)$/;
+
+export function computeSizes(roots, scheme, constants) {
+  // `at` is where the item starts, counted from the start of its record, because the compiler aligns
+  // a SYNCHRONIZED item against the record and puts the slack inside the group that holds it. A
+  // table's entry is laid out from its own start and rounded up to its widest alignment, so every
+  // occurrence aligns alike.
+  const visit = (item, inheritedUsage, inheritedSignSeparate, at) => {
+    item.effectiveUsage = item.usage || inheritedUsage || null;
+    if (inheritedSignSeparate && !item.signExplicit) item.signSeparate = true;
+    const structural = item.children.filter(c => c.level !== 88 && c.level !== 66 && c.level !== 78);
+    if (!structural.length) {
+      const one = elementarySize(item, scheme, constants);
+      item.contributes = one * item.occurs;
+      // The listing prints the whole table only for POINTER and INDEX; every other usage prints one occurrence.
+      const wholeTable = /^(POINTER|INDEX)$/.test(item.effectiveUsage || '');
+      item.size = wholeTable ? item.contributes : one;
+      const usage = (item.effectiveUsage || '').replace('COMPUTATIONAL', 'COMP');
+      item.align = item.sync && ALIGNED_USAGE.test(usage) ? Math.min(one, 8) : 1;
+      item.maxAlign = item.align;
+      return;
+    }
+    const base = item.occurs > 1 ? 0 : at;
+    let offset = 0;
+    let end = 0;
+    let maxAlign = 1;
+    const startOf = new Map();
+    for (const c of structural) {
+      if (c.redefines) {
+        // REDEFINES names a SIBLING. Resolving it by name across the whole program reached the
+        // first item of that name anywhere, which crossed records.
+        const known = startOf.has(c.redefines);
+        visit(c, item.effectiveUsage, item.signSeparate, base + (known ? startOf.get(c.redefines) : offset));
+        const start = known ? startOf.get(c.redefines) : offset - c.contributes;
+        startOf.set(c.name, start);
+        c.localStart = start;
+        end = Math.max(end, start + c.contributes);
+        // A REDEFINES larger than the item it redefines pushes the next sibling past its end.
+        offset = Math.max(offset, start + c.contributes);
+        maxAlign = Math.max(maxAlign, c.maxAlign);
+        continue;
+      }
+      visit(c, item.effectiveUsage, item.signSeparate, base + offset);
+      const skew = (base + offset) % c.align;
+      if (c.align > 1 && skew) offset += c.align - skew;
+      startOf.set(c.name, offset);
+      c.localStart = offset;
+      offset += c.contributes;
+      end = Math.max(end, offset);
+      maxAlign = Math.max(maxAlign, c.maxAlign);
+    }
+    if (item.occurs > 1 && end % maxAlign) end += maxAlign - (end % maxAlign);
+    item.size = end * item.occurs;
+    item.contributes = item.size;
+    item.align = 1;
+    item.maxAlign = maxAlign;
+  };
+  for (const r of roots) visit(r, null, false, 0);
+  // Offsets are assigned after sizing: a child's absolute start depends on its parent's, which is
+  // only known once the parent's own siblings have been laid out.
+  const place = (item, at) => {
+    item.offset = at;
+    for (const c of item.children) if (c.localStart != null) place(c, at + c.localStart);
+  };
+  for (const r of roots) place(r, 0);
+}
+
+// A report group is laid out by column, not by adding up its items: a line is as wide as the column
+// its rightmost item ends in, COLUMN PLUS counting on from the end of the item before. A group holds
+// its lines one after another, and every 01 group of a report, like the file the report is written
+// to, is as large as the largest group.
+export function layoutReport(rd) {
+  const structural = (x) => x.children.filter(c => c.level !== 88 && c.level !== 66 && c.level !== 78);
+  const mark = (x) => { x.rd = rd; for (const c of x.children) mark(c); };
+  for (const g of rd.groups) mark(g);
+  let width = 0;
+  // Items printed at the same column under PRESENT WHEN each keep their own storage, so a line is
+  // never smaller than its items laid end to end.
+  const lineWidth = (line) => {
+    let last = 0;
+    let right = 0;
+    let total = 0;
+    const place = (c) => {
+      const len = c.contributes || c.size || 0;
+      const start = c.rwColumn ? (c.rwColumn.at != null ? c.rwColumn.at : last + c.rwColumn.plus) : last + 1;
+      last = start + len - 1;
+      right = Math.max(right, last);
+      total += len;
+    };
+    const walk = (x) => { for (const c of structural(x)) { if (structural(c).length) walk(c); else place(c); } };
+    if (structural(line).length) walk(line);
+    else place(line);
+    return Math.max(right, total);
+  };
+  // The entries that open a line; a group with no LINE clause anywhere in it is one line.
+  for (const g of rd.groups) {
+    const lines = [];
+    const collect = (x) => { if (x.rwLine) { lines.push(x); return; } for (const c of structural(x)) collect(c); };
+    collect(g);
+    if (!lines.length) lines.push(g);
+    let total = 0;
+    for (const line of lines) {
+      const w = lineWidth(line);
+      if (line !== g) { line.size = w; line.contributes = w * (line.occurs || 1); }
+      total += w;
+    }
+    width = Math.max(width, total);
+  }
+  for (const g of rd.groups) { g.size = width; g.contributes = width; }
+  rd.width = width;
+}
+
+// Whether an item's bytes are read as decimal digits: zoned (DISPLAY with a numeric picture) or
+// packed. A group, an edited picture, binary and floating point are not.
+export function holdsDecimal(it) {
+  if ((it.children || []).some((c) => c.level !== 88)) return false;
+  const usage = String(it.effectiveUsage || 'DISPLAY').replace('COMPUTATIONAL', 'COMP');
+  if (usage === 'COMP-3' || usage === 'PACKED-DECIMAL' || usage === 'COMP-6') return true;
+  return usage === 'DISPLAY' && !!it.picture && /9/.test(it.picture) && /^[S9VP()0-9]+$/i.test(it.picture);
+}

package/lib/option-diff.mjs

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Which compiler options a change to a program's CBL and PROCESS cards changes, for the families
+// that change arithmetic, validation or collation without touching a statement
+// (docs/spec/evidence.md §13.4). Spellings come from IBM's option table (lib/enterprise-options.mjs).
+import { OPTION_SPELLINGS } from './enterprise-options.mjs';
+import { optionCards, optionTokens } from './options.mjs';
+
+export const WATCHED = ['TRUNC', 'ARITH', 'NUMPROC', 'NUMCHECK', 'SSRANGE', 'CODEPAGE', 'INTDATE'];
+const ARITH_SUBS = { C: 'COMPAT', COMPAT: 'COMPAT', E: 'EXTEND', EXTEND: 'EXTEND' };
+
+// One option token as `FAMILY(SUB,...)` or `NOFAMILY`, or null for a family not watched.
+function settingOf(token) {
+  const m = /^([A-Z0-9-]+)(?:\((.*)\))?$/.exec(token);
+  if (!m) return null;
+  const spelled = OPTION_SPELLINGS[m[1]];
+  if (!spelled || !WATCHED.includes(spelled[0])) return null;
+  const [family, off] = spelled;
+  if (off) return { family, value: `NO${family}` };
+  let subs = m[2] === undefined ? [] : optionTokens(m[2]);
+  if (family === 'ARITH') subs = subs.map((s) => ARITH_SUBS[s] || s);
+  if (family === 'NUMCHECK' || family === 'SSRANGE') subs = [...subs].sort();
+  return { family, value: subs.length ? `${family}(${subs.join(',')})` : family };
+}
+
+// The watched options a program's cards set, the later card winning, each with its line.
+export function optionsInForce(text) {
+  const state = new Map();
+  for (const card of optionCards(text)) {
+    for (const token of card.options) {
+      const s = settingOf(token);
+      if (s) state.set(s.family, { value: s.value, line: card.line });
+    }
+  }
+  return state;
+}
+
+export function optionChanges(baseText, headText) {
+  const before = optionsInForce(baseText);
+  const after = optionsInForce(headText);
+  const out = [];
+  for (const family of WATCHED) {
+    const b = before.get(family);
+    const a = after.get(family);
+    const base = b ? b.value : 'default';
+    const head = a ? a.value : 'default';
+    if (base !== head) out.push({ option: family, base, head, line: (a || b).line });
+  }
+  return out;
+}