polen 0.11.0-next.24 → 0.11.0-next.25

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

@@ -0,0 +1,6 @@
+export * from './apply.js'
+export * from './augmentation.js'
+export * from './config.js'
+export { Diagnostic } from './diagnostics/diagnostic.js'
+export * from './input.js'
+export * from './placement.js'

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

@@ -1 +1 @@
-export * as Augmentations from './schema-augmentation.js'
+export * as Augmentations from './$$.js'

package/src/api/schema/augmentations/apply.test.ts

@@ -0,0 +1,89 @@
+import type { GrafaidOld } from '#lib/grafaid-old'
+import { describe, expect, test } from 'vitest'
+import { mutateDescription } from './apply.js'
+import type { AugmentationConfig } from './config.js'
+
+describe('mutateDescription', () => {
+  describe('with empty existing description', () => {
+    test.for([
+      { placement: 'before' as const, expected: 'New content' },
+      { placement: 'after' as const, expected: 'New content' },
+      { placement: 'over' as const, expected: 'New content' },
+    ])('$placement placement does not add extra newlines', ({ placement, expected }) => {
+      const type = { description: undefined } as GrafaidOld.Groups.Describable
+      const augmentation: AugmentationConfig = {
+        on: {} as any, // Not used by mutateDescription
+        content: 'New content',
+        placement,
+      }
+
+      mutateDescription(type, augmentation)
+
+      expect(type.description).toBe(expected)
+    })
+
+    test.for([
+      { placement: 'before' as const, expected: 'New content' },
+      { placement: 'after' as const, expected: 'New content' },
+      { placement: 'over' as const, expected: 'New content' },
+    ])('$placement placement handles empty string description', ({ placement, expected }) => {
+      const type = { description: '' } as GrafaidOld.Groups.Describable
+      const augmentation: AugmentationConfig = {
+        on: {} as any,
+        content: 'New content',
+        placement,
+      }
+
+      mutateDescription(type, augmentation)
+
+      expect(type.description).toBe(expected)
+    })
+  })
+
+  describe('with existing description', () => {
+    test.for([
+      { placement: 'before' as const, expected: 'New content\n\nExisting description' },
+      { placement: 'after' as const, expected: 'Existing description\n\nNew content' },
+      { placement: 'over' as const, expected: 'New content' },
+    ])('$placement placement correctly combines content', ({ placement, expected }) => {
+      const type = { description: 'Existing description' } as GrafaidOld.Groups.Describable
+      const augmentation: AugmentationConfig = {
+        on: {} as any,
+        content: 'New content',
+        placement,
+      }
+
+      mutateDescription(type, augmentation)
+
+      expect(type.description).toBe(expected)
+    })
+  })
+
+  describe('edge cases', () => {
+    test('handles whitespace-only existing description as empty', () => {
+      const type = { description: '   \n  \t  ' } as GrafaidOld.Groups.Describable
+      const augmentation: AugmentationConfig = {
+        on: {} as any,
+        content: 'New content',
+        placement: 'before',
+      }
+
+      mutateDescription(type, augmentation)
+
+      expect(type.description).toBe('New content')
+    })
+
+    test('preserves meaningful whitespace in existing description', () => {
+      const type = { description: '  Indented content  ' } as GrafaidOld.Groups.Describable
+      const augmentation: AugmentationConfig = {
+        on: {} as any,
+        content: 'New content',
+        placement: 'before',
+      }
+
+      mutateDescription(type, augmentation)
+
+      expect(type.description).toBe('New content\n\nIndented content')
+    })
+  })
+})

package/src/api/schema/augmentations/apply.ts

