@redue/cli 0.0.0-stage → 0.1.0-alpha.3

package/src/npm-typecheck-probe.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Read-only reviewed boundary for an npm script invoking local TypeScript.
+// A nonzero exit withdraws applicability. Output is a digest, never config values.
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+const [rootArg,nodeArg,npmArg,reviewedTsconfigHash,npmVersion,typescriptVersion]=process.argv.slice(2);
+const sha=value=>createHash('sha256').update(value).digest('hex');
+const inside=(file,dir)=>file===dir||file.startsWith(dir+path.sep);
+const fail=reason=>{throw Error(`typecheck boundary unavailable: ${reason}`);};
+const real=file=>fs.realpathSync(file);
+function fileHash(file){
+  const digest=createHash('sha256'),fd=fs.openSync(file,'r'),buffer=Buffer.alloc(1024*1024);
+  try{for(;;){const count=fs.readSync(fd,buffer,0,buffer.length,null);
+    if(!count)break;digest.update(buffer.subarray(0,count));}}
+  finally{fs.closeSync(fd);}
+  return digest.digest('hex');
+}
+function treeHash(dir){
+  const digest=createHash('sha256');
+  function visit(folder,relative=''){
+    for(const entry of fs.readdirSync(folder,{withFileTypes:true}).sort((a,b)=>
+      a.name.localeCompare(b.name))){
+      const rel=relative?relative+'/'+entry.name:entry.name,full=path.join(folder,entry.name);
+      if(entry.isDirectory()){digest.update(`d\0${rel}\0`);visit(full,rel);}
+      else if(entry.isFile())digest.update(`f\0${rel}\0${fileHash(full)}\0`);
+      else fail('npm installation contains an unsupported entry');
+    }
+  }
+  visit(dir);return digest.digest('hex');
+}
+function namesAt(dir){
+  if(!fs.existsSync(dir))return null;
+  if(!fs.statSync(dir).isDirectory())fail('ancestor resolution boundary is not a directory');
+  const names=[];
+  for(const entry of fs.readdirSync(dir,{withFileTypes:true}).sort((a,b)=>
+    a.name.localeCompare(b.name))){
+    names.push(entry.name);
+    if(entry.name.startsWith('@')&&entry.isDirectory())
+      names.push(...fs.readdirSync(path.join(dir,entry.name)).map(name=>entry.name+'/'+name).sort());
+  }
+  return names;
+}
+function rcKeys(file){
+  if(!fs.existsSync(file))return null;
+  const keys=[];
+  for(const line of fs.readFileSync(file,'utf8').split(/\r?\n/)){
+    const trimmed=line.trim();
+    if(!trimmed||trimmed.startsWith('#')||trimmed.startsWith(';'))continue;
+    const at=trimmed.indexOf('=');
+    if(at<0)fail('npm configuration has an unsupported entry');
+    const key=trimmed.slice(0,at).trim();
+    // These affect package acquisition, not this offline `npm run typecheck`.
+    if(key!=='registry'&&!/^\/\/[^\s]+\/:_authToken$/.test(key))
+      fail('npm configuration contains an unreviewed key');
+    keys.push(key);
+  }
+  return keys.sort();
+}
+function pathExecutable(name){
+  for(const folder of (process.env.PATH||'').split(path.delimiter)){
+    if(!folder)continue;
+    const candidate=path.join(folder,name);
+    try{fs.accessSync(candidate,fs.constants.X_OK);return real(candidate);}catch{}
+  }
+  return null;
+}
+try{
+  if(!rootArg||!nodeArg||!npmArg||!reviewedTsconfigHash||!npmVersion||!typescriptVersion)
+    fail('arguments missing');
+  const root=real(rootArg),node=real(nodeArg),npm=real(npmArg),home=process.env.HOME;
+  if(!home||!path.isAbsolute(home))fail('HOME is unavailable');
+  const homeTarget=real(home);
+  if(real(process.execPath)!==node||pathExecutable('node')!==node)
+    fail('npm shebang would use a different Node executable');
+  if(process.env.NODE_OPTIONS||process.env.NODE_PATH||process.env.BASH_ENV||process.env.ENV)
+    fail('unreviewed Node or shell preload environment');
+  if(Object.keys(process.env).some(key=>key.toLowerCase().startsWith('npm_config_')))
+    fail('npm configuration environment override');
+  if(Object.keys(process.env).some(key=>key.startsWith('DYLD_')||key.startsWith('TSGO_')))
+    fail('unreviewed native runtime environment');
+  const npmRoot=path.dirname(path.dirname(npm)),prefix=path.dirname(path.dirname(path.dirname(npmRoot)));
+  if(path.basename(npmRoot)!=='npm'||path.basename(path.dirname(npmRoot))!=='node_modules')
+    fail('npm installation layout changed');
+  if(JSON.parse(fs.readFileSync(path.join(npmRoot,'package.json'),'utf8')).version!==npmVersion||
+    JSON.parse(fs.readFileSync(path.join(root,'node_modules/typescript/package.json'),'utf8'))
+      .version!==typescriptVersion)fail('reviewed npm or TypeScript version changed');
+  const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));
+  if(pkg.scripts?.typecheck!=='tsc --noEmit'||pkg.scripts?.pretypecheck||pkg.scripts?.posttypecheck)
+    fail('typecheck script or lifecycle changed');
+  const tsconfig=path.join(root,'tsconfig.json');
+  if(fileHash(tsconfig)!==reviewedTsconfigHash)fail('TypeScript configuration needs review');
+  const tsc=real(path.join(root,'node_modules','.bin','tsc'));
+  if(tsc!==path.join(root,'node_modules','typescript','bin','tsc'))
+    fail('typecheck executable does not resolve to local TypeScript');
+  const listed=spawnSync(tsc,['--noEmit','--listFilesOnly'],{cwd:root,env:process.env,
+    encoding:'utf8',timeout:10000,maxBuffer:4*1024*1024,stdio:['ignore','pipe','pipe']});
+  if(listed.error||listed.signal||listed.status!==0)fail('TypeScript input listing unavailable');
+  const files=listed.stdout.trim().split(/\r?\n/).filter(Boolean).map(file=>path.resolve(file));
+  if(!files.length||files.some(file=>!inside(file,root)||
+    !(inside(file,path.join(root,'src'))||file===path.join(root,'vite.config.ts')||
+      inside(file,path.join(root,'node_modules')))))
+    fail('TypeScript consumes an input outside the observed file sets');
+  const ancestors=[];
+  for(let dir=path.dirname(root);;dir=path.dirname(dir)){
+    ancestors.push([dir,namesAt(path.join(dir,'node_modules'))]);
+    if(dir===path.dirname(dir))break;
+  }
+  const configFiles=[path.join(root,'.npmrc'),path.join(home,'.npmrc'),
+    path.join(prefix,'etc','npmrc')];
+  const npmConfig=configFiles.map(file=>[file,rcKeys(file)]);
+  // Metadata alone is insufficient for the installed npm CLI and native tools.
+  const fingerprint=sha(JSON.stringify({schema:1,probe:fileHash(fileURLToPath(import.meta.url)),
+    homeTarget,files:files.sort(),ancestors,
+    npmConfig,npmTree:treeHash(npmRoot),node:fileHash(node),shell:fileHash('/bin/sh')}));
+  process.stdout.write(fingerprint);
+}catch(e){console.error(e.message);process.exitCode=2;}

