polen 0.10.0-next.8 → 0.10.0

package/src/api/config/configurator.ts

@@ -1,10 +1,10 @@
 import type { Vite } from '#dep/vite/index'
 import { assertPathAbsolute } from '#lib/kit-temp'
 import { type PackagePaths, packagePaths } from '#package-paths'
-import { Path } from '@wollybeard/kit'
+import { Err, Manifest, Path, Str } 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,23 +18,71 @@ 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.
+   * Configuration for how Polen loads your GraphQL schema.
    *
-   * Relative paths will be resolved relative to this config file.
+   * 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 The directory where the config file is located.
+   * @example
+   * ```ts
+   * // Single file
+   * schema: {
+   *   useDataSources: 'file',
+   *   dataSources: {
+   *     file: { path: './my-schema.graphql' }
+   *   }
+   * }
+   *
+   * // Multiple versions for changelog
+   * schema: {
+   *   useDataSources: 'directory',
+   *   dataSources: {
+   *     directory: { path: './schema' }
+   *   }
+   * }
+   * ```
    */
-  root?: string
+  schema?: SchemaConfigInput
   /**
-   * Enable a special module explorer for the source code that Polen assembles for your app.
+   * Programmatically enhance your GraphQL schema documentation without modifying the schema files.
    *
-   * Powered by [Vite Inspect](https://github.com/antfu-collective/vite-plugin-inspect).
+   * Perfect for adding implementation details, usage examples, deprecation notices,
+   * or any additional context that helps developers understand your API better.
    *
-   * @default true
+   * @example
+   * ```ts
+   * schemaAugmentations: [
+   *   {
+   *     type: 'description',
+   *     on: {
+   *       type: 'TargetType',
+   *       name: 'User'
+   *     },
+   *     placement: 'after',
+   *     content: '\n\nSee the [User Guide](/guides/users) for detailed usage.'
+   *   },
+   *   {
+   *     type: 'description',
+   *     on: {
+   *       type: 'TargetField',
+   *       targetType: 'Query',
+   *       name: 'users'
+   *     },
+   *     placement: 'after',
+   *     content: '\n\n**Rate limit:** 100 requests per minute'
+   *   }
+   * ]
+   * ```
    */
