polen 0.11.0-next.24 → 0.11.0-next.26

package/src/lib/graphql-path/query.ts

@@ -2,117 +2,34 @@
  * Query path operations
  */
 
-import { createFieldSegment, createTypeSegment } from './constructors.js'
-import type { QueryPath, QuerySegment } from './types.js'
-
-/**
- * Builder class for creating query paths with a fluent interface
- *
- * @example
- * ```ts
- * const path = builder()
- *   .type('User')
- *   .field('posts')
- *   .type('Post')
- *   .field('author')
- *   .build()
- * ```
- */
-export class QueryPathBuilder {
-  private segments: QuerySegment[] = []
-
-  /**
-   * Add a type segment to the path
-   *
-   * @param typeName - The type name
-   * @returns The builder for chaining
-   */
-  type(typeName: string): this {
-    this.segments.push(createTypeSegment(typeName))
-    return this
-  }
-
-  /**
-   * Add a field segment to the path
-   *
-   * @param fieldName - The field name
-   * @returns The builder for chaining
-   */
-  field(fieldName: string): this {
-    this.segments.push(createFieldSegment(fieldName))
-    return this
-  }
-
-  /**
-   * Build the final query path
-   *
-   * @returns The constructed query path
-   */
-  build(): QueryPath {
-    return this.segments
-  }
-}
-
-/**
- * Create a new query path builder
- *
- * @returns A new query path builder instance
- * @example
- * ```ts
- * const path = builder()
- *   .type('User')
- *   .field('posts')
- *   .type('Post')
- *   .field('author')
- *   .build()
- * ```
- */
-export const builder = (): QueryPathBuilder => new QueryPathBuilder()
+import { S } from '#lib/kit-temp/effect'
+import { QueryPath } from './types.js'
 
 /**
  * Encode a query path to a human-readable expression string
+ * Uses the Effect Schema codec for QueryPath
  *
- * @param path - The query path to encode
+ * @param path - The query path segments to encode
  * @returns A string expression representation
  * @example
- * encode(builder().type('User').field('posts').type('Post').field('title').build()) // 'User.posts.Post.title'
+ * encode([
+ *   { _tag: 'TypeSegment', type: 'User' },
+ *   { _tag: 'FieldSegment', field: 'posts' },
+ *   { _tag: 'TypeSegment', type: 'Post' },
+ *   { _tag: 'FieldSegment', field: 'title' }
+ * ]) // 'User.posts.Post.title'
  */
-export const encode = (path: QueryPath): string => {
-  return path.map(segment => {
-    if (segment.kind === 'type') return segment.type
-    if (segment.kind === 'field') return segment.field
-    return ''
-  }).filter(Boolean).join('.')
-}
+export const encode = S.encodeSync(QueryPath)
 
 /**
  * Decode a string expression into a query path
+ * Uses the Effect Schema codec for QueryPath
  * Note: This assumes alternating type.field.type.field pattern
  *
  * @param expression - The string expression to decode
- * @returns The decoded query path or null if invalid
+ * @returns The decoded query path segments
+ * @throws ParseError if the expression is invalid
  * @example
  * decode('User.posts.Post.title') // Query path traversing User->posts->Post->title
  */
-export const decode = (expression: string): QueryPath | null => {
-  if (!expression) return null
-
-  const parts = expression.split('.')
-  const segments: QuerySegment[] = []
-
-  // Assume alternating pattern: type.field.type.field...
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i]
-    if (!part) continue
-
-    if (i % 2 === 0) {
-      // Even indices are types
-      segments.push(createTypeSegment(part))
-    } else {
-      // Odd indices are fields
-      segments.push(createFieldSegment(part))
-    }
-  }
-
-  return segments
-}
+export const decode = S.decodeUnknownSync(QueryPath)

package/src/lib/graphql-path/schema.ts

