polen 0.11.0-next.17 → 0.11.0-next.18

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/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')
+})

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

@@ -1,9 +1,9 @@
 import { Catalog as SchemaCatalog } from '#lib/catalog/$'
 import { Document } from '#lib/document/$'
+import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
-import { Match } from 'effect'
-import { HashMap } from 'effect/Schema'
-import type { GraphQLError, GraphQLSchema } from 'graphql'
+import { Array, Either, Match, Schema as S } from 'effect'
+import type { DocumentNode, GraphQLError } from 'graphql'
 import { parse, specifiedRules, validate } from 'graphql'
 import { Example } from '../schemas/example/$.js'
 import type { DiagnosticValidationError } from './diagnostic.js'
@@ -15,6 +15,35 @@ import { makeDiagnosticValidationError } from './diagnostic.js'
 
 export type ValidationDiagnostic = DiagnosticValidationError
 
+// ============================================================================
+// Schemas
+// ============================================================================
+
+const GraphQLErrorData = S.Struct({
+  message: S.String,
+  locations: S.optional(S.Array(S.Struct({
+    line: S.Number,
+    column: S.Number,
+  }))),
+})
+
+type GraphQLErrorData = S.Schema.Type<typeof GraphQLErrorData>
+
+// ============================================================================
+// Safe Parsing
+// ============================================================================
+
+/**
+ * Safely parse a GraphQL document without throwing.
+ * Returns an Either with the document on success or error on failure.
+ */
+const parseDocumentSafe = (content: string): Either.Either<DocumentNode, GraphQLError> => {
+  return Either.try({
+    try: () => parse(content),
+    catch: (error) => error as GraphQLError,
+  })
+}
+
 // ============================================================================
 // Validation
 // ============================================================================
