@portll/cobolwork 0.6.0 → 0.7.0

package/lib/pli/program.mjs

@@ -0,0 +1,280 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// A PL/I source file as the program the flow engine reads (lib/dataflow.mjs summarise): data items
+// with offsets and sizes from lib/pli/layout.mjs, statements as the names they read and write,
+// external calls with their arguments, EXEC blocks as the engine's tokens, and the MAIN procedure's
+// parameters. The engine itself is unchanged.
+import { basename } from 'node:path';
+import { readPli } from './lex.mjs';
+import { readPliExpanded } from './include.mjs';
+import { parseStatement } from './statements.mjs';
+import { layout } from './layout.mjs';
+
+// The token naming a reference: its last name at parenthesis depth 0.
+function nameToken(ref) {
+  let depth = 0;
+  let last = null;
+  for (const t of ref.toks) {
+    if (t.t === 'op' && t.v === '(') depth++;
+    else if (t.t === 'op' && t.v === ')') depth--;
+    else if (depth === 0 && t.t === 'word') last = t;
+  }
+  return last;
+}
+
+// EXEC block tokens as lib/parser.mjs gives them: parentheses as separators, commas dropped, a
+// period between two names joined.
+function execTokens(toks) {
+  const out = [];
+  for (let k = 0; k < toks.length; k++) {
+    const t = toks[k];
+    if (t.t === 'op' && (t.v === '(' || t.v === ')')) out.push({ ...t, t: 'sep' });
+    else if (t.t === 'op' && t.v === ',') continue;
+    else if (t.t === 'op' && t.v === '.') out.push({ ...t, t: 'period', joined: !!(toks[k - 1]?.t === 'word' && toks[k + 1]?.t === 'word' && toks[k + 1].col === t.col + 1) });
+    else out.push(t);
+  }
+  return out;
+}
+
+const ARITHMETIC_OPS = new Set(['+', '-', '*', '/', '**', 'prefix-', 'prefix+']);
+
+// What the Db2 precompiler writes for EXEC SQL INCLUDE SQLCA in a PL/I program (Db2 13 SQL
+// Reference, "The included SQLCA").
+const SQLCA_PLI = ` DECLARE
+ 1 SQLCA,
+ 2 SQLCAID CHAR(8),
+ 2 SQLCABC FIXED(31) BINARY,
+ 2 SQLCODE FIXED(31) BINARY,
+ 2 SQLERRM CHAR(70) VAR,
+ 2 SQLERRP CHAR(8),
+ 2 SQLERRD(6) FIXED(31) BINARY,
+ 2 SQLWARN,
+ 3 SQLWARN0 CHAR(1),
+ 3 SQLWARN1 CHAR(1),
+ 3 SQLWARN2 CHAR(1),
+ 3 SQLWARN3 CHAR(1),
+ 3 SQLWARN4 CHAR(1),
+ 3 SQLWARN5 CHAR(1),
+ 3 SQLWARN6 CHAR(1),
+ 3 SQLWARN7 CHAR(1),
+ 2 SQLEXT,
+ 3 SQLWARN8 CHAR(1),
+ 3 SQLWARN9 CHAR(1),
+ 3 SQLWARNA CHAR(1),
+ 3 SQLSTATE CHAR(5);`;
+
+// readMember(name, fromFile) -> { path, text } | null splices %INCLUDE members in; without it the
+// directives stay as statements and what they would have declared is missing.
+export function pliProgram(text, file, { readMember = null } = {}) {
+  const read = readMember ? readPliExpanded(text, { file, readMember }) : readPli(text, { file });
+  const statements = read.statements.map((st) => ({ st, r: parseStatement(st) }));
+  const declared = [];
+  for (const { st, r } of statements) if (r.status === 'parsed' && r.kind === 'DECLARE') declared.push(...r.node.items.map((it) => ({ ...it, file: st.file || file })));
+  const sqlcaAt = statements.find(({ st, r }) => r.kind === 'EXEC' && r.node?.processor === 'SQL' && r.node.sql?.verb === 'INCLUDE' && st.toks[3]?.u === 'SQLCA')?.st;
+  if (sqlcaAt && !declared.some((it) => it.name === 'SQLCA')) {
+    for (const st of readPli(SQLCA_PLI, { file }).statements) {
+      const r = parseStatement(st);
+      if (r.kind === 'DECLARE') declared.push(...r.node.items.map((it) => ({ ...it, file: sqlcaAt.file || file, line: sqlcaAt.line })));
+    }
+  }
+  const { roots } = layout(declared);
+
+  const items = [];
+  const flatten = (node, parent) => {
+    const item = {
+      name: node.name, level: node.logical, parent, children: [], file: node.file || file, line: node.line, values: [],
+      offset: node.offset, occurs: node.occurs || 1,
+      size: node.children.length ? node.size * Math.max(1, node.occurs || 1) : node.size,
+      attributes: node.attributes.map((a) => a.name), storage: node.storage || null,
+    };
+    items.push(item);
+    for (const ch of node.children) item.children.push(flatten(ch, item));
+    return item;
+  };
+  for (const r of roots) flatten(r, null);
+  const byName = new Map();
+  for (const it of items) { if (!byName.has(it.name)) byName.set(it.name, []); byName.get(it.name).push(it); }
+  const builtin = new Set(items.filter((it) => it.attributes.includes('BUILTIN') || it.attributes.includes('GENERIC')).map((it) => it.name));
+
+  // A qualified reference A.B.C names the C whose containing structures include B and then A; after
+  // a locator, P->X.Y, only the part after the arrow qualifies the data.
+  const resolved = new Map();
+  const resolve = (ref) => {
+    const qual = ref.path.slice(ref.locators.length ? ref.locators[ref.locators.length - 1] : 0);
+    const cands = (byName.get(ref.name) || []).filter((it) => !builtin.has(it.name));
+    const fits = cands.filter((it) => {
+      let k = qual.length - 2;
+      for (let a = it.parent; a && k >= 0; a = a.parent) if (a.name === qual[k]) k--;
+      return k < 0;
+    });
+    const item = fits[0] || null;
+    const tok = nameToken(ref);
+    if (item && tok) resolved.set(tok, item);
+    return item ? tok : null;
+  };
+
+  // The names an expression reads: references to declared data; a reference that names no declared
+  // item and has arguments is a function, read through its arguments.
+  // A subscript names a table element; SUBSTR's start and length bound a reference into its
+  // first argument. Both are what the engine's subscript and reference-modification sinks read.
+  const tableOf = (it) => { for (let a = it; a; a = a.parent) if ((a.occurs || 1) > 1) return a; return null; };
+  const indexOf = (a) => {
+    const t = a && a.tree;
+    if (!t) return null;
+    if (t.t === 'ref') { const tok = resolve(t); return tok ? { tok, offset: 0 } : null; }
+    if ((t.op === '+' || t.op === '-') && t.args[0]?.t === 'ref' && t.args[1]?.t === 'num' && /^\d+$/.test(t.args[1].tok.v)) {
+      const tok = resolve(t.args[0]);
+      return tok ? { tok, offset: (t.op === '+' ? 1 : -1) * Number(t.args[1].tok.v) } : null;
+    }
+    return null;
+  };
+  const noteIndexes = (n, hostTok, indexes) => {
+    if (!indexes) return;
+    const item = resolved.get(hostTok);
+    if (item && tableOf(item)) {
+      for (const list of n.args) for (const a of list) { const x = indexOf(a); if (x) indexes.push({ host: hostTok, tok: x.tok, kind: 'subscript', ...(x.offset ? { offset: x.offset } : {}) }); }
+    } else if (!item && n.name === 'SUBSTR' && n.args[0]?.[0]?.tree?.t === 'ref') {
+      const host = resolve(n.args[0][0].tree);
+      const [, from, len] = n.args[0].map(indexOf);
+      if (host && from) indexes.push({ host, tok: from.tok, kind: 'refmod-offset', ...(from.offset ? { offset: from.offset } : {}) });
+      if (host && len) indexes.push({ host, tok: len.tok, kind: 'refmod-length' });
+    }
+  };
+  const reads = (expr, out = [], indexes = null) => {
+    const walk = (n) => {
+      if (!n) return;
+      if (n.t === 'ref') {
+        const tok = resolve(n);
+        if (tok) out.push(tok);
+        noteIndexes(n, tok, indexes);
+        if (!tok) for (const list of n.args) for (const a of list) if (a.tree) walk(a.tree);
+        for (const at of n.locators) { const p = byName.get(n.path[at - 1]); if (p) { const t = n.toks.find((x) => x.t === 'word' && x.u === n.path[at - 1]); if (t) { resolved.set(t, p[0]); out.push(t); } } }
+      } else if (n.t === 'paren') walk(n.expr.tree);
+      else if (n.t === 'lit' && n.factor) walk(n.factor.tree);
+      else if (n.args) n.args.forEach(walk);
+    };
+    walk(expr.tree ?? expr);
+    return out;
+  };
+  const hasOp = (tree, ops) => !!tree && (ops.has(tree.op) || (tree.args || []).some((a) => hasOp(a, ops)));
+
+  const prog = { id: null, line: 1, file, items, resolved, statements: [], execs: [], calls: [], paramTokens: [], labels: [], proc: null, files: [], fds: [], accepts: [], unresolvedRefs: [] };
+  const procs = new Map();
+  for (const { st, r } of statements) {
+    if (r.status !== 'parsed' || r.kind !== 'PROCEDURE') continue;
+    procs.set(r.node.name, { node: r.node, st });
+    if (!prog.id) {
+      prog.id = r.node.name;
+      prog.line = st.line;
+    }
+    if (r.node.options.some((o) => o.name === 'MAIN') && !prog.paramTokens.length) {
+      for (const p of r.node.params) {
+        const tok = st.toks.find((t) => t.t === 'word' && t.u === p);
+        const item = (byName.get(p) || [])[0];
+        if (tok && item) {
+          resolved.set(tok, item);
+          prog.paramTokens.push({ tok, mode: 'REFERENCE' });
+          // A MAIN procedure's parameter is the PARM string, or the command line off z/OS.
+          prog.accepts.push({ target: p, targetTok: tok, from: 'COMMAND-LINE', line: st.line, file: st.file || file });
+        }
+      }
+    }
+  }
+  if (!prog.id) prog.id = basename(file).replace(/\.[^.]*$/, '').toUpperCase();
+
+  const add = (st, verb, sources, targets, extra = {}) => prog.statements.push({ verb, sources, targets, file: st.file || file, line: st.line, ...extra });
+  const visit = (st, r, top = true) => {
+    if (r.status !== 'parsed' && r.status !== 'unbuilt') return;
+    const n = r.node;
+    if (!n) return;
+    if (r.kind === 'ASSIGNMENT') {
+      const indexes = [];
+      const sources = reads(n.value, [], indexes);
+      const targets = [];
+      for (const t of n.targets) {
+        const tok = resolve(t);
+        noteIndexes(t, tok, indexes);
+        if (tok) { targets.push(tok); continue; }
+        // A pseudovariable such as SUBSTR(X, 1, 2) = ... writes its first argument.
+        const first = t.args[0]?.[0];
+        if (first?.tree?.t === 'ref') { const a = resolve(first.tree); if (a) targets.push(a); }
+      }
+      const verb = n.value.tree?.t === 'ref' ? 'MOVE' : hasOp(n.value.tree, new Set(['||'])) ? 'STRING' : hasOp(n.value.tree, ARITHMETIC_OPS) ? 'COMPUTE' : 'MOVE';
+      add(st, verb, sources, targets, indexes.length ? { indexes } : {});
+    } else if (r.kind === 'IF' || r.kind === 'WHEN' || (r.kind === 'DO' && (n.while || n.until))) {
+      // A condition is what the engine credits as a check on the names it compares.
+      const conds = r.kind === 'IF' ? [n.cond] : r.kind === 'WHEN' ? n.values : [n.while, n.until].filter(Boolean);
+      const indexes = [];
+      const sources = conds.flatMap((c) => reads(c, [], indexes));
+      const ops = [];
+      const walk = (t) => { if (!t) return; if (t.op) ops.push(t.op); (t.args || []).forEach(walk); if (t.t === 'paren') walk(t.expr.tree); };
+      conds.forEach((c) => walk(c.tree));
+      add(st, r.kind === 'WHEN' ? 'WHEN' : 'IF', sources, [], { ops, ...(indexes.length ? { indexes } : {}) });
+    } else if (r.kind === 'READ') {
+      const into = n.options?.INTO;
+      const recTok = into ? resolve(into) : null;
+      add(st, 'READ', [], recTok ? [recTok] : []);
+      // A PL/I file's DD name is its own name unless OPEN gives it a TITLE; the record it reads
+      // into is what a job's DD for that name supplies.
+      const fname = n.file?.name;
+      if (fname && recTok) {
+        let fd = prog.fds.find((x) => x.name === fname);
+        if (!fd) { fd = { name: fname, records: [], file: st.file || file, line: st.line }; prog.fds.push(fd); prog.files.push({ name: fname, assign: { t: 'lit', v: fname }, file: st.file || file, line: st.line }); }
+        const rec = resolved.get(recTok);
+        if (rec && !fd.records.includes(rec)) fd.records.push(rec);
+      }
+    } else if (r.kind === 'WRITE' || r.kind === 'REWRITE') {
+      const from = n.options?.FROM;
+      add(st, 'WRITE', from ? [resolve(from)].filter(Boolean) : [], []);
+    } else if (r.kind === 'CALL') {
+      const internal = procs.get(n.name);
+      const argToks = n.args.map((a) => (a.tree?.t === 'ref' ? resolve(a.tree) : null));
+      if (internal) {
+        // Arguments pass by reference: an internal procedure's parameter is the argument's storage.
+        internal.node.params.forEach((p, k) => {
+          const pTok = internal.st.toks.find((t) => t.t === 'word' && t.u === p);
+          const pItem = (byName.get(p) || [])[0];
+          if (!pTok || !pItem || !argToks[k]) return;
+          resolved.set(pTok, pItem);
+          add(st, 'MOVE', [argToks[k]], [pTok]);
+          add(st, 'MOVE', [pTok], [argToks[k]]);
+        });
+      } else {
+        const variable = (byName.get(n.callee.name) || []).some((it) => it.attributes.includes('ENTRY') && it.attributes.includes('VARIABLE'));
+        const targetTok = variable ? resolve(n.callee) : nameToken(n.callee);
+        add(st, 'CALL', [], []);
+        prog.calls.push({
+          kind: variable ? 'I' : 'L', name: n.name, line: st.line, file: st.file || file, targetTok,
+          using: n.args.map((a, k) => ({ tok: argToks[k], word: argToks[k]?.u ?? null, mode: 'REFERENCE' })),
+          stmtIndex: prog.statements.length - 1,
+        });
+      }
+    } else if (r.kind === 'FETCH') {
+      // A TITLE that is a variable names the module loaded at run time.
+      for (const e of n.entries) {
+        const t = e.title && e.title.tree;
+        const tok = t && t.t === 'ref' ? resolve(t) : null;
+        if (!tok) continue;
+        add(st, 'CALL', [], []);
+        prog.calls.push({ kind: 'I', name: tok.u, line: st.line, file: st.file || file, targetTok: tok, using: [], stmtIndex: prog.statements.length - 1 });
+      }
+    } else if (r.kind === 'OPEN') {
+      // A TITLE that is a variable names the dataset opened, as SELECT ... ASSIGN TO a data item does.
+      for (const f of n.files) {
+        const t = f.options && f.options.TITLE && f.options.TITLE.tree;
+        if (t && t.t === 'ref' && resolve(t)) prog.files.push({ name: f.file.name, assign: { t: 'word', v: t.name }, file: st.file || file, line: st.line });
+      }
+    } else if (r.kind === 'EXEC' && top) {
+      prog.execs.push({ t: 'exec', kind: n.processor, toks: execTokens(st.toks.slice(2)), line: st.line, file: st.file || file });
+      for (const t of st.toks) if (t.t === 'word' && byName.has(t.u)) resolved.set(t, byName.get(t.u)[0]);
+    }
+    for (const u of n.units || []) if (u.node) visit(st, u, false);
+  };
+  for (const { st, r } of statements) visit(st, r);
+  prog.includes = { included: read.included || [], unresolved: read.unresolved || [], cycles: read.cycles || [] };
+  return prog;
+}
+
+// The engine's parse result for one PL/I source file.
+export function parsePliSource(text, file, opts = {}) {
+  return { file, format: 'pli', programs: [pliProgram(text, file, opts)], options: [], diags: [], copies: [] };
+}

