@3fn/core 14.0.0 → 15.0.0

package/src/config/ConfigLoader.ts

@@ -1,143 +0,0 @@
-/**
- * Configuration Loader
- *
- * Loads `designerpunk.config.ts` from the working directory.
- * Falls back to defaults when no config file exists.
- * Resolves all paths relative to the config file's directory.
- *
- * @see Spec 094 design.md § "ConfigLoader"
- */
-
-import * as path from 'path';
-import * as fs from 'fs';
-import type { DesignerPunkConfig, ConfigTheme } from './defineConfig';
-import { scopedTsRequire } from './scopedTsRequire';
-import { resolvePackageRoot } from '../cli/shared/resolvePackageRoot';
-
-/** Fully resolved configuration with absolute paths. */
-export interface ResolvedConfig {
-  /** Product name for generated type names. */
-  name: string;
-  /** Short form for environment keys. */
-  abbreviation: string;
-  /** Registered themes from config. */
-  themes: ConfigTheme[];
-  /** Resolved absolute path to token source root. */
-  tokenSourceRoot: string;
-  /** Whether token source is local (from config) or package (default). */
-  tokenSourceMode: 'local' | 'package';
-  /** Resolved absolute paths to component token directories. */
-  componentTokenDirs: string[];
-  /** Resolved absolute path to output directory. */
-  outputDir: string;
-  /** Directory the config file was loaded from (or cwd for defaults). */
-  configDir: string;
-  /** Resolved absolute path to product tokens directory, or undefined if not configured. */
-  productTokens?: string;
-}
-
-const DEFAULTS = {
-  name: 'DesignerPunk',
-  abbreviation: 'DP',
-  themes: [] as ConfigTheme[],
-  componentTokens: [] as string[],
-  output: 'dist',
-};
-
-/**
- * Loads a config module at runtime and returns its module namespace object
- * (the caller unwraps `.default`). The injectable resolution seam for
- * {@link loadConfig} — see {@link defaultConfigModuleLoader}.
- */
-export type ConfigModuleLoader = (configPath: string) => unknown | Promise<unknown>;
-
-/**
- * Default config-module loader — **Approach A** (Spec 118 Task 1 selection):
- * `tsx/cjs/api` namespaced `register` + scoped synchronous `require`.
- *
- * Spec 118 Task 9.5: this delegates to the SHARED {@link scopedTsRequire} primitive —
- * the single runtime-TS resolution mechanism behind all three per-site scoped seams
- * (config, `resolveTokens`, `loadComponentTokens`), replacing three inline copies of the
- * register/require/unregister cycle. The mechanism is unchanged: `register()` mutates
- * `module._resolveFilename` / `module._extensions` process-globally; the namespace scopes
- * requests; `unregister()` (in `finally`, inside `scopedTsRequire`) restores global state —
- * load-bearing for the no-ambient-residue criterion. (Task 1: `findings/loader-selection.md`.)
- *
- * Anchored at `__filename` so transitive relative imports inside the config resolve as
- * before. Returns synchronously; the loader type stays `Promise`-compatible for callers.
- *
- * Constraint: this loader **cannot run inside a jest process** — tsx's scoped require
- * appends a `?namespace=` tag that jest's module resolver rejects (ENOENT). In-process
- * jest tests must inject a jest-compatible loader via `loadConfig`'s `loadModule`
- * parameter (e.g. `(p) => import(p)`, `jestConfigModuleLoader`). Production (real-node)
- * execution uses this default unconditionally — there is deliberately NO test-environment
- * detection in this path.
- */
-export const defaultConfigModuleLoader: ConfigModuleLoader = (configPath: string) =>
-  scopedTsRequire(configPath, __filename);
-
-/**
- * Load and resolve a DesignerPunk configuration.
- *
- * @param cwd - Working directory to search for config file. Defaults to process.cwd().
- * @param loadModule - Injectable config-module loader (resolution seam). Defaults to
- *   {@link defaultConfigModuleLoader} (Approach A). In-process jest tests inject a
- *   jest-compatible loader because Approach A cannot run inside jest (see that loader's docs).
- * @returns Fully resolved configuration with absolute paths.
- */
-export async function loadConfig(
-  cwd: string = process.cwd(),
-  loadModule: ConfigModuleLoader = defaultConfigModuleLoader,
-): Promise<ResolvedConfig> {
-  const configPath = path.resolve(cwd, 'designerpunk.config.ts');
-  let userConfig: DesignerPunkConfig = {};
-  let configDir = cwd;
-
-  if (fs.existsSync(configPath)) {
-    try {
-      // Resolution seam — production default is Approach A (tsx/cjs/api); see
-      // defaultConfigModuleLoader. In-process jest tests inject a jest-compatible
-      // loader. No test-environment detection lives in this path.
-      const loaded = await loadModule(configPath);
-      userConfig = (loaded as { default?: DesignerPunkConfig } & DesignerPunkConfig).default || (loaded as DesignerPunkConfig);
-      configDir = path.dirname(configPath);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new Error(`Failed to load ${configPath}: ${message}`);
-    }
-  }
-
-  const name = userConfig.name || DEFAULTS.name;
-  const abbreviation = userConfig.abbreviation || DEFAULTS.abbreviation;
-  const themes = userConfig.themes || DEFAULTS.themes;
-  const output = userConfig.output || DEFAULTS.output;
-  const componentTokenPaths = userConfig.componentTokens || DEFAULTS.componentTokens;
-
-  // Resolve token source: configured local path or package's src/tokens/.
-  // Package-mode default routes through the shared resolvePackageRoot() (Spec 118 Task
-  // 9.5.2, Class C / B1) rather than `path.resolve(__dirname, '../tokens')`. The bare
-  // __dirname form breaks under compile-to-dist (dist/config → dist/tokens, where no raw
-  // .ts token source exists); resolving from the self-checking package root finds the
-  // package's `src/tokens` regardless of whether this module runs from `src/` (tsx) or
-  // `dist/` (compiled), so it survives the target model's compile-and-ship step.
-  const tokenSourceMode: 'local' | 'package' = userConfig.tokenSource ? 'local' : 'package';
-  const tokenSourceRoot = userConfig.tokenSource
-    ? path.resolve(configDir, userConfig.tokenSource)
-    : path.resolve(resolvePackageRoot(__dirname), 'src/tokens');
-
-  // Resolve paths relative to config directory
-  const outputDir = path.resolve(configDir, output);
-  const componentTokenDirs = componentTokenPaths.map(p => path.resolve(configDir, p));
-
-  return {
-    name,
-    abbreviation,
-    themes,
-    tokenSourceRoot,
-    tokenSourceMode,
-    componentTokenDirs,
-    outputDir,
-    configDir,
-    productTokens: userConfig.productTokens ? path.resolve(configDir, userConfig.productTokens) : undefined,
-  };
-}

