polen 0.11.0-next.15 → 0.11.0-next.17

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

@@ -0,0 +1,161 @@
+import { Catalog } from '#lib/catalog/$'
+import { DateOnly } from '#lib/date-only/$'
+import { Version } from '#lib/version/$'
+import { HashMap } from 'effect'
+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: HashMap.make(
+            [
+              Version.fromInteger(1),
+              makeVersionedEntry(1, buildSchema('type Query { hello: String }'), ['2024-01-01', '2024-01-15']),
+            ],
+            [
+              Version.fromInteger(2),
+              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: HashMap.make(
+        [
+          Version.fromInteger(1),
+          makeVersionedEntry(1, buildSchema('type Query { test: String }'), ['2024-01-01', '2024-01-05']),
+        ],
+        [Version.fromInteger(2), 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 Catalog.Versioned.getAll(versioned)) {
+        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 (first in array since sorted newest first)
+  const current = versions[0]
+
+  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
+}

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

@@ -0,0 +1,226 @@
+import type { AnalyzeOptions } from '#lib/catalog-statistics/analyze-options'
+import type {
+  DeprecationMetrics,
+  DescriptionCoverage,
+  StabilityMetrics,
+  TypeKindBreakdown,
+  VersionStatistics,
+} from '#lib/catalog-statistics/data'
+import {
+  type GraphQLSchema,
+  isEnumType,
+  isInputObjectType,
+  isInterfaceType,
+  isObjectType,
+  isScalarType,
+  isUnionType,
+} from 'graphql'
+
+const BUILT_IN_SCALARS = new Set(['String', 'Int', 'Float', 'Boolean', 'ID'])
+
+/**
+ * Analyze a single GraphQL schema version.
+ */
+export const analyzeSchema = (
+  schema: GraphQLSchema,
+  version: string,
+  date?: string,
+  options: AnalyzeOptions = {},
+): VersionStatistics => {
+  const ignoreDeprecated = options.ignoreDeprecated ?? false
+  const typeMap = schema.getTypeMap()
+
+  // Initialize counters
+  let totalTypes = 0
+  let objectTypes = 0
+  let interfaceTypes = 0
+  let unionTypes = 0
+  let enumTypes = 0
+  let scalarTypes = 0
+  let inputTypes = 0
+  let totalFields = 0
+  let totalArguments = 0
+  let deprecatedFields = 0
+  let deprecatedEnumValues = 0
+  let deprecatedArguments = 0
+  let typesWithDescriptions = 0
+  let fieldsWithDescriptions = 0
+  let argumentsWithDescriptions = 0
+
+  // Analyze each type
+  for (const [typeName, type] of Object.entries(typeMap)) {
+    // Skip introspection types
+    if (typeName.startsWith('__')) continue
+
+    totalTypes++
+
+    // Check for description
+    if (type.description) {
+      typesWithDescriptions++
+    }
+
+    // Categorize by type kind using proper type guards
+    if (isObjectType(type)) {
+      objectTypes++
+
+      const fields = type.getFields()
+      for (const field of Object.values(fields)) {
+        if (ignoreDeprecated && field.deprecationReason) continue
+
+        totalFields++
+
+        if (field.description) {
+          fieldsWithDescriptions++
+        }
+
+        if (field.deprecationReason) {
+          deprecatedFields++
+        }
+
+        // Count arguments
+        if (field.args) {
+          for (const arg of field.args) {
+            if (ignoreDeprecated && arg.deprecationReason) continue
+
+            totalArguments++
+
+            if (arg.description) {
+              argumentsWithDescriptions++
+            }
+
+            if (arg.deprecationReason) {
+              deprecatedArguments++
+            }
+          }
+        }
+      }
+    } else if (isInterfaceType(type)) {
+      interfaceTypes++
+
+      const fields = type.getFields()
+      for (const field of Object.values(fields)) {
+        if (ignoreDeprecated && field.deprecationReason) continue
+
+        totalFields++
+
+        if (field.description) {
+          fieldsWithDescriptions++
+        }
+
+        if (field.deprecationReason) {
+          deprecatedFields++
+        }
+
+        // Count arguments
+        if (field.args) {
+          for (const arg of field.args) {
+            if (ignoreDeprecated && arg.deprecationReason) continue
+
+            totalArguments++
+
+            if (arg.description) {
+              argumentsWithDescriptions++
+            }
+
+            if (arg.deprecationReason) {
+              deprecatedArguments++
+            }
+          }
+        }
+      }
+    } else if (isUnionType(type)) {
+      unionTypes++
+    } else if (isEnumType(type)) {
+      enumTypes++
+
+      const values = type.getValues()
+      for (const value of values) {
+        if (ignoreDeprecated && value.deprecationReason) continue
+
+        if (value.deprecationReason) {
+          deprecatedEnumValues++
+        }
+      }
+    } else if (isScalarType(type)) {
+      // Only count custom scalars
+      if (!BUILT_IN_SCALARS.has(typeName)) {
+        scalarTypes++
+      } else {
+        // Built-in scalar, don't count in totalTypes
+        totalTypes--
+      }
+    } else if (isInputObjectType(type)) {
+      inputTypes++
+
+      const fields = type.getFields()
+      for (const field of Object.values(fields)) {
+        if (ignoreDeprecated && field.deprecationReason) continue
+
+        totalFields++
+
+        if (field.description) {
+          fieldsWithDescriptions++
+        }
+      }
+    }
+  }
+
+  // Calculate percentages for type breakdown
+  const typeBreakdown: TypeKindBreakdown = {
+    objectTypes,
+    objectTypesPercentage: totalTypes > 0 ? (objectTypes / totalTypes) * 100 : 0,
+    interfaceTypes,
+    interfaceTypesPercentage: totalTypes > 0 ? (interfaceTypes / totalTypes) * 100 : 0,
+    unionTypes,
+    unionTypesPercentage: totalTypes > 0 ? (unionTypes / totalTypes) * 100 : 0,
+    enumTypes,
+    enumTypesPercentage: totalTypes > 0 ? (enumTypes / totalTypes) * 100 : 0,
+    scalarTypes,
+    scalarTypesPercentage: totalTypes > 0 ? (scalarTypes / totalTypes) * 100 : 0,
+    inputTypes,
+    inputTypesPercentage: totalTypes > 0 ? (inputTypes / totalTypes) * 100 : 0,
+  }
+
+  // Calculate description coverage
+  const totalElements = totalTypes + totalFields + totalArguments
+  const elementsWithDescriptions = typesWithDescriptions + fieldsWithDescriptions + argumentsWithDescriptions
+  const descriptionCoverage: DescriptionCoverage = {
+    types: totalTypes > 0 ? (typesWithDescriptions / totalTypes) * 100 : 0,
+    fields: totalFields > 0 ? (fieldsWithDescriptions / totalFields) * 100 : 0,
+    arguments: totalArguments > 0 ? (argumentsWithDescriptions / totalArguments) * 100 : 0,
+    overall: totalElements > 0 ? (elementsWithDescriptions / totalElements) * 100 : 0,
+  }
+
+  // Calculate deprecation metrics
+  const totalDeprecatable = totalFields + totalArguments + deprecatedEnumValues
+  const totalDeprecated = deprecatedFields + deprecatedArguments + deprecatedEnumValues
+  const deprecation: DeprecationMetrics = {
+    fields: deprecatedFields,
+    enumValues: deprecatedEnumValues,
+    arguments: deprecatedArguments,
+    surfaceAreaPercentage: totalDeprecatable > 0 ? (totalDeprecated / totalDeprecatable) * 100 : 0,
+  }
+
+  // Get operation counts
+  const queryType = schema.getQueryType()
+  const mutationType = schema.getMutationType()
+  const subscriptionType = schema.getSubscriptionType()
+
+  const queries = queryType ? Object.keys(queryType.getFields()).length : 0
+  const mutations = mutationType ? Object.keys(mutationType.getFields()).length : 0
+  const subscriptions = subscriptionType ? Object.keys(subscriptionType.getFields()).length : 0
+
+  return {
+    version,
+    ...(date ? { date } : {}),
+    totalTypes,
+    typeBreakdown,
+    queries,
+    mutations,
+    subscriptions,
+    descriptionCoverage,
+    deprecation,
+    totalFields,
+    totalArguments,
+  }
+}