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

package/src/api/examples/type-usage-indexer.test.ts

@@ -0,0 +1,276 @@
+import { Catalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { Schema } from '#lib/schema/$'
+import { Version } from '#lib/version/$'
+import { HashMap, HashSet, Schema as S } from 'effect'
+import { buildSchema } from 'graphql'
+import { describe, expect, test } from 'vitest'
+import { Example } from './schemas/example/example.js'
+import * as ExampleReferenceModule from './schemas/type-usage-index.js'
+import { createTypeUsageIndex, getExampleReferencesForType } from './type-usage-indexer.js'
+
+describe('type-usage-indexer', () => {
+  const schemaString = `
+    type Query {
+      user(id: ID!): User
+      users: [User!]!
+      product(id: ID!): Product
+    }
+
+    type User {
+      id: ID!
+      name: String!
+      email: String!
+    }
+
+    type Product {
+      id: ID!
+      name: String!
+      price: Float!
+    }
+
+    interface Node {
+      id: ID!
+    }
+
+    union SearchResult = User | Product
+  `
+
+  const schemaDef = buildSchema(schemaString)
+  const version1 = Version.decodeSync('1.0.0')
+  const version2 = Version.decodeSync('2.0.0')
+
+  describe('createTypeUsageIndex', () => {
+    test('indexes unversioned examples', () => {
+      const example = Example.make({
+        name: 'get-user',
+        path: 'examples/get-user.graphql',
+        document: Document.Unversioned.make({
+          document: 'query { user(id: "1") { id name } }',
+        }),
+      })
+
+      const catalog = Catalog.Unversioned.make({
+        schema: Schema.Unversioned.make({
+          definition: schemaDef,
+          revisions: [],
+        }),
+      })
+
+      const index = createTypeUsageIndex([example], catalog)
+
+      // For unversioned examples, they get indexed with the latest version (1.0.0 default)
+      const defaultVersion = Version.decodeSync('1.0.0')
+
+      // Should index Query and User types
+      const queryRefs = getExampleReferencesForType(index, 'Query')
+      const userRefs = getExampleReferencesForType(index, 'User')
+
+      expect(HashSet.size(queryRefs)).toBe(1)
+      expect([...queryRefs][0]).toEqual({ name: 'get-user', version: defaultVersion })
+
+      expect(HashSet.size(userRefs)).toBe(1)
+      expect([...userRefs][0]).toEqual({ name: 'get-user', version: defaultVersion })
+
+      // Should not index Product type (not used)
+      const productRefs = getExampleReferencesForType(index, 'Product')
+      expect(HashSet.size(productRefs)).toBe(0)
+    })
+
+    test('indexes versioned examples', () => {
+      const example = Example.make({
+        name: 'get-user-versioned',
+        path: 'examples/get-user-versioned.graphql',
+        document: Document.Versioned.make({
+          versionDocuments: HashMap.make(
+            [version1, 'query { user(id: "1") { id } }'],
+            [version2, 'query { user(id: "1") { id name email } }'],
+          ),
+        }),
+      })
+
+      const catalog = Catalog.Versioned.make({
+        entries: HashMap.make(
+          [
+            version1,
+            Schema.Versioned.make({
+              version: version1,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+          [
+            version2,
+            Schema.Versioned.make({
+              version: version2,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+        ),
+      })
+
+      const index = createTypeUsageIndex([example], catalog)
+
+      // Check version 1 references
+      const userRefsV1 = getExampleReferencesForType(index, 'User', version1)
+      expect(HashSet.size(userRefsV1)).toBe(1)
+      expect([...userRefsV1][0]).toEqual({ name: 'get-user-versioned', version: version1 })
+
+      // Check version 2 references
+      const userRefsV2 = getExampleReferencesForType(index, 'User', version2)
+      expect(HashSet.size(userRefsV2)).toBe(1)
+      expect([...userRefsV2][0]).toEqual({ name: 'get-user-versioned', version: version2 })
+    })
+
+    test('deduplicates example references using HashSet', () => {
+      // Create two examples that use the same types
+      const example1 = Example.make({
+        name: 'get-user-1',
+        path: 'examples/get-user-1.graphql',
+        document: Document.Unversioned.make({
+          document: 'query { user(id: "1") { id name } }',
+        }),
+      })
+
+      const example2 = Example.make({
+        name: 'get-user-2',
+        path: 'examples/get-user-2.graphql',
+        document: Document.Unversioned.make({
+          document: 'query { user(id: "2") { id name } }',
+        }),
+      })
+
+      const catalog = Catalog.Unversioned.make({
+        schema: Schema.Unversioned.make({
+          definition: schemaDef,
+          revisions: [],
+        }),
+      })
+
+      const index = createTypeUsageIndex([example1, example2], catalog)
+
+      // For unversioned examples with unversioned catalog, use default version
+      const defaultVersion = Version.decodeSync('1.0.0')
+
+      // Both examples should be indexed for User type
+      const userRefs = getExampleReferencesForType(index, 'User')
+      expect(HashSet.size(userRefs)).toBe(2)
+
+      const refNames = [...userRefs].map(ref => ref.name).sort()
+      expect(refNames).toEqual(['get-user-1', 'get-user-2'])
+
+      // All should have the same version
+      for (const ref of userRefs) {
+        expect(ref.version).toEqual(defaultVersion)
+      }
+    })
+
+    test('handles interface and union types', () => {
+      const example = Example.make({
+        name: 'search',
+        path: 'examples/search.graphql',
+        document: Document.Unversioned.make({
+          document: `
+            query {
+              user(id: "1") {
+                ... on Node {
+                  id
+                }
+              }
+            }
+          `,
+        }),
+      })
+
+      const catalog = Catalog.Unversioned.make({
+        schema: Schema.Unversioned.make({
+          definition: schemaDef,
+          revisions: [],
+        }),
+      })
+
+      const index = createTypeUsageIndex([example], catalog)
+
+      // For unversioned example with unversioned catalog
+      const defaultVersion = Version.decodeSync('1.0.0')
+
+      // Should index the Node interface
+      const nodeRefs = getExampleReferencesForType(index, 'Node')
+      expect(HashSet.size(nodeRefs)).toBe(1)
+      expect([...nodeRefs][0]).toEqual({ name: 'search', version: defaultVersion })
+    })
+
+    test('indexes examples with version sets', () => {
+      // Create a versioned document where multiple versions share the same document
+      const versionSet = HashSet.make(version1, version2)
+      const example = Example.make({
+        name: 'shared-example',
+        path: 'examples/shared.graphql',
+        document: Document.Versioned.make({
+          versionDocuments: HashMap.make(
+            [versionSet, 'query { user(id: "1") { id name } }'],
+          ),
+        }),
+      })
+
+      const catalog = Catalog.Versioned.make({
+        entries: HashMap.make(
+          [
+            version1,
+            Schema.Versioned.make({
+              version: version1,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+          [
+            version2,
+            Schema.Versioned.make({
+              version: version2,
+              definition: schemaDef,
+              branchPoint: null,
+              revisions: [],
+            }),
+          ],
+        ),
+      })
+
+      const index = createTypeUsageIndex([example], catalog)
+
+      // Both versions should have the same example reference
+      const userRefsV1 = getExampleReferencesForType(index, 'User', version1)
+      expect(HashSet.size(userRefsV1)).toBe(1)
+      expect([...userRefsV1][0]).toEqual({ name: 'shared-example', version: version1 })
+
+      const userRefsV2 = getExampleReferencesForType(index, 'User', version2)
+      expect(HashSet.size(userRefsV2)).toBe(1)
+      expect([...userRefsV2][0]).toEqual({ name: 'shared-example', version: version2 })
+    })
+  })
+
+  describe('ExampleReference', () => {
+    test('ExampleReference structural equality works with HashSet', () => {
+      // Use the Schema's make constructor to create Data instances with proper Equal/Hash support
+      const version = Version.decodeSync('1.0.0')
+
+      const ref1 = ExampleReferenceModule.ExampleReference.make({ name: 'example1', version })
+      const ref2 = ExampleReferenceModule.ExampleReference.make({ name: 'example1', version })
+      const ref3 = ExampleReferenceModule.ExampleReference.make({ name: 'example2', version })
+
+      // Create a HashSet and add references
+      let set = HashSet.empty<ExampleReferenceModule.ExampleReference>()
+      set = HashSet.add(set, ref1)
+      set = HashSet.add(set, ref2) // Should not increase size (duplicate)
+      set = HashSet.add(set, ref3)
+
+      // Should have only 2 unique references
+      expect(HashSet.size(set)).toBe(2)
+      expect(HashSet.has(set, ExampleReferenceModule.ExampleReference.make({ name: 'example1', version }))).toBe(true)
+      expect(HashSet.has(set, ExampleReferenceModule.ExampleReference.make({ name: 'example2', version }))).toBe(true)
+    })
+  })
+})

package/src/api/examples/type-usage-indexer.ts

@@ -0,0 +1,291 @@
+import { Catalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { Schema } from '#lib/schema/$'
+import { Version } from '#lib/version/$'
+import { HashMap, HashSet, Option } from 'effect'
+import { Schema as S } from 'effect'
+import {
+  type DocumentNode,
+  getNamedType,
+  type GraphQLSchema,
+  isInterfaceType,
+  isObjectType,
+  isUnionType,
+  Kind,
+  parse,
+  visit,
+} from 'graphql'
+import type { Example } from './schemas/example/example.js'
+import { ExampleReference, type TypeUsageIndex, UNVERSIONED_KEY, type VersionKey } from './schemas/type-usage-index.js'
+
+// ============================================================================
+// Type Extraction
+// ============================================================================
+
+/**
+ * Extract all named types referenced in a GraphQL document.
+ *
+ * This includes:
+ * - Types referenced in fields
+ * - Types referenced in fragments (inline and spreads)
+ * - For interfaces: both the interface and all implementations
+ * - For unions: both the union and all member types
+ */
+const extractTypesFromQuery = (
+  documentString: string,
+  schema: GraphQLSchema,
+): Set<string> => {
+  const types = new Set<string>()
+  const visitedTypes = new Set<string>() // Prevent infinite recursion
+
+  let ast: DocumentNode
+  try {
+    ast = parse(documentString)
+  } catch {
+    // If parsing fails, return empty set
+    return types
+  }
+
+  // Helper to add a type and its related types
+  const addType = (typeName: string) => {
+    if (visitedTypes.has(typeName)) return
+    visitedTypes.add(typeName)
+    types.add(typeName)
+
+    const type = schema.getType(typeName)
+    if (!type) return
+
+    // If interface, add all implementations
+    if (isInterfaceType(type)) {
+      const implementations = schema.getImplementations(type)
+      for (const impl of implementations.objects) {
+        types.add(impl.name)
+      }
+      for (const impl of implementations.interfaces) {
+        types.add(impl.name)
+      }
+    } // If union, add all member types
+    else if (isUnionType(type)) {
+      for (const member of type.getTypes()) {
+        types.add(member.name)
+      }
+    }
+  }
+
+  // Helper to resolve field type from selection
+  const resolveFieldType = (
+    fieldName: string,
+    parentTypeName: string | null,
+  ): string | null => {
+    if (!parentTypeName) return null
+
+    const parentType = schema.getType(parentTypeName)
+    if (!parentType || !isObjectType(parentType) && !isInterfaceType(parentType)) {
+      return null
+    }
+
+    const field = parentType.getFields()[fieldName]
+    if (!field) return null
+
+    const namedType = getNamedType(field.type)
+    return namedType.name
+  }
+
+  // Track the current type context as we traverse
+  let currentType: string | null = null
+
+  visit(ast, {
+    [Kind.OPERATION_DEFINITION]: (node) => {
+      // Set initial type based on operation
+      switch (node.operation) {
+        case 'query':
+          currentType = schema.getQueryType()?.name ?? null
+          break
+        case 'mutation':
+          currentType = schema.getMutationType()?.name ?? null
+          break
+        case 'subscription':
+          currentType = schema.getSubscriptionType()?.name ?? null
+          break
+      }
+      if (currentType) {
+        addType(currentType)
+      }
+    },
+
+    [Kind.FIELD]: {
+      enter(node) {
+        if (!currentType) return
+
+        // Special handling for __typename
+        if (node.name.value === '__typename') return
+
+        const fieldType = resolveFieldType(node.name.value, currentType)
+        if (fieldType) {
+          addType(fieldType)
+          // Update context for nested selections
+          if (node.selectionSet) {
+            currentType = fieldType
+          }
+        }
+      },
+      leave(node) {
+        // Restore parent context when leaving field with selection set
+        if (node.selectionSet && currentType) {
+          // This is simplified - in production would need proper context stack
+        }
+      },
+    },
+
+    [Kind.INLINE_FRAGMENT]: (node) => {
+      if (node.typeCondition) {
+        const typeName = node.typeCondition.name.value
+        addType(typeName)
+        currentType = typeName
+      }
+    },
+
+    [Kind.FRAGMENT_SPREAD]: (node) => {
+      // Fragment spreads reference fragment definitions which have their own type
+      // In a full implementation, we'd look up the fragment definition
+    },
+
+    [Kind.FRAGMENT_DEFINITION]: (node) => {
+      const typeName = node.typeCondition.name.value
+      addType(typeName)
+      currentType = typeName
+    },
+  })
+
+  return types
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Get a schema by version from the catalog.
+ */
+const getSchemaByVersion = (
+  catalog: Catalog.Catalog,
+  version: Version.Version,
+): Schema.Schema | undefined => {
+  if (Catalog.Versioned.is(catalog)) {
+    // Use HashMap.get for O(1) lookup
+    return HashMap.get(catalog.entries, version).pipe(Option.getOrElse(() => undefined))
+  }
+  // For unversioned catalog, return the single schema if version matches
+  if (Catalog.Unversioned.is(catalog)) {
+    // Unversioned catalogs don't have versions, so we can't match
+    return undefined
+  }
+  return undefined
+}
+
+// ============================================================================
+// Index Creation
+// ============================================================================
+
+/**
+ * Create a type usage index from examples and schemas.
+ *
+ * Processes all examples and their documents (versioned or unversioned)
+ * to build an index of which types are used in which examples.
+ */
+export const createTypeUsageIndex = (
+  examples: readonly Example[],
+  schemasCatalog: Catalog.Catalog,
+): TypeUsageIndex => {
+  let index = HashMap.empty<VersionKey, HashMap.HashMap<string, HashSet.HashSet<ExampleReference>>>()
+
+  for (const example of examples) {
+    // Process based on document type
+    if (Document.Unversioned.is(example.document)) {
+      // Unversioned document
+      const schema = Catalog.getLatest(schemasCatalog)
+      const types = extractTypesFromQuery(example.document.document, schema.definition)
+
+      for (const typeName of types) {
+        // For unversioned, use the latest version from the catalog
+        const latestVersion = Catalog.getLatestVersion(schemasCatalog) ?? Version.fromString('1.0.0')
+        index = addExampleToIndex(index, UNVERSIONED_KEY, typeName, example, latestVersion)
+      }
+    } else if (Document.Versioned.is(example.document)) {
+      // Versioned document - process each version covered
+      const allVersions = Document.Versioned.getAllVersions(example.document)
+
+      for (const version of allVersions) {
+        const schema = getSchemaByVersion(schemasCatalog, version)
+        if (!schema) continue
+
+        const documentString = Document.Versioned.getContentForVersion(example.document, version)
+        if (!documentString) continue
+
+        const types = extractTypesFromQuery(documentString, schema.definition)
+
+        for (const typeName of types) {
+          index = addExampleToIndex(index, version, typeName, example, version)
+        }
+      }
+    }
+  }
+
+  return index
+}
+
+/**
+ * Helper to add an example to the index for a specific version and type.
+ */
+const addExampleToIndex = (
+  index: TypeUsageIndex,
+  versionKey: VersionKey,
+  typeName: string,
+  example: Example,
+  version: Version.Version,
+): TypeUsageIndex => {
+  // Create lightweight reference using the schema's make constructor
+  const exampleRef = ExampleReference.make({ name: example.name, version })
+
+  // Get or create the version's type map
+  const versionMap = HashMap.get(index, versionKey).pipe(
+    Option.getOrElse(HashMap.empty<string, HashSet.HashSet<S.Schema.Type<typeof ExampleReference>>>),
+  )
+
+  // Get or create the type's example set
+  const examples = HashMap.get(versionMap, typeName).pipe(
+    Option.getOrElse(HashSet.empty<S.Schema.Type<typeof ExampleReference>>),
+  )
+
+  // Add example reference to set (HashSet handles deduplication automatically)
+  const updatedExamples = HashSet.add(examples, exampleRef)
+
+  // Update both maps immutably
+  const updatedVersionMap = HashMap.set(
+    versionMap,
+    typeName,
+    updatedExamples,
+  )
+
+  return HashMap.set(index, versionKey, updatedVersionMap)
+}
+
+// ============================================================================
+// Query Functions
+// ============================================================================
+
+/**
+ * Get example references that use a specific type in a specific version.
+ */
+export const getExampleReferencesForType = (
+  typeUsageIndex: TypeUsageIndex,
+  typeName: string,
+  version: Version.Version | null = null,
+): HashSet.HashSet<S.Schema.Type<typeof ExampleReference>> => {
+  const versionKey = version ?? UNVERSIONED_KEY
+
+  return HashMap.get(typeUsageIndex, versionKey).pipe(
+    Option.flatMap(versionMap => HashMap.get(versionMap, typeName)),
+    Option.getOrElse(HashSet.empty<S.Schema.Type<typeof ExampleReference>>),
+  )
+}

package/src/api/iso/schema/routing.ts

@@ -40,7 +40,7 @@ export const createReferenceVersionPath = (version?: Version.Version): string =>
   if (version === undefined) return ''
   // VERSION_LATEST is not used with the Version type anymore
   // Just use the version string directly
-  return `/${segmentLiterals.version}/${Version.toString(version)}`
+  return `/${segmentLiterals.version}/${Version.encodeSync(version)}`
 }
 
 export const joinSegmentsAndPaths = (
@@ -153,7 +153,7 @@ export const createChangelogUrl = (revisionDate: string, schema: Schema.Schema):
   // Create base changelog path with version if needed
   const version = Schema.getVersion(schema)
   const changelogBase = version
-    ? joinSegmentsAndPaths(segmentLiterals.changelog, segmentLiterals.version, Version.toString(version))
+    ? joinSegmentsAndPaths(segmentLiterals.changelog, segmentLiterals.version, Version.encodeSync(version))
     : `/${segmentLiterals.changelog}`
 
   // Add anchor for the specific date

package/src/api/project/$.ts

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

package/src/api/schema/$.test.ts

@@ -3,7 +3,7 @@ import { Catalog } from '#lib/catalog/$'
 import { Grafaid } from '#lib/grafaid'
 import { MemoryFilesystem } from '#lib/memory-filesystem/$'
 import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
-import { Effect } from 'effect'
+import { Effect, HashMap } from 'effect'
 import { expect } from 'vitest'
 import { Test } from '../../../tests/unit/helpers/test.js'
 import { Schema } from './$.js'
@@ -421,7 +421,7 @@ testWithFileSystem<BaseTestCase & {
         expect(result!._tag).toBe('CatalogVersioned')
         if (expected.versionCount !== undefined) {
           const versioned = result as Catalog.Versioned.Versioned
-          expect(versioned.entries.length).toBe(expected.versionCount)
+          expect(HashMap.size(versioned.entries)).toBe(expected.versionCount)
         }
       } else {
         expect(result!._tag).toBe('CatalogUnversioned')

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

@@ -10,7 +10,7 @@ import { debugPolen } from '#singletons/debug'
 import { PlatformError } from '@effect/platform/Error'
 import { FileSystem } from '@effect/platform/FileSystem'
 import { Arr, Path } from '@wollybeard/kit'
-import { Effect } from 'effect'
+import { Effect, HashMap } from 'effect'
 import type { GraphQLSchema } from 'graphql'
 
 const debug = debugPolen.sub(`schema:data-source-versioned-schema-directory`)
@@ -247,7 +247,7 @@ export const readOrThrow = (
     // Build a map of versions for parent lookups
     const versionMap = new Map<string, typeof versions[0]>()
     for (const version of versions) {
-      versionMap.set(Version.toString(version.version), version)
+      versionMap.set(Version.encodeSync(version.version), version)
     }
 
     // Create catalog entries for each version
@@ -257,7 +257,7 @@ export const readOrThrow = (
           // Get parent schema for first revision comparison if this is a branched version
           let parentSchemaForComparison: GraphQLSchema | null = null
           if (version.parentVersion && version.branchDate) {
-            const parentVersionStr = Version.toString(version.parentVersion)
+            const parentVersionStr = Version.encodeSync(version.parentVersion)
             const parentVersionData = versionMap.get(parentVersionStr)
             if (parentVersionData) {
               const matchingRevisionIndex = parentVersionData.revisions.findIndex(
@@ -301,14 +301,14 @@ export const readOrThrow = (
             { concurrency: 1 }, // Sequential for correct changeset calculation
           )
 
-          // Get the latest schema definition
+          // Get the latest schema definition (last element since revisions are still in chronological order)
           const latestRevision = version.revisions[version.revisions.length - 1]
           const schemaDefinition = latestRevision?.schema ?? Grafaid.Schema.empty
 
           // Find parent schema based on parentVersion and branchDate
           let parentSchema: Schema.Versioned.Versioned | null = null
           if (version.parentVersion) {
-            const parentVersionStr = Version.toString(version.parentVersion)
+            const parentVersionStr = Version.encodeSync(version.parentVersion)
             const parentVersionData = versionMap.get(parentVersionStr)
 
             if (parentVersionData) {
@@ -393,9 +393,14 @@ export const readOrThrow = (
     // Reverse to have newest first
     catalogEntries.reverse()
 
+    // Convert array to HashMap with version as key
+    const entriesMap = HashMap.fromIterable(
+      catalogEntries.map(entry => [entry.version, entry] as const),
+    )
+
     debug(`computed ${catalogEntries.length} entries`)
     return Catalog.Versioned.make({
-      entries: catalogEntries,
+      entries: entriesMap,
     })
   })
 

package/src/api/schema/load.ts

@@ -142,7 +142,7 @@ export const loadOrNull = (
       const catalog = loadedSchema.data as Catalog.Catalog
       Catalog.fold(
         (versioned) => {
-          for (const schema of versioned.entries) {
+          for (const schema of Catalog.Versioned.getAll(versioned)) {
             Augmentations.apply(schema.definition, augmentations)
           }
         },

package/src/api/typings/$$.ts

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

package/src/api/typings/$.ts

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