@portll/cobolwork 0.0.1 → 0.2.75

package/lib/sources.mjs

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { readFileSync, openSync, readSync, closeSync } from 'node:fs';
+import { extname, relative, sep } from 'node:path';
+
+// One definition of what each kind of file is, used by every rule set. They disagreed: the flow
+// and CICS rules skipped .sqb and .pco (embedded SQL, where the SQL rules matter most), and the
+// resolver could not find a .copy or .inc copybook that the inventory counted.
+// A path in a report is POSIX-shaped on every platform. A report is stored, diffed and compared
+// against git output, which uses forward slashes, so a native separator would make one file read
+// as two. On a platform whose separator already is '/', this is the identity.
+export const relPath = (root, p) => relative(root, p).split(sep).join('/');
+
+export const PROGRAM_EXT = ['.cbl', '.cob', '.cobol', '.sqb', '.pco'];
+export const COPY_EXT = ['.cpy', '.copy', '.inc'];
+export const JCL_EXT = ['.jcl', '.job', '.proc', '.prc', '.cntl'];
+export const BMS_EXT = ['.bms'];
+
+const has = (list) => (p) => list.includes(extname(p).toLowerCase());
+
+// A member of a partitioned data set has no extension. That is not an edge case - it is what a
+// real estate looks like, because the mainframe has no such thing as a file extension, and an
+// estate exported from a PDS arrives as bare names. Reading by extension alone means opening none
+// of it and reporting a clean zero, which is the failure this project exists to refuse.
+//
+// So a file with no extension is classified by what is in it. Only the first few kilobytes are
+// read, only files without an extension are sniffed, and the answer is cached: this runs over
+// every file in the tree and must not cost a parse.
+const SNIFF_BYTES = 4096;
+const sniffed = new Map();
+
+// Names that are certainly not source, so the commonest extensionless files cost nothing.
+const NOT_SOURCE = /^(LICEN[CS]E|README|MAKEFILE|DOCKERFILE|CHANGELOG|NOTICE|AUTHORS|CONTRIBUTING|CODEOWNERS|VERSION|COPYING|Jenkinsfile|Procfile|\..*)$/i;
+
+export function sniffKind(path) {
+  if (sniffed.has(path)) return sniffed.get(path);
+  let kind = null;
+  const name = path.split(/[\\/]/).pop();
+  if (!NOT_SOURCE.test(name)) {
+    try {
+      const fd = openSync(path, 'r');
+      const buf = Buffer.alloc(SNIFF_BYTES);
+      let n;
+      try { n = readSync(fd, buf, 0, SNIFF_BYTES, 0); } finally { closeSync(fd); }
+      const head = buf.subarray(0, n);
+      // An EBCDIC member is decoded before it is read, or every test below sees mojibake.
+      const text = looksEbcdic(head) ? decodeEbcdic(head) : head.toString('latin1');
+      // A NUL byte means binary. Tested on the bytes rather than with a literal, because a literal
+      // NUL in source is exactly the character an editor or a patch is most likely to eat.
+      if (head.includes(0)) kind = null;
+      else if (/^\s*\/\/\S*\s+(?:JOB|EXEC|PROC|DD)\b/m.test(text)) kind = 'jcl';
+      else if (/\bIDENTIFICATION\s+DIVISION|\bPROGRAM-ID\s*\./i.test(text)) kind = 'program';
+      // A copybook is a data description with no divisions: level numbers and picture clauses.
+      else if (/^[^*\n]{0,10}\s*\d\d\s+[A-Z][A-Z0-9-]*\s+(?:PIC|PICTURE|OCCURS|REDEFINES|USAGE)\b/im.test(text)) kind = 'copybook';
+      // A BMS map opens its mapset with DFHMSD in the operation field. Tested last, so nothing that
+      // classified before classifies differently.
+      else if (/^[^*\s]*[ \t]+DFHMSD(?=\s|$)/im.test(text)) kind = 'bms';
+    } catch { kind = null; }
+  }
+  sniffed.set(path, kind);
+  return kind;
+}
+
+// Extension first, because it is free and it is right whenever it is present.
+const byExtOrContent = (list, kind) => (p) => (extname(p) ? list.includes(extname(p).toLowerCase()) : sniffKind(p) === kind);
+
+export const isProgram = byExtOrContent(PROGRAM_EXT, 'program');
+export const isCopybook = byExtOrContent(COPY_EXT, 'copybook');
+export const isJcl = byExtOrContent(JCL_EXT, 'jcl');
+export const isBms = byExtOrContent(BMS_EXT, 'bms');
+// Not BMS, by either route: the sets that read every source file have not chosen to read maps.
+export const isSource = (p) => (extname(p)
+  ? [...PROGRAM_EXT, ...COPY_EXT, ...JCL_EXT].includes(extname(p).toLowerCase())
+  : ![null, 'bms'].includes(sniffKind(p)));
+
+// For a report that wants to say how much of what it read had no extension to go on.
+export const sniffedCount = () => {
+  let n = 0;
+  for (const v of sniffed.values()) if (v) n++;
+  return n;
+};
+
+// `opts.only` is about rule sets; this is about files. A rule set given an allow list reads the
+// files on it and no others.
+//
+// `deny` is the other direction, and it exists for measurement rather than for scanning. A corpus
+// run over public COBOL is dominated by files that are not code anybody runs: a repository holding
+// the NIST conformance suite fires SET ADDRESS OF thousands of times because exercising every
+// construct exhaustively is what those files are for. Counting them tells you about conformance
+// suites, not about COBOL. Substrings are matched against the POSIX-shaped path, so 'tests/' and
+// '/fixtures/' read the way someone would write them.
+//
+// It is off unless asked for. A scan of a real estate should read the test code too - test JCL
+// carries real credentials as often as anything else does.
+export const inScope = (opts = {}) => {
+  const allow = opts.allow ? (p) => opts.allow.has(p) : () => true;
+  if (!opts.deny || !opts.deny.length) return allow;
+  const deny = opts.deny.map((d) => d.replace(/\\/g, '/').toLowerCase());
+  return (p) => {
+    if (!allow(p)) return false;
+    const norm = String(p).replace(/\\/g, '/').toLowerCase();
+    return !deny.some((d) => norm.includes(d));
+  };
+};
+
+// IBM code page 037, the printable range. Positions outside it decode to U+FFFD so an unknown byte
+// is visible as unknown rather than guessed at. 037 and 1047 differ only in brackets, caret and
+// not-sign, none of which COBOL needs; both bracket positions are mapped so either reads.
+const E2A = (() => {
+  const t = new Array(256).fill('�');
+  const set = (at, chars) => { for (let i = 0; i < chars.length; i++) t[at + i] = chars[i]; };
+  t[0x05] = '\t'; t[0x0D] = '\r'; t[0x15] = '\n'; t[0x25] = '\n'; t[0x40] = ' ';
+  set(0x4A, '¢.<(+|&'); set(0x5A, '!$*);¬-/');
+  set(0x6A, '¦,%_>?'); set(0x79, '`:#@\'="');
+  set(0x81, 'abcdefghi'); set(0x91, 'jklmnopqr'); set(0xA1, '~stuvwxyz');
+  set(0xC0, '{ABCDEFGHI'); set(0xD0, '}JKLMNOPQR'); set(0xE0, '\\'); set(0xE2, 'STUVWXYZ');
+  set(0xF0, '0123456789');
+  t[0xAD] = '['; t[0xBA] = '['; t[0xBD] = ']'; t[0xBB] = ']'; t[0x5F] = '¬'; t[0xB0] = '^';
+  return t;
+})();
+
+const ASCII_ALNUM = (b) => (b >= 0x30 && b <= 0x39) || (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A);
+const EBCDIC_ALNUM = (b) => (b >= 0x81 && b <= 0xA9) || (b >= 0xC1 && b <= 0xE9) || (b >= 0xF0 && b <= 0xF9);
+
+// EBCDIC source has a space at 0x40 and letters above 0x80; ASCII has almost none of either. A NUL
+// byte means binary, which is neither.
+export function looksEbcdic(buf) {
+  const n = Math.min(buf.length, 8192);
+  if (n < 16) return false;
+  let eb = 0; let as = 0;
+  for (let i = 0; i < n; i++) {
+    const b = buf[i];
+    if (b === 0) return false;
+    if (b === 0x40 || EBCDIC_ALNUM(b)) eb++;
+    if (b === 0x20 || ASCII_ALNUM(b)) as++;
+  }
+  return eb / n > 0.6 && as / n < 0.25;
+}
+
+export function decodeEbcdic(buf) {
+  let hasNewline = false;
+  for (let i = 0; i < buf.length; i++) if (buf[i] === 0x15 || buf[i] === 0x25) { hasNewline = true; break; }
+  const chars = new Array(buf.length);
+  for (let i = 0; i < buf.length; i++) chars[i] = E2A[buf[i]];
+  const text = chars.join('');
+  // A member copied off the mainframe in binary keeps its fixed 80-byte records and no line ends.
+  if (!hasNewline && buf.length % 80 === 0) return text.match(/[\s\S]{80}/g).join('\n');
+  return text;
+}
+
+// Every rule set reads source through here, so an EBCDIC member is decoded once, the same way,
+// and reported as EBCDIC instead of silently parsing as noise.
+export function readSource(path) {
+  const buf = readFileSync(path);
+  if (looksEbcdic(buf)) return { text: decodeEbcdic(buf), encoding: 'ebcdic' };
+  return { text: buf.toString('latin1'), encoding: 'latin1' };
+}

