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

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

package/src/lib/diagnostic/reporter.ts

@@ -0,0 +1,74 @@
+import { Group } from '@wollybeard/kit'
+import type { Diagnostic } from './diagnostic.js'
+import { Severity } from './severity.js'
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const getIcon = (severity: Diagnostic['severity']): string => {
+  switch (severity) {
+    case Severity.enums.error:
+      return '✗'
+    case Severity.enums.warning:
+      return '⚠'
+    case Severity.enums.info:
+      return 'ⓘ'
+  }
+}
+
+const formatSummary = (diagnostics: Diagnostic[]): string => {
+  const errors = diagnostics.filter(d => d.severity === Severity.enums.error)
+  const warnings = diagnostics.filter(d => d.severity === Severity.enums.warning)
+  const infos = diagnostics.filter(d => d.severity === Severity.enums.info)
+
+  const parts = [
+    errors.length > 0 && `${errors.length} error${errors.length === 1 ? '' : 's'}`,
+    warnings.length > 0 && `${warnings.length} warning${warnings.length === 1 ? '' : 's'}`,
+    infos.length > 0 && `${infos.length} info${infos.length === 1 ? '' : 's'}`,
+  ].filter(Boolean)
+
+  return parts.join(', ')
+}
+
+// ============================================================================
+// Reporter
+// ============================================================================
+
+/**
+ * Reports diagnostics to the console, grouped by source.
+ *
+ * This is a generic reporter that works with any diagnostic
+ * that extends DiagnosticBase. It groups diagnostics by their
+ * source field and displays them with appropriate icons and
+ * formatting.
+ *
+ * @param diagnostics - Array of diagnostics to report
+ *
+ * @example
+ * ```typescript
+ * const diagnostics = [
+ *   { type: 'missing-file', severity: 'error', message: 'File not found', source: 'file-router' },
+ *   { type: 'unused-default', severity: 'warning', message: 'Default never used', source: 'examples' }
+ * ]
+ * report(diagnostics)
+ * ```
+ */
+export const report = (diagnostics: Diagnostic[]): void => {
+  if (diagnostics.length === 0) return
+
+  // Group diagnostics by source using kit's Group.by
+  const bySource = Group.by(diagnostics, 'source')
+
+  // Report each source's diagnostics
+  for (const [source, sourceDiagnostics] of Object.entries(bySource)) {
+    if (!sourceDiagnostics) continue
+    const summary = formatSummary(sourceDiagnostics)
+    console.warn(`\n${source} found ${summary}:\n`)
+
+    sourceDiagnostics.forEach((diagnostic, index) => {
+      const icon = getIcon(diagnostic.severity)
+      console.warn(`${icon} ${index + 1}. ${diagnostic.message}\n`)
+    })
+  }
+}

package/src/lib/diagnostic/severity.ts

@@ -0,0 +1,93 @@
+import { S } from '#lib/kit-temp/effect'
+import { Order } from 'effect'
+
+// ============================================================================
+// Schema - Severity
+// ============================================================================
+
+export const Severity = S.Enums(
+  {
+    error: 'error',
+    warning: 'warning',
+    info: 'info',
+  } as const,
+).annotations({
+  identifier: 'DiagnosticSeverity',
+  description: 'The severity level of a diagnostic message',
+})
+
+Severity.enums.error
+
+export type Severity = typeof Severity.Type
+
+// ============================================================================
+// Severity Literals
+// ============================================================================
+
+export const Error = S.Literal(Severity.enums.error)
+export const Warning = S.Literal(Severity.enums.warning)
+export const Info = S.Literal(Severity.enums.info)
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Severity)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Severity)
+export const decodeSync = S.decodeSync(Severity)
+export const encode = S.encode(Severity)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalence = S.equivalence(Severity)
+
+// ============================================================================
+// Ordering
+// ============================================================================
+
+/**
+ * Order for severity levels.
+ * error > warning > info
+ */
+export const order: Order.Order<Severity> = Order.mapInput(
+  Order.number,
+  (severity: Severity) => {
+    switch (severity) {
+      case Severity.enums.error:
+        return 3
+      case Severity.enums.warning:
+        return 2
+      case Severity.enums.info:
+        return 1
+    }
+  },
+)
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Returns the highest severity from an array of severities.
+ * Returns 'info' if array is empty.
+ */
+export const highest = (severities: Severity[]): Severity => {
+  if (severities.length === 0) return Severity.enums.info
+  return severities.reduce(Order.max(order))
+}
+
+/**
+ * Returns the lowest severity from an array of severities.
+ * Returns 'error' if array is empty (most conservative).
+ */
+export const lowest = (severities: Severity[]): Severity => {
+  if (severities.length === 0) return Severity.enums.error
+  return severities.reduce(Order.min(order))
+}

