polen 0.10.0-next.13 → 0.10.0-next.15

package/src/api/config/configurator.ts

@@ -3,8 +3,8 @@ import { assertPathAbsolute } from '#lib/kit-temp'
 import { type PackagePaths, packagePaths } from '#package-paths'
 import { Path } from '@wollybeard/kit'
 import { z } from 'zod'
-import type { SchemaAugmentation } from '../../api/schema-augmentation/index.ts'
-import type { Schema } from '../schema/index.ts'
+import type { SchemaAugmentation } from '../../api/schema-augmentation/index.js'
+import type { Schema } from '../schema/index.js'
 
 export const BuildArchitectureEnum = {
   ssg: `ssg`,
@@ -18,6 +18,11 @@ export type BuildArchitecture = typeof BuildArchitectureEnum[keyof typeof BuildA
 
 type SchemaConfigInput = Omit<Schema.Config, `projectRoot`>
 
+/**
+ * Polen configuration input.
+ *
+ * All options are optional. Polen provides sensible defaults for a great developer experience out of the box.
+ */
 export interface ConfigInput {
   /**
    * Path to the root directory of your project.
@@ -28,13 +33,52 @@ export interface ConfigInput {
    */
   root?: string
   /**
-   * Enable a special module explorer for the source code that Polen assembles for your app.
+   * Configuration for how Polen loads your GraphQL schema.
    *
-   * Powered by [Vite Inspect](https://github.com/antfu-collective/vite-plugin-inspect).
+   * Polen supports multiple schema sources:
+   * - `file` - Load from a single SDL file (default: schema.graphql)
+   * - `directory` - Load multiple SDL files with date prefixes (enables changelog)
+   * - `memory` - Define schemas programmatically in configuration
    *
-   * @default true
+   * @example
+   * ```ts
+   * // Single file
+   * schema: {
+   *   useDataSources: 'file',
+   *   dataSources: {
+   *     file: { path: './my-schema.graphql' }
+   *   }
+   * }
+   *
+   * // Multiple versions for changelog
+   * schema: {
+   *   useDataSources: 'directory',
+   *   dataSources: {
+   *     directory: { path: './schema' }
+   *   }
+   * }
+   * ```
    */
   schema?: SchemaConfigInput
+  /**
+   * Programmatically add descriptions and metadata to your GraphQL schema.
+   *
+   * Use this to enhance your schema documentation without modifying the SDL files.
+   *
+   * @example
+   * ```ts
+   * schemaAugmentations: [{
+   *   Query: {
+   *     description: 'The root query type',
+   *     fields: {
+   *       users: {
+   *         description: 'Get a list of all users'
+   *       }
+   *     }
+   *   }
+   * }]
+   * ```
+   */
   schemaAugmentations?: SchemaAugmentation.Augmentation[]
   templateVariables?: {
     /**
@@ -46,17 +90,36 @@ export interface ConfigInput {
      */
     title?: string
   }
+  /**
+   * Build configuration for your developer portal.
+   */
   build?: {
+    /**
+     * The build architecture for your developer portal.
+     *
+     * - `ssg` - Static Site Generation: Pre-renders all pages at build time. Best for public docs.
+     * - `ssr` - Server-Side Rendering: Renders pages on each request. Enables dynamic features.
+     * - `spa` - Single Page Application: Client-side rendering only.
+     *
+     * @default 'ssg'
+     */
     architecture?: BuildArchitecture
     /**
      * Base public path for the deployed site.
      *
      * Use this when deploying to a subdirectory (e.g., GitHub Pages project sites).
      *
-     * Examples:
-     * - `/` (default) - Deploy to root
-     * - `/my-project/` - Deploy to subdirectory
-     * - `/pr-123/` - PR preview deployments
+     * @example
+     * ```ts
+     * // Deploy to root
+     * base: '/'
+     *
+     * // Deploy to subdirectory
+     * base: '/my-project/'
+     *
+     * // PR preview deployments
+     * base: '/pr-123/'
+     * ```
      *
      * Must start and end with `/`.
      *
@@ -64,7 +127,24 @@ export interface ConfigInput {
      */
     base?: string
   }
+  /**
+   * Advanced configuration options.
+   *
+   * These settings are for advanced use cases and debugging.
+   */
   advanced?: {
+    /**
+     * Enable a special module explorer for the source code that Polen assembles for your app.
+     *
+     * This opens an interactive UI to inspect the module graph and transformations.
+     * Useful for debugging build issues or understanding Polen's internals.
+     *
+     * Access the explorer at `/__inspect/` when running the dev server.
+     *
+     * Powered by [Vite Inspect](https://github.com/antfu-collective/vite-plugin-inspect).
+     *
+     * @default false
+     */
     explorer?: boolean
     /**
      * Force the CLI to resolve Polen imports in your project to itself rather than
@@ -144,20 +224,20 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
         },
         pages: `pages`,
         public: {
-          root: 'public',
-          logo: 'logo.svg',
+          root: `public`,
+          logo: `logo.svg`,
         },
       },
       absolute: {
         pages: rootAbsolute(`pages`),
         build: {
-          root: buildAbsolute('.'),
+          root: buildAbsolute(`.`),
           serverEntrypoint: buildAbsolute(`app.js`),
           assets: buildAbsolute(`assets`),
         },
         public: {
-          root: publicAbsolute('.'),
-          logo: publicAbsolute('logo.svg'),
+          root: publicAbsolute(`.`),
+          logo: publicAbsolute(`logo.svg`),
         },
       },
     },
@@ -256,7 +336,6 @@ export const normalizeInput = async (
    * If this is omitted, then relative root paths will throw an error.
    */
   baseRootDirPath: string,
-  // eslint-disable-next-line
 ): Promise<Config> => {
   assertPathAbsolute(baseRootDirPath)
 

package/src/api/config/define.ts

@@ -1,5 +1,5 @@
 import { Fn } from '@wollybeard/kit'
-import type { ConfigInput } from './configurator.ts'
+import type { ConfigInput } from './configurator.js'
 
 /**
  * Define a Polen configuration.

package/src/api/config/index.ts

@@ -1 +1 @@
-export * as Config from './config.ts'
+export * as Config from './config.js'

package/src/api/config/load.ts

@@ -5,7 +5,7 @@ import { debugPolen } from '#singletons/debug'
 import type { Prom } from '@wollybeard/kit'
 import { Path } from '@wollybeard/kit'
 import * as Module from 'node:module'
-import type { ConfigInput } from './configurator.ts'
+import type { ConfigInput } from './configurator.js'
 
 export const fileNameBases = [`polen.config`, `.polen.config`]
 export const fileNameExtensionsTypeScript = [`.ts`, `.js`, `.mjs`, `.mts`]
@@ -55,16 +55,13 @@ export const load = async (options: LoadOptions): Promise<ConfigInput> => {
     configInput = {}
   } else {
     // If the user's config is a TypeScript file, we will use TSX to import it.
-    // TODO: Use NodeJS's native ESM support for TypeScript files.
 
     let module: { default?: Prom.Maybe<ConfigInput>; config?: Prom.Maybe<ConfigInput> }
     if (fileNameExtensionsTypeScript.some(_ => filePath.endsWith(_))) {
       // @see https://tsx.is/dev-api/ts-import#usage
       const { tsImport } = await import(`tsx/esm/api`)
-      // eslint-disable-next-line
       module = await tsImport(filePath, import.meta.url)
     } else {
-      // eslint-disable-next-line
       module = await import(filePath)
     }
     debug(`imported config module`)

package/src/api/config/merge.ts

@@ -1,5 +1,5 @@
 import { Vite } from '#dep/vite/index'
-import type { ConfigInput } from './configurator.ts'
+import type { ConfigInput } from './configurator.js'
 
 /**
  * Deep merge two Polen config inputs.
@@ -7,7 +7,6 @@ import type { ConfigInput } from './configurator.ts'
  */
 export const mergeInputs = (
   base: ConfigInput,
-  // eslint-disable-next-line
   overrides?: ConfigInput | undefined,
 ): ConfigInput => {
   if (!overrides) {

package/src/api/config-resolver/config-resolver.ts

@@ -1,2 +1,2 @@
-export * from './resolve.ts'
-export * from './vite.ts'
+export * from './resolve.js'
+export * from './vite.js'

package/src/api/config-resolver/index.ts

@@ -1 +1 @@
-export * as ConfigResolver from './config-resolver.ts'
+export * as ConfigResolver from './config-resolver.js'

package/src/api/config-resolver/resolve.ts

@@ -1,8 +1,8 @@
 import { debugPolen } from '#singletons/debug'
-import { type ConfigInput, normalizeInput } from '../config/configurator.ts'
-import { load, type LoadOptions } from '../config/load.ts'
-import { mergeInputs } from '../config/merge.ts'
-import { toViteUserConfig, type ViteUserConfigWithPolen } from './vite.ts'
+import { type ConfigInput, normalizeInput } from '../config/configurator.js'
+import { load, type LoadOptions } from '../config/load.js'
+import { mergeInputs } from '../config/merge.js'
+import { toViteUserConfig, type ViteUserConfigWithPolen } from './vite.js'
 
 interface ResolveFromFileOptions extends LoadOptions {
   overrides?: ConfigInput

package/src/api/config-resolver/vite.ts

@@ -1,6 +1,6 @@
 import { Main } from '#api/vite/plugins/main'
 import { Vite } from '#dep/vite/index'
-import type { Config } from '../config/configurator.ts'
+import type { Config } from '../config/configurator.js'
 
 /**
  * Transform Polen config input into a Vite configuration.

package/src/api/content/$$.ts

@@ -1,6 +1,6 @@
-export * from './metadata.ts'
-export * from './navbar.ts'
-export * from './page.ts'
-export * from './scan.ts'
-export * from './sidebar.ts'
-export * from './utils.ts'
+export * from './metadata.js'
+export * from './navbar.js'
+export * from './page.js'
+export * from './scan.js'
+export * from './sidebar.js'
+export * from './utils.js'

package/src/api/content/$.test.ts

@@ -1,6 +1,6 @@
 import { Fs, Path } from '@wollybeard/kit'
 import { afterEach, beforeEach, describe, expect, test } from 'vitest'
-import { Content } from './$.ts'
+import { Content } from './$.js'
 
 describe('content', () => {
   let testDir: string

package/src/api/content/$.ts

@@ -1 +1 @@
-export * as Content from './$$.ts'
+export * as Content from './$$.js'

package/src/api/content/navbar.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { createNavbar } from './navbar.ts'
-import type { Page } from './page.ts'
+import { createNavbar } from './navbar.js'
+import type { Page } from './page.js'
 
 const createPage = (path: string[], fileName = 'index', hidden = false): Page => ({
   route: {

package/src/api/content/navbar.ts

@@ -1,5 +1,5 @@
 import { Str } from '@wollybeard/kit'
-import type { Page } from './page.ts'
+import type { Page } from './page.js'
 
 export interface NavbarItem {
   pathExp: string
@@ -33,12 +33,12 @@ export const createNavbar = (pages: Page[]): NavbarItem[] => {
     // For directories, check if there's an index page
     const indexPage = pages.find(p =>
       p.route.logical.path.length === 1
-      && p.route.file.path.relative.name === 'index'
+      && p.route.file.path.relative.name === `index`
     )
 
     // For single non-index files at top level
     const singlePage = pages.length === 1 && pages[0]!.route.logical.path.length === 1
-      && pages[0]!.route.file.path.relative.name !== 'index'
+      && pages[0]!.route.file.path.relative.name !== `index`
 
     // Include in navbar if:
     // 1. It's a directory with an index page, OR

package/src/api/content/page.ts

@@ -1,5 +1,5 @@
 import type { FileRouter } from '#lib/file-router/index'
-import type { Metadata } from './metadata.ts'
+import type { Metadata } from './metadata.js'
 
 export type { Metadata }
 

package/src/api/content/scan.ts

@@ -1,8 +1,8 @@
 import { FileRouter } from '#lib/file-router/index'
 import { Fs, Path, Tree } from '@wollybeard/kit'
 import matter from 'gray-matter'
-import { MetadataSchema } from './metadata.ts'
-import type { Page } from './page.ts'
+import { MetadataSchema } from './metadata.js'
+import type { Page } from './page.js'
 
 export interface ScanResult {
   list: Page[]
@@ -23,7 +23,7 @@ export const scan = async (options: {
   // Scan for routes
   const routeScanResult = await FileRouter.scan({
     dir: options.dir,
-    glob: options.glob ?? '**/*.{md,mdx}',
+    glob: options.glob ?? `**/*.{md,mdx}`,
   })
 
   // Create pages with metadata (id/parentId now come from route)
@@ -53,12 +53,12 @@ export const scan = async (options: {
     // Create a virtual root node to hold all root-level pages
     const virtualRoot: Page & { id: string; parentId: null } = {
       route: {
-        id: '__virtual_root__',
+        id: `__virtual_root__`,
         parentId: null,
         file: {
           path: {
-            absolute: Path.parse(''),
-            relative: Path.parse(''),
+            absolute: Path.parse(``),
+            relative: Path.parse(``),
           },
         },
         logical: {
@@ -66,14 +66,14 @@ export const scan = async (options: {
         },
       },
       metadata: { hidden: true },
-      id: '__virtual_root__',
+      id: `__virtual_root__`,
       parentId: null,
     }
 
     // Update pages to have virtual root as parent if they don't have one
     const pagesWithVirtualRoot = pagesWithIds.map(page => ({
       ...page,
-      parentId: page.parentId || '__virtual_root__',
+      parentId: page.parentId || `__virtual_root__`,
     }))
 
     tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])

package/src/api/content/sidebar.test.ts

@@ -1,8 +1,8 @@
 import * as fc from 'fast-check'
 import { describe, expect, it } from 'vitest'
-import type { Page } from './page.ts'
-import type { ScanResult } from './scan.ts'
-import { buildSidebarIndex, type Item, type SidebarIndex } from './sidebar.ts'
+import type { Page } from './page.js'
+import type { ScanResult } from './scan.js'
+import { buildSidebarIndex } from './sidebar.js'
 
 // Generators
 const pathSegmentArb = fc.stringMatching(/^[a-z][a-z0-9-]{0,19}$/)

package/src/api/content/sidebar.ts

@@ -1,7 +1,7 @@
 import { FileRouter } from '#lib/file-router/index'
 import { Str } from '@wollybeard/kit'
-import type { Page } from './page.ts'
-import type { ScanResult } from './scan.ts'
+import type { Page } from './page.js'
+import type { ScanResult } from './scan.js'
 
 /**
  * Represents a complete sidebar structure with navigation items.
@@ -27,17 +27,17 @@ export type Item = ItemLink | ItemSection
  * ```ts
  * const link: ItemLink = {
  *   type: 'ItemLink',
- *   title: 'Getting Started',
- *   pathExp: 'guide/getting-started'
+ *   title: 'Get Started',
+ *   pathExp: 'guide/get-started'
  * }
  * ```
  */
 export interface ItemLink {
   /** Discriminator for TypeScript union types */
   type: `ItemLink`
-  /** Display title for the link (e.g., "Getting Started") */
+  /** Display title for the link (e.g., "Get Started") */
   title: string
-  /** Path expression relative to the base path, without leading slash (e.g., "guide/getting-started") */
+  /** Path expression relative to the base path, without leading slash (e.g., "guide/get-started") */
   pathExp: string
 }
 
@@ -164,7 +164,7 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
     }
 
     // Get the immediate parent path (e.g., for ['guide', 'advanced', 'tips'], parent is ['guide', 'advanced'])
-    const parentPath = page.route.logical.path.slice(0, -1).join('/')
+    const parentPath = page.route.logical.path.slice(0, -1).join(`/`)
 
     if (!pagesByParent.has(parentPath)) {
       pagesByParent.set(parentPath, [])
@@ -178,12 +178,12 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
   // Sort pages by their directory order (extracted from file path)
   const sortedTopLevelPages = [...topLevelPages].sort((a, b) => {
     // For sections, we need to look at the directory name in the file path
-    const dirA = a.route.file.path.relative.dir.split('/').pop() || ''
-    const dirB = b.route.file.path.relative.dir.split('/').pop() || ''
+    const dirA = a.route.file.path.relative.dir.split(`/`).pop() || ``
+    const dirB = b.route.file.path.relative.dir.split(`/`).pop() || ``
 
     // Extract order from directory names like "10_b", "20_c"
-    const orderMatchA = dirA.match(/^(\d+)[_-]/)
-    const orderMatchB = dirB.match(/^(\d+)[_-]/)
+    const orderMatchA = /^(\d+)[_-]/.exec(dirA)
+    const orderMatchB = /^(\d+)[_-]/.exec(dirB)
 
     const orderA = orderMatchA ? parseInt(orderMatchA[1]!, 10) : Number.MAX_SAFE_INTEGER
     const orderB = orderMatchB ? parseInt(orderMatchB[1]!, 10) : Number.MAX_SAFE_INTEGER
@@ -196,7 +196,7 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
 
   for (const page of sortedTopLevelPages) {
     const pageName = page.route.logical.path[page.route.logical.path.length - 1]!
-    const childPath = page.route.logical.path.join('/')
+    const childPath = page.route.logical.path.join(`/`)
     const childPages = pagesByParent.get(childPath) || []
 
     if (childPages.length > 0 || FileRouter.routeIsFromIndexFile(page.route)) {
@@ -204,7 +204,7 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
       const hasIndex = FileRouter.routeIsFromIndexFile(page.route)
 
       const section: ItemSection = {
-        type: 'ItemSection',
+        type: `ItemSection`,
         title: Str.titlizeSlug(pageName),
         pathExp: childPath,
         isLinkToo: hasIndex,
@@ -221,9 +221,9 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
       for (const childPage of sortedChildPages) {
         if (!FileRouter.routeIsFromIndexFile(childPage.route)) {
           section.links.push({
-            type: 'ItemLink',
+            type: `ItemLink`,
             title: Str.titlizeSlug(childPage.route.logical.path[childPage.route.logical.path.length - 1]!),
-            pathExp: childPage.route.logical.path.join('/'),
+            pathExp: childPage.route.logical.path.join(`/`),
           })
         }
       }
@@ -232,7 +232,7 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
       const allDescendants: Page[] = []
       for (const [parentPath, pagesInParent] of pagesByParent) {
         // Check if this path is a descendant (but not direct child)
-        if (parentPath.startsWith(childPath + '/')) {
+        if (parentPath.startsWith(childPath + `/`)) {
           for (const descendantPage of pagesInParent) {
             if (!FileRouter.routeIsFromIndexFile(descendantPage.route)) {
               allDescendants.push(descendantPage)
@@ -258,11 +258,11 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
 
       for (const descendantPage of allDescendants) {
         section.links.push({
-          type: 'ItemLink',
+          type: `ItemLink`,
           title: Str.titlizeSlug(
             descendantPage.route.logical.path[descendantPage.route.logical.path.length - 1]!,
           ),
-          pathExp: descendantPage.route.logical.path.join('/'),
+          pathExp: descendantPage.route.logical.path.join(`/`),
         })
       }
 
@@ -272,9 +272,9 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
     } else {
       // This is a simple link
       items.push({
-        type: 'ItemLink',
+        type: `ItemLink`,
         title: Str.titlizeSlug(pageName),
-        pathExp: page.route.logical.path.join('/'),
+        pathExp: page.route.logical.path.join(`/`),
       })
     }
   }

package/src/api/index.ts

@@ -1 +1 @@
-export * as Api from './api.ts'
+export * as Api from './api.js'

package/src/api/schema/data-sources/data-sources.ts

@@ -1,3 +1,3 @@
-export * as Memory from './memory/memory.ts'
-export * as SchemaDirectory from './schema-directory/schema-directory.ts'
-export * as SchemaFile from './schema-file/schema-file.ts'
+export * as Memory from './memory/memory.js'
+export * as SchemaDirectory from './schema-directory/schema-directory.js'
+export * as SchemaFile from './schema-file/schema-file.js'

package/src/api/schema/data-sources/index.ts

@@ -1 +1 @@
-export * as DataSources from './data-sources.ts'
+export * as DataSources from './data-sources.js'

package/src/api/schema/data-sources/memory/memory.ts

@@ -2,9 +2,44 @@ import { Grafaid } from '#lib/grafaid/index'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { Arr } from '@wollybeard/kit'
-import type { Schema } from '../../schema.ts'
+import type { Schema } from '../../schema.js'
 
+/**
+ * Configuration for defining schemas programmatically in memory.
+ *
+ * Useful for demos, testing, or when schemas are generated dynamically.
+ */
 export interface ConfigInput {
+  /**
+   * Schema versions defined as SDL strings.
+   *
+   * Can be:
+   * - A single SDL string (no changelog)
+   * - Array of SDL strings (uses current date for all)
+   * - Array of objects with date and SDL (full changelog support)
+   *
+   * @example
+   * ```ts
+   * // Single schema
+   * versions: `
+   *   type Query {
+   *     hello: String
+   *   }
+   * `
+   *
+   * // Multiple versions with explicit dates
+   * versions: [
+   *   {
+   *     date: new Date('2024-01-15'),
+   *     value: `type Query { users: [User] }`
+   *   },
+   *   {
+   *     date: new Date('2024-03-20'),
+   *     value: `type Query { users: [User], posts: [Post] }`
+   *   }
+   * ]
+   * ```
+   */
   versions:
     | string
     | string[]

package/src/api/schema/data-sources/schema-directory/file-name-expression/file-name-expression.ts

@@ -58,7 +58,6 @@ const expressionPreviousSerializedPattern = /^(?<year>\d{4})-(?<month>\d{2})-(?<
 //   filePath: string
 // }
 
-// // eslint-disable-next-line
 // const parseExpressionLatestSerialized = (serializedExpression: string): null | {} => {
 //   if (serializedExpression === `latest`) return {}
 //   return null

package/src/api/schema/data-sources/schema-directory/file-name-expression/index.ts

@@ -1 +1 @@
-export * as FileNameExpression from './file-name-expression.ts'
+export * as FileNameExpression from './file-name-expression.js'

package/src/api/schema/data-sources/schema-directory/schema-directory.ts

@@ -4,8 +4,8 @@ import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { debugPolen } from '#singletons/debug'
 import { Arr, Path } from '@wollybeard/kit'
 import { glob } from 'tinyglobby'
-import type { Schema } from '../../schema.ts'
-import { FileNameExpression } from './file-name-expression/index.ts'
+import type { Schema } from '../../schema.js'
+import { FileNameExpression } from './file-name-expression/index.js'
 
 // const debug = debugPolen.sub([`schema`, `data-source-schema-directory`])
 const debug = debugPolen.sub(`schema:data-source-schema-directory`)
@@ -14,7 +14,36 @@ const defaultPaths = {
   schemaDirectory: `./schema`,
 }
 
+/**
+ * Configuration for loading multiple schema versions from a directory.
+ *
+ * Enables the schema changelog feature by loading SDL files with date prefixes.
+ */
 export interface ConfigInput {
+  /**
+   * Path to the directory containing dated SDL files.
+   *
+   * Files should be named with ISO date prefixes: `YYYY-MM-DD.graphql`
+   *
+   * @default './schema'
+   *
+   * @example
+   * ```ts
+   * // Default location
+   * path: './schema'
+   *
+   * // Custom location
+   * path: './graphql/versions'
+   * ```
+   *
+   * Directory structure example:
+   * ```
+   * schema/
+   *   2024-01-15.graphql
+   *   2024-03-20.graphql
+   *   2024-06-10.graphql
+   * ```
+   */
   path?: string
   projectRoot?: string
 }