@redue/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/src/test-direct.mjs

@@ -10,11 +10,13 @@ import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {fileURLToPath} from 'node:url';
 import {spawnSync} from 'node:child_process';
-import micromatch from './glob.mjs';
+import {patternMatcher} from './glob.mjs';
 import {runFact} from './direct-run-certificate.mjs';
 import {queryAnswer} from './typescript-list.mjs';
-import {pnpmInstallInfo,pnpmProjectInfo} from './pnpm-inputs.mjs';
+import {pnpmInstallInfo,pnpmProjectInfo,yaml} from './pnpm-inputs.mjs';
 import {workspaceManifests} from './workspace-manifests.mjs';
+import {atomicJson} from './state-store.mjs';
+import {racyUntil} from './path-identity.mjs';
 
 const digest=value=>createHash('sha256').update(value).digest('hex');
 export const testRecorder=fileURLToPath(new URL('test-recorder.cjs',import.meta.url));
@@ -59,15 +61,17 @@ export function recordedEnvironment(guardFile,env=process.env) {
 // input (relative path) at the start checkpoint to its digest; `runner` is the
 // PID of the process REDUE started. Returns {issues, runFacts, environmentReads,
 // isOutput}: environmentReads maps each variable the run read directly to the
-// caller's value digest, or '<unset>'.
-export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=testEnvironment,coverage=null}) {
+// caller's value digest, or '<unset>'. `programs` is the general recipe's
+// account of processes (node-script.mjs): `judge(child, parentMain)` says
+// whether a started program is accounted for and must load the recorder,
+// `runner` describes the program REDUE started, and `trusted` names checkout
+// paths (runner caches) whose use is not an input.
+export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=testEnvironment,coverage=null,programs=null}) {
   // The recipe's variables and any the project declares are compared, not guarded.
   const compared=name=>(environment.variables||[]).includes(name)||
     (environment.prefixes||[]).some(prefix=>name.toLowerCase().startsWith(prefix.toLowerCase()));
   const issues=[],add=issue=>{if(!issues.includes(issue))issues.push(issue);};
-  const positive=sourcePatterns.filter(p=>!p.startsWith('!')).map(p=>micromatch.matcher(p,{dot:true}));
-  const negative=sourcePatterns.filter(p=>p.startsWith('!')).map(p=>micromatch.matcher(p.slice(1),{dot:true}));
-  const included=rel=>positive.some(fn=>fn(rel))&&!negative.some(fn=>fn(rel));
+  const included=patternMatcher(sourcePatterns);
   const observed=rel=>Object.hasOwn(files||{},rel);
   const headers=new Map(),records=[];
   let names=[];
@@ -82,16 +86,28 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
     headers.set(`${header.pid}-${header.threadId}`,header);
     records.push({header,rows:rows.slice(1)});
   }
-  if(!headers.has(`${runner}-0`))add('the test runner did not load the REDUE recorder');
+  let opaque=false;
+  if(!programs){if(!headers.has(`${runner}-0`))add('the test runner did not load the REDUE recorder');}
+  else{const judged=programs.judge(programs.runner,null);
+    if(judged.issue)add(judged.issue);
+    else if(judged.needsHeader&&!headers.has(`${runner}-0`))add('the package manager did not load the REDUE recorder');
+    opaque||=Boolean(judged.opaque);}
+  const trusted=programs?.trusted?patternMatcher(['**',...programs.trusted.map(pattern=>'!'+pattern)]):null;
+  // A cache directory itself, and everything in it.
+  const isTrusted=rel=>trusted!==null&&(!trusted(rel)||!trusted(rel+'/_'));
   // Answers per question; a question answered two ways changed during the run.
   const answers=new Map(),ask=(key,answer)=>{const set=answers.get(key)||new Set();set.add(JSON.stringify(answer));answers.set(key,set);};
