@hyperfrontend/builder 0.1.0

package/memory/index.cjs.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const node_os = require('node:os');
+const index_cjs_js$3 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.cjs.js');
+const index_cjs_js$2 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js');
+const index_cjs_js$1 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
+const index_cjs_js = require('../_dependencies/@hyperfrontend/logging/index.cjs.js');
+const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.cjs.js');
+const { recover } = require('../_shared/memory/recover/index.cjs.js');
+
+const DEFAULT_WARNING_MB = 512;
+const DEFAULT_CRITICAL_MB = 768;
+const DEFAULT_GROWTH_MB = 50;
+const BYTES_PER_MB = 1024 * 1024;
+const toMB = (bytes) => bytes / BYTES_PER_MB;
+const formatMB = (mb) => mb.toFixed(1);
+/**
+ * Creates an opt-in memory monitor backed by `process.memoryUsage()`.
+ *
+ * The monitor records snapshot history, emits threshold warnings when
+ * `check()` is called, and is intended for instrumenting long-running build
+ * phases. All thresholds default to safe values when omitted.
+ *
+ * @param options - Optional threshold overrides. Each field defaults to a value
+ * appropriate for builder workloads (warning 512 MB, critical 768 MB, growth 50 MB).
+ * @returns A frozen `MemoryMonitor` with snapshot, check, logDebug, logSummary,
+ * and getSnapshots methods.
+ *
+ * @example Recording snapshots between phases
+ * ```typescript
+ * const monitor = createMemoryMonitor({ warningMB: 256, criticalMB: 512, growthMB: 32 })
+ * monitor.check('bundle:start')
+ * await runBundlePhase(ctx, config)
+ * monitor.check('bundle:end')
+ * monitor.logSummary()
+ * ```
+ */
+const createMemoryMonitor = (options = {}) => {
+    const warningMB = options.warningMB ?? DEFAULT_WARNING_MB;
+    const criticalMB = options.criticalMB ?? DEFAULT_CRITICAL_MB;
+    const growthMB = options.growthMB ?? DEFAULT_GROWTH_MB;
+    const log = index_cjs_js.logger.channel('memory');
+    const history = [];
+    const capture = (label) => {
+        const usage = process.memoryUsage();
+        const snapshot = index_cjs_js$1.freeze({
+            label,
+            timestampMs: index_cjs_js$3.dateNow(),
+            heapUsedMB: toMB(usage.heapUsed),
+            heapTotalMB: toMB(usage.heapTotal),
+            rssMB: toMB(usage.rss),
+            externalMB: toMB(usage.external),
+        });
+        history.push(snapshot);
+        return snapshot;
+    };
+    const systemSuffix = (current) => `rss=${formatMB(current.rssMB)}MB free=${formatMB(toMB(node_os.freemem()))}MB total=${formatMB(toMB(node_os.totalmem()))}MB`;
+    const evaluateThresholds = (current) => {
+        if (current.heapUsedMB >= criticalMB) {
+            log.error(`${current.label}: critical heap usage ${formatMB(current.heapUsedMB)}MB >= threshold ${criticalMB}MB ${systemSuffix(current)}`);
+        }
+        else if (current.heapUsedMB >= warningMB) {
+            log.warn(`${current.label}: high heap usage ${formatMB(current.heapUsedMB)}MB >= threshold ${warningMB}MB ${systemSuffix(current)}`);
+        }
+        const previous = history[history.length - 2];
+        if (previous && current.heapUsedMB - previous.heapUsedMB >= growthMB) {
+            log.warn(`${current.label}: heap grew ${formatMB(current.heapUsedMB - previous.heapUsedMB)}MB since '${previous.label}' (threshold ${growthMB}MB) ${systemSuffix(current)}`);
+        }
+    };
+    const monitor = index_cjs_js$1.freeze({
+        snapshot: capture,
+        check: (label) => {
+            const snap = capture(label);
+            evaluateThresholds(snap);
+            return snap;
+        },
+        logDebug: (label) => {
+            const snap = capture(label);
+            log.debug(`${label}: heap=${formatMB(snap.heapUsedMB)}MB rss=${formatMB(snap.rssMB)}MB`);
+            return snap;
+        },
+        logSummary: () => {
+            if (history.length === 0) {
+                log.info('no snapshots captured');
+                return;
+            }
+            const peakHeap = history.reduce((peak, snap) => index_cjs_js$2.max(peak, snap.heapUsedMB), 0);
+            const peakRss = history.reduce((peak, snap) => index_cjs_js$2.max(peak, snap.rssMB), 0);
+            const first = history[0];
+            const last = history[history.length - 1];
+            const elapsed = last.timestampMs - first.timestampMs;
+            log.info(`peak heap=${formatMB(peakHeap)}MB peak rss=${formatMB(peakRss)}MB across ${history.length} snapshots over ${elapsed}ms`);
+        },
+        getSnapshots: () => history.slice(),
+    });
+    return monitor;
+};
+
+exports.createMemoryMonitor = createMemoryMonitor;
+exports.recover = recover;

