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

package/src/lib/change/criticality.ts

@@ -0,0 +1,53 @@
+import { Level } from '#lib/change/level'
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const Criticality = S.Struct({
+  level: Level,
+  reason: S.optional(S.String),
+}).annotations({
+  identifier: 'Criticality',
+  title: 'Change Criticality',
+  description: 'The criticality assessment of a GraphQL schema change',
+})
+
+export type Level = typeof Level.Type
+export type Criticality = typeof Criticality.Type
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Criticality.make
+
+// ============================================================================
+// Guards
+// ============================================================================
+
+export const is = S.is(Criticality)
+
+// ============================================================================
+// State Predicates
+// ============================================================================
+
+export const isBreaking = (criticality: Criticality): boolean => criticality.level === 'BREAKING'
+
+export const isDangerous = (criticality: Criticality): boolean => criticality.level === 'DANGEROUS'
+
+export const isSafe = (criticality: Criticality): boolean => criticality.level === 'NON_BREAKING'
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decode = S.decode(Criticality)
+export const encode = S.encode(Criticality)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalence = S.equivalence(Criticality)

package/src/lib/change/level.ts

@@ -0,0 +1,3 @@
+import { S } from '#lib/kit-temp/effect'
+
+export const Level = S.Literal('BREAKING', 'DANGEROUS', 'NON_BREAKING')

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

@@ -0,0 +1 @@
+export * as DateOnly from './date-only.js'

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

@@ -0,0 +1,112 @@
+import { S } from '#lib/kit-temp/effect'
+import { Order } from 'effect'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const DateOnly = S.String.pipe(
+  S.pattern(/^\d{4}-\d{2}-\d{2}$/),
+  S.annotations({
+    identifier: 'DateOnly',
+    title: 'Date Only',
+    description: 'A date-only value in YYYY-MM-DD format',
+    examples: ['2024-01-15', '2023-12-31'],
+  }),
+  S.brand('DateOnly'),
+)
+
+// ============================================================================
+// Type
+// ============================================================================
+
+export type DateOnly = typeof DateOnly.Type
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = DateOnly.make
+
+// ============================================================================
+// Ordering
+// ============================================================================
+
+export const order: Order.Order<DateOnly> = Order.mapInput(Order.string, (date) => date)
+
+export const min = Order.min(order)
+
+export const max = Order.max(order)
+
+export const lessThan = Order.lessThan(order)
+
+export const greaterThan = Order.greaterThan(order)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalence = S.equivalence(DateOnly)
+
+// ============================================================================
+// Type Guard
+// ============================================================================
+
+export const is = S.is(DateOnly)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(DateOnly)
+
+export const decodeSync = S.decodeSync(DateOnly)
+
+export const encode = S.encode(DateOnly)
+
+// ============================================================================
+// Importers
+// ============================================================================
+
+export const fromDate = (date: Date): DateOnly => {
+  const dateString = date.toISOString().split('T')[0]!
+  return make(dateString)
+}
+
+// ============================================================================
+// Exporters
+// ============================================================================
+
+export const toDate = (date: DateOnly): Date => new Date(date + 'T00:00:00.000Z')
+
+// ============================================================================
+// Domain Logic
+// ============================================================================
+
+/**
+ * Get the year from a date
+ */
+export const getYear = (date: DateOnly): number => parseInt(date.substring(0, 4), 10)
+
+/**
+ * Get the month from a date (1-12)
+ */
+export const getMonth = (date: DateOnly): number => parseInt(date.substring(5, 7), 10)
+
+/**
+ * Get the day from a date (1-31)
+ */
+export const getDay = (date: DateOnly): number => parseInt(date.substring(8, 10), 10)
+
+/**
+ * Calculate the number of days between two dates
+ * @param from - The starting date
+ * @param to - The ending date
+ * @returns Number of days between the dates (positive if to > from, negative otherwise)
+ */
+export const getDaysBetween = (from: DateOnly, to: DateOnly): number => {
+  const fromDate = toDate(from)
+  const toDate_ = toDate(to)
+  const diffMs = toDate_.getTime() - fromDate.getTime()
+  return Math.floor(diffMs / (1000 * 60 * 60 * 24))
+}

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

package/src/lib/diagnostic/diagnostic.ts

