@openelement/ssg 0.41.0-alpha.1

package/src/route-scanner.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @openelement/core - Route scanner
+ * Scans the routes directory and generates a route map.
+ * Produces the virtual:routes module.
+ *
+ * Phase 1 enhancement: support for _renderer.ts (layout) and
+ * _middleware.ts (Hono middleware) special files.
+ *
+ * Phase 2 enhancement: support for package islands auto-detection.
+ * Packages can export an `islands` array in their main entry.
+ *
+ * Convention (minimal augmentation):
+ * - _renderer.ts: exports a renderer that wraps route VNodes
+ * - _middleware.ts: exports a Hono middleware function applied before the route
+ * - Files starting with _ are not route handlers but are loaded by the framework
+ *
+ * ─── SSR Import Discovery Audit (Step1) ─────────────────────
+ *
+ * This file discovers islands but does NOT import them (static scan only):
+ *
+ * 1. Local island files:
+ *    - Scanned by `scanIslands()`
+ *    - Metadata read by `scanIslandMeta()` (static, no import)
+ *    - SSR decision: `openElement.ssr` field (static read, no import)
+ *
+ * 2. Package manifest islands:
+ *    - Discovered by `scanPackageManifests()`
+ *    - Imports package module to read `manifest` export
+ *    - Browser-only packages: caught by try/catch
+ *    - SSR decision: `manifest.declarations[].openElement.ssr` field
+ *
+ * 3. CEM manifests (v0.18.0):
+ *    - Discovered by `scanCemManifests()` - reads custom-elements.json from
+ *      node_modules packages WITHOUT importing package code
+ *    - Results fed into the compatibility classifier (parseCem + classifyCemManifest)
+ *
+ * 4. Nested custom elements (from the VNode tree):
+ *    - NOT handled in this file
+ *    - See: `packages/core/src/jsx-render-string.ts` and `renderDsdTree()`
+ *
+ * Audit completed: 2026-05-17
+ * Auditor: AI agent (openElement v0.17.4 SOP compliance check)
+ *
+ * ─── v0.41.0-alpha.1: AST removed ────────────────────────────
+ *
+ * Replaced TypeScript AST scanning with regex/glob-based extraction.
+ * Route and island modules are simple ESM files; parsing the whole source
+ * with the TypeScript compiler is overkill and adds a heavy dependency.
+ */ import type { CompatibilityClassification, RouteEntry } from '@openelement/protocol/framework';
+import type { OpenElementPackageManifest } from '@openelement/protocol/manifest';
+/** Local island metadata indexed by tag name. */ export interface LocalIslandMeta {
+  tagName: string;
+  filePath: string;
+  ssr?: boolean;
+  dsd?: boolean;
+  hydrate?: 'load' | 'idle' | 'visible' | 'only';
+  reason?: string;
+}
+/**
+ * Recursively scan a directory for route files.
+ * Also collects _renderer.ts and _middleware.ts special files.
+ */ export declare function scanRoutes(routesDir: string, baseDir?: string): Promise<RouteEntry[]>;
+/**
+ * v0.25: AST-verified — converts file name to a valid Custom Element tag name.
+ * Uses regex for path manipulation since tag names are derived from file paths.
+ *
+ * Examples:
+ *   'my-counter.ts'        -> 'my-counter'
+ *   'posts/index.ts'       -> 'posts-index'
+ *   'admin\\dashboard.ts'  -> 'admin-dashboard'
+ */ export declare function fileToTagName(fileName: string): string;
+/**
+ * Scan islands directory recursively for island files.
+ * Returns paths relative to islandsDir (e.g., ['my-counter.ts', 'posts/index.ts']).
+ */ export declare function scanIslands(islandsDir: string, relativeDir?: string): Promise<string[]>;
+/**
+ * v0.41.0-alpha.1: Regex-based — reads island metadata by statically scanning the module
+ * source for `export const openElement = defineIslandConfig({ ... })`.
+ *
+ * Supported form:
+ *   export const openElement = defineIslandConfig({ ssr: false, dsd: false, hydrate: 'only' })
+ *
+ * This is more reliable than regex because it handles:
+ * - Comments inside the object literal
+ * - Computed properties
+ * - Destructured/re-exported values
+ * - Canonical defineIslandConfig(...) calls
+ *
+ * If a module cannot be read, its metadata is silently skipped.
+ */ export declare function scanIslandMeta(islandsDir: string, islandFiles: string[]): Promise<Record<string, LocalIslandMeta>>;
+/**
+ * Scan package exports for OpenElementPackageManifest.
+ * Packages should export a `manifest` OpenElementPackageManifest in their main entry.
+ *
+ * Example package export:
+ * ```ts
+ * // @openelement/ui/index.ts
+ * export { manifest } from './manifest.js';
+ * ```
+ *
+ * @param packageNames - List of package names to scan (e.g., ['@openelement/ui'])
+ * @returns Array of OpenElementPackageManifest
+ */ export declare function scanPackageManifests(packageNames: string[]): Promise<OpenElementPackageManifest[]>;
+/** Result of scanning node_modules for CEM manifests */ export interface CemScanResult {
+  /** Package name (e.g. '@openelement/ui') */ packageName: string;
+  /** Absolute path to custom-elements.json */ cemPath: string;
+  /** Raw JSON content */ json: string;
+}
+/**
+ * Scan node_modules for packages that ship a `custom-elements.json`.
+ *
+ * Strategy:
+ *   1. Read node_modules directory entries (top-level packages + scoped orgs)
+ *   2. For each package, check if `<pkg>/custom-elements.json` exists
+ *   3. Return the raw JSON - caller is responsible for parsing + classifying
+ *
+ * This function reads files only. It never imports or executes package code.
+ *
+ * @param nodeModulesDir - Absolute path to the node_modules directory
+ * @returns Array of found CEM manifests
+ */ export declare function scanCemManifests(nodeModulesDir: string): Promise<CemScanResult[]>;
+/**
+ * Run CEM auto-detection: scan node_modules, parse each manifest,
+ * and classify all discovered components.
+ *
+ * This is the high-level function called from the Vite plugin buildStart().
+ * It combines scanCemManifests() + parseCem() + classifyCemManifest()
+ * into a single pipeline.
+ *
+ * @param nodeModulesDir - Absolute path to node_modules
+ * @returns Array of compatibility classifications (may be empty if no CEM found)
+ */ export declare function detectAndClassifyCemPackages(nodeModulesDir: string): Promise<CompatibilityClassification[]>;