package/lib/tui/app.mjs

@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { createScreen, put, styleRow } from './screen.mjs';
+import { ACTIONS, KEYMAPS, LEGEND, actionFor } from './keys.mjs';
+import { EVIDENCE } from '../kernel/findings.mjs';
+import {
+  banner, countsLine, rows as findingRows, viewLabel, DEFAULT_VIEW, SORT_NAMES, EVIDENCE_KINDS, WHO_ACTS, SEV_LETTER,
+} from './model.mjs';
+
+export const PANELS = Object.freeze(['home', 'findings', 'finding', 'help']);
+export const MIN_COLS = 80;
+export const MIN_ROWS = 24;
+
+export function initialState({ report, keymap = 'ispf', cols = MIN_COLS, rows = MIN_ROWS }) {
+  return {
+    report, keymap: KEYMAPS[keymap] ? keymap : 'ispf', cols, rows,
+    stack: [{ panel: 'home' }], view: { ...DEFAULT_VIEW }, sel: 0, top: 0,
+    cmd: '', cmdOpen: false, message: '',
+  };
+}
+
+const current = (s) => s.stack[s.stack.length - 1];
+const done = (state, effects = []) => ({ state, effects });
+const replaceTop = (s, entry) => ({ ...s, stack: [...s.stack.slice(0, -1), entry] });
+
+export function update(state, event) {
+  if (event.type === 'resize') return done({ ...state, cols: event.cols, rows: event.rows });
+  if (event.type !== 'key') return done(state);
+  const t = event.token;
+  const s = { ...state, message: '' };
+  // Typing edits the command line: always under ISPF, under modern only after ':' or '/'.
+  if (s.keymap === 'ispf' || s.cmdOpen) {
+    if (t.startsWith('char:')) return done({ ...s, cmd: s.cmd + t.slice(5) });
+    if (t === 'Backspace') return done({ ...s, cmd: s.cmd.slice(0, -1) });
+    if (t === 'Enter' && s.cmd.trim()) return command({ ...s, cmd: '', cmdOpen: false }, s.cmd.trim());
+    if ((t === 'Escape' || t === 'Enter') && s.cmdOpen) return done({ ...s, cmd: '', cmdOpen: false });
+  }
+  const action = actionFor(s.keymap, t);
+  return action ? act(s, action, t) : done(s);
+}
+
+function act(s, action, token) {
+  switch (action) {
+    case 'quit': return done(s, [{ type: 'quit' }]);
+    case 'end': return end(s);
+    case 'help': return help(s);
+    case 'command': return done({ ...s, cmdOpen: true, cmd: token === 'char:/' ? 'FIND ' : s.cmd });
+    case 'open': return open(s);
+    default: return move(s, action);
+  }
+}
+
+function end(s) {
+  if (s.stack.length === 1) return done(s, [{ type: 'quit' }]);
+  return done({ ...s, stack: s.stack.slice(0, -1) });
+}
+
+function help(s) {
+  const t = current(s);
+  if (t.panel === 'help') return done(replaceTop(s, { ...t, keys: !t.keys, scroll: 0 }));
+  return done({ ...s, stack: [...s.stack, { panel: 'help', of: t.panel, keys: false, scroll: 0 }] });
+}
+
+function open(s) {
+  const t = current(s);
+  if (t.panel === 'home') return done({ ...s, stack: [...s.stack, { panel: 'findings' }] });
+  if (t.panel === 'findings') {
+    const list = findingRows(s.report, s.view);
+    if (!list.length) return done({ ...s, message: 'There is no finding to open in this view.' });
+    return done({ ...s, stack: [...s.stack, { panel: 'finding', f: list[s.sel].f, scroll: 0 }] });
+  }
+  return done(s);
+}
+
+function move(s, action) {
+  const t = current(s);
+  if (t.panel === 'findings') {
+    const n = findingRows(s.report, s.view).length;
+    const page = Math.max(1, findingsLayout(s).height);
+    const to = { up: s.sel - 1, down: s.sel + 1, pageUp: s.sel - page, pageDown: s.sel + page, top: 0, bottom: n - 1 }[action];
+    const sel = Math.max(0, Math.min(n - 1, to ?? s.sel));
+    let top = s.top;
+    if (action === 'pageDown' || action === 'pageUp') top = Math.max(0, Math.min(Math.max(0, n - page), s.top + (to - s.sel)));
+    if (sel < top) top = sel;
+    if (sel >= top + page) top = sel - page + 1;
+    return done({ ...s, sel: Math.max(0, sel), top: Math.max(0, top) });
+  }
+  if (t.panel === 'finding' || t.panel === 'help') {
+    const page = Math.max(1, s.rows - 4);
+    const delta = { up: -1, down: 1, pageUp: -page, pageDown: page, top: -Infinity, bottom: Infinity }[action] || 0;
+    const max = Math.max(0, bodyLines(s, t).length - page);
+    return done(replaceTop(s, { ...t, scroll: Math.max(0, Math.min(max, (t.scroll || 0) + delta)) }));
+  }
+  return done(s);
+}
+
+const SORT_WORDS = { SEV: 'severity', SEVERITY: 'severity', RULE: 'rule', PROGRAM: 'program', PGM: 'program', WHERE: 'where', FILE: 'where', PATH: 'where', EVIDENCE: 'evidence', EVID: 'evidence' };
+
+function command(s, text) {
+  const [word, ...rest] = text.split(/\s+/);
+  const verb = word.toUpperCase();
+  const arg = rest.join(' ');
+  const fresh = (view) => done({ ...s, view, sel: 0, top: 0 });
+  switch (verb) {
+    case 'HELP': return help(s);
+    case 'END': return end(s);
+    case '=X': case 'EXIT': case 'QUIT': return done(s, [{ type: 'quit' }]);
+    case '1': case 'FINDINGS': {
+      const at = s.stack.findIndex((t) => t.panel === 'findings');
+      return done({ ...s, stack: at < 0 ? [...s.stack, { panel: 'findings' }] : s.stack.slice(0, at + 1) });
+    }
+    case 'TOP': return move(s, 'top');
+    case 'BOTTOM': return move(s, 'bottom');
+    case 'RESET': return fresh({ ...DEFAULT_VIEW });
+    case 'SORT': {
+      const key = SORT_WORDS[arg.toUpperCase()];
+      return key ? fresh({ ...s.view, sort: key }) : done({ ...s, message: `SORT takes ${SORT_NAMES.join(', ')}.` });
+    }
+    case 'FILTER': {
+      if (/^off$/i.test(arg)) return fresh({ ...s.view, evidence: null });
+      const kinds = arg.toLowerCase().split(/[,\s]+/).filter(Boolean);
+      const bad = kinds.filter((k) => !EVIDENCE_KINDS.includes(k));
+      if (!kinds.length || bad.length) return done({ ...s, message: `FILTER takes ${EVIDENCE_KINDS.join(', ')} or OFF${bad.length ? `; not ${bad.join(', ')}` : ''}.` });
+      return fresh({ ...s.view, evidence: kinds });
+    }
+    case 'FIND':
+      return arg ? fresh({ ...s.view, find: arg }) : done({ ...s, message: 'FIND needs the text to look for.' });
+    case 'KEYS': {
+      const k = arg.toLowerCase();
+      return KEYMAPS[k] ? done({ ...s, keymap: k, message: `Keys are now ${k}.` }) : done({ ...s, message: `KEYS takes ${Object.keys(KEYMAPS).join(' or ')}.` });
+    }
+    default:
+      return done({ ...s, message: `Command "${word}" not recognised. F1 lists the commands.` });
+  }
+}
+
+export function view(state) {
+  const { cols, rows } = state;
+  const scr = createScreen(cols, rows);
+  if (cols < MIN_COLS || rows < MIN_ROWS) {
+    put(scr, 0, 1, 'cobolwork needs a terminal of at least 80x24;', 'warn');
+    put(scr, 1, 1, `this one is ${cols}x${rows}. Enlarge it, or press Ctrl-C to leave.`);
+    return scr;
+  }
+  const t = current(state);
+  const drawn = DRAW[t.panel](scr, state, t);
+  put(scr, 0, 0, ` COBOLWORK  ${drawn.title}`, 'title');
+  if (drawn.right) put(scr, 0, cols - drawn.right.length - 1, drawn.right, 'title');
+  styleRow(scr, 0, 'title');
+  put(scr, 1, 0, ` Command ===> ${state.cmd}${state.cmdOpen ? '_' : ''}`);
+  if (state.keymap === 'ispf') put(scr, 1, cols - 17, 'Scroll ===> PAGE');
+  if (state.message) put(scr, rows - 2, 0, ` ${state.message}`, 'hi');
+  else if (drawn.hint) put(scr, rows - 2, 0, ` ${drawn.hint}`, 'dim');
+  put(scr, rows - 1, 0, LEGEND[state.keymap], 'dim');
+  return scr;
+}
+
+function drawBanner(scr, report, row, max) {
+  const b = banner(report);
+  let shown = b.lines;
+  if (shown.length > max) shown = [...b.lines.slice(0, max - 1), `... and ${b.lines.length - max + 1} more: Home lists every one`];
+  shown.forEach((line, i) => {
+    const text = i > 0 ? `   ${line}` : b.complete ? ` ${line}` : ` ! ${line}`;
+    put(scr, row + i, 0, text, b.complete ? 'dim' : 'warn');
+  });
+  return row + shown.length;
+}
+
+function findingsLayout(s) {
+  const b = banner(s.report);
+  const bannerLines = Math.min(b.lines.length, 4);
+  const listTop = 2 + bannerLines + 2;
+  return { bannerLines, listTop, height: s.rows - 2 - listTop };
+}
+
+const pad = (text, width) => {
+  const str = String(text ?? '');
+  return str.length > width ? str.slice(0, width - 1) + '>' : str.padEnd(width);
+};
+
+const DRAW = {
+  home(scr, s) {
+    const r0 = drawBanner(scr, s.report, 2, s.rows - 12);
+    const sum = s.report.summary;
+    const accepted = sum.baseline && sum.baseline.suppressed ? `, and ${sum.baseline.suppressed} accepted by a baseline` : '';
+    let r = r0 + 1;
+    put(scr, r++, 1, `Findings  ${sum.findings ?? s.report.findings.length}${accepted}`);
+    put(scr, r++, 1, countsLine(s.report));
+    const kinds = [['programs', sum.programFiles], ['copybooks', sum.copybookFiles], ['JCL', sum.jclFiles]].filter(([, n]) => n != null);
+    put(scr, r++, 1, `Read      ${sum.filesScanned ?? '?'} file(s)${kinds.length ? `: ${kinds.map(([k, n]) => `${n} ${k}`).join(', ')}` : ''}`);
+    r++;
+    const sets = Object.entries(sum.bySet || {});
+    if (sets.length && r < s.rows - 3) {
+      put(scr, r++, 1, 'Rule set      Read  Unreadable  Stopped', 'dim');
+      for (const [name, x] of sets) {
+        if (r >= s.rows - 2) break;
+        put(scr, r++, 1, `${pad(name, 12)}${String(x.filesScanned ?? '').padStart(6)}${String(x.filesUnreadable ?? '').padStart(12)}  ${x.stoppedBy || ''}`);
+      }
+    }
+    return { title: 'Home', right: `${s.report.findings.length} finding(s)`, hint: 'Enter or 1: Findings.  F1: Help.  F3: Leave.' };
+  },
+
+  findings(scr, s) {
+    const layout = findingsLayout(s);
+    let r = drawBanner(scr, s.report, 2, 4);
+    put(scr, r++, 1, countsLine(s.report));
+    const whereW = 17, progW = 9;
+    const ruleW = s.cols - 18 - progW - whereW - 1;
+    put(scr, r++, 0, `   Sv Evidence  X ${pad('Rule', ruleW)} ${pad('Program', progW)}${'Where'}`, 'dim');
+    const list = findingRows(s.report, s.view);
+    if (!list.length) put(scr, layout.listTop, 1, s.report.findings.length ? 'No finding matches this view. RESET shows them all.' : 'No findings.');
+    for (let i = 0; i < layout.height && s.top + i < list.length; i++) {
+      const at = s.top + i;
+      const x = list[at];
+      const row = layout.listTop + i;
+      const mark = at === s.sel ? ' > ' : '   ';
+      put(scr, row, 0, `${mark}${x.letter}  ${pad(x.evidence, 9)} ${x.cross ? 'X' : ' '} ${pad(x.rule, ruleW)} ${pad(x.program || '-', progW)}${pad(x.where, whereW)}`);
+      if (at === s.sel) styleRow(scr, row, 'sel');
+      else if (x.sev === 'crit' || x.sev === 'high') put(scr, row, 3, x.letter, x.sev);
+    }
+    const label = viewLabel(s.view);
+    return {
+      title: `Findings${label ? ` (${label})` : ''}`,
+      right: list.length ? `Row ${s.sel + 1} of ${list.length}` : 'No rows',
+      hint: 'Enter: open.  SORT, FILTER, FIND, RESET on the command line.',
+    };
+  },
+
+  finding(scr, s, t) {
+    const body = bodyLines(s, t);
+    body.slice(t.scroll || 0, (t.scroll || 0) + s.rows - 4).forEach((line, i) => put(scr, 2 + i, 0, line));
+    const list = findingRows(s.report, s.view);
+    const at = list.findIndex((r) => r.f === t.f);
+    return { title: 'Finding', right: at < 0 ? `not in this view of ${list.length}` : `${at + 1} of ${list.length}`, hint: 'F3: back to the list.  F7/F8: scroll.' };
+  },
+
+  help(scr, s, t) {
+    const body = bodyLines(s, t);
+    body.slice(t.scroll || 0, (t.scroll || 0) + s.rows - 4).forEach((line, i) => put(scr, 2 + i, 0, line));
+    const of = t.keys ? `${s.keymap} keys` : PANEL_NAME[t.of];
+    return { title: `Help: ${of}`, right: '', hint: t.keys ? 'F1: help for the panel.  F3: back.' : 'F1: the keys.  F3: back.' };
+  },
+};
+
+const PANEL_NAME = { home: 'Home', findings: 'Findings', finding: 'Finding', help: 'Help' };
+
+function wrap(text, width, indent = '') {
+  const out = [];
+  let line = '';
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && (line + ' ' + word).length > width) { out.push(line); line = indent + word; }
+    else line = line ? `${line} ${word}` : word;
+  }
+  if (line) out.push(line);
+  return out;
+}
+
+function bodyLines(s, t) {
+  const w = s.cols - 2;
+  if (t.panel === 'help') {
+    if (t.keys) {
+      const map = KEYMAPS[s.keymap];
+      return [` The ${s.keymap} keys. KEYS ISPF or KEYS MODERN switches.`, '',
+        ...ACTIONS.map((a) => ` ${a.padEnd(10)} ${Object.entries(map).filter(([, v]) => v === a).map(([k]) => k.replace(/^char:/, '')).join('  ')}`)];
+    }
+    return HELP[t.of].flatMap((p) => (p ? wrap(p, w).map((l) => ` ${l}`) : ['']));
+  }
+  const { f } = t;
+  const field = (label, value) => wrap(value, w - 11).map((l, i) => ` ${i ? ''.padEnd(10) : label.padEnd(10)}${l}`);
+  const lines = [
+    ...field('Rule', f.rule),
+    ...field('Severity', `${f.sev} (${SEV_LETTER[f.sev] || '?'})${f.cwe ? `   ${f.cwe}` : ''}`),
+    ...(f.guardedFrom ? field('Checked', `lowered from ${f.guardedFrom} by the check on ${f.guard.item} at ${f.guard.file}:${f.guard.line}`) : []),
+    ...field('Evidence', `${f.evidence}: ${EVIDENCE[f.evidence] || ''}`),
+    ...field('Who acts', WHO_ACTS[f.evidence] || 'not stated'),
+    ...(f.program ? field('Program', `${f.program}${f.crossProgram ? '   crosses programs' : ''}${f.hops ? `   ${f.hops} hop(s)` : ''}`) : []),
+    ...field('Where', `${f.path}:${f.line}`),
+    ...field('Identity', f.fingerprint || 'none: this report predates fingerprints'),
+    '',
+    ...wrap(f.detail || '', w).map((l) => ` ${l}`),
+  ];
+  if (f.related && f.related.length) {
+    lines.push('');
+    for (const x of f.related) lines.push(...field('Related', `${x.path}:${x.line}  ${x.detail || ''}`));
+  }
+  if (f.trace && f.trace.length) {
+    lines.push('', ' Trace', ...f.trace.map((h, i) => (h.elided ? `   ${h.via}` : `   ${String(i + 1).padStart(2)}  ${pad(h.program, 9)}${pad(h.item, 18)}${h.via}`)));
+    lines.push('', ` Source for each hop: cobolwork explain <path> ${f.fingerprint || '<fingerprint>'}`);
+  }
+  return lines;
+}
+
+const HELP = {
+  home: [
+    'Home shows what the scan read before what it found.',
+    '',
+    'The lines under the command line are coverage: each rule set that fell short, and why. A count over files nobody read is not a clean result, so read them first.',
+    '',
+    'Enter, or the command 1, opens Findings.',
+    '',
+    'Commands: FINDINGS (or 1), KEYS ISPF or KEYS MODERN, HELP, END, and =X to leave.',
+  ],
+  findings: [
+    'Findings lists every finding, critical first, then by rule.',
+    '',
+    'Sv is severity as a letter: C critical, H high, M medium, L low, I info. Evidence is the kind of claim a finding makes. X marks a path that crosses programs.',
+    '',
+    'Enter opens the selected finding. F7 and F8, or Page Up and Page Down, move a page.',
+    '',
+    'Commands:',
+    '  SORT SEVERITY, RULE, PROGRAM, WHERE or EVIDENCE',
+    `  FILTER one or more of ${EVIDENCE_KINDS.join(', ')}; FILTER OFF`,
+    '  FIND text: rule, program, path or detail containing it',
+    '  RESET: the whole list, by severity',
+    '  TOP, BOTTOM, END, and =X to leave',
+  ],
+  finding: [
+    'One finding: what the rule claims, who acts on it, and where.',
+    '',
+    'Evidence says what the tool established. A path was traced by reading the code, not by running it. Severity says how urgent it is; a check on the route lowers it one step and is named here.',
+    '',
+    'Identity is the fingerprint. It does not change when code moves above the finding, so a baseline or a later report can refer to it.',
+    '',
+    'cobolwork explain <path> <fingerprint> prints the trace with the source line of every hop.',
+  ],
+};

