polen 0.11.0-next.15 → 0.11.0-next.17

package/src/vite/plugins/examples.ts

@@ -0,0 +1,201 @@
+import type { Api } from '#api/$'
+import { Examples as ExamplesModule } from '#api/examples/$'
+import * as Catalog from '#api/examples/schemas/catalog'
+import { generateExampleTypes } from '#api/examples/type-generator'
+import { createTypeUsageIndex } from '#api/examples/type-usage-indexer'
+import { Diagnostic } from '#lib/diagnostic/$'
+import { ViteReactive } from '#lib/vite-reactive/$'
+import { type AssetReader, createAssetReader } from '#lib/vite-reactive/reactive-asset-plugin'
+import { ViteVirtual } from '#lib/vite-virtual'
+import { debugPolen } from '#singletons/debug'
+import { FileSystem } from '@effect/platform'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
+import { Str } from '@wollybeard/kit'
+import { Effect } from 'effect'
+import * as Path from 'node:path'
+import type * as Vite from 'vite'
+import { polenVirtual } from '../vi.js'
+
+// Virtual modules provided by this plugin
+export const viProjectExamples = polenVirtual([`project`, `examples`])
+
+export interface Options {
+  config: Api.Config.Config
+  // todo: get type ref via import from SOT
+  schemaReader: AssetReader<Api.Schema.InputSource.LoadedCatalog | null, any, any>
+  dependentVirtualModules?: ViteVirtual.Identifier.Identifier[]
+}
+
+export interface ProjectExamplesCatalog {
+  examples: ExamplesModule.Example.Example[]
+}
+
+/**
+ * Examples plugin with versioning support
+ */
+export const Examples = ({
+  config,
+  schemaReader,
+  dependentVirtualModules = [],
+}: Options): {
+  plugins: Vite.Plugin[]
+  reader: AssetReader<ExamplesModule.ScanResult, Error, FileSystem.FileSystem>
+} => {
+  const debug = debugPolen.sub(`vite-examples`)
+  const examplesDir = Path.join(config.paths.project.rootDir, 'examples')
+
+  // Track last generated example names to detect changes
+  let lastGeneratedExampleNames: string[] | null = null
+
+  const reader = createAssetReader<ExamplesModule.ScanResult, Error, FileSystem.FileSystem>(() => {
+    return Effect.gen(function*() {
+      const loadedCatalog = yield* schemaReader.read()
+
+      const scanExamplesResult = yield* ExamplesModule.scan({
+        dir: examplesDir,
+        schemaCatalog: loadedCatalog?.data as any ?? undefined,
+      })
+
+      // Generate TypeScript types if examples have changed
+      const currentExampleNames = scanExamplesResult.catalog.examples.map(e => e.name).sort()
+      const exampleNamesChanged = lastGeneratedExampleNames === null
+        || currentExampleNames.length !== lastGeneratedExampleNames.length
+        || currentExampleNames.some((id, i) => id !== lastGeneratedExampleNames![i])
+
+      if (exampleNamesChanged) {
+        debug(`Examples changed, regenerating types`)
+        yield* generateExampleTypes(scanExamplesResult.catalog, config.paths.project.rootDir)
+        lastGeneratedExampleNames = currentExampleNames
+      }
+
+      debug('Found examples', { count: scanExamplesResult.catalog.examples.length })
+      return scanExamplesResult
+    })
+  })
+
+  const scanExamples = async () => {
+    return await Effect.runPromise(
+      reader.read().pipe(Effect.provide(NodeFileSystem.layer)),
+    )
+  }
+
+  // Map diagnostic to its control configuration
+  const getControlForDiagnostic = (diagnostic: ExamplesModule.Diagnostic) => {
+    if (diagnostic.source === 'examples-scanner') {
+      switch (diagnostic.name) {
+        case 'unused-default':
+          return config.examples.diagnostics?.unusedVersions
+        case 'duplicate-content':
+          return config.examples.diagnostics?.duplicateContent
+        case 'missing-versions':
+          return config.examples.diagnostics?.missingVersions
+        case 'unknown-version':
+          // Always show errors for unknown versions (they are discarded from catalog)
+          return {
+            enabled: true,
+            dev: { severity: 'error' as const },
+            build: { severity: 'error' as const },
+          }
+      }
+    } else if (diagnostic.source === 'examples-validation') {
+      return config.examples.diagnostics?.validation
+    }
+    return undefined
+  }
+
+  // Apply DiagnosticControl filtering and report diagnostics
+  const reportDiagnostics = (
+    diagnostics: ExamplesModule.Diagnostic[],
+    phase: 'dev' | 'build' = 'dev',
+  ) => {
+    Diagnostic.filterAndReport(diagnostics, getControlForDiagnostic, phase)
+  }
+
+  const plugins = [
+    ViteReactive.ReactiveAssetPlugin({
+      name: 'examples',
+      reader,
+      filePatterns: {
+        watch: [examplesDir],
+        isRelevant: (file) => {
+          return file.includes(examplesDir) && (
+            file.endsWith('.graphql')
+            || file.endsWith('.gql')
+            || file.endsWith('index.md')
+            || file.endsWith('index.mdx')
+          )
+        },
+      },
+      dependentVirtualModules: [viProjectExamples, ...dependentVirtualModules],
+      hooks: {
+        async shouldFullReload() {
+          // Always trigger full reload for examples changes
+          return true
+        },
+        async onDiagnostics(data) {
+          // Report diagnostics with DiagnosticControl filtering
+          reportDiagnostics(data.diagnostics, 'dev')
+        },
+      },
+    }),
+    {
+      name: 'polen:examples-virtual',
+      ...ViteVirtual.IdentifiedLoader.toHooks(
+        {
+          identifier: viProjectExamples,
+          async loader() {
+            debug(`Loading viProjectExamples virtual module`)
+
+            const scanExamplesResult = await scanExamples()
+
+            reportDiagnostics(scanExamplesResult.diagnostics, 'dev')
+
+            // Generate type usage index if schemas are available
+            let catalogWithIndex = scanExamplesResult.catalog
+            const schemaReaderResult = await Effect.runPromise(
+              schemaReader.read().pipe(Effect.provide(NodeFileSystem.layer)) as any,
+            )
+            const schemasCatalog = (schemaReaderResult as any)?.data
+            if (schemasCatalog) {
+              const typeUsageIndex = createTypeUsageIndex(
+                scanExamplesResult.catalog.examples,
+                schemasCatalog,
+              )
+              // The index will be properly encoded by the Catalog schema
+              catalogWithIndex = {
+                ...scanExamplesResult.catalog,
+                typeUsageIndex: typeUsageIndex as any, // Will be encoded by Catalog.encode
+              }
+            }
+
+            // Generate the module code with both catalog and component exports
+            const s = Str.Builder()
+            s`import { Effect } from 'effect'`
+            s`import * as Catalog from '#api/examples/schemas/catalog'`
+
+            const indexFilePath = scanExamplesResult.catalog.index?.path
+            if (indexFilePath) {
+              s``
+              s`export { default as IndexComponent } from '${indexFilePath}'`
+            } else {
+              s``
+              s`export const IndexComponent = null`
+            }
+
+            // Encode the catalog to ensure HashMap and other Effect types are properly serialized
+            const encodedCatalog = Catalog.encodeSync(catalogWithIndex)
+
+            s``
+            s`const catalogData = ${JSON.stringify(encodedCatalog)}`
+            s``
+            s`export const examplesCatalog = Effect.runSync(Catalog.decode(catalogData))`
+
+            return s.render()
+          },
+        },
+      ),
+    },
+  ]
+
+  return { plugins, reader }
+}