@@ -0,0 +1,277 @@
+import type { Augmentation } from '#api/schema/augmentations/augmentation'
+import type { AugmentationConfig } from '#api/schema/augmentations/config'
+import {
+  Diagnostic,
+  makeDiagnosticDuplicateVersion,
+  makeDiagnosticInvalidPath,
+  makeDiagnosticVersionMismatch,
+} from '#api/schema/augmentations/diagnostics/diagnostic'
+import type { AugmentationInput } from '#api/schema/augmentations/input'
+import { normalizeAugmentationInput } from '#api/schema/augmentations/input'
+import type { GrafaidOld } from '#lib/grafaid-old'
+import { GraphQLPath } from '#lib/graphql-path'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Version } from '#lib/version/$'
+import { Either, HashMap, Match, Option, pipe } from 'effect'
+
+/**
+ * Apply version-aware augmentations to a schema.
+ *
+ * @param schema - The GraphQL schema to augment (mutated in place)
+ * @param augmentations - The input augmentations (may include version specifications)
+ * @param version - The specific version to apply augmentations for (null for unversioned)
+ * @returns Diagnostics generated during augmentation application
+ */
+export const applyAll = (
+  schema: GrafaidOld.Schema.Schema,
+  augmentations: readonly AugmentationInput[],
+  version: Version.Version | null = null,
+): { diagnostics: Diagnostic[] } => {
+  const diagnostics: Diagnostic[] = []
+
+  // Track versions to detect duplicates
+  const seenVersions = new Map<string, AugmentationInput>()
+
+  for (const augmentationInput of augmentations) {
+    // Check for duplicate versions
+    const versionKey = augmentationInput.versions
+      ? Object.keys(augmentationInput.versions).sort().join(',')
+      : 'unversioned'
+
+    if (seenVersions.has(versionKey) && versionKey !== 'unversioned') {
+      const firstInput = seenVersions.get(versionKey)!
+      diagnostics.push(makeDiagnosticDuplicateVersion({
+        message: `Duplicate version '${versionKey}' found in augmentation configuration`,
+        version: versionKey,
+        firstPath: firstInput.on ?? 'unknown',
+        duplicatePath: augmentationInput.on ?? 'unknown',
+      }))
+      continue
+    }
+    seenVersions.set(versionKey, augmentationInput)
+
+    // Transform input to normalized format
+    const normalized = normalizeAugmentationInput(augmentationInput)
+
+    if (!normalized) {
+      console.warn('Skipping invalid augmentation configuration')
+      continue
+    }
+
+    const applyDiagnostics = applyVersioned(schema, normalized, version)
+    diagnostics.push(...applyDiagnostics)
+  }
+
+  return { diagnostics }
+}
+
+export const apply = (
+  schema: GrafaidOld.Schema.Schema,
+  augmentation: AugmentationConfig,
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = []
+
+  pipe(
+    augmentation.on,
+    Match.value,
+    Match.when(
+      GraphQLPath.Definition.isTypeDefinitionPath,
+      (path) => {
+        pipe(
+          GraphQLPath.Schema.locateType(schema, path),
+          Either.match({
+            onLeft: (error) => {
+              diagnostics.push(makeDiagnosticInvalidPath({
+                message: `Type '${error.typeName}' not found in schema`,
+                path: error.path,
+                version: null,
+                error: `Type '${error.typeName}' not found`,
+              }))
+            },
+            onRight: (type) => {
+              mutateDescription(type, augmentation)
+            },
+          }),
+        )
+      },
+    ),
+    Match.when(
+      GraphQLPath.Definition.isFieldDefinitionPath,
+      (path) => {
+        pipe(
+          GraphQLPath.Schema.locateField(schema, path),
+          Either.match({
+            onLeft: (error) => {
+              diagnostics.push(makeDiagnosticInvalidPath({
+                message: `Field '${error.fieldName}' not found on type '${error.typeName}'`,
+                path: error.path,
+                version: null,
+                error: `Field '${error.fieldName}' not found on type '${error.typeName}'`,
+              }))
+            },
+            onRight: (field) => {
+              mutateDescription(field, augmentation)
+            },
+          }),
+        )
+      },
+    ),
+    Match.orElse(() => {
+      diagnostics.push(makeDiagnosticInvalidPath({
+        message: `Unsupported path type for augmentations: ${GraphQLPath.Definition.encodeSync(augmentation.on)}`,
+        path: GraphQLPath.Definition.encodeSync(augmentation.on),
+        version: null,
+        error: 'Unsupported path type for augmentations',
+      }))
+    }),
+  )
+
+  return diagnostics
+}
+
+/**
+ * Apply a version-aware augmentation to a schema.
+ *
+ * @param schema - The GraphQL schema to augment
+ * @param augmentation - The normalized augmentation with version coverage
+ * @param version - The specific version to apply augmentations for (null for unversioned)
+ * @returns Diagnostics generated during augmentation application
+ */
+export const applyVersioned = (
+  schema: GrafaidOld.Schema.Schema,
+  augmentation: Augmentation,
+  version: Version.Version | null,
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = []
+  // Try to find augmentation for this specific version
+  let config: AugmentationConfig | undefined
+
+  if (version) {
+    // First try exact version match
+    const versionCoverage = VersionCoverage.single(version)
+    const maybeConfig = HashMap.get(augmentation.versionAugmentations, versionCoverage)
+    if (Option.isSome(maybeConfig)) {
+      config = maybeConfig.value
+    }
+
+    // If not found, check if any coverage matches this version
+    if (!config) {
+      for (const [coverage, cfg] of augmentation.versionAugmentations) {
+        if (VersionCoverage.matches(coverage, version)) {
+          config = cfg
+          break
+        }
+      }
+    }
+  } else {
+    // For unversioned schemas, only apply unversioned augmentations
+    const unversionedCoverage = VersionCoverage.unversioned()
+    const maybeConfig = HashMap.get(augmentation.versionAugmentations, unversionedCoverage)
+    if (Option.isSome(maybeConfig)) {
+      config = maybeConfig.value
+    }
+  }
+
+  // Apply the augmentation if found
+  if (config) {
+    pipe(
+      config.on,
+      Match.value,
+      Match.when(
+        GraphQLPath.Definition.isTypeDefinitionPath,
+        (path) => {
+          pipe(
+            GraphQLPath.Schema.locateType(schema, path),
+            Either.match({
+              onLeft: (error) => {
+                diagnostics.push(makeDiagnosticInvalidPath({
+                  message: `Type '${error.typeName}' not found in schema`,
+                  path: error.path,
+                  version: version,
+                  error: `Type '${error.typeName}' not found`,
+                }))
+              },
+              onRight: (type) => {
+                mutateDescription(type, config)
+              },
+            }),
+          )
+        },
+      ),
+      Match.when(
+        GraphQLPath.Definition.isFieldDefinitionPath,
+        (path) => {
+          pipe(
+            GraphQLPath.Schema.locateField(schema, path),
+            Either.match({
+              onLeft: (error) => {
+                diagnostics.push(makeDiagnosticInvalidPath({
+                  message: `Field '${error.fieldName}' not found on type '${error.typeName}'`,
+                  path: error.path,
+                  version: version,
+                  error: `Field '${error.fieldName}' not found on type '${error.typeName}'`,
+                }))
+              },
+              onRight: (field) => {
+                mutateDescription(field, config)
+              },
+            }),
+          )
+        },
+      ),
+      Match.orElse(() => {
+        diagnostics.push(makeDiagnosticInvalidPath({
+          message: `Unsupported path type for augmentations: ${GraphQLPath.Definition.encodeSync(config.on)}`,
+          path: GraphQLPath.Definition.encodeSync(config.on),
+          version: version,
+          error: 'Unsupported path type for augmentations',
+        }))
+      }),
+    )
+  } else if (version && HashMap.size(augmentation.versionAugmentations) > 0) {
+    // No matching version coverage found - generate version mismatch diagnostic
+    // Get first config from HashMap
+    const firstEntry = pipe(
+      augmentation.versionAugmentations,
+      HashMap.values,
+      (iter) => Array.from(iter)[0],
+    )
+
+    if (firstEntry) {
+      diagnostics.push(makeDiagnosticVersionMismatch({
+        message: `No augmentation found for version '${version}' on path '${
+          GraphQLPath.Definition.encodeSync(firstEntry.on)
+        }'`,
+        path: GraphQLPath.Definition.encodeSync(firstEntry.on),
+        requestedVersion: version,
+        availableVersions: pipe(
+          augmentation.versionAugmentations,
+          HashMap.keys,
+          (iter) => Array.from(iter).map(VersionCoverage.toLabel),
+        ),
+      }))
+    }
+  }
+
+  return diagnostics
+}
+
+export const mutateDescription = (
+  type: GrafaidOld.Groups.Describable,
+  augmentation: AugmentationConfig,
+) => {
+  const existingDescription = type.description?.trim() ?? ''
+
+  type.description = Match.value(augmentation.placement).pipe(
+    Match.when(
+      'before',
+      () => existingDescription ? `${augmentation.content}\n\n${existingDescription}` : augmentation.content,
+    ),
+    Match.when(
+      'after',
+      () => existingDescription ? `${existingDescription}\n\n${augmentation.content}` : augmentation.content,
+    ),
+    Match.when('over', () => augmentation.content),
+    Match.exhaustive,
+  )
+}

