polen 0.11.0-next.14 → 0.11.0-next.16

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
+}

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,
+  }
+}

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

@@ -0,0 +1,196 @@
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema - Options
+// ============================================================================
+
+// ============================================================================
+// Schema - Type Breakdown
+// ============================================================================
+
+/**
+ * Breakdown of types by kind with percentages.
+ */
+export const TypeKindBreakdown = S.Struct({
+  objectTypes: S.Number,
+  objectTypesPercentage: S.Number,
+  interfaceTypes: S.Number,
+  interfaceTypesPercentage: S.Number,
+  unionTypes: S.Number,
+  unionTypesPercentage: S.Number,
+  enumTypes: S.Number,
+  enumTypesPercentage: S.Number,
+  scalarTypes: S.Number,
+  scalarTypesPercentage: S.Number,
+  inputTypes: S.Number,
+  inputTypesPercentage: S.Number,
+}).annotations({
+  identifier: 'TypeKindBreakdown',
+  description: 'Breakdown of types by kind with percentages',
+})
+
+export type TypeKindBreakdown = typeof TypeKindBreakdown.Type
+
+// ============================================================================
+// Schema - Description Coverage
+// ============================================================================
+
+/**
+ * Coverage statistics for descriptions.
+ */
+export const DescriptionCoverage = S.Struct({
+  /**
+   * Percentage of types with descriptions.
+   */
+  types: S.Number,
+  /**
+   * Percentage of fields with descriptions.
+   */
+  fields: S.Number,
+  /**
+   * Percentage of arguments with descriptions.
+   */
+  arguments: S.Number,
+  /**
+   * Overall description coverage percentage.
+   */
+  overall: S.Number,
+}).annotations({
+  identifier: 'DescriptionCoverage',
+  description: 'Coverage statistics for descriptions',
+})
+
+export type DescriptionCoverage = typeof DescriptionCoverage.Type
+
+// ============================================================================
+// Schema - Deprecation Metrics
+// ============================================================================
+
+/**
+ * Metrics about deprecated schema elements.
+ */
+export const DeprecationMetrics = S.Struct({
+  /**
+   * Total number of deprecated fields.
+   */
+  fields: S.Number,
+  /**
+   * Total number of deprecated enum values.
+   */
+  enumValues: S.Number,
+  /**
+   * Total number of deprecated arguments.
+   */
+  arguments: S.Number,
+  /**
+   * Percentage of schema surface area that is deprecated.
+   */
+  surfaceAreaPercentage: S.Number,
+}).annotations({
+  identifier: 'DeprecationMetrics',
+  description: 'Metrics about deprecated schema elements',
+})
+
+export type DeprecationMetrics = typeof DeprecationMetrics.Type
+
+// ============================================================================
+// Schema - Version Statistics
+// ============================================================================
+
+/**
+ * Statistics for a single schema version.
+ */
+export const VersionStatistics = S.Struct({
+  /**
+   * Version identifier.
+   */
+  version: S.String,
+  /**
+   * Date of this version/revision.
+   */
+  date: S.optional(S.String),
+  /**
+   * Total number of types (excluding introspection types).
+   */
+  totalTypes: S.Number,
+  /**
+   * Type breakdown by kind.
+   */
+  typeBreakdown: TypeKindBreakdown,
+  /**
+   * Number of queries.
+   */
+  queries: S.Number,
+  /**
+   * Number of mutations.
+   */
+  mutations: S.Number,
+  /**
+   * Number of subscriptions.
+   */
+  subscriptions: S.Number,
+  /**
+   * Description coverage metrics.
+   */
+  descriptionCoverage: DescriptionCoverage,
+  /**
+   * Deprecation metrics.
+   */
+  deprecation: DeprecationMetrics,
+  /**
+   * Total number of fields across all types.
+   */
+  totalFields: S.Number,
+  /**
+   * Total number of arguments across all fields.
+   */
+  totalArguments: S.Number,
+}).annotations({
+  identifier: 'VersionStatistics',
+  description: 'Statistics for a single schema version',
+})
+
+export type VersionStatistics = typeof VersionStatistics.Type
+
+// ============================================================================
+// Schema - Stability Metrics
+// ============================================================================
+
+/**
+ * Stability metrics calculated across schema history.
+ */
+export const StabilityMetrics = S.Struct({
+  /**
+   * Churn rate - percentage of schema that changes between versions.
+   */
+  churnRate: S.optional(S.Number),
+  /**
+   * Average duration in milliseconds between revisions.
+   */
+  averageRevisionInterval: S.optional(S.Number),
+  /**
+   * Average number of revisions per day.
+   */
+  averageRevisionsPerDay: S.optional(S.Number),
+  /**
+   * Total number of revisions.
+   */
+  totalRevisions: S.Number,
+  /**
+   * Date of first revision.
+   */
+  firstRevisionDate: S.optional(S.String),
+  /**
+   * Date of last revision.
+   */
+  lastRevisionDate: S.optional(S.String),
+  /**
+   * Stability rating: 'high', 'medium', 'low' based on churn rate.
+   */
+  rating: S.optional(S.Union(S.Literal('high'), S.Literal('medium'), S.Literal('low'))),
+}).annotations({
+  identifier: 'StabilityMetrics',
+  description: 'Stability metrics calculated across schema history',
+})
+
+export type StabilityMetrics = typeof StabilityMetrics.Type

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

@@ -0,0 +1,45 @@
+import { StabilityMetrics, VersionStatistics } from '#lib/catalog-statistics/data'
+import { S } from '#lib/kit-temp/effect'
+
+/**
+ * Complete statistics report for a GraphQL catalog.
+ */
+export const Report = S.Struct({
+  /**
+   * Global stability metrics across all versions.
+   */
+  stability: StabilityMetrics,
+  /**
+   * Statistics per version.
+   */
+  versions: S.Array(VersionStatistics),
+  /**
+   * Current/latest version statistics (convenience).
+   */
+  current: S.optional(VersionStatistics),
+}).annotations({
+  identifier: 'StatisticsReport',
+  description: 'Complete statistics report for a GraphQL catalog',
+})
+
+export type Report = typeof Report.Type
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Report.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Report)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Report)
+export const decodeSync = S.decodeSync(Report)
+export const encode = S.encode(Report)

package/src/lib/change/$$.ts

@@ -0,0 +1,3 @@
+export { calcChangeset } from './calc-changeset.js'
+export * from './change.js'
+export * as Criticality from './criticality.js'

package/src/lib/change/$.ts

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