@portll/cobolwork 0.0.1 → 0.2.75

package/lib/policy.mjs

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Which findings stop a build, which run-time checks the compiler must generate, and what an
+// incomplete scan means: docs/spec/build-gate.md §4. Two layers - a floor from outside the reviewed
+// tree and the repository's own file - and at every key the stricter of the two applies.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ALL_RULES } from './kernel/registry.mjs';
+import { resolvesInside } from './kernel/source-tree.mjs';
+import { printable } from './kernel/printable.mjs';
+import { CLASSES, TIERS, TIER_RANK } from './consequence.mjs';
+
+export const POLICY_FILE = 'cobolwork.policy.json';
+export const CHECKS = ['subscript', 'reference-modification', 'numeric-data', 'argument-length'];
+export const COMPILERS = ['enterprise', 'gnucobol'];
+
+export const DEFAULT_POLICY = Object.freeze({
+  policyVersion: 1,
+  block: 'high',
+  always: 'crit',
+  classes: [...CLASSES],
+  rules: {},
+  coverage: 'block',
+  options: 'warn',
+  waivers: { maxDays: 180 },
+  checks: ['subscript', 'reference-modification'],
+  forbid: { enterprise: [], gnucobol: [] },
+});
+
+const KEYS = Object.keys(DEFAULT_POLICY);
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isStrings = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string' && x.trim() !== '');
+
+// What is wrong with a policy document, or nothing. A key nobody reads and a rule id nothing
+// declares are both refused: either would be a setting that silently does nothing.
+export function validatePolicy(raw) {
+  if (!isObject(raw)) return ['the policy is not a JSON object'];
+  const errs = [];
+  for (const k of Object.keys(raw)) if (!KEYS.includes(k) && k !== '_comment') errs.push(`${printable(k, 40)} is not a policy key; the keys are ${KEYS.join(', ')}`);
+  if (raw.policyVersion !== 1) errs.push('policyVersion must be 1');
+  for (const k of ['block', 'always']) if (k in raw && !TIERS.includes(raw[k])) errs.push(`${k} must be one of ${TIERS.join(', ')}`);
+  if ('classes' in raw) {
+    if (!Array.isArray(raw.classes) || raw.classes.some((c) => !CLASSES.includes(c))) errs.push(`classes must be a list drawn from ${CLASSES.join(', ')}`);
+  }
+  for (const k of ['coverage', 'options']) if (k in raw && !['block', 'warn'].includes(raw[k])) errs.push(`${k} must be block or warn`);
+  if ('rules' in raw) {
+    if (!isObject(raw.rules)) errs.push('rules must be an object of rule id to block or warn');
+    else for (const [id, v] of Object.entries(raw.rules)) {
+      if (!Object.hasOwn(ALL_RULES, id)) errs.push(`rules: ${printable(id, 60)} is not a rule cobolwork declares`);
+      else if (!['block', 'warn'].includes(v)) errs.push(`rules: ${id} must be block or warn`);
+    }
+  }
+  if ('waivers' in raw) {
+    const w = raw.waivers;
+    if (!isObject(w) || Object.keys(w).some((k) => k !== 'maxDays') || !Number.isInteger(w.maxDays) || w.maxDays < 1) {
+      errs.push('waivers must be { "maxDays": <a whole number of days, at least 1> }');
+    }
+  }
+  if ('checks' in raw) {
+    if (!isStrings(raw.checks)) errs.push(`checks must be a list drawn from ${CHECKS.join(', ')}`);
+    else for (const c of raw.checks) if (!CHECKS.includes(c)) errs.push(`checks: ${printable(c, 40)} is not one of ${CHECKS.join(', ')}`);
+  }
+  if ('forbid' in raw) {
+    if (!isObject(raw.forbid)) errs.push(`forbid must be an object keyed by ${COMPILERS.join(' or ')}`);
+    else for (const [c, list] of Object.entries(raw.forbid)) {
+      if (!COMPILERS.includes(c)) errs.push(`forbid: ${printable(c, 40)} is not one of ${COMPILERS.join(', ')}`);
+      else if (!isStrings(list)) errs.push(`forbid.${c} must be a list of options`);
+    }
+  }
+  return errs;
+}
+
+// { path, raw, problems }, or null when the file is absent.
+export function readPolicy(path) {
+  if (!existsSync(path)) return null;
+  let raw;
+  try { raw = JSON.parse(readFileSync(path, 'utf8')); } catch (e) {
+    return { path, raw: null, problems: [`${path} is not readable as JSON: ${printable(e.message, 120)}`] };
+  }
+  return { path, raw, problems: validatePolicy(raw).map((p) => `${path}: ${p}`) };
+}
+
+// The repository's own policy, from a tree on disk. A link out of the tree is not followed.
+export function treePolicy(root) {
+  const path = join(root, POLICY_FILE);
+  if (!existsSync(path)) return null;
+  if (!resolvesInside(root, path)) return { path, raw: null, problems: [`${POLICY_FILE} is a link that leads outside the tree`] };
+  return readPolicy(path);
+}
+
+// The floor must come from outside the reviewed tree, or the change under review could write it.
+export function floorPolicy(file, repo) {
+  const path = resolve(file);
+  if (!existsSync(path)) return { path, raw: null, problems: [`--policy ${path}: no such file`] };
+  if (resolvesInside(repo, path)) return { path, raw: null, problems: [`--policy ${path} is inside the repository; a floor the change can edit is not a floor`] };
+  return readPolicy(path);
+}
+
+const stricterTier = (a, b) => (TIER_RANK[a] <= TIER_RANK[b] ? a : b);
+const union = (a, b) => [...new Set([...a, ...b])].sort();
+// A list key the repository can add to and never shrink below the floor, or the defaults without one.
+const listKey = (key, f, r, floor) => {
+  const base = key in f ? f[key] : DEFAULT_POLICY[key];
+  if (!(key in r)) return { value: [...base].sort(), by: key in f ? 'floor' : 'default' };
+  if (!floor) return { value: [...r[key]].sort(), by: 'repository' };
+  return { value: union(base, r[key]), by: key in f ? 'floor+repository' : 'default+repository' };
+};
+
+// { policy, setBy, ignored }. Without a floor the repository's file stands over the defaults. With
+// one, a repository key applies only where it is at least as strict as the floor's, and each key it
+// could not loosen is named in `ignored`.
+export function combinePolicies({ floor = null, repository = null } = {}) {
+  const f = floor || {};
+  const r = repository || {};
+  const setBy = {};
+  const ignored = [];
+  const pick = (key, stricter) => {
+    const base = key in f ? f[key] : DEFAULT_POLICY[key];
+    const baseBy = key in f ? 'floor' : 'default';
+    if (!(key in r)) { setBy[key] = baseBy; return base; }
+    if (!floor) { setBy[key] = 'repository'; return r[key]; }
+    const s = stricter(base, r[key]);
+    if (JSON.stringify(s) === JSON.stringify(r[key])) { setBy[key] = 'repository'; return r[key]; }
+    ignored.push(key);
+    setBy[key] = baseBy;
+    return base;
+  };
+  const checks = listKey('checks', f, r, floor);
+  const classes = listKey('classes', f, r, floor);
+  const policy = {
+    policyVersion: 1,
+    block: pick('block', stricterTier),
+    always: pick('always', stricterTier),
+    classes: classes.value,
+    coverage: pick('coverage', (a, b) => (a === 'block' || b === 'block' ? 'block' : 'warn')),
+    options: pick('options', (a, b) => (a === 'block' || b === 'block' ? 'block' : 'warn')),
+    waivers: pick('waivers', (a, b) => ({ maxDays: Math.min(a.maxDays, b.maxDays) })),
+    checks: checks.value,
+    forbid: Object.fromEntries(COMPILERS.map((c) => [c, union((f.forbid || {})[c] || [], (r.forbid || {})[c] || [])])),
+    rules: {},
+  };
+  setBy.checks = checks.by;
+  setBy.classes = classes.by;
+  setBy.forbid = r.forbid ? (f.forbid ? 'floor+repository' : 'repository') : f.forbid ? 'floor' : 'default';
+  const fr = f.rules || {};
+  const rr = r.rules || {};
+  for (const id of [...new Set([...Object.keys(fr), ...Object.keys(rr)])].sort()) {
+    // block is always the stricter; the repository's warn stands only where the floor also says warn.
+    if (rr[id] === 'block' || !floor || !(id in rr) || fr[id] === 'warn') policy.rules[id] = id in rr ? rr[id] : fr[id];
+    else { policy.rules[id] = fr[id] || null; ignored.push(`rules.${id}`); }
+    if (policy.rules[id] === null) delete policy.rules[id];
+  }
+  return { policy, setBy, ignored };
+}
+
+// Keys sorted at every level, so one policy has one hash however its file was written.
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (isObject(value)) return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+export const policyHash = (policy) => createHash('sha256').update(canonical(policy)).digest('hex');