package/src/config/__resolution-matrix__/README.md

@@ -1,76 +0,0 @@
-# Resolution-Matrix Harness (Spec 118, Task 1)
-
-Empirically determines which TS-aware loader `loadConfig` (`src/config/ConfigLoader.ts`)
-should use, by exercising candidate loaders against a faithful reproduction of the
-config-load failure — in **real `node` subprocesses, NOT under jest**.
-
-## Re-run
-
-```
-npm run test:resolution-matrix
-# or:  node src/config/__resolution-matrix__/run-matrix.js
-# subset: node src/config/__resolution-matrix__/run-matrix.js A      (only approach A)
-#         node src/config/__resolution-matrix__/run-matrix.js none A B
-```
-
-A single cell can be run directly:
-
-```
-node src/config/__resolution-matrix__/runner.js <none|A|B|C> <fixtureDir> <expectedSentinel>
-```
-
-## THE critical constraint — why this is NOT a jest test
-
-Under ts-jest, jest intercepts `await import()` via its own module registry and
-**never hits Node's strict-ESM resolver** — so a jest-hosted matrix goes *green
-against the very bug*. This is proven in-repo: `src/config/__tests__/ConfigLoader.test.ts`
-writes configs as `module.exports` in `.ts` files and passes today even though the
-production config-load path is broken. Therefore every cell here runs in a real
-`node` process (`runner.js`, plain CommonJS) that faithfully reproduces
-`loadConfig`'s load locus (CJS context: `__dirname`/`__filename`, no `import.meta`;
-`loaded.default || loaded` unwrap; fail-loud `try/catch`). The candidate loader is
-the only thing that can make a `.ts` config resolve.
-
-## The matrix
-
-Rows (each in BOTH ESM-authored and CJS-authored form — R2 AC4 forward-compat):
-
-- **source-directory import** — config imports a directory (`./src/config`) with no
-  explicit `/index.ts`. Bare-Node fails `Directory import not supported` (ESM) /
-  `Cannot find module` (CJS).
-- **faithful-consumer** — config does a compiled import (`./compiled/defineConfig.js`,
-  modeling `@3fn/core/config` → dist) PLUS a transitive relative raw-`.ts` override
-  `./my-overrides`. Bare-Node fails `Cannot find module ... ./my-overrides`.
-
-Fixtures use **real** authoring (`export default` + ESM imports / real `require()`),
-never `module.exports`-in-`.ts` (a jest-transform artifact that is neither faithful
-CJS nor ESM). The sentinel asserted is one **only the transitive `./my-overrides`
-import produces** (positive sentinel — never "not DEFAULTS").
-
-## Candidate loaders
-
-- **A** — `tsx/cjs/api` `register({namespace})` + scoped synchronous `require`,
-  with mandatory `unregister()` after the load (A mutates `module._resolveFilename`
-  process-globally; namespace only scopes requests, so `unregister()` is what
-  satisfies the no-residue criterion).
-- **B** — `tsImport` via `await import('tsx/esm/api')` with `parentURL` from
-  `pathToFileURL(__filename)`.
-- **C** — `jiti` (NOT installed; only exercised if both A and B fail; would be a
-  budgeted dependency add).
-
-## Accept-criteria
-
-(a) failing rows green; (b) both CJS- and ESM-authored configs; (c) operates in
-`loadConfig`'s CJS context incl. transitive relative raw-`.ts` (OQ-1); (d) preserves
-`loaded.default || loaded` + fail-loud (resolution failure THROWS, never partial);
-(e) leaves no ambient/global residue after the call.
-
-## Result (see `findings/loader-selection.md` for the dated record)
-
-A passes all rows in both directions with no residue; B fails all rows (the OQ-1
-CJS-host/ESM-loader boundary — `tsImport` does not resolve the transitive raw-`.ts`
-from a CJS host, and leaves residue). **Selected: A.** jiti was not needed.
-
-> This harness is the Task-1 selection evidence. The *standing* preventive guard is
-> the Task-3 subprocess consumer guard (pack → install → `npx designerpunk generate`);
-> this harness is a re-runnable selection/regression tool, not the CI release gate.

