@useavalon/avalon 0.1.23 → 0.1.25

package/dist/src/islands/component-analysis.d.ts

@@ -0,0 +1,38 @@
+import type { JSX } from 'preact';
+import { type AnalyzerOptions, type AnalysisReport } from '../core/components/component-analyzer.ts';
+import type { IslandProps } from './types.ts';
+/**
+ * Analyze component file for rendering strategy
+ *
+ * Attempts to read the component file from various path variations and
+ * analyzes its content to determine the optimal rendering strategy.
+ * Uses caching to avoid repeated file I/O and analysis for the same components.
+ *
+ * @param src - The source path to the component
+ * @param options - Analyzer options for customizing the analysis
+ * @returns Analysis result with rendering strategy decision
+ * @throws Error if component file cannot be found
+ */
+export declare function analyzeComponentFile(src: string, options?: AnalyzerOptions): Promise<AnalysisReport>;
+/**
+ * Render component with SSR-only strategy (no hydration)
+ *
+ * Renders a component server-side without adding client-side hydration.
+ * This is useful for static components that don't require interactivity.
+ *
+ * @param params - Rendering parameters
+ * @param params.src - Component source path
+ * @param params.condition - Island hydration condition
+ * @param params.props - Props to pass to the component
+ * @param params.framework - Optional explicit framework (if not provided, will be detected)
+ * @param params.renderOptions - Additional render options
+ * @returns Island component with SSR-only rendering
+ * @throws Error if SSR rendering fails
+ */
+export declare function renderComponentSSROnly({ src, condition, props, framework: explicitFramework, renderOptions, }: {
+    src: string;
+    condition: IslandProps['condition'];
+    props: Record<string, unknown>;
+    framework?: string;
+    renderOptions: AnalyzerOptions;
+}): Promise<JSX.Element>;

package/dist/src/islands/css-utils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * CSS Utilities Module
+ *
+ * This module contains all CSS-related utilities for the Island system:
+ * - Svelte SSR CSS collection and management
+ * - CSS scoping for component isolation
+ * - CSS optimization and minification
+ * - CSS parsing and deduplication
+ */
+declare global {
+    var __svelteSSRCSS: Map<string, SvelteSSRCSSEntry> | undefined;
+}
+interface SvelteSSRCSSEntry {
+    css: string;
+    scopeId: string;
+    src: string;
+    isGlobal: boolean;
+    timestamp: number;
+}
+/**
+ * Add CSS to the global Svelte SSR collection with scoping information
+ */
+export declare function addSvelteSSRCSS(css: string, scopeId: string, src: string, isGlobal?: boolean): void;
+/**
+ * Get collected Svelte SSR CSS with enhanced processing and deduplication
+ * Enhanced version with better CSS management and document head injection support
+ */
+export declare function getSvelteSSRCSS(clear?: boolean): string;
+/**
+ * Get CSS formatted for document head injection during SSR
+ * Returns CSS wrapped in appropriate style tags with metadata
+ */
+export declare function getSvelteSSRCSSForHead(clear?: boolean): string;
+/**
+ * Get CSS statistics for debugging and monitoring
+ */
+export declare function getSvelteSSRCSSStats(): {
+    totalComponents: number;
+    globalComponents: number;
+    scopedComponents: number;
+    totalCSSSize: number;
+    averageCSSSize: number;
+    oldestTimestamp: number;
+    newestTimestamp: number;
+};
+/**
+ * Get CSS for specific component scope
+ */
+export declare function getSvelteComponentCSS(scopeId: string): string;
+/**
+ * Clear CSS for specific component scope
+ */
+export declare function clearSvelteComponentCSS(scopeId: string): boolean;
+/**
+ * Apply CSS scoping to selectors with advanced logic
+ * Enhanced version with better selector parsing and scoping rules
+ */
+export declare function applyCSSScoping(cssContent: string, scopeId: string): string;
+/**
+ * Apply scoping to a single CSS selector with comprehensive logic
+ */
+export declare function applySelectorScoping(selector: string, scopeId: string): string;
+/**
+ * Optimize component CSS by removing duplicates and applying minification
+ * Enhanced version with better deduplication and optimization strategies
+ */
+export declare function optimizeComponentCSS(css: string): string;
+/**
+ * Minify CSS for production builds
+ */
+export declare function minifyCSS(css: string): string;
+/**
+ * Generate consistent scope ID for any component framework
+ * Provides unified scoping across Vue, Svelte, and other frameworks
+ */
+export declare function generateComponentScopeId(src: string, framework?: string): string;
+/**
+ * Simple hash function for generating consistent short hashes
+ */
+export declare function simpleHash(str: string): string;
+export {};