package/src/api/schema/augmentations/augmentation.ts

@@ -0,0 +1,24 @@
+import { AugmentationConfig } from '#api/schema/augmentations/config'
+import { S } from '#lib/kit-temp/effect'
+import { VersionCoverage } from '#lib/version-coverage'
+
+/**
+ * Internal normalized schema for description augmentations.
+ * Uses VersionCoverage as keys to support unversioned (all versions) and version-specific augmentations.
+ */
+export const Augmentation = S.Struct({
+  // Map from VersionCoverage to augmentation config
+  // Key can be:
+  // - VersionCoverageUnversioned: applies to all versions
+  // - VersionCoverageOne: applies to a specific version
+  // - VersionCoverageSet: applies to a set of versions (future enhancement)
+  versionAugmentations: S.HashMap({
+    key: VersionCoverage.VersionCoverage,
+    value: AugmentationConfig,
+  }),
+}).annotations({
+  identifier: 'AugmentationNormalized',
+  description: 'Internal normalized description augmentation with version coverage support',
+})
+
+export type Augmentation = S.Schema.Type<typeof Augmentation>

package/src/api/schema/augmentations/config.ts

@@ -0,0 +1,11 @@
+import { Placement } from '#api/schema/augmentations/placement'
+import { GraphQLPath } from '#lib/graphql-path'
+import { S } from '#lib/kit-temp/effect'
+
+export const AugmentationConfig = S.Struct({
+  on: GraphQLPath.Definition.DefinitionPath,
+  placement: Placement,
+  content: S.String,
+})
+
+export type AugmentationConfig = S.Schema.Type<typeof AugmentationConfig>

