@vertz/ui-compiler 0.2.3

package/README.md

@@ -0,0 +1,19 @@
+# @vertz/ui-compiler
+
+> **Internal package** — You don't use this directly. It powers the reactive compiler behind `@vertz/ui`.
+
+The UI compiler transforms `@vertz/ui` components at build time — converting `let` declarations into signals, wrapping derived `const` values in `computed()`, inserting `.value` accessors, and generating getter-based props for cross-component reactivity.
+
+## Who uses this
+
+- **`@vertz/ui-server`** — The Bun plugin loads this compiler to transform `.tsx` files during development and SSR.
+- **Framework contributors** — If you're working on the compiler itself, see the source in `src/` for architecture details.
+
+## Related Packages
+
+- [`@vertz/ui`](../ui) — The UI framework this compiler targets
+- [`@vertz/ui-server`](../ui-server) — Dev server and SSR runtime that invokes the compiler
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,564 @@
+import { SourceFile } from "ts-morph";
+/** Options for the compile() function. */
+interface CompileOptions {
+	/** Filename for source map generation. Defaults to 'input.tsx'. */
+	filename?: string;
+	/** Compilation target. 'dom' uses @vertz/ui/internals, 'tui' uses @vertz/tui/internals. */
+	target?: "dom" | "tui";
+}
+/** Severity of a compiler diagnostic. */
+type DiagnosticSeverity = "error" | "warning" | "info";
+/** A diagnostic message emitted during compilation. */
+interface CompilerDiagnostic {
+	/** Unique code identifying this diagnostic kind. */
+	code: string;
+	/** Human-readable message. */
+	message: string;
+	/** Severity level. */
+	severity: DiagnosticSeverity;
+	/** 1-based line number in source. */
+	line: number;
+	/** 0-based column offset. */
+	column: number;
+	/** Optional fix suggestion. */
+	fix?: string;
+}
+/** Result of a compile() call. */
+interface CompileOutput {
+	/** Transformed source code. */
+	code: string;
+	/** Source map (v3 JSON). */
+	map: {
+		version: number;
+		sources: string[];
+		sourcesContent?: string[];
+		mappings: string;
+		names: string[];
+	};
+	/** Diagnostics produced during compilation. */
+	diagnostics: CompilerDiagnostic[];
+}
+/** Classification of a variable's reactivity. */
+type ReactivityKind = "signal" | "computed" | "static";
+/** Information about a variable inside a component. */
+interface VariableInfo {
+	/** Variable name. */
+	name: string;
+	/** Reactivity classification. */
+	kind: ReactivityKind;
+	/** 0-based start position of the declaration in source. */
+	start: number;
+	/** 0-based end position of the declaration in source. */
+	end: number;
+	/**
+	* Signal properties on this variable (for signal-returning APIs like query()).
+	*
+	* @remarks
+	* Uses `Set<string>` for O(1) lookup performance during transformation.
+	* **Not JSON-serializable** — if this type is serialized (e.g., for caching or IPC),
+	* convert to `Array.from(signalProperties)` before serialization and reconstruct
+	* the Set on deserialization.
+	*/
+	signalProperties?: Set<string>;
+	/** Plain (non-signal) properties on this variable. */
+	plainProperties?: Set<string>;
+	/** Per-field signal properties (e.g., form().title.error). */
+	fieldSignalProperties?: Set<string>;
+	/** Synthetic variable name this binding was destructured from (e.g., `__query_0`). */
+	destructuredFrom?: string;
+	/** Whether this variable is a reactive source (e.g., useContext result). */
+	isReactiveSource?: boolean;
+}
+/** Information about a detected component function. */
+interface ComponentInfo {
+	/** Component function name. */
+	name: string;
+	/** Name of the props parameter (e.g. "props"), or null if none. */
+	propsParam: string | null;
+	/** Whether the props parameter uses destructuring. */
+	hasDestructuredProps: boolean;
+	/** 0-based start position of the function body. */
+	bodyStart: number;
+	/** 0-based end position of the function body. */
+	bodyEnd: number;
+}
+/** Classification of a JSX expression's reactivity. */
+interface JsxExpressionInfo {
+	/** 0-based start of the expression in source. */
+	start: number;
+	/** 0-based end of the expression in source. */
+	end: number;
+	/** Whether this expression depends on reactive variables. */
+	reactive: boolean;
+	/** Names of reactive variables referenced. */
+	deps: string[];
+}
+/** Kinds of in-place mutations on signal variables. */
+type MutationKind = "method-call" | "property-assignment" | "index-assignment" | "delete" | "object-assign";
+/** A detected in-place mutation on a signal variable. */
+interface MutationInfo {
+	/** The signal variable name being mutated. */
+	variableName: string;
+	/** Kind of mutation. */
+	kind: MutationKind;
+	/** 0-based start of the mutation expression. */
+	start: number;
+	/** 0-based end of the mutation expression. */
+	end: number;
+}
+/**
+* Detect functions that return JSX — the component boundaries
+* the compiler operates within.
+*/
+declare class ComponentAnalyzer {
+	analyze(sourceFile: SourceFile): ComponentInfo[];
+	/**
+	* Check whether a function contains JSX — either in a return statement
+	* or anywhere in the function body (e.g., variable assignments, loops,
+	* function call arguments).
+	*/
+	private _returnsJsx;
+	private _containsJsx;
+	private _fromFunctionDeclaration;
+	private _fromVariableDeclaration;
+}
+import { SourceFile as SourceFile2 } from "ts-morph";
+/** Classification of a css() call. */
+type CSSCallKind = "static" | "reactive";
+/** Information about a detected css() call. */
+interface CSSCallInfo {
+	/** Whether the call can be fully resolved at compile time. */
+	kind: CSSCallKind;
+	/** 0-based start position of the entire css() call expression. */
+	start: number;
+	/** 0-based end position of the entire css() call expression. */
+	end: number;
+	/** 1-based line number. */
+	line: number;
+	/** 0-based column. */
+	column: number;
+	/** The raw source text of the css() call. */
+	text: string;
+	/** For static calls: the parsed block names. */
+	blockNames: string[];
+}
+/**
+* Analyze a source file for css() calls.
+*/
+declare class CSSAnalyzer {
+	analyze(sourceFile: SourceFile2): CSSCallInfo[];
+	/** Classify whether a css() argument is fully static. */
+	private classifyArgument;
+	/** Check if a nested object (for complex selectors) is fully static. */
+	private isStaticNestedObject;
+	/** Check if a node is a static raw declaration: { property: '...', value: '...' } */
+	private isStaticRawDeclaration;
+	/** Extract block names from a static css() argument. */
+	private extractBlockNames;
+}
+import { SourceFile as SourceFile3 } from "ts-morph";
+/**
+* Map each JSX expression/attribute to its dependencies.
+* Classify as reactive or static based on whether any dependency is a signal,
+* computed, or a signal API property access (e.g., query().data, form().submitting).
+*/
+declare class JsxAnalyzer {
+	analyze(sourceFile: SourceFile3, component: ComponentInfo, variables: VariableInfo[]): JsxExpressionInfo[];
+}
+import { SourceFile as SourceFile4 } from "ts-morph";
+/**
+* Detect in-place mutations on signal variables.
+* These need special treatment: peek() + notify() pattern.
+*/
+declare class MutationAnalyzer {
+	analyze(sourceFile: SourceFile4, component: ComponentInfo, variables: VariableInfo[]): MutationInfo[];
+}
+import { SourceFile as SourceFile5 } from "ts-morph";
+/**
+* Two-pass taint analysis classifying variables as signal, computed, or static.
+*
+* Pass 1: Collect all `let` and `const` declarations in the component body,
+*         along with their dependency references.
+* Pass 2: Starting from JSX-referenced identifiers, trace backwards through
+*         const dependency chains to find which `let` vars are "needed" by JSX.
+*         Those `let` vars become signals, and the intermediate consts become computeds.
+*/
+declare class ReactivityAnalyzer {
+	analyze(sourceFile: SourceFile5, component: ComponentInfo): VariableInfo[];
+}
+/**
+* Main compile pipeline.
+*
+* 1. Parse → 2. Component analysis → 3. Reactivity analysis →
+* 4. Mutation analysis + transform → 5. Signal transform →
+* 6. Computed transform → 7. JSX analysis →
+* 8. JSX transform (includes prop transform) →
+* 9. Diagnostics → 10. Add imports → 11. Return { code, map, diagnostics }
+*/
+declare function compile(source: string, optionsOrFilename?: CompileOptions | string): CompileOutput;
+/** Result of extracting CSS from a source file. */
+interface CSSExtractionResult {
+	/** The extracted CSS rules as a string. */
+	css: string;
+	/** The block names found in static css() calls. */
+	blockNames: string[];
+}
+/**
+* Extracts CSS from css() calls in source code.
+* Produces a CSS string and list of block names for each file.
+*/
+declare class CSSExtractor {
+	/**
+	* Extract CSS from all static css() calls in the given source.
+	* @param source - The source code to analyze.
+	* @param filePath - The file path (used for deterministic class name generation).
+	* @returns The extracted CSS and block names.
+	*/
+	extract(source: string, filePath: string): CSSExtractionResult;
+}
+/**
+* Splits extracted CSS into per-route chunks with a shared common chunk.
+*/
+declare class CSSCodeSplitter {
+	/**
+	* Split CSS by route, extracting shared CSS into a common chunk.
+	*
+	* @param manifest - Map of route path to list of CSS-contributing file paths.
+	* @param fileExtractions - Map of file path to CSS extraction result.
+	* @returns Record of route path (or `__common`) to CSS string.
+	*/
+	split(manifest: Map<string, string[]>, fileExtractions: Map<string, CSSExtractionResult>): Record<string, string>;
+}
+/**
+* Eliminates CSS from modules that are not in the used set.
+*/
+declare class DeadCSSEliminator {
+	/**
+	* Filter extracted CSS to only include styles from used modules.
+	*
+	* @param extractions - Map of file path to extraction result.
+	* @param usedFiles - Set of file paths that are reachable in the module graph.
+	* @returns Combined CSS from only the used modules.
+	*/
+	eliminate(extractions: Map<string, CSSExtractionResult>, usedFiles: Set<string>): string;
+}
+/**
+* CSS HMR Integration for Vite Dev Mode.
+*
+* When a css() call changes, only the affected CSS is hot-replaced.
+* No full page reload needed for style changes. This module provides
+* the invalidation logic that a Vite plugin would call — it does not
+* need to BE a Vite plugin itself.
+*
+* Usage from a Vite plugin:
+*   1. On file load: handler.register(filePath, extractedCSS)
+*   2. On file change: handler.update(filePath, newCSS) -> { hasChanged, css, affectedFiles }
+*   3. If hasChanged: inject the new CSS via Vite's HMR API
+*/
+/** Result of a CSS HMR update check. */
+interface CSSHMRUpdateResult {
+	/** Whether the CSS actually changed. */
+	hasChanged: boolean;
+	/** The new CSS content (only meaningful if hasChanged is true). */
+	css: string;
+	/** List of file paths whose CSS was affected. */
+	affectedFiles: string[];
+}
+/**
+* Tracks CSS state per file and provides change detection for HMR.
+*/
+declare class CSSHMRHandler {
+	/** Map of file path to its last known CSS content. */
+	private cssCache;
+	/**
+	* Register a file's extracted CSS. Called on initial load.
+	* @param filePath - The source file path.
+	* @param css - The extracted CSS content.
+	*/
+	register(filePath: string, css: string): void;
+	/**
+	* Check if a file's CSS has changed and update the cache.
+	* @param filePath - The source file path.
+	* @param newCSS - The newly extracted CSS content.
+	* @returns Update result with change status and affected files.
+	*/
+	update(filePath: string, newCSS: string): CSSHMRUpdateResult;
+	/**
+	* Remove a file from HMR tracking.
+	* @param filePath - The source file path to untrack.
+	*/
+	remove(filePath: string): void;
+	/**
+	* Get a full CSS snapshot of all tracked files.
+	* Useful for providing the complete CSS state to Vite's HMR API.
+	* @returns Combined CSS from all tracked files.
+	*/
+	getSnapshot(): string;
+	/**
+	* Get the number of tracked files.
+	*/
+	get size(): number;
+	/**
+	* Clear all tracked CSS state.
+	*/
+	clear(): void;
+}
+/**
+* Builds a manifest mapping routes to their CSS file dependencies.
+*/
+declare class RouteCSSManifest {
+	/**
+	* Build a route-to-CSS manifest.
+	*
+	* @param routeToFiles - Map of route path to the component file paths used by that route.
+	* @param fileExtractions - Map of file path to CSS extraction result.
+	* @returns Map of route path to list of CSS-contributing file paths.
+	*/
+	build(routeToFiles: Map<string, string[]>, fileExtractions: Map<string, CSSExtractionResult>): Map<string, string[]>;
+}
+import { SourceFile as SourceFile6 } from "ts-morph";
+/**
+* Analyze css() calls for diagnostic issues.
+*/
+declare class CSSDiagnostics {
+	analyze(sourceFile: SourceFile6): CompilerDiagnostic[];
+	/** Validate a single shorthand string. */
+	private validateShorthand;
+	/** Validate a color token value. */
+	private validateColorToken;
+}
+import { SourceFile as SourceFile7 } from "ts-morph";
+/**
+* Detect mutations on `const` variables that are referenced in JSX.
+* These are likely bugs — the user probably meant to use `let`.
+*/
+declare class MutationDiagnostics {
+	analyze(sourceFile: SourceFile7, component: ComponentInfo, variables: VariableInfo[]): CompilerDiagnostic[];
+}
+import { SourceFile as SourceFile8 } from "ts-morph";
+/**
+* Warn when component props are destructured in the parameter.
+* Destructuring breaks reactivity because it eagerly reads values.
+*/
+declare class PropsDestructuringDiagnostics {
+	analyze(sourceFile: SourceFile8, components: ComponentInfo[]): CompilerDiagnostic[];
+}
+import { SourceFile as SourceFile9 } from "ts-morph";
+/**
+* Detect browser-only API usage at component top level that would crash during SSR.
+*
+* Flags globals like `localStorage`, `navigator`, observer constructors, and
+* browser-only `document` properties when used outside of callbacks (arrow
+* functions, function expressions). Usage inside `onMount()`, event handlers,
+* or any nested function is safe and not flagged.
+*/
+declare class SSRSafetyDiagnostics {
+	analyze(sourceFile: SourceFile9, component: ComponentInfo): CompilerDiagnostic[];
+}
+import { BunPlugin } from "bun";
+/** Options for the Vertz library compilation plugin. */
+interface VertzLibraryPluginOptions {
+	/** File filter regex. Defaults to /\.tsx$/. */
+	filter?: RegExp;
+	/** Compilation target. Defaults to 'dom'. */
+	target?: "dom" | "tui";
+}
+/**
+* Creates a Bun plugin for compiling Vertz library packages.
+*
+* Runs hydration transform + compile on .tsx files during bunup build.
+* CSS extraction is intentionally skipped — CSS hashing is path-dependent
+* and must be done by the consuming app's build pipeline.
+*/
+declare function createVertzLibraryPlugin(options?: VertzLibraryPluginOptions): BunPlugin;
+import MagicString from "magic-string";
+import { SourceFile as SourceFile10 } from "ts-morph";
+/**
+* Transform `const x = expr` → `const x = computed(() => expr)` when classified as computed.
+* Also handles destructuring: `const { a, b } = expr` → individual computed declarations.
+*/
+declare class ComputedTransformer {
+	transform(source: MagicString, sourceFile: SourceFile10, component: ComponentInfo, variables: VariableInfo[]): void;
+}
+import MagicString2 from "magic-string";
+import { SourceFile as SourceFile11 } from "ts-morph";
+/** Result of CSS transformation. */
+interface CSSTransformResult {
+	/** Extracted CSS rules. */
+	css: string;
+	/** Class name mappings per css() call: call index -> { blockName -> className }. */
+	classNameMaps: Map<number, Record<string, string>>;
+}
+/**
+* Transform static css() calls in the source.
+*/
+declare class CSSTransformer {
+	transform(s: MagicString2, sourceFile: SourceFile11, cssCalls: CSSCallInfo[], filePath: string): CSSTransformResult;
+	/** Process a static css() call to extract CSS and generate class names. */
+	private processStaticCall;
+	/** Build the replacement JS expression: { card: '_a1b2c3d4', title: '_e5f6g7h8' } */
+	private buildReplacement;
+}
+import MagicString3 from "magic-string";
+import { SourceFile as SourceFile12 } from "ts-morph";
+/**
+* Marks interactive components with `data-v-id` hydration markers.
+*
+* A component is "interactive" if it contains `let` variable declarations
+* (reactive state) in its body. Static components (only `const` or no state)
+* are skipped and ship zero JS.
+*
+* For interactive components, the root JSX element's opening tag is augmented
+* with `data-v-id="ComponentName"`.
+*/
+declare class HydrationTransformer {
+	transform(s: MagicString3, sourceFile: SourceFile12): void;
+	/**
+	* Determine whether a component is interactive by checking for `let`
+	* declarations in the component body.
+	*/
+	private _isInteractive;
+	/**
+	* Find the root JSX element in the component's return statement
+	* and inject `data-v-id` attribute into its opening tag.
+	*/
+	private _addHydrationMarker;
+	private _findRootJsx;
+	private _injectAttribute;
+}
+import MagicString4 from "magic-string";
+import { SourceFile as SourceFile13 } from "ts-morph";
+/**
+* Transform JSX into DOM helper calls.
+* Reactive expressions are wrapped in functions, static expressions are passed directly.
+*
+* IMPORTANT: This transformer reads expression text from MagicString (via source.slice())
+* so that it picks up .value transforms from the signal/computed transformers.
+*/
+declare class JsxTransformer {
+	transform(source: MagicString4, sourceFile: SourceFile13, component: ComponentInfo, variables: VariableInfo[], jsxExpressions: JsxExpressionInfo[]): void;
+	/**
+	* Walk the full function body and transform every top-level JSX node.
+	* "Top-level" means JSX that isn't nested inside other JSX (children are
+	* handled recursively by transformJsxNode).
+	*/
+	private transformAllJsx;
+}
+import MagicString5 from "magic-string";
+/**
+* Transform in-place mutations on signal variables into peek() + notify() pattern.
+*
+* `items.push('x')` → `(items.peek().push('x'), items.notify())`
+* `user.name = "Bob"` → `(user.peek().name = "Bob", user.notify())`
+*/
+declare class MutationTransformer {
+	transform(source: MagicString5, _component: ComponentInfo, mutations: MutationInfo[]): void;
+	/** `items.push('x')` → `(items.peek().push('x'), items.notify())` */
+	private _transformMethodCall;
+	/** `user.name = "Bob"` → `(user.peek().name = "Bob", user.notify())` */
+	private _transformPropertyAssignment;
+	/** `items[0] = 99` → `(items.peek()[0] = 99, items.notify())` */
+	private _transformIndexAssignment;
+	/** `delete config.debug` → `(delete config.peek().debug, config.notify())` */
+	private _transformDelete;
+	/** `Object.assign(user, ...)` → `(Object.assign(user.peek(), ...), user.notify())` */
+	private _transformObjectAssign;
+}
+import MagicString6 from "magic-string";
+import { Node, SourceFile as SourceFile14 } from "ts-morph";
+/**
+* Transform component props: reactive → getter, static → plain value.
+*
+* This transformer's core logic is integrated into the JsxTransformer's
+* buildPropsObject function. This class exists as a standalone API for
+* cases where prop transformation is needed independently.
+*/
+declare class PropTransformer {
+	transform(_source: MagicString6, _sourceFile: SourceFile14, _component: ComponentInfo, _variables: VariableInfo[], _jsxExpressions: JsxExpressionInfo[]): void;
+	/** Build a props object string for a component call. */
+	buildPropsObject(attrs: Node[], jsxMap: Map<number, JsxExpressionInfo>): string;
+}
+import MagicString7 from "magic-string";
+import { SourceFile as SourceFile15 } from "ts-morph";
+/**
+* Transform `let x = val` → `const x = signal(val)` and all reads/writes
+* for variables classified as signals.
+*
+* Accepts optional mutation ranges to skip — identifiers within mutation
+* expressions are handled by the MutationTransformer instead.
+*/
+declare class SignalTransformer {
+	transform(source: MagicString7, sourceFile: SourceFile15, component: ComponentInfo, variables: VariableInfo[], mutationRanges?: Array<{
+		start: number;
+		end: number;
+	}>): void;
+}
+/**
+* Token-aware CSS properties type generation.
+*
+* Generates a `CSSProperties` interface and a `ThemeTokenVar` union type
+* that knows about the theme's token names. This enables type-safe usage
+* of CSS custom property references like `var(--color-primary-500)`.
+*
+* Usage:
+* ```ts
+* const source = generateCSSProperties(themeInput);
+* // Produces:
+* // type ThemeTokenVar = 'var(--color-primary-500)' | 'var(--color-background)' | ...;
+* // export interface CSSProperties {
+* //   color?: ThemeTokenVar | string;
+* //   backgroundColor?: ThemeTokenVar | string;
+* //   ...
+* // }
+* ```
+*/
+/** Color tokens: a map of color names to their raw/contextual values. */
+type ColorTokens = Record<string, Record<string, string>>;
+/** Spacing tokens: a flat map of names to CSS values. */
+type SpacingTokens = Record<string, string>;
+/** Theme input matching defineTheme() input shape. */
+interface CSSPropertiesInput {
+	colors: ColorTokens;
+	spacing?: SpacingTokens;
+}
+/**
+* Generate TypeScript source for a token-aware CSSProperties interface.
+*
+* @param input - Theme token definitions (same shape as defineTheme input).
+* @returns TypeScript source string with ThemeTokenVar type and CSSProperties interface.
+*/
+declare function generateCSSProperties(input: CSSPropertiesInput): string;
+/**
+* Theme type generation.
+*
+* Generates TypeScript type definitions from a theme input,
+* producing a `ThemeTokens` type with all resolved token paths
+* as string-typed keys.
+*
+* Usage:
+* ```ts
+* const source = generateThemeTypes(themeInput);
+* // Produces:
+* // export type ThemeTokens = {
+* //   'primary.500': string;
+* //   'background': string;
+* // };
+* ```
+*/
+/** Color tokens: a map of color names to their raw/contextual values. */
+type ColorTokens2 = Record<string, Record<string, string>>;
+/** Spacing tokens: a flat map of names to CSS values. */
+type SpacingTokens2 = Record<string, string>;
+/** Theme input matching defineTheme() input shape. */
+interface ThemeTypeInput {
+	colors: ColorTokens2;
+	spacing?: SpacingTokens2;
+}
+/**
+* Generate TypeScript source for a ThemeTokens type from a theme definition.
+*
+* @param input - Theme token definitions (same shape as defineTheme input).
+* @returns TypeScript source string with exported ThemeTokens type.
+*/
+declare function generateThemeTypes(input: ThemeTypeInput): string;
+export { generateThemeTypes, generateCSSProperties, createVertzLibraryPlugin, compile, VertzLibraryPluginOptions, VariableInfo, ThemeTypeInput, SignalTransformer, SSRSafetyDiagnostics, RouteCSSManifest, ReactivityKind, ReactivityAnalyzer, PropsDestructuringDiagnostics, PropTransformer, MutationTransformer, MutationKind, MutationInfo, MutationDiagnostics, MutationAnalyzer, JsxTransformer, JsxExpressionInfo, JsxAnalyzer, HydrationTransformer, DiagnosticSeverity, DeadCSSEliminator, ComputedTransformer, ComponentInfo, ComponentAnalyzer, CompilerDiagnostic, CompileOutput, CompileOptions, CSSTransformer, CSSTransformResult, CSSPropertiesInput, CSSHMRUpdateResult, CSSHMRHandler, CSSExtractor, CSSExtractionResult, CSSDiagnostics, CSSCodeSplitter, CSSCallKind, CSSCallInfo, CSSAnalyzer };