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

package/src/lib/ai-image-generation/service.ts

@@ -0,0 +1,185 @@
+/**
+ * AI Image Generation Service
+ * Manages Pollinations.ai image generation with caching
+ */
+
+import type { GraphQLSchema } from 'graphql'
+import * as FS from 'node:fs/promises'
+import * as Path from 'node:path'
+import {
+  type AiImageConfig,
+  analyzeSchema,
+  type ArtStyle,
+  buildPrompt,
+  type GeneratedImage,
+} from './ai-image-generation.js'
+import * as Pollinations from './providers/pollinations.js'
+
+export interface GenerateOptions {
+  config: AiImageConfig
+  schema?: GraphQLSchema | undefined
+  projectName?: string | undefined
+  cacheDir?: string | undefined
+  layout?: 'asymmetric' | 'cinematic' | 'auto' | undefined
+}
+
+/**
+ * Main service for generating AI hero images
+ */
+export class AiImageGenerationService {
+  private cacheDir: string
+
+  constructor(cacheDir: string = 'node_modules/.vite/polen-assets/ai-images') {
+    this.cacheDir = cacheDir
+  }
+
+  /**
+   * Generate a hero image based on configuration and schema
+   */
+  async generate(options: GenerateOptions): Promise<GeneratedImage | null> {
+    const { config, schema, projectName, layout } = options
+
+    if (!config.enabled) {
+      return null
+    }
+
+    const style = config.style || 'modern'
+    const width = config.width || 1200
+    const height = config.height || 400
+    const seed = config.seed
+    const nologo = config.nologo !== false
+    const shouldCache = config.cache !== false
+
+    // Build or use custom prompt
+    let prompt: string
+    if (config.prompt) {
+      prompt = config.prompt
+    } else if (schema) {
+      const context = analyzeSchema(schema)
+      if (projectName) {
+        context.name = projectName
+      }
+      prompt = buildPrompt(context, style as ArtStyle, config.prompt, layout)
+    } else {
+      // Fallback generic prompt
+      prompt = buildPrompt(
+        {
+          mainTypes: [],
+          queryNames: [],
+          mutationNames: [],
+          subscriptionNames: [],
+          suggestedTheme: 'modern API',
+        },
+        style as ArtStyle,
+        undefined,
+        layout,
+      )
+    }
+
+    // Skip cache for now to ensure fresh images
+    // TODO: Consider adding timestamp to cache key for time-based invalidation
+    // if (shouldCache) {
+    //   const cached = await this.getCachedImage(prompt)
+    //   if (cached) {
+    //     return cached
+    //   }
+    // }
+
+    // Generate image using Pollinations
+    // Use provided seed or generate random one for unique images
+    const finalSeed = seed || Math.floor(Math.random() * 1000000)
+    const result = await Pollinations.generateImage({
+      prompt,
+      width,
+      height,
+      seed: finalSeed,
+      nologo,
+    })
+
+    // Skip caching for now to ensure fresh images
+    // TODO: Consider adding timestamp to cache key
+    // if (shouldCache) {
+    //   await this.cacheImage(result)
+    // }
+
+    return result
+  }
+
+  /**
+   * Get a cached image if it exists
+   */
+  private async getCachedImage(
+    prompt: string,
+  ): Promise<GeneratedImage | null> {
+    try {
+      const cacheKey = this.getCacheKey(prompt)
+      const cachePath = Path.join(this.cacheDir, `${cacheKey}.json`)
+
+      const exists = await FS.access(cachePath).then(() => true).catch(() => false)
+      if (!exists) {
+        return null
+      }
+
+      const data = await FS.readFile(cachePath, 'utf-8')
+      const cached = JSON.parse(data) as GeneratedImage
+
+      // Return with cached flag set to true
+      return {
+        ...cached,
+        cached: true,
+      }
+    } catch (error) {
+      console.warn('Failed to read cached image:', error)
+      return null
+    }
+  }
+
+  /**
+   * Cache an image result
+   */
+  private async cacheImage(image: GeneratedImage): Promise<void> {
+    try {
+      const cacheKey = this.getCacheKey(image.prompt)
+      const cachePath = Path.join(this.cacheDir, `${cacheKey}.json`)
+
+      // Ensure cache directory exists
+      await FS.mkdir(this.cacheDir, { recursive: true })
+
+      // Write cache file
+      await FS.writeFile(cachePath, JSON.stringify(image, null, 2))
+    } catch (error) {
+      console.warn('Failed to cache image:', error)
+    }
+  }
+
+  /**
+   * Generate a cache key from prompt
+   */
+  private getCacheKey(prompt: string): string {
+    // Create a simple hash from the prompt
+    const hash = prompt
+      .split('')
+      .reduce((acc, char) => {
+        const charCode = char.charCodeAt(0)
+        return ((acc << 5) - acc) + charCode
+      }, 0)
+      .toString(36)
+      .replace('-', 'n') // Replace negative sign
+
+    return `hero-pollinations-${hash}`
+  }
+
+  /**
+   * Clear the cache
+   */
+  async clearCache(): Promise<void> {
+    try {
+      await FS.rm(this.cacheDir, { recursive: true, force: true })
+    } catch (error) {
+      console.warn('Failed to clear cache:', error)
+    }
+  }
+}
+
+// Default service instance
+export const defaultService = new AiImageGenerationService()

