@redue/cli 0.1.0-alpha.26 → 0.1.0-alpha.28

package/src/sandbox.mjs

@@ -19,10 +19,22 @@ import {spawn,spawnSync} from 'node:child_process';
 import {fileURLToPath} from 'node:url';
 import {lookup,scriptCaches,scriptCheckInputs,scriptProject,toolchainDirs} from './node-script.mjs';
 import {displayVariables} from './test-direct.mjs';
+import picomatch from 'picomatch';
 
 export const sandboxQualification='sandbox-v1';
 export const sandboxInterpretation='sandbox@1';
-export const sandboxKinds=['typecheck','lint'];
+// The same recipe with the checkout's git-ignored files hidden from the run
+// (hiddenEntries): they are not its inputs, so build and test outputs do not
+// make it STALE. init gives it when the run gives the same result that way.
+export const hiddenQualification='sandbox-v2';
+export const hiddenInterpretation='sandbox@2';
+export const hiddenListIssue='git cannot list the ignored files';
+export const isSandboxed=qualification=>qualification===sandboxQualification||qualification===hiddenQualification;
+export const sandboxInterpretationOf=qualification=>qualification===hiddenQualification?hiddenInterpretation:sandboxInterpretation;
+export const sandboxKinds=['typecheck','lint','test'];
+// A test run gets loopback networking and a private /tmp (sandboxArgv's
+// `network` and `writes`); a typecheck or lint gets no network.
+export const testRun=check=>check?.kind==='test';
 const fail=code=>{throw Object.assign(Error(code),{code});};
 const digest=value=>createHash('sha256').update(value).digest('hex');
 const real=file=>{try{return fs.realpathSync(file);}catch{return null;}};
@@ -53,10 +65,12 @@ export const pythonTool=check=>Array.isArray(check?.command)&&/^\.venv\/bin\/[A-
 // script check names its package manager first among the executables, as the
 // general recipe does.
 const managers=['npm','pnpm','yarn','corepack'];
-export function sandboxEnvironment(python=false,manager=null){
+export function sandboxEnvironment(python=false,manager=null,kind=null){
   return {variables:['TZ','LANG','LANGUAGE','CI','USER','LOGNAME'],
     prefixes:['LC_','DYLD_','LD_',...python?['PYTHON','MYPY','RUFF_','PYRIGHT','TY_']:
-      ['NODE_','npm_config_','PNPM_','YARN_','COREPACK_','TSGO_']],
+      ['NODE_','npm_config_','PNPM_','YARN_','COREPACK_','TSGO_'],
+      // A test runner's own variables.
+      ...kind==='test'?python?['PYTEST_']:['VITEST_','JEST_']:[]],
     ...manager?{pathExecutables:['node',manager,...managers.filter(name=>name!==manager)]}:{}};
 }
 
@@ -157,16 +171,26 @@ export function sandboxEnv(check,env,{root,home,tmp}){
   }
   return out;
 }
-// The files in the checkout's .git that tools read to choose files (ruff's
-// and biome's ignore rules): the repository's exclude file and config. The
-// observer does not watch .git, so they are compared as context.
+// The files in the repository's .git that tools read to choose files (ruff's
+// and biome's ignore rules), and that decide what sandbox-v2 hides: its
+// exclude file and config. For a project in a subdirectory of the
+// repository, also the .gitignore files above it. The observer watches
+// neither, so they are compared as context.
 function gitIgnoreSources(root){
-  let dir=path.join(root,'.git');
+  let top=root;
+  while(!fs.existsSync(path.join(top,'.git'))){const up=path.dirname(top);if(up===top)return [];top=up;}
+  let dir=path.join(top,'.git');
   try{if(fs.statSync(dir).isFile()){
-    const gitdir=path.resolve(root,/^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dir,'utf8'))?.[1].trim()??'');
+    const gitdir=path.resolve(top,/^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dir,'utf8'))?.[1].trim()??'');
     let common=gitdir;try{common=path.resolve(gitdir,fs.readFileSync(path.join(gitdir,'commondir'),'utf8').trim());}catch{}
     dir=common;}}catch{return [];}
