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

package/build/vite/plugins/schemas.js

@@ -1,6 +1,7 @@
 import { Api } from '#api/$';
 import { Schema } from '#api/schema/$';
 import { Catalog } from '#lib/catalog/$';
+import { Diagnostic } from '#lib/diagnostic/$';
 import { ViteReactive } from '#lib/vite-reactive/$';
 import { createAssetReader } from '#lib/vite-reactive/reactive-asset-plugin';
 import { ViteVirtual } from '#lib/vite-virtual/$';
@@ -30,7 +31,30 @@ export const Schemas = ({ config, dependentVirtualModules = [], }) => {
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     // Self-contained Schema Reader
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    const reader = createAssetReader(() => Schema.loadOrNull(config));
+    let lastDiagnostics = [];
+    const reader = createAssetReader(() => Schema.loadOrNull(config).pipe(Effect.map((result) => {
+        // Store diagnostics for reporting
+        if (result?.diagnostics) {
+            lastDiagnostics = result.diagnostics;
+        }
+        return result;
+    })));
+    // Map diagnostic to its control configuration
+    const getControlForDiagnostic = (diagnostic) => {
+        if (diagnostic.source === 'schema-augmentations') {
+            // All augmentation errors are always enabled with error severity
+            return {
+                enabled: true,
+                dev: { severity: 'error' },
+                build: { severity: 'error' },
+            };
+        }
+        return undefined;
+    };
+    // Report diagnostics
+    const reportDiagnostics = (diagnostics, phase = 'dev') => {
+        Diagnostic.filterAndReport(diagnostics, getControlForDiagnostic, phase);
+    };
     // Helper to check if a file is a schema file that should trigger regeneration
     const isSchemaFile = (file) => {
         if (!config.schema)
@@ -77,7 +101,7 @@ export const Schemas = ({ config, dependentVirtualModules = [], }) => {
             emit: {
                 // @claude in what case can data be null?
                 serializer: (loadedCatalog) => Effect.gen(function* () {
-                    if (!loadedCatalog.data)
+                    if (!loadedCatalog?.data)
                         throw new Error('No schema data to serialize');
                     const encoded = yield* Catalog.encode(loadedCatalog.data);
                     return JSON.stringify(encoded, null, 2);
@@ -89,6 +113,14 @@ export const Schemas = ({ config, dependentVirtualModules = [], }) => {
                 isRelevant: isSchemaFile,
             },
             dependentVirtualModules,
+            hooks: {
+                async onDiagnostics(data) {
+                    // Report augmentation diagnostics
+                    if (data?.diagnostics) {
+                        reportDiagnostics(data.diagnostics, 'dev');
+                    }
+                },
+            },
         }),
         {
             name: 'polen:schemas-virtual',
@@ -98,6 +130,10 @@ export const Schemas = ({ config, dependentVirtualModules = [], }) => {
                     const debug = debugPolen.sub(`module-project-schema`);
                     debug(`load`, { id: viProjectSchema.id });
                     const schemaResult = await Effect.runPromise(reader.read().pipe(Effect.provide(NodeFileSystem.layer)));
+                    // Report diagnostics if any
+                    if (schemaResult?.diagnostics && schemaResult.diagnostics.length > 0) {
+                        reportDiagnostics(schemaResult.diagnostics, 'dev');
+                    }
                     if (!schemaResult?.data) {
                         return `export const schemasCatalog = null`;
                     }

package/build/vite/plugins/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/vite/plugins/schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/vite/plugins/schemas.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/src/api/config/input.ts

@@ -1,4 +1,5 @@
 import { ExamplesConfig } from '#api/examples/config'
+import { ReferenceConfig } from '#api/reference/config'
 import { ConfigSchema } from '#api/schema/config-schema'
 import { Vite } from '#dep/vite/index'
 import { spreadShallow } from '#lib/kit-temp'
@@ -306,6 +307,7 @@ export const ConfigInput = S.Struct({
    */
   description: S.optional(S.String),
   schema: S.optional(ConfigSchema),
+  reference: S.optional(ReferenceConfig),
   examples: S.optional(ExamplesConfig),
   templateVariables: S.optional(TemplateVariables),
   home: S.optional(HomeConfig),

package/src/api/config/normalized.ts

@@ -1,4 +1,5 @@
 import { ExamplesConfig } from '#api/examples/config'
+import { DescriptionsView, ReferenceConfigObject } from '#api/reference/config'
 import { ConfigSchema } from '#api/schema/config-schema'
 import { Typings } from '#api/typings/$'
 import { DirectedFilter } from '#lib/directed-filter/$'
@@ -11,6 +12,24 @@ import { Effect } from 'effect'
 import type { WritableDeep } from 'type-fest'
 import { BuildArchitecture, ConfigInput } from './input.js'
 
+// ============================================================================
+// Normalized Reference Config
+// ============================================================================
+
+/**
+ * Normalized reference configuration where all optional fields have defaults applied.
+ */
+const NormalizedReferenceConfig = S.extend(
+  ReferenceConfigObject.pipe(S.omit('descriptionsView', 'nullabilityRendering')),
+  S.Struct({
+    descriptionsView: S.Struct({
+      defaultMode: S.Literal('compact', 'expanded'),
+      showControl: S.Boolean,
+    }),
+    nullabilityRendering: S.Literal('questionMark', 'bangMark'),
+  }),
+)
+
 // ============================================================================
 // DirectedFilter for Strings
 // ============================================================================
@@ -320,6 +339,11 @@ export const Config = S.Struct({
    */
   schema: ConfigSchema,
 
+  /**
+   * Reference documentation configuration with resolved defaults.
+   */
+  reference: NormalizedReferenceConfig,
+
   /**
    * Examples configuration with resolved defaults.
    */
@@ -487,6 +511,13 @@ const getConfigInputDefaults = (baseRootDirPath: string): Config => ({
     },
   },
   schema: {},
+  reference: {
+    descriptionsView: {
+      defaultMode: 'expanded',
+      showControl: true,
+    },
+    nullabilityRendering: 'bangMark',
+  },
   examples: {
     display: 'all',
   },
@@ -658,6 +689,29 @@ export const normalizeInput = (
         configInput_as_writeable.warnings.interactiveWithoutSchema.enabled
     }
 
+    // Process reference configuration
+    if (configInput_as_writeable?.reference) {
+      const referenceInput = configInput_as_writeable.reference
+      // The schema transform handles boolean shorthand, so we always get an object here
+      if (referenceInput.enabled !== undefined) {
+        config.reference.enabled = referenceInput.enabled
+      }
+      if (referenceInput.descriptionsView) {
+        if (referenceInput.descriptionsView.defaultMode !== undefined) {
+          config.reference.descriptionsView.defaultMode = referenceInput.descriptionsView.defaultMode
+        }
+        if (referenceInput.descriptionsView.showControl !== undefined) {
+          config.reference.descriptionsView.showControl = referenceInput.descriptionsView.showControl
+        }
+      }
+      if (referenceInput.nullabilityRendering !== undefined) {
+        config.reference.nullabilityRendering = referenceInput.nullabilityRendering
+      }
+      if (referenceInput.diagnostics) {
+        config.reference.diagnostics = referenceInput.diagnostics
+      }
+    }
+
     // Process examples configuration
     if (configInput_as_writeable?.examples) {
       const examplesInput = configInput_as_writeable.examples

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

@@ -1,5 +1,6 @@
 import type { Api } from '#api/$'
 import { ExamplesConfigObject } from '#api/examples/config'
+import { ReferenceConfigObject } from '#api/reference/config'
 import { ConfigSchema } from '#api/schema/config-schema'
 import type { Catalog } from '#lib/catalog/$'
 import { S } from '#lib/kit-temp/effect'
@@ -16,6 +17,13 @@ export const resolve = (config: Config, data: {
       ...config.schema,
       enabled: Boolean(config.schema.enabled ?? data.schemas),
     },
+    reference: {
+      ...config.reference,
+      // Reference is enabled if explicitly enabled OR if schemas exist (unless explicitly disabled)
+      enabled: Boolean(config.reference.enabled ?? data.schemas),
+      descriptionsView: config.reference.descriptionsView,
+      nullabilityRendering: config.reference.nullabilityRendering,
+    },
     examples: {
       ...config.examples,
       enabled: Boolean(config.examples.enabled ?? (data.examples && data.examples.examples.length > 0)),
@@ -33,7 +41,7 @@ export const resolve = (config: Config, data: {
  * that control feature enablement have been resolved to concrete values.
  */
 export const TemplateConfig = S.extend(
-  Config.pipe(S.omit('_input', 'schema', 'examples')),
+  Config.pipe(S.omit('_input', 'schema', 'reference', 'examples')),
   S.Struct({
     schema: S.extend(
       ConfigSchema.pipe(S.omit('enabled')),
@@ -41,6 +49,15 @@ export const TemplateConfig = S.extend(
         enabled: S.Boolean,
       }),
     ),
+    reference: S.Struct({
+      enabled: S.Boolean,
+      descriptionsView: S.Struct({
+        defaultMode: S.Literal('compact', 'expanded'),
+        showControl: S.Boolean,
+      }),
+      nullabilityRendering: S.Literal('questionMark', 'bangMark'),
+      diagnostics: S.optional(S.Unknown), // From ReferenceConfigObject
+    }),
     examples: S.extend(
       ExamplesConfigObject.pipe(S.omit('enabled')),
       S.Struct({

package/src/api/examples/diagnostic/diagnostic.ts

@@ -2,7 +2,6 @@ import { DiagnosticDuplicateContent } from '#api/examples/diagnostic/duplicate-c
 import { DiagnosticInvalidFilename } from '#api/examples/diagnostic/invalid-filename'
 import { DiagnosticMissingVersions } from '#api/examples/diagnostic/missing-versions'
 import { DiagnosticUnknownVersion } from '#api/examples/diagnostic/unknown-version'
-import { DiagnosticUnusedDefault } from '#api/examples/diagnostic/unused-default'
 import { DiagnosticValidationError } from '#api/examples/diagnostic/validation-error'
 import { S } from '#lib/kit-temp/effect'
 
@@ -11,12 +10,10 @@ export * from './duplicate-content.js'
 export * from './invalid-filename.js'
 export * from './missing-versions.js'
 export * from './unknown-version.js'
-export * from './unused-default.js'
 export * from './validation-error.js'
 export { validateExamples } from './validator.js'
 
 export const Diagnostic = S.Union(
-  DiagnosticUnusedDefault,
   DiagnosticDuplicateContent,
   DiagnosticMissingVersions,
   DiagnosticInvalidFilename,

package/src/api/examples/scanner.test.ts

@@ -0,0 +1,83 @@
+import { Version } from '#lib/version/$'
+import { HashMap } from 'effect'
+import { describe, expect, test } from 'vitest'
+import * as scanner from './scanner.js'
+
+describe('parseExampleFile', () => {
+  test.for([
+    {
+      input: 'get-user.graphql',
+      expected: { type: 'unversioned', name: 'get-user', file: 'get-user.graphql' },
+    },
+    {
+      input: 'get-user.1.graphql',
+      expected: {
+        type: 'versioned',
+        name: 'get-user',
+        version: Version.decodeSync('1'),
+        file: 'get-user.1.graphql',
+      },
+    },
+    {
+      input: 'get-user.default.graphql',
+      expected: {
+        type: 'versioned',
+        name: 'get-user',
+        version: expect.objectContaining({ _tag: 'VersionCustom', value: 'default' }),
+        file: 'get-user.default.graphql',
+      },
+    },
+  ])('parses $input correctly', ({ input, expected }) => {
+    expect(scanner.parseExampleFile(input)).toEqual(expected)
+  })
+})
+
+describe('resolveDefaultFiles', () => {
+  const v1 = Version.decodeSync('1')
+  const v2 = Version.decodeSync('2')
+  const v3 = Version.decodeSync('3')
+  const schemaVersions = [v1, v2, v3]
+
+  test.for([
+    {
+      name: 'unversioned file alone remains unversioned',
+      grouped: new Map([['example', { unversioned: 'example.graphql', versioned: new Map() }]]),
+      assertions: (resolved: ReturnType<typeof scanner.resolveDefaultFiles>) => {
+        const example = resolved.get('example')!
+        expect(example.unversioned).toBe('example.graphql')
+        expect(HashMap.size(example.versionDocuments)).toBe(0)
+      },
+    },
+    {
+      name: 'unversioned file acts as default when versioned files exist',
+      grouped: new Map([['example', {
+        unversioned: 'example.graphql',
+        versioned: new Map([[v1, 'example.1.graphql']]),
+      }]]),
+      assertions: (resolved: ReturnType<typeof scanner.resolveDefaultFiles>) => {
+        const example = resolved.get('example')!
+        expect(example.unversioned).toBeUndefined()
+        expect(HashMap.size(example.versionDocuments)).toBe(2)
+        expect(HashMap.has(example.versionDocuments, v1)).toBe(true)
+
+        const entries = [...HashMap.entries(example.versionDocuments)]
+        const defaultEntry = entries.find(([_, value]) => value === 'example.graphql')
+        expect(defaultEntry).toBeDefined()
+      },
+    },
+    {
+      name: 'only versioned files when no unversioned exists',
+      grouped: new Map([['example', {
+        versioned: new Map([[v1, 'example.1.graphql'], [v2, 'example.2.graphql']]),
+      }]]),
+      assertions: (resolved: ReturnType<typeof scanner.resolveDefaultFiles>) => {
+        const example = resolved.get('example')!
+        expect(example.unversioned).toBeUndefined()
+        expect(HashMap.size(example.versionDocuments)).toBe(2)
+      },
+    },
+  ])('$name', ({ grouped, assertions }) => {
+    const resolved = scanner.resolveDefaultFiles(grouped, schemaVersions)
+    assertions(resolved)
+  })
+})

package/src/api/examples/scanner.ts

@@ -50,19 +50,17 @@ const VERSIONED_FILE_PATTERN = Str.pattern<{ groups: ['name', 'version'] }>(
 type ParsedExampleFile =
   | { type: 'unversioned'; name: string; file: string }
   | { type: 'versioned'; name: string; version: Version.Version; file: string }
-  | { type: 'default'; name: string; file: string }
 
 type GroupedExampleFiles = Map<string, {
   unversioned?: string
   versioned: Map<Version.Version, string>
-  default?: string
 }>
 
 // ============================================================================
 // Helpers
 // ============================================================================
 
-const parseExampleFile = (filename: string): ParsedExampleFile => {
+export const parseExampleFile = (filename: string): ParsedExampleFile => {
   const parsed = Path.parse(filename)
   const base = parsed.name
 
@@ -72,11 +70,6 @@ const parseExampleFile = (filename: string): ParsedExampleFile => {
   if (match) {
     const { name, version: versionStr } = match.groups
 
-    // Handle special 'default' keyword
-    if (versionStr === 'default') {
-      return { type: 'default', name, file: filename }
-    }
-
     const version = Version.decodeSync(versionStr)
     return { type: 'versioned', name, version, file: filename }
   }
@@ -106,9 +99,6 @@ const groupExampleFiles = (files: string[]): GroupedExampleFiles => {
       case 'versioned':
         group.versioned.set(parsed.version, parsed.file)
         break
-      case 'default':
-        group.default = parsed.file
-        break
     }
   }
 
@@ -119,7 +109,7 @@ const groupExampleFiles = (files: string[]): GroupedExampleFiles => {
  * Resolve .default files into proper version coverage.
  * This erases the .default convention and converts it to semantic version sets.
  */
-const resolveDefaultFiles = (
+export const resolveDefaultFiles = (
   grouped: GroupedExampleFiles,
   schemaVersions: Version.Version[],
 ): Map<string, {
@@ -139,9 +129,9 @@ const resolveDefaultFiles = (
       versionDocuments = HashMap.set(versionDocuments, version, file)
     }
 
-    // Handle default file if present
-    if (group.default) {
-      // Determine which versions the default covers
+    // Handle unversioned file
+    if (group.unversioned && group.versioned.size > 0) {
+      // When both unversioned and versioned exist, use unversioned as default for missing versions
       const explicitVersions = HashSet.fromIterable(group.versioned.keys())
       const defaultVersions = schemaVersions.filter(v => !HashSet.has(explicitVersions, v))
 
@@ -151,14 +141,20 @@ const resolveDefaultFiles = (
           ? defaultVersions[0]! // Single version
           : HashSet.fromIterable(defaultVersions) // Version set
 
-        versionDocuments = HashMap.set(versionDocuments, defaultCoverage, group.default)
+        versionDocuments = HashMap.set(versionDocuments, defaultCoverage, group.unversioned)
       }
+      // Don't add to resolved.unversioned since it's acting as a default
+      resolved.set(name, { versionDocuments })
+    } else if (group.unversioned) {
+      // Only unversioned exists - truly unversioned
+      resolved.set(name, {
+        versionDocuments,
+        unversioned: group.unversioned,
+      })
+    } else {
+      // Only versioned files exist
+      resolved.set(name, { versionDocuments })
     }
-
-    resolved.set(name, {
-      versionDocuments,
-      ...(group.unversioned ? { unversioned: group.unversioned } : {}),
-    })
   }
 
   return resolved
@@ -334,6 +330,20 @@ export const scan = (
       }
 
       if (example) {
+        // Check for description.md or description.mdx file
+        const descriptionMdPath = Path.join(options.dir, `${name}.md`)
+        const descriptionMdxPath = Path.join(options.dir, `${name}.mdx`)
+
+        const descriptionPath = (yield* fs.exists(descriptionMdPath))
+          ? descriptionMdPath
+          : (yield* fs.exists(descriptionMdxPath))
+          ? descriptionMdxPath
+          : null
+
+        if (descriptionPath) {
+          example = { ...example, description: { path: descriptionPath } }
+        }
+
         examples.push(example)
         // Generate diagnostics for this example
         diagnostics.push(...lintFileLayout(example, options.schemaCatalog))

package/src/api/examples/schemas/example/example.ts

@@ -26,6 +26,12 @@ export const Example = S.Struct({
    * The document content, which can be unversioned, versioned, or partially versioned.
    */
   document: Document.Document,
+
+  /**
+   * Optional description file for this example.
+   * Points to a markdown/MDX file that describes the example.
+   */
+  description: S.optional(S.Struct({ path: S.String })),
 }).annotations({
   identifier: 'Example',
   description: 'A GraphQL example that contains a document with optional versioning support',

package/src/api/reference/$.ts

@@ -0,0 +1,3 @@
+export * as Catalog from './catalog.js'
+export * as Config from './config.js'
+export * from './scanner.js'

package/src/api/reference/catalog.ts

@@ -0,0 +1,55 @@
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema and Type
+// ============================================================================
+
+export const Catalog = S.Struct({
+  /**
+   * Optional index file metadata for custom reference landing page.
+   * If not provided, the app will redirect to the Query type.
+   */
+  index: S.optional(S.Struct({
+    /**
+     * Path to the index.md or index.mdx file
+     */
+    path: S.String,
+  })),
+}).annotations({
+  identifier: 'ReferenceCatalog',
+  description: 'A catalog of reference documentation metadata',
+})
+
+export type Catalog = S.Schema.Type<typeof Catalog>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Catalog.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Catalog)
+
+// ============================================================================
+// State Predicates
+// ============================================================================
+
+/**
+ * Check if the catalog has a custom index page
+ */
+export const hasIndex = (catalog: Catalog): boolean => {
+  return catalog.index !== undefined
+}
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Catalog)
+export const decodeSync = S.decodeSync(Catalog)
+export const encode = S.encode(Catalog)
+export const encodeSync = S.encodeSync(Catalog)