package/lib/precompile-cics.mjs

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The EXEC CICS half of lib/precompile.mjs: what one CICS command becomes, and the copybooks a CICS
+// program copies that no repository holds. The commands, the direction each option's data moves and
+// the DFHRESP and DFHVALUE numbers are IBM's, recorded with their pages in provenance/precompile.json.
+import { EIB_LAYOUT } from './words.mjs';
+import { CICS_COMMANDS, CICS_EVERY_COMMAND, DFHRESP, DFHVALUE, DFHAID_NAMES, DFHBMSCA_NAMES } from './cics-commands.mjs';
+
+// The number DFHRESP(name) or DFHVALUE(name) stands for, or undefined for a name IBM's tables lack.
+export const builtinValue = (fn, name) => (fn === 'RESP' ? DFHRESP : DFHVALUE)[name];
+
+// Whitespace runs outside literals, as one space.
+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) {
+  const out = [];
+  let i = 0;
+  while (i < text.length) {
+    const m = /^[\s,]*([A-Z0-9][A-Z0-9-]*)/i.exec(text.slice(i));
+    if (!m) { i++; continue; }
+    i += m[0].length;
+    const word = m[1].toUpperCase();
+    const p = /^\s*\(/.exec(text.slice(i));
+    if (!p) { out.push({ word }); continue; }
+    i += p[0].length;
+    let depth = 1;
+    let quote = null;
+    let arg = '';
+    for (; i < text.length; i++) {
+      const ch = text[i];
+      if (quote) { if (ch === quote) quote = null; } else if (ch === "'" || ch === '"') quote = ch;
+      else if (ch === '(') depth++;
+      else if (ch === ')' && --depth === 0) break;
+      arg += ch;
+    }
+    i++;
+    out.push({ word, arg: squeeze(arg) });
+  }
+  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).
+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)))
+    || names.find((n) => n === verb) || names.find((n) => CICS_COMMANDS[n].default) || null;
+}
+
+// A literal, a figurative constant or anything computed can only be sent, whatever its option does.
+const LITERAL = /^(?:[A-Z]{0,2}(['"])[\s\S]*\1|[+-]?\d*\.?\d+|(?:ZEROE?S?|SPACES?|LOW-VALUES?|HIGH-VALUES?|QUOTES?|NULLS?|ALL\s.+))$/i;
+const COMPUTED = /^(?:LENGTH\s+OF|FUNCTION)\s/i;
+
+// The commands that set or clear how a later condition, attention key or abend is handled.
+const HANDLERS = new Set(['HANDLE CONDITION', 'HANDLE AID', 'HANDLE ABEND', 'IGNORE CONDITION', 'PUSH HANDLE', 'POP HANDLE']);
+
+// The EIB halfword a HANDLE's GO TO ... DEPENDING ON reads: 0 when the HANDLE itself runs, so control
+// falls through, and the label's position when CICS later returns there to take the branch.
+export const SELECTOR = 'DFHEIGDI';
+
+// What one EXEC CICS block becomes: a CALL naming the command, then each argument by its option's
+// direction, then the EIB, which every command updates. A command the table lacks passes every data
+// name BY REFERENCE, since nothing says what it does not write. A HANDLE with labels is followed by the
+// GO TO ... DEPENDING ON its branch is taken through. `state` carries whether the block is in the
+// procedure division, has the EIB and the selector, and collects the handlers and the counts.
+export function translateCics(block, state) {
+  if (!state.procedure) return '';
+  const options = cicsOptions(block.text);
+  if (!options.length) return 'CONTINUE';
+  const name = cicsCommand(options);
+  const command = name && CICS_COMMANDS[name];
+  const second = options[1];
+  const callName = name || [options[0].word, ...(second && second.arg === undefined && second.word !== 'NOHANDLE' ? [second.word] : [])].join(' ');
+  if (!command) state.unknown++;
+  if (HANDLERS.has(name)) state.handlers.push({ line: block.line + 1, command: name, options: Object.fromEntries(options.slice(name.split(' ').length).map((o) => [o.word, o.arg ?? null])) });
+  const sending = [];
+  const receiving = [];
+  const labels = [];
+  const pass = (text, direction) => {
+    const list = direction === 'sends' || LITERAL.test(text) || COMPUTED.test(text) ? sending : receiving;
+    if (!list.includes(text)) list.push(text);
+  };
+  for (const o of options.slice(1)) {
+    if (!o.arg) continue;
+    const direction = command ? (command.options[o.word] || CICS_EVERY_COMMAND[o.word] || command.anyOption) : null;
+    if (direction === 'label') { labels.push(o.arg); continue; }
+    if (command && !direction) state.undirected++;
+    const builtin = /^DFH(RESP|VALUE)\s*\(\s*([A-Z0-9-]+)\s*\)$/i.exec(o.arg);
+    const value = builtin ? builtinValue(builtin[1].toUpperCase(), builtin[2].toUpperCase()) : undefined;
+    if (builtin && value === undefined) state.unresolved++;
+    pass(value === undefined ? o.arg : String(value), builtin ? 'sends' : direction);
+  }
+  // RECEIVE MAP without INTO writes the map's input record, SEND MAP without FROM reads its output one.
+  const written = new Set(options.map((o) => o.word));
+  for (const [option, d] of Object.entries(command?.defaults || {})) {
+    const map = /^(['"])([A-Z0-9$#@]+)\1$/i.exec(options.find((o) => o.word === d.name)?.arg || '');
+    if (map && !written.has(option) && !d.unless.some((w) => written.has(w))) pass(`${map[2].toUpperCase()}${d.suffix}`, command.options[option]);
+  }
+  const content = sending.filter((t) => !receiving.includes(t));
+  if (state.eib) receiving.push('DFHEIBLK');
+  const args = [...(content.length ? ['BY CONTENT', ...content] : []), ...(receiving.length ? ['BY REFERENCE', ...receiving] : [])];
+  state.translated++;
+  const branch = labels.length && state.selector ? [`GO TO ${labels.join(' ')} DEPENDING ON ${SELECTOR}`] : [];
+  return [`CALL 'CW-CICS-${callName.split(' ').join('-')}'`, ...(args.length ? ['USING', ...args] : []), ...branch].join(' ');
+}
+
+// The EXEC interface block the translator declares for every program with CICS in it, with the
+// selector a HANDLE's branch reads in the reserved halfword after EIBTRMID.
+export function eibCopybook() {
+  const fields = EIB_LAYOUT.flatMap(([n, pic]) => [[n, pic], ...(n === 'EIBTRMID' ? [[SELECTOR, 'S9(4) COMP']] : [])]);
+  return ['       01 DFHEIBLK.', ...fields.map(([n, pic]) => `          05 ${n} PIC ${pic}.`), ''].join('\n');
+}
+
+// DFHAID and DFHBMSCA are IBM's and in no repository; each name is declared as one character, enough
+// for a program that compares EIBAID with one or moves one to an attribute byte.
+export const CONSTANT_COPYBOOKS = { DFHAID: DFHAID_NAMES, DFHBMSCA: DFHBMSCA_NAMES };
+export const constantsCopybook = (names) => `${names.map((n) => `       01 ${n} PIC X.`).join('\n')}\n`;
+
+// A mapset's symbolic map, laid out the way the BMS assembler lays one out for COBOL: the 12-byte
+// prefix when TIOAPFX=YES, then for each named field its length, flag or attribute byte, extended
+// attribute bytes and data, the output record redefining the input. Grouped (GRPNAME) and OCCURS
+// fields are laid out differently, and a mapset holding either is not written. Returns the copybook
+// text and the names it declares, or null.
+const ATTRIBUTE_LETTER = { COLOR: 'C', PS: 'P', HILIGHT: 'H', VALIDN: 'V', OUTLINE: 'U', SOSI: 'M', TRANSP: 'T' };
+export function symbolicMapCopybook(mapset) {
+  const out = [];
+  const names = [];
+  const line = (s) => out.push(`       ${s}`);
+  const declare = (n, s) => { names.push(n); line(s); };
+  // The assembler writes FILLER; each gets a name here, the layout unchanged, so the grade can tell
+  // the stand-in's items from the program's.
+  let k = 0;
+  const filler = (rec) => { const n = `${rec}-F${++k}`; names.push(n); return n; };
+  for (const map of mapset.maps) {
+    const fields = map.fields.filter((f) => f.name);
+    if (fields.some((f) => f.grpname || f.occurs > 1)) return null;
+    const { input, output, attributes } = map.symbolic;
+    if (!input && !output) continue;
+    const prefix = String(map.operands?.get?.('TIOAPFX') ?? mapset.options.tioapfx ?? '').toUpperCase() === 'YES';
+    const pic = (f, which) => f[which] || `X(${f.length})`;
+    if (input) {
+      declare(input, `01  ${input}.`);
+      if (prefix) line(`    02  ${filler(input)} PIC X(12).`);
+      for (const f of fields) {
+        const n = f.name.toUpperCase();
+        declare(`${n}L`, `    02  ${n}L COMP PIC S9(4).`);
+        declare(`${n}F`, `    02  ${n}F PIC X.`);
+        line(`    02  ${filler(input)} REDEFINES ${n}F.`);
+        declare(`${n}A`, `      03  ${n}A PIC X.`);
+        if (attributes.length) line(`    02  ${filler(input)} PIC X(${attributes.length}).`);
+        declare(`${n}I`, `    02  ${n}I PIC ${pic(f, 'picin')}.`);
+      }
+    }
+    if (output) {
+      declare(output, input ? `01  ${output} REDEFINES ${input}.` : `01  ${output}.`);
+      if (prefix) line(`    02  ${filler(output)} PIC X(12).`);
+      for (const f of fields) {
+        const n = f.name.toUpperCase();
+        if (input) line(`    02  ${filler(output)} PIC X(3).`);
+        else { line(`    02  ${filler(output)} PIC X(2).`); declare(`${n}A`, `    02  ${n}A PIC X.`); }
+        for (const a of attributes) declare(`${n}${ATTRIBUTE_LETTER[a]}`, `    02  ${n}${ATTRIBUTE_LETTER[a]} PIC X.`);
+        declare(`${n}O`, `    02  ${n}O PIC ${pic(f, 'picout')}.`);
+      }
+    }
+  }
+  return out.length ? { text: `${out.join('\n')}\n`, names } : null;
+}