package/lib/pli/rules/based.mjs

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Rule: BASED storage addressed through a pointer.
+
+export const RULES = {
+  'pli-based-storage-addressing': {
+    sev: 'info',
+    evidence: 'coverage',
+    cwe: 'CWE-119',
+    text: 'A program addresses storage through a pointer, so data flow through it is not followed'
+  }
+};
+
+const ADDRESS_ARITHMETIC = new Set(['POINTERADD', 'PTRADD', 'POINTERVALUE', 'PTRVALUE', 'POINTERSUBTRACT', 'PTRSUBTRACT']);
+
+// Whether an expression computes an address rather than copying one.
+function computed(tree) {
+  if (!tree) return false;
+  if (tree.t === 'ref') return ADDRESS_ARITHMETIC.has(tree.name) || tree.args.some((list) => list.some((a) => computed(a.tree)));
+  if (tree.op === '+' || tree.op === '-') return true;
+  if (tree.t === 'paren') return computed(tree.expr.tree);
+  return (tree.args || []).some(computed);
+}
+
+export function check(program) {
+  const basedVars = [];
+  const pointerVars = new Set();
+  let firstBasedLine = null;
+  let firstPointerAssign = null;
+
+  const walk = (units) => {
+    if (!Array.isArray(units)) return;
+    for (const unit of units) {
+      if (!unit || unit.status !== 'parsed' || !unit.node) continue;
+      const node = unit.node;
+
+      if (node.kind === 'DECLARE') {
+        for (const item of node.items || []) {
+          const name = item.name;
+          if (!name) continue;
+          const attrs = item.attributes || [];
+          const basedAttr = attrs.find((a) => a.name === 'BASED');
+          if (basedAttr) {
+            basedVars.push({ name, args: basedAttr.args || [] });
+            if (firstBasedLine === null) firstBasedLine = unit.line;
+          }
+          if (attrs.some((a) => a.name === 'POINTER')) {
+            pointerVars.add(name.toUpperCase());
+          }
+        }
+      } else if (node.kind === 'ASSIGNMENT') {
+        const targets = node.targets || [];
+        for (const target of targets) {
+          if (target && target.t === 'ref' && target.name && pointerVars.has(target.name.toUpperCase())) {
+            if (computed(node.value && node.value.tree) && !firstPointerAssign) firstPointerAssign = { name: target.name, line: unit.line };
+          }
+        }
+      }
+
+      if (node.units) walk(node.units.map((u) => ({ ...u, line: unit.line })));
+    }
+  };
+
+  walk(program.statements.map((st) => ({ ...st.parsed, line: st.line })));
+
+  if (basedVars.length === 0) return [];
+
+  const names = basedVars.slice(0, 3).map((v) => v.name);
+  const namesStr = names.join(', ');
+  const count = basedVars.length;
+
+  let detail = `${count} variable${count === 1 ? '' : 's'} declared BASED (${namesStr})`;
+
+  const overlay = (v) => v.args[0] && v.args[0].t === 'word' && v.args[0].u === 'ADDR';
+  const hasAddr = basedVars.some(overlay);
+  const hasPlain = basedVars.some((v) => !overlay(v));
+
+  if (hasAddr && hasPlain) {
+    detail += ', some using ADDR() of declared variables (overlays) and some plain pointers';
+  } else if (hasAddr) {
+    detail += ', using ADDR() of declared variables (overlays)';
+  } else if (hasPlain) {
+    detail += ', plain pointers addressing whatever the pointer holds';
+  }
+
+  if (firstPointerAssign) {
+    detail += `; first computed address assignment to ${firstPointerAssign.name} at line ${firstPointerAssign.line}`;
+  }
+
+  return [{
+    rule: 'pli-based-storage-addressing',
+    path: program.path,
+    line: firstBasedLine,
+    detail
+  }];
+}

