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

package/src/api/reference/config.ts

@@ -0,0 +1,193 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema - Reference Diagnostics
+// ============================================================================
+
+/**
+ * Diagnostic controls for reference documentation.
+ */
+export const ReferenceDiagnostics = S.Struct({
+  /**
+   * Control diagnostics for missing or invalid reference content.
+   *
+   * @default true (info in dev, warning in build)
+   */
+  validation: S.optional(S.Union(S.Boolean, Diagnostic.Control)),
+}).annotations({
+  identifier: 'ReferenceDiagnostics',
+  description: 'Diagnostic controls for reference documentation',
+})
+
+export type ReferenceDiagnostics = S.Schema.Type<typeof ReferenceDiagnostics>
+
+// ============================================================================
+// Schema - Descriptions View
+// ============================================================================
+
+/**
+ * Configuration for how descriptions are displayed in reference documentation.
+ */
+export const DescriptionsView = S.Struct({
+  /**
+   * Default view mode for descriptions.
+   * - 'expanded': Show full descriptions (default)
+   * - 'compact': Show condensed view
+   *
+   * @default 'expanded'
+   */
+  defaultMode: S.optional(S.Literal('compact', 'expanded')),
+
+  /**
+   * Whether to show the view mode toggle control.
+   * Allows users to switch between compact and expanded views.
+   *
+   * @default true
+   */
+  showControl: S.optional(S.Boolean),
+}).annotations({
+  identifier: 'DescriptionsView',
+  description: 'Configuration for descriptions display in reference documentation',
+})
+
+export type DescriptionsView = S.Schema.Type<typeof DescriptionsView>
+
+// ============================================================================
+// Schema - Reference Config
+// ============================================================================
+
+export const ReferenceConfigObject = S.Struct({
+  /**
+   * Control whether the reference documentation is enabled.
+   * - true: Always enabled (show in nav even if no schema exists)
+   * - false: Always disabled (hide even if schema exists)
+   * - undefined: Auto-detect based on schema presence (default behavior)
+   *
+   * @default undefined (auto-detect based on schema presence)
+   * @example
+   * // Always show reference section
+   * reference: { enabled: true }
+   *
+   * @example
+   * // Never show reference
+   * reference: { enabled: false }
+   *
+   * @example
+   * // Auto-detect based on schema (default)
+   * reference: { }
+   */
+  enabled: S.optional(S.Boolean),
+
+  /**
+   * Configuration for how descriptions are displayed.
+   *
+   * @example
+   * // Use compact mode by default
+   * descriptionsView: {
+   *   defaultMode: 'compact'
+   * }
+   *
+   * @example
+   * // Hide the view mode toggle
+   * descriptionsView: {
+   *   showControl: false
+   * }
+   */
+  descriptionsView: S.optional(DescriptionsView),
+
+  /**
+   * Configuration for how field nullability is rendered.
+   * - 'bangMark': Show '!' after non-nullable types (GraphQL style)
+   * - 'questionMark': Show '?' after nullable field names (TypeScript style)
+   *
+   * @default 'bangMark'
+   * @example
+   * // Use TypeScript-style nullability rendering
+   * nullabilityRendering: 'questionMark'
+   */
+  nullabilityRendering: S.optional(S.Literal('questionMark', 'bangMark')),
+
+  /**
+   * Diagnostic controls for reference documentation.
+   *
+   * @example
+   * // Enable all diagnostics with defaults
+   * diagnostics: {
+   *   validation: true
+   * }
+   *
+   * @example
+   * // Fine-grained control
+   * diagnostics: {
+   *   validation: {
+   *     enabled: true,
+   *     dev: { severity: 'error' },
+   *     build: { severity: 'warning' }
+   *   }
+   * }
+   */
+  diagnostics: S.optional(ReferenceDiagnostics),
+}).annotations({
+  identifier: 'ReferenceConfigObject',
+  title: 'Reference Configuration',
+  description: 'Configuration for reference documentation feature',
+})
+
+export type ReferenceConfigObject = S.Schema.Type<typeof ReferenceConfigObject>
+
+/**
+ * Reference configuration with boolean shorthand support.
+ * - true: Enable with defaults
+ * - false: Disable completely
+ * - object: Fine-grained control
+ */
+export const ReferenceConfig = S.transform(
+  S.Union(
+    S.Boolean,
+    ReferenceConfigObject,
+  ),
+  ReferenceConfigObject,
+  {
+    strict: false,
+    decode: (input) => {
+      if (typeof input === 'boolean') {
+        return {
+          enabled: input,
+          descriptionsView: {},
+          nullabilityRendering: undefined,
+          diagnostics: {},
+        }
+      }
+      return input
+    },
+    encode: (config) => config,
+  },
+).annotations({
+  identifier: 'ReferenceConfig',
+  title: 'Reference Configuration',
+  description: 'Reference documentation configuration with boolean shortcuts',
+})
+
+export type ReferenceConfig = S.Schema.Type<typeof ReferenceConfig>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = ReferenceConfigObject.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(ReferenceConfig)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decode = S.decode(ReferenceConfig)
+export const decodeSync = S.decodeSync(ReferenceConfig)
+export const encode = S.encode(ReferenceConfig)
+export const encodeSync = S.encodeSync(ReferenceConfig)

package/src/api/reference/scanner.ts

@@ -0,0 +1,53 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { FileSystem } from '@effect/platform'
+import { Effect } from 'effect'
+import * as Path from 'node:path'
+import * as Catalog from './catalog.js'
+
+export interface ScanOptions {
+  /**
+   * The directory to scan for reference content
+   */
+  dir: string
+}
+
+export interface ScanResult {
+  /**
+   * The reference catalog with index metadata
+   */
+  catalog: Catalog.Catalog
+  /**
+   * Any diagnostics generated during scanning
+   */
+  diagnostics: Diagnostic.Diagnostic[]
+}
+
+/**
+ * Scan for reference documentation content.
+ * Currently looks for index.md or index.mdx files for custom landing pages.
+ */
+export const scan = (
+  options: ScanOptions,
+): Effect.Effect<ScanResult, Error, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    const diagnostics: Diagnostic.Diagnostic[] = []
+
+    // Check for index.md or index.mdx file
+    const indexMdPath = Path.join(options.dir, 'reference', 'index.md')
+    const indexMdxPath = Path.join(options.dir, 'reference', 'index.mdx')
+
+    // Try index.md first, then index.mdx
+    const indexPath = (yield* fs.exists(indexMdPath))
+      ? indexMdPath
+      : (yield* fs.exists(indexMdxPath))
+      ? indexMdxPath
+      : null
+
+    const catalog = Catalog.make({
+      index: indexPath ? { path: indexPath } : undefined,
+    })
+
+    return { catalog, diagnostics }
+  })

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>