polen 0.11.0-next.15 → 0.11.0-next.16

package/src/api/examples/config.ts

@@ -0,0 +1,242 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Global Interface for Type Augmentation
+// ============================================================================
+
+declare global {
+  namespace PolenGlobal {
+    /**
+     * Global interface for type-safe example selection.
+     * This interface is augmented by the type generator with discovered example names.
+     */
+    interface Examples {
+      /**
+       * Fallback generic example names for when types haven't been generated yet.
+       * This allows the code to compile even without generated types.
+       */
+      readonly namesGeneric: readonly string[]
+    }
+  }
+}
+
+// ============================================================================
+// Type Helpers
+// ============================================================================
+
+/**
+ * Get example names with fallback to generic if not generated yet.
+ * Prefers the generated 'names' property if it exists, otherwise falls back to 'namesGeneric'.
+ */
+export type GetExampleNames<$Examples = PolenGlobal.Examples> = $Examples extends { names: infer N } ? N
+  : $Examples extends { namesGeneric: infer G } ? G
+  : never
+
+/**
+ * Type-safe example names that work with or without generation.
+ */
+export type AvailableExampleNames = GetExampleNames
+
+// ============================================================================
+// Schema - Example Selection
+// ============================================================================
+
+/**
+ * Schema for example names that provides type-safety at compile time
+ * while accepting any string at runtime for flexibility.
+ */
+export const ExampleName = S.transform(
+  S.String,
+  S.String.pipe(S.annotations({
+    identifier: 'ExampleName',
+    description: 'Name of an example',
+  })),
+  {
+    strict: false,
+    decode: (s) => s as any as AvailableExampleNames,
+    encode: (s) => s,
+  },
+)
+
+export type ExampleName = S.Schema.Type<typeof ExampleName>
+
+/**
+ * Example selection configuration supporting both include and exclude patterns.
+ */
+export const ExampleSelection = S.optional(
+  S.Union(
+    S.Literal('all'),
+    S.Literal('none'),
+    S.Struct({
+      /**
+       * Examples to include. If specified, only these examples will be shown.
+       */
+      include: S.Array(ExampleName),
+    }).annotations({
+      identifier: 'ExampleSelectionInclude',
+      description: 'Include specific examples',
+    }),
+    S.Struct({
+      /**
+       * Examples to exclude. All other examples will be shown.
+       */
+      exclude: S.Array(ExampleName),
+    }).annotations({
+      identifier: 'ExampleSelectionExclude',
+      description: 'Exclude specific examples',
+    }),
+  ),
+).annotations({
+  identifier: 'ExampleSelection',
+  title: 'Example Selection',
+  description: 'Configuration for selecting which examples to display',
+})
+
+export type ExampleSelection = S.Schema.Type<typeof ExampleSelection>
+
+// ============================================================================
+// Schema - Example Diagnostics
+// ============================================================================
+
+/**
+ * Diagnostic controls for example scanning and validation.
+ */
+const ExampleDiagnostics = S.Struct({
+  /**
+   * Control validation of GraphQL documents against the schema.
+   *
+   * @default true (warns in dev, errors in build)
+   */
+  validation: S.optional(S.Union(S.Boolean, Diagnostic.Control)),
+
+  /**
+   * Control warnings about unused default versions when versioned files exist.
+   *
+   * @default true (info in dev, warning in build)
+   */
+  unusedVersions: S.optional(S.Union(S.Boolean, Diagnostic.Control)),
+
+  /**
+   * Control detection of duplicate content across versions.
+   *
+   * @default true in dev only
+   */
+  duplicateContent: S.optional(S.Union(S.Boolean, Diagnostic.Control)),
+
+  /**
+   * Control warnings about missing versions for examples.
+   *
+   * @default true (info in dev, warning in build)
+   */
+  missingVersions: S.optional(S.Union(S.Boolean, Diagnostic.Control)),
+}).annotations({
+  identifier: 'ExampleDiagnostics',
+  description: 'Diagnostic controls for example scanning and validation',
+})
+
+export type ExampleDiagnostics = S.Schema.Type<typeof ExampleDiagnostics>
+
+// ============================================================================
+// Schema - Examples Config
+// ============================================================================
+
+export const ExamplesConfig = S.Struct({
+  /**
+   * Control whether the examples feature is enabled.
+   * - true: Always enabled (show in nav even if no examples exist)
+   * - false: Always disabled (hide even if examples files exist)
+   * - undefined: Auto-detect based on file presence (default behavior)
+   *
+   * @default undefined (auto-detect)
+   * @example
+   * ```ts
+   * // Always show examples section
+   * examples: { enabled: true }
+   *
+   * // Never show examples
+   * examples: { enabled: false }
+   *
+   * // Auto-detect (default)
+   * examples: { /* enabled not specified *\/ }
+   * ```
+   */
+  enabled: S.optional(S.Boolean),
+
+  /**
+   * Control which examples are available in the application.
+   *
+   * @default 'all'
+   * @example
+   * ```ts
+   * // Show all examples
+   * examples: { display: 'all' }
+   *
+   * // Show no examples
+   * examples: { display: 'none' }
+   *
+   * // Show specific examples (type-safe with generated types)
+   * examples: {
+   *   display: {
+   *     include: ['get-user', 'create-post']
+   *   }
+   * }
+   *
+   * // Exclude specific examples
+   * examples: {
+   *   display: {
+   *     exclude: ['advanced-filtering']
+   *   }
+   * }
+   * ```
+   */
+  display: ExampleSelection,
+
+  /**
+   * Diagnostic controls for examples.
+   * Can be a simple boolean for all diagnostics, or fine-grained control per diagnostic type.
+   *
+   * @example
+   * ```ts
+   * // Enable all diagnostics with defaults
+   * diagnostics: {
+   *   validation: true
+   * }
+   *
+   * // Fine-grained control
+   * diagnostics: {
+   *   validation: {
+   *     enabled: true,
+   *     dev: { enabled: true, severity: 'warning' },
+   *     build: { enabled: true, severity: 'error' }
+   *   }
+   * }
+   * ```
+   */
+  diagnostics: S.optional(ExampleDiagnostics),
+}).annotations({
+  identifier: 'ExamplesConfig',
+  title: 'Examples Configuration',
+  description: 'Configuration for GraphQL examples behavior and diagnostics',
+})
+
+export type ExamplesConfig = S.Schema.Type<typeof ExamplesConfig>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const makeExamplesConfig = ExamplesConfig.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const isExamplesConfig = S.is(ExamplesConfig)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decodeExamplesConfig = S.decode(ExamplesConfig)
+export const encodeExamplesConfig = S.encode(ExamplesConfig)

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