package/dist/src/islands/discovery/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Island Discovery Module
+ *
+ * Exports all types and functions for discovering island components
+ * in nested directory structures.
+ */
+export type { IslandDirectory, DiscoveredIsland, IslandCollision, IslandChangeEvent, IslandFileExtension, IslandDiscoveryConfig, } from "./types.ts";
+export { ISLAND_FILE_EXTENSIONS, DEFAULT_DISCOVERY_CONFIG, isSupportedIslandExtension, } from "./types.ts";
+export { discoverIslandDirectories, discoverIslandsInDirectory, discoverAllIslands, isIslandsDirectory, getDefaultIslandsPath, hasDefaultIslandsDirectory, getQualifiedIslandName, parseQualifiedIslandName, } from "./scanner.ts";
+export { IslandRegistry, createIslandRegistry, } from "./registry.ts";
+export type { ResolutionResult, ImportPathOptions, } from "./resolver.ts";
+export { IslandResolver, createIslandResolver, } from "./resolver.ts";
+export type { ValidationResult, ValidationError, ValidationWarning, CircularDependency, } from "./validator.ts";
+export { IslandValidator, createIslandValidator, validateAllIslands, formatValidationError, formatValidationWarning, formatCircularDependency, formatValidationResult, } from "./validator.ts";
+export type { IslandChangeCallback, IslandWatcherOptions, } from "./watcher.ts";
+export { IslandWatcher, createIslandWatcher, } from "./watcher.ts";

package/dist/src/islands/discovery/registry.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Island Registry
+ *
+ * Central registry for all discovered islands with resolution capabilities.
+ * Handles registration, resolution by name/namespace, and collision detection.
+ */
+import type { DiscoveredIsland, IslandDirectory, IslandCollision, IslandDiscoveryConfig } from "./types.ts";
+/**
+ * Central registry for all discovered islands.
+ * Provides registration, resolution, and collision detection capabilities.
+ */
+export declare class IslandRegistry {
+    /** All discovered islands indexed by qualified name */
+    private _islands;
+    /** All discovered island directories */
+    private _directories;
+    /** Index of islands by name (for fast lookup) */
+    private _byName;
+    /** Detected collisions */
+    private _collisions;
+    /** Project root directory */
+    private _projectRoot;
+    /** Discovery configuration */
+    private _config;
+    constructor(projectRoot: string, config?: IslandDiscoveryConfig);
+    /**
+     * Get all discovered islands as a Map.
+     */
+    get islands(): Map<string, DiscoveredIsland>;
+    /**
+     * Get all discovered island directories.
+     */
+    get directories(): IslandDirectory[];
+    /**
+     * Get all detected collisions.
+     */
+    get collisions(): IslandCollision[];
+    /**
+     * Get the number of registered islands.
+     */
+    get size(): number;
+    /**
+     * Register a discovered island in the registry.
+     * Updates the name index and detects collisions.
+     *
+     * @param island - The island to register
+     */
+    register(island: DiscoveredIsland): void;
+    /**
+     * Resolve an island by name with optional namespace.
+     *
+     * Resolution priority:
+     * 1. Exact qualified name match (namespace/name)
+     * 2. Default islands directory (highest priority for unqualified names)
+     * 3. First match in alphabetical order by namespace
+     *
+     * @param name - Component name or qualified name (namespace/name)
+     * @param namespace - Optional namespace to narrow search
+     * @returns The resolved island or null if not found
+     */
+    resolve(name: string, namespace?: string): DiscoveredIsland | null;
+    /**
+     * Find all islands matching a name.
+     * Useful for collision detection and disambiguation.
+     *
+     * @param name - Component name to search for
+     * @returns Array of all islands with this name
+     */
+    findByName(name: string): DiscoveredIsland[];
+    /**
+     * Get the qualified name for an island.
+     *
+     * @param island - The island to get the qualified name for
+     * @returns The qualified name (namespace/name or just name for default)
+     */
+    getQualifiedName(island: DiscoveredIsland): string;
+    /**
+     * Check if an island with the given name or qualified name exists.
+     *
+     * @param nameOrQualified - Component name or qualified name
+     * @returns True if the island exists
+     */
+    has(nameOrQualified: string): boolean;
+    /**
+     * Detect naming collisions across all registered islands.
+     * A collision occurs when multiple islands share the same component name.
+     *
+     * @returns Array of detected collisions
+     */
+    detectCollisions(): IslandCollision[];
+    /**
+     * Clear the registry and rebuild from filesystem.
+     * Discovers all island directories and their components.
+     */
+    rebuild(): Promise<void>;
+    /**
+     * Get all islands as an array.
+     *
+     * @returns Array of all registered islands
+     */
+    getAllIslands(): DiscoveredIsland[];
+    /**
+     * Get islands from a specific directory.
+     *
+     * @param directory - The directory to get islands from
+     * @returns Array of islands in the directory
+     */
+    getIslandsInDirectory(directory: IslandDirectory): DiscoveredIsland[];
+    /**
+     * Get islands by namespace.
+     *
+     * @param namespace - The namespace to filter by (empty string for default)
+     * @returns Array of islands in the namespace
+     */
+    getIslandsByNamespace(namespace: string): DiscoveredIsland[];
+    /**
+     * Remove an island from the registry.
+     *
+     * @param qualifiedName - The qualified name of the island to remove
+     * @returns True if the island was removed
+     */
+    unregister(qualifiedName: string): boolean;
+    /**
+     * Create a snapshot of the registry state.
+     * Useful for debugging and testing.
+     */
+    toJSON(): {
+        islands: Record<string, DiscoveredIsland>;
+        directories: IslandDirectory[];
+        collisions: IslandCollision[];
+    };
+}
+/**
+ * Create and initialize an island registry.
+ * Convenience function that creates a registry and rebuilds it.
+ *
+ * @param projectRoot - The root directory of the project
+ * @param config - Optional configuration for discovery
+ * @returns Initialized island registry
+ */
+export declare function createIslandRegistry(projectRoot: string, config?: IslandDiscoveryConfig): Promise<IslandRegistry>;