package/memory/index.d.ts

@@ -0,0 +1,81 @@
+import { MemoryMonitorOptions } from '../models';
+
+/**
+ * Single memory measurement captured by the monitor.
+ *
+ * Sizes are normalized to megabytes (1 MB = 1024 * 1024 bytes) so callers can
+ * compare directly against the configured thresholds.
+ */
+interface MemorySnapshot {
+    /** Caller-supplied label identifying the capture site. */
+    label: string;
+    /** Wall-clock timestamp (ms since epoch) when the snapshot was taken. */
+    timestampMs: number;
+    /** `process.memoryUsage().heapUsed` in MB. */
+    heapUsedMB: number;
+    /** `process.memoryUsage().heapTotal` in MB. */
+    heapTotalMB: number;
+    /** `process.memoryUsage().rss` in MB. */
+    rssMB: number;
+    /** `process.memoryUsage().external` in MB. */
+    externalMB: number;
+}
+/**
+ * Monitor instance returned by `createMemoryMonitor`.
+ */
+interface MemoryMonitor {
+    /** Capture a snapshot, append it to the history, and return it. */
+    snapshot: (label: string) => MemorySnapshot;
+    /** Capture a snapshot and emit warnings when configured thresholds are crossed. */
+    check: (label: string) => MemorySnapshot;
+    /** Capture a snapshot and emit a debug-level log line summarizing it. */
+    logDebug: (label: string) => MemorySnapshot;
+    /** Emit an info-level summary covering every snapshot taken so far. */
+    logSummary: () => void;
+    /** Returns a copy of every snapshot captured so far. */
+    getSnapshots: () => MemorySnapshot[];
+}
+/**
+ * Creates an opt-in memory monitor backed by `process.memoryUsage()`.
+ *
+ * The monitor records snapshot history, emits threshold warnings when
+ * `check()` is called, and is intended for instrumenting long-running build
+ * phases. All thresholds default to safe values when omitted.
+ *
+ * @param options - Optional threshold overrides. Each field defaults to a value
+ * appropriate for builder workloads (warning 512 MB, critical 768 MB, growth 50 MB).
+ * @returns A frozen `MemoryMonitor` with snapshot, check, logDebug, logSummary,
+ * and getSnapshots methods.
+ *
+ * @example Recording snapshots between phases
+ * ```typescript
+ * const monitor = createMemoryMonitor({ warningMB: 256, criticalMB: 512, growthMB: 32 })
+ * monitor.check('bundle:start')
+ * await runBundlePhase(ctx, config)
+ * monitor.check('bundle:end')
+ * monitor.logSummary()
+ * ```
+ */
+declare const createMemoryMonitor: (options?: MemoryMonitorOptions) => MemoryMonitor;
+
+/**
+ * Yields control to the event loop and triggers a manual garbage-collection cycle when
+ * `globalThis.gc` is available (Node.js started with `--expose-gc`).
+ *
+ * This is the always-on free utility companion to the opt-in memory monitor. Call it
+ * between memory-heavy phases to drain pending I/O microtasks and reclaim transient
+ * allocations before the next phase begins.
+ *
+ * @returns A promise that resolves after one macrotask tick, post-GC if available.
+ *
+ * @example Yielding between heavy build phases
+ * ```typescript
+ * await runBundlePhase(ctx, config)
+ * await recover()
+ * await runPackagePhase(ctx, config)
+ * ```
+ */
+declare const recover: () => Promise<void>;
+
+export { createMemoryMonitor, recover };
+export type { MemoryMonitor, MemorySnapshot };