@@ -0,0 +1,30 @@
+import { DiagnosticDuplicateContent } from '#api/examples/diagnostic/duplicate-content'
+import { DiagnosticInvalidFilename } from '#api/examples/diagnostic/invalid-filename'
+import { DiagnosticMissingVersions } from '#api/examples/diagnostic/missing-versions'
+import { DiagnosticUnknownVersion } from '#api/examples/diagnostic/unknown-version'
+import { DiagnosticUnusedDefault } from '#api/examples/diagnostic/unused-default'
+import { DiagnosticValidationError } from '#api/examples/diagnostic/validation-error'
+import { S } from '#lib/kit-temp/effect'
+
+// Re-export all individual diagnostics
+export * from './duplicate-content.js'
+export * from './invalid-filename.js'
+export * from './missing-versions.js'
+export * from './unknown-version.js'
+export * from './unused-default.js'
+export * from './validation-error.js'
+export { validateExamples } from './validator.js'
+
+export const Diagnostic = S.Union(
+  DiagnosticUnusedDefault,
+  DiagnosticDuplicateContent,
+  DiagnosticMissingVersions,
+  DiagnosticInvalidFilename,
+  DiagnosticUnknownVersion,
+  DiagnosticValidationError,
+).annotations({
+  identifier: 'ExamplesDiagnostic',
+  description: 'All diagnostics that can be generated for examples',
+})
+
+export type Diagnostic = S.Schema.Type<typeof Diagnostic>

package/src/api/examples/diagnostic/duplicate-content.ts

