polen 0.10.0-next.13 → 0.10.0-next.3

package/src/lib/github-actions/step.test.ts

@@ -1,149 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { z } from 'zod/v4'
-import { createStep } from './step.ts'
-
-describe('defineWorkflowStep', () => {
-  const mockCore = {
-    startGroup: vi.fn(),
-    endGroup: vi.fn(),
-    debug: vi.fn(),
-    info: vi.fn(),
-    warning: vi.fn(),
-    error: vi.fn(),
-    setOutput: vi.fn(),
-  } as any
-
-  const mockContext = {
-    core: mockCore,
-    github: {} as any,
-    context: {} as any,
-    $: {} as any,
-    fs: {} as any,
-  } as any
-
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('executes step with validated inputs', async () => {
-    const TestStep = createStep({
-      name: 'test-step',
-      description: 'Test step',
-      inputs: z.object({
-        required: z.string(),
-        optional: z.string().optional(),
-      }),
-      outputs: z.object({ result: z.string() }),
-      async run({ inputs }) {
-        return { result: `Got ${inputs.required}` }
-      },
-    })
-
-    // Create context with PR controller
-    const contextWithPR = {
-      ...mockContext,
-      pr: {
-        number: 0,
-        isActive: false,
-        comment: vi.fn(),
-        deleteComment: vi.fn(),
-        getComments: vi.fn(),
-      },
-    }
-
-    const result = await TestStep.run({
-      ...contextWithPR,
-      inputs: {
-        required: 'value',
-        optional: 'optional-value',
-      },
-    })
-
-    expect(result).toEqual({ result: 'Got value' })
-  })
-
-  it('validates output types', async () => {
-    const TestStep = createStep({
-      name: 'test-step',
-      description: 'Test step',
-      inputs: z.object({
-        required: z.string(),
-      }),
-      outputs: z.object({ result: z.string() }),
-      async run({ inputs }) {
-        return { result: inputs.required }
-      },
-    })
-
-    // Outputs are validated in the runner, not in execute
-    expect(TestStep.definition.outputsSchema).toBeDefined()
-    expect(TestStep.definition.inputsSchema).toBeDefined()
-  })
-
-  it('step definition contains all metadata', async () => {
-    const TestStep = createStep({
-      name: 'test-step',
-      description: 'Test step',
-      inputs: z.object({
-        number: z.number(),
-      }),
-      outputs: z.object({ result: z.string() }),
-      async run() {
-        return { result: 'ok' }
-      },
-    })
-
-    expect(TestStep.definition.name).toBe('test-step')
-    expect(TestStep.definition.description).toBe('Test step')
-    expect(TestStep.definition.inputsSchema).toBeDefined()
-    expect(TestStep.definition.outputsSchema).toBeDefined()
-  })
-
-  // todo: this test is now a static type error, update to refelct that
-  // it('does not warn for non-object schemas', async () => {
-  //   const TestStep = defineStep({
-  //     name: 'test-step',
-  //     description: 'Test step',
-  //     inputs: z.string(),
-  //     outputs: z.object({ result: z.string() }),
-  //     async run({ inputs }) {
-  //       return { result: inputs }
-  //     },
-  //   })
-
-  //   await TestStep(mockContext, 'just-a-string')
-
-  //   expect(mockCore.warning).not.toHaveBeenCalled()
-  // })
-
-  it('always provides PR controller', async () => {
-    const mockPR = {
-      number: 123,
-      isActive: true,
-      comment: vi.fn(),
-      deleteComment: vi.fn(),
-      getComments: vi.fn(),
-    }
-
-    const contextWithPR = {
-      ...mockContext,
-      pr: mockPR,
-    }
-
-    const TestStep = createStep({
-      name: 'test-step',
-      description: 'Test step with PR',
-      inputs: z.object({}),
-      outputs: z.object({ isActive: z.boolean() }),
-      async run({ pr }) {
-        return { isActive: pr.isActive }
-      },
-    })
-
-    const result = await TestStep.run({
-      ...contextWithPR,
-      inputs: {},
-    })
-    expect(result).toEqual({ isActive: true })
-  })
-})

package/src/lib/github-actions/step.ts