package/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/builder/src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA"}

package/memory/index.esm.js

@@ -0,0 +1,98 @@
+import { freemem, totalmem } from 'node:os';
+import { dateNow } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.esm.js';
+import { max } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
+import { freeze } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import { logger } from '../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { createPromise } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
+import { setTimeout } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.esm.js';
+import { recover } from '../_shared/memory/recover/index.esm.js';
+
+const DEFAULT_WARNING_MB = 512;
+const DEFAULT_CRITICAL_MB = 768;
+const DEFAULT_GROWTH_MB = 50;
+const BYTES_PER_MB = 1024 * 1024;
+const toMB = (bytes) => bytes / BYTES_PER_MB;
+const formatMB = (mb) => mb.toFixed(1);
+/**
+ * Creates an opt-in memory monitor backed by `process.memoryUsage()`.
+ *
+ * The monitor records snapshot history, emits threshold warnings when
+ * `check()` is called, and is intended for instrumenting long-running build
+ * phases. All thresholds default to safe values when omitted.
+ *
+ * @param options - Optional threshold overrides. Each field defaults to a value
+ * appropriate for builder workloads (warning 512 MB, critical 768 MB, growth 50 MB).
+ * @returns A frozen `MemoryMonitor` with snapshot, check, logDebug, logSummary,
+ * and getSnapshots methods.
+ *
+ * @example Recording snapshots between phases
+ * ```typescript
+ * const monitor = createMemoryMonitor({ warningMB: 256, criticalMB: 512, growthMB: 32 })
+ * monitor.check('bundle:start')
+ * await runBundlePhase(ctx, config)
+ * monitor.check('bundle:end')
+ * monitor.logSummary()
+ * ```
+ */
+const createMemoryMonitor = (options = {}) => {
+    const warningMB = options.warningMB ?? DEFAULT_WARNING_MB;
+    const criticalMB = options.criticalMB ?? DEFAULT_CRITICAL_MB;
+    const growthMB = options.growthMB ?? DEFAULT_GROWTH_MB;
+    const log = logger.channel('memory');
+    const history = [];
+    const capture = (label) => {
+        const usage = process.memoryUsage();
+        const snapshot = freeze({
+            label,
+            timestampMs: dateNow(),
+            heapUsedMB: toMB(usage.heapUsed),
+            heapTotalMB: toMB(usage.heapTotal),
+            rssMB: toMB(usage.rss),
+            externalMB: toMB(usage.external),
+        });
+        history.push(snapshot);
+        return snapshot;
+    };
+    const systemSuffix = (current) => `rss=${formatMB(current.rssMB)}MB free=${formatMB(toMB(freemem()))}MB total=${formatMB(toMB(totalmem()))}MB`;
+    const evaluateThresholds = (current) => {
+        if (current.heapUsedMB >= criticalMB) {
+            log.error(`${current.label}: critical heap usage ${formatMB(current.heapUsedMB)}MB >= threshold ${criticalMB}MB ${systemSuffix(current)}`);
+        }
+        else if (current.heapUsedMB >= warningMB) {
+            log.warn(`${current.label}: high heap usage ${formatMB(current.heapUsedMB)}MB >= threshold ${warningMB}MB ${systemSuffix(current)}`);
+        }
+        const previous = history[history.length - 2];
+        if (previous && current.heapUsedMB - previous.heapUsedMB >= growthMB) {
+            log.warn(`${current.label}: heap grew ${formatMB(current.heapUsedMB - previous.heapUsedMB)}MB since '${previous.label}' (threshold ${growthMB}MB) ${systemSuffix(current)}`);
+        }
+    };
+    const monitor = freeze({
+        snapshot: capture,
+        check: (label) => {
+            const snap = capture(label);
+            evaluateThresholds(snap);
+            return snap;
+        },
+        logDebug: (label) => {
+            const snap = capture(label);
+            log.debug(`${label}: heap=${formatMB(snap.heapUsedMB)}MB rss=${formatMB(snap.rssMB)}MB`);
+            return snap;
+        },
+        logSummary: () => {
+            if (history.length === 0) {
+                log.info('no snapshots captured');
+                return;
+            }
+            const peakHeap = history.reduce((peak, snap) => max(peak, snap.heapUsedMB), 0);
+            const peakRss = history.reduce((peak, snap) => max(peak, snap.rssMB), 0);
+            const first = history[0];
+            const last = history[history.length - 1];
+            const elapsed = last.timestampMs - first.timestampMs;
+            log.info(`peak heap=${formatMB(peakHeap)}MB peak rss=${formatMB(peakRss)}MB across ${history.length} snapshots over ${elapsed}ms`);
+        },
+        getSnapshots: () => history.slice(),
+    });
+    return monitor;
+};
+
+export { createMemoryMonitor, recover };