package/src/lib/directed-filter/$$.ts

@@ -0,0 +1 @@
+export * from './directed-filter.js'

package/src/lib/directed-filter/$.test.ts

@@ -0,0 +1,169 @@
+import { S } from '#lib/kit-temp/effect'
+import { describe, expect, test } from 'vitest'
+import { DirectedFilter } from './$.js'
+
+describe('create', () => {
+  test('returns Union and member schemas', () => {
+    const F = DirectedFilter.create(S.String)
+    expect(F).toHaveProperty('Union')
+    expect(F).toHaveProperty('Allow')
+    expect(F).toHaveProperty('Deny')
+    expect(F.Allow.make({ items: ['a'] })._tag).toBe('DirectedFilterAllow')
+    expect(F.Deny.make({ items: ['b'] })._tag).toBe('DirectedFilterDeny')
+  })
+})
+
+describe('constructor functions', () => {
+  test('allow creates DirectedFilterAllow', () => {
+    const filter = DirectedFilter.allow(['a', 'b'])
+    expect(filter._tag).toBe('DirectedFilterAllow')
+    expect(filter.items).toEqual(['a', 'b'])
+  })
+
+  test('deny creates DirectedFilterDeny', () => {
+    const filter = DirectedFilter.deny(['c', 'd'])
+    expect(filter._tag).toBe('DirectedFilterDeny')
+    expect(filter.items).toEqual(['c', 'd'])
+  })
+
+  test('AllowAll is DirectedFilterAllowAll', () => {
+    expect(DirectedFilter.AllowAll._tag).toBe('DirectedFilterAllowAll')
+  })
+
+  test('denyAll is DirectedFilterDenyAll', () => {
+    expect(DirectedFilter.DenyAll._tag).toBe('DirectedFilterDenyAll')
+  })
+})
+
+describe('fromOnlyExclude', () => {
+  test.for([
+    { only: ['a', 'b'], exclude: undefined, expected: { _tag: 'DirectedFilterAllow', items: ['a', 'b'] } },
+    { only: undefined, exclude: ['c', 'd'], expected: { _tag: 'DirectedFilterDeny', items: ['c', 'd'] } },
+    { only: ['a'], exclude: ['b'], expected: { _tag: 'DirectedFilterAllow', items: ['a'] } }, // only wins
+    { only: undefined, exclude: undefined, expected: { _tag: 'DirectedFilterAllowAll' } },
+    { only: [], exclude: [], expected: { _tag: 'DirectedFilterAllowAll' } },
+    { only: [], exclude: undefined, expected: { _tag: 'DirectedFilterAllowAll' } },
+  ])('$only/$exclude -> $expected', ({ only, exclude, expected }) => {
+    expect(DirectedFilter.fromOnlyExclude(only, exclude)).toEqual(expected)
+  })
+})
+
+describe('filter', () => {
+  const items = ['a', 'b', 'c', 'd']
+
+  test.for([
+    { filter: { _tag: 'DirectedFilterAllow', items: ['a', 'c'] }, expected: ['a', 'c'] },
+    { filter: { _tag: 'DirectedFilterDeny', items: ['b', 'd'] }, expected: ['a', 'c'] },
+    { filter: { _tag: 'DirectedFilterAllow', items: ['a', 'z'] }, expected: ['a'] }, // non-existent
+    { filter: { _tag: 'DirectedFilterDeny', items: ['x', 'y'] }, expected: items }, // non-existent
+    { filter: { _tag: 'DirectedFilterAllow', items: [] }, expected: [] },
+    { filter: { _tag: 'DirectedFilterDeny', items: [] }, expected: items },
+    { filter: { _tag: 'DirectedFilterAllowAll' }, expected: items },
+    { filter: { _tag: 'DirectedFilterDenyAll' }, expected: [] },
+  ])('$filter._tag with items $filter.items -> $expected', ({ filter, expected }) => {
+    expect(DirectedFilter.filter(filter as any)(items)).toEqual(expected)
+  })
+})
+
+describe('filterBy', () => {
+  const people = [
+    { id: 1, name: 'Alice', age: 30 },
+    { id: 2, name: 'Bob', age: 25 },
+    { id: 3, name: 'Charlie', age: 30 },
+  ]
+
+  test.for([
+    {
+      filter: { _tag: 'DirectedFilterAllow', items: [30] },
+      getter: (p: any) => p.age,
+      expected: [people[0], people[2]],
+    },
+    {
+      filter: { _tag: 'DirectedFilterDeny', items: ['Bob'] },
+      getter: (p: any) => p.name,
+      expected: [people[0], people[2]],
+    },
+    {
+      filter: { _tag: 'DirectedFilterAllowAll' },
+      getter: (p: any) => p.age,
+      expected: people,
+    },
+    {
+      filter: { _tag: 'DirectedFilterDenyAll' },
+      getter: (p: any) => p.name,
+      expected: [],
+    },
+  ])('filters by custom getter', ({ filter, getter, expected }) => {
+    expect(DirectedFilter.filterBy(filter as any)(getter)(people)).toEqual(expected)
+  })
+
+  test('supports partial application', () => {
+    const filter = { _tag: 'DirectedFilterAllow' as const, items: [1, 3] }
+    const filterById = DirectedFilter.filterBy(filter)((p: any) => p.id)
+    expect(filterById(people).map(p => p.id)).toEqual([1, 3])
+    expect(filterById([{ id: 5 }])).toEqual([])
+  })
+})
+
+describe('filterByProperty', () => {
+  const products = [
+    { id: 'p1', category: 'Electronics', price: 1000 },
+    { id: 'p2', category: 'Media', price: 20 },
+    { id: 'p3', category: 'Electronics', price: 800 },
+  ]
+
+  test.for([
+    {
+      filter: { _tag: 'DirectedFilterAllow', items: ['Electronics'] },
+      prop: 'category',
+      expected: [products[0], products[2]],
+    },
+    {
+      filter: { _tag: 'DirectedFilterDeny', items: ['p2'] },
+      prop: 'id',
+      expected: [products[0], products[2]],
+    },
+    {
+      filter: { _tag: 'DirectedFilterAllow', items: [20, 800] },
+      prop: 'price',
+      expected: [products[1], products[2]],
+    },
+  ])('filters by property $prop', ({ filter, prop, expected }) => {
+    expect(DirectedFilter.filterByProperty(filter as any)(prop as any)(products)).toEqual(expected)
+  })
+})
+
+describe('type guards', () => {
+  const allow = { _tag: 'DirectedFilterAllow' as const, items: ['a'] }
+  const deny = { _tag: 'DirectedFilterDeny' as const, items: ['b'] }
+  const allowAll = { _tag: 'DirectedFilterAllowAll' as const }
+  const denyAll = { _tag: 'DirectedFilterDenyAll' as const }
+
+  test('isAllow', () => {
+    expect(DirectedFilter.isAllow(allow)).toBe(true)
+    expect(DirectedFilter.isAllow(deny)).toBe(false)
+    expect(DirectedFilter.isAllow(allowAll)).toBe(false)
+    expect(DirectedFilter.isAllow(denyAll)).toBe(false)
+  })
+
+  test('isDeny', () => {
+    expect(DirectedFilter.isDeny(allow)).toBe(false)
+    expect(DirectedFilter.isDeny(deny)).toBe(true)
+    expect(DirectedFilter.isDeny(allowAll)).toBe(false)
+    expect(DirectedFilter.isDeny(denyAll)).toBe(false)
+  })
+
+  test('isAllowAll', () => {
+    expect(DirectedFilter.isAllowAll(allow)).toBe(false)
+    expect(DirectedFilter.isAllowAll(deny)).toBe(false)
+    expect(DirectedFilter.isAllowAll(allowAll)).toBe(true)
+    expect(DirectedFilter.isAllowAll(denyAll)).toBe(false)
+  })
+
+  test('isDenyAll', () => {
+    expect(DirectedFilter.isDenyAll(allow)).toBe(false)
+    expect(DirectedFilter.isDenyAll(deny)).toBe(false)
+    expect(DirectedFilter.isDenyAll(allowAll)).toBe(false)
+    expect(DirectedFilter.isDenyAll(denyAll)).toBe(true)
+  })
+})

package/src/lib/directed-filter/$.ts

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