polen 0.11.0-next.17 → 0.11.0-next.18

package/src/api/examples/scanner.ts

@@ -1,18 +1,17 @@
 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 { VersionCoverage } from '#lib/version-coverage'
 import { Version } from '#lib/version/$'
 import { FileSystem } from '@effect/platform'
 import { Str } from '@wollybeard/kit'
-import { Effect, HashMap, HashSet, Match } from 'effect'
+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,
-  makeDiagnosticUnusedDefault,
 } from './diagnostic/diagnostic.js'
 import { validateExamples } from './diagnostic/validator.js'
 import { Catalog } from './schemas/catalog.js'
@@ -44,11 +43,26 @@ 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 parseExampleFilename = (filename: string): { name: string; version: string | null } => {
+const parseExampleFile = (filename: string): ParsedExampleFile => {
   const parsed = Path.parse(filename)
   const base = parsed.name
 
@@ -60,32 +74,96 @@ const parseExampleFilename = (filename: string): { name: string; version: string
 
     // Handle special 'default' keyword
     if (versionStr === 'default') {
-      return { name, version: 'default' }
+      return { type: 'default', name, file: filename }
     }
-    const decoded = Version.decodeSync(versionStr)
-    // Return canonical version string
-    return { name, version: Version.encodeSync(decoded) }
+
+    const version = Version.decodeSync(versionStr)
+    return { type: 'versioned', name, version, file: filename }
   }
 
   // No version found - this is an unversioned example
-  return { name: base, version: null }
+  return { type: 'unversioned', name: base, file: filename }
 }
 
-const groupExampleFiles = (files: string[]): Map<string, Map<string | null, string>> => {
-  const grouped = new Map<string, Map<string | null, string>>()
+const groupExampleFiles = (files: string[]): GroupedExampleFiles => {
+  const grouped: GroupedExampleFiles = new Map()
 
   for (const file of files) {
-    const { name, version } = parseExampleFilename(file)
+    const parsed = parseExampleFile(file)
 
-    if (!grouped.has(name)) {
-      grouped.set(name, new Map())
+    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
     }
-    grouped.get(name)!.set(version, file)
   }
 
   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,
@@ -105,7 +183,10 @@ const lintFileLayout = (
       DocumentVersioned: (doc) => {
         // Get all versions covered by this document
         const coveredVersions = Document.Versioned.getAllVersions(doc)
-        const missingVersions = schemaVersions.filter(sv => !coveredVersions.some(cv => Version.equivalence(sv, cv)))
+        const missingVersions = Array.filter(
+          schemaVersions,
+          sv => !Array.some(coveredVersions, cv => Version.equivalence(sv, cv)),
+        )
 
         if (missingVersions.length > 0) {
           diagnostics.push(makeDiagnosticMissingVersions({
@@ -117,7 +198,7 @@ const lintFileLayout = (
         }
 
         // Check for duplicate content between selections
-        const entries = Array.from(HashMap.entries(doc.versionDocuments))
+        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++) {
@@ -161,32 +242,41 @@ export const scan = (
     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, 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
-
+    for (const [name, resolved] of resolvedFiles) {
       // Determine the base path for this example
-      const firstFilePath = Array.from(versions.values())[0]!
-      const basePath = versions.size === 1
-        ? firstFilePath
-        : Path.dirname(firstFilePath)
+      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
+      let example: Example.Example | undefined
 
-      if (hasUnversionedFile && versions.size === 1) {
+      if (resolved.unversioned) {
         // Unversioned example - single file with no version
-        const filePath = versions.get(null)!
-        const fullPath = Path.join(options.dir, filePath)
+        const fullPath = Path.join(options.dir, resolved.unversioned)
         const document = yield* fs.readFileString(fullPath)
 
         example = Example.make({
@@ -196,104 +286,36 @@ export const scan = (
             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) => SchemaCatalog.Versioned.getVersions(versioned),
-            () => [], // 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
+      } else if (HashMap.size(resolved.versionDocuments) > 0) {
+        // Versioned example - read all version documents
         let versionDocuments = HashMap.empty<VersionCoverage.VersionCoverage, string>()
-        let defaultDocument: string | undefined
-        let explicitVersions = HashSet.empty<Version.Version>() // Track which versions have explicit files
         const unknownVersions: Version.Version[] = []
-
-        // Get available schema versions if catalog is provided
-        const schemaVersions: Version.Version[] = options.schemaCatalog
-          ? SchemaCatalog.fold(
-            (versioned) => SchemaCatalog.Versioned.getVersions(versioned),
-            () => [], // Unversioned schemas don't have version-specific examples
-          )(options.schemaCatalog)
-          : []
-        
-        // Create HashSet for O(1) lookups
         const schemaVersionsSet = HashSet.fromIterable(schemaVersions)
 
-        // 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) {
-            // Parse the version string
-            const parsedVersion = Version.decodeSync(version)
-            // Check if this version exists in the schema
-            const versionExists = HashSet.has(schemaVersionsSet, parsedVersion)
+        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(parsedVersion)
+              unknownVersions.push(versionCoverage)
               // Create diagnostic for unknown version
               diagnostics.push(makeDiagnosticUnknownVersion({
-                message: `Example "${name}" specifies version "${version}" which does not exist in the schema`,
+                message: `Example "${name}" specifies version "${
+                  Version.encodeSync(versionCoverage)
+                }" which does not exist in the schema`,
                 example: { name, path: basePath },
-                version: parsedVersion,
+                version: versionCoverage,
                 availableVersions: schemaVersions,
               }))
               // Skip this version - don't include it in the example
               continue
             }
-
-            // We already have parsedVersion from above
-            versionDocuments = HashMap.set(versionDocuments, parsedVersion, fileContent)
-            explicitVersions = HashSet.add(explicitVersions, parsedVersion)
           }
-        }
-
-        if (defaultDocument) {
-          // If we have a default, determine which versions it applies to
-          const defaultVersions = schemaVersions.filter(v => !HashSet.has(explicitVersions, v))
 
-          if (defaultVersions.length > 0) {
-            // Create a version set for the default document
-            const defaultVersionSet = defaultVersions.length === 1
-              ? defaultVersions[0]! // Single version
-              : HashSet.fromIterable(defaultVersions) // Version set
+          const fullPath = Path.join(options.dir, filePath)
+          const fileContent = yield* fs.readFileString(fullPath)
 
-            versionDocuments = HashMap.set(versionDocuments, defaultVersionSet, defaultDocument)
-          }
+          versionDocuments = HashMap.set(versionDocuments, versionCoverage, fileContent)
         }
 
         if (HashMap.size(versionDocuments) > 0) {
@@ -308,9 +330,6 @@ export const scan = (
         } else if (unknownVersions.length > 0) {
           // All versions were unknown, skip this example entirely
           continue
-        } else {
-          // No versions at all - shouldn't happen
-          continue
         }
       }
 

package/src/api/examples/type-usage-indexer.ts

@@ -1,6 +1,5 @@
 import { Catalog } from '#lib/catalog/$'
 import { Document } from '#lib/document/$'
-import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
 import { HashMap, HashSet, Option } from 'effect'
 import { Schema as S } from 'effect'
@@ -76,19 +75,19 @@ const extractTypesFromQuery = (
   const resolveFieldType = (
     fieldName: string,
     parentTypeName: string | null,
-  ): string | null => {
-    if (!parentTypeName) return null
+  ): Option.Option<string> => {
+    if (!parentTypeName) return Option.none()
 
     const parentType = schema.getType(parentTypeName)
     if (!parentType || !isObjectType(parentType) && !isInterfaceType(parentType)) {
-      return null
+      return Option.none()
     }
 
     const field = parentType.getFields()[fieldName]
-    if (!field) return null
+    if (!field) return Option.none()
 
     const namedType = getNamedType(field.type)
-    return namedType.name
+    return Option.some(namedType.name)
   }
 
   // Track the current type context as we traverse
@@ -120,8 +119,9 @@ const extractTypesFromQuery = (
         // Special handling for __typename
         if (node.name.value === '__typename') return
 
-        const fieldType = resolveFieldType(node.name.value, currentType)
-        if (fieldType) {
+        const fieldTypeOption = resolveFieldType(node.name.value, currentType)
+        if (Option.isSome(fieldTypeOption)) {
+          const fieldType = fieldTypeOption.value
           addType(fieldType)
           // Update context for nested selections
           if (node.selectionSet) {
@@ -160,29 +160,6 @@ const extractTypesFromQuery = (
   return types
 }
 
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-/**
- * Get a schema by version from the catalog.
- */
-const getSchemaByVersion = (
-  catalog: Catalog.Catalog,
-  version: Version.Version,
-): Schema.Schema | undefined => {
-  if (Catalog.Versioned.is(catalog)) {
-    // Use HashMap.get for O(1) lookup
-    return HashMap.get(catalog.entries, version).pipe(Option.getOrElse(() => undefined))
-  }
-  // For unversioned catalog, return the single schema if version matches
-  if (Catalog.Unversioned.is(catalog)) {
-    // Unversioned catalogs don't have versions, so we can't match
-    return undefined
-  }
-  return undefined
-}
-
 // ============================================================================
 // Index Creation
 // ============================================================================
@@ -208,7 +185,10 @@ export const createTypeUsageIndex = (
 
       for (const typeName of types) {
         // For unversioned, use the latest version from the catalog
-        const latestVersion = Catalog.getLatestVersion(schemasCatalog) ?? Version.fromString('1.0.0')
+        const latestVersion = Option.getOrElse(
+          Catalog.getLatestVersion(schemasCatalog),
+          () => Version.fromString('1.0.0'),
+        )
         index = addExampleToIndex(index, UNVERSIONED_KEY, typeName, example, latestVersion)
       }
     } else if (Document.Versioned.is(example.document)) {
@@ -216,11 +196,19 @@ export const createTypeUsageIndex = (
       const allVersions = Document.Versioned.getAllVersions(example.document)
 
       for (const version of allVersions) {
-        const schema = getSchemaByVersion(schemasCatalog, version)
-        if (!schema) continue
+        // Use centralized resolution to get schema for version
+        const schemaOption = Option.liftThrowable(
+          () => Catalog.resolveCatalogSchema(schemasCatalog, version),
+        )()
+        if (Option.isNone(schemaOption)) {
+          // Skip if version not found in catalog
+          continue
+        }
+        const schema = schemaOption.value
 
-        const documentString = Document.Versioned.getContentForVersion(example.document, version)
-        if (!documentString) continue
+        const documentStringOption = Document.Versioned.getContentForVersion(example.document, version)
+        if (Option.isNone(documentStringOption)) continue
+        const documentString = documentStringOption.value
 
         const types = extractTypesFromQuery(documentString, schema.definition)
 

package/src/api/iso/schema/routing.ts

@@ -1,6 +1,7 @@
 import { Grafaid } from '#lib/grafaid'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
+import { Array, Option, Predicate } from 'effect'
 
 export interface ReferencePathParts {
   version?: Version.Version
@@ -46,16 +47,15 @@ export const createReferenceVersionPath = (version?: Version.Version): string =>
 export const joinSegmentsAndPaths = (
   ...segmentsOrPaths: (string | undefined | null | (string | null | undefined)[])[]
 ): string => {
-  const path = '/' + segmentsOrPaths
-    .flat()
-    .filter((_): _ is string => _ !== undefined && _ !== null)
-    .map(chunkUnformatted =>
-      chunkUnformatted
-        .replace(/^\//, '')
-        .replace(/\/$/, '')
-    )
-    .filter(Boolean)
-    .join('/')
+  const segments = Array.filterMap(
+    segmentsOrPaths.flat(),
+    (segment) => {
+      if (!Predicate.isNotNullable(segment)) return Option.none()
+      const cleaned = segment.replace(/^\//, '').replace(/\/$/, '')
+      return cleaned ? Option.some(cleaned) : Option.none()
+    },
+  )
+  const path = '/' + segments.join('/')
 
   return path
 }

package/src/api/iso/schema/validation.ts

@@ -1,4 +1,5 @@
 import { Grafaid } from '#lib/grafaid'
+import { Array, Option } from 'effect'
 import type { GraphQLFieldMap, GraphQLSchema } from 'graphql'
 
 export interface PathValidation {
@@ -28,8 +29,8 @@ export const doesPathExist = (schema: GraphQLSchema, path: PathValidation): bool
   if (!path.argument) return true
 
   // Check if argument exists
-  const arg = field.args.find(a => a.name === path.argument)
-  return !!arg
+  const arg = Array.findFirst(field.args, a => a.name === path.argument)
+  return Option.isSome(arg)
 }
 
 /**

package/src/api/schema/input-sources/directory.ts

@@ -98,8 +98,8 @@ export const loader = InputSource.createEffect({
       // Check if we have either:
       // 1. A single schema.graphql file (non-versioned mode)
       // 2. Any .graphql files with valid date names (versioned mode)
-      const hasSchemaFile = files.some(file => file === 'schema.graphql')
-      const hasVersionedFiles = files.some(file => {
+      const hasSchemaFile = Array.some(files, file => file === 'schema.graphql')
+      const hasVersionedFiles = Array.some(files, file => {
         if (!file.endsWith('.graphql')) return false
         const name = Path.basename(file, '.graphql')
         return /^\d{4}-\d{2}-\d{2}$/.test(name)

package/src/api/schema/input-sources/versioned-directory.ts

@@ -10,7 +10,7 @@ import { debugPolen } from '#singletons/debug'
 import { PlatformError } from '@effect/platform/Error'
 import { FileSystem } from '@effect/platform/FileSystem'
 import { Arr, Path } from '@wollybeard/kit'
-import { Effect, HashMap } from 'effect'
+import { Array, Effect, HashMap } from 'effect'
 import type { GraphQLSchema } from 'graphql'
 
 const debug = debugPolen.sub(`schema:data-source-versioned-schema-directory`)
@@ -452,9 +452,8 @@ export const loader = InputSource.createEffect({
           // Check for revision files or schema.graphql
           const dirFiles = yield* Effect.either(fs.readDirectory(versionPath))
           if (dirFiles._tag === 'Right') {
-            const hasRevisions = dirFiles.right.some(file =>
-              /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql'
-            )
+            const hasRevisions = Array.some(dirFiles.right, file =>
+              /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql')
             if (hasRevisions) {
               return true
             }
@@ -520,9 +519,8 @@ export const loader = InputSource.createEffect({
         // Check for schema files
         const dirFiles = yield* Effect.either(fs.readDirectory(versionPath))
         if (dirFiles._tag === 'Right') {
-          const hasSchemaFiles = dirFiles.right.some(file =>
-            /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql'
-          )
+          const hasSchemaFiles = Array.some(dirFiles.right, file =>
+            /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql')
 
           if (hasSchemaFiles) {
             debug('found valid schema files, proceeding with full read')

package/src/api/schema/load.ts

@@ -7,7 +7,7 @@ import { Catalog } from '#lib/catalog/$'
 import type { PlatformError } from '@effect/platform/Error'
 import type { FileSystem } from '@effect/platform/FileSystem'
 import { Arr } from '@wollybeard/kit'
-import { Effect } from 'effect'
+import { Array, Effect, Option } from 'effect'
 
 // For now, we'll need a type that accepts both promise and effect sources
 type AnyInputSource = InputSource | EffectInputSource