polen 0.11.0-next.2 → 0.11.0-next.21

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

@@ -0,0 +1,322 @@
+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
+})
+
+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

@@ -0,0 +1,221 @@
+import { Catalog as SchemaCatalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { Schema } from '#lib/schema/$'
+import { Version } from '#lib/version/$'
+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'
+import { makeDiagnosticValidationError } from './diagnostic.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+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
+// ============================================================================
+
+/**
+ * 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[] = []
+
+  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)
+          }
+        },
+      })
+    }
+  })
+
+  return diagnostics
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Validate a single document and add diagnostics if needed.
+ */
+const validateDocument = (
+  example: Example.Example,
+  schema: Schema.Schema,
+  content: string,
+  diagnostics: ValidationDiagnostic[],
+): void => {
+  // 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: formatValidationMessage(example.name, version, errors),
+      example: { name: example.name, path: example.path },
+      version,
+      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: Version.Version | undefined,
+  errors: Array.NonEmptyReadonlyArray<GraphQLError>,
+): string => {
+  const versionStr = version ? ` (${Version.encodeSync(version)})` : ''
+  const errorCount = errors.length
+  const errorWord = errorCount === 1 ? 'error' : 'errors'
+
+  // 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}`
+}
+
+/**
+ * Format a GraphQL error for diagnostic reporting.
+ */
+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.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,85 @@
+import { HashSet } from 'effect'
+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 = HashSet.fromIterable(selection.include)
+    return examples.filter(example => HashSet.has(includeSet, example.name as ExampleName))
+  }
+
+  // Handle exclude pattern
+  if ('exclude' in selection) {
+    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
+  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) {
+    const includeSet = HashSet.fromIterable(selection.include)
+    return HashSet.has(includeSet, exampleName)
+  }
+
+  // Handle exclude pattern
+  if ('exclude' in selection) {
+    const excludeSet = HashSet.fromIterable(selection.exclude)
+    return !HashSet.has(excludeSet, exampleName)
+  }
+
+  // Fallback to show if selection pattern is not recognized
+  return true
+}