@hyperfrontend/builder 0.1.0

package/bundle/dependencies/index.d.ts

@@ -0,0 +1,388 @@
+import { Plugin } from '../../_dependencies/rollup/index.js';
+import { WorkspaceBundledDep, IsWorkspacePackagePredicate, WorkspaceDepHoistPolicy } from '../../models';
+import { MemoryMonitor } from '../../memory';
+export { PrePassWorkerJob, PrePassWorkerReport, runPrePassWorkerJob } from './worker';
+
+/**
+ * Format produced by the rollup invocation that uses the plugin.
+ *
+ * D.ts passes use `'dts'` so the plugin maps imports to `.d.ts` siblings under
+ * `_dependencies/<dep>/`; JS passes use `'esm'` / `'cjs'`.
+ */
+type ExternalizeFormat = 'esm' | 'cjs' | 'dts';
+/**
+ * Computes the relative import specifier that a rollup output at `fromDir`
+ * needs to use to reach `toFile`. The result always uses POSIX separators and
+ * starts with `./` or `../` so node treats it as a relative path.
+ *
+ * @param fromDir - Absolute directory containing the output file.
+ * @param toFile - Absolute path to the target file.
+ * @returns Relative import specifier ready for inclusion in emitted code.
+ *
+ * @example Computing the relative path to a bundled dep
+ * ```typescript
+ * relativeImport('/abs/dist/libs/foo/bundle/rollup', '/abs/dist/libs/foo/_dependencies/rollup/index.esm.js')
+ * // => '../../_dependencies/rollup/index.esm.js'
+ * ```
+ */
+declare const relativeImport: (fromDir: string, toFile: string) => string;
+/**
+ * Per-package workspace-dep routing entry.
+ *
+ * - `policy: 'whole-surface'` collapses every import of `<packageName>` (root or
+ *   sub-path) onto the single root chunk at `_dependencies/<packageName>/index.<ext>`.
+ * - `policy: 'sub-path'` matches each pre-passed specifier exactly; non-matched
+ *   sub-path imports of the same package fall through unchanged so the rest of
+ *   the plugin chain can resolve / inline them.
+ */
+interface WorkspaceBundledDepRoute {
+    /** Workspace package name (e.g. `@hyperfrontend/logging`). */
+    packageName: string;
+    /** Routing policy applied to imports of this package. */
+    policy: 'whole-surface' | 'sub-path';
+    /** When `policy === 'sub-path'`: the exact specifiers that were pre-passed. */
+    specifiers?: string[];
+}
+/**
+ * Inputs to {@link createExternalizeBundledDepsPlugin}.
+ */
+interface ExternalizeBundledDepsPluginOptions {
+    /** Bundled-dep package names. Any import of these (or their subpaths) is rerouted to `_dependencies/<dep>/`. */
+    deps: string[];
+    /** Absolute directory the rollup invocation writes its output to. */
+    entryOutDir: string;
+    /** Format being produced by this rollup invocation. */
+    format: ExternalizeFormat;
+    /** Absolute path to the `_dependencies/` root. */
+    depsRoot: string;
+    /** Workspace bundled-dep routes. Imports of these packages reroute to `_dependencies/<packageName>(/<sub>)?/`. */
+    workspaceRoutes?: WorkspaceBundledDepRoute[];
+}
+/**
+ * Groups `WorkspaceBundledDep` entries into per-package `WorkspaceBundledDepRoute`
+ * shapes consumable by {@link createExternalizeBundledDepsPlugin}.
+ *
+ * Whole-surface deps emit a single route with no specifiers; sub-path deps emit
+ * a route enumerating each pre-passed specifier so the plugin can match exactly.
+ *
+ * @param entries - Workspace bundled-dep entries from `BuildContext.workspaceBundledDeps`.
+ * @returns Routes ready to feed into the externalize plugin.
+ *
+ * @example Building plugin routes from the build context
+ * ```typescript
+ * const routes = buildWorkspaceRoutes(context.workspaceBundledDeps)
+ * createExternalizeBundledDepsPlugin({ deps, entryOutDir, format, depsRoot, workspaceRoutes: routes })
+ * ```
+ */
+declare const buildWorkspaceRoutes: (entries: WorkspaceBundledDep[]) => WorkspaceBundledDepRoute[];
+/**
+ * Returns a rollup plugin whose `resolveId` hook maps any import of a bundled
+ * dep (or its subpath) to a relative import that points at the pre-passed
+ * artifact under `_dependencies/<dep>/`. With `workspaceRoutes` populated, the
+ * plugin also routes workspace `@hyperfrontend/*` imports through the matching
+ * workspace chunk (whole-surface or sub-path mode per route).
+ *
+ * The plugin marks node builtins (and `node:*` imports) as external so they
+ * survive untouched, and returns `null` for everything else so the rest of the
+ * plugin chain can resolve normally.
+ *
+ * @param options - Plugin configuration.
+ * @returns Rollup plugin.
+ *
+ * @example Routing imports of `rollup` to the pre-passed copy
+ * ```typescript
+ * const plugin = createExternalizeBundledDepsPlugin({
+ *   deps: ['rollup'],
+ *   entryOutDir: '/abs/dist/libs/foo/bundle/rollup',
+ *   format: 'esm',
+ *   depsRoot: '/abs/dist/libs/foo/_dependencies',
+ * })
+ * ```
+ */
+declare const createExternalizeBundledDepsPlugin: (options: ExternalizeBundledDepsPluginOptions) => Plugin;
+
+/**
+ * Pre-pass kind. Mirrors `PrePassWorkerJobKind` on the worker side.
+ */
+type PrePassJobKind = 'js' | 'dts' | 'workspace-js' | 'workspace-dts';
+/**
+ * Single-rollup-invocation job description fed to a forked worker.
+ */
+interface PrePassJob {
+    /**
+     * Pre-pass kind. `js` and `dts` cover npm bundled deps; `workspace-js` and
+     * `workspace-dts` cover workspace `@hyperfrontend/*` deps whose entries are
+     * TypeScript source.
+     */
+    kind: PrePassJobKind;
+    /** Dep package name (or workspace specifier), e.g. `"rollup"` or `"@hyperfrontend/logging"`. */
+    dep: string;
+    /** Absolute path to the dep's input entry. */
+    inputPath: string;
+    /** Format produced by this rollup invocation. */
+    format: 'esm' | 'cjs';
+    /** Absolute path to the worker's output file. */
+    outputPath: string;
+    /** Other deps in the pre-pass set; prefix-matched and marked external so cross-dep imports stay link-time. */
+    otherDeps: string[];
+    /**
+     * Sub-path-mode workspace specifiers in the pre-pass set; matched as exact
+     * specifier only. Used by `workspace-*` jobs so sibling sub-paths externalize
+     * cleanly (e.g., one `built-in-copy/<x>` chunk does not pull in another).
+     */
+    otherWorkspaceSpecifiers?: string[];
+    /** Absolute path to the project's tsconfig (workspace-* jobs only). */
+    tsConfigPath?: string;
+    /** Absolute workspace root used as `baseUrl` for path-mapping resolution (workspace-* jobs only). */
+    workspaceRoot?: string;
+    /**
+     * Sibling-entry descriptors used by the per-entry `dts` pass to externalize
+     * imports that resolve into another entry's directory. See {@link
+     * SiblingEntryDescriptor}. Empty / omitted for dep pre-pass jobs.
+     */
+    siblingEntries?: SiblingEntryDescriptor[];
+    /** Absolute path to the input file's owning entry directory (used to compute sibling specifiers). */
+    selfDtsPath?: string;
+    /** Owning entry's `srcPath`. Empty string for the package root. */
+    selfSrcPath?: string;
+    /**
+     * NPM bundled-dep names consumed by the worker's externalize plugin to rewrite
+     * cross-dep imports to relative paths under {@link depsRoot}. Disjoint from
+     * {@link workspaceRoutes}.
+     */
+    npmDeps?: string[];
+    /**
+     * Workspace bundled-dep routes consumed by the worker's externalize plugin.
+     * For self-pre-pass jobs (`workspace-js` / `workspace-dts`) this excludes the
+     * specifier or package being built so the chunk inlines its own internals.
+     */
+    workspaceRoutes?: WorkspaceBundledDepRoute[];
+    /** Absolute path to the project's `_dependencies/` root. Required when {@link npmDeps} or {@link workspaceRoutes} is non-empty. */
+    depsRoot?: string;
+}
+/**
+ * Sibling-entry descriptor threaded through to the worker for the per-entry
+ * d.ts pass.
+ */
+interface SiblingEntryDescriptor {
+    /** Sibling entry's `srcPath` (subpath under `<outputPath>`). `''` for the package root. */
+    srcPath: string;
+    /** Absolute path to the sibling's bundled `index.d.ts`. */
+    indexDtsPath: string;
+}
+/**
+ * Result emitted by the worker for a single job.
+ */
+interface PrePassResult {
+    /** The job that produced this result. */
+    job: PrePassJob;
+    /** Output file size in bytes. */
+    outputSize: number;
+    /** Heap reported by the child at exit, in MB. */
+    endHeapMB: number;
+    /** RSS reported by the child at exit, in MB. */
+    endRssMB: number;
+    /** Wall-clock duration the worker reported, in ms. */
+    durationMs: number;
+}
+/**
+ * Caller-supplied options threaded through {@link runPrePass}.
+ */
+interface RunPrePassOptions {
+    /** Absolute path to the worker entry script. Required — see `resolveDefaultWorkerPath`. */
+    workerPath: string;
+    /** Optional memory monitor invoked between every spawned worker. */
+    monitor?: MemoryMonitor;
+    /** Override `process.execPath` for the spawned worker (used by tests). */
+    execPath?: string;
+    /** Extra arguments prepended to the worker invocation (e.g. `['--require', '@swc-node/register']`). */
+    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).
+ *
+ * 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')
+ * ```
+ */
+declare const resolveDefaultWorkerPath: (workspaceRoot: string) => WorkerInvocation | 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' })
+ * ```
+ */
+declare const runPrePass: (jobs: PrePassJob[], options: RunPrePassOptions) => Promise<PrePassResult[]>;
+
+/**
+ * Inputs to {@link resolveBundledDeps}.
+ */
+interface ResolveBundledDepsOptions {
+    /** Predicate identifying workspace-internal packages; when matched, packages are NOT pre-passed. */
+    isWorkspacePackage?: IsWorkspacePackagePredicate;
+    /** Force-include packages even if absent from `package.json#dependencies`. */
+    include?: string[];
+    /** Skip these packages even if otherwise selected. */
+    exclude?: string[];
+}
+/**
+ * Resolves the list of third-party dependencies that should be pre-passed
+ * (bundled once into `_dependencies/<dep>/`) for the build.
+ *
+ * Algorithm:
+ * 1. Read `dependencies` from the project's `package.json`.
+ * 2. Subtract `peerDependencies` — those stay external.
+ * 3. Subtract anything matching `isWorkspacePackage` — workspace deps are inlined per the existing flow.
+ * 4. Apply `include` / `exclude` overrides.
+ *
+ * The returned list is sorted and de-duplicated.
+ *
+ * @param packageJsonPath - Absolute path to the project's `package.json`.
+ * @param options - Caller overrides.
+ * @returns Sorted list of third-party package names to pre-pass.
+ *
+ * @example Resolving bundled deps for a workspace library
+ * ```typescript
+ * const deps = resolveBundledDeps('/abs/libs/foo/package.json', {
+ *   isWorkspacePackage: (n) => n.startsWith('@hyperfrontend/'),
+ * })
+ * ```
+ */
+declare const resolveBundledDeps: (packageJsonPath: string, options?: ResolveBundledDepsOptions) => string[];
+
+/**
+ * Resolved workspace-dep pre-pass entry.
+ */
+interface ResolvedWorkspaceDepEntry {
+    /** Workspace package name, e.g. `@hyperfrontend/logging`. */
+    packageName: string;
+    /** Sub-path under the package; `''` when the entry is the package root. */
+    subPath: string;
+    /** Public import specifier this entry resolves: `<packageName>` or `<packageName>/<subPath>`. */
+    specifier: string;
+    /** Absolute path to the source file (from tsconfig path-mapping). */
+    inputPath: string;
+    /** Absolute path to the dep's own tsconfig used by `@rollup/plugin-typescript` during pre-pass. */
+    tsConfigPath: string;
+    /** Hoist policy applied to this entry's package; carried through so callers need not re-derive it. */
+    policy: WorkspaceDepHoistPolicy;
+}
+/**
+ * Inputs to {@link resolveWorkspaceBundledDeps}.
+ */
+interface ResolveWorkspaceBundledDepsOptions {
+    /** Predicate identifying workspace-internal packages. */
+    isWorkspacePackage: IsWorkspacePackagePredicate;
+    /** Force-include packages even if absent from `package.json#dependencies`. */
+    include?: string[];
+    /** Skip these packages even if otherwise selected. */
+    exclude?: string[];
+    /**
+     * Per-package hoist-policy override, keyed by package name. Packages absent
+     * from the map default to `'sub-path'` (granular, zero-config). Set a package
+     * to `'whole-surface'` to opt into collapsing its sub-paths onto the root
+     * chunk. No built-in entries; callers supply their own opinions.
+     */
+    policy?: Record<string, WorkspaceDepHoistPolicy>;
+}
+/**
+ * Loads tsconfig path-mappings from a workspace, preferring `tsconfig.base.json`
+ * at the workspace root and falling back to a `tsconfig.json` extends chain when
+ * the base form is absent.
+ *
+ * @param workspaceRoot - Absolute workspace root.
+ * @returns Map keyed by tsconfig `paths` key (e.g. `@hyperfrontend/logging`),
+ * with values pointing at absolute source files.
+ *
+ * @example Loading the workspace's path-mapping table
+ * ```typescript
+ * const paths = loadWorkspacePathMappings('/abs/repo')
+ * paths.get('@hyperfrontend/logging') // => ['/abs/repo/libs/logging/src/index.ts']
+ * ```
+ */
+declare const loadWorkspacePathMappings: (workspaceRoot: string) => Map<string, string[]>;
+/**
+ * Resolves the list of workspace `@hyperfrontend/*` deps that should be hoisted
+ * into `_dependencies/<name>(/<sub>)?/index.<ext>.js`.
+ *
+ * Algorithm:
+ * 1. Read the project's `package.json#dependencies`, retain entries matching
+ *    `isWorkspacePackage`, and apply caller `include` / `exclude` overrides.
+ *    Peer deps and excluded packages are skipped; `include` cannot resurrect a
+ *    peer dep.
+ * 2. Load workspace path-mappings (tsconfig `paths`).
+ * 3. For each eligible workspace dep, apply the per-dep hoist policy
+ *    (`options.policy`, defaulting to `'sub-path'`):
+ *    - `'sub-path'` (the zero-config default) emits one entry per resolvable
+ *      tsconfig specifier (root + every sub-path with a real source file),
+ *      preserving sub-module granularity and supporting subpath-only packages
+ *      that expose no root export.
+ *    - `'whole-surface'` is an explicit opt-in collapse: it emits a single entry
+ *      for the package root, so it requires the dep to expose a root export.
+ * 4. The returned list is sorted by `specifier` for stable downstream ordering.
+ *
+ * Because the caller requested `bundleAllDeps`, an eligible dep that cannot be
+ * fully resolved is a contract violation, not a soft skip. The function throws
+ * (rather than silently externalising) when an eligible dep has no resolvable
+ * tsconfig mapping, when a mapped source has no owning tsconfig, or when a dep
+ * is explicitly opted into `'whole-surface'` yet exposes no root export — each
+ * with a message naming the dep and the remedy.
+ *
+ * @param packageJsonPath - Absolute path to the project's `package.json`.
+ * @param workspaceRoot - Absolute workspace root used to load `tsconfig.base.json` paths.
+ * @param options - Caller overrides + workspace-package predicate + per-package policy map.
+ * @returns Resolved workspace-dep pre-pass entries sorted by specifier.
+ * @throws {Error} When an eligible workspace dep cannot be bundled (no mapping, no root export under `'whole-surface'`, or no owning tsconfig).
+ *
+ * @example Resolving workspace pre-pass entries for builder
+ * ```typescript
+ * const entries = resolveWorkspaceBundledDeps(
+ *   '/abs/libs/builder/package.json',
+ *   '/abs/repo',
+ *   { isWorkspacePackage: (n) => n.startsWith('@hyperfrontend/') }
+ * )
+ * ```
+ */
+declare const resolveWorkspaceBundledDeps: (packageJsonPath: string, workspaceRoot: string, options: ResolveWorkspaceBundledDepsOptions) => ResolvedWorkspaceDepEntry[];
+
+export { buildWorkspaceRoutes, createExternalizeBundledDepsPlugin, loadWorkspacePathMappings, relativeImport, resolveBundledDeps, resolveDefaultWorkerPath, resolveWorkspaceBundledDeps, runPrePass };
+export type { ExternalizeBundledDepsPluginOptions, ExternalizeFormat, PrePassJob, PrePassJobKind, PrePassResult, ResolveBundledDepsOptions, ResolveWorkspaceBundledDepsOptions, ResolvedWorkspaceDepEntry, RunPrePassOptions, WorkspaceBundledDepRoute };

package/bundle/dependencies/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bundle/dependencies/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,mCAAmC,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC5H,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9F,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AACvE,YAAY,EAAE,yBAAyB,EAAE,kCAAkC,EAAE,MAAM,kCAAkC,CAAA;AACrH,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACrE,OAAO,EAAE,oBAAoB,EAAE,kCAAkC,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC/G,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAA;AACzG,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA"}