package/lib/tui/keys.mjs

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export const ACTIONS = Object.freeze([
+  'help', 'end', 'quit', 'up', 'down', 'pageUp', 'pageDown', 'top', 'bottom', 'open', 'command',
+]);
+
+const COMMON = {
+  F1: 'help', 'C-c': 'quit', Up: 'up', Down: 'down', PageUp: 'pageUp', PageDown: 'pageDown',
+  Home: 'top', End: 'bottom', Enter: 'open',
+};
+
+const ISPF = { ...COMMON, F3: 'end', F12: 'end', F7: 'pageUp', F8: 'pageDown', Tab: 'command' };
+
+const MODERN = {
+  ...COMMON, F3: 'end', Escape: 'end', 'char:q': 'end', 'char:?': 'help', 'char:j': 'down', 'char:k': 'up',
+  'char: ': 'pageDown', 'char:b': 'pageUp', 'char:g': 'top', 'char:G': 'bottom', 'char::': 'command', 'char:/': 'command',
+};
+
+export const KEYMAPS = Object.freeze({ ispf: Object.freeze(ISPF), modern: Object.freeze(MODERN) });
+
+export const actionFor = (keymap, token) => (KEYMAPS[keymap] || KEYMAPS.ispf)[token] || null;
+
+export const LEGEND = Object.freeze({
+  ispf: ' F1=Help F3=End F7=Up F8=Down F12=Cancel  Enter=Open  Type a command, then Enter',
+  modern: ' F1=Help ?=Help q/Esc=Back j/k=Move Space/b=Page Enter=Open :=Command /=Find',
+});
+
+const NAMED = {
+  up: 'Up', down: 'Down', left: 'Left', right: 'Right', pageup: 'PageUp', pagedown: 'PageDown',
+  home: 'Home', end: 'End', return: 'Enter', enter: 'Enter', escape: 'Escape', tab: 'Tab', backspace: 'Backspace',
+};
+
+// readline keypress → 'F1'..'F12', 'Up', 'Enter', ..., 'char:<c>', or 'C-c'.
+export function keyToken(str, key = {}) {
+  if (key.ctrl && key.name === 'c') return 'C-c';
+  if (key.name && /^f([1-9]|1[0-2])$/.test(key.name)) return key.name.toUpperCase();
+  if (key.name && NAMED[key.name] && !key.ctrl && !key.meta) return NAMED[key.name];
+  if (typeof str === 'string' && str.length === 1 && str >= ' ' && str !== '\x7f') return `char:${str}`;
+  return null;
+}