package/lib/pli/rules/conditions.mjs

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// PL/I rules on condition handling.
+
+export const RULES = {
+  'pli-error-condition-ignored': {
+    sev: 'low',
+    evidence: 'construct',
+    cwe: 'CWE-390',
+    text: 'An ON unit for a condition does nothing with it, so the condition is silently ignored',
+    impact: 'A failure the condition reports, such as a conversion error, a division by zero, a subscript out of range or a file that would not open, reaches an ON unit that does nothing with it, so no message or log says the operation failed',
+    remedy: 'Handle the condition in its ON unit: record it and recover, or end the run with a message; where a condition is expected, test for it and act rather than leave the unit empty'
+  }
+};
+
+const IGNORED_CONDITIONS = new Set([
+  'ERROR', 'ANYCONDITION', 'ANYCOND', 'CONVERSION', 'CONV',
+  'ZERODIVIDE', 'ZDIV', 'FIXEDOVERFLOW', 'FOFL', 'SIZE',
+  'STRINGRANGE', 'STRG', 'SUBSCRIPTRANGE', 'SUBRG', 'KEY',
+  'RECORD', 'TRANSMIT', 'UNDEFINEDFILE', 'UNDF'
+]);
+
+const BLOCK_OPENERS = new Set(['BEGIN', 'DO', 'SELECT', 'PROCEDURE', 'PACKAGE']);
+
+// Whether a statement opens a block that a later END closes: BEGIN, DO, SELECT or a procedure,
+// itself or as the unit of an IF, ELSE, WHEN, OTHERWISE or ON.
+function opens(r) {
+  if (!r || r.status !== 'parsed' || !r.node) return false;
+  if (BLOCK_OPENERS.has(r.kind)) return true;
+  const units = r.node.units || [];
+  return units.length > 0 && opens(units[units.length - 1]);
+}
+
+// The statements of the block a statement at `at` opens, up to and not including its END.
+function blockBody(statements, at) {
+  let depth = 1;
+  for (let k = at + 1; k < statements.length; k++) {
+    const r = statements[k].parsed;
+    if (r.kind === 'END') { if (--depth === 0) return statements.slice(at + 1, k); continue; }
+    if (opens(r)) depth++;
+  }
+  return statements.slice(at + 1);
+}
+
+// Doing nothing is a null unit, a block that is empty, or only jumping away.
+const inert = (r) => r.kind === 'NULL' || r.kind === 'GOTO';
+
+export function check(program) {
+  const findings = [];
+  const statements = program.statements;
+  statements.forEach((st, at) => {
+    const r = st.parsed;
+    if (r.status !== 'parsed' || r.kind !== 'ON' || r.node.system) return;
+    const names = r.node.conditions.filter((c) => IGNORED_CONDITIONS.has(c.name)).map((c) => c.name);
+    if (!names.length) return;
+    const unit = r.node.units[0];
+    const on = `ON ${names.join(', ')}`;
+    let detail = null;
+    if (!unit) detail = `${on} has a null unit, so the condition is raised and dropped`;
+    else if (unit.kind === 'GOTO') detail = `${on} only does GO TO ${unit.node.target.path.join('.')}`;
+    else if (unit.kind === 'BEGIN') {
+      const body = blockBody(statements, at).map((s) => s.parsed);
+      if (!body.length) detail = `${on} has an empty BEGIN block`;
+      else if (body.every(inert)) detail = `${on} has a BEGIN block that only does GO TO ${body.filter((b) => b.kind === 'GOTO').map((b) => b.node.target.path.join('.')).join(', ')}`;
+    }
+    if (detail) findings.push({ rule: 'pli-error-condition-ignored', path: program.path, line: st.line, detail });
+  });
+  return findings;
+}