@@ -0,0 +1,136 @@
+/**
+ * GraphQL schema location utilities for definition paths
+ */
+
+import { Grafaid } from '#lib/grafaid'
+import { Data, Either, Match } from 'effect'
+import * as Definition from './definition.js'
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class TypeNotFoundError extends Data.TaggedError('TypeNotFoundError')<{
+  typeName: string
+  path: string
+}> {}
+
+export class FieldNotFoundError extends Data.TaggedError('FieldNotFoundError')<{
+  typeName: string
+  fieldName: string
+  path: string
+}> {}
+
+// ============================================================================
+// Locate Functions
+// ============================================================================
+
+/**
+ * Locate a type in the GraphQL schema from a type definition path.
+ *
+ * @param schema - The GraphQL schema
+ * @param path - The type definition path
+ * @returns Either the located type or a TypeNotFoundError
+ */
+export const locateType = (
+  schema: Grafaid.Schema.Schema,
+  path: Definition.TypeDefinitionPath,
+): Either.Either<Grafaid.Schema.TypesLike.Named, TypeNotFoundError> => {
+  const typeName = Definition.getType(path)
+  const type = schema.getType(typeName)
+  if (!type) {
+    return Either.left(
+      new TypeNotFoundError({
+        typeName,
+        path: Definition.encodeSync(path),
+      }),
+    )
+  }
+  return Either.right(type)
+}
+
+/**
+ * Locate a field in the GraphQL schema from a field definition path.
+ *
+ * @param schema - The GraphQL schema
+ * @param path - The field definition path
+ * @returns Either the located field or a FieldNotFoundError
+ */
+export const locateField = (
+  schema: Grafaid.Schema.Schema,
+  path: Definition.FieldDefinitionPath,
+): Either.Either<Grafaid.Schema.NodesLike.Field, FieldNotFoundError> => {
+  const typeName = Definition.getType(path)
+  const fieldName = Definition.getField(path)
+
+  const type = schema.getType(typeName)
+  if (!type) {
+    return Either.left(
+      new FieldNotFoundError({
+        typeName,
+        fieldName,
+        path: Definition.encodeSync(path),
+      }),
+    )
+  }
+
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
+    return Either.left(
+      new FieldNotFoundError({
+        typeName,
+        fieldName,
+        path: Definition.encodeSync(path),
+      }),
+    )
+  }
+
+  const fields = type.getFields()
+  const field = fields[fieldName]
+
+  if (!field) {
+    // dprint-ignore
+    return Either.left(new FieldNotFoundError({
+      typeName,
+      fieldName,
+      path: Definition.encodeSync(path),
+    }))
+  }
+
+  return Either.right(field)
+}
+
+/**
+ * Locate a type or field in the GraphQL schema from a definition path.
+ *
+ * @param schema - The GraphQL schema
+ * @param path - The definition path (type or field)
+ * @returns Either the located type/field or an error
+ */
+export const locate = (
+  schema: Grafaid.Schema.Schema,
+  path: Definition.DefinitionPath,
+): Either.Either<
+  Grafaid.Schema.TypesLike.Named | Grafaid.Schema.NodesLike.Field,
+  TypeNotFoundError | FieldNotFoundError
+> => {
+  return Match.value(path).pipe(
+    Match.when(
+      Definition.isTypeDefinitionPath,
+      (p) => locateType(schema, p),
+    ),
+    Match.when(
+      Definition.isFieldDefinitionPath,
+      (p) => locateField(schema, p),
+    ),
+    Match.orElse(() => {
+      // This should never happen with proper path types
+      // Return a generic error for unsupported path types
+      return Either.left(
+        new TypeNotFoundError({
+          typeName: 'unknown',
+          path: Definition.encodeSync(path),
+        }),
+      )
+    }),
+  )
+}

package/src/lib/graphql-path/types.ts

@@ -1,55 +1,135 @@
 /**
- * GraphQL Path type definitions
+ * GraphQL Path type definitions using Effect Schema
  */
 
+import { S } from '#lib/kit-temp/effect'
+import { ParseResult } from 'effect'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
 /**
- * Base segment representing a GraphQL type in a path
+ * Segment representing a GraphQL type in a path
  */