@@ -0,0 +1,25 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+export const DiagnosticDuplicateContent = Diagnostic.create({
+  source: 'examples-scanner',
+  name: 'duplicate-content',
+  severity: 'info',
+  context: {
+    example: S.Struct({
+      name: S.String,
+      path: S.String,
+    }),
+    duplicates: S.Array(S.Struct({
+      version1: S.String,
+      version2: S.String,
+    })),
+  },
+}).annotations({
+  identifier: 'DiagnosticDuplicateContent',
+  description: 'Multiple versions of an example have identical content',
+})
+
+export const makeDiagnosticDuplicateContent = Diagnostic.createMake(DiagnosticDuplicateContent)
+
+export type DiagnosticDuplicateContent = S.Schema.Type<typeof DiagnosticDuplicateContent>

package/src/api/examples/diagnostic/invalid-filename.ts

@@ -0,0 +1,19 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+export const DiagnosticInvalidFilename = Diagnostic.create({
+  source: 'examples-scanner',
+  name: 'invalid-filename',
+  severity: 'error',
+  context: {
+    file: S.String,
+    reason: S.String,
+  },
+}).annotations({
+  identifier: 'DiagnosticInvalidFilename',
+  description: 'Example file has an invalid filename pattern',
+})
+
+export const makeDiagnosticInvalidFilename = Diagnostic.createMake(DiagnosticInvalidFilename)
+
+export type DiagnosticInvalidFilename = S.Schema.Type<typeof DiagnosticInvalidFilename>

package/src/api/examples/diagnostic/missing-versions.ts

@@ -0,0 +1,23 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+export const DiagnosticMissingVersions = Diagnostic.create({
+  source: 'examples-scanner',
+  name: 'missing-versions',
+  severity: 'info',
+  context: {
+    example: S.Struct({
+      name: S.String,
+      path: S.String,
+    }),
+    providedVersions: S.Array(S.String),
+    missingVersions: S.Array(S.String),
+  },
+}).annotations({
+  identifier: 'DiagnosticMissingVersions',
+  description: 'Example does not have explicit versions for all schema versions',
+})
+
+export const makeDiagnosticMissingVersions = Diagnostic.createMake(DiagnosticMissingVersions)
+
+export type DiagnosticMissingVersions = S.Schema.Type<typeof DiagnosticMissingVersions>

package/src/api/examples/diagnostic/unknown-version.ts

@@ -0,0 +1,23 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+export const DiagnosticUnknownVersion = Diagnostic.create({
+  source: 'examples-scanner',
+  name: 'unknown-version',
+  severity: 'error',
+  context: {
+    example: S.Struct({
+      name: S.String,
+      path: S.String,
+    }),
+    version: S.String,
+    availableVersions: S.Array(S.String),
+  },
+}).annotations({
+  identifier: 'DiagnosticUnknownVersion',
+  description: 'Example specifies a version that does not exist in the API',
+})
+
+export const makeDiagnosticUnknownVersion = Diagnostic.createMake(DiagnosticUnknownVersion)
+
+export type DiagnosticUnknownVersion = S.Schema.Type<typeof DiagnosticUnknownVersion>

package/src/api/examples/diagnostic/unused-default.ts

@@ -0,0 +1,22 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+export const DiagnosticUnusedDefault = Diagnostic.create({
+  source: 'examples-scanner',
+  name: 'unused-default',
+  severity: 'warning',
+  context: {
+    example: S.Struct({
+      name: S.String,
+      path: S.String,
+    }),
+    versions: S.Array(S.String),
+  },
+}).annotations({
+  identifier: 'DiagnosticUnusedDefault',
+  description: 'Default example file that is never used because explicit versions exist for all schema versions',
+})
+
+export const makeDiagnosticUnusedDefault = Diagnostic.createMake(DiagnosticUnusedDefault)
+
+export type DiagnosticUnusedDefault = S.Schema.Type<typeof DiagnosticUnusedDefault>

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

@@ -0,0 +1,24 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { GraphQLError } from '#lib/graphql-error/$'
+import { S } from '#lib/kit-temp/effect'
+
+export const DiagnosticValidationError = Diagnostic.create({
+  source: 'examples-validation',
+  name: 'invalid-graphql',
+  severity: 'error', // Will be overridden based on config
+  context: {
+    example: S.Struct({
+      name: S.String,
+      path: S.String,
+    }),
+    version: S.String,
+    errors: S.Array(GraphQLError.GraphQLError),
+  },
+}).annotations({
+  identifier: 'DiagnosticValidationError',
+  description: 'GraphQL document validation error against the schema',
+})
+
+export const makeDiagnosticValidationError = Diagnostic.createMake(DiagnosticValidationError)
+
+export type DiagnosticValidationError = S.Schema.Type<typeof DiagnosticValidationError>

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

