skrypt-ai 0.3.3 → 0.4.0

package/dist/template/src/app/docs/generator/generator.md

@@ -0,0 +1,504 @@
+# Generator.ts
+
+## Functions
+
+### `generateForElement`
+
+```typescript
+async function generateForElement(element: APIElement, client: LLMClient, options: GenerationOptions, onProgress?: (progress: GenerationProgress) => void): Promise<GeneratedDoc>
+```
+
+Use this to generate documentation for a single API element using an LLM client, without running any test validation on the output.
+
+This is the core documentation generation function — pass it a parsed API element (function, class, type, etc.), an LLM client, and generation options to receive structured documentation. Optionally track progress in real time via the `onProgress` callback.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `element` | `APIElement` | ✅ | The parsed API element to document (function, class, interface, etc.) |
+| `client` | `LLMClient` | ✅ | Configured LLM client used to generate the documentation |
+| `options` | `GenerationOptions` | ✅ | Controls generation behavior: model, style, language, max tokens, etc. |
+| `onProgress` | `(progress: GenerationProgress) => void` | ❌ | Optional callback invoked during generation to report progress stages |
+
+## Returns
+
+Returns a `Promise<GeneratedDoc>` that resolves to a structured documentation object containing:
+
+| Field | Description |
+|-------|-------------|
+| `markdown` | The generated documentation as a markdown string |
+| `element` | Reference back to the source `APIElement` |
+| `metadata` | Generation metadata (model used, token counts, timestamp) |
+
+Rejects with an error if the LLM client fails or the element cannot be processed.
+
+**Example:**
+
+```typescript example.ts
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'type'
+  signature: string
+  docstring?: string
+  filePath: string
+}
+
+type GenerationOptions = {
+  model: string
+  style: 'concise' | 'detailed'
+  language: 'typescript' | 'javascript'
+  maxTokens?: number
+}
+
+type GenerationProgress = {
+  stage: 'preparing' | 'generating' | 'formatting' | 'complete'
+  percentComplete: number
+  message: string
+}
+
+type GeneratedDoc = {
+  markdown: string
+  element: APIElement
+  metadata: {
+    model: string
+    tokensUsed: number
+    generatedAt: string
+  }
+}
+
+type LLMClient = {
+  apiKey: string
+  baseUrl: string
+  complete: (prompt: string, maxTokens: number) => Promise<string>
+}
+
+// ─── Simulated implementations ───────────────────────────────────────────────
+
+function createLLMClient(apiKey: string): LLMClient {
+  return {
+    apiKey,
+    baseUrl: 'https://api.openai.com/v1',
+    complete: async (prompt: string, maxTokens: number): Promise<string> => {
+      // Simulates an LLM response for demonstration
+      return `Use this to calculate the total price including tax.\n\n**Parameters:**\n- \`price\`: number — base price\n- \`taxRate\`: number — tax rate as a decimal\n\n**Returns:** \`number\` — final price with tax applied`
+    }
+  }
+}
+
+async function generateForElement(
+  element: APIElement,
+  client: LLMClient,
+  options: GenerationOptions,
+  onProgress?: (progress: GenerationProgress) => void
+): Promise<GeneratedDoc> {
+  const reportProgress = (stage: GenerationProgress['stage'], percent: number, message: string) => {
+    onProgress?.({ stage, percentComplete: percent, message })
+  }
+
+  reportProgress('preparing', 10, `Preparing context for "${element.name}"`)
+  await new Promise(r => setTimeout(r, 50)) // simulate async work
+
+  reportProgress('generating', 40, `Sending "${element.name}" to ${options.model}`)
+  const prompt = `Generate ${options.style} documentation for:\n${element.signature}`
+  const rawDoc = await client.complete(prompt, options.maxTokens ?? 1024)
+
+  reportProgress('formatting', 80, 'Formatting output')
+  await new Promise(r => setTimeout(r, 30))
+
+  reportProgress('complete', 100, 'Documentation generated successfully')
+
+  return {
+    markdown: rawDoc,
+    element,
+    metadata: {
+      model: options.model,
+      tokensUsed: rawDoc.split(' ').length * 2, // rough estimate for demo
+      generatedAt: new Date().toISOString()
+    }
+  }
+}
+
+// ─── Usage example ────────────────────────────────────────────────────────────
+
+const apiElement: APIElement = {
+  name: 'calculateTotalPrice',
+  kind: 'function',
+  signature: 'function calculateTotalPrice(price: number, taxRate: number): number',
+  docstring: 'Calculates the total price including tax.',
+  filePath: 'src/pricing/utils.ts'
+}
+
+const client = createLLMClient(process.env.OPENAI_API_KEY || 'sk-your-api-key-here')
+
+const options: GenerationOptions = {
+  model: 'gpt-4o',
+  style: 'detailed',
+  language: 'typescript',
+  maxTokens: 512
+}
+
+async function main() {
+  try {
+    console.log(`Generating docs for: ${apiElement.name}\n`)
+
+    const doc = await generateForElement(
+      apiElement,
+      client,
+      options,
+      (progress: GenerationProgress) => {
+        console.log(`[${progress.percentComplete}%] ${progress.stage}: ${progress.message}`)
+      }
+    )
+
+    console.log('\n─── Generated Documentation ───────────────────────────')
+    console.log(doc.markdown)
+    console.log('\n─── Metadata ──────────────────────────────────────────')
+    console.log(`Model:        ${doc.metadata.model}`)
+    console.log(`Tokens used:  ${doc.metadata.tokensUsed}`)
+    console.log(`Generated at: ${doc.metadata.generatedAt}`)
+
+    // Expected output:
+    // [10%] preparing: Preparing context for "calculateTotalPrice"
+    // [40%] generating: Sending "calculateTotalPrice" to gpt-4o
+    // [80%] formatting: Formatting output
+    // [100%] complete: Documentation generated successfully
+    //
+    // ─── Generated Documentation ───
+    // Use this to calculate the total price including tax.
+    // ...
+  } catch (error) {
+    console.error('Documentation generation failed:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `generateForElements`
+
+```typescript
+async function generateForElements(elements: APIElement[], client: LLMClient, options: GenerationOptions): Promise<GeneratedDoc[]>
+```
+
+Use this to batch-generate documentation for multiple API elements in a single call, processing an entire scanned API surface and returning structured docs for each element.
+
+This is the primary entry point for bulk documentation generation — pass in your parsed API elements, an LLM client, and generation options to get back a full array of generated documentation objects.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elements` | `APIElement[]` | Yes | Array of parsed API elements (functions, classes, types, etc.) to generate docs for |
+| `client` | `LLMClient` | Yes | Configured LLM client used to generate the documentation content |
+| `options` | `GenerationOptions` | Yes | Controls generation behavior: model selection, output format, concurrency, etc. |
+
+## Returns
+
+Returns `Promise<GeneratedDoc[]>` — resolves to an array of generated documentation objects, one per input element, in the same order as the input `elements` array.
+
+| Scenario | Result |
+|----------|--------|
+| All elements processed successfully | Array of `GeneratedDoc` objects with markdown/content for each element |
+| Empty `elements` array | Resolves to `[]` |
+| LLM client error on an element | Rejects or returns partial results depending on `options.onError` strategy |
+
+**Example:**
+
+```typescript example.ts
+// ─── Inline type definitions (no external imports needed) ───────────────────
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'type' | 'interface' | 'variable'
+  signature: string
+  docstring?: string
+  filePath: string
+}
+
+type GeneratedDoc = {
+  elementName: string
+  kind: APIElement['kind']
+  markdown: string
+  generatedAt: Date
+}
+
+type GenerationOptions = {
+  model?: string
+  maxConcurrency?: number
+  outputFormat?: 'markdown' | 'html'
+  onError?: 'skip' | 'throw'
+}
+
+type LLMClient = {
+  apiKey: string
+  baseUrl: string
+  complete: (prompt: string) => Promise<string>
+}
+
+// ─── Simulated implementation of generateForElements ────────────────────────
+
+async function generateForElements(
+  elements: APIElement[],
+  client: LLMClient,
+  options: GenerationOptions
+): Promise<GeneratedDoc[]> {
+  const {
+    maxConcurrency = 3,
+    outputFormat = 'markdown',
+    onError = 'skip',
+  } = options
+
+  const results: GeneratedDoc[] = []
+
+  // Process in batches to respect maxConcurrency
+  for (let i = 0; i < elements.length; i += maxConcurrency) {
+    const batch = elements.slice(i, i + maxConcurrency)
+
+    const batchResults = await Promise.allSettled(
+      batch.map(async (element) => {
+        const prompt = `Generate ${outputFormat} documentation for: ${element.signature}`
+
+        try {
+          const content = await client.complete(prompt)
+          return {
+            elementName: element.name,
+            kind: element.kind,
+            markdown: content,
+            generatedAt: new Date(),
+          } satisfies GeneratedDoc
+        } catch (err) {
+          if (onError === 'throw') throw err
+          console.warn(`Skipping ${element.name} due to error:`, err)
+          return null
+        }
+      })
+    )
+
+    for (const result of batchResults) {
+      if (result.status === 'fulfilled' && result.value !== null) {
+        results.push(result.value)
+      }
+    }
+  }
+
+  return results
+}
+
+// ─── Simulated LLM client (replace complete() with real API call) ────────────
+
+function createLLMClient(apiKey: string): LLMClient {
+  return {
+    apiKey,
+    baseUrl: 'https://api.openai.com/v1',
+    complete: async (prompt: string): Promise<string> => {
+      // Simulate LLM latency
+      await new Promise((r) => setTimeout(r, 50))
+      return `**Auto-generated doc**\n\nPrompt received: "${prompt.slice(0, 60)}..."`
+    },
+  }
+}
+
+// ─── Example usage ───────────────────────────────────────────────────────────
+
+const elements: APIElement[] = [
+  {
+    name: 'fetchUser',
+    kind: 'function',
+    signature: 'async function fetchUser(id: string): Promise<User>',
+    docstring: 'Fetches a user by ID',
+    filePath: 'src/api/users.ts',
+  },
+  {
+    name: 'UserService',
+    kind: 'class',
+    signature: 'class UserService { constructor(db: Database) }',
+    filePath: 'src/services/UserService.ts',
+  },
+  {
+    name: 'UserRole',
+    kind: 'type',
+    signature: "type UserRole = 'admin' | 'editor' | 'viewer'",
+    filePath: 'src/types/roles.ts',
+  },
+]
+
+const client = createLLMClient(process.env.LLM_API_KEY || 'sk-your-api-key-here')
+
+const options: GenerationOptions = {
+  model: 'gpt-4o',
+  maxConcurrency: 2,
+  outputFormat: 'markdown',
+  onError: 'skip',
+}
+
+async function main() {
+  try {
+    console.log(`Generating docs for ${elements.length} elements...\n`)
+
+    const docs = await generateForElements(elements, client, options)
+
+    console.log(`✅ Generated ${docs.length} documentation entries:\n`)
+
+    for (const doc of docs) {
+      console.log(`─── ${doc.elementName} (${doc.kind}) ───`)
+      console.log(doc.markdown)
+      console.log(`Generated at: ${doc.generatedAt.toISOString()}\n`)
+    }
+
+    // Expected output:
+    // ✅ Generated 3 documentation entries:
+    // ─── fetchUser (function) ───
+    // **Auto-generated doc**
+    // Prompt received: "Generate markdown documentation for: async function fe..."
+    // Generated at: 2024-11-15T10:23:45.123Z
+    // ... (one entry per element)
+  } catch (error) {
+    console.error('Documentation generation failed:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `formatAsMarkdown`
+
+```typescript
+function formatAsMarkdown(docs: GeneratedDoc[], title: string): string
+```
+
+Use this to convert an array of generated documentation objects into a formatted Markdown string, ready to write to a `.md` file or display in a docs site.
+
+Takes structured doc data (functions, classes, methods) and a page title, and returns a complete Markdown document with sections organized by element type.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ | Array of generated documentation objects, each containing an element descriptor and its rendered doc content |
+| `title` | `string` | ✅ | The top-level heading for the Markdown document (rendered as `# title`) |
+
+## Returns
+
+A `string` containing the full Markdown file content, with:
+- A `# Title` heading at the top
+- Sections grouped by element kind: **Functions**, **Classes**, and **Methods**
+- Each doc entry rendered under its appropriate section
+
+---MARKDOWN---
+
+**Example:**
+
+```typescript example.ts
+// ---- Inline types (mirrors the real GeneratedDoc / APIElement shape) ----
+type ElementKind = 'function' | 'class' | 'method'
+
+interface APIElement {
+  name: string
+  kind: ElementKind
+  signature?: string
+}
+
+interface GeneratedDoc {
+  element: APIElement
+  documentation: string
+}
+
+// ---- Inline implementation of formatAsMarkdown ----
+function formatAsMarkdown(docs: GeneratedDoc[], title: string): string {
+  let content = `# ${title}\n\n`
+
+  const functions = docs.filter(d => d.element.kind === 'function')
+  const classes   = docs.filter(d => d.element.kind === 'class')
+  const methods   = docs.filter(d => d.element.kind === 'method')
+
+  function renderSection(heading: string, items: GeneratedDoc[]): string {
+    if (items.length === 0) return ''
+    let section = `## ${heading}\n\n`
+    for (const doc of items) {
+      section += `### \`${doc.element.name}\`\n\n`
+      if (doc.element.signature) {
+        section += `\`\`\`ts\n${doc.element.signature}\n\`\`\`\n\n`
+      }
+      section += `${doc.documentation}\n\n`
+    }
+    return section
+  }
+
+  content += renderSection('Functions', functions)
+  content += renderSection('Classes', classes)
+  content += renderSection('Methods', methods)
+
+  return content.trimEnd() + '\n'
+}
+
+// ---- Realistic sample data ----
+const sampleDocs: GeneratedDoc[] = [
+  {
+    element: {
+      name: 'fetchUser',
+      kind: 'function',
+      signature: 'function fetchUser(id: string): Promise<User>',
+    },
+    documentation:
+      'Fetches a user record by ID from the remote API. Throws `NotFoundError` if the user does not exist.',
+  },
+  {
+    element: {
+      name: 'UserService',
+      kind: 'class',
+      signature: 'class UserService',
+    },
+    documentation:
+      'Provides high-level methods for managing user accounts, including creation, updates, and deletion.',
+  },
+  {
+    element: {
+      name: 'UserService.update',
+      kind: 'method',
+      signature: 'update(id: string, patch: Partial<User>): Promise<User>',
+    },
+    documentation:
+      'Applies a partial update to an existing user. Returns the updated user object.',
+  },
+]
+
+// ---- Run the example ----
+try {
+  const markdown = formatAsMarkdown(sampleDocs, 'API Reference')
+  console.log(markdown)
+  /*
+  Expected output:
+  ─────────────────────────────────────────
+  # API Reference
+
+  ## Functions
+
+  ### `fetchUser`
+
+  ```ts
+  function fetchUser(id: string): Promise<User>
+  ```
+
+  Fetches a user record by ID from the remote API. Throws `NotFoundError` if the user does not exist.
+
+  ## Classes
+
+  ### `UserService`
+  ...
+
+  ## Methods
+
+  ### `UserService.update`
+  ...
+  ─────────────────────────────────────────
+  */
+} catch (error) {
+  console.error('formatAsMarkdown failed:', error)
+}
+```
+