@portll/cobolwork 0.5.0 → 0.7.0

package/lib/pli/stmt/stream.mjs

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Parsers for PL/I stream I/O statements: GET, PUT, DISPLAY, FORMAT, and FLUSH.
+import { cursor, split } from '../cursor.mjs';
+import { parseExpression, parseReference } from '../expr.mjs';
+
+function parseFormatItem(c) {
+  const start = c.pos;
+  let factor = null;
+  // A parenthesised group followed by another item is an iteration factor, (N) F(5,2); one followed
+  // by ',' or the end is a nested format list, (A, X(2)).
+  if (c.isOp('(')) {
+    const inner = c.group();
+    const next = c.peek();
+    if (next && (next.t === 'word' || (next.t === 'op' && next.v === '('))) {
+      const s = cursor(inner);
+      factor = parseExpression(s);
+      if (!s.done()) s.fail('end of iteration factor');
+    } else {
+      c.pos = start;
+    }
+  } else if (c.peek() && c.peek().t === 'num') {
+    factor = c.next();
+  }
+
+  if (c.isOp('(')) {
+    const inner = c.group();
+    const s = cursor(inner);
+    const items = [];
+    while (!s.done()) {
+      const item = parseFormatItem(s);
+      items.push(item);
+      if (!s.done()) {
+        if (s.isOp(',')) s.next();
+        else s.fail("',' or ')'");
+      }
+    }
+    const toks = c.slice(start);
+    return { factor, items, toks };
+  }
+
+  const t = c.peek();
+  if (!t) c.fail('a format item');
+  if (t.t === 'word') {
+    c.next();
+    if (c.isOp('(')) c.group();
+    else if (t.u === 'P' && c.peek() && c.peek().t === 'lit') c.next();
+  } else if (t.t === 'lit') {
+    c.next();
+  } else {
+    c.fail('a format item');
+  }
+  return { factor, items: null, toks: c.slice(start) };
+}
+
+function parseFormatList(c) {
+  const inner = c.group();
+  const s = cursor(inner);
+  const items = [];
+  while (!s.done()) {
+    const item = parseFormatItem(s);
+    items.push(item);
+    if (!s.done()) {
+      if (s.isOp(',')) s.next();
+      else s.fail("',' or ')'");
+    }
+  }
+  return items;
+}
+
+// A repetitive specification, (X(I) DO I = 1 TO N), is an item whose parentheses hold a DO at depth one.
+function isRepetitive(toks) {
+  if (!toks.length || toks[0].t !== 'op' || toks[0].v !== '(') return false;
+  let depth = 0;
+  for (const t of toks) {
+    if (t.t === 'op' && t.v === '(') depth++;
+    else if (t.t === 'op' && t.v === ')') depth--;
+    else if (depth === 1 && t.t === 'word' && t.u === 'DO') return true;
+  }
+  return false;
+}
+
+function parseDataList(c) {
+  const items = [];
+  for (const toks of split(c.group(), ',')) {
+    if (!toks.length) c.fail('a data item');
+    if (isRepetitive(toks)) { items.push({ t: 'repetitive', toks }); continue; }
+    const s = cursor(toks);
+    items.push(parseExpression(s));
+    if (!s.done()) s.fail("',' or ')'");
+  }
+  return items;
+}
+
+function parsePut(c, stmt, ctx) {
+  c.expectWord('PUT');
+  const node = { kind: 'PUT', file: null, string: null, page: false, line: null, skip: null, mode: null, data: [], formats: [] };
+
+  while (!c.done()) {
+    if (c.isWord('FILE')) {
+      c.next();
+      c.expectOp('(');
+      node.file = parseReference(c);
+      c.expectOp(')');
+    } else if (c.isWord('STRING')) {
+      c.next();
+      c.expectOp('(');
+      node.string = parseExpression(c);
+      c.expectOp(')');
+    } else if (c.isWord('PAGE')) {
+      c.next();
+      node.page = true;
+    } else if (c.isWord('LINE')) {
+      c.next();
+      c.expectOp('(');
+      node.line = parseExpression(c);
+      c.expectOp(')');
+    } else if (c.isWord('SKIP')) {
+      c.next();
+      if (c.isOp('(')) {
+        c.next();
+        node.skip = parseExpression(c);
+        c.expectOp(')');
+      } else {
+        node.skip = true;
+      }
+    } else if (c.isWord('LIST')) {
+      c.next();
+      node.mode = 'LIST';
+      if (c.isOp('(')) {
+        node.data = parseDataList(c);
+      }
+    } else if (c.isWord('EDIT')) {
+      c.next();
+      node.mode = 'EDIT';
+      // EDIT takes one or more (data list) (format list) pairs.
+      do {
+        node.data.push(...parseDataList(c));
+        node.formats.push(parseFormatList(c));
+      } while (c.isOp('('));
+    } else if (c.isWord('DATA')) {
+      c.next();
+      node.mode = 'DATA';
+      if (c.isOp('(')) {
+        node.data = parseDataList(c);
+      }
+    } else {
+      c.fail('PUT option');
+    }
+  }
+  return node;
+}
+
+function parseGet(c, stmt, ctx) {
+  c.expectWord('GET');
+  const node = { kind: 'GET', file: null, string: null, page: false, line: null, skip: null, copy: null, mode: null, data: [], formats: [] };
+
+  while (!c.done()) {
+    if (c.isWord('FILE')) {
+      c.next();
+      c.expectOp('(');
+      node.file = parseReference(c);
+      c.expectOp(')');
+    } else if (c.isWord('STRING')) {
+      c.next();
+      c.expectOp('(');
+      node.string = parseExpression(c);
+      c.expectOp(')');
+    } else if (c.isWord('PAGE')) {
+      c.next();
+      node.page = true;
+    } else if (c.isWord('LINE')) {
+      c.next();
+      c.expectOp('(');
+      node.line = parseExpression(c);
+      c.expectOp(')');
+    } else if (c.isWord('SKIP')) {
+      c.next();
+      if (c.isOp('(')) {
+        c.next();
+        node.skip = parseExpression(c);
+        c.expectOp(')');
+      } else {
+        node.skip = true;
+      }
+    } else if (c.isWord('COPY')) {
+      c.next();
+      if (c.isOp('(')) {
+        c.next();
+        node.copy = parseReference(c);
+        c.expectOp(')');
+      } else {
+        node.copy = true;
+      }
+    } else if (c.isWord('LIST')) {
+      c.next();
+      node.mode = 'LIST';
+      if (c.isOp('(')) {
+        node.data = parseDataList(c);
+      }
+    } else if (c.isWord('EDIT')) {
+      c.next();
+      node.mode = 'EDIT';
+      // EDIT takes one or more (data list) (format list) pairs.
+      do {
+        node.data.push(...parseDataList(c));
+        node.formats.push(parseFormatList(c));
+      } while (c.isOp('('));
+    } else if (c.isWord('DATA')) {
+      c.next();
+      node.mode = 'DATA';
+      if (c.isOp('(')) {
+        node.data = parseDataList(c);
+      }
+    } else {
+      c.fail('GET option');
+    }
+  }
+  return node;
+}
+
+function parseDisplay(c, stmt, ctx) {
+  c.expectWord('DISPLAY');
+  c.expectOp('(');
+  const value = parseExpression(c);
+  c.expectOp(')');
+  const node = { kind: 'DISPLAY', value, reply: null, event: null, routcde: null, desc: null };
+
+  while (!c.done()) {
+    if (c.isWord('REPLY')) {
+      c.next();
+      c.expectOp('(');
+      node.reply = parseReference(c);
+      c.expectOp(')');
+    } else if (c.isWord('EVENT')) {
+      c.next();
+      c.expectOp('(');
+      node.event = parseReference(c);
+      c.expectOp(')');
+    } else if (c.isWord('ROUTCDE')) {
+      c.next();
+      c.expectOp('(');
+      node.routcde = parseDataList(c);
+      c.expectOp(')');
+    } else if (c.isWord('DESC')) {
+      c.next();
+      c.expectOp('(');
+      node.desc = parseDataList(c);
+      c.expectOp(')');
+    } else {
+      c.fail('DISPLAY option');
+    }
+  }
+  return node;
+}
+
+function parseFormat(c, stmt, ctx) {
+  c.expectWord('FORMAT');
+  const items = parseFormatList(c);
+  return { kind: 'FORMAT', items };
+}
+
+function parseFlush(c, stmt, ctx) {
+  c.expectWord('FLUSH');
+  c.expectWord('FILE');
+  c.expectOp('(');
+  let file;
+  if (c.isOp('*')) {
+    c.next();
+    file = '*';
+  } else {
+    file = parseReference(c);
+  }
+  c.expectOp(')');
+  return { kind: 'FLUSH', file };
+}
+
+export const parsers = {
+  PUT: parsePut,
+  GET: parseGet,
+  DISPLAY: parseDisplay,
+  FORMAT: parseFormat,
+  FLUSH: parseFlush,
+};