package/memory/monitor.d.ts

@@ -0,0 +1,59 @@
+import type { MemoryMonitorOptions } from '../models';
+/**
+ * Single memory measurement captured by the monitor.
+ *
+ * Sizes are normalized to megabytes (1 MB = 1024 * 1024 bytes) so callers can
+ * compare directly against the configured thresholds.
+ */
+export interface MemorySnapshot {
+    /** Caller-supplied label identifying the capture site. */
+    label: string;
+    /** Wall-clock timestamp (ms since epoch) when the snapshot was taken. */
+    timestampMs: number;
+    /** `process.memoryUsage().heapUsed` in MB. */
+    heapUsedMB: number;
+    /** `process.memoryUsage().heapTotal` in MB. */
+    heapTotalMB: number;
+    /** `process.memoryUsage().rss` in MB. */
+    rssMB: number;
+    /** `process.memoryUsage().external` in MB. */
+    externalMB: number;
+}
+/**
+ * Monitor instance returned by `createMemoryMonitor`.
+ */
+export interface MemoryMonitor {
+    /** Capture a snapshot, append it to the history, and return it. */
+    snapshot: (label: string) => MemorySnapshot;
+    /** Capture a snapshot and emit warnings when configured thresholds are crossed. */
+    check: (label: string) => MemorySnapshot;
+    /** Capture a snapshot and emit a debug-level log line summarizing it. */
+    logDebug: (label: string) => MemorySnapshot;
+    /** Emit an info-level summary covering every snapshot taken so far. */
+    logSummary: () => void;
+    /** Returns a copy of every snapshot captured so far. */
+    getSnapshots: () => MemorySnapshot[];
+}
+/**
+ * Creates an opt-in memory monitor backed by `process.memoryUsage()`.
+ *
+ * The monitor records snapshot history, emits threshold warnings when
+ * `check()` is called, and is intended for instrumenting long-running build
+ * phases. All thresholds default to safe values when omitted.
+ *
+ * @param options - Optional threshold overrides. Each field defaults to a value
+ * appropriate for builder workloads (warning 512 MB, critical 768 MB, growth 50 MB).
+ * @returns A frozen `MemoryMonitor` with snapshot, check, logDebug, logSummary,
+ * and getSnapshots methods.
+ *
+ * @example Recording snapshots between phases
+ * ```typescript
+ * const monitor = createMemoryMonitor({ warningMB: 256, criticalMB: 512, growthMB: 32 })
+ * monitor.check('bundle:start')
+ * await runBundlePhase(ctx, config)
+ * monitor.check('bundle:end')
+ * monitor.logSummary()
+ * ```
+ */
+export declare const createMemoryMonitor: (options?: MemoryMonitorOptions) => MemoryMonitor;
+//# sourceMappingURL=monitor.d.ts.map

package/memory/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../../../../../../libs/builder/src/memory/monitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAYrD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAA;IACb,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAA;IACnB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAA;IACnB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,cAAc,CAAA;IAC3C,mFAAmF;IACnF,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,cAAc,CAAA;IACxC,yEAAyE;IACzE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,cAAc,CAAA;IAC3C,uEAAuE;IACvE,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,wDAAwD;IACxD,YAAY,EAAE,MAAM,cAAc,EAAE,CAAA;CACrC;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAS,oBAAyB,KAAG,aAmExE,CAAA"}