-export interface TypeSegment {
-  kind: 'type'
-  type: string
-}
+export const TypeSegment = S.TaggedStruct('TypeSegment', {
+  type: S.String,
+})
+
+export type TypeSegment = S.Schema.Type<typeof TypeSegment>
+
+// Type guard derived from Effect Schema
+export const isTypeSegment = S.is(TypeSegment)
 
 /**
- * Base segment representing a field in a path
+ * Segment representing a field in a path
  */
-export interface FieldSegment {
-  kind: 'field'
-  field: string
-}
+export const FieldSegment = S.TaggedStruct('FieldSegment', {
+  field: S.String,
+})
+
+export type FieldSegment = S.Schema.Type<typeof FieldSegment>
+
+// Type guard derived from Effect Schema
+export const isFieldSegment = S.is(FieldSegment)
 
 /**
- * Base segment representing an argument in a path
+ * Segment representing an argument in a path
  */
-export interface ArgumentSegment {
-  kind: 'argument'
-  argument: string
-}
+export const ArgumentSegment = S.TaggedStruct('ArgumentSegment', {
+  argument: S.String,
+})
+
+export type ArgumentSegment = S.Schema.Type<typeof ArgumentSegment>
+
+// Type guard derived from Effect Schema
+export const isArgumentSegment = S.is(ArgumentSegment)
 
 /**
  * Union of all possible segments
  */
-export type Segment = TypeSegment | FieldSegment | ArgumentSegment
+export const Segment = S.Union(TypeSegment, FieldSegment, ArgumentSegment)
+
+export type Segment = S.Schema.Type<typeof Segment>
+
+// Type guard derived from Effect Schema
+export const isSegment = S.is(Segment)
 
 /**
  * Query segments - only types and fields can be traversed in queries
  * Arguments cannot be part of query paths as they are not traversable
  */
-export type QuerySegment = TypeSegment | FieldSegment
+export const QuerySegment = S.Union(TypeSegment, FieldSegment)
+
+export type QuerySegment = S.Schema.Type<typeof QuerySegment>
+
+// Type guard derived from Effect Schema
+export const isQuerySegment = S.is(QuerySegment)
+
+/**
+ * Internal decoded form of QueryPath
+ */
+const QueryPathDecoded = S.Array(QuerySegment)
 
 /**
  * Query/Data paths - potentially deep paths that span multiple types through fields
  * These represent traversal paths through the schema graph
  *
- * @example
- * User.posts.author.name would be:
- * [
- *   { kind: 'type', type: 'User' },
- *   { kind: 'field', field: 'posts' },
- *   { kind: 'type', type: 'Post' },
- *   { kind: 'field', field: 'author' },
- *   { kind: 'type', type: 'User' },
- *   { kind: 'field', field: 'name' }
+ * Encoded: "User.posts.Post.author.User.name"
+ * Decoded: [
+ *   { _tag: 'TypeSegment', type: 'User' },
+ *   { _tag: 'FieldSegment', field: 'posts' },
+ *   { _tag: 'TypeSegment', type: 'Post' },
+ *   { _tag: 'FieldSegment', field: 'author' },
+ *   { _tag: 'TypeSegment', type: 'User' },
+ *   { _tag: 'FieldSegment', field: 'name' }
  * ]
+ *
+ * Note: Assumes alternating type.field.type.field pattern
  */
-export type QueryPath = QuerySegment[]
+export const QueryPath = S.transformOrFail(
+  S.String,
+  QueryPathDecoded,
+  {
+    decode: (str, _options, ast) => {
+      if (!str) {
+        return ParseResult.fail(new ParseResult.Type(ast, str))
+      }
+
+      const parts = str.split('.')
+      const segments: QuerySegment[] = []
+
+      // Assume alternating pattern: type.field.type.field...
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i]
+        if (!part) {
+          return ParseResult.fail(new ParseResult.Type(ast, str))
+        }
+
+        if (i % 2 === 0) {
+          // Even indices are types
+          segments.push(TypeSegment.make({ type: part }))
+        } else {
+          // Odd indices are fields
+          segments.push(FieldSegment.make({ field: part }))
+        }
+      }
+
+      return ParseResult.succeed(segments)
+    },
+    encode: (path) => {
+      const str = path.map(segment => {
+        if (segment._tag === 'TypeSegment') return segment.type
+        if (segment._tag === 'FieldSegment') return segment.field
+        return ''
+      }).filter(Boolean).join('.')
+
+      return ParseResult.succeed(str)
+    },
+  },
+).annotations({
+  identifier: 'QueryPath',
+  description: 'Query path through a GraphQL schema',
+})
+
+export type QueryPath = S.Schema.Type<typeof QueryPath>

