@hyperfrontend/builder 0.1.0

package/models/index.d.ts

@@ -0,0 +1,581 @@
+/**
+ * Repository field in package.json.
+ */
+interface RepositoryField {
+    /** Repository type (e.g., 'git'). */
+    type: string;
+    /** Repository URL. */
+    url: string;
+    /** Optional sub-directory inside the repository. */
+    directory?: string;
+}
+/**
+ * Bugs field in package.json.
+ */
+interface BugsField {
+    /** Bug tracker URL. */
+    url?: string;
+    /** Bug tracker email. */
+    email?: string;
+}
+/**
+ * Author / contributor entry in package.json.
+ */
+interface AuthorField {
+    /** Author name. */
+    name: string;
+    /** Author email. */
+    email?: string;
+    /** Author URL. */
+    url?: string;
+}
+/**
+ * Funding entry in package.json.
+ */
+interface FundingField {
+    /** Funding type (e.g., 'github', 'patreon'). */
+    type: string;
+    /** Funding URL. */
+    url: string;
+}
+/**
+ * Conditional export specification for the package.json `exports` field.
+ *
+ * Each property maps an export condition (e.g., `import`, `require`, `types`) to a
+ * resolved file path, or to a nested conditional-export object for further refinement.
+ */
+interface ConditionalExport {
+    /** Path used by ESM `import`. */
+    import?: string;
+    /** Path used by CommonJS `require`. */
+    require?: string;
+    /** Default fallback path. */
+    default?: string;
+    /** TypeScript declaration path. */
+    types?: string;
+    /** Node.js-specific export. */
+    node?: string | ConditionalExport;
+    /** Browser-specific export. */
+    browser?: string | ConditionalExport;
+    /** Development build export. */
+    development?: string | ConditionalExport;
+    /** Production build export. */
+    production?: string | ConditionalExport;
+}
+/**
+ * Value form for an `exports` map entry — a resolved string path, a conditional
+ * exports object, or a nested record for sub-conditions.
+ */
+type ExportValue = string | ConditionalExport | Record<string, unknown>;
+/**
+ * Subset of the npm package.json schema that the builder reads from and writes to.
+ *
+ * Only fields the builder pipeline interacts with directly are typed; arbitrary additional
+ * fields are preserved through the index signature and emitted to the output package.json.
+ */
+interface PackageJson {
+    /** Package name. */
+    name?: string;
+    /** Package version. */
+    version?: string;
+    /** Short package description. */
+    description?: string;
+    /** SPDX license identifier or expression. */
+    license?: string;
+    /** Main entry path (CommonJS). */
+    main?: string;
+    /** Module entry path (ESM). */
+    module?: string;
+    /** TypeScript type-declarations entry path. */
+    types?: string;
+    /** Subpath exports map. */
+    exports?: Record<string, ExportValue>;
+    /** Bin name → script path mapping. */
+    bin?: Record<string, string> | string;
+    /** Runtime dependencies. */
+    dependencies?: Record<string, string>;
+    /** Development dependencies. */
+    devDependencies?: Record<string, string>;
+    /** Peer dependencies. */
+    peerDependencies?: Record<string, string>;
+    /** Optional dependencies. */
+    optionalDependencies?: Record<string, string>;
+    /** Repository field. */
+    repository?: RepositoryField | string;
+    /** Bugs field. */
+    bugs?: BugsField | string;
+    /** Homepage URL. */
+    homepage?: string;
+    /** Author field. */
+    author?: AuthorField | string;
+    /** Contributors. */
+    contributors?: (AuthorField | string)[];
+    /** Funding entry or list. */
+    funding?: FundingField | FundingField[] | string;
+    /** Whether the package has side effects. */
+    sideEffects?: boolean;
+    /** Keywords for npm search. */
+    keywords?: string[];
+    /** unpkg CDN entry path. */
+    unpkg?: string;
+    /** jsdelivr CDN entry path. */
+    jsdelivr?: string;
+    /** Engines compatibility map. */
+    engines?: Record<string, string>;
+    /** Files included when packaging. */
+    files?: string[];
+    /** Arbitrary additional fields preserved on read/write. */
+    [key: string]: unknown;
+}
+
+/**
+ * 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.
+ */
+type IsWorkspacePackagePredicate = (name: string) => boolean;
+/**
+ * Predicate gating whether an asset spec materializes for a given package.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+type BinScriptFormat = 'cjs' | 'esm';
+/**
+ * Per-bin format declaration: a single format or an explicit list.
+ */
+type BinFormatSpec = BinScriptFormat | BinScriptFormat[];
+/**
+ * Native binary platform identifier in the form `<process.platform>-<process.arch>`.
+ */
+type SeaPlatform = 'linux-x64' | 'linux-arm64' | 'darwin-x64' | 'darwin-arm64' | 'win32-x64';
+/**
+ * Node SEA (single-executable application) configuration for a bin.
+ */
+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.
+ */
+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.
+ */
+type WorkspaceDepHoistPolicy = 'sub-path' | 'whole-surface';
+/**
+ * Memory-monitor configuration thresholds (in MB).
+ */
+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.
+ */
+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;
+}
+
+/**
+ * Structural pattern of a library's entry-point layout.
+ *
+ * - `root`: single entry at `src/index.ts`
+ * - `platform`: browser / node split under `src/browser/` and `src/node/`
+ * - `feature`: multiple feature modules under `src/<feature>/`
+ * - `hybrid`: a mix of root, platform, and / or feature entries
+ * - `complex`: nested platform-plus-feature structures
+ */
+type EntryPointCategory = 'root' | 'platform' | 'feature' | 'hybrid' | 'complex';
+/**
+ * Platform hint used for browser / node-specific entry points.
+ */
+type EntryPointPlatform = 'browser' | 'node';
+/**
+ * A single resolved entry point within a library.
+ */
+interface EntryPoint {
+    /** Subpath export key relative to the package root (e.g., `.`, `./browser`, `./browser/v1`). */
+    exportPath: string;
+    /** Path inside `src/` to the entry directory (e.g., ``, `browser`, `browser/v1`). */
+    srcPath: string;
+    /** Absolute path to the entry source file (e.g., `<projectRoot>/src/<srcPath>/index.ts`). */
+    inputFile: string;
+    /** True when the entry corresponds to `src/index.ts`. */
+    isRoot: boolean;
+    /** Platform hint when the entry lives under `src/browser/` or `src/node/`. */
+    platform?: EntryPointPlatform;
+}
+/**
+ * Result of scanning a library for its entry points.
+ */
+interface EntryPointDiscovery {
+    /** Detected layout category. */
+    category: EntryPointCategory;
+    /** Every discovered entry point in stable order. */
+    entryPoints: EntryPoint[];
+    /** Whether `src/index.ts` exists. */
+    hasRootEntry: boolean;
+    /** Subset of entries flagged with a platform hint. */
+    platformEntries: EntryPoint[];
+    /** Subset of feature / module entries (non-root, non-platform). */
+    featureEntries: EntryPoint[];
+}
+
+/**
+ * Per-package workspace dependency to bundle into a hoisted chunk under
+ * `_dependencies/<packageName>(/<sub>)?`.
+ *
+ * The default set is `package.json#dependencies` intersected with the workspace
+ * predicate.
+ */
+interface WorkspaceBundledDep {
+    /** Workspace package name (e.g. `@hyperfrontend/logging`). */
+    packageName: string;
+    /** Sub-path under the package; `''` for the package root. */
+    subPath: string;
+    /** Public import specifier the entry resolves: `<packageName>` or `<packageName>/<subPath>`. */
+    specifier: string;
+    /** Absolute path to the source `.ts` file resolved via tsconfig path mappings. */
+    inputPath: string;
+    /**
+     * Absolute path to the dep's own tsconfig (e.g. `tsconfig.lib.json`), so the
+     * dep is compiled with its own options rather than the consumer project's.
+     */
+    tsConfigPath: string;
+    /** Hoist policy for this dep's chunk(s); see {@link WorkspaceDepHoistPolicy}. */
+    policy: WorkspaceDepHoistPolicy;
+}
+/**
+ * Resolved, fully-computed runtime context derived from a `BuildConfig`.
+ *
+ * Unlike `BuildConfig`, every path and option here has been resolved to an absolute
+ * value and every default has been filled in. Builder primitives consume the
+ * `BuildContext`, never the raw config.
+ */
+interface BuildContext {
+    /** Absolute path to the project being built. */
+    projectRoot: string;
+    /** Absolute path to the workspace root. */
+    workspaceRoot: string;
+    /** Project path relative to the workspace root (forward-slash separated). */
+    projectRelativePath: string;
+    /** Resolved absolute output directory. */
+    outputPath: string;
+    /** Resolved absolute path to the project's tsconfig. */
+    tsConfigPath: string;
+    /** Global external dependencies to exclude from every bundle. */
+    external: string[];
+    /** Asset specs to materialize. */
+    assets: AssetSpec[];
+    /** Workspace-package predicate, normalized to always-defined. */
+    isWorkspacePackage: IsWorkspacePackagePredicate;
+    /** Result of the entry-point discovery scan. */
+    entryPointDiscovery: EntryPointDiscovery;
+    /**
+     * Third-party deps bundled into `_dependencies/<dep>/` and stripped from the
+     * output `package.json`. Empty unless at least one format declares
+     * `bundleAllDeps`.
+     */
+    bundledDeps: string[];
+    /**
+     * Workspace deps bundled into `_dependencies/<packageName>(/<sub>)?/`. Empty
+     * unless at least one format declares `bundleAllDeps` and the project declares
+     * workspace deps.
+     */
+    workspaceBundledDeps: WorkspaceBundledDep[];
+    /** Wall-clock timestamp captured at context creation, used for `BuildResult.durationMs`. */
+    startedAt: number;
+}
+
+/**
+ * Build output for a single IIFE bundle.
+ */
+interface IifeOutput {
+    /** Resolved IIFE configuration that produced the bundle. */
+    config: IifeConfig;
+    /** Entry points combined into the bundle. */
+    entries: EntryPoint[];
+}
+/**
+ * Build output for a single UMD bundle.
+ */
+interface UmdOutput {
+    /** Resolved UMD configuration that produced the bundle. */
+    config: UmdConfig;
+    /** Entry points combined into the bundle. */
+    entries: EntryPoint[];
+}
+/**
+ * Aggregate per-format output collected during the bundle phase.
+ */
+interface FormatOutputs {
+    /** ESM entry points emitted. */
+    esm: EntryPoint[];
+    /** CommonJS entry points emitted. */
+    cjs: EntryPoint[];
+    /** IIFE bundles emitted. */
+    iife: IifeOutput[];
+    /** UMD bundles emitted. */
+    umd: UmdOutput[];
+}
+
+/**
+ * Per-format counts emitted during a build, derived from `FormatOutputs`.
+ */
+interface FormatCounts {
+    /** Number of ESM entry points emitted. */
+    esm: number;
+    /** Number of CommonJS entry points emitted. */
+    cjs: number;
+    /** Number of IIFE bundles emitted. */
+    iife: number;
+    /** Number of UMD bundles emitted. */
+    umd: number;
+}
+/**
+ * Output record describing a single emitted bin (per format and per platform).
+ */
+interface BinOutput {
+    /** Bin name (matches the configured `BinConfig.name`). */
+    name: string;
+    /** Output kind: a JS script for one of the supported formats, or a native SEA binary. */
+    kind: 'cjs' | 'esm' | 'native';
+    /** Absolute path to the emitted artifact. */
+    outputPath: string;
+    /** Native target identifier (e.g., `linux-x64`); present only when `kind === 'native'`. */
+    platform?: string;
+}
+/**
+ * Final result returned by the `build()` facade.
+ */
+interface BuildResult {
+    /** Whether the build completed without throwing. Always `true` when `build()` resolves. */
+    success: true;
+    /** Per-format counts of emitted artifacts. */
+    formatCounts: FormatCounts;
+    /** Aggregated per-format outputs. */
+    formatOutputs: FormatOutputs;
+    /** Bins emitted (JS scripts and / or native binaries). */
+    binOutputs: BinOutput[];
+    /** Total wall-clock duration in milliseconds. */
+    durationMs: number;
+}
+
+export type { AssetConditionPredicate, AssetSpec, AuthorField, BinConfig, BinFormatSpec, BinOutput, BinScriptFormat, BugsField, BuildConfig, BuildContext, BuildResult, BundleAllDepsOptions, CjsConfig, ConditionalExport, EntryPoint, EntryPointCategory, EntryPointDiscovery, EntryPointPlatform, EsmConfig, ExportValue, FormatCounts, FormatEntryConfig, FormatOutputs, FundingField, IifeConfig, IifeOutput, InheritFromSpec, IsWorkspacePackagePredicate, MemoryMonitorOptions, PackageJson, RepositoryField, SeaConfig, SeaPlatform, UmdConfig, UmdOutput, WorkspaceBundledDep, WorkspaceDepHoistPolicy };

package/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/builder/src/models/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EACV,uBAAuB,EACvB,SAAS,EACT,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,2BAA2B,EAC3B,oBAAoB,EACpB,SAAS,EACT,WAAW,EACX,SAAS,EACT,uBAAuB,GACxB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC1E,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAC5G,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3E,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA"}

package/models/index.esm.js

@@ -0,0 +1 @@
+