@@ -1,232 +0,0 @@
-/**
- * Type-safe workflow step framework for GitHub Actions
- */
-
-// import type { Context } from '@actions/github/lib/context.ts'
-import type { GitHub } from '@actions/github/lib/utils.ts'
-import { z } from 'zod/v4'
-import type { GitController } from './git-controller.ts'
-import type { PullRequestController } from './pr-controller.ts'
-import type { Context, ContextSchema as RealContextSchema } from './schemas/context.ts'
-
-/**
- * Arguments passed to the step's run function.
- *
- * @template $Inputs - The validated input values based on your inputs schema
- * @template $Context - The GitHub Actions context (validated if context schema provided)
- */
-export interface Args<$Inputs extends Inputs = Inputs, $Context = Context> {
-  /** GitHub Actions core utilities for logging, setting outputs, etc. */
-  core: typeof import('@actions/core')
-
-  /** GitHub Actions context containing event payload, repo info, etc. */
-  context: $Context
-
-  /** Validated input values passed to the step */
-  inputs: $Inputs
-
-  /** Authenticated Octokit instance for GitHub API operations */
-  github: InstanceType<typeof GitHub>
-
-  /** zx's $ function for executing shell commands */
-  $: typeof import('zx').$
-
-  /** Node.js fs/promises module for file operations */
-  fs: typeof import('node:fs/promises')
-
-  /** PR controller for pull request operations (comment, review, etc.) */
-  pr: PullRequestController
-
-  /** Git controller for git operations (commit, push, etc.) without subprocess details */
-  git: GitController
-}
-
-export type Outputs = object
-
-export type Inputs = object
-
-type InputsSchema = z.ZodObject
-
-type OutputsSchema = z.ZodObject
-
-// This is a loose type because working with sub/sup schema types is complex, maybe not even workable, unclear, and not worth the effort
-type ContextSchema = z.Schema
-
-// Export the full step definition for runner
-export interface Step<
-  $InputsSchema extends InputsSchema = InputsSchema,
-  $OutputsSchema extends OutputsSchema = OutputsSchema,
-  $ContextSchema extends ContextSchema = ContextSchema,
-> {
-  definition: Definition<
-    $InputsSchema,
-    $OutputsSchema,
-    $ContextSchema
-  >
-  run: Runner<
-    z.output<$InputsSchema>,
-    z.output<$OutputsSchema>,
-    z.output<$ContextSchema>
-  >
-}
-
-export type Runner<
-  $Inputs extends Inputs = Inputs,
-  $Outputs extends Outputs = Outputs,
-  $Context = Context,
-> = (
-  context: Args<$Inputs, $Context>,
-) => Promise<$Outputs>
-
-// Generic workflow step definition
-export interface Definition<
-  $InputsSchema extends InputsSchema,
-  $OutputsSchema extends OutputsSchema,
-  $ContextSchema extends ContextSchema,
-> {
-  description?: string
-  name?: string
-  inputsSchema?: $InputsSchema
-  outputsSchema?: $OutputsSchema
-  contextSchema?: $ContextSchema
-}
-
-// Generic workflow step definition
-export interface CreateInput<
-  $InputsSchema extends InputsSchema,
-  $OutputsSchema extends OutputsSchema,
-  $ContextSchema extends z.Schema,
-> {
-  description?: string
-  name?: string
-  inputs?: $InputsSchema
-  outputs?: $OutputsSchema
-  context?: $ContextSchema
-  run: (
-    args: Args<z.output<$InputsSchema>, z.output<$ContextSchema>>,
-    // todo: Obj.isEmpty ...
-  ) => Promise<{} extends z.Infer<$OutputsSchema> ? void : z.Infer<$OutputsSchema>>
-}
-
-/**
- * Create a type-safe GitHub Actions workflow step with runtime validation.
- *
- * This is the main entry point for defining custom workflow steps that can be executed
- * by the GitHub Actions runner. It provides:
- * - Type-safe inputs/outputs with Zod schema validation
- * - Automatic GitHub Actions output handling (both individual outputs and bundled JSON)
- * - Context validation to ensure steps run in the correct workflow events
- * - Integration with GitHub API via Octokit
- * - Built-in error handling and logging
- *
- * @example Basic step with inputs and outputs
- * ```typescript
- * import { z } from 'zod'
- * import { GitHubActions } from '#lib/github-actions'
- *
- * export default GitHubActions.createStep({
- *   name: 'my-step',
- *   description: 'Processes some data and returns results',
- *   inputs: z.object({
- *     message: z.string(),
- *     count: z.number().optional().default(1),
- *   }),
- *   outputs: z.object({
- *     result: z.string(),
- *     processed: z.boolean(),
- *   }),
- *   async run({ inputs, core }) {
- *     core.info(`Processing: ${inputs.message}`)
- *
- *     return {
- *       result: inputs.message.toUpperCase(),
- *       processed: true,
- *     }
- *   }
- * })
- * ```
- *
- * @example Step with specific context requirements
- * ```typescript
- * export default GitHubActions.createStep({
- *   name: 'pr-only-step',
- *   description: 'This step only runs on pull requests',
- *   context: GitHubActions.PullRequestContext,
- *   outputs: z.object({
- *     pr_number: z.number(),
- *   }),
- *   async run({ context, core }) {
- *     const prNumber = context.payload.pull_request.number
- *     core.info(`Running on PR #${prNumber}`)
- *
- *     return { pr_number: prNumber }
- *   }
- * })
- * ```
- *
- * @example Using the GitHub API
- * ```typescript
- * export default GitHubActions.createStep({
- *   name: 'create-issue',
- *   description: 'Creates a GitHub issue',
- *   inputs: z.object({
- *     title: z.string(),
- *     body: z.string(),
- *   }),
- *   outputs: z.object({
- *     issue_number: z.number(),
- *     issue_url: z.string(),
- *   }),
- *   async run({ inputs, github, context }) {
- *     const issue = await github.rest.issues.create({
- *       owner: context.repo.owner,
- *       repo: context.repo.repo,
- *       title: inputs.title,
- *       body: inputs.body,
- *     })
- *
- *     return {
- *       issue_number: issue.data.number,
- *       issue_url: issue.data.html_url,
- *     }
- *   }
- * })
- * ```
- *
- * @param input - Step configuration object
- * @param input.name - Unique identifier for the step (used in logging and debugging)
- * @param input.description - Human-readable description of what the step does
- * @param input.inputs - Optional Zod schema for validating step inputs
- * @param input.outputs - Optional Zod schema for validating step outputs
- * @param input.context - Optional Zod schema for validating GitHub Actions context (event type)
- * @param input.run - Async function that implements the step logic
- *
- * @returns A Step object that can be executed by the GitHub Actions runner
- *
- * @remarks
- * - All outputs are automatically set as GitHub Actions outputs
- * - Boolean outputs are properly handled (use fromJSON in workflows)
- * - A special 'json' output contains all outputs bundled together
- * - The runner provides extensive logging and error handling
- * - Steps can access PR controller for pull request operations
- * - The `$` from zx is available for shell commands
- */
-export function createStep<
-  $InputsSchema extends InputsSchema,
-  $OutputsSchema extends OutputsSchema,
-  $ContextSchema extends ContextSchema = RealContextSchema,
->(
-  input: CreateInput<$InputsSchema, $OutputsSchema, $ContextSchema>,
-): Step<$InputsSchema, $OutputsSchema, $ContextSchema> {
-  const { run, inputs, outputs, context, ...rest } = input
-  const definition: Definition<$InputsSchema, $OutputsSchema, $ContextSchema> = {
-    ...rest,
-    inputsSchema: inputs,
-    outputsSchema: outputs,
-    contextSchema: context,
-  }
-  return {
-    definition,
-    run,
-  } as any
-}

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