package/lib/tui/model.mjs

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { EVIDENCE } from '../kernel/findings.mjs';
+
+export { WHO_ACTS } from '../kernel/findings.mjs';
+export const SEVERITIES = Object.freeze(['crit', 'high', 'med', 'low', 'info']);
+export const SEV_LETTER = Object.freeze({ crit: 'C', high: 'H', med: 'M', low: 'L', info: 'I' });
+export const EVIDENCE_KINDS = Object.freeze(Object.keys(EVIDENCE));
+
+export function readReport(doc) {
+  const refuse = (why) => { throw new Error(`not a cobolwork findings report: ${why}`); };
+  if (!doc || typeof doc !== 'object') refuse('it is not a JSON object');
+  if (typeof doc.tool !== 'string' || !doc.tool.startsWith('cobolwork')) refuse(`its tool is ${JSON.stringify(doc.tool ?? null)}`);
+  if (!Array.isArray(doc.findings)) refuse('it has no findings list');
+  if (!doc.summary || typeof doc.summary !== 'object') refuse('it has no summary');
+  const problem = doc.findings.map(findingProblem).find(Boolean);
+  if (problem) refuse(problem);
+  const sets = doc.summary.setsIncomplete;
+  if (sets !== undefined && (!Array.isArray(sets) || !sets.every((x) => isEntry(x) && typeof x.set === 'string'))) refuse('its incomplete sets are not named');
+  return doc;
+}
+
+const isEntry = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+
+function findingProblem(f, i) {
+  const n = `finding ${i + 1}`;
+  if (!isEntry(f)) return `${n} is not an object`;
+  for (const k of ['rule', 'path', 'detail']) if (f[k] != null && typeof f[k] !== 'string') return `${n} has a ${k} that is not text`;
+  for (const k of ['related', 'trace']) if (f[k] != null && !(Array.isArray(f[k]) && f[k].every(isEntry))) return `${n} has a ${k} that is not a list of entries`;
+  if (f.guardedFrom != null && !isEntry(f.guard)) return `${n} says a check lowered it but names no check`;
+  return null;
+}
+
+export function banner(report) {
+  const s = report.summary;
+  if (s.nosrc) return { complete: false, lines: ['COVERAGE: nothing was read - no COBOL, JCL or copybook was found'] };
+  const sets = (s.setsIncomplete || []).map((x) => `${x.set.padEnd(9)}${x.kind === 'configuration' ? 'not run: ' : ''}${x.why}`);
+  if (!s.coverageIncomplete) {
+    return { complete: true, lines: [`Coverage complete: every file was read (${s.filesScanned ?? '?'})`, ...sets] };
+  }
+  const lines = ['COVERAGE INCOMPLETE - read this before the counts', ...sets];
+  if (s.copiesMissing) lines.push(`copy     ${s.copiesMissing} COPY statement(s) name a copybook that is not in the tree`);
+  if (s.filesUnreadable) lines.push(`files    ${s.filesUnreadable} file(s) could not be read`);
+  if (s.filesOverBudget) lines.push(`budget   ${s.filesOverBudget} file(s) were past the source budget`);
+  return { complete: false, lines };
+}
+
+export const countsLine = (report) => {
+  const bs = report.summary.bySeverity || {};
+  const sev = SEVERITIES.map((k) => `${SEV_LETTER[k]} ${bs[k] || 0}`).join(' ');
+  const be = report.summary.byEvidence || {};
+  const ev = Object.entries(be).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ${n}`).join(' ');
+  return `Sev ${sev}    Evidence ${ev || 'none'}`;
+};
+
+const SORTS = {
+  severity: (a, b) => SEVERITIES.indexOf(a.sev) - SEVERITIES.indexOf(b.sev) || cmp(a.rule, b.rule) || cmpWhere(a, b),
+  rule: (a, b) => cmp(a.rule, b.rule) || SEVERITIES.indexOf(a.sev) - SEVERITIES.indexOf(b.sev) || cmpWhere(a, b),
+  program: (a, b) => cmp(a.program, b.program) || SORTS.severity(a, b),
+  where: (a, b) => cmpWhere(a, b) || cmp(a.rule, b.rule),
+  evidence: (a, b) => cmp(a.evidence, b.evidence) || SORTS.severity(a, b),
+};
+export const SORT_NAMES = Object.freeze(Object.keys(SORTS));
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const cmpWhere = (a, b) => cmp(a.path, b.path) || (a.line || 0) - (b.line || 0);
+
+export const DEFAULT_VIEW = Object.freeze({ sort: 'severity', evidence: null, find: '' });
+
+export function rows(report, view = DEFAULT_VIEW) {
+  const find = (view.find || '').toUpperCase();
+  const out = [];
+  for (const f of report.findings) {
+    if (view.evidence && !view.evidence.includes(f.evidence)) continue;
+    if (find && ![f.rule, f.program, f.path, f.detail].some((x) => x && String(x).toUpperCase().includes(find))) continue;
+    out.push({
+      f,
+      sev: f.sev,
+      letter: SEV_LETTER[f.sev] || '?',
+      evidence: f.evidence || '',
+      rule: f.rule || '',
+      program: f.program || '',
+      path: f.path || '',
+      line: f.line || 0,
+      where: f.path ? `${f.path.split('/').pop()}:${f.line ?? ''}` : '',
+      cross: !!f.crossProgram,
+    });
+  }
+  return out.sort(SORTS[view.sort] || SORTS.severity);
+}
+
+export function viewLabel(view) {
+  const parts = [];
+  if (view.sort && view.sort !== 'severity') parts.push(`sorted by ${view.sort}`);
+  if (view.evidence) parts.push(`evidence ${view.evidence.join(',')}`);
+  if (view.find) parts.push(`find ${view.find}`);
+  return parts.join(', ');
+}

package/lib/tui/run.mjs

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import * as core from './app.mjs';
+import { redraw } from './screen.mjs';
+
+export function runTui({ report, terminal, keymap = 'ispf', color = true, app = core }) {
+  return new Promise((resolve, reject) => {
+    let state = app.initialState({ report, keymap, ...terminal.size() });
+    let shown = null;
+    let finished = false;
+    const finish = (err) => {
+      if (finished) return;
+      finished = true;
+      terminal.stop();
+      if (err) reject(err); else resolve(state);
+    };
+    const paint = () => {
+      const next = app.view(state);
+      terminal.write(redraw(shown, next, { color }));
+      shown = next;
+    };
+    const handle = (event) => {
+      if (finished) return;
+      try {
+        const r = app.update(state, event);
+        state = r.state;
+        if (r.effects.some((e) => e.type === 'quit')) return finish();
+        if (event.type === 'resize') shown = null;
+        paint();
+      } catch (e) {
+        finish(e);
+      }
+    };
+    terminal.onKey((token) => handle({ type: 'key', token }));
+    terminal.onResize(({ cols, rows }) => handle({ type: 'resize', cols, rows }));
+    terminal.start();
+    try { paint(); } catch (e) { finish(e); }
+  });
+}