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

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

@@ -0,0 +1,241 @@
+import { S } from '#lib/kit-temp/effect'
+import { Match } from 'effect'
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+/**
+ * Creates a DirectedFilter schema for a given item schema.
+ * Returns an object containing the Union schema and its member schemas.
+ *
+ * @param itemSchema - The schema for items in the filter
+ * @returns Object with Union, Allow, Deny, AllowAll, and DenyAll schemas
+ */
+export const create = <ItemSchema extends S.Schema.Any>(itemSchema: ItemSchema) => {
+  const Allow = S.TaggedStruct('DirectedFilterAllow', {
+    items: S.Array(itemSchema),
+  }).annotations({
+    identifier: 'DirectedFilterAllow',
+    description: 'Filter that allows only specified items',
+  })
+
+  const Deny = S.TaggedStruct('DirectedFilterDeny', {
+    items: S.Array(itemSchema),
+  }).annotations({
+    identifier: 'DirectedFilterDeny',
+    description: 'Filter that denies specified items',
+  })
+
+  const AllowAll = S.TaggedStruct('DirectedFilterAllowAll', {}).annotations({
+    identifier: 'DirectedFilterAllowAll',
+    description: 'Filter that allows all items (no-op)',
+  })
+
+  const DenyAll = S.TaggedStruct('DirectedFilterDenyAll', {}).annotations({
+    identifier: 'DirectedFilterDenyAll',
+    description: 'Filter that denies all items',
+  })
+
+  const Union = S.Union(Allow, Deny, AllowAll, DenyAll).annotations({
+    identifier: 'DirectedFilter',
+    description: 'A filter that controls item inclusion/exclusion',
+  })
+
+  return {
+    Union,
+    Allow,
+    Deny,
+    AllowAll,
+    DenyAll,
+  } as const
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DirectedFilterAllow<T> = {
+  readonly _tag: 'DirectedFilterAllow'
+  readonly items: readonly T[]
+}
+
+export type DirectedFilterDeny<T> = {
+  readonly _tag: 'DirectedFilterDeny'
+  readonly items: readonly T[]
+}
+
+export type DirectedFilterAllowAll = {
+  readonly _tag: 'DirectedFilterAllowAll'
+}
+
+export type DirectedFilterDenyAll = {
+  readonly _tag: 'DirectedFilterDenyAll'
+}
+
+export type DirectedFilter<T> =
+  | DirectedFilterAllow<T>
+  | DirectedFilterDeny<T>
+  | DirectedFilterAllowAll
+  | DirectedFilterDenyAll
+
+// ============================================================================
+// Filtering Functions
+// ============================================================================
+
+/**
+ * Filters a collection based on a DirectedFilter using a custom value getter.
+ * Returns a curried function for partial application.
+ * Short-circuits for AllowAll/DenyAll for performance.
+ *
+ * TODO: Use equivalence trait from schema if available instead of === for comparison
+ *
+ * @param filter - The DirectedFilter to apply
+ * @returns Curried function that takes a value getter and then a collection
+ */
+export const filterBy = <FilterItem>(
+  filter: DirectedFilter<FilterItem>,
+) =>
+<Item>(
+  getValue: (item: Item) => FilterItem,
+) =>
+(
+  collection: readonly Item[],
+): Item[] => {
+  return Match.value(filter).pipe(
+    Match.tagsExhaustive({
+      DirectedFilterAllowAll: () => [...collection], // Return copy for immutability
+      DirectedFilterDenyAll: () => [],
+      DirectedFilterAllow: (f) => {
+        const allowSet = new Set(f.items)
+        return collection.filter(item => allowSet.has(getValue(item)))
+      },
+      DirectedFilterDeny: (f) => {
+        const denySet = new Set(f.items)
+        return collection.filter(item => !denySet.has(getValue(item)))
+      },
+    }),
+  )
+}
+
+/**
+ * Filters a collection based on a DirectedFilter using a property name.
+ * Convenience function that extracts values by property key.
+ *
+ * @param filter - The DirectedFilter to apply
+ * @returns Curried function that takes a property name and then a collection
+ */
+export function filterByProperty<FilterItem>(
+  filter: DirectedFilter<FilterItem>,
+): <K extends PropertyKey>(
+  propertyName: K,
+) => <Item extends Record<K, any>>(
+  collection: readonly Item[],
+) => Item[]
+export function filterByProperty<FilterItem>(
+  filter: DirectedFilter<FilterItem>,
+) {
+  return <K extends PropertyKey>(propertyName: K) =>
+  <Item extends Record<K, any>>(collection: readonly Item[]): Item[] => {
+    return filterBy(filter)((item: Item) => item[propertyName] as FilterItem)(collection)
+  }
+}
+
+/**
+ * Filters a collection based on a DirectedFilter using identity.
+ * Used when the items themselves are the filter values.
+ *
+ * @param filter - The DirectedFilter to apply
+ * @returns Function that filters a collection
+ */
+export const filter = <Item>(
+  filter: DirectedFilter<Item>,
+) =>
+(
+  collection: readonly Item[],
+): Item[] => {
+  return filterBy(filter)((item: Item) => item)(collection)
+}
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+/**
+ * Const instance for allowing all items.
+ */
+export const AllowAll: DirectedFilterAllowAll = { _tag: 'DirectedFilterAllowAll' }
+
+/**
+ * Const instance for denying all items.
+ */
+export const DenyAll: DirectedFilterDenyAll = { _tag: 'DirectedFilterDenyAll' }
+
+/**
+ * Creates an Allow filter with the specified items.
+ */
+export const allow = <T>(items: readonly T[]): DirectedFilterAllow<T> => ({
+  _tag: 'DirectedFilterAllow',
+  items,
+})
+
+/**
+ * Creates a Deny filter with the specified items.
+ */
+export const deny = <T>(items: readonly T[]): DirectedFilterDeny<T> => ({
+  _tag: 'DirectedFilterDeny',
+  items,
+})
+
+/**
+ * Creates a DirectedFilter from only/exclude pattern commonly used in configuration.
+ * Returns AllowAll if neither only nor exclude has items.
+ *
+ * @param only - Items to allow (takes precedence over exclude)
+ * @param exclude - Items to deny
+ * @returns DirectedFilter (never null)
+ */
+export const fromOnlyExclude = <T>(
+  only: readonly T[] | undefined,
+  exclude: readonly T[] | undefined,
+  /**
+   * @default allowAll
+   */
+  fallback?: DirectedFilterDenyAll | DirectedFilterAllowAll,
+): DirectedFilter<T> => {
+  if (only && only.length > 0) {
+    return allow(only)
+  }
+  if (exclude && exclude.length > 0) {
+    return deny(exclude)
+  }
+  return fallback ?? AllowAll
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Type guard for DirectedFilterAllow
+ */
+export const isAllow = <T>(filter: DirectedFilter<T>): filter is DirectedFilterAllow<T> =>
+  filter._tag === 'DirectedFilterAllow'
+
+/**
+ * Type guard for DirectedFilterDeny
+ */
+export const isDeny = <T>(filter: DirectedFilter<T>): filter is DirectedFilterDeny<T> =>
+  filter._tag === 'DirectedFilterDeny'
+
+/**
+ * Type guard for DirectedFilterAllowAll
+ */
+export const isAllowAll = <T>(filter: DirectedFilter<T>): filter is DirectedFilterAllowAll =>
+  filter._tag === 'DirectedFilterAllowAll'
+
+/**
+ * Type guard for DirectedFilterDenyAll
+ */
+export const isDenyAll = <T>(filter: DirectedFilter<T>): filter is DirectedFilterDenyAll =>
+  filter._tag === 'DirectedFilterDenyAll'

package/src/lib/document/$$.ts

@@ -0,0 +1,3 @@
+export * from './document.js'
+export * as Unversioned from './unversioned.js'
+export * as Versioned from './versioned.js'

package/src/lib/document/$.ts

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

package/src/lib/document/document.ts

@@ -0,0 +1,37 @@
+import { S } from '#lib/kit-temp/effect'
+import { DocumentUnversioned } from './unversioned.js'
+import { DocumentVersioned } from './versioned.js'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+/**
+ * A Document represents versionable content that can be:
+ * - Unversioned: A single document with no version support
+ * - Versioned: Multiple versions mapped by version selections (single versions or version sets)
+ */
+export const Document = S.Union(
+  DocumentUnversioned,
+  DocumentVersioned,
+)
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type Document = typeof Document.Type
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Document)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Document)
+export const decodeSync = S.decodeSync(Document)
+export const encode = S.encode(Document)

