polen 0.11.0-next.14 → 0.11.0-next.15

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

@@ -0,0 +1,415 @@
+import { AugmentationSchema } from '#api/schema/augmentations/schema-augmentation'
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema - Input Source Names
+// ============================================================================
+
+export const InputSourceNameSchema = S.Enums(
+  {
+    file: 'file',
+    directory: 'directory',
+    versionedDirectory: 'versionedDirectory',
+    memory: 'memory',
+    introspection: 'introspection',
+    introspectionFile: 'introspectionFile',
+  } as const,
+)
+
+export type InputSourceName = S.Schema.Type<typeof InputSourceNameSchema>
+
+// ============================================================================
+// Schema - Input Sources
+// ============================================================================
+
+const FileOptionsSchema = S.Struct({
+  /**
+   * Path to the GraphQL SDL file.
+   *
+   * Can be absolute or relative to the project root.
+   *
+   * @default './schema.graphql'
+   *
+   * @example
+   * ```ts
+   * // Default location
+   * path: './schema.graphql'
+   *
+   * // Custom location
+   * path: './src/graphql/schema.sdl'
+   * ```
+   */
+  path: S.optional(S.String),
+}).annotations({
+  identifier: 'FileOptions',
+  description: 'Configuration for loading schema from a single SDL file.',
+})
+
+const DirectoryOptionsSchema = S.Struct({
+  /**
+   * Path to the directory containing schema files.
+   *
+   * Supports two patterns:
+   * 1. Multiple versioned files with ISO date prefixes: `YYYY-MM-DD.graphql`
+   * 2. Single file named: `schema.graphql`
+   *
+   * @default './schema'
+   *
+   * @example
+   * ```ts
+   * // Default location
+   * path: './schema'
+   *
+   * // Custom location
+   * path: './graphql/versions'
+   * ```
+   *
+   * Directory structure examples:
+   * ```
+   * // Versioned schemas (enables changelog)
+   * schema/
+   *   2024-01-15.graphql
+   *   2024-03-20.graphql
+   *   2024-06-10.graphql
+   *
+   * // Single schema (non-versioned)
+   * schema/
+   *   schema.graphql
+   * ```
+   */
+  path: S.optional(S.String),
+}).annotations({
+  identifier: 'DirectoryOptions',
+  description: 'Configuration for loading multiple schema versions from a directory.',
+})
+
+const VersionedDirectoryOptionsSchema = S.Struct({
+  /**
+   * Path to the directory containing versioned schema subdirectories.
+   *
+   * @default './schema'
+   */
+  path: S.optional(S.String),
+}).annotations({
+  identifier: 'VersionedDirectoryOptions',
+  description: 'Configuration for loading versioned schemas from subdirectories.',
+})
+
+const HttpHeadersSchema = S.Record({
+  key: S.String,
+  value: S.String,
+})
+
+const IntrospectionOptionsSchema = S.Struct({
+  /**
+   * The GraphQL endpoint URL to introspect.
+   *
+   * Must be a valid GraphQL endpoint that supports introspection queries.
+   *
+   * @example 'https://api.example.com/graphql'
+   */
+  url: S.String,
+  /**
+   * Optional headers to include in the introspection request.
+   *
+   * Use this for authentication, API keys, or any custom headers
+   * required by your GraphQL endpoint.
+   *
+   * @example
+   * ```ts
+   * headers: {
+   *   'Authorization': `Bearer ${process.env.API_TOKEN}`,
+   *   'X-API-Key': process.env.API_KEY
+   * }
+   * ```
+   */
+  headers: S.optional(HttpHeadersSchema),
+}).annotations({
+  identifier: 'IntrospectionOptions',
+  description: 'Configuration for loading schema via GraphQL introspection.',
+})
+
+const IntrospectionFileOptionsSchema = S.Struct({
+  /**
+   * Path to the introspection file.
+   *
+   * @default './schema.introspection.json'
+   */
+  path: S.optional(S.String),
+}).annotations({
+  identifier: 'IntrospectionFileOptions',
+  description: 'Configuration for loading schema from an existing introspection file.',
+})
+
+// Complex union for memory revisions - we define the actual runtime types here
+// and use S.Unknown for now, with a TODO to properly type this later
+const MemoryRevisionsSchema = S.Unknown.annotations({
+  description:
+    `Schema revisions in various formats: SDL strings, GraphQL schema objects, or pre-built unversioned Catalog`,
+})
+
+const MemoryOptionsSchema = S.Struct({
+  /**
+   * Schema revisions defined in various formats.
+   *
+   * Creates an unversioned catalog with multiple revisions (dated snapshots) that can show changes over time.
+   *
+   * Can be:
+   * - A single SDL string (single revision, no changelog)
+   * - Array of SDL strings (uses current date for all)
+   * - Array of objects with date and SDL (full changelog support)
+   * - A GraphQLSchema object (single revision, no changelog)
+   * - Array of GraphQLSchema objects (uses current date for all)
+   * - Array of objects with date and GraphQLSchema (full changelog support)
+   * - A pre-built unversioned Catalog object
+   *
+   * @example
+   * ```ts
+   * // Single SDL schema revision
+   * revisions: `
+   *   type Query {
+   *     hello: String
+   *   }
+   * `
+   *
+   * // Multiple revisions with explicit dates (enables changelog)
+   * revisions: [
+   *   {
+   *     date: new Date('2024-01-15'),
+   *     value: `type Query { users: [User] }`
+   *   },
+   *   {
+   *     date: new Date('2024-03-20'),
+   *     value: `type Query { users: [User], posts: [Post] }`
+   *   }
+   * ]
+   *
+   * // GraphQL schema object
+   * revisions: buildSchema(`type Query { hello: String }`)
+   *
+   * // Pre-built unversioned catalog
+   * revisions: myCatalog
+   * ```
+   */
+  revisions: MemoryRevisionsSchema,
+}).annotations({
+  identifier: 'MemoryOptions',
+  description:
+    'Configuration for defining schema revisions programmatically in memory. Creates an unversioned catalog.',
+})
+
+// ============================================================================
+// Schema - Sources
+// ============================================================================
+
+const SourcesSchema = S.Struct({
+  /**
+   * Configuration for loading schema from a single SDL file.
+   */
+  file: S.optional(FileOptionsSchema),
+  /**
+   * Configuration for loading multiple schema versions from a directory.
+   */
+  directory: S.optional(DirectoryOptionsSchema),
+  /**
+   * Configuration for loading versioned schemas from subdirectories.
+   */
+  versionedDirectory: S.optional(VersionedDirectoryOptionsSchema),
+  /**
+   * Configuration for defining schemas programmatically.
+   *
+   * Accepts SDL strings, GraphQL schema objects, or pre-built SchemaHydrated objects.
+   */
+  memory: S.optional(MemoryOptionsSchema),
+  /**
+   * Configuration for loading schema via GraphQL introspection.
+   *
+   * Introspection fetches your schema directly from a running GraphQL endpoint
+   * and caches it in `.polen/cache/introspection/`.
+   *
+   * @example
+   * ```ts
+   * introspection: {
+   *   url: 'https://api.example.com/graphql',
+   *   headers: { 'Authorization': 'Bearer token' }
+   * }
+   * ```
+   */
+  introspection: S.optional(IntrospectionOptionsSchema),
+  /**
+   * Configuration for loading schema from an existing introspection file.
+   *
+   * Reads a pre-existing `schema.introspection.json` file from your project root.
+   * This is useful when you have an introspection file generated by other tools.
+   *
+   * @example
+   * ```ts
+   * introspectionFile: {
+   *   // Uses default path: ./schema.introspection.json
+   * }
+   * ```
+   */
+  introspectionFile: S.optional(IntrospectionFileOptionsSchema),
+}).annotations({
+  identifier: 'Sources',
+  description: 'Configuration for each data source type.',
+})
+
+// ============================================================================
+// Schema - Main Config
+// ============================================================================
+
+/**
+ * Configuration for how Polen loads your GraphQL schema.
+ *
+ * Polen supports multiple schema sources:
+ * - `file` - Load from a single SDL file (default: schema.graphql)
+ * - `directory` - Load multiple SDL files with date prefixes (enables changelog)
+ * - `memory` - Define schemas programmatically in configuration
+ * - `introspection` - Fetch schema from a GraphQL endpoint
+ * - `data` - Use pre-built schema objects
+ *
+ * @example
+ * ```ts
+ * // Default: looks for schema.graphql
+ * schema: {}
+ *
+ * // Load via introspection
+ * schema: {
+ *   sources: {
+ *     introspection: {
+ *       url: 'https://api.example.com/graphql',
+ *       headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
+ *     }
+ *   }
+ * }
+ *
+ * // Multiple versions for changelog
+ * schema: {
+ *   sources: {
+ *     directory: { path: './schema' }
+ *   }
+ * }
+ *
+ * // Custom source order
+ * schema: {
+ *   useSources: ['introspection', 'file'],
+ *   sources: {
+ *     introspection: { url: 'https://api.example.com/graphql' },
+ *     file: { path: './fallback.graphql' }
+ *   }
+ * }
+ * ```
+ *
+ * **Two introspection features**:
+ * 1. **File Convention**: Polen auto-detects `schema.introspection.json` files
+ * 2. **Config-driven**: Polen fetches and caches introspection for you
+ *
+ * **Interoperability**: The `schema.introspection.json` file uses the standard
+ * GraphQL introspection format, compatible with GraphQL Codegen, Apollo CLI, etc.
+ *
+ * **Lifecycle**:
+ * - First run: Fetches from endpoint, saves to `schema.introspection.json`
+ * - Subsequent runs: Loads from JSON file (no network request)
+ * - To refresh: Delete the JSON file
+ * - Runs during `polen dev` and `polen build`, never at runtime
+ *
+ * **Query details**: Uses the standard introspection query from the GraphQL spec
+ * @see https://spec.graphql.org/draft/#sec-Introspection
+ */
+export const ConfigSchema = S.Struct({
+  /**
+   * Whether to enable schema loading.
+   *
+   * Set to `false` to disable schema features entirely. This removes
+   * the Reference and Changelog pages from your portal.
+   *
+   * @default true
+   *
+   * @example
+   * ```ts
+   * // Disable schema features
+   * schema: { enabled: false }
+   * ```
+   */
+  enabled: S.optional(S.Boolean),
+  /**
+   * Programmatically enhance your GraphQL schema documentation without modifying the schema files.
+   *
+   * Perfect for adding implementation details, usage examples, deprecation notices,
+   * or any additional context that helps developers understand your API better.
+   *
+   * @example
+   * ```ts
+   * augmentations: [
+   *   {
+   *     type: 'description',
+   *     on: {
+   *       type: 'TargetType',
+   *       name: 'User'
+   *     },
+   *     placement: 'after',
+   *     content: '\n\nSee the [User Guide](/guides/users) for detailed usage.'
+   *   },
+   *   {
+   *     type: 'description',
+   *     on: {
+   *       type: 'TargetField',
+   *       targetType: 'Query',
+   *       name: 'users'
+   *     },
+   *     placement: 'after',
+   *     content: '\n\n**Rate limit:** 100 requests per minute'
+   *   }
+   * ]
+   * ```
+   */
+  augmentations: S.optional(S.Array(AugmentationSchema)),
+  /**
+   * Which data sources to use for loading schemas.
+   *
+   * - `file` - Load from a single SDL file (default: `./schema.graphql`)
+   * - `directory` - Load multiple SDL files from a directory (default: `./schema/`)
+   * - `versionedDirectory` - Load versioned schemas from subdirectories (default: `./schema/`)
+   * - `memory` - Use schemas defined in configuration
+   * - `introspection` - Load schema via GraphQL introspection
+   * - `introspectionFile` - Load schema from an introspection JSON file
+   *
+   * If not specified, Polen tries all sources in this order:
+   * 1. `versionedDirectory` 2. `directory` 3. `file` 4. `memory` 5. `introspection` 6. `introspectionFile`
+   *
+   * @example
+   * ```ts
+   * // Use only file source
+   * useSources: 'file'
+   *
+   * // Try multiple sources in custom order
+   * useSources: ['introspection', 'file']
+   *
+   * // Default behavior (try all sources)
+   * // useSources: undefined
+   * ```
+   */
+  useSources: S.optional(S.Union(InputSourceNameSchema, S.Array(InputSourceNameSchema))),
+  /**
+   * Configuration for each data source type.
+   */
+  sources: S.optional(SourcesSchema),
+}).annotations({
+  identifier: 'SchemaConfig',
+  title: 'Schema Configuration',
+  description: 'Configuration for how Polen loads your GraphQL schema.',
+})
+
+export type ConfigInput = S.Schema.Type<typeof ConfigSchema>
+
+// For backward compatibility during migration
+export type Config = ConfigInput
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(ConfigSchema)
+export const encode = S.encode(ConfigSchema)
+export const validate = S.validate(ConfigSchema)