@@ -32,69 +61,76 @@ export const validateExamples = (
 ): ValidationDiagnostic[] => {
   const diagnostics: ValidationDiagnostic[] = []
 
-  return Match.value(catalog).pipe(
-    Match.tagsExhaustive({
-      CatalogVersioned: (versioned) => {
-        for (const example of examples) {
-          Match.value(example.document).pipe(
-            Match.tagsExhaustive({
-              DocumentVersioned: (doc) => {
-                // Validate each version against its corresponding schema
-                for (const schema of SchemaCatalog.Versioned.getAll(versioned)) {
-                  const content = Document.Versioned.getContentForVersion(doc, schema.version)
-                  if (content) {
-                    const versionStr = Version.encodeSync(schema.version)
-                    validateDocument(
-                      example.name,
-                      example.path,
-                      versionStr,
-                      content,
-                      schema.definition,
-                      diagnostics,
-                    )
-                  }
-                }
-                return undefined
-              },
-              DocumentUnversioned: (doc) => {
-                const latestEntry = SchemaCatalog.Versioned.getLatestOrThrow(versioned)
-                validateDocument(
-                  example.name,
-                  example.path,
-                  'default',
-                  doc.document,
-                  latestEntry.definition,
-                  diagnostics,
-                )
-                return undefined
-              },
-            }),
-          )
-        }
-
-        return diagnostics
-      },
-      CatalogUnversioned: (unversioned) => {
-        // For unversioned catalog, only unversioned documents make sense
-        for (const example of examples) {
-          if (example.document._tag === 'DocumentUnversioned') {
-            validateDocument(
-              example.name,
-              example.path,
-              'default',
-              example.document.document,
-              unversioned.schema.definition,
-              diagnostics,
+  Array.forEach(examples, (example) => {
+    if (example.document._tag === 'DocumentVersioned') {
+      // Versioned document: iterate all versions and let utility handle compatibility
+      const documentVersions = Document.Versioned.getAllVersions(example.document)
+      let versionMismatchDetected = false
+
+      Array.forEach(documentVersions, (version) => {
+        // Skip remaining versions if we already detected a version mismatch
+        if (versionMismatchDetected) return
+
+        const result = Document.resolveDocumentAndSchema(
+          example.document,
+          catalog,
+          version, // Pass each version as VersionCoverage
+        )
+
+        Either.match(result, {
+          onLeft: (error) => {
+            // Pattern match on error types - all errors are now tagged
+            Match.value(error).pipe(
+              Match.when({ _tag: 'VersionCoverageMismatchError' }, (err) => {
+                diagnostics.push(makeDiagnosticValidationError({
+                  message: `Example "${example.name}" has versioned content but catalog is unversioned`,
+                  example: { name: example.name, path: example.path },
+                  version: undefined,
+                  errors: [{ message: err.reason }],
+                }))
+                // Set flag to skip remaining versions - all will have same error
+                versionMismatchDetected = true
+              }),
+              Match.when({ _tag: 'VersionNotFoundInDocumentError' }, () => {
+                // Skip silently - version not found in document
+              }),
+              Match.when({ _tag: 'VersionNotFoundInCatalogError' }, () => {
+                // Skip silently - version not found in catalog
+              }),
+              Match.when({ _tag: 'EmptyCatalogError' }, () => {
+                // Skip silently - catalog has no entries
+              }),
+              Match.exhaustive,
             )
+          },
+          onRight: ({ content, schema }) => {
+            if (schema) {
+              validateDocument(example, schema, content, diagnostics)
+            }
+          },
+        })
+      })
+    } else {
+      // Unversioned document: call without version coverage
+      const result = Document.resolveDocumentAndSchema(
+        example.document,
+        catalog,
+      )
+
+      Either.match(result, {
+        onLeft: () => {
+          // Resolution failed - skip silently
+        },
+        onRight: ({ content, schema }) => {
+          if (schema) {
+            validateDocument(example, schema, content, diagnostics)
           }
-          // Versioned/PartiallyVersioned documents with unversioned catalog don't make sense
-          // These should be caught by other diagnostics
-        }
+        },
+      })
+    }
+  })
 
-        return diagnostics
-      },
-    }),
-  )
+  return diagnostics
 }
 
 // ============================================================================
@@ -105,54 +141,67 @@ export const validateExamples = (
  * Validate a single document and add diagnostics if needed.
  */
 const validateDocument = (
-  exampleName: string,
-  examplePath: string,
-  version: string,
+  example: Example.Example,
+  schema: Schema.Schema,
   content: string,
-  schema: GraphQLSchema,
   diagnostics: ValidationDiagnostic[],
 ): void => {
-  try {
-    // Parse the GraphQL document
-    const document = parse(content)
-
-    // Validate against the schema
-    const errors = validate(schema, document, specifiedRules)
-
-    if (errors.length > 0) {
-      diagnostics.push(makeDiagnosticValidationError({
-        message: formatValidationMessage(exampleName, version, errors),
-        example: { name: exampleName, path: examplePath },
-        version,
-        errors: errors.map(formatGraphQLError),
-      }))
-    }
-  } catch (parseError) {
-    // Parse errors are also validation errors
+  // Extract version from schema (undefined for unversioned)
+  const version = Schema.getVersion(schema)
+
+  // Parse the document safely
+  const parseResult = parseDocumentSafe(content)
+
+  if (Either.isLeft(parseResult)) {
+    // Handle parse errors
+    diagnostics.push(makeDiagnosticValidationError({
+      message: formatParseError(example.name, version),
+      example: { name: example.name, path: example.path },
+      version,
+      errors: [{ message: parseResult.left.message }],
+    }))
+    return
+  }
+
+  // Validate the parsed document against the schema
+  const errors = validate(schema.definition, parseResult.right, specifiedRules)
+
+  if (Array.isNonEmptyReadonlyArray(errors)) {
     diagnostics.push(makeDiagnosticValidationError({
-      message: `Example "${exampleName}" (${version}) has invalid GraphQL syntax`,
-      example: { name: exampleName, path: examplePath },
+      message: formatValidationMessage(example.name, version, errors),
+      example: { name: example.name, path: example.path },
       version,
-      errors: [{ message: String(parseError) }],
+      errors: errors.map(formatGraphQLError),
     }))
   }
 }
 
+/**
+ * Format a parse error message for an example.
+ */
+const formatParseError = (
+  exampleId: string,
+  version: Version.Version | undefined,
+): string => {
+  const versionStr = version ? ` (${Version.encodeSync(version)})` : ''
+  return `Example "${exampleId}"${versionStr} has invalid GraphQL syntax`
+}
+
 /**
  * Format a validation message for an example.
  */
 const formatValidationMessage = (
   exampleId: string,
-  version: string,
-  errors: readonly GraphQLError[],
+  version: Version.Version | undefined,
+  errors: Array.NonEmptyReadonlyArray<GraphQLError>,
 ): string => {
-  const versionStr = version === 'default' ? '' : ` (${version})`
+  const versionStr = version ? ` (${Version.encodeSync(version)})` : ''
   const errorCount = errors.length
   const errorWord = errorCount === 1 ? 'error' : 'errors'
 
-  // Include the first error message for context
-  const firstError = errors[0]
-  const preview = firstError ? `: ${firstError.message}` : ''
+  // Include the first error message for context - always safe with NonEmptyArray
+  const firstError = Array.headNonEmpty(errors)
+  const preview = `: ${firstError.message}`
 
   return `Example "${exampleId}"${versionStr} has ${errorCount} validation ${errorWord}${preview}`
 }
@@ -160,17 +209,13 @@ const formatValidationMessage = (
 /**
  * Format a GraphQL error for diagnostic reporting.
  */
-const formatGraphQLError = (error: GraphQLError): {
-  message: string
-  locations?: Array<{ line: number; column: number }>
-} => ({
-  message: error.message,
-  ...(error.locations
-    ? {
+const formatGraphQLError = (error: GraphQLError): GraphQLErrorData =>
+  GraphQLErrorData.make({
+    message: error.message,
+    ...(error.locations && {
       locations: error.locations.map(loc => ({
         line: loc.line,
         column: loc.column,
       })),
-    }
-    : {}),
-})
+    }),
+  })

package/src/api/examples/filter.ts

@@ -1,3 +1,4 @@
+import { HashSet } from 'effect'
 import type { ExampleName, ExampleSelection } from './config.js'
 import { Example } from './schemas/example/$.js'
 
@@ -28,14 +29,14 @@ export const filterExamplesBySelection = (
 
   // Handle include pattern
   if ('include' in selection) {
-    const includeSet = new Set<ExampleName>(selection.include)
-    return examples.filter(example => includeSet.has(example.name as ExampleName))
+    const includeSet = HashSet.fromIterable(selection.include)
+    return examples.filter(example => HashSet.has(includeSet, example.name as ExampleName))
   }
 
   // Handle exclude pattern
   if ('exclude' in selection) {
-    const excludeSet = new Set<ExampleName>(selection.exclude)
-    return examples.filter(example => !excludeSet.has(example.name as ExampleName))
+    const excludeSet = HashSet.fromIterable(selection.exclude)
+    return examples.filter(example => !HashSet.has(excludeSet, example.name as ExampleName))
   }
 
   // Fallback to all examples if selection pattern is not recognized
@@ -69,12 +70,14 @@ export const shouldDisplayExample = (
 
   // Handle include pattern
   if ('include' in selection) {
-    return selection.include.includes(exampleName)
+    const includeSet = HashSet.fromIterable(selection.include)
+    return HashSet.has(includeSet, exampleName)
   }
 
   // Handle exclude pattern
   if ('exclude' in selection) {
-    return !selection.exclude.includes(exampleName)
+    const excludeSet = HashSet.fromIterable(selection.exclude)
+    return !HashSet.has(excludeSet, exampleName)
   }
 
   // Fallback to show if selection pattern is not recognized