-  return ['info/exclude','config'].map(rel=>{try{return [rel,digest(fs.readFileSync(path.join(dir,rel)))];}catch{return [rel,null];}});
+  const read=file=>{try{return digest(fs.readFileSync(file));}catch{return null;}};
+  const above=[];
+  for(let at=path.dirname(root);top!==root&&(at===top||at.startsWith(top+path.sep));at=path.dirname(at)){
+    above.push([path.relative(top,path.join(at,'.gitignore')),read(path.join(at,'.gitignore'))]);
+    if(at===top)break;
+  }
+  return [...['info/exclude','config'].map(rel=>[rel,read(path.join(dir,rel))]),...above];
 }
 // What a sandboxed result depends on outside the observed files, compared
 // before reuse, one entry each so a change can be named (sandboxChange): every
@@ -211,33 +235,160 @@ export function sandboxDirs(state,name){
   return {home,tmp:fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'redue-run-')))};
 }
 
+// The checkout's git-ignored entries a run may be kept from reading: what
+// `git ls-files --others --ignored --exclude-standard --directory` lists (a
+// wholly ignored directory as one entry, ending in /), but the installed
+// trees (node_modules, .venv) and runner caches. Relative to root. null when
+// git cannot list them. Only the project's rules count (.gitignore files and
+// .git/info/exclude), not a user's global excludes file, as on CI.
+const installedTree=/(?:^|\/)(?:node_modules|\.venv)(?:\/|$)/;
+const runnerCache=picomatch(sandboxCaches,{dot:true});
+const projectGit=['-c','core.excludesFile=/dev/null'],gitEnv=()=>({...process.env,GIT_OPTIONAL_LOCKS:'0'});
+export function hiddenEntries(root){
+  const r=spawnSync('git',[...projectGit,'ls-files','-z','--others','--ignored','--exclude-standard','--directory'],
+    {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:60000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+  if(r.status!==0)return null;
+  return r.stdout.split('\0').filter(Boolean).filter(rel=>!installedTree.test(rel)&&
+    !runnerCache(rel)&&!runnerCache(rel.replace(/\/$/,'')+'/x'));
+}
+
+// What git lists now as ignored at or beneath `paths` (relative files, or
+// directories ending in /), as hiddenEntries would: nested repositories are
+// not entered, and an entry that is an installed tree is not ignored (one
+// inside an ignored build directory is). {has(rel)} for a file, or null when
+// git cannot tell. A directory git ignores holds no file it does not, so
+// asking a new directory once covers its files.
+export function ignoredNow(root,paths){
+  const asked=paths;
+  if(!asked.length)return {has:()=>false};
+  const listed=new Set();
+  for(let at=0;at<asked.length;at+=500){
+    const r=spawnSync('git',[...projectGit,'ls-files','-z','--others','--ignored','--exclude-standard','--directory','--',...asked.slice(at,at+500)],
+      {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:10000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+    if(r.status!==0)return null;
+    for(const entry of r.stdout.split('\0'))if(entry)listed.add(entry);
+  }
+  const entries=[...listed].filter(entry=>!installedTree.test(entry));
+  return {has:rel=>entries.some(entry=>rel===entry||entry.endsWith('/')&&rel.startsWith(entry))};
+}
+// The files git tracks now beneath `entries` (relative). null when git cannot tell.
+export function trackedBeneath(root,entries){
+  if(!entries.length)return new Set();
+  const r=spawnSync('git',['ls-files','-z','--cached','--',...entries],
+    {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:10000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+  return r.status===0?new Set(r.stdout.split('\0').filter(Boolean)):null;
+}
+// For a run that hid `hidden` (relative entries), the first path of `paths`
+// that changes its inputs, between `before` and `current` ({rel: identity}),
+// or null. A file the run saw always counts. A file beneath a hidden entry
+// counts only once git tracks it, and a new file only when git does not list
+// it as ignored now, as the next run's hidden entries would not. When git
+// cannot tell, every change counts. `external:` paths always count. With
+// `during` (changes while the run ran), a new file outside the hidden
+// entries counts too: the run could read it.
+export function visibleChange(root,hidden,before,current,paths,{during=false}={}){
+  const entries=hidden.map(entry=>entry.replace(/\/$/,''));
+  const beneath=file=>entries.some(entry=>file===entry||file.startsWith(entry+'/'));
+  const changed=[...new Set(paths)].filter(file=>before[file]!==current[file]).sort();
+  const seen=changed.filter(file=>file in before&&!beneath(file));
+  if(seen.length)return seen[0];
+  const covered=changed.filter(beneath),fresh=changed.filter(file=>!(file in before)&&!beneath(file));
+  if(covered.length){
+    const tracked=trackedBeneath(root,entries.filter(entry=>covered.some(file=>file===entry||file.startsWith(entry+'/'))));
+    const found=covered.find(file=>!tracked||tracked.has(file));
+    if(found)return found;
+  }
+  if(!fresh.length)return null;
+  if(during)return fresh[0];
+  // Asked once per directory the run had no file in, then the files outside one.
+  const dirs=new Set(Object.keys(before).flatMap(file=>file.split('/').slice(0,-1).map((_,i,parts)=>parts.slice(0,i+1).join('/'))));
+  const newDir=file=>{const parts=file.split('/');for(let i=1;i<parts.length;i++){const dir=parts.slice(0,i).join('/');if(!dirs.has(dir))return dir+'/';}return null;};
+  const ignored=ignoredNow(root,[...new Set(fresh.filter(file=>!file.startsWith('external:')).map(file=>newDir(file)??file))]);
+  return fresh.find(file=>file.startsWith('external:')||!ignored||!ignored.has(file))??null;
+}
+// A refusal line that names a hidden entry (relative): a refusal by the
+// sandbox, or a missing file, which Linux tools report for an unreadable one.
+export function hiddenRefusal(text,hidden){
+  const names=hidden.map(file=>file.replace(/\/$/,'')).filter(Boolean)
+    .map(name=>new RegExp(`(?:^|[\\s'"\`(=/])${escape(name)}(?:[/\\s'"\`):,]|$)`));
+  for(const line of String(text).split(/\r?\n/))
+    if((denial.test(line)||missing.test(line))&&names.some(name=>name.test(line)))return line.trim().slice(0,200);
+  return null;
+}
+
 const ancestors=list=>[...new Set(list.flatMap(dir=>{const out=[];for(let at=path.dirname(dir);at!=='/'&&at!=='.';at=path.dirname(at))out.push(at);return out;}))];
 // The Seatbelt profile: reads and executes only beneath the places, the
 // metadata of their parent directories, and no network but Unix sockets in
 // the run's own temporary directory (`own`), which is new for each run: a
-// daemon an earlier run left behind cannot answer a later one.
-export function seatbeltProfile(reads,own=null){
+// daemon an earlier run left behind cannot answer a later one. `hidden`:
+// absolute paths whose contents it may not read or execute.
+// A test run (`network` "loopback") may bind and accept anywhere and
+// connect to loopback only; with `writes`, it writes nothing beneath /tmp
+// and /var/tmp but beneath those places (its checkout, home and own
+// temporary directory).
+export function seatbeltProfile(reads,own=null,hidden=[],{network='none',writes=null}={}){
   const quote=value=>JSON.stringify(value);
+  const both=list=>[...new Set(list.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
   const all=[...new Set(reads.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
   return ['(version 1)','(allow default)','(deny file-read* process-exec*)',
     `(allow file-read* process-exec* ${all.map(dir=>`(subpath ${quote(dir)})`).join(' ')} (literal "/") (literal "/etc") (literal "/var") (literal "/tmp"))`,
     `(allow file-read-metadata ${ancestors(all).map(dir=>`(literal ${quote(dir)})`).join(' ')})`,
-    '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
+    // The entry's own path, by its directory's real path: a hidden link's target is not hidden.
+    // Its contents only, as on Linux: a run may still see that it exists, and write beneath it.
+    ...hidden.length?[`(deny file-read-data process-exec* ${[...new Set(hidden.flatMap(file=>[file,path.join(real(path.dirname(file))??path.dirname(file),path.basename(file))]))]
+      .map(file=>`(subpath ${quote(file)})`).join(' ')})`]:[],
+    '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[],
+    ...network==='loopback'?['(allow network-bind)','(allow network-inbound)','(allow network-outbound (remote ip "localhost:*"))']:[],
+    ...writes?['(deny file-write* (subpath "/tmp") (subpath "/private/tmp") (subpath "/var/tmp") (subpath "/private/var/tmp"))',
+      `(allow file-write* ${both(writes).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
 }
 // The argv that runs `argv` sandboxed: reads beneath `reads`, no network but
-// Unix sockets beneath `tmp` on macOS.
-export function sandboxArgv(mode,argv,{reads,tmp=null,python}){
-  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp),...argv];
+// Unix sockets beneath `tmp` on macOS, nothing beneath `hidden` (absolute).
+// On Linux a hidden directory can still be listed and its entries stat'ed:
+// Landlock restricts neither beneath a listable parent.
+// `network` "loopback" and `writes`: a test run's (seatbeltProfile). On Linux
+// its network is supervised: `stats` then says whether the supervisor served
+// the whole run (supervisorIssue).
+export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null,network='none',writes=null,fault=null}){
+  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden,{network,writes}),...argv];
   // The launcher's own warnings would become the check's output.
-  if(mode==='landlock')return [python,'-I','-W','ignore',landlockScript,...reads.flatMap(dir=>['--read',dir]),'--no-tcp','--',...argv];
+  if(mode==='landlock')return [python,'-I','-W','ignore',landlockScript,...reads.flatMap(dir=>['--read',dir]),
+    ...hidden.flatMap(file=>['--hide',file]),...stats?['--stats',stats]:[],
+    ...network==='loopback'?['--loopback']:['--no-tcp'],
+    ...writes?['--deny-write','/tmp','--deny-write','/var/tmp',...writes.flatMap(dir=>['--write',dir])]:[],
+    ...fault?['--test-fault',fault]:[],'--',...argv];
   throw Error(`unknown sandbox ${mode}`);
 }
+// Why a supervised run's network was not supervised throughout, from the
+// launcher's stats file, or null when it was.
+export function supervisorIssue(stats){
+  let value=null;try{value=JSON.parse(fs.readFileSync(stats,'utf8'));}catch{}
+  return value?.supervisor==='ok'?null:`the network supervisor ${value?.supervisor?`reported: ${value.supervisor}`:'left no report'}`;
+}
+// The counts a test runner's summary gives, the last of each: pytest, Vitest,
+// Jest, Mocha, node --test.
+const ansi=/\u001b\[[0-9;]*m/g;
+export function testCounts(text){
+  const plain=String(text).replace(ansi,'');
+  const last=(...patterns)=>{for(const re of patterns){let m,v=null;const g=new RegExp(re,'gim');while((m=g.exec(plain)))v=Number(m[1]);if(v!==null)return v;}return null;};
+  return {passed:last('(\\d+) (?:tests? )?(?:passed|passing)\\b','^(?:#|ℹ) pass (\\d+)'),failed:last('(\\d+) (?:tests? )?(?:failed|failing)\\b','^(?:#|ℹ) fail (\\d+)'),
+    skipped:last('(\\d+) (?:tests? )?(?:skipped|pending|todo)\\b','^(?:#|ℹ) (?:skip|skipped) (\\d+)')};
+}
 // A line of a failed run's output that looks like the sandbox refused
 // something: a refused read or write, or the network unreachable. Such a
 // failure is run again outside the sandbox to tell a denial from a real one.
 const denial=/operation not permitted|permission denied|read-only file system|\bE(?:PERM|ACCES|ROFS|NOTFOUND|AI_AGAIN|CONNREFUSED|NETUNREACH|HOSTUNREACH)\b|sandbox-exec:|landlock\.py:|network is unreachable|could not resolve host|name or service not known|nodename nor servname|temporary failure in name resolution|getaddrinfo|connection refused/i;
-export function denialLine(text){
-  for(const line of String(text).split(/\r?\n/))if(denial.test(line))return line.trim().slice(0,200);
+// A missing file counts only when the line names a path the run was kept
+// from (`hidden`, relative to the checkout or absolute): Linux tools report
+// an unreadable file as not found.
+const missing=/not found|no such file|cannot find|can't find|could not find|cannot read|\bENOENT\b/i;
+const escape=text=>text.replace(/[.*+?^${}()|[\]\\]/g,'\\$&');
+export function denialLine(text,hidden=[]){
+  // A name as a whole path or path component, not inside a longer word.
+  const names=hidden.map(file=>file.replace(/\/$/,'')).filter(Boolean)
+    .map(name=>new RegExp(`(?:^|[\\s'"\`(=/])${escape(name)}(?:[/\\s'"\`):,]|$)`));
+  for(const line of String(text).split(/\r?\n/))
+    if(denial.test(line)||missing.test(line)&&names.some(name=>name.test(line)))return line.trim().slice(0,200);
   return null;
 }
 
@@ -366,22 +517,33 @@ export function runToEnd(argv,{cwd,env,timeout=0,echo=false,started=null}){
   });
 }
 // {same, plain, sandboxed, line} or {issue} when the sandbox cannot run here.
-export async function sandboxTrial(root,check,{timeout=300000}={}){
+// With `hide`, the git-ignored entries hiddenEntries lists are kept from the
+// sandboxed run, and it also returns them, their count, the run times and, on
+// Linux, the launcher's rule count and setup time.
+// `plain`: the plain run of an earlier trial of the same check, reused.
+export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:earlier=null}={}){
   const supported=sandboxSupport();
   if(supported.issue)return {issue:supported.issue};
   const python=Boolean(pythonTool(check));
   const command=python?check.command:[lookup(scriptProject(root,check.script).manager,process.env.PATH,root)||'npm','run',check.script];
-  const selected={...check,command,environment:sandboxEnvironment(python,python?null:scriptProject(root,check.script).manager)};
+  const selected={...check,command,environment:sandboxEnvironment(python,python?null:scriptProject(root,check.script).manager,check.kind)};
+  const tests=testRun(check);
   const scratch=fs.mkdtempSync(path.join(os.tmpdir(),'redue-trial-')),home=path.join(scratch,'home'),tmp=path.join(scratch,'tmp');
   fs.mkdirSync(home);fs.mkdirSync(tmp);
   try{
-    const run=async(argv,env)=>{const r=await runToEnd(argv,{cwd:root,env,timeout});
-      return {status:r.timedOut?'timeout':r.status??r.signal??r.error?.code,output:`${r.stdout}\n${r.stderr}`};};
-    const plain=await run(command,{...process.env,...python?{}:{npm_config_update_notifier:'false'}});
+    const entries=hide?hiddenEntries(root):[];
+    if(!entries)return {issue:hiddenListIssue};
+    const hidden=entries.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=(hide||tests)&&supported.mode==='landlock'?path.join(scratch,'stats.json'):null;
+    const run=async(argv,env)=>{const started=Date.now(),r=await runToEnd(argv,{cwd:root,env,timeout});
+      return {status:r.timedOut?'timeout':r.status??r.signal??r.error?.code,output:`${r.stdout}\n${r.stderr}`,ms:Date.now()-started};};
+    const plain=earlier??await run(command,{...process.env,...python?{}:{npm_config_update_notifier:'false'}});
     const reads=[root,home,tmp,...sandboxPlaces(selected,process.env,root),...systemPlaces];
-    const sandboxed=await run(sandboxArgv(supported.mode,command,{reads,tmp,python:supported.python}),sandboxEnv(selected,process.env,{root,home,tmp}));
+    const sandboxed=await run(sandboxArgv(supported.mode,command,{reads,tmp,python:supported.python,hidden,stats,
+      ...tests?{network:'loopback',writes:[root,home,tmp]}:{}}),sandboxEnv(selected,process.env,{root,home,tmp}));
+    // A test run's network was supervised throughout, on Linux.
+    const supervisor=tests&&stats?supervisorIssue(stats):null;
     // A failure both ways counts as the same only without a sign of a refusal.
-    const denied=sandboxed.status===0?null:denialLine(sandboxed.output);
+    const denied=sandboxed.status===0?null:denialLine(sandboxed.output,entries);
     const realOf=dir=>{try{return fs.realpathSync(dir);}catch{return null;}},plainTmp=process.env.TMPDIR||os.tmpdir();
     const paths=[[home,'<home>'],[realOf(home),'<home>'],[tmp,'<tmp>'],[realOf(tmp),'<tmp>'],[plainTmp,'<tmp>'],[realOf(plainTmp),'<tmp>'],
       [os.homedir(),'<home>'],[realOf(os.homedir()),'<home>']];
@@ -390,7 +552,15 @@ export async function sandboxTrial(root,check,{timeout=300000}={}){
     let at=a.findIndex((line,i)=>line!==b[i]);
     if(at<0&&b.length>a.length)at=a.length;
     const output=at<0?null:{plain:(a[at]??'(no more output)').slice(0,160),sandboxed:(b[at]??'(no more output)').slice(0,160)};
-    return {same:plain.status===sandboxed.status&&!denied&&!output,plain:plain.status,sandboxed:sandboxed.status,output,
-      line:denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null)};
+    let launcher=null;if(stats)try{launcher=JSON.parse(fs.readFileSync(stats,'utf8'));}catch{}
+    // Tests print in an order their workers decide: the counts their summary
+    // gives are compared, not every line.
+    // When neither summary can be read, every line is compared, as for a typecheck.
+    const counts=tests?[plain,sandboxed].map(r=>testCounts(r.output)):null;
+    const read=counts?.some(c=>Object.values(c).some(value=>value!==null));
+    const differs=tests&&read?(JSON.stringify(counts[0])===JSON.stringify(counts[1])?null:{plain:JSON.stringify(counts[0]),sandboxed:JSON.stringify(counts[1])}):output;
+    return {same:plain.status===sandboxed.status&&!denied&&!differs&&!supervisor,plain:plain.status,sandboxed:sandboxed.status,output:differs,plainRun:plain,
+      line:supervisor||denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null),
+      ...hide?{hidden:entries.length,entries,plainMs:plain.ms,sandboxedMs:sandboxed.ms,...launcher?{rules:launcher.rules,setupMs:launcher.ms}:{}}:{}};
   }finally{fs.rmSync(scratch,{recursive:true,force:true});}
 }

package/src/stats.mjs

@@ -0,0 +1,72 @@
+// `redue stats`: what REDUE did for each check, from a local log. The hook,
+// `run --if-due` and recorded runs append one line each to stats-v1.jsonl in
+// the project's state: a skip (with the skipped run's duration), a recorded
+// run, or a check that was due (STALE or UNVERIFIED, with the reason). The log
+// stays on this machine and goes away with `redue remove-state`.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const statsFile=state=>path.join(state,'stats-v1.jsonl');
+
+// Never fails the command it is called from.
+export function note(state,entry){
+  try{fs.appendFileSync(statsFile(state),JSON.stringify({at:Date.now(),...entry})+'\n',{mode:0o600});}catch{}
+}
+
+// A skip of `name`, from a status row that allowed it.
+export const skipNote=(status,name,via)=>{
+  const ms=status?.checks?.find(row=>row?.name===name)?.invocation?.durationMs;
+  return {kind:'skip',check:name,via,savedMs:Number.isFinite(ms)&&ms>=0?ms:null};
+};
+// A check about to run because its last result does not apply, or null.
+export const dueNote=(status,name)=>{
+  const row=status?.observation?.healthy===true?status.checks?.find(item=>item?.name===name):null;
+  return row&&row.freshness!=='CURRENT'?{kind:'due',check:name,freshness:row.freshness,reason:row.reason??null}:null;
+};
+
+// Run ids, hashes and digits in a reason say nothing about its kind.
+const reasonKind=reason=>String(reason??'no reason').replace(/[0-9a-f]{8}(?:-?[0-9a-f]{4,})+|[0-9a-f]{12,}/g,'…').slice(0,160);
+
+export function readStats(state,names=[]){
+  let text='';try{text=fs.readFileSync(statsFile(state),'utf8');}catch{}
+  // Configured checks first, in config order, then any the log still names.
+  const checks=new Map();
+  const row=name=>{let value=checks.get(name);
+    if(!value)checks.set(name,value={name,skips:0,savedMs:0,runs:0,passed:0,failed:0,runMs:0,stale:0,unverified:0,reasons:{}});
+    return value;};
+  for(const name of names)row(name);
+  let since=null;
+  for(const line of text.split('\n')){
+    let entry;try{entry=JSON.parse(line);}catch{continue;}
+    if(typeof entry?.check!=='string')continue;
+    since??=entry.at;
+    const value=row(entry.check);
+    if(entry.kind==='skip'){value.skips++;value.savedMs+=entry.savedMs??0;}
+    else if(entry.kind==='run'){value.runs++;value.runMs+=entry.ms??0;
+      if(entry.result==='PASS')value.passed++;else if(entry.result==='FAIL')value.failed++;}
+    else if(entry.kind==='due'&&entry.freshness==='STALE')value.stale++;
+    else if(entry.kind==='due'&&entry.freshness==='UNVERIFIED'){value.unverified++;
+      const kind=reasonKind(entry.reason);value.reasons[kind]=(value.reasons[kind]??0)+1;}
+  }
+  const list=[...checks.values()].map(({reasons,...value})=>({...value,
+    topUnverified:Object.entries(reasons).sort((a,b)=>b[1]-a[1]).slice(0,3).map(([reason,count])=>({reason,count}))}));
+  return {schema:1,since:since===null?null:new Date(since).toISOString(),checks:list};
+}
+
+export const duration=ms=>!ms?'0s':ms<60_000?`${(ms/1000).toFixed(ms<10_000?1:0)}s`:
+  ms<3_600_000?`${Math.floor(ms/60_000)}m ${Math.round(ms%60_000/1000)}s`:`${Math.floor(ms/3_600_000)}h ${Math.round(ms%3_600_000/60_000)}m`;
+
+export function renderStats(value){
+  if(!value.since)return 'No skips or recorded runs yet.';
+  const head=['check','skips','saved','runs','pass','fail','stale','unverified'];
+  const rows=value.checks.map(c=>[c.name,c.skips,duration(c.savedMs),c.runs,c.passed,c.failed,c.stale,c.unverified].map(String));
+  const total=value.checks.reduce((sum,c)=>({skips:sum.skips+c.skips,savedMs:sum.savedMs+c.savedMs}),{skips:0,savedMs:0});
+  const widths=head.map((h,i)=>Math.max(h.length,...rows.map(r=>r[i].length)));
+  const line=r=>r.map((cell,i)=>i?cell.padStart(widths[i]):cell.padEnd(widths[i])).join('  ');
+  const lines=[`Since ${value.since.slice(0,10)}: ${total.skips} skips saved ${duration(total.savedMs)}.`,'',line(head),...rows.map(line)];
+  const reasons=value.checks.filter(c=>c.topUnverified.length);
+  if(reasons.length){lines.push('','Why checks were UNVERIFIED when they were due:');
+    for(const c of reasons)for(const r of c.topUnverified)lines.push(`  ${c.name}  ${r.count}×  ${r.reason}`);}
+  lines.push('','Saved is the duration of the run each skip reused.');
+  return lines.join('\n');
+}