package/lib/pli/rules/entry.mjs

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// PL/I rules on calls through entry variables and FETCH of a non-literal title.
+
+export const RULES = {
+  'pli-entry-variable-call': {
+    sev: 'info',
+    evidence: 'coverage',
+    cwe: 'CWE-470',
+    text: 'A CALL through an entry variable dispatches to a procedure chosen at run time, so the callee is not known statically',
+  },
+  'pli-fetch-title-variable': {
+    sev: 'med',
+    evidence: 'construct',
+    cwe: 'CWE-494',
+    text: 'A FETCH whose TITLE is not a literal names the module to load at run time',
+    impact: 'FETCH loads the load module whose name the TITLE value holds when the statement runs, so whatever sets that value chooses the code the program then calls, with the program\'s authority',
+    remedy: 'Give FETCH a literal TITLE where the module is fixed; where it must vary, check the name against a list of the modules the program may load before the FETCH',
+  },
+};
+
+function walkUnits(units, visit) {
+  if (!Array.isArray(units)) return;
+  for (const u of units) {
+    if (!u || typeof u !== 'object') continue;
+    visit(u);
+    if (u.node && typeof u.node === 'object') walkUnits(u.node.units, visit);
+  }
+}
+
+function eachParsed(program, visit) {
+  for (const st of program.statements) {
+    if (!st || !st.parsed || st.parsed.status !== 'parsed') continue;
+    visit(st);
+    walkUnits(st.parsed.node && st.parsed.node.units, (u) => {
+      if (u && u.status === 'parsed') visit({ line: st.line, parsed: u });
+    });
+  }
+}
+
+function isEntryVariable(item) {
+  if (!item || !Array.isArray(item.attributes)) return false;
+  const names = new Set(item.attributes.map((a) => (a && a.name ? String(a.name).toUpperCase() : '')));
+  return names.has('ENTRY') && names.has('VARIABLE');
+}
+
+function isEntryMember(item) {
+  if (!item || !Array.isArray(item.attributes)) return false;
+  const names = new Set(item.attributes.map((a) => (a && a.name ? String(a.name).toUpperCase() : '')));
+  return names.has('ENTRY') && !names.has('VARIABLE');
+}
+
+function isProcedure(name, procedures) {
+  return procedures.has(String(name || '').toUpperCase());
+}
+
+const isLiteralTitle = (title) => !!title && title.tree && title.tree.t === 'lit';
+
+export function check(program) {
+  const findings = [];
+  if (!program || !Array.isArray(program.statements)) return findings;
+
+  const entryVariables = new Map();
+  const entryMembers = new Set();
+  const procedures = new Set();
+
+  eachParsed(program, (st) => {
+    const node = st.parsed && st.parsed.node;
+    if (!node || typeof node !== 'object') return;
+    if (node.kind === 'DECLARE' && Array.isArray(node.items)) {
+      for (const item of node.items) {
+        if (!item || !item.name) continue;
+        const key = String(item.name).toUpperCase();
+        // A member of a structure is a variable whatever it declares.
+        if (isEntryVariable(item) || (item.level > 1 && isEntryMember(item))) entryVariables.set(key, item.name);
+        else if (isEntryMember(item)) entryMembers.add(key);
+      }
+    } else if (node.kind === 'PROCEDURE' && node.name) {
+      procedures.add(String(node.name).toUpperCase());
+    }
+  });
+
+  const assignedConstants = new Map();
+  eachParsed(program, (st) => {
+    const node = st.parsed && st.parsed.node;
+    if (!node || node.kind !== 'ASSIGNMENT') return;
+    const ref = node.value && node.value.tree;
+    if (!Array.isArray(node.targets) || !ref || ref.t !== 'ref' || !ref.name) return;
+    const valueName = String(ref.name).toUpperCase();
+    if (!procedures.has(valueName) && !entryMembers.has(valueName)) return;
+    for (const target of node.targets) {
+      if (!target || target.t !== 'ref' || !target.name) continue;
+      const key = String(target.name).toUpperCase();
+      if (!entryVariables.has(key)) continue;
+      if (!assignedConstants.has(key)) assignedConstants.set(key, new Set());
+      assignedConstants.get(key).add(ref.name);
+    }
+  });
+
+  eachParsed(program, (st) => {
+    const node = st.parsed && st.parsed.node;
+    if (!node || typeof node !== 'object') return;
+    if (node.kind === 'CALL') {
+      const callee = node.callee;
+      if (!callee || callee.t !== 'ref' || !callee.name) return;
+      const key = String(callee.name).toUpperCase();
+      if (entryVariables.has(key)) {
+        const varName = entryVariables.get(key);
+        const constants = assignedConstants.get(key);
+        const detail = constants && constants.size
+          ? `CALL ${callee.name} dispatches through an entry variable assigned ${[...constants].join(', ')}`
+          : `CALL ${callee.name} dispatches through an entry variable with no entry constant assigned in this program`;
+        findings.push({ rule: 'pli-entry-variable-call', path: program.path, line: st.line, detail });
+      }
+    } else if (node.kind === 'FETCH' && Array.isArray(node.entries)) {
+      for (const entry of node.entries) {
+        if (!entry || entry.title === null || entry.title === undefined) continue;
+        if (isLiteralTitle(entry.title)) continue;
+        const name = entry.name || 'FETCH';
+        findings.push({
+          rule: 'pli-fetch-title-variable',
+          path: program.path,
+          line: st.line,
+          detail: `FETCH ${name} loads a module named at run time because its TITLE is not a literal`,
+        });
+      }
+    }
+  });
+
+  return findings;
+}

