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

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

@@ -0,0 +1,215 @@
+import type { Augmentation } from '#api/schema/augmentations/augmentation'
+import type { AugmentationConfig } from '#api/schema/augmentations/config'
+import { Placement } from '#api/schema/augmentations/placement'
+import { GraphQLPath } from '#lib/graphql-path'
+import { S } from '#lib/kit-temp/effect'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Version } from '#lib/version/$'
+import { HashMap } from 'effect'
+
+/**
+ * Configuration for augmenting GraphQL schema descriptions.
+ *
+ * This schema supports two usage patterns:
+ *
+ * 1. **Unversioned augmentations** - Apply to all schema versions
+ * 2. **Version-specific augmentations** - Apply to specific schema versions with optional defaults
+ *
+ * @example
+ * ```ts
+ * // Unversioned - applies to all versions
+ * {
+ *   on: 'Pokemon',
+ *   placement: 'after',
+ *   content: '**Note:** This type includes battle stats.'
+ * }
+ *
+ * // Version-specific with defaults
+ * {
+ *   on: 'Pokemon',                    // Default for all versions
+ *   placement: 'after',                // Default for all versions
+ *   content: 'Base Pokemon info.',    // Default content
+ *   versions: {
+ *     '2': {
+ *       content: 'Enhanced Pokemon with battle capabilities.' // Override for v2
+ *     },
+ *     '3': {
+ *       on: 'BattlePokemon',          // Different type in v3
+ *       content: 'Battle-ready Pokemon with full stats.'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * When using version-specific augmentations:
+ * - Top-level fields serve as defaults for all versions
+ * - Version-specific fields override defaults
+ * - A version entry must have complete configuration (after merging with defaults) to be valid
+ * - Invalid paths or missing types will generate build diagnostics rather than crashing
+ */
+export const AugmentationInput = S.Struct({
+  /**
+   * GraphQL path to the type or field to augment.
+   *
+   * @example
+   * - Type path: `'Pokemon'`, `'Query'`, `'User'`
+   * - Field path: `'Pokemon.name'`, `'Query.users'`, `'Mutation.createUser'`
+   *
+   * @remarks
+   * If the specified path doesn't exist in the schema, a diagnostic error will be generated
+   * during the build process rather than causing a crash.
+   */
+  on: S.optional(S.String),
+
+  /**
+   * How to apply the augmentation content relative to existing description.
+   *
+   * - `'over'` - Replace the existing description entirely
+   * - `'before'` - Prepend content to the existing description
+   * - `'after'` - Append content to the existing description
+   *
+   * @default 'after'
+   */
+  placement: S.optional(Placement),
+
+  /**
+   * The content to add to the description.
+   *
+   * Supports full Markdown syntax including:
+   * - Bold/italic text
+   * - Code blocks and inline code
+   * - Links
+   * - Lists
+   * - Tables
+   *
+   * @example
+   * ```ts
+   * content: `
+   * **Important:** This field requires authentication.
+   *
+   * Example query:
+   * \`\`\`graphql
+   * query {
+   *   users(limit: 10) {
+   *     id
+   *     name
+   *   }
+   * }
+   * \`\`\`
+   * `
+   * ```
+   */
+  content: S.optional(S.String),
+
+  /**
+   * Version-specific augmentation overrides.
+   *
+   * Keys are version identifiers (e.g., `'1'`, `'2'`, `'3'`).
+   * Values are partial augmentation configs that override top-level defaults.
+   *
+   * @example
+   * ```ts
+   * versions: {
+   *   '1': { content: 'Legacy API - see migration guide.' },
+   *   '2': { content: 'Current stable API.' },
+   *   '3': {
+   *     on: 'NewTypeName',  // Type renamed in v3
+   *     content: 'Beta API - subject to change.'
+   *   }
+   * }
+   * ```
+   *
+   * @remarks
+   * - Version keys must be valid numeric strings
+   * - Each version inherits top-level defaults
+   * - Invalid version identifiers will generate build diagnostics
+   * - Duplicate version keys will generate build diagnostics
+   */
+  versions: S.optional(
+    S.Record({
+      key: S.String,
+      value: S.Struct({
+        on: S.optional(S.String),
+        placement: S.optional(Placement),
+        content: S.optional(S.String),
+      }),
+    }),
+  ),
+}).annotations({
+  identifier: 'AugmentationInput',
+  description: 'Configuration for augmenting GraphQL schema descriptions with version support',
+})
+
+export type AugmentationInput = S.Schema.Type<typeof AugmentationInput>
+
+/**
+ * Transform user-facing input to normalized internal representation.
+ *
+ * Rules:
+ * 1. If no versions field → create single unversioned entry
+ * 2. If versions field exists:
+ *    - Create version-specific entries for each version
+ *    - If top-level defaults exist, they are used as fallbacks for version entries
+ *    - If a version entry would be incomplete without defaults, skip it
+ */
+export const normalizeAugmentationInput = (input: AugmentationInput): Augmentation | null => {
+  const map = HashMap.empty<VersionCoverage.VersionCoverage, AugmentationConfig>()
+
+  // Case 1: No versions field - create unversioned entry
+  if (!input.versions || Object.keys(input.versions).length === 0) {
+    // Must have complete top-level configuration
+    if (!input.on || !input.placement || !input.content) {
+      return null // Invalid: incomplete unversioned augmentation
+    }
+
+    const unversionedConfig: AugmentationConfig = {
+      on: GraphQLPath.Definition.decodeSync(input.on),
+      placement: input.placement,
+      content: input.content,
+    }
+
+    return {
+      versionAugmentations: HashMap.set(
+        map,
+        VersionCoverage.unversioned(),
+        unversionedConfig,
+      ),
+    }
+  }
+
+  // Case 2: Has versions field - create version-specific entries
+  let resultMap = map
+
+  // Process each version
+  for (const [versionStr, versionOverrides] of Object.entries(input.versions)) {
+    // Merge with top-level defaults
+    const onString = versionOverrides.on ?? input.on
+    const placement = versionOverrides.placement ?? input.placement
+    const content = versionOverrides.content ?? input.content
+
+    // Skip if incomplete after merging with defaults
+    if (!onString || !placement || !content) {
+      continue
+    }
+
+    const config: AugmentationConfig = {
+      on: GraphQLPath.Definition.decodeSync(onString),
+      placement,
+      content,
+    }
+    const version = Version.decodeSync(versionStr)
+    const coverage = VersionCoverage.single(version)
+
+    resultMap = HashMap.set(resultMap, coverage, config)
+  }
+
+  // If no valid version configurations were created, return null
+  if (HashMap.size(resultMap) === 0) {
+    return null
+  }
+
+  return {
+    versionAugmentations: resultMap,
+  }
+}

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

