@portll/cobolwork 0.5.0 → 0.7.0

package/lib/build.mjs

@@ -6,25 +6,29 @@ import { checkEquivalence } from './equivalence.mjs';
 import { optionChanges } from './option-diff.mjs';
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { basename, extname, join } from 'node:path';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { parseAllowedSigners } from './evidence/sshsig.mjs';
 import { scanAll } from './scan.mjs';
 import { withRefs, configurationChanges, WORKING_TREE } from './diff.mjs';
 import { pairLists, findExecutable } from './gate.mjs';
 import { pairingKeys } from './kernel/identity.mjs';
-import { directoryTree } from './kernel/source-tree.mjs';
+import { directoryTree, pdsExportTree, resolvesInside } from './kernel/source-tree.mjs';
 import { printable } from './kernel/printable.mjs';
 import { ALL_RULES } from './kernel/registry.mjs';
 import { loadBaseline, applyBaseline, SUPPRESSING } from './baseline.mjs';
 import { loadSite, SITE_FILE } from './site.mjs';
-import { isProgram, isJcl, isSource, readSource, relPath } from './sources.mjs';
-import { parseJclFile } from './jcl.mjs';
+import { isProgram, isJcl, isSource, relPath } from './sources.mjs';
+import { parseJcl } from './jcl.mjs';
 import { POLICY_FILE, treePolicy, floorPolicy, combinePolicies, canonical, policyHash } from './policy.mjs';
 import { classesOf, tierOf, TIERS, TIER_RANK } from './consequence.mjs';
-import { optionCards, enterpriseChecks, compilerChecks, scriptedChecks, compilerInvocations, compilerTasks, compileStepOptions, compilerOf } from './options.mjs';
+import { optionCards, enterpriseChecks, compilerChecks, scriptedChecks, compilerInvocations, compilerTasks, compileStepOptions, compilerOf, olderThan } from './options.mjs';
+import { isBuildFile, pinsIn } from './sets/build.mjs';
 import { FLOW_MODEL, TOOL_VERSION } from './version.mjs';
 import { checkWithIronwork, ironworkVerdict, ironworkReasons, ironworkVersion, listed } from './ironwork.mjs';
 import { buildFileIndex } from './parser.mjs';
+import { precompileCheck } from './precompile-check.mjs';
 
 export const BUILD_SCHEMA_VERSION = 1;
 export const BUILD_EXIT = { pass: 0, fail: 1, undecided: 3, compilerFailed: 4 };