package/src/lib/document/unversioned.ts

@@ -0,0 +1,35 @@
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const DocumentUnversioned = S.TaggedStruct('DocumentUnversioned', {
+  document: S.String,
+})
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DocumentUnversioned = typeof DocumentUnversioned.Type
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = DocumentUnversioned.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(DocumentUnversioned)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(DocumentUnversioned)
+export const decodeSync = S.decodeSync(DocumentUnversioned)
+export const encode = S.encode(DocumentUnversioned)

package/src/lib/document/versioned.ts

@@ -0,0 +1,106 @@
+import { S } from '#lib/kit-temp/effect'
+import { VersionCoverage } from '#lib/version-selection/$'
+import { Version } from '#lib/version/$'
+import { HashMap, Option } from 'effect'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const DocumentVersioned = S.TaggedStruct('DocumentVersioned', {
+  /**
+   * Map from version selection (single or set) to document content.
+   * Supports:
+   * - Single version → document (e.g., v1 → "query for v1")
+   * - Version set → document (e.g., {v2,v3} → "shared query")
+   */
+  versionDocuments: S.HashMap({
+    key: VersionCoverage.VersionCoverage,
+    value: S.String,
+  }),
+})
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DocumentVersioned = typeof DocumentVersioned.Type
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = DocumentVersioned.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(DocumentVersioned)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(DocumentVersioned)
+export const decodeSync = S.decodeSync(DocumentVersioned)
+export const encode = S.encode(DocumentVersioned)
+
+// ============================================================================
+// Domain Logic
+// ============================================================================
+
+/**
+ * Get document for a specific version
+ */
+export const getContentForVersion = (
+  doc: DocumentVersioned,
+  version: Version.Version,
+): string | null => {
+  // Try exact match first (single version key)
+  const exactMatch = HashMap.get(doc.versionDocuments, version)
+  if (Option.isSome(exactMatch)) {
+    return exactMatch.value
+  }
+
+  // Check version sets
+  for (const [selection, content] of HashMap.entries(doc.versionDocuments)) {
+    if (VersionCoverage.isSet(selection) && VersionCoverage.contains(selection, version)) {
+      return content
+    }
+  }
+
+  return null
+}
+
+/**
+ * Get all individual versions covered by this document
+ */
+export const getAllVersions = (doc: DocumentVersioned): Version.Version[] => {
+  const versions = new Set<Version.Version>()
+  for (const selection of HashMap.keys(doc.versionDocuments)) {
+    for (const v of VersionCoverage.toVersions(selection)) {
+      versions.add(v)
+    }
+  }
+  return Array.from(versions)
+}
+/**
+ * Get document content for the latest version available in the document
+ */
+export const getContentForLatestVersionOrThrow = (doc: DocumentVersioned): string => {
+  const versions = getAllVersions(doc)
+
+  if (versions.length === 0) {
+    throw new Error('No versions found in document')
+  }
+
+  // Use Version.max with reduce to find the latest version
+  const latestVersion = versions.reduce(Version.max)
+
+  const content = getContentForVersion(doc, latestVersion)
+  if (!content) {
+    throw new Error('Latest version not found in document')
+  }
+  return content
+}