package/src/lib/catalog/catalog.ts

@@ -1,6 +1,7 @@
 import { S } from '#lib/kit-temp/effect'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
+import { Match } from 'effect'
 import * as Unversioned from './unversioned.js'
 import * as Versioned from './versioned.js'
 
@@ -17,7 +18,7 @@ export const Catalog = S.Union(Versioned.Versioned, Unversioned.Unversioned).ann
   description: 'A catalog of GraphQL schemas and their revision history',
 })
 
-export type Catalog = S.Schema.Type<typeof Catalog>
+export type Catalog = typeof Catalog.Type
 
 // ============================================================================
 // Type Guard
@@ -40,7 +41,9 @@ export const fold = <$A>(
 // ============================================================================
 
 export const decode = S.decode(Catalog)
+export const decodeSync = S.decodeSync(Catalog)
 export const encode = S.encode(Catalog)
+export const encodeSync = S.encodeSync(Catalog)
 
 // ============================================================================
 // Equivalence
@@ -69,5 +72,35 @@ export const getVersionCount = (catalog: Catalog): number =>
  */
 export const getSchemaVersionString = (schema: Schema.Schema): string => {
   const version = Schema.getVersion(schema)
-  return version ? Version.toString(version) : '__UNVERSIONED__'
+  return version ? Version.encodeSync(version) : '__UNVERSIONED__'
+}
+
+/**
+ * Get the version string from a schema.
+ * Returns the stringified version for versioned schemas, or '__UNVERSIONED__' for unversioned schemas.
+ */
+export const getLatestSchema = (catalog: Catalog): Schema.Schema =>
+  Match.value(catalog).pipe(Match.tagsExhaustive({
+    CatalogVersioned: (versioned) => {
+      // Entries are sorted newest first, so get the first entry
+      const latestEntry = versioned.entries[0]!
+      return latestEntry
+    },
+    CatalogUnversioned: (unversioned) => {
+      return unversioned.schema
+    },
+  }))
+
+/**
+ * Get the latest version identifier from a catalog.
+ * Returns the version for versioned catalogs, or null for unversioned catalogs.
+ */
+export const getLatestVersionIdentifier = (catalog?: Catalog): Version.Version | null => {
+  if (!catalog) return null
+  return Match.value(catalog).pipe(
+    Match.tagsExhaustive({
+      CatalogUnversioned: () => null,
+      CatalogVersioned: (cat) => cat.entries[0]?.version ?? null,
+    }),
+  )
 }

package/src/lib/catalog/unversioned.ts

@@ -14,7 +14,7 @@ export const Unversioned = S.TaggedStruct('CatalogUnversioned', {
   adt: { name: 'Catalog' },
 })
 
-export type Unversioned = S.Schema.Type<typeof Unversioned>
+export type Unversioned = typeof Unversioned.Type
 
 // ============================================================================
 // Constructors

package/src/lib/catalog/versioned.ts

@@ -14,7 +14,7 @@ export const Versioned = S.TaggedStruct('CatalogVersioned', {
   adt: { name: 'Catalog' },
 })
 
-export type Versioned = S.Schema.Type<typeof Versioned>
+export type Versioned = typeof Versioned.Type
 
 // ============================================================================
 // Constructors
@@ -40,3 +40,23 @@ export const encode = S.encode(Versioned)
 // ============================================================================
 
 export const equivalence = S.equivalence(Versioned)
+
+// ============================================================================
+// Domain Logic
+// ============================================================================
+
+/**
+ * Get the latest schema definition from a versioned catalog.
+ * The latest version is the first entry in the catalog (entries are ordered newest to oldest).
+ *
+ * @param catalog - The versioned catalog
+ * @returns The GraphQL schema definition of the latest version
+ * @throws {Error} If the catalog has no entries
+ */
+export const getLatest = (catalog: Versioned): Schema.Schema => {
+  const latestEntry = catalog.entries[0]
+  if (!latestEntry) {
+    throw new Error('Versioned catalog has no entries - cannot get latest schema')
+  }
+  return latestEntry
+}

package/src/lib/catalog-statistics/$$.ts

@@ -0,0 +1,4 @@
+export * from './analyze-catalog.js'
+export * from './analyze-options.js'
+export * from './analyze-schema.js'
+export * from './data.js'

package/src/lib/catalog-statistics/$.test.ts

@@ -0,0 +1,151 @@
+import { Catalog } from '#lib/catalog/$'
+import { DateOnly } from '#lib/date-only/$'
+import { Version } from '#lib/version/$'
+import { buildSchema, type GraphQLSchema } from 'graphql'
+import { describe, expect, test } from 'vitest'
+import { CatalogStatistics } from './$.js'
+
+describe('analyzeSchema', () => {
+  const testSchema = buildSchema(`
+    type Query {
+      """Get a user by ID"""
+      user(id: ID!): User
+      posts: [Post!]!
+    }
+
+    type User {
+      id: ID!
+      """The user's display name"""
+      name: String!
+      email: String @deprecated(reason: "Use emailAddress instead")
+      emailAddress: String
+    }
+
+    type Post {
+      id: ID!
+      title: String!
+      content: String
+      author: User!
+    }
+
+    enum Status {
+      DRAFT
+      PUBLISHED @deprecated(reason: "Use LIVE instead")
+      LIVE
+    }
+
+    scalar DateTime
+  `)
+
+  test('calculates basic statistics', () => {
+    const stats = CatalogStatistics.analyzeSchema(testSchema, '1.0.0', '2024-01-15')
+
+    expect(stats).toMatchObject({
+      version: '1.0.0',
+      date: '2024-01-15',
+      totalTypes: 5, // Query, User, Post, Status, DateTime
+      queries: 2,
+      mutations: 0,
+      subscriptions: 0,
+      typeBreakdown: {
+        objectTypes: 3, // Query, User, Post
+        enumTypes: 1, // Status
+        scalarTypes: 1, // DateTime only (built-ins excluded)
+      },
+      deprecation: {
+        fields: 1, // User.email
+        enumValues: 1, // Status.PUBLISHED
+      },
+    })
+    expect(stats.descriptionCoverage.fields).toBeGreaterThan(0)
+    expect(stats.descriptionCoverage.arguments).toBe(0)
+  })
+
+  test.for([
+    { ignoreDeprecated: false, expectedFields: 2 },
+    { ignoreDeprecated: true, expectedFields: 1 },
+  ])('ignoreDeprecated=$ignoreDeprecated yields $expectedFields fields', ({ ignoreDeprecated, expectedFields }) => {
+    const schema = buildSchema(`
+      type Query {
+        current: String
+        old: String @deprecated
+      }
+    `)
+
+    const stats = CatalogStatistics.analyzeSchema(schema, '1.0.0', undefined, { ignoreDeprecated })
+    expect(stats.totalFields).toBe(expectedFields)
+  })
+})
+
+describe('analyzeCatalog', () => {
+  const makeVersionedEntry = (version: number, schema: GraphQLSchema, dates: string[]) => ({
+    _tag: 'SchemaVersioned' as const,
+    version: Version.fromInteger(version),
+    branchPoint: null,
+    revisions: dates.map(date => ({ _tag: 'Revision' as const, date: DateOnly.make(date), changes: [] })),
+    definition: schema,
+  })
+
+  test.for([
+    {
+      name: 'versioned catalog',
+      catalog: () =>
+        Catalog.Versioned.make({
+          entries: [
+            makeVersionedEntry(1, buildSchema('type Query { hello: String }'), ['2024-01-01', '2024-01-15']),
+            makeVersionedEntry(
+              2,
+              buildSchema('type Query { hello: String, world: String } type User { id: ID!, name: String }'),
+              ['2024-02-01'],
+            ),
+          ],
+        }),
+      expectedVersions: 2,
+      expectedCurrentVersion: '2',
+    },
+    {
+      name: 'unversioned catalog',
+      catalog: () =>
+        Catalog.Unversioned.make({
+          schema: {
+            _tag: 'SchemaUnversioned',
+            revisions: ['2024-01-01', '2024-01-15', '2024-02-01'].map(date => ({
+              _tag: 'Revision' as const,
+              date: DateOnly.make(date),
+              changes: [],
+            })),
+            definition: buildSchema('type Query { test: String }'),
+          },
+        }),
+      expectedVersions: 1,
+      expectedCurrentVersion: '2024-02-01',
+    },
+  ])('processes $name', ({ catalog, expectedVersions, expectedCurrentVersion }) => {
+    const report = CatalogStatistics.analyzeCatalog(catalog())
+
+    expect(report.versions).toHaveLength(expectedVersions)
+    expect(report.current?.version).toBe(expectedCurrentVersion)
+    expect(report.stability.totalRevisions).toBe(expectedVersions)
+    expect(report.stability.firstRevisionDate).toBeDefined()
+    expect(report.stability.lastRevisionDate).toBeDefined()
+  })
+
+  test('calculates stability metrics', () => {
+    const catalog = Catalog.Versioned.make({
+      entries: [
+        makeVersionedEntry(1, buildSchema('type Query { test: String }'), ['2024-01-01', '2024-01-05']),
+        makeVersionedEntry(2, buildSchema('type Query { test: String }'), ['2024-01-10']),
+      ],
+    })
+
+    const report = CatalogStatistics.analyzeCatalog(catalog)
+
+    expect(report.stability).toMatchObject({
+      totalRevisions: 2,
+      averageRevisionInterval: expect.any(Number),
+      averageRevisionsPerDay: expect.any(Number),
+      churnRate: expect.any(Number),
+      rating: expect.stringMatching(/^(high|medium|low)$/),
+    })
+  })
+})

package/src/lib/catalog-statistics/$.ts

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

package/src/lib/catalog-statistics/analyze-catalog.ts

@@ -0,0 +1,158 @@
+import { Catalog } from '#lib/catalog/$'
+import { Version } from '#lib/version/$'
+import type { AnalyzeOptions } from './analyze-options.js'
+import { analyzeSchema } from './analyze-schema.js'
+import type { StabilityMetrics, VersionStatistics } from './data.js'
+import type { Report } from './report.js'
+
+/**
+ * Analyze a GraphQL catalog and generate comprehensive statistics.
+ */
+export const analyzeCatalog = (catalog: Catalog.Catalog, options: AnalyzeOptions = {}): Report => {
+  const versions: VersionStatistics[] = []
+  const revisionDates: string[] = []
+
+  // Process based on catalog type
+  const processResult = Catalog.fold(
+    // Versioned catalog
+    (versioned) => {
+      for (const entry of versioned.entries) {
+        const versionId = Version.encodeSync(entry.version)
+        // Analyze the schema definition for this version
+        // Use the first revision date if available
+        const firstRevisionDate = entry.revisions[0]?.date
+        const stats = analyzeSchema(entry.definition, versionId, firstRevisionDate, options)
+        versions.push(stats)
+
+        // Collect all revision dates for this version
+        for (const revision of entry.revisions) {
+          revisionDates.push(revision.date)
+        }
+      }
+    },
+    // Unversioned catalog
+    (unversioned) => {
+      // For unversioned, we analyze the single schema definition
+      // Using the latest revision date as the version identifier
+      if (unversioned.schema.revisions && unversioned.schema.revisions.length > 0) {
+        const latestRevisionDate = unversioned.schema.revisions[unversioned.schema.revisions.length - 1]!.date
+        const stats = analyzeSchema(unversioned.schema.definition, latestRevisionDate, latestRevisionDate, options)
+        versions.push(stats)
+
+        // Collect all revision dates
+        for (const revision of unversioned.schema.revisions) {
+          revisionDates.push(revision.date)
+        }
+      } else {
+        // Single schema without revisions
+        versions.push(analyzeSchema(unversioned.schema.definition, 'current', undefined, options))
+      }
+    },
+  )
+
+  processResult(catalog)
+
+  // Calculate stability metrics
+  const stability = calculateStabilityMetrics(versions, revisionDates)
+
+  // Get current version (last in array)
+  const current = versions[versions.length - 1]
+
+  return {
+    stability,
+    versions,
+    ...(current ? { current } : {}),
+  }
+}
+
+/**
+ * Calculate stability metrics from revision history.
+ */
+const calculateStabilityMetrics = (
+  versions: VersionStatistics[],
+  revisionDates?: string[],
+): StabilityMetrics => {
+  const totalRevisions = versions.length
+
+  if (totalRevisions === 0) {
+    return { totalRevisions: 0 }
+  }
+
+  // Parse dates if available
+  const dates = revisionDates?.map(d => new Date(d).getTime()).filter(d => !isNaN(d)) ?? []
+
+  // Build metrics object with all properties at once
+  let firstRevisionDate: string | undefined
+  let lastRevisionDate: string | undefined
+  let averageRevisionInterval: number | undefined
+  let averageRevisionsPerDay: number | undefined
+  let churnRate: number | undefined
+  let rating: 'high' | 'medium' | 'low' | undefined
+
+  if (dates.length >= 2) {
+    // Sort dates
+    dates.sort((a, b) => a - b)
+
+    const firstDate = dates[0]!
+    const lastDate = dates[dates.length - 1]!
+    const totalDuration = lastDate - firstDate
+
+    firstRevisionDate = new Date(firstDate).toISOString()
+    lastRevisionDate = new Date(lastDate).toISOString()
+
+    // Calculate average interval between revisions
+    if (dates.length > 1) {
+      let totalIntervals = 0
+      for (let i = 1; i < dates.length; i++) {
+        totalIntervals += dates[i]! - dates[i - 1]!
+      }
+      averageRevisionInterval = totalIntervals / (dates.length - 1)
+    }
+
+    // Calculate average revisions per day
+    if (totalDuration > 0) {
+      const daysElapsed = totalDuration / (1000 * 60 * 60 * 24)
+      averageRevisionsPerDay = totalRevisions / daysElapsed
+    }
+  }
+
+  // Calculate churn rate (simplified - comparing consecutive versions)
+  if (versions.length >= 2) {
+    let totalChanges = 0
+    for (let i = 1; i < versions.length; i++) {
+      const prev = versions[i - 1]!
+      const curr = versions[i]!
+
+      // Simple change detection based on counts
+      const typeChanges = Math.abs(curr.totalTypes - prev.totalTypes)
+      const fieldChanges = Math.abs(curr.totalFields - prev.totalFields)
+      const argChanges = Math.abs(curr.totalArguments - prev.totalArguments)
+
+      totalChanges += typeChanges + fieldChanges + argChanges
+    }
+
+    // Average changes per version as percentage of schema size
+    const avgSchemaSize = versions.reduce((sum, v) => sum + v.totalTypes + v.totalFields + v.totalArguments, 0)
+      / versions.length
+    churnRate = avgSchemaSize > 0 ? (totalChanges / (versions.length - 1)) / avgSchemaSize * 100 : 0
+
+    // Determine stability rating based on churn rate
+    if (churnRate < 5) {
+      rating = 'high'
+    } else if (churnRate < 15) {
+      rating = 'medium'
+    } else {
+      rating = 'low'
+    }
+  }
+
+  return {
+    totalRevisions,
+    ...(firstRevisionDate ? { firstRevisionDate } : {}),
+    ...(lastRevisionDate ? { lastRevisionDate } : {}),
+    ...(averageRevisionInterval !== undefined ? { averageRevisionInterval } : {}),
+    ...(averageRevisionsPerDay !== undefined ? { averageRevisionsPerDay } : {}),
+    ...(churnRate !== undefined ? { churnRate } : {}),
+    ...(rating ? { rating } : {}),
+  }
+}

package/src/lib/catalog-statistics/analyze-options.ts

@@ -0,0 +1,15 @@
+/**
+ * Options for analyzing GraphQL schemas.
+ */
+export interface AnalyzeOptions {
+  /**
+   * Whether to ignore deprecated fields/types in statistics.
+   * @default false
+   */
+  ignoreDeprecated?: boolean
+  /**
+   * Whether to include detailed type breakdown.
+   * @default false
+   */
+  includeTypeBreakdown?: boolean
+}