package/memory/recover.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Yields control to the event loop and triggers a manual garbage-collection cycle when
+ * `globalThis.gc` is available (Node.js started with `--expose-gc`).
+ *
+ * This is the always-on free utility companion to the opt-in memory monitor. Call it
+ * between memory-heavy phases to drain pending I/O microtasks and reclaim transient
+ * allocations before the next phase begins.
+ *
+ * @returns A promise that resolves after one macrotask tick, post-GC if available.
+ *
+ * @example Yielding between heavy build phases
+ * ```typescript
+ * await runBundlePhase(ctx, config)
+ * await recover()
+ * await runPackagePhase(ctx, config)
+ * ```
+ */
+export declare const recover: () => Promise<void>;
+//# sourceMappingURL=recover.d.ts.map

package/memory/recover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../../../../../../libs/builder/src/memory/recover.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,QAAO,OAAO,CAAC,IAAI,CAOnC,CAAA"}

package/models/build-config.d.ts

@@ -0,0 +1,266 @@
+import type { PackageJson } from './package-json';
+/**
+ * Predicate identifying packages that are local to the workspace.
+ *
+ * Returning `true` opts the package into workspace-aware behavior such as inlining
+ * during bundling or stripping from the published `dependencies` map.
+ */
+export type IsWorkspacePackagePredicate = (name: string) => boolean;
+/**
+ * Predicate gating whether an asset spec materializes for a given package.
+ */
+export type AssetConditionPredicate = (pkg: PackageJson) => boolean;
+/**
+ * Generic asset-copy specification consumed by the package phase.
+ *
+ * Either `files` or `glob` selects the inputs under `from`. When neither is provided,
+ * every file directly under `from` is copied.
+ */
+export interface AssetSpec {
+    /** Absolute source directory. */
+    from: string;
+    /** Output subdirectory relative to the build's outputPath; defaults to `.` (the dist root). */
+    to?: string;
+    /** Explicit relative file names to copy. */
+    files?: string[];
+    /** POSIX-style glob pattern, evaluated relative to `from`. */
+    glob?: string;
+    /** Predicate gating whether the spec is materialized. */
+    condition?: AssetConditionPredicate;
+}
+/**
+ * Inheritance specification: copy the listed top-level fields from another package.json
+ * onto the synthesized output package.json, leaving existing fields intact.
+ */
+export interface InheritFromSpec {
+    /** Absolute path to the source package.json. */
+    from: string;
+    /** Top-level field names to copy if present on the source. */
+    fields: string[];
+}
+/**
+ * Entry-point selection shared by every per-format configuration.
+ */
+export interface FormatEntryConfig {
+    /** Entry pattern(s) — exact path, glob, or list. Omit to include all detected entries. */
+    entry?: string | string[];
+    /** Pattern(s) to exclude from the resolved entry set. */
+    exclude?: string | string[];
+}
+/**
+ * Caller overrides to the auto-derived bundled-dep set.
+ *
+ * The default set is `package.json#dependencies` minus `peerDependencies` minus
+ * any package matching `isWorkspacePackage`. `include` adds packages absent
+ * from `dependencies`; `exclude` skips ones that would otherwise be picked up.
+ * Neither override can resurrect a peer or workspace package.
+ */
+export interface BundleAllDepsOptions {
+    /** Force-include packages even if absent from `package.json#dependencies`. */
+    include?: string[];
+    /** Skip these packages even if otherwise selected. */
+    exclude?: string[];
+}
+/**
+ * ESM output configuration.
+ */
+export interface EsmConfig extends FormatEntryConfig {
+    /** Generate sourcemaps. Defaults to `false`. */
+    sourcemap?: boolean;
+    /** Additional package names to mark external. */
+    external?: string[];
+    /** Inline workspace dependencies (`true`) or keep them external (`false`). Defaults to `true`. */
+    bundleWorkspaceDeps?: boolean;
+    /**
+     * Bundle every third-party dep into `_dependencies/<dep>/` and route entry imports
+     * through that directory at install-relative paths. When `true`, builder produces
+     * a fully self-contained dist with no `dependencies` field on the published package.
+     */
+    bundleAllDeps?: boolean | BundleAllDepsOptions;
+}
+/**
+ * CommonJS output configuration.
+ */
+export interface CjsConfig extends FormatEntryConfig {
+    /** Generate sourcemaps. Defaults to `false`. */
+    sourcemap?: boolean;
+    /** Additional package names to mark external. */
+    external?: string[];
+    /** Inline workspace dependencies (`true`) or keep them external (`false`). Defaults to `true`. */
+    bundleWorkspaceDeps?: boolean;
+    /**
+     * Bundle every third-party dep into `_dependencies/<dep>/` and route entry imports
+     * through that directory at install-relative paths. When `true`, builder produces
+     * a fully self-contained dist with no `dependencies` field on the published package.
+     */
+    bundleAllDeps?: boolean | BundleAllDepsOptions;
+}
+/**
+ * IIFE (browser self-executing) output configuration.
+ */
+export interface IifeConfig extends FormatEntryConfig {
+    /** Global variable name exposed by the bundle. */
+    globalName: string;
+    /** Emit a minified twin alongside the unminified bundle. Defaults to `true`. */
+    minify?: boolean;
+    /** Output subdirectory relative to outputPath. Defaults to `bundle`. */
+    output?: string;
+    /** Generate sourcemaps. Defaults to `false`. */
+    sourcemap?: boolean;
+    /** Package names to keep external; if omitted, every dependency is inlined. */
+    external?: string[];
+    /** Global names for each external dependency. Required when `external` is set. */
+    globals?: Record<string, string>;
+}
+/**
+ * UMD (universal module definition) output configuration.
+ */
+export interface UmdConfig extends FormatEntryConfig {
+    /** Global variable name exposed by the bundle. */
+    globalName: string;
+    /** Emit a minified twin alongside the unminified bundle. Defaults to `true`. */
+    minify?: boolean;
+    /** AMD module identifier. Defaults to the package name. */
+    amdId?: string;
+    /** Output subdirectory relative to outputPath. Defaults to `bundle`. */
+    output?: string;
+    /** Generate sourcemaps. Defaults to `false`. */
+    sourcemap?: boolean;
+    /** Package names to keep external; if omitted, every dependency is inlined. */
+    external?: string[];
+    /** Global names for each external dependency. Required when `external` is set. */
+    globals?: Record<string, string>;
+}
+/**
+ * Output formats permitted for a JS bin.
+ */
+export type BinScriptFormat = 'cjs' | 'esm';
+/**
+ * Per-bin format declaration: a single format or an explicit list.
+ */
+export type BinFormatSpec = BinScriptFormat | BinScriptFormat[];
+/**
+ * Native binary platform identifier in the form `<process.platform>-<process.arch>`.
+ */
+export type SeaPlatform = 'linux-x64' | 'linux-arm64' | 'darwin-x64' | 'darwin-arm64' | 'win32-x64';
+/**
+ * Node SEA (single-executable application) configuration for a bin.
+ */
+export interface SeaConfig {
+    /** Platforms for which a native binary should be produced. */
+    platforms: SeaPlatform[];
+}
+/**
+ * Bin synthesis configuration.
+ *
+ * The source file is fixed at `src/bin/<name>.ts`. The runner export defaults to the
+ * file's `default` export; override with `runner` to target a named export instead.
+ */
+export interface BinConfig {
+    /** Bin name (also the package.json#bin key and the source file basename). */
+    name: string;
+    /** Required output format(s) for the bin. */
+    format: BinFormatSpec;
+    /** Named runner export to bootstrap. Defaults to the file's `default` export. */
+    runner?: string;
+    /** Override the bootstrap footer template. */
+    bootstrap?: string;
+    /** Opt into Node SEA native binary emission. */
+    sea?: SeaConfig;
+}
+/**
+ * Per-package hoist policy for a bundled workspace dependency.
+ *
+ * `'sub-path'` (the zero-config default) gives every public tsconfig specifier
+ * of the dep — root and each sub-path — its own
+ * `_dependencies/<name>(/<sub>)?/index.<ext>` chunk, preserving sub-module
+ * tree-shaking and reuse, and supporting subpath-only packages that expose no
+ * root export. `'whole-surface'` is an explicit opt-in collapse: it routes every
+ * import of the dep onto a single root chunk, and therefore requires the dep to
+ * expose a root export.
+ */
+export type WorkspaceDepHoistPolicy = 'sub-path' | 'whole-surface';
+/**
+ * Memory-monitor configuration thresholds (in MB).
+ */
+export interface MemoryMonitorOptions {
+    /** Heap-used threshold above which a warning is logged. */
+    warningMB?: number;
+    /** Heap-used threshold above which a critical-level message is logged. */
+    criticalMB?: number;
+    /** Step-over-step heap growth threshold above which a growth warning is logged. */
+    growthMB?: number;
+}
+/**
+ * Top-level builder configuration consumed by the `build()` facade.
+ */
+export interface BuildConfig {
+    /** Absolute path to the project being built. */
+    projectRoot: string;
+    /** Absolute path to the workspace root. */
+    workspaceRoot: string;
+    /** Absolute output directory. Defaults to `<workspaceRoot>/dist/<projectRelativePath>`. */
+    outputPath?: string;
+    /** Path to the project's tsconfig used for declarations. Defaults to `<projectRoot>/tsconfig.lib.json`. */
+    tsConfig?: string;
+    /** Workspace-package predicate; when omitted the bundler treats every dep as external. */
+    isWorkspacePackage?: IsWorkspacePackagePredicate;
+    /**
+     * Per-package override of the workspace-dependency hoist policy, 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. Builder ships no built-in entries; consumers
+     * inject their own opinions here, mirroring {@link isWorkspacePackage}.
+     */
+    workspaceDepPolicy?: Record<string, WorkspaceDepHoistPolicy>;
+    /** Drop workspace-internal entries from the output package.json's `dependencies`. */
+    filterWorkspaceDepsFromOutput?: boolean;
+    /** Selectively copy fields from another package.json onto the output package.json. */
+    inheritFieldsFrom?: InheritFromSpec;
+    /** Asset specs to materialize alongside the bundle. */
+    assets?: AssetSpec[];
+    /** Global externals applied to every format. */
+    external?: string[];
+    /** ESM configuration; omit to skip ESM output. */
+    esm?: EsmConfig | EsmConfig[];
+    /** CommonJS configuration; omit to skip CJS output. */
+    cjs?: CjsConfig | CjsConfig[];
+    /** IIFE bundle configuration; omit to skip IIFE output. */
+    iife?: IifeConfig | IifeConfig[];
+    /** UMD bundle configuration; omit to skip UMD output. */
+    umd?: UmdConfig | UmdConfig[];
+    /** Override path for the unpkg field. Defaults to the first UMD bundle path. */
+    unpkg?: string;
+    /** Override path for the jsdelivr field. Defaults to the first UMD bundle path. */
+    jsdelivr?: string;
+    /** Bin declarations to synthesize alongside the library. */
+    bin?: BinConfig[];
+    /**
+     * Override the published `package.json#files` allowlist.
+     *
+     * When omitted, the allowlist is reflected from the materialized output tree
+     * after every emit phase — it names exactly what shipped. Provide an explicit
+     * array to take full control of what `npm publish` ships.
+     */
+    files?: string[];
+    /**
+     * Hoist first-party modules that are inlined into multiple entry bundles into
+     * shared `_shared/<srcPath>/` chunks and rewrite the entries to import them,
+     * removing the duplicated copies. Runs as a safe, additive post-emit pass over
+     * the `esm`/`cjs` outputs only. Defaults to enabled; set `false` to keep every
+     * entry fully self-contained.
+     */
+    dedupeSharedInternals?: boolean;
+    /** Emit a third-party-licenses file. */
+    thirdPartyLicenses?: boolean;
+    /** Enable the memory monitor; pass `true` for defaults or an options object for custom thresholds. */
+    memoryMonitor?: boolean | MemoryMonitorOptions;
+    /**
+     * Raise the build's log level. When `true`, the shared logger emits at `debug`
+     * (surfacing every phase's progress, timing, and memory diagnostics); when
+     * omitted or `false`, the build stays quiet at `error`. Also settable via the
+     * `hf-build --verbose` flag.
+     */
+    verbose?: boolean;
+}
+//# sourceMappingURL=build-config.d.ts.map

package/models/build-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-config.d.ts","sourceRoot":"","sources":["../../../../../../../libs/builder/src/models/build-config.ts"],"names":[],"mappings":"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"}