@marcomigozzi/trailhead 0.12.1 → 0.14.0

package/plugins/trailhead/hooks/lib/unmodelled.js

@@ -0,0 +1,345 @@
+'use strict';
+// unmodelled.js: the ONE closed list of shell constructs the secret-guard, the
+// body-guard and the secret-read guard cannot interpret with certainty (#227).
+// The threat model of those guards is the ACCIDENTAL leak: a construct they cannot
+// follow is not emulated (the emulation of #210-#220 stays as it is), it is blocked
+// with a "rewrite it in a simple form" message, but only when it can matter to the
+// guard that looks at it.
+//
+// This module finds the constructs and the code each one hides; it does NOT decide
+// what a gh write is. Every hit carries what a guard needs (`stmt`, `payload`,
+// `after`, `calls`, `reach`) and each guard judges relevance with its OWN write
+// classifier, passed to firstRelevant (secret-guard: ghWrites, body-guard:
+// ghBodyWrites; the read guard looks for a secret-looking piece itself), so there is
+// no second classifier to drift. Best-effort like the guards: not a shell parser.
+// Self-contained: requires only the sibling libs.
+
+const {
+  splitStatementsWithSeparators,
+  substitutionBodies,
+  heredocBodies,
+  heredocSubstitutionBodies,
+  functionSubstitutions,
+  inWordContinuations,
+} = require('./shell-scan.js');
+const { words, ASSIGN_TOKEN_RE } = require('./body-sources.js');
+const { parseGhSubcommand, dequote } = require('./gh-subcommand.js');
+
+// The closed list. `reach` says what makes a hit relevant to a guard:
+//   payload  the code it hides holds a write (eval, funsub), or the construct is
+//            CALLED later and what it runs holds a write (function, alias);
+//   state    a write comes AFTER it and can depend on state it changed (source,
+//            printf -v: an expansion, a ~ or a relative path in the write; a fully
+//            literal write is out of reach);
+//   local    its own statement (with its pipeline) is a write;
+//   self     the construct is itself a body-field write (a quoted gh api key).
+const UNMODELLED = {
+  eval: { label: 'eval', reach: 'payload', hint: 'call gh directly, not through eval, with the body in a file passed by its literal absolute path' },
+  source: { label: 'source / `.`', reach: 'state', hint: 'run the sourced steps in a separate Bash call first, then post with a literal --body-file path' },
+  funsub: { label: 'a function substitution (`${ cmd; }`)', reach: 'payload', hint: 'use a plain $(...) command substitution or a separate command' },
+  'printf-v': { label: 'printf -v', reach: 'state', hint: 'put the text in a file, or in a single-quoted literal' },
+  function: { label: 'a function definition', reach: 'payload', hint: 'call gh directly, not through a function defined in the same command' },
+  alias: { label: 'alias', reach: 'payload', hint: 'call gh directly, not through an alias' },
+  'api-field': { label: 'a quoted or split gh api body field name', reach: 'self', hint: 'write the field plainly: `-f body=...` or `-f "body=..."`' },
+  continuation: { label: 'a backslash-newline inside a word', reach: 'local', hint: 'keep every word on one line (a trailing backslash may only sit between words)' },
+};
+
+const MAX_DEPTH = 32;
+const MAX_BYTES = 64 * 1024;
+const SAMPLE_MAX = 80;
+
+// --- command word ----------------------------------------------------------------
+
+const LEADERS = new Set(['!', '{', '(', 'then', 'do', 'else', 'elif', 'if', 'while', 'until', 'time']);
+const WRAPPER_VALUE_FLAGS = {
+  env: ['-u', '-C', '-S'],
+  sudo: ['-u', '-g', '-h', '-p', '-C', '-r', '-t', '-U', '-D', '-R'],
+  nice: ['-n'],
+  timeout: ['-k', '-s'],
+  command: [],
+  builtin: [],
+  exec: ['-a'],
+  nohup: [],
+};
+
+// Index just past a wrapper's own flags (and assignments), from the wrapper at toks[k].
+function skipWrapper(toks, k) {
+  const w = dequote(toks[k]);
+  let j = k + 1;
+  while (j < toks.length) {
+    const t = dequote(toks[j]);
+    if (WRAPPER_VALUE_FLAGS[w].includes(t)) j += 2;
+    else if (t.startsWith('-')) j++;
+    else if ((w === 'env' || w === 'sudo') && ASSIGN_TOKEN_RE.test(t)) j++;
+    else break;
+  }
+  if (w === 'timeout' && j < toks.length) j++; // the duration
+  return j;
+}
+
+// The words of a statement from its command word on: reserved words, a leading `(`,
+// NAME=v prefixes, case heads and arm patterns and wrappers are skipped. So the
+// word `eval` in `--body 'use eval here'` is never a command word.
+function commandInfo(text) {
+  let toks = words(text);
+  while (toks.length) {
+    const open = /^\(+/.exec(toks[0]);
+    if (open) { toks = toks[0].length > open[0].length ? [toks[0].slice(open[0].length), ...toks.slice(1)] : toks.slice(1); continue; }
+    const d = dequote(toks[0]);
+    if (LEADERS.has(d) || ASSIGN_TOKEN_RE.test(toks[0])) { toks = toks.slice(1); continue; }
+    if (d === 'case' && toks.includes('in')) { toks = toks.slice(toks.indexOf('in') + 1); continue; }
+    if (/^[^\s()$"'`]*\)$/.test(toks[0])) { toks = toks.slice(1); continue; } // case arm pattern)
+    if (Object.prototype.hasOwnProperty.call(WRAPPER_VALUE_FLAGS, d)) { toks = toks.slice(skipWrapper(toks, 0)); continue; }
+    break;
+  }
+  return { toks, cmd: toks.length ? dequote(toks[0]) : '', args: toks.slice(1) };
+}
+
+const NAME_RE = /^[A-Za-z_][\w.:+-]*$/;
+
+// The name a statement defines as a function (`f()`, `f(){`, `f ()`, `function f`), or null.
+function functionHeadName(toks) {
+  if (!toks.length) return null;
+  const glued = /^([A-Za-z_][\w.:+-]*)\(\)/.exec(toks[0]);
+  if (glued) return glued[1];
+  if (NAME_RE.test(toks[0]) && toks[1] && /^\(\)/.test(toks[1])) return toks[0];
+  if (toks[0] === 'function' && toks[1]) {
+    const name = toks[1].replace(/\(\)\{?$/, '');
+    return NAME_RE.test(name) ? name : null;
+  }
+  return null;
+}
+
+// --- per-construct helpers -------------------------------------------------------
+
+const compact = (t) => String(t).replace(/\s+/g, ' ').trim();
+
+// The statements, from entries[idx], that make up a function body: up to the closing
+// `}` of the first brace group, or just the head statement when none opens there.
+function functionBody(entries, idx) {
+  const parts = [];
+  let depth = 0;
+  let opened = false;
+  for (let j = idx; j < entries.length; j++) {
+    parts.push(entries[j].text);
+    for (const w of words(entries[j].text)) {
+      if (w === '{' || /^\S+\(\)\{$/.test(w)) { depth++; opened = true; } else if (w === '}') depth--;
+    }
+    if (!opened || depth <= 0) break;
+  }
+  return parts.join('\n');
+}
+
+// The later statements that call `name` as a command word (also through a command
+// substitution in them): [{ text, args }].
+function callsOf(name, entries, idx) {
+  const calls = [];
+  const scan = (text) => {
+    const info = commandInfo(text);
+    if (info.cmd === name) calls.push({ text, args: info.args });
+  };
+  for (const e of entries.slice(idx + 1)) {
+    scan(e.text);
+    for (const body of substitutionBodies(e.text)) {
+      for (const inner of splitStatementsWithSeparators(body)) scan(inner.text);
+    }
+  }
+  return calls;
+}
+
+const API_FIELD_FLAGS = new Set(['-f', '-F', '--field', '--raw-field']);
+
+// A `gh api` statement with a body field whose key is `body` once quotes are removed
+// but is not written as the bare key (`'body'=`, `bo""dy=`, `b\ody=`). A fully quoted
+// pair (`-f "body=x"`, `-f 'body=x'`) is the plain form. Returns the statement
+// rewritten with the plain field (`-f 'body=<value>'`), or null when there is no such
+// field, so a guard can judge the body the field sets.
+function quotedBodyFieldStatement(toks) {
+  const parsed = parseGhSubcommand(toks.join(' '));
+  if (!parsed || parsed.sub !== 'api') return null;
+  for (let k = 0; k < toks.length; k++) {
+    const flag = dequote(toks[k]);
+    let raw = null;
+    let lead = ''; // what stays in front of the rewritten field when the flag and value are glued
+    let at = k; // index of the token holding the value
+    if (API_FIELD_FLAGS.has(flag) && k + 1 < toks.length) { raw = toks[k + 1]; at = k + 1; k++; }
+    else if (/^--(?:raw-)?field=/.test(flag)) { raw = toks[k].slice(toks[k].indexOf('=') + 1); lead = `${flag.slice(0, flag.indexOf('='))} `; }
+    else if (/^-[fF]./.test(toks[k])) { raw = toks[k].slice(2); lead = `${toks[k].slice(0, 2)} `; }
+    if (raw === null) continue;
+    const value = dequote(raw);
+    const eq = value.indexOf('=');
+    if (eq < 0 || value.slice(0, eq) !== 'body') continue;
+    const plain = /^body=/.test(raw) || /^"body=(?:[^"\\]|\\[\s\S])*"$/.test(raw) || /^'body=[^']*'$/.test(raw);
+    if (plain) continue;
+    const field = `${lead}'body=${value.slice(eq + 1).replace(/'/g, "'\\''")}'`;
+    return [...toks.slice(0, at), field, ...toks.slice(at + 1)].join(' ');
+  }
+  return null;
+}
+
+// printf with a -v option before its format.
+function printfAssigns(args) {
+  for (const a of args) {
+    const d = dequote(a);
+    if (d === '--' || !d.startsWith('-')) return false;
+    if (d.startsWith('-v')) return true;
+  }
+  return false;
+}
+
+// --- the walk --------------------------------------------------------------------
+
+function makeHit(id, fields) {
+  const { label, hint, reach } = UNMODELLED[id];
+  return { id, label, hint, reach, sample: '', stmt: '', stmtIndex: -1, payload: '', name: '', calls: [], after: '', afterEntries: [], ...fields };
+}
+
+// Hits that belong to one statement (its command word and what it defines).
+function statementHits(entries, idx) {
+  const e = entries[idx];
+  const { toks, cmd, args } = commandInfo(e.text);
+  const base = { stmt: e.text, stmtIndex: idx, sample: compact(e.text), afterEntries: entries.slice(idx + 1).map((x, i, rest) => ({ text: x.text, piped: (i === 0 ? e.sep : rest[i - 1].sep) === '|', heredocs: x.heredocs })), after: entries.slice(idx + 1).map((x) => x.text).join('\n') };
+  const fnName = functionHeadName(toks);
+  if (fnName) {
+    return [makeHit('function', { ...base, name: fnName, payload: functionBody(entries, idx), calls: callsOf(fnName, entries, idx).map((c) => c.text) })];
+  }
+  if (cmd === 'eval') return [makeHit('eval', { ...base, payload: args.map(dequote).join(' ') })];
+  if (cmd === 'source' || cmd === '.') return [makeHit('source', base)];
+  if (cmd === 'printf' && printfAssigns(args)) return [makeHit('printf-v', { ...base, payload: args.map(dequote).join(' ') })];
+  if (cmd === 'alias') {
+    const defs = args.map(dequote).filter((a) => a.includes('=')).map((a) => [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)]);
+    const calls = defs.flatMap(([name, value]) => callsOf(name, entries, idx).map((c) => `${value} ${c.args.join(' ')}`.trim()));
+    return [makeHit('alias', { ...base, name: defs.length ? defs[0][0] : '', payload: defs.map((d) => d[1]).join('\n'), calls })];
+  }
+  const normalized = cmd ? quotedBodyFieldStatement(toks) : null;
+  return normalized ? [makeHit('api-field', { ...base, payload: normalized })] : [];
+}
+
+// The pipeline a statement belongs to, joined (`a | b | c`).
+function pipelineText(entries, idx) {
+  let from = idx;
+  let to = idx;
+  while (from > 0 && entries[from - 1].sep === '|') from--;
+  while (to < entries.length - 1 && entries[to].sep === '|') to++;
+  return entries.slice(from, to + 1).map((x) => x.text).join(' | ');
+}
+
+function continuationHits(text, entries) {
+  return inWordContinuations(text).map(({ junction }) => {
+    const idx = entries.findIndex((e) => e.text.includes(junction));
+    const stmt = idx < 0 ? text : pipelineText(entries, idx);
+    return makeHit('continuation', { stmt, stmtIndex: idx, sample: compact(stmt) });
+  });
+}
+
+// Every unmodelled construct in a command, including those inside command
+// substitutions, backtick spans and unquoted heredoc bodies (depth- and size-capped).
+function findUnmodelled(cmd) {
+  const out = [];
+  const work = [{ text: String(cmd), depth: 0 }];
+  let bytes = 0;
+  for (let w = 0; w < work.length; w++) {
+    const { text, depth } = work[w];
+    if (depth > 0) bytes += text.length;
+    if (depth > MAX_DEPTH || bytes > MAX_BYTES) continue;
+    const entries = splitStatementsWithSeparators(text);
+    entries.forEach((_, idx) => out.push(...statementHits(entries, idx)));
+    for (const f of functionSubstitutions(text)) {
+      out.push(makeHit('funsub', { payload: f.payload, sample: compact('${' + f.payload + '}'), stmt: compact(f.payload) }));
+    }
+    out.push(...continuationHits(text, entries));
+    for (const body of substitutionBodies(text)) work.push({ text: body, depth: depth + 1 });
+    for (const doc of heredocBodies(text)) {
+      if (doc.quoted) continue;
+      for (const body of heredocSubstitutionBodies(doc.body)) work.push({ text: body, depth: depth + 1 });
+    }
+  }
+  return out;
+}
+
+// Does a raw shell word hold an expansion the shell would run (`$`, a backtick) outside
+// single quotes? Double-quoted text counts; `$'..'` and `$".."` are quoting, not expansion.
+function hasLiveExpansion(raw) {
+  let q = null; // ' or "
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i];
+    if (q === "'") { if (c === "'") q = null; continue; }
+    if (c === '\\') { i++; continue; }
+    if (c === '`') return true;
+    if (c === '$') {
+      if (raw[i + 1] === "'" && q === null) { // ANSI-C span: literal, backslash escapes inside
+        for (i += 2; i < raw.length && raw[i] !== "'"; i++) if (raw[i] === '\\') i++;
+        continue;
+      }
+      if (raw[i + 1] === '"' && q === null) continue;
+      return true;
+    }
+    if (q === '"') { if (c === '"') q = null; continue; }
+    if (c === "'" || c === '"') q = c;
+  }
+  return false;
+}
+
+const STDIN_VALUES = new Set(['-', '/dev/stdin', '/dev/fd/0']);
+
+// Can what a statement posts depend on state a sourced script or printf -v may have
+// changed? An expansion outside single quotes, a `~`, a relative body-file / `-F` /
+// `--input` / api `@path`, or a body read from stdin (`-`, /dev/stdin, `@-`, an input
+// redirect, here-string or heredoc, or the right side of a pipe, whose input another
+// statement builds) can; a fully literal write cannot. Judged token by token.
+// `entry` is { text, piped, heredocs }.
+function stateDependent(entry) {
+  if (entry.piped || entry.heredocs > 0) return true;
+  const toks = words(entry.text);
+  const fileValue = (flag, v) => { // a file the flag reads: stdin or a relative path
+    if (flag === '-F' && v.includes('=')) return false; // a field, not a file
+    return STDIN_VALUES.has(v) || !v.startsWith('/');
+  };
+  for (let k = 0; k < toks.length; k++) {
+    const raw = toks[k];
+    if (hasLiveExpansion(raw) || /^~|[=:]~/.test(raw) || /^<(?!\()/.test(raw)) return true;
+    const d = dequote(raw);
+    const flag = /^(--body-file|-F|--input)(?:=([\s\S]*))?$/.exec(d);
+    if (flag) {
+      const v = flag[2] !== undefined ? flag[2] : (k + 1 < toks.length ? dequote(toks[k + 1]) : null);
+      if (v !== null && fileValue(flag[1], v)) return true;
+    }
+    const field = /body=@([\s\S]*)$/.exec(d);
+    if (field && (field[1] === '-' || !field[1].startsWith('/'))) return true;
+  }
+  return false;
+}
+
+// --- relevance, per hit, by the construct's reach ----------------------------------
+
+// `isWrite(text)` is the CALLING guard's own write classifier.
+function isRelevant(hit, isWrite) {
+  switch (hit.id) {
+    case 'eval':
+    case 'funsub': return isWrite(hit.payload);
+    case 'function': return hit.calls.length > 0 && isWrite(hit.payload);
+    case 'alias': return hit.calls.some((c) => isWrite(c));
+    case 'source':
+    case 'printf-v': return hit.afterEntries.some((e) => isWrite(e.text) && stateDependent(e));
+    case 'continuation': return isWrite(hit.stmt);
+    default: return true; // api-field: the statement is itself a body write
+  }
+}
+
+// The first relevant hit, or null. `modelled` lists ids of constructs the calling guard
+// already follows exactly (its frozen emulation), so they are not blocked there.
+function firstRelevant(hits, isWrite, modelled = []) {
+  return hits.find((h) => !modelled.includes(h.id) && isRelevant(h, isWrite)) || null;
+}
+
+// --- the message -----------------------------------------------------------------
+
+// `redact(text)` must strip anything secret-looking from the sample; without one the
+// sample is withheld, so a token is never echoed back.
+function unmodelledReason(guard, what, hit, redact) {
+  const sample = typeof redact === 'function' ? redact(String(hit.sample)).slice(0, SAMPLE_MAX) : '';
+  return `trailhead ${guard}: this command uses ${hit.label}${sample ? ` (\`${sample}\`)` : ''}, which the guard cannot ` +
+    `interpret with certainty, so it cannot verify ${what}. Rewrite it in a simple form: ${hit.hint}.`;
+}
+
+module.exports = { UNMODELLED, findUnmodelled, firstRelevant, unmodelledReason };

package/plugins/trailhead/hooks/lib/unmodelled.test.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Tests for unmodelled.js. Run: node unmodelled.test.js
+const assert = require('assert');
+const { findUnmodelled, firstRelevant, unmodelledReason, UNMODELLED } = require('./unmodelled.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const ids = (cmd) => findUnmodelled(cmd).map((h) => h.id);
+const has = (cmd, id) => ids(cmd).includes(id);
+const none = (cmd) => ids(cmd).length === 0;
+// A stand-in write classifier: the lib has none of its own, each guard passes its own.
+const isWrite = (t) => /\bgh\s+(?:issue|pr)\s+(?:comment|edit|create)\b/.test(t);
+const relevant = (cmd) => !!firstRelevant(findUnmodelled(cmd), isWrite);
+
+// --- the closed table ---
+ok('UNMODELLED lists every construct with a label and a hint', ['eval', 'source', 'funsub', 'printf-v', 'function', 'alias', 'api-field', 'continuation']
+  .every((id) => UNMODELLED[id] && UNMODELLED[id].label && UNMODELLED[id].hint));
+
+// --- eval ---
+ok('eval is detected', has('eval "$(ssh-agent)"', 'eval'));
+ok('eval payload is its quote-removed arguments', findUnmodelled("eval 'gh issue comment 1 --body x'")[0].payload === 'gh issue comment 1 --body x');
+ok('eval behind a wrapper is detected', has('command eval x', 'eval') && has('FOO=1 eval x', 'eval'));
+ok('eval after && is detected', has('true && eval x', 'eval'));
+ok('eval in quoted prose is not', none("gh issue comment 1 --body 'use eval here'"));
+ok('eval as an argument is not', none('echo eval'));
+ok('eval in a comment is not', none('echo hi # eval x'));
+
+// --- source ---
+ok('source is detected', has('source ./post.sh', 'source'));
+ok('. is detected', has('. ./post.sh', 'source'));
+ok('. inside quotes is not', none('echo ". x"'));
+ok('./script is not', none('./post.sh'));
+ok('source as an argument is not', none('echo source x'));
+
+// --- function substitution ---
+ok('${ cmd; } is detected', has('echo ${ gh issue comment 1 --body x; }', 'funsub'));
+ok('${| cmd; } is detected', has('echo ${| REPLY=x; }', 'funsub'));
+ok('${<newline> is detected', has('echo ${\ndate\n}', 'funsub'));
+ok('funsub payload is the body', findUnmodelled('echo ${ date; }')[0].payload === ' date; ');
+ok('plain expansions are not', none('echo ${x} ${x:-y}'));
+ok('a single-quoted funsub is not', none("echo '${ x; }'"));
+ok('a funsub inside a $(..) body is found', has('echo $(echo ${ date; })', 'funsub'));
+ok('a funsub inside a backtick body is found', has('echo `echo ${ date; }`', 'funsub'));
+ok('a funsub in an unquoted heredoc is found', has('cat <<E\n${ date; }\nE', 'funsub'));
+
+// --- printf -v ---
+ok('printf -v is detected', has('printf -v B %s x', 'printf-v'));
+ok('printf -vNAME is detected', has('printf -vB %s x', 'printf-v'));
+ok('printf without -v is not', none("printf '%s' x"));
+ok('a -v after the format is not', none('printf %s -v'));
+
+// --- function definitions ---
+ok('name() { is detected', has('f(){ :; }', 'function'));
+ok('name () is detected', has('f () { :; }', 'function'));
+ok('function name is detected', has('function f { :; }', 'function'));
+ok('a function head after a leader is detected', has('true && f() { :; }', 'function'));
+ok('f() in quotes is not', none('echo "f()"') && none('git commit -m "f() {"'));
+ok('function name and body are reported', (() => {
+  const h = findUnmodelled('f() { gh issue comment 1 --body x; }; f')[0];
+  return h.id === 'function' && h.name === 'f' && /gh issue comment/.test(h.payload) && h.calls.length === 1;
+})());
+ok('a multi-line function body is the payload', /gh issue comment/.test(findUnmodelled('f() {\n  ls\n  gh issue comment 1 --body x\n}\nf')[0].payload));
+
+// --- alias ---
+ok('alias is detected', has('alias a=b', 'alias'));
+ok('alias in prose is not', none('echo alias'));
+ok('alias name and value are reported', (() => {
+  const h = findUnmodelled('alias g=gh; g issue list')[0];
+  return h.name === 'g' && h.payload === 'gh' && h.calls.length === 1 && h.calls[0] === 'gh issue list';
+})());
+
+// --- gh api body field ---
+ok("-f 'body'= is detected", has("gh api -X PATCH repos/o/r/issues/1 -f 'body'=\"\"", 'api-field'));
+ok('-f bo""dy= is detected', has('gh api -X PATCH repos/o/r/issues/1 -f bo""dy=""', 'api-field'));
+ok('-f b\\ody= is detected', has('gh api repos/o/r/issues/1 -f b\\ody=x', 'api-field'));
+ok('--field "body"= is detected', has('gh api repos/o/r/issues/1 --field "body"=x', 'api-field'));
+ok('--raw-field=bo""dy=x is detected', has('gh api repos/o/r/issues/1 --raw-field=bo""dy=x', 'api-field'));
+ok('-Fb\'ody\'=x glued is detected', has("gh api repos/o/r/issues/1 -F'body'=x", 'api-field'));
+ok('the api-field payload is the statement with a plain field', findUnmodelled("gh api -X PATCH r -f 'body'=\"\"")[0].payload === "gh api -X PATCH r -f 'body='");
+ok('the api-field payload keeps a glued form plain too', findUnmodelled('gh api r --field=bo""dy=hi')[0].payload === "gh api r --field 'body=hi'");
+ok('-f body=x is plain', none('gh api repos/o/r/issues/1 -f body=x'));
+ok('-f "body=x" is plain', none('gh api repos/o/r/issues/1 -f "body=x"'));
+ok("-f 'body=x' is plain", none("gh api repos/o/r/issues/1 -f 'body=x'"));
+ok('-f "body=say \\"hi\\"" is plain', none('gh api repos/o/r/issues/1 -f "body=say \\"hi\\""'));
+ok('-F title=x is plain', none('gh api repos/o/r/issues/1 -F title=x'));
+ok('-f "title"=x is plain', none('gh api repos/o/r/issues/1 -f "title"=x'));
+ok('a non-api gh statement is not', none('gh issue comment 1 --body "bo""dy=x"'));
+
+// --- in-word continuation ---
+ok('cat .e\\<nl>nv is detected', has('cat .e\\\nnv', 'continuation'));
+ok('a continuation between words is not', none('gh issue comment 1 \\\n  --body x'));
+ok('a single-quoted continuation is not', none("echo 'a\\\nb'"));
+
+// --- statement bookkeeping ---
+ok('a hit carries its statement and index', (() => {
+  const h = findUnmodelled('echo a; source f; echo b')[0];
+  return h.stmt === 'source f' && h.stmtIndex === 1 && h.after === 'echo b';
+})());
+ok('the sample is the compacted statement', findUnmodelled('echo a\nsource f')[0].sample === 'source f');
+ok('a hit inside a $(..) is found with its own statements', has('x=$(source f; gh issue comment 1 --body y)', 'source'));
+ok('a hit inside a quoted heredoc body is not', none("cat <<'E'\neval x\nsource y\nE"));
+ok('a hit inside an unquoted heredoc $(..) is found', has('cat <<E\n$(source f)\nE', 'source'));
+
+// --- relevance: payload constructs ---
+ok('eval with a write payload is relevant', relevant("eval 'gh issue comment 1 --body x'"));
+ok('eval "$(ssh-agent)" next to a write is not', !relevant('eval "$(ssh-agent)"; gh issue comment 1 --body-file /tmp/clean.md'));
+ok('eval alone is not', !relevant('eval "$(ssh-agent)"'));
+ok('funsub with a write payload is relevant', relevant('echo ${ gh issue comment 1 --body-file /tmp/f; }'));
+ok('funsub without a write payload is not', !relevant('echo ${ date; }; gh issue comment 1 --body-file /tmp/clean.md'));
+ok('a called function with a write body is relevant', relevant('f() { gh issue comment 1 --body x; }; f'));
+ok('an uncalled function with a write body is not', !relevant('f() { gh issue comment 1 --body x; }'));
+ok('a called function without a write body next to a write is not', !relevant('f(){ ls; }; f; gh issue comment 1 --body-file /tmp/clean.md'));
+ok('a function called through a substitution is relevant', relevant('f() { gh issue comment 1 --body x; }; x=$(f)'));
+ok('alias g=gh then g issue comment is relevant', relevant('alias g=gh; g issue comment 1 --body x'));
+ok('alias g=gh alone is not', !relevant('alias g=gh'));
+ok('alias g=gh then a read-only call is not', !relevant('alias g=gh; g issue list'));
+ok("alias ll='ls -l' next to a write is not", !relevant("alias ll='ls -l'; gh issue comment 1 --body-file /tmp/clean.md"));
+ok('a write quoted in prose next to an alias is not', !relevant('echo "gh issue edit 1"; alias ll=ls'));
+
+// --- relevance: state constructs ---
+ok('source before a state-dependent write is relevant', relevant('source ./post.sh; gh issue comment 1 --body "$B"'));
+ok('source before a relative body file is relevant', relevant('source x; gh issue comment 1 --body-file rel.md'));
+ok('source before a ~ body file is relevant', relevant('source x; gh issue comment 1 --body-file ~/b.md'));
+ok('source before a relative api @path is relevant', relevant('source x; gh issue edit 1 --body-file ./b.md'));
+ok('source before a backtick body is relevant', relevant('source x; gh issue comment 1 --body `date`'));
+ok('source before a literal write is not', !relevant('source venv/bin/activate && gh issue comment 1 --body-file /tmp/clean.md'));
+ok('. before a literal inline body is not', !relevant(". venv/bin/activate && gh issue edit 1 --body 'hello'"));
+ok('a single-quoted dollar is literal', !relevant("source x; gh issue comment 1 --body 'costs $5'"));
+ok('an unrelated expansion beside a literal write is not', !relevant('source x; echo $HOME; gh issue comment 1 --body-file /tmp/clean.md'));
+ok('source after the write is not', !relevant('gh issue comment 1 --body-file /tmp/clean.md; source ./post.sh'));
+ok('source with no write is not', !relevant('source ~/.venv/bin/activate && pytest'));
+ok('printf -v before a write is relevant', relevant('printf -v B %s x; gh issue comment 1 --body "$B"'));
+ok('printf -v after the write is not', !relevant('gh issue comment 1 --body-file /tmp/clean.md; printf -v B %s x'));
+ok('W2: an apostrophe inside double quotes does not hide an expansion', relevant(`printf -v B %s ''; gh issue edit 1 --body "it's $B and 'x'"`));
+ok('W2: the same after source', relevant(`source x.sh; gh issue edit 1 --body "it's $B and 'x'"`));
+ok('W2: stdin fed by a pipe from another statement', relevant('printf -v B %s ""; printf %s "$B" | gh issue edit 1 --body-file -'));
+ok('W2: stdin fed by an unquoted heredoc', relevant('printf -v B %s ""; gh issue edit 1 --body-file - <<EOF\n$B\nEOF'));
+ok('W2: stdin fed by a redirect', relevant('source x; gh issue edit 1 --body-file - < in.md'));
+ok('W2: stdin fed by a here-string', relevant('source x; gh issue edit 1 --body-file - <<< "$B"'));
+ok('W2: --body-file /dev/stdin', relevant('source x; gh issue edit 1 --body-file /dev/stdin'));
+ok('W2: --input - (the stand-in classifier knows issue writes only)', relevant('source x; gh issue edit 1 --input -'));
+ok('W2: api body=@-', relevant('source x; gh issue edit 1 -F body=@-'));
+ok('W2: a quoted relative -F value is one token', relevant("source x; gh issue edit 1 -F 'a b.md'"));
+ok('W2: a double-quoted dollar counts', relevant('source x; gh issue edit 1 --body "$B"'));
+ok('W2: a literal body with an apostrophe in double quotes is not', !relevant(`source x; gh issue edit 1 --body "it's fine"`));
+ok('W2: a plain word body is not', !relevant('source x; gh issue edit 1 --body lit'));
+ok('W2: a single-quoted body is not', !relevant("source x; gh issue edit 1 --body 'lit'"));
+ok('W2: an absolute body file is not', !relevant('source x; gh issue edit 1 --body-file /abs/clean.md'));
+ok('W2: tokens are not matched across each other', !relevant("source x; gh issue edit 1 --body 'a -F b' --title t"));
+ok('printf -v before a literal write is not', !relevant("printf -v B %s x; gh issue edit 1 --body 'hello'"));
+ok('printf -v with no write is not', !relevant('printf -v x %s y; echo $x'));
+
+// --- relevance: statement-local constructs ---
+ok('a quoted api field is always relevant', relevant("gh api -X PATCH repos/o/r/issues/1 -f 'body'=\"\""));
+ok('an in-word continuation in a write is relevant', relevant('gh issue com\\\nment 1 --body x'));
+ok('an in-word continuation outside a write is not', !relevant('cat .e\\\nnv; gh issue comment 1 --body-file /tmp/clean.md'));
+ok('an in-word continuation in a piped write is relevant', relevant('cat .e\\\nnv | gh issue comment 1 --body-file -'));
+
+ok('a construct the guard already models is skipped', firstRelevant(findUnmodelled("gh api repos/o/r/issues/1 -f 'body'=x"), isWrite, ['api-field']) === null);
+
+// --- the message ---
+{
+  const hit = findUnmodelled('eval "gh issue comment 1 --body ghp_' + 'a'.repeat(36) + '"')[0];
+  const redact = (t) => t.replace(/ghp_[A-Za-z0-9]+/g, '<REDACTED>');
+  const msg = unmodelledReason('secret-guard', 'the body it posts is secret-free', hit, redact);
+  ok('the message names the guard, the construct and the rewrite', /^trailhead secret-guard: this command uses /.test(msg) && /Rewrite it in a simple form: /.test(msg) && msg.includes(UNMODELLED.eval.label));
+  ok('the message never echoes a token', !msg.includes('ghp_'));
+  ok('the sample is truncated to 80 chars', unmodelledReason('g', 'w', { ...hit, sample: 'x'.repeat(200) }, (t) => t).match(/`(x+)`/)[1].length === 80);
+  ok('without a redactor the sample is withheld', !/ghp_/.test(unmodelledReason('g', 'w', hit)));
+}
+
+console.log(`✓ unmodelled: ${passed} assertions passed`);