package/src/config/__resolution-matrix__/fixtures/faithful-cjs/compiled/defineConfig.js

@@ -1,9 +0,0 @@
-/**
- * COMPILED require target (models `@3fn/core/config` → dist CJS output).
- * Pure CJS; required by the CJS-authored config via require('./compiled/defineConfig.js').
- */
-'use strict';
-function defineConfig(config) {
-  return config;
-}
-module.exports = { defineConfig };

package/src/config/__resolution-matrix__/fixtures/faithful-cjs/designerpunk.config.ts

@@ -1,20 +0,0 @@
-/**
- * Matrix row: faithful-consumer (CJS-authored).
- *
- * Faithful CJS authoring of the same conjunction the ESM variant exercises:
- *   (1) `.ts` config (typeless package),
- *   (2) a COMPILED `require('./compiled/defineConfig.js')` (models dist), and
- *   (3) a TRANSITIVE relative raw-`.ts` override `require('./my-overrides')`
- *       (no extension) — the require that, without a TS-aware loader, fails
- *       `Cannot find module ... ./my-overrides`.
- *
- * Sentinel produced ONLY by the transitive `./my-overrides` raw-`.ts` require.
- */
-const { defineConfig } = require('./compiled/defineConfig.js');
-const { overrideSentinel } = require('./my-overrides');
-
-module.exports = defineConfig({
-  name: 'FaithfulCJS',
-  abbreviation: 'FC',
-  sentinel: overrideSentinel,
-});

package/src/config/__resolution-matrix__/fixtures/faithful-cjs/my-overrides.ts

@@ -1,8 +0,0 @@
-/**
- * Transitive relative raw-`.ts` override (CJS). Required by the config as
- * `require('./my-overrides')` (no extension). Carries the sentinel that ONLY
- * this module produces — the positive-sentinel target for the faithful-consumer
- * CJS row.
- */
-const overrideSentinel = 'faithful-cjs:my-overrides-resolved';
-module.exports = { overrideSentinel };

package/src/config/__resolution-matrix__/fixtures/faithful-esm/compiled/defineConfig.js

