polen 0.11.0-next.14 → 0.11.0-next.16

package/src/api/schema/data-sources/introspection/introspection.ts

@@ -1,216 +0,0 @@
-import { Grafaid } from '#lib/grafaid'
-import { GraphqlChange } from '#lib/graphql-change'
-import type { GraphqlChangeset } from '#lib/graphql-changeset'
-import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader'
-import { Fs, Json, Path } from '@wollybeard/kit'
-import type { SchemaReadResult } from '../../schema.js'
-
-/**
- * Configuration for loading schema via GraphQL introspection.
- *
- * Polen supports two introspection features:
- * 1. **File Convention**: Automatically detects `schema.introspection.json` if present
- * 2. **Automatic Introspection**: Fetches from your endpoint and creates the file
- *
- * When configured, Polen will:
- * - Execute the standard GraphQL introspection query against your endpoint
- * - Save the result to `schema.introspection.json` in your project root
- * - Use this cached file for subsequent builds (no network requests)
- *
- * The saved file contains a standard GraphQL introspection query result as defined
- * in the GraphQL specification, making it compatible with any tool that works with
- * introspection data (GraphQL Codegen, Apollo CLI, etc.).
- *
- * To refresh the schema, delete `schema.introspection.json` and rebuild.
- *
- * **Technical details**:
- * - Uses Graffle's introspection extension
- * - Performs the full introspection query (all types, fields, descriptions, etc.)
- * - No customization of the query is currently supported
- *
- * @see https://spec.graphql.org/draft/#sec-Introspection - GraphQL Introspection spec
- * @see https://github.com/graphql/graphql-js/blob/main/src/utilities/getIntrospectionQuery.ts - Reference implementation
- *
- * @example
- * ```ts
- * // Basic introspection
- * introspection: {
- *   url: 'https://api.example.com/graphql'
- * }
- *
- * // With authentication
- * introspection: {
- *   url: 'https://api.example.com/graphql',
- *   headers: {
- *     'Authorization': `Bearer ${process.env.API_TOKEN}`
- *   }
- * }
- * ```
- */
-export interface ConfigInput {
-  /**
-   * The GraphQL endpoint URL to introspect.
-   *
-   * Must be a valid GraphQL endpoint that supports introspection queries.
-   *
-   * @example 'https://api.example.com/graphql'
-   */
-  url?: 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?: Record<string, string>
-  projectRoot?: string
-}
-
-export interface Config {
-  url: string
-  headers?: Record<string, string>
-  projectRoot: string
-}
-
-export const normalizeConfig = (configInput: ConfigInput): Config => {
-  if (!configInput.url) {
-    throw new Error(`Introspection data source requires a URL`)
-  }
-
-  if (!configInput.projectRoot) {
-    throw new Error(`Introspection data source requires a projectRoot`)
-  }
-
-  const config: Config = {
-    url: configInput.url,
-    headers: configInput.headers,
-    projectRoot: configInput.projectRoot,
-  }
-
-  return config
-}
-
-const INTROSPECTION_FILE_NAME = `schema.introspection.json`
-
-const getIntrospectionFilePath = (projectRoot: string) => {
-  return Path.join(projectRoot, INTROSPECTION_FILE_NAME)
-}
-
-export const readOrThrow = async (
-  configInput: ConfigInput,
-): Promise<SchemaReadResult> => {
-  const config = normalizeConfig(configInput)
-  const introspectionFilePath = getIntrospectionFilePath(config.projectRoot)
-
-  // Check if introspection file exists
-  const introspectionFileContent = await Fs.read(introspectionFilePath)
-  let schema: Grafaid.Schema.Schema
-
-  if (introspectionFileContent) {
-    // Load from existing file - no reCreate capability
-    try {
-      const introspectionData = Json.codec.decode(introspectionFileContent)
-
-      // Validate introspection data structure before passing to fromIntrospectionQuery
-      if (!introspectionData || typeof introspectionData !== 'object') {
-        throw new Error('Introspection data must be a valid JSON object')
-      }
-
-      // Allow fromIntrospectionQuery to handle validation of the introspection format
-      // It will provide more specific GraphQL-related error messages
-      if (!('data' in introspectionData)) {
-        throw new Error(
-          'Introspection data missing required "data" property (expected GraphQL introspection result format)',
-        )
-      }
-
-      schema = Grafaid.Schema.fromIntrospectionQuery(introspectionData as any)
-    } catch (error) {
-      if (error instanceof SyntaxError) {
-        throw new Error(`Invalid JSON in ${introspectionFilePath}: ${error.message}`)
-      } else {
-        throw new Error(
-          `Invalid introspection data in ${introspectionFilePath}: ${
-            error instanceof Error ? error.message : String(error)
-          }. Delete this file to fetch fresh introspection data.`,
-        )
-      }
-    }
-
-    const schemaData = await createSingleSchemaChangeset(schema)
-    return {
-      data: schemaData,
-      source: { type: 'introspectionFile' },
-    }
-  } else {
-    // Fetch via introspection - can reCreate
-    const introspectionResult = await GraphqlSchemaLoader.load({
-      type: `introspect`,
-      url: config.url,
-      headers: config.headers,
-    })
-
-    schema = introspectionResult
-
-    // Get the raw introspection result for saving
-    const __schema = Grafaid.Schema.toIntrospectionQuery(schema)
-
-    // Wrap in GraphQL response format for consistency with API responses
-    const introspectionData = { data: { __schema } }
-
-    // Write to file
-    await Fs.write({
-      path: introspectionFilePath,
-      content: Json.codec.encode(introspectionData as any),
-    })
-
-    const schemaData = await createSingleSchemaChangeset(schema)
-    return {
-      data: schemaData,
-      source: {
-        type: 'introspectionAuto',
-        reCreate: async () => {
-          // Re-fetch using captured config - capture closure
-          const result = await readOrThrow(configInput)
-          return result.data
-        },
-      },
-    }
-  }
-}
-
-/**
- * Create a single changeset from a schema object.
- * This is the core logic for handling single (unversioned) schemas from introspection.
- */
-export const createSingleSchemaChangeset = async (
-  schema: Grafaid.Schema.Schema,
-): Promise<GraphqlChangeset.ChangelogLinked> => {
-  const date = new Date() // Generate date here for unversioned schema
-  const after = schema
-  const before = Grafaid.Schema.empty
-  const changes = await GraphqlChange.calcChangeset({
-    before,
-    after,
-  })
-
-  const changeset: GraphqlChangeset.IntermediateChangeSetLinked = {
-    type: 'IntermediateChangeSet',
-    date,
-    after: { version: null, data: after },
-    before: { version: null, data: before },
-    changes,
-  }
-
-  const result: GraphqlChangeset.ChangelogLinked = [changeset]
-
-  return result
-}

