polen 0.10.0-next.9 → 0.11.0-next.1

package/src/api/schema/read.ts

@@ -1,27 +1,68 @@
 import { Arr } from '@wollybeard/kit'
-import * as DataSources from './data-sources/data-sources.ts'
-import type { Schema } from './schema.ts'
+import * as DataSources from './data-sources/data-sources.js'
+import type { NonEmptyChangeSets } from './schema.js'
 
 export type DataSourceType = `file` | `directory` | `memory` | `data`
 
+/**
+ * Schema configuration for Polen.
+ */
 export interface Config {
   /**
+   * Whether to enable schema loading.
+   *
+   * Set to `false` to disable schema features entirely.
+   *
    * @default `true`
    */
   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
+   * - `memory` - Use schemas defined in configuration
+   * - `data` - Use a pre-built schema object
+   *
+   * If not specified, Polen will try all sources in order until one succeeds.
+   *
+   * @example
+   * ```ts
+   * // Use only file source
+   * useDataSources: 'file'
+   *
+   * // Try multiple sources
+   * useDataSources: ['directory', 'file']
+   * ```
+   */
   useDataSources?: Arr.Maybe<DataSourceType>
+  /**
+   * Configuration for each data source type.
+   */
   dataSources?: {
+    /**
+     * Configuration for loading schema from a single SDL file.
+     */
     file?: DataSources.SchemaFile.ConfigInput
+    /**
+     * Configuration for loading multiple schema versions from a directory.
+     */
     directory?: DataSources.SchemaDirectory.ConfigInput
+    /**
+     * Configuration for defining schemas programmatically.
+     */
     memory?: DataSources.Memory.ConfigInput
-    data?: Schema
+    /**
+     * Pre-built schema object to use directly.
+     */
+    data?: NonEmptyChangeSets
   }
   projectRoot: string
 }
 
 export const readOrThrow = async (
   config: Config,
-): Promise<null | Schema> => {
+): Promise<null | NonEmptyChangeSets> => {
   if (config.enabled === false) {
     return null
   }

package/src/api/schema/schema.ts

@@ -1,9 +1,69 @@
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 
-export * as DataSources from './data-sources/data-sources.ts'
+export * as DataSources from './data-sources/data-sources.js'
 
-export * from './read.ts'
+export * from './read.js'
 
-export interface Schema {
-  versions: [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]
+export * from './metadata.js'
+
+export type ChangeSets = GraphqlChangeset.ChangeSet[]
+
+export type NonEmptyChangeSets = [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]
+
+/**
+ * Changelog data structure for JSON serialization
+ */
+export interface ChangelogData {
+  changes: GraphqlChangeset.ChangeSet['changes']
+  date: string
+}
+
+/**
+ * Constants for schema versioning
+ */
+
+/**
+ * The version identifier for the latest schema
+ */
+export const VERSION_LATEST = `latest`
+
+/**
+ * Fallback version name when date parsing fails
+ */
+export const VERSION_UNKNOWN_FALLBACK = `unknown`
+
+/**
+ * Convert a date to a version string in YYYY-MM-DD format
+ */
+export const dateToVersionString = (date: Date): string => {
+  return date.toLocaleDateString('en-CA')
+}
+
+/**
+ * Determine if a version at the given index should have a changelog file.
+ * Only non-oldest versions get changelog files.
+ */
+export const shouldVersionHaveChangelog = (versionIndex: number, totalVersions: number): boolean => {
+  return versionIndex < totalVersions - 1
+}
+
+/**
+ * Convert a version string back to a Date
+ */
+export const versionStringToDate = (version: string): Date => {
+  if (version === VERSION_LATEST) {
+    return new Date()
+  }
+
+  // Use modern date parsing - the version string should be in YYYY-MM-DD format
+  // which is ISO 8601 compatible
+  const parsedDate = new Date(version + 'T00:00:00Z')
+
+  // Check if the date is valid
+  if (!isNaN(parsedDate.getTime())) {
+    return parsedDate
+  }
+
+  // Throw error for invalid dates instead of silently defaulting
+  throw new Error(`Invalid version string: ${version}`)
 }

package/src/api/schema-augmentation/augmentations/description.ts

@@ -1,7 +1,7 @@
 import type { GrafaidOld } from '#lib/grafaid-old/index'
 import { neverCase } from '@wollybeard/kit/language'
-import type { Target } from '../target.ts'
-import { locateTargetField, locateTargetType } from '../target.ts'
+import type { Target } from '../target.js'
+import { locateTargetField, locateTargetType } from '../target.js'
 
 export const Placement = {
   Before: `before`,

package/src/api/schema-augmentation/index.ts

@@ -1 +1 @@
-export * as SchemaAugmentation from './schema-augmentation.ts'
+export * as SchemaAugmentation from './schema-augmentation.js'

package/src/api/schema-augmentation/schema-augmentation.ts

@@ -1,6 +1,6 @@
 import type { GrafaidOld } from '#lib/grafaid-old/index'
 import { neverCase } from '@wollybeard/kit/language'
-import * as AugmentationDescription from './augmentations/description.ts'
+import * as AugmentationDescription from './augmentations/description.js'
 
 export { AugmentationDescription }
 
@@ -12,7 +12,6 @@ export const apply = (
 ): GrafaidOld.Schema.Schema => {
   for (const augmentation of augmentations) {
     switch (augmentation.type) {
-      // eslint-disable-next-line
       case `description`: {
         AugmentationDescription.apply(schema, augmentation)
         break

package/src/api/schema-source/index.ts

@@ -0,0 +1 @@
+export * from './schema-source.js'

package/src/api/schema-source/schema-source.ts

@@ -0,0 +1,189 @@
+import { Schema } from '#api/schema/index'
+import { Grafaid } from '#lib/grafaid/index'
+import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { astToSchema } from '#template/lib/schema-utils/schema-utils'
+import { Cache } from '@wollybeard/kit'
+import type { GraphQLSchema } from 'graphql'
+
+type WriteFile = (path: string, content: string) => Promise<void>
+
+type ReadFile = (locator: string) => Promise<string>
+
+type ClearDirectory = (path: string) => Promise<void>
+
+type RemoveFile = (path: string) => Promise<void>
+
+const NoImplementationWriteFile: WriteFile = async (path: string, content: string) => {
+  throw new Error('Write operations not supported in this environment')
+}
+
+const NoImplementationClearDirectory: ClearDirectory = async (path: string) => {
+  throw new Error('Directory operations not supported in this environment')
+}
+
+const NoImplementationRemoveFile: RemoveFile = async (path: string) => {
+  throw new Error('File removal operations not supported in this environment')
+}
+
+interface SchemaSourceConfig {
+  io: {
+    read: ReadFile
+    write?: WriteFile
+    clearDirectory?: ClearDirectory
+    removeFile?: RemoveFile
+  }
+  versions: string[]
+  assetsPath: string
+}
+
+export const createSchemaSource = (config: SchemaSourceConfig) => {
+  const getSchemaPath = (version: string) => `${config.assetsPath}/schemas/${version}.json`
+
+  const getChangelogPath = (version: string) => `${config.assetsPath}/schemas/${version}.changelog.json`
+
+  const getSchemasDirectory = () => `${config.assetsPath}/schemas`
+
+  const getMetadataPath = () => `${config.assetsPath}/schemas/metadata.json`
+
+  const ioWrite = config.io.write || NoImplementationWriteFile
+  const ioClearDirectory = config.io.clearDirectory || NoImplementationClearDirectory
+  const ioRemoveFile = config.io.removeFile || NoImplementationRemoveFile
+
+  // Memoize only the base IO read operation
+  const ioReadMemoized = Cache.memoize(config.io.read)
+
+  const get = async (version: string): Promise<GraphQLSchema> => {
+    const content = await ioReadMemoized(getSchemaPath(version))
+    const schemaAst = JSON.parse(content)
+    const schema = astToSchema(schemaAst)
+    return schema
+  }
+
+  const getChangelog = async (version: string): Promise<Schema.ChangelogData> => {
+    const content = await ioReadMemoized(getChangelogPath(version))
+    return JSON.parse(content)
+  }
+
+  const getAllChangesets = async (): Promise<GraphqlChangeset.ChangeSet[]> => {
+    const changesets: GraphqlChangeset.ChangeSet[] = []
+
+    for (let i = 0; i < config.versions.length; i++) {
+      const version = config.versions[i]
+      if (!version) continue
+
+      const schema = await get(version)
+      if (!schema) continue
+
+      // Only try to read changelog for non-oldest versions (matching writeDevAssets logic)
+      let changelogData = null
+      if (i < config.versions.length - 1) {
+        changelogData = await getChangelog(version)
+      }
+
+      if (changelogData) {
+        const prevVersion = config.versions[i + 1]
+        const prevSchema = prevVersion ? await get(prevVersion) : null
+
+        if (prevSchema) {
+          changesets.push({
+            after: schema,
+            before: prevSchema,
+            changes: changelogData.changes,
+            date: new Date(changelogData.date),
+          })
+        }
+      } else {
+        // Oldest version - no changelog, use existing utility
+        changesets.push({
+          after: schema,
+          before: Grafaid.Schema.empty,
+          changes: [],
+          date: Schema.versionStringToDate(version),
+        })
+      }
+    }
+
+    return changesets
+  }
+
+  return {
+    //
+    // Properties
+    //
+    versions: config.versions,
+    isEmpty: config.versions.length === 0,
+
+    //
+    // Methods
+    //
+    get,
+    getChangelog,
+    getAllChangesets,
+
+    // Expose the memoized reader's clear method
+    clearCache: ioReadMemoized.clear,
+
+    // Write operations (use the writer, which throws if not provided)
+    writeSchema: async (version: string, schema: GraphQLSchema) => {
+      const ast = Grafaid.Schema.AST.parse(Grafaid.Schema.print(schema))
+      await ioWrite(getSchemaPath(version), JSON.stringify(ast))
+    },
+
+    writeChangelog: async (version: string, changelog: Schema.ChangelogData) => {
+      await ioWrite(getChangelogPath(version), JSON.stringify(changelog))
+    },
+
+    // Directory operations
+    clearAllAssets: async () => {
+      await ioClearDirectory(getSchemasDirectory())
+    },
+
+    removeAsset: async (version: string) => {
+      try {
+        await ioRemoveFile(getSchemaPath(version))
+      } catch (error) {
+        // Swallow errors for file removal as requested
+      }
+
+      try {
+        await ioRemoveFile(getChangelogPath(version))
+      } catch (error) {
+        // Swallow errors for file removal as requested
+      }
+    },
+
+    writeMetadata: async (metadata: Schema.SchemaMetadata) => {
+      await ioWrite(getMetadataPath(), JSON.stringify(metadata, null, 2))
+    },
+
+    writeAllAssets: async (
+      schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>,
+      metadata: Schema.SchemaMetadata,
+    ) => {
+      if (!schemaData) return
+
+      // Write schema and changelog files
+      for (const [index, version] of schemaData.entries()) {
+        const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(version.date)
+
+        // Write schema file
+        await ioWrite(
+          getSchemaPath(versionName),
+          JSON.stringify(Grafaid.Schema.AST.parse(Grafaid.Schema.print(version.after))),
+        )
+
+        // Write changelog file (except for the oldest/last version)
+        if (Schema.shouldVersionHaveChangelog(index, schemaData.length)) {
+          const changelogData = {
+            changes: version.changes,
+            date: version.date.toISOString(),
+          }
+          await ioWrite(getChangelogPath(versionName), JSON.stringify(changelogData))
+        }
+      }
+
+      // Write metadata file
+      await ioWrite(getMetadataPath(), JSON.stringify(metadata, null, 2))
+    },
+  }
+}

package/src/api/server/report-error.ts

@@ -19,7 +19,7 @@ export const reportError = async (value: unknown): Promise<void> => {
   const snippets = createSnippets(parsedError)
 
   if (snippets) {
-    console.log('\n\n\n\n' + snippets)
+    console.log(`\n\n\n\n` + snippets)
   }
 }
 
@@ -27,15 +27,15 @@ const createSnippets = (parsedError: ParsedError) => {
   const snippets = parsedError.frames.map((frame) => {
     let snippet = createSnippet(frame)
 
-    snippet = frame.fileName + '\n' + frame.lineNumber + '\n\n' + snippet
+    snippet = frame.fileName + `\n` + frame.lineNumber + `\n\n` + snippet
     return snippet
-  }).join('\n\n----------------------------------------------------------------------------------\n\n')
+  }).join(`\n\n----------------------------------------------------------------------------------\n\n`)
   return snippets
 }
 
 const createSnippet = (stackFrame: StackFrame) => {
   const snippet = stackFrame.source?.map(line => {
-    return line.lineNumber.toString().padStart(4, ' ') + `: ` + line.chunk
+    return line.lineNumber.toString().padStart(4, ` `) + `: ` + line.chunk
   }).join(`\n`)
 
   return snippet
@@ -45,7 +45,9 @@ const createSnippet = (stackFrame: StackFrame) => {
 // pathFilter: Fn.compose(Str.isMatchWith(excludePattern), Bool.negate)
 const cleanStackRecursive = (value: unknown, excludePattern: RegExp) => {
   if (value instanceof AggregateError) {
-    value.errors.forEach((error) => cleanStackRecursive(error, excludePattern))
+    value.errors.forEach((error) => {
+      cleanStackRecursive(error, excludePattern)
+    })
   }
   // console.log(`Filtering path: ${path}`, isInclude ? 'Included' : 'Excluded')
   if (value instanceof Error) {

package/src/api/singletons/markdown/index.ts

@@ -1 +1 @@
-export * as Markdown from './markdown.ts'
+export * as Markdown from './markdown.js'

package/src/api/singletons/markdown/markdown.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, test } from 'vitest'
-import { parse } from './markdown.ts'
+import { parse } from './markdown.js'
 
-describe(`markdown parser with syntax highlighting`, () => {
-  test(`parse highlights code blocks`, async () => {
+describe('markdown parser', () => {
+  test('parse converts code blocks', async () => {
     const markdown = `
 # Hello
 
@@ -13,17 +13,14 @@ console.log(x)
 `
     const result = await parse(markdown)
 
-    expect(result).toContain(`<h1>Hello</h1>`)
-    expect(result).toContain(`<pre`)
-    expect(result).toContain(`shiki`)
-    expect(result).toContain(`console`)
-    expect(result).toContain(`42`)
+    expect(result).toContain('<h1>Hello</h1>')
+    expect(result).toContain('<pre')
+    expect(result).toContain('<code class="language-javascript">')
+    expect(result).toContain('console')
+    expect(result).toContain('42')
   })
 
-  // Note: parseSync cannot be used with async rehype plugins like Shiki
-  // This is a known limitation - syntax highlighting requires async processing
-
-  test(`parse supports GraphQL syntax`, async () => {
+  test('parse supports GraphQL syntax', async () => {
     const markdown = `
 \`\`\`graphql
 type Query {
@@ -33,21 +30,20 @@ type Query {
 `
     const result = await parse(markdown)
 
-    expect(result).toContain(`type`)
-    expect(result).toContain(`Query`)
-    // Check that both ID and ! are present (they may be in separate spans)
-    expect(result).toContain(`> ID<`)
-    expect(result).toContain(`>!</`)
+    expect(result).toContain('<code class="language-graphql">')
+    expect(result).toContain('type Query')
+    expect(result).toContain('ID!')
+    expect(result).toContain('User')
   })
 
-  test(`parse handles inline code`, async () => {
-    const markdown = `This is \`inline code\` in a sentence.`
+  test('parse handles inline code', async () => {
+    const markdown = 'This is `inline code` in a sentence.'
     const result = await parse(markdown)
 
-    expect(result).toContain(`<code>inline code</code>`)
+    expect(result).toContain('<code>inline code</code>')
   })
 
-  test(`parse supports GitHub Flavored Markdown`, async () => {
+  test('parse supports GitHub Flavored Markdown', async () => {
     const markdown = `
 | Column 1 | Column 2 |
 |----------|----------|
@@ -58,12 +54,12 @@ type Query {
 `
     const result = await parse(markdown)
 
-    expect(result).toContain(`<table>`)
-    expect(result).toContain(`<input`)
-    expect(result).toContain(`checked`)
+    expect(result).toContain('<table>')
+    expect(result).toContain('<input')
+    expect(result).toContain('checked')
   })
 
-  test(`parse handles code blocks without language`, async () => {
+  test('parse handles code blocks without language', async () => {
     const markdown = `
 \`\`\`
 plain text without language
@@ -71,11 +67,11 @@ plain text without language
 `
     const result = await parse(markdown)
 
-    expect(result).toContain(`<pre`)
-    expect(result).toContain(`plain text without language`)
+    expect(result).toContain('<pre')
+    expect(result).toContain('plain text without language')
   })
 
-  test(`parse preserves theme CSS variables`, async () => {
+  test('parse converts code blocks without syntax highlighting', async () => {
     const markdown = `
 \`\`\`javascript
 const theme = "light"
@@ -83,7 +79,8 @@ const theme = "light"
 `
     const result = await parse(markdown)
 
-    expect(result).toContain(`--shiki-light`)
-    expect(result).toContain(`--shiki-dark`)
+    expect(result).toContain('<pre>')
+    expect(result).toContain('<code class="language-javascript">')
+    expect(result).toContain('const theme = "light"')
   })
 })

package/src/api/singletons/markdown/markdown.ts

@@ -1,29 +1,11 @@
-import rehypeShiki from '@shikijs/rehype'
 import rehypeStringify from 'rehype-stringify'
 import remarkGfm from 'remark-gfm'
 import remarkParse from 'remark-parse'
 import remarkRehype from 'remark-rehype'
 import { unified } from 'unified'
 
-// Create a processor with Shiki for syntax highlighting (async only)
-const createProcessorWithShiki = () => {
-  return unified()
-    .use(remarkParse)
-    .use(remarkGfm)
-    .use(remarkRehype)
-    .use(rehypeShiki, {
-      themes: {
-        light: `github-light`,
-        dark: `tokyo-night`,
-      },
-      defaultColor: false,
-      cssVariablePrefix: `--shiki-`,
-    })
-    .use(rehypeStringify)
-}
-
-// Create a processor without syntax highlighting for sync processing
-const createProcessorSync = () => {
+// Create a processor without syntax highlighting
+const createProcessor = () => {
   return unified()
     .use(remarkParse)
     .use(remarkGfm)
@@ -32,12 +14,11 @@ const createProcessorSync = () => {
 }
 
 export const parse = async (content: string): Promise<string> => {
-  const result = await createProcessorWithShiki().process(content)
+  const result = await createProcessor().process(content)
   return String(result)
 }
 
 export const parseSync = (content: string): string => {
-  // Note: Syntax highlighting is not available in sync mode due to @shikijs/rehype being async-only
-  const result = createProcessorSync().processSync(content)
+  const result = createProcessor().processSync(content)
   return String(result)
 }

package/src/api/static/index.ts

@@ -1 +1 @@
-export * as Static from './static.ts'
+export * as Static from './static.js'

package/src/api/static/manifest.test.ts

@@ -1,6 +1,6 @@
 import { Err, Fs, Path } from '@wollybeard/kit'
 import { afterEach, beforeEach, describe, expect, test } from 'vitest'
-import { buildManifest, type PolenBuildManifest } from './manifest.ts'
+import { buildManifest, type PolenBuildManifest } from './manifest.js'
 
 describe('validate-build', () => {
   let testDir: string

package/src/api/static/manifest.ts

@@ -2,7 +2,7 @@ import { Codec, Resource } from '@wollybeard/kit'
 import { z } from 'zod/v4'
 
 export const PolenBuildManifestSchema = z.object({
-  type: z.enum(['ssg', 'ssr']),
+  type: z.enum([`ssg`, `ssr`]),
   version: z.string(),
   basePath: z.string(),
 }).loose()
@@ -10,7 +10,7 @@ export const PolenBuildManifestSchema = z.object({
 export type PolenBuildManifest = z.infer<typeof PolenBuildManifestSchema>
 
 export const buildManifest = Resource.create({
-  name: 'polen-build-manifest',
-  path: '.polen/build.json',
+  name: `polen-build-manifest`,
+  path: `.polen/build.json`,
   codec: Codec.fromZod(PolenBuildManifestSchema),
 })

package/src/api/static/rebase.test.ts

@@ -1,10 +1,10 @@
 import { Fs, Path } from '@wollybeard/kit'
 import { afterEach, beforeEach, describe, expect, test } from 'vitest'
-import { rebase, type RebasePlan } from './rebase.ts'
+import { rebase, type RebasePlan } from './rebase.js'
 
 const testDir = 'temp/rebase-test'
 
-const createTestBuild = async (dir: string, basePath: string = '/') => {
+const createTestBuild = async (dir: string, basePath = '/') => {
   await Fs.makeDirectory(dir)
 
   // Create Polen build manifest