package/src/api/schema/config.ts

@@ -0,0 +1,7 @@
+export type { Config, ConfigInput, InputSourceName } from './config-schema.js'
+export { InputSourceNameSchema } from './config-schema.js'
+
+// Keep legacy exports for backward compatibility during migration
+import type { InputSources } from './input-sources/$.js'
+
+export type DataSourceTypeNew = typeof InputSources[keyof typeof InputSources]['loader']['name']

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

@@ -0,0 +1,2 @@
+export * from './input-source.js'
+export * from './load.js'

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

@@ -0,0 +1 @@
+export * as InputSource from './$$.js'

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

@@ -0,0 +1,134 @@
+import { InputSource } from '#api/schema/input-source/$'
+import type { Catalog } from '#lib/catalog/$'
+import type { PlatformError } from '@effect/platform/Error'
+import type { FileSystem } from '@effect/platform/FileSystem'
+import { Err, Fn } from '@wollybeard/kit'
+import { Effect } from 'effect'
+
+type Options = object
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export interface InputSourceError {
+  readonly _tag: 'InputSourceError'
+  readonly source: string
+  readonly message: string
+  readonly cause?: unknown
+}
+
+export const InputSourceError = (
+  source: string,
+  message: string,
+  cause?: unknown,
+): InputSourceError => ({
+  _tag: 'InputSourceError',
+  source,
+  message,
+  cause,
+})
+
+// ============================================================================
+// Effect-based InputSource
+// ============================================================================
+
+export interface EffectInputSource<
+  $Name extends string = string,
+  $Options extends Options = Options,
+  $Catalog extends Catalog.Catalog = Catalog.Catalog,
+> {
+  name: $Name
+  isApplicable: (
+    options: $Options,
+    context: InputSource.Context,
+  ) => Effect.Effect<boolean, PlatformError | InputSourceError, FileSystem>
+  readIfApplicableOrThrow: (
+    options: $Options,
+    context: InputSource.Context,
+  ) => Effect.Effect<null | $Catalog, PlatformError | InputSourceError, FileSystem>
+  reCreate?: (
+    options: $Options,
+    context: InputSource.Context,
+  ) => Effect.Effect<null | $Catalog, PlatformError | InputSourceError, FileSystem>
+}
+
+export const createEffect = <
+  $Name extends string,
+  $Options extends Options,
+  $Catalog extends Catalog.Catalog,
+>(input: {
+  name: $Name
+  isApplicable?: (
+    options: $Options,
+    context: InputSource.Context,
+  ) => Effect.Effect<boolean, PlatformError | InputSourceError, FileSystem>
+  readIfApplicableOrThrow: (
+    options: $Options,
+    context: InputSource.Context,
+  ) => Effect.Effect<null | $Catalog, PlatformError | InputSourceError, FileSystem>
+  reCreate?: (
+    options: $Options,
+    context: InputSource.Context,
+  ) => Effect.Effect<null | $Catalog, PlatformError | InputSourceError, FileSystem>
+}): EffectInputSource<$Name, $Options, $Catalog> => {
+  const defaultIsApplicable = (
+    options: $Options,
+    context: InputSource.Context,
+  ): Effect.Effect<boolean, PlatformError | InputSourceError, FileSystem> =>
+    Effect.gen(function*() {
+      const result = yield* Effect.either(input.readIfApplicableOrThrow(options, context))
+      return result._tag === 'Right' && result.right !== null
+    })
+
+  return {
+    name: input.name,
+    isApplicable: input.isApplicable ?? defaultIsApplicable,
+    readIfApplicableOrThrow: input.readIfApplicableOrThrow,
+    reCreate: input.reCreate,
+    __effectInputSource: true,
+  } as EffectInputSource<$Name, $Options, $Catalog> & { __effectInputSource: true }
+}
+
+// ============================================================================
+// Promise-based InputSource (for backward compatibility)
+// ============================================================================
+
+export interface InputSource<
+  $Name extends string = string,
+  $Options extends Options = Options,
+  $Catalog extends Catalog.Catalog = Catalog.Catalog,
+> {
+  name: $Name
+  isApplicable: (options: $Options, context: InputSource.Context) => Promise<boolean>
+  readIfApplicableOrThrow: (options: $Options, context: InputSource.Context) => Promise<null | $Catalog>
+  reCreate?: (options: $Options, context: InputSource.Context) => Promise<null | $Catalog>
+}
+
+export const create = <
+  $Name extends string,
+  $Options extends Options,
+  $Catalog extends Catalog.Catalog,
+>(input: {
+  name: $Name
+  isApplicable?: (options: $Options, context: InputSource.Context) => Promise<boolean>
+  readIfApplicableOrThrow: (options: $Options, context: InputSource.Context) => Promise<null | $Catalog>
+  reCreate?: (options: $Options, context: InputSource.Context) => Promise<null | $Catalog>
+}): InputSource<
+  $Name,
+  $Options,
+  $Catalog
+> => {
+  const defaultIsApplicable = async (options: $Options, context: InputSource.Context): Promise<boolean> => {
+    return Err.tryOrAsync(() => input.readIfApplicableOrThrow(options, context), false).then(Fn.constant(true))
+  }
+
+  const api = {
+    name: input.name,
+    isApplicable: input.isApplicable ?? defaultIsApplicable,
+    readIfApplicableOrThrow: input.readIfApplicableOrThrow,
+    reCreate: input.reCreate,
+  } as InputSource<$Name, $Options, $Catalog>
+
+  return api
+}

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