package/src/observation.mjs

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {fork} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+// Observation contract: live notifications establish continuity only while the
+// subscription is healthy; history may accelerate catch-up; a fresh scan is
+// the deterministic fallback. A failed history operation never updates cursor.
+const workerFile=path.join(path.dirname(fileURLToPath(import.meta.url)),'history-worker.mjs');
+export function history(root,cursor,backend,deadlineMs,faultFile) {
+  const next=cursor+'.'+randomUUID()+'.next';
+  return new Promise((resolve,reject)=>{
+    const worker=fork(workerFile,[root,fs.existsSync(cursor)?cursor:'',next,backend,
+      faultFile||''],{stdio:['ignore','ignore','ignore','ipc']});
+    let settled=false,abandoned=false;
+    const finish=(error,value)=>{
+      if(settled)return;settled=true;clearTimeout(timer);
+      worker.kill('SIGKILL');
+      if(error){abandoned=true;try{fs.unlinkSync(next);}catch{}
+        reject(error);return;}
+      try{fs.renameSync(next,cursor);resolve(value);}
+      catch(e){try{fs.unlinkSync(next);}catch{}reject(e);}
+    };
+    const timer=setTimeout(()=>{
+      const e=Error(`history query did not settle within ${deadlineMs} ms`);
+      e.code='ETIMEDOUT';finish(e);
+    },deadlineMs);
+    worker.on('message',message=>message.ok?finish(null,message.changes):
+      finish(Object.assign(Error(message.error),{code:message.code})));
+    worker.once('error',e=>finish(e));
+    worker.once('exit',(code,signal)=>{
+      if(abandoned)try{fs.unlinkSync(next);}catch{}
+      if(!settled)finish(Error(`history helper exited ${code??signal}`));
+    });
+  });
+}

package/src/owned-state.mjs

