@hyperfrontend/builder 0.1.0

package/bundle/rollup/index.d.ts

@@ -0,0 +1,174 @@
+import { MemoryMonitor } from '../../memory';
+import { RollupBuildDescriptor, RollupWorkerReport } from './worker';
+export { RollupBuildDescriptor, RollupWorkerBin, RollupWorkerBundleOutput, RollupWorkerFormat, RollupWorkerReport, runRollupWorkerJob } from './worker';
+import { BinConfig, BuildContext, BinScriptFormat, EntryPoint, CjsConfig, EsmConfig, IifeConfig, UmdConfig } from '../../models';
+
+/**
+ * Caller-supplied options threaded through {@link dispatchRollupWorker}.
+ */
+interface DispatchRollupWorkerOptions {
+    /** Absolute path to the worker entry script. Required — see `resolveDefaultRollupWorkerPath`. */
+    workerPath: string;
+    /** Optional memory monitor invoked before and after the 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[];
+    /** Human-readable label for log lines and monitor checkpoints (e.g. `esm:./browser`). */
+    label?: 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 RollupWorkerInvocation {
+    /** 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/rollup/worker/index.cjs.js`
+ * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/rollup/worker/index.cjs.js`
+ * 3. `<workspaceRoot>/libs/builder/src/bundle/rollup/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 = resolveDefaultRollupWorkerPath('/abs/repo')
+ * if (!invocation) throw new Error('builder rollup worker artifact not found')
+ * ```
+ */
+declare const resolveDefaultRollupWorkerPath: (workspaceRoot: string) => RollupWorkerInvocation | undefined;
+/**
+ * Forks a single rollup worker for the supplied descriptor and waits for it
+ * to exit. The caller-provided descriptor's `reportPath` is overwritten with
+ * a temp-dir path created by this function.
+ *
+ * Each worker writes a JSON report at the temp path; this function reads it
+ * after the child exits and returns the per-job statistics. If the worker
+ * exits non-zero or fails to produce a report, the function throws with a
+ * label-rich message.
+ *
+ * The temp report directory is cleaned up before returning, regardless of
+ * success or failure.
+ *
+ * @param descriptor - Build descriptor to dispatch.
+ * @param options - Worker path + optional memory monitor.
+ * @returns Worker report (output size + memory + duration) for the dispatched job.
+ *
+ * @example Dispatching a single ESM build
+ * ```typescript
+ * const report = await dispatchRollupWorker(descriptor, { workerPath: '/abs/dist/.../worker.cjs.js' })
+ * ```
+ */
+declare const dispatchRollupWorker: (descriptor: RollupBuildDescriptor, options: DispatchRollupWorkerOptions) => Promise<RollupWorkerReport>;
+
+/**
+ * Builds the worker descriptor for the ESM output of a single entry point.
+ *
+ * The returned descriptor is fully serializable (no functions), ready to be
+ * passed to {@link dispatchRollupWorker}.
+ *
+ * @param entry - Entry point to compile.
+ * @param config - ESM-format configuration.
+ * @param context - Resolved build context.
+ * @param reportPath - Absolute path the worker will write its JSON report to.
+ * @returns Descriptor ready to be JSON-serialized for the worker.
+ *
+ * @example Producing the descriptor for the root entry
+ * ```typescript
+ * const descriptor = toEsmBuildDescriptor(entry, esmConfig, context, '/tmp/report.json')
+ * ```
+ */
+declare const toEsmBuildDescriptor: (entry: EntryPoint, config: EsmConfig, context: BuildContext, reportPath: string) => RollupBuildDescriptor;
+/**
+ * Builds the worker descriptor for the CommonJS output of a single entry point.
+ *
+ * @param entry - Entry point to compile.
+ * @param config - CJS-format configuration.
+ * @param context - Resolved build context.
+ * @param reportPath - Absolute path the worker will write its JSON report to.
+ * @returns Descriptor ready to be JSON-serialized for the worker.
+ *
+ * @example Producing the descriptor for the root entry
+ * ```typescript
+ * const descriptor = toCjsBuildDescriptor(entry, cjsConfig, context, '/tmp/report.json')
+ * ```
+ */
+declare const toCjsBuildDescriptor: (entry: EntryPoint, config: CjsConfig, context: BuildContext, reportPath: string) => RollupBuildDescriptor;
+/**
+ * Builds the worker descriptor for an IIFE bundle of a single entry point.
+ *
+ * Validates the externals/globals pairing eagerly, throwing before the
+ * descriptor is returned.
+ *
+ * @param entry - Entry point to bundle.
+ * @param config - IIFE-format configuration.
+ * @param context - Resolved build context.
+ * @param reportPath - Absolute path the worker will write its JSON report to.
+ * @returns Descriptor ready to be JSON-serialized for the worker.
+ * @throws {Error} When `config.external` is non-empty but `config.globals` is missing entries.
+ *
+ * @example Producing the descriptor for an IIFE bundle
+ * ```typescript
+ * const descriptor = toIifeBuildDescriptor(entry, iifeConfig, context, '/tmp/report.json')
+ * ```
+ */
+declare const toIifeBuildDescriptor: (entry: EntryPoint, config: IifeConfig, context: BuildContext, reportPath: string) => RollupBuildDescriptor;
+/**
+ * Builds the worker descriptor for a single bin output (one (bin, format) pair).
+ *
+ * Bins are self-contained executable scripts: workspace deps are inlined and the
+ * worker writes to `<outputPath>/bin/<name>.<ext>` with the shebang banner, the
+ * resolved bootstrap footer, and `chmod 0o755` applied.
+ *
+ * Output naming convention:
+ * - ESM: `<name>.mjs`
+ * - CJS only: `<name>.js`
+ * - CJS alongside ESM: `<name>.cjs.js`
+ *
+ * @param bin - Bin declaration including name, runner, and per-bin bootstrap override.
+ * @param context - Resolved build context.
+ * @param format - Format being built (one of `bin.format`'s entries).
+ * @param formats - Full list of formats requested for this bin (drives the CJS filename).
+ * @param reportPath - Absolute path the worker will write its JSON report to.
+ * @returns Descriptor ready to be JSON-serialized for the worker.
+ *
+ * @example Producing the descriptor for an `hf-build` CJS bin alongside an ESM twin
+ * ```typescript
+ * const descriptor = toBinBuildDescriptor(bin, context, 'cjs', ['cjs', 'esm'], '/tmp/r.json')
+ * ```
+ */
+declare const toBinBuildDescriptor: (bin: BinConfig, context: BuildContext, format: BinScriptFormat, formats: BinScriptFormat[], reportPath: string) => RollupBuildDescriptor;
+/**
+ * Builds the worker descriptor for a UMD bundle of a single entry point.
+ *
+ * Validates the externals/globals pairing eagerly, throwing before the
+ * descriptor is returned.
+ *
+ * @param entry - Entry point to bundle.
+ * @param config - UMD-format configuration.
+ * @param context - Resolved build context.
+ * @param reportPath - Absolute path the worker will write its JSON report to.
+ * @returns Descriptor ready to be JSON-serialized for the worker.
+ * @throws {Error} When `config.external` is non-empty but `config.globals` is missing entries.
+ *
+ * @example Producing the descriptor for a UMD bundle
+ * ```typescript
+ * const descriptor = toUmdBuildDescriptor(entry, umdConfig, context, '/tmp/report.json')
+ * ```
+ */
+declare const toUmdBuildDescriptor: (entry: EntryPoint, config: UmdConfig, context: BuildContext, reportPath: string) => RollupBuildDescriptor;
+
+export { dispatchRollupWorker, resolveDefaultRollupWorkerPath, toBinBuildDescriptor, toCjsBuildDescriptor, toEsmBuildDescriptor, toIifeBuildDescriptor, toUmdBuildDescriptor };
+export type { DispatchRollupWorkerOptions, RollupWorkerInvocation };

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bundle/rollup/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACrF,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAC5I,OAAO,EAAE,oBAAoB,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAA;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA"}