package/lib/pli/rules/index.mjs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The PL/I rules: each module checks one parsed program and returns findings. A program is
+// { path, statements } where each statement is as readPli gives it with `parsed`, its parseStatement
+// result, attached.
+import { readPli } from '../lex.mjs';
+import { parseStatement } from '../statements.mjs';
+import * as based from './based.mjs';
+import * as entry from './entry.mjs';
+import * as preprocessor from './preprocessor.mjs';
+import * as conditions from './conditions.mjs';
+
+const MODULES = [based, entry, preprocessor, conditions];
+
+export const PLI_RULES = Object.freeze(Object.assign({}, ...MODULES.map((m) => m.RULES)));
+
+export function programOf(path, text) {
+  const statements = readPli(text, { file: path }).statements.map((st) => ({ ...st, parsed: parseStatement(st) }));
+  return { path, statements };
+}
+
+// Findings { rule, path, line, detail } for one program, in source order.
+export function checkProgram(program) {
+  return MODULES.flatMap((m) => m.check(program)).sort((a, b) => a.line - b.line || (a.rule < b.rule ? -1 : 1));
+}

package/lib/pli/rules/preprocessor.mjs

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// PL/I rules on preprocessor use.
+
+export const RULES = {
+  'pli-preprocessor-in-use': {
+    sev: 'info',
+    evidence: 'coverage',
+    cwe: 'CWE-1059',
+    text: 'A program uses PL/I preprocessor directives, so the source text is not the code that is compiled'
+  }
+};
+
+// Directives that change the text compiled; INCLUDE is read through and listing directives change nothing.
+const DIRECTIVES = new Set(['IF', 'DO', 'DCL', 'DECLARE', 'ASSIGN', 'ACT', 'ACTIVATE', 'DEACT', 'DEACTIVATE', 'PROC', 'PROCEDURE', 'SELECT', 'REPLACE', 'GO', 'GOTO']);
+
+function collectDirectives(node, set) {
+  if (!node) return;
+  if (node.kind === 'PREPROCESSOR' && typeof node.directive === 'string') {
+    const d = node.directive.toUpperCase();
+    if (DIRECTIVES.has(d)) set.add(d);
+  }
+  if (Array.isArray(node.units)) {
+    for (const u of node.units) {
+      if (u && u.node) collectDirectives(u.node, set);
+    }
+  }
+}
+
+export function check(program) {
+  const findings = [];
+  const directives = new Set();
+  let firstLine = null;
+
+  for (const st of program.statements) {
+    if (!st.parsed || st.parsed.status !== 'parsed') continue;
+    const node = st.parsed.node;
+    if (!node) continue;
+    collectDirectives(node, directives);
+    if (directives.size > 0 && firstLine === null) {
+      firstLine = st.line;
+    }
+  }
+
+  if (firstLine !== null) {
+    const list = [...directives].sort().join(', ');
+    findings.push({
+      rule: 'pli-preprocessor-in-use',
+      path: program.path,
+      line: firstLine,
+      detail: `preprocessor directives ${list} alter the source before compilation`
+    });
+  }
+
+  return findings;
+}