@hyperfrontend/builder 0.1.0

package/bundle/dedupe/index.d.ts

@@ -0,0 +1,400 @@
+import { ChunkFormat } from '../dependencies';
+import ts from 'typescript';
+import { MemoryMonitor } from '../../memory';
+import { BuildContext } from '../../models';
+
+/**
+ * A first-party module's path under `src/`, without extension and
+ * forward-slashed (e.g. `events/events`, `models`). Doubles as the directory
+ * name the module's hoisted chunk lives under: `_shared/<moduleKey>/`.
+ */
+type ModuleKey = string;
+/**
+ * Ownership index mapping each unambiguously-owned runtime symbol to the
+ * first-party module that declares it.
+ */
+interface OwnerIndex {
+    /**
+     * Maps a runtime symbol's base name (rollup `$N` collision suffix stripped)
+     * to its owning module key. Names declared by more than one module are
+     * omitted — an ambiguous name can never be safely attributed.
+     */
+    ownerOf: Map<string, ModuleKey>;
+}
+/**
+ * A single import binding observed at an entry bundle's top level, retaining
+ * enough shape to re-materialize the same edge from a hoisted chunk.
+ */
+interface ImportBinding {
+    /** Raw module specifier exactly as written in the entry source. */
+    specifier: string;
+    /** Shape of the binding, governing how it is re-emitted into a shared chunk. */
+    kind: 'named' | 'namespace' | 'default' | 'cjs-namespace' | 'cjs-named';
+    /** Exported name on the target module for `named`/`cjs-named` bindings. */
+    imported?: string;
+}
+/**
+ * A removable top-level runtime declaration in an entry bundle, attributed to
+ * its owning first-party module by name.
+ */
+interface EntryDecl {
+    /** Owning symbol's base name (collision suffix stripped). */
+    base: string;
+    /** Local name exactly as the bundle declares it (may carry a `$N` suffix). */
+    localName: string;
+    /** The owning top-level statement. */
+    statement: ts.Statement;
+    /** Emitted code text (leading comments excluded); the raw chunk-body source. */
+    text: string;
+    /**
+     * Rename-insensitive identity key — `$N` suffixes stripped from identifier
+     * nodes; the raw {@link text} is still the chunk-body source.
+     */
+    fingerprint: string;
+}
+/**
+ * Structural model of one parsed entry bundle.
+ */
+interface ParsedEntry {
+    /** The parsed source file. */
+    sourceFile: ts.SourceFile;
+    /** Top-level runtime declarations in source order. */
+    decls: EntryDecl[];
+    /** Import/`require` bindings keyed by their local name. */
+    importBindings: Map<string, ImportBinding>;
+    /** Top-level statements that are neither imports, declarations, nor the export surface. */
+    bareStatements: ts.Statement[];
+    /** Every local name a top-level declaration binds. */
+    declNames: Set<string>;
+    /** End offset of the bundle's leading import/`require`/`'use strict'` header — the insertion point for hoisted imports. */
+    headerEnd: number;
+}
+/**
+ * Strips rollup's `$N` collision-rename suffix from a local name, yielding the
+ * canonical source symbol name.
+ *
+ * @param name - A local identifier from an emitted bundle.
+ * @returns The base name with any trailing `$digits` removed.
+ *
+ * @example Undoing a collision rename
+ * ```typescript
+ * baseName('Store$1') // => 'Store'
+ * ```
+ */
+declare const baseName: (name: string) => string;
+/**
+ * Computes a rename-insensitive identity key for a top-level statement.
+ *
+ * Two copies of the same source that differ only in rollup's per-entry `$N`
+ * collision suffixes compare equal, while genuinely different code never
+ * collides: `$N` is stripped from identifier nodes only, so string literals,
+ * comments, numeric tokens, and discriminating member names stay intact.
+ *
+ * @param statement - The top-level statement to fingerprint.
+ * @param sourceFile - The source file the statement belongs to.
+ * @returns The statement's text with `$N` stripped from every identifier node.
+ *
+ * @example Stripping a dep-namespace local's collision suffix
+ * ```typescript
+ * fingerprintOf(statement, sourceFile) // 'const x = index_cjs_js.getType();' for both `$1` and `$2` copies
+ * ```
+ */
+declare const fingerprintOf: (statement: ts.Statement, sourceFile: ts.SourceFile) => string;
+/**
+ * Resolves a hoisted module's chunk file name for a format.
+ *
+ * @param format - Output module format.
+ * @returns The per-entry chunk file name (`index.esm.js` / `index.cjs.js`).
+ *
+ * @example Naming the CJS chunk
+ * ```typescript
+ * chunkFileName('cjs') // => 'index.cjs.js'
+ * ```
+ */
+declare const chunkFileName: (format: ChunkFormat) => string;
+/**
+ * Computes the `_shared/` directory (relative to the output root) that holds a
+ * module's hoisted chunk.
+ *
+ * @param moduleKey - The owning module's key.
+ * @returns The forward-slashed `_shared/<moduleKey>` directory.
+ *
+ * @example Locating a module's shared directory
+ * ```typescript
+ * sharedDirFor('events/events') // => '_shared/events/events'
+ * ```
+ */
+declare const sharedDirFor: (moduleKey: ModuleKey) => string;
+/**
+ * Parses one entry bundle into the structural model the hoist pass consumes.
+ *
+ * Classifies every top-level statement as an import binding, a removable
+ * runtime declaration, the export surface, or an opaque bare statement. Inline
+ * `export`-modified declarations are treated as part of the export surface
+ * (never removable), so the bundle's published API is never disturbed.
+ *
+ * @param source - Raw entry bundle source text.
+ * @param format - Module format selecting ESM vs CJS import/export shapes.
+ * @returns The parsed entry model.
+ *
+ * @example Modeling an ESM entry bundle
+ * ```typescript
+ * const parsed = parseEntry("import { x } from './_dependencies/a/index.esm.js'\nclass C {}", 'esm')
+ * ```
+ */
+declare const parseEntry: (source: string, format: ChunkFormat) => ParsedEntry;
+/**
+ * Groups an entry's attributable declarations by their owning module.
+ *
+ * Declarations whose base name is unowned (a dependency or unexported helper
+ * inlined into the bundle) are skipped, leaving them in place.
+ *
+ * @param parsed - A parsed entry bundle.
+ * @param owners - The first-party ownership index.
+ * @returns Map from module key to that module's declarations in source order.
+ *
+ * @example Attributing an entry's declarations
+ * ```typescript
+ * const byModule = attribute(parseEntry(source, 'esm'), owners)
+ * ```
+ */
+declare const attribute: (parsed: ParsedEntry, owners: OwnerIndex) => Map<ModuleKey, EntryDecl[]>;
+/**
+ * Builds the first-party ownership index by scanning `<srcRoot>/**` for the
+ * runtime symbols each module exports.
+ *
+ * Both exported and private top-level runtime declarations are indexed, so a
+ * module's private helpers hoist alongside the exports that use them. Types-only
+ * modules declare no runtime symbols and contribute nothing. A name declared by
+ * two different modules is ambiguous and dropped from the index, so the pass can
+ * never misattribute it.
+ *
+ * @param srcRoot - Absolute path to the project's `src/` directory.
+ * @returns The ownership index.
+ *
+ * @example Indexing a library's source tree
+ * ```typescript
+ * const owners = indexOwners('/abs/libs/foo/src')
+ * ```
+ */
+declare const indexOwners: (srcRoot: string) => OwnerIndex;
+
+/**
+ * A reference from a module's declarations into another first-party module's
+ * hoisted chunk.
+ */
+interface CrossRef {
+    /** Local identifier as written in this module's code (may carry a `$N` suffix). */
+    ref: string;
+    /** The referenced symbol's base name — the name the target chunk exports. */
+    base: string;
+    /** Owning module key of the referenced symbol. */
+    moduleKey: ModuleKey;
+}
+/**
+ * A reference from a module's declarations into a dependency import the entry
+ * already carries.
+ */
+interface DepRef {
+    /** Local identifier as written in this module's code. */
+    ref: string;
+    /** The entry's binding shape for that identifier. */
+    binding: ImportBinding;
+}
+/**
+ * Raw classification of every free identifier a module's declarations reference.
+ */
+interface ModuleResolution {
+    /** References into other first-party modules. */
+    crossModule: CrossRef[];
+    /** References into dependency imports the entry carries. */
+    depImports: DepRef[];
+    /** References that name an inlined, unattributable top-level entry binding — a hard blocker. */
+    unresolved: string[];
+}
+/** A cross-module import edge resolved to a concrete chunk specifier. */
+interface CrossImport {
+    /** Local binding name in the emitted chunk. */
+    ref: string;
+    /** Exported name on the target chunk. */
+    exported: string;
+    /** Module specifier reaching the target chunk from this chunk. */
+    specifier: string;
+}
+/** A dependency import edge resolved to a concrete (chunk-relative) specifier. */
+interface DepImport {
+    /** Local binding name in the emitted chunk. */
+    ref: string;
+    /** Binding shape governing how the import is re-emitted. */
+    kind: ImportBinding['kind'];
+    /** Exported name for `named`/`cjs-named` bindings. */
+    imported?: string;
+    /** Chunk-relative module specifier reaching the dependency. */
+    specifier: string;
+}
+/** Everything needed to render a single module's hoisted chunk. */
+interface ChunkPlan {
+    /** The module's declarations in canonical source order. */
+    decls: EntryDecl[];
+    /** Resolved cross-module import edges. */
+    crossImports: CrossImport[];
+    /** Resolved dependency import edges. */
+    depImports: DepImport[];
+}
+/**
+ * Classifies every free identifier referenced by a module's declarations,
+ * partitioning them into cross-module edges, dependency edges, and hard
+ * blockers.
+ *
+ * Identifiers the module declares itself are intra-chunk and ignored. A name
+ * that is neither owned, nor a dependency binding, nor a top-level entry
+ * declaration is a runtime global and needs no import. Cross-module references
+ * are always safe to lift because {@link planHoists} only keeps an acyclic
+ * subset, so every dependency chunk is fully evaluated before its dependent.
+ *
+ * @param decls - The module's canonical declarations.
+ * @param owners - First-party ownership index.
+ * @param importBindings - The consuming entry's import bindings.
+ * @param entryDeclNames - Every top-level declaration name in the entry.
+ * @param selfModuleKey - The module being resolved.
+ * @returns The reference resolution.
+ *
+ * @example Resolving a module's references
+ * ```typescript
+ * const resolution = resolveModuleRefs(decls, owners, parsed.importBindings, parsed.declNames, 'events/events')
+ * ```
+ */
+declare const resolveModuleRefs: (decls: EntryDecl[], owners: OwnerIndex, importBindings: Map<string, ImportBinding>, entryDeclNames: Set<string>, selfModuleKey: ModuleKey) => ModuleResolution;
+/**
+ * Renders a hoisted module chunk: its resolved imports, the union of its
+ * declarations, and an export surface naming each declaration by its base name.
+ *
+ * @param plan - The module's declarations plus resolved import edges.
+ * @param format - Output module format.
+ * @returns The chunk source text.
+ *
+ * @example Rendering an ESM chunk
+ * ```typescript
+ * const source = renderChunk({ decls, crossImports: [], depImports: [] }, 'esm')
+ * ```
+ */
+declare const renderChunk: (plan: ChunkPlan, format: ChunkFormat) => string;
+
+/**
+ * Aggregate result of the shared-first-party hoist pass.
+ */
+interface HoistReport {
+    /** Number of `_shared/` chunk files written across all formats. */
+    chunksWritten: number;
+    /** Net bytes reclaimed: inlined copies removed minus the shared chunks emitted. */
+    bytesReclaimed: number;
+}
+/**
+ * Lifts first-party modules that are inlined into multiple entry bundles into
+ * shared `_shared/<srcPath>/index.<fmt>.js` chunks and rewrites every consuming
+ * entry to import them.
+ *
+ * Runs as an additive post-emit pass over the already-bundled `esm` and `cjs`
+ * outputs, each processed independently; `iife`/`umd`/`bin` and `.d.ts` outputs
+ * are never read. Per-entry isolated bundling is untouched. Every hoist is
+ * proven safe by {@link planHoists} before it happens — structurally identical
+ * copies, resolvable references, and cycle-free module-initialization — so any module
+ * that cannot be proven safe is left inlined and the output is, worst case,
+ * identical to the input.
+ *
+ * @param context - Resolved build context. `outputPath` locates the bundles and
+ * `projectRoot/src` drives ownership attribution.
+ * @param monitor - Optional memory monitor; a checkpoint is captured after each
+ * format so the pass is observable.
+ * @returns Counts of chunks written and net bytes reclaimed.
+ *
+ * @example Hoisting after the dependency prune
+ * ```typescript
+ * const report = hoistSharedFirstParty(context, monitor)
+ * ```
+ */
+declare const hoistSharedFirstParty: (context: BuildContext, monitor?: MemoryMonitor) => HoistReport;
+
+/**
+ * One parsed entry bundle paired with its declarations grouped by owning module.
+ */
+interface EntryInput {
+    /** The parsed entry bundle. */
+    parsed: ParsedEntry;
+    /** The entry's attributable declarations grouped by module key. */
+    byModule: Map<ModuleKey, EntryDecl[]>;
+}
+/**
+ * A module the plan will hoist into a shared chunk.
+ */
+interface PlannedModule {
+    /** Index of the entry whose copy defines the canonical chunk content and order. */
+    canonicalEntryIndex: number;
+    /** Canonical declarations, in source order, that populate the chunk. */
+    decls: EntryDecl[];
+    /** Resolved references the chunk must re-import. */
+    resolution: ModuleResolution;
+    /** Indexes of every entry that inlines this module and must be rewritten. */
+    consumingEntryIndexes: number[];
+}
+/**
+ * Plans which first-party modules can be hoisted into shared chunks.
+ *
+ * A module qualifies only when it is inlined into at least two entries, is not
+ * entangled with a bare statement, presents structurally identical declarations
+ * (rename-insensitive) in a consistent order across every copy, references
+ * nothing unresolvable, and —
+ * after closure and acyclic peeling — depends only on other hoisted modules
+ * through a cycle-free graph. Anything failing these is left inlined, so the
+ * worst case equals the unmodified output.
+ *
+ * @param entries - Parsed entries with their per-module attribution.
+ * @param owners - First-party ownership index.
+ * @returns Map from module key to its hoist plan.
+ *
+ * @example Planning hoists for a set of entries
+ * ```typescript
+ * const plan = planHoists(entries, owners)
+ * ```
+ */
+declare const planHoists: (entries: EntryInput[], owners: OwnerIndex) => Map<ModuleKey, PlannedModule>;
+
+/**
+ * One module's hoist within a single entry: the declarations to splice out and
+ * the chunk specifier the entry should import them from.
+ */
+interface EntryHoist {
+    /** The module's declarations as they appear in this entry. */
+    decls: EntryDecl[];
+    /** Chunk-relative module specifier reaching the module's shared chunk. */
+    specifier: string;
+}
+/**
+ * Rewrites an entry bundle to consume hoisted modules from `_shared/` chunks
+ * instead of inlining them.
+ *
+ * Splices every hoisted declaration (and its leading comments) out of the entry
+ * and prepends an import/`require` binding the chunk's base export to the
+ * entry's local name — aliasing when rollup renamed the local (`foo as foo$1`).
+ * Only the hoisted symbols the entry still references after splicing are
+ * re-imported: a private helper used solely by another hoisted export (e.g. a
+ * reducer's `handlers`, used only by the hoisted `rootReducer`) is seen as dead
+ * against the spliced body and omitted from the import, while the chunk it lives
+ * in keeps it. The bundle's export surface is left untouched: surviving spliced
+ * names are now supplied by the inserted imports, so the published API is
+ * byte-for-byte identical to before.
+ *
+ * @param parsed - The parsed entry bundle.
+ * @param hoists - The modules hoisted out of this entry, each with its chunk specifier.
+ * @param format - Output module format.
+ * @returns The rewritten entry source, or the original source when `hoists` is empty.
+ *
+ * @example Rewriting an entry to import a shared module
+ * ```typescript
+ * const rewritten = rewriteEntry(parseEntry(source, 'esm'), [{ decls, specifier: './_shared/state/index.esm.js' }], 'esm')
+ * ```
+ */
+declare const rewriteEntry: (parsed: ParsedEntry, hoists: EntryHoist[], format: ChunkFormat) => string;
+
+export { attribute, baseName, chunkFileName, fingerprintOf, hoistSharedFirstParty, indexOwners, parseEntry, planHoists, renderChunk, resolveModuleRefs, rewriteEntry, sharedDirFor };
+export type { ChunkPlan, CrossImport, CrossRef, DepImport, DepRef, EntryDecl, EntryHoist, EntryInput, HoistReport, ImportBinding, ModuleKey, ModuleResolution, OwnerIndex, ParsedEntry, PlannedModule };

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bundle/dedupe/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACvG,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAC5G,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC9D,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAC9H,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}