@@ -1,4 +0,0 @@
-export * from './analysis.ts'
-export * from './positioning-simple.ts'
-export * from './schema-integration.ts'
-export * from './types.ts'

package/src/lib/graphql-document/$.test.ts

@@ -1,132 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { GraphQLDocument } from './$.ts'
-
-describe('GraphQLDocument', () => {
-  describe('analyze', () => {
-    it('should parse a simple query and extract identifiers', () => {
-      const source = `
-        query GetUser($id: ID!) {
-          user(id: $id) {
-            name
-            email
-          }
-        }
-      `
-
-      const result = GraphQLDocument.analyze(source)
-
-      expect(result.isValid).toBe(true)
-      expect(result.identifiers.all.length).toBeGreaterThan(0)
-
-      // Should find variable
-      const variables = result.identifiers.byKind.get('Variable') || []
-      expect(variables).toHaveLength(1)
-      expect(variables[0]?.name).toBe('id')
-
-      // Should find fields
-      const fields = result.identifiers.byKind.get('Field') || []
-      expect(fields.length).toBeGreaterThan(0)
-      const fieldNames = fields.map(f => f.name)
-      expect(fieldNames).toContain('user')
-      expect(fieldNames).toContain('name')
-      expect(fieldNames).toContain('email')
-
-      // Should find types
-      const types = result.identifiers.byKind.get('Type') || []
-      expect(types.length).toBeGreaterThan(0)
-      const typeNames = types.map(t => t.name)
-      expect(typeNames).toContain('ID')
-    })
-
-    it('should handle parsing errors gracefully', () => {
-      const invalidSource = `
-        query {
-          user(id: $id {
-            name
-          }
-        }
-      `
-
-      const result = GraphQLDocument.analyze(invalidSource)
-
-      expect(result.isValid).toBe(false)
-      expect(result.identifiers.errors.length).toBeGreaterThan(0)
-    })
-
-    it('should extract context information', () => {
-      const source = `
-        query GetUserPosts($userId: ID!) {
-          user(id: $userId) {
-            posts {
-              title
-              content
-            }
-          }
-        }
-      `
-
-      const result = GraphQLDocument.analyze(source)
-
-      const fields = result.identifiers.byKind.get('Field') || []
-      const userField = fields.find(f => f.name === 'user')
-
-      expect(userField?.context.operationType).toBe('query')
-      expect(userField?.context.operationName).toBe('GetUserPosts')
-      expect(userField?.context.selectionPath).toEqual(['user'])
-    })
-
-    it('should track parent types in nested selections', () => {
-      const source = `
-        query {
-          user {
-            posts {
-              title
-            }
-          }
-        }
-      `
-
-      const result = GraphQLDocument.analyze(source)
-
-      const fields = result.identifiers.byKind.get('Field') || []
-      const titleField = fields.find(f => f.name === 'title')
-
-      expect(titleField?.schemaPath).toEqual(['Post', 'title'])
-    })
-  })
-
-  describe('extractIdentifiers', () => {
-    it('should extract identifiers with positions', () => {
-      const source = `query { user { name } }`
-
-      const identifiers = GraphQLDocument.extractIdentifiers(source)
-
-      expect(identifiers.all.length).toBeGreaterThan(0)
-
-      // Each identifier should have position information
-      for (const identifier of identifiers.all) {
-        expect(identifier.position.start).toBeTypeOf('number')
-        expect(identifier.position.end).toBeTypeOf('number')
-        expect(identifier.position.line).toBeGreaterThan(0)
-        expect(identifier.position.column).toBeGreaterThan(0)
-      }
-    })
-
-    it('should create proper index maps', () => {
-      const source = `query { user { name } }`
-
-      const identifiers = GraphQLDocument.extractIdentifiers(source)
-
-      // Should have position index
-      expect(identifiers.byPosition.size).toBeGreaterThan(0)
-
-      // Should have kind index
-      expect(identifiers.byKind.size).toBeGreaterThan(0)
-
-      // All identifiers should be indexed
-      for (const identifier of identifiers.all) {
-        expect(identifiers.byPosition.get(identifier.position.start)).toBe(identifier)
-      }
-    })
-  })
-})

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