package/src/api/schema/data-sources/memory/memory.ts

@@ -1,125 +0,0 @@
-import { Grafaid } from '#lib/grafaid'
-import { GraphqlChange } from '#lib/graphql-change'
-import type { GraphqlChangeset } from '#lib/graphql-changeset'
-import { Arr } from '@wollybeard/kit'
-
-/**
- * Configuration for defining schemas programmatically in memory.
- *
- * Useful for demos, testing, or when schemas are generated dynamically.
- */
-export interface ConfigInput {
-  /**
-   * Schema versions defined as SDL strings.
-   *
-   * Can be:
-   * - A single SDL string (no changelog)
-   * - Array of SDL strings (uses current date for all)
-   * - Array of objects with date and SDL (full changelog support)
-   *
-   * @example
-   * ```ts
-   * // Single schema
-   * versions: `
-   *   type Query {
-   *     hello: String
-   *   }
-   * `
-   *
-   * // Multiple versions with explicit dates
-   * versions: [
-   *   {
-   *     date: new Date('2024-01-15'),
-   *     value: `type Query { users: [User] }`
-   *   },
-   *   {
-   *     date: new Date('2024-03-20'),
-   *     value: `type Query { users: [User], posts: [Post] }`
-   *   }
-   * ]
-   * ```
-   */
-  versions:
-    | string
-    | string[]
-    | { date: Date; value: string }[]
-}
-
-export interface Config {
-  versions: { date: Date; value: string }[]
-}
-
-export const normalize = (configInput: ConfigInput): Config => {
-  const config: Config = {
-    versions: Arr.map(Arr.sure(configInput.versions), _ => {
-      if (typeof _ === `string`) {
-        return {
-          date: new Date(),
-          value: _,
-        }
-      }
-      return _
-    }),
-  }
-
-  return config
-}
-
-export const read = async (
-  configInput: ConfigInput,
-): Promise<null | GraphqlChangeset.ChangelogLinked> => {
-  const config = normalize(configInput)
-
-  if (!Arr.isntEmpty(config.versions)) {
-    return null
-  }
-
-  const versions = Arr.map(config.versions, _ => {
-    return {
-      date: _.date,
-      schema: Grafaid.Schema.fromAST(Grafaid.Schema.AST.parse(_.value)),
-    }
-  })
-
-  versions.sort((a, b) => a.date.getTime() - b.date.getTime())
-
-  // todo: make DRY, this is same as for schema-directory
-  const changesets = await Promise.all(
-    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSetLinked> => {
-      const current = version
-      const previous = versions[index - 1]
-
-      const before = previous?.schema ?? Grafaid.Schema.empty
-      const after = current.schema
-
-      if (!previous) {
-        // First version - create InitialChangeSet
-        return {
-          type: 'InitialChangeSet',
-          date: current.date,
-          after: { version: null, data: after },
-        }
-      } else {
-        // Subsequent versions - create IntermediateChangeSet
-        const changes = await GraphqlChange.calcChangeset({
-          before,
-          after,
-        })
-
-        return {
-          type: 'IntermediateChangeSet',
-          date: current.date,
-          before: { version: null, data: before },
-          after: { version: null, data: after },
-          changes,
-        }
-      }
-    }),
-  )
-
-  changesets.reverse()
-
-  const schema: GraphqlChangeset.ChangelogLinked = changesets
-
-  return schema
-}

