@useavalon/avalon 0.1.0

package/src/vite-plugin/island-sidecar-plugin.ts

@@ -0,0 +1,176 @@
+import type { Plugin } from "vite";
+import { readFile, access } from "node:fs/promises";
+import path from "node:path";
+import { detectFrameworkFromPath } from "../islands/integration-loader.ts";
+import { EXTRACTOR_MAP } from "../build/prop-extractors/index.ts";
+import { renderSidecarContent } from "../build/sidecar-renderer.ts";
+import {
+	getSidecarPath,
+	writeSidecarIfChanged,
+	deleteSidecar,
+	isSidecarFresh,
+} from "../build/sidecar-file-manager.ts";
+
+export interface SidecarPluginOptions {
+	/** Whether to log verbose output */
+	verbose?: boolean;
+}
+
+/** Frameworks that should be skipped — they already work natively with Preact/React JSX */
+const SKIP_FRAMEWORKS = new Set(["react", "preact"]);
+
+/** File extensions that qualify as island source files for HMR */
+const ISLAND_EXTENSIONS = [".vue", ".svelte", ".lit.ts", ".solid.tsx", ".qwik.tsx"];
+
+/**
+ * Check tsconfig.json for `allowArbitraryExtensions` and warn if missing.
+ */
+export async function checkTsConfigForArbitraryExtensions(
+	projectRoot: string,
+): Promise<void> {
+	const tsconfigPath = path.join(projectRoot, "tsconfig.json");
+	try {
+		const raw = await readFile(tsconfigPath, "utf-8");
+		const tsconfig = JSON.parse(raw);
+		if (tsconfig?.compilerOptions?.allowArbitraryExtensions !== true) {
+			console.warn(
+				'[avalon] tsconfig.json is missing "allowArbitraryExtensions: true" — sidecar .d.[ext].ts files require this setting',
+			);
+		}
+	} catch {
+		// tsconfig doesn't exist or can't be parsed - skip warning
+	}
+}
+
+/**
+ * Check if a file path is already a sidecar declaration file.
+ * Sidecar files contain `.d.` before the framework extension.
+ */
+function isSidecarFile(filePath: string): boolean {
+	const basename = path.basename(filePath);
+	return /\.d\.(vue|svelte|lit|solid\.tsx)/.test(basename);
+}
+
+/**
+ * Check if a file path looks like a supported component file that needs a sidecar.
+ * Excludes files that are already sidecar declaration files.
+ */
+function needsSidecar(filePath: string): boolean {
+	if (isSidecarFile(filePath)) {
+		return false;
+	}
+	return ISLAND_EXTENSIONS.some((ext) => filePath.endsWith(ext));
+}
+
+/**
+ * Generate a sidecar for a single component file.
+ * Returns true if a sidecar was written/updated, false otherwise.
+ */
+async function generateSidecarForFile(filePath: string, verbose?: boolean): Promise<boolean> {
+	try {
+		const framework = detectFrameworkFromPath(filePath);
+		if (SKIP_FRAMEWORKS.has(framework)) {
+			return false;
+		}
+
+		const extractor = EXTRACTOR_MAP[framework];
+		if (!extractor) {
+			return false;
+		}
+
+		const source = await readFile(filePath, "utf-8");
+		const result = extractor(source);
+		const content = renderSidecarContent(result.propsType);
+		const sidecarPath = getSidecarPath(filePath);
+		return await writeSidecarIfChanged(sidecarPath, content);
+	} catch (err) {
+		if (verbose) {
+			console.warn(
+				`[avalon] Failed to generate sidecar for ${filePath}:`,
+				err instanceof Error ? err.message : err,
+			);
+		}
+		return false;
+	}
+}
+
+/**
+ * Vite plugin that auto-generates `.d.[ext].ts` sidecar declaration files
+ * for non-React/Preact components when they are used as islands.
+ * 
+ * Sidecars are generated on-demand when component files are loaded,
+ * rather than scanning a fixed directory at startup.
+ */
+export function islandSidecarPlugin(options: SidecarPluginOptions = {}): Plugin {
+	let projectRoot: string;
+	const processedFiles = new Set<string>();
+
+	return {
+		name: "avalon:island-sidecar",
+
+		configResolved(config) {
+			projectRoot = config.root;
+		},
+
+		async buildStart() {
+			await checkTsConfigForArbitraryExtensions(projectRoot);
+			processedFiles.clear();
+		},
+
+		// Generate sidecar when a component file is loaded
+		async load(id) {
+			if (!needsSidecar(id) || processedFiles.has(id)) {
+				return null;
+			}
+
+			processedFiles.add(id);
+
+			// Check if sidecar needs regeneration
+			const sidecarPath = getSidecarPath(id);
+			if (await isSidecarFresh(id, sidecarPath)) {
+				return null;
+			}
+
+			const wrote = await generateSidecarForFile(id, options.verbose);
+			if (wrote && options.verbose) {
+				console.log(`[avalon] Generated sidecar for: ${id}`);
+			}
+
+			return null; // Let Vite handle the actual file loading
+		},
+
+		async handleHotUpdate(ctx) {
+			const filePath = ctx.file;
+
+			if (!needsSidecar(filePath)) {
+				return;
+			}
+
+			// Check if the file was deleted
+			let fileExists = true;
+			try {
+				await access(filePath);
+			} catch {
+				fileExists = false;
+			}
+
+			if (!fileExists) {
+				// File was deleted — remove the sidecar
+				const sidecarPath = getSidecarPath(filePath);
+				const deleted = await deleteSidecar(sidecarPath);
+				if (deleted && options.verbose) {
+					console.log(`[avalon] Deleted sidecar for removed file: ${filePath}`);
+				}
+				processedFiles.delete(filePath);
+				return;
+			}
+
+			// File was changed — regenerate sidecar
+			processedFiles.delete(filePath); // Allow re-processing
+			const wrote = await generateSidecarForFile(filePath, options.verbose);
+			if (wrote && options.verbose) {
+				console.log(`[avalon] Updated sidecar for: ${filePath}`);
+			}
+		},
+	};
+}

