polen 0.11.0-next.2 → 0.11.0-next.20

package/src/api/examples/scanner.ts

@@ -0,0 +1,365 @@
+import { Catalog as SchemaCatalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { EffectGlob } from '#lib/effect-glob/$'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Version } from '#lib/version/$'
+import { FileSystem } from '@effect/platform'
+import { Str } from '@wollybeard/kit'
+import { Array, Effect, HashMap, HashSet, Match } from 'effect'
+import * as Path from 'node:path'
+import type { Diagnostic } from './diagnostic/diagnostic.js'
+import {
+  makeDiagnosticDuplicateContent,
+  makeDiagnosticMissingVersions,
+  makeDiagnosticUnknownVersion,
+} 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>.+)$/,
+)
+
+// ============================================================================
+// File Parsing Types
+// ============================================================================
+
+type ParsedExampleFile =
+  | { type: 'unversioned'; name: string; file: string }
+  | { type: 'versioned'; name: string; version: Version.Version; file: string }
+  | { type: 'default'; name: string; file: string }
+
+type GroupedExampleFiles = Map<string, {
+  unversioned?: string
+  versioned: Map<Version.Version, string>
+  default?: string
+}>
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const parseExampleFile = (filename: string): ParsedExampleFile => {
+  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 { type: 'default', name, file: filename }
+    }
+
+    const version = Version.decodeSync(versionStr)
+    return { type: 'versioned', name, version, file: filename }
+  }
+
+  // No version found - this is an unversioned example
+  return { type: 'unversioned', name: base, file: filename }
+}
+
+const groupExampleFiles = (files: string[]): GroupedExampleFiles => {
+  const grouped: GroupedExampleFiles = new Map()
+
+  for (const file of files) {
+    const parsed = parseExampleFile(file)
+
+    if (!grouped.has(parsed.name)) {
+      grouped.set(parsed.name, {
+        versioned: new Map(),
+      })
+    }
+
+    const group = grouped.get(parsed.name)!
+
+    switch (parsed.type) {
+      case 'unversioned':
+        group.unversioned = parsed.file
+        break
+      case 'versioned':
+        group.versioned.set(parsed.version, parsed.file)
+        break
+      case 'default':
+        group.default = parsed.file
+        break
+    }
+  }
+
+  return grouped
+}
+
+/**
+ * Resolve .default files into proper version coverage.
+ * This erases the .default convention and converts it to semantic version sets.
+ */
+const resolveDefaultFiles = (
+  grouped: GroupedExampleFiles,
+  schemaVersions: Version.Version[],
+): Map<string, {
+  versionDocuments: HashMap.HashMap<VersionCoverage.VersionCoverage, string>
+  unversioned?: string
+}> => {
+  const resolved = new Map<string, {
+    versionDocuments: HashMap.HashMap<VersionCoverage.VersionCoverage, string>
+    unversioned?: string
+  }>()
+
+  for (const [name, group] of grouped) {
+    let versionDocuments = HashMap.empty<VersionCoverage.VersionCoverage, string>()
+
+    // Add explicit versions
+    for (const [version, file] of group.versioned) {
+      versionDocuments = HashMap.set(versionDocuments, version, file)
+    }
+
+    // Handle default file if present
+    if (group.default) {
+      // Determine which versions the default covers
+      const explicitVersions = HashSet.fromIterable(group.versioned.keys())
+      const defaultVersions = schemaVersions.filter(v => !HashSet.has(explicitVersions, v))
+
+      if (defaultVersions.length > 0) {
+        // Create version coverage for default
+        const defaultCoverage = defaultVersions.length === 1
+          ? defaultVersions[0]! // Single version
+          : HashSet.fromIterable(defaultVersions) // Version set
+
+        versionDocuments = HashMap.set(versionDocuments, defaultCoverage, group.default)
+      }
+    }
+
+    resolved.set(name, {
+      versionDocuments,
+      ...(group.unversioned ? { unversioned: group.unversioned } : {}),
+    })
+  }
+
+  return resolved
+}
+
+const lintFileLayout = (
+  example: Example.Example,
+  schemaCatalog?: SchemaCatalog.Catalog,
+): Diagnostic[] => {
+  // Extract schema versions from catalog if provided
+  const schemaVersions: Version.Version[] = schemaCatalog
+    ? SchemaCatalog.fold(
+      (versioned) => SchemaCatalog.Versioned.getVersions(versioned),
+      (unversioned) => [], // Unversioned doesn't have Version objects, just dates
+    )(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 missingVersions = Array.filter(
+          schemaVersions,
+          sv => !Array.some(coveredVersions, cv => Version.equivalence(sv, cv)),
+        )
+
+        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: coveredVersions,
+            missingVersions,
+          }))
+        }
+
+        // Check for duplicate content between selections
+        const entries = [...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 }))
+
+    // Get schema versions upfront for default file resolution
+    const schemaVersions: Version.Version[] = options.schemaCatalog
+      ? SchemaCatalog.fold(
+        (versioned) => SchemaCatalog.Versioned.getVersions(versioned),
+        () => [], // Unversioned schemas don't have version-specific examples
+      )(options.schemaCatalog)
+      : []
+
+    // Group files by example
+    const groupedFiles = groupExampleFiles(files)
+
+    // Resolve .default files into proper version coverage immediately
+    const resolvedFiles = resolveDefaultFiles(groupedFiles, schemaVersions)
+
+    // Process each example group
+    const examples: Example.Example[] = []
+    const diagnostics: Diagnostic[] = []
+
+    for (const [name, resolved] of resolvedFiles) {
+      // Determine the base path for this example
+      const firstFile = resolved.unversioned
+        || (HashMap.size(resolved.versionDocuments) > 0
+          ? HashMap.values(resolved.versionDocuments).next().value
+          : undefined)
+      if (!firstFile) continue // No files for this example
+
+      const basePath = HashMap.size(resolved.versionDocuments) > 1 || resolved.unversioned
+        ? Path.dirname(firstFile)
+        : firstFile
+
+      let example: Example.Example | undefined
+
+      if (resolved.unversioned) {
+        // Unversioned example - single file with no version
+        const fullPath = Path.join(options.dir, resolved.unversioned)
+        const document = yield* fs.readFileString(fullPath)
+
+        example = Example.make({
+          name,
+          path: basePath,
+          document: Document.Unversioned.make({
+            document,
+          }),
+        })
+      } else if (HashMap.size(resolved.versionDocuments) > 0) {
+        // Versioned example - read all version documents
+        let versionDocuments = HashMap.empty<VersionCoverage.VersionCoverage, string>()
+        const unknownVersions: Version.Version[] = []
+        const schemaVersionsSet = HashSet.fromIterable(schemaVersions)
+
+        for (const [versionCoverage, filePath] of HashMap.entries(resolved.versionDocuments)) {
+          // Check if version is known (only for single versions, not sets)
+          if (Version.is(versionCoverage)) {
+            const versionExists = HashSet.has(schemaVersionsSet, versionCoverage)
+            if (options.schemaCatalog && schemaVersions.length > 0 && !versionExists) {
+              unknownVersions.push(versionCoverage)
+              // Create diagnostic for unknown version
+              diagnostics.push(makeDiagnosticUnknownVersion({
+                message: `Example "${name}" specifies version "${
+                  Version.encodeSync(versionCoverage)
+                }" which does not exist in the schema`,
+                example: { name, path: basePath },
+                version: versionCoverage,
+                availableVersions: schemaVersions,
+              }))
+              // Skip this version - don't include it in the example
+              continue
+            }
+          }
+
+          const fullPath = Path.join(options.dir, filePath)
+          const fileContent = yield* fs.readFileString(fullPath)
+
+          versionDocuments = HashMap.set(versionDocuments, versionCoverage, fileContent)
+        }
+
+        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
+        }
+      }
+
+      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 }
+  })

