polen 0.11.0-next.7 → 0.11.0-next.9

package/build/template/routes/reference.js

@@ -1,17 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { GrafaidOld } from '#lib/grafaid-old/index';
-import { createRoute } from '#lib/react-router-aid/react-router-aid';
+import { Grafaid } from '#lib/grafaid/index';
+import { route, routeIndex } from '#lib/react-router-aid/react-router-aid';
 import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader';
 import { Box } from '@radix-ui/themes';
-import { Outlet } from 'react-router';
+import { Outlet, useParams, useRouteLoaderData } from 'react-router';
+import { Field } from '../components/Field.js';
 import { MissingSchema } from '../components/MissingSchema.js';
+import { NamedType } from '../components/NamedType.js';
 import { VersionSelector } from '../components/VersionSelector.js';
 import { SidebarLayout } from '../layouts/index.js';
 import { VERSION_LATEST } from '../lib/schema-utils/constants.js';
 import { schemaSource } from '../sources/schema-source.js';
-import { reference$type } from './reference.$type.js';
-import { referenceVersion$version$type } from './reference.version.$version.$type.js';
-const loader = createLoader(async ({ params }) => {
+export const loader = createLoader(async ({ params }) => {
     // Handle both versioned and unversioned routes:
     // - Versioned: /reference/version/:version/:type → params.version exists
     // - Unversioned: /reference/:type → params.version is undefined, defaults to latest
@@ -24,7 +25,7 @@ const loader = createLoader(async ({ params }) => {
         availableVersions,
     };
 });
-const Component = () => {
+const RouteReferenceComponent = () => {
     const data = useLoaderData();
     if (!data.schema) {
         return _jsx(MissingSchema, {});
@@ -53,18 +54,76 @@ const Component = () => {
     }
     return (_jsxs(SidebarLayout, { sidebar: sidebarItems, children: [_jsx(Box, { mb: `4`, children: _jsx(VersionSelector, { availableVersions: data.availableVersions, currentVersion: data.currentVersion }) }), _jsx(Outlet, {})] }));
 };
-// Create the versioned reference route with explicit version prefix
-const referenceVersioned = createRoute({
-    path: `version/:version`,
-    loader,
-    Component,
-    children: [referenceVersion$version$type],
-});
-// Create the main reference route with explicit version path and fallback type path
-export const reference = createRoute({
+// Shared hooks for schema data validation and retrieval
+const useReferenceSchema = () => {
+    const data = useRouteLoaderData('reference');
+    if (!data?.schema) {
+        throw new Error('Schema not found');
+    }
+    return data;
+};
+const useSchemaType = (typeName) => {
+    const { schema } = useReferenceSchema();
+    const type = schema.getType(typeName);
+    if (!type) {
+        throw new Error(`Could not find type ${typeName}`);
+    }
+    return type;
+};
+const useSchemaField = (typeName, fieldName) => {
+    const type = useSchemaType(typeName);
+    if (!Grafaid.Schema.TypesLike.isFielded(type)) {
+        throw new Error(`Type ${typeName} does not have fields`);
+    }
+    const fields = type.getFields();
+    const field = fields[fieldName];
+    if (!field) {
+        throw new Error(`Could not find field ${fieldName} on type ${typeName}`);
+    }
+    return field;
+};
+const RouteComponentIndex = () => {
+    return _jsx("div", { children: "Select a type from the sidebar to view its documentation." });
+};
+const RouteComponentType = () => {
+    const params = useParams();
+    const type = useSchemaType(params.type);
+    return _jsx(NamedType, { data: type });
+};
+const RouteComponentTypeField = () => {
+    const params = useParams();
+    const field = useSchemaField(params.type, params.field);
+    return _jsx(Field, { data: field });
+};
+const typeAndFieldRoutes = [
+    routeIndex(RouteComponentIndex),
+    route({
+        path: `:type`,
+        Component: RouteComponentType,
+        errorElement: _jsx(MissingSchema, {}),
+        children: [
+            route({
+                path: `:field`,
+                Component: RouteComponentTypeField,
+                errorElement: _jsx(MissingSchema, {}),
+            }),
+        ],
+    }),
+];
+/**
+ * Reference documentation with proper nested structure - all routes in one file
+ */
+export const reference = route({
+    id: 'reference',
     path: `reference`,
     loader,
-    Component,
-    children: [referenceVersioned, reference$type],
+    Component: RouteReferenceComponent,
+    children: [
+        ...typeAndFieldRoutes,
+        route({
+            path: `version/:version`,
+            children: typeAndFieldRoutes,
+        }),
+    ],
 });
 //# sourceMappingURL=reference.js.map

package/build/template/routes/reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../src/template/routes/reference.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../src/template/routes/reference.tsx"],"names":[],"mappings":"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"}

package/build/template/routes/root.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { createRoute } from '#lib/react-router-aid/react-router-aid';
+import { route } from '#lib/react-router-aid/react-router-aid';
 import { Box, Flex, Theme } from '@radix-ui/themes';
 import { Link as LinkReactRouter } from 'react-router';
 import { Outlet, ScrollRestoration } from 'react-router';
@@ -50,7 +50,7 @@ if (PROJECT_SCHEMA) {
 //
 //
 //
-const notFoundRoute = createRoute({
+const notFoundRoute = route({
     id: `*_not_found`,
     path: `*`,
     Component: NotFound,
@@ -65,7 +65,7 @@ children.push(notFoundRoute);
 // ━━━━━━━━━━━━━━ • Root Route
 //
 //
-export const root = createRoute({
+export const root = route({
     path: `/`,
     Component,
     children,

package/build/template/routes/root.js.map

@@ -1 +1 @@
-{"version":3,"file":"root.js","sourceRoot":"","sources":["../../../src/template/routes/root.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"root.js","sourceRoot":"","sources":["../../../src/template/routes/root.tsx"],"names":[],"mappings":"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"}

package/build/template/sources/schema-source.d.ts

@@ -10,6 +10,6 @@ export declare const schemaSource: {
     clearAllAssets: () => Promise<void>;
     removeAsset: (version: string) => Promise<void>;
     writeMetadata: (metadata: import("../../api/schema/metadata.js").SchemaMetadata) => Promise<void>;
-    writeAllAssets: (schemaData: Awaited<ReturnType<typeof import("../../api/schema/read.js").readOrThrow>>, metadata: import("../../api/schema/metadata.js").SchemaMetadata) => Promise<void>;
+    writeAllAssets: (schemaData: Awaited<ReturnType<typeof import("../../api/schema/read.js").readOrThrow>>["data"], metadata: import("../../api/schema/metadata.js").SchemaMetadata) => Promise<void>;
 };
 //# sourceMappingURL=schema-source.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.11.0-next.7",
+  "version": "0.11.0-next.9",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {

package/src/api/config/configurator.ts

@@ -31,25 +31,56 @@ export interface ConfigInput {
    * - `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
-   * // Single file
+   * // Default: looks for schema.graphql
+   * schema: {}
+   *
+   * // Load via introspection
    * schema: {
-   *   useDataSources: 'file',
    *   dataSources: {
-   *     file: { path: './my-schema.graphql' }
+   *     introspection: {
+   *       url: 'https://api.example.com/graphql',
+   *       headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
+   *     }
    *   }
    * }
    *
    * // Multiple versions for changelog
    * schema: {
-   *   useDataSources: 'directory',
    *   dataSources: {
    *     directory: { path: './schema' }
    *   }
    * }
+   *
+   * // Custom source order
+   * schema: {
+   *   useDataSources: ['introspection', 'file'],
+   *   dataSources: {
+   *     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
    */
   schema?: SchemaConfigInput
   /**

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

@@ -1,3 +1,4 @@
+export * as Introspection from './introspection/introspection.js'
 export * as Memory from './memory/memory.js'
 export * as SchemaDirectory from './schema-directory/schema-directory.js'
 export * as SchemaFile from './schema-file/schema-file.js'

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/read.ts

@@ -1,38 +1,104 @@
-import { Arr } from '@wollybeard/kit'
+import { Arr, Fs, Path } from '@wollybeard/kit'
 import * as DataSources from './data-sources/data-sources.js'
 import type { NonEmptyChangeSets } from './schema.js'
 
-export type DataSourceType = `file` | `directory` | `memory` | `data`
+export type DataSourceType =
+  | `file`
+  | `directory`
+  | `memory`
+  | `data`
+  | `introspection`
+  | `introspectionFile`
+  | `introspectionAuto`
+
+/**
+ * Result of schema reading with provenance tracking for file watching and debugging.
+ */
+export interface SchemaReadResult {
+  data: NonEmptyChangeSets | null
+  source: {
+    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<NonEmptyChangeSets | null>
+  }
+}
 
 /**
  * Schema configuration for Polen.
+ *
+ * Polen supports multiple ways to load your GraphQL schema, from simple files
+ * to dynamic introspection. Configure which sources to use and in what order.
+ *
+ * @example
+ * ```ts
+ * // Load from a file (default)
+ * schema: {} // Looks for schema.graphql
+ *
+ * // Load via introspection
+ * schema: {
+ *   dataSources: {
+ *     introspection: {
+ *       url: 'https://api.example.com/graphql',
+ *       headers: { 'Authorization': 'Bearer token' }
+ *     }
+ *   }
+ * }
+ *
+ * // Try multiple sources in order
+ * schema: {
+ *   useDataSources: ['introspection', 'file'],
+ *   dataSources: {
+ *     introspection: { url: 'https://api.example.com/graphql' },
+ *     file: { path: './fallback-schema.graphql' }
+ *   }
+ * }
+ * ```
  */
 export interface Config {
   /**
    * Whether to enable schema loading.
    *
-   * Set to `false` to disable schema features entirely.
+   * Set to `false` to disable schema features entirely. This removes
+   * the Reference and Changelog pages from your portal.
    *
-   * @default `true`
+   * @default true
+   *
+   * @example
+   * ```ts
+   * // Disable schema features
+   * schema: { enabled: false }
+   * ```
    */
   enabled?: boolean
   /**
    * Which data sources to use for loading schemas.
    *
-   * - `file` - Load from a single SDL file
-   * - `directory` - Load multiple SDL files from a directory
+   * - `file` - Load from a single SDL file (default: `./schema.graphql`)
+   * - `directory` - Load multiple SDL files from a directory (default: `./schema/`)
    * - `memory` - Use schemas defined in configuration
    * - `data` - Use a pre-built schema object
+   * - `introspection` - Load schema via GraphQL introspection
    *
-   * If not specified, Polen will try all sources in order until one succeeds.
+   * If not specified, Polen tries all sources in this order:
+   * 1. `data` 2. `directory` 3. `file` 4. `memory` 5. `introspection`
    *
    * @example
    * ```ts
    * // Use only file source
    * useDataSources: 'file'
    *
-   * // Try multiple sources
-   * useDataSources: ['directory', 'file']
+   * // Try multiple sources in custom order
+   * useDataSources: ['introspection', 'file']
+   *
+   * // Default behavior (try all sources)
+   * // useDataSources: undefined
    * ```
    */
   useDataSources?: Arr.Maybe<DataSourceType>
@@ -56,22 +122,38 @@ export interface Config {
      * Pre-built schema object to use directly.
      */
     data?: NonEmptyChangeSets
+    /**
+     * Configuration for loading schema via GraphQL introspection.
+     *
+     * Introspection fetches your schema directly from a running GraphQL endpoint.
+     * The schema is saved to `schema.introspection.json` in your project root.
+     * Delete this file to force a fresh introspection on the next build.
+     *
+     * @example
+     * ```ts
+     * introspection: {
+     *   url: 'https://api.example.com/graphql',
+     *   headers: { 'Authorization': 'Bearer token' }
+     * }
+     * ```
+     */
+    introspection?: DataSources.Introspection.ConfigInput
   }
   projectRoot: string
 }
 
 export const readOrThrow = async (
   config: Config,
-): Promise<null | NonEmptyChangeSets> => {
+): Promise<SchemaReadResult> => {
   if (config.enabled === false) {
-    return null
+    return { data: null, source: { type: 'data' } }
   }
 
   const useDataSources = config.useDataSources ? Arr.sure(config.useDataSources) : null
   const usingDataSource = (dataSource: DataSourceType) => useDataSources === null || useDataSources.includes(dataSource)
 
   if (usingDataSource(`data`) && config.dataSources?.data) {
-    return config.dataSources.data
+    return { data: config.dataSources.data, source: { type: 'data' } }
   }
 
   if (usingDataSource(`directory`)) {
@@ -80,7 +162,7 @@ export const readOrThrow = async (
       ...config.dataSources?.directory,
     }
     const result = await DataSources.SchemaDirectory.readOrThrow(directoryConfig)
-    if (result) return result
+    if (result) return { data: result, source: { type: 'directory' } }
   }
 
   if (usingDataSource(`file`)) {
@@ -89,7 +171,7 @@ export const readOrThrow = async (
       ...config.dataSources?.file,
     }
     const result = await DataSources.SchemaFile.readOrThrow(fileConfig)
-    if (result) return result
+    if (result) return { data: result, source: { type: 'file' } }
   }
 
   if (usingDataSource(`memory`) && config.dataSources?.memory) {
@@ -98,8 +180,17 @@ export const readOrThrow = async (
       ...config.dataSources.memory,
     }
     const result = await DataSources.Memory.read(memoryConfig)
-    if (result) return result
+    if (result) return { data: result, source: { type: 'memory' } }
+  }
+
+  if (usingDataSource(`introspection`) && config.dataSources?.introspection) {
+    const introspectionConfig = {
+      projectRoot: config.projectRoot,
+      ...config.dataSources.introspection,
+    }
+    const result = await DataSources.Introspection.readOrThrow(introspectionConfig)
+    if (result.data) return result
   }
 
-  return null
+  return { data: null, source: { type: 'data' } }
 }