@portll/cobolwork 0.6.0 → 0.7.0

package/lib/ironwork.mjs

@@ -19,17 +19,20 @@ const REJECTED = new Set([8, 12, 16]);
 // errors in the program, whatever their wording says; the wording decides only at 12 and 16.
 const GRADED_ERROR = 8;
 // Warnings and informational lines follow the errors, and say nothing about why a program failed.
-const NOT_AN_ERROR = /^(?:informational:|.*?: warning: )/;
+// The label follows the position, or opens a line that has none.
+const NOT_AN_ERROR = /(?:^|: )(?:warning|informational): /;
+// ironwork opens a message with its id and severity, `IWC0101-S`, as IBM opens its own.
+const MESSAGE_ID = /^((?:IW[A-Z]|IGY[A-Z]{2})\d{4})-[IWESU] (.*)$/;
 const PER_PROGRAM_MS = 60000;
 const MAX_LISTED = 10;
 
-// ironwork refuses by name what it does not model yet; that says nothing about the program. A name
-// the CICS, DL/I or SQL translator declares it reports as undefined, without saying so, and that is
-// read as its gap, not the program's.
+// ironwork refuses by name what it does not model yet, with an IWR id; that says nothing about the
+// program. A name the CICS, DL/I or SQL translator declares it reports as undefined, without saying
+// so, and that is read as its gap, not the program's.
 const NOT_SUPPORTED = /\bnot supported\b/i;
 const TRANSLATOR_NAMES = [EIB_FIELDS, DIB_FIELDS, SQLCA_FIELDS];
