polen 0.11.0-next.16 → 0.11.0-next.18

package/src/api/schema/$.test.ts

@@ -3,7 +3,7 @@ import { Catalog } from '#lib/catalog/$'
 import { Grafaid } from '#lib/grafaid'
 import { MemoryFilesystem } from '#lib/memory-filesystem/$'
 import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
-import { Effect } from 'effect'
+import { Effect, HashMap } from 'effect'
 import { expect } from 'vitest'
 import { Test } from '../../../tests/unit/helpers/test.js'
 import { Schema } from './$.js'
@@ -421,7 +421,7 @@ testWithFileSystem<BaseTestCase & {
         expect(result!._tag).toBe('CatalogVersioned')
         if (expected.versionCount !== undefined) {
           const versioned = result as Catalog.Versioned.Versioned
-          expect(versioned.entries.length).toBe(expected.versionCount)
+          expect(HashMap.size(versioned.entries)).toBe(expected.versionCount)
         }
       } else {
         expect(result!._tag).toBe('CatalogUnversioned')

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 } from 'effect'
+import { Array, Effect, HashMap } from 'effect'
 import type { GraphQLSchema } from 'graphql'
 
 const debug = debugPolen.sub(`schema:data-source-versioned-schema-directory`)
@@ -393,9 +393,14 @@ export const readOrThrow = (
     // Reverse to have newest first
     catalogEntries.reverse()
 
+    // Convert array to HashMap with version as key
+    const entriesMap = HashMap.fromIterable(
+      catalogEntries.map(entry => [entry.version, entry] as const),
+    )
+
     debug(`computed ${catalogEntries.length} entries`)
     return Catalog.Versioned.make({
-      entries: catalogEntries,
+      entries: entriesMap,
     })
   })
 
@@ -447,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
             }