package/src/api/schema/augmentations/diagnostics/diagnostic.ts

@@ -0,0 +1,20 @@
+import { DiagnosticDuplicateVersion } from '#api/schema/augmentations/diagnostics/duplicate-version'
+import { DiagnosticInvalidPath } from '#api/schema/augmentations/diagnostics/invalid-path'
+import { DiagnosticVersionMismatch } from '#api/schema/augmentations/diagnostics/version-mismatch'
+import { S } from '#lib/kit-temp/effect'
+
+// Re-export all individual diagnostics
+export * from './duplicate-version.js'
+export * from './invalid-path.js'
+export * from './version-mismatch.js'
+
+export const Diagnostic = S.Union(
+  DiagnosticInvalidPath,
+  DiagnosticVersionMismatch,
+  DiagnosticDuplicateVersion,
+).annotations({
+  identifier: 'AugmentationsDiagnostic',
+  description: 'All diagnostics that can be generated for schema augmentations',
+})
+
+export type Diagnostic = S.Schema.Type<typeof Diagnostic>

package/src/api/schema/augmentations/diagnostics/duplicate-version.ts

@@ -0,0 +1,20 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+export const DiagnosticDuplicateVersion = Diagnostic.create({
+  source: 'schema-augmentations',
+  name: 'duplicate-version',
+  severity: 'error',
+  context: {
+    version: S.String,
+    firstPath: S.String,
+    duplicatePath: S.String,
+  },
+}).annotations({
+  identifier: 'DiagnosticDuplicateVersion',
+  description: 'Same version is specified multiple times in augmentation configuration',
+})
+
+export const makeDiagnosticDuplicateVersion = Diagnostic.createMake(DiagnosticDuplicateVersion)
+
+export type DiagnosticDuplicateVersion = S.Schema.Type<typeof DiagnosticDuplicateVersion>

package/src/api/schema/augmentations/diagnostics/invalid-path.ts

@@ -0,0 +1,21 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+import { Version } from '#lib/version/$'
+
+export const DiagnosticInvalidPath = Diagnostic.create({
+  source: 'schema-augmentations',
+  name: 'invalid-path',
+  severity: 'error',
+  context: {
+    path: S.String,
+    version: S.optional(S.Union(Version.Version, S.Null)),
+    error: S.String,
+  },
+}).annotations({
+  identifier: 'DiagnosticInvalidPath',
+  description: 'Augmentation references a non-existent type or field in the schema',
+})
+
+export const makeDiagnosticInvalidPath = Diagnostic.createMake(DiagnosticInvalidPath)
+
+export type DiagnosticInvalidPath = S.Schema.Type<typeof DiagnosticInvalidPath>

package/src/api/schema/augmentations/diagnostics/version-mismatch.ts

@@ -0,0 +1,21 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+import { Version } from '#lib/version/$'
+
+export const DiagnosticVersionMismatch = Diagnostic.create({
+  source: 'schema-augmentations',
+  name: 'version-mismatch',
+  severity: 'error',
+  context: {
+    path: S.String,
+    requestedVersion: Version.Version,
+    availableVersions: S.Array(S.String),
+  },
+}).annotations({
+  identifier: 'DiagnosticVersionMismatch',
+  description: 'Augmentation specifies a version that does not match any schema version',
+})
+
+export const makeDiagnosticVersionMismatch = Diagnostic.createMake(DiagnosticVersionMismatch)
+
+export type DiagnosticVersionMismatch = S.Schema.Type<typeof DiagnosticVersionMismatch>

package/src/api/schema/augmentations/input.test.ts

