polen 0.10.0 → 0.11.0-next.10

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

@@ -0,0 +1,213 @@
+import { Grafaid } from '#lib/grafaid/index'
+import { GraphqlChange } from '#lib/graphql-change/index'
+import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader/index'
+import { Fs, Json, Path } from '@wollybeard/kit'
+import type { NonEmptyChangeSets, 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<NonEmptyChangeSets> => {
+  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.ChangeSet = {
+    date,
+    after,
+    before,
+    changes,
+  }
+
+  const result: NonEmptyChangeSets = [changeset]
+
+  return result
+}

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

@@ -2,7 +2,7 @@ import { Grafaid } from '#lib/grafaid/index'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { Arr } from '@wollybeard/kit'
-import type { Schema } from '../../schema.js'
+import type { NonEmptyChangeSets } from '../../schema.js'
 
 /**
  * Configuration for defining schemas programmatically in memory.
@@ -68,7 +68,7 @@ export const normalize = (configInput: ConfigInput): Config => {
 
 export const read = async (
   configInput: ConfigInput,
-): Promise<null | Schema> => {
+): Promise<null | NonEmptyChangeSets> => {
   const config = normalize(configInput)
 
   if (!Arr.isntEmpty(config.versions)) {
@@ -109,9 +109,7 @@ export const read = async (
 
   changesets.reverse()
 
-  const schema: Schema = {
-    versions: changesets,
-  }
+  const schema: NonEmptyChangeSets = changesets
 
   return schema
 }

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

@@ -1,6 +1,6 @@
 import { Path } from '@wollybeard/kit'
 
-export type Expression = ExpressionPrevious
+export type Expression = ExpressionVersioned | ExpressionSingle
 
 export const parseOrThrow = (fileNameOrSerializedExpression: string): Expression => {
   const result = parse(fileNameOrSerializedExpression)
@@ -18,41 +18,57 @@ export const parse = (fileName: string): null | Expression => {
   }
   const serializedExpression = path.name
 
-  const previous = parseExpressionPreviousSerialized(serializedExpression)
-  if (previous) return { ...previous, filePath: fileName, type: `FileNameExpressionPrevious` }
+  const versioned = parseExpressionVersionedSerialized(serializedExpression)
+  if (versioned) return { ...versioned, filePath: fileName, type: `FileNameExpressionVersioned` }
 
-  // const latest = parseExpressionLatestSerialized(serializedExpression)
-  // if (latest) return { ...latest, filePath: fileName, type: `FileNameExpressionLatest` }
+  const single = parseExpressionSingleSerialized(serializedExpression)
+  if (single) return { ...single, filePath: fileName, type: `FileNameExpressionSingle` }
 
   return null
 }
 
 // ----
 
-export interface ExpressionPrevious {
-  type: `FileNameExpressionPrevious`
+export interface ExpressionVersioned {
+  type: `FileNameExpressionVersioned`
   date: Date
   filePath: string
 }
 
-const parseExpressionPreviousSerialized = (
+const parseExpressionVersionedSerialized = (
   serializedExpression: string,
-): Pick<ExpressionPrevious, `date`> | null => {
-  const match = expressionPreviousSerializedPattern.exec(serializedExpression)
+): 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 expressionPreviousSerializedPattern = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/
+const expressionVersionedSerializedPattern = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/
 
-// export const isExpressionPrevious = (expression: Expression): expression is ExpressionPrevious => {
-//   return expression.type === `FileNameExpressionPrevious`
+// 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

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

@@ -4,7 +4,8 @@ import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { debugPolen } from '#singletons/debug'
 import { Arr, Path } from '@wollybeard/kit'
 import { glob } from 'tinyglobby'
-import type { Schema } from '../../schema.js'
+import type { NonEmptyChangeSets } from '../../schema.js'
+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`])
@@ -15,15 +16,19 @@ const defaultPaths = {
 }
 
 /**
- * Configuration for loading multiple schema versions from a directory.
+ * Configuration for loading schema(s) from a directory.
  *
- * Enables the schema changelog feature by loading SDL files with date prefixes.
+ * 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 dated SDL files.
+   * Path to the directory containing schema files.
    *
-   * Files should be named with ISO date prefixes: `YYYY-MM-DD.graphql`
+   * Supports two patterns:
+   * 1. Multiple versioned files with ISO date prefixes: `YYYY-MM-DD.graphql`
+   * 2. Single file named: `schema.graphql`
    *
    * @default './schema'
    *
@@ -36,12 +41,17 @@ export interface ConfigInput {
    * path: './graphql/versions'
    * ```
    *
-   * Directory structure example:
+   * 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
@@ -61,7 +71,7 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
   return config
 }
 
-export const readOrThrow = async (configInput: ConfigInput): Promise<null | Schema> => {
+export const readOrThrow = async (configInput: ConfigInput): Promise<null | NonEmptyChangeSets> => {
   const config = normalizeConfig(configInput)
 
   debug(`will search`, config)
@@ -80,7 +90,42 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | Sche
   const fileNameExpressions = Arr.map(filePaths, FileNameExpression.parseOrThrow)
   debug(`parsed file names`, fileNameExpressions)
 
-  const versions = await Promise.all(Arr.map(fileNameExpressions, async fileNameExpression => {
+  // 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<NonEmptyChangeSets> => {
+  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}`)
@@ -90,7 +135,7 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | Sche
       schema: schemaFile.content,
     }
   }))
-  debug(`read schemas`)
+  debug(`read versioned schemas`)
 
   versions.sort((a, b) => a.date.getTime() - b.date.getTime())
 
@@ -118,11 +163,6 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | Sche
 
   changesets.reverse()
 
-  const schema: Schema = {
-    versions: changesets,
-  }
-
-  debug(`computed schema`)
-
-  return schema
+  debug(`computed versioned schema`)
+  return changesets as NonEmptyChangeSets
 }

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

@@ -2,7 +2,7 @@ import { Grafaid } from '#lib/grafaid/index'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { Path } from '@wollybeard/kit'
-import type { Schema } from '../../schema.js'
+import type { NonEmptyChangeSets } from '../../schema.js'
 
 const defaultPaths = {
   schemaFile: `./schema.graphql`,
@@ -46,13 +46,24 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
 
 export const readOrThrow = async (
   configInput: ConfigInput,
-): Promise<null | Schema> => {
+): Promise<null | NonEmptyChangeSets> => {
   const config = normalizeConfig(configInput)
 
   const schemaFile = await Grafaid.Schema.read(config.path)
   if (!schemaFile) return null
 
-  const date = new Date()
+  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<NonEmptyChangeSets> => {
+  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({
@@ -60,16 +71,14 @@ export const readOrThrow = async (
     after,
   })
 
-  const schemaVersion: GraphqlChangeset.ChangeSet = {
+  const changeset: GraphqlChangeset.ChangeSet = {
     date,
     after,
     before,
     changes,
   }
 
-  const schema: Schema = {
-    versions: [schemaVersion],
-  }
+  const schema: NonEmptyChangeSets = [changeset]
 
   return schema
 }

package/src/api/schema/metadata.ts

@@ -0,0 +1,23 @@
+import { Fs } from '@wollybeard/kit'
+import { z } from 'zod'
+
+export const SchemaMetadataSchema = z.object({
+  /** Whether a schema is present in the project */
+  hasSchema: z.boolean(),
+  /** Array of available version identifiers */
+  versions: z.array(z.string()),
+})
+
+export type SchemaMetadata = z.infer<typeof SchemaMetadataSchema>
+
+export const getMetadata = async (path: string): Promise<SchemaMetadata> => {
+  const result = await Fs.readJson(path)
+  if (!result) {
+    return {
+      hasSchema: false,
+      versions: [],
+    }
+  }
+
+  return SchemaMetadataSchema.parse(result)
+}