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

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

package/src/lib/diagnostic/control.ts

@@ -0,0 +1,140 @@
+import { S } from '#lib/kit-temp/effect'
+import type { Diagnostic } from './diagnostic.js'
+import { Severity } from './severity.js'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+/**
+ * Phase-specific control for diagnostics.
+ */
+const PhaseControl = S.Struct({
+  /**
+   * Whether diagnostics are enabled for this phase.
+   * If not specified, uses the global enabled setting.
+   */
+  enabled: S.optional(S.Boolean),
+  /**
+   * Override the default severity for this phase.
+   * If not specified, the diagnostic's default severity is used.
+   */
+  severity: S.optional(Severity),
+}).annotations({
+  identifier: 'DiagnosticPhaseControl',
+  description: 'Control diagnostic behavior for a specific phase',
+})
+
+/**
+ * Fine-grained control over diagnostic behavior.
+ * Can be used as a boolean for simple on/off, or as an object for detailed control.
+ */
+export const Control = S.Struct({
+  /**
+   * Master switch - if false, diagnostic is disabled in all phases.
+   */
+  enabled: S.Boolean,
+  /**
+   * Control behavior during development.
+   */
+  dev: S.optional(PhaseControl),
+  /**
+   * Control behavior during build.
+   */
+  build: S.optional(PhaseControl),
+}).annotations({
+  identifier: 'DiagnosticControl',
+  description: 'Fine-grained control over diagnostic behavior',
+})
+
+export type Control = typeof Control.Type
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Filters diagnostics based on control settings and adjusts their severity.
+ *
+ * @param diagnostics - Array of diagnostics to filter
+ * @param getControl - Function to get the control setting for a diagnostic
+ * @param phase - Current phase (dev or build)
+ * @returns Filtered diagnostics with adjusted severity
+ */
+export const applyControl = <T extends Diagnostic>(
+  diagnostics: T[],
+  getControl: (diagnostic: T) => Control | boolean | undefined,
+  phase: Phase = 'dev',
+): T[] => {
+  return diagnostics.filter(diagnostic => {
+    const control = getControl(diagnostic)
+
+    // Get effective settings for this phase
+    const settings = getEffetivePhaseSettings(
+      control,
+      phase,
+      { enabled: true, severity: diagnostic.severity },
+    )
+
+    if (!settings.enabled) {
+      return false // Filter out disabled diagnostics
+    } // Override severity based on control settings
+
+    ;(diagnostic as any).severity = settings.severity
+
+    return true
+  })
+}
+
+export type Phase = 'dev' | 'build'
+
+/**
+ * Get effective settings for a specific phase.
+ * Call sites provide their own defaults for each diagnostic type.
+ *
+ * @param control - The diagnostic control configuration (boolean, object, or undefined)
+ * @param phase - The current phase (dev or build)
+ * @param defaults - Default settings to use when not specified
+ * @returns Effective enabled state and severity for the phase
+ */
+export const getEffetivePhaseSettings = (
+  control: Control | boolean | undefined,
+  phase: Phase,
+  defaults: {
+    enabled: boolean
+    severity: Severity
+  },
+): { enabled: boolean; severity: Severity } => {
+  // Handle undefined - use defaults
+  if (control === undefined) {
+    return defaults
+  }
+
+  // Handle boolean shorthand
+  if (typeof control === 'boolean') {
+    return {
+      enabled: control,
+      severity: defaults.severity,
+    }
+  }
+
+  // Handle full DiagnosticControl
+  const phaseControl = control[phase]
+
+  // Determine enabled state
+  // Priority: phase.enabled > global.enabled > default.enabled
+  const enabled = phaseControl?.enabled ?? control.enabled
+
+  // If globally disabled and phase doesn't explicitly enable, stay disabled
+  if (!enabled) {
+    return {
+      enabled: false,
+      severity: phaseControl?.severity ?? defaults.severity,
+    }
+  }
+
+  return {
+    enabled,
+    severity: phaseControl?.severity ?? defaults.severity,
+  }
+}