polen 0.11.0-next.15 → 0.11.0-next.17

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

@@ -0,0 +1,292 @@
+import { Catalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { Schema } from '#lib/schema/$'
+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: HashMap.make(
+    [
+      Version.fromString('v1'),
+      Schema.Versioned.make({
+        version: Version.fromString('v1'),
+        definition: schema,
+        branchPoint: null,
+        revisions: [],
+      }),
+    ],
+    [
+      Version.fromString('v2'),
+      Schema.Versioned.make({
+        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: HashMap.make(
+      [
+        Version.fromString('1.0.0'),
+        Schema.Versioned.make({
+          version: Version.fromString('1.0.0'),
+          revisions: [],
+          definition: v1Schema,
+          branchPoint: null,
+        }),
+      ],
+      [
+        Version.fromString('2.0.0'),
+        Schema.Versioned.make({
+          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: HashMap.make(
+      [
+        v1,
+        Schema.Versioned.make({
+          version: v1,
+          definition: schema,
+          branchPoint: null,
+          revisions: [],
+        }),
+      ],
+      [
+        v2,
+        Schema.Versioned.make({
+          version: v2,
+          definition: schema,
+          branchPoint: null,
+          revisions: [],
+        }),
+      ],
+      [
+        Version.fromString('v3'),
+        Schema.Versioned.make({
+          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
+})

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

@@ -0,0 +1,176 @@
+import { Catalog as SchemaCatalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { Version } from '#lib/version/$'
+import { Match } from 'effect'
+import { HashMap } from 'effect/Schema'
+import type { GraphQLError, GraphQLSchema } from 'graphql'
+import { parse, specifiedRules, validate } from 'graphql'
+import { Example } from '../schemas/example/$.js'
+import type { DiagnosticValidationError } from './diagnostic.js'
+import { makeDiagnosticValidationError } from './diagnostic.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ValidationDiagnostic = DiagnosticValidationError
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate examples against a schema catalog.
+ *
+ * @param examples - The examples to validate
+ * @param catalog - The schema catalog containing versioned or unversioned schemas
+ * @returns Array of validation diagnostics
+ */
+export const validateExamples = (
+  examples: Example.Example[],
+  catalog: SchemaCatalog.Catalog,
+): 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,
+            )
+          }
+          // Versioned/PartiallyVersioned documents with unversioned catalog don't make sense
+          // These should be caught by other diagnostics
+        }
+
+        return diagnostics
+      },
+    }),
+  )
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Validate a single document and add diagnostics if needed.
+ */
+const validateDocument = (
+  exampleName: string,
+  examplePath: string,
+  version: string,
+  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
+    diagnostics.push(makeDiagnosticValidationError({
+      message: `Example "${exampleName}" (${version}) has invalid GraphQL syntax`,
+      example: { name: exampleName, path: examplePath },
+      version,
+      errors: [{ message: String(parseError) }],
+    }))
+  }
+}
+
+/**
+ * Format a validation message for an example.
+ */
+const formatValidationMessage = (
+  exampleId: string,
+  version: string,
+  errors: readonly GraphQLError[],
+): string => {
+  const versionStr = version === 'default' ? '' : ` (${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}` : ''
+
+  return `Example "${exampleId}"${versionStr} has ${errorCount} validation ${errorWord}${preview}`
+}
+
+/**
+ * Format a GraphQL error for diagnostic reporting.
+ */
+const formatGraphQLError = (error: GraphQLError): {
+  message: string
+  locations?: Array<{ line: number; column: number }>
+} => ({
+  message: error.message,
+  ...(error.locations
+    ? {
+      locations: error.locations.map(loc => ({
+        line: loc.line,
+        column: loc.column,
+      })),
+    }
+    : {}),
+})

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

@@ -0,0 +1,56 @@
+import { Document } from '#lib/document/$'
+import { describe, expect, test } from 'vitest'
+import type { ExampleName, ExampleSelection } from './config.js'
+import { filterExamplesBySelection, shouldDisplayExample } from './filter.js'
+import { Example } from './schemas/example/$.js'
+
+describe('filterExamplesBySelection', () => {
+  const examples = [
+    Example.make({
+      name: 'a',
+      path: 'a.graphql',
+      document: Document.Unversioned.make({ document: 'a' }),
+    }),
+    Example.make({
+      name: 'b',
+      path: 'b.graphql',
+      document: Document.Unversioned.make({ document: 'b' }),
+    }),
+    Example.make({
+      name: 'c',
+      path: 'c.graphql',
+      document: Document.Unversioned.make({ document: 'c' }),
+    }),
+  ]
+
+  test.for([
+    { selection: undefined, expected: ['a', 'b', 'c'] },
+    { selection: 'all', expected: ['a', 'b', 'c'] },
+    { selection: 'none', expected: [] },
+    { selection: { include: ['a', 'b'] }, expected: ['a', 'b'] },
+    { selection: { include: [] }, expected: [] },
+    { selection: { exclude: ['c'] }, expected: ['a', 'b'] },
+    { selection: { exclude: [] }, expected: ['a', 'b', 'c'] },
+    { selection: { include: ['a', 'non-existent'] }, expected: ['a'] },
+    { selection: { exclude: ['c', 'non-existent'] }, expected: ['a', 'b'] },
+  ])('selection $selection returns $expected', ({ selection, expected }) => {
+    const result = filterExamplesBySelection(examples, selection as ExampleSelection)
+    expect(result.map(e => e.name)).toEqual(expected)
+  })
+})
+
+describe('shouldDisplayExample', () => {
+  test.for([
+    { name: 'x' as ExampleName, selection: undefined, expected: true },
+    { name: 'x' as ExampleName, selection: 'all', expected: true },
+    { name: 'x' as ExampleName, selection: 'none', expected: false },
+    { name: 'x' as ExampleName, selection: { include: ['x'] }, expected: true },
+    { name: 'x' as ExampleName, selection: { include: ['y'] }, expected: false },
+    { name: 'x' as ExampleName, selection: { include: [] }, expected: false },
+    { name: 'x' as ExampleName, selection: { exclude: ['x'] }, expected: false },
+    { name: 'x' as ExampleName, selection: { exclude: ['y'] }, expected: true },
+    { name: 'x' as ExampleName, selection: { exclude: [] }, expected: true },
+  ])('name "$name" with selection $selection returns $expected', ({ name, selection, expected }) => {
+    expect(shouldDisplayExample(name, selection as ExampleSelection)).toBe(expected)
+  })
+})

package/src/api/examples/filter.ts

@@ -0,0 +1,82 @@
+import type { ExampleName, ExampleSelection } from './config.js'
+import { Example } from './schemas/example/$.js'
+
+/**
+ * Filter examples based on the display configuration.
+ *
+ * @param examples - All available examples
+ * @param selection - The display configuration
+ * @returns Filtered examples based on the selection criteria
+ */
+export const filterExamplesBySelection = (
+  examples: Example.Example[],
+  selection: ExampleSelection | undefined,
+): Example.Example[] => {
+  // If no selection config, default to all
+  if (selection === undefined) {
+    return examples
+  }
+
+  // Handle string literals
+  if (selection === 'all') {
+    return examples
+  }
+
+  if (selection === 'none') {
+    return []
+  }
+
+  // Handle include pattern
+  if ('include' in selection) {
+    const includeSet = new Set<ExampleName>(selection.include)
+    return examples.filter(example => includeSet.has(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))
+  }
+
+  // Fallback to all examples if selection pattern is not recognized
+  return examples
+}
+
+/**
+ * Check if an example should be displayed based on the selection criteria.
+ *
+ * @param exampleName - The ID of the example to check
+ * @param selection - The display configuration
+ * @returns Whether the example should be displayed
+ */
+export const shouldDisplayExample = (
+  exampleName: ExampleName,
+  selection: ExampleSelection | undefined,
+): boolean => {
+  // If no selection config, default to show
+  if (selection === undefined) {
+    return true
+  }
+
+  // Handle string literals
+  if (selection === 'all') {
+    return true
+  }
+
+  if (selection === 'none') {
+    return false
+  }
+
+  // Handle include pattern
+  if ('include' in selection) {
+    return selection.include.includes(exampleName)
+  }
+
+  // Handle exclude pattern
+  if ('exclude' in selection) {
+    return !selection.exclude.includes(exampleName)
+  }
+
+  // Fallback to show if selection pattern is not recognized
+  return true
+}