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

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/change.ts

@@ -491,7 +491,7 @@ export const Change = S.Union(
   description: 'A change detected between two schemas',
 })
 
-export type Change = S.Schema.Type<typeof Change>
+export type Change = typeof Change.Type
 
 // ============================================================================
 // Constructors

package/src/lib/change/criticality.ts

@@ -14,8 +14,8 @@ export const Criticality = S.Struct({
   description: 'The criticality assessment of a GraphQL schema change',
 })
 
-export type Level = S.Schema.Type<typeof Level>
-export type Criticality = S.Schema.Type<typeof Criticality>
+export type Level = typeof Level.Type
+export type Criticality = typeof Criticality.Type
 
 // ============================================================================
 // Constructors

package/src/lib/date-only/date-only.ts

@@ -20,7 +20,7 @@ export const DateOnly = S.String.pipe(
 // Type
 // ============================================================================
 
-export type DateOnly = S.Schema.Type<typeof DateOnly>
+export type DateOnly = typeof DateOnly.Type
 
 // ============================================================================
 // Constructors

package/src/lib/diagnostic/$$.ts

@@ -0,0 +1,5 @@
+export * from './control.js'
+export * from './diagnostic.js'
+export * from './filter.js'
+export * from './reporter.js'
+export * as Severity from './severity.js'

package/src/lib/diagnostic/$.test.ts

@@ -0,0 +1,109 @@
+import { S } from '#lib/kit-temp/effect'
+import { Ts } from '@wollybeard/kit'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { Diagnostic } from './$.js'
+
+describe('DiagnosticBase', () => {
+  test('validates base structure', () => {
+    const valid = {
+      _tag: 'Diagnostic' as const,
+      source: 'test-source',
+      name: 'test-name',
+      severity: 'error' as const,
+      message: 'Test message',
+    }
+
+    expect(Diagnostic.is(valid)).toBe(true)
+  })
+
+  test.for([
+    { field: '_tag', value: 'NotDiagnostic' },
+    { field: 'source', value: 123 },
+    { field: 'name', value: null },
+    { field: 'severity', value: 'critical' },
+    { field: 'message', value: true },
+  ])('rejects invalid $field', ({ field, value }) => {
+    const invalid = {
+      _tag: 'Diagnostic' as const,
+      source: 'test-source',
+      name: 'test-name',
+      severity: 'error' as const,
+      message: 'Test message',
+      [field]: value,
+    }
+
+    expect(Diagnostic.is(invalid)).toBe(false)
+  })
+})
+
+describe('report', () => {
+  const spy = vi.spyOn(console, 'warn')
+
+  beforeEach(() => spy.mockClear())
+
+  test('handles empty array', () => {
+    Diagnostic.report([])
+    expect(spy).not.toHaveBeenCalled()
+  })
+
+  test.for([
+    {
+      name: 'groups by source',
+      diagnostics: [
+        { source: 'source-a', name: 'error-1', severity: 'error' as const, message: 'Error from A' },
+        { source: 'source-b', name: 'warning-1', severity: 'warning' as const, message: 'Warning from B' },
+        { source: 'source-a', name: 'error-2', severity: 'error' as const, message: 'Another error from A' },
+      ],
+      expectedInOutput: ['source-a', 'source-b', 'Error from A', 'Warning from B', 'Another error from A'],
+    },
+    {
+      name: 'uses severity icons',
+      diagnostics: [
+        { source: 'test', name: 'e', severity: 'error' as const, message: 'E' },
+        { source: 'test', name: 'w', severity: 'warning' as const, message: 'W' },
+        { source: 'test', name: 'i', severity: 'info' as const, message: 'I' },
+      ],
+      expectedInOutput: ['✗', '⚠', 'ⓘ'],
+    },
+  ])('$name', ({ diagnostics, expectedInOutput }) => {
+    const fullDiagnostics = diagnostics.map(d => ({ _tag: 'Diagnostic' as const, ...d }))
+    Diagnostic.report(fullDiagnostics)
+
+    expect(spy).toHaveBeenCalled()
+    const output = spy.mock.calls.map(call => call.join('')).join('')
+    expectedInOutput.forEach(expected => {
+      expect(output).toContain(expected)
+    })
+  })
+})
+
+describe('extending DiagnosticBase', () => {
+  test('can extend base schema with additional fields', () => {
+    // Example of how features would use the create helper
+    const CustomDiagnostic = Diagnostic.create({
+      source: 'custom-feature',
+      name: 'custom-error',
+      severity: 'error',
+      context: {
+        customField: S.String,
+        lineNumber: S.Number,
+      },
+    })
+    const makeCustomDiagnostic = Diagnostic.createMake(CustomDiagnostic)
+
+    type CustomDiagnostic = S.Schema.Type<typeof CustomDiagnostic>
+
+    const diagnostic = makeCustomDiagnostic({
+      message: 'Custom error occurred',
+      customField: 'extra data',
+      lineNumber: 42,
+    })
+
+    // Should be valid for both base and extended schemas
+    expect(Diagnostic.is(diagnostic)).toBe(true)
+    expect(S.is(CustomDiagnostic)(diagnostic)).toBe(true)
+
+    // Type assertion to ensure it's assignable to base
+    Ts.assertSub<Diagnostic.Diagnostic>()(diagnostic)
+  })
+})

package/src/lib/diagnostic/$.ts

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

package/src/lib/diagnostic/control.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'vitest'
+import { Control, getEffetivePhaseSettings } from './control.js'
+
+describe('getPhaseSettings', () => {
+  const defaults = { enabled: true, severity: 'warning' as const }
+
+  test.for([
+    { control: undefined, expected: defaults, name: 'undefined returns defaults' },
+    { control: true, expected: { enabled: true, severity: 'warning' }, name: 'true enables with default severity' },
+    { control: false, expected: { enabled: false, severity: 'warning' }, name: 'false disables' },
+  ])('$name', ({ control, expected }) => {
+    expect(getEffetivePhaseSettings(control, 'dev', defaults)).toEqual(expected)
+  })
+
+  test.for([
+    {
+      control: { enabled: false },
+      phase: 'dev' as const,
+      expected: { enabled: false, severity: 'warning' },
+      name: 'uses global enabled when phase not specified',
+    },
+    {
+      control: { enabled: false, dev: { enabled: true } },
+      phase: 'dev' as const,
+      expected: { enabled: true, severity: 'warning' },
+      name: 'phase settings override global enabled',
+    },
+    {
+      control: { enabled: true, dev: { severity: 'error' as const } },
+      phase: 'dev' as const,
+      expected: { enabled: true, severity: 'error' },
+      name: 'phase severity overrides default',
+    },
+    {
+      control: { enabled: true, dev: { enabled: false } },
+      phase: 'dev' as const,
+      expected: { enabled: false, severity: 'warning' },
+      name: 'phase enabled false overrides global true',
+    },
+    {
+      control: { enabled: true, dev: { enabled: false }, build: { enabled: true, severity: 'error' as const } },
+      phase: 'build' as const,
+      expected: { enabled: true, severity: 'error' },
+      name: 'build phase uses build settings',
+    },
+  ])('$name', ({ control, phase, expected }) => {
+    expect(getEffetivePhaseSettings(Control.make(control), phase, defaults)).toEqual(expected)
+  })
+
+  test('different phases can have different severities', () => {
+    const control = Control.make({
+      enabled: true,
+      dev: { severity: 'info' as const },
+      build: { severity: 'error' as const },
+    })
+    expect(getEffetivePhaseSettings(control, 'dev', defaults)).toEqual({ enabled: true, severity: 'info' })
+    expect(getEffetivePhaseSettings(control, 'build', defaults)).toEqual({ enabled: true, severity: 'error' })
+  })
+})
+
+describe('Control.make', () => {
+  test.for([
+    {
+      control: {
+        enabled: true,
+        dev: { enabled: false, severity: 'warning' as const },
+        build: { severity: 'error' as const },
+      },
+      name: 'accepts valid control',
+    },
+    { control: { enabled: false }, name: 'accepts minimal control' },
+  ])('$name', ({ control }) => {
+    expect(() => Control.make(control)).not.toThrow()
+  })
+})