-  const reads=new Map(),produced=new Set(),created=new Set(),environmentReads={},spawned=new Map();
+  // Every child with a PID, accepted shells too: a header with one of these
+  // PIDs is that child, not an execSync child (which reports no PID).
+  const installedWrites=new Set();
+  const reads=new Map(),produced=new Set(),created=new Set(),environmentReads={},spawned=new Map(),childPids=new Map();
   for(const {header,rows} of records){
     for(const row of rows){
       const [kind,...value]=Array.isArray(row)?row:[];
       if(kind==='U')add(`recorder: ${value[0]}`);
       else if(kind==='R')reads.set(value[0],reads.get(value[0])||value[1]===true);
       else if(kind==='P')produced.add(path.join(root,value[0]));
+      else if(kind==='I')installedWrites.add(value[0]);
       else if(kind==='M')created.add(value[0]);
       else if(kind==='L')ask(`stat\0${value[0]}`,value[1]);
       else if(kind==='D')ask(`entries\0${value[0]}`,value[1]);
@@ -101,7 +117,15 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
         environmentReads[name]=typeof state==='string'?state:'<unset>';}
       else if(kind==='N')add(`network: ${value[0]}`);
       else if(kind==='C'||kind==='S'){
-        const list=spawned.get(header.pid)||[];list.push({pid:kind==='C'?value[0]:null,file:value[kind==='C'?1:0]});
+        const [file,args,cwd,searchPath,env,script]=kind==='C'?value.slice(1):value;
+        if(kind==='C')childPids.set(header.pid,[...childPids.get(header.pid)||[],value[0]]);
+        // The general recipe accounts for each program; one that needs no
+        // recorder (a shell, the pnpm executable) is not matched to a header.
+        if(programs){const judged=programs.judge({file,args,cwd,searchPath,env,script},header.main??null);
+          if(judged.issue){add(judged.issue);continue;}
+          opaque||=Boolean(judged.opaque);
+          if(!judged.needsHeader)continue;}
+        const list=spawned.get(header.pid)||[];list.push({pid:kind==='C'?value[0]:null,file});
         spawned.set(header.pid,list);}
       else if(kind==='T'){if(!headers.has(`${header.pid}-${value[0]}`))add('a worker thread did not load the REDUE recorder');}
       else if(kind!=='H')add('a run record is unreadable');
@@ -114,9 +138,14 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
     const unknown=children.filter(child=>child.pid===null);
     for(const child of children)if(child.pid!==null&&!recorded.some(h=>h.pid===child.pid))
       add(`started ${path.basename(child.file)}, which REDUE does not record`);
-    const matched=recorded.filter(h=>!children.some(child=>child.pid===h.pid)).length;
+    const matched=recorded.filter(h=>!(childPids.get(parent)||[]).includes(h.pid)).length;
     if(unknown.length>matched)add(`started ${path.basename(unknown[0].file)}, which REDUE does not record`);
   }
+  // What the pnpm executable starts is not seen. Its node-options setting
+  // replaces NODE_OPTIONS for everything it starts, so a run through it must
+  // show at least one recorded Node process the recorded ones did not start.
+  if(opaque&&![...headers.values()].some(h=>h.threadId===0&&h.pid!==runner&&!headers.has(`${h.ppid}-0`)))
+    add('no Node process the pnpm executable started loaded the REDUE recorder');
   // Inside a directory the run created. A file the run wrote excuses nothing:
   // another process may have read it before the write. Listings may differ
   // by such files (listingAfter).
@@ -128,8 +157,11 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
   // (coverageReadable); its contents do not decide pass or fail.
   const inCoverage=rel=>coverage!==null&&(rel===coverage||rel.startsWith(coverage+'/'));
   // File content in the checkout must be an observed input.