@@ -1,11 +0,0 @@
-/**
- * COMPILED import target (models `@3fn/core/config` → dist CJS output).
- * Pure CJS (`module.exports`), as the project's dist is CJS. The ESM-authored
- * config imports it via `import { defineConfig } from './compiled/defineConfig.js'`,
- * exercising the ESM->CJS named-import interop that the real workflow relies on.
- */
-'use strict';
-function defineConfig(config) {
-  return config;
-}
-module.exports = { defineConfig };

package/src/config/__resolution-matrix__/fixtures/faithful-esm/designerpunk.config.ts

@@ -1,23 +0,0 @@
-/**
- * Matrix row: faithful-consumer (ESM-authored).
- *
- * Reproduces the documented theme-override workflow's failure conjunction:
- *   (1) ESM-syntax `.ts` config under a typeless package,
- *   (2) a COMPILED import (`./compiled/defineConfig.js`, modeling
- *       `@3fn/core/config` → dist), and
- *   (3) a TRANSITIVE relative raw-`.ts` override import (`./my-overrides`)
- *       — no extension — which hits Node's strict-ESM resolver and fails
- *       `Cannot find module ... ./my-overrides`.
- *
- * The sentinel is produced ONLY by the transitive `./my-overrides` raw-`.ts`
- * import (Lina SF-A: positive sentinel, never "not DEFAULTS"), so the row is
- * green only if the transitive raw-`.ts` require actually resolved.
- */
-import { defineConfig } from './compiled/defineConfig.js';
-import { overrideSentinel } from './my-overrides';
-
-export default defineConfig({
-  name: 'FaithfulESM',
-  abbreviation: 'FE',
-  sentinel: overrideSentinel,
-});

package/src/config/__resolution-matrix__/fixtures/faithful-esm/my-overrides.ts

@@ -1,6 +0,0 @@
-/**
- * Transitive relative raw-`.ts` override (ESM). Imported by the config as
- * `./my-overrides` (no extension). Carries the sentinel that ONLY this module
- * produces — the positive-sentinel target for the faithful-consumer ESM row.
- */
-export const overrideSentinel = 'faithful-esm:my-overrides-resolved';

package/src/config/__resolution-matrix__/fixtures/source-dir-cjs/designerpunk.config.ts

@@ -1,11 +0,0 @@
-/**
- * Matrix row: source-directory import (CJS-authored).
- *
- * Faithful CJS authoring: real `require()` of a DIRECTORY (`./src/config`) with
- * no explicit `/index.ts`, exported via `module.exports`. Exercises the same
- * directory-index resolution as the ESM variant but through the CJS require path,
- * proving the loader does not silently assume a direction (R2 AC4).
- */
-const { makeConfig, SENTINEL } = require('./src/config');
-
-module.exports = makeConfig({ sentinel: SENTINEL });

package/src/config/__resolution-matrix__/fixtures/source-dir-cjs/src/config/index.ts

@@ -1,15 +0,0 @@
-/**
- * Directory-import target (CJS). Resolved only via the bare directory specifier
- * `require('./src/config')` from the config — exercises directory-index resolution.
- */
-const SENTINEL = 'source-dir-cjs:index-resolved';
-
-function makeConfig(opts) {
-  return {
-    name: 'SourceDirCJS',
-    abbreviation: 'SDC',
-    sentinel: opts.sentinel,
-  };
-}
-
-module.exports = { SENTINEL, makeConfig };

package/src/config/__resolution-matrix__/fixtures/source-dir-esm/designerpunk.config.ts

@@ -1,15 +0,0 @@
-/**
- * Matrix row: source-directory import (ESM-authored).
- *
- * Faithfully reproduces the "source-directory import" failure: an ESM-syntax
- * `.ts` config under a typeless package that imports a DIRECTORY (`./src/config`)
- * with no explicit `/index.ts`. Under Node's strict-ESM resolver this fails with
- * `Directory import ... is not supported`. A TS-aware loader must resolve the
- * directory to its index module.
- *
- * The sentinel (`SENTINEL`) is produced ONLY by the directory's index module,
- * so a positive sentinel assertion proves the directory import actually resolved.
- */
-import { makeConfig, SENTINEL } from './src/config';
-
-export default makeConfig({ sentinel: SENTINEL });

package/src/config/__resolution-matrix__/fixtures/source-dir-esm/src/config/index.ts

