@hyperfrontend/builder 0.1.0

package/bundle/declarations/index.d.ts

@@ -0,0 +1,262 @@
+import { BuildContext } from '../../models';
+import { Plugin } from '../../_dependencies/rollup/index.js';
+import { MemoryMonitor } from '../../memory';
+
+/**
+ * Result of running tsc to emit declaration files.
+ */
+interface GenerateDeclarationsResult {
+    /** Whether the tsc invocation succeeded. */
+    success: boolean;
+    /** Captured stdout content from tsc. */
+    stdout: string;
+    /** Captured stderr content from tsc. */
+    stderr: string;
+}
+/**
+ * Generates `.d.ts` and `.d.ts.map` files for every entry point in the project
+ * by spawning the workspace-local TypeScript compiler.
+ *
+ * After tsc finishes, calls `flattenDeclarationPaths` to relocate the nested
+ * `dist/<lib>/libs/<lib>/src/...` structure that tsc emits with `baseUrl=workspaceRoot`
+ * back into the flat per-library shape consumers expect.
+ *
+ * @param context - Resolved build context. Provides project root, output path, tsconfig path,
+ * workspace root, and entry point discovery for the flatten step.
+ * @returns Promise resolving with tsc's exit status, captured stdout, and captured stderr.
+ * @throws {Error} When tsc exits with a non-zero status or fails to spawn.
+ *
+ * @example Generating declarations as part of a custom build
+ * ```typescript
+ * const result = await generateDeclarations(context)
+ * console.log(result.stdout)
+ * ```
+ */
+declare const generateDeclarations: (context: BuildContext) => Promise<GenerateDeclarationsResult>;
+
+/**
+ * Sibling entry record consumed by {@link createSiblingExternalizePlugin}.
+ *
+ * Each sibling represents another entry-point in the same library that has its
+ * own bundled `index.d.ts`. The per-entry d.ts pass externalizes imports that
+ * resolve into a sibling's directory so consumers see one canonical type
+ * surface (e.g., `import type { EntryPoint } from '../models'` instead of an
+ * inlined declaration in every entry).
+ */
+interface SiblingEntry {
+    /** Entry's `srcPath` (subpath under `<outputPath>`). `''` for the package root. */
+    srcPath: string;
+    /** Absolute path to the entry's bundled `index.d.ts`. */
+    indexDtsPath: string;
+}
+/**
+ * Inputs to {@link createSiblingExternalizePlugin}.
+ */
+interface SiblingResolverInput {
+    /** `srcPath` of the entry the plugin is rewriting. */
+    selfSrcPath: string;
+    /** Absolute path to the current entry's bundled `index.d.ts`. */
+    selfDtsPath: string;
+    /** Other entries' bundled `index.d.ts` records. */
+    siblings: SiblingEntry[];
+}
+/**
+ * Returns the sibling entry whose directory contains `absolutePath`, or `undefined`
+ * when no sibling owns the path.
+ *
+ * @param absolutePath - Resolved absolute path of an import.
+ * @param siblings - Sibling-entry records.
+ * @returns Owning sibling entry, or `undefined`.
+ *
+ * @example Identifying a sibling for a resolved type import
+ * ```typescript
+ * const owner = findOwningSibling('/abs/dist/libs/foo/models/index.d.ts', siblings)
+ * ```
+ */
+declare const findOwningSibling: (absolutePath: string, siblings: SiblingEntry[]) => SiblingEntry | undefined;
+/**
+ * Computes the bare-specifier form of a sibling import as emitted in the
+ * rewritten `.d.ts` (e.g., `../models`, `../../models`, `./bundle/declarations`).
+ *
+ * Always omits the trailing `index.d.ts` so both `moduleResolution: 'bundler'`
+ * and `node` accept it.
+ *
+ * @param selfDtsPath - Absolute path to the current entry's `index.d.ts`.
+ * @param sibling - The sibling entry being targeted.
+ * @returns POSIX-style relative specifier ready for `id` in a rollup external resolution.
+ *
+ * @example Computing a sibling import from `bundle/index.d.ts` to `models/`
+ * ```typescript
+ * computeSiblingSpecifier(
+ *   '/abs/dist/libs/foo/bundle/index.d.ts',
+ *   { srcPath: 'models', indexDtsPath: '/abs/dist/libs/foo/models/index.d.ts' }
+ * ) // => '../models'
+ * ```
+ */
+declare const computeSiblingSpecifier: (selfDtsPath: string, sibling: SiblingEntry) => string;
+/**
+ * Returns a rollup plugin that externalizes any import resolving inside a
+ * sibling entry's directory tree, rewriting the emitted specifier to a POSIX
+ * relative path stripped of `/index` and `.d.ts` suffixes.
+ *
+ * The plugin's `resolveId` hook returns `null` for everything that does not
+ * resolve into a sibling — that lets the rest of the rollup-plugin-dts chain
+ * inline third-party type imports as before.
+ *
+ * Self-ownership is enforced by adding the current entry into the ownership
+ * pool: when the deepest-matching entry directory is the entry being rewritten
+ * (and not a sibling), the resolver returns `null` so rollup keeps the path
+ * internal. This matters for the package root entry whose directory prefix-
+ * matches every other entry's path — without including self, root would
+ * spuriously claim its own subtree's files.
+ *
+ * @param input - Self + sibling entry descriptors.
+ * @returns Rollup plugin.
+ *
+ * @example Plugin instance for the bundle entry pass
+ * ```typescript
+ * const plugin = createSiblingExternalizePlugin({
+ *   selfSrcPath: 'bundle',
+ *   selfDtsPath: '/abs/dist/libs/foo/bundle/index.d.ts',
+ *   siblings: [{ srcPath: 'models', indexDtsPath: '/abs/dist/libs/foo/models/index.d.ts' }],
+ * })
+ * ```
+ */
+declare const createSiblingExternalizePlugin: (input: SiblingResolverInput) => Plugin;
+/**
+ * Minimal entry-shape projection accepted by {@link filterSiblings}.
+ */
+interface SiblingFilterEntry {
+    /** Entry's `srcPath`. */
+    srcPath: string;
+}
+/**
+ * Convenience: filters an entry list to siblings of the supplied `srcPath`.
+ *
+ * @param srcPath - The entry's `srcPath` to exclude.
+ * @param entries - All discovered entries.
+ * @returns Entries whose `srcPath` differs from the supplied one.
+ *
+ * @example Building the sibling list for `bundle/`
+ * ```typescript
+ * const siblings = filterSiblings('bundle', allEntries)
+ * ```
+ */
+declare const filterSiblings: <T extends SiblingFilterEntry>(srcPath: string, entries: T[]) => T[];
+/**
+ * Joins an output base directory with an entry's `srcPath` to produce the
+ * absolute path of the entry's bundled `index.d.ts`.
+ *
+ * @param outputPath - Absolute output directory.
+ * @param srcPath - Entry's `srcPath`. `''` for root.
+ * @returns Absolute path to `<outputPath>/<srcPath>/index.d.ts`.
+ *
+ * @example Computing the d.ts path for a sub-entry
+ * ```typescript
+ * dtsPathFor('/abs/dist/libs/foo', 'models') // => '/abs/dist/libs/foo/models/index.d.ts'
+ * ```
+ */
+declare const dtsPathFor: (outputPath: string, srcPath: string) => string;
+
+/**
+ * Runs the per-entry d.ts inlining pass: re-runs `rollup-plugin-dts` over every
+ * tsc-emitted entry `.d.ts` so (a) local per-source sibling re-exports
+ * (`export … from './create-logger'`) are flattened into the entry's
+ * `index.d.ts`, and (b) bundled-dep type imports are routed through
+ * `_dependencies/<dep>/index.d.ts` rather than left as bare specifiers. This
+ * self-containment is what lets `pruneOrphanDeclarations` delete the orphaned
+ * per-source `.d.ts` afterwards without orphaning a still-referenced sibling.
+ *
+ * Runs whenever the build bundles any dep — npm (`bundledDeps`) **or** workspace
+ * (`workspaceBundledDeps`); a package whose deps are all `@hyperfrontend/*` still
+ * needs the flatten. Entries whose tsc output is missing are skipped silently —
+ * the bundle phase may have skipped them deliberately (e.g., empty bundles).
+ *
+ * @param context - Resolved build context.
+ * @param monitor - Optional memory monitor invoked between jobs.
+ * @throws {Error} When the worker artifact cannot be located, or when any per-entry job fails.
+ *
+ * @example Inlining bundled-dep types into every entry's .d.ts after tsc emission
+ * ```typescript
+ * await runDtsPerEntry(context)
+ * ```
+ */
+declare const runDtsPerEntry: (context: BuildContext, monitor?: MemoryMonitor) => Promise<void>;
+
+/**
+ * Runs the d.ts pre-pass: for each bundled dep, produces `_dependencies/<dep>/index.d.ts`
+ * by running `rollup-plugin-dts` over the dep's types entry. Cross-dep type imports are
+ * marked external so the per-entry d.ts pass can route them through `_dependencies/`.
+ *
+ * @param context - Resolved build context.
+ * @param monitor - Optional memory monitor invoked between jobs.
+ * @throws {Error} When the worker artifact cannot be located, or when any d.ts job fails.
+ *
+ * @example Producing _dependencies/<dep>/index.d.ts for a self-contained build
+ * ```typescript
+ * await runDtsPrePass(context)
+ * ```
+ */
+declare const runDtsPrePass: (context: BuildContext, monitor?: MemoryMonitor) => Promise<void>;
+
+/**
+ * Reshapes the nested declaration tree produced by tsc (with `baseUrl=workspaceRoot`)
+ * into the flat per-library structure consumers expect.
+ *
+ * Without this step tsc emits declarations at
+ *   `dist/libs/<lib>/libs/<lib>/src/index.d.ts`
+ * because it preserves the workspace-relative path. This primitive flattens that to
+ *   `dist/libs/<lib>/index.d.ts`
+ * while preserving any nested platform / feature subdirectories.
+ *
+ * The copy is recursive and unconditional, so internal non-entry subdirectories
+ * that any entry's `index.d.ts` re-exports from (e.g. `shared/`, `lib/`) are
+ * preserved rather than dropped. Per-source declarations left unreachable once
+ * the per-entry pass inlines each `index.d.ts` are removed afterwards by
+ * `pruneOrphanDeclarations`. Finally removes the leftover `libs/`, `plugins/`,
+ * and `apps/` folders tsc created at the output root.
+ *
+ * @param context - Resolved build context. Uses `projectRoot`, `outputPath`,
+ * and `workspaceRoot`.
+ *
+ * @example Flattening declarations after a manual tsc invocation
+ * ```typescript
+ * flattenDeclarationPaths(context)
+ * ```
+ */
+declare const flattenDeclarationPaths: (context: BuildContext) => void;
+
+/**
+ * Removes redundant per-source `.d.ts` / `.d.ts.map` files left behind once the
+ * per-entry flatten has inlined each entry's declarations into a self-contained
+ * `index.d.ts`.
+ *
+ * Walks the whole package tree (excluding `_dependencies/`) and deletes every
+ * declaration file **not reachable** from an entry-point `index.d.ts` via its
+ * transitive relative specifiers. Reachability — rather than a per-directory
+ * sweep — guarantees the invariant that after this runs no surviving `.d.ts`
+ * references a removed one: when the flatten made `index.d.ts` self-contained
+ * the reachable set collapses to the roots and every per-source sibling is
+ * pruned; when the flatten was skipped the siblings the public entry still
+ * re-exports (and anything they transitively re-export) stay live so the shipped
+ * types resolve. This removes the redundancy at the source so `dist` == the
+ * shipped tarball, demoting `package.json#files` to a backstop.
+ *
+ * Safety rails:
+ * - Never touches anything inside `_dependencies/`.
+ * - A `.d.ts.map` is kept iff its sibling `.d.ts` is reachable.
+ * - A dynamic (non-literal) `import(`/`require(` in any reached declaration
+ *   aborts the prune and keeps every declaration file.
+ *
+ * @param context - Resolved build context.
+ * @returns The total number of `.d.ts` / `.d.ts.map` files removed.
+ *
+ * @example Pruning orphans after generateDeclarations
+ * ```typescript
+ * const removed = pruneOrphanDeclarations(context)
+ * ```
+ */
+declare const pruneOrphanDeclarations: (context: BuildContext) => number;
+
+export { computeSiblingSpecifier, createSiblingExternalizePlugin, dtsPathFor, filterSiblings, findOwningSibling, flattenDeclarationPaths, generateDeclarations, pruneOrphanDeclarations, runDtsPerEntry, runDtsPrePass };
+export type { GenerateDeclarationsResult, SiblingEntry, SiblingResolverInput };

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bundle/declarations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAA;AACzE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,uBAAuB,EAAE,8BAA8B,EAAE,UAAU,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA"}