package/src/vite/plugins/hooks.ts

@@ -0,0 +1,49 @@
+import { Api } from '#api/$'
+import { ViteVirtual } from '#lib/vite-virtual'
+import { polenVirtual } from '#vite/vi'
+import type * as Vite from 'vite'
+
+export const viProjectHooks = polenVirtual([`project`, `hooks`], { allowPluginProcessing: true })
+
+export interface Options {
+  config: Api.Config.Config
+}
+
+/**
+ * Hooks plugin that handles user-defined hooks from hooks.ts or hooks.tsx
+ */
+export const Hooks = ({ config }: Options): Vite.Plugin => {
+  return {
+    name: 'polen:hooks-virtual',
+    ...ViteVirtual.IdentifiedLoader.toHooks({
+      identifier: viProjectHooks,
+      async loader() {
+        const fs = await import('node:fs/promises')
+        const path = await import('node:path')
+
+        const hooksPathTs = path.join(config.paths.project.rootDir, 'hooks.ts')
+        const hooksPathTsx = path.join(config.paths.project.rootDir, 'hooks.tsx')
+
+        let hooksPath = null
+        try {
+          await fs.access(hooksPathTsx)
+          hooksPath = hooksPathTsx
+        } catch {
+          try {
+            await fs.access(hooksPathTs)
+            hooksPath = hooksPathTs
+          } catch {
+            // No hooks file found
+          }
+        }
+
+        if (!hooksPath) {
+          // Return an empty module if no hooks file exists
+          return `// No hooks file found`
+        }
+
+        return `export * from '${hooksPath}'`
+      },
+    }),
+  }
+}