@@ -1,13 +0,0 @@
-/**
- * Directory-import target (ESM). Resolved only via the bare directory specifier
- * `./src/config` from the config — exercises directory-index resolution.
- */
-export const SENTINEL = 'source-dir-esm:index-resolved';
-
-export function makeConfig(opts: { sentinel: string }) {
-  return {
-    name: 'SourceDirESM',
-    abbreviation: 'SDE',
-    sentinel: opts.sentinel,
-  };
-}

package/src/config/__resolution-matrix__/run-matrix.js

@@ -1,107 +0,0 @@
-#!/usr/bin/env node
-/**
- * Resolution-matrix ORCHESTRATOR (Spec 118, Task 1).
- *
- * Spawns a REAL `node` subprocess per (approach x row x authoring-direction)
- * cell via runner.js, collects the structured JSON result, and prints a
- * green/red table. NOTHING here runs under jest — each cell is a faithful
- * `loadConfig`-locus reproduction executed by `node` directly, so the candidate
- * loader is the only thing that can resolve a `.ts` config (THE critical
- * constraint: jest's module registry would otherwise mask the bug).
- *
- * Re-run with:  npm run test:resolution-matrix
- *           or: node src/config/__resolution-matrix__/run-matrix.js
- *           or: node src/config/__resolution-matrix__/run-matrix.js A B   (subset)
- *
- * Exit code 0 only if every selected non-baseline approach behaves as the
- * accept-criteria require for at least one fully-passing approach; otherwise 1.
- * (The orchestrator is a reporting harness, not a release gate — the standing
- * CI gate is the Task-3 subprocess consumer guard. This exits nonzero if NO
- * approach passes all rows, so a regression that breaks the selected loader is
- * visible when the harness is re-run.)
- */
-'use strict';
-
-const { spawnSync } = require('child_process');
-const path = require('path');
-
-const RUNNER = path.resolve(__dirname, 'runner.js');
-
-// row id -> { dir, sentinel, direction }
-const ROWS = [
-  { id: 'source-directory import', direction: 'ESM', dir: 'fixtures/source-dir-esm', sentinel: 'source-dir-esm:index-resolved' },
-  { id: 'source-directory import', direction: 'CJS', dir: 'fixtures/source-dir-cjs', sentinel: 'source-dir-cjs:index-resolved' },
-  { id: 'faithful-consumer',       direction: 'ESM', dir: 'fixtures/faithful-esm',   sentinel: 'faithful-esm:my-overrides-resolved' },
-  { id: 'faithful-consumer',       direction: 'CJS', dir: 'fixtures/faithful-cjs',   sentinel: 'faithful-cjs:my-overrides-resolved' },
-];
-
-// Default approaches: baseline + A + B. C only if explicitly requested AND jiti installed.
-const requested = process.argv.slice(2);
-const APPROACHES = requested.length ? requested : ['none', 'A', 'B'];
-
-function runCell(approach, row) {
-  const res = spawnSync('node', [RUNNER, approach, path.resolve(__dirname, row.dir), row.sentinel], {
-    encoding: 'utf-8',
-    cwd: __dirname,
-  });
-  let parsed = null;
-  const line = (res.stdout || '').trim().split('\n').filter(Boolean).pop();
-  try { parsed = JSON.parse(line); } catch { /* runner crashed before emitting */ }
-  if (!parsed) {
-    return { ok: false, sentinel: null, residue: { changed: false }, error: (res.stderr || 'no output').trim().split('\n')[0] };
-  }
-  return parsed;
-}
-
-const results = {}; // approach -> row-index -> cell
-
-for (const approach of APPROACHES) {
-  results[approach] = ROWS.map((row) => runCell(approach, row));
-}
-
-// ---- Print the table ----
-function cellGlyph(cell) {
-  if (cell.ok && !cell.residue.changed) return 'green';
-  if (cell.ok && cell.residue.changed) return 'green*';   // resolved but left residue
-  return 'red';
-}
-
-const label = (r) => `${r.id} [${r.direction}]`;
-const labelW = Math.max(...ROWS.map((r) => label(r).length));
-
-console.log('\n=== Spec 118 Resolution Matrix (real node subprocesses, NOT jest) ===\n');
-const header = ['row'.padEnd(labelW), ...APPROACHES.map((a) => a.padEnd(8))].join(' | ');
-console.log(header);
-console.log('-'.repeat(header.length));
-ROWS.forEach((row, i) => {
-  const cells = APPROACHES.map((a) => cellGlyph(results[a][i]).padEnd(8));
-  console.log([label(row).padEnd(labelW), ...cells].join(' | '));
-});
-
-console.log('\nLegend: green = resolved + sentinel matched + no residue;');
-console.log('        green* = resolved + sentinel matched BUT left global residue (fails criterion e);');
-console.log('        red = resolution failed (fail-loud threw) or sentinel mismatch.\n');
-
-// Per-approach accept-criteria summary.
-console.log('=== Accept-criteria summary (per approach) ===\n');
-const summary = {};
-for (const approach of APPROACHES) {
-  if (approach === 'none') continue;
-  const cells = results[approach];
-  const allResolved = cells.every((c) => c.ok);                // (a)(b)(c) rows green both directions
-  const noResidue = cells.every((c) => !c.residue.changed);    // (e)
-  summary[approach] = { allResolved, noResidue };
-  console.log(`Approach ${approach}:`);
-  console.log(`  (a) failing rows green ......... ${cells.filter(c=>c.ok).length}/${cells.length}`);
-  console.log(`  (b) both CJS & ESM authored .... ${allResolved ? 'PASS' : 'FAIL'}`);
-  console.log(`  (e) no ambient/global residue .. ${noResidue ? 'PASS' : 'FAIL'}`);
-  cells.forEach((c, i) => {
-    if (!c.ok) console.log(`      red [${label(ROWS[i])}]: ${(c.error||'').split('\n')[0]}`);
-    else if (c.residue.changed) console.log(`      residue [${label(ROWS[i])}]: module._resolveFilename not restored`);
-  });
-  console.log('');
-}
-
-// Exit nonzero if no non-baseline approach fully passes (a)(b)(c)+(e).
-const anyFullPass = Object.values(summary).some((s) => s.allResolved && s.noResidue);
-process.exit(anyFullPass ? 0 : 1);