@@ -62,8 +66,11 @@ function introducedIn(before, after, baseRoot, headRoot) {
 // Why a finding blocks, or null. `renewed` is a finding whose waiver expired or ran past maxDays: in
 // ratchet mode it is judged as new, because the promise that carried it has lapsed.
 export function blockingReason(f, { policy, ratchet, introduced, renewed }) {
+  if (f.abend?.inputFrom === 'interface' && policy.interface !== 'tier') return null;
   const setting = policy.rules[f.rule];
   if (setting === 'warn') return null;
+  // A rule whose firing rate the corpus has not recorded blocks only where the policy names it.
+  if (ALL_RULES[f.rule]?.measured === false) return setting === 'block' ? 'rule' : null;
   const tier = tierOf(f);
   if (ratchet && TIER_RANK[tier] >= TIER_RANK[policy.always]) return 'tier';
   if (ratchet && !introduced.has(f) && !renewed.has(f.fingerprint)) return null;
@@ -82,12 +89,12 @@ const MAX_BARE_SCRIPT_BYTES = 64 << 10;
 const kindOf = (rel) => (/(^|\/)(gnu)?makefile$|\.mk$/i.test(rel) ? 'make' : /(^|\/)dockerfile$/i.test(rel) ? 'docker'
   : /\.(bat|cmd)$/i.test(rel) ? 'batch' : /\.ps1$/i.test(rel) ? 'powershell' : /\.ya?ml$/i.test(rel) ? 'yaml' : 'sh');
 
-function scriptInvocations(file, rel) {
-  if (EDITOR_TASKS.test(rel)) return compilerTasks(readSource(file).text);
-  const size = statSync(file).size;
-  if (BUILD_SCRIPT.test(rel) && size <= MAX_SCRIPT_BYTES) return compilerInvocations(readSource(file).text, { kind: kindOf(rel) });
+function scriptInvocations(tree, file, rel) {
+  if (EDITOR_TASKS.test(rel)) return compilerTasks(tree.text(file).text);
+  const size = tree.kind === 'directory' ? statSync(file).size : tree.bytes(file).length;
+  if (BUILD_SCRIPT.test(rel) && size <= MAX_SCRIPT_BYTES) return compilerInvocations(tree.text(file).text, { kind: kindOf(rel) });
   if (!extname(file) && size <= MAX_BARE_SCRIPT_BYTES) {
-    const bytes = readFileSync(file);
+    const bytes = tree.bytes(file);
     return bytes.includes(0) ? [] : compilerInvocations(bytes.toString('latin1'), { kind: 'sh' });
   }
   return [];
@@ -95,14 +102,14 @@ function scriptInvocations(file, rel) {
 
 // How the repository says it compiles its programs: the cobc and gcobol commands its build scripts
 // run, and the Enterprise COBOL compile steps its JCL holds.
-function declaredCompiles(root, files) {
+function declaredCompiles(tree, files) {
   const invocations = [];
   const parsedJcl = [];
   for (const f of files) {
-    const rel = relPath(root, f);
+    const rel = tree.rel(f);
     try {
-      if (isJcl(f)) parsedJcl.push({ ...parseJclFile(f), file: rel });
-      else if (!isProgram(f)) for (const inv of scriptInvocations(f, rel)) invocations.push({ ...inv, file: rel });
+      if (isJcl(f)) parsedJcl.push({ ...parseJcl(tree.text(f).text, f), file: rel });
+      else if (!isProgram(f)) for (const inv of scriptInvocations(tree, f, rel)) invocations.push({ ...inv, file: rel });
     } catch { /* unreadable: the scan counts it, and it declares nothing here */ }
   }
   const steps = new Map();
@@ -115,27 +122,41 @@ function declaredCompiles(root, files) {
 
 const memberName = (file) => basename(file).replace(/\.[^.]*$/, '').toUpperCase();
 
+// The GnuCOBOL version the repository's build files pin, the oldest where they pin several.
+function pinnedGnucobol(tree, files) {
+  let oldest = null;
+  for (const file of files.filter(isBuildFile)) {
+    let text;
+    try { text = tree.text(file).text; } catch { continue; }
+    for (const p of pinsIn(text)) {
+      if (p.product === 'gnucobol' && (!oldest || olderThan(p.version, oldest.version))) oldest = { version: p.version, where: tree.rel(file) };
+    }
+  }
+  return oldest;
+}
+
 // The options every program in the tree is compiled with, held to the policy. A program's options
 // come from the estate's declared defaults, the JCL step that compiles it and its own option cards;
 // where it has none of those, from the cobc and gcobol commands the repository's build scripts run.
 // `ok` is false where a required check is not generated and null where no one can tell; `forbidden`
 // counts options the policy's forbid list names. `generated` maps each program and build script to
 // the checks it generates, for telling a change that removes one.
-function optionsCheck({ root, allow, site, policy, compiler }) {
+function optionsCheck({ root, tree: given = null, allow, site, policy, compiler }) {
   const required = policy.checks;
   const kind = compiler && compilerOf(compiler[0]);
   if (compiler && !kind) {
     return { ok: null, forbidden: 0, reasons: [`the gate reads the options of cobc, of gcobol and of Enterprise COBOL option cards; for ${printable(compiler[0], 60)} it cannot tell what reaches the compiler`], add: [], generated: new Map() };
   }
+  const tree = given || directoryTree(root);
+  const files = [...new Set(tree.list())].filter((p) => !allow || allow.has(p)).sort();
+  const pinned = pinnedGnucobol(tree, files);
   if (compiler) {
-    const r = compilerChecks(kind, compiler.slice(1), { required, forbid: policy.forbid[kind] });
+    const r = compilerChecks(kind, compiler.slice(1), { required, forbid: policy.forbid[kind], pinned });
     const missing = r.checks.filter((c) => c.ok === false).map((c) => c.why);
     return { ok: missing.length || r.forbidden.length ? false : true, forbidden: r.forbidden.length, reasons: [...r.forbidden, ...missing], add: r.forbidden.length ? [] : r.add, compiler: kind, generated: new Map() };
   }
-  const tree = directoryTree(root);
-  const files = [...new Set(tree.list())].filter((p) => !allow || allow.has(p)).sort();
   const programs = files.filter(isProgram);
-  const declared = declaredCompiles(root, files);
+  const declared = declaredCompiles(tree, files);
   let ok = true;
   let forbidden = 0;
   const reasons = [];
@@ -150,7 +171,7 @@ function optionsCheck({ root, allow, site, policy, compiler }) {
   };
 
   for (const inv of declared.invocations) {
-    const r = scriptedChecks(inv.compiler, inv.args, { required, forbid: policy.forbid[inv.compiler] });
+    const r = scriptedChecks(inv.compiler, inv.args, { required, forbid: policy.forbid[inv.compiler], pinned });
     record(inv.file, r.checks);
     forbidden += r.forbidden.length;
     for (const why of [...r.checks.filter((c) => c.ok === false).map((c) => c.why), ...r.forbidden]) fail(`${inv.file}:${inv.line}: ${why}`);
@@ -158,7 +179,7 @@ function optionsCheck({ root, allow, site, policy, compiler }) {
   let unknown = 0;
   for (const file of programs) {
     let text;
-    try { text = readSource(file).text; } catch { open(); reasons.push(`${printable(relPath(root, file), 120)} could not be read, so its options are not known`); continue; }
+    try { text = tree.text(file).text; } catch { open(); reasons.push(`${printable(tree.rel(file), 120)} could not be read, so its options are not known`); continue; }
     const cards = optionCards(text);
     const steps = declared.steps.get(memberName(file)) || [];
     const siteOptions = site.compilerOptions || [];
@@ -167,10 +188,10 @@ function optionsCheck({ root, allow, site, policy, compiler }) {
       continue;
     }
     const r = enterpriseChecks({ required, site: siteOptions, steps, cards, forbid: policy.forbid.enterprise });
-    record(relPath(root, file), r.checks);
+    record(tree.rel(file), r.checks);
     forbidden += r.forbidden.length;
     const failed = r.checks.filter((c) => c.ok === false).map((c) => c.why);
-    for (const why of [...failed, ...r.forbidden]) fail(`${relPath(root, file)}: ${why}`);
+    for (const why of [...failed, ...r.forbidden]) fail(`${tree.rel(file)}: ${why}`);
     if (!failed.length && !r.forbidden.length && r.checks.some((c) => c.ok === null)) { unknown++; open(); }
   }
   if (unknown) reasons.push(`${unknown} program(s) have no option this gate can read for ${required.join(', ')}: no compile step or build script names them; declare the estate's defaults as compilerOptions in cobolwork.site.json`);
@@ -193,20 +214,41 @@ function optionsRemoved(before, after) {
   return removed;
 }
 
-// The files a scan of `root` reads, hashed, for the provenance record.
-function sourceHashes(root, allow) {
-  const tree = directoryTree(root);
+// The files a scan of `root`, or of a PDS export's tree, reads, hashed, for the provenance record.
+function sourceHashes(root, allow, given = null) {
+  const tree = given || directoryTree(root);
   return [...new Set(tree.list())].filter((p) => isSource(p) && (!allow || allow.has(p))).sort()
-    .map((p) => ({ path: relPath(root, p), sha256: sha256(readFileSync(p)) }))
+    .map((p) => ({ path: tree.rel(p), sha256: sha256(tree.bytes(p)) }))
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
 }
 
+// A PDS export's members written out as DATA.SET/MEMBER for ironwork, which reads files: the
+// programs to check, and each copy library's directory. `fn` gets the layout's root and those.
+function withLayout(tree, allow, fn) {
+  const root = mkdtempSync(join(tmpdir(), 'cobolwork-pds-layout-'));
+  try {
+    const programs = [];
+    for (const p of tree.list()) {
+      const file = join(root, ...tree.rel(p).split('/'));
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, tree.text(p).text, 'latin1');
+      if (isProgram(p) && (!allow || allow.has(p))) programs.push(file);
+    }
+    return fn(root, programs.sort(), tree.index.copyDirs.map((d) => join(root, ...tree.rel(d).split('/'))));
+  } finally { rmSync(root, { recursive: true, force: true }); }
+}
+
 // ironwork checks the head tree, which in ratchet mode exists only while judge runs, so it runs
 // here rather than after the verdict the way a caller's compiler does.
-function ironworkCompile(path, { root, allow, copylibs, env }) {
-  const result = checkWithIronwork(path, root, { allow, copylibs, env });
+function ironworkCompile(path, { root, tree = null, allow, copylibs, env }) {
+  if (tree) return withLayout(tree, allow, (layout, programs, copyDirs) => ironworkChecked(path, { root: layout, programs, copyDirs, copylibs, env }));
+  return ironworkChecked(path, { root, allow, copylibs, env });
+}
+
+function ironworkChecked(path, { root, allow = null, programs = null, copyDirs = null, copylibs, env }) {
+  const result = checkWithIronwork(path, root, { allow, programs, copyDirs, copylibs, env });
   const check = ironworkVerdict(result);
-  const libraries = [...buildFileIndex(root).copyDirs.map((d) => relPath(root, d) || '.'), ...copylibs];
+  const libraries = [...(copyDirs || buildFileIndex(root).copyDirs).map((d) => relPath(root, d) || '.'), ...copylibs];
   return {
     check,
     reasons: ironworkReasons(result),
@@ -219,16 +261,27 @@ function ironworkCompile(path, { root, allow, copylibs, env }) {
   };
 }
 
-function judge({ baseDir, headDir, allow, policyRoot, floor, noBaseline, compiler, compilerPath, ironworkPath, env, now, advisoryFeeds, copylibs, equivalenceFiles = [], allowed = null, refs = null }) {
+// The members of a PDS export whose files `allow` holds: an archive's members by the archive's file.
+function membersAllowed(tree, allow) {
+  return new Set(tree.list().filter((p) => allow.has(resolve(tree.dir, tree.origin(p).replace(/\([^)]*\)$/, '')))));
+}
+
+function judge({ baseDir, headDir, allow: given, policyRoot, floor, noBaseline, compiler, compilerPath, ironworkPath, env, now, advisoryFeeds, copylibs, equivalenceFiles = [], allowed = null, refs = null, pdsExport = false }) {
   const repoPolicy = treePolicy(policyRoot);
   if (repoPolicy && repoPolicy.problems.length) throw refusal(`the repository policy does not validate: ${repoPolicy.problems.join('; ')}`);
   const { policy, setBy, ignored } = combinePolicies({ floor: floor ? floor.raw : null, repository: repoPolicy ? repoPolicy.raw : null });
   const ratchet = baseDir !== null;
+  // A PDS export is judged as its members, each side read as scan --pds-export reads it; the policy,
+  // site file and baseline stay files beside the members.
+  const trees = pdsExport ? { base: ratchet ? pdsExportTree(baseDir, { systemDirs: copylibs }) : null, head: pdsExportTree(headDir, { systemDirs: copylibs }) } : null;
+  const allow = trees && given ? membersAllowed(trees.head, given) : given;
   // In ratchet mode the change is judged by its base's site file, not by one it wrote itself.
-  const scanOpts = { ...(ratchet ? { site: join(baseDir, SITE_FILE) } : {}), ...(advisoryFeeds ? { advisoryFeeds } : {}), systemDirs: copylibs };
-  const before = ratchet ? scanAll(baseDir, scanOpts) : null;
-  const after = scanAll(headDir, { ...scanOpts, allow });
-  const introduced = ratchet ? introducedIn(before, after, baseDir, headDir) : new Set();
+  const siteFile = ratchet ? join(baseDir, SITE_FILE) : trees && existsSync(join(headDir, SITE_FILE)) ? join(headDir, SITE_FILE) : null;
+  const scanOpts = { ...(siteFile ? { site: siteFile } : {}), ...(advisoryFeeds ? { advisoryFeeds } : {}), systemDirs: copylibs };
+  const scanOf = (dir, tree, extra = {}) => (tree ? scanAll(tree.root, { ...scanOpts, ...extra, tree, feedRoot: dir }) : scanAll(dir, { ...scanOpts, ...extra }));
+  const before = ratchet ? scanOf(baseDir, trees?.base) : null;
+  const after = scanOf(headDir, trees?.head, { allow });
+  const introduced = ratchet ? introducedIn(before, after, trees ? trees.base.root : baseDir, trees ? trees.head.root : headDir) : new Set();
 
   const bounded = boundBaseline(noBaseline ? null : loadBaseline(policyRoot), policy.waivers.maxDays);
   applyBaseline(after, bounded.baseline, { now });
@@ -257,20 +310,22 @@ function judge({ baseDir, headDir, allow, policyRoot, floor, noBaseline, compile
     reasons.push(`coverage is incomplete${sets.length ? ` in ${sets.join(', ')}` : ''}${policy.coverage === 'block' ? ', and the policy says block, so what was not read cannot be told from what is clean' : '; the policy says warn'}`);
   }
   const site = loadSite(policyRoot);
-  const options = optionsCheck({ root: headDir, allow, site, policy, compiler });
+  const options = optionsCheck({ root: headDir, tree: trees?.head, allow, site, policy, compiler });
   reasons.push(...options.reasons);
   // A missing run-time check is a weaker build, not a defect: warn passes it relaxed. What the
   // policy forbids by name, and a check the change itself removed, still fail.
-  const removed = ratchet && !compiler ? optionsRemoved(optionsCheck({ root: baseDir, allow: null, site, policy, compiler }), options) : [];
+  const removed = ratchet && !compiler ? optionsRemoved(optionsCheck({ root: baseDir, tree: trees?.base, allow: null, site, policy, compiler }), options) : [];
   reasons.push(...removed.slice(0, MAX_PROGRAM_REASONS));
-  const optionsChanged = ratchet ? programOptionChanges(baseDir, headDir, allow) : [];
+  const optionsChanged = ratchet ? programOptionChanges(baseDir, headDir, allow, trees) : [];
   for (const c of optionsChanged.slice(0, MAX_PROGRAM_REASONS)) reasons.push(`${c.path}:${c.line} changes ${c.option} from ${c.base} to ${c.head}, which changes what the program's statements do without changing a statement`);
-  const equivalence = ratchet && (equivalenceFiles.length || policy.requireEquivalence !== 'never')
+  const wantsEquivalence = ratchet && (equivalenceFiles.length || policy.requireEquivalence !== 'never');
+  const equivalence = wantsEquivalence && !trees
     ? checkEquivalence({ baseDir, headDir, allow, files: equivalenceFiles, allowed, mode: policy.requireEquivalence, ...(refs || {}), systemDirs: copylibs, env })
-    : null;
+    : wantsEquivalence ? { problems: [], required: null, programs: [], mode: policy.requireEquivalence, notRun: 'equivalence is not run over a PDS export' } : null;
   if (equivalence) {
     reasons.push(...equivalence.problems);
-    if (equivalence.required === null) reasons.push('the policy requires equivalence for machine-authored changes, and whether this one is could not be read from the commits');
+    if (equivalence.notRun) reasons.push(`${equivalence.notRun}, and the policy or --equivalence asks for it`);
+    else if (equivalence.required === null) reasons.push('the policy requires equivalence for machine-authored changes, and whether this one is could not be read from the commits');
     if (equivalence.required) for (const p of equivalence.programs.filter((x) => !x.ok).slice(0, MAX_PROGRAM_REASONS)) reasons.push(`${p.path}: ${p.because}, and the policy requires equivalence${equivalence.mode === 'machineAuthored' ? ' for a machine-authored change' : ''}`);
   }
   const relaxOptions = policy.options === 'warn' && options.ok !== true && !options.forbidden && !removed.length;
@@ -288,7 +343,7 @@ function judge({ baseDir, headDir, allow, policyRoot, floor, noBaseline, compile
   const verdict = decided.includes(false) ? 'fail' : decided.includes(null) ? 'undecided' : 'pass';
   let compiled = null;
   if (ironworkPath && verdict === 'pass') {
-    const iw = ironworkCompile(ironworkPath, { root: headDir, allow, copylibs, env });
+    const iw = ironworkCompile(ironworkPath, { root: headDir, tree: trees?.head, allow, copylibs, env });
     compiled = iw.compiled;
     checks.compile = iw.check;
     reasons.push(...iw.reasons);
@@ -333,23 +388,26 @@ function judge({ baseDir, headDir, allow, policyRoot, floor, noBaseline, compile
       byTier,
       coverageIncomplete: incomplete,
       ...(after.summary.baseline && after.summary.baseline.problems ? { baselineProblems: after.summary.baseline.problems } : {}),
+      ...(trees ? { pdsExport: { ...(trees.base ? { base: trees.base.export } : {}), head: trees.head.export } } : {}),
     },
   };
-  const hashes = sourceHashes(headDir, allow);
+  const hashes = sourceHashes(headDir, allow, trees?.head);
   return { doc, report: after, policy, setBy, hashes, add: options.add, compilerPath };
 }
 
 // The watched options in force changed by the change, per program present on both sides.
-function programOptionChanges(baseDir, headDir, allow) {
+function programOptionChanges(baseDir, headDir, allow, trees = null) {
   const out = [];
-  const files = directoryTree(headDir).list().filter((p) => isProgram(p) && (!allow || allow.has(p))).sort();
+  const headTree = trees ? trees.head : directoryTree(headDir);
+  const baseTree = trees ? trees.base : directoryTree(baseDir);
+  const files = headTree.list().filter((p) => isProgram(p) && (!allow || allow.has(p))).sort();
   for (const head of files) {
-    const path = relPath(headDir, head);
-    const base = join(baseDir, path);
-    if (!existsSync(base)) continue;
+    const path = headTree.rel(head);
+    const base = resolve(baseTree.root, ...path.split('/'));
+    if (!(trees ? baseTree.contains(base) : existsSync(base))) continue;
     let before;
     let after;
-    try { before = readSource(base).text; after = readSource(head).text; } catch { continue; }
+    try { before = baseTree.text(base).text; after = headTree.text(head).text; } catch { continue; }
     for (const c of optionChanges(before, after)) out.push({ path, ...c });
   }
   return out;
@@ -364,10 +422,19 @@ function policyChanged(baseDir, headDir) {
 
 // Runs the gate over `repo`. `compiler` is the argument vector after `--`, or null. Returns
 // { doc, report, provenance, exit }; throws with code EBUILD when it could not run.
-export function build(repo, { base = null, head = null, policy = null, noBaseline = false, compiler = null, ironwork = null, advisoryFeeds = null, copylibs = [], equivalence = [], allowed = null, now = new Date().toISOString(), env = process.env } = {}) {
+export function build(repo, { base = null, head = null, policy = null, noBaseline = false, compiler = null, ironwork = null, advisoryFeeds = null, copylibs = [], equivalence = [], allowed: given = null, allowedSigners = null, now = new Date().toISOString(), env = process.env, pdsExport = false, precompile = false } = {}) {
   const floor = policy ? floorPolicy(policy, repo) : null;
   if (floor && floor.problems.length) throw refusal(floor.problems.join('; '));
+  let allowed = given;
+  if (allowedSigners) {
+    const path = resolve(allowedSigners);
+    if (resolvesInside(repo, path)) throw refusal(`--allowed-signers ${path} is inside the repository; signers the change can edit vouch for nothing`);
+    allowed = parseAllowedSigners(readFileSync(path, 'utf8'));
+  }
   if (compiler && ironwork) throw refusal('one compiler per build: -- names one and --ironwork another');
+  if (precompile && !compiler) throw refusal('--precompile translates the programs a compiler command names, so it needs -- and the compiler');
+  if (precompile && !compilerOf(compiler[0])) throw refusal(`--precompile checks a translation with cobc or gcobol -fsyntax-only; for ${printable(compiler[0], 60)} it cannot`);
+  if (pdsExport && compiler) throw refusal('a PDS export is checked with --ironwork; the compiler after -- reads the files of a repository, not the members of an export');
   let compilerPath = null;
   if (compiler) {
     if (!compiler.length) throw refusal('nothing follows --, so there is no compiler to run');
@@ -381,7 +448,7 @@ export function build(repo, { base = null, head = null, policy = null, noBaselin
     if (!found.path) throw refusal(`--ironwork: ${found.why}`);
     ironworkPath = found.path;
   }
-  const run = (baseDir, headDir, allow, policyRoot) => judge({ baseDir, headDir, allow, policyRoot, floor, noBaseline, compiler, compilerPath, ironworkPath, env, now, advisoryFeeds, copylibs, equivalenceFiles: equivalence, allowed, refs: base ? { repo, base, head: head || 'HEAD' } : null });
+  const run = (baseDir, headDir, allow, policyRoot) => judge({ baseDir, headDir, allow, policyRoot, floor, noBaseline, compiler, compilerPath, ironworkPath, env, now, advisoryFeeds, copylibs, equivalenceFiles: equivalence, allowed, refs: base ? { repo, base, head: head || 'HEAD' } : null, pdsExport });
   const judged = base
     ? withRefs(repo, base, head, {}, (baseDir, headDir, scoped) => {
       const r = run(baseDir, headDir, scoped.allow || null, baseDir);
@@ -399,7 +466,20 @@ export function build(repo, { base = null, head = null, policy = null, noBaselin
     if (doc.checks.compile === false) exit = BUILD_EXIT.compilerFailed;
     else if (doc.checks.compile === null && !doc.relaxed.includes('compile')) exit = BUILD_EXIT.undecided;
   }
-  if (compiler && doc.verdict === 'pass') {
+  // A program the compiler refuses once its EXEC SQL and CICS are translated stops the build before
+  // the caller's compiler runs, as a fail stops it.
+  if (precompile && doc.verdict === 'pass') {
+    const checked = precompileCheck({ compilerPath, argv: compiler.slice(1), repo, copylibs, env });
+    doc.precompiled = checked;
+    const refused = checked.programs.filter((p) => !p.ok);
+    doc.checks.precompile = refused.length === 0;
+    if (refused.length) {
+      exit = BUILD_EXIT.compilerFailed;
+      doc.reasons.push(`${refused.length} of ${checked.programs.length} program(s) holding EXEC SQL or CICS do not compile once precompiled`);
+      for (const p of refused.slice(0, MAX_PROGRAM_REASONS)) doc.reasons.push(`${p.path}: ${(p.errors || [])[0] || 'the compiler exited non-zero'}`);
+    }
+  }
+  if (compiler && doc.verdict === 'pass' && doc.checks.precompile !== false) {
     const argv = [...compiler.slice(1), ...judged.add];
     // The compiler's own output goes to standard error: standard output carries the document.
     const r = spawnSync(compilerPath, argv, { stdio: ['ignore', 2, 2], env, windowsHide: true });

package/lib/capabilities.mjs

@@ -6,29 +6,30 @@ import { RULE_SETS, ALL_RULES } from './kernel/registry.mjs';
 import { EVIDENCE } from './kernel/findings.mjs';
 import { FINGERPRINT_VERSION } from './kernel/identity.mjs';
 import { PROGRAM_EXT, COPY_EXT, JCL_EXT, BMS_EXT } from './sources.mjs';
-import { FLOW_MODEL, SCHEMA_VERSION, TOOL_VERSION } from './version.mjs';
+import { FLOW_MODEL, SCHEMA_VERSION, TOOL_VERSION, EXPLAIN_SCHEMA_VERSION, PARSE_SCHEMA_VERSION, BASELINE_RESULT_SCHEMA_VERSION, EVIDENCE_RESULT_SCHEMA_VERSION } from './version.mjs';
 import { BUILD_SCHEMA_VERSION, BUILD_EXIT } from './build.mjs';
 import { VERDICT_EXIT } from './gate.mjs';
 import { CHECKS, COMPILERS, DEFAULT_POLICY } from './policy.mjs';
 import { CLASSES, TIERS } from './consequence.mjs';
 import { toolRevision } from './revision.mjs';
+import { IRONWORK_FORMATS, IRONWORK_MINIMUM, NOT_RUN_ABENDS, RUN_ENDINGS } from './ironwork-ids.mjs';
 
 export const CAPABILITIES_SCHEMA_VERSION = 1;
 
 // Each command, what it takes and what it writes.
 export const COMMANDS = {
-  scan: { args: ['<path>'], options: ['--format', '--out', '--repos', '--only', '--quiet', '--full-trace', '--all-routes', '--baseline', '--no-baseline', '--advisories', '--copylib', '--pds-export', '--evidence'], documents: ['cobolwork', 'sarif'] },
+  scan: { args: ['<path>'], options: ['--format', '--out', '--repos', '--only', '--quiet', '--full-trace', '--all-routes', '--baseline', '--no-baseline', '--advisories', '--copylib', '--pds-export', '--mvs38-forms', '--no-mvs38-forms', '--hlasm-optable', '--evidence'], documents: ['cobolwork', 'sarif'] },
   flow: { args: ['<path>'], options: ['--out', '--repos', '--quiet', '--full-trace', '--all-routes', '--baseline', '--no-baseline', '--copylib', '--evidence'], documents: ['cobolwork-flow'] },
   inventory: { args: ['<path>'], options: ['--out', '--quiet', '--copylib', '--evidence'], documents: ['cobolwork-inventory'] },
   parse: { args: ['<file>'], options: ['--out'], documents: ['cobolwork-parse'] },
   sbom: { args: ['<path>'], options: ['--name', '--out', '--quiet', '--copylib', '--evidence'], documents: ['cyclonedx'] },
-  diff: { args: ['<repo>'], options: ['--base', '--head', '--format', '--out', '--only', '--quiet', '--full-trace', '--copylib', '--evidence'], documents: ['cobolwork-diff', 'sarif'] },
+  diff: { args: ['<repo>'], options: ['--base', '--head', '--format', '--out', '--only', '--quiet', '--full-trace', '--copylib', '--pds-export', '--evidence'], documents: ['cobolwork-diff', 'sarif'] },
   baseline: { args: ['<path>'], options: ['--reason', '--who', '--expires', '--action', '--rule', '--out', '--repos', '--only', '--advisories', '--copylib', '--evidence'], documents: ['cobolwork-baseline'] },
   tui: { args: ['[path]'], options: ['--report', '--keys', '--baseline', '--no-baseline', '--advisories', '--copylib'], documents: [] },
   explain: { args: ['<path>', '<fingerprint>'], options: ['--report', '--out', '--baseline', '--no-baseline', '--advisories', '--copylib'], documents: ['cobolwork-explain'] },
   gate: { args: ['<repo>'], options: ['--base', '--head', '--target', '--cobc', '--exit-code', '--target-only', '--out', '--evidence'], documents: ['cobolwork-gate'] },
-  build: { args: ['<repo>', '[-- <compiler> <arg>...]'], options: ['--base', '--head', '--policy', '--provenance', '--provenance-format', '--artifact', '--equivalence', '--allowed-signers', '--ironwork', '--advisories', '--copylib', '--no-baseline', '--format', '--out', '--evidence'], documents: ['cobolwork-build', 'cobolwork-build-provenance', 'sarif'] },
-  evidence: { args: ['verify|seal|anchor|sign', '[statement]'], options: ['--evidence', '--ssh-key', '--signer', '--expect-key', '--allowed-signers', '--anchor-git', '--ref', '--push', '--max-unsealed', '--tsq', '--out', '--quiet'], documents: ['cobolwork-evidence'] },
+  build: { args: ['<repo>', '[-- <compiler> <arg>...]'], options: ['--base', '--head', '--policy', '--provenance', '--provenance-format', '--artifact', '--equivalence', '--allowed-signers', '--ironwork', '--precompile', '--advisories', '--copylib', '--pds-export', '--no-baseline', '--format', '--out', '--evidence'], documents: ['cobolwork-build', 'cobolwork-build-provenance', 'sarif'] },
+  evidence: { args: ['verify|seal|anchor|sign', '[statement]'], options: ['--evidence', '--ssh-key', '--signer', '--expect-key', '--allowed-signers', '--anchor-git', '--ref', '--anchor-pin', '--push', '--max-unsealed', '--tsq', '--tsr', '--tsa-ca', '--cosign-bundle', '--cosign-key', '--certificate-identity', '--certificate-oidc-issuer', '--trusted-root', '--insecure-ignore-tlog', '--out', '--quiet'], documents: ['cobolwork-evidence'] },
   capabilities: { args: [], options: ['--json'], documents: ['cobolwork-capabilities'] },
 };
 
@@ -43,7 +44,6 @@ export function capabilities() {
     toolRevision: toolRevision(),
     commands: COMMANDS,
     globalOptions: GLOBAL_OPTIONS,
-    // A document whose schemaVersion is null carries none yet; a reader should key on `tool`.
     documents: {
       cobolwork: SCHEMA_VERSION,
       'cobolwork-flow': SCHEMA_VERSION,
@@ -53,10 +53,10 @@ export function capabilities() {
       'cobolwork-build': BUILD_SCHEMA_VERSION,
       'cobolwork-build-provenance': BUILD_SCHEMA_VERSION,
       'cobolwork-capabilities': CAPABILITIES_SCHEMA_VERSION,
-      'cobolwork-explain': null,
-      'cobolwork-baseline': null,
-      'cobolwork-parse': null,
-      'cobolwork-evidence': null,
+      'cobolwork-explain': EXPLAIN_SCHEMA_VERSION,
+      'cobolwork-baseline': BASELINE_RESULT_SCHEMA_VERSION,
+      'cobolwork-parse': PARSE_SCHEMA_VERSION,
+      'cobolwork-evidence': EVIDENCE_RESULT_SCHEMA_VERSION,
       cyclonedx: '1.6',
       sarif: '2.1.0',
     },
@@ -68,7 +68,7 @@ export function capabilities() {
       jcl: JCL_EXT,
       bms: BMS_EXT,
       extensionless: 'sniffed by content: a file with no extension is classified by what it holds',
-      pdsExport: 'scan --pds-export: every member classified by content, whatever extension the download gave it; text, --binary and --record downloads',
+      pdsExport: 'scan --pds-export: every member classified by content, whatever extension the download gave it; text, --binary and --record downloads; XMIT files and IEBCOPY unloads of a PDS or a sequential data set',
       zowe: ['zowe.config.json', 'zowe.config.user.json', '.mcp.json', '.vscode/mcp.json', '.cursor/mcp.json', '.claude/settings.json', '.claude/settings.local.json', '.gemini/settings.json', 'claude_desktop_config.json', '.vscode/settings.json', 'systems.json under a mock directory'],
     },
     evidenceKinds: Object.keys(EVIDENCE),
@@ -81,5 +81,7 @@ export function capabilities() {
       exit: { ...BUILD_EXIT, couldNotRun: 2 },
     },
     gate: { exit: { ...VERDICT_EXIT, couldNotRun: 2 } },
+    // The ironwork releases cobolwork reads: from `minimum` on, each format from the release it names.
+    ironwork: { minimum: IRONWORK_MINIMUM, formats: IRONWORK_FORMATS, runEndings: RUN_ENDINGS, notRunAbends: NOT_RUN_ABENDS },
   };
 }