polen 0.11.0-next.17 → 0.11.0-next.19

package/src/api/config/normalized.ts

@@ -469,7 +469,7 @@ const buildPaths = (rootDir: string, overrides?: ConfigAdvancedPathsInput | unde
   }
 }
 
-const getConfigInputDefaults = (): Config => ({
+const getConfigInputDefaults = (baseRootDirPath: string): Config => ({
   _input: {},
   name: `My Developer Portal`,
   description: `Explore and integrate with our GraphQL API`,
@@ -525,7 +525,7 @@ const getConfigInputDefaults = (): Config => ({
       enabled: true,
     },
   },
-  paths: buildPaths(process.cwd()),
+  paths: buildPaths(baseRootDirPath),
   advanced: {
     isSelfContainedMode: false,
     debug: false,
@@ -549,7 +549,7 @@ export const normalizeInput = (
     assertPathAbsolute(baseRootDirPath)
 
     const configInput_as_writeable = configInput as WritableDeep<ConfigInput> | undefined
-    const config = structuredClone(getConfigInputDefaults()) as WritableDeep<Config>
+    const config = structuredClone(getConfigInputDefaults(baseRootDirPath)) as WritableDeep<Config>
 
     if (configInput_as_writeable) {
       config._input = configInput_as_writeable
@@ -656,6 +656,15 @@ export const normalizeInput = (
     if (configInput_as_writeable?.examples) {
       const examplesInput = configInput_as_writeable.examples
 
+      // The schema transform handles boolean shorthand, so we always get an object here
+      if (examplesInput.enabled !== undefined) {
+        // If explicitly disabled, set display to 'none'
+        if (examplesInput.enabled === false) {
+          config.examples.display = 'none'
+        }
+        // enabled: true keeps defaults
+      }
+
       if (examplesInput.display !== undefined) {
         config.examples.display = examplesInput.display
       }

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

@@ -1,5 +1,5 @@
 import type { Api } from '#api/$'
-import { ExamplesConfig } from '#api/examples/config'
+import { ExamplesConfigObject } from '#api/examples/config'
 import { ConfigSchema } from '#api/schema/config-schema'
 import type { Catalog } from '#lib/catalog/$'
 import { S } from '#lib/kit-temp/effect'
@@ -42,7 +42,7 @@ export const TemplateConfig = S.extend(
       }),
     ),
     examples: S.extend(
-      ExamplesConfig.pipe(S.omit('enabled')),
+      ExamplesConfigObject.pipe(S.omit('enabled')),
       S.Struct({
         enabled: S.Boolean,
       }),

package/src/api/content/sidebar.ts

@@ -1,5 +1,6 @@
 import { FileRouter } from '#lib/file-router'
 import { Str } from '@wollybeard/kit'
+import { Array } from 'effect'
 import type { Page } from './page.js'
 import type { ScanResult } from './scan.js'
 
@@ -129,10 +130,9 @@ export const buildSidebarIndex = (scanResult: ScanResult): SidebarIndex => {
 
   // Build sidebar for each directory that has an index page
   for (const [topLevelDir, pages] of pagesByTopLevelDir) {
-    const hasIndexPage = pages.some(page =>
+    const hasIndexPage = Array.some(pages, page =>
       page.route.logical.path.length === 1
-      && FileRouter.routeIsFromIndexFile(page.route)
-    )
+      && FileRouter.routeIsFromIndexFile(page.route))
 
     // Skip directories without index pages
     if (!hasIndexPage) continue

package/src/api/errors.ts

@@ -0,0 +1,227 @@
+import { Data } from 'effect'
+
+// =====================================
+// Config Errors
+// =====================================
+
+/**
+ * Error thrown when config file cannot be found
+ */
+export class ConfigFileNotFoundError extends Data.TaggedError('ConfigFileNotFoundError')<{
+  readonly path: string
+}> {}
+
+/**
+ * Error thrown when config file cannot be imported
+ */
+export class ConfigImportError extends Data.TaggedError('ConfigImportError')<{
+  readonly filePath: string
+  readonly cause: unknown
+}> {}
+
+/**
+ * Error thrown when config file has invalid format
+ */
+export class ConfigParseError extends Data.TaggedError('ConfigParseError')<{
+  readonly filePath: string
+  readonly parseErrors: unknown
+}> {}
+
+/**
+ * Error thrown when config cannot be resolved from module
+ */
+export class ConfigResolveError extends Data.TaggedError('ConfigResolveError')<{
+  readonly cause: unknown
+}> {}
+
+/**
+ * Error thrown when package.json cannot be read
+ */
+export class PackageJsonReadError extends Data.TaggedError('PackageJsonReadError')<{
+  readonly rootDir: string
+  readonly cause: unknown
+}> {}
+
+// =====================================
+// Static Site Errors
+// =====================================
+
+/**
+ * Error thrown when Polen build manifest is not found
+ */
+export class PolenManifestNotFoundError extends Data.TaggedError('PolenManifestNotFoundError')<{
+  readonly path: string
+}> {}
+
+/**
+ * Error thrown when base path is invalid
+ */
+export class InvalidBasePathError extends Data.TaggedError('InvalidBasePathError')<{
+  readonly basePath: string
+}> {}
+
+/**
+ * Error thrown when target path already exists and is not empty
+ */
+export class TargetExistsError extends Data.TaggedError('TargetExistsError')<{
+  readonly targetPath: string
+}> {}
+
+/**
+ * Error thrown when HTML processing fails
+ */
+export class HtmlProcessingError extends Data.TaggedError('HtmlProcessingError')<{
+  readonly filePath: string
+  readonly reason: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Error thrown when file system operation fails
+ */
+export class FileSystemError extends Data.TaggedError('FileSystemError')<{
+  readonly operation: 'read' | 'write' | 'copy' | 'stat' | 'mkdir' | 'remove'
+  readonly path: string
+  readonly cause: unknown
+}> {}
+
+// =====================================
+// Builder Errors
+// =====================================
+
+/**
+ * Error thrown when Vite builder fails
+ */
+export class ViteBuilderError extends Data.TaggedError('ViteBuilderError')<{
+  readonly phase: 'create' | 'build'
+  readonly cause: unknown
+}> {}
+
+/**
+ * Error thrown when server fails to start
+ */
+export class ServerStartupError extends Data.TaggedError('ServerStartupError')<{
+  readonly port: number
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Error thrown when server exits unexpectedly
+ */
+export class ServerExitError extends Data.TaggedError('ServerExitError')<{
+  readonly port: number
+  readonly code: number | null
+  readonly signal: string | null
+}> {}
+
+/**
+ * Error thrown when server startup times out
+ */
+export class ServerTimeoutError extends Data.TaggedError('ServerTimeoutError')<{
+  readonly port: number
+  readonly timeoutSeconds: number
+}> {}
+
+/**
+ * Error thrown when port allocation fails
+ */
+export class PortAllocationError extends Data.TaggedError('PortAllocationError')<{
+  readonly cause: unknown
+}> {}
+
+/**
+ * Error thrown when route processing fails
+ */
+export class RouteProcessingError extends Data.TaggedError('RouteProcessingError')<{
+  readonly route: string
+  readonly cause: unknown
+}> {}
+
+/**
+ * Error thrown when route fetch fails
+ */
+export class RouteFetchError extends Data.TaggedError('RouteFetchError')<{
+  readonly route: string
+  readonly status: number
+  readonly statusText: string
+}> {}
+
+// =====================================
+// Schema Loading Errors
+// =====================================
+
+/**
+ * Error thrown when no applicable schema source is found
+ */
+export class NoApplicableSchemaSourceError extends Data.TaggedError('NoApplicableSchemaSourceError')<{}> {}
+
+/**
+ * Error thrown when schema source returns no data
+ */
+export class SchemaSourceNoDataError extends Data.TaggedError('SchemaSourceNoDataError')<{}> {}
+
+// =====================================
+// Schema Augmentation Errors
+// =====================================
+
+/**
+ * Error thrown when a type cannot be found in the schema
+ */
+export class TypeNotFoundError extends Data.TaggedError('TypeNotFoundError')<{
+  readonly typeName: string
+}> {}
+
+/**
+ * Error thrown when a field cannot be found on a type
+ */
+export class FieldNotFoundError extends Data.TaggedError('FieldNotFoundError')<{
+  readonly fieldName: string
+  readonly typeName: string
+}> {}
+
+/**
+ * Error thrown when a type doesn't have fields
+ */
+export class TypeHasNoFieldsError extends Data.TaggedError('TypeHasNoFieldsError')<{
+  readonly typeName: string
+}> {}
+
+// =====================================
+// Routes Manifest Errors
+// =====================================
+
+/**
+ * Error thrown when routes manifest cannot be read
+ */
+export class RoutesManifestReadError extends Data.TaggedError('RoutesManifestReadError')<{
+  readonly path: string
+  readonly cause: unknown
+}> {}
+
+/**
+ * Error thrown when routes manifest cannot be written
+ */
+export class RoutesManifestWriteError extends Data.TaggedError('RoutesManifestWriteError')<{
+  readonly path: string
+  readonly cause: unknown
+}> {}
+
+// =====================================
+// Validation Errors
+// =====================================
+
+/**
+ * Error thrown when base path validation fails
+ */
+export class InvalidPathError extends Data.TaggedError('InvalidPathError')<{
+  readonly path: string
+  readonly requirement: string
+}> {}
+
+/**
+ * Error thrown when version string is invalid
+ */
+export class InvalidVersionError extends Data.TaggedError('InvalidVersionError')<{
+  readonly version: string
+}> {}

package/src/api/examples/config.test.ts

@@ -28,6 +28,16 @@ describe('ExamplesConfig', () => {
       expect(result).toEqual({})
     })
 
+    test('boolean shorthand: false disables examples', () => {
+      const result = decodeExamplesConfig(false)
+      expect(result).toEqual({ enabled: false })
+    })
+
+    test('boolean shorthand: true uses defaults', () => {
+      const result = decodeExamplesConfig(true)
+      expect(result).toEqual({})
+    })
+
     test('decodes full config', () => {
       const input = {
         display: { include: ['example1', 'example2'] },

package/src/api/examples/config.ts

@@ -141,7 +141,7 @@ export type ExampleDiagnostics = S.Schema.Type<typeof ExampleDiagnostics>
 // Schema - Examples Config
 // ============================================================================
 
-export const ExamplesConfig = S.Struct({
+export const ExamplesConfigObject = S.Struct({
   /**
    * Control whether the examples feature is enabled.
    * - true: Always enabled (show in nav even if no examples exist)
@@ -220,13 +220,42 @@ export const ExamplesConfig = S.Struct({
   description: 'Configuration for GraphQL examples behavior and diagnostics',
 })
 
+/**
+ * Examples configuration supporting both boolean shorthand and detailed object form.
+ * - `false`: Disable examples entirely
+ * - `true`: Enable examples with defaults
+ * - object: Fine-grained configuration
+ */
+export const ExamplesConfig = S.transform(
+  S.Union(
+    S.Boolean,
+    ExamplesConfigObject,
+  ),
+  ExamplesConfigObject,
+  {
+    strict: false,
+    decode: (input) => {
+      if (typeof input === 'boolean') {
+        // Convert boolean shorthand to object form
+        return input === false
+          ? { enabled: false } as const
+          : {} // true means use defaults
+      }
+      return input
+    },
+    encode: (value) => value,
+  },
+).annotations({
+  identifier: 'ExamplesConfigTransform',
+  title: 'Examples Configuration with Boolean Shorthand',
+  description: 'Configuration for GraphQL examples - accepts boolean shorthand or detailed object',
+})
+
 export type ExamplesConfig = S.Schema.Type<typeof ExamplesConfig>
 
 // ============================================================================
 // Constructors
-// ============================================================================
-
-export const makeExamplesConfig = ExamplesConfig.make
+export const makeExamplesConfig = ExamplesConfigObject.make
 
 // ============================================================================
 // Type Guards

package/src/api/examples/diagnostic/validation-error.ts

@@ -1,6 +1,6 @@
 import { Diagnostic } from '#lib/diagnostic/$'
-import { GraphQLError } from '#lib/graphql-error/$'
 import { S } from '#lib/kit-temp/effect'
+import { Version } from '#lib/version/$'
 
 export const DiagnosticValidationError = Diagnostic.create({
   source: 'examples-validation',
@@ -11,8 +11,14 @@ export const DiagnosticValidationError = Diagnostic.create({
       name: S.String,
       path: S.String,
     }),
-    version: S.String,
-    errors: S.Array(GraphQLError.GraphQLError),
+    version: S.optional(Version.Version),
+    errors: S.Array(S.Struct({
+      message: S.String,
+      locations: S.optional(S.Array(S.Struct({
+        line: S.Number,
+        column: S.Number,
+      }))),
+    })),
   },
 }).annotations({
   identifier: 'DiagnosticValidationError',

package/src/api/examples/diagnostic/validator.test.ts

@@ -290,3 +290,33 @@ test('validates examples with version sets', () => {
   const diagnostics = validateExamples(examples, versionedCatalogWithV3)
   expect(diagnostics.length).toBe(1) // invalidField doesn't exist in the test schema
 })
+
+test('detects mismatch between versioned document and unversioned catalog', () => {
+  // Create a versioned document with multiple versions
+  const v1 = Version.fromString('1.0.0')
+  const v2 = Version.fromString('2.0.0')
+
+  const versionedDocument = Document.Versioned.make({
+    versionDocuments: HashMap.make(
+      [v1, 'query { user(id: "1") { id name } }'],
+      [v2, 'query { users { id name } }'],
+    ),
+  })
+
+  // Create an example with versioned document
+  const example = Example.make({
+    name: 'test-version-mismatch',
+    path: 'test.graphql',
+    document: versionedDocument,
+  })
+
+  // Validate against unversioned catalog - should detect mismatch
+  const diagnostics = validateExamples([example], catalog)
+
+  // Should have exactly one diagnostic about the version mismatch
+  expect(diagnostics.length).toBe(1)
+  expect(diagnostics[0]!._tag).toBe('Diagnostic')
+  expect(diagnostics[0]!.name).toBe('invalid-graphql')
+  expect(diagnostics[0]!.message).toContain('versioned content but catalog is unversioned')
+  expect(diagnostics[0]!.errors![0]!.message).toContain('Cannot use a version coverage with an unversioned catalog')
+})