@@ -0,0 +1,32 @@
+// Resolve the destination, including linked parent directories, before any
+// state creation or removal. A watched root is readable, never state-owned.
+import fs from 'node:fs';
+import path from 'node:path';
+import {withinPath as within,realObservedPath} from './path-identity.mjs';
+
+export function resolvedDestination(file) {
+  let current=path.resolve(file),rest=[];
+  for(;;) {
+    try {
+      const canonical=realObservedPath(current);
+      return path.join(canonical,...rest);
+    } catch(e) {
+      if(e.code!=='ENOENT')throw e;
+      const parent=path.dirname(current);
+      if(parent===current)throw Error('state destination cannot be resolved');
+      rest.unshift(path.basename(current));current=parent;
+    }
+  }
+}
+
+export function assertOwnedStatePlacement(config) {
+  const state=path.resolve(config.state),resolved=resolvedDestination(state);
+  const observed=[config.root,...(config.checks||[]).flatMap(check=>
+    check.allowedExternalRoots||[])].map(resolvedDestination);
+  for(const boundary of observed)if(within(resolved,boundary)||within(boundary,resolved))
+    throw Error('REDUE state overlaps an observed checkout or external root');
+  try{if(fs.lstatSync(state).isSymbolicLink())
+    throw Error('REDUE state directory must not be a symlink');}
+  catch(e){if(e.code!=='ENOENT')throw e;}
+  return {state,resolved};
+}

package/src/path-identity.mjs

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+// Windows callers may supply an 8.3 spelling while filesystem APIs and
+// TypeScript report the long name. Canonicalize existing paths at observation
+// boundaries; keep logical link paths separately for invalidation.
+export function realObservedPath(value) {
+  return process.platform==='win32'?fs.realpathSync.native(value):fs.realpathSync(value);
+}
+
+// Use the host path implementation in production. Passing path.win32 makes
+// the identity rules testable elsewhere; those tests are not NTFS acceptance.
+export function normalizedPath(value,paths=path) {
+  const resolved=paths.resolve(value);
+  if(paths!==path.win32)return resolved;
+  if(/^\\\\\?\\UNC\\/i.test(resolved))return '\\\\'+resolved.slice(8);
+  if(/^\\\\\?\\[A-Za-z]:\\/.test(resolved))return resolved.slice(4);
+  return resolved;
+}
+
+export function samePath(left,right,paths=path) {
+  return paths.relative(normalizedPath(left,paths),normalizedPath(right,paths))==='';
+}
+
+export function withinPath(file,root,paths=path) {
+  const relative=paths.relative(normalizedPath(root,paths),normalizedPath(file,paths));
+  return relative===''||(!paths.isAbsolute(relative)&&relative!=='..'&&
+    !relative.startsWith('..'+paths.sep));
+}
+
+export function observedRelative(root,file,paths=path) {
+  if(!withinPath(file,root,paths))return null;
+  return paths.relative(normalizedPath(root,paths),normalizedPath(file,paths))
+    .split(paths.sep).join('/');
+}
+
+export function validInputRelative(rel,platform=process.platform) {
+  if(typeof rel!=='string'||!rel||path.posix.isAbsolute(rel)||
+    rel.split('/').includes('..'))return false;
+  if(platform==='win32'&&(path.win32.isAbsolute(rel)||/^[A-Za-z]:/.test(rel)||
+    rel.includes('\\')))return false;
+  return true;
+}

package/src/plan-worker.mjs