package/src/api/schema/data-sources/schema-directory/file-name-expression/file-name-expression.ts

@@ -1,84 +0,0 @@
-import { Path } from '@wollybeard/kit'
-
-export type Expression = ExpressionVersioned | ExpressionSingle
-
-export const parseOrThrow = (fileNameOrSerializedExpression: string): Expression => {
-  const result = parse(fileNameOrSerializedExpression)
-  if (!result) throw new Error(`Invalid serialized expression: ${fileNameOrSerializedExpression}`)
-
-  return result
-}
-
-export const parse = (fileName: string): null | Expression => {
-  const path = Path.parse(fileName)
-  if (path.ext !== `.graphql`) {
-    throw new Error(
-      `If file name is provided, must be .graphql. Got: ${fileName}`,
-    )
-  }
-  const serializedExpression = path.name
-
-  const versioned = parseExpressionVersionedSerialized(serializedExpression)
-  if (versioned) return { ...versioned, filePath: fileName, type: `FileNameExpressionVersioned` }
-
-  const single = parseExpressionSingleSerialized(serializedExpression)
-  if (single) return { ...single, filePath: fileName, type: `FileNameExpressionSingle` }
-
-  return null
-}
-
-// ----
-
-export interface ExpressionVersioned {
-  type: `FileNameExpressionVersioned`
-  date: Date
-  filePath: string
-}
-
-const parseExpressionVersionedSerialized = (
-  serializedExpression: string,
-): Pick<ExpressionVersioned, `date`> | null => {
-  const match = expressionVersionedSerializedPattern.exec(serializedExpression)
-  if (!match) return null
-  const { year, month, day } = match.groups as { year: string; month: string; day: string }
-  const date = new Date(parseInt(year), parseInt(month) - 1, parseInt(day))
-  return { date }
-}
-
-const expressionVersionedSerializedPattern = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/
-
-// export const isExpressionVersioned = (expression: Expression): expression is ExpressionVersioned => {
-//   return expression.type === `FileNameExpressionVersioned`
-// }
-
-// ----
-
-export interface ExpressionSingle {
-  type: `FileNameExpressionSingle`
-  filePath: string
-}
-
-const parseExpressionSingleSerialized = (
-  serializedExpression: string,
-): {} | null => {
-  if (serializedExpression === `schema`) {
-    return {}
-  }
-  return null
-}
-
-// ----
-
-// export interface ExpressionLatest {
-//   type: `FileNameExpressionLatest`
-//   filePath: string
-// }
-
-// const parseExpressionLatestSerialized = (serializedExpression: string): null | {} => {
-//   if (serializedExpression === `latest`) return {}
-//   return null
-// }
-
-// export const isExpressionLatest = (expression: Expression): expression is ExpressionLatest => {
-//   return expression.type === `FileNameExpressionLatest`
-// }

