@redue/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/pnpm-shims.mjs

@@ -0,0 +1,54 @@
+// pnpm's launchers. On macOS and Linux, pnpm writes each node_modules/.bin
+// entry as a `#!/bin/sh` script that finds its own directory (with sed,
+// dirname, readlink, uname or printf, depending on the pnpm release), sets
+// NODE_PATH and execs Node on the package's bin file. A launcher is trusted only
+// when its text is one of the templates pnpm releases write
+// (pnpm-shim-templates.json, built by eval/pnpm-shim-templates.mjs), with only
+// the NODE_PATH value, the bin file and the trailing target comment filled in.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const templates=JSON.parse(fs.readFileSync(new URL('pnpm-shim-templates.json',import.meta.url),'utf8')).templates;
+const known=new Set(templates.map(row=>row.template));
+// A value with no quote, expansion, escape or line break: it stays literal in
+// the shell.
+const literal=/^[^"$`\\\n]*$/;
+
+// The launcher's text as a template, with the values it fills in, or null
+// when it does not have pnpm's form.
+export function shimTemplate(text){
+  if(typeof text!=='string'||!text.startsWith('#!/bin/sh\n'))return null;
+  let template=text,nodePath=null;
+  // NODE_PATH, set alone or in front of the caller's.
+  const alone=/\n  export NODE_PATH="([^"\n]*)"\n/.exec(text);
+  if(alone){
+    nodePath=alone[1];
+    // Each entry is literal, or relative to the launcher's own directory
+    // ($basedir_abs, which pnpm 12.6 and later write).
+    if(!nodePath.split(':').every(entry=>literal.test(entry.replace(/^\$basedir(?:_abs)?\//,'')))||
+      !text.includes(`\n  export NODE_PATH="${nodePath}:$NODE_PATH"\n`))return null;
+    template=template.split(`\n  export NODE_PATH="${nodePath}:$NODE_PATH"\n`).join('\n  export NODE_PATH="@@NODE_PATH@@:$NODE_PATH"\n')
+      .split(`\n  export NODE_PATH="${nodePath}"\n`).join('\n  export NODE_PATH="@@NODE_PATH@@"\n');
+  }
+  // The bin file, relative to the launcher's directory, after $basedir,
+  // $basedir_abs or $basedir_win; `node` and `node.exe` there are Node itself.
+  const targets=new Set([...template.matchAll(/"\$basedir(?:_abs|_win)?\/([^"\n]+)"/g)].map(match=>match[1])
+    .filter(value=>value!=='node'&&value!=='node.exe'));
+  if(targets.size!==1)return null;
+  const [target]=targets;
+  if(!literal.test(target))return null;
+  for(const prefix of ['$basedir','$basedir_abs','$basedir_win'])
+    template=template.split(`"${prefix}/${target}"`).join(`"${prefix}/@@TARGET@@"`);
+  // pnpm 11 and later end with a comment naming the target.
+  template=template.replace(/\n# cmd-shim-target=[^\n]*\n?$/,'\n# cmd-shim-target=@@COMMENT@@\n');
+  return {template,nodePath,target};
+}
+// The bin file a pnpm launcher runs with Node, as an absolute path, or null
+// when `file` is not a launcher pnpm writes.
+export function pnpmShimTarget(file,text=null){
+  try{
+    text??=fs.readFileSync(file,'utf8');
+    const shim=shimTemplate(text);
+    return shim&&known.has(shim.template)?path.resolve(path.dirname(file),shim.target):null;
+  }catch{return null;}
+}

package/src/pnpm-typecheck-probe.mjs

@@ -7,14 +7,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {pnpmTypecheckInputs} from './pnpm-inputs.mjs';
+import {patternMatcher} from './glob.mjs';
 import {withinPath as within,realObservedPath} from './path-identity.mjs';
+import {runFromArgv} from './typescript-invocation.mjs';
 
-const [rootArg,workspace,script]=process.argv.slice(2);
+const [rootArg,workspace,...rest]=process.argv.slice(2).filter(value=>!value.startsWith('--redue-'));
 const hash=value=>createHash('sha256').update(value).digest('hex');
 const digest=file=>hash(fs.readFileSync(file));
 const fail=code=>{throw Object.assign(Error(code),{code});};
 try{
-  if(!rootArg||!workspace||!script)fail('probe-arguments');
+  if(!rootArg||!workspace)fail('probe-arguments');
+  const run=runFromArgv(rest);
   const root=realObservedPath(rootArg);
   if(process.env.NODE_OPTIONS||process.env.NODE_PATH||process.env.BASH_ENV||
     process.env.ENV||Object.entries(process.env).some(([key,value])=>{
@@ -24,23 +27,25 @@ try{
       return /^(PNPM_|COREPACK_|npm_config_|DYLD_|TSGO_)/i.test(key);
     }))
     fail('pnpm-execution-environment-unsupported');
-  const contextHash=hash(JSON.stringify([root,workspace,script,process.version]));
+  const contextHash=hash(JSON.stringify([root,workspace,run,process.version]));
   if(contextOnly(contextHash))process.exit(0);
-  const contract=pnpmTypecheckInputs(root,workspace,script,{captureQueries:process.argv.includes('--redue-checkpoint')});
+  const contract=pnpmTypecheckInputs(root,workspace,run,{captureQueries:process.argv.includes('--redue-checkpoint')});
   if(contract.limitations.length)fail('pnpm-input-coverage-unavailable');
   const selected=path.join(root,contract.workspace.dir),tsc=contract.tsc;
   const inputs=contract.listedFiles;
   if(!inputs.length)fail('typescript-input-list-unavailable');
-  const inputRoots=[path.join(selected,'src'),...contract.generated.map(pattern=>
+  const inputRoots=[...contract.generated.map(pattern=>
     path.join(root,pattern.slice(0,-3))),...contract.installed.filter(p=>!p.startsWith('!'))
       .map(pattern=>path.join(root,pattern.slice(0,-3)))];
+  const isSource=patternMatcher(contract.sourcePatterns);
   for(const file of inputs)if(!within(file,root)||
+    !isSource(path.relative(root,file).split(path.sep).join('/'))&&
     !inputRoots.some(boundary=>within(file,boundary)))
     fail('typescript-input-outside-pnpm-contract');
   const files=[...new Set(inputs)].sort().map(file=>
     [hash(path.relative(root,file)),digest(file)]);
   const configs=contract.configs.map(file=>[hash(file),digest(path.join(root,file))]);
-  probeResult(hash(JSON.stringify({schema:1,workspace,script,
+  probeResult(hash(JSON.stringify({schema:1,workspace,run,
     files,configs,node:process.version,tsc:digest(tsc),
     packageManager:contract.install.version,linker:contract.install.linker})),contextHash,contract.discoveryQueries);
 }catch(e){console.error(`VSTATE_REASON:${e.code&&/^[a-z-]+$/.test(e.code)?e.code:

package/src/presentation.mjs

@@ -1,4 +1,9 @@
 // Presentation consumes evidence; it never grants applicability.
+// The recipe that made a receipt, by the qualification it names.
+const recipes={'npm-typescript-direct-v1':'direct TypeScript recipe','npm-tests-direct-v1':'direct test recipe',
+  'node-script-v1':'general recipe','pnpm-tsc-v1':'pnpm TypeScript recipe','yarn-workspace-tsc-v1':'Yarn workspace TypeScript recipe',
+  'typescript-noemit-v1':'npm TypeScript recipe'};
+export const recipeLabel=recipe=>recipes[recipe]??null;
 export function checkLabel(row) {
   return row.result==='FAIL'?'FAILED':row.freshness;
 }
@@ -21,7 +26,8 @@ export function renderStatus(value,{short=false}={}) {
     const label=checkLabel(row),symbol=label==='CURRENT'&&row.result==='PASS'?'✓':label==='FAILED'?'✗':'?';
     const mark=label==='STALE'?'⚠':symbol;
     const historical=row.result?` / ${row.result}`:'';
-    lines.push(`${mark} ${row.name}  ${label}${historical}`);
+    const recipe=label==='CURRENT'?recipeLabel(row.recipe):null;
+    lines.push(`${mark} ${row.name}  ${label}${historical}${recipe?`  (${recipe})`:''}`);
     if(label!=='CURRENT')lines.push(`  ${row.result==='FAIL'?`Historical failure; applicability ${row.freshness}. `:''}${explanation(row)}`);
   }
   if(!lines.length)lines.push('UNVERIFIED — observation is initializing; no check state is available yet.');
@@ -33,6 +39,8 @@ export function renderExplain(value,name) {
   return rows.map(row=>{
     const lines=[`${row.name}: ${checkLabel(row)}${row.result?` / ${row.result}`:''}`];
     if(row.result==='FAIL')lines.push(`Historical failure; applicability: ${row.freshness}.`);
+    if(row.verification_recipe==='npm-direct-typescript@1')lines.push('Recorded recipe: direct local TypeScript compiler; npm and lifecycle scripts were not executed.');
+    else if(recipeLabel(row.recipe))lines.push(`Recorded recipe: ${recipeLabel(row.recipe)}.`);
     lines.push(explanation(row));
     if(row.changed_inputs?.length)lines.push('Relevant inputs changed:',...row.changed_inputs.map(file=>`  ${file}`));
     if(row.freshness==='STALE')lines.push(`Due again when verification is needed: redue run ${JSON.stringify(row.name)}`);

package/src/probe-deadline.mjs

@@ -0,0 +1,37 @@
+// How long a full probe may run before it is killed and the check stays
+// UNVERIFIED. It grows with the project: the larger of the hint from earlier
+// probes (twice the last successful one, or twice the deadline that last timed
+// out) and the last completed run, between the platform floor and a ceiling.
+import {fileURLToPath} from 'node:url';
+export const probeCeilingMs=process.env.VSTATE_TEST_FAULTS==='1'&&
+  Number(process.env.VSTATE_TEST_PROBE_CEILING_MS)||60000;
+// Supported TypeScript probes perform bounded input/toolchain hashing.
+// Native NTFS runs have exceeded the generic 5 s cap under load, despite
+// completing normally and with the duplicated work already removed.
+export const probeFloorMs=qualification=>qualification==='pnpm-tsc-v1'||
+  (process.platform==='win32'&&['typescript-noemit-v1','npm-typescript-direct-v1','yarn-workspace-tsc-v1']
+    .includes(qualification))?10000:5000;
+// REDUE's own probes, which accept --redue-deadline; a user's probe never gets it.
+const builtIn=new Set(['typescript-contract-probe.mjs','direct-typescript-probe.mjs',
+  'yarn-workspace-typecheck-probe.mjs','pnpm-typecheck-probe.mjs'].map(name=>fileURLToPath(new URL(name,import.meta.url))));
+export const builtInProbe=argv=>builtIn.has(argv?.[1]);
+// A deadline read from status.json, as a whole number of milliseconds no
+// longer than a decision could need (0 when absent or unusable).
+export function publishedDeadline(value) {
+  return Number.isFinite(value)&&value>0?Math.min(Math.round(value),10*60*1000):0;
+}
+export function probeDeadline({floor,hint=0,runMs=0,ceiling=probeCeilingMs}) {
+  const finite=value=>Number.isFinite(value)&&value>0?value:0;
+  return Math.round(Math.min(ceiling,Math.max(floor,finite(hint),finite(runMs))));
+}
+// The hint the next probe starts from.
+export function nextProbeHint({durationMs,deadlineMs,timedOut}) {
+  return 2*(timedOut?deadlineMs:durationMs);
+}
+// Inside a probe process: what is left of the deadline its caller passed with
+// --redue-deadline=MS, or the fallback when none was passed. An inner call
+// always ends before its parent is killed, so it never outlives the probe.
+export function probeTimeLeft(fallback) {
+  const deadline=Number(/^--redue-deadline=(\d+)$/.exec(process.argv.find(arg=>arg.startsWith('--redue-deadline='))||'')?.[1]);
+  return deadline?Math.max(1,Math.round(deadline-performance.now()-250)):fallback;
+}

package/src/probe-result.mjs

@@ -9,11 +9,15 @@ export function contextOnly(context) {
   }
   return false;
 }
-export function probeResult(output,context,queries=null) {
+// A layout lets a recorded run rebuild the output after a content-only edit.
+export function probeResult(output,context,queries=null,layout=null) {
   if(!process.argv.includes('--redue-checkpoint')){process.stdout.write(output);return;}
   const raw=queries?JSON.stringify(queries):null;
-  let value=JSON.stringify({output,context,queryData:raw&&Buffer.byteLength(raw)<=8*1024*1024?
-    deflateSync(raw).toString('base64'):null});
+  const queryData=raw&&Buffer.byteLength(raw)<=8*1024*1024?deflateSync(raw).toString('base64'):null;
+  let value=JSON.stringify({output,context,queryData,
+    ...(layout?{layoutData:deflateSync(JSON.stringify(layout)).toString('base64')}:{})});
+  // The layout is dropped first: it only shortens the run after an edit.
+  if(Buffer.byteLength(value)>512*1024)value=JSON.stringify({output,context,queryData});
   // Optimization metadata must not overflow the ordinary probe channel.
   // Larger contracts keep the normal complete probe, without result reuse.
   if(Buffer.byteLength(value)>512*1024)value=JSON.stringify({output,context,queries:null});

package/src/project-location.mjs

@@ -0,0 +1,34 @@
+// Shared project selection only; evidence and caller-context semantics stay in the kernel.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {realObservedPath} from './path-identity.mjs';
+import {stateIdentity,userStateBase} from './platform-state.mjs';
+
+export function discoverConfig(cwd=process.cwd()) {
+  let dir=path.resolve(cwd);const found=[];
+  for(;;){
+    for(const name of ['redue.config.json','vstate.config.json']) {
+      const file=path.join(dir,name);
+      if(fs.existsSync(file))found.push(file);
+    }
+    if(fs.existsSync(path.join(dir,'.git'))||path.dirname(dir)===dir)break;
+    dir=path.dirname(dir);
+  }
+  if(found.length>1)throw Error('multiple REDUE configurations apply; select the intended one with --config FILE');
+  return found[0]||path.resolve(cwd,'redue.config.json');
+}
+export function canonicalConfig(configFile) {
+  return path.join(realObservedPath(path.dirname(configFile)),path.basename(configFile));
+}
+export function projectState(root,configFile) {
+  return path.join(userStateBase(process.platform,process.env,os.homedir()),'vstate',
+    `vstate-${createHash('sha256').update(stateIdentity(root)+'\0'+stateIdentity(canonicalConfig(configFile))).digest('hex').slice(0,16)}`);
+}
+export function readProject(configFile) {
+  const config=JSON.parse(fs.readFileSync(configFile,'utf8'));
+  if(config.schema!==1||!Array.isArray(config.checks)||!config.checks.length)
+    throw Error('config needs schema 1 and at least one check');
+  return {config,root:realObservedPath(path.resolve(path.dirname(configFile),config.root||'.'))};
+}

package/src/run-recorder.cjs

@@ -0,0 +1,91 @@
+// Preload for a direct compiler run: node --require <this> <tsc> ... with a
+// pipe on fd 3. Records the answers the compiler received from node:fs, in the
+// terms of queryAnswer, and writes them to fd 3 at exit. It never changes an
+// answer, an output or the exit code; any failure only makes the record unusable.
+'use strict';
+const fs=require('node:fs'),path=require('node:path'),{createHash}=require('node:crypto');
+const original={readFileSync:fs.readFileSync,statSync:fs.statSync,readdirSync:fs.readdirSync,
+  realpathSync:fs.realpathSync,native:fs.realpathSync.native,writeSync:fs.writeSync,openSync:fs.openSync};
+const real=file=>(process.platform==='win32'?original.native:original.realpathSync)(file);
+const facts=new Map(),compilerReads=new Set();let unsupported=null,conflict=null,main=null,compilerRoot=null;
+try{main=real(process.argv[1]);compilerRoot=path.dirname(path.dirname(main));}
+catch{unsupported='main module unavailable';}
+const kindOf=st=>st.isFile()?'f':st.isDirectory()?'d':'o';
+const missing=error=>['ENOENT','ENOTDIR'].includes(error?.code);
+// The compiler tree (lib/<entry>/../..) is covered by the daemon's toolchain
+// identity, not by this record. tsc also stats a case-swapped copy of its own path.
+const inCompiler=full=>full===compilerRoot||full.startsWith(compilerRoot+path.sep)||
+  full!==main&&full.toLowerCase()===main.toLowerCase();
+function observe(kind,call,answer) {
+  return function(file,...rest){
+    let value,full=null;
+    // Compiler-tree reads are named only: which lib files a program loads.
+    try{if(typeof file==='string'){full=path.resolve(file);
+      if(inCompiler(full)){if(kind==='read')compilerReads.add(full);full=null;}}
+      else unsupported??=`${kind} of a non-string path`;}
+    catch{unsupported??='recorder failure';}
+    if(full===null)return call.call(this,file,...rest);
+    let recorded;
+    try{value=call.call(this,file,...rest);}
+    catch(error){recorded=missing(error)?null:{error:error?.code||'error'};note(kind,full,recorded);throw error;}
+    try{recorded=answer(value,file);}catch{unsupported??='recorder failure';return value;}
+    note(kind,full,recorded);
+    return value;
+  };
+}
+function note(kind,full,answer) {
+  try{const key=kind+'\0'+full,value=JSON.stringify(answer),seen=facts.get(key);
+    if(seen===undefined)facts.set(key,value);else if(seen!==value)conflict??=`${kind} ${full}`;}
+  catch{unsupported??='recorder failure';}
+}
+fs.readFileSync=observe('read',original.readFileSync,value=>
+  createHash('sha256').update(JSON.stringify(typeof value==='string'?value:value.toString('utf8'))).digest('hex'));
+fs.statSync=observe('stat',original.statSync,value=>value?kindOf(value):null);
+fs.readdirSync=observe('readdir',original.readdirSync,(value,dir)=>value.map(entry=>{
+  if(typeof entry==='string')return [entry,'?'];
+  if(!entry.isSymbolicLink())return [entry.name,kindOf(entry)];
+  let target=null;try{target=kindOf(original.statSync(path.join(dir,entry.name)));}catch{}
+  return [entry.name,'l',target];
+}).sort((a,b)=>a[0]<b[0]?-1:a[0]>b[0]?1:0));
+const realpath=observe('realpath',original.realpathSync,value=>value);
+realpath.native=observe('realpath',original.native,value=>value);
+fs.realpathSync=realpath;
+// readFileSync opens through fs.openSync; only a writable open is a write.
+// The one write a direct run may make is its build-info file (incremental);
+// it is recorded, and the caller checks it is the configured one.
+const buildInfo=file=>typeof file==='string'&&file.endsWith('.tsbuildinfo');
+fs.openSync=function(file,flags,...rest){
+  if(!(flags===undefined||flags==='r'||flags==='rs'||flags===fs.constants.O_RDONLY)){
+    if(flags==='w'&&buildInfo(file))note('write',path.resolve(file),null);
+    else unsupported??='openSync';
+  }
+  return original.openSync.call(this,file,flags,...rest);
+};
+// tsc creates the build-info directory one level at a time; each is recorded.
+const mkdirSync=fs.mkdirSync;
+fs.mkdirSync=function(file,options,...rest){
+  if(typeof file==='string'&&options===undefined)note('mkdir',path.resolve(file),null);
+  else unsupported??='mkdirSync';
+  return mkdirSync.call(this,file,options,...rest);
+};
+// Writes, and reads this record cannot answer for, make it unusable. readSync
+// and fstatSync stay open: readFileSync reads through them.
+for(const name of ['writeFileSync','appendFileSync','unlinkSync','utimesSync',
+  'renameSync','rmSync','watch','watchFile','existsSync','lstatSync','accessSync','opendirSync',
+  'readlinkSync','readFile','stat','lstat','readdir','realpath','access','exists','open','opendir',
+  'readlink','createReadStream']){
+  const call=fs[name];
+  fs[name]=Object.assign(function(...args){unsupported??=name;return call.apply(this,args);},call);
+}
+for(const name of ['readFile','stat','lstat','readdir','realpath','access','open','opendir','readlink']){
+  const call=fs.promises[name];
+  fs.promises[name]=function(...args){unsupported??=`promises.${name}`;return call.apply(this,args);};
+}
+process.on('exit',()=>{
+  try{
+    const buffer=Buffer.from(JSON.stringify({schema:1,node:[real(process.execPath),process.version],main,
+      unsupported,conflict,compilerReads:[...compilerReads],facts:[...facts].map(([key,value])=>{const at=key.indexOf('\0');
+        return [key.slice(0,at),key.slice(at+1),JSON.parse(value)];})}));
+    for(let at=0;at<buffer.length;)at+=original.writeSync(3,buffer,at,buffer.length-at);
+  }catch{}
+});

package/src/state-store.mjs

@@ -19,19 +19,55 @@ export function readReceipts(state){
   let value;
   try{value=JSON.parse(fs.readFileSync(path.join(state,'receipts-v1.json'),'utf8'));}
   catch(e){if(e.code==='ENOENT')return {schema:STATE_SCHEMA,checks:{}};throw e;}
-  if(value.schema!==STATE_SCHEMA||!value.checks||typeof value.checks!=='object')
+  if(!value||typeof value!=='object'||Array.isArray(value)||value.schema!==STATE_SCHEMA||
+    !value.checks||typeof value.checks!=='object'||Array.isArray(value.checks))
     throw Error(`incompatible receipt state in ${state}; inspect or remove only this vstate state directory`);
   return value;
 }
 
+// This identity detects replacement of REDUE's owned, atomically written receipt
+// selector. It is not an input-content fingerprint or permission to reuse inputs.
+export function receiptRevision(state){
+  // A failed/crashed owned writer may have persisted a new immutable outcome
+  // without replacing the selector. Never certify its older selection.
+  try {fs.lstatSync(path.join(state,'receipt-selection-pending-v1.json'));
+    throw Error('receipt selection update incomplete; inspect the failed run, then record a new execution to recover');
+  }catch(error){if(error.code!=='ENOENT')throw error;}
+  try {const stat=fs.statSync(path.join(state,'receipts-v1.json'),{bigint:true});
+    if(!stat.isFile())throw Error('receipt selector is not a file');
+    return JSON.stringify(['dev','ino','size','mtimeNs','ctimeNs'].map(key=>String(stat[key])));
+  }catch(error){if(error.code==='ENOENT')return 'absent';throw error;}
+}
+
+export function readReceiptSnapshot(state){
+  const revision=receiptRevision(state),value=readReceipts(state);
+  if(receiptRevision(state)!==revision)
+    throw Error('receipt selection changed during read; retry status');
+  return {revision,value};
+}
+
 export function commitReceipt(state,name,receipt){
   const prior=readReceipts(state),runId=receipt.invocation?.runId;
   if(!/^[0-9a-f-]{36}$/.test(runId||''))throw Error('receipt lacks a valid run ID');
   const runs=path.join(state,'runs-v1');
   fs.mkdirSync(runs,{recursive:true,mode:0o700});
+  // The caller holds the state run lock. Leave this marker on any write failure;
+  // only a later successful owned commit may clear it. No journal scan guesses
+  // which incomplete execution should become the selected evidence.
+  const pending=path.join(state,'receipt-selection-pending-v1.json');
+  let updates={schema:STATE_SCHEMA,checks:{}};
+  try {updates=JSON.parse(fs.readFileSync(pending,'utf8'));
+    if(updates?.schema!==STATE_SCHEMA||!updates.checks||typeof updates.checks!=='object'||Array.isArray(updates.checks))
+      throw Error('incompatible incomplete receipt update; inspect owned state before recording');
+  }catch(error){if(error.code!=='ENOENT')throw error;}
+  updates.checks[name]={runId};
+  atomicJson(pending,updates);
   // One immutable outcome per invocation. Never overwrite an existing run.
   fs.writeFileSync(path.join(runs,runId+'.json'),
     JSON.stringify({schema:STATE_SCHEMA,check:name,receipt}),{flag:'wx',mode:0o600});
   prior.checks[name]=receipt;
   atomicJson(path.join(state,'receipts-v1.json'),prior);
+  delete updates.checks[name];
+  if(Object.keys(updates.checks).length)atomicJson(pending,updates);
+  else fs.unlinkSync(pending);
 }