polen 0.11.0-next.15 → 0.11.0-next.16

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

@@ -0,0 +1,77 @@
+import type { Api } from '#api/$'
+import { ExamplesConfig } from '#api/examples/config'
+import { ConfigSchema } from '#api/schema/config-schema'
+import type { Catalog } from '#lib/catalog/$'
+import { S } from '#lib/kit-temp/effect'
+import { Fn, Obj } from '@wollybeard/kit'
+import { Config } from '../config/normalized.js'
+
+export const resolve = (config: Config, data: {
+  examples?: Api.Examples.Catalog.Catalog | undefined
+  schemas?: Catalog.Catalog | undefined
+}): TemplateConfig => {
+  return {
+    ...Obj.omit(config, ['_input']),
+    schema: {
+      ...config.schema,
+      enabled: Boolean(config.schema.enabled ?? data.schemas),
+    },
+    examples: {
+      ...config.examples,
+      enabled: Boolean(config.examples.enabled ?? (data.examples && data.examples.examples.length > 0)),
+    },
+  }
+}
+
+// ============================================================================
+// Schema - Template Config
+// ============================================================================
+
+/**
+ * Template configuration with all feature flags resolved.
+ * This is the configuration that templates receive, where optional fields
+ * that control feature enablement have been resolved to concrete values.
+ */
+export const TemplateConfig = S.extend(
+  Config.pipe(S.omit('_input', 'schema', 'examples')),
+  S.Struct({
+    schema: S.extend(
+      ConfigSchema.pipe(S.omit('enabled')),
+      S.Struct({
+        enabled: S.Boolean,
+      }),
+    ),
+    examples: S.extend(
+      ExamplesConfig.pipe(S.omit('enabled')),
+      S.Struct({
+        enabled: S.Boolean,
+      }),
+    ),
+  }),
+).annotations({
+  identifier: 'TemplateConfig',
+  title: 'Template Configuration',
+  description: 'Fully resolved configuration for template consumption with all feature flags determined',
+})
+
+export type TemplateConfig = S.Schema.Type<typeof TemplateConfig>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const makeTemplateConfig = Fn.identity(TemplateConfig)
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const isTemplateConfig = S.is(TemplateConfig)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decodeTemplateConfig = S.decode(TemplateConfig)
+export const encodeTemplateConfig = S.encode(TemplateConfig)
+export const encodeSyncTemplateConfig = S.encodeSync(TemplateConfig)

package/src/api/content/$$.ts

@@ -1,3 +1,4 @@
+export * from './mdx-compiler.js'
 export * from './metadata.js'
 export * from './navbar.js'
 export * from './page.js'

package/src/api/content/mdx-compiler.ts

@@ -0,0 +1,74 @@
+import { compile } from '@mdx-js/mdx'
+import { recmaCodeHike, remarkCodeHike } from 'codehike/mdx'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkGfm from 'remark-gfm'
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Core MDX configuration used across Polen.
+ * This ensures consistent MDX processing for all content types.
+ */
+export const MDX_CONFIG = {
+  jsxImportSource: 'polen/react',
+  providerImportSource: 'polen/mdx',
+  codeHike: {
+    components: { code: 'CodeBlock' },
+    syntaxHighlighting: {
+      theme: 'github-light',
+    },
+  },
+} as const
+
+// ============================================================================
+// Plugin Configuration
+// ============================================================================
+
+/**
+ * Create standard remark and recma plugins configuration for MDX processing.
+ * This ensures consistent plugin usage across all MDX compilation.
+ */
+export const createMdxPlugins = () => ({
+  remarkPlugins: [
+    remarkFrontmatter,
+    remarkGfm,
+    [remarkCodeHike, MDX_CONFIG.codeHike] as any,
+  ],
+  recmaPlugins: [
+    [recmaCodeHike, MDX_CONFIG.codeHike] as any,
+  ],
+})
+
+// ============================================================================
+// Compilation Functions
+// ============================================================================
+
+/**
+ * Compile MDX content to function body format.
+ * Used for runtime compilation of MDX content (e.g., example index files).
+ *
+ * @param content - The MDX content to compile
+ * @returns Compiled MDX as a function body string
+ */
+export const compileMdxToFunctionBody = async (content: string) => {
+  return compile(content, {
+    ...MDX_CONFIG,
+    ...createMdxPlugins(),
+    outputFormat: 'function-body',
+    development: false,
+  })
+}
+
+/**
+ * Get configuration for @mdx-js/rollup plugin.
+ * Used for build-time compilation of MDX pages.
+ *
+ * @returns Configuration object for mdx rollup plugin
+ */
+export const getMdxRollupConfig = () => ({
+  ...MDX_CONFIG,
+  ...createMdxPlugins(),
+  rehypePlugins: [],
+})