package/dist/src/islands/discovery/resolver.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Island Resolver
+ *
+ * Handles runtime resolution of island references to actual file paths.
+ * Supports priority-based resolution with default /src/islands/ having highest priority.
+ *
+ * ## Resolution Order
+ *
+ * When resolving an island reference, the resolver follows this priority order:
+ *
+ * 1. **Explicit path-based references** (e.g., "src/modules/auth/islands/Counter")
+ *    - Full path to the island file
+ *    - Always unambiguous
+ *
+ * 2. **Qualified name matches** (e.g., "modules/auth/Counter")
+ *    - Namespace/name format
+ *    - Namespace is derived from directory path between src/ and islands/
+ *
+ * 3. **Default /src/islands/ directory**
+ *    - Highest priority for simple names (backward compatibility)
+ *    - If an island exists in both default and nested directories,
+ *      the default directory wins
+ *
+ * 4. **Nested directories in alphabetical order**
+ *    - When not found in default directory
+ *    - Sorted alphabetically by namespace
+ *
+ * ## Namespace Conventions
+ *
+ * - src/islands/Counter.tsx -> namespace: "", qualified: "Counter"
+ * - src/modules/auth/islands/LoginForm.tsx -> namespace: "modules/auth", qualified: "modules/auth/LoginForm"
+ * - src/features/checkout/islands/PaymentForm.tsx -> namespace: "features/checkout", qualified: "features/checkout/PaymentForm"
+ *
+ * ## Handling Collisions
+ *
+ * When multiple islands share the same name:
+ * - Use qualified names to disambiguate
+ * - The resolver returns `ambiguous: true` with alternatives
+ * - Default directory always has priority for simple name resolution
+ */
+import type { DiscoveredIsland } from "./types.ts";
+import type { IslandRegistry } from "./registry.ts";
+/**
+ * Result of resolving an island reference
+ */
+export interface ResolutionResult {
+    /** Resolved island */
+    island: DiscoveredIsland;
+    /** Import path for the island */
+    importPath: string;
+    /** Whether resolution was ambiguous (multiple matches found) */
+    ambiguous: boolean;
+    /** Alternative matches if ambiguous */
+    alternatives?: DiscoveredIsland[];
+}
+/**
+ * Options for import path generation
+ */
+export interface ImportPathOptions {
+    /** Whether generating for development (true) or production (false) */
+    isDevelopment?: boolean;
+    /** Base path for imports (e.g., "/@fs/" for dev, "/" for prod) */
+    basePath?: string;
+    /** Project root directory */
+    projectRoot?: string;
+    /** Whether to use absolute paths */
+    absolute?: boolean;
+}
+/**
+ * Island Resolver class
+ *
+ * Resolves island references to actual file paths with priority-based resolution.
+ * Default /src/islands/ directory has highest priority for backward compatibility.
+ */
+export declare class IslandResolver {
+    private _registry;
+    private _projectRoot;
+    constructor(registry: IslandRegistry, projectRoot: string);
+    /**
+     * Get the underlying registry
+     */
+    get registry(): IslandRegistry;
+    /**
+     * Get the project root
+     */
+    get projectRoot(): string;
+    /**
+     * Resolve an island reference to a file path.
+     *
+     * Resolution priority:
+     * 1. Explicit path-based reference (e.g., "modules/auth/Counter")
+     * 2. Qualified name match (namespace/name)
+     * 3. Default islands directory (highest priority for unqualified names)
+     * 4. First match in alphabetical order by namespace
+     *
+     * @param reference - Island reference (name, qualified name, or path)
+     * @returns Resolution result or null if not found
+     */
+    resolve(reference: string): ResolutionResult | null;
+    /**
+     * Normalize an island reference for consistent resolution.
+     */
+    private normalizeReference;
+    /**
+     * Resolve an explicit path-based reference.
+     * Handles references like "src/modules/auth/islands/Counter"
+     */
+    private resolveExplicitPath;
+    /**
+     * Resolve a qualified name (namespace/name).
+     */
+    private resolveQualifiedName;
+    /**
+     * Resolve by name with priority-based resolution.
+     * Default /src/islands/ has highest priority.
+     */
+    private resolveByName;
+    /**
+     * Generate an import path for an island.
+     * Handles both development and production paths.
+     *
+     * @param island - The island to generate an import path for
+     * @param options - Options for path generation
+     * @returns The import path string
+     */
+    generateImportPath(island: DiscoveredIsland, options?: ImportPathOptions): string;
+    /**
+     * Generate a qualified import path for disambiguation.
+     * Always includes the namespace for clarity.
+     *
+     * @param island - The island to generate a path for
+     * @returns Qualified import path
+     */
+    generateQualifiedImportPath(island: DiscoveredIsland): string;
+    /**
+     * Get the resolution order documentation.
+     * Describes how islands are resolved when multiple matches exist.
+     *
+     * @returns Array of resolution order descriptions
+     */
+    getResolutionOrder(): string[];
+    /**
+     * Check if a reference would resolve ambiguously.
+     *
+     * @param reference - Island reference to check
+     * @returns True if the reference matches multiple islands
+     */
+    isAmbiguous(reference: string): boolean;
+    /**
+     * Get all possible resolutions for a reference.
+     * Useful for providing suggestions when resolution is ambiguous.
+     *
+     * @param reference - Island reference
+     * @returns Array of all matching islands
+     */
+    getAllMatches(reference: string): DiscoveredIsland[];
+    /**
+     * Suggest qualified names for disambiguation.
+     *
+     * @param name - Component name with multiple matches
+     * @returns Array of qualified name suggestions
+     */
+    suggestQualifiedNames(name: string): string[];
+    /**
+     * Resolve an island and throw if not found.
+     *
+     * @param reference - Island reference
+     * @throws Error if island is not found
+     * @returns Resolution result
+     */
+    resolveOrThrow(reference: string): ResolutionResult;
+    /**
+     * Find similar island names for suggestions.
+     * Uses simple string similarity for fuzzy matching.
+     */
+    private findSimilarNames;
+    /**
+     * Calculate Levenshtein distance between two strings.
+     * Used for fuzzy name matching.
+     */
+    private levenshteinDistance;
+}
+/**
+ * Create an island resolver from a registry.
+ *
+ * @param registry - The island registry to use
+ * @param projectRoot - The project root directory
+ * @returns A new IslandResolver instance
+ */
+export declare function createIslandResolver(registry: IslandRegistry, projectRoot: string): IslandResolver;

