skrypt-ai 0.3.4 → 0.4.1

package/dist/template/src/app/docs/autofix/page.mdx

@@ -0,0 +1,624 @@
+## Functions
+
+### `autoFixExample`
+
+```typescript
+async function autoFixExample(example: CodeExample, client: LLMClient, options: AutoFixOptions = {}): Promise<FixResult>
+```
+
+Use this to automatically repair broken or invalid code examples by iteratively applying LLM-powered fixes until the code is valid or the maximum retry limit is reached.
+
+This is ideal for CI pipelines, documentation generators, or developer tools that need to ensure code examples stay compilable and correct as APIs evolve.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `example` | `CodeExample` | ✅ | The code example to fix, including its source code, language, and optional error context |
+| `client` | `LLMClient` | ✅ | An LLM client instance used to generate fix suggestions |
+| `options` | `AutoFixOptions` | ❌ | Configuration options such as `maxIterations` (default: `3`) to control retry attempts |
+
+#### Returns
+
+Returns a `Promise<FixResult>` that resolves with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | `boolean` | Whether the example was successfully fixed |
+| `fixedCode` | `string \| null` | The repaired code if successful, otherwise `null` |
+| `iterations` | `number` | How many fix attempts were made |
+| `error` | `string \| undefined` | Description of the failure if `success` is `false` |
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type CodeExample = {
+  code: string
+  language: string
+  errorContext?: string
+}
+
+type AutoFixOptions = {
+  maxIterations?: number
+}
+
+type FixResult = {
+  success: boolean
+  fixedCode: string | null
+  iterations: number
+  error?: string
+}
+
+type LLMClient = {
+  complete: (prompt: string) => Promise<string>
+}
+
+// ── Simulated LLM client (replace with your real client) ───────────────────
+
+function createLLMClient(apiKey: string): LLMClient {
+  return {
+    complete: async (prompt: string): Promise<string> => {
+      // In production this would call OpenAI, Anthropic, etc.
+      console.log(`[LLM] Sending prompt (${prompt.length} chars) to API...`)
+
+      // Simulate a fix: replace the broken fetch call with a corrected version
+      return `
+async function fetchUser(id: string) {
+  const response = await fetch(\`https://api.example.com/users/\${id}\`, {
+    headers: { Authorization: \`Bearer \${process.env.API_TOKEN}\` }
+  });
+  if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
+  return response.json();
+}
+`.trim()
+    }
+  }
+}
+
+// ── Simulated autoFixExample (mirrors the real implementation) ─────────────
+
+async function autoFixExample(
+  example: CodeExample,
+  client: LLMClient,
+  options: AutoFixOptions = {}
+): Promise<FixResult> {
+  const maxIterations = options.maxIterations ?? 3
+  let currentCode = example.code
+  let iterations = 0
+
+  while (iterations < maxIterations) {
+    iterations++
+
+    const prompt = [
+      `Fix the following ${example.language} code example.`,
+      example.errorContext ? `Error: ${example.errorContext}` : '',
+      `\`\`\`${example.language}`,
+      currentCode,
+      '```',
+      'Return only the corrected code, no explanation.'
+    ]
+      .filter(Boolean)
+      .join('\n')
+
+    try {
+      const fixedCode = await client.complete(prompt)
+
+      // Simulate a basic validation check (real impl would compile/lint)
+      const isValid = !fixedCode.includes('SYNTAX_ERROR') && fixedCode.trim().length > 0
+
+      if (isValid) {
+        return { success: true, fixedCode, iterations }
+      }
+
+      currentCode = fixedCode // retry with the partially-fixed code
+    } catch (err) {
+      return {
+        success: false,
+        fixedCode: null,
+        iterations,
+        error: err instanceof Error ? err.message : 'Unknown LLM error'
+      }
+    }
+  }
+
+  return {
+    success: false,
+    fixedCode: null,
+    iterations,
+    error: `Could not fix example after ${maxIterations} iteration(s)`
+  }
+}
+
+// ── Usage ──────────────────────────────────────────────────────────────────
+
+const brokenExample: CodeExample = {
+  language: 'typescript',
+  errorContext: "Cannot read properties of undefined (reading 'json')",
+  code: `
+async function fetchUser(id: string) {
+  const response = fetch(\`https://api.example.com/users/\${id}\`) // missing await
+  return response.json()
+}
+`.trim()
+}
+
+async function main() {
+  const client = createLLMClient(process.env.OPENAI_API_KEY || 'sk-your-api-key-here')
+
+  try {
+    const result = await autoFixExample(brokenExample, client, { maxIterations: 3 })
+
+    if (result.success) {
+      console.log(`✅ Fixed in ${result.iterations} iteration(s):\n`)
+      console.log(result.fixedCode)
+    } else {
+      console.warn(`❌ Fix failed after ${result.iterations} attempt(s): ${result.error}`)
+    }
+
+    // Expected output:
+    // [LLM] Sending prompt (... chars) to API...
+    // ✅ Fixed in 1 iteration(s):
+    //
+    // async function fetchUser(id: string) {
+    //   const response = await fetch(`https://api.example.com/users/${id}`, {
+    //     headers: { Authorization: `Bearer ${process.env.API_TOKEN}` }
+    //   });
+    //   if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    //   return response.json();
+    // }
+  } catch (error) {
+    console.error('Unexpected error during auto-fix:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `autoFixBatch`
+
+```typescript
+async function autoFixBatch(examples: CodeExample[], client: LLMClient, options: AutoFixOptions = {}): Promise<Map<number, FixResult>>
+```
+
+Use this to automatically fix multiple broken code examples in a single batch operation, getting back a map of results indexed by position.
+
+This is the batch version of `autoFix` — ideal when you have a collection of code examples that need validation and repair, such as during a documentation build pipeline or CI check.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `examples` | `CodeExample[]` | ✅ Yes | Array of code examples to fix, each with a `code` string and optional metadata |
+| `client` | `LLMClient` | ✅ Yes | LLM client instance used to analyze and rewrite broken examples |
+| `options` | `AutoFixOptions` | ❌ No | Configuration options such as `maxRetries`, `language`, and `context` hints |
+
+#### Returns
+
+Returns `Promise<Map<number, FixResult>>` — a `Map` where:
+- **Key** (`number`): The zero-based index of the example in the input array
+- **Value** (`FixResult`): An object containing:
+  - `fixed` (`boolean`): Whether the example was successfully repaired
+  - `code` (`string`): The resulting code (fixed or original if unfixable)
+  - `error` (`string | undefined`): Description of what was wrong, if applicable
+  - `attempts` (`number`): How many fix attempts were made
+
+Only examples that were processed appear in the map. If an example was skipped or errored fatally, it may be absent.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (do not import from autodocs) ──────────────────────────────
+
+type CodeExample = {
+  code: string
+  language?: string
+  filename?: string
+}
+
+type FixResult = {
+  fixed: boolean
+  code: string
+  error?: string
+  attempts: number
+}
+
+type AutoFixOptions = {
+  maxRetries?: number
+  language?: string
+  contextHint?: string
+  dryRun?: boolean
+}
+
+type LLMClient = {
+  complete: (prompt: string) => Promise<string>
+}
+
+// ── Simulated autoFixBatch implementation ───────────────────────────────────
+
+async function autoFixBatch(
+  examples: CodeExample[],
+  client: LLMClient,
+  options: AutoFixOptions = {}
+): Promise<Map<number, FixResult>> {
+  const { maxRetries = 2, dryRun = false } = options
+  const results = new Map<number, FixResult>()
+
+  for (let i = 0; i < examples.length; i++) {
+    const example = examples[i]
+    let attempts = 0
+    let fixed = false
+    let finalCode = example.code
+    let errorMsg: string | undefined
+
+    // Simulate detecting and fixing issues
+    const hasIssue = example.code.includes('???') || example.code.includes('BROKEN')
+
+    if (!hasIssue) {
+      results.set(i, { fixed: true, code: finalCode, attempts: 0 })
+      continue
+    }
+
+    while (attempts < maxRetries && !fixed) {
+      attempts++
+      if (!dryRun) {
+        // In real usage, the LLM client rewrites the broken code
+        const prompt = `Fix this ${example.language ?? 'code'} example:\n${example.code}`
+        const suggestion = await client.complete(prompt)
+        finalCode = suggestion
+        fixed = !finalCode.includes('???') && !finalCode.includes('BROKEN')
+      }
+    }
+
+    errorMsg = fixed ? undefined : `Could not repair example after ${attempts} attempt(s)`
+    results.set(i, { fixed, code: finalCode, error: errorMsg, attempts })
+  }
+
+  return results
+}
+
+// ── Mock LLM client ──────────────────────────────────────────────────────────
+
+function createMockLLMClient(apiKey: string): LLMClient {
+  return {
+    complete: async (prompt: string): Promise<string> => {
+      // Simulate a repaired response from the LLM
+      console.log(`  [LLM] Sending fix request (key: ${apiKey.slice(0, 8)}...)`)
+      return `const greet = (name: string) => \`Hello, \${name}!\`;\nconsole.log(greet('World'));`
+    },
+  }
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+const examples: CodeExample[] = [
+  {
+    code: `const greet = (name: string) => \`Hello, \${name}!\`;\nconsole.log(greet('World'));`,
+    language: 'typescript',
+    filename: 'greet.ts',
+  },
+  {
+    code: `function add(a, b) { return ???; }`, // BROKEN
+    language: 'javascript',
+    filename: 'add.js',
+  },
+  {
+    code: `export const PI = BROKEN_VALUE;`, // BROKEN
+    language: 'typescript',
+    filename: 'constants.ts',
+  },
+]
+
+async function main() {
+  const apiKey = process.env.LLM_API_KEY || 'sk-demo-1234567890abcdef'
+  const client = createMockLLMClient(apiKey)
+
+  const options: AutoFixOptions = {
+    maxRetries: 3,
+    language: 'typescript',
+    contextHint: 'These are documentation examples for a math utility library',
+  }
+
+  try {
+    console.log(`Processing ${examples.length} examples...\n`)
+    const results = await autoFixBatch(examples, client, options)
+
+    results.forEach((result, index) => {
+      const example = examples[index]
+      console.log(`── Example ${index} (${example.filename}) ──`)
+      console.log(`   Fixed:    ${result.fixed}`)
+      console.log(`   Attempts: ${result.attempts}`)
+      if (result.error) {
+        console.log(`   Error:    ${result.error}`)
+      }
+      console.log(`   Code:     ${result.code.split('\n')[0]}...`)
+      console.log()
+    })
+
+    // Summary
+    const fixedCount = [...results.values()].filter((r) => r.fixed).length
+    console.log(`✅ ${fixedCount}/${results.size} examples fixed successfully`)
+
+    // Expected output:
+    // Processing 3 examples...
+    //
+    // ── Example 0 (greet.ts) ──
+    //    Fixed:    true
+    //    Attempts: 0
+    //    Code:     const greet = (name: string) => `Hello, ${name}!`;...
+    //
+    // ── Example 1 (add.js) ──
+    //    Fixed:    true
+    //    Attempts: 1
+    //    Code:     const greet = (name: string) => `Hello, ${name}!`;...
+    //
+    // ── Example 2 (constants.ts) ──
+    //    Fixed:    true
+    //    Attempts: 1
+    //    Code:     const greet = (name: string) => `Hello, ${name}!`;...
+    //
+    // ✅ 3/3 examples fixed successfully
+  } catch (error) {
+    console.error('Batch fix failed:', error instanceof Error ? error.message : error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `createTypeScriptValidator`
+
+```typescript
+function createTypeScriptValidator(): (code: string) => Promise<ValidationResult>
+```
+
+Use this to validate TypeScript code strings at runtime — perfect for checking LLM-generated code, user-submitted snippets, or dynamically built TypeScript before execution.
+
+Returns a validator function that accepts a TypeScript code string and resolves with a `ValidationResult` indicating whether the code is valid and any diagnostic errors found.
+
+#### Parameters
+
+This factory function takes no parameters.
+
+#### Returned Validator Function
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✅ | The TypeScript source code string to validate |
+
+#### Returns
+
+**`(code: string) => Promise<ValidationResult>`** — A reusable async validator function.
+
+Each call to the validator returns a `Promise<ValidationResult>`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `valid` | `boolean` | `true` if the code compiled without errors |
+| `errors` | `string[]` | List of TypeScript diagnostic messages; empty array if valid |
+
+#### When results are returned
+
+| Scenario | `valid` | `errors` |
+|----------|---------|----------|
+| Code compiles cleanly | `true` | `[]` |
+| Type errors or syntax issues found | `false` | Array of diagnostic messages |
+| Unexpected runtime failure | `false` | Single-element array with the caught error message |
+
+**Example:**
+
+```typescript example.ts
+import * as ts from 'typescript'
+
+// --- Inline types (do not import from autodocs) ---
+interface ValidationResult {
+  valid: boolean
+  errors: string[]
+}
+
+// --- Inline implementation matching the library's behavior ---
+function createTypeScriptValidator(): (code: string) => Promise<ValidationResult> {
+  return async (code: string): Promise<ValidationResult> => {
+    try {
+      const diagnostics: string[] = []
+
+      const result = ts.transpileModule(code, {
+        compilerOptions: {
+          strict: true,
+          noImplicitAny: true,
+          target: ts.ScriptTarget.ES2020,
+        },
+        reportDiagnostics: true,
+      })
+
+      if (result.diagnostics && result.diagnostics.length > 0) {
+        for (const diag of result.diagnostics) {
+          const message =
+            typeof diag.messageText === 'string'
+              ? diag.messageText
+              : diag.messageText.messageText
+          diagnostics.push(message)
+        }
+        return { valid: false, errors: diagnostics }
+      }
+
+      return { valid: true, errors: [] }
+    } catch (err) {
+      return {
+        valid: false,
+        errors: [err instanceof Error ? err.message : String(err)],
+      }
+    }
+  }
+}
+
+// --- Usage ---
+const validate = createTypeScriptValidator()
+
+async function main() {
+  try {
+    // ✅ Valid TypeScript
+    const validCode = `
+      const greet = (name: string): string => {
+        return \`Hello, \${name}!\`
+      }
+      console.log(greet('World'))
+    `
+
+    const validResult = await validate(validCode)
+    console.log('Valid code result:', validResult)
+    // Output: { valid: true, errors: [] }
+
+    // ❌ Invalid TypeScript — type mismatch
+    const invalidCode = `
+      const add = (a: number, b: number): number => {
+        return a + b
+      }
+      const result: string = add(1, 2)
+    `
+
+    const invalidResult = await validate(invalidCode)
+    console.log('Invalid code result:', invalidResult)
+    // Output: { valid: false, errors: ["Type 'number' is not assignable to type 'string'."] }
+
+    // ❌ Syntax error
+    const brokenCode = `
+      function broken( {
+        return 42
+    `
+
+    const brokenResult = await validate(brokenCode)
+    console.log('Broken code result:', brokenResult)
+    // Output: { valid: false, errors: ["',' expected.", ...] }
+
+  } catch (error) {
+    console.error('Unexpected failure:', error)
+  }
+}
+
+main()
+```
+
+### `createPythonValidator`
+
+```typescript
+function createPythonValidator(): (code: string) => Promise<ValidationResult>
+```
+
+Use this to validate Python code syntax and catch errors before execution, without needing a Python runtime wrapper or external validation service — just `python3` in your PATH.
+
+Returns a reusable validator function you can call repeatedly with different code strings. Each call spawns a `python3` process to perform real syntax checking.
+
+#### Parameters
+
+This factory function takes no parameters.
+
+#### Returns
+
+| Return | Type | Description |
+|--------|------|-------------|
+| validator | `(code: string) => Promise<ValidationResult>` | Async function that validates a Python code string |
+
+#### `ValidationResult` Shape
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `valid` | `boolean` | `true` if the code passed validation, `false` if errors were found |
+| `errors` | `string[]` | List of error messages; empty array when `valid` is `true` |
+
+#### When each value is returned
+
+- **`valid: true`** — Python code is syntactically correct and parseable
+- **`valid: false`** — Code contains syntax errors, indentation issues, or other parse-time problems; `errors` will contain the Python error output
+
+#### Requirements
+
+- `python3` must be available in your system `PATH`
+- Works by writing code to a temp file and running `python3 -m py_compile` against it
+
+**Example:**
+
+```typescript example.ts
+import { spawnSync } from 'child_process'
+import { writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// Inline the ValidationResult type (matches the library's shape)
+type ValidationResult = {
+  valid: boolean
+  errors: string[]
+}
+
+// Self-contained implementation matching the library's behavior
+function createPythonValidator(): (code: string) => Promise<ValidationResult> {
+  return async (code: string): Promise<ValidationResult> => {
+    const tmpFile = join(tmpdir(), `validate_${Date.now()}.py`)
+
+    try {
+      writeFileSync(tmpFile, code, 'utf8')
+
+      const result = spawnSync('python3', ['-m', 'py_compile', tmpFile], {
+        encoding: 'utf8',
+        timeout: 10_000,
+      })
+
+      if (result.status === 0) {
+        return { valid: true, errors: [] }
+      }
+
+      const errorOutput = result.stderr || result.stdout || 'Unknown error'
+      // Strip the temp file path from error messages for cleaner output
+      const cleanedError = errorOutput.replace(tmpFile, '<code>')
+      return { valid: false, errors: [cleanedError.trim()] }
+    } catch (err) {
+      return {
+        valid: false,
+        errors: [`Validator error: ${err instanceof Error ? err.message : String(err)}`],
+      }
+    } finally {
+      try { unlinkSync(tmpFile) } catch { /* ignore cleanup errors */ }
+    }
+  }
+}
+
+// --- Usage ---
+
+const validate = createPythonValidator()
+
+async function main() {
+  try {
+    // ✅ Valid Python
+    const validCode = `
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+print(greet("world"))
+`.trim()
+
+    const validResult = await validate(validCode)
+    console.log('Valid code result:', validResult)
+    // Output: { valid: true, errors: [] }
+
+    // ❌ Invalid Python (bad indentation + missing colon)
+    const invalidCode = `
+def broken(x)
+  return x * 2
+`.trim()
+
+    const invalidResult = await validate(invalidCode)
+    console.log('Invalid code result:', invalidResult)
+    // Output: { valid: false, errors: ['  File "<code>", line 1\n    def broken(x)\n              ^\nSyntaxError: expected \':\'' ] }
+
+  } catch (error) {
+    console.error('Unexpected failure:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+