@portll/cobolwork 0.4.0 → 0.6.0

package/lib/hlasm/macro/storage.mjs

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Parser for z/OS virtual storage macros: STORAGE, GETMAIN, and FREEMAIN.
+import { HlasmSyntax } from '../operands.mjs';
+
+const GETMAIN_MODES = new Set(['R', 'RU', 'RC', 'VU', 'VC', 'EU', 'EC', 'LU', 'LC', 'VRC', 'VRU']);
+const FREEMAIN_MODES = new Set(['R', 'RU', 'RC', 'VU', 'VC', 'V', 'EU', 'EC', 'E', 'LU', 'LC', 'L']);
+
+function getKeyword(keywords, key) {
+  const val = keywords.get(key);
+  return val === undefined ? null : val;
+}
+
+function parseStorage(st, ops) {
+  const { positional, keywords } = ops;
+  if (positional.length < 1) {
+    throw new HlasmSyntax('STORAGE requires a request type (OBTAIN or RELEASE)');
+  }
+  const request = positional[0].trim().toUpperCase();
+  if (request !== 'OBTAIN' && request !== 'RELEASE') {
+    throw new HlasmSyntax(`STORAGE request must be OBTAIN or RELEASE, got ${positional[0]}`);
+  }
+  if (positional.length > 1) {
+    throw new HlasmSyntax(`STORAGE does not accept extra positional operands: ${positional[1]}`);
+  }
+
+  const allowed = new Set(['LENGTH', 'ADDR', 'INADDR', 'SP', 'BNDRY', 'CONTBDY', 'STARTBDY', 'KEY', 'CALLRKY', 'LOC', 'LINKAGE', 'RTCD', 'COND', 'CHECKZERO', 'BACK', 'FIX', 'EXECUTABLE', 'RELATED']);
+  for (const key of keywords.keys()) {
+    if (!allowed.has(key)) {
+      throw new HlasmSyntax(`STORAGE does not accept keyword ${key}`);
+    }
+  }
+
+  return {
+    kind: 'STORAGE',
+    request,
+    length: getKeyword(keywords, 'LENGTH'),
+    address: getKeyword(keywords, 'ADDR'),
+    subpool: getKeyword(keywords, 'SP'),
+    key: getKeyword(keywords, 'KEY'),
+    cond: getKeyword(keywords, 'COND'),
+    keywords: Object.fromEntries(keywords)
+  };
+}
+
+function parseGetmain(st, ops) {
+  const { positional, keywords } = ops;
+  if (positional.length < 1) {
+    throw new HlasmSyntax('GETMAIN requires a request type');
+  }
+  const mode = positional[0].trim().toUpperCase();
+  if (!GETMAIN_MODES.has(mode)) {
+    throw new HlasmSyntax(`GETMAIN request type must be one of ${[...GETMAIN_MODES].join(', ')}, got ${positional[0]}`);
+  }
+  if (positional.length > 1) {
+    throw new HlasmSyntax(`GETMAIN does not accept extra positional operands: ${positional[1]}`);
+  }
+
+  const allowed = new Set(['LA', 'LV', 'A', 'SP', 'BNDRY', 'CONTBDY', 'STARTBDY', 'KEY', 'LOC', 'INADDR', 'CHECKZERO', 'RELATED']);
+  for (const key of keywords.keys()) {
+    if (!allowed.has(key)) {
+      throw new HlasmSyntax(`GETMAIN does not accept keyword ${key}`);
+    }
+  }
+
+  const length = getKeyword(keywords, 'LV') ?? getKeyword(keywords, 'LA');
+  const address = getKeyword(keywords, 'A');
+  const subpool = getKeyword(keywords, 'SP');
+
+  return {
+    kind: 'GETMAIN',
+    mode,
+    length,
+    address,
+    subpool,
+    keywords: Object.fromEntries(keywords)
+  };
+}
+
+function parseFreemain(st, ops) {
+  const { positional, keywords } = ops;
+  if (positional.length < 1) {
+    throw new HlasmSyntax('FREEMAIN requires a request type');
+  }
+  const mode = positional[0].trim().toUpperCase();
+  if (!FREEMAIN_MODES.has(mode)) {
+    throw new HlasmSyntax(`FREEMAIN request type must be one of ${[...FREEMAIN_MODES].join(', ')}, got ${positional[0]}`);
+  }
+  if (positional.length > 1) {
+    throw new HlasmSyntax(`FREEMAIN does not accept extra positional operands: ${positional[1]}`);
+  }
+
+  const allowed = new Set(['LA', 'LV', 'A', 'SP', 'KEY', 'RELATED']);
+  for (const key of keywords.keys()) {
+    if (!allowed.has(key)) {
+      throw new HlasmSyntax(`FREEMAIN does not accept keyword ${key}`);
+    }
+  }
+
+  const length = getKeyword(keywords, 'LV') ?? getKeyword(keywords, 'LA');
+  const address = getKeyword(keywords, 'A');
+  const subpool = getKeyword(keywords, 'SP');
+
+  return {
+    kind: 'FREEMAIN',
+    mode,
+    length,
+    address,
+    subpool,
+    keywords: Object.fromEntries(keywords)
+  };
+}
+
+export const parsers = {
+  STORAGE: parseStorage,
+  GETMAIN: parseGetmain,
+  FREEMAIN: parseFreemain
+};