package/src/lib/version-coverage/version-coverage.ts

@@ -6,19 +6,23 @@ import { Array, HashSet, pipe } from 'effect'
 // Schema
 // ============================================================================
 
+export class VersionCoverageUnversioned
+  extends S.TaggedClass<VersionCoverageUnversioned>()('VersionCoverageUnversioned', {})
+{}
 export const VersionCoverageOne = Version.Version
 export const VersionCoverageSet = S.HashSet(Version.Version)
 
 /**
- * A selection of versions - either a single version or a set of versions.
+ * A selection of versions - either unversioned (applies to all), a single version, or a set of versions.
  * Used as keys in versioned documents to map version(s) to document content.
  */
 export const VersionCoverage = S.Union(
+  VersionCoverageUnversioned,
   VersionCoverageOne,
   VersionCoverageSet,
 ).annotations({
   identifier: 'VersionCoverage',
-  description: 'A single version or set of versions',
+  description: 'Unversioned (all versions), a single version, or a set of versions',
 })
 
 // ============================================================================
@@ -31,16 +35,34 @@ export type VersionCoverage = S.Schema.Type<typeof VersionCoverage>
 // Constructors
 // ============================================================================
 
+/**
+ * Create an unversioned coverage that applies to all versions
+ */
+export const unversioned = (): VersionCoverage => new VersionCoverageUnversioned({})
+
+/**
+ * Create a single version coverage
+ */
+export const single = (version: Version.Version): VersionCoverage => version
+
+/**
+ * Create a version set coverage
+ */
+export const set = (versions: Version.Version[]): VersionCoverage => HashSet.fromIterable(versions)
+
 // ============================================================================
 // Type Guards
 // ============================================================================
 
 export const is = S.is(VersionCoverage)
 
-export const isSingle = Version.is
+export const isUnversioned = (coverage: VersionCoverage): coverage is VersionCoverageUnversioned =>
+  coverage instanceof VersionCoverageUnversioned
 
-export const isSet = (selection: VersionCoverage): selection is HashSet.HashSet<Version.Version> =>
-  !Version.is(selection)
+export const isSingle = (coverage: VersionCoverage): coverage is Version.Version => Version.is(coverage)
+
+export const isSet = (coverage: VersionCoverage): coverage is HashSet.HashSet<Version.Version> =>
+  !isUnversioned(coverage) && !Version.is(coverage)
 
 // ============================================================================
 // Codec
