carrick 0.3.53

package/sidecar/dist/src/bundler.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Surface Emitter - Emits .d.ts surface files with rewritten module specifiers
+ *
+ * This module replaces the previous dts-bundle-generator approach with a
+ * ts-morph-based AST transformation and emission pipeline.
+ *
+ * Key features:
+ * - Does NOT bundle dependencies (unlike dts-bundle-generator)
+ * - Rewrites module specifiers to repo-specific aliases (@carrick/{repoName}/{spec})
+ * - Handles ImportDeclaration, ImportTypeNode, and ExportDeclaration
+ * - Supports scoped packages and subpaths
+ * - Includes a safety pass for any compiler-introduced raw specifiers
+ */
+import { Project } from 'ts-morph';
+import type { PayloadDefinition, SurfaceEmitResult, SymbolRequest, BundleResult } from './types.js';
+/**
+ * Options for SurfaceEmitter construction
+ */
+export interface SurfaceEmitterOptions {
+    /** The ts-morph Project instance */
+    project: Project;
+    /** The repository root directory (absolute path) */
+    repoRoot: string;
+}
+/**
+ * Options for TypeBundler construction (legacy)
+ */
+export interface TypeBundlerOptions {
+    /** The ts-morph Project instance */
+    project: Project;
+    /** The repository root directory (absolute path) */
+    repoRoot: string;
+}
+/**
+ * SurfaceEmitter - Generates .d.ts surface files with rewritten imports
+ *
+ * Usage:
+ *   const emitter = new SurfaceEmitter({ project, repoRoot });
+ *   const result = emitter.emit(repoName, payloads, outputPath);
+ */
+export declare class SurfaceEmitter {
+    private readonly project;
+    private readonly repoRoot;
+    constructor(options: SurfaceEmitterOptions);
+    /**
+     * Emit a surface .d.ts file containing payload type declarations
+     *
+     * @param repoName - Repository name for specifier rewriting
+     * @param payloads - Payload definitions to include
+     * @param outputPath - Path to write the surface file
+     * @returns SurfaceEmitResult
+     */
+    emit(repoName: string, payloads: PayloadDefinition[], outputPath: string): SurfaceEmitResult;
+    /**
+     * Extract potential import references from a type string.
+     * These are module specifiers that might need rewriting.
+     */
+    private extractImportReferences;
+    /**
+     * Rewrite all module specifiers in a source file to use repo-scoped aliases.
+     *
+     * Targets:
+     * 1. ImportDeclaration.moduleSpecifier
+     * 2. ImportTypeNode argument (import("..."))
+     * 3. ExportDeclaration.moduleSpecifier
+     *
+     * @returns Array of rewritten specifiers
+     */
+    private rewriteModuleSpecifiers;
+    /**
+     * Determine if a module specifier should be rewritten.
+     * Only non-relative specifiers should be rewritten.
+     */
+    private shouldRewriteSpecifier;
+    /**
+     * Rewrite a module specifier to the repo-scoped format.
+     *
+     * Format: @carrick/{repoName}/{originalSpecifier}
+     *
+     * Preserves:
+     * - Scoped packages: "@scope/pkg" → "@carrick/repo-a/@scope/pkg"
+     * - Subpaths: "zod/lib/helpers" → "@carrick/repo-a/zod/lib/helpers"
+     * - Combined: "@scope/pkg/subpath" → "@carrick/repo-a/@scope/pkg/subpath"
+     */
+    private rewriteSpecifier;
+    /**
+     * Safety pass: Scan emitted content for any raw specifiers that might have
+     * been introduced by the TypeScript compiler and rewrite them.
+     *
+     * This catches edge cases where the compiler emits types with their original
+     * module specifiers that weren't caught by AST traversal.
+     */
+    private safetyRewritePass;
+    /**
+     * Log a message to stderr
+     */
+    private log;
+    /**
+     * Log an error to stderr
+     */
+    private logError;
+}
+/**
+ * TypeBundler - Legacy bundler using simpler approach
+ *
+ * This is a simplified replacement that doesn't use dts-bundle-generator.
+ * It extracts type definitions directly using ts-morph.
+ *
+ * @deprecated Use SurfaceEmitter instead for the new architecture
+ */
+export declare class TypeBundler {
+    private readonly project;
+    private readonly repoRoot;
+    constructor(options: TypeBundlerOptions);
+    /**
+     * Bundle the requested symbols into type definitions
+     *
+     * @param symbols - Array of symbol requests to bundle
+     * @returns BundleResult with the bundled content or errors
+     */
+    bundle(symbols: SymbolRequest[]): BundleResult;
+    private dedupeSymbols;
+    private validateSymbols;
+    private validateSymbol;
+    /**
+     * Structural body (`{ ... }`) for an interface/object type, with every nested
+     * named member inlined recursively. Returns null when the expansion is not a
+     * usable object body (e.g. the expander fell back to a bare name), so the
+     * caller can keep the verbatim declaration instead of emitting an invalid
+     * interface. The expander already guards recursion (depth + per-branch cycle
+     * set) and keeps builtins/`node_modules` types by name.
+     */
+    private expandObjectBody;
+    private extractTypeDefinition;
+    private elementNeedsArrayParens;
+    private extractTypeDefinitionBase;
+    private isPathSource;
+    private isPlaceholderSource;
+    private log;
+    private logError;
+}