@hyperfrontend/builder 0.1.0 → 0.1.1

package/bundle/declarations/index.esm.js

@@ -4,7 +4,7 @@ import { join as join$2, exists, relativePath, removeDirectory, readFileContent,
 import { from } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
 import { createSet } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
 import { createRequire } from 'node:module';
-import { join as join$1, isAbsolute, resolve, dirname } from 'node:path';
+import { join as join$1, dirname, isAbsolute, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { existsSync, rmSync, mkdtempSync, readFileSync, cpSync, statSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -23,6 +23,70 @@ import { collectChunkSpecifiers, hasDynamicSpecifier } from '../../_shared/bundl
 import { entryDirOf } from '../../_shared/bundle/fs/entry-dir/index.esm.js';
 import { isUnderDir } from '../../_shared/bundle/fs/under-dir/index.esm.js';
 
+const SWC_NODE_REGISTER = '@swc-node/register';
+const probeDir = (dir, offset) => {
+    const compiled = join$1(dir, ...offset, 'index.cjs.js');
+    if (existsSync(compiled))
+        return { path: compiled, execArgv: [] };
+    const source = join$1(dir, ...offset, 'index.ts');
+    if (existsSync(source))
+        return { path: source, execArgv: ['--require', SWC_NODE_REGISTER] };
+    return undefined;
+};
+/**
+ * Directory of the currently-executing builder module, read from `__dirname`.
+ * It is present in the shipped CommonJS build, in the `@swc-node/register` source
+ * bootstrap, and under the test runner, so callers get their own on-disk location
+ * and can find the worker beside them however the builder was packaged.
+ *
+ * @returns Absolute directory path of the running module.
+ *
+ * @example Anchoring a lookup beside the running builder
+ * ```typescript
+ * const invocation = ascendForWorker(['bundle', 'rollup', 'worker'], currentModuleDir())
+ * ```
+ */
+const currentModuleDir = () => {
+    /* istanbul ignore if -- @preserve the ESM build has no __dirname; the shipped CommonJS build and the test runner always define it, so this guard is unreachable under test */
+    if (typeof __dirname === 'undefined') {
+        throw createError('@hyperfrontend/builder self-location requires the CommonJS build; drive build() from the CommonJS entry point');
+    }
+    return __dirname;
+};
+/**
+ * Locate a builder worker entry by ascending from a start directory toward the
+ * filesystem root, returning the first ancestor at which the worker exists at the
+ * given in-package offset. The compiled `index.cjs.js` is preferred; an `index.ts`
+ * sibling (source-mode bootstrap) resolves with the swc loader attached.
+ *
+ * The worker ships inside the builder's own package, so resolving relative to the
+ * running module finds it wherever the package lives — built dist, an installed
+ * `node_modules` copy, or melded into a host bundle under `_dependencies/`.
+ *
+ * @param offset - In-package path segments to the worker directory (e.g. `['bundle', 'rollup', 'worker']`).
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns The resolved worker invocation, or `undefined` if no worker exists at the offset under any ancestor.
+ *
+ * @example Resolving the rollup worker from the running module
+ * ```typescript
+ * const invocation = ascendForWorker(['bundle', 'rollup', 'worker'])
+ * if (!invocation) throw new Error('builder rollup worker not found beside the builder module')
+ * ```
+ */
+const ascendForWorker = (offset, startDir = currentModuleDir()) => {
+    let dir = startDir;
+    let parent = dirname(dir);
+    // how: probe each level then step up; the final probe covers the filesystem root, where parent === dir
+    while (parent !== dir) {
+        const found = probeDir(dir, offset);
+        if (found)
+            return found;
+        dir = parent;
+        parent = dirname(dir);
+    }
+    return probeDir(dir, offset);
+};
+
 const log$4 = logger.channel('builder:bundle:dependencies:pre-pass');
 const REPORT_DIR_PREFIX = 'hf-builder-prepass-';
 const createReportDir = () => mkdtempSync(join$2(tmpdir(), REPORT_DIR_PREFIX));
@@ -59,43 +123,25 @@ const readReport = (reportPath, job) => {
     const data = parse(readFileSync(reportPath, 'utf8'));
     return { job, outputSize: data.outputSize, endHeapMB: data.endHeapMB, endRssMB: data.endRssMB, durationMs: data.durationMs };
 };
-const SWC_NODE_REGISTER = '@swc-node/register';
-const swcNodeAvailable = (workspaceRoot) => existsSync(join$2(workspaceRoot, 'node_modules', '@swc-node', 'register', 'index.js'));
 /**
- * Default worker-path resolution: prefers the built-and-published artifact, falls
- * back to the workspace dist path, and finally to the in-source TypeScript file
- * via `@swc-node/register` (bootstrap case where builder is building itself for
- * the first time and the dist worker doesn't exist yet).
- *
- * Looks at, in order:
- * 1. `<workspaceRoot>/dist/libs/builder/bundle/dependencies/worker/index.cjs.js`
- * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/dependencies/worker/index.cjs.js`
- * 3. `<workspaceRoot>/libs/builder/src/bundle/dependencies/worker/index.ts` (with `--require \@swc-node/register`)
- *
- * @param workspaceRoot - Absolute workspace root.
- * @returns Worker invocation descriptor, or `undefined` if no candidate exists.
- *
- * @example Locating the worker for an in-workspace consumer
+ * Resolves the dependency pre-pass worker by self-locating it beside the running
+ * builder module: ascends from the module's own directory to the builder package
+ * root and returns the worker at `bundle/dependencies/worker`. This works whether
+ * the builder runs from its built dist, an installed `node_modules` copy, or
+ * melded into a host bundle under `_dependencies/`. The compiled `index.cjs.js`
+ * is preferred; an `index.ts` sibling resolves with the `@swc-node/register`
+ * loader for source-mode bootstrap.
+ *
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns Worker invocation descriptor, or `undefined` if no worker is found under any ancestor.
+ *
+ * @example Locating the worker beside the builder
  * ```typescript
- * const invocation = resolveDefaultWorkerPath('/abs/repo')
+ * const invocation = resolveDefaultWorkerPath()
  * if (!invocation) throw new Error('builder worker artifact not found')
  * ```
  */
-const resolveDefaultWorkerPath = (workspaceRoot) => {
-    const distCandidates = [
-        join$2(workspaceRoot, 'dist', 'libs', 'builder', 'bundle', 'dependencies', 'worker', 'index.cjs.js'),
-        join$2(workspaceRoot, 'node_modules', '@hyperfrontend', 'builder', 'bundle', 'dependencies', 'worker', 'index.cjs.js'),
-    ];
-    for (const path of distCandidates) {
-        if (existsSync(path))
-            return { path, execArgv: [] };
-    }
-    const sourcePath = join$2(workspaceRoot, 'libs', 'builder', 'src', 'bundle', 'dependencies', 'worker', 'index.ts');
-    if (existsSync(sourcePath) && swcNodeAvailable(workspaceRoot)) {
-        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER] };
-    }
-    return undefined;
-};
+const resolveDefaultWorkerPath = (startDir) => ascendForWorker(['bundle', 'dependencies', 'worker'], startDir);
 /**
  * Sequentially runs the supplied pre-pass jobs by forking a fresh Node child
  * per invocation. Strict sequential execution is mandatory — concurrent
@@ -401,9 +447,9 @@ const buildJobs$1 = (entries, context) => {
 const runDtsPerEntry = async (context, monitor) => {
     if (context.bundledDeps.length === 0 && context.workspaceBundledDeps.length === 0)
         return;
-    const invocation = resolveDefaultWorkerPath(context.workspaceRoot);
+    const invocation = resolveDefaultWorkerPath();
     if (!invocation) {
-        throw createError('bundleAllDeps is enabled but the pre-pass worker artifact was not found for the per-entry d.ts pass.');
+        throw createError('bundleAllDeps is enabled but the pre-pass worker could not be located beside the builder module for the per-entry d.ts pass.');
     }
     const jobs = buildJobs$1(context.entryPointDiscovery.entryPoints, context);
     if (jobs.length === 0) {
@@ -585,9 +631,9 @@ const buildWorkspaceJobs = (context, npmDeps) => {
 const runDtsPrePass = async (context, monitor) => {
     if (context.bundledDeps.length === 0 && context.workspaceBundledDeps.length === 0)
         return;
-    const invocation = resolveDefaultWorkerPath(context.workspaceRoot);
+    const invocation = resolveDefaultWorkerPath();
     if (!invocation) {
-        throw createError('bundleAllDeps is enabled but the pre-pass worker artifact was not found for the d.ts pre-pass.');
+        throw createError('bundleAllDeps is enabled but the pre-pass worker could not be located beside the builder module for the d.ts pre-pass.');
     }
     const npmJobs = buildJobs(context.bundledDeps, context);
     const workspaceJobs = buildWorkspaceJobs(context, context.bundledDeps);

package/bundle/dependencies/index.cjs.js

@@ -5,11 +5,11 @@ const node_path = require('node:path');
 const node_child_process = require('node:child_process');
 const node_fs = require('node:fs');
 const node_os = require('node:os');
-const index_cjs_js$4 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
-const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
-const index_cjs_js$2 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
-const index_cjs_js = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
-const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/project-scope/core/index.cjs.js');
+const index_cjs_js = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js$4 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
+const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
+const index_cjs_js$2 = require('../../_dependencies/@hyperfrontend/project-scope/core/index.cjs.js');
 const index_cjs_js$7 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
 const index_cjs_js$6 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
 const index_cjs_js$5 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js');
@@ -31,13 +31,77 @@ const json__default = /*#__PURE__*/_interopDefaultCompat(json);
 const nodeResolve__default = /*#__PURE__*/_interopDefaultCompat(nodeResolve);
 const typescript__default = /*#__PURE__*/_interopDefaultCompat(typescript);
 
-const log = index_cjs_js.logger.channel('builder:bundle:dependencies:pre-pass');
+const SWC_NODE_REGISTER = '@swc-node/register';
+const probeDir = (dir, offset) => {
+    const compiled = node_path.join(dir, ...offset, 'index.cjs.js');
+    if (node_fs.existsSync(compiled))
+        return { path: compiled, execArgv: [] };
+    const source = node_path.join(dir, ...offset, 'index.ts');
+    if (node_fs.existsSync(source))
+        return { path: source, execArgv: ['--require', SWC_NODE_REGISTER] };
+    return undefined;
+};
+/**
+ * Directory of the currently-executing builder module, read from `__dirname`.
+ * It is present in the shipped CommonJS build, in the `@swc-node/register` source
+ * bootstrap, and under the test runner, so callers get their own on-disk location
+ * and can find the worker beside them however the builder was packaged.
+ *
+ * @returns Absolute directory path of the running module.
+ *
+ * @example Anchoring a lookup beside the running builder
+ * ```typescript
+ * const invocation = ascendForWorker(['bundle', 'rollup', 'worker'], currentModuleDir())
+ * ```
+ */
+const currentModuleDir = () => {
+    /* istanbul ignore if -- @preserve the ESM build has no __dirname; the shipped CommonJS build and the test runner always define it, so this guard is unreachable under test */
+    if (typeof __dirname === 'undefined') {
+        throw index_cjs_js.createError('@hyperfrontend/builder self-location requires the CommonJS build; drive build() from the CommonJS entry point');
+    }
+    return __dirname;
+};
+/**
+ * Locate a builder worker entry by ascending from a start directory toward the
+ * filesystem root, returning the first ancestor at which the worker exists at the
+ * given in-package offset. The compiled `index.cjs.js` is preferred; an `index.ts`
+ * sibling (source-mode bootstrap) resolves with the swc loader attached.
+ *
+ * The worker ships inside the builder's own package, so resolving relative to the
+ * running module finds it wherever the package lives — built dist, an installed
+ * `node_modules` copy, or melded into a host bundle under `_dependencies/`.
+ *
+ * @param offset - In-package path segments to the worker directory (e.g. `['bundle', 'rollup', 'worker']`).
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns The resolved worker invocation, or `undefined` if no worker exists at the offset under any ancestor.
+ *
+ * @example Resolving the rollup worker from the running module
+ * ```typescript
+ * const invocation = ascendForWorker(['bundle', 'rollup', 'worker'])
+ * if (!invocation) throw new Error('builder rollup worker not found beside the builder module')
+ * ```
+ */
+const ascendForWorker = (offset, startDir = currentModuleDir()) => {
+    let dir = startDir;
+    let parent = node_path.dirname(dir);
+    // how: probe each level then step up; the final probe covers the filesystem root, where parent === dir
+    while (parent !== dir) {
+        const found = probeDir(dir, offset);
+        if (found)
+            return found;
+        dir = parent;
+        parent = node_path.dirname(dir);
+    }
+    return probeDir(dir, offset);
+};
+
+const log = index_cjs_js$1.logger.channel('builder:bundle:dependencies:pre-pass');
 const REPORT_DIR_PREFIX = 'hf-builder-prepass-';
-const createReportDir = () => node_fs.mkdtempSync(index_cjs_js$1.join(node_os.tmpdir(), REPORT_DIR_PREFIX));
-const reportPathFor = (reportDir, job, index) => index_cjs_js$1.join(reportDir, `${index}-${job.dep.replace(/\//g, '__')}-${job.kind}-${job.format}.json`);
-const runOne = (job, reportPath, options) => index_cjs_js$2.createPromise((resolve, reject) => {
+const createReportDir = () => node_fs.mkdtempSync(index_cjs_js$2.join(node_os.tmpdir(), REPORT_DIR_PREFIX));
+const reportPathFor = (reportDir, job, index) => index_cjs_js$2.join(reportDir, `${index}-${job.dep.replace(/\//g, '__')}-${job.kind}-${job.format}.json`);
+const runOne = (job, reportPath, options) => index_cjs_js$3.createPromise((resolve, reject) => {
     const execPath = options.execPath ?? process.execPath;
-    const argv = [...(options.execArgv ?? []), options.workerPath, index_cjs_js$3.stringify({ ...job, reportPath })];
+    const argv = [...(options.execArgv ?? []), options.workerPath, index_cjs_js$4.stringify({ ...job, reportPath })];
     const child = node_child_process.spawn(execPath, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
     let capturedStderr = '';
     child.stdout?.on('data', (chunk) => {
@@ -49,12 +113,12 @@ const runOne = (job, reportPath, options) => index_cjs_js$2.createPromise((resol
         process.stderr.write(text);
     });
     child.on('error', (error) => {
-        reject(index_cjs_js$4.createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) failed to spawn: ${error.message}`));
+        reject(index_cjs_js.createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) failed to spawn: ${error.message}`));
     });
     child.on('exit', (code) => {
         if (code !== 0) {
             const tail = capturedStderr.trim().split('\n').slice(-10).join('\n');
-            reject(index_cjs_js$4.createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) exited with code ${code}\n${tail}`));
+            reject(index_cjs_js.createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) exited with code ${code}\n${tail}`));
             return;
         }
         resolve();
@@ -62,48 +126,30 @@ const runOne = (job, reportPath, options) => index_cjs_js$2.createPromise((resol
 });
 const readReport = (reportPath, job) => {
     if (!node_fs.existsSync(reportPath)) {
-        throw index_cjs_js$4.createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) did not write a report at ${reportPath}`);
+        throw index_cjs_js.createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) did not write a report at ${reportPath}`);
     }
-    const data = index_cjs_js$3.parse(node_fs.readFileSync(reportPath, 'utf8'));
+    const data = index_cjs_js$4.parse(node_fs.readFileSync(reportPath, 'utf8'));
     return { job, outputSize: data.outputSize, endHeapMB: data.endHeapMB, endRssMB: data.endRssMB, durationMs: data.durationMs };
 };
-const SWC_NODE_REGISTER = '@swc-node/register';
-const swcNodeAvailable = (workspaceRoot) => node_fs.existsSync(index_cjs_js$1.join(workspaceRoot, 'node_modules', '@swc-node', 'register', 'index.js'));
 /**
- * Default worker-path resolution: prefers the built-and-published artifact, falls
- * back to the workspace dist path, and finally to the in-source TypeScript file
- * via `@swc-node/register` (bootstrap case where builder is building itself for
- * the first time and the dist worker doesn't exist yet).
- *
- * Looks at, in order:
- * 1. `<workspaceRoot>/dist/libs/builder/bundle/dependencies/worker/index.cjs.js`
- * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/dependencies/worker/index.cjs.js`
- * 3. `<workspaceRoot>/libs/builder/src/bundle/dependencies/worker/index.ts` (with `--require \@swc-node/register`)
- *
- * @param workspaceRoot - Absolute workspace root.
- * @returns Worker invocation descriptor, or `undefined` if no candidate exists.
- *
- * @example Locating the worker for an in-workspace consumer
+ * Resolves the dependency pre-pass worker by self-locating it beside the running
+ * builder module: ascends from the module's own directory to the builder package
+ * root and returns the worker at `bundle/dependencies/worker`. This works whether
+ * the builder runs from its built dist, an installed `node_modules` copy, or
+ * melded into a host bundle under `_dependencies/`. The compiled `index.cjs.js`
+ * is preferred; an `index.ts` sibling resolves with the `@swc-node/register`
+ * loader for source-mode bootstrap.
+ *
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns Worker invocation descriptor, or `undefined` if no worker is found under any ancestor.
+ *
+ * @example Locating the worker beside the builder
  * ```typescript
- * const invocation = resolveDefaultWorkerPath('/abs/repo')
+ * const invocation = resolveDefaultWorkerPath()
  * if (!invocation) throw new Error('builder worker artifact not found')
  * ```
  */
-const resolveDefaultWorkerPath = (workspaceRoot) => {
-    const distCandidates = [
-        index_cjs_js$1.join(workspaceRoot, 'dist', 'libs', 'builder', 'bundle', 'dependencies', 'worker', 'index.cjs.js'),
-        index_cjs_js$1.join(workspaceRoot, 'node_modules', '@hyperfrontend', 'builder', 'bundle', 'dependencies', 'worker', 'index.cjs.js'),
-    ];
-    for (const path of distCandidates) {
-        if (node_fs.existsSync(path))
-            return { path, execArgv: [] };
-    }
-    const sourcePath = index_cjs_js$1.join(workspaceRoot, 'libs', 'builder', 'src', 'bundle', 'dependencies', 'worker', 'index.ts');
-    if (node_fs.existsSync(sourcePath) && swcNodeAvailable(workspaceRoot)) {
-        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER] };
-    }
-    return undefined;
-};
+const resolveDefaultWorkerPath = (startDir) => ascendForWorker(['bundle', 'dependencies', 'worker'], startDir);
 /**
  * Sequentially runs the supplied pre-pass jobs by forking a fresh Node child
  * per invocation. Strict sequential execution is mandatory — concurrent
@@ -425,13 +471,13 @@ const resolveWorkspaceBundledDeps = (packageJsonPath, workspaceRoot, options) =>
     for (const packageName of filtered) {
         const matches = collectMatchingSpecifiers(packageName, mappings);
         if (matches.length === 0) {
-            throw index_cjs_js$4.createError(`bundleAllDeps: workspace dependency "${packageName}" has no resolvable tsconfig path mapping under ${workspaceRoot} (no matching paths entry, or its mapped source files are missing), so it cannot be bundled. Add a "${packageName}" (or "${packageName}/<sub-path>") entry to tsconfig.base.json paths pointing at an existing source file, or exclude it via bundleAllDeps.exclude.`);
+            throw index_cjs_js.createError(`bundleAllDeps: workspace dependency "${packageName}" has no resolvable tsconfig path mapping under ${workspaceRoot} (no matching paths entry, or its mapped source files are missing), so it cannot be bundled. Add a "${packageName}" (or "${packageName}/<sub-path>") entry to tsconfig.base.json paths pointing at an existing source file, or exclude it via bundleAllDeps.exclude.`);
         }
         const policy = policyFor(packageName);
         const pushEntry = (specifier, inputPath) => {
             const tsConfigPath = resolveTsConfigForPackage(inputPath);
             if (!tsConfigPath) {
-                throw index_cjs_js$4.createError(`bundleAllDeps: workspace dependency "${specifier}" resolves to ${inputPath}, but no tsconfig (tsconfig.lib.json / tsconfig.json) was found in its project root, so it cannot be transformed during bundling.`);
+                throw index_cjs_js.createError(`bundleAllDeps: workspace dependency "${specifier}" resolves to ${inputPath}, but no tsconfig (tsconfig.lib.json / tsconfig.json) was found in its project root, so it cannot be transformed during bundling.`);
             }
             const split = splitSpecifier(specifier);
             results.push({ packageName, subPath: split.subPath, specifier, inputPath, tsConfigPath, policy });
@@ -439,7 +485,7 @@ const resolveWorkspaceBundledDeps = (packageJsonPath, workspaceRoot, options) =>
         if (policy === 'whole-surface') {
             const root = matches.find((m) => m.specifier === packageName);
             if (!root) {
-                throw index_cjs_js$4.createError(`bundleAllDeps: workspace dependency "${packageName}" is explicitly set to the 'whole-surface' hoist policy but is subpath-only (no root export; tsconfig exposes only ${matches.map((m) => `"${m.specifier}"`).join(', ')}). Remove the 'whole-surface' override for it (sub-path is the default), or add a root export.`);
+                throw index_cjs_js.createError(`bundleAllDeps: workspace dependency "${packageName}" is explicitly set to the 'whole-surface' hoist policy but is subpath-only (no root export; tsconfig exposes only ${matches.map((m) => `"${m.specifier}"`).join(', ')}). Remove the 'whole-surface' override for it (sub-path is the default), or add a root export.`);
             }
             pushEntry(root.specifier, root.inputPath);
             continue;

package/bundle/dependencies/index.d.ts

@@ -1,6 +1,7 @@
 import { Plugin } from '../../_dependencies/rollup/index.js';
 import { WorkspaceBundledDep, IsWorkspacePackagePredicate, WorkspaceDepHoistPolicy } from '../../models';
 import { MemoryMonitor } from '../../memory';
+import { WorkerInvocation } from '..';
 export { PrePassWorkerJob, PrePassWorkerReport, runPrePassWorkerJob } from './worker';
 
 /**
@@ -199,36 +200,24 @@ interface RunPrePassOptions {
     execArgv?: string[];
 }
 /**
- * Resolved worker invocation: absolute path + any extra Node args (e.g. `--require \@swc-node/register`
- * when the worker is loaded from TypeScript source during a bootstrap build).
- */
-interface WorkerInvocation {
-    /** Absolute path to the worker entry script. */
-    path: string;
-    /** Extra args prepended to the spawned child's argv. */
-    execArgv: string[];
-}
-/**
- * Default worker-path resolution: prefers the built-and-published artifact, falls
- * back to the workspace dist path, and finally to the in-source TypeScript file
- * via `@swc-node/register` (bootstrap case where builder is building itself for
- * the first time and the dist worker doesn't exist yet).
+ * Resolves the dependency pre-pass worker by self-locating it beside the running
+ * builder module: ascends from the module's own directory to the builder package
+ * root and returns the worker at `bundle/dependencies/worker`. This works whether
+ * the builder runs from its built dist, an installed `node_modules` copy, or
+ * melded into a host bundle under `_dependencies/`. The compiled `index.cjs.js`
+ * is preferred; an `index.ts` sibling resolves with the `@swc-node/register`
+ * loader for source-mode bootstrap.
  *
- * Looks at, in order:
- * 1. `<workspaceRoot>/dist/libs/builder/bundle/dependencies/worker/index.cjs.js`
- * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/dependencies/worker/index.cjs.js`
- * 3. `<workspaceRoot>/libs/builder/src/bundle/dependencies/worker/index.ts` (with `--require \@swc-node/register`)
- *
- * @param workspaceRoot - Absolute workspace root.
- * @returns Worker invocation descriptor, or `undefined` if no candidate exists.
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns Worker invocation descriptor, or `undefined` if no worker is found under any ancestor.
  *
- * @example Locating the worker for an in-workspace consumer
+ * @example Locating the worker beside the builder
  * ```typescript
- * const invocation = resolveDefaultWorkerPath('/abs/repo')
+ * const invocation = resolveDefaultWorkerPath()
  * if (!invocation) throw new Error('builder worker artifact not found')
  * ```
  */
-declare const resolveDefaultWorkerPath: (workspaceRoot: string) => WorkerInvocation | undefined;
+declare const resolveDefaultWorkerPath: (startDir?: string) => WorkerInvocation | undefined;
 /**
  * Sequentially runs the supplied pre-pass jobs by forking a fresh Node child
  * per invocation. Strict sequential execution is mandatory — concurrent

package/bundle/dependencies/index.esm.js

@@ -1,5 +1,5 @@
 import { isBuiltin } from 'node:module';
-import { join as join$1, relative, isAbsolute, resolve, dirname } from 'node:path';
+import { join as join$1, relative, dirname, isAbsolute, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { existsSync, rmSync, mkdtempSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -22,6 +22,70 @@ import { rollup } from '../../_dependencies/rollup/index.esm.js';
 import { normalizeToForwardSlashes, join } from '../../_shared/bundle/fs/posix-path/index.esm.js';
 import { relativeImport, buildWorkspaceRoutes, createExternalizeBundledDepsPlugin } from '../../_shared/bundle/dependencies/externalize-plugin/index.esm.js';
 
+const SWC_NODE_REGISTER = '@swc-node/register';
+const probeDir = (dir, offset) => {
+    const compiled = join$1(dir, ...offset, 'index.cjs.js');
+    if (existsSync(compiled))
+        return { path: compiled, execArgv: [] };
+    const source = join$1(dir, ...offset, 'index.ts');
+    if (existsSync(source))
+        return { path: source, execArgv: ['--require', SWC_NODE_REGISTER] };
+    return undefined;
+};
+/**
+ * Directory of the currently-executing builder module, read from `__dirname`.
+ * It is present in the shipped CommonJS build, in the `@swc-node/register` source
+ * bootstrap, and under the test runner, so callers get their own on-disk location
+ * and can find the worker beside them however the builder was packaged.
+ *
+ * @returns Absolute directory path of the running module.
+ *
+ * @example Anchoring a lookup beside the running builder
+ * ```typescript
+ * const invocation = ascendForWorker(['bundle', 'rollup', 'worker'], currentModuleDir())
+ * ```
+ */
+const currentModuleDir = () => {
+    /* istanbul ignore if -- @preserve the ESM build has no __dirname; the shipped CommonJS build and the test runner always define it, so this guard is unreachable under test */
+    if (typeof __dirname === 'undefined') {
+        throw createError('@hyperfrontend/builder self-location requires the CommonJS build; drive build() from the CommonJS entry point');
+    }
+    return __dirname;
+};
+/**
+ * Locate a builder worker entry by ascending from a start directory toward the
+ * filesystem root, returning the first ancestor at which the worker exists at the
+ * given in-package offset. The compiled `index.cjs.js` is preferred; an `index.ts`
+ * sibling (source-mode bootstrap) resolves with the swc loader attached.
+ *
+ * The worker ships inside the builder's own package, so resolving relative to the
+ * running module finds it wherever the package lives — built dist, an installed
+ * `node_modules` copy, or melded into a host bundle under `_dependencies/`.
+ *
+ * @param offset - In-package path segments to the worker directory (e.g. `['bundle', 'rollup', 'worker']`).
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns The resolved worker invocation, or `undefined` if no worker exists at the offset under any ancestor.
+ *
+ * @example Resolving the rollup worker from the running module
+ * ```typescript
+ * const invocation = ascendForWorker(['bundle', 'rollup', 'worker'])
+ * if (!invocation) throw new Error('builder rollup worker not found beside the builder module')
+ * ```
+ */
+const ascendForWorker = (offset, startDir = currentModuleDir()) => {
+    let dir = startDir;
+    let parent = dirname(dir);
+    // how: probe each level then step up; the final probe covers the filesystem root, where parent === dir
+    while (parent !== dir) {
+        const found = probeDir(dir, offset);
+        if (found)
+            return found;
+        dir = parent;
+        parent = dirname(dir);
+    }
+    return probeDir(dir, offset);
+};
+
 const log = logger.channel('builder:bundle:dependencies:pre-pass');
 const REPORT_DIR_PREFIX = 'hf-builder-prepass-';
 const createReportDir = () => mkdtempSync(join$2(tmpdir(), REPORT_DIR_PREFIX));
@@ -58,43 +122,25 @@ const readReport = (reportPath, job) => {
     const data = parse(readFileSync(reportPath, 'utf8'));
     return { job, outputSize: data.outputSize, endHeapMB: data.endHeapMB, endRssMB: data.endRssMB, durationMs: data.durationMs };
 };
-const SWC_NODE_REGISTER = '@swc-node/register';
-const swcNodeAvailable = (workspaceRoot) => existsSync(join$2(workspaceRoot, 'node_modules', '@swc-node', 'register', 'index.js'));
 /**
- * Default worker-path resolution: prefers the built-and-published artifact, falls
- * back to the workspace dist path, and finally to the in-source TypeScript file
- * via `@swc-node/register` (bootstrap case where builder is building itself for
- * the first time and the dist worker doesn't exist yet).
- *
- * Looks at, in order:
- * 1. `<workspaceRoot>/dist/libs/builder/bundle/dependencies/worker/index.cjs.js`
- * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/dependencies/worker/index.cjs.js`
- * 3. `<workspaceRoot>/libs/builder/src/bundle/dependencies/worker/index.ts` (with `--require \@swc-node/register`)
- *
- * @param workspaceRoot - Absolute workspace root.
- * @returns Worker invocation descriptor, or `undefined` if no candidate exists.
- *
- * @example Locating the worker for an in-workspace consumer
+ * Resolves the dependency pre-pass worker by self-locating it beside the running
+ * builder module: ascends from the module's own directory to the builder package
+ * root and returns the worker at `bundle/dependencies/worker`. This works whether
+ * the builder runs from its built dist, an installed `node_modules` copy, or
+ * melded into a host bundle under `_dependencies/`. The compiled `index.cjs.js`
+ * is preferred; an `index.ts` sibling resolves with the `@swc-node/register`
+ * loader for source-mode bootstrap.
+ *
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns Worker invocation descriptor, or `undefined` if no worker is found under any ancestor.
+ *
+ * @example Locating the worker beside the builder
  * ```typescript
- * const invocation = resolveDefaultWorkerPath('/abs/repo')
+ * const invocation = resolveDefaultWorkerPath()
  * if (!invocation) throw new Error('builder worker artifact not found')
  * ```
  */
-const resolveDefaultWorkerPath = (workspaceRoot) => {
-    const distCandidates = [
-        join$2(workspaceRoot, 'dist', 'libs', 'builder', 'bundle', 'dependencies', 'worker', 'index.cjs.js'),
-        join$2(workspaceRoot, 'node_modules', '@hyperfrontend', 'builder', 'bundle', 'dependencies', 'worker', 'index.cjs.js'),
-    ];
-    for (const path of distCandidates) {
-        if (existsSync(path))
-            return { path, execArgv: [] };
-    }
-    const sourcePath = join$2(workspaceRoot, 'libs', 'builder', 'src', 'bundle', 'dependencies', 'worker', 'index.ts');
-    if (existsSync(sourcePath) && swcNodeAvailable(workspaceRoot)) {
-        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER] };
-    }
-    return undefined;
-};
+const resolveDefaultWorkerPath = (startDir) => ascendForWorker(['bundle', 'dependencies', 'worker'], startDir);
 /**
  * Sequentially runs the supplied pre-pass jobs by forking a fresh Node child
  * per invocation. Strict sequential execution is mandatory — concurrent

package/bundle/dependencies/pre-pass.d.ts

@@ -1,4 +1,5 @@
 import type { MemoryMonitor } from '../../memory/monitor';
+import type { WorkerInvocation } from '../worker-locator';
 import type { WorkspaceBundledDepRoute } from './externalize-plugin';
 /**
  * Pre-pass kind. Mirrors `PrePassWorkerJobKind` on the worker side.
@@ -98,36 +99,24 @@ export interface RunPrePassOptions {
     execArgv?: string[];
 }
 /**
- * Resolved worker invocation: absolute path + any extra Node args (e.g. `--require \@swc-node/register`
- * when the worker is loaded from TypeScript source during a bootstrap build).
- */
-export interface WorkerInvocation {
-    /** Absolute path to the worker entry script. */
-    path: string;
-    /** Extra args prepended to the spawned child's argv. */
-    execArgv: string[];
-}
-/**
- * Default worker-path resolution: prefers the built-and-published artifact, falls
- * back to the workspace dist path, and finally to the in-source TypeScript file
- * via `@swc-node/register` (bootstrap case where builder is building itself for
- * the first time and the dist worker doesn't exist yet).
- *
- * Looks at, in order:
- * 1. `<workspaceRoot>/dist/libs/builder/bundle/dependencies/worker/index.cjs.js`
- * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/dependencies/worker/index.cjs.js`
- * 3. `<workspaceRoot>/libs/builder/src/bundle/dependencies/worker/index.ts` (with `--require \@swc-node/register`)
+ * Resolves the dependency pre-pass worker by self-locating it beside the running
+ * builder module: ascends from the module's own directory to the builder package
+ * root and returns the worker at `bundle/dependencies/worker`. This works whether
+ * the builder runs from its built dist, an installed `node_modules` copy, or
+ * melded into a host bundle under `_dependencies/`. The compiled `index.cjs.js`
+ * is preferred; an `index.ts` sibling resolves with the `@swc-node/register`
+ * loader for source-mode bootstrap.
  *
- * @param workspaceRoot - Absolute workspace root.
- * @returns Worker invocation descriptor, or `undefined` if no candidate exists.
+ * @param startDir - Directory to begin the ascent from. Defaults to the running module's directory; pass an explicit value to resolve from another anchor or under test.
+ * @returns Worker invocation descriptor, or `undefined` if no worker is found under any ancestor.
  *
- * @example Locating the worker for an in-workspace consumer
+ * @example Locating the worker beside the builder
  * ```typescript
- * const invocation = resolveDefaultWorkerPath('/abs/repo')
+ * const invocation = resolveDefaultWorkerPath()
  * if (!invocation) throw new Error('builder worker artifact not found')
  * ```
  */
-export declare const resolveDefaultWorkerPath: (workspaceRoot: string) => WorkerInvocation | undefined;
+export declare const resolveDefaultWorkerPath: (startDir?: string) => WorkerInvocation | undefined;
 /**
  * Sequentially runs the supplied pre-pass jobs by forking a fresh Node child
  * per invocation. Strict sequential execution is mandatory — concurrent