@@ -0,0 +1,131 @@
+import {parentPort,workerData} from 'node:worker_threads';
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {discover} from './plan.mjs';
+import {InputIndex} from './index.mjs';
+import {queriesMatch} from './typescript-list.mjs';
+import {planGuard,inputKey} from './decision-validation.mjs';
+import {timing} from './decision-profile.mjs';
+
+try {
+  const totalStarted=performance.now();
+  const configStarted=performance.now();
+  const config=JSON.parse(fs.readFileSync(workerData.config));
+  timing('worker.config_load',configStarted);
+  let discoveryStarted=performance.now();
+  let bundle=workerData.reuse?.bundle;
+  let validatedIndex=null,guard=null,reuseReason='no_validated_plan',planReused=false;
+  if(bundle){
+    const started=performance.now();
+    try{
+      guard=planGuard(bundle);
+      const queryStarted=performance.now();
+      const queriesValid=!workerData.reuse.queries?.length||queriesMatch(workerData.reuse.queries);
+      timing('worker.compiler_queries',queryStarted,{queries:workerData.reuse.queries?.length||0,matched:queriesValid?1:0});
+      if(guard!==workerData.reuse.guard||!queriesValid)reuseReason='configuration_or_resolution_changed';
+      else {
+        validatedIndex=new InputIndex(bundle);
+        validatedIndex.coldScan(progress=>parentPort.postMessage({kind:'progress',
+          phase:'validating',scanned:progress.scanned,total:progress.total}));
+        if(validatedIndex.unavailable)throw Error(validatedIndex.unavailable);
+        if(planGuard(bundle)!==guard)throw Error('plan dependencies changed during validation');
+        // Compiler imports can change effective membership. Until that content
+        // has been rediscovered, never reuse a compiler input contract.
+        const changed=[...validatedIndex.checks].some(([name,row])=>
+          row.plan.qualification&&inputKey(row)!==workerData.reuse.inputs[name]);
+        reuseReason=changed?'compiler_inputs_changed':'dependencies_unchanged';
+        planReused=!changed;
+      }
+    }catch{reuseReason='validation_unavailable';}
+    timing('worker.plan_validation',started,{reason:reuseReason,
+      files:validatedIndex?.files.size||0,
+      bytes:validatedIndex?.rehashedBytes||0,
+      hashingMs:Math.round(validatedIndex?.profile.hashingMs||0),
+      enumerationMs:Math.round(validatedIndex?.profile.enumerationMs||0)});
+  }
+  discoveryStarted=performance.now();
+  if(!planReused){bundle=discover(config,workerData.state);validatedIndex=null;
+    guard=planGuard(bundle);}
+  timing('worker.discovery_reason',performance.now(),{reason:reuseReason,reused:planReused?1:0});
+  const discoveryMs=performance.now()-discoveryStarted;
+  timing(planReused?'worker.discovery_reused':'worker.discovery',discoveryStarted,{checks:Object.keys(bundle.plans).length});
+  parentPort.postMessage({kind:'progress',phase:'indexing',discoveryMs,scanned:0,total:null});
+  const digest=file=>createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  let retained=null;
+  const retainedStarted=performance.now();
+  try {if(workerData.forceCold)throw Error('fresh reconciliation required');
+    retained=JSON.parse(fs.readFileSync(path.join(workerData.state,'index-v1.json')));
+    const identity=fs.statSync(bundle.root,{bigint:true});
+    if(retained.schema!==1||retained.root!==bundle.root||
+      JSON.stringify(retained.identity)!==JSON.stringify([String(identity.dev),String(identity.ino)])||
+      JSON.stringify(retained.planIds)!==JSON.stringify(Object.fromEntries(
+        Object.entries(bundle.plans).map(([name,plan])=>[name,plan.id])))||
+      retained.cursor!==digest(path.join(workerData.state,'fs-events.snapshot'))||
+      Object.keys(retained.external||{}).length!==new Set(Object.values(bundle.plans)
+        .flatMap(plan=>plan.externalObservationRoots||
+          Object.keys(plan.externalPatterns||{}))).size||
+      Object.entries(retained.external||{}).some(([root,value])=>
+        value.cursor!==digest(path.join(workerData.state,
+          `external-${createHash('sha256').update(root).digest('hex').slice(0,16)}.snapshot`))))
+      retained=null;
+  } catch {retained=null;}
+  timing('worker.retained_state_validation',retainedStarted,{reused:retained?1:0});
+  if(retained){
+    timing('worker.total',totalStarted,{mode:'retained'});
+    parentPort.postMessage({ok:true,bundle,discoveryMs,indexingMs:0,
+      restartMode:'retained-replay',index:retained.index,
+      external:Object.fromEntries(Object.entries(retained.external||{})
+        .map(([root,value])=>[root,value.index]))});
+  } else {
+  if(workerData.reconcileFaultFile&&fs.existsSync(workerData.reconcileFaultFile))
+    throw Error('injected reconciliation failure');
+  const indexingStarted=performance.now(), index=validatedIndex||new InputIndex(bundle);
+  if(!validatedIndex){const report=progress=>parentPort.postMessage({kind:'progress',phase:'indexing',discoveryMs,...progress});
+    index.coldScan(report);}
+  const indexingMs=performance.now()-indexingStarted;
+  timing(validatedIndex?'worker.index_reused':'worker.index',indexingStarted,{files:index.files.size,
+    entries:index.profile.enumeratedEntries,hashed:index.rehashedFiles,
+    bytes:index.rehashedBytes,enumerationMs:Math.round(index.profile.enumerationMs),
+    matchingMs:Math.round(index.profile.matchingMs),
+    hashingMs:Math.round(index.profile.hashingMs)});
+  if(index.unavailable)throw Error(index.unavailable);
+  const external={};
+  for(const boundary of [...new Set(Object.values(bundle.plans)
+    .flatMap(plan=>plan.externalObservationRoots||
+      Object.keys(plan.externalPatterns||{})))]) {
+    const plans=Object.fromEntries(Object.entries(bundle.plans)
+      .filter(([,plan])=>(plan.externalObservationRoots||
+        Object.keys(plan.externalPatterns||{})).includes(boundary))
+      .map(([name,plan])=>[name,{...plan,patterns:plan.externalPatterns[boundary],
+        sourcePatterns:[],
+        additivePatterns:plan.externalPatterns[boundary]||[],
+        installedPhysicalRoots:[]}]));
+    const outside=new InputIndex({root:boundary,plans},{trackGit:false,includeInstalled:true});
+    outside.coldScan();
+    if(outside.unavailable)throw Error(outside.unavailable);
+    external[boundary]={files:[...outside.files],
+      aliasDependencies:[...outside.aliasDependencies].map(([name,refs])=>[name,[...refs]]),
+      rows:[...outside.checks]
+      .map(([name,row])=>({name,files:[...row.files],sum:row.sum.toString('hex'),
+        revision:row.revision,lastReason:row.lastReason})),
+      eventCount:outside.eventCount,rehashedFiles:outside.rehashedFiles,
+      rehashedBytes:outside.rehashedBytes,profile:outside.profile};
+  }
+  timing('worker.total',totalStarted,{mode:'cold',files:index.files.size});
+  parentPort.postMessage({ok:true,bundle,discoveryMs,indexingMs,guard,planReused,
+    inputKeys:Object.fromEntries([...index.checks].map(([name,row])=>[name,inputKey(row)])),
+    restartMode:'cold-index',
+    external,
+    index:{files:[...index.files],
+      aliasDependencies:[...index.aliasDependencies].map(([name,refs])=>[name,[...refs]]),
+      rows:[...index.checks].map(([name,row])=>({
+      name,files:[...row.files],sum:row.sum.toString('hex'),revision:row.revision,
+      lastReason:row.lastReason})),
+    eventCount:index.eventCount,rehashedFiles:index.rehashedFiles,
+    rehashedBytes:index.rehashedBytes,profile:index.profile}});
+  }
+} catch(error) {
+  parentPort.postMessage({ok:false,error:error?.message||String(error),
+    classification:error?.name||'Error'});
+}

