polen 0.11.0-next.22 → 0.11.0-next.24

package/src/api/schema/input-sources/memory.ts

@@ -121,11 +121,11 @@ export const normalize = (configInput: Options): Config => {
 const parseSchema = (value: string | GraphQLSchema): Effect.Effect<GraphQLSchema, InputSource.InputSourceError> =>
   Effect.gen(function*() {
     if (typeof value === 'string') {
-      const ast = yield* Grafaid.Schema.AST.parse(value).pipe(
+      const ast = yield* Grafaid.Parse.parseSchema(value, { source: 'memory' }).pipe(
         Effect.mapError((error) =>
           new InputSource.InputSourceError({
             source: 'memory',
-            message: `Failed to parse schema: ${error}`,
+            message: error.message,
             cause: error,
           })
         ),
@@ -134,7 +134,7 @@ const parseSchema = (value: string | GraphQLSchema): Effect.Effect<GraphQLSchema
         Effect.mapError((error) =>
           new InputSource.InputSourceError({
             source: 'memory',
-            message: `Failed to build schema: ${error}`,
+            message: error.message,
             cause: error,
           })
         ),

package/src/api/schema/input-sources/versioned-directory.ts

@@ -201,11 +201,11 @@ export const readOrThrow = (
               Effect.gen(function*() {
                 const filePath = Path.join(versionInfo.path, revisionFile)
                 const content = yield* fs.readFileString(filePath)
-                const ast = yield* Grafaid.Schema.AST.parse(content).pipe(
+                const ast = yield* Grafaid.Parse.parseSchema(content, { source: filePath }).pipe(
                   Effect.mapError((error) =>
                     new InputSource.InputSourceError({
                       source: 'versionedDirectory',
-                      message: `Failed to parse schema from ${filePath}: ${error}`,
+                      message: error.message,
                       cause: error,
                     })
                   ),
@@ -214,7 +214,7 @@ export const readOrThrow = (
                   Effect.mapError((error) =>
                     new InputSource.InputSourceError({
                       source: 'versionedDirectory',
-                      message: `Failed to build schema from ${filePath}: ${error}`,
+                      message: error.message,
                       cause: error,
                     })
                   ),

package/src/cli/commands/open.ts

@@ -74,7 +74,7 @@ const cacheRead = async (source: string, useCache: boolean) => {
     const filePath = Path.join(cacheDir, fileName)
     const sdl = await Fs.read(filePath)
     if (!sdl) return null
-    const documentNode = await Effect.runPromise(Grafaid.Schema.AST.parse(sdl))
+    const documentNode = await Effect.runPromise(Grafaid.Parse.parseSchema(sdl, { source: filePath }))
     return await Effect.runPromise(Grafaid.Schema.fromAST(documentNode))
   })
 }

package/src/lib/grafaid/$$.ts

@@ -1,4 +1,6 @@
 export * as Document from './document.js'
 export * from './graphql.js'
 export * as HTTP from './http/http.js'
+export { ParseError } from './parse-error.js'
+export * as Parse from './parse.js'
 export * as Schema from './schema/schema.js'

package/src/lib/grafaid/parse-error.ts

@@ -0,0 +1,69 @@
+import { Data } from 'effect'
+
+/**
+ * Error that occurs when parsing GraphQL source text fails.
+ *
+ * This error provides structured information about parse failures,
+ * including the source context and the underlying parse error details.
+ */
+export class ParseError extends Data.TaggedError('ParseError')<{
+  /**
+   * The type of GraphQL content being parsed.
+   * Helps identify whether the error occurred while parsing a schema or a document.
+   */
+  readonly parseType: 'schema' | 'document' | 'unknown'
+
+  /**
+   * Optional source identifier for debugging.
+   * Could be a file path, URL, or other identifier.
+   */
+  readonly source?: string
+
+  /**
+   * The error message describing what went wrong.
+   */
+  readonly message: string
+
+  /**
+   * The original error that caused the parse failure.
+   */
+  readonly cause?: unknown
+
+  /**
+   * Optional excerpt of the source text where the error occurred.
+   * Useful for showing context in error messages.
+   */
+  readonly excerpt?: string
+}> {}
+
+/**
+ * Helper to create a ParseError with common defaults.
+ */
+export const makeParseError = (
+  message: string,
+  options?: {
+    parseType?: 'schema' | 'document' | 'unknown'
+    source?: string
+    cause?: unknown
+    excerpt?: string
+  },
+): ParseError => {
+  const props: any = {
+    parseType: options?.parseType ?? 'unknown',
+    message,
+  }
+
+  if (options?.source !== undefined) {
+    props.source = options.source
+  }
+
+  if (options?.cause !== undefined) {
+    props.cause = options.cause
+  }
+
+  if (options?.excerpt !== undefined) {
+    props.excerpt = options.excerpt
+  }
+
+  return new ParseError(props)
+}

package/src/lib/grafaid/parse.test.ts

@@ -0,0 +1,175 @@
+import { Cause, Effect, Exit, Option } from 'effect'
+import { expect, test } from 'vitest'
+import { Grafaid } from './$.js'
+
+test('parseSchema - parses valid GraphQL schema SDL', () => {
+  const sdl = `type Query { hello: String }`
+  const result = Effect.runSync(Grafaid.Parse.parseSchema(sdl))
+  expect(result).toBeDefined()
+  expect(result.kind).toBe('Document')
+  expect(result.definitions).toHaveLength(1)
+})
+
+test('parseSchema - returns ParseError for invalid schema SDL', () => {
+  const invalidSdl = `type Query { hello: String missing_closing_brace`
+  const result = Effect.runSyncExit(Grafaid.Parse.parseSchema(invalidSdl, { source: 'test.graphql' }))
+  expect(Exit.isFailure(result)).toBe(true)
+
+  if (Exit.isFailure(result)) {
+    const error = Cause.failureOption(result.cause)
+    expect(Option.isSome(error)).toBe(true)
+    if (Option.isSome(error)) {
+      expect(error.value).toBeInstanceOf(Grafaid.ParseError)
+      expect(error.value._tag).toBe('ParseError')
+      expect(error.value.parseType).toBe('schema')
+      expect(error.value.source).toBe('test.graphql')
+      expect(error.value.message).toContain('Failed to parse GraphQL schema')
+      expect(error.value.message).toContain('test.graphql')
+    }
+  }
+})
+
+test('parseSchema - includes excerpt in error for parse failures', () => {
+  const invalidSdl = `type Query {
+  hello: String
+  invalid syntax here
+}`
+  const result = Effect.runSyncExit(Grafaid.Parse.parseSchema(invalidSdl))
+  expect(Exit.isFailure(result)).toBe(true)
+
+  if (Exit.isFailure(result)) {
+    const error = Cause.failureOption(result.cause)
+    expect(Option.isSome(error)).toBe(true)
+    if (Option.isSome(error)) {
+      expect(error.value.excerpt).toBeDefined()
+      expect(error.value.excerpt).toContain('Line')
+    }
+  }
+})
+
+test('parseDocument - parses valid GraphQL query document', () => {
+  const query = `query GetUser { user { id name } }`
+  const result = Effect.runSync(Grafaid.Parse.parseDocument(query))
+  expect(result).toBeDefined()
+  expect(result.kind).toBe('Document')
+  expect(result.definitions).toHaveLength(1)
+  expect(result.definitions[0]?.kind).toBe('OperationDefinition')
+})
+
+test('parseDocument - parses anonymous query', () => {
+  const query = `{ user { id name } }`
+  const result = Effect.runSync(Grafaid.Parse.parseDocument(query))
+  expect(result).toBeDefined()
+  expect(result.kind).toBe('Document')
+  expect(result.definitions).toHaveLength(1)
+})
+
+test('parseDocument - returns ParseError for invalid query document', () => {
+  const invalidQuery = `query GetUser { user { id name // invalid comment syntax } }`
+  const result = Effect.runSyncExit(Grafaid.Parse.parseDocument(invalidQuery, { source: 'getUserQuery' }))
+  expect(Exit.isFailure(result)).toBe(true)
+
+  if (Exit.isFailure(result)) {
+    const error = Cause.failureOption(result.cause)
+    expect(Option.isSome(error)).toBe(true)
+    if (Option.isSome(error)) {
+      expect(error.value).toBeInstanceOf(Grafaid.ParseError)
+      expect(error.value._tag).toBe('ParseError')
+      expect(error.value.parseType).toBe('document')
+      expect(error.value.source).toBe('getUserQuery')
+      expect(error.value.message).toContain('Failed to parse GraphQL document')
+    }
+  }
+})
+
+test('parse - auto-detects schema type', () => {
+  const sdl = `type Query { hello: String }`
+  const result = Effect.runSyncExit(Grafaid.Parse.parse(sdl))
+  expect(Exit.isSuccess(result)).toBe(true)
+
+  // Check error for parseType inference
+  const invalidSdl = `type Query { invalid`
+  const errorResult = Effect.runSyncExit(Grafaid.Parse.parse(invalidSdl))
+
+  if (Exit.isFailure(errorResult)) {
+    const error = Cause.failureOption(errorResult.cause)
+    if (Option.isSome(error)) {
+      expect(error.value.parseType).toBe('schema')
+    }
+  }
+})
+
+test('parse - auto-detects document type for query', () => {
+  const query = `query GetUser { user { id } }`
+  const result = Effect.runSyncExit(Grafaid.Parse.parse(query))
+  expect(Exit.isSuccess(result)).toBe(true)
+
+  // Check error for parseType inference
+  const invalidQuery = `query GetUser { invalid`
+  const errorResult = Effect.runSyncExit(Grafaid.Parse.parse(invalidQuery))
+
+  if (Exit.isFailure(errorResult)) {
+    const error = Cause.failureOption(errorResult.cause)
+    if (Option.isSome(error)) {
+      expect(error.value.parseType).toBe('document')
+    }
+  }
+})
+
+test('parse - auto-detects document type for anonymous query', () => {
+  const query = `{ user { id } }`
+  const result = Effect.runSyncExit(Grafaid.Parse.parse(query))
+  expect(Exit.isSuccess(result)).toBe(true)
+
+  // Check error for parseType inference
+  const invalidQuery = `{ invalid`
+  const errorResult = Effect.runSyncExit(Grafaid.Parse.parse(invalidQuery))
+
+  if (Exit.isFailure(errorResult)) {
+    const error = Cause.failureOption(errorResult.cause)
+    if (Option.isSome(error)) {
+      expect(error.value.parseType).toBe('document')
+    }
+  }
+})
+
+test('parse - returns unknown type when unable to infer', () => {
+  const ambiguous = `something that is not clearly schema or document`
+  const errorResult = Effect.runSyncExit(Grafaid.Parse.parse(ambiguous))
+
+  if (Exit.isFailure(errorResult)) {
+    const error = Cause.failureOption(errorResult.cause)
+    if (Option.isSome(error)) {
+      expect(error.value.parseType).toBe('unknown')
+    }
+  }
+})
+
+test.for([
+  { input: 'type Query { field: String }', expectedType: 'schema' },
+  { input: 'interface Node { id: ID! }', expectedType: 'schema' },
+  { input: 'enum Status { ACTIVE }', expectedType: 'schema' },
+  { input: 'scalar Date', expectedType: 'schema' },
+  { input: 'union Result = Success | Error', expectedType: 'schema' },
+  { input: 'input Filter { name: String }', expectedType: 'schema' },
+  { input: 'schema { query: Query }', expectedType: 'schema' },
+  { input: 'extend type Query { extra: String }', expectedType: 'schema' },
+  { input: 'directive @custom on FIELD', expectedType: 'schema' },
+  { input: 'query GetData { field }', expectedType: 'document' },
+  { input: 'mutation UpdateData { field }', expectedType: 'document' },
+  { input: 'subscription OnData { field }', expectedType: 'document' },
+  { input: 'fragment UserFields on User { id }', expectedType: 'document' },
+  { input: '{ field }', expectedType: 'document' },
+  { input: 'random text', expectedType: 'unknown' },
+])('parse - infers parseType "$expectedType" for "$input"', ({ input, expectedType }) => {
+  const errorResult = Effect.runSyncExit(Grafaid.Parse.parse(input))
+
+  // These will all fail to parse, but we're testing the type inference
+  if (Exit.isFailure(errorResult)) {
+    const error = Cause.failureOption(errorResult.cause)
+    expect(Option.isSome(error)).toBe(true)
+    if (Option.isSome(error)) {
+      expect(error.value.parseType).toBe(expectedType)
+    }
+  }
+})

package/src/lib/grafaid/parse.ts

@@ -0,0 +1,165 @@
+import { Effect } from 'effect'
+import { type DocumentNode, Kind, parse as graphqlParse } from 'graphql'
+import { makeParseError, ParseError } from './parse-error.js'
+
+/**
+ * Parse GraphQL source text into an AST.
+ *
+ * This is the centralized parsing function that should be used throughout
+ * the codebase for parsing any GraphQL content (schemas or documents).
+ *
+ * @param source - The GraphQL source text to parse
+ * @param options - Optional parsing configuration
+ * @returns An Effect that yields a DocumentNode AST or fails with ParseError
+ *
+ * @example
+ * ```ts
+ * // Parse a schema
+ * const schemaAst = yield* parse(schemaSDL, {
+ *   parseType: 'schema',
+ *   source: 'schema.graphql'
+ * })
+ *
+ * // Parse a query document
+ * const queryAst = yield* parse(queryString, {
+ *   parseType: 'document',
+ *   source: 'getUserQuery'
+ * })
+ * ```
+ */
+export const parse = (
+  source: string,
+  options?: {
+    /**
+     * The type of content being parsed.
+     * Helps provide better error messages.
+     */
+    parseType?: 'schema' | 'document' | 'unknown'
+
+    /**
+     * Optional source identifier for debugging.
+     * Could be a file path, URL, or descriptive name.
+     */
+    source?: string
+  },
+): Effect.Effect<DocumentNode, ParseError> =>
+  Effect.try({
+    try: () => graphqlParse(source),
+    catch: (error) => {
+      // Extract useful error information
+      let message = 'Failed to parse GraphQL'
+      let excerpt: string | undefined
+
+      if (error instanceof Error) {
+        message = error.message
+
+        // GraphQL parse errors often include location info
+        // Try to extract a meaningful excerpt if possible
+        if ('locations' in error && Array.isArray(error.locations) && error.locations.length > 0) {
+          const location = error.locations[0]
+          if (location && typeof location.line === 'number') {
+            const lines = source.split('\n')
+            const errorLine = lines[location.line - 1]
+            if (errorLine) {
+              excerpt = `Line ${location.line}: ${errorLine.trim()}`
+            }
+          }
+        }
+      }
+
+      const parseType = options?.parseType ?? inferParseType(source)
+
+      const errorOptions: Parameters<typeof makeParseError>[1] = {
+        parseType,
+        cause: error,
+      }
+
+      if (options?.source) {
+        errorOptions.source = options.source
+      }
+
+      if (excerpt) {
+        errorOptions.excerpt = excerpt
+      }
+
+      return makeParseError(
+        `Failed to parse GraphQL ${parseType}${options?.source ? ` from ${options.source}` : ''}: ${message}`,
+        errorOptions,
+      )
+    },
+  })
+
+/**
+ * Parse GraphQL schema SDL with typed errors.
+ *
+ * This is a specialized version of parse() that's explicitly for schemas.
+ *
+ * @param source - The GraphQL schema SDL to parse
+ * @param options - Optional parsing configuration
+ * @returns An Effect that yields a DocumentNode AST or fails with ParseError
+ */
+export const parseSchema = (
+  source: string,
+  options?: {
+    source?: string
+  },
+): Effect.Effect<DocumentNode, ParseError> =>
+  parse(source, {
+    parseType: 'schema',
+    ...options,
+  })
+
+/**
+ * Parse GraphQL document (query/mutation/subscription) with typed errors.
+ *
+ * This is a specialized version of parse() that's explicitly for executable documents.
+ *
+ * @param source - The GraphQL document to parse
+ * @param options - Optional parsing configuration
+ * @returns An Effect that yields a DocumentNode AST or fails with ParseError
+ */
+export const parseDocument = (
+  source: string,
+  options?: {
+    source?: string
+  },
+): Effect.Effect<DocumentNode, ParseError> =>
+  parse(source, {
+    parseType: 'document',
+    ...options,
+  })
+
+/**
+ * Try to infer whether the source is a schema or document.
+ * This is a best-effort heuristic and may not always be accurate.
+ */
+const inferParseType = (source: string): 'schema' | 'document' | 'unknown' => {
+  // Common schema definition keywords
+  const schemaKeywords = /^\s*(type|interface|enum|scalar|union|input|schema|extend|directive)\s+/m
+  // Common document keywords
+  const documentKeywords = /^\s*(query|mutation|subscription|fragment)\s+/m
+
+  if (schemaKeywords.test(source)) {
+    return 'schema'
+  }
+
+  if (documentKeywords.test(source)) {
+    return 'document'
+  }
+
+  // Check for anonymous query syntax { ... }
+  if (/^\s*\{/.test(source)) {
+    return 'document'
+  }
+
+  return 'unknown'
+}
+
+/**
+ * Create an empty DocumentNode.
+ * Useful for representing an absence of GraphQL content.
+ */
+export const empty: DocumentNode = {
+  definitions: [],
+  kind: Kind.DOCUMENT,
+}

package/src/lib/grafaid/schema/ast.ts

@@ -1,12 +1,4 @@
-import { Effect } from 'effect'
-import { type DocumentNode, Kind, parse as graphqlParse } from 'graphql'
-
-// Effect-based version of parse
-export const parse = (source: string): Effect.Effect<DocumentNode, Error> =>
-  Effect.try({
-    try: () => graphqlParse(source),
-    catch: (error) => new Error(`Failed to parse GraphQL: ${error}`),
-  })
+import { type DocumentNode, Kind } from 'graphql'
 
 export { type DocumentNode as Document } from 'graphql'
 

package/src/lib/grafaid/schema/read.ts

@@ -2,7 +2,7 @@ import { FileSystem } from '@effect/platform/FileSystem'
 import { Fs } from '@wollybeard/kit'
 import { Effect } from 'effect'
 import { type GraphQLSchema } from 'graphql'
-import * as AST from './ast.js'
+import * as Parse from '../parse.js'
 import { fromAST } from './schema.js'
 
 export const read = (sdlFilePath: string): Effect.Effect<null | Fs.File<GraphQLSchema>, Error, FileSystem> =>
@@ -19,7 +19,7 @@ export const read = (sdlFilePath: string): Effect.Effect<null | Fs.File<GraphQLS
     const content = yield* fs.readFileString(sdlFilePath)
 
     // Parse and build schema
-    const node = yield* AST.parse(content)
+    const node = yield* Parse.parseSchema(content, { source: sdlFilePath })
     const schema = yield* fromAST(node)
 
     return {

package/src/lib/grafaid/schema/schema.ts

@@ -1,5 +1,6 @@
 import { Effect } from 'effect'
 import { buildASTSchema, type GraphQLSchema } from 'graphql'
+import { makeParseError, ParseError } from '../parse-error.js'
 
 export {
   buildClientSchema as fromIntrospectionQuery,
@@ -9,10 +10,17 @@ export {
 } from 'graphql'
 
 // Effect-based version of fromAST
-export const fromAST = (ast: AST.Document): Effect.Effect<GraphQLSchema, Error> =>
+export const fromAST = (ast: AST.Document): Effect.Effect<GraphQLSchema, ParseError> =>
   Effect.try({
     try: () => buildASTSchema(ast),
-    catch: (error) => new Error(`Failed to build schema from AST: ${error}`),
+    catch: (error) =>
+      makeParseError(
+        `Failed to build schema from AST: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          parseType: 'schema',
+          cause: error,
+        },
+      ),
   })
 
 export * as AST from './ast.js'

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

@@ -59,24 +59,16 @@ export const load = (source: SchemaPointer): Effect.Effect<Grafaid.Schema.Schema
             catch: (error) => new Error(`Failed to read response text: ${error}`),
           })
 
-          const ast = yield* Grafaid.Schema.AST.parse(sdlContent).pipe(
-            Effect.mapError((error) => new Error(`Failed to parse SDL from ${source.pathOrUrl}: ${error}`)),
-          )
-          return yield* Grafaid.Schema.fromAST(ast).pipe(
-            Effect.mapError((error) => new Error(`Failed to build schema from ${source.pathOrUrl}: ${error}`)),
-          )
+          const ast = yield* Grafaid.Parse.parseSchema(sdlContent, { source: source.pathOrUrl })
+          return yield* Grafaid.Schema.fromAST(ast)
         } else {
           const fs = yield* FileSystem
           const sdlContent = yield* fs.readFileString(source.pathOrUrl).pipe(
             Effect.mapError((error) => new Error(`Failed to read SDL from ${source.pathOrUrl}: ${error}`)),
           )
 
-          const ast = yield* Grafaid.Schema.AST.parse(sdlContent).pipe(
-            Effect.mapError((error) => new Error(`Failed to parse SDL from ${source.pathOrUrl}: ${error}`)),
-          )
-          return yield* Grafaid.Schema.fromAST(ast).pipe(
-            Effect.mapError((error) => new Error(`Failed to build schema from ${source.pathOrUrl}: ${error}`)),
-          )
+          const ast = yield* Grafaid.Parse.parseSchema(sdlContent, { source: source.pathOrUrl })
+          return yield* Grafaid.Schema.fromAST(ast)
         }
       }
       case `name`: {

package/src/lib/path-map/$.test.ts

@@ -258,22 +258,37 @@ describe('PathMap', () => {
 
     it('absolute paths always start with base', () => {
       fc.assert(
-        fc.property(pathInput, fc.string({ minLength: 1 }).filter(s => s.startsWith('/')), (input, base) => {
-          const paths = PathMap.create(input, base)
-          const normalizedBase = normalizeBasePath(base)
-
-          function checkAbsolute(obj: any) {
-            for (const [key, value] of Object.entries(obj)) {
-              if (typeof value === 'string') {
-                expect(value.startsWith(normalizedBase)).toBe(true)
-              } else if (typeof value === 'object') {
-                checkAbsolute(value)
+        fc.property(
+          pathInput,
+          fc.string({ minLength: 1 })
+            .filter(s => s.startsWith('/'))
+            // Exclude paths with .. segments as Path.join will resolve them
+            .filter(s => !s.includes('..')),
+          (input, base) => {
+            const paths = PathMap.create(input, base)
+            const normalizedBase = normalizeBasePath(base)
+
+            function checkAbsolute(obj: any) {
+              for (const [key, value] of Object.entries(obj)) {
+                if (typeof value === 'string') {
+                  // Path.join resolves .. segments, so we need to resolve the base too
+                  const resolvedBase = Path.resolve(normalizedBase)
+                  const resolvedValue = Path.resolve(value)
+                  // Check that the resolved absolute path starts with resolved base
+                  // or that both resolve to root
+                  expect(
+                    resolvedValue.startsWith(resolvedBase)
+                      || (resolvedBase === '/' && resolvedValue.startsWith('/')),
+                  ).toBe(true)
+                } else if (typeof value === 'object') {
+                  checkAbsolute(value)
+                }
               }
             }
-          }
 
-          checkAbsolute(paths.absolute)
-        }),
+            checkAbsolute(paths.absolute)
+          },
+        ),
       )
     })
 

package/src/template/components/ExampleLink.tsx

@@ -12,8 +12,10 @@ export interface Props {
  * Always includes the version query parameter for consistent behavior.
  */
 export const ExampleLink: FC<Props> = ({ exampleRef }) => {
-  // Always include version parameter for consistency
-  const href = `/examples/${exampleRef.name}?version=${Version.encodeSync(exampleRef.version)}`
+  // Include version parameter only if version exists
+  const href = exampleRef.version
+    ? `/examples/${exampleRef.name}?version=${Version.encodeSync(exampleRef.version)}`
+    : `/examples/${exampleRef.name}`
 
   return (
     <Link href={href} style={{ textDecoration: 'none' }}>

package/src/template/components/NamedType.tsx

@@ -59,7 +59,9 @@ export const NamedType: FC<Props> = ({ data }) => {
           <Box style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
             {[...examples].map((exampleRef) => (
               <ExampleLink
-                key={`${exampleRef.name}-${Version.encodeSync(exampleRef.version)}`}
+                key={`${exampleRef.name}-${
+                  exampleRef.version ? Version.encodeSync(exampleRef.version) : 'unversioned'
+                }`}
                 exampleRef={exampleRef}
               />
             ))}

package/src/template/components/VersionCoveragePicker.tsx

@@ -26,6 +26,12 @@ export const VersionCoveragePicker: FC<Props> = ({
   const options = Array.from(HashMap.keys(document.versionDocuments))
   if (options.length === 0) return null
 
+  // Helper to format labels with proper Version/Versions prefix
+  const formatLabel = (versionCoverage: VersionCoverage.VersionCoverage): string => {
+    const prefix = VersionCoverage.isSingle(versionCoverage) ? 'Version' : 'Versions'
+    return `${prefix} ${VersionCoverage.toLabel(versionCoverage)}`
+  }
+
   return (
     <Select.Root
       value={VersionCoverage.toLabel(current)}
@@ -39,7 +45,7 @@ export const VersionCoveragePicker: FC<Props> = ({
       }}
     >
       <Select.Trigger>
-        {VersionCoverage.toLabel(current)}
+        {formatLabel(current)}
       </Select.Trigger>
       <Select.Content position='popper' sideOffset={5}>
         {options.map(selection => (
@@ -47,7 +53,7 @@ export const VersionCoveragePicker: FC<Props> = ({
             key={VersionCoverage.toLabel(selection)}
             value={VersionCoverage.toLabel(selection)}
           >
-            {VersionCoverage.toLabel(selection)}
+            {formatLabel(selection)}
           </Select.Item>
         ))}
       </Select.Content>