package/lib/pli/storage.mjs

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The storage a PL/I element takes and the boundary it needs, from its DECLARE attributes, as the
+// Enterprise PL/I Language Reference's alignment table gives them (LP(32), OFFSETSIZE(4)). Sizes
+// and alignments are in bits so unaligned bit strings pack.
+
+const STRING_TYPES = new Set(['CHARACTER', 'BIT', 'GRAPHIC', 'WIDECHAR', 'UCHAR']);
+const UNALIGNED_BY_DEFAULT = new Set([...STRING_TYPES, 'PICTURE']);
+const ARITHMETIC = new Set(['FIXED', 'FLOAT', 'BINARY', 'DECIMAL', 'PRECISION', 'SIGNED', 'UNSIGNED', 'REAL', 'COMPLEX']);
+const UNIT = { CHARACTER: 8, BIT: 1, GRAPHIC: 16, WIDECHAR: 16, UCHAR: 32 };
+// Program-control data: bytes and alignment in bytes.
+const CONTROL = { POINTER: [4, 4], HANDLE: [4, 4], OFFSET: [4, 4], FILE: [4, 4], ENTRY: [8, 4], LABEL: [8, 4], FORMAT: [8, 4], TASK: [16, 4] };
+
+// Names that occupy no storage of their own.
+const NO_STORAGE = new Set(['BUILTIN', 'GENERIC', 'CONDITION']);
+// File description attributes declare a file even when FILE itself is not written.
+const FILE_DESCRIPTION = new Set(['STREAM', 'RECORD', 'INPUT', 'OUTPUT', 'UPDATE', 'SEQUENTIAL', 'DIRECT', 'TRANSIENT', 'KEYED', 'PRINT', 'ENVIRONMENT', 'BUFFERED', 'UNBUFFERED', 'BACKWARDS', 'EXCLUSIVE']);
+// Attributes that say nothing about the data type, so a name carrying only these takes the default.
+const NOT_TYPE = new Set(['STATIC', 'AUTOMATIC', 'BASED', 'CONTROLLED', 'DEFINED', 'POSITION', 'PARAMETER', 'EXTERNAL', 'INTERNAL', 'INITIAL', 'ALIGNED', 'UNALIGNED', 'NORMAL', 'ABNORMAL', 'ASSIGNABLE', 'NONASSIGNABLE', 'CONNECTED', 'NONCONNECTED', 'BYADDR', 'BYVALUE', 'OPTIONAL', 'INONLY', 'OUTONLY', 'INOUT', 'RESERVED', 'VALUE']);
+
+const plainNumber = (toks) => (toks && toks.length === 1 && toks[0].t === 'num' && /^\d+$/.test(toks[0].v) ? Number(toks[0].v) : null);
+
+function precisionOf(args) {
+  if (!args || !args.length) return null;
+  const parts = [[]];
+  for (const t of args) { if (t.t === 'op' && t.v === ',') parts.push([]); else parts[parts.length - 1].push(t); }
+  const signed = (p) => (p.length === 2 && p[0].t === 'op' && p[0].v === '-' ? -plainNumber([p[1]]) : plainNumber(p));
+  return { p: plainNumber(parts[0]), q: parts[1] ? signed(parts[1]) : 0 };
+}
+
+// Bytes a PICTURE occupies: every picture character except V, K and the F scaling factor, a
+// repetition factor (n) multiplying the character after it, CR and DB two characters each.
+export function pictureBytes(pic) {
+  const s = pic.toUpperCase().replace(/F\(\s*[+-]?\d+\s*\)/g, '');
+  let n = 0;
+  for (const m of s.matchAll(/\((\d+)\)(CR|DB|.)|(CR|DB)|([^VK])|[VK]/g)) {
+    if (m[2]) n += Number(m[1]) * (m[2].length === 2 ? 2 : m[2] === 'V' || m[2] === 'K' ? 0 : 1);
+    else if (m[3]) n += 2;
+    else if (m[4]) n += 1;
+  }
+  return n;
+}
+
+// { type, bits, align (bits), aligned, varying, base, scale, precision, known } for one element.
+// bits is null when an extent is not a constant (CHAR(*), CHAR(N), REFER). align is what the
+// element needs once ALIGNED or UNALIGNED is settled; `inherited` is the containing structure's
+// explicit choice, used when the element makes none of its own.
+export function storageOf(attributes, { inherited = null, name = null } = {}) {
+  const has = (n) => attributes.find((a) => a.name === n);
+  if (attributes.some((a) => NO_STORAGE.has(a.name))) return { type: attributes.find((a) => NO_STORAGE.has(a.name)).name, bits: 0, align: 8, aligned: null, known: true, storage: false };
+  if (has('TYPE')) return { type: 'TYPE', typeName: has('TYPE').args?.[0]?.u ?? null, bits: null, align: 8, aligned: null, known: false };
+  if (!has('FILE') && attributes.some((a) => FILE_DESCRIPTION.has(a.name))) attributes = [...attributes, { name: 'FILE', args: null }];
+  // RULES(IBM): a name with no data attribute is FIXED BINARY(15) when it starts with I to N, else
+  // FLOAT DECIMAL(6).
+  if (name && attributes.every((a) => NOT_TYPE.has(a.name))) {
+    const implicit = /^[I-N]/.test(name) ? [{ name: 'FIXED', args: null }, { name: 'BINARY', args: null }] : [{ name: 'FLOAT', args: null }, { name: 'DECIMAL', args: null }];
+    return { ...storageOf([...attributes, ...implicit], { inherited }), implicit: true };
+  }
+  const explicit = has('ALIGNED') ? true : has('UNALIGNED') ? false : null;
+  const alignedN = has('ALIGNED') && plainNumber(has('ALIGNED').args);
+  let type = null;
+  let bits = null;
+  let aligned;
+  let alignAligned = 8;
+  let alignUnaligned = 8;
+  const out = {};
+
+  const stringType = attributes.find((a) => STRING_TYPES.has(a.name));
+  const varying = has('VARYING') ? 'VARYING' : has('VARYINGZ') ? 'VARYINGZ' : has('VARYING4') ? 'VARYING4' : null;
+  if (stringType) {
+    type = stringType.name;
+    const n = stringType.args ? plainNumber(stringType.args) : 1;
+    const unit = UNIT[type];
+    aligned = explicit ?? inherited ?? !UNALIGNED_BY_DEFAULT.has(type);
+    if (n != null) {
+      if (type === 'BIT' && !varying) bits = aligned ? Math.ceil(n / 8) * 8 : n;
+      else if (type === 'BIT') bits = (varying === 'VARYING4' ? 32 : 16) + (aligned ? Math.ceil(n / 8) * 8 : n);
+      else bits = n * unit + (varying === 'VARYING' ? 16 : varying === 'VARYING4' ? 32 : varying === 'VARYINGZ' ? (type === 'CHARACTER' || type === 'UCHAR' ? 8 : 16) : 0);
+    }
+    alignAligned = varying === 'VARYING' ? 16 : varying === 'VARYING4' ? 32 : 8;
+    alignUnaligned = type === 'BIT' && !varying ? 1 : 8;
+    Object.assign(out, { length: n, varying });
+  } else if (has('PICTURE')) {
+    type = 'PICTURE';
+    aligned = explicit ?? inherited ?? false;
+    bits = has('PICTURE').picture != null ? pictureBytes(has('PICTURE').picture) * 8 : null;
+    out.picture = has('PICTURE').picture ?? null;
+  } else if (has('AREA')) {
+    type = 'AREA';
+    aligned = true;
+    const n = has('AREA').args ? plainNumber(has('AREA').args) : 1000;
+    bits = n == null ? null : (16 + n) * 8;
+    alignAligned = alignUnaligned = 64;
+  } else if (Object.keys(CONTROL).some((k) => has(k))) {
+    type = Object.keys(CONTROL).find((k) => has(k));
+    aligned = explicit ?? inherited ?? true;
+    const limited = type === 'ENTRY' && has('LIMITED');
+    const [bytes, align] = limited ? [4, 4] : CONTROL[type];
+    bits = bytes * 8;
+    alignAligned = align * 8;
+  } else if (attributes.some((a) => ARITHMETIC.has(a.name))) {
+    const last = (names) => [...attributes].reverse().find((a) => names.includes(a.name) && a.args);
+    const scale = has('FIXED') ? 'FIXED' : 'FLOAT';
+    const base = has('BINARY') ? 'BINARY' : 'DECIMAL';
+    const prec = precisionOf(last(['FIXED', 'FLOAT', 'BINARY', 'DECIMAL', 'PRECISION'])?.args);
+    const unsigned = !!has('UNSIGNED');
+    const p = prec?.p ?? (scale === 'FIXED' ? (base === 'BINARY' ? 15 : 5) : base === 'BINARY' ? 21 : 6);
+    type = `${scale} ${base}`;
+    aligned = explicit ?? inherited ?? true;
+    Object.assign(out, { scale, base, precision: p, fraction: prec?.q ?? 0, signed: !unsigned });
+    if (prec && prec.p == null) bits = null;
+    else if (scale === 'FIXED' && base === 'DECIMAL') { bits = Math.ceil((p + 1) / 2) * 8; alignAligned = 8; }
+    else if (scale === 'FIXED') {
+      const q = unsigned ? p - 1 : p;
+      const bytes = q <= 7 ? 1 : q <= 15 ? 2 : q <= 31 ? 4 : 8;
+      bits = bytes * 8;
+      alignAligned = bytes * 8;
+    } else {
+      const short = base === 'BINARY' ? p <= 21 : p <= 6;
+      const long = base === 'BINARY' ? p <= 53 : p <= 16;
+      bits = short ? 32 : long ? 64 : 128;
+      alignAligned = short ? 32 : 64;
+    }
+    if (has('COMPLEX') && bits != null) bits *= 2;
+  } else {
+    return { type: null, bits: null, align: 8, aligned: explicit ?? inherited ?? null, known: false };
+  }
+  const align = alignedN ? alignedN * 8 : aligned ? alignAligned : alignUnaligned;
+  return { type, bits, align, aligned, known: bits != null, ...out };
+}