package/dist/src/islands/discovery/scanner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Island Directory Scanner
+ *
+ * Recursively scans the source directory to discover all islands directories.
+ * Supports nested patterns like /src/modules/[module]/islands/.
+ */
+import type { IslandDirectory, IslandDiscoveryConfig, DiscoveredIsland } from "./types.ts";
+/**
+ * Discover all island directories within the source directory.
+ * Uses recursive scanning to find all directories named "islands".
+ *
+ * @param projectRoot - The root directory of the project
+ * @param config - Optional configuration for discovery
+ * @returns Array of discovered island directories
+ */
+export declare function discoverIslandDirectories(projectRoot: string, config?: IslandDiscoveryConfig): Promise<IslandDirectory[]>;
+/**
+ * Check if a directory is an islands directory.
+ */
+export declare function isIslandsDirectory(dirPath: string): boolean;
+/**
+ * Get the default islands directory path.
+ */
+export declare function getDefaultIslandsPath(projectRoot: string, rootDir?: string): string;
+/**
+ * Check if the default islands directory exists.
+ */
+export declare function hasDefaultIslandsDirectory(projectRoot: string, rootDir?: string): Promise<boolean>;
+/**
+ * Discover all island components within a specific islands directory.
+ *
+ * @param directory - The island directory to scan
+ * @param projectRoot - The root directory of the project
+ * @returns Array of discovered island components
+ */
+export declare function discoverIslandsInDirectory(directory: IslandDirectory, projectRoot: string): Promise<DiscoveredIsland[]>;
+/**
+ * Discover all islands across all directories.
+ *
+ * @param projectRoot - The root directory of the project
+ * @param config - Optional configuration for discovery
+ * @returns Array of all discovered island components
+ */
+export declare function discoverAllIslands(projectRoot: string, config?: IslandDiscoveryConfig): Promise<DiscoveredIsland[]>;
+/**
+ * Get the qualified name for an island (namespace/name or just name for default).
+ */
+export declare function getQualifiedIslandName(island: DiscoveredIsland): string;
+/**
+ * Parse a qualified island name into namespace and name parts.
+ */
+export declare function parseQualifiedIslandName(qualifiedName: string): {
+    namespace: string;
+    name: string;
+};