+  // A runner cache is git-ignored; a file in a cache path git keeps is source.
+  const trustedReads=[...reads].filter(([rel,found])=>found&&isTrusted(rel)&&!inCreated(checkout(rel))).map(([rel])=>rel);
+  const ignoredCaches=gitIgnored(root,trustedReads);
   for(const [rel,found] of [...reads].sort(([a],[b])=>a<b?-1:a>b?1:0)){
-    if(inCreated(checkout(rel))||inCoverage(rel))continue;
+    if(inCreated(checkout(rel))||inCoverage(rel)||isTrusted(rel)&&(!found||ignoredCaches.has(rel)||produced.has(checkout(rel))))continue;
     if(!included(rel))add(`read ${rel}, which the check's inputs exclude`);
     else if(found&&!observed(rel))add(`read ${rel}, which REDUE does not observe (ignored by git)`);
     // A missing file may be ignored by git, so the index would not see it appear.
@@ -141,7 +173,7 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
     if(question==='stat'||question==='entries'){
       const full=checkout(where);
       // A path the run made answers differently afterwards; it is output, not input.
-      if(madeByRun(full)||produced.has(full)||inCoverage(where))continue;
+      if(madeByRun(full)||produced.has(full)||inCoverage(where)||isTrusted(where))continue;
       if(set.size>1){add(`${where} changed during the run`);continue;}
       if(question==='stat'){
         // Observed files and directories: the index covers them. A missing
@@ -173,7 +205,8 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
     produced.has(checkout(rel))&&reads.get(rel)!==true);
   return {issues:issues.length>issueLimit?[...issues.slice(0,issueLimit),`${issues.length-issueLimit} more`]:issues,
     runFacts:runFacts.length>factLimit?[]:[...new Map(runFacts.map(f=>[JSON.stringify(f),f])).values()],
-    environmentReads:Object.fromEntries(Object.entries(environmentReads).sort(([a],[b])=>a<b?-1:a>b?1:0)),isOutput};
+    environmentReads:Object.fromEntries(Object.entries(environmentReads).sort(([a],[b])=>a<b?-1:a>b?1:0)),isOutput,opaque,
+    wroteInstalled:rel=>installedWrites.has(rel)};
 }
 // The observed files that differ between two checkpoints' file maps.
 export function changedFiles(before,after){
@@ -336,21 +369,70 @@ export function testWorkspaceDirs(root,pkg){
 // Each node_modules the recipe observes as installed: the root's and every
 // workspace package's, relative to the root.
 const modulesDirs=({dirs=[]})=>['node_modules',...dirs.map(dir=>`${dir}/node_modules`)];
-// The first installed file with more than one link, or null. A package store
-// outside the checkout (pnpm's default on Linux, Yarn's hardlinks modes) can
-// change such a file with no event here. Checked at every recorded run: a later
-// install that adds links replaces the files, which is a change REDUE sees.
-export function sharedInstalledFile(root,project={}){
+// pnpm's content-addressed store, as the install recorded it in .modules.yaml:
+// files/<first 2 hex>/<rest of the content's sha512 hex>, "-exec" for
+// executables. pnpm writes new store files and never changes one in place.
+function pnpmStoreFiles(root){
+  try{const {storeDir}=yaml(path.join(root,'node_modules','.modules.yaml'));
+    return typeof storeDir==='string'&&path.isAbsolute(storeDir)?path.join(storeDir,'files'):null;}
+  catch{return null;}
+}
+const identity=st=>`${st.size}:${st.mtimeNs}:${st.ctimeNs}`;
+const sameFile=(file,st)=>{
+  try{const other=fs.statSync(file,{bigint:true});return other.dev===st.dev&&other.ino===st.ino;}
+  catch{return false;}};
+// The file's store path relative to `files`, or null when the store does not
+// hold this file at its content's address.
+function storePath(files,file,st){
+  const hash=createHash('sha512'),buffer=Buffer.alloc(1<<20),fd=fs.openSync(file,'r');
+  try{for(let n;(n=fs.readSync(fd,buffer,0,buffer.length,null))>0;)hash.update(buffer.subarray(0,n));}
+  finally{fs.closeSync(fd);}
+  const hex=hash.digest('hex'),at=path.join(hex.slice(0,2),hex.slice(2));
+  return [at,at+'-exec'].find(candidate=>sameFile(path.join(files,candidate),st))??null;
+}
+// The first installed file with more than one link, as {file, reason}, or
+// null. A package store outside the checkout (pnpm's default on Linux, Yarn's
+// hardlinks modes) can change such a file with no event here. A link into
+// pnpm's own store is accepted: the store's file is named by its content.
+// Checked at every recorded run: a later install that adds links replaces the
+// files, which is a change REDUE sees. `cache` (in owned state) keeps each
+// file found in the store with its identity and store path, so an unchanged
+// file is not hashed again; its store link is still checked.
+export function sharedInstalledFile(root,project={},cache=null){
   const stack=modulesDirs(project).map(dir=>path.join(root,dir));
+  const files=pnpmStoreFiles(root),now=Date.now();
+  let known={},changed=false;
+  if(files&&cache)try{const value=JSON.parse(fs.readFileSync(cache,'utf8'));
+    if(value?.files===files&&value.entries&&typeof value.entries==='object')known=value.entries;}catch{}
+  const found={};
+  const shared=(file,reason)=>({file:path.relative(root,file).split(path.sep).join('/'),reason});
   while(stack.length){
     const dir=stack.pop();let entries;
     try{entries=fs.readdirSync(dir,{withFileTypes:true});}catch{continue;}
     for(const entry of entries){
       const file=path.join(dir,entry.name);
-      if(entry.isDirectory())stack.push(file);
-      else if(entry.isFile())try{if(fs.lstatSync(file).nlink>1)return path.relative(root,file).split(path.sep).join('/');}catch{}
+      if(entry.isDirectory()){stack.push(file);continue;}
+      if(!entry.isFile())continue;
+      let st;try{st=fs.lstatSync(file,{bigint:true});}catch{continue;}
+      if(st.nlink<=1n)continue;
+      if(!files)return shared(file,'has another hard link, and the install records no pnpm store');
+      const key=`${st.dev}:${st.ino}`,cached=known[key];
+      let at=Array.isArray(cached)&&cached[0]===identity(st)&&typeof cached[1]==='string'&&
+        sameFile(path.join(files,cached[1]),st)?cached[1]:null;
+      if(!at){
+        try{at=storePath(files,file,st);}
+        catch(e){return shared(file,`could not be checked against pnpm's store (${e.code||e.message})`);}
+        if(!at)return shared(file,"has another hard link outside pnpm's store");
+        changed=true;
+      }
+      // A file changed within the racy window could change again unseen in
+      // the same timestamp tick; it is hashed again next time.
+      if(racyUntil(st)<=now)found[key]=[identity(st),at];
+      else changed=true;
     }
   }
+  if(files&&cache&&(changed||Object.keys(found).length!==Object.keys(known).length))
+    try{atomicJson(cache,{files,entries:found});}catch{}
   return null;
 }
 // The runner a package's script reaches: Node's lookup from the package

package/src/test-recorder.cjs

@@ -23,11 +23,15 @@ function install(){
   const emit=row=>{try{const line=Buffer.from(JSON.stringify(row)+'\n');
     for(let at=0;at<line.length;)at+=original.writeSync(fd,line,at,line.length-at);}catch{}};
   const failed=reason=>emit(['U',reason]);
-  emit(['H',{pid:process.pid,ppid:process.ppid,threadId}]);
+  // The main script tells the guard which program a process runs (a package
+  // manager may start helpers of its own).
+  emit(['H',{pid:process.pid,ppid:process.ppid,threadId,main:typeof process.argv[1]==='string'?process.argv[1]:null}]);
   // Every node_modules observed as installed: the root's and each workspace package's.
   const sep=path.sep,root=config.root,installed=Array.isArray(config.installed)?config.installed:[path.join(root,'node_modules')],
     tmp=config.tmp;
   const within=(file,dir)=>file===dir||file.startsWith(dir+sep);
+  let installedReal=null;
+  const realInstalled=()=>installedReal??=installed.map(dir=>realDir(dir));
   const digest=value=>createHash('sha256').update(value).digest('hex');
   // Directory realpaths, so a checkout path spelled through a link is still
   // classified as the checkout.
@@ -44,7 +48,8 @@ function install(){
   // The absolute path an argument names; undefined for a descriptor, whose
   // open was recorded; null for anything else.
   function located(file){
-    if(typeof file==='number')return undefined;
+    // A descriptor or a FileHandle: its open was recorded.
+    if(typeof file==='number'||file&&typeof file==='object'&&typeof file.fd==='number'&&typeof file.close==='function')return undefined;
     if(Buffer.isBuffer(file))file=file.toString();
     else if(file instanceof URL){if(file.protocol!=='file:')return null;file=require('node:url').fileURLToPath(file);}
     if(typeof file!=='string')return null;
@@ -75,18 +80,45 @@ function install(){
     if(!produced.size)return false;
     for(let at=full;;at=path.dirname(at)){if(produced.has(at))return true;if(path.dirname(at)===at)return false;}
   }
-  const runnerData=config.runnerData||[];
-  const runnerCache=full=>tmp.some(dir=>within(full,dir)&&full.slice(dir.length+1).split(sep)[0].startsWith('jest_'))||
+  // Runner data and the toolchain's own files (a package manager's install
+  // and logs) are not inputs.
+  const runnerData=[...(config.runnerData||[]),...(Array.isArray(config.toolchain)?config.toolchain:[])];
+  // Runner caches in the temporary directory, keyed by content: Jest's,
+  // Yarn 1's compile cache, tsx's, jiti's, ts-node's and Babel's.
+  const tmpCache=/^(?:jest_|v8-compile-cache|tsx-\d+$|jiti$|node-jiti$|ts-node|babel)/;
+  const runnerCache=full=>tmp.some(dir=>within(full,dir)&&tmpCache.test(full.slice(dir.length+1).split(sep)[0]))||
     runnerData.some(dir=>within(full,dir));
+  // A read of the process's own executable through /proc (detect-libc reads
+  // its ELF header there), when the process runs the Node on PATH, which the
+  // environment identifies by its file.
+  const ownExePath=process.platform==='linux'?`/proc/${process.pid}/exe`:null;
+  let ownExe;
+  const ownExecutable=(role,full)=>{
+    if(role!=='read'||full!==ownExePath)return false;
+    if(ownExe===undefined)try{ownExe=typeof config.node==='string'&&original.real(full)===config.node;}catch{ownExe=false;}
+    return ownExe;
+  };
   // One filesystem access by its role: read (content), produce, touch (a write
   // that keeps earlier content), mkdir, mkdtemp, list, stat or realpath.
   function access(role,file,error=null,result=undefined,recursive=false){
     try{
-      const full=located(file);
+      let full=located(file);
       if(full===undefined)return;
       if(full===null){if(!['produce','touch','mkdir'].includes(role))failed(`${role} of an unsupported path argument`);return;}
-      // Installed files are observed by identity.
-      if(installed.some(dir=>within(full,dir)))return;
+      // Installed files are observed by identity. A path under node_modules
+      // that a link leads out of the installed tree (a workspace package's
+      // link) is classified where it leads.
+      if(installed.some(dir=>within(full,dir))){
+        // A listing, lookup or realpath of the link itself follows it.
+        const real=['list','stat','realpath'].includes(role)?realDir(full):path.join(realDir(path.dirname(full)),path.basename(full));
+        // A write there is noted apart from checkout outputs: the guard does
+        // not see reads of installed files, so only named tool files use it.
+        if(real===full||realInstalled().some(dir=>within(real,dir))){
+          if(role==='produce'&&!error&&within(full,root))once(['I',rel(full)]);
+          return;
+        }
+        full=real;
+      }
       if(role==='produce'){if(!error)produced.add(full);if(!error&&within(full,root))once(['P',rel(full)]);return;}
       // A directory the run created held nothing before it, so everything in
       // it is the run's output, whichever process reads it.
@@ -105,7 +137,7 @@ function install(){
         else if(role==='list')emit(['D',rel(full),error?missing(error):entries(full)]);
         return;
       }
-      if(runnerCache(full))return;
+      if(runnerCache(full)||ownExecutable(role,full))return;
       // A small file read outside the checkout is kept by its content, as
       // queryAnswer's readFile hashes it, so status can ask again.
       if(role==='read'&&!error){
@@ -212,7 +244,8 @@ function install(){
       envSeen.add(key);emit(['E',key,caller[key]]);
     }catch{failed('recorder failure');}
   }
-  const recordingEnv=source=>new Proxy(source,{
+  const targets=new WeakMap();
+  const recordingEnv=source=>{const proxy=new Proxy(source,{
     ownKeys(t){const keys=Reflect.ownKeys(t),current={keys:new Set(keys),last:null,copy:nodeInternal()};enumeration=current;
       queueMicrotask(()=>{if(enumeration===current)enumeration=null;});return keys;},
     getOwnPropertyDescriptor(t,key){
@@ -225,7 +258,10 @@ function install(){
       return Reflect.get(t,key);},
     has(t,key){if(enumeration)enumeration.last=null;envRead(t,key);return Reflect.has(t,key);},
     set(t,key,value){t[key]=value;return true;},
-  });
+  });targets.set(proxy,source);return proxy;};
+  // PATH as a child receives it, read without recording a read.
+  const pathOf=env=>{try{const value=Reflect.get(targets.get(env)??env??{},'PATH');return typeof value==='string'?value:null;}
+    catch{return null;}};
   function wrapEnv(holder){
     let current=recordingEnv(holder.env);
     // Code that replaces the environment object keeps being recorded.
@@ -289,17 +325,63 @@ function install(){
     }
   // Child processes and threads must load this recorder too; the guard checks
   // for their headers. Children of execSync/execFileSync report no PID, so
-  // they are counted instead.
+  // they are counted instead. Each row names the program and its arguments
+  // as Node's spawn normalizes them (a `shell` option runs /bin/sh -c and the
+  // joined command), the working directory and PATH, so the guard can tell
+  // which program a name ran and read what a shell was asked to run.
+  // Arguments over 64 KB in all are left out (null).
+  const argsOf=args=>{try{const list=Array.isArray(args)?args.map(String):[];
+    return list.reduce((n,arg)=>n+arg.length,0)>65536?null:list;}catch{return null;}};
+  const normalized=(file,args,options,shell)=>{
+    if(!Array.isArray(args)){options=args;args=[];}
+    shell=options?.shell??shell;
+    if(!shell)return [String(file),argsOf(args)];
+    return [typeof shell==='string'?shell:'/bin/sh',['-c',[file,...args].join(' ')]];
+  };
+  // What the child's environment says: whether NODE_OPTIONS still loads this
+  // recorder for the same run (npm's and pnpm's `node-options` setting
+  // replaces it), and whether BASH_ENV is set (bash -c sources it).
+  const envFacts=lookupVar=>{
+    try{const options=lookupVar('NODE_OPTIONS');
+      return {preload:typeof options==='string'&&options.includes(__filename)&&lookupVar('REDUE_RUN_RECORD')===configFile,
+        bashEnv:Boolean(lookupVar('BASH_ENV'))};}
+    catch{return {preload:false,bashEnv:true};}
+  };
+  const envOf=env=>envFacts(name=>{const value=Reflect.get(targets.get(env)??env??{},name);return typeof value==='string'?value:undefined;});
+  const pairsOf=pairs=>envFacts(name=>{const pair=(pairs||[]).find(item=>typeof item==='string'&&item.startsWith(name+'='));
+    return pair?pair.slice(name.length+1):undefined;});
+  const where=options=>[path.resolve(typeof options?.cwd==='string'?options.cwd:options?.cwd instanceof URL?
+    require('node:url').fileURLToPath(options.cwd):'.'),pathOf(options?.env??process.env),envOf(options?.env??process.env)];
+  const optionsOf=(args,options)=>Array.isArray(args)?options:args;
+  // A #! script the child runs, as it is now: Yarn writes its bin wrappers
+  // into a temporary directory and removes them after the run.
+  function scriptOf(file,cwd,searchPath){
+    try{
+      const candidates=file.includes(sep)?[path.resolve(cwd,file)]:String(searchPath??'').split(path.delimiter).map(dir=>path.join(path.resolve(cwd,dir||'.'),file));
+      for(const candidate of candidates){
+        let st;try{st=original.statSync(candidate);}catch{continue;}
+        if(!st.isFile()||!(st.mode&0o111))continue;
+        if(st.size>16384)return null;
+        const text=original.readFileSync(candidate,'utf8');
+        return text.startsWith('#!')?{file:original.real(candidate),text}:null;
+      }
+    }catch{}
+    return null;
+  }
   const childProcess=require('node:child_process'),spawn=childProcess.ChildProcess.prototype.spawn;
   childProcess.ChildProcess.prototype.spawn=function(options){
     const result=spawn.call(this,options);
-    try{if(this.pid)emit(['C',this.pid,String(options?.file)]);}catch{failed('recorder failure');}
+    try{if(this.pid){const pair=(options?.envPairs||[]).find(item=>typeof item==='string'&&item.startsWith('PATH='));
+      emit(['C',this.pid,String(options?.file),argsOf(options?.args?.slice(1)),where(options)[0],pair?pair.slice(5):null,
+        pairsOf(options?.envPairs),scriptOf(String(options?.file),where(options)[0],pair?pair.slice(5):null)]);}}
+    catch{failed('recorder failure');}
     return result;
   };
   const spawnSync=childProcess.spawnSync;
   childProcess.spawnSync=function(file,...rest){
     const result=spawnSync.call(this,file,...rest);
-    try{if(result?.pid)emit(['C',result.pid,String(file)]);}catch{failed('recorder failure');}
+    try{if(result?.pid)emit(['C',result.pid,...normalized(file,rest[0],rest[1]),...where(optionsOf(rest[0],rest[1]))]);}
+    catch{failed('recorder failure');}
     return result;
   };
   for(const name of ['execSync','execFileSync']){
@@ -308,12 +390,17 @@ function install(){
       let started=true;
       try{return call.call(this,file,...rest);}
       catch(error){if(error?.code==='ENOENT'&&!error.pid)started=false;throw error;}
-      finally{if(started)emit(['S',String(file)]);}
+      finally{if(started)try{emit(['S',...name==='execSync'?normalized(file,[],rest[0],true):normalized(file,rest[0],rest[1]),
+        ...where(name==='execSync'?rest[0]:optionsOf(rest[0],rest[1]))]);}
+        catch{failed('recorder failure');}}
     };
   }
   const workers=require('node:worker_threads'),Worker=workers.Worker;
   workers.Worker=class extends Worker{
     constructor(...args){super(...args);try{emit(['T',this.threadId]);}catch{failed('recorder failure');}}
   };
+  // Node reads an environment file natively; this is the one JavaScript entry to it.
+  if(typeof process.loadEnvFile==='function'){const load=process.loadEnvFile;
+    process.loadEnvFile=function(file='.env',...rest){access('read',file);return load.call(this,file,...rest);};}
   try{Module.syncBuiltinESMExports();}catch{failed('recorder failure');}
 }

package/src/typescript-input-facts.mjs

@@ -9,7 +9,7 @@ import {timing} from './decision-profile.mjs';
 const require=createRequire(import.meta.url),hash=value=>createHash('sha256').update(value).digest('hex');
 const digestFile=file=>hash(fs.readFileSync(file));
 const fail=code=>{throw Object.assign(Error(code),{code});};
-export function typeScriptInputFacts(root,tsRoot,tsc){
+export function typeScriptInputFacts(root,tsRoot,tsc,config='tsconfig.json'){
   const configReads=new Set(),visited=new Set(),referenced=[];
   let buildInfo=null;
   let ts;try{ts=require(tsRoot);}catch{}
@@ -37,15 +37,15 @@ export function typeScriptInputFacts(root,tsRoot,tsc){
         parseConfig(reference.path.endsWith('.json')?reference.path:
           path.join(reference.path,'tsconfig.json'));
     };
-    parseConfig(path.join(root,'tsconfig.json'),true);
+    parseConfig(path.join(root,config),true);
   }else{
     // TypeScript 7's native compiler does not expose the previous config API.
     // Its CLI reports the effective config; restrict this path to one direct
     // config rather than guessing about extends/reference provenance.
-    const config=path.join(root,'tsconfig.json'),raw=fs.readFileSync(config,'utf8');
+    const file=path.join(root,config),raw=fs.readFileSync(file,'utf8');
     if(/"(?:extends|references|plugins|incremental|composite)"\s*:/.test(raw))
       fail('typescript-config-graph-unsupported');
-    const shown=spawnSync(process.execPath,[tsc,'--showConfig'],{cwd:root,
+    const shown=spawnSync(process.execPath,[tsc,'--showConfig','-p',config],{cwd:root,
       env:process.env,encoding:'utf8',timeout:probeTimeLeft(4000),maxBuffer:16*1024*1024,
       stdio:['ignore','pipe','pipe']});
     if(shown.error||shown.signal||shown.status!==0)fail('typescript-config-unavailable');
@@ -53,13 +53,13 @@ export function typeScriptInputFacts(root,tsRoot,tsc){
     if(effective.compilerOptions?.plugins?.length||
       effective.compilerOptions?.incremental||effective.compilerOptions?.composite)
       fail('typescript-config-graph-unsupported');
-    configReads.add(config);
+    configReads.add(file);
   }
   for(const file of configReads)if(!within(realObservedPath(file),root))
     fail('typescript-config-outside-repository');
   const listingStarted=performance.now();
-  const captured=process.argv.includes('--redue-checkpoint')?compilerFiles(tsRoot,root):null;
-  const listed=captured?{status:0,stdout:captured.files.join('\n')}:spawnSync(process.execPath,[tsc,'--noEmit','--listFilesOnly'],
+  const captured=process.argv.includes('--redue-checkpoint')?compilerFiles(tsRoot,root,config):null;
+  const listed=captured?{status:0,stdout:captured.files.join('\n')}:spawnSync(process.execPath,[tsc,'--noEmit','--listFilesOnly','-p',config],
     {cwd:root,env:process.env,encoding:'utf8',timeout:probeTimeLeft(process.platform==='win32'?10000:4000),
       maxBuffer:16*1024*1024,
       stdio:['ignore','pipe','pipe']});

package/src/typescript-invocation.mjs

@@ -0,0 +1,92 @@
+// The package-script forms of a standalone TypeScript check: one `tsc` run, or
+// several joined by `&&`, each with these arguments in any order:
+// --noEmit, -p/--project PATH, --skipLibCheck, --pretty [true|false].
+// Anything else (tsc -b, --watch, other options, other commands) is not one.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// No shell metacharacters; a leading @ would read as a REDUE token.
+const word=/^[A-Za-z0-9_./+-][A-Za-z0-9_./@+-]*$/;
+// More runs than this is not a script REDUE splits into checks.
+const maxRuns=16;
+function parseRun(words){
+  if(words[0]!=='tsc'||!words.every(value=>word.test(value)))return null;
+  let project=null,noEmit=false;
+  for(let i=1;i<words.length;i++){
+    const value=words[i];
+    if(value==='-p'||value==='--project'){
+      if(project!==null||!words[i+1]||words[i+1].startsWith('-'))return null;
+      project=words[++i];
+    }else if(value==='--noEmit')noEmit=true;
+    else if(value==='--pretty'){if(['true','false'].includes(words[i+1]))i++;}
+    else if(value!=='--skipLibCheck')return null;
+  }
+  return {args:words.slice(1),project,noEmit};
+}
+// The runs of a script, as [{args, project, noEmit}], or null.
+export function tscRuns(text){
+  if(typeof text!=='string'||!text.trim())return null;
+  const parts=text.trim().split(/[ \t]+&&[ \t]+/);
+  if(parts.length>maxRuns)return null;
+  const runs=parts.map(part=>parseRun(part.split(/[ \t]+/)));
+  return runs.every(Boolean)?runs:null;
+}
+// The run a check makes: its `script` (null for a check init proposed without
+// one), the tsc arguments after the compiler in its command, and `count`, the
+// number of configured checks for that script (more than one for a chain).
+// Returns {run} with the parsed run, or {issue} when the arguments are outside
+// the forms, or the script no longer has exactly `count` runs, one of them
+// with exactly these arguments.
+export function tscRun(scripts,{script=null,args,count=1}){
+  if(!Array.isArray(args)||!args.every(value=>typeof value==='string'))return {issue:'TypeScript arguments are invalid'};
+  const own=parseRun(['tsc',...args]);
+  if(!own)return {issue:'TypeScript arguments are outside the supported forms'};
+  if(script===null)return {run:own};
+  if(typeof scripts?.[script]!=='string')return {issue:'typecheck script was removed'};
+  if(scripts['pre'+script]||scripts['post'+script])return {issue:'typecheck script has pre or post scripts'};
+  const runs=tscRuns(scripts[script]);
+  if(runs?.length!==count||!runs.some(run=>JSON.stringify(run.args)===JSON.stringify(args)))
+    return {issue:'typecheck script changed'};
+  return {run:own};
+}
+// The config file a run names, relative to the directory `dir` it runs in
+// (posix): tsconfig.json without -p, a directory's tsconfig.json, or null
+// when it leaves that directory or the arguments are not a run.
+export function runConfig(dir,args){
+  const run=parseRun(['tsc',...args]);
+  if(!run)return null;
+  let file=path.posix.normalize((run.project??'tsconfig.json').split(path.sep).join('/'));
+  let directory=false;try{directory=fs.statSync(path.join(dir,file)).isDirectory();}catch{}
+  if(!file.endsWith('.json')||directory)file=path.posix.join(file,'tsconfig.json');
+  if(path.posix.isAbsolute(file)||file==='..'||file.startsWith('../'))return null;
+  return file;
+}
+// The check names for a script's runs: the kind's name for one run, and
+// NAME.1 ... NAME.n for a chain (not #: the hook refuses it and zsh may glob it).
+export const partName=(name,index,count)=>count===1?name:`${name}.${index}`;
+// Probe arguments for a run, and back: SCRIPT (or -), COUNT, then the tsc
+// arguments.
+export const runArgv=({script=null,args,count=1})=>[script??'-',String(count),...args];
+export function runFromArgv(values){
+  const [script,count,...args]=values;
+  if(typeof script!=='string'||!script||!/^[1-9]\d?$/.test(count||''))throw Object.assign(Error('probe-arguments'),{code:'probe-arguments'});
+  return {script:script==='-'?null:script,args,count:Number(count)};
+}
+// The run a configured check makes: its script, the arguments after the
+// compiler in its command, and how many checks the config has for the script
+// (`runCount`, set when the config is loaded).
+export const checkRun=check=>({script:check.script??null,
+  args:Array.isArray(check.command)?check.command.slice(2):[],count:check.runCount??1});
+// A script's checks in the order of its runs: one check per run with the same
+// arguments ({name, args} each), as names; null when they do not correspond.
+export function scriptRunChecks(text,checks){
+  const runs=tscRuns(text);
+  if(!runs||runs.length!==checks.length)return null;
+  const left=[...checks],names=[];
+  for(const run of runs){
+    const at=left.findIndex(check=>JSON.stringify(check.args)===JSON.stringify(run.args));
+    if(at<0)return null;
+    names.push(left.splice(at,1)[0].name);
+  }
+  return names;
+}

package/src/typescript-list.mjs

@@ -63,7 +63,7 @@ export function queriesMatch(queries) {
   return queries.every(([kind,file,answer,options])=>
     JSON.stringify(queryAnswer(kind,file,options))===JSON.stringify(answer));
 }
-export function compilerFiles(tsRoot,cwd) {
+export function compilerFiles(tsRoot,cwd,config='tsconfig.json') {
   const require=createRequire(import.meta.url),ts=require(tsRoot);
   if(typeof ts.createProgram!=='function'||typeof ts.createCompilerHost!=='function')return null;
   const queries=new Map();
@@ -114,7 +114,7 @@ export function compilerFiles(tsRoot,cwd) {
   };
   const realpath=file=>{remember('realpath',file);return ts.sys.realpath(file);};
   // `extends` of a package config resolves through realpath too.
-  const parsed=ts.getParsedCommandLineOfConfigFile(path.join(cwd,'tsconfig.json'),{},
+  const parsed=ts.getParsedCommandLineOfConfigFile(path.join(cwd,config),{},
     {...ts.sys,readFile,fileExists,directoryExists,getDirectories,readDirectory,realpath,
       onUnRecoverableConfigFileDiagnostic(){}});
   if(!parsed||parsed.errors?.length)throw Error('TypeScript configuration unavailable');

package/src/typescript-qualification.mjs

@@ -2,6 +2,7 @@ import {directProject,directQualification,directEnvironment} from './direct-type
 import fs from 'node:fs';
 import path from 'node:path';
 import {realObservedPath} from './path-identity.mjs';
+import {checkRun,runArgv} from './typescript-invocation.mjs';
 
 // This is a machine-enforced contract, not a claim inferred from a script name.
 // Runtime validation checks effective compiler membership, configuration and
@@ -11,10 +12,9 @@ export function qualifyTypeScript(root,selected,discovered={}) {
   if(selected.qualification===directQualification){
     const issues=[];
     try{
-      const compiler=directProject(root,selected.script);
-      if(selected.command?.length!==3||selected.command[0]!==process.execPath||
-        selected.command[1]!==compiler.entry||selected.command[2]!=='--noEmit'||
-        selected.cwd&&selected.cwd!=='.')issues.push('direct compiler invocation changed');
+      const compiler=directProject(root,checkRun(selected));
+      if(selected.command?.[0]!==process.execPath||
+        selected.command[1]!==compiler.entry||selected.cwd&&selected.cwd!=='.')issues.push('direct compiler invocation changed');
     }catch(e){issues.push(e.code||'direct compiler prerequisites unavailable');}
     if(!selected.inputs?.includes('**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc}')||
       !selected.inputs?.includes('package.json')||!selected.inputs?.includes('tsconfig.json')||
@@ -24,23 +24,22 @@ export function qualifyTypeScript(root,selected,discovered={}) {
       !directEnvironment.prefixes.every(key=>selected.environment?.prefixes?.includes(key)))
       issues.push('direct compiler execution context incomplete');
     if(selected.probes?.length!==1||!selected.probes?.some(argv=>path.basename(argv[1]||'')==='direct-typescript-probe.mjs'&&
-      argv[0]===process.execPath&&argv[2]===root&&argv[3]===selected.script))issues.push('direct compiler probe missing');
+      argv[0]===process.execPath&&argv[2]===root&&
+      JSON.stringify(argv.slice(3))===JSON.stringify(runArgv(checkRun(selected)))))issues.push('direct compiler probe missing');
     return {qualified:issues.length===0,issues};
   }
   if(selected.qualification==='pnpm-tsc-v1'){
     const issues=[];
     const workspace=selected.workspace||'.';
-    const script=selected.script||selected.command?.at(-1);
     try{
       if(discovered.issue)throw Error(discovered.issue);
       const contract=discovered.workspace;
       if(!contract)throw Error('pnpm TypeScript input discovery unavailable');
       issues.push(...contract.limitations);
-      const declared=contract.workspace.pkg.scripts[script].trim().split(/\s+/).slice(1);
+      // The arguments are checked against the script by the contract itself.
       if(path.resolve(root,selected.cwd||'.')!==path.join(root,contract.workspace.dir)||
         selected.command?.[0]!==process.execPath||
-        selected.command?.[1]!==contract.tsc||
-        JSON.stringify(selected.command.slice(2))!==JSON.stringify(declared))
+        selected.command?.[1]!==contract.tsc)
         issues.push('standalone TypeScript invocation changed');
     }catch(e){issues.push(e.message);}
     if(!selected.probes?.some(argv=>path.basename(argv[1]||'')==='pnpm-typecheck-probe.mjs'))

package/src/workspace-manifests.mjs

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {spawnSync} from 'node:child_process';
-import micromatch from './glob.mjs';
+import {patternMatcher} from './glob.mjs';
 
 export function workspaceManifests(root,patterns) {
   const listing=spawnSync('git',['ls-files','--cached','--others','--exclude-standard',
@@ -12,11 +12,10 @@ export function workspaceManifests(root,patterns) {
     env:{...process.env,GIT_OPTIONAL_LOCKS:'0'}});
   if(listing.status!==0||listing.error)throw Error('workspace package manifests cannot be inspected');
   // `!pattern` entries exclude, as in pnpm-workspace.yaml.
-  const positive=patterns.filter(p=>!p.startsWith('!')),negative=patterns.filter(p=>p.startsWith('!')).map(p=>p.slice(1));
+  const included=patternMatcher(patterns);
   const matched=listing.stdout.split('\0').filter(Boolean).filter(file=>{
     const dir=path.posix.dirname(file);
-    return dir!=='.'&&!dir.split('/').includes('node_modules')&&
-      micromatch.isMatch(dir,positive,{dot:true})&&!(negative.length&&micromatch.isMatch(dir,negative,{dot:true}));
+    return dir!=='.'&&!dir.split('/').includes('node_modules')&&included(dir);
   }).sort();
   if(matched.length>50)throw Error('more than 50 workspace packages found; select checks explicitly');
   return matched.map(file=>({file,pkg:JSON.parse(fs.readFileSync(path.join(root,file),'utf8'))}));