package/src/api/schema/data-sources/schema-directory/file-name-expression/index.ts

@@ -1 +0,0 @@
-export * as FileNameExpression from './file-name-expression.js'

package/src/api/schema/data-sources/schema-directory/schema-directory.ts

@@ -1,178 +0,0 @@
-import { Grafaid } from '#lib/grafaid'
-import { GraphqlChange } from '#lib/graphql-change'
-import type { GraphqlChangeset } from '#lib/graphql-changeset'
-import { debugPolen } from '#singletons/debug'
-import { Arr, Path } from '@wollybeard/kit'
-import { glob } from 'tinyglobby'
-import { readSingleSchemaFile } from '../schema-file/schema-file.js'
-import { FileNameExpression } from './file-name-expression/index.js'
-
-// const debug = debugPolen.sub([`schema`, `data-source-schema-directory`])
-const debug = debugPolen.sub(`schema:data-source-schema-directory`)
-
-const defaultPaths = {
-  schemaDirectory: `./schema`,
-}
-
-/**
- * Configuration for loading schema(s) from a directory.
- *
- * Supports two modes:
- * 1. Multiple versioned schemas with date prefixes (enables changelog feature)
- * 2. Single schema file named 'schema.graphql' (non-versioned, like file data source)
- */
-export interface ConfigInput {
-  /**
-   * 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?: string
-  projectRoot?: string
-}
-
-export interface Config {
-  path: string
-}
-
-export const normalizeConfig = (configInput: ConfigInput): Config => {
-  const ensureAbsolute = Path.ensureAbsoluteWith(configInput.projectRoot)
-  const config: Config = {
-    path: ensureAbsolute(configInput.path ?? defaultPaths.schemaDirectory),
-  }
-
-  return config
-}
-
-export const readOrThrow = async (configInput: ConfigInput): Promise<null | GraphqlChangeset.ChangelogLinked> => {
-  const config = normalizeConfig(configInput)
-
-  debug(`will search`, config)
-  const filePaths = await glob({
-    cwd: config.path,
-    absolute: true,
-    onlyFiles: true,
-    patterns: [`*.graphql`],
-  })
-  debug(`did find`, filePaths)
-
-  if (!Arr.isntEmpty(filePaths)) {
-    return null
-  }
-
-  const fileNameExpressions = Arr.map(filePaths, FileNameExpression.parseOrThrow)
-  debug(`parsed file names`, fileNameExpressions)
-
-  // Separate versioned (dated) and single schema files
-  const versionedExpressions = fileNameExpressions.filter(
-    (expr): expr is FileNameExpression.ExpressionVersioned => expr.type === `FileNameExpressionVersioned`,
-  )
-  const singleExpressions = fileNameExpressions.filter(
-    (expr): expr is FileNameExpression.ExpressionSingle => expr.type === `FileNameExpressionSingle`,
-  )
-
-  // If we have versioned files, use them (versioned takes precedence)
-  if (Arr.isntEmpty(versionedExpressions)) {
-    return await readVersionedSchemas(versionedExpressions)
-  }
-
-  // If we have a single schema file, use it
-  if (Arr.isntEmpty(singleExpressions)) {
-    if (singleExpressions.length > 1) {
-      throw new Error(
-        `Multiple single schema files found, expected exactly one: ${
-          singleExpressions.map(e => e.filePath).join(', ')
-        }`,
-      )
-    }
-    return await readSingleSchemaFile(singleExpressions[0].filePath)
-  }
-
-  // Should not happen since we already checked for empty filePaths
-  throw new Error(`No schema files found despite non-empty file paths`)
-}
-
-/**
- * Read multiple versioned schema files and create changesets
- */
-const readVersionedSchemas = async (
-  versionedExpressions: FileNameExpression.ExpressionVersioned[],
-): Promise<GraphqlChangeset.ChangelogLinked> => {
-  const versions = await Promise.all(Arr.map(versionedExpressions, async fileNameExpression => {
-    const schemaFile = await Grafaid.Schema.read(fileNameExpression.filePath)
-    // Should never happen since these paths come from the glob.
-    if (!schemaFile) throw new Error(`Failed to read schema file: ${fileNameExpression.filePath}`)
-
-    return {
-      ...fileNameExpression,
-      schema: schemaFile.content,
-    }
-  }))
-  debug(`read versioned schemas`)
-
-  versions.sort((a, b) => a.date.getTime() - b.date.getTime())
-
-  const changesets = await Promise.all(
-    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSetLinked> => {
-      const current = version
-      const previous = versions[index - 1]
-
-      const before = previous?.schema ?? Grafaid.Schema.empty
-      const after = current.schema
-
-      if (!previous) {
-        // First version - create InitialChangeSet
-        return {
-          type: 'InitialChangeSet',
-          date: current.date,
-          after: { version: null, data: after },
-        }
-      } else {
-        // Subsequent versions - create IntermediateChangeSet
-        const changes = await GraphqlChange.calcChangeset({
-          before,
-          after,
-        })
-
-        return {
-          type: 'IntermediateChangeSet',
-          date: current.date,
-          before: { version: null, data: before },
-          after: { version: null, data: after },
-          changes,
-        }
-      }
-    }),
-  )
-
-  changesets.reverse()
-
-  debug(`computed versioned schema`)
-  return changesets as GraphqlChangeset.ChangelogLinked
-}