package/src/api/examples/schemas/catalog.ts

@@ -0,0 +1,51 @@
+import { S } from '#lib/kit-temp/effect'
+import { Example } from './example/$.js'
+import { TypeUsageIndex } from './type-usage-index.js'
+
+// ============================================================================
+// Schema and Type
+// ============================================================================
+
+export const Catalog = S.Struct({
+  /**
+   * Array of GraphQL examples in the catalog.
+   */
+  examples: S.Array(Example.Example),
+  /**
+   * Optional index file metadata.
+   */
+  index: S.optional(S.Struct({
+    path: S.String,
+  })),
+  /**
+   * Index mapping GraphQL types to examples that use them.
+   * Structure: VersionKey → TypeName → Example[]
+   */
+  typeUsageIndex: S.optional(TypeUsageIndex),
+}).annotations({
+  identifier: 'ExamplesCatalog',
+  description: 'A catalog of GraphQL examples with optional index file and type usage index',
+})
+
+export type Catalog = S.Schema.Type<typeof Catalog>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Catalog.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Catalog)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Catalog)
+export const decodeSync = S.decodeSync(Catalog)
+export const encode = S.encode(Catalog)
+export const encodeSync = S.encodeSync(Catalog)

package/src/api/examples/schemas/example/$$.ts

@@ -0,0 +1 @@
+export * from './example.js'

package/src/api/examples/schemas/example/$.ts

@@ -0,0 +1 @@
+export * as Example from './$$.js'

package/src/api/examples/schemas/example/example.ts