-  schema?: SchemaConfigInput
   schemaAugmentations?: SchemaAugmentation.Augmentation[]
   templateVariables?: {
     /**
@@ -42,21 +90,52 @@ export interface ConfigInput {
      *
      * Used in the navigation bar and in the title tag.
      *
-     * @default `My Developer Portal`
+     * If not provided, Polen will try to use your project's package.json name
+     * field, converting it to title case (e.g., "my-project" → "My Project").
+     *
+     * @default Your package.json name (title-cased) or "My Developer Portal"
+     * @example
+     * ```ts
+     * // Explicit title
+     * title: 'Acme GraphQL API'
+     *
+     * // Falls back to package.json name
+     * // If package.json has { "name": "acme-graphql" }
+     * // Title will be "Acme Graphql"
+     * ```
      */
     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 +143,86 @@ export interface ConfigInput {
      */
     base?: string
   }
+  /**
+   * Server configuration for development and production.
+   */
+  server?: {
+    /**
+     * Port for the server to listen on.
+     *
+     * - In development: The port for the Vite dev server
+     * - In production SSR: The default port for the Node.js server
+     *
+     * For production SSR builds, this can be overridden at runtime
+     * using the PORT environment variable.
+     *
+     * @default 3000
+     * @example
+     * ```ts
+     * // Use a specific port
+     * server: {
+     *   port: 4000
+     * }
+     *
+     * // Or via CLI flags:
+     * // polen dev --port 4000
+     * // polen build --port 4000
+     * ```
+     */
+    port?: number
+  }
+  /**
+   * Configuration for developer experience warnings.
+   *
+   * Polen can show helpful warnings for common issues or misconfigurations.
+   * Each warning type can be individually enabled or disabled.
+   *
+   * @example
+   * ```ts
+   * warnings: {
+   *   interactiveWithoutSchema: {
+   *     enabled: false // Disable warning when interactive code blocks are used without a schema
+   *   }
+   * }
+   * ```
+   */
+  warnings?: {
+    /**
+     * Warning shown when GraphQL code blocks have the `interactive` flag
+     * but no schema is configured.
+     *
+     * Interactive features require a schema to provide field validation,
+     * type information, and auto-completion.
+     *
+     * @default { enabled: true }
+     */
+    interactiveWithoutSchema?: {
+      /**
+       * Whether to show this warning.
+       *
+       * @default true
+       */
+      enabled?: boolean
+    }
+  }
+  /**
+   * 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 +302,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`),
         },
       },
     },
@@ -171,6 +329,9 @@ export interface Config {
     architecture: BuildArchitecture
     base: string
   }
+  server: {
+    port: number
+  }
   watch: {
     also: string[]
   }
@@ -180,6 +341,11 @@ export interface Config {
   ssr: {
     enabled: boolean
   }
+  warnings: {
+    interactiveWithoutSchema: {
+      enabled: boolean
+    }
+  }
   paths: {
     project: {
       rootDir: string
@@ -233,10 +399,18 @@ const configInputDefaults: Config = {
     architecture: BuildArchitecture.enum.ssg,
     base: `/`,
   },
+  server: {
+    port: 3000,
+  },
   schema: null,
   ssr: {
     enabled: true,
   },
+  warnings: {
+    interactiveWithoutSchema: {
+      enabled: true,
+    },
+  },
   paths: buildPaths(process.cwd()),
   advanced: {
     isSelfContainedMode: false,
@@ -256,7 +430,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)
 
@@ -286,16 +459,19 @@ export const normalizeInput = async (
     config.advanced.debug = configInput.advanced.debug
   }
 
-  if (configInput?.root !== undefined) {
-    if (!baseRootDirPath && !Path.isAbsolute(configInput.root)) {
-      throw new Error(
-        `Root path must be absolute or baseRootPath must be provided to resolve relative root paths. Provided: ${configInput.root}`,
-      )
+  // Always use the baseRootDirPath as the project root
+  // This is either the --project directory or the config file directory
+  config.paths = buildPaths(baseRootDirPath)
+
+  // Try to read package.json name as fallback for title
+  if (!configInput?.templateVariables?.title) {
+    const packageJson = await Manifest.resource.read(config.paths.project.rootDir)
+
+    // todo: let the user know there was an error...
+    if (!Err.is(packageJson) && packageJson.name) {
+      // Package name will be used as default, but can still be overridden below
+      config.templateVariables.title = Str.Case.title(packageJson.name)
     }
-    const root = Path.ensureAbsolute(configInput.root, baseRootDirPath)
-    config.paths = buildPaths(root)
-  } else if (baseRootDirPath) {
-    config.paths = buildPaths(baseRootDirPath)
   }
 
   if (configInput?.advanced?.vite) {
@@ -327,5 +503,14 @@ export const normalizeInput = async (
     config.watch.also = configInput.advanced.watch.also
   }
 
+  if (configInput?.server?.port !== undefined) {
+    config.server.port = configInput.server.port
+  }
+
+  // Process warnings configuration
+  if (configInput?.warnings?.interactiveWithoutSchema?.enabled !== undefined) {
+    config.warnings.interactiveWithoutSchema.enabled = configInput.warnings.interactiveWithoutSchema.enabled
+  }
+
   return config
 }

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,6 @@
 import { Vite } from '#dep/vite/index'
-import type { ConfigInput } from './configurator.ts'
+import { spreadShallow } from '#lib/kit-temp'
+import type { ConfigInput } from './configurator.js'
 
 /**
  * Deep merge two Polen config inputs.
@@ -7,47 +8,55 @@ import type { ConfigInput } from './configurator.ts'
  */
 export const mergeInputs = (
   base: ConfigInput,
-  // eslint-disable-next-line
   overrides?: ConfigInput | undefined,
 ): ConfigInput => {
   if (!overrides) {
     return base
   }
 
-  const merged: ConfigInput = {
-    ...base,
-    ...overrides,
-  }
+  const merged: ConfigInput = spreadShallow(base, overrides)
 
   // Merge schema if both have it
-  if (base.schema || overrides.schema) {
+  if (base.schema ?? overrides.schema) {
     merged.schema = overrides.schema ?? base.schema
   }
 
   // Merge build config
-  if (base.build || overrides.build) {
-    merged.build = {
-      ...base.build,
-      ...overrides.build,
+  if (base.build ?? overrides.build) {
+    merged.build = spreadShallow(base.build, overrides.build)
+  }
+
+  // Merge server config
+  if (base.server ?? overrides.server) {
+    merged.server = spreadShallow(base.server, overrides.server)
+  }
+
+  // Merge warnings config
+  if (base.warnings ?? overrides.warnings) {
+    merged.warnings = spreadShallow(base.warnings, overrides.warnings)
+
+    // Merge interactiveWithoutSchema config
+    if (base.warnings?.interactiveWithoutSchema ?? overrides.warnings?.interactiveWithoutSchema) {
+      merged.warnings.interactiveWithoutSchema = spreadShallow(
+        base.warnings?.interactiveWithoutSchema,
+        overrides.warnings?.interactiveWithoutSchema,
+      )
     }
   }
 
   // Merge advanced config
-  if (base.advanced || overrides.advanced) {
-    merged.advanced = {
-      ...base.advanced,
-      ...overrides.advanced,
-    }
+  if (base.advanced ?? overrides.advanced) {
+    merged.advanced = spreadShallow(base.advanced, overrides.advanced)
 
     // Merge advanced.watch config
-    if (base.advanced?.watch || overrides.advanced?.watch) {
-      merged.advanced.watch = {
-        ...base.advanced?.watch,
-        ...overrides.advanced?.watch,
-      }
+    if (base.advanced?.watch ?? overrides.advanced?.watch) {
+      merged.advanced.watch = spreadShallow(
+        base.advanced?.watch,
+        overrides.advanced?.watch,
+      )
 
       // Merge watch.also arrays
-      if (base.advanced?.watch?.also || overrides.advanced?.watch?.also) {
+      if (base.advanced?.watch?.also ?? overrides.advanced?.watch?.also) {
         merged.advanced.watch.also = [
           ...(base.advanced?.watch?.also ?? []),
           ...(overrides.advanced?.watch?.also ?? []),

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,5 +1,6 @@
-export * from './metadata.ts'
-export * from './navbar.ts'
-export * from './page.ts'
-export * from './scan.ts'
-export * from './sidebar.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)
@@ -44,7 +44,42 @@ export const scan = async (options: {
     parentId: page.route.parentId,
   }))
 
-  const tree = Tree.fromList(pagesWithIds)
+  // Handle cases where there might be multiple root nodes
+  // If all pages are at root level (no parentId), create a virtual root
+  const hasMultipleRoots = pagesWithIds.filter(p => !p.parentId).length > 1
+
+  let tree: Tree.Tree<Page>
+  if (hasMultipleRoots) {
+    // Create a virtual root node to hold all root-level pages
+    const virtualRoot: Page & { id: string; parentId: null } = {
+      route: {
+        id: `__virtual_root__`,
+        parentId: null,
+        file: {
+          path: {
+            absolute: Path.parse(``),
+            relative: Path.parse(``),
+          },
+        },
+        logical: {
+          path: [],
+        },
+      },
+      metadata: { hidden: true },
+      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__`,
+    }))
+
+    tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
+  } else {
+    tree = Tree.fromList(pagesWithIds)
+  }
 
   return {
     list: pages,

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}$/)