@@ -68,6 +90,9 @@ export const contains = (
   versionCoverage: VersionCoverage,
   version: Version.Version,
 ): boolean => {
+  if (isUnversioned(versionCoverage)) {
+    return true // Unversioned applies to all versions
+  }
   if (Version.is(versionCoverage)) {
     return Version.equivalence(versionCoverage, version)
   }
@@ -78,6 +103,9 @@ export const contains = (
  * Get display label for UI
  */
 export const toLabel = (versionCoverage: VersionCoverage): string => {
+  if (isUnversioned(versionCoverage)) {
+    return 'All Versions'
+  }
   return pipe(versionCoverage, encodeSync, Array.ensure, Array.map(_ => _.toString()), Array.join(', '))
 }
 
@@ -85,6 +113,9 @@ export const toLabel = (versionCoverage: VersionCoverage): string => {
  * Get all versions from a selection
  */
 export const toVersions = (versionCoverage: VersionCoverage): Version.Version[] => {
+  if (isUnversioned(versionCoverage)) {
+    return [] // Unversioned doesn't map to specific versions
+  }
   if (Version.is(versionCoverage)) {
     return [versionCoverage]
   }
@@ -98,9 +129,12 @@ export const toVersions = (versionCoverage: VersionCoverage): Version.Version[]
  *
  * @param versionCoverage - The version coverage to get the latest version from
  * @returns The latest version
- * @throws {Error} If the version set is empty
+ * @throws {Error} If the version set is empty or if called on unversioned coverage
  */
 export const getLatest = (versionCoverage: VersionCoverage): Version.Version => {
+  if (isUnversioned(versionCoverage)) {
+    throw new Error('Cannot get latest version from unversioned coverage')
+  }
   if (Version.is(versionCoverage)) {
     return versionCoverage
   }
@@ -115,3 +149,11 @@ export const getLatest = (versionCoverage: VersionCoverage): Version.Version =>
   // Reduce the array to find the maximum
   return versions.reduce((latest, current) => Version.max(latest, current))
 }
+
+/**
+ * Check if a version coverage matches a specific version.
+ * Unversioned always matches, single version must be equal, set must contain the version.
+ */
+export const matches = (coverage: VersionCoverage, version: Version.Version): boolean => {
+  return contains(coverage, version)
+}

package/src/template/components/ArgumentAnnotation.tsx

@@ -1,24 +1,73 @@
-import { Box, Flex, Text } from '@radix-ui/themes'
+import { Grafaid } from '#lib/grafaid'
+import { Box, Flex, HoverCard, Text } from '@radix-ui/themes'
 import type { GraphQLArgument } from 'graphql'
 import type { FC } from 'react'
+import { useViewMode } from '../contexts/ViewModeContext.js'
+import { Description } from './Description.js'
 import { TypeAnnotation } from './TypeAnnotation.js'
 
 export interface Props {
   data: GraphQLArgument
+  nameWidth?: number
 }
 
 /**
- * Renders a single GraphQL argument in SDL syntax
+ * Renders a single GraphQL argument with aligned columns
  */
-export const ArgumentAnnotation: FC<Props> = ({ data }) => {
-  return (
-    <Box as='div'>
-      <Flex>
-        <Text>{data.name}</Text>
-        <Text>:&nbsp;</Text>
+export const ArgumentAnnotation: FC<Props> = ({ data, nameWidth }) => {
+  const { viewMode } = useViewMode()
+
+  const nameElement = (
+    <Text size='2' weight='bold' color='gray'>
+      {data.name}
+    </Text>
+  )
 
-        <TypeAnnotation type={data.type} />
+  return (
+    <Box>
+      <Flex align='baseline' gap='2'>
+        <Box
+          style={{
+            minWidth: nameWidth ? `${nameWidth}ch` : 'auto',
+            flexShrink: 0,
+          }}
+        >
+          {viewMode === 'compact' && data.description
+            ? (
+              <HoverCard.Root>
+                <HoverCard.Trigger>
+                  {nameElement}
+                </HoverCard.Trigger>
+                <HoverCard.Content
+                  size='2'
+                  maxWidth='400px'
+                  side='top'
+                  align='center'
+                >
+                  <Text size='2' color='gray'>
+                    <Description data={data} />
+                  </Text>
+                </HoverCard.Content>
+              </HoverCard.Root>
+            )
+            : nameElement}
+        </Box>
+        <TypeAnnotation type={data.type} showDescription={true} />
+        {data.defaultValue !== undefined && (
+          <Text size='2' color='gray'>
+            {' = '}
+            {Grafaid.Schema.formatDefaultValue(data.defaultValue, data.type)}
+          </Text>
+        )}
       </Flex>
+      {/* Argument description below name/type (only in expanded mode) */}
+      {data.description && viewMode === 'expanded' && (
+        <Box mt='2'>
+          <Text size='2' color='gray' style={{ lineHeight: '1.5' }}>
+            <Description data={data} />
+          </Text>
+        </Box>
+      )}
     </Box>
   )
 }