@@ -515,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
@@ -142,7 +142,7 @@ export const loadOrNull = (
       const catalog = loadedSchema.data as Catalog.Catalog
       Catalog.fold(
         (versioned) => {
-          for (const schema of versioned.entries) {
+          for (const schema of Catalog.Versioned.getAll(versioned)) {
             Augmentations.apply(schema.definition, augmentations)
           }
         },

package/src/cli/commands/hero-image.ts

@@ -133,7 +133,7 @@ export const heroImage = Command.make(
       const schemaResult = yield* Api.Schema.loadOrNull(config)
       if (schemaResult?.data) {
         try {
-          const latestSchema = Catalog.getLatestSchema(schemaResult.data)
+          const latestSchema = Catalog.getLatest(schemaResult.data)
           if (latestSchema?.definition) {
             schema = latestSchema.definition
             const context = AiImageGeneration.analyzeSchema(schema)

package/src/lib/catalog/catalog.ts

@@ -1,13 +1,33 @@
 import { S } from '#lib/kit-temp/effect'
 import { Schema } from '#lib/schema/$'
+import { VersionCoverage } from '#lib/version-coverage'
 import { Version } from '#lib/version/$'
-import { Match } from 'effect'
+import { Data, Either, HashMap, Match, Option } from 'effect'
 import * as Unversioned from './unversioned.js'
 import * as Versioned from './versioned.js'
 
 export * as Unversioned from './unversioned.js'
 export * as Versioned from './versioned.js'
 
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Error thrown when a version is not found in the catalog
+ */
+export class VersionNotFoundInCatalogError extends Data.TaggedError('VersionNotFoundInCatalogError')<{
+  readonly version: string
+  readonly reason: string
+}> {}
+
+/**
+ * Error thrown when a catalog has no entries
+ */
+export class EmptyCatalogError extends Data.TaggedError('EmptyCatalogError')<{
+  readonly reason: string
+}> {}
+
 // ============================================================================
 // Schema
 // ============================================================================
@@ -62,7 +82,7 @@ export const equivalence = S.equivalence(Catalog)
  */
 export const getVersionCount = (catalog: Catalog): number =>
   fold(
-    (versioned) => versioned.entries.length,
+    (versioned) => HashMap.size(versioned.entries),
     (_unversioned) => 1, // Unversioned catalog is effectively one version
   )(catalog)
 
@@ -79,28 +99,85 @@ export const getSchemaVersionString = (schema: Schema.Schema): string => {
  * Get the version string from a schema.
  * Returns the stringified version for versioned schemas, or '__UNVERSIONED__' for unversioned schemas.
  */
-export const getLatestSchema = (catalog: Catalog): Schema.Schema =>
+export const getLatest = (catalog: Catalog): Schema.Schema =>
   Match.value(catalog).pipe(Match.tagsExhaustive({
-    CatalogVersioned: (versioned) => {
-      // Entries are sorted newest first, so get the first entry
-      const latestEntry = versioned.entries[0]!
-      return latestEntry
-    },
-    CatalogUnversioned: (unversioned) => {
-      return unversioned.schema
-    },
+    CatalogVersioned: Versioned.getLatestOrThrow,
+    CatalogUnversioned: (unversioned) => unversioned.schema,
   }))
 
 /**
  * Get the latest version identifier from a catalog.
- * Returns the version for versioned catalogs, or null for unversioned catalogs.
+ * Returns the version for versioned catalogs, or none for unversioned catalogs.
  */
-export const getLatestVersionIdentifier = (catalog?: Catalog): Version.Version | null => {
-  if (!catalog) return null
+export const getLatestVersion = (catalog?: Catalog): Option.Option<Version.Version> => {
+  if (!catalog) return Option.none()
   return Match.value(catalog).pipe(
     Match.tagsExhaustive({
-      CatalogUnversioned: () => null,
-      CatalogVersioned: (cat) => cat.entries[0]?.version ?? null,
+      CatalogUnversioned: () => Option.none(),
+      CatalogVersioned: (cat) => {
+        const versions = Versioned.getVersions(cat)
+        return versions[0] ? Option.some(versions[0]) : Option.none()
+      },
     }),
   )
 }
+
+// ============================================================================
+// Resolution Functions
+// ============================================================================
+
+/**
+ * Resolve schema from catalog for a given version coverage.
+ *
+ * @param catalog - The schema catalog
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns Either with the resolved schema or error
+ */
+export const resolveCatalogSchemaEither = (
+  catalog: Catalog,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): Either.Either<Schema.Schema, VersionNotFoundInCatalogError | EmptyCatalogError> => {
+  if (Unversioned.is(catalog)) {
+    return Either.right(catalog.schema)
+  }
+
+  // If no version coverage specified, use latest
+  if (!versionCoverage) {
+    return Versioned.getLatest(catalog)
+  }
+
+  // Get the latest version from the coverage
+  const version = VersionCoverage.getLatest(versionCoverage)
+
+  const schemaOption = HashMap.get(catalog.entries, version)
+  if (Option.isNone(schemaOption)) {
+    return Either.left(
+      new VersionNotFoundInCatalogError({
+        version: Version.encodeSync(version),
+        reason: `Version ${Version.encodeSync(version)} not found in catalog`,
+      }),
+    )
+  }
+
+  return Either.right(Option.getOrThrow(schemaOption))
+}
+
+/**
+ * Resolve schema from catalog for a given version coverage.
+ *
+ * @param catalog - The schema catalog
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns The resolved schema
+ * @throws {Error} If catalog is versioned but version is not found
+ * @deprecated Use resolveCatalogSchemaEither which returns Either
+ */
+export const resolveCatalogSchema = (
+  catalog: Catalog,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): Schema.Schema => {
+  const result = resolveCatalogSchemaEither(catalog, versionCoverage)
+  if (Either.isLeft(result)) {
+    throw new Error(result.left.reason)
+  }
+  return result.right
+}

package/src/lib/catalog/versioned.ts

@@ -1,12 +1,18 @@
 import { S } from '#lib/kit-temp/effect'
+import { Array, Either, HashMap, Iterable, Order, pipe } from 'effect'
 import { Schema } from '../schema/$.js'
+import { Version } from '../version/$.js'
+import { EmptyCatalogError } from './catalog.js'
 
 // ============================================================================
 // Schema
 // ============================================================================
 
 export const Versioned = S.TaggedStruct('CatalogVersioned', {
-  entries: S.Array(Schema.Versioned.Versioned),
+  entries: S.HashMap({
+    key: Version.Version,
+    value: Schema.Versioned.Versioned,
+  }),
 }).annotations({
   identifier: 'CatalogVersioned',
   title: 'Versioned Catalog',
@@ -45,18 +51,62 @@ export const equivalence = S.equivalence(Versioned)
 // Domain Logic
 // ============================================================================
 
+/**
+ * Get the latest schema from a versioned catalog.
+ * The latest version is determined by Version.max comparison.
+ *
+ * @param catalog - The versioned catalog
+ * @returns Either with the latest schema or EmptyCatalogError
+ */
+export const getLatest = (catalog: Versioned): Either.Either<Schema.Versioned.Versioned, EmptyCatalogError> => {
+  const schema = getAll(catalog)[0]
+  if (!schema) {
+    return Either.left(
+      new EmptyCatalogError({
+        reason: 'Versioned catalog has no entries - cannot get latest schema',
+      }),
+    )
+  }
+  return Either.right(schema)
+}
+
 /**
  * Get the latest schema definition from a versioned catalog.
- * The latest version is the first entry in the catalog (entries are ordered newest to oldest).
+ * The latest version is determined by Version.max comparison.
  *
  * @param catalog - The versioned catalog
  * @returns The GraphQL schema definition of the latest version
  * @throws {Error} If the catalog has no entries
+ * @deprecated Use getLatest which returns Either
  */
-export const getLatest = (catalog: Versioned): Schema.Schema => {
-  const latestEntry = catalog.entries[0]
-  if (!latestEntry) {
-    throw new Error('Versioned catalog has no entries - cannot get latest schema')
+export const getLatestOrThrow = (catalog: Versioned): Schema.Versioned.Versioned => {
+  const result = getLatest(catalog)
+  if (Either.isLeft(result)) {
+    throw new Error(result.left.reason)
   }
-  return latestEntry
+  return result.right
+}
+
+/**
+ * Get all schemas sorted by version (newest first)
+ */
+export const getAll = (catalog: Versioned): Schema.Versioned.Versioned[] => {
+  return pipe(
+    catalog.entries,
+    HashMap.values,
+    Array.fromIterable,
+    // Put newest versions first in array
+    Array.sort(Order.reverse(Schema.Versioned.order)),
+  )
+}
+
+/**
+ * Get all versions sorted (newest first)
+ */
+export const getVersions = (catalog: Versioned): Version.Version[] => {
+  return pipe(
+    catalog,
+    getAll,
+    Array.map(_ => _.version),
+  )
 }

package/src/lib/catalog-statistics/$.test.ts

@@ -1,6 +1,7 @@
 import { Catalog } from '#lib/catalog/$'
 import { DateOnly } from '#lib/date-only/$'
 import { Version } from '#lib/version/$'
+import { HashMap } from 'effect'
 import { buildSchema, type GraphQLSchema } from 'graphql'
 import { describe, expect, test } from 'vitest'
 import { CatalogStatistics } from './$.js'
@@ -91,14 +92,20 @@ describe('analyzeCatalog', () => {
       name: 'versioned catalog',
       catalog: () =>
         Catalog.Versioned.make({
-          entries: [
-            makeVersionedEntry(1, buildSchema('type Query { hello: String }'), ['2024-01-01', '2024-01-15']),
-            makeVersionedEntry(
-              2,
-              buildSchema('type Query { hello: String, world: String } type User { id: ID!, name: String }'),
-              ['2024-02-01'],
-            ),
-          ],
+          entries: HashMap.make(
+            [
+              Version.fromInteger(1),
+              makeVersionedEntry(1, buildSchema('type Query { hello: String }'), ['2024-01-01', '2024-01-15']),
+            ],
+            [
+              Version.fromInteger(2),
+              makeVersionedEntry(
+                2,
+                buildSchema('type Query { hello: String, world: String } type User { id: ID!, name: String }'),
+                ['2024-02-01'],
+              ),
+            ],
+          ),
         }),
       expectedVersions: 2,
       expectedCurrentVersion: '2',
@@ -132,10 +139,13 @@ describe('analyzeCatalog', () => {
 
   test('calculates stability metrics', () => {
     const catalog = Catalog.Versioned.make({
-      entries: [
-        makeVersionedEntry(1, buildSchema('type Query { test: String }'), ['2024-01-01', '2024-01-05']),
-        makeVersionedEntry(2, buildSchema('type Query { test: String }'), ['2024-01-10']),
-      ],
+      entries: HashMap.make(
+        [
+          Version.fromInteger(1),
+          makeVersionedEntry(1, buildSchema('type Query { test: String }'), ['2024-01-01', '2024-01-05']),
+        ],
+        [Version.fromInteger(2), makeVersionedEntry(2, buildSchema('type Query { test: String }'), ['2024-01-10'])],
+      ),
     })
 
     const report = CatalogStatistics.analyzeCatalog(catalog)

package/src/lib/catalog-statistics/analyze-catalog.ts

@@ -16,7 +16,7 @@ export const analyzeCatalog = (catalog: Catalog.Catalog, options: AnalyzeOptions
   const processResult = Catalog.fold(
     // Versioned catalog
     (versioned) => {
-      for (const entry of versioned.entries) {
+      for (const entry of Catalog.Versioned.getAll(versioned)) {
         const versionId = Version.encodeSync(entry.version)
         // Analyze the schema definition for this version
         // Use the first revision date if available
@@ -55,8 +55,8 @@ export const analyzeCatalog = (catalog: Catalog.Catalog, options: AnalyzeOptions
   // Calculate stability metrics
   const stability = calculateStabilityMetrics(versions, revisionDates)
 
-  // Get current version (last in array)
-  const current = versions[versions.length - 1]
+  // Get current version (first in array since sorted newest first)
+  const current = versions[0]
 
   return {
     stability,

package/src/lib/document/document.ts

@@ -1,6 +1,30 @@
+import { Catalog } from '#lib/catalog/$'
 import { S } from '#lib/kit-temp/effect'
+import { Schema } from '#lib/schema/$'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Version } from '#lib/version/$'
+import { Data, Either, Option } from 'effect'
 import { DocumentUnversioned } from './unversioned.js'
-import { DocumentVersioned } from './versioned.js'
+import * as DocumentVersioned from './versioned.js'
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Error thrown when trying to use version coverage with an unversioned catalog
+ */
+export class VersionCoverageMismatchError extends Data.TaggedError('VersionCoverageMismatchError')<{
+  readonly reason: string
+}> {}
+
+/**
+ * Error thrown when a version is not found in the document
+ */
+export class VersionNotFoundInDocumentError extends Data.TaggedError('VersionNotFoundInDocumentError')<{
+  readonly version: string
+  readonly reason: string
+}> {}
 
 // ============================================================================
 // Schema
@@ -13,7 +37,7 @@ import { DocumentVersioned } from './versioned.js'
  */
 export const Document = S.Union(
   DocumentUnversioned,
-  DocumentVersioned,
+  DocumentVersioned.DocumentVersioned,
 )
 
 // ============================================================================
@@ -35,3 +59,112 @@ export const is = S.is(Document)
 export const decode = S.decode(Document)
 export const decodeSync = S.decodeSync(Document)
 export const encode = S.encode(Document)
+
+// ============================================================================
+// Domain Logic - Resolution Functions
+// ============================================================================
+
+/**
+ * Resolve document content for a given version coverage.
+ *
+ * @param document - The document to resolve content from
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns The resolved document content
+ * @throws {Error} If version is not found in document
+ */
+export const resolveDocumentContent = (
+  document: Document,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): string => {
+  if (document._tag === 'DocumentUnversioned') {
+    return document.document
+  }
+
+  // If no version coverage specified, use latest
+  if (!versionCoverage) {
+    return DocumentVersioned.getContentForLatestVersionOrThrow(document)
+  }
+
+  // Get the latest version from the coverage
+  const version = VersionCoverage.getLatest(versionCoverage)
+  const contentOption = DocumentVersioned.getContentForVersion(document, version)
+
+  if (Option.isNone(contentOption)) {
+    throw new VersionNotFoundInDocumentError({
+      version: Version.encodeSync(version),
+      reason: `Version ${Version.encodeSync(version)} not covered by document`,
+    })
+  }
+
+  return contentOption.value
+}
+
+/**
+ * Resolve both document content and schema for a given version coverage.
+ * This is the primary resolution function that handles all combinations
+ * of versioned/unversioned documents and catalogs.
+ *
+ * @param document - The document to resolve content from
+ * @param catalog - The schema catalog (optional)
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns Either with resolved content and optional schema, or error
+ */
+export const resolveDocumentAndSchema = (
+  document: Document,
+  catalog?: Catalog.Catalog,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): Either.Either<
+  { content: string; schema?: Schema.Schema },
+  | VersionCoverageMismatchError
+  | VersionNotFoundInDocumentError
+  | Catalog.VersionNotFoundInCatalogError
+  | Catalog.EmptyCatalogError
+> => {
+  // Handle unversioned document
+  if (document._tag === 'DocumentUnversioned') {
+    const content = document.document
+
+    if (!catalog) {
+      return Either.right({ content })
+    }
+
+    return Catalog.resolveCatalogSchemaEither(catalog, null).pipe(
+      Either.map(schema => ({ content, schema })),
+    )
+  }
+
+  // Handle versioned document
+  let content: string
+  try {
+    content = resolveDocumentContent(document, versionCoverage)
+  } catch (error) {
+    // resolveDocumentContent throws our tagged error
+    if (error instanceof VersionNotFoundInDocumentError) {
+      return Either.left(error)
+    }
+    // This shouldn't happen but handle gracefully
+    return Either.left(
+      new VersionNotFoundInDocumentError({
+        version: String(versionCoverage),
+        reason: error instanceof Error ? error.message : String(error),
+      }),
+    )
+  }
+
+  if (!catalog) {
+    return Either.right({ content })
+  }
+
+  // Cannot use version coverage with unversioned catalog
+  if (versionCoverage && Catalog.Unversioned.is(catalog)) {
+    return Either.left(
+      new VersionCoverageMismatchError({
+        reason: 'Cannot use a version coverage with an unversioned catalog',
+      }),
+    )
+  }
+
+  return Catalog.resolveCatalogSchemaEither(catalog, versionCoverage).pipe(
+    Either.map(schema => ({ content, schema })),
+  )
+}

package/src/lib/document/versioned.ts

@@ -1,5 +1,5 @@
 import { S } from '#lib/kit-temp/effect'
-import { VersionCoverage } from '#lib/version-selection/$'
+import { VersionCoverage } from '#lib/version-coverage'
 import { Version } from '#lib/version/$'
 import { HashMap, Option } from 'effect'
 
@@ -56,21 +56,21 @@ export const encode = S.encode(DocumentVersioned)
 export const getContentForVersion = (
   doc: DocumentVersioned,
   version: Version.Version,
-): string | null => {
+): Option.Option<string> => {
   // Try exact match first (single version key)
   const exactMatch = HashMap.get(doc.versionDocuments, version)
   if (Option.isSome(exactMatch)) {
-    return exactMatch.value
+    return Option.some(exactMatch.value)
   }
 
   // Check version sets
   for (const [selection, content] of HashMap.entries(doc.versionDocuments)) {
     if (VersionCoverage.isSet(selection) && VersionCoverage.contains(selection, version)) {
-      return content
+      return Option.some(content)
     }
   }
 
-  return null
+  return Option.none()
 }
 
 /**
@@ -98,9 +98,9 @@ export const getContentForLatestVersionOrThrow = (doc: DocumentVersioned): strin
   // Use Version.max with reduce to find the latest version
   const latestVersion = versions.reduce(Version.max)
 
-  const content = getContentForVersion(doc, latestVersion)
-  if (!content) {
+  const contentOption = getContentForVersion(doc, latestVersion)
+  if (Option.isNone(contentOption)) {
     throw new Error('Latest version not found in document')
   }
-  return content
+  return contentOption.value
 }