@@ -0,0 +1,75 @@
+import { Config as PolenConfig } from '#api/config/$'
+import type { Config } from '#api/schema/config'
+import type { InputSource } from '#api/schema/input-source/input-source'
+import type { Catalog } from '#lib/catalog/$'
+
+/**
+ * Result of schema reading with provenance tracking for file watching and debugging.
+ */
+export interface LoadedCatalog {
+  data: Catalog.Catalog | null
+  source: InputSource
+  // {
+  //   type: DataSourceType
+  //   /**
+  //    * Recreate the schema data and file after it has been deleted.
+  //    *
+  //    * This function re-fetches data from the original source and recreates
+  //    * the schema file on disk. Only called by file watchers after deletion.
+  //    *
+  //    * @returns Promise resolving to the recreated schema data, or null if recreation fails
+  //    */
+  //   reCreate?: () => Promise<Catalog.Catalog | null>
+  // }
+}
+
+export interface Context {
+  paths: PolenConfig.Config['paths']
+}
+
+type InputSourceName = string
+
+export const loadOrThrow = async (
+  params: {
+    context: Context
+    config: Config | null
+    useFirst: (InputSourceName[]) | null
+    sources: InputSource[]
+  },
+): Promise<LoadedCatalog> => {
+  const getSourceConfig = (sourceName: InputSourceName) => {
+    const sourceConfigs = (params.config?.sources ?? {}) as Record<InputSourceName, object>
+    const sourceConfig = sourceConfigs[sourceName] ?? {}
+    return sourceConfig
+  }
+  // If useFirst is specified, try sources in that specific order
+  if (params.useFirst) {
+    for (const sourceName of params.useFirst) {
+      const source = params.sources.find(s => s.name === sourceName)
+      if (!source) continue
+
+      const sourceConfig = getSourceConfig(source.name)
+      const result = await source.readIfApplicableOrThrow(sourceConfig as any, params.context)
+      if (result) {
+        return {
+          data: result,
+          source,
+        }
+      }
+    }
+  } else {
+    // Otherwise, try all sources in the order they were provided
+    for (const source of params.sources) {
+      const sourceConfig = getSourceConfig(source.name)
+      const result = await source.readIfApplicableOrThrow(sourceConfig as any, params.context)
+      if (result) {
+        return {
+          data: result,
+          source,
+        }
+      }
+    }
+  }
+
+  throw new Error(`No applicable schema source found. Please check your configuration.`)
+}

package/src/api/schema/input-sources/$$.ts

@@ -0,0 +1,6 @@
+export * as Directory from './directory.js'
+export * as File from './file.js'
+export * as IntrospectionFile from './introspection-file.js'
+export * as Introspection from './introspection.js'
+export * as Memory from './memory.js'
+export * as VersionedDirectory from './versioned-directory.js'

package/src/api/schema/input-sources/$.ts

@@ -0,0 +1 @@
+export * as InputSources from './$$.js'