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

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

@@ -0,0 +1,178 @@
+import { Catalog as SchemaCatalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { Version } from '#lib/version/$'
+import { HashMap, Match, Option } from 'effect'
+import { Array } from 'effect'
+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) => {
+        const schemaVersions = versioned.entries.map(e => e.version)
+
+        for (const example of examples) {
+          Match.value(example.document).pipe(
+            Match.tagsExhaustive({
+              DocumentVersioned: (doc) => {
+                // Validate each version against its corresponding schema
+                for (const entry of versioned.entries) {
+                  const content = Document.Versioned.getContentForVersion(doc, entry.version)
+                  if (content) {
+                    const versionStr = Version.encodeSync(entry.version)
+                    validateDocument(
+                      example.name,
+                      example.path,
+                      versionStr,
+                      content,
+                      entry.definition,
+                      diagnostics,
+                    )
+                  }
+                }
+                return undefined
+              },
+              DocumentUnversioned: (doc) => {
+                const latestEntry = versioned.entries[0]!
+                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
+}

package/src/api/examples/scanner.ts

@@ -0,0 +1,341 @@
+import { Catalog as SchemaCatalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { EffectGlob } from '#lib/effect-glob/$'
+import { VersionCoverage } from '#lib/version-selection/$'
+import { Version } from '#lib/version/$'
+import { FileSystem } from '@effect/platform'
+import { Str } from '@wollybeard/kit'
+import { Effect, HashMap, HashSet, Match } from 'effect'
+import * as Path from 'node:path'
+import type { Diagnostic } from './diagnostic/diagnostic.js'
+import {
+  makeDiagnosticDuplicateContent,
+  makeDiagnosticMissingVersions,
+  makeDiagnosticUnknownVersion,
+  makeDiagnosticUnusedDefault,
+} from './diagnostic/diagnostic.js'
+import { validateExamples } from './diagnostic/validator.js'
+import { Catalog } from './schemas/catalog.js'
+import { Example } from './schemas/example/$.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ScanResult {
+  catalog: Catalog
+  diagnostics: Diagnostic[]
+}
+
+export interface ScanOptions {
+  dir: string
+  extensions?: string[]
+  schemaCatalog?: SchemaCatalog.Catalog
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_EXTENSIONS = ['graphql', 'gql']
+
+// Pattern for versioned files: <name>.<version>.graphql
+const VERSIONED_FILE_PATTERN = Str.pattern<{ groups: ['name', 'version'] }>(
+  /^(?<name>.+?)\.(?<version>.+)$/,
+)
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const parseExampleFilename = (filename: string): { name: string; version: string | null } => {
+  const parsed = Path.parse(filename)
+  const base = parsed.name
+
+  // Try to match versioned pattern: <name>.<version>
+  const match = Str.match(base, VERSIONED_FILE_PATTERN)
+
+  if (match) {
+    const { name, version: versionStr } = match.groups
+
+    // Handle special 'default' keyword
+    if (versionStr === 'default') {
+      return { name, version: 'default' }
+    }
+    const decoded = Version.decodeSync(versionStr)
+    // Return canonical version string
+    return { name, version: Version.encodeSync(decoded) }
+  }
+
+  // No version found - this is an unversioned example
+  return { name: base, version: null }
+}
+
+const groupExampleFiles = (files: string[]): Map<string, Map<string | null, string>> => {
+  const grouped = new Map<string, Map<string | null, string>>()
+
+  for (const file of files) {
+    const { name, version } = parseExampleFilename(file)
+
+    if (!grouped.has(name)) {
+      grouped.set(name, new Map())
+    }
+    grouped.get(name)!.set(version, file)
+  }
+
+  return grouped
+}
+
+const lintFileLayout = (
+  example: Example.Example,
+  schemaCatalog?: SchemaCatalog.Catalog,
+): Diagnostic[] => {
+  // Extract schema versions from catalog if provided
+  const schemaVersions: string[] = schemaCatalog
+    ? SchemaCatalog.fold(
+      (versioned) => versioned.entries.map(entry => Version.encodeSync(entry.version)),
+      (unversioned) => unversioned.schema.revisions?.map(r => r.date) ?? [],
+    )(schemaCatalog)
+    : []
+
+  const diagnostics: Diagnostic[] = []
+
+  Match.value(example.document).pipe(
+    Match.tagsExhaustive({
+      DocumentVersioned: (doc) => {
+        // Get all versions covered by this document
+        const coveredVersions = Document.Versioned.getAllVersions(doc)
+        const coveredVersionStrings = coveredVersions.map(Version.encodeSync)
+        const missingVersions = schemaVersions.filter(sv => !coveredVersionStrings.includes(sv))
+
+        if (missingVersions.length > 0) {
+          diagnostics.push(makeDiagnosticMissingVersions({
+            message: `Versioned example must provide documents for all schema versions`,
+            example: { name: example.name, path: example.path },
+            providedVersions: coveredVersionStrings,
+            missingVersions,
+          }))
+        }
+
+        // Check for duplicate content between selections
+        const entries = Array.from(HashMap.entries(doc.versionDocuments))
+        const duplicates: Array<{ version1: string; version2: string }> = []
+        for (let i = 0; i < entries.length; i++) {
+          for (let j = i + 1; j < entries.length; j++) {
+            const [sel1, content1] = entries[i]!
+            const [sel2, content2] = entries[j]!
+            if (content1 === content2) {
+              duplicates.push({
+                version1: VersionCoverage.toLabel(sel1),
+                version2: VersionCoverage.toLabel(sel2),
+              })
+            }
+          }
+        }
+        if (duplicates.length > 0) {
+          diagnostics.push(makeDiagnosticDuplicateContent({
+            message: `Multiple version selections have identical content, consider combining them`,
+            example: { name: example.name, path: example.path },
+            duplicates,
+          }))
+        }
+      },
+      DocumentUnversioned: () => {
+        // DocumentUnversioned doesn't have version-related diagnostics
+      },
+    }),
+  )
+
+  return diagnostics
+}
+
+// ============================================================================
+// Scanner
+// ============================================================================
+
+export const scan = (
+  options: ScanOptions & { files?: string[] },
+): Effect.Effect<ScanResult, Error, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const extensions = options.extensions ?? DEFAULT_EXTENSIONS
+    const pattern = `**/*.{${extensions.join(',')}}`
+    const files = options.files ?? (yield* EffectGlob.glob(pattern, { cwd: options.dir }))
+
+    // Group files by example
+    const groupedFiles = groupExampleFiles(files)
+
+    // Process each example group
+    const examples: Example.Example[] = []
+    const diagnostics: Diagnostic[] = []
+
+    for (const [name, versions] of groupedFiles) {
+      // Check if this is a versioned or unversioned example
+      const hasMultipleVersions = versions.size > 1
+      const hasUnversionedFile = versions.has(null)
+      const hasDefaultFile = versions.has('default')
+      const hasOnlyDefaultFile = hasDefaultFile && versions.size === 1
+
+      // Determine the base path for this example
+      const firstFilePath = Array.from(versions.values())[0]!
+      const basePath = versions.size === 1
+        ? firstFilePath
+        : Path.dirname(firstFilePath)
+
+      let example: Example.Example
+
+      if (hasUnversionedFile && versions.size === 1) {
+        // Unversioned example - single file with no version
+        const filePath = versions.get(null)!
+        const fullPath = Path.join(options.dir, filePath)
+        const document = yield* fs.readFileString(fullPath)
+
+        example = Example.make({
+          name,
+          path: basePath,
+          document: Document.Unversioned.make({
+            document,
+          }),
+        })
+      } else if (hasOnlyDefaultFile) {
+        // Only default file - create versioned document with all schema versions as a set
+        const filePath = versions.get('default')!
+        const fullPath = Path.join(options.dir, filePath)
+        const documentContent = yield* fs.readFileString(fullPath)
+
+        // Get all schema versions to map to this default document
+        const schemaVersions: Version.Version[] = options.schemaCatalog
+          ? SchemaCatalog.fold(
+            (versioned) => versioned.entries.map(entry => entry.version),
+            () => [], // Unversioned schemas don't have version-specific examples
+          )(options.schemaCatalog)
+          : []
+
+        if (schemaVersions.length > 0) {
+          // Create a version set for all schema versions
+          const versionSet = HashSet.fromIterable(schemaVersions)
+          let versionDocuments = HashMap.empty<VersionCoverage.VersionCoverage, string>()
+          versionDocuments = HashMap.set(versionDocuments, versionSet, documentContent)
+
+          example = Example.make({
+            name,
+            path: basePath,
+            document: Document.Versioned.make({
+              versionDocuments,
+            }),
+          })
+        } else {
+          // No schema versions, treat as unversioned
+          example = Example.make({
+            name,
+            path: basePath,
+            document: Document.Unversioned.make({
+              document: documentContent,
+            }),
+          })
+        }
+      } else {
+        // Versioned example - multiple files or versioned files
+        let versionDocuments = HashMap.empty<VersionCoverage.VersionCoverage, string>()
+        let defaultDocument: string | undefined
+        const explicitVersions = new Set<string>() // Track which versions have explicit files
+        const unknownVersions: string[] = []
+
+        // Get available schema versions if catalog is provided
+        const schemaVersions: string[] = options.schemaCatalog
+          ? SchemaCatalog.fold(
+            (versioned) => versioned.entries.map(entry => Version.encodeSync(entry.version)),
+            () => [], // Unversioned schemas don't have version-specific examples
+          )(options.schemaCatalog)
+          : []
+
+        // Read content for each version
+        for (const [version, filePath] of versions) {
+          const fullPath = Path.join(options.dir, filePath)
+          const fileContent = yield* fs.readFileString(fullPath)
+
+          if (version === 'default') {
+            defaultDocument = fileContent
+          } else if (version !== null) {
+            // Check if this version exists in the schema
+            if (options.schemaCatalog && schemaVersions.length > 0 && !schemaVersions.includes(version)) {
+              unknownVersions.push(version)
+              // Create diagnostic for unknown version
+              diagnostics.push(makeDiagnosticUnknownVersion({
+                message: `Example "${name}" specifies version "${version}" which does not exist in the schema`,
+                example: { name, path: basePath },
+                version,
+                availableVersions: schemaVersions,
+              }))
+              // Skip this version - don't include it in the example
+              continue
+            }
+
+            const versionObj = Version.decodeSync(version)
+            versionDocuments = HashMap.set(versionDocuments, versionObj, fileContent)
+            explicitVersions.add(version)
+          }
+        }
+
+        if (defaultDocument) {
+          // If we have a default, determine which versions it applies to
+          const defaultVersions = schemaVersions.filter(v => !explicitVersions.has(v))
+
+          if (defaultVersions.length > 0) {
+            // Create a version set for the default document
+            const defaultVersionSet = defaultVersions.length === 1
+              ? Version.decodeSync(defaultVersions[0]!) // Single version
+              : HashSet.fromIterable(defaultVersions.map(_ => Version.decodeSync(_))) // Version set
+
+            versionDocuments = HashMap.set(versionDocuments, defaultVersionSet, defaultDocument)
+          }
+        }
+
+        if (HashMap.size(versionDocuments) > 0) {
+          // Create versioned document
+          example = Example.make({
+            name,
+            path: basePath,
+            document: Document.Versioned.make({
+              versionDocuments,
+            }),
+          })
+        } else if (unknownVersions.length > 0) {
+          // All versions were unknown, skip this example entirely
+          continue
+        } else {
+          // No versions at all - shouldn't happen
+          continue
+        }
+      }
+
+      if (example) {
+        examples.push(example)
+        // Generate diagnostics for this example
+        diagnostics.push(...lintFileLayout(example, options.schemaCatalog))
+      }
+    }
+
+    // Perform validation if catalog is provided
+    if (options.schemaCatalog) {
+      diagnostics.push(...validateExamples(examples, options.schemaCatalog))
+    }
+
+    // @claude create a utility for reading a file at variable paths
+    // Check for index.md or index.mdx file
+    const indexMdPath = Path.join(options.dir, 'index.md')
+    const indexMdxPath = Path.join(options.dir, 'index.mdx')
+
+    // Try index.md first, then index.mdx
+    const indexPath = (yield* fs.exists(indexMdPath))
+      ? indexMdPath
+      : (yield* fs.exists(indexMdxPath))
+      ? indexMdxPath
+      : null
+
+    const catalog = Catalog.make({
+      examples,
+      index: indexPath ? { path: indexPath } : undefined,
+    })
+    return { catalog, diagnostics }
+  })