@useavalon/avalon 0.1.12 → 0.1.13

package/src/build/prop-extractors/lit.ts

@@ -0,0 +1,140 @@
+import { FALLBACK_PROPS, type PropExtractionResult } from "./vue.ts";
+
+/** Mapping from Lit type constructors to TypeScript type strings */
+const LIT_TYPE_MAP: Record<string, string> = {
+	String: "string",
+	Number: "number",
+	Boolean: "boolean",
+	Array: "unknown[]",
+	Object: "Record<string, unknown>",
+};
+
+/**
+ * Extract props from a Lit element source string.
+ *
+ * Parses `static properties = { ... }` blocks and maps Lit type
+ * constructors to TypeScript types. Properties with `state: true`
+ * are excluded (internal state, not public props).
+ *
+ * Never throws — returns fallback on any failure.
+ */
+export function extractLitProps(source: string): PropExtractionResult {
+	try {
+		const block = extractStaticPropertiesBlock(source);
+		if (block === null) {
+			return { propsType: FALLBACK_PROPS, fallback: true };
+		}
+
+		const props = parsePropertyEntries(block);
+		if (props.length === 0) {
+			return { propsType: FALLBACK_PROPS, fallback: true };
+		}
+
+		const fields = props.map((p) => p.name + "?: " + p.tsType).join("; ");
+		const propsType = "{ " + fields + " }";
+		return { propsType, fallback: false };
+	} catch {
+		console.warn(
+			"[avalon] Failed to extract Lit props — falling back to Record<string, unknown>",
+		);
+		return { propsType: FALLBACK_PROPS, fallback: true };
+	}
+}
+
+/**
+ * Extract the content inside `static properties = { ... }`.
+ * Uses brace-counting to handle nested objects.
+ * Returns the inner content (without outer braces), or null if not found.
+ */
+function extractStaticPropertiesBlock(source: string): string | null {
+	const marker = /static\s+properties\s*=\s*\{/;
+	const match = marker.exec(source);
+	if (!match) {
+		return null;
+	}
+
+	// Position of the opening brace
+	const openBrace = match.index + match[0].length - 1;
+	let depth = 1;
+	let i = openBrace + 1;
+
+	while (i < source.length && depth > 0) {
+		if (source[i] === "{") depth++;
+		else if (source[i] === "}") depth--;
+		i++;
+	}
+
+	if (depth !== 0) {
+		return null;
+	}
+
+	// Return content between the outer braces
+	return source.slice(openBrace + 1, i - 1);
+}
+
+interface ParsedProp {
+	name: string;
+	tsType: string;
+}
+
+/**
+ * Parse individual property entries from the static properties block content.
+ * Each entry looks like: `propName: { type: Constructor, ... }`
+ * Filters out entries with `state: true`.
+ */
+function parsePropertyEntries(block: string): ParsedProp[] {
+	const props: ParsedProp[] = [];
+
+	// Match each property entry: name: { ... }
+	// We use a regex to find property names followed by `{`, then brace-count
+	const entryRegex = /(\w+)\s*:\s*\{/g;
+	let entryMatch: RegExpExecArray | null;
+
+	while ((entryMatch = entryRegex.exec(block)) !== null) {
+		const name = entryMatch[1];
+		const openIdx = entryMatch.index + entryMatch[0].length - 1;
+
+		// Extract the balanced { ... } for this entry
+		const entryBody = extractBalancedBraces(block, openIdx);
+		if (entryBody === null) continue;
+
+		// Skip state properties
+		if (/\bstate\s*:\s*true\b/.test(entryBody)) continue;
+
+		// Extract the type constructor
+		const typeMatch = new RegExp(/\btype\s*:\s*(\w+)/).exec(entryBody);
+		const litType = typeMatch ? typeMatch[1] : null;
+		const tsType = litType && litType in LIT_TYPE_MAP
+			? LIT_TYPE_MAP[litType]
+			: "unknown";
+
+		props.push({ name, tsType });
+
+		// Advance regex past this entry to avoid re-matching nested braces
+		entryRegex.lastIndex = openIdx + (entryBody.length);
+	}
+
+	return props;
+}
+
+/**
+ * Extract a balanced `{ ... }` block starting at the given index.
+ * Returns the content between the braces (excluding outer braces), or null.
+ */
+function extractBalancedBraces(source: string, startIdx: number): string | null {
+	if (source[startIdx] !== "{") return null;
+
+	let depth = 0;
+	let i = startIdx;
+
+	while (i < source.length) {
+		if (source[i] === "{") depth++;
+		else if (source[i] === "}") depth--;
+		if (depth === 0) {
+			return source.slice(startIdx + 1, i);
+		}
+		i++;
+	}
+
+	return null;
+}

package/src/build/prop-extractors/qwik.ts

@@ -0,0 +1,16 @@
+import type { PropExtractionResult } from "./vue.ts";
+import { FALLBACK_PROPS } from "./vue.ts";
+
+/**
+ * Extract props type from a Qwik component file.
+ * Qwik components use component$(() => ...) — props are typed via the
+ * generic parameter or a Props interface. For now we fall back to
+ * Record<string, unknown> since Qwik's JSX types aren't Preact-compatible
+ * and the sidecar just needs to expose the island prop.
+ */
+export function extractQwikProps(_source: string): PropExtractionResult {
+	return {
+    propsType: FALLBACK_PROPS,
+    fallback: false
+};
+}

package/src/build/prop-extractors/solid.ts

@@ -0,0 +1,125 @@
+import { FALLBACK_PROPS, type PropExtractionResult } from "./vue.ts";
+
+/**
+ * Extract props from a Solid component source string.
+ *
+ * Supports two patterns:
+ *   1. `export default function Name(props: { ... })` — named function export
+ *   2. `export default (props: { ... }) =>` — arrow function export
+ *
+ * Uses brace-counting to handle nested types in the props parameter.
+ * Never throws — returns fallback on any failure.
+ */
+export function extractSolidProps(source: string): PropExtractionResult {
+	try {
+		// Try named function pattern first
+		const namedResult = extractFromNamedFunction(source);
+		if (namedResult !== null) {
+			return { propsType: namedResult, fallback: false };
+		}
+
+		// Try arrow function pattern
+		const arrowResult = extractFromArrowFunction(source);
+		if (arrowResult !== null) {
+			return { propsType: arrowResult, fallback: false };
+		}
+
+		return { propsType: FALLBACK_PROPS, fallback: true };
+	} catch {
+		console.warn(
+			"[avalon] Failed to extract Solid props — falling back to Record<string, unknown>",
+		);
+		return { propsType: FALLBACK_PROPS, fallback: true };
+	}
+}
+
+/**
+ * Extract props type from `export default function Name(props: { ... })`.
+ * Returns the type literal string, or null if not found.
+ */
+function extractFromNamedFunction(source: string): string | null {
+	// Match: export default function <Name>(props:
+	const regex = /export\s+default\s+function\s+\w+\s*\(\s*props\s*:\s*/;
+	const match = regex.exec(source);
+	if (!match) {
+		return null;
+	}
+
+	const typeStart = match.index + match[0].length;
+	return extractPropsType(source, typeStart);
+}
+
+/**
+ * Extract props type from `export default (props: { ... }) =>`.
+ * Returns the type literal string, or null if not found.
+ */
+function extractFromArrowFunction(source: string): string | null {
+	// Match: export default (props:
+	const regex = /export\s+default\s+\(\s*props\s*:\s*/;
+	const match = regex.exec(source);
+	if (!match) {
+		return null;
+	}
+
+	const typeStart = match.index + match[0].length;
+	return extractPropsType(source, typeStart);
+}
+
+/**
+ * Extract a props type starting at the given index in the source.
+ * Handles both inline type literals `{ ... }` using brace-counting
+ * and simple type references like `Props`.
+ * Returns the trimmed type string, or null if extraction fails.
+ */
+function extractPropsType(source: string, startIdx: number): string | null {
+	// Skip leading whitespace
+	let i = startIdx;
+	while (i < source.length && /\s/.test(source[i])) {
+		i++;
+	}
+
+	if (i >= source.length) {
+		return null;
+	}
+
+	// If it starts with `{`, use brace-counting for inline type literal
+	if (source[i] === "{") {
+		return extractBalancedBraces(source, i);
+	}
+
+	// Otherwise it's a type reference — read until `)` or `,`
+	const remaining = source.slice(i);
+	const refMatch = new RegExp(/^([A-Za-z_$][\w$]*(?:<[^>]*>)?)/).exec(remaining);
+	if (refMatch) {
+		return refMatch[1].trim();
+	}
+
+	return null;
+}
+
+/**
+ * Extract a balanced `{ ... }` block starting at the given index.
+ * Returns the full string including the outer braces, or null if unbalanced.
+ */
+function extractBalancedBraces(source: string, startIdx: number): string | null {
+	if (source[startIdx] !== "{") {
+		return null;
+	}
+
+	let depth = 0;
+	let i = startIdx;
+
+	while (i < source.length) {
+		if (source[i] === "{") {
+			depth++;
+		} else if (source[i] === "}") {
+			depth--;
+			if (depth === 0) {
+				return source.slice(startIdx, i + 1).trim();
+			}
+		}
+		i++;
+	}
+
+	return null; // unbalanced
+}

package/src/build/prop-extractors/svelte.ts

@@ -0,0 +1,194 @@
+import { FALLBACK_PROPS, type PropExtractionResult } from "./vue.ts";
+
+/**
+ * Extract props from a Svelte component source string.
+ *
+ * Supports three patterns:
+ *   1. `let { ... }: { ... } = $props()` — inline type literal
+ *   2. `let { ... }: TypeName = $props()` or `let name: TypeName = $props()`
+ *      — named type resolved from an interface/type declaration in the script block
+ *   3. `export let name: type` — Svelte 4 style, collected into a type literal
+ *
+ * Never throws — returns fallback on any failure.
+ */
+export function extractSvelteProps(source: string): PropExtractionResult {
+	try {
+		const scriptContent = extractScriptContent(source);
+		if (scriptContent === null) {
+			return { propsType: FALLBACK_PROPS, fallback: true };
+		}
+
+		// Try $props() patterns first (Svelte 5)
+		const propsResult = extractFromDollarProps(scriptContent);
+		if (propsResult !== null) {
+			return { propsType: propsResult, fallback: false };
+		}
+
+		// Try export let pattern (Svelte 4)
+		const exportLetResult = extractFromExportLet(scriptContent);
+		if (exportLetResult !== null) {
+			return { propsType: exportLetResult, fallback: false };
+		}
+
+		return { propsType: FALLBACK_PROPS, fallback: true };
+	} catch {
+		console.warn(
+			"[avalon] Failed to extract Svelte props — falling back to Record<string, unknown>",
+		);
+		return { propsType: FALLBACK_PROPS, fallback: true };
+	}
+}
+
+/**
+ * Extract the content of the `<script>` or `<script lang="ts">` block.
+ * Returns `null` if no script block is found.
+ */
+function extractScriptContent(source: string): string | null {
+	const scriptRegex = /<script\b[^>]*>([\s\S]*?)<\/script>/i;
+	const match = new RegExp(scriptRegex).exec(source);
+	return match ? match[1] : null;
+}
+
+/**
+ * Extract props type from `$props()` call patterns.
+ *
+ * Handles:
+ *   - `let { ... }: { ... } = $props()` (inline type literal)
+ *   - `let { ... }: TypeName = $props()` (named type, destructuring)
+ *   - `let name: TypeName = $props()` (named type, non-destructuring)
+ */
+function extractFromDollarProps(scriptContent: string): string | null {
+	// Match: let <binding> : <type> = $props()
+	// The binding can be `{ ... }` (destructuring) or a simple identifier
+	const propsCallRegex =
+		/let\s+(?:\{[^}]*\}|\w+)\s*:\s*([\s\S]*?)\s*=\s*\$props\s*\(\s*\)/;
+	const match = new RegExp(propsCallRegex).exec(scriptContent);
+	if (!match) {
+		return null;
+	}
+
+	const typeAnnotation = match[1].trim();
+	if (typeAnnotation.length === 0) {
+		return null;
+	}
+
+	// If it starts with `{`, it's an inline type literal — return as-is
+	if (typeAnnotation.startsWith("{")) {
+		// Validate balanced braces
+		if (!areBracesBalanced(typeAnnotation)) {
+			console.warn(
+				"[avalon] Unbalanced braces in Svelte $props() type — falling back",
+			);
+			return null;
+		}
+		return typeAnnotation;
+	}
+
+	// Otherwise it's a named type — resolve from interface/type in the script
+	return resolveNamedType(scriptContent, typeAnnotation);
+}
+
+/**
+ * Resolve a named type (interface or type alias) from the script content.
+ * Returns the body as a type literal string, or null if not found.
+ */
+function resolveNamedType(
+	scriptContent: string,
+	typeName: string,
+): string | null {
+	// Try interface first: `interface TypeName { ... }`
+	const interfaceRegex = new RegExp(
+		String.raw`interface\s+${escapeRegex(typeName)}\s*\{`,
+	);
+	const interfaceMatch = interfaceRegex.exec(scriptContent);
+	if (interfaceMatch) {
+		const startIdx = interfaceMatch.index + interfaceMatch[0].length - 1; // position of `{`
+		const body = extractBalancedBraces(scriptContent, startIdx);
+		if (body !== null) {
+			return body;
+		}
+	}
+
+	// Try type alias: `type TypeName = { ... }`
+	const typeAliasRegex = new RegExp(
+		String.raw`type\s+${escapeRegex(typeName)}\s*=\s*\{`,
+	);
+	const typeAliasMatch = typeAliasRegex.exec(scriptContent);
+	if (typeAliasMatch) {
+		const startIdx =
+			typeAliasMatch.index + typeAliasMatch[0].length - 1; // position of `{`
+		const body = extractBalancedBraces(scriptContent, startIdx);
+		if (body !== null) {
+			return body;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Extract a balanced `{ ... }` block starting at the given index.
+ * Returns the full string including the outer braces, or null if unbalanced.
+ */
+function extractBalancedBraces(source: string, startIdx: number): string | null {
+	if (source[startIdx] !== "{") {
+		return null;
+	}
+
+	let depth = 0;
+	let i = startIdx;
+
+	while (i < source.length) {
+		if (source[i] === "{") {
+			depth++;
+		} else if (source[i] === "}") {
+			depth--;
+			if (depth === 0) {
+				return source.slice(startIdx, i + 1).trim();
+			}
+		}
+		i++;
+	}
+
+	return null; // unbalanced
+}
+
+/**
+ * Extract props from `export let` declarations (Svelte 4 pattern).
+ * Collects all `export let name: type` and builds a type literal.
+ */
+function extractFromExportLet(scriptContent: string): string | null {
+	const exportLetRegex = /export\s+let\s+(\w+)\s*:\s*([^;=]+)/g;
+	const props: string[] = [];
+	let match: RegExpExecArray | null;
+
+	while ((match = exportLetRegex.exec(scriptContent)) !== null) {
+		const name = match[1].trim();
+		const type = match[2].trim();
+		if (name && type) {
+			props.push(`${name}: ${type}`);
+		}
+	}
+
+	if (props.length === 0) {
+		return null;
+	}
+
+	return `{ ${props.join("; ")} }`;
+}
+
+/** Check if braces are balanced in a string */
+function areBracesBalanced(str: string): boolean {
+	let depth = 0;
+	for (const ch of str) {
+		if (ch === "{") depth++;
+		else if (ch === "}") depth--;
+		if (depth < 0) return false;
+	}
+	return depth === 0;
+}
+
+/** Escape special regex characters in a string */
+function escapeRegex(str: string): string {
+	return str.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}

package/src/build/prop-extractors/vue.ts

@@ -0,0 +1,111 @@
+/** Result of prop extraction */
+export interface PropExtractionResult {
+	/** The TypeScript type literal for props, e.g. "{ count?: number }" */
+	propsType: string;
+	/** Whether extraction succeeded or fell back */
+	fallback: boolean;
+}
+
+/** Fallback props type used when extraction fails or no props are found */
+export const FALLBACK_PROPS = "Record<string, unknown>";
+
+/**
+ * Extract props from a Vue SFC source string.
+ *
+ * Looks for `defineProps<{...}>()` inside a `<script setup>` or
+ * `<script setup lang="ts">` block. Uses brace-counting to handle
+ * nested types within the angle brackets.
+ *
+ * Never throws — returns fallback on any failure.
+ */
+export function extractVueProps(source: string): PropExtractionResult {
+	try {
+		// 1. Extract the <script setup ...> block content
+		const scriptContent = extractScriptSetupContent(source);
+		if (scriptContent === null) {
+			return { propsType: FALLBACK_PROPS, fallback: true };
+		}
+
+		// 2. Find defineProps<...>() and extract the type argument
+		const propsType = extractDefinePropsType(scriptContent);
+		if (propsType === null) {
+			return { propsType: FALLBACK_PROPS, fallback: true };
+		}
+
+		return { propsType, fallback: false };
+	} catch {
+		console.warn(
+			"[avalon] Failed to extract Vue props — falling back to Record<string, unknown>",
+		);
+		return { propsType: FALLBACK_PROPS, fallback: true };
+	}
+}
+
+/**
+ * Extract the content of the `<script setup>` block from a Vue SFC source.
+ * Returns `null` if no `<script setup>` block is found.
+ */
+function extractScriptSetupContent(source: string): string | null {
+	// Match <script setup> or <script setup lang="ts"> (and other attrs)
+	// The 's' flag makes . match newlines
+	const scriptSetupRegex =
+		/<script\b[^>]*\bsetup\b[^>]*>([\s\S]*?)<\/script>/i;
+	const match = new RegExp(scriptSetupRegex).exec(source);
+	return match ? match[1] : null;
+}
+
+/** Check that `{` and `}` are balanced in a string */
+function hasBracesBalanced(str: string): boolean {
+	let depth = 0;
+	for (const ch of str) {
+		if (ch === "{") depth++;
+		else if (ch === "}") depth--;
+		if (depth < 0) return false;
+	}
+	return depth === 0;
+}
+
+/**
+ * Extract the type argument from `defineProps<TYPE>()` using angle-bracket
+ * counting to handle nested generics and object types.
+ *
+ * After extraction, validates that braces are balanced in the result.
+ * Returns the trimmed type string, or `null` if not found.
+ */
+function extractDefinePropsType(scriptContent: string): string | null {
+	const marker = "defineProps<";
+	const idx = scriptContent.indexOf(marker);
+	if (idx === -1) {
+		return null;
+	}
+
+	const start = idx + marker.length;
+	let depth = 1;
+	let i = start;
+
+	while (i < scriptContent.length && depth > 0) {
+		const ch = scriptContent[i];
+		if (ch === "<") depth++;
+		else if (ch === ">") depth--;
+		if (depth > 0) i++;
+	}
+
+	if (depth !== 0) {
+		console.warn("[avalon] Unbalanced angle brackets in defineProps<...> — falling back");
+		return null;
+	}
+
+	const typeStr = scriptContent.slice(start, i).trim();
+	if (typeStr.length === 0) {
+		return null;
+	}
+
+	if (!hasBracesBalanced(typeStr)) {
+		console.warn("[avalon] Unbalanced braces in defineProps type — falling back");
+		return null;
+	}
+
+	return typeStr;
+}
+
+

package/src/build/sidecar-file-manager.ts

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { readFile, writeFile, unlink, stat } from "node:fs/promises";
+
+/**
+ * Supported compound extensions for island files, ordered longest-first
+ * so that `.solid.tsx` matches before `.tsx`.
+ *
+ * Sidecar naming strategy per extension type:
+ * - `.vue`, `.svelte`  → `Name.d.vue.ts`, `Name.d.svelte.ts`
+ *   (foreign extensions — allowArbitraryExtensions picks these up)
+ * - `.lit.ts`          → `Name.lit.d.ts`
+ *   (TypeScript declaration file lookup: for `Name.lit.ts` TS looks for `Name.lit.d.ts`)
+ * - `.solid.tsx`       → `Name.solid.d.ts`
+ *   (TypeScript declaration file lookup: for `Name.solid.tsx` TS looks for `Name.solid.d.ts`)
+ * - `.qwik.tsx`        → `Name.qwik.d.ts`
+ *   (same as solid.tsx)
+ */
+const COMPOUND_EXTENSIONS = [".solid.tsx", ".qwik.tsx", ".lit.ts", ".svelte", ".vue"];
+
+/**
+ * Extensions where TypeScript's native `.d.ts` declaration lookup applies.
+ * For `Name.lit.ts`, TS looks for `Name.lit.d.ts`.
+ * For `Name.solid.tsx` / `Name.qwik.tsx`, TS looks for `Name.solid.d.ts` / `Name.qwik.d.ts`.
+ */
+const NATIVE_DECL_EXTENSIONS = new Set([".lit.ts", ".solid.tsx", ".qwik.tsx"]);
+
+/**
+ * Compute the sidecar declaration file path for a given island file path.
+ *
+ * For simple extensions like `.vue`, the sidecar is `Name.d.vue.ts`.
+ * For compound extensions like `.lit.ts`, the sidecar is `Name.d.lit.ts`.
+ * For `.solid.tsx`, the sidecar is `Name.d.solid.tsx.ts`.
+ */
+export function getSidecarPath(islandFilePath: string): string {
+	const dir = path.dirname(islandFilePath);
+	const basename = path.basename(islandFilePath);
+
+	for (const ext of COMPOUND_EXTENSIONS) {
+		if (basename.endsWith(ext)) {
+			const name = basename.slice(0, -ext.length);
+			if (NATIVE_DECL_EXTENSIONS.has(ext)) {
+				// For .lit.ts → Name.lit.d.ts  (TS declaration file lookup)
+				// For .solid.tsx / .qwik.tsx → Name.solid.d.ts / Name.qwik.d.ts
+				const innerExt = ext.endsWith(".ts") ? ext.slice(0, -3) : ext.slice(0, -4); // strip .ts or .tsx
+				return path.join(dir, `${name}${innerExt}.d.ts`);
+			}
+			// For .vue/.svelte → Name.d.vue.ts / Name.d.svelte.ts (allowArbitraryExtensions)
+			return path.join(dir, `${name}.d${ext}.ts`);
+		}
+	}
+
+	// Fallback
+	const ext = path.extname(islandFilePath);
+	const name = basename.slice(0, -ext.length);
+	return path.join(dir, `${name}.d${ext}.ts`);
+}
+
+/**
+ * Check if a sidecar file is up-to-date by comparing mtimes.
+ * Returns `true` if the sidecar exists and is newer than the source file.
+ */
+export async function isSidecarFresh(sourcePath: string, sidecarPath: string): Promise<boolean> {
+	try {
+		const [sourceStat, sidecarStat] = await Promise.all([
+			stat(sourcePath),
+			stat(sidecarPath),
+		]);
+		return sidecarStat.mtimeMs >= sourceStat.mtimeMs;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Write sidecar content only if it differs from the existing file.
+ * Returns `true` if a write was performed, `false` if content was already up-to-date.
+ */
+export async function writeSidecarIfChanged(sidecarPath: string, content: string): Promise<boolean> {
+	try {
+		const existing = await readFile(sidecarPath, "utf-8");
+		if (existing === content) {
+			return false;
+		}
+	} catch {
+		// File doesn't exist yet — that's fine, we'll write it
+	}
+
+	await writeFile(sidecarPath, content, "utf-8");
+	return true;
+}
+
+/**
+ * Delete a sidecar file if it exists.
+ * Returns `true` if a file was deleted, `false` if it didn't exist.
+ */
+export async function deleteSidecar(sidecarPath: string): Promise<boolean> {
+	try {
+		await unlink(sidecarPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+