@useavalon/avalon 0.1.12 → 0.1.13

package/src/build/island-types-generator.ts

@@ -0,0 +1,476 @@
+/**
+ * Island Types Generator
+ * 
+ * Generates TypeScript declaration files (.d.ts) for discovered islands.
+ * Provides type information including namespace and qualified names for
+ * better IDE support and type safety when referencing islands.
+ */
+
+import { resolve, dirname, relative } from "node:path";
+import { writeFile, mkdir } from "node:fs/promises";
+import type {
+  DiscoveredIsland,
+  IslandDirectory,
+  IslandCollision,
+} from "../islands/discovery/types.ts";
+import {
+  createIslandRegistry,
+  getQualifiedIslandName,
+} from "../islands/discovery/index.ts";
+
+/**
+ * Options for type generation
+ */
+export interface IslandTypeGeneratorOptions {
+  /** Output directory for generated types (default: "src/types") */
+  outputDir?: string;
+  /** Whether to generate a single file or per-directory files (default: "single") */
+  mode?: "single" | "per-directory";
+  /** Module name for the generated types (default: "avalon-islands") */
+  moduleName?: string;
+  /** Whether to include JSDoc comments (default: true) */
+  includeJsDoc?: boolean;
+}
+
+/**
+ * Default options for type generation
+ */
+const DEFAULT_OPTIONS: Required<IslandTypeGeneratorOptions> = {
+  outputDir: "src/types",
+  mode: "single",
+  moduleName: "avalon-islands",
+  includeJsDoc: true,
+};
+
+/**
+ * Result of type generation
+ */
+export interface TypeGenerationResult {
+  /** Whether generation was successful */
+  success: boolean;
+  /** Generated file paths */
+  files: string[];
+  /** Number of islands typed */
+  islandCount: number;
+  /** Any errors that occurred */
+  errors: string[];
+}
+
+/**
+ * Generate TypeScript declaration files for all discovered islands.
+ * 
+ * @param projectRoot - The root directory of the project
+ * @param options - Options for type generation
+ * @returns Result of the type generation
+ */
+export async function generateIslandTypes(
+  projectRoot: string,
+  options: IslandTypeGeneratorOptions = {}
+): Promise<TypeGenerationResult> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const result: TypeGenerationResult = {
+    success: true,
+    files: [],
+    islandCount: 0,
+    errors: [],
+  };
+
+  try {
+    // Discover all islands
+    const registry = await createIslandRegistry(projectRoot);
+    const islands = registry.getAllIslands();
+    const directories = registry.directories;
+    const collisions = registry.collisions;
+
+    result.islandCount = islands.length;
+
+    if (islands.length === 0) {
+      return result;
+    }
+
+    if (opts.mode === "single") {
+      // Generate a single declaration file
+      const content = generateSingleTypeFile(
+        islands,
+        directories,
+        collisions,
+        opts
+      );
+      const outputPath = resolve(projectRoot, opts.outputDir, "islands.d.ts");
+      
+      await ensureDir(dirname(outputPath));
+      await writeFile(outputPath, content);
+      result.files.push(outputPath);
+    } else {
+      // Generate per-directory declaration files
+      const filesByDir = await generatePerDirectoryTypeFiles(
+        islands,
+        directories,
+        projectRoot,
+        opts
+      );
+      result.files.push(...filesByDir);
+    }
+  } catch (error) {
+    result.success = false;
+    result.errors.push(error instanceof Error ? error.message : String(error));
+  }
+
+  return result;
+}
+
+/**
+ * Generate a single TypeScript declaration file for all islands.
+ */
+function generateSingleTypeFile(
+  islands: DiscoveredIsland[],
+  directories: IslandDirectory[],
+  collisions: IslandCollision[],
+  options: Required<IslandTypeGeneratorOptions>
+): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push("/**");
+  lines.push(" * Auto-generated TypeScript declarations for Avalon islands.");
+  lines.push(" * Do not edit this file manually - it will be overwritten.");
+  lines.push(` * Generated at: ${new Date().toISOString()}`);
+  lines.push(" */");
+  lines.push("");
+
+  // Module declaration
+  lines.push(`declare module "${options.moduleName}" {`);
+  lines.push("");
+
+  // Island directory info
+  if (options.includeJsDoc) {
+    lines.push("  /**");
+    lines.push("   * Discovered island directories");
+    lines.push("   */");
+  }
+  lines.push("  export const islandDirectories: readonly string[];");
+  lines.push("");
+
+  // Generate types for each island
+  const islandsByNamespace = groupIslandsByNamespace(islands);
+
+  for (const [namespace, nsIslands] of islandsByNamespace) {
+    if (namespace === "") {
+      // Default namespace - export directly
+      lines.push("  // Default islands (src/islands/)");
+      for (const island of nsIslands) {
+        lines.push(...generateIslandTypeDeclaration(island, options, "  "));
+      }
+    } else {
+      // Nested namespace - create namespace block
+      const namespaceParts = namespace.split("/");
+      const nsName = namespaceParts.map(p => toPascalCase(p)).join("");
+      
+      lines.push(`  // Islands from ${namespace}/islands/`);
+      lines.push(`  export namespace ${nsName} {`);
+      for (const island of nsIslands) {
+        lines.push(...generateIslandTypeDeclaration(island, options, "    "));
+      }
+      lines.push("  }");
+    }
+    lines.push("");
+  }
+
+  // Island map type
+  lines.push("  /**");
+  lines.push("   * Map of all island qualified names to their component types");
+  lines.push("   */");
+  lines.push("  export interface IslandMap {");
+  for (const island of islands) {
+    const qualifiedName = getQualifiedIslandName(island);
+    lines.push(`    "${qualifiedName}": typeof ${getIslandTypeName(island)};`);
+  }
+  lines.push("  }");
+  lines.push("");
+
+  // Collision warnings
+  if (collisions.length > 0) {
+    lines.push("  /**");
+    lines.push("   * Warning: The following island names have collisions.");
+    lines.push("   * Use qualified names (namespace/name) to disambiguate.");
+    lines.push("   */");
+    lines.push("  export type CollidingIslandNames =");
+    const collisionNames = collisions.map(c => `    | "${c.name}"`);
+    lines.push(collisionNames.join("\n") + ";");
+    lines.push("");
+  }
+
+  // Helper type for island resolution
+  lines.push("  /**");
+  lines.push("   * Get the component type for an island by name or qualified name");
+  lines.push("   */");
+  lines.push("  export type GetIsland<K extends keyof IslandMap> = IslandMap[K];");
+  lines.push("");
+
+  lines.push("}");
+  lines.push("");
+
+  // Global augmentation for Island component props
+  lines.push("// Augment the Island component props with discovered islands");
+  lines.push("declare global {");
+  lines.push("  namespace Avalon {");
+  lines.push("    interface DiscoveredIslands {");
+  for (const island of islands) {
+    const qualifiedName = getQualifiedIslandName(island);
+    lines.push(`      "${qualifiedName}": true;`);
+  }
+  lines.push("    }");
+  lines.push("  }");
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate per-directory TypeScript declaration files.
+ */
+async function generatePerDirectoryTypeFiles(
+  islands: DiscoveredIsland[],
+  directories: IslandDirectory[],
+  projectRoot: string,
+  options: Required<IslandTypeGeneratorOptions>
+): Promise<string[]> {
+  const files: string[] = [];
+  const islandsByDir = new Map<string, DiscoveredIsland[]>();
+
+  // Group islands by directory
+  for (const island of islands) {
+    const dirPath = island.directory.path;
+    const existing = islandsByDir.get(dirPath) || [];
+    existing.push(island);
+    islandsByDir.set(dirPath, existing);
+  }
+
+  // Generate a file for each directory
+  for (const directory of directories) {
+    const dirIslands = islandsByDir.get(directory.path) || [];
+    if (dirIslands.length === 0) continue;
+
+    const content = generateDirectoryTypeFile(directory, dirIslands, options);
+    const outputPath = resolve(
+      projectRoot,
+      directory.path,
+      "islands.d.ts"
+    );
+
+    await ensureDir(dirname(outputPath));
+    await writeFile(outputPath, content);
+    files.push(outputPath);
+  }
+
+  // Generate index file that re-exports all
+  const indexContent = generateIndexTypeFile(directories, projectRoot, options);
+  const indexPath = resolve(projectRoot, options.outputDir, "islands.d.ts");
+  
+  await ensureDir(dirname(indexPath));
+  await writeFile(indexPath, indexContent);
+  files.push(indexPath);
+
+  return files;
+}
+
+/**
+ * Generate a TypeScript declaration file for a single directory.
+ */
+function generateDirectoryTypeFile(
+  directory: IslandDirectory,
+  islands: DiscoveredIsland[],
+  options: Required<IslandTypeGeneratorOptions>
+): string {
+  const lines: string[] = [];
+
+  lines.push("/**");
+  lines.push(` * Auto-generated TypeScript declarations for islands in ${directory.relativePath}`);
+  lines.push(" * Do not edit this file manually - it will be overwritten.");
+  lines.push(" */");
+  lines.push("");
+
+  for (const island of islands) {
+    lines.push(...generateIslandTypeDeclaration(island, options, ""));
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate an index file that re-exports all island types.
+ */
+function generateIndexTypeFile(
+  directories: IslandDirectory[],
+  projectRoot: string,
+  options: Required<IslandTypeGeneratorOptions>
+): string {
+  const lines: string[] = [];
+
+  lines.push("/**");
+  lines.push(" * Auto-generated index for all island type declarations.");
+  lines.push(" * Do not edit this file manually - it will be overwritten.");
+  lines.push(" */");
+  lines.push("");
+
+  for (const directory of directories) {
+    const relativePath = relative(
+      resolve(projectRoot, options.outputDir),
+      resolve(projectRoot, directory.path, "islands.d.ts")
+    ).replace(/\\/g, "/").replace(/\.d\.ts$/, "");
+    
+    lines.push(`export * from "${relativePath}";`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate type declaration for a single island.
+ */
+function generateIslandTypeDeclaration(
+  island: DiscoveredIsland,
+  options: Required<IslandTypeGeneratorOptions>,
+  indent: string
+): string[] {
+  const lines: string[] = [];
+  const typeName = getIslandTypeName(island);
+
+  if (options.includeJsDoc) {
+    lines.push(`${indent}/**`);
+    lines.push(`${indent} * Island component: ${island.name}`);
+    lines.push(`${indent} * Framework: ${island.framework}`);
+    lines.push(`${indent} * Source: ${island.relativePath}`);
+    if (island.namespace) {
+      lines.push(`${indent} * Namespace: ${island.namespace}`);
+    }
+    lines.push(`${indent} */`);
+  }
+
+  // Generate appropriate type based on framework
+  const componentType = getFrameworkComponentType(island.framework);
+  lines.push(`${indent}export const ${typeName}: ${componentType};`);
+
+  return lines;
+}
+
+/**
+ * Get the TypeScript type name for an island.
+ */
+function getIslandTypeName(island: DiscoveredIsland): string {
+  // Use the component name directly (already PascalCase)
+  return island.name;
+}
+
+/**
+ * Get the appropriate component type for a framework.
+ */
+function getFrameworkComponentType(framework: string): string {
+  switch (framework) {
+    case "preact":
+      return "import('preact').FunctionComponent<any>";
+    case "react":
+      return "import('react').FC<any>";
+    case "vue":
+      return "import('vue').DefineComponent<any, any, any>";
+    case "svelte":
+      return "import('svelte').SvelteComponent";
+    case "solid":
+      return "import('solid-js').Component<any>";
+    case "lit":
+      return "typeof import('lit').LitElement";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * Group islands by their namespace.
+ */
+function groupIslandsByNamespace(
+  islands: DiscoveredIsland[]
+): Map<string, DiscoveredIsland[]> {
+  const grouped = new Map<string, DiscoveredIsland[]>();
+
+  for (const island of islands) {
+    const existing = grouped.get(island.namespace) || [];
+    existing.push(island);
+    grouped.set(island.namespace, existing);
+  }
+
+  // Sort by namespace (empty string first, then alphabetically)
+  const sorted = new Map<string, DiscoveredIsland[]>();
+  const keys = Array.from(grouped.keys()).sort((a, b) => {
+    if (a === "") return -1;
+    if (b === "") return 1;
+    return a.localeCompare(b);
+  });
+
+  for (const key of keys) {
+    sorted.set(key, grouped.get(key)!);
+  }
+
+  return sorted;
+}
+
+/**
+ * Convert a string to PascalCase.
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split(/[-_\s]+/)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join("");
+}
+
+/**
+ * Ensure a directory exists.
+ */
+async function ensureDir(path: string): Promise<void> {
+  try {
+    await mkdir(path, { recursive: true });
+  } catch (error) {
+    if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== 'EEXIST') {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Watch for island changes and regenerate types.
+ * 
+ * @param projectRoot - The root directory of the project
+ * @param options - Options for type generation
+ * @returns Cleanup function to stop watching
+ */
+export async function watchAndGenerateTypes(
+  projectRoot: string,
+  options: IslandTypeGeneratorOptions = {}
+): Promise<() => void> {
+  const { createIslandWatcher, createIslandRegistry } = await import(
+    "../islands/discovery/index.ts"
+  );
+
+  const registry = await createIslandRegistry(projectRoot);
+  const watcher = createIslandWatcher(projectRoot, registry);
+
+  // Generate initial types
+  await generateIslandTypes(projectRoot, options);
+
+  // Watch for changes
+  const cleanup = await watcher.watch(async (event) => {
+    // Rebuild registry and regenerate types
+    await registry.rebuild();
+    const result = await generateIslandTypes(projectRoot, options);
+    
+    if (!result.success) {
+      console.error(`❌ Failed to regenerate types:`, result.errors);
+    }
+  });
+
+  return () => {
+    cleanup();
+    watcher.stop();
+  };
+}