polen 0.11.0-next.2 → 0.11.0-next.20

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

@@ -0,0 +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 { Schemas } from './schemas.js'
+export { Serve } from './serve.js'

package/src/vite/plugins/main.ts

@@ -0,0 +1,42 @@
+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'
+import ViteReact from '@vitejs/plugin-react-oxc'
+import { Path } from '@wollybeard/kit'
+import Inspect from 'vite-plugin-inspect'
+import { Branding } from './branding.js'
+import { Build } from './build.js'
+import { Core } from './core.js'
+import { Serve } from './serve.js'
+
+export const Main = (
+  config: Api.Config.Config,
+): Vite.PluginOption => {
+  const plugins: Vite.PluginOption = []
+
+  // Optional Plugins based on config
+
+  if (config.advanced.explorer) {
+    const outputDir = Path.join(config.paths.project.rootDir, `.bundle-explorer`)
+    const plugin = Inspect({
+      build: true,
+      outputDir,
+    })
+    plugins.push(plugin)
+  }
+
+  plugins.push(
+    ViteReact(),
+    vitePluginSsrCss({
+      entries: [`/${config.paths.framework.template.relative.client.entrypoint}`],
+    }),
+    Branding(config),
+    Manifest(config),
+    Serve(config),
+    Core(config),
+    Build(config),
+  )
+
+  return plugins
+}

package/src/vite/plugins/manifest.ts

@@ -0,0 +1,36 @@
+import type { Api } from '#api/$'
+import { Vite } from '#dep/vite/index'
+import { ViteVirtual } from '#lib/vite-virtual'
+import { Path } from '@wollybeard/kit'
+import { polenVirtual } from '../vi.js'
+
+const viClientManifest = polenVirtual([`vite`, `client`, `manifest`])
+
+export const Manifest = (config: Api.Config.Config): Vite.Plugin => {
+  let configEnv: Vite.ConfigEnv
+
+  return {
+    name: `polen-manifest`,
+    config(_, configEnv_) {
+      configEnv = configEnv_
+    },
+    ...ViteVirtual.IdentifiedLoader.toHooks(
+      {
+        identifier: viClientManifest,
+        loader: async () => {
+          // In development just return an empty manifest
+          if (configEnv.mode === Vite.ModeName.development) {
+            return `export default {}`
+          }
+
+          const manifestPath = Path.join(config.paths.project.absolute.build.root, `.vite`, `manifest.json`)
+          const module = await import(manifestPath, { with: { type: `json` } }) as {
+            default: Vite.Manifest
+          }
+
+          return `export default ${JSON.stringify(module.default)}`
+        },
+      },
+    ),
+  }
+}

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

@@ -0,0 +1,181 @@
+import type { Api } from '#api/$'
+import { Content } from '#api/content/$'
+import type { Vite } from '#dep/vite/index'
+import { Diagnostic } from '#lib/diagnostic/$'
+import { FileRouter } from '#lib/file-router'
+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, Path, Str } from '@wollybeard/kit'
+import { Effect } from 'effect'
+import { polenVirtual } from '../vi.js'
+
+export const viProjectRoutes = polenVirtual([`project`, `routes.jsx`], { allowPluginProcessing: true })
+
+export const viProjectPages = polenVirtual([`project`, `pages`], {
+  allowPluginProcessing: true,
+})
+
+export interface Options {
+  config: Api.Config.Config
+  dependentVirtualModules?: ViteVirtual.Identifier.Identifier[]
+}
+
+export interface ProjectPagesCatalog {
+  sidebarIndex: Content.SidebarIndex
+  pages: Content.Page[]
+}
+
+/**
+ * Pages plugin with tree support
+ */
+export const Pages = ({
+  config,
+  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 $ = {
+      routes: `routes`,
+    }
+
+    const s = Str.Builder()
+    s`export const ${$.routes} = []`
+
+    // Generate imports and route objects
+    for (const { route, metadata } of pages) {
+      const filePathExp = Path.format(route.file.path.absolute)
+      const pathExp = FileRouter.routeToPathExpression(route)
+      const $$ = {
+        ...$,
+        Component: Str.Case.camel(`page ` + Str.titlizeSlug(pathExp)),
+      }
+
+      s`
+        import ${$$.Component} from '${filePathExp}'
+
+        ${$$.routes}.push({
+          path: '${pathExp}',
+          Component: ${$$.Component},
+          metadata: ${JSON.stringify(metadata)}
+        })
+      `
+    }
+
+    return s.render()
+  }
+
+  const plugins: Vite.Plugin[] = [
+    // Plugin 1: MDX Processing
+    {
+      enforce: `pre` as const,
+      ...mdx(Content.getMdxRollupConfig()),
+    },
+
+    // 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),
+      },
+      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)
+        },
+      },
+    }),
+
+    // Plugin 3: Pages Virtual Module
+    {
+      name: `polen:pages-virtual`,
+      resolveId(id: string) {
+        if (id === viProjectPages.id) {
+          return viProjectPages.resolved
+        }
+      },
+      load: {
+        async handler(id: string) {
+          if (id !== viProjectPages.resolved) return
+          debug(`hook load`)
+
+          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(loadedPages)
+
+          //
+          // ━━ Put It All together
+          //
+
+          const projectPagesCatalog: ProjectPagesCatalog = {
+            sidebarIndex,
+            pages: loadedPages.list,
+          }
+
+          return `export const pagesCatalog = ${JSON.stringify(projectPagesCatalog)}`
+        },
+      },
+    },
+    // Plugin 3: Virtual Module for React Router Routes
+    {
+      name: `polen:routes`,
+      resolveId(id: string) {
+        if (id === viProjectRoutes.id) {
+          return viProjectRoutes.resolved
+        }
+      },
+      load: {
+        handler: async (id: string) => {
+          if (id !== viProjectRoutes.resolved) return
+
+          debug(`Loading viProjectRoutes virtual module`)
+
+          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
+          return {
+            code,
+            moduleType: `js`,
+          }
+        },
+      },
+    },
+  ]
+
+  return { plugins, reader }
+}