polen 0.11.0-next.16 → 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,41 +74,105 @@ 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,
 ): Diagnostic[] => {
   // Extract schema versions from catalog if provided
-  const schemaVersions: string[] = schemaCatalog
+  const schemaVersions: Version.Version[] = schemaCatalog
     ? SchemaCatalog.fold(
-      (versioned) => versioned.entries.map(entry => Version.encodeSync(entry.version)),
-      (unversioned) => unversioned.schema.revisions?.map(r => r.date) ?? [],
+      (versioned) => SchemaCatalog.Versioned.getVersions(versioned),
+      (unversioned) => [], // Unversioned doesn't have Version objects, just dates
     )(schemaCatalog)
     : []
 
@@ -105,20 +183,22 @@ const lintFileLayout = (
       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))
+        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: coveredVersionStrings,
+            providedVersions: coveredVersions,
             missingVersions,
           }))
         }
 
         // 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++) {
@@ -162,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({
@@ -197,98 +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) => 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
+      } else if (HashMap.size(resolved.versionDocuments) > 0) {
+        // Versioned example - read all version documents
         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)
+        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}" 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,
+                version: versionCoverage,
                 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
+          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) {
@@ -303,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.test.ts

@@ -1,6 +1,5 @@
 import { Catalog } from '#lib/catalog/$'
 import { Document } from '#lib/document/$'
-import { Revision } from '#lib/revision/$'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
 import { HashMap, HashSet, Schema as S } from 'effect'
@@ -17,23 +16,23 @@ describe('type-usage-indexer', () => {
       users: [User!]!
       product(id: ID!): Product
     }
-    
+
     type User {
       id: ID!
       name: String!
       email: String!
     }
-    
+
     type Product {
       id: ID!
       name: String!
       price: Float!
     }
-    
+
     interface Node {
       id: ID!
     }
-    
+
     union SearchResult = User | Product
   `
 
@@ -91,20 +90,26 @@ describe('type-usage-indexer', () => {
       })
 
       const catalog = Catalog.Versioned.make({
-        entries: [
-          Schema.Versioned.make({
-            version: version1,
-            definition: schemaDef,
-            branchPoint: null,
-            revisions: [],
-          }),
-          Schema.Versioned.make({
-            version: version2,
-            definition: schemaDef,
-            branchPoint: null,
-            revisions: [],
-          }),
-        ],
+        entries: HashMap.make(
+          [
+            version1,
+            Schema.Versioned.make({
+              version: version1,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+          [
+            version2,
+            Schema.Versioned.make({
+              version: version2,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+        ),
       })
 
       const index = createTypeUsageIndex([example], catalog)
@@ -212,20 +217,26 @@ describe('type-usage-indexer', () => {
       })
 
       const catalog = Catalog.Versioned.make({
-        entries: [
-          Schema.Versioned.make({
-            version: version1,
-            definition: schemaDef,
-            branchPoint: null,
-            revisions: [],
-          }),
-          Schema.Versioned.make({
-            version: version2,
-            definition: schemaDef,
-            branchPoint: null,
-            revisions: [],
-          }),
-        ],
+        entries: HashMap.make(
+          [
+            version1,
+            Schema.Versioned.make({
+              version: version1,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+          [
+            version2,
+            Schema.Versioned.make({
+              version: version2,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+        ),
       })
 
       const index = createTypeUsageIndex([example], catalog)

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,32 +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)) {
-    // Find the schema with matching version
-    return catalog.entries.find(entry =>
-      Schema.Versioned.is(entry)
-      && Version.equivalence(entry.version, version)
-    )
-  }
-  // 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
 // ============================================================================
@@ -206,12 +180,15 @@ export const createTypeUsageIndex = (
     // Process based on document type
     if (Document.Unversioned.is(example.document)) {
       // Unversioned document
-      const schema = Catalog.getLatestSchema(schemasCatalog)
+      const schema = Catalog.getLatest(schemasCatalog)
       const types = extractTypesFromQuery(example.document.document, schema.definition)
 
       for (const typeName of types) {
         // For unversioned, use the latest version from the catalog
-        const latestVersion = Catalog.getLatestVersionIdentifier(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)) {
@@ -219,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)
 }
 
 /**