package/dist/src/islands/discovery/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Island Discovery Types
+ *
+ * Type definitions for the nested islands discovery system.
+ * Supports discovering island components in modular architectures
+ * like /src/modules/[module]/islands/ and arbitrary nesting patterns.
+ */
+import type { Framework } from "../types.ts";
+/**
+ * Represents a discovered islands directory
+ */
+export interface IslandDirectory {
+    /** Absolute path to the islands directory */
+    path: string;
+    /** Relative path from src/ (e.g., "modules/auth/islands") */
+    relativePath: string;
+    /** Namespace prefix for components (e.g., "modules/auth") */
+    namespace: string;
+    /** Whether this is the default /src/islands/ directory */
+    isDefault: boolean;
+}
+/**
+ * Represents a discovered island component
+ */
+export interface DiscoveredIsland {
+    /** Component name without extension */
+    name: string;
+    /** Full absolute path to the component file */
+    filePath: string;
+    /** Relative path from project root */
+    relativePath: string;
+    /** Namespace (empty string for default islands directory) */
+    namespace: string;
+    /** Detected framework */
+    framework: Framework;
+    /** File extension (e.g., ".tsx", ".vue", ".svelte") */
+    extension: string;
+    /** The directory this island belongs to */
+    directory: IslandDirectory;
+}
+/**
+ * Represents a naming collision between islands
+ */
+export interface IslandCollision {
+    /** Component name that has collisions */
+    name: string;
+    /** All islands with this name */
+    islands: DiscoveredIsland[];
+    /** Resolution strategy used */
+    resolution: "namespace" | "priority";
+}
+/**
+ * Event emitted when island files change
+ */
+export interface IslandChangeEvent {
+    /** Type of change */
+    type: "add" | "change" | "remove";
+    /** Affected island (null for remove events before discovery) */
+    island: DiscoveredIsland | null;
+    /** File path that changed */
+    filePath: string;
+    /** Timestamp of the change */
+    timestamp: number;
+}
+/**
+ * Supported file extensions for island components
+ */
+export declare const ISLAND_FILE_EXTENSIONS: readonly [".tsx", ".ts", ".jsx", ".js", ".vue", ".svelte"];
+export type IslandFileExtension = (typeof ISLAND_FILE_EXTENSIONS)[number];
+/**
+ * Check if a file extension is supported for islands
+ */
+export declare function isSupportedIslandExtension(ext: string): ext is IslandFileExtension;
+/**
+ * Configuration options for island discovery
+ */
+export interface IslandDiscoveryConfig {
+    /** Root directory to scan (defaults to "src") */
+    rootDir?: string;
+    /** Additional directories to scan (beyond default patterns) */
+    include?: string[];
+    /** Directories to exclude from scanning */
+    exclude?: string[];
+    /** Custom namespace mapping */
+    namespaces?: Record<string, string>;
+    /** Whether to fail on naming collisions */
+    strictCollisions?: boolean;
+}
+/**
+ * Default configuration for island discovery
+ */
+export declare const DEFAULT_DISCOVERY_CONFIG: Required<IslandDiscoveryConfig>;