-function notModelled(message) {
-  if (NOT_SUPPORTED.test(message)) return true;
+function notModelled({ id, message }) {
+  if (id?.startsWith('IWR') || NOT_SUPPORTED.test(message)) return true;
   const name = /^([A-Z][A-Z0-9-]*) is not defined$/.exec(message);
   return !!name && TRANSLATOR_NAMES.some((s) => s.has(name[1]));
 }
@@ -45,9 +48,10 @@ function diagnostic(line, programPath, rel) {
   if (!m) return { path: rel, message: printable(redact(line), 200) };
   const [file, ln, col, text] = m.length === 5 ? [m[1], Number(m[2]), Number(m[3]), m[4]] : [m[1], null, null, m[2]];
   const inProgram = resolve(file) === programPath;
+  const [, id, said] = MESSAGE_ID.exec(text) || [null, null, text];
   return {
-    path: rel, ...(ln ? { line: ln, col } : {}), ...(inProgram ? {} : { member: printable(file, 80) }),
-    message: printable(redact(text), 200),
+    path: rel, ...(ln ? { line: ln, col } : {}), ...(inProgram ? {} : { member: printable(file, 80) }), ...(id ? { id } : {}),
+    message: printable(redact(said), 200),
   };
 }
 
@@ -60,9 +64,9 @@ export function ironworkVersion(path, { env = process.env } = {}) {
 // estate's copy libraries as -I, and sorts the programs into those it accepts, those it rejects,
 // and those it could not decide: a construct it does not model, a copybook the tree lacks, or a
 // run that ended some other way.
-export function checkWithIronwork(path, root, { allow = null, copylibs = [], env = process.env } = {}) {
-  const programs = [...new Set(directoryTree(root).list())].filter((p) => isProgram(p) && (!allow || allow.has(p))).sort();
-  const libraries = [...buildFileIndex(root).copyDirs, ...copylibs].flatMap((d) => ['-I', d]);
+export function checkWithIronwork(path, root, { allow = null, programs: given = null, copyDirs = null, copylibs = [], env = process.env } = {}) {
+  const programs = given || [...new Set(directoryTree(root).list())].filter((p) => isProgram(p) && (!allow || allow.has(p))).sort();
+  const libraries = [...(copyDirs || buildFileIndex(root).copyDirs), ...copylibs].flatMap((d) => ['-I', d]);
   const out = { programs: programs.length, accepted: 0, warned: 0, failed: [], notModelled: [], unresolved: [], unrun: [] };
   for (const file of programs) {
     const rel = relPath(root, file);
@@ -76,7 +80,7 @@ export function checkWithIronwork(path, root, { allow = null, copylibs = [], env
       continue;
     }
     const found = String(r.stderr || '').split(/\r?\n/).filter((l) => l && !NOT_AN_ERROR.test(l)).map((l) => diagnostic(l, resolve(file), rel));
-    const errors = found.filter((d) => !(r.status !== GRADED_ERROR && notModelled(d.message)) && !UNRESOLVED.test(d.message));
+    const errors = found.filter((d) => !(r.status !== GRADED_ERROR && notModelled(d)) && !UNRESOLVED.test(d.message));
     if (errors.length) out.failed.push({ ...errors[0], errors: errors.length });
     else if (found.some((d) => UNRESOLVED.test(d.message))) out.unresolved.push(found.find((d) => UNRESOLVED.test(d.message)));
     else out.notModelled.push(found[0] || { path: rel, message: `ironwork exited ${r.status} and gave no error` });
@@ -93,7 +97,7 @@ export function ironworkVerdict(result) {
 
 export function ironworkReasons(result) {
   const reasons = [];
-  const at = (d) => `${d.path}${d.line ? `:${d.line}:${d.col}` : ''}${d.member ? ` (in ${d.member})` : ''}`;
+  const at = (d) => `${d.path}${d.line ? `:${d.line}:${d.col}` : ''}${d.member ? ` (in ${d.member})` : ''}${d.id ? ` ${d.id}` : ''}`;
   if (result.failed.length) {
     reasons.push(`ironwork check: ${result.failed.length} of ${result.programs} program(s) do not compile as Enterprise COBOL`);
     for (const d of result.failed.slice(0, MAX_LISTED)) reasons.push(`${at(d)}: ${d.message}`);

package/lib/kernel/pds-archive.mjs

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Data sets brought off z/OS whole: a TSO TRANSMIT (XMIT) file, and an IEBCOPY unload data set, alone
+// or inside one. Each partitioned data set's members come back as their records, in EBCDIC, ended by
+// NL (X'15'), as a z/OSMF record download gives them; a sequential data set comes back as one file.
+//
+// The layouts are IBM's: z/OS TSO/E Customization, "Format of transmitted data", "Control record
+// formats" and "Numeric values" (the text units); z/OS DFSMSdfp Utilities, "Unload partitioned data
+// set format" (COPYR1, COPYR2, directory and member data records); z/OS DFSMSdfp Advanced Services,
+// "Data Extent Block (DEB) Fields" and "Device Characteristics Information" (DEVTYPE), which turn a
+// member block's MBBCCHHR into the TTR its directory entry holds.
+import { ebcdicByte } from '../sources.mjs';
+
+const EOR = 0x15;
+const UNLOAD_ID = [0xca, 0x6d, 0x0f];
+const ebcdic = (s) => Buffer.from([...s].map((c) => ebcdicByte(c)));
+const INMR = (n) => ebcdic(`INMR0${n}`);
+
+const KEY = { INMDSNAM: 0x0002, INMDSORG: 0x003c, INMLRECL: 0x0042, INMRECFM: 0x0049, INMUTILN: 0x1028, INMNUMF: 0x102f };
+const DSORG_PO = 0x0200;
+
+const textOf = (buf) => [...buf].map((b) => EBCDIC_TEXT[b]).join('');
+const EBCDIC_TEXT = (() => {
+  const t = new Array(256).fill('?');
+  for (let c = 0x20; c < 0x7f; c++) {
+    const b = ebcdicByte(String.fromCharCode(c));
+    if (b !== null) t[b] = String.fromCharCode(c);
+  }
+  return t;
+})();
+const uint = (buf) => buf.reduce((n, b) => n * 256 + b, 0);
+const isUnloadId = (buf, at) => buf.length >= at + 3 && UNLOAD_ID.every((b, i) => buf[at + i] === b);
+
+// What a file holds, from its first bytes: an XMIT file's first segment is its INMR01 header record;
+// an unload's COPYR1 carries X'CA6D0F' after its flag byte, with a BDW and SDW, an RDW, or nothing
+// before it.
+export function archiveKind(head) {
+  if (head.length >= 8 && (head[1] & 0xa0) === 0xa0 && head.subarray(2, 8).equals(INMR(1))) return 'xmit';
+  for (const at of [1, 5, 9]) if (isUnloadId(head, at)) return 'unload';
+  return null;
+}
+
+// The transmission's logical records, each from its segments: a length byte counting itself and the
+// flag byte, the flags (X'80' first, X'40' last, X'20' control record) and up to 253 bytes.
+function xmitRecords(buf) {
+  const records = [];
+  let parts = null;
+  let control = false;
+  for (let at = 0; at < buf.length;) {
+    const n = buf[at];
+    if (n < 2 || at + n > buf.length) break;
+    const flags = buf[at + 1];
+    if (flags & 0x80) { parts = []; control = (flags & 0x20) !== 0; }
+    if (parts) parts.push(buf.subarray(at + 2, at + n));
+    if (flags & 0x40 && parts) {
+      const bytes = Buffer.concat(parts);
+      records.push({ control, bytes });
+      parts = null;
+      if (control && bytes.subarray(0, 6).equals(INMR(6))) break;
+    }
+    at += n;
+  }
+  return records;
+}
+
+// Text units from `at`: a key, a count, and that many length and data pairs.
+function textUnits(bytes, at) {
+  const units = new Map();
+  while (at + 4 <= bytes.length) {
+    const key = bytes.readUInt16BE(at);
+    const count = bytes.readUInt16BE(at + 2);
+    at += 4;
+    const fields = [];
+    for (let i = 0; i < count && at + 2 <= bytes.length; i++) {
+      const len = bytes.readUInt16BE(at);
+      fields.push(bytes.subarray(at + 2, at + 2 + len));
+      at += 2 + len;
+    }
+    units.set(key, fields);
+  }
+  return units;
+}
+
+function readXmit(buf) {
+  const records = xmitRecords(buf);
+  const last = records[records.length - 1];
+  if (!last?.control || !last.bytes.subarray(0, 6).equals(INMR(6))) return { why: 'the transmission ends before its INMR06 trailer' };
+  const header = textUnits(records[0].bytes, 6);
+  const files = header.get(KEY.INMNUMF)?.[0];
+  if (files && uint(files) > 1) return { why: `the transmission holds ${uint(files)} files, and cobolwork reads one` };
+  const utilities = records.filter((r) => r.control && r.bytes.subarray(0, 6).equals(INMR(2))).map((r) => textUnits(r.bytes, 10));
+  const named = utilities.find((u) => u.has(KEY.INMDSNAM));
+  const dataSet = named ? named.get(KEY.INMDSNAM).map(textOf).join('.') : null;
+  const start = records.findIndex((r) => r.control && r.bytes.subarray(0, 6).equals(INMR(3)));
+  if (start < 0) return { why: 'the transmission has no INMR03 data control record' };
+  const data = records.slice(start + 1, -1).filter((r) => !r.control).map((r) => r.bytes);
+  const unloaded = utilities.some((u) => textOf(u.get(KEY.INMUTILN)?.[0] || Buffer.alloc(0)) === 'IEBCOPY');
+  if (unloaded) return { ...readUnloadRecords(data), kind: 'xmit', dataSet };
+  const dsorg = utilities.map((u) => u.get(KEY.INMDSORG)?.[0]).find(Boolean);
+  if (dsorg && uint(dsorg) === DSORG_PO) return { why: 'a partitioned data set transmitted without IEBCOPY' };
+  return { kind: 'xmit', dataSet, sequential: true, members: [{ name: null, bytes: joined(data) }], aliases: [] };
+}
+
+// An unload stored with its descriptors: each block a BDW, then segments, each an SDW whose third
+// byte's low two bits say whether it is a whole record (0), its first (1), last (2) or middle (3)
+// part; or each record after an RDW; or the records with nothing between them, COPYR1 and COPYR2 at
+// their fixed lengths and everything after them one stream.
+function unloadRecords(buf) {
+  if (isUnloadId(buf, 9)) {
+    const records = [];
+    let parts = [];
+    for (let at = 0; at + 4 <= buf.length;) {
+      const end = at + buf.readUInt16BE(at);
+      if (end <= at || end > buf.length) break;
+      for (let s = at + 4; s + 4 <= end;) {
+        const len = buf.readUInt16BE(s);
+        if (len < 4) break;
+        const code = buf[s + 2] & 0x03;
+        parts.push(buf.subarray(s + 4, s + len));
+        if (code === 0 || code === 2) { records.push(Buffer.concat(parts)); parts = []; }
+        s += len;
+      }
+      at = end;
+    }
+    return records;
+  }
+  if (isUnloadId(buf, 5)) {
+    const records = [];
+    for (let at = 0; at + 4 <= buf.length;) {
+      const len = buf.readUInt16BE(at);
+      if (len < 4 || at + len > buf.length) break;
+      records.push(buf.subarray(at + 4, at + len));
+      at += len;
+    }
+    return records;
+  }
+  return [buf.subarray(0, COPYR1_LENGTH), buf.subarray(COPYR1_LENGTH, COPYR1_LENGTH + COPYR2_LENGTH), buf.subarray(COPYR1_LENGTH + COPYR2_LENGTH)];
+}
+
+const COPYR1_LENGTH = 56;
+const COPYR2_LENGTH = 276;
+const DIRECTORY_BLOCK = 276;
+const BLOCK_HEADER = 12;
+
+export function readArchive(buf) {
+  const kind = archiveKind(buf.subarray(0, 16));
+  if (kind === 'xmit') return readXmit(buf);
+  if (kind === 'unload') return { ...readUnloadRecords(unloadRecords(buf)), kind: 'unload', dataSet: null };
+  return { why: 'neither an XMIT file nor an IEBCOPY unload' };
+}
+
+// COPYR1 and COPYR2, then the directory blocks and every member's blocks, which run on across
+// records: a directory block is a 12-byte count, the 8-byte key and 256 bytes of entries, and the
+// directory ends with 12 bytes of zeros; a member's blocks are each a flag byte, MBB, CCHHR, key
+// length, data length, key and data, and its last is one with no key and no data.
+function readUnloadRecords(records) {
+  const [r1, r2] = records;
+  if (!r1 || !isUnloadId(r1, 1)) return { why: 'the unload has no COPYR1 record' };
+  const format = r1[0] >> 6;
+  if (format === 2) return { why: 'IEBCOPY marked the unload incomplete or in error' };
+  if (format !== 0 || r1[0] & 0x01) return { why: 'a PDSE unload, whose attribute records cobolwork does not read yet' };
+  const headers = r1.length >= 38 ? r1.readUInt16BE(36) || 2 : 2;
+  if (headers !== 2) return { why: `the unload has ${headers} header records, and cobolwork reads two` };
+  if (!r2 || r2.length < 16 + 16) return { why: 'the unload has no COPYR2 record' };
+  const lrecl = r1.readUInt16BE(8);
+  const recfm = r1[10] >> 6;
+  const tracksPerCylinder = r1.readUInt16BE(26);
+  const extents = [];
+  for (let at = 16; at + 16 <= r2.length && extents.length < 16; at += 16) {
+    extents.push({ cyl: cylinder(r2.readUInt16BE(at + 6), r2.readUInt16BE(at + 8)), trk: r2.readUInt16BE(at + 8) & 0x0f, tracks: r2[at + 5] * 0x10000 + r2.readUInt16BE(at + 14) });
+  }
+  const stream = Buffer.concat(records.slice(2));
+  let at = 0;
+  const entries = [];
+  for (;;) {
+    if (at + BLOCK_HEADER > stream.length) return { why: 'the directory runs past the end of the unload' };
+    if (stream.subarray(at, at + BLOCK_HEADER).every((b) => b === 0)) { at += BLOCK_HEADER; break; }
+    const block = stream.subarray(at + BLOCK_HEADER + 8, at + DIRECTORY_BLOCK);
+    const used = Math.min(block.readUInt16BE(0), block.length);
+    for (let e = 2; e + 12 <= used;) {
+      const name = block.subarray(e, e + 8);
+      if (name.every((b) => b === 0xff)) break;
+      const c = block[e + 11];
+      entries.push({ name: textOf(name).trimEnd(), ttr: uint(block.subarray(e + 8, e + 11)), alias: (c & 0x80) !== 0 });
+      e += 12 + (c & 0x1f) * 2;
+    }
+    at += DIRECTORY_BLOCK;
+  }
+  const byTtr = new Map(entries.filter((e) => !e.alias).map((e) => [e.ttr, e.name]));
+  const members = [];
+  let unmatched = 0;
+  while (at + BLOCK_HEADER <= stream.length) {
+    let ttr = null;
+    const blocks = [];
+    for (;;) {
+      if (at + BLOCK_HEADER > stream.length) return { why: 'a member runs past the end of the unload' };
+      const h = stream.subarray(at, at + BLOCK_HEADER);
+      const keyLength = h[9];
+      const dataLength = h.readUInt16BE(10);
+      at += BLOCK_HEADER;
+      if (keyLength === 0 && dataLength === 0) break;
+      if (ttr === null) ttr = relativeTrack(extents, tracksPerCylinder, h) * 256 + h[8];
+      blocks.push(stream.subarray(at + keyLength, at + keyLength + dataLength));
+      at += keyLength + dataLength;
+    }
+    if (!blocks.length) continue;
+    const name = byTtr.get(ttr);
+    if (name === undefined) { unmatched++; continue; }
+    members.push({ name, bytes: joined(blocks.flatMap((b) => recordsOf(b, recfm, lrecl))) });
+  }
+  const held = new Set(members.map((m) => m.name));
+  return {
+    members,
+    aliases: entries.filter((e) => e.alias).map((e) => e.name),
+    ...(unmatched ? { unmatched } : {}),
+    ...(entries.some((e) => !e.alias && !held.has(e.name)) ? { missing: entries.filter((e) => !e.alias && !held.has(e.name)).map((e) => e.name) } : {}),
+  };
+}
+
+// A cylinder number from CC and HH, whose high 12 bits hold the cylinder's high bits on an extended
+// address volume (DEBSTRHH).
+const cylinder = (cc, hh) => (hh >> 4) * 0x10000 + cc;
+
+// The track's number from the start of the data set: the tracks of the extents before extent M, then
+// the cylinders and tracks into M.
+function relativeTrack(extents, tracksPerCylinder, h) {
+  const m = h[1];
+  const e = extents[m];
+  if (!e) return -1;
+  const before = extents.slice(0, m).reduce((n, x) => n + x.tracks, 0);
+  const hh = h.readUInt16BE(6);
+  return before + (cylinder(h.readUInt16BE(4), hh) - e.cyl) * tracksPerCylinder + ((hh & 0x0f) - e.trk);
+}
+
+// A physical block's records: fixed-length records LRECL at a time, variable ones after the BDW each
+// by its RDW, an undefined block as one record. RECFM's first two bits: 10 fixed, 01 variable, 11
+// undefined.
+function recordsOf(block, recfm, lrecl) {
+  if (recfm === 2 && lrecl > 0) {
+    const out = [];
+    for (let i = 0; i + lrecl <= block.length; i += lrecl) out.push(block.subarray(i, i + lrecl));
+    return out;
+  }
+  if (recfm === 1) {
+    const out = [];
+    for (let i = 4; i + 4 <= block.length;) {
+      const len = block.readUInt16BE(i);
+      if (len < 4) break;
+      out.push(block.subarray(i + 4, i + len));
+      i += len;
+    }
+    return out;
+  }
+  return [block];
+}
+
+const joined = (records) => Buffer.concat(records.flatMap((r) => [r, Buffer.from([EOR])]));

package/lib/kernel/registry.mjs

@@ -14,11 +14,11 @@
 // map it guarded is gone, because a name derived from one place cannot disagree with itself.
 import { scan as scanFlow, scanSteps as scanFlowSteps, RULES as FLOW_RULES } from '../sets/flow.mjs';
 import { scanCics, scanCicsSteps, CICS_RULES } from '../sets/cics.mjs';
-import { scanHidden, HIDDEN_RULES } from '../sets/hidden.mjs';
+import { scanHidden, scanHiddenSteps, HIDDEN_RULES } from '../sets/hidden.mjs';
 import { scanCopybooks, scanCopybooksSteps, COPYBOOK_RULES } from '../sets/copybook.mjs';
 import { scanJcl, JCL_RULES } from '../sets/jcl.mjs';
 import { scanBuild, BUILD_RULES } from '../sets/build.mjs';
-import { scanRecon, RECON_RULES } from '../sets/recon.mjs';
+import { scanRecon, scanReconSteps, RECON_RULES } from '../sets/recon.mjs';
 import { scanVendor, VENDOR_RULES } from '../sets/vendor.mjs';
 import { scanOpaque, OPAQUE_RULES } from '../sets/opaque.mjs';
 import { scanWeb, scanWebSteps, WEB_RULES } from '../sets/web.mjs';
@@ -29,8 +29,11 @@ import { scanSemantics, scanSemanticsSteps, SEMANTICS_RULES } from '../sets/sema
 import { scanZowe, ZOWE_RULES } from '../sets/zowe.mjs';
 import { scanAbend, ABEND_RULES } from '../sets/abend.mjs';
 import { scanHlasm, HLASM_RULES } from '../sets/hlasm.mjs';
-import { scanCrypto, CRYPTO_RULES } from '../sets/crypto.mjs';
-import { scanSecrets, SECRETS_RULES } from '../sets/secrets.mjs';
+import { scanIms, IMS_RULES } from '../sets/ims.mjs';
+import { scanDb2, DB2_RULES } from '../sets/ddl.mjs';
+import { scanPli, PLI_RULES } from '../sets/pli.mjs';
+import { scanCrypto, scanCryptoSteps, CRYPTO_RULES } from '../sets/crypto.mjs';
+import { scanSecrets, scanSecretsSteps, SECRETS_RULES } from '../sets/secrets.mjs';
 import { toolName } from './ruleset.mjs';
 
 // The order is the order a scan runs them and the order --only lists them. It is not significant
@@ -39,11 +42,11 @@ import { toolName } from './ruleset.mjs';
 export const REGISTRY = [
   { name: 'flow', scan: scanFlow, steps: scanFlowSteps, rules: FLOW_RULES },
   { name: 'cics', scan: scanCics, steps: scanCicsSteps, rules: CICS_RULES },
-  { name: 'hidden', scan: scanHidden, rules: HIDDEN_RULES },
+  { name: 'hidden', scan: scanHidden, steps: scanHiddenSteps, rules: HIDDEN_RULES },
   { name: 'copybook', scan: scanCopybooks, steps: scanCopybooksSteps, rules: COPYBOOK_RULES },
   { name: 'jcl', scan: scanJcl, rules: JCL_RULES },
   { name: 'build', scan: scanBuild, rules: BUILD_RULES },
-  { name: 'recon', scan: scanRecon, rules: RECON_RULES },
+  { name: 'recon', scan: scanRecon, steps: scanReconSteps, rules: RECON_RULES },
   { name: 'vendor', scan: scanVendor, rules: VENDOR_RULES },
   { name: 'opaque', scan: scanOpaque, rules: OPAQUE_RULES },
   { name: 'web', scan: scanWeb, steps: scanWebSteps, rules: WEB_RULES },
@@ -54,8 +57,11 @@ export const REGISTRY = [
   { name: 'zowe', scan: scanZowe, rules: ZOWE_RULES },
   { name: 'abend', scan: scanAbend, rules: ABEND_RULES },
   { name: 'hlasm', scan: scanHlasm, rules: HLASM_RULES },
-  { name: 'crypto', scan: scanCrypto, rules: CRYPTO_RULES },
-  { name: 'secrets', scan: scanSecrets, rules: SECRETS_RULES },
+  { name: 'ims', scan: scanIms, rules: IMS_RULES },
+  { name: 'ddl', scan: scanDb2, rules: DB2_RULES },
+  { name: 'pli', scan: scanPli, rules: PLI_RULES },
+  { name: 'crypto', scan: scanCrypto, steps: scanCryptoSteps, rules: CRYPTO_RULES },
+  { name: 'secrets', scan: scanSecrets, steps: scanSecretsSteps, rules: SECRETS_RULES },
 ];
 
 // Re-exported from the kernel's ruleset module, which is where it has to live: this file imports

package/lib/kernel/shared-pass.mjs

@@ -14,11 +14,18 @@
 import { eachWithinMemory, memoryStatus, stoppedBecause, watchMemoryBuffer, MEMORY_RESERVE } from './memory.mjs';
 
 const LOOP = Symbol('loop');
+const LOOPS = Symbol('loops');
 
 // What a set yields in place of `eachWithinMemory(items, work, opts)`. `guarded: false` asks for a
 // plain loop: every item, no memory check and no byte budget.
 export const loopOver = (items, work, opts = {}) => ({ [LOOP]: true, items, work, opts });
 
+// Several loops of one set walked in the same pass, each with its own account, the set resumed with
+// their accounts in the order given. A file both loops hold goes to the first, then the second.
+export const loopsOver = (...loops) => ({ [LOOPS]: true, loops });
+const loopsOf = (value) => (value[LOOPS] ? value.loops : [value]);
+const resumeWith = (value, runs) => (value[LOOPS] ? runs : runs[0]);
+
 function plainLoop(items, work, label) {
   for (let i = 0; i < items.length; i++) work(items[i], i);
   return { label, processed: items.length, bytes: 0, skipped: [], complete: true, stoppedBy: null, peakHeapBytes: 0, note: null };
@@ -30,24 +37,38 @@ const runAlone = (req) => (req.opts.guarded === false
 
 export function drive(steps) {
   let step = steps.next();
-  while (!step.done) step = steps.next(runAlone(step.value));
+  while (!step.done) step = steps.next(resumeWith(step.value, loopsOf(step.value).map(runAlone)));
   return step.value;
 }
 
-// A tree that, while `focus` names a file, answers text() and parse() for that file once and hands
-// every later caller the same answer, its error included.
+// A tree that, while `focus` names a file, answers bytes(), text() and parse() for that file once and
+// hands every later caller the same answer, its error included. A tree whose text is its bytes
+// through `decode` has the file read once for both.
 export function sharingTree(base) {
   let focus = null;
+  let bytes = null;
   let text = null;
   let parsed = null;
+  const once = (held, read) => {
+    if (!held) { try { held = { value: read() }; } catch (e) { held = { error: e }; } }
+    return held;
+  };
+  const answer = (held) => {
+    if (held.error) throw held.error;
+    return held.value;
+  };
   const tree = {
     ...base,
-    focusOn(f) { focus = f; text = null; parsed = null; },
+    focusOn(f) { focus = f; bytes = null; text = null; parsed = null; },
+    bytes(p) {
+      if (p !== focus) return base.bytes(p);
+      bytes = once(bytes, () => base.bytes(p));
+      return answer(bytes);
+    },
     text(p) {
       if (p !== focus) return base.text(p);
-      if (!text) { try { text = { value: base.text(p) }; } catch (e) { text = { error: e }; } }
-      if (text.error) throw text.error;
-      return text.value;
+      text = once(text, () => (base.decode ? base.decode(tree.bytes(p)) : base.text(p)));
+      return answer(text);
     },
     parse(p, src) {
       if (p !== focus) return base.parse(p, src);
@@ -75,8 +96,12 @@ export function driveTogether(stepsList, tree) {
   for (;;) {
     const waiting = live.filter((g) => !g.step.done);
     if (!waiting.length) break;
-    const runs = mergedLoop(waiting.map((g) => g.step.value), tree);
-    waiting.forEach((g, k) => advance(g, runs[k].run, runs[k].error));
+    const runs = mergedLoop(waiting.flatMap((g) => loopsOf(g.step.value)), tree);
+    let at = 0;
+    for (const g of waiting) {
+      const own = runs.slice(at, at += loopsOf(g.step.value).length);
+      advance(g, resumeWith(g.step.value, own.map((r) => r.run)), own.find((r) => r.error)?.error);
+    }
   }
   return live.map((g) => (g.error ? { error: g.error } : g.result));
 }