@hyperfrontend/builder 0.1.0

package/bundle/declarations/index.esm.js

@@ -0,0 +1,857 @@
+import { createError } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { logger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { join as join$2, exists, relativePath, removeDirectory, readFileContent, getDirname, readDirectory } from '../../_dependencies/@hyperfrontend/project-scope/core/index.esm.js';
+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 { spawn } from 'node:child_process';
+import { existsSync, rmSync, mkdtempSync, readFileSync, cpSync, statSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { stringify, parse } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
+import { createPromise } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
+import { readJsonFileIfExists, exists as exists$1 } from '../../_dependencies/@hyperfrontend/project-scope/core/fs/index.esm.js';
+import { join as join$3, normalizeToForwardSlashes as normalizeToForwardSlashes$1 } from '../../_dependencies/@hyperfrontend/project-scope/core/path/index.esm.js';
+import { dateNow } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.esm.js';
+import { clearInterval, setInterval } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.esm.js';
+import { normalizeToForwardSlashes, join } from '../../_shared/bundle/fs/posix-path/index.esm.js';
+import { buildWorkspaceRoutes } from '../../_shared/bundle/dependencies/externalize-plugin/index.esm.js';
+import { depsRootOf } from '../../_shared/bundle/fs/deps-root/index.esm.js';
+import { collectWorkspacePrefixDeps, collectWorkspaceExactSpecifiers } from '../../_shared/bundle/dependencies/collect-workspace-deps/index.esm.js';
+import { flattenDeclarationPaths } from '../../_shared/bundle/declarations/flatten-paths/index.esm.js';
+import { collectChunkSpecifiers, hasDynamicSpecifier } from '../../_shared/bundle/dependencies/prune/specifiers/index.esm.js';
+import { entryDirOf } from '../../_shared/bundle/fs/entry-dir/index.esm.js';
+import { isUnderDir } from '../../_shared/bundle/fs/under-dir/index.esm.js';
+
+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));
+const reportPathFor = (reportDir, job, index) => join$2(reportDir, `${index}-${job.dep.replace(/\//g, '__')}-${job.kind}-${job.format}.json`);
+const runOne = (job, reportPath, options) => createPromise((resolve, reject) => {
+    const execPath = options.execPath ?? process.execPath;
+    const argv = [...(options.execArgv ?? []), options.workerPath, stringify({ ...job, reportPath })];
+    const child = spawn(execPath, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let capturedStderr = '';
+    child.stdout?.on('data', (chunk) => {
+        process.stdout.write(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+        const text = typeof chunk === 'string' ? chunk : chunk.toString();
+        capturedStderr += text;
+        process.stderr.write(text);
+    });
+    child.on('error', (error) => {
+        reject(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(createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) exited with code ${code}\n${tail}`));
+            return;
+        }
+        resolve();
+    });
+});
+const readReport = (reportPath, job) => {
+    if (!existsSync(reportPath)) {
+        throw createError(`pre-pass worker for ${job.dep} (${job.kind}/${job.format}) did not write a report at ${reportPath}`);
+    }
+    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
+ * ```typescript
+ * const invocation = resolveDefaultWorkerPath('/abs/repo')
+ * 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;
+};
+/**
+ * Sequentially runs the supplied pre-pass jobs by forking a fresh Node child
+ * per invocation. Strict sequential execution is mandatory — concurrent
+ * children would simultaneously pressure RAM and OOM the container.
+ *
+ * Each child writes a JSON report to a parent-supplied path; this function
+ * reads the report after the child exits and accumulates per-job statistics.
+ * If any worker exits non-zero or fails to produce a report, the function
+ * throws with the failed job's context.
+ *
+ * The report directory is created in the OS temp dir and removed before
+ * returning, regardless of success or failure.
+ *
+ * @param jobs - Pre-pass jobs to run.
+ * @param options - Worker path + optional memory monitor.
+ * @returns One result per supplied job, in the order the jobs were given.
+ *
+ * @example Pre-passing rollup and one of its plugins
+ * ```typescript
+ * const results = await runPrePass(jobs, { workerPath: '/abs/dist/libs/builder/bundle/dependencies/worker.cjs.js' })
+ * ```
+ */
+const runPrePass = async (jobs, options) => {
+    if (jobs.length === 0)
+        return [];
+    const reportDir = createReportDir();
+    const results = [];
+    try {
+        for (const [index, job] of jobs.entries()) {
+            const reportPath = reportPathFor(reportDir, job, index);
+            log$4.info(`pre-pass ${index + 1}/${jobs.length}: ${job.dep} (${job.kind}/${job.format})`);
+            options.monitor?.check(`bundle:dependencies:prepass:${index + 1}/${jobs.length}:${job.dep}:${job.kind}:${job.format}:start`);
+            await runOne(job, reportPath, options);
+            const result = readReport(reportPath, job);
+            log$4.debug(`pre-pass ${index + 1}/${jobs.length} done: ${job.dep} size=${result.outputSize}B heap=${result.endHeapMB.toFixed(1)}MB rss=${result.endRssMB.toFixed(1)}MB t=${result.durationMs}ms`);
+            options.monitor?.check(`bundle:dependencies:prepass:${index + 1}/${jobs.length}:${job.dep}:${job.kind}:${job.format}:end`);
+            results.push(result);
+        }
+        return results;
+    }
+    finally {
+        rmSync(reportDir, { recursive: true, force: true });
+    }
+};
+
+const stripTrailingIndexDts = (filePath) => {
+    const normalized = normalizeToForwardSlashes(filePath);
+    const trimmed = normalized.replace(/\/index\.d\.ts$/, '');
+    return trimmed === normalized ? normalized.replace(/\.d\.ts$/, '') : trimmed;
+};
+const stripTrailingSlash = (value) => (value.endsWith('/') ? value.slice(0, -1) : value);
+const dirnameOf = (filePath) => {
+    const normalized = normalizeToForwardSlashes(filePath);
+    const idx = normalized.lastIndexOf('/');
+    return idx <= 0 ? normalized : normalized.slice(0, idx);
+};
+/**
+ * Computes the directory (without trailing slash) that owns a sibling's
+ * `index.d.ts`. Used to test whether an absolute resolved id falls inside the
+ * sibling's directory tree.
+ *
+ * @param sibling - Sibling-entry record.
+ * @returns Sibling's directory with no trailing slash.
+ */
+const siblingDir = (sibling) => stripTrailingSlash(dirnameOf(sibling.indexDtsPath));
+const startsWithDir = (resolved, dir) => {
+    const normalizedResolved = normalizeToForwardSlashes(resolved);
+    if (normalizedResolved === dir)
+        return true;
+    return normalizedResolved.startsWith(`${dir}/`);
+};
+/**
+ * Returns the sibling entry whose directory contains `absolutePath`, or `undefined`
+ * when no sibling owns the path.
+ *
+ * @param absolutePath - Resolved absolute path of an import.
+ * @param siblings - Sibling-entry records.
+ * @returns Owning sibling entry, or `undefined`.
+ *
+ * @example Identifying a sibling for a resolved type import
+ * ```typescript
+ * const owner = findOwningSibling('/abs/dist/libs/foo/models/index.d.ts', siblings)
+ * ```
+ */
+const findOwningSibling = (absolutePath, siblings) => {
+    const normalized = normalizeToForwardSlashes(absolutePath);
+    let best;
+    let bestDirLength = -1;
+    for (const sibling of siblings) {
+        const dir = siblingDir(sibling);
+        if (!startsWithDir(normalized, dir))
+            continue;
+        if (dir.length > bestDirLength) {
+            best = sibling;
+            bestDirLength = dir.length;
+        }
+    }
+    return best;
+};
+/**
+ * Computes the bare-specifier form of a sibling import as emitted in the
+ * rewritten `.d.ts` (e.g., `../models`, `../../models`, `./bundle/declarations`).
+ *
+ * Always omits the trailing `index.d.ts` so both `moduleResolution: 'bundler'`
+ * and `node` accept it.
+ *
+ * @param selfDtsPath - Absolute path to the current entry's `index.d.ts`.
+ * @param sibling - The sibling entry being targeted.
+ * @returns POSIX-style relative specifier ready for `id` in a rollup external resolution.
+ *
+ * @example Computing a sibling import from `bundle/index.d.ts` to `models/`
+ * ```typescript
+ * computeSiblingSpecifier(
+ *   '/abs/dist/libs/foo/bundle/index.d.ts',
+ *   { srcPath: 'models', indexDtsPath: '/abs/dist/libs/foo/models/index.d.ts' }
+ * ) // => '../models'
+ * ```
+ */
+const computeSiblingSpecifier = (selfDtsPath, sibling) => {
+    const fromDir = dirnameOf(selfDtsPath);
+    const toDir = siblingDir(sibling);
+    const fromSegments = fromDir.split('/').filter((s) => s.length > 0);
+    const toSegments = toDir.split('/').filter((s) => s.length > 0);
+    let common = 0;
+    while (common < fromSegments.length && common < toSegments.length && fromSegments[common] === toSegments[common]) {
+        common += 1;
+    }
+    const upSegments = fromSegments.length - common;
+    const downSegments = toSegments.slice(common);
+    if (upSegments === 0 && downSegments.length === 0)
+        return '.';
+    const ups = '../'.repeat(upSegments);
+    const downs = downSegments.join('/');
+    if (upSegments === 0)
+        return `./${downs}`;
+    return downs.length > 0 ? `${ups}${downs}` : ups.replace(/\/$/, '');
+};
+/**
+ * Resolves a relative or absolute `source` against `importer` (or `selfDtsPath`
+ * when no importer is given) and returns the absolute filesystem candidate
+ * suitable for matching against sibling entries.
+ *
+ * Mirrors TypeScript's lookup rules at the level we need: when the candidate
+ * exists as `<candidate>/index.d.ts` we treat that as the resolved file,
+ * otherwise the candidate path itself.
+ *
+ * @param source - The import specifier as it appears in source.
+ * @param importer - Absolute path of the importing module, when known.
+ * @param selfDtsPath - Absolute path to the entry currently being rewritten (fallback importer).
+ * @returns Absolute candidate path for sibling matching.
+ */
+const resolveCandidate = (source, importer, selfDtsPath) => {
+    if (isAbsolute(source))
+        return normalizeToForwardSlashes(source);
+    if (source.startsWith('.')) {
+        const fromDir = dirnameOf(importer ?? selfDtsPath);
+        return normalizeToForwardSlashes(resolve(fromDir, source));
+    }
+    return source;
+};
+/**
+ * Returns a rollup plugin that externalizes any import resolving inside a
+ * sibling entry's directory tree, rewriting the emitted specifier to a POSIX
+ * relative path stripped of `/index` and `.d.ts` suffixes.
+ *
+ * The plugin's `resolveId` hook returns `null` for everything that does not
+ * resolve into a sibling — that lets the rest of the rollup-plugin-dts chain
+ * inline third-party type imports as before.
+ *
+ * Self-ownership is enforced by adding the current entry into the ownership
+ * pool: when the deepest-matching entry directory is the entry being rewritten
+ * (and not a sibling), the resolver returns `null` so rollup keeps the path
+ * internal. This matters for the package root entry whose directory prefix-
+ * matches every other entry's path — without including self, root would
+ * spuriously claim its own subtree's files.
+ *
+ * @param input - Self + sibling entry descriptors.
+ * @returns Rollup plugin.
+ *
+ * @example Plugin instance for the bundle entry pass
+ * ```typescript
+ * const plugin = createSiblingExternalizePlugin({
+ *   selfSrcPath: 'bundle',
+ *   selfDtsPath: '/abs/dist/libs/foo/bundle/index.d.ts',
+ *   siblings: [{ srcPath: 'models', indexDtsPath: '/abs/dist/libs/foo/models/index.d.ts' }],
+ * })
+ * ```
+ */
+const createSiblingExternalizePlugin = (input) => {
+    const { selfSrcPath, selfDtsPath, siblings } = input;
+    const selfEntry = { srcPath: selfSrcPath, indexDtsPath: selfDtsPath };
+    const ownershipPool = [selfEntry, ...siblings];
+    const selfDtsResolved = normalizeToForwardSlashes(selfDtsPath);
+    return {
+        name: 'externalize-sibling-subpaths',
+        resolveId(source, importer) {
+            if (siblings.length === 0)
+                return null;
+            const candidate = resolveCandidate(source, importer, selfDtsPath);
+            const indexCandidate = candidate.endsWith('.d.ts') ? candidate : `${stripTrailingIndexDts(candidate)}/index.d.ts`;
+            const owner = findOwningSibling(candidate, ownershipPool) ?? findOwningSibling(indexCandidate, ownershipPool);
+            if (!owner)
+                return null;
+            if (normalizeToForwardSlashes(owner.indexDtsPath) === selfDtsResolved)
+                return null;
+            return { id: computeSiblingSpecifier(selfDtsPath, owner), external: true };
+        },
+    };
+};
+/**
+ * Convenience: filters an entry list to siblings of the supplied `srcPath`.
+ *
+ * @param srcPath - The entry's `srcPath` to exclude.
+ * @param entries - All discovered entries.
+ * @returns Entries whose `srcPath` differs from the supplied one.
+ *
+ * @example Building the sibling list for `bundle/`
+ * ```typescript
+ * const siblings = filterSiblings('bundle', allEntries)
+ * ```
+ */
+const filterSiblings = (srcPath, entries) => entries.filter((entry) => entry.srcPath !== srcPath);
+/**
+ * Joins an output base directory with an entry's `srcPath` to produce the
+ * absolute path of the entry's bundled `index.d.ts`.
+ *
+ * @param outputPath - Absolute output directory.
+ * @param srcPath - Entry's `srcPath`. `''` for root.
+ * @returns Absolute path to `<outputPath>/<srcPath>/index.d.ts`.
+ *
+ * @example Computing the d.ts path for a sub-entry
+ * ```typescript
+ * dtsPathFor('/abs/dist/libs/foo', 'models') // => '/abs/dist/libs/foo/models/index.d.ts'
+ * ```
+ */
+const dtsPathFor = (outputPath, srcPath) => srcPath ? join(outputPath, srcPath, 'index.d.ts') : join(outputPath, 'index.d.ts');
+
+const log$3 = logger.channel('builder:bundle:declarations:dts-per-entry');
+const buildSiblingDescriptors = (entries, context, currentSrcPath) => {
+    const descriptors = [];
+    for (const entry of entries) {
+        if (entry.srcPath === currentSrcPath)
+            continue;
+        const indexDtsPath = dtsPathFor(context.outputPath, entry.srcPath);
+        if (!exists(indexDtsPath))
+            continue;
+        descriptors.push({ srcPath: entry.srcPath, indexDtsPath });
+    }
+    return descriptors;
+};
+const buildJobs$1 = (entries, context) => {
+    const jobs = [];
+    const workspacePrefixDeps = collectWorkspacePrefixDeps(context);
+    const workspaceExactSpecifiers = collectWorkspaceExactSpecifiers(context);
+    const workspaceRoutes = buildWorkspaceRoutes(context.workspaceBundledDeps);
+    const depsRoot = depsRootOf(context);
+    for (const entry of entries) {
+        const inputPath = dtsPathFor(context.outputPath, entry.srcPath);
+        if (!exists(inputPath))
+            continue;
+        const siblingEntries = buildSiblingDescriptors(entries, context, entry.srcPath);
+        jobs.push({
+            kind: 'dts',
+            dep: entry.exportPath,
+            inputPath,
+            format: 'esm',
+            outputPath: inputPath,
+            otherDeps: [...context.bundledDeps, ...workspacePrefixDeps],
+            otherWorkspaceSpecifiers: workspaceExactSpecifiers,
+            siblingEntries,
+            selfDtsPath: inputPath,
+            selfSrcPath: entry.srcPath,
+            npmDeps: context.bundledDeps,
+            workspaceRoutes,
+            depsRoot,
+        });
+    }
+    return jobs;
+};
+/**
+ * Runs the per-entry d.ts inlining pass: re-runs `rollup-plugin-dts` over every
+ * tsc-emitted entry `.d.ts` so (a) local per-source sibling re-exports
+ * (`export … from './create-logger'`) are flattened into the entry's
+ * `index.d.ts`, and (b) bundled-dep type imports are routed through
+ * `_dependencies/<dep>/index.d.ts` rather than left as bare specifiers. This
+ * self-containment is what lets `pruneOrphanDeclarations` delete the orphaned
+ * per-source `.d.ts` afterwards without orphaning a still-referenced sibling.
+ *
+ * Runs whenever the build bundles any dep — npm (`bundledDeps`) **or** workspace
+ * (`workspaceBundledDeps`); a package whose deps are all `@hyperfrontend/*` still
+ * needs the flatten. Entries whose tsc output is missing are skipped silently —
+ * the bundle phase may have skipped them deliberately (e.g., empty bundles).
+ *
+ * @param context - Resolved build context.
+ * @param monitor - Optional memory monitor invoked between jobs.
+ * @throws {Error} When the worker artifact cannot be located, or when any per-entry job fails.
+ *
+ * @example Inlining bundled-dep types into every entry's .d.ts after tsc emission
+ * ```typescript
+ * await runDtsPerEntry(context)
+ * ```
+ */
+const runDtsPerEntry = async (context, monitor) => {
+    if (context.bundledDeps.length === 0 && context.workspaceBundledDeps.length === 0)
+        return;
+    const invocation = resolveDefaultWorkerPath(context.workspaceRoot);
+    if (!invocation) {
+        throw createError('bundleAllDeps is enabled but the pre-pass worker artifact was not found for the per-entry d.ts pass.');
+    }
+    const jobs = buildJobs$1(context.entryPointDiscovery.entryPoints, context);
+    if (jobs.length === 0) {
+        log$3.debug('per-entry d.ts pass: no entries with tsc-emitted .d.ts files');
+        return;
+    }
+    log$3.info(`per-entry d.ts pass: ${jobs.length} entries`);
+    monitor?.check('bundle:declarations:dts-perentry:start');
+    await runPrePass(jobs, { workerPath: invocation.path, execArgv: invocation.execArgv, monitor });
+    monitor?.check('bundle:declarations:dts-perentry:end');
+};
+
+const ROOTS = (projectRoot, workspaceRoot) => [projectRoot, workspaceRoot];
+const findPackageJsonByWalkingUp = (entryPath, dep) => {
+    const segments = entryPath.split('/');
+    for (let i = segments.length - 1; i > 0; i--) {
+        const prefix = segments.slice(0, i).join('/');
+        const candidate = `${prefix}/package.json`;
+        if (!exists$1(candidate))
+            continue;
+        try {
+            const meta = readJsonFileIfExists(candidate);
+            if (meta?.name === dep)
+                return candidate;
+        }
+        catch {
+            // fall through
+        }
+    }
+    return undefined;
+};
+const findPackageJsonViaRequire = (dep, fromRoots) => {
+    for (const root of fromRoots) {
+        try {
+            const anchor = join$3(root, 'package.json');
+            if (!exists$1(anchor))
+                continue;
+            const req = createRequire(anchor);
+            const direct = `${dep}/package.json`;
+            try {
+                const path = req.resolve(direct);
+                if (exists$1(path))
+                    return path;
+            }
+            catch {
+                // package may restrict ./package.json via exports — fall through to entry-anchored walk
+            }
+            try {
+                const entryPath = req.resolve(dep);
+                const found = findPackageJsonByWalkingUp(entryPath, dep);
+                if (found)
+                    return found;
+            }
+            catch {
+                // entry resolution may also fail (e.g., type-only package); try the next root
+            }
+        }
+        catch {
+            // try next root
+        }
+    }
+    return undefined;
+};
+const ensureDtsEntry = (pkg) => pkg.types ?? pkg.typings;
+const absolutize = (relativeTo, rel) => {
+    if (isAbsolute(rel))
+        return normalizeToForwardSlashes$1(rel);
+    return normalizeToForwardSlashes$1(resolve(relativeTo, rel));
+};
+/**
+ * Resolves the absolute path to a bundled dep's entry file (JS or `.d.ts`) for a
+ * pre-pass invocation.
+ *
+ * For JS jobs the resolution prefers the dep's `module` field (ESM) over `main`
+ * (CJS). For dts jobs it prefers `types` over `typings`. Lookup walks the project
+ * root first, then the workspace root, using `createRequire` so node's standard
+ * resolution semantics apply (including support for hoisted `node_modules`).
+ *
+ * @param options - Dep name, root paths, and kind.
+ * @returns Absolute path to the dep's entry file.
+ * @throws {Error} When the dep's `package.json` cannot be located or it lacks the
+ * required entry field.
+ *
+ * @example Resolving the runtime entry for `rollup`
+ * ```typescript
+ * const entry = resolveDepEntry({ dep: 'rollup', projectRoot, workspaceRoot, kind: 'js' })
+ * ```
+ */
+const resolveDepEntry = (options) => {
+    const { dep, projectRoot, workspaceRoot} = options;
+    const pkgPath = findPackageJsonViaRequire(dep, ROOTS(projectRoot, workspaceRoot));
+    if (!pkgPath)
+        throw createError(`pre-pass: cannot locate package.json for dep "${dep}"`);
+    const pkg = readJsonFileIfExists(pkgPath);
+    if (!pkg)
+        throw createError(`pre-pass: package.json for dep "${dep}" could not be read at ${pkgPath}`);
+    const relative = ensureDtsEntry(pkg);
+    if (!relative)
+        throw createError(`pre-pass: dep "${dep}" has no ${'types/typings'} entry`);
+    return absolutize(dirname(pkgPath), relative);
+};
+
+const log$2 = logger.channel('builder:bundle:declarations:dts-pre-pass');
+const workspaceDtsOutputFile = (entry) => entry.subPath ? `${entry.specifier}/index.d.ts` : `${entry.packageName}/index.d.ts`;
+const filterRouteEntries = (entry, all) => all.filter((other) => (entry.policy === 'sub-path' ? other.specifier !== entry.specifier : other.packageName !== entry.packageName));
+const buildJobs = (deps, context) => {
+    const depsRoot = depsRootOf(context);
+    const jobs = [];
+    const workspacePrefixDeps = collectWorkspacePrefixDeps(context);
+    const workspaceExactSpecifiers = collectWorkspaceExactSpecifiers(context);
+    const workspaceRoutes = buildWorkspaceRoutes(context.workspaceBundledDeps);
+    for (const dep of deps) {
+        let inputPath;
+        try {
+            inputPath = resolveDepEntry({ dep, projectRoot: context.projectRoot, workspaceRoot: context.workspaceRoot, kind: 'dts' });
+        }
+        catch (error) {
+            log$2.warn(`skipping d.ts pre-pass for ${dep}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        const otherNpmDeps = deps.filter((d) => d !== dep);
+        jobs.push({
+            kind: 'dts',
+            dep,
+            inputPath,
+            format: 'esm',
+            outputPath: join$2(depsRoot, dep, 'index.d.ts'),
+            otherDeps: [...otherNpmDeps, ...workspacePrefixDeps],
+            otherWorkspaceSpecifiers: workspaceExactSpecifiers,
+            npmDeps: otherNpmDeps,
+            workspaceRoutes,
+            depsRoot,
+        });
+    }
+    return jobs;
+};
+const buildWorkspaceJobs = (context, npmDeps) => {
+    if (context.workspaceBundledDeps.length === 0)
+        return [];
+    const depsRoot = depsRootOf(context);
+    const wholeSurface = collectWorkspacePrefixDeps(context);
+    const subPathSpecifiers = collectWorkspaceExactSpecifiers(context);
+    const jobs = [];
+    for (const entry of context.workspaceBundledDeps) {
+        const otherWorkspacePackages = wholeSurface.filter((name) => name !== entry.packageName || entry.policy === 'sub-path');
+        const otherSubPathSpecifiers = subPathSpecifiers.filter((spec) => spec !== entry.specifier);
+        const workspaceRoutes = buildWorkspaceRoutes(filterRouteEntries(entry, context.workspaceBundledDeps));
+        jobs.push({
+            kind: 'workspace-dts',
+            dep: entry.specifier,
+            inputPath: entry.inputPath,
+            format: 'esm',
+            outputPath: join$2(depsRoot, workspaceDtsOutputFile(entry)),
+            otherDeps: [...npmDeps, ...otherWorkspacePackages],
+            otherWorkspaceSpecifiers: otherSubPathSpecifiers,
+            tsConfigPath: entry.tsConfigPath,
+            workspaceRoot: context.workspaceRoot,
+            npmDeps,
+            workspaceRoutes,
+            depsRoot,
+        });
+    }
+    return jobs;
+};
+/**
+ * Runs the d.ts pre-pass: for each bundled dep, produces `_dependencies/<dep>/index.d.ts`
+ * by running `rollup-plugin-dts` over the dep's types entry. Cross-dep type imports are
+ * marked external so the per-entry d.ts pass can route them through `_dependencies/`.
+ *
+ * @param context - Resolved build context.
+ * @param monitor - Optional memory monitor invoked between jobs.
+ * @throws {Error} When the worker artifact cannot be located, or when any d.ts job fails.
+ *
+ * @example Producing _dependencies/<dep>/index.d.ts for a self-contained build
+ * ```typescript
+ * await runDtsPrePass(context)
+ * ```
+ */
+const runDtsPrePass = async (context, monitor) => {
+    if (context.bundledDeps.length === 0 && context.workspaceBundledDeps.length === 0)
+        return;
+    const invocation = resolveDefaultWorkerPath(context.workspaceRoot);
+    if (!invocation) {
+        throw createError('bundleAllDeps is enabled but the pre-pass worker artifact was not found for the d.ts pre-pass.');
+    }
+    const npmJobs = buildJobs(context.bundledDeps, context);
+    const workspaceJobs = buildWorkspaceJobs(context, context.bundledDeps);
+    const jobs = [...npmJobs, ...workspaceJobs];
+    if (jobs.length === 0) {
+        log$2.debug('d.ts pre-pass: no eligible deps (all skipped due to missing types)');
+        return;
+    }
+    log$2.info(`d.ts pre-pass: ${npmJobs.length} npm + ${workspaceJobs.length} workspace = ${jobs.length} job(s)`);
+    monitor?.check('bundle:declarations:dts-prepass:start');
+    await runPrePass(jobs, { workerPath: invocation.path, execArgv: invocation.execArgv, monitor });
+    monitor?.check('bundle:declarations:dts-prepass:end');
+};
+
+const log$1 = logger.channel('builder:bundle:declarations');
+const HEARTBEAT_INTERVAL_MS = 5000;
+const BYTES_PER_MB = 1024 * 1024;
+const formatMB = (bytes) => (bytes / BYTES_PER_MB).toFixed(1);
+const startHeartbeat = (label, startedAt) => setInterval(() => {
+    const usage = process.memoryUsage();
+    const elapsedSec = ((dateNow() - startedAt) / 1000).toFixed(1);
+    log$1.info(`${label} still running: elapsed=${elapsedSec}s parent heap=${formatMB(usage.heapUsed)}MB rss=${formatMB(usage.rss)}MB`);
+}, HEARTBEAT_INTERVAL_MS);
+const runTsc = (tscPath, args, cwd) => createPromise((resolve, reject) => {
+    const startedAt = dateNow();
+    const child = spawn(tscPath, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    log$1.info(`tsc spawned: pid=${child.pid ?? 'unknown'}`);
+    log$1.debug(`tsc args: ${args.join(' ')}`);
+    const heartbeat = startHeartbeat('tsc', startedAt);
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+        const text = chunk.toString();
+        stdout += text;
+        log$1.debug(text.trimEnd());
+    });
+    child.stderr.on('data', (chunk) => {
+        const text = chunk.toString();
+        stderr += text;
+        log$1.warn(text.trimEnd());
+    });
+    child.on('error', (error) => {
+        clearInterval(heartbeat);
+        log$1.error(`tsc spawn error: ${error.message}`);
+        reject(error);
+    });
+    child.on('close', (code) => {
+        clearInterval(heartbeat);
+        const durationMs = dateNow() - startedAt;
+        if (code !== 0) {
+            log$1.error(`tsc failed with exit code ${code} after ${durationMs}ms`);
+            reject(createError(`tsc failed with exit code ${code}`));
+            return;
+        }
+        log$1.info(`tsc exited 0 in ${durationMs}ms`);
+        resolve({ success: true, stdout, stderr });
+    });
+});
+/**
+ * Generates `.d.ts` and `.d.ts.map` files for every entry point in the project
+ * by spawning the workspace-local TypeScript compiler.
+ *
+ * After tsc finishes, calls `flattenDeclarationPaths` to relocate the nested
+ * `dist/<lib>/libs/<lib>/src/...` structure that tsc emits with `baseUrl=workspaceRoot`
+ * back into the flat per-library shape consumers expect.
+ *
+ * @param context - Resolved build context. Provides project root, output path, tsconfig path,
+ * workspace root, and entry point discovery for the flatten step.
+ * @returns Promise resolving with tsc's exit status, captured stdout, and captured stderr.
+ * @throws {Error} When tsc exits with a non-zero status or fails to spawn.
+ *
+ * @example Generating declarations as part of a custom build
+ * ```typescript
+ * const result = await generateDeclarations(context)
+ * console.log(result.stdout)
+ * ```
+ */
+const generateDeclarations = async (context) => {
+    log$1.info('generating typescript declarations');
+    const usage = process.memoryUsage();
+    log$1.info(`pre-tsc memory: parent heap=${formatMB(usage.heapUsed)}MB rss=${formatMB(usage.rss)}MB`);
+    const tscPath = join$3(context.workspaceRoot, 'node_modules', '.bin', 'tsc');
+    const args = [
+        '--project',
+        context.tsConfigPath,
+        '--noEmit',
+        'false',
+        '--emitDeclarationOnly',
+        '--declaration',
+        '--declarationMap',
+        '--outDir',
+        context.outputPath,
+    ];
+    const result = await runTsc(tscPath, args, context.projectRoot);
+    log$1.info('flattening declaration paths');
+    const flattenStart = dateNow();
+    flattenDeclarationPaths(context);
+    log$1.info(`flatten complete in ${dateNow() - flattenStart}ms`);
+    return result;
+};
+
+const log = logger.channel('builder:bundle:declarations:prune-orphans');
+const ORPHAN_DTS_RE = /\.d\.ts$|\.d\.ts\.map$/;
+const INDEX_DTS_NAME = 'index.d.ts';
+/**
+ * Resolves a relative specifier found in a `.d.ts` to the absolute `.d.ts` file
+ * it points at, or `null` when it resolves to nothing on disk or into
+ * `_dependencies/`.
+ *
+ * Declaration specifiers are extensionless (`./create-logger`, `./shared/consts`)
+ * or directory imports (`./shared` → `shared/index.d.ts`); the canonical
+ * `_dependencies` routing uses an explicit runtime extension (`.../index.js`),
+ * which is rewritten to its declaration sibling. Targets under `depsRoot` are
+ * never edges for this pass — bundled-dep declarations are managed by the
+ * dependency Type Prune, and this pass must never touch them.
+ *
+ * @param dir - Absolute directory of the referencing `.d.ts`.
+ * @param spec - Relative specifier text (already known to start with `.`).
+ * @param depsRoot - Absolute path to the `_dependencies/` directory.
+ * @returns Absolute `.d.ts` path of the referenced sibling, or `null`.
+ */
+const toDtsTarget = (dir, spec, depsRoot) => {
+    const abs = join$2(dir, spec);
+    // why: a `.js` specifier is the bundled-dep routing shape; map it onto its declaration sibling.
+    const candidates = spec.endsWith('.js') ? [`${abs.slice(0, -3)}.d.ts`] : [`${abs}.d.ts`, join$2(abs, INDEX_DTS_NAME)];
+    for (const candidate of candidates) {
+        if (isUnderDir(candidate, depsRoot))
+            return null;
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+};
+/**
+ * Computes the set of `.d.ts` files reachable from the entry-point `index.d.ts`
+ * roots by transitively following their relative specifiers.
+ *
+ * Breadth-first: each visited file's text is read, scanned once, then released
+ * before the next, so only one declaration source is resident at a time and the
+ * memory profile stays flat. Edges into `_dependencies/` and to non-existent
+ * targets are dropped. The specifier scan over-approximates (a spurious match
+ * over-keeps harmless bytes) so it never under-keeps a referenced sibling.
+ *
+ * If any reached `.d.ts` contains a dynamic (non-literal) `import(`/`require(`,
+ * the graph cannot be fully resolved, so the function returns `null` — the
+ * safe sentinel that makes the caller keep every declaration.
+ *
+ * @param roots - Absolute paths to the entry-point `index.d.ts` roots.
+ * @param depsRoot - Absolute path to the `_dependencies/` directory.
+ * @returns The set of reachable absolute `.d.ts` paths, or `null` on a dynamic
+ * specifier bail.
+ */
+const computeReachableDeclarations = (roots, depsRoot) => {
+    const reachable = createSet([]);
+    const queue = [];
+    for (const root of roots) {
+        if (exists(root) && !reachable.has(root)) {
+            reachable.add(root);
+            queue.push(root);
+        }
+    }
+    let head = 0;
+    while (head < queue.length) {
+        const file = queue[head];
+        head += 1;
+        // why: every queued path was `exists`-checked before enqueue (roots and `toDtsTarget` targets), so a direct read is safe.
+        const source = readFileContent(file);
+        if (hasDynamicSpecifier(source)) {
+            log.warn(`dynamic import/require in ${file}; keeping all orphan declarations for safety`);
+            return null;
+        }
+        const dir = getDirname(file);
+        for (const spec of collectChunkSpecifiers(source)) {
+            const target = toDtsTarget(dir, spec, depsRoot);
+            if (target !== null && !reachable.has(target)) {
+                reachable.add(target);
+                queue.push(target);
+            }
+        }
+    }
+    return reachable;
+};
+/**
+ * Collects every `.d.ts` / `.d.ts.map` file under `root`, recursing the whole
+ * package tree but skipping the `_dependencies/` subtree (managed by the
+ * dependency Type Prune, never touched here).
+ *
+ * @param root - Absolute path to the package output root.
+ * @param depsRoot - Absolute path to the `_dependencies/` directory.
+ * @returns Absolute paths of all declaration files outside `_dependencies/`.
+ */
+const collectDeclarationFiles = (root, depsRoot) => {
+    const files = [];
+    if (!exists(root))
+        return files;
+    const visit = (dir) => {
+        for (const entry of readDirectory(dir)) {
+            if (entry.isDirectory) {
+                if (isUnderDir(entry.path, depsRoot))
+                    continue;
+                visit(entry.path);
+            }
+            else if (entry.isFile && ORPHAN_DTS_RE.test(entry.name)) {
+                files.push(entry.path);
+            }
+        }
+    };
+    visit(root);
+    return files;
+};
+/**
+ * Removes redundant per-source `.d.ts` / `.d.ts.map` files left behind once the
+ * per-entry flatten has inlined each entry's declarations into a self-contained
+ * `index.d.ts`.
+ *
+ * Walks the whole package tree (excluding `_dependencies/`) and deletes every
+ * declaration file **not reachable** from an entry-point `index.d.ts` via its
+ * transitive relative specifiers. Reachability — rather than a per-directory
+ * sweep — guarantees the invariant that after this runs no surviving `.d.ts`
+ * references a removed one: when the flatten made `index.d.ts` self-contained
+ * the reachable set collapses to the roots and every per-source sibling is
+ * pruned; when the flatten was skipped the siblings the public entry still
+ * re-exports (and anything they transitively re-export) stay live so the shipped
+ * types resolve. This removes the redundancy at the source so `dist` == the
+ * shipped tarball, demoting `package.json#files` to a backstop.
+ *
+ * Safety rails:
+ * - Never touches anything inside `_dependencies/`.
+ * - A `.d.ts.map` is kept iff its sibling `.d.ts` is reachable.
+ * - A dynamic (non-literal) `import(`/`require(` in any reached declaration
+ *   aborts the prune and keeps every declaration file.
+ *
+ * @param context - Resolved build context.
+ * @returns The total number of `.d.ts` / `.d.ts.map` files removed.
+ *
+ * @example Pruning orphans after generateDeclarations
+ * ```typescript
+ * const removed = pruneOrphanDeclarations(context)
+ * ```
+ */
+const pruneOrphanDeclarations = (context) => {
+    const depsRoot = depsRootOf(context);
+    const roots = [];
+    for (const entry of context.entryPointDiscovery.entryPoints) {
+        const dir = entryDirOf(entry, context);
+        if (isUnderDir(dir, depsRoot))
+            continue;
+        roots.push(join$2(dir, INDEX_DTS_NAME));
+    }
+    const reachable = computeReachableDeclarations(roots, depsRoot);
+    if (reachable === null)
+        return 0;
+    let total = 0;
+    for (const file of collectDeclarationFiles(context.outputPath, depsRoot)) {
+        // why: a `.d.ts.map` shares the liveness of its `.d.ts` sibling, keyed by stripping the trailing `.map`.
+        const dtsKey = file.endsWith('.d.ts.map') ? file.slice(0, -4) : file;
+        if (reachable.has(dtsKey))
+            continue;
+        unlinkSync(file);
+        total += 1;
+    }
+    if (total > 0)
+        log.info(`pruned ${total} orphan declaration file(s)`);
+    return total;
+};
+
+export { computeSiblingSpecifier, createSiblingExternalizePlugin, dtsPathFor, filterSiblings, findOwningSibling, flattenDeclarationPaths, generateDeclarations, pruneOrphanDeclarations, runDtsPerEntry, runDtsPrePass };