package/src/vite-plugin/module-discovery.ts

@@ -0,0 +1,189 @@
+/**
+ * Module Discovery for Modular Architecture
+ * 
+ * Discovers pages and layouts within feature modules for file-based routing.
+ * Supports co-located architecture where each module contains its own pages/layouts.
+ */
+
+import { readdir, stat } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import type { ResolvedModulesConfig } from "./types.ts";
+
+/**
+ * Discovered module with its pages and layouts directories
+ */
+export interface DiscoveredModule {
+  /** Module name (folder name) */
+  name: string;
+  /** Absolute path to the module directory */
+  path: string;
+  /** Absolute path to pages directory (if exists) */
+  pagesDir: string | null;
+  /** Absolute path to layouts directory (if exists) */
+  layoutsDir: string | null;
+  /** Route prefix derived from module name */
+  routePrefix: string;
+}
+
+/**
+ * Result of module discovery
+ */
+export interface ModuleDiscoveryResult {
+  /** All discovered modules */
+  modules: DiscoveredModule[];
+  /** All page directories (for route discovery) */
+  pageDirs: Array<{ dir: string; prefix: string }>;
+  /** All layout directories */
+  layoutDirs: Array<{ dir: string; prefix: string }>;
+}
+
+/**
+ * Discover all modules within the modules directory
+ * 
+ * @param modulesConfig - Resolved modules configuration
+ * @param projectRoot - Project root directory
+ * @returns Discovery result with modules, page dirs, and layout dirs
+ */
+export async function discoverModules(
+  modulesConfig: ResolvedModulesConfig,
+  projectRoot: string
+): Promise<ModuleDiscoveryResult> {
+  const modulesDir = resolve(projectRoot, modulesConfig.dir);
+  const modules: DiscoveredModule[] = [];
+  const pageDirs: Array<{ dir: string; prefix: string }> = [];
+  const layoutDirs: Array<{ dir: string; prefix: string }> = [];
+
+  try {
+    const entries = await readdir(modulesDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      
+      // Skip hidden directories and common non-module folders
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+
+      const modulePath = join(modulesDir, entry.name);
+      const pagesPath = join(modulePath, modulesConfig.pagesDirName);
+      const layoutsPath = join(modulePath, modulesConfig.layoutsDirName);
+
+      // Check if pages/layouts directories exist
+      const [pagesExists, layoutsExists] = await Promise.all([
+        directoryExists(pagesPath),
+        directoryExists(layoutsPath),
+      ]);
+
+      // Determine route prefix
+      // 'home' or 'root' module maps to '/', others map to '/moduleName'
+      const routePrefix = getRoutePrefix(entry.name);
+
+      const module: DiscoveredModule = {
+        name: entry.name,
+        path: modulePath,
+        pagesDir: pagesExists ? pagesPath : null,
+        layoutsDir: layoutsExists ? layoutsPath : null,
+        routePrefix,
+      };
+
+      modules.push(module);
+
+      if (pagesExists) {
+        pageDirs.push({ dir: pagesPath, prefix: routePrefix });
+      }
+
+      if (layoutsExists) {
+        layoutDirs.push({ dir: layoutsPath, prefix: routePrefix });
+      }
+    }
+  } catch (error) {
+    // Modules directory doesn't exist or can't be read
+    // This is fine - modules are optional
+  }
+
+  // Sort modules so 'home'/'root' comes first (for route priority)
+  modules.sort((a, b) => {
+    if (a.routePrefix === '/') return -1;
+    if (b.routePrefix === '/') return 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  return { modules, pageDirs, layoutDirs };
+}
+
+/**
+ * Get the route prefix for a module
+ * Special modules like 'home', 'root', 'main' map to '/'
+ */
+function getRoutePrefix(moduleName: string): string {
+  const rootModules = ['home', 'root', 'main', 'index'];
+  if (rootModules.includes(moduleName.toLowerCase())) {
+    return '/';
+  }
+  return '/' + moduleName;
+}
+
+/**
+ * Check if a directory exists
+ */
+async function directoryExists(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get all page directories including both traditional and modular
+ * 
+ * @param pagesDir - Traditional pages directory
+ * @param modulesConfig - Modules configuration (if any)
+ * @param projectRoot - Project root
+ * @returns Array of page directories with their route prefixes
+ */
+export async function getAllPageDirs(
+  pagesDir: string,
+  modulesConfig: ResolvedModulesConfig | null,
+  projectRoot: string
+): Promise<Array<{ dir: string; prefix: string }>> {
+  const dirs: Array<{ dir: string; prefix: string }> = [];
+
+  // Add traditional pages directory
+  const traditionalPagesPath = resolve(projectRoot, pagesDir);
+  if (await directoryExists(traditionalPagesPath)) {
+    dirs.push({ dir: traditionalPagesPath, prefix: '/' });
+  }
+
+  // Add modular page directories
+  if (modulesConfig) {
+    const { pageDirs } = await discoverModules(modulesConfig, projectRoot);
+    dirs.push(...pageDirs);
+  }
+
+  return dirs;
+}
+
+/**
+ * Get all layout directories including both traditional and modular
+ */
+export async function getAllLayoutDirs(
+  layoutsDir: string,
+  modulesConfig: ResolvedModulesConfig | null,
+  projectRoot: string
+): Promise<Array<{ dir: string; prefix: string }>> {
+  const dirs: Array<{ dir: string; prefix: string }> = [];
+
+  // Add traditional layouts directory
+  const traditionalLayoutsPath = resolve(projectRoot, layoutsDir);
+  if (await directoryExists(traditionalLayoutsPath)) {
+    dirs.push({ dir: traditionalLayoutsPath, prefix: '/' });
+  }
+
+  // Add modular layout directories
+  if (modulesConfig) {
+    const { layoutDirs } = await discoverModules(modulesConfig, projectRoot);
+    dirs.push(...layoutDirs);
+  }
+
+  return dirs;
+}