package/src/api/schema/data-sources/schema-file/schema-file.ts

@@ -1,84 +0,0 @@
-import { Grafaid } from '#lib/grafaid'
-import { GraphqlChange } from '#lib/graphql-change'
-import type { GraphqlChangeset } from '#lib/graphql-changeset'
-import { Path } from '@wollybeard/kit'
-
-const defaultPaths = {
-  schemaFile: `./schema.graphql`,
-}
-
-/**
- * Configuration for loading schema from a single SDL file.
- */
-export interface ConfigInput {
-  /**
-   * 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?: string
-  projectRoot?: string
-}
-
-export interface Config {
-  path: string
-}
-
-export const normalizeConfig = (configInput: ConfigInput): Config => {
-  const config: Config = {
-    path: Path.ensureAbsolute(configInput.path ?? defaultPaths.schemaFile, configInput.projectRoot),
-  }
-
-  return config
-}
-
-export const readOrThrow = async (
-  configInput: ConfigInput,
-): Promise<null | GraphqlChangeset.ChangelogLinked> => {
-  const config = normalizeConfig(configInput)
-
-  const schemaFile = await Grafaid.Schema.read(config.path)
-  if (!schemaFile) return null
-
-  return await readSingleSchemaFile(config.path)
-}
-
-/**
- * Create a single changeset from a schema file path.
- * This is the core logic for handling single (unversioned) schemas.
- */
-export const readSingleSchemaFile = async (filePath: string): Promise<GraphqlChangeset.ChangelogLinked> => {
-  const schemaFile = await Grafaid.Schema.read(filePath)
-  if (!schemaFile) throw new Error(`Failed to read schema file: ${filePath}`)
-
-  const date = new Date() // Generate date here for unversioned schema
-  const after = schemaFile.content
-  const before = Grafaid.Schema.empty
-  const changes = await GraphqlChange.calcChangeset({
-    before,
-    after,
-  })
-
-  const changeset: GraphqlChangeset.IntermediateChangeSetLinked = {
-    type: 'IntermediateChangeSet',
-    date,
-    after: { version: null, data: after },
-    before: { version: null, data: before },
-    changes,
-  }
-
-  const schema: GraphqlChangeset.ChangelogLinked = [changeset]
-
-  return schema
-}