package/src/lib/effect-cli-help-markdown/$$.ts

@@ -0,0 +1 @@
+export * from './effect-cli-help-markdown.js'

package/src/lib/effect-cli-help-markdown/$.test.ts

@@ -0,0 +1,49 @@
+import { Command, Options } from '@effect/cli'
+import { Effect } from 'effect'
+import { describe, expect, test } from 'vitest'
+import { EffectCliHelpMarkdown } from './$.js'
+
+describe('EffectCliHelpMarkdown', () => {
+  describe('commandToMarkdown', () => {
+    test('generates markdown for a simple command', () => {
+      const command = Command.make('test').pipe(
+        Command.withHandler(() => Effect.succeed(undefined)),
+      )
+
+      const markdown = EffectCliHelpMarkdown.commandToMarkdown(command)
+
+      // Basic expectations - will enhance once we have proper implementation
+      expect(markdown).toBeDefined()
+      expect(typeof markdown).toBe('string')
+    })
+
+    test('respects baseHeadingLevel option', () => {
+      const command = Command.make('test').pipe(
+        Command.withHandler(() => Effect.succeed(undefined)),
+      )
+
+      const markdown = EffectCliHelpMarkdown.commandToMarkdown(command, {
+        baseHeadingLevel: 2,
+        includeCommandName: true,
+      })
+
+      // Should start with ## instead of #
+      if (markdown.includes('#')) {
+        expect(markdown).toMatch(/^##\s/)
+      }
+    })
+
+    test('excludes command name when includeCommandName is false', () => {
+      const command = Command.make('test-command').pipe(
+        Command.withHandler(() => Effect.succeed(undefined)),
+      )
+
+      const markdown = EffectCliHelpMarkdown.commandToMarkdown(command, {
+        includeCommandName: false,
+      })
+
+      // Should not include the command name as a heading
+      expect(markdown).not.toMatch(/^#.*test-command/)
+    })
+  })
+})

package/src/lib/effect-cli-help-markdown/$.ts

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