package/src/api/content/navbar.test.ts

@@ -25,13 +25,13 @@ describe('createNavbar', () => {
   it('excludes hidden pages', () => {
     const pages = [createPage(['visible'], 'index', false), createPage(['hidden'], 'index', true)]
     const result = createNavbar(pages)
-    expect(result).toEqual([{ pathExp: '/visible', title: 'Visible', position: 'left' }])
+    expect(result).toEqual([{ pathExp: '/visible', title: 'Visible', position: 'right' }])
   })
 
   it('includes directories with index pages', () => {
     const pages = [createPage(['guide'], 'index'), createPage(['guide', 'intro'], 'intro')]
     const result = createNavbar(pages)
-    expect(result).toEqual([{ pathExp: '/guide', title: 'Guide', position: 'left' }])
+    expect(result).toEqual([{ pathExp: '/guide', title: 'Guide', position: 'right' }])
   })
 
   it('excludes directories without index pages', () => {
@@ -43,7 +43,7 @@ describe('createNavbar', () => {
   it('includes single top-level pages', () => {
     const pages = [createPage(['about'], 'about')]
     const result = createNavbar(pages)
-    expect(result).toEqual([{ pathExp: '/about', title: 'About', position: 'left' }])
+    expect(result).toEqual([{ pathExp: '/about', title: 'About', position: 'right' }])
   })
 
   it('sorts results alphabetically', () => {

package/src/api/content/navbar.ts

@@ -51,7 +51,7 @@ export const createNavbar = (pages: Page[]): NavbarItem[] => {
       navbarItems.push({
         pathExp,
         title,
-        position: 'left',
+        position: 'right',
       })
     }
   })

package/src/api/examples/$$.ts

@@ -0,0 +1,7 @@
+export * from './config.js'
+export * from './diagnostic/diagnostic.js'
+export * from './filter.js'
+export * from './scanner.js'
+export * as Catalog from './schemas/catalog.js'
+export { Example } from './schemas/example/$.js'
+export * from './type-generator.js'

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

@@ -0,0 +1,201 @@
+import { Catalog } from '#lib/catalog/$'
+import { Diagnostic } from '#lib/diagnostic/$'
+import { Document } from '#lib/document/$'
+import { Version } from '#lib/version/$'
+import { Effect, HashMap } from 'effect'
+import { buildSchema } from 'graphql'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { Examples } from './$.js'
+
+describe('Example', () => {
+  test.for([
+    {
+      name: 'validates unversioned example',
+      example: Examples.Example.Example.make({
+        name: 'list-users',
+        path: 'examples/list-users.graphql',
+        document: Document.Unversioned.make({
+          document: 'query ListUsers { users { id name } }',
+        }),
+      }),
+      expected: true,
+    },
+    {
+      name: 'validates versioned example',
+      example: Examples.Example.Example.make({
+        name: 'list-users',
+        path: 'examples',
+        document: Document.Versioned.make({
+          versionDocuments: HashMap.make(
+            [Version.fromString('v1'), 'query ListUsers { users { id name } }'],
+            [Version.fromString('v2'), 'query ListUsers { users { id email name } }'],
+          ),
+        }),
+      }),
+      expected: true,
+    },
+  ])('$name', ({ example, expected }) => {
+    expect(Examples.Example.is(example)).toBe(expected)
+  })
+})
+
+describe('ExampleScanner', () => {
+  const mockFs = {
+    readFileString: vi.fn(),
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test.skip.for([
+    {
+      name: 'scans unversioned example',
+      files: ['get-users.graphql'],
+      fileContents: { 'get-users.graphql': 'query GetUsers { users { id } }' },
+      expectedExamples: 1,
+      expectedDiagnostics: 0,
+    },
+    {
+      name: 'scans versioned examples',
+      files: ['users/v1.graphql', 'users/v2.graphql'],
+      fileContents: {
+        'users/v1.graphql': 'query V1 { users { id } }',
+        'users/v2.graphql': 'query V2 { users { id email } }',
+      },
+      expectedExamples: 1,
+      expectedDiagnostics: 0,
+    },
+    {
+      name: 'detects duplicate content',
+      files: ['users/v1.graphql', 'users/v2.graphql'],
+      fileContents: {
+        'users/v1.graphql': 'query Users { users { id } }',
+        'users/v2.graphql': 'query Users { users { id } }',
+      },
+      expectedExamples: 1,
+      expectedDiagnostics: 1,
+    },
+  ])('$name', async ({ files, fileContents, expectedExamples, expectedDiagnostics }) => {
+    mockFs.readFileString.mockImplementation((path: string) => {
+      const fileName = path.split('/').pop()!
+      const content = (fileContents as any)[files.find(f => f.endsWith(fileName!))!]
+      return Effect.succeed(content)
+    })
+
+    // Skip this test for now - needs proper FileSystem mock setup
+    // const result = await Effect.runPromise(
+    //   Examples.scan({
+    //     dir: '/examples',
+    //     schemaVersions: ['v1', 'v2'],
+    //     files,
+    //   }).pipe(Effect.provide({ FileSystem: mockFs } as any) as any),
+    // )
+
+    // expect((result as any).examples).toHaveLength(expectedExamples)
+    // expect((result as any).diagnostics).toHaveLength(expectedDiagnostics)
+  })
+})
+
+describe('ExampleValidator', () => {
+  const mockCatalog = Catalog.Unversioned.make({
+    schema: {
+      _tag: 'SchemaUnversioned' as const,
+      revisions: [],
+      definition: buildSchema('type Query { test: String }'),
+    },
+  })
+
+  test.for([
+    {
+      name: 'validates unversioned example',
+      examples: [
+        Examples.Example.Example.make({
+          name: 'test',
+          path: 'test.graphql',
+          document: Document.Unversioned.make({
+            document: 'query Test { test }',
+          }),
+        }),
+      ],
+      expectedErrors: 0,
+    },
+    {
+      name: 'validates versioned example',
+      examples: [
+        Examples.Example.Example.make({
+          name: 'test',
+          path: 'test',
+          document: Document.Versioned.make({
+            versionDocuments: HashMap.make(
+              [Version.fromString('v1'), 'query Test { test }'],
+              [Version.fromString('v2'), 'query Test { test { id } }'],
+            ),
+          }),
+        }),
+      ],
+      expectedErrors: 0,
+    },
+  ])('$name', ({ examples, expectedErrors }) => {
+    // Note: This would need a real GraphQL schema to test properly
+    // For now just ensure the function accepts the new Example types
+    const diagnostics = Examples.validateExamples(examples, mockCatalog)
+    expect(diagnostics).toBeDefined()
+  })
+})
+
+describe('filterExamplesBySelection', () => {
+  const examples = [
+    Examples.Example.Example.make({
+      name: 'a',
+      path: 'a.graphql',
+      document: Document.Unversioned.make({ document: 'a' }),
+    }),
+    Examples.Example.Example.make({
+      name: 'b',
+      path: 'b.graphql',
+      document: Document.Unversioned.make({ document: 'b' }),
+    }),
+    Examples.Example.Example.make({
+      name: 'c',
+      path: 'c.graphql',
+      document: Document.Unversioned.make({ document: 'c' }),
+    }),
+  ]
+
+  test.for([
+    { selection: undefined, expected: ['a', 'b', 'c'] },
+    { selection: 'all', expected: ['a', 'b', 'c'] },
+    { selection: 'none', expected: [] },
+    { selection: { include: ['a', 'b'] }, expected: ['a', 'b'] },
+  ])('selection $selection returns $expected', ({ selection, expected }) => {
+    const result = Examples.filterExamplesBySelection(examples, selection as any)
+    expect(result.map(e => e.name)).toEqual(expected)
+  })
+})
+
+describe('ExampleDiagnostics', () => {
+  const examples = [
+    Examples.Example.Example.make({
+      name: 'test',
+      path: 'test',
+      document: Document.Versioned.make({
+        versionDocuments: HashMap.make(
+          [Version.fromString('v1'), 'content'],
+        ),
+      }),
+    }),
+  ]
+
+  // Test diagnostic control
+
+  test('filters diagnostics based on control settings', () => {
+    const control = {
+      enabled: true,
+      dev: { severity: 'warning' as const },
+    }
+
+    const settings = Diagnostic.getEffetivePhaseSettings(control, 'dev', { enabled: true, severity: 'info' })
+    expect(settings.severity).toBe('warning')
+  })
+})

package/src/api/examples/$.ts

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

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

@@ -0,0 +1,92 @@
+import { S } from '#lib/kit-temp/effect'
+import { describe, expect, test } from 'vitest'
+import { ExamplesConfig } from './config.js'
+
+describe('ExamplesConfig', () => {
+  const decodeExamplesConfig = S.decodeSync(ExamplesConfig)
+
+  describe('ExampleSelection', () => {
+    test.for([
+      { input: 'all', expected: 'all' },
+      { input: 'none', expected: 'none' },
+      { input: { include: ['example1', 'example2'] }, expected: { include: ['example1', 'example2'] } },
+      { input: { exclude: ['example3'] }, expected: { exclude: ['example3'] } },
+    ])('accepts $input as display value', ({ input, expected }) => {
+      const result = decodeExamplesConfig({ display: input as any })
+      expect(result.display).toEqual(expected)
+    })
+
+    test('undefined display is omitted', () => {
+      const result = decodeExamplesConfig({})
+      expect('display' in result).toBe(false)
+    })
+  })
+
+  describe('ExamplesConfigSchema', () => {
+    test('decodes with defaults', () => {
+      const result = decodeExamplesConfig({})
+      expect(result).toEqual({})
+    })
+
+    test('decodes full config', () => {
+      const input = {
+        display: { include: ['example1', 'example2'] },
+        diagnostics: {
+          validation: true,
+          unusedVersions: false,
+        },
+      }
+
+      const result = decodeExamplesConfig(input as any)
+      expect(result).toEqual(input)
+    })
+
+    test.for([
+      {
+        name: 'include pattern',
+        config: { display: { include: ['get-user', 'create-post'] } },
+      },
+      {
+        name: 'exclude pattern',
+        config: { display: { exclude: ['advanced-filtering'] } },
+      },
+      {
+        name: 'all examples',
+        config: { display: 'all' },
+      },
+      {
+        name: 'no examples',
+        config: { display: 'none' },
+      },
+    ])('accepts $name', ({ config }) => {
+      const result = decodeExamplesConfig(config as any)
+      expect(result.display).toEqual(config.display)
+    })
+  })
+
+  describe('Type safety demonstration', () => {
+    test('example selection type safety', () => {
+      // This demonstrates the type-safe API
+      // In real usage, the types would be augmented by the generator
+
+      type TestExampleNames = 'get-user' | 'create-post' | 'update-user'
+
+      interface TestExampleSelection {
+        include?: TestExampleNames[]
+        exclude?: TestExampleNames[]
+      }
+
+      const validInclude: TestExampleSelection = {
+        include: ['get-user', 'create-post'],
+      }
+
+      const validExclude: TestExampleSelection = {
+        exclude: ['update-user'],
+      }
+
+      // Type assertions to ensure the structure is correct
+      expect(validInclude.include).toBeDefined()
+      expect(validExclude.exclude).toBeDefined()
+    })
+  })
+})