package/lib/hlasm/macro/structured.mjs

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Parsers for the HLASM Toolkit structured programming macros (IF, DO, SELECT, etc.).
+import { HlasmSyntax, NAME, splitOperands } from '../operands.mjs';
+
+const CC_MNEMONICS = new Set(['H', 'L', 'E', 'Z', 'O', 'M', 'P', 'NH', 'NL', 'NE', 'NZ', 'NO', 'NM', 'NP', 'EQ', 'GT', 'LT', 'GE', 'LE',
+  'HE', 'LE', 'NHE', 'NLE']);
+const CONNECTORS = new Set(['AND', 'OR', 'ANDIF', 'ORIF']);
+
+// (Z) or (8): a condition-code mnemonic or a mask; (CLI,0(R1),EQ,C'A') or (LTR,R15,R15,NZ): an
+// instruction and its operands with the condition among them.
+function parseCondition(text) {
+  const t = text.trim();
+  if (!t.startsWith('(') || !t.endsWith(')')) {
+    if (CC_MNEMONICS.has(t.toUpperCase())) return t;
+    throw new HlasmSyntax(`unrecognised condition: ${t}`);
+  }
+  const parts = splitOperands(t.slice(1, -1)).map((x) => x.trim());
+  if (parts.length === 1) {
+    if (CC_MNEMONICS.has(parts[0].toUpperCase()) || /^(?:CC=)?(?:[1-9]|1[0-4])$/i.test(parts[0])) return t;
+    throw new HlasmSyntax(`unrecognised condition: ${t}`);
+  }
+  if (!NAME.test(parts[0])) throw new HlasmSyntax(`condition ${t} does not start with an instruction`);
+  if (!parts.slice(1).some((x) => CC_MNEMONICS.has(x.toUpperCase()))) throw new HlasmSyntax(`unrecognised condition: ${t} names no condition mnemonic`);
+  return t;
+}
+
+// Conditions joined by AND, OR, ANDIF and ORIF, each operand of the macro one condition or joiner.
+function parsePredicate(positional) {
+  const items = positional.map((x) => x.trim()).filter(Boolean);
+  if (!items.length) throw new HlasmSyntax('requires a predicate');
+  const conditions = [];
+  const joins = [];
+  items.forEach((x, i) => {
+    if (i % 2) {
+      if (!CONNECTORS.has(x.toUpperCase())) throw new HlasmSyntax(`expected AND, OR, ANDIF or ORIF, not ${x}`);
+      joins.push(x.toUpperCase());
+    } else conditions.push(parseCondition(x));
+  });
+  if (joins.length === conditions.length) throw new HlasmSyntax('a predicate cannot end with a joiner');
+  return { conditions, joins };
+}
+
+function parseIF(st, ops) {
+  const { conditions, joins } = parsePredicate(ops.positional);
+  return { kind: 'IF', conditions, joins, keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseELSEIF(st, ops) {
+  const { conditions, joins } = parsePredicate(ops.positional);
+  return { kind: 'ELSEIF', conditions, joins, keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseDO(st, ops) {
+  const pos = ops.positional[0] || '';
+  const kw = ops.keywords;
+  let form = 'SIMPLE';
+  if (pos) {
+    const upper = pos.toUpperCase();
+    if (upper === 'ONCE') form = 'ONCE';
+    else if (upper === 'INF') form = 'INF';
+    else if (upper === 'BXH' || upper === 'BXLE' || upper === 'BCT' || upper === 'BCTR') form = 'COUNT';
+    else if (pos.startsWith('(')) form = 'COUNT';
+    else if (upper === 'WHILE' || upper === 'UNTIL') {
+      if (kw.has(upper)) form = upper;
+      else throw new HlasmSyntax(`unknown DO positional operand: ${pos}`);
+    }
+    else throw new HlasmSyntax(`unknown DO positional operand: ${pos}`);
+  }
+  if (kw.has('FROM')) form = 'FROM';
+  else if (kw.has('WHILE')) form = 'WHILE';
+  else if (kw.has('UNTIL')) form = 'UNTIL';
+  return { kind: 'DO', form, keywords: Object.fromEntries(kw) };
+}
+
+function parseDOEXIT(st, ops) {
+  const pos = ops.positional[0] || '';
+  if (pos) {
+    parseCondition(pos);
+  }
+  return { kind: 'DOEXIT', operands: [pos], keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseITERATE(st, ops) {
+  const pos = ops.positional[0] || '';
+  if (pos) {
+    if (!NAME.test(pos)) throw new HlasmSyntax(`ITERATE operand must be a label: ${pos}`);
+  }
+  return { kind: 'ITERATE', operands: [pos], keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseASMLEAVE(st, ops) {
+  const pos = ops.positional[0] || '';
+  if (pos && !NAME.test(pos)) throw new HlasmSyntax(`ASMLEAVE operand must be a label: ${pos}`);
+  return { kind: 'ASMLEAVE', operands: [pos], keywords: Object.fromEntries(ops.keywords) };
+}
+
+// SELECT alone, or SELECT instruction,operand,condition: CLI,0(R6),EQ compares each WHEN's values.
+function parseSELECT(st, ops) {
+  const parts = ops.positional.map((x) => x.trim()).filter(Boolean);
+  if (parts.length && (parts.length < 3 || !CC_MNEMONICS.has(parts[2].toUpperCase()))) throw new HlasmSyntax(`SELECT ${parts.join(',')} is not instruction,operand,condition`);
+  return { kind: 'SELECT', operands: [parts.join(',')].filter(Boolean), keywords: Object.fromEntries(ops.keywords) };
+}
+
+// WHEN takes a condition, or after a comparing SELECT a parenthesised list of values: (X'20'), (1,5,13).
+function parseWHEN(st, ops) {
+  const parts = ops.positional.map((x) => x.trim()).filter(Boolean);
+  if (!parts.length) throw new HlasmSyntax('WHEN needs a condition or values');
+  for (const p of parts) if (!(p.startsWith('(') && p.endsWith(')')) && !CONNECTORS.has(p.toUpperCase())) throw new HlasmSyntax(`WHEN operand ${p} is not in parentheses`);
+  return { kind: 'WHEN', operands: parts, keywords: Object.fromEntries(ops.keywords) };
+}
+
+function parseNoOperand(st, ops) {
+  if (ops.positional.length > 0) throw new HlasmSyntax(`${st.operation} does not accept positional operands`);
+  return { kind: st.operation, keywords: Object.fromEntries(ops.keywords) };
+}
+
+export const parsers = {
+  IF: parseIF,
+  ELSEIF: parseELSEIF,
+  ELSE: parseNoOperand,
+  ENDIF: parseNoOperand,
+  DO: parseDO,
+  ENDDO: parseNoOperand,
+  DOEXIT: parseDOEXIT,
+  ITERATE: parseITERATE,
+  ASMLEAVE: parseASMLEAVE,
+  SELECT: parseSELECT,
+  WHEN: parseWHEN,
+  OTHRWISE: parseNoOperand,
+  ENDSEL: parseNoOperand
+};

package/lib/hlasm/model.mjs

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Macro prototypes, model statements and open-code statements that hold variable symbols. A model
+// statement is read as the statement it is: each variable symbol in its operands stands in for an
+// ordinary symbol, or for the letter X inside a quoted string, and the result goes to the parser for
+// its operation. An operation that is itself a variable symbol is decided at expansion and refused.
+import { HlasmSyntax, NAME, splitOperands } from './operands.mjs';
+import { parseHlasmStatement } from './read.mjs';
+
+const VARIABLE = /^&[A-Z$#@_][A-Z0-9$#@_]*$/i;
+// System variable symbols whose value has a fixed length, which is all a constant's length needs.
+// https://www.ibm.com/docs/en/hla-and-tf/1.6.0?topic=symbols-sysdate-system-variable-symbol
+const FIXED_LENGTH = { '&SYSDATE': 8, '&SYSDATC': 8, '&SYSTIME': 5 };
+
+// &NAME, with an optional subscript (&A(1), &A(&I+1)) and an optional period that joins it to what
+// follows. && is one ampersand, not a variable symbol. Inside a quoted string a variable becomes as
+// many X as its value has characters when that is fixed, and one X otherwise, counted as unsized.
+function substitute(text) {
+  let out = '';
+  let quoted = false;
+  let n = 0;
+  let unsized = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "'") { quoted = !quoted; out += c; continue; }
+    if (c !== '&') { out += c; continue; }
+    if (text[i + 1] === '&') { out += '&&'; i++; continue; }
+    const m = /^&[A-Z$#@_][A-Z0-9$#@_]*/i.exec(text.slice(i));
+    if (!m) { out += c; continue; }
+    i += m[0].length;
+    if (text[i] === '(') {
+      let depth = 0;
+      for (; i < text.length; i++) { if (text[i] === '(') depth++; else if (text[i] === ')' && --depth === 0) { i++; break; } }
+    }
+    if (text[i] === '.') i++;
+    i--;
+    const fixed = FIXED_LENGTH[m[0].toUpperCase()];
+    if (quoted && !fixed) unsized++;
+    out += quoted ? 'X'.repeat(fixed || 1) : `VAR${++n}`;
+  }
+  return { text: out, unsized };
+}
+
+function read(kind, st) {
+  if (/&[A-Z$#@_]/i.test(st.operation)) throw new HlasmSyntax(`the operation ${st.operation} is decided when the macro is expanded`);
+  const name = st.name && !st.name.startsWith('&') && !st.name.startsWith('.') ? st.name : null;
+  const { text, unsized } = substitute(st.field || '');
+  const res = parseHlasmStatement({ ...st, name, field: text, inMacro: false, prototype: false });
+  // exact: no quoted string holds a variable of unknown length, so the node's lengths are the source's.
+  if (res.status === 'parsed') return { kind, as: res.kind, node: res.node, exact: unsized === 0 };
+  if (res.status === 'unbuilt') throw new HlasmSyntax(`no parser yet for ${res.kind}`);
+  throw new HlasmSyntax(res.reason || `${res.kind} ${res.status}`);
+}
+
+function prototype(st) {
+  if (st.name && !VARIABLE.test(st.name)) throw new HlasmSyntax(`a prototype's name field is a variable symbol or empty, not ${st.name}`);
+  if (!NAME.test(st.operation)) throw new HlasmSyntax(`${st.operation} is not a macro name`);
+  const positional = [];
+  const keywords = {};
+  for (const part of splitOperands(st.field || '')) {
+    const m = /^(&[A-Z$#@_][A-Z0-9$#@_]*)=([\s\S]*)$/i.exec(part);
+    if (m) keywords[m[1].toUpperCase()] = m[2];
+    else if (VARIABLE.test(part)) positional.push(part.toUpperCase());
+    else if (part !== '') throw new HlasmSyntax(`prototype operand ${part} is not a variable symbol`);
+  }
+  return { kind: 'PROTOTYPE', macro: st.operation, label: st.name || null, positional, keywords };
+}
+
+export const parsers = {
+  PROTOTYPE: prototype,
+  MODEL: (st) => read('MODEL', st),
+  SUBSTITUTED: (st) => read('SUBSTITUTED', st),
+};

package/lib/hlasm/operands.mjs

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// What every HLASM statement parser shares: the refusal it throws, and the split of an operand field
+// into operands at the commas outside parentheses and quotes.
+
+export class HlasmSyntax extends Error {
+  constructor(message) { super(message); this.name = 'HlasmSyntax'; }
+}
+
+export const NAME = /^[A-Z$#@_][A-Z0-9$#@_]{0,62}$/i;
+export const ATTRIBUTES = 'LTSIKNDO';
+
+// A quote after an attribute letter that stands alone, before a name, a variable symbol, * or a
+// literal, is an attribute reference (L'FIELD), not the start of a string. The card reader
+// (lib/bms.mjs) folds continuations by the same rule.
+export const isAttributeQuote = (text, i) => i > 0 && ATTRIBUTES.includes(text[i - 1].toUpperCase())
+  && !/[A-Z0-9$#@_&]/i.test(text[i - 2] || '') && /[A-Z$#@_&*=]/i.test(text[i + 1] || '');
+
+export function splitOperands(field) {
+  const out = [];
+  let depth = 0, quoted = false, start = 0;
+  for (let i = 0; i < field.length; i++) {
+    const c = field[i];
+    if (quoted) {
+      if (c === "'") { if (field[i + 1] === "'") i++; else quoted = false; }
+      continue;
+    }
+    if (c === "'") { if (!isAttributeQuote(field, i)) quoted = true; }
+    else if (c === '(') depth++;
+    else if (c === ')') { if (--depth < 0) throw new HlasmSyntax(`a closing parenthesis has no opening one at column ${i + 1} of the operands`); }
+    else if (c === ',' && depth === 0) { out.push(field.slice(start, i)); start = i + 1; }
+  }
+  if (quoted) throw new HlasmSyntax('a quoted string in the operands is not closed');
+  if (depth) throw new HlasmSyntax('a parenthesis in the operands is not closed');
+  out.push(field.slice(start));
+  return field === '' ? [] : out;
+}
+
+// Positional operands until the first KEY=VALUE, as a macro call is written. A literal (=F'1') is a
+// positional operand, not a keyword with an empty name.
+export function macroOperands(field) {
+  const positional = [];
+  const keywords = new Map();
+  for (const part of splitOperands(field)) {
+    const m = /^([A-Z$#@_][A-Z0-9$#@_]*)=([\s\S]*)$/i.exec(part);
+    if (m) keywords.set(m[1].toUpperCase(), m[2]);
+    else positional.push(part);
+  }
+  return { positional, keywords };
+}

package/lib/hlasm/read.mjs

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// HLASM source read statement by statement: the cards fold as the assembler folds them (lib/bms.mjs),
+// and each statement goes to the parser for what its operation is. A machine instruction is matched
+// against IBM's operand syntax, an assembler instruction and a system macro each have their own
+// parser, and any other macro call is split into its operands. Conditional assembly and macro
+// definitions are counted and not evaluated: nothing here expands a macro.
+import { foldStatements } from '../bms.mjs';
+import { HlasmSyntax, NAME, macroOperands } from './operands.mjs';
+import { INSTRUCTIONS, parseInstruction, formatFamily } from './instr.mjs';
+import { parsers as data } from './asm/data.mjs';
+import { parsers as sections } from './asm/sections.mjs';
+import { parsers as symbols } from './asm/symbols.mjs';
+import { parsers as listing } from './asm/listing.mjs';
+import { parsers as output } from './asm/output.mjs';
+import { parsers as program } from './macro/program.mjs';
+import { parsers as linkage } from './macro/linkage.mjs';
+import { parsers as storage } from './macro/storage.mjs';
+import { parsers as authorization } from './macro/authorization.mjs';
+import { parsers as operator } from './macro/operator.mjs';
+import { parsers as datasets } from './macro/datasets.mjs';
+import { parsers as io } from './macro/io.mjs';
+import { parsers as recovery } from './macro/recovery.mjs';
+import { parsers as le } from './macro/le.mjs';
+import { parsers as structured } from './macro/structured.mjs';
+import { parsers as exec } from './exec.mjs';
+import { parsers as model } from './model.mjs';
+
+// The assembler instructions of HLASM V1R6 (Language Reference SC26-4940-09, chapters 5 and 9).
+export const ASSEMBLER = new Set(['ACONTROL', 'ADATA', 'AINSERT', 'ALIAS', 'AMODE', 'CATTR', 'CCW', 'CCW0', 'CCW1',
+  'CEJECT', 'CNOP', 'COM', 'COPY', 'CSECT', 'CXD', 'DC', 'DROP', 'DS', 'DSECT', 'DXD', 'EJECT', 'END', 'ENTRY', 'EQU',
+  'EXITCTL', 'EXTRN', 'ICTL', 'ISEQ', 'LOCTR', 'LTORG', 'MNOTE', 'OPSYN', 'ORG', 'POP', 'PRINT', 'PUNCH', 'PUSH',
+  'REPRO', 'RMODE', 'RSECT', 'SPACE', 'START', 'TITLE', 'USING', 'WXTRN', 'XATTR']);
+export const CONDITIONAL = new Set(['ACTR', 'AEJECT', 'AGO', 'AGOB', 'AIF', 'AIFB', 'ANOP', 'AREAD', 'ASPACE',
+  'GBLA', 'GBLB', 'GBLC', 'LCLA', 'LCLB', 'LCLC', 'MEXIT', 'MHELP', 'SETA', 'SETAF', 'SETB', 'SETC', 'SETCF']);
+// The z/OS macros the rules read, each parsed against the keywords IBM lists for it.
+export const SYSTEM_MACROS = new Set(['LINK', 'XCTL', 'LOAD', 'ATTACH', 'CALL', 'SAVE', 'RETURN', 'MODESET',
+  'STORAGE', 'GETMAIN', 'FREEMAIN', 'RACROUTE', 'TESTAUTH', 'WTO', 'WTOR', 'OPEN', 'CLOSE', 'DCB', 'GET', 'PUT',
+  'READ', 'WRITE', 'ESTAE', 'ESPIE', 'ABEND', 'SNAP']);
+// Language Environment's prolog, epilog and mapping macros, and the HLASM Toolkit's structured
+// programming macros, each with its own parser.
+export const LE_MACROS = new Set(['CEEENTRY', 'CEETERM', 'CEEPPA', 'CEECAA', 'CEEDSA']);
+export const TOOLKIT_MACROS = new Set(['IF', 'ELSE', 'ELSEIF', 'ENDIF', 'DO', 'ENDDO', 'DOEXIT', 'ASMLEAVE', 'ITERATE',
+  'SELECT', 'WHEN', 'NEXTWHEN', 'OTHRWISE', 'ENDSEL', 'STRTSRCH', 'EXITIF', 'ORELSE', 'ENDLOOP', 'ENDSRCH',
+  'CASENTRY', 'CASE', 'ENDCASE', 'ASMMREL']);
+export const NAMED_MACROS = new Set([...SYSTEM_MACROS, ...LE_MACROS, ...TOOLKIT_MACROS]);
+
+const NO_OPERANDS = new Set(['CSECT', 'DSECT', 'RSECT', 'COM', 'LOCTR', 'LTORG', 'EJECT', 'REPRO', 'CXD']);
+
+export const PARSERS = Object.freeze({ ...data, ...sections, ...symbols, ...listing, ...output });
+export const MACRO_PARSERS = Object.freeze({ ...program, ...linkage, ...storage, ...authorization, ...operator, ...datasets, ...io, ...recovery, ...le, ...structured });
+
+// Statements other than comments, each marked inMacro when it is part of a macro definition, the
+// prototype (the statement after MACRO) marked as such.
+// EXEC CICS and EXEC SQL are written for their translators, with blanks between the words: their
+// field is the cards' text after EXEC, columns 16 to 71 of each continuation, not the operands up
+// to the first blank as an assembler statement's are.
+function execField(phys, st) {
+  return st.lines.map((n, i) => (i === 0 ? phys[n - 1].slice(0, 71).replace(/^\S*\s+EXEC\b/i, '') : phys[n - 1].slice(15, 71))).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+export function readHlasmStatements(text) {
+  const { statements, diags } = foldStatements(text);
+  const phys = String(text).replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  let depth = 0;
+  let prototypeNext = false;
+  for (const s of statements) {
+    if (s.kind === 'comment') continue;
+    const st = { ...s, inMacro: depth > 0, prototype: false };
+    if (s.kind === 'statement' && s.operation === 'EXEC') st.field = execField(phys, s);
+    if (s.kind === 'statement') {
+      if (s.operation === 'MACRO') { depth++; prototypeNext = true; st.inMacro = true; }
+      else if (prototypeNext) { st.prototype = true; prototypeNext = false; }
+      if (s.operation === 'MEND') depth = Math.max(0, depth - 1);
+    }
+    out.push(st);
+  }
+  return { statements: out, diags };
+}
+
+function run(kind, parser, st, ...args) {
+  if (!parser) return { kind, status: 'unbuilt' };
+  try {
+    return { kind, status: 'parsed', node: parser(st, ...args) };
+  } catch (e) {
+    if (e instanceof HlasmSyntax) return { kind, status: 'unparsed', reason: e.message };
+    return { kind, status: 'unparsed', reason: `parser error: ${e && e.message}`, crash: true };
+  }
+}
+
+// { kind, status, node?, reason?, crash? }: parsed, unbuilt (no parser for the kind yet), unparsed
+// (the parser refused it) or unknown (not an operation HLASM has).
+export function parseHlasmStatement(st) {
+  if (st.kind !== 'statement') return { kind: 'UNREADABLE', status: 'unknown', reason: 'no operation field' };
+  const op = st.operation;
+  if (op === 'MACRO' || op === 'MEND') return { kind: 'MACRO DEFINITION', status: 'parsed', node: { kind: op } };
+  if (CONDITIONAL.has(op)) return { kind: 'CONDITIONAL', status: 'unbuilt' };
+  if (st.prototype) return run('PROTOTYPE', model.PROTOTYPE, st);
+  if (st.inMacro) return run('MODEL', model.MODEL, st);
+  if (/&[A-Z$#@_]/i.test(`${st.name || ''} ${op} ${st.field || ''}`.replace(/&&/g, ''))) return run('SUBSTITUTED', model.SUBSTITUTED, st);
+  // A lone comma is the convention for no operands with remarks after it (CSECT , remark); an
+  // instruction that takes no operands reads whatever follows it as remarks.
+  if (ASSEMBLER.has(op)) return run(op, PARSERS[op], st.field === ',' || NO_OPERANDS.has(op) ? { ...st, field: '' } : st);
+  const row = INSTRUCTIONS.get(op);
+  if (row) return run(formatFamily(row.format), parseInstruction, st, row);
+  if (op === 'EXEC') {
+    const kind = `EXEC ${(/^\S+/.exec(st.field || '') || ['?'])[0].toUpperCase()}`;
+    return run(kind, exec[kind], st);
+  }
+  if (!NAME.test(op)) return { kind: 'UNKNOWN', status: 'unknown', reason: `${op} is not an operation name` };
+  if (NAMED_MACROS.has(op)) {
+    const parser = MACRO_PARSERS[op];
+    return run(op, parser && ((s) => parser(s, macroOperands(s.field === ',' ? '' : s.field || ''))), st);
+  }
+  return run('MACRO CALL', (s) => ({ kind: 'MACRO CALL', macro: op, ...macroOperands(s.field || '') }), st);
+}

package/lib/hlasm.mjs

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// HLASM source, read and not assembled. The cards fold into statements as the assembler folds them
+// (lib/bms.mjs), and each statement's operation is looked up in rules/hlasm-operations.json, the
+// operations that matter to a reviewer, each with the IBM document that defines it. Macros are not
+// expanded and conditional assembly is not evaluated, so an operation is reported where it is
+// written: in a macro definition, or in a branch AIF jumps over, as much as anywhere else.
+import { readFileSync } from 'node:fs';
+import { foldStatements } from './bms.mjs';
+import { parseOperands, splitOperands } from './cards.mjs';
+
+const TABLE = JSON.parse(readFileSync(new URL('../rules/hlasm-operations.json', import.meta.url), 'utf8'));
+export const OPERATIONS = new Map(TABLE.operations.map((o) => [o.name, o]));
+
+// Operations only assembler source holds: sections, base registers, the instructions every
+// program's linkage uses, and macro definitions. x86 or 6502 source written in a .asm file has none.
+// The weak ones are words another assembler's source can hold (a 6502 `zproc start`), so it takes
+// two different ones to count. USING counts only with the comma between its base and register: a
+// comment line written `C  Using a ...`, as GMP's are, reads as label C and operation USING.
+const ASSEMBLER = new Set(['CSECT', 'DSECT', 'RSECT', 'USING', 'BALR', 'BASR', 'STM', 'STMG', 'LM', 'LMG', 'MVC',
+  'MACRO', 'MEND', 'AMODE', 'RMODE', 'LTORG', 'CNOP']);
+const WEAK = new Set(['START', 'DC', 'DS', 'BAL', 'BAS', 'DROP']);
+const strong = (s) => ASSEMBLER.has(s.operation) && (s.operation !== 'USING' || s.field.includes(','));
+
+// GNU assembler source, run through m4 as GMP's is, holds s390 instructions too, and is not HLASM.
+const GNU = /^dnl\b|^\s*\.(?:text|globl|global|section|align|file)\b|\b(?:PROLOGUE|EPILOGUE|ASM_START)\(/m;
+
+// The macros that make a file a BMS map or an IMS database or program definition, which their own
+// readers take.
+const BMS = new Set(['DFHMSD', 'DFHMDI', 'DFHMDF']);
+const IMS = new Set(['DBD', 'DBDGEN', 'SEGM', 'PSBGEN', 'PCB', 'SENSEG']);
+
+// MODESET changes the PSW key or the state; these operand values make it key zero or supervisor
+// state, and the opposite values (KEY=NZERO, MODE=PROB) return from it. EXTKEY is the inline form,
+// which sets only the PSW key.
+const STATE_CHANGE = { KEY: ['ZERO'], MODE: ['SUP'], EXTKEY: ['ZERO'] };
+
+const nameList = (field) => splitOperands(field || '').map((s) => s.trim().toUpperCase()).filter((s) => /^[A-Z$#@_][A-Z0-9$#@_]*$/.test(s));
+
+function stateChange(field) {
+  let ops;
+  try { ops = parseOperands(field || ''); } catch { return null; }
+  for (const [key, values] of Object.entries(STATE_CHANGE)) {
+    const v = ops.keywords.get(key);
+    if (v && values.includes(String(v).trim().toUpperCase())) return `${key}=${String(v).trim().toUpperCase()}`;
+  }
+  return null;
+}
+
+// What the file is, and in it: each operation the table names with where it is written; the
+// sections and entry points it defines, which a CALL or a job step can name; and the names it
+// leaves to the binder.
+export function readHlasm(text) {
+  const { statements, diags } = foldStatements(text);
+  const ops = statements.filter((s) => s.kind === 'statement');
+  const has = (set) => ops.some((s) => set.has(s.operation));
+  const weak = new Set(ops.filter((s) => WEAK.has(s.operation)).map((s) => s.operation)).size;
+  const assembler = !GNU.test(text) && (ops.some(strong) || weak >= 2);
+  const kind = has(BMS) ? 'bms' : has(IMS) ? 'ims' : assembler ? 'hlasm' : 'unrecognised';
+  const out = { kind, statements: ops.length, operations: [], defines: [], external: [], diags };
+  if (kind !== 'hlasm') return out;
+
+  let macroDepth = 0;
+  for (const s of ops) {
+    if (s.operation === 'MACRO') { macroDepth++; continue; }
+    if (s.operation === 'MEND') { macroDepth = Math.max(0, macroDepth - 1); continue; }
+    const inMacro = macroDepth > 0;
+    if (!inMacro && ['CSECT', 'RSECT', 'START'].includes(s.operation) && s.name && !s.name.startsWith('&')) {
+      out.defines.push({ name: s.name.toUpperCase(), how: s.operation, line: s.line });
+    }
+    if (!inMacro && s.operation === 'ENTRY') for (const name of nameList(s.field)) out.defines.push({ name, how: 'ENTRY', line: s.line });
+    if (!inMacro && (s.operation === 'EXTRN' || s.operation === 'WXTRN')) for (const name of nameList(s.field)) out.external.push({ name, how: s.operation, line: s.line });
+    const op = OPERATIONS.get(s.operation);
+    if (!op || op.class === 'section' || op.class === 'linkage') continue;
+    const use = { name: op.name, class: op.class, line: s.line, inMacro, field: s.field };
+    if (op.name === 'MODESET') use.stateChange = stateChange(s.field);
+    out.operations.push(use);
+  }
+  return out;
+}

package/lib/inventory.mjs

@@ -3,12 +3,13 @@ import { detectFormat } from './parser.mjs';
 import { inScope, isCopybook, isJcl, isProgram, relPath } from './sources.mjs';
 import { SCHEMA_VERSION, TOOL_VERSION } from './version.mjs';
 import { treeFor } from './kernel/source-tree.mjs';
+import { drive, loopOver } from './kernel/shared-pass.mjs';
 
 const SYSTEM_COPY = /^(?:(?:DFH|DSN|CEE|IGZ|EZA|BPX|CSQ|CMQ|DLI)[A-Z0-9$#@]{0,5}|SQLCA|SQLDA|ATTRIB)$/i;
 
 // What the repository contains and, as importantly, what could not be read: a scan over a tree
 // whose copybooks are missing has not examined what it appears to have examined.
-export function inventory(root, opts = {}) {
+export function* inventorySteps(root, opts = {}) {
   const tree = treeFor(root, opts);
   const idx = tree.index;
   const files = tree.list().filter(inScope(opts));
@@ -28,27 +29,27 @@ export function inventory(root, opts = {}) {
     ebcdic: [],
     recursiveCopybooks: {},
   };
-  for (const f of files) {
+  yield loopOver(files, (f) => {
     if (isCopybook(f)) out.summary.copybookFiles++;
     if (isJcl(f)) out.summary.jclFiles++;
-    if (!isProgram(f)) continue;
+    if (!isProgram(f)) return;
     out.summary.programFiles++;
     let src;
     try {
       const s = tree.text(f);
       src = s.text;
       if (s.encoding === 'ebcdic') { out.summary.filesEbcdic++; out.ebcdic.push(tree.rel(f)); }
-    } catch (e) { out.summary.filesUnreadable++; out.unreadable.push(`${tree.rel(f)}: ${e.code || e.name}`); continue; }
+    } catch (e) { out.summary.filesUnreadable++; out.unreadable.push(`${tree.rel(f)}: ${e.code || e.name}`); return; }
     // A file with a program extension and no program in it is usually a copybook named .cbl; it is
     // counted so the difference between program files and programs read is accounted for.
-    if (!/PROCEDURE\s+DIVISION|PROGRAM-ID/i.test(src)) { out.summary.notPrograms++; continue; }
+    if (!/PROCEDURE\s+DIVISION|PROGRAM-ID/i.test(src)) { out.summary.notPrograms++; return; }
     let res;
     try {
       res = tree.parse(f, src);
     } catch (e) {
       out.summary.filesUnreadable++;
       out.unreadable.push(`${tree.rel(f)}: ${e.code || e.name}`);
-      continue;
+      return;
     }
     out.summary.filesScanned++;
     out.summary.programs += res.programs.length;
@@ -71,8 +72,10 @@ export function inventory(root, opts = {}) {
         out.missingCopybooks[k] = (out.missingCopybooks[k] || 0) + 1;
       }
     }
-  }
+  }, { guarded: false, label: 'inventory' });
   out.summary.nosrc = out.summary.filesScanned === 0;
   out.summary.coverageIncomplete = out.summary.copiesMissing > 0 || out.summary.copiesRecursive > 0 || (out.summary.copiesOverLimit || 0) > 0 || out.summary.filesUnreadable > 0 || out.summary.copiesRefused > 0 || out.summary.dirsUnreadable > 0 || out.summary.symlinks.outside > 0;
   return out;
 }
+
+export const inventory = (root, opts = {}) => drive(inventorySteps(root, opts));

package/lib/ironwork-ids.mjs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// What cobolwork reads from ironwork, and from which ironwork release: the formats it keys on, and
+// how ironwork says it ended a run. The run endings are ironwork's docs/run-endings.tsv; a test holds
+// them to the copy in test/fixtures/ironwork, and CI holds that copy to ironwork's.
+
+// Each format by the id its reader keys on, with the first ironwork release that writes all of what
+// cobolwork reads from it. A reader refuses an id it does not know, so a later format is not misread.
+export const IRONWORK_FORMATS = {
+  'ironwork-fuzz/v1': '0.3.0',
+  'ironwork-fuzz-interface/v1': '0.5.0',
+  'cobolwork-evidence/v1': '0.4.0',
+  'https://github.com/Portll/ironwork/blob/main/docs/evidence.md#equivalence-v1': '0.1.2',
+  'run-endings': '0.4.1',
+};
+
+// The first ironwork release whose output cobolwork reads throughout; a format listed with a later
+// release is read from that release on.
+export const IRONWORK_MINIMUM = '0.4.1';
+
+// How ironwork ends a run other than with its RETURN-CODE, by exit status.
+export const RUN_ENDINGS = { 240: 'abend', 241: 'refused', 242: 'not-generated', 243: 'stopped', 244: 'not-run', 245: 'unreadable', 246: 'usage', 255: 'internal' };
+
+// The abend codes that say a run reached what ironwork does not run.
+export const NOT_RUN_ABENDS = ['IRONWORK', 'EXEC', 'JAVA'];