package/src/vite/plugins/index.ts

@@ -1,7 +1,8 @@
 export { Branding } from './branding.js'
 export { Build } from './build.js'
 export { Core } from './core.js'
+export { Examples } from './examples.js'
 export { Main } from './main.js'
 export { Pages } from './pages.js'
-export { SchemaAssets } from './schema-assets.js'
+export { Schemas } from './schemas.js'
 export { Serve } from './serve.js'

package/src/vite/plugins/main.ts

@@ -1,4 +1,4 @@
-import type { Api } from '#api/index'
+import type { Api } from '#api/$'
 import type { Vite } from '#dep/vite/index'
 import { Manifest } from '#vite/plugins/manifest'
 import { vitePluginSsrCss } from '@hiogawa/vite-plugin-ssr-css'

package/src/vite/plugins/manifest.ts

@@ -1,4 +1,4 @@
-import type { Api } from '#api/index'
+import type { Api } from '#api/$'
 import { Vite } from '#dep/vite/index'
 import { ViteVirtual } from '#lib/vite-virtual'
 import { Path } from '@wollybeard/kit'

package/src/vite/plugins/navbar.ts

@@ -0,0 +1,102 @@
+import { Api } from '#api/$'
+import { createNavbar, type NavbarItem } from '#api/content/navbar'
+import { Catalog } from '#lib/catalog/$'
+import type { AssetReader } from '#lib/vite-reactive/reactive-asset-plugin'
+import { ViteVirtual } from '#lib/vite-virtual'
+import { debugPolen } from '#singletons/debug'
+import { polenVirtual } from '#vite/vi'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
+import { Effect } from 'effect'
+import type * as Vite from 'vite'
+
+export const viProjectNavbar = polenVirtual([`project`, `navbar`])
+
+export interface Options {
+  config: Api.Config.Config
+  schemaReader: AssetReader<Api.Schema.InputSource.LoadedCatalog | null, any, any>
+  examplesReader: AssetReader<any, any, any>
+  pagesReader: AssetReader<any, any, any>
+}
+
+/**
+ * Navbar plugin that generates the navigation structure based on available content
+ */
+export const Navbar = ({
+  config,
+  schemaReader,
+  examplesReader,
+  pagesReader,
+}: Options): Vite.Plugin => {
+  return {
+    name: 'polen:navbar-virtual',
+    ...ViteVirtual.IdentifiedLoader.toHooks(
+      {
+        identifier: viProjectNavbar,
+        async loader() {
+          const debug = debugPolen.sub(`module-project-navbar`)
+          debug(`load`, { id: viProjectNavbar.id })
+
+          const navbar: NavbarItem[] = []
+
+          // ━ Schema presence causes adding some navbar items
+          const loadedSchemaCatalog = await Effect.runPromise(
+            schemaReader.read().pipe(Effect.provide(NodeFileSystem.layer)) as Effect.Effect<
+              Api.Schema.InputSource.LoadedCatalog | null,
+              never
+            >,
+          )
+
+          if (loadedSchemaCatalog?.data) {
+            // IMPORTANT: Always ensure paths start with '/' for React Router compatibility.
+            // Without the leading slash, React Router treats paths as relative, which causes
+            // hydration mismatches between SSR (where base path is prepended) and client
+            // (where basename is configured). This ensures consistent behavior.
+            const referencePath = Api.Schema.Routing.createReferenceBasePath()
+            navbar.push({ pathExp: referencePath, title: `Reference`, position: 'right' })
+
+            // Check if we have revisions to show changelog
+            const catalog = loadedSchemaCatalog.data
+            const hasMultipleRevisions = Catalog.fold(
+              (versioned) => {
+                // For versioned catalogs, count total revisions across all entries
+                const totalRevisions = Catalog.Versioned.getAll(versioned).reduce(
+                  (sum: number, entry) => sum + entry.revisions.length,
+                  0,
+                )
+                return totalRevisions > 1
+              },
+              (unversioned) => unversioned.schema.revisions?.length > 1,
+            )(catalog)
+
+            if (hasMultipleRevisions) {
+              navbar.push({ pathExp: `/changelog`, title: `Changelog`, position: 'right' })
+            }
+          }
+
+          // ━ Examples presence causes adding navbar item
+          const loadedExamplesCatalog = await Effect.runPromise(
+            examplesReader.read().pipe(Effect.provide(NodeFileSystem.layer)) as Effect.Effect<any, never>,
+          )
+
+          // Use config.examples.enabled if explicitly set, otherwise auto-detect
+          const examplesEnabled = config.examples.enabled
+            ?? (loadedExamplesCatalog.catalog.examples.length > 0)
+
+          if (examplesEnabled) {
+            navbar.push({ pathExp: '/examples', title: 'Examples', position: 'right' })
+          }
+
+          // ━━ Scan pages and add to navbar
+          const scanResult = await Effect.runPromise(
+            pagesReader.read().pipe(Effect.provide(NodeFileSystem.layer)) as Effect.Effect<any, never>,
+          )
+          const data = createNavbar(scanResult.list)
+          navbar.push(...data)
+
+          // Return a JavaScript module that exports the navbar
+          return `export const navbar = ${JSON.stringify(navbar)}`
+        },
+      },
+    ),
+  }
+}