@@ -0,0 +1,144 @@
+import { VersionCoverage } from '#lib/version-coverage'
+import { Version } from '#lib/version/$'
+import { HashMap, Option } from 'effect'
+import { describe, expect, test } from 'vitest'
+import { normalizeAugmentationInput } from './input.js'
+
+describe('Description Augmentation Transform', () => {
+  test('transforms unversioned augmentation', () => {
+    const input = {
+      on: 'Query',
+      placement: 'before' as const,
+      content: 'Test content',
+    }
+
+    const result = normalizeAugmentationInput(input)
+    expect(result).not.toBeNull()
+
+    // Should have one unversioned entry
+    expect(HashMap.size(result!.versionAugmentations)).toBe(1)
+
+    // Check the entry exists by iterating
+    let foundUnversioned = false
+    for (const [coverage, config] of result!.versionAugmentations) {
+      if (VersionCoverage.isUnversioned(coverage)) {
+        foundUnversioned = true
+        expect(config.content).toBe('Test content')
+        expect(config.placement).toBe('before')
+      }
+    }
+    expect(foundUnversioned).toBe(true)
+  })
+
+  test('transforms versioned augmentation with defaults', () => {
+    const input = {
+      on: 'Pokemon',
+      placement: 'after' as const,
+      content: 'Default content',
+      versions: {
+        v1: { content: 'V1 content' },
+        v2: { content: 'V2 content', placement: 'before' as const },
+      },
+    }
+
+    const result = normalizeAugmentationInput(input)
+    expect(result).not.toBeNull()
+
+    // Should have two version entries (no unversioned when versions exist)
+    expect(HashMap.size(result!.versionAugmentations)).toBe(2)
+
+    // Check v1 - inherits placement from default
+    const v1 = Version.decodeSync('v1')
+    const v1Config = HashMap.get(
+      result!.versionAugmentations,
+      VersionCoverage.single(v1),
+    )
+    expect(Option.isSome(v1Config)).toBe(true)
+    if (Option.isSome(v1Config)) {
+      expect(v1Config.value.content).toBe('V1 content')
+      expect(v1Config.value.placement).toBe('after') // inherited
+    }
+
+    // Check v2 - overrides placement
+    const v2 = Version.decodeSync('v2')
+    const v2Config = HashMap.get(
+      result!.versionAugmentations,
+      VersionCoverage.single(v2),
+    )
+    expect(Option.isSome(v2Config)).toBe(true)
+    if (Option.isSome(v2Config)) {
+      expect(v2Config.value.content).toBe('V2 content')
+      expect(v2Config.value.placement).toBe('before') // overridden
+    }
+  })
+
+  test('transforms version-only augmentation', () => {
+    const input = {
+      versions: {
+        v2: {
+          on: 'Pokemon.stats',
+          content: 'V2 only content',
+          placement: 'after' as const,
+        },
+      },
+    }
+
+    const result = normalizeAugmentationInput(input)
+    expect(result).not.toBeNull()
+
+    // Should have one version entry
+    expect(HashMap.size(result!.versionAugmentations)).toBe(1)
+
+    const v2 = Version.decodeSync('v2')
+    const v2Config = HashMap.get(
+      result!.versionAugmentations,
+      VersionCoverage.single(v2),
+    )
+    expect(Option.isSome(v2Config)).toBe(true)
+    if (Option.isSome(v2Config)) {
+      expect(v2Config.value.content).toBe('V2 only content')
+      // v2Config.value.on is now a GraphQLPath.Definition.FieldDefinitionPath
+      // which is a tuple: [TypeSegment, FieldSegment]
+      expect(v2Config.value.on).toEqual([
+        { _tag: 'TypeSegment', type: 'Pokemon' },
+        { _tag: 'FieldSegment', field: 'stats' },
+      ])
+    }
+  })
+
+  test('returns null for invalid augmentation', () => {
+    const input = {
+      // Missing required fields and no versions
+    }
+
+    const result = normalizeAugmentationInput(input)
+    expect(result).toBeNull()
+  })
+
+  test('skips incomplete version entries', () => {
+    const input = {
+      on: 'Query',
+      // Missing placement and content at top level
+      versions: {
+        v1: { content: 'V1 content' }, // Missing placement, can't inherit
+        v2: {
+          content: 'V2 content',
+          placement: 'after' as const,
+        }, // Complete
+      },
+    }
+
+    const result = normalizeAugmentationInput(input)
+    expect(result).not.toBeNull()
+
+    // Should have only v2 (v1 is incomplete)
+    expect(HashMap.size(result!.versionAugmentations)).toBe(1)
+
+    const v2 = Version.decodeSync('v2')
+    const v2Config = HashMap.get(
+      result!.versionAugmentations,
+      VersionCoverage.single(v2),
+    )
+    expect(Option.isSome(v2Config)).toBe(true)
+  })
+})