package/src/plan.mjs

@@ -0,0 +1,10 @@
+import {createHash} from 'node:crypto';
+import {discoverDeclared} from './declared-plan.mjs';
+
+export const sha = value => createHash('sha256').update(value).digest('hex');
+
+export function discover(config) {
+  if (config.provider !== 'declared-project@1')
+    throw Error(`unsupported input-plan provider: ${config.provider}`);
+  return discoverDeclared(config);
+}

package/src/platform-observation.mjs

@@ -0,0 +1,17 @@
+import parcelWatcher from '@parcel/watcher';
+import {subscribeLinux} from './linux-observer.mjs';
+
+export const hasHistory=process.platform==='darwin';
+export const backend=process.platform==='win32'?'windows':hasHistory?'fs-events':'inotify';
+export function subscribe(root,callback){
+  if(process.platform!=='darwin'&&process.platform!=='linux'&&process.platform!=='win32')
+    throw Error(`filesystem observation is unavailable on ${process.platform}`);
+  if(process.platform==='linux')return subscribeLinux(root,callback);
+  if(process.platform==='win32')return parcelWatcher.subscribe(root,callback,{backend}).then(handle=>({
+    unsubscribe:()=>handle.unsubscribe(),
+    // This is not a continuity barrier. Decision-grade reads on Windows use
+    // deterministic reconciliation, including after a watcher restart.
+    synchronize:async()=>{},watchFiles:async()=>{}
+  }));
+  return parcelWatcher.subscribe(root,callback,{backend});
+}

package/src/platform-state.mjs

@@ -0,0 +1,14 @@
+import path from 'node:path';
+
+export function userStateBase(platform=process.platform,env=process.env,
+  home=process.env.HOME||'',paths=path) {
+  if(platform==='win32')return paths.isAbsolute(env.LOCALAPPDATA||'')?
+    env.LOCALAPPDATA:paths.join(home,'AppData','Local');
+  if(platform==='linux')return paths.isAbsolute(env.XDG_STATE_HOME||'')?
+    env.XDG_STATE_HOME:paths.join(home,'.local','state');
+  return paths.join(home,'Library','Application Support');
+}
+
+export function stateIdentity(value,platform=process.platform) {
+  return platform==='win32'?path.win32.normalize(value).toLowerCase():value;
+}