@@ -0,0 +1,277 @@
+import { Catalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { Version } from '#lib/version/$'
+import { HashMap, HashSet } from 'effect'
+import { buildSchema } from 'graphql'
+import { expect, test } from 'vitest'
+import { Example } from '../schemas/example/example.js'
+import { validateExamples } from './validator.js'
+
+const schema = buildSchema(`
+  type Query {
+    user(id: ID!): User
+    users: [User!]!
+  }
+  type User {
+    id: ID!
+    name: String!
+    email: String
+  }
+`)
+
+// Create an unversioned catalog for testing
+const catalog = Catalog.Unversioned.make({
+  schema: {
+    _tag: 'SchemaUnversioned',
+    revisions: [],
+    definition: schema,
+  },
+})
+
+// Create a versioned catalog for versioned tests
+const versionedCatalogForTests = Catalog.Versioned.make({
+  entries: [
+    {
+      _tag: 'SchemaVersioned',
+      version: Version.fromString('v1'),
+      definition: schema,
+      branchPoint: null,
+      revisions: [],
+    },
+    {
+      _tag: 'SchemaVersioned',
+      version: Version.fromString('v2'),
+      definition: schema,
+      branchPoint: null,
+      revisions: [],
+    },
+  ],
+})
+
+test.for([
+  {
+    name: 'valid query returns no diagnostics',
+    examples: [Example.make({
+      name: 'test',
+      path: 'test.graphql',
+      document: Document.Unversioned.make({
+        document: 'query { user(id: "1") { id name } }',
+      }),
+    })],
+    expectedDiagnostics: 0,
+  },
+  {
+    name: 'field that does not exist',
+    examples: [Example.make({
+      name: 'test',
+      path: 'test.graphql',
+      document: Document.Unversioned.make({
+        document: 'query { user(id: "1") { id name nonExistentField } }',
+      }),
+    })],
+    expectedDiagnostics: 1,
+    errorContains: 'Cannot query field',
+  },
+  {
+    name: 'missing required argument',
+    examples: [Example.make({
+      name: 'test',
+      path: 'test.graphql',
+      document: Document.Unversioned.make({
+        document: 'query { user { id name } }',
+      }),
+    })],
+    expectedDiagnostics: 1,
+    errorContains: 'argument "id" of type "ID!" is required',
+  },
+  {
+    name: 'invalid GraphQL syntax',
+    examples: [Example.make({
+      name: 'test',
+      path: 'test.graphql',
+      document: Document.Unversioned.make({
+        document: 'query { user(id: "1") {{ id name } }',
+      }),
+    })],
+    expectedDiagnostics: 1,
+    messageContains: 'invalid GraphQL syntax',
+  },
+  {
+    name: 'versioned example validates all versions',
+    examples: [Example.make({
+      name: 'test',
+      path: 'test.graphql',
+      document: Document.Versioned.make({
+        versionDocuments: HashMap.make(
+          [Version.fromString('v1'), 'query { user(id: "1") { id name } }'],
+          [Version.fromString('v2'), 'query { user(id: "1") { id name invalidField } }'],
+        ),
+      }),
+    })],
+    expectedDiagnostics: 1,
+    version: 'v2',
+  },
+  {
+    name: 'multiple examples with mixed validity',
+    examples: [
+      Example.make({
+        name: 'valid',
+        path: 'valid.graphql',
+        document: Document.Unversioned.make({
+          document: 'query { users { id name } }',
+        }),
+      }),
+      Example.make({
+        name: 'invalid',
+        path: 'invalid.graphql',
+        document: Document.Unversioned.make({
+          document: 'query { unknownField }',
+        }),
+      }),
+    ],
+    expectedDiagnostics: 1,
+    errorContains: 'Cannot query field',
+  },
+])('%s', ({ examples, expectedDiagnostics, errorContains, messageContains }) => {
+  // Use versioned catalog if any example is versioned
+  const hasVersionedExample = examples.some(e => e.document._tag === 'DocumentVersioned')
+  const catalogToUse = hasVersionedExample ? versionedCatalogForTests : catalog
+
+  const diagnostics = validateExamples(examples, catalogToUse)
+  expect(diagnostics.length).toBe(expectedDiagnostics)
+
+  if (errorContains) {
+    expect(diagnostics.some(d => d.errors?.some(e => e.message.includes(errorContains)))).toBe(true)
+  }
+
+  if (messageContains) {
+    expect(diagnostics.some(d => d.message.includes(messageContains))).toBe(true)
+  }
+})
+
+test('validates versioned catalog with multiple schemas', () => {
+  const v1Schema = buildSchema(`
+    type Query {
+      user(id: ID!): User
+    }
+    type User {
+      id: ID!
+      name: String!
+    }
+  `)
+
+  const v2Schema = buildSchema(`
+    type Query {
+      user(id: ID!): User
+      users: [User!]!
+    }
+    type User {
+      id: ID!
+      name: String!
+      email: String
+    }
+  `)
+
+  const versionedCatalog = Catalog.Versioned.make({
+    entries: [
+      {
+        _tag: 'SchemaVersioned',
+        version: Version.fromString('1.0.0'),
+        revisions: [],
+        definition: v1Schema,
+        branchPoint: null,
+      },
+      {
+        _tag: 'SchemaVersioned',
+        version: Version.fromString('2.0.0'),
+        revisions: [],
+        definition: v2Schema,
+        branchPoint: null,
+      },
+    ],
+  })
+
+  const v1 = Version.fromString('1.0.0')
+  const v2 = Version.fromString('2.0.0')
+  const defaultVersions = HashSet.make(v1)
+
+  const examples = [
+    Example.make({
+      name: 'test-version-sets',
+      path: 'test.graphql',
+      document: Document.Versioned.make({
+        versionDocuments: HashMap.make(
+          [defaultVersions, 'query { user(id: "1") { id name } }'],
+          [v2, 'query { users { id name email } }'],
+        ),
+      }),
+    }),
+  ]
+
+  const diagnostics = validateExamples(examples, versionedCatalog)
+  expect(diagnostics.length).toBe(0) // Both queries should be valid for their versions
+})
+
+test('validates examples against unversioned catalog', () => {
+  const examples = [
+    Example.make({
+      name: 'test-unversioned',
+      path: 'test.graphql',
+      document: Document.Unversioned.make({
+        document: 'query { user(id: "1") { id name } }',
+      }),
+    }),
+  ]
+
+  const diagnostics = validateExamples(examples, catalog)
+  expect(diagnostics.length).toBe(0)
+})
+
+test('validates examples with version sets', () => {
+  const v1 = Version.fromString('v1')
+  const v2 = Version.fromString('v2')
+  const versionSet = HashSet.make(v1, v2)
+
+  const examples = [
+    Example.make({
+      name: 'test-version-sets',
+      path: 'test.graphql',
+      document: Document.Versioned.make({
+        versionDocuments: HashMap.make(
+          [versionSet, 'query { user(id: "1") { id name } }'],
+          [Version.fromString('v3'), 'query { user(id: "1") { id name invalidField } }'],
+        ),
+      }),
+    }),
+  ]
+
+  // Create catalog with v1, v2, v3 versions
+  const versionedCatalogWithV3 = Catalog.Versioned.make({
+    entries: [
+      {
+        _tag: 'SchemaVersioned',
+        version: v1,
+        definition: schema,
+        branchPoint: null,
+        revisions: [],
+      },
+      {
+        _tag: 'SchemaVersioned',
+        version: v2,
+        definition: schema,
+        branchPoint: null,
+        revisions: [],
+      },
+      {
+        _tag: 'SchemaVersioned',
+        version: Version.fromString('v3'),
+        definition: schema,
+        branchPoint: null,
+        revisions: [],
+      },
+    ],
+  })
+
+  const diagnostics = validateExamples(examples, versionedCatalogWithV3)
+  expect(diagnostics.length).toBe(1) // invalidField doesn't exist in the test schema
+})