polen 0.11.0-next.24 → 0.11.0-next.26

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)
+  })
+})

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/grafaid/schema/format-default-value.ts

@@ -0,0 +1,22 @@
+import { astFromValue, print } from 'graphql'
+import type { GraphQLInputType } from 'graphql'
+
+/**
+ * Formats a GraphQL default value into a string representation.
+ * Returns just the value part (e.g., "20", "true", '"hello"')
+ *
+ * @param value - The default value from a GraphQL argument or input field
+ * @param type - The GraphQL input type of the field
+ * @returns The formatted value string, or null if value is undefined
+ */
+export const formatDefaultValue = (value: unknown, type: GraphQLInputType): string | null => {
+  if (value === undefined) return null
+
+  const ast = astFromValue(value, type)
+  if (!ast) {
+    // Fallback for edge cases where astFromValue fails
+    return JSON.stringify(value)
+  }
+
+  return print(ast)
+}

package/src/lib/grafaid/schema/schema.ts

@@ -51,6 +51,8 @@ export * as NodesLike from './nodes-like.js'
 
 export * from './read.js'
 
+export * from './format-default-value.js'
+
 import * as AST from './ast.js'
 
 export const empty: GraphQLSchema = buildASTSchema(AST.empty)

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'