@@ -0,0 +1,73 @@
+import { Document } from '#lib/document/$'
+import { S } from '#lib/kit-temp/effect'
+import { Order } from 'effect'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+/**
+ * An Example represents a GraphQL query/mutation example with metadata.
+ * The versioning complexity is handled by the Document type.
+ */
+export const Example = S.Struct({
+  /**
+   * The name/identifier of the example (e.g., "get-pokemon", "list-users")
+   */
+  name: S.String,
+
+  /**
+   * The file system path where this example was found.
+   * Used for diagnostic reporting and error messages.
+   */
+  path: S.String,
+
+  /**
+   * The document content, which can be unversioned, versioned, or partially versioned.
+   */
+  document: Document.Document,
+}).annotations({
+  identifier: 'Example',
+  description: 'A GraphQL example that contains a document with optional versioning support',
+})
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type Example = S.Schema.Type<typeof Example>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Example.make
+
+// ============================================================================
+// Ordering
+// ============================================================================
+
+export const order: Order.Order<Example> = Order.mapInput(
+  Order.string,
+  (example: Example) => example.name,
+)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalent = S.equivalence(Example)
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Example)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Example)
+export const decodeSync = S.decodeSync(Example)
+export const encode = S.encode(Example)

package/src/api/examples/schemas/type-usage-index.ts

@@ -0,0 +1,75 @@
+import { S } from '#lib/kit-temp/effect'
+import { Version } from '#lib/version/$'
+
+// ============================================================================
+// Runtime Types
+// ============================================================================
+
+/**
+ * Sentinel type for unversioned schemas in the type usage index.
+ */
+export const UnversionedKey = S.TaggedStruct('UnversionedKey', {})
+export type UnversionedKey = S.Schema.Type<typeof UnversionedKey>
+
+/**
+ * Singleton instance for unversioned key.
+ */
+export const UNVERSIONED_KEY = UnversionedKey.make({})
+
+/**
+ * Union type for version keys in the index.
+ */
+export const VersionKey = S.Union(Version.Version, UnversionedKey)
+export type VersionKey = S.Schema.Type<typeof VersionKey>
+
+// ============================================================================
+// Example Reference
+// ============================================================================
+
+/**
+ * Lightweight reference to an example with version.
+ * Uses Class for proper Equal and Hash support needed by HashSet,
+ * and provides a convenient make constructor.
+ */
+export class ExampleReference extends S.Class<ExampleReference>('ExampleReference')({
+  /**
+   * The unique name of the example
+   */
+  name: S.String,
+  /**
+   * The version this reference is for.
+   * Always included for consistent URL generation.
+   */
+  version: Version.Version,
+}) {}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+/**
+ * Schema for type usage index with proper HashMap transformation.
+ * Structure: VersionKey → TypeName → HashSet<ExampleReference>
+ *
+ * S.HashMap automatically handles transformation between:
+ * - Runtime: HashMap<K, V>
+ * - Encoded: Array<[K, V]> for JSON serialization
+ *
+ * S.HashSet automatically handles:
+ * - Runtime: HashSet<ExampleReference>
+ * - Encoded: Array<ExampleReference> for JSON serialization
+ * - Automatic deduplication based on ExampleReference's structural equality
+ */
+export const TypeUsageIndex = S.HashMap({
+  key: VersionKey,
+  value: S.HashMap({
+    key: S.String,
+    value: S.HashSet(ExampleReference),
+  }),
+}).annotations({
+  identifier: 'TypeUsageIndex',
+  description: 'Index mapping versions to types to example references that use those types',
+})
+
+export type TypeUsageIndex = S.Schema.Type<typeof TypeUsageIndex>
+export type TypeUsageIndexEncoded = S.Schema.Encoded<typeof TypeUsageIndex>

package/src/api/examples/type-generator.ts

@@ -0,0 +1,49 @@
+import { Typings } from '#api/typings/$'
+import { FileSystem } from '@effect/platform'
+import { Effect } from 'effect'
+import type { Catalog } from './schemas/catalog.js'
+
+/**
+ * Generate TypeScript type definitions for discovered examples.
+ */
+export const generateExampleTypes = (
+  catalog: Catalog,
+  projectRoot: string,
+): Effect.Effect<void, Error, FileSystem.FileSystem> => {
+  const exampleNames = catalog.examples.map(e => e.name)
+  const typeDefinition = generateTypeDefinition(exampleNames)
+  return Typings.write(
+    {
+      name: 'config.examples',
+      content: typeDefinition,
+    },
+    { projectRoot },
+  )
+}
+
+/**
+ * Generate the TypeScript type definition content.
+ */
+function generateTypeDefinition(exampleNames: string[]): string {
+  const quotedNames = exampleNames.map(name => `'${name}'`)
+  const namesArray = quotedNames.length > 0
+    ? `readonly [${quotedNames.join(', ')}]`
+    : 'readonly []'
+
+  const interfaceContent = `/**
+ * Augment the global Examples interface with discovered example names.
+ * This extends the base interface defined in #api/examples/config.
+ */
+interface Examples {
+  /**
+   * Type-safe list of discovered example names from the /examples directory.
+   * This property is generated and provides autocomplete for example selection.
+   */
+  readonly names: ${namesArray}
+}`
+
+  return Typings.createGlobalAugmentation(
+    interfaceContent,
+    'Example type definitions',
+  )
+}