package/src/vite/plugins/pages.ts

@@ -1,28 +1,27 @@
+import type { Api } from '#api/$'
 import { Content } from '#api/content/$'
-import type { Api } from '#api/index'
 import type { Vite } from '#dep/vite/index'
+import { Diagnostic } from '#lib/diagnostic/$'
 import { FileRouter } from '#lib/file-router'
-import { reportDiagnostics } from '#lib/file-router/diagnostic-reporter'
+import { ViteReactive } from '#lib/vite-reactive/$'
+import { createAssetReader } from '#lib/vite-reactive/reactive-asset-plugin'
+import type { ViteVirtual } from '#lib/vite-virtual/$'
 import { debugPolen } from '#singletons/debug'
 import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
 import mdx from '@mdx-js/rollup'
-import { Arr, Cache, Path, Str } from '@wollybeard/kit'
-import { recmaCodeHike, remarkCodeHike } from 'codehike/mdx'
+import { Arr, Path, Str } from '@wollybeard/kit'
 import { Effect } from 'effect'
-import remarkFrontmatter from 'remark-frontmatter'
-import remarkGfm from 'remark-gfm'
 import { polenVirtual } from '../vi.js'
-import { viProjectData } from './core.js'
-
-const debug = debugPolen.sub(`vite-pages`)
 
 export const viProjectRoutes = polenVirtual([`project`, `routes.jsx`], { allowPluginProcessing: true })
