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

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

@@ -0,0 +1,294 @@
+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)) {
+    // Find the schema with matching version
+    return catalog.entries.find(entry =>
+      Schema.Versioned.is(entry)
+      && Version.equivalence(entry.version, version)
+    )
+  }
+  // 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.getLatestSchema(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.getLatestVersionIdentifier(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/input-sources/versioned-directory.ts

@@ -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) {

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'

package/src/api/typings/typings.ts

@@ -0,0 +1,273 @@
+import type { Config } from '#api/config/normalized'
+import { FileSystem } from '@effect/platform'
+import { Effect } from 'effect'
+import * as Path from 'node:path'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface TypeDefinition {
+  /**
+   * The name of the type definition file (without .d.ts extension).
+   * Will be placed under @types/polen-generated/{name}.d.ts
+   */
+  name: string
+  /**
+   * The TypeScript type definition content.
+   */
+  content: string
+}
+
+export interface WriterOptions {
+  /**
+   * The root directory where node_modules exists.
+   * Usually the project root.
+   */
+  projectRoot: string
+}
+
+export interface WriterOptionsWithConfig {
+  /**
+   * The normalized Polen configuration.
+   * The generated types path will be extracted from config.paths.framework.generatedTypes
+   */
+  config: Config
+}
+
+// ============================================================================
+// Paths
+// ============================================================================
+
+export const relativePathGeneratedTypesDir = 'node_modules/@types/polen-generated'
+
+/**
+ * Get the output directory for generated type definitions.
+ */
+export const getGeneratedTypesDir = (projectRoot: string): string => {
+  return Path.join(projectRoot, relativePathGeneratedTypesDir)
+}
+
+/**
+ * Get the full path for a generated type definition file.
+ */
+export const getGeneratedTypePath = (projectRoot: string, name: string): string => {
+  return Path.join(getGeneratedTypesDir(projectRoot), `${name}.d.ts`)
+}
+
+// ============================================================================
+// Package Structure
+// ============================================================================
+
+/**
+ * Ensure the package structure exists for @types/polen-generated.
+ * Creates package.json and index.d.ts if they don't exist.
+ */
+const ensurePackageStructure = (
+  options: WriterOptions,
+): Effect.Effect<void, Error, FileSystem.FileSystem> => {
+  const outputDir = getGeneratedTypesDir(options.projectRoot)
+  const packageJsonPath = Path.join(outputDir, 'package.json')
+  const indexPath = Path.join(outputDir, 'index.d.ts')
+
+  return Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    // Ensure output directory exists
+    yield* fs.makeDirectory(outputDir, { recursive: true })
+
+    // Check if package.json exists
+    const packageJsonExists = yield* fs.exists(packageJsonPath)
+
+    if (!packageJsonExists) {
+      const packageJson = {
+        name: '@types/polen-generated',
+        version: '0.0.0',
+        type: 'module',
+        exports: {
+          '.': {
+            import: './index.d.ts',
+          },
+        },
+      }
+      yield* fs.writeFileString(packageJsonPath, JSON.stringify(packageJson, null, 2))
+    }
+
+    // Check if index.d.ts exists
+    const indexExists = yield* fs.exists(indexPath)
+
+    if (!indexExists) {
+      const indexContent = `// Auto-generated index file for @types/polen-generated
+// This file is automatically managed by Polen
+// Do not edit this file directly
+
+// This file exists to satisfy TypeScript's module resolution
+// Individual type definition files are placed alongside this index
+export {}
+`
+      yield* fs.writeFileString(indexPath, indexContent)
+    }
+  })
+}
+
+// ============================================================================
+// Writer
+// ============================================================================
+
+/**
+ * Write a TypeScript type definition to the generated types directory.
+ *
+ * @example
+ * ```ts
+ * await Effect.runPromise(
+ *   Typings.write(
+ *     { name: 'config.examples', content: 'declare global { ... }' },
+ *     { projectRoot: '/path/to/project' }
+ *   ).pipe(Effect.provide(FileSystem.layer))
+ * )
+ * ```
+ */
+export const write = (
+  definition: TypeDefinition,
+  options: WriterOptions,
+): Effect.Effect<void, Error, FileSystem.FileSystem> => {
+  const outputDir = getGeneratedTypesDir(options.projectRoot)
+  const outputFile = getGeneratedTypePath(options.projectRoot, definition.name)
+
+  return Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    // Ensure package structure exists (package.json and index.d.ts)
+    yield* ensurePackageStructure(options)
+
+    // Write the type definition file
+    yield* fs.writeFileString(outputFile, definition.content)
+  })
+}
+
+/**
+ * Write multiple TypeScript type definitions.
+ */
+export const writeMany = (
+  definitions: TypeDefinition[],
+  options: WriterOptions,
+): Effect.Effect<void, Error, FileSystem.FileSystem> => {
+  return Effect.gen(function*() {
+    // Ensure package structure once before writing all definitions
+    yield* ensurePackageStructure(options)
+
+    // Write all definitions without re-checking package structure
+    const fs = yield* FileSystem.FileSystem
+
+    for (const definition of definitions) {
+      const outputFile = getGeneratedTypePath(options.projectRoot, definition.name)
+      yield* fs.writeFileString(outputFile, definition.content)
+    }
+  })
+}
+
+/**
+ * Remove a generated type definition file.
+ */
+export const remove = (
+  name: string,
+  options: WriterOptions,
+): Effect.Effect<void, Error, FileSystem.FileSystem> => {
+  const outputFile = getGeneratedTypePath(options.projectRoot, name)
+
+  return Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    // Try to remove the file, ignore if it doesn't exist
+    yield* fs.remove(outputFile).pipe(
+      Effect.catchIf(
+        error => (error as any).code === 'ENOENT',
+        () => Effect.void,
+      ),
+    )
+  })
+}
+
+/**
+ * Clear all generated type definitions.
+ */
+export const clear = (
+  options: WriterOptions,
+): Effect.Effect<void, Error, FileSystem.FileSystem> => {
+  const outputDir = getGeneratedTypesDir(options.projectRoot)
+
+  return Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    // Try to remove the directory, ignore if it doesn't exist
+    yield* fs.remove(outputDir, { recursive: true }).pipe(
+      Effect.catchIf(
+        error => (error as any).code === 'ENOENT',
+        () => Effect.void,
+      ),
+    )
+  })
+}
+
+// ============================================================================
+// Type Definition Builders
+// ============================================================================
+
+/**
+ * Create a global namespace augmentation type definition.
+ *
+ * @example
+ * ```ts
+ * const typeDef = Typings.createGlobalAugmentation(
+ *   'interface Examples { readonly names: readonly ["example1", "example2"] }',
+ *   'Example type definitions'
+ * )
+ * ```
+ */
+export const createGlobalAugmentation = (
+  content: string,
+  header?: string,
+): string => {
+  const headerComment = header
+    ? `// ${header}\n// This file is auto-generated by Polen\n// Do not edit this file directly\n\n`
+    : `// This file is auto-generated by Polen\n// Do not edit this file directly\n\n`
+
+  return `${headerComment}declare global {
+  namespace PolenGlobal {
+    ${content.split('\n').join('\n    ')}
+  }
+}
+
+// Ensure the file is treated as a module
+export {}
+`
+}
+
+/**
+ * Create a module augmentation type definition.
+ *
+ * @example
+ * ```ts
+ * const typeDef = Typings.createModuleAugmentation(
+ *   '#api/examples/config',
+ *   'export type AvailableExampleNames = Polen.AvailableExampleNames'
+ * )
+ * ```
+ */
+export const createModuleAugmentation = (
+  modulePath: string,
+  content: string,
+  header?: string,
+): string => {
+  const headerComment = header
+    ? `// ${header}\n// This file is auto-generated by Polen\n// Do not edit this file directly\n\n`
+    : `// This file is auto-generated by Polen\n// Do not edit this file directly\n\n`
+
+  return `${headerComment}declare module '${modulePath}' {
+  ${content.split('\n').join('\n  ')}
+}
+
+// Ensure the file is treated as a module
+export {}
+`
+}

package/src/cli/_/parameters.ts

@@ -1,17 +1,17 @@
-import { z } from 'zod'
+import { Args, Options } from '@effect/cli'
 
 /**
- * Common parameter schemas for CLI commands
+ * Common parameter schemas for Effect CLI commands
  */
 
-export const projectParameter = z
-  .string()
-  .optional()
-  .describe(`The path to the project directory. Default is CWD (current working directory).`)
+export const projectParameter = Args.text({ name: 'project' }).pipe(
+  Args.optional,
+  Args.withDescription('The path to the project directory. Default is CWD (current working directory).'),
+)
 
-export const allowGlobalParameter = z
-  .boolean()
-  .optional()
-  .describe(
-    `Allow using global Polen in a project with local Polen. Not recommended as it can cause version conflicts.`,
-  )
+export const allowGlobalParameter = Options.boolean('allow-global').pipe(
+  Options.optional,
+  Options.withDescription(
+    'Allow using global Polen in a project with local Polen. Not recommended as it can cause version conflicts.',
+  ),
+)