@@ -1 +0,0 @@
-export * as GraphQLDocument from './graphql-document.ts'

package/src/lib/graphql-document/README.md

@@ -1,102 +0,0 @@
-# GraphQL Document Component
-
-Transform static GraphQL code blocks into interactive documentation with hyperlinks, tooltips, and schema validation.
-
-## Overview
-
-The GraphQL Document component enhances markdown code blocks with:
-
-- **Hyperlinked identifiers** - Click to navigate to reference documentation
-- **Hover tooltips** - View type information and descriptions
-- **Schema validation** - Highlight errors and deprecations
-- **Build-time checking** - Catch GraphQL errors during build
-
-## Architecture
-
-The implementation follows a layered architecture:
-
-1. **Analysis Layer** - Parses GraphQL and extracts identifiers
-2. **Schema Integration** - Resolves identifiers against GraphQL schema
-3. **Positioning Engine** - Maps source positions to DOM coordinates
-4. **UI Components** - React components for interactivity
-5. **Orchestration** - Main component tying everything together
-6. **Polen Integration** - Virtual modules and Vite plugin
-
-## Usage
-
-### Basic Setup
-
-1. Import the component in your MDX files:
-
-```typescript
-import { GraphQLDocumentWithSchema } from 'polen/components'
-```
-
-2. Use the component with GraphQL documents:
-
-```mdx
-<GraphQLDocumentWithSchema>
-{`query GetUser($id: ID!) {
-  user(id: $id) {
-    name
-    email
-  }
-}`}
-</GraphQLDocumentWithSchema>
-```
-
-### Component Props
-
-The `GraphQLDocumentWithSchema` component automatically loads the schema from Polen's virtual modules. You can pass options:
-
-```mdx
-<GraphQLDocumentWithSchema 
-  options={{ 
-    debug: true,
-    onNavigate: (url) => console.log('Navigate to:', url)
-  }}
->
-{`query { user { name } }`}
-</GraphQLDocumentWithSchema>
-```
-
-### React Component
-
-Use the component directly in React:
-
-```tsx
-import { GraphQLDocument } from 'polen/lib/graphql-document'
-
-<GraphQLDocument schema={schema} options={{ debug: true }}>
-  {`query { user { name } }`}
-</GraphQLDocument>
-```
-
-## Implementation Details
-
-### Key Components
-
-- `GraphQLDocument` - Main React component
-- `IdentifierLink` - Interactive overlay for identifiers
-- `HoverTooltip` - Tooltip showing type information
-- `GraphQLDocumentWithSchema` - Wrapper that loads schema from Polen
-- `PolenSchemaResolver` - Schema integration
-
-### Testing
-
-Run tests with:
-
-```bash
-pnpm test:unit src/lib/graphql-document
-```
-
-### Type Safety
-
-Full TypeScript support with strict typing throughout.
-
-## Future Enhancements
-
-- Code folding for large queries
-- Inline query execution
-- Schema diff visualization
-- Export to various formats