polen 0.11.0-next.17 → 0.11.0-next.19

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
 }

package/src/lib/lifecycles/lifecycles.ts

@@ -3,7 +3,7 @@ import { Change } from '#lib/change/$'
 import { Revision } from '#lib/revision/$'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
-import { Match } from 'effect'
+import { Match, Option } from 'effect'
 
 // ============================================================================
 // Lifecycles Type - Simple Index
@@ -44,21 +44,21 @@ export type Since =
 /**
  * Extract the type name from a change
  */
-const extractTypeNameFromChange = (change: Change.Change): string | null => {
+const extractTypeNameFromChange = (change: Change.Change): Option.Option<string> => {
   return Match.value(change).pipe(
-    Match.tag('TYPE_ADDED', (c) => c.name),
-    Match.tag('TYPE_REMOVED', (c) => c.name),
-    Match.tag('FIELD_ADDED', (c) => c.typeName),
-    Match.tag('FIELD_REMOVED', (c) => c.typeName),
-    Match.tag('INPUT_FIELD_ADDED', (c) => c.inputName),
-    Match.tag('INPUT_FIELD_REMOVED', (c) => c.inputName),
-    Match.tag('ENUM_VALUE_ADDED', (c) => c.enumName),
-    Match.tag('ENUM_VALUE_REMOVED', (c) => c.enumName),
-    Match.tag('UNION_MEMBER_ADDED', (c) => c.unionName),
-    Match.tag('UNION_MEMBER_REMOVED', (c) => c.unionName),
-    Match.tag('OBJECT_TYPE_INTERFACE_ADDED', (c) => c.objectName),
-    Match.tag('OBJECT_TYPE_INTERFACE_REMOVED', (c) => c.objectName),
-    Match.orElse(() => null),
+    Match.tag('TYPE_ADDED', (c) => Option.some(c.name)),
+    Match.tag('TYPE_REMOVED', (c) => Option.some(c.name)),
+    Match.tag('FIELD_ADDED', (c) => Option.some(c.typeName)),
+    Match.tag('FIELD_REMOVED', (c) => Option.some(c.typeName)),
+    Match.tag('INPUT_FIELD_ADDED', (c) => Option.some(c.inputName)),
+    Match.tag('INPUT_FIELD_REMOVED', (c) => Option.some(c.inputName)),
+    Match.tag('ENUM_VALUE_ADDED', (c) => Option.some(c.enumName)),
+    Match.tag('ENUM_VALUE_REMOVED', (c) => Option.some(c.enumName)),
+    Match.tag('UNION_MEMBER_ADDED', (c) => Option.some(c.unionName)),
+    Match.tag('UNION_MEMBER_REMOVED', (c) => Option.some(c.unionName)),
+    Match.tag('OBJECT_TYPE_INTERFACE_ADDED', (c) => Option.some(c.objectName)),
+    Match.tag('OBJECT_TYPE_INTERFACE_REMOVED', (c) => Option.some(c.objectName)),
+    Match.orElse(() => Option.none()),
   )
 }
 
@@ -72,8 +72,9 @@ export const createFromSchema = (schema: Schema.Schema): Lifecycles => {
   for (const revision of schema.revisions) {
     // Process all changes in this revision
     for (const change of revision.changes) {
-      const typeName = extractTypeNameFromChange(change)
-      if (typeName) {
+      const typeNameOption = extractTypeNameFromChange(change)
+      if (Option.isSome(typeNameOption)) {
+        const typeName = typeNameOption.value
         if (!lifecycles[typeName]) {
           lifecycles[typeName] = []
         }
@@ -100,8 +101,9 @@ export const create = (catalog: Catalog.Catalog): Lifecycles => {
     for (const revision of schema.revisions) {
       // Process all changes in this revision
       for (const change of revision.changes) {
-        const typeName = extractTypeNameFromChange(change)
-        if (typeName) {
+        const typeNameOption = extractTypeNameFromChange(change)
+        if (Option.isSome(typeNameOption)) {
+          const typeName = typeNameOption.value
           if (!lifecycles[typeName]) {
             lifecycles[typeName] = []
           }
@@ -477,9 +479,9 @@ export const getFieldLifecycle = (
   lifecycles: Lifecycles,
   typeName: string,
   fieldName: string,
-): { events: ChangeEntry[] } | undefined => {
+): Option.Option<{ events: ChangeEntry[] }> => {
   const entries = lifecycles[typeName]
-  if (!entries) return undefined
+  if (!entries) return Option.none()
 
   // Filter entries related to this specific field
   const fieldEntries = entries.filter(entry => {
@@ -497,25 +499,28 @@ export const getFieldLifecycle = (
         && entry.change.fieldName === fieldName)
   })
 
-  if (fieldEntries.length === 0) return undefined
+  if (fieldEntries.length === 0) return Option.none()
 
   // Return in a format compatible with existing code that expects an object with events
-  return { events: fieldEntries }
+  return Option.some({ events: fieldEntries })
 }
 
 /**
  * Get type lifecycle info (for compatibility with existing UI code)
  */
-export const getTypeLifecycle = (lifecycles: Lifecycles, typeName: string): { events: ChangeEntry[] } | undefined => {
+export const getTypeLifecycle = (
+  lifecycles: Lifecycles,
+  typeName: string,
+): Option.Option<{ events: ChangeEntry[] }> => {
   const entries = lifecycles[typeName]
-  if (!entries) return undefined
+  if (!entries) return Option.none()
 
   // Filter entries related to type-level changes
   const typeEntries = entries.filter(entry => {
     return entry.change._tag === 'TYPE_ADDED' || entry.change._tag === 'TYPE_REMOVED'
   })
 
-  if (typeEntries.length === 0) return undefined
+  if (typeEntries.length === 0) return Option.none()
 
-  return { events: typeEntries }
+  return Option.some({ events: typeEntries })
 }

package/src/lib/version-coverage/$$.ts

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

package/src/lib/{version-selection/version-selection.ts → version-coverage/version-coverage.ts}

@@ -58,7 +58,7 @@ export const encodeSync = S.encodeSync(VersionCoverage)
 export const equivalence = S.equivalence(VersionCoverage)
 
 // ============================================================================
-// Domain Logic
+// Domain Logic - Basic Operations
 // ============================================================================
 
 /**

package/src/template/components/GraphQLDocument.tsx

@@ -1,12 +1,7 @@
 import { Catalog } from '#lib/catalog/$'
 import { Document } from '#lib/document/$'
-import { S } from '#lib/kit-temp/$'
-import type { Schema } from '#lib/schema/$'
-import { VersionCoverage } from '#lib/version-selection/$'
-import { VersionCoverageSet } from '#lib/version-selection/version-selection'
-import { Version } from '#lib/version/$'
-import { Array, HashMap, Match, Option } from 'effect'
-import type { GraphQLSchema } from 'graphql'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Either, Option } from 'effect'
 import * as React from 'react'
 import { useHighlighted } from '../hooks/use-highlighted.js'
 import { GraphQLInteractive } from './GraphQLInteractive/GraphQLInteractive.js'
@@ -47,7 +42,7 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
   /// ━ VERSION MANAGEMENT
   const isControlled = controlledVersionCoverage !== undefined
   const [internalVersionCoverage, setInternalVersionCoverage] = React.useState<VersionCoverage.VersionCoverage | null>(
-    Catalog.getLatestVersion(schemaCatalog),
+    Option.getOrNull(Catalog.getLatestVersion(schemaCatalog)),
   )
   const selectedVersionCoverage = isControlled ? controlledVersionCoverage : internalVersionCoverage
   const internalOnVersionChange = (version: VersionCoverage.VersionCoverage) => {
@@ -58,11 +53,15 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
   }
 
   /// ━ DATA RESOLUTION
-  const {
-    schema,
-    content,
-  } = resolveSelectedVerCov(document, selectedVersionCoverage, schemaCatalog)
+  const result = Document.resolveDocumentAndSchema(document, schemaCatalog, selectedVersionCoverage)
 
+  // Handle resolution errors gracefully
+  if (Either.isLeft(result)) {
+    console.error('Failed to resolve document and schema:', result.left.message)
+    return null
+  }
+
+  const { schema, content } = result.right
   const highlightedCode = useHighlighted(content, { interactive: true })
 
   if (!highlightedCode) {
@@ -87,60 +86,3 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
     />
   )
 }
-
-/**
- * Matches a document with an optional schema catalog, returning the document content,
- * corresponding schema, and available versions for the selected version.
- *
- * @param document - The document to retrieve content from (required)
- * @param selectedVersionCoverage - The version to select (optional, defaults to latest)
- * @param schemaCatalog - The schema catalog to match against (optional)
- * @returns Object with document content, optional schema, and available versions
- * @throws {Error} If versions in catalog don't match versions in document
- */
-type Result = { content: string; schema?: Schema.Schema }
-const resolveSelectedVerCov = (
-  document: Document.Document,
-  selectedVersionCoverage?: VersionCoverage.VersionCoverage | null,
-  schemaCatalog?: Catalog.Catalog,
-): Result => {
-  if (Document.Unversioned.is(document)) {
-    return {
-      content: document.document,
-      schema: Match.value(schemaCatalog).pipe(
-        Match.tagsExhaustive({
-          CatalogUnversioned: (catalog) => catalog.schema,
-          CatalogVersioned: (catalog) => Catalog.Versioned.getLatestOrThrow(catalog),
-        }),
-      ),
-    }
-  }
-
-  return Match.value(selectedVersionCoverage).pipe(
-    Match.whenOr(null, undefined, _ => {
-      const content = Document.Versioned.getContentForLatestVersionOrThrow(document)
-      return { content }
-    }),
-    Match.orElse(_ => {
-      const version = VersionCoverage.getLatest(_)
-
-      const content = Document.Versioned.getContentForVersion(document, version)
-      if (!content) {
-        throw new Error(`Version ${Version.encodeSync(version)} not covered by document`)
-      }
-
-      if (!schemaCatalog) return { version, content }
-
-      if (Catalog.Unversioned.is(schemaCatalog)) {
-        throw new Error('Cannot use a set of versions with an unversioned catalog')
-      }
-      const schemaOption = HashMap.get(schemaCatalog.entries, version)
-      if (Option.isNone(schemaOption)) {
-        throw new Error(`Version ${Version.encodeSync(version)} not found in catalog`)
-      }
-      const schema = Option.getOrThrow(schemaOption)
-
-      return { content, schema: schema }
-    }),
-  )
-}

package/src/template/components/GraphQLInteractive/lib/parser.ts

@@ -7,6 +7,7 @@
 
 import { Api } from '#api/iso'
 import type { CodeAnnotation } from 'codehike/code'
+import { Either } from 'effect'
 import {
   getNamedType,
   type GraphQLArgument,
@@ -504,41 +505,65 @@ class SemanticContext {
 }
 
 /**
- * Parse GraphQL code into interactive tokens with semantic information
+ * Error types for GraphQL parsing
+ */
+export type ParseError =
+  | { readonly _tag: 'InvalidInput'; readonly message: string }
+  | { readonly _tag: 'DocumentTooLarge'; readonly maxSize: number; readonly actualSize: number }
+  | { readonly _tag: 'TreeSitterError'; readonly message: string }
+  | { readonly _tag: 'ParserInitError'; readonly message: string }
+
+const makeParseError = {
+  invalidInput: (message: string): ParseError => ({ _tag: 'InvalidInput', message }),
+  documentTooLarge: (maxSize: number, actualSize: number): ParseError => ({
+    _tag: 'DocumentTooLarge',
+    maxSize,
+    actualSize,
+  }),
+  treeSitterError: (message: string): ParseError => ({ _tag: 'TreeSitterError', message }),
+  parserInitError: (message: string): ParseError => ({ _tag: 'ParserInitError', message }),
+}
+
+/**
+ * Parse GraphQL code into interactive tokens with semantic information (Either version)
  *
  * @param code - The raw GraphQL code to parse
  * @param annotations - CodeHike annotations that might affect rendering
  * @param schema - Optional GraphQL schema for semantic analysis
- * @returns Array of tokens representing the parsed code
+ * @returns Either with array of tokens on right or ParseError on left
  */
-export async function parseGraphQLWithTreeSitter(
+export async function parseGraphQLWithTreeSitterEither(
   code: string,
   annotations: CodeAnnotation[] = [],
   schema?: GraphQLSchema,
-): Promise<GraphQLToken[]> {
+): Promise<Either.Either<GraphQLToken[], ParseError>> {
   // Validate input
   if (!code || typeof code !== 'string') {
-    throw new Error('Invalid GraphQL code: code must be a non-empty string')
+    return Either.left(makeParseError.invalidInput('Invalid GraphQL code: code must be a non-empty string'))
   }
 
   // Prevent parsing extremely large documents that could cause performance issues
-  if (code.length > 100_000) {
-    throw new Error('GraphQL document too large: maximum 100,000 characters allowed')
+  const maxSize = 100_000
+  if (code.length > maxSize) {
+    return Either.left(makeParseError.documentTooLarge(maxSize, code.length))
   }
 
   // Step 1: Parse with tree-sitter
-  const parser = await getParser()
+  let parser: WebTreeSitter.Parser
+  try {
+    parser = await getParser()
+  } catch (error) {
+    return Either.left(makeParseError.parserInitError(
+      error instanceof Error ? error.message : 'Failed to initialize parser',
+    ))
+  }
+
   const tree = parser.parse(code)
 
   if (!tree) {
-    throw new Error('Tree-sitter failed to parse GraphQL code')
+    return Either.left(makeParseError.treeSitterError('Tree-sitter failed to parse GraphQL code'))
   }
 
-  // Check if tree-sitter found syntax errors (disabled for now as it may be too strict)
-  // if (tree.rootNode.hasError) {
-  //   throw new Error('GraphQL syntax error detected by tree-sitter parser')
-  // }
-
   try {
     // Step 2: Walk tree and attach semantics
     const tokens = collectTokensWithSemantics(tree, code, schema, annotations)
@@ -546,26 +571,53 @@ export async function parseGraphQLWithTreeSitter(
     // Step 3: Add error hint tokens after invalid fields
     const tokensWithHints = addErrorHintTokens(tokens, code, annotations)
 
-    return tokensWithHints
+    return Either.right(tokensWithHints)
+  } catch (error) {
+    return Either.left(makeParseError.treeSitterError(
+      error instanceof Error ? error.message : 'Failed to process tokens',
+    ))
   } finally {
-    // ## Tree-sitter Resource Lifecycle Management
-    //
-    // Tree-sitter creates native WASM objects that must be explicitly freed to prevent memory leaks.
-    // The tree object holds references to parsed nodes and internal parser state that won't be
-    // garbage collected automatically by JavaScript.
-    //
-    // Critical cleanup points:
-    // 1. Always call tree.delete() in a finally block to ensure cleanup even on errors
-    // 2. Do not access tree or any of its nodes after calling delete()
-    // 3. The parser instance is cached globally and reused across multiple parsing calls
-    //
-    // Memory safety: Once tree.delete() is called, all WebTreeSitter.Node references become invalid.
-    // Our tokens hold references to these nodes, but only use their text and position properties
-    // which are copied during token creation, so the nodes can be safely deleted.
+    // Tree-sitter Resource Lifecycle Management
     tree.delete()
   }
 }
 
+/**
+ * Parse GraphQL code into interactive tokens with semantic information
+ *
+ * @param code - The raw GraphQL code to parse
+ * @param annotations - CodeHike annotations that might affect rendering
+ * @param schema - Optional GraphQL schema for semantic analysis
+ * @returns Array of tokens representing the parsed code
+ * @deprecated Use parseGraphQLWithTreeSitterEither for better error handling
+ */
+export async function parseGraphQLWithTreeSitter(
+  code: string,
+  annotations: CodeAnnotation[] = [],
+  schema?: GraphQLSchema,
+): Promise<GraphQLToken[]> {
+  const result = await parseGraphQLWithTreeSitterEither(code, annotations, schema)
+
+  if (Either.isLeft(result)) {
+    const error = result.left
+    switch (error._tag) {
+      case 'InvalidInput':
+        throw new Error(error.message)
+      case 'DocumentTooLarge':
+        throw new Error(`GraphQL document too large: maximum ${error.maxSize} characters allowed`)
+      case 'TreeSitterError':
+      case 'ParserInitError':
+        throw new Error(error.message)
+      default: {
+        const exhaustiveCheck: never = error
+        throw new Error(`Unhandled parse error: ${JSON.stringify(exhaustiveCheck)}`)
+      }
+    }
+  }
+
+  return result.right
+}
+
 /**
  * Get or create the tree-sitter parser instance
  */