@@ -0,0 +1,144 @@
+import { EffectKit, S } from '#lib/kit-temp/effect'
+import * as SeverityModule from './severity.js'
+
+// ============================================================================
+// Schema - Base Diagnostic
+// ============================================================================
+
+/**
+ * Base schema that all diagnostics must extend.
+ *
+ * This provides a three-level hierarchy for diagnostics:
+ * - Level 1: `_tag: 'Diagnostic'` - Identifies any diagnostic
+ * - Level 2: `source` - Which system generated the diagnostic
+ * - Level 3: `name` - The specific diagnostic type
+ *
+ * @example
+ * ```typescript
+ * const MyDiagnostic = S.extend(
+ *   DiagnosticBase,
+ *   S.Struct({
+ *     _tag: S.Literal('Diagnostic'),
+ *     source: S.Literal('my-feature'),
+ *     name: S.Literal('specific-error'),
+ *     // ... additional fields
+ *   })
+ * )
+ * ```
+ */
+export const Diagnostic = S.Struct({
+  /**
+   * Level 1: Identifies this as a diagnostic.
+   * All diagnostics must have this tag.
+   */
+  _tag: S.Literal('Diagnostic'),
+
+  /**
+   * Level 2: Source system/feature that generated this diagnostic.
+   * Examples: 'file-router', 'examples', 'schema-validator'
+   */
+  source: S.String,
+
+  /**
+   * Level 3: Specific diagnostic name within the source.
+   * Should be kebab-case and unique within the source.
+   * Examples: 'index-conflict', 'unused-default', 'missing-field'
+   */
+  name: S.String,
+
+  /**
+   * Severity level of the diagnostic.
+   */
+  severity: SeverityModule.Severity,
+
+  /**
+   * Human-readable message describing the issue.
+   */
+  message: S.String,
+}).annotations({
+  identifier: 'DiagnosticBase',
+  description: 'Base diagnostic structure with three-level hierarchy',
+})
+
+export type Diagnostic = typeof Diagnostic.Type
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Create a diagnostic schema that extends DiagnosticBase.
+ *
+ * This helper properly handles field narrowing (like severity)
+ * and ensures the diagnostic follows the three-level hierarchy.
+ *
+ * @example
+ * ```typescript
+ * const MyDiagnostic = Diagnostic.create({
+ *   source: 'my-feature',
+ *   name: 'specific-error',
+ *   severity: 'error',
+ *   context: {
+ *     customField: S.String,
+ *   }
+ * })
+ * ```
+ */
+export const create = <
+  source extends string,
+  name extends string,
+  severity extends SeverityModule.Severity | undefined = undefined,
+  context extends S.Struct.Fields = {},
+>(
+  params: {
+    source: source
+    name: name
+    severity?: severity
+    context?: context
+  },
+): S.TaggedStruct<
+  'Diagnostic',
+  & Omit<EffectKit.Schema.Struct.ExtractFields<typeof Diagnostic>, 'name' | 'source' | 'severity' | '_tag'>
+  & {
+    name: S.Literal<[name]>
+    source: S.Literal<[source]>
+    severity: severity extends string ? S.Literal<[severity]>
+      : EffectKit.Schema.Struct.ExtractFields<typeof Diagnostic>['severity']
+  }
+  & context
+> => {
+  // Use TaggedStruct instead of Struct, and omit _tag from fields since TaggedStruct adds it
+  const { _tag, ...diagnosticFieldsWithoutTag } = Diagnostic.fields
+  return S.TaggedStruct('Diagnostic', {
+    ...diagnosticFieldsWithoutTag,
+    source: S.Literal(params.source),
+    name: S.Literal(params.name),
+    ...(params.severity ? { severity: S.Literal(params.severity) } : {}),
+    ...params.context,
+  }) as any
+}
+
+export const createMake = <diagnostic extends S.TaggedStruct<any, any>>(
+  diagnostic: diagnostic,
+): EffectKit.Schema.ConstructorUsingOmitLiteral1Algo<diagnostic> => {
+  return ((fields: object) => {
+    return diagnostic.make({
+      ...EffectKit.Schema.pickLiteral1FieldsAsLiterals(diagnostic),
+      ...fields,
+    }) as any
+  }) as any
+}
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Diagnostic)
+export const decodeSync = S.decodeSync(Diagnostic)
+export const encode = S.encode(Diagnostic)
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Diagnostic)

package/src/lib/diagnostic/filter.ts

@@ -0,0 +1,21 @@
+import { applyControl, type Control } from './control.js'
+import type { Diagnostic } from './diagnostic.js'
+import { report } from './reporter.js'
+
+/**
+ * Filters diagnostics based on control settings and reports them.
+ *
+ * @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)
+ */
+export const filterAndReport = <T extends Diagnostic>(
+  diagnostics: T[],
+  getControl: (diagnostic: T) => Control | boolean | undefined,
+  phase: 'dev' | 'build' = 'dev',
+): void => {
+  const filteredDiagnostics = applyControl(diagnostics, getControl, phase)
+  if (filteredDiagnostics.length > 0) {
+    report(filteredDiagnostics)
+  }
+}