package/lib/policy.mjs

@@ -26,9 +26,13 @@ export const DEFAULT_POLICY = Object.freeze({
   checks: ['subscript', 'reference-modification'],
   forbid: { enterprise: [], gnucobol: [], gcobol: [] },
   requireEquivalence: 'never',
+  interface: 'warn',
 });
 
 export const EQUIVALENCE_MODES = ['never', 'machineAuthored', 'always'];
+// How an abend from a subprogram fuzzed at its interface, with no caller run shown to pass the input,
+// is gated: `warn` never blocks on it, `tier` gates it as any other finding.
+export const INTERFACE_MODES = ['warn', 'tier'];
 
 const KEYS = Object.keys(DEFAULT_POLICY);
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -64,6 +68,7 @@ export function validatePolicy(raw) {
     else for (const c of raw.checks) if (!CHECKS.includes(c)) errs.push(`checks: ${printable(c, 40)} is not one of ${CHECKS.join(', ')}`);
   }
   if ('requireEquivalence' in raw && !EQUIVALENCE_MODES.includes(raw.requireEquivalence)) errs.push(`requireEquivalence takes ${EQUIVALENCE_MODES.join(', ')}`);
+  if ('interface' in raw && !INTERFACE_MODES.includes(raw.interface)) errs.push(`interface takes ${INTERFACE_MODES.join(', ')}`);
   if ('forbid' in raw) {
     if (!isObject(raw.forbid)) errs.push(`forbid must be an object keyed by ${COMPILERS.join(', ')}`);
     else for (const [c, list] of Object.entries(raw.forbid)) {
@@ -142,6 +147,7 @@ export function combinePolicies({ floor = null, repository = null } = {}) {
     checks: checks.value,
     forbid: Object.fromEntries(COMPILERS.map((c) => [c, union((f.forbid || {})[c] || [], (r.forbid || {})[c] || [])])),
     requireEquivalence: pick('requireEquivalence', (a, b) => (EQUIVALENCE_MODES.indexOf(a) >= EQUIVALENCE_MODES.indexOf(b) ? a : b)),
+    interface: pick('interface', (a, b) => (a === 'tier' || b === 'tier' ? 'tier' : 'warn')),
     rules: {},
   };
   setBy.checks = checks.by;

package/lib/precompile-check.mjs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The compile check `cobolwork build --precompile` runs before the caller's compiler: each program the
+// compiler command names that holds EXEC SQL or EXEC CICS is translated by lib/precompile.mjs into a
+// directory of its own, beside the stand-in copybooks and translated members it needs, and given to
+// the same compiler with -fsyntax-only, so a program GnuCOBOL refuses only for its EXEC blocks is
+// checked. Nothing it writes outlives the check.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, delimiter, dirname, extname, join, relative, resolve } from 'node:path';
+import { parseBms } from './bms.mjs';
+import { printable } from './kernel/printable.mjs';
+import { detectFormat, parseSource } from './parser.mjs';
+import { precompile } from './precompile.mjs';
+import { isBms, isProgram, readSource } from './sources.mjs';
+
+const COPY_EXTENSIONS = ['', '.cpy', '.CPY', '.cbl', '.CBL', '.cob', '.COB'];
+const MAX_ERRORS = 3;
+
+// A COPY member's text from the first directory holding it, as cobc searches them.
+export const copybookIn = (dirs) => (name) => {
+  for (const d of dirs) {
+    for (const ext of COPY_EXTENSIONS) {
+      const p = join(d, name + ext);
+      try { if (statSync(p).isFile()) return readSource(p).text; } catch { /* not here */ }
+    }
+  }
+  return null;
+};
+
+// The BMS files under a repository, the member names its other files supply, and the mapsets it holds
+// no copybook for, whose symbolic maps the translator writes.
+export function repositoryBms(repoRoot) {
+  const files = [];
+  const walk = (d) => {
+    let es;
+    try { es = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of es) {
+      if (e.name === '.git' || e.name.startsWith('._')) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p); else files.push(p);
+    }
+  };
+  walk(repoRoot);
+  const bms = files.filter(isBms);
+  const members = new Set(files.filter((f) => !bms.includes(f)).map((f) => basename(f, extname(f)).toUpperCase()));
+  const mapsets = bms.flatMap((f) => { try { return parseBms(readFileSync(f, 'latin1')).mapsets; } catch { return []; } })
+    .filter((ms) => ms.name && !members.has(ms.name.toUpperCase()));
+  return { bms, has: (n) => members.has(n.toUpperCase()), mapsets };
+}
+
+const EXEC = /EXEC\s+(?:SQL|CICS)\b/i;
+const DLI = /EXEC\s+DLI\b/i;
+const redact = (s) => String(s).replace(/'[^']*'|"[^"]*"/g, "'…'");
+
+// The copy directories a cobc or gcobol argument vector names, in order: -I <dir> and -I<dir>.
+function includeDirsOf(argv, cwd) {
+  const dirs = [];
+  argv.forEach((a, i) => {
+    if (a === '-I' && argv[i + 1]) dirs.push(resolve(cwd, argv[i + 1]));
+    else if (a.startsWith('-I') && a.length > 2) dirs.push(resolve(cwd, a.slice(2)));
+  });
+  return dirs;
+}
+
+// The argument vector with -o and its value taken out: a syntax check writes nothing.
+const withoutOutput = (argv) => argv.filter((a, i) => a !== '-o' && argv[i - 1] !== '-o' && !(a.startsWith('-o') && a.length > 2));
+
+// A compiler's first error lines, each named by the source line it came from and with every quoted
+// literal masked, since a diagnostic may quote the program and no output of the gate carries source.
+function errorsOf(stderr, translated, map, rel) {
+  const out = [];
+  for (const line of String(stderr || '').split('\n')) {
+    const m = /^(.*?):(\d+):\s*error:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const at = resolve(m[1]) === translated ? `${rel}:${map[Number(m[2]) - 1] ?? m[2]}` : `${basename(m[1])}:${m[2]}`;
+    out.push(printable(`${at}: ${redact(m[3])}`, 300));
+    if (out.length === MAX_ERRORS) break;
+  }
+  return out;
+}
+
+// Runs the check. `compilerPath` is the resolved compiler and `argv` the caller's arguments after it;
+// `cwd` is where the caller's compiler runs, so its relative paths resolve there. Returns, for each
+// program the argument vector names that holds EXEC SQL or CICS, whether the compiler accepted its
+// translation and its first errors; programs holding EXEC DLI, which nothing translates, are skipped.
+export function precompileCheck({ compilerPath, argv, cwd = process.cwd(), repo, copylibs = [], env = process.env }) {
+  const sources = argv.map((a, i) => ({ a, i, path: resolve(cwd, a) }))
+    .filter(({ a, i, path }) => !a.startsWith('-') && argv[i - 1] !== '-o' && argv[i - 1] !== '-I' && isProgram(path) && isFile(path));
+  const includeDirs = [...includeDirsOf(argv, cwd), ...String(env.COBCPY || '').split(delimiter).filter(Boolean), ...copylibs];
+  const others = withoutOutput(argv.filter((_, i) => !sources.some((s) => s.i === i)));
+  const programs = [];
+  const skipped = [];
+  let mapsets = null;
+  const root = mkdtempSync(join(tmpdir(), 'cw-precompile-'));
+  try {
+    for (const { path } of sources) {
+      const rel = printable(relative(repo, path).startsWith('..') ? relative(cwd, path) : relative(repo, path), 200);
+      const text = readSource(path).text;
+      if (DLI.test(text)) { skipped.push({ path: rel, why: 'EXEC DLI is not translated' }); continue; }
+      if (!EXEC.test(text)) continue;
+      const format = detectFormat(text);
+      const dirs = [dirname(path), ...includeDirs];
+      let items = [];
+      try { items = parseSource(text, path, { format, includeDirs: dirs }).programs.flatMap((p) => p.items); } catch { /* unparsed: no host-variable arrays known */ }
+      if (/EXEC\s+CICS\b/i.test(text) && !mapsets) mapsets = repositoryBms(repo).mapsets;
+      const p = precompile(text, { format, items, mapsets: /EXEC\s+CICS\b/i.test(text) ? mapsets : [], copybook: copybookIn(dirs) });
+      const dir = mkdtempSync(join(root, 'p-'));
+      const translated = join(dir, basename(path));
+      writeFileSync(translated, p.text);
+      for (const [name, body] of Object.entries(p.copybooks)) writeFileSync(join(dir, `${name}.cpy`), body);
+      const r = spawnSync(compilerPath, ['-fsyntax-only', '-I', dir, ...others, translated], { cwd, env, encoding: 'utf8', windowsHide: true });
+      const ok = !r.error && r.status === 0;
+      programs.push({ path: rel, ok, ...(ok ? {} : { errors: r.error ? [printable(r.error.message, 200)] : errorsOf(r.stderr, translated, p.map, rel) }) });
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+  return { argv: ['-fsyntax-only', '-I', '<translation>', ...others, '<program>'], programs, skipped };
+}
+
+function isFile(path) {
+  try { return statSync(path).isFile(); } catch { return false; }
+}

package/lib/precompile-cics.mjs

@@ -12,7 +12,7 @@ export const builtinValue = (fn, name) => (fn === 'RESP' ? DFHRESP : DFHVALUE)[n
 const squeeze = (text) => text.replace(/('[^']*'|"[^"]*")|\s+/g, (_, lit) => lit || ' ').trim();
 
 // The options of an EXEC CICS command in order: each word, with its argument's text when it has one.
-function cicsOptions(text) {
+export function cicsOptions(text) {
   const out = [];
   let i = 0;
   while (i < text.length) {
@@ -39,13 +39,17 @@ function cicsOptions(text) {
   return out;
 }
 
-// Which table entry a command is: the one an option word identifies (SEND MAP by MAP), else the verb
-// alone, else the one IBM makes the default (READQ is READQ TS).
+// Which table entry a command is: the longest one whose name the words after the verb spell in order
+// (WEB READ HTTPHEADER; INQUIRE TRANSACTION though a PROGRAM option follows), else the one an
+// option word identifies (SEND MAP by MAP), else the verb alone, else the one IBM makes the default
+// (READQ is READQ TS).
 export function cicsCommand(options) {
   const verb = options[0]?.word;
   const words = new Set(options.slice(1).map((o) => o.word));
   const names = Object.keys(CICS_COMMANDS).filter((n) => n === verb || n.startsWith(`${verb} `));
-  return names.find((n) => CICS_COMMANDS[n].identify?.some((w) => words.has(w)))
+  const spelled = names.map((n) => n.split(' ')).filter((w) => w.length > 1 && w.slice(1).every((x, i) => options[i + 1]?.word === x))
+    .sort((a, b) => b.length - a.length)[0];
+  return spelled?.join(' ') || names.find((n) => CICS_COMMANDS[n].identify?.some((w) => words.has(w)))
     || names.find((n) => n === verb) || names.find((n) => CICS_COMMANDS[n].default) || null;
 }
 

package/lib/reach.mjs

@@ -14,11 +14,15 @@
 // lib/exploitability.mjs joins them with the route into a verdict.
 import { readFileSync, realpathSync } from 'node:fs';
 import { basename, sep, delimiter } from 'node:path';
+import { versionProblem, unknownKeys, ignoredKey } from './kernel/version-key.mjs';
 
 const str = (v) => typeof v === 'string' && v.length > 0;
 const isoDate = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v);
 const up = (s) => String(s || '').toUpperCase();
 const ACCESS = new Set(['open', 'restricted']);
+export const REACH_VERSION = 1;
+const REACH_KEYS = new Set(['$schema', 'version', 'extract', 'retrieved', 'transactions', 'jobs', 'privileged']);
+const PRIVILEGED_KEYS = new Set(['transactions', 'jobs']);
 const arr = (v) => (Array.isArray(v) ? v.filter(str).map(up) : []);
 
 // The feeds a scan was given: the caller's list, or COBOLWORK_REACH read when the scan runs.
@@ -34,7 +38,7 @@ export function reachFeedPaths(opts = {}) {
 // derived from a RACF unload (who may start each transaction, and which run with elevated authority)
 // and the SIT (which face a network).
 export function loadReachFeed(path, { root = null } = {}) {
-  const feed = { file: basename(path), extract: null, retrieved: null, transactions: {}, jobs: {}, privileged: { transactions: [], jobs: [] }, refused: [], problem: null };
+  const feed = { file: basename(path), extract: null, retrieved: null, transactions: {}, jobs: {}, privileged: { transactions: [], jobs: [] }, refused: [], warnings: [], problem: null };
   let real;
   try { real = realpathSync(path); } catch (e) { feed.problem = `could not be read (${e.code || e.name})`; return feed; }
   if (root) {
@@ -43,6 +47,9 @@ export function loadReachFeed(path, { root = null } = {}) {
   }
   let doc;
   try { doc = JSON.parse(readFileSync(real, 'utf8')); } catch (e) { feed.problem = `is not JSON (${e.message})`; return feed; }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) { feed.problem = 'is not a JSON object'; return feed; }
+  feed.problem = versionProblem(doc, REACH_VERSION);
+  if (feed.problem) return feed;
   if (!str(doc.extract)) { feed.problem = 'does not say which extract it is'; return feed; }
   if (!isoDate(doc.retrieved)) { feed.problem = 'does not say when it was retrieved'; return feed; }
   feed.extract = doc.extract;
@@ -56,7 +63,9 @@ export function loadReachFeed(path, { root = null } = {}) {
     }
   }
   const pv = doc.privileged;
-  if (pv && typeof pv === 'object' && !Array.isArray(pv)) { feed.privileged.transactions = arr(pv.transactions); feed.privileged.jobs = arr(pv.jobs); }
+  const held = pv && typeof pv === 'object' && !Array.isArray(pv);
+  if (held) { feed.privileged.transactions = arr(pv.transactions); feed.privileged.jobs = arr(pv.jobs); }
+  feed.warnings = [...unknownKeys(doc, REACH_KEYS).map((k) => ignoredKey(feed.file, k)), ...(held ? unknownKeys(pv, PRIVILEGED_KEYS) : []).map((k) => ignoredKey(`${feed.file} privileged`, k))];
   return feed;
 }
 

package/lib/revision.json

@@ -1 +1 @@
-{"commit":"2144d560676dda84c8ae6546dfb7b858399f0b7d"}
+{"commit":"4d7151cd03c0ac0850eec10a2529b07f0fc04aa1","tag":"v0.7.0"}