-export const viProjectPagesCatalog = polenVirtual([`project`, `data`, `pages-catalog.json`], {
+
+export const viProjectPages = polenVirtual([`project`, `pages`], {
   allowPluginProcessing: true,
 })
 
 export interface Options {
   config: Api.Config.Config
+  dependentVirtualModules?: ViteVirtual.Identifier.Identifier[]
 }
 
 export interface ProjectPagesCatalog {
@@ -35,38 +34,14 @@ export interface ProjectPagesCatalog {
  */
 export const Pages = ({
   config,
-}: Options): Vite.Plugin[] => {
-  const scanPages = Cache.memoize(debug.trace(async function scanPages() {
-    const result = await Effect.runPromise(
-      Content.scan({
-        dir: config.paths.project.absolute.pages,
-        glob: `**/*.{md,mdx}`,
-      }).pipe(
-        Effect.provide(NodeFileSystem.layer),
-      ),
-    )
-    return result
-  }))
-
-  const invalidateVirtualModules = (server: Vite.ViteDevServer) => {
-    const routesModule = server.moduleGraph.getModuleById(viProjectRoutes.id)
-    if (routesModule) {
-      server.moduleGraph.invalidateModule(routesModule)
-      debug(`Invalidated routes virtual module`)
-    }
-
-    const catalogModule = server.moduleGraph.getModuleById(viProjectPagesCatalog.id)
-    if (catalogModule) {
-      server.moduleGraph.invalidateModule(catalogModule)
-      debug(`Invalidated pages catalog virtual module`)
-    }
-
-    const projectDataModule = server.moduleGraph.getModuleById(viProjectData.id)
-    if (projectDataModule) {
-      server.moduleGraph.invalidateModule(projectDataModule)
-      debug(`Invalidated project data virtual module`)
-    }
-  }
+  dependentVirtualModules = [],
+}: Options) => {
+  const debug = debugPolen.sub(`vite-pages`)
+  const reader = createAssetReader(() =>
+    Content.scan({
+      dir: config.paths.project.absolute.pages,
+    })
+  )
 
   const generateRoutesModule = (pages: Content.Page[]): string => {
     const $ = {
@@ -99,128 +74,65 @@ export const Pages = ({
     return s.render()
   }
 
-  const chConfig = {
-    components: { code: 'CodeBlock' },
-    syntaxHighlighting: {
-      theme: `github-light`,
-    },
-  }
-
-  return [
+  const plugins: Vite.Plugin[] = [
     // Plugin 1: MDX Processing
     {
-      enforce: `pre`,
-      ...mdx({
-        jsxImportSource: `polen/react`,
-        providerImportSource: `polen/mdx`,
-        remarkPlugins: [
-          // Parse frontmatter blocks so they're removed from content
-          remarkFrontmatter,
-          remarkGfm,
-          [remarkCodeHike, chConfig],
-        ],
-        recmaPlugins: [
-          [recmaCodeHike, chConfig],
-        ],
-        rehypePlugins: [],
-      }),
+      enforce: `pre` as const,
+      ...mdx(Content.getMdxRollupConfig()),
     },
 
-    // Plugin 2: Pages Management
-    {
-      name: `polen:pages`,
-
-      // Dev server configuration
-      configureServer(server) {
-        // Add pages directory to watcher
-        debug(`configureServer: watch pages directory`, config.paths.project.absolute.pages)
-        server.watcher.add(config.paths.project.absolute.pages)
-
-        // Handle file additions and deletions
-        const handleFileStructureChange = async (file: string, event: `add` | `unlink`) => {
-          if (!Content.isPageFile(file, config.paths.project.absolute.pages)) return
-
-          debug(`Page file ${event === `add` ? `added` : `deleted`}:`, file)
-
-          // Clear cache and rescan
-          scanPages.clear()
-          const newScanResult = await scanPages()
-
-          // Invalidate virtual modules
-          invalidateVirtualModules(server)
-
-          // Report any diagnostics
-          reportDiagnostics(newScanResult.diagnostics)
-
-          // Trigger full reload to ensure routes are updated
-          server.ws.send({ type: `full-reload` })
-        }
-
-        server.watcher.on(`add`, (file) => handleFileStructureChange(file, `add`))
-        server.watcher.on(`unlink`, (file) => handleFileStructureChange(file, `unlink`))
+    // Plugin 2: Reactive Pages Management
+    ViteReactive.ReactiveAssetPlugin({
+      name: 'pages',
+      reader,
+      filePatterns: {
+        watch: [config.paths.project.absolute.pages],
+        isRelevant: (file) => Content.isPageFile(file, config.paths.project.absolute.pages),
       },
-
-      // Hot update handling for existing files
-      async handleHotUpdate({ file, server, modules }) {
-        debug(`handleHotUpdate`, file)
-        if (!Content.isPageFile(file, config.paths.project.absolute.pages)) return
-
-        debug(`Page file changed:`, file)
-
-        // Get current pages before clearing cache
-        const oldPages = await scanPages()
-
-        // Clear cache and rescan
-        scanPages.clear()
-        const newScanResult = await scanPages()
-
-        // Check if the visible pages list changed. This can happen when:
-        // - A page's frontmatter `hidden` field changes (true <-> false)
-        // - A page's frontmatter affects its route (though we don't support this yet)
-        // If only the content changed (not frontmatter), we can use fast HMR.
-        const pageStructureChanged = !oldPages || !Arr.equalShallowly(
-          oldPages.list.map(p => Path.format(p.route.file.path.absolute)),
-          newScanResult.list.map(p => Path.format(p.route.file.path.absolute)),
-        )
-
-        if (!pageStructureChanged) {
-          debug(`Page content changed, allowing HMR`)
-          // Let default HMR handle the MDX file change
-          return modules
-        }
-
-        //
-        // ━━ Manual Invalidation
-        //
-
-        debug(`Page structure changed, triggering full reload`)
-
-        // Invalidate virtual modules and trigger reload
-        invalidateVirtualModules(server)
-        reportDiagnostics(newScanResult.diagnostics)
-        server.ws.send({ type: `full-reload` })
-        return []
+      dependentVirtualModules: [
+        viProjectPages,
+        ...dependentVirtualModules,
+      ],
+      hooks: {
+        async shouldFullReload(oldData, newData) {
+          // Check if the visible pages list changed
+          const pageStructureChanged = !oldData || !Arr.equalShallowly(
+            oldData.list.map(p => Path.format(p.route.file.path.absolute)),
+            newData.list.map(p => Path.format(p.route.file.path.absolute)),
+          )
+          // Return true for full reload only if structure changed
+          return pageStructureChanged
+        },
+        async onDiagnostics(data) {
+          Diagnostic.report(data.diagnostics)
+        },
       },
-      resolveId(id) {
-        if (id === viProjectPagesCatalog.id) {
-          return viProjectPagesCatalog.resolved
+    }),
+
+    // Plugin 3: Pages Virtual Module
+    {
+      name: `polen:pages-virtual`,
+      resolveId(id: string) {
+        if (id === viProjectPages.id) {
+          return viProjectPages.resolved
         }
       },
       load: {
-        async handler(id) {
-          if (id !== viProjectPagesCatalog.resolved) return
+        async handler(id: string) {
+          if (id !== viProjectPages.resolved) return
           debug(`hook load`)
 
-          const scanResult = await scanPages()
-
-          reportDiagnostics(scanResult.diagnostics)
-          debug(`found visible`, { count: scanResult.list.length })
+          const loadedPages = await Effect.runPromise(
+            reader.read().pipe(Effect.provide(NodeFileSystem.layer)),
+          )
+          Diagnostic.report(loadedPages.diagnostics)
+          debug(`found visible`, { count: loadedPages.list.length })
 
           //
           // ━━ Build Sidebar
           //
 
-          const sidebarIndex = Content.buildSidebarIndex(scanResult)
+          const sidebarIndex = Content.buildSidebarIndex(loadedPages)
 
           //
           // ━━ Put It All together
@@ -228,30 +140,31 @@ export const Pages = ({
 
           const projectPagesCatalog: ProjectPagesCatalog = {
             sidebarIndex,
-            pages: scanResult.list,
+            pages: loadedPages.list,
           }
 
-          // Return a JavaScript module that exports the data
-          return `export default ${JSON.stringify(projectPagesCatalog)}`
+          return `export const pagesCatalog = ${JSON.stringify(projectPagesCatalog)}`
         },
       },
     },
     // Plugin 3: Virtual Module for React Router Routes
     {
       name: `polen:routes`,
-      resolveId(id) {
+      resolveId(id: string) {
         if (id === viProjectRoutes.id) {
           return viProjectRoutes.resolved
         }
       },
       load: {
-        handler: async (id) => {
+        handler: async (id: string) => {
           if (id !== viProjectRoutes.resolved) return
 
           debug(`Loading viProjectRoutes virtual module`)
 
-          const scanResult = await scanPages()
-          reportDiagnostics(scanResult.diagnostics)
+          const scanResult = await Effect.runPromise(
+            reader.read().pipe(Effect.provide(NodeFileSystem.layer)),
+          )
+          Diagnostic.report(scanResult.diagnostics)
           const code = generateRoutesModule(scanResult.list)
 
           // Generate the module code
@@ -263,4 +176,6 @@ export const Pages = ({
       },
     },
   ]
+
+  return { plugins, reader }
 }