package/src/config/__resolution-matrix__/runner.js

@@ -1,153 +0,0 @@
-#!/usr/bin/env node
-/**
- * Resolution-matrix RUNNER (Spec 118, Task 1).
- *
- * Runs ONE candidate loader against ONE fixture config, inside a FAITHFUL
- * reproduction of `loadConfig`'s load locus, in a REAL `node` process.
- *
- * WHY a real `node` subprocess (THE critical constraint): under ts-jest, jest
- * intercepts `await import()` via its own module registry and never hits Node's
- * strict-ESM resolver — so a jest-hosted matrix goes green against the very bug
- * (proven in-repo by ConfigLoader.test.ts passing today despite the production
- * config-load path being broken). This runner is plain CJS executed by `node`
- * directly (NOT jest, NOT ts-node), so the candidate loader is the ONLY thing
- * that can make a `.ts` config resolve.
- *
- * This file is itself CommonJS (`module.exports` style, `__dirname`/`__filename`
- * present, no `import.meta`) so it reproduces loadConfig's CJS execution context
- * (ConfigLoader.ts:78) — the OQ-1 CJS-host boundary.
- *
- * Contract reproduced from ConfigLoader.ts:57-65 EXACTLY:
- *   - the load locus is a single load call wrapped in try/catch
- *   - unwrap is `loaded.default || loaded`
- *   - failure is RE-WRAPPED and THROWN (fail-loud) — never a partial/empty config
- *
- * Usage:
- *   node runner.js <approach:none|A|B|C> <fixtureDir> <expectedSentinel>
- *
- * Output (always, on stdout): a single JSON line:
- *   { approach, fixtureDir, ok, sentinel, expectedSentinel, residue, error }
- * Exit code 0 if ok && sentinel matches && no residue; non-zero otherwise.
- */
-'use strict';
-
-const path = require('path');
-
-const [, , approach, fixtureDirArg, expectedSentinel] = process.argv;
-
-if (!approach || !fixtureDirArg) {
-  process.stderr.write('usage: node runner.js <approach> <fixtureDir> <expectedSentinel>\n');
-  process.exit(2);
-}
-
-const fixtureDir = path.resolve(fixtureDirArg);
-const configPath = path.resolve(fixtureDir, 'designerpunk.config.ts');
-
-/**
- * The faithful reproduction of loadConfig's load locus.
- * `doLoad(configPath)` MUST throw on resolution failure (fail-loud) and
- * return the unwrapped userConfig on success.
- */
-async function loadWith(approach, configPath) {
-  let loaded;
-
-  if (approach === 'none') {
-    // BASELINE: the current production locus, verbatim (ConfigLoader.ts:59).
-    // No TS-aware loader registered → reproduces the bug.
-    loaded = await import(configPath);
-  } else if (approach === 'A') {
-    // Approach A: tsx/cjs/api register({namespace}) + scoped (synchronous) require.
-    // register mutates module._resolveFilename + module._extensions PROCESS-GLOBALLY;
-    // the namespace only scopes requests. So A MUST call unregister() after the load
-    // to leave no residue (accept-criterion (e)). A's scoped require is SYNCHRONOUS
-    // (ScopedRequire) — `await` on it is harmless (Ada SF-2: do not "fix" it).
-    const { register } = require('tsx/cjs/api');
-    const ns = `dp-matrix-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    const unregister = register({ namespace: ns });
-    try {
-      // The NamespacedUnregister carries a scoped `require(id, fromFile)`.
-      loaded = unregister.require(configPath, __filename);
-    } finally {
-      // Mandatory lifecycle: restore module._resolveFilename (residue criterion).
-      unregister.unregister();
-    }
-  } else if (approach === 'B') {
-    // Approach B: tsImport from tsx/esm/api, invoked from THIS CJS host.
-    // `__filename` exists in CJS so parentURL is clean. tsImport self-scopes
-    // (internal register({namespace: Date.now()}) per call) → no persistent
-    // global hook. OQ-1: does dynamic import() inside the ESM-loader hook
-    // resolve when the host is CJS, incl. the transitive relative raw-`.ts`?
-    const { pathToFileURL } = require('url');
-    const { tsImport } = await import('tsx/esm/api');
-    loaded = await tsImport(configPath, { parentURL: pathToFileURL(__filename).href });
-  } else if (approach === 'C') {
-    // Approach C: jiti (NOT installed unless explicitly added). Budgeted dep.
-    const { createJiti } = require('jiti');
-    const jiti = createJiti(__filename);
-    loaded = await jiti.import(configPath, { default: false });
-  } else {
-    throw new Error(`unknown approach: ${approach}`);
-  }
-
-  // Preserved unwrap (ConfigLoader.ts:60).
-  return loaded && (loaded.default || loaded);
-}
-
-/**
- * Residue probe (accept-criterion (e)): capture module._resolveFilename and the
- * set of registered require extensions BEFORE the load, and confirm they are
- * restored AFTER. A non-restored hook = ambient/global residue.
- */
-function snapshotResolver() {
-  const Module = require('module');
-  return {
-    resolveFilename: Module._resolveFilename,
-    extensions: Object.keys(Module._extensions).sort().join(','),
-  };
-}
-
-(async () => {
-  const result = {
-    approach,
-    fixtureDir,
-    ok: false,
-    sentinel: null,
-    expectedSentinel: expectedSentinel || null,
-    residue: null,
-    error: null,
-  };
-
-  const before = snapshotResolver();
-
-  try {
-    // Faithful reproduction of ConfigLoader.ts:57-65 (the try/catch + re-wrap).
-    let userConfig;
-    try {
-      const loaded = await loadWith(approach, configPath);
-      userConfig = loaded;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new Error(`Failed to load ${configPath}: ${message}`);
-    }
-
-    result.sentinel = userConfig ? userConfig.sentinel : undefined;
-    result.ok = !!userConfig && result.sentinel === expectedSentinel;
-  } catch (err) {
-    result.error = err instanceof Error ? err.message : String(err);
-    result.ok = false;
-  }
-
-  // Residue check after the call (criterion (e)).
-  const after = snapshotResolver();
-  const residueChanged =
-    after.resolveFilename !== before.resolveFilename ||
-    after.extensions !== before.extensions;
-  result.residue = residueChanged
-    ? { changed: true, beforeExtensions: before.extensions, afterExtensions: after.extensions,
-        resolveFilenameChanged: after.resolveFilename !== before.resolveFilename }
-    : { changed: false };
-
-  process.stdout.write(JSON.stringify(result) + '\n');
-  // Exit nonzero on any failure incl. residue (so the orchestrator and CI see it).
-  process.exit(result.ok && !result.residue.changed ? 0 : 1);
-})();