@@ -0,0 +1,11 @@
+import { S } from '#lib/kit-temp/effect'
+
+export const Placement = S.Enums(
+  {
+    before: 'before',
+    after: 'after',
+    over: 'over',
+  } as const,
+)
+
+export type Placement = S.Schema.Type<typeof Placement>

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

@@ -1,4 +1,4 @@
-import { AugmentationSchema } from '#api/schema/augmentations/schema-augmentation'
+import { Augmentations } from '#api/schema/augmentations/$'
 import { S } from '#lib/kit-temp/effect'
 
 // ============================================================================
@@ -364,7 +364,7 @@ export const ConfigSchema = S.Struct({
    * ]
    * ```
    */
-  augmentations: S.optional(S.Array(AugmentationSchema)),
+  augmentations: S.optional(S.Array(Augmentations.AugmentationInput)),
   /**
    * Which data sources to use for loading schemas.
    *

package/src/api/schema/input-source/load.ts

@@ -1,4 +1,5 @@
 import { Config as PolenConfig } from '#api/config/$'
+import type { Diagnostic } from '#api/schema/augmentations/diagnostics/diagnostic'
 import type { Config } from '#api/schema/config'
 import type { InputSource } from '#api/schema/input-source/input-source'
 import type { Catalog } from '#lib/catalog/$'
@@ -9,6 +10,7 @@ import type { Catalog } from '#lib/catalog/$'
 export interface LoadedCatalog {
   data: Catalog.Catalog | null
   source: InputSource
+  diagnostics?: Diagnostic[]
   // {
   //   type: DataSourceType
   //   /**

package/src/api/schema/load.ts

@@ -141,16 +141,33 @@ export const loadOrNull = (
     if (loadedSchema.data && config.schema?.augmentations) {
       const augmentations = config.schema.augmentations
       const catalog = loadedSchema.data as Catalog.Catalog
+      const allDiagnostics: Augmentations.Diagnostic[] = []
+
       Catalog.fold(
         (versioned) => {
           for (const schema of Catalog.Versioned.getAll(versioned)) {
-            Augmentations.apply(schema.definition, augmentations)
+            const { diagnostics } = Augmentations.applyAll(
+              schema.definition,
+              augmentations,
+              schema.version,
+            )
+            allDiagnostics.push(...diagnostics)
           }
         },
         (unversioned) => {
-          Augmentations.apply(unversioned.schema.definition, augmentations)
+          const { diagnostics } = Augmentations.applyAll(
+            unversioned.schema.definition,
+            augmentations,
+            null,
+          )
+          allDiagnostics.push(...diagnostics)
         },
       )(catalog)
+
+      // Add diagnostics to loaded schema if any were generated
+      if (allDiagnostics.length > 0) {
+        loadedSchema.diagnostics = allDiagnostics
+      }
     }
 
     return loadedSchema

package/src/lib/graphql-path/$$.ts

@@ -22,21 +22,15 @@
  * const encoded = GraphQLPath.Definition.encode(userNameFieldPath) // "User.name"
  * const decoded = GraphQLPath.Definition.decode("User.name") // field definition path
  *
- * // Create a query path
- * const queryPath = GraphQLPath.Query.builder()
- *   .type('User')
- *   .field('posts')
- *   .type('Post')
- *   .field('author')
- *   .type('User')
- *   .field('name')
- *   .build()
- *
- * // Encode/decode query paths
- * const encodedQuery = GraphQLPath.Query.encode(queryPath) // "User.posts.Post.author.User.name"
- * const decodedQuery = GraphQLPath.Query.decode("User.posts.Post.author") // query path
+ * // Decode a query path from a string
+ * const queryPath = GraphQLPath.Query.decode("User.posts.Post.author.User.name")
+ * // Returns array of segments: [TypeSegment, FieldSegment, TypeSegment, FieldSegment, ...]
+ *
+ * // Encode query path segments to a string
+ * const encoded = GraphQLPath.Query.encode(queryPath) // "User.posts.Post.author.User.name"
  * ```
  */
 
 export * as Definition from './definition.js'
 export * as Query from './query.js'
+export * as Schema from './schema.js'

package/src/lib/graphql-path/$.test.ts

@@ -0,0 +1,175 @@
+import { S } from '#lib/kit-temp/effect'
+import { describe, expect, test } from 'vitest'
+import { GraphQLPath } from './$.js'
+
+describe('decode', () => {
+  test.for([
+    ['User', [{ _tag: 'TypeSegment', type: 'User' }]],
+    ['User.name', [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'name' },
+    ]],
+    ['User.posts(limit)', [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'posts' },
+      { _tag: 'ArgumentSegment', argument: 'limit' },
+    ]],
+  ])('decodes "%s"', ([input, expected]) => {
+    expect(GraphQLPath.Definition.decodeSync(input)).toEqual(expected)
+  })
+
+  test.for([
+    '',
+    'Type.field.extra',
+    'Type(arg)',
+    '.field',
+    'Type.',
+  ])('throws on invalid format "%s"', (input) => {
+    expect(() => GraphQLPath.Definition.decodeSync(input)).toThrow()
+  })
+})
+
+describe('encode', () => {
+  test.for(
+    [
+      [GraphQLPath.Definition.type('User'), 'User'],
+      [GraphQLPath.Definition.field('User', 'name'), 'User.name'],
+      [GraphQLPath.Definition.argument('User', 'posts', 'limit'), 'User.posts(limit)'],
+    ] as const,
+  )('encodes path to "%s"', ([path, expected]) => {
+    expect(GraphQLPath.Definition.encodeSync(path as any)).toBe(expected)
+  })
+})
+
+describe('round-trip', () => {
+  test.for([
+    'Query',
+    'Mutation',
+    'User',
+    'User.id',
+    'User.name',
+    'Query.users',
+    'User.posts(limit)',
+    'Query.search(query)',
+    'Mutation.createUser(input)',
+  ])('round-trips "%s"', (pathString) => {
+    const decoded = GraphQLPath.Definition.decodeSync(pathString)
+    const encoded = GraphQLPath.Definition.encodeSync(decoded)
+    expect(encoded).toBe(pathString)
+  })
+})
+
+describe('type guards', () => {
+  const typePath = GraphQLPath.Definition.decodeSync('User')
+  const fieldPath = GraphQLPath.Definition.decodeSync('User.name')
+  const argPath = GraphQLPath.Definition.decodeSync('User.posts(limit)')
+
+  test('isTypeDefinitionPath', () => {
+    expect(GraphQLPath.Definition.isTypeDefinitionPath(typePath)).toBe(true)
+    expect(GraphQLPath.Definition.isTypeDefinitionPath(fieldPath)).toBe(false)
+    expect(GraphQLPath.Definition.isTypeDefinitionPath(argPath)).toBe(false)
+  })
+
+  test('isFieldDefinitionPath', () => {
+    expect(GraphQLPath.Definition.isFieldDefinitionPath(typePath)).toBe(false)
+    expect(GraphQLPath.Definition.isFieldDefinitionPath(fieldPath)).toBe(true)
+    expect(GraphQLPath.Definition.isFieldDefinitionPath(argPath)).toBe(false)
+  })
+
+  test('isArgumentDefinitionPath', () => {
+    expect(GraphQLPath.Definition.isArgumentDefinitionPath(typePath)).toBe(false)
+    expect(GraphQLPath.Definition.isArgumentDefinitionPath(fieldPath)).toBe(false)
+    expect(GraphQLPath.Definition.isArgumentDefinitionPath(argPath)).toBe(true)
+  })
+
+  test('Effect Schema derived segment type guards', async () => {
+    // Import from the types module directly since constructors re-exports them
+    const { isTypeSegment, isFieldSegment, isArgumentSegment } = await import('./types.js')
+
+    const typeSegment = { _tag: 'TypeSegment', type: 'User' } as const
+    const fieldSegment = { _tag: 'FieldSegment', field: 'name' } as const
+    const argSegment = { _tag: 'ArgumentSegment', argument: 'limit' } as const
+
+    // Test that Effect Schema derived guards work correctly
+    expect(isTypeSegment(typeSegment)).toBe(true)
+    expect(isTypeSegment(fieldSegment)).toBe(false)
+    expect(isFieldSegment(fieldSegment)).toBe(true)
+    expect(isFieldSegment(typeSegment)).toBe(false)
+    expect(isArgumentSegment(argSegment)).toBe(true)
+    expect(isArgumentSegment(typeSegment)).toBe(false)
+  })
+})
+
+describe('helper functions', () => {
+  test('getType extracts type from all path types', () => {
+    expect(GraphQLPath.Definition.getType(GraphQLPath.Definition.decodeSync('User'))).toBe('User')
+    expect(GraphQLPath.Definition.getType(GraphQLPath.Definition.decodeSync('User.name'))).toBe('User')
+    expect(GraphQLPath.Definition.getType(GraphQLPath.Definition.decodeSync('User.posts(limit)'))).toBe('User')
+  })
+
+  test('getField extracts field name', () => {
+    const fieldPath = GraphQLPath.Definition.decodeSync('User.name')
+    const argPath = GraphQLPath.Definition.decodeSync('User.posts(limit)')
+
+    if (GraphQLPath.Definition.isFieldDefinitionPath(fieldPath)) {
+      expect(GraphQLPath.Definition.getField(fieldPath)).toBe('name')
+    }
+    if (GraphQLPath.Definition.isArgumentDefinitionPath(argPath)) {
+      expect(GraphQLPath.Definition.getField(argPath)).toBe('posts')
+    }
+  })
+
+  test('getArgument extracts argument name', () => {
+    const argPath = GraphQLPath.Definition.decodeSync('User.posts(limit)')
+    if (GraphQLPath.Definition.isArgumentDefinitionPath(argPath)) {
+      expect(GraphQLPath.Definition.getArgument(argPath)).toBe('limit')
+    }
+  })
+})
+
+describe('constructors', () => {
+  test.for([
+    [GraphQLPath.Definition.type('User'), [{ _tag: 'TypeSegment', type: 'User' }]],
+    [GraphQLPath.Definition.field('User', 'name'), [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'name' },
+    ]],
+    [GraphQLPath.Definition.argument('User', 'posts', 'limit'), [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'posts' },
+      { _tag: 'ArgumentSegment', argument: 'limit' },
+    ]],
+  ])('constructor creates correct structure', ([result, expected]) => {
+    expect(result).toEqual(expected)
+  })
+})
+
+describe('Schema validation', () => {
+  test.for(
+    [
+      [GraphQLPath.Definition.TypeDefinitionPath, 'User', [{ _tag: 'TypeSegment', type: 'User' }]],
+      [GraphQLPath.Definition.FieldDefinitionPath, 'User.name', [
+        { _tag: 'TypeSegment', type: 'User' },
+        { _tag: 'FieldSegment', field: 'name' },
+      ]],
+      [GraphQLPath.Definition.ArgumentDefinitionPath, 'User.posts(limit)', [
+        { _tag: 'TypeSegment', type: 'User' },
+        { _tag: 'FieldSegment', field: 'posts' },
+        { _tag: 'ArgumentSegment', argument: 'limit' },
+      ]],
+    ] as const,
+  )('validates through Effect Schema', ([schema, input, expected]) => {
+    const result = S.decodeUnknownSync(schema as any)(input)
+    expect(result).toEqual(expected)
+  })
+
+  test('union automatically selects correct type', () => {
+    const typePath = S.decodeUnknownSync(GraphQLPath.Definition.DefinitionPath)('User')
+    const fieldPath = S.decodeUnknownSync(GraphQLPath.Definition.DefinitionPath)('User.name')
+    const argPath = S.decodeUnknownSync(GraphQLPath.Definition.DefinitionPath)('User.posts(limit)')
+
+    expect(typePath.length).toBe(1)
+    expect(fieldPath.length).toBe(2)
+    expect(argPath.length).toBe(3)
+  })
+})