skrypt-ai 0.3.4 → 0.4.0

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

@@ -0,0 +1,613 @@
+## Functions
+
+### `writeLlmsTxt`
+
+```typescript
+async function writeLlmsTxt(docs: GeneratedDoc[], outputDir: string, options: { projectName?: string; description?: string } = {}): Promise<void>
+```
+
+Use this to generate an `llms.txt` file for your API documentation, making it discoverable and consumable by LLM-powered answer engines following the [llmstxt.org](https://llmstxt.org) convention.
+
+This is particularly useful for Answer Engine Optimization (AEO) — the equivalent of SEO but for AI assistants and LLM-based search tools.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | Yes | Array of generated documentation objects to include in the output file |
+| `outputDir` | `string` | Yes | Directory path where the `llms.txt` file will be written |
+| `options` | `object` | No | Optional configuration for the output file |
+| `options.projectName` | `string` | No | Name of the project/API (defaults to `'API'`) |
+| `options.description` | `string` | No | Short description of the project included in the file header |
+
+#### Returns
+
+`Promise<void>` — Resolves when the `llms.txt` file has been successfully written to `outputDir`. Rejects if the directory cannot be created or the file cannot be written.
+
+## Output Format
+
+The generated `llms.txt` file follows the [llmstxt.org](https://llmstxt.org) specification, which structures documentation in a way that LLMs can efficiently parse and reference when answering questions about your API.
+
+**Example:**
+
+```typescript example.ts
+import { mkdir, writeFile } from 'fs/promises'
+import { join } from 'path'
+import * as os from 'os'
+import * as path from 'path'
+
+// --- Inline types (mirrors the real GeneratedDoc shape) ---
+type GeneratedDoc = {
+  filePath: string
+  elementName: string
+  content: string
+  description?: string
+}
+
+// --- Self-contained implementation of writeLlmsTxt ---
+async function writeLlmsTxt(
+  docs: GeneratedDoc[],
+  outputDir: string,
+  options: { projectName?: string; description?: string } = {}
+): Promise<void> {
+  const projectName = options.projectName || 'API'
+  const description = options.description || ''
+
+  const lines: string[] = []
+
+  // Header block following llmstxt.org convention
+  lines.push(`# ${projectName}`)
+  if (description) {
+    lines.push('')
+    lines.push(`> ${description}`)
+  }
+  lines.push('')
+  lines.push('## Documentation')
+  lines.push('')
+
+  // List each documented element
+  for (const doc of docs) {
+    const label = doc.elementName || path.basename(doc.filePath)
+    lines.push(`- **${label}**: ${doc.description || doc.content.slice(0, 120).replace(/\n/g, ' ')}`)
+  }
+
+  lines.push('')
+  lines.push(`---`)
+  lines.push(`Generated by autodocs • ${new Date().toISOString()}`)
+
+  const outputPath = join(outputDir, 'llms.txt')
+
+  await mkdir(outputDir, { recursive: true })
+  await writeFile(outputPath, lines.join('\n'), 'utf-8')
+
+  console.log(`✅ llms.txt written to: ${outputPath}`)
+}
+
+// --- Example usage ---
+const exampleDocs: GeneratedDoc[] = [
+  {
+    filePath: 'src/auth/login.ts',
+    elementName: 'login',
+    description: 'Authenticates a user and returns a session token.',
+    content: 'async function login(email: string, password: string): Promise<string>',
+  },
+  {
+    filePath: 'src/auth/logout.ts',
+    elementName: 'logout',
+    description: 'Invalidates the current session token.',
+    content: 'async function logout(token: string): Promise<void>',
+  },
+  {
+    filePath: 'src/users/getUser.ts',
+    elementName: 'getUser',
+    description: 'Fetches a user record by their unique ID.',
+    content: 'async function getUser(userId: string): Promise<User>',
+  },
+]
+
+async function main() {
+  // Write to a temp directory so this example is safe to run anywhere
+  const outputDir = join(os.tmpdir(), 'autodocs-example')
+
+  try {
+    await writeLlmsTxt(exampleDocs, outputDir, {
+      projectName: 'MyApp API',
+      description: 'REST and SDK documentation for the MyApp platform.',
+    })
+
+    // Verify the output
+    const { readFile } = await import('fs/promises')
+    const content = await readFile(join(outputDir, 'llms.txt'), 'utf-8')
+    console.log('\n--- Generated llms.txt ---\n')
+    console.log(content)
+    // Expected output:
+    // # MyApp API
+    //
+    // > REST and SDK documentation for the MyApp platform.
+    //
+    // ## Documentation
+    //
+    // - **login**: Authenticates a user and returns a session token.
+    // - **logout**: Invalidates the current session token.
+    // - **getUser**: Fetches a user record by their unique ID.
+    //
+    // ---
+    // Generated by autodocs • 2024-01-15T10:30:00.000Z
+  } catch (error) {
+    console.error('❌ Failed to write llms.txt:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `writeDocsToDirectory`
+
+```typescript
+async function writeDocsToDirectory(results: FileGenerationResult[], outputDir: string, sourceDir: string): Promise<{ filesWritten: number; totalDocs: number }>
+```
+
+Use this to persist generated documentation to disk, writing markdown files into an output directory while preserving the relative structure of your source directory.
+
+After generating docs for your source files, pass the results to this function to write them out as organized markdown files. It handles directory creation automatically and maps each source file to a corresponding output path.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `results` | `FileGenerationResult[]` | ✅ | Array of generation results, each containing a source file path and its generated documentation entries |
+| `outputDir` | `string` | ✅ | Root directory where documentation files will be written (created if it doesn't exist) |
+| `sourceDir` | `string` | ✅ | Root directory of your source files — used to compute relative paths so the output structure mirrors your source layout |
+
+#### Returns
+
+Returns a `Promise` that resolves to an object with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `filesWritten` | `number` | Number of markdown files successfully written to disk |
+| `totalDocs` | `number` | Total number of individual documentation entries across all files |
+
+### Notes
+
+- Output directories are created recursively — no need to pre-create nested folders
+- Source file paths are made relative to `sourceDir` to determine output paths, so `/src/utils/math.ts` becomes `<outputDir>/utils/math.md`
+- Files with no generated docs are skipped and won't count toward `filesWritten`
+
+**Example:**
+
+```typescript example.ts
+import { mkdir, writeFile } from 'fs/promises'
+import { join, dirname, relative, basename } from 'path'
+
+// --- Inline types (mirrors autodocs internals) ---
+interface GeneratedDoc {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'type'
+  markdown: string
+}
+
+interface FileGenerationResult {
+  sourceFile: string
+  docs: GeneratedDoc[]
+  error?: string
+}
+
+// --- Inline implementation of writeDocsToDirectory ---
+async function writeDocsToDirectory(
+  results: FileGenerationResult[],
+  outputDir: string,
+  sourceDir: string
+): Promise<{ filesWritten: number; totalDocs: number }> {
+  let filesWritten = 0
+  let totalDocs = 0
+
+  for (const result of results) {
+    if (result.error || result.docs.length === 0) continue
+
+    // Mirror source structure in output directory
+    const relativePath = relative(sourceDir, result.sourceFile)
+    const outputFile = join(
+      outputDir,
+      relativePath.replace(/\.(ts|tsx|js|jsx)$/, '.md')
+    )
+
+    // Combine all docs for this file into one markdown file
+    const content = result.docs
+      .map((doc) => `## ${doc.name}\n\n${doc.markdown}`)
+      .join('\n\n---\n\n')
+
+    await mkdir(dirname(outputFile), { recursive: true })
+    await writeFile(outputFile, content, 'utf-8')
+
+    filesWritten++
+    totalDocs += result.docs.length
+  }
+
+  return { filesWritten, totalDocs }
+}
+
+// --- Realistic usage example ---
+const mockResults: FileGenerationResult[] = [
+  {
+    sourceFile: '/project/src/utils/math.ts',
+    docs: [
+      {
+        name: 'add',
+        kind: 'function',
+        markdown: 'Adds two numbers together.\n\n**Params:** `a: number`, `b: number`\n\n**Returns:** `number`',
+      },
+      {
+        name: 'multiply',
+        kind: 'function',
+        markdown: 'Multiplies two numbers.\n\n**Params:** `a: number`, `b: number`\n\n**Returns:** `number`',
+      },
+    ],
+  },
+  {
+    sourceFile: '/project/src/api/client.ts',
+    docs: [
+      {
+        name: 'ApiClient',
+        kind: 'class',
+        markdown: 'HTTP client for interacting with the REST API.\n\n**Constructor:** `new ApiClient(baseUrl: string)`',
+      },
+    ],
+  },
+  {
+    // Simulates a file that failed to generate — should be skipped
+    sourceFile: '/project/src/broken/module.ts',
+    docs: [],
+    error: 'Parse error: unexpected token',
+  },
+]
+
+async function main() {
+  const outputDir = process.env.DOCS_OUTPUT_DIR || './docs-output'
+  const sourceDir = '/project/src'
+
+  try {
+    const { filesWritten, totalDocs } = await writeDocsToDirectory(
+      mockResults,
+      outputDir,
+      sourceDir
+    )
+
+    console.log(`✅ Documentation written successfully`)
+    console.log(`   Files written : ${filesWritten}`)  // Files written : 2
+    console.log(`   Total docs    : ${totalDocs}`)     // Total docs    : 3
+    // Output files:
+    //   ./docs-output/utils/math.md      (2 docs: add, multiply)
+    //   ./docs-output/api/client.md      (1 doc:  ApiClient)
+    //   ./docs-output/broken/module.md   ← skipped (error + no docs)
+  } catch (error) {
+    console.error('Failed to write docs:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `groupDocsByFile`
+
+```typescript
+function groupDocsByFile(docs: GeneratedDoc[]): FileGenerationResult[]
+```
+
+Use this to organize a flat list of generated documentation objects into groups by their source file, making it easy to write one output file per source file.
+
+This is the key step between generating individual doc entries and writing them to disk — it collapses a flat array into a file-keyed structure so you can iterate over files and write each one independently.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ | Flat array of generated documentation objects, each containing an `element` with a `filePath` property |
+
+#### Returns
+
+Returns `FileGenerationResult[]` — an array of objects where each entry represents one source file and contains all the `GeneratedDoc` entries that belong to it.
+
+| Scenario | Result |
+|----------|--------|
+| Multiple docs from the same file | Grouped into a single `FileGenerationResult` |
+| Docs from different files | Each file gets its own `FileGenerationResult` |
+| Empty array passed | Returns an empty array `[]` |
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (do not import from autodocs) ──────────────────────────────
+
+interface CodeElement {
+  name: string
+  filePath: string
+  kind: 'function' | 'class' | 'interface' | 'type'
+  signature: string
+}
+
+interface GeneratedDoc {
+  element: CodeElement
+  markdown: string
+  generatedAt: Date
+}
+
+interface FileGenerationResult {
+  filePath: string
+  docs: GeneratedDoc[]
+}
+
+// ── Inline implementation ────────────────────────────────────────────────────
+
+function groupDocsByFile(docs: GeneratedDoc[]): FileGenerationResult[] {
+  const byFile = new Map<string, GeneratedDoc[]>()
+
+  for (const doc of docs) {
+    const file = doc.element.filePath
+    if (!byFile.has(file)) {
+      byFile.set(file, [])
+    }
+    byFile.get(file)!.push(doc)
+  }
+
+  return Array.from(byFile.entries()).map(([filePath, docs]) => ({
+    filePath,
+    docs,
+  }))
+}
+
+// ── Realistic usage example ──────────────────────────────────────────────────
+
+const generatedDocs: GeneratedDoc[] = [
+  {
+    element: {
+      name: 'fetchUser',
+      filePath: 'src/api/users.ts',
+      kind: 'function',
+      signature: 'function fetchUser(id: string): Promise<User>',
+    },
+    markdown: '## fetchUser\n\nFetches a user by ID.',
+    generatedAt: new Date('2024-01-15T10:00:00Z'),
+  },
+  {
+    element: {
+      name: 'createUser',
+      filePath: 'src/api/users.ts',   // same file as fetchUser
+      kind: 'function',
+      signature: 'function createUser(data: UserInput): Promise<User>',
+    },
+    markdown: '## createUser\n\nCreates a new user.',
+    generatedAt: new Date('2024-01-15T10:00:01Z'),
+  },
+  {
+    element: {
+      name: 'AuthService',
+      filePath: 'src/services/auth.ts', // different file
+      kind: 'class',
+      signature: 'class AuthService',
+    },
+    markdown: '## AuthService\n\nHandles authentication.',
+    generatedAt: new Date('2024-01-15T10:00:02Z'),
+  },
+  {
+    element: {
+      name: 'UserRole',
+      filePath: 'src/types/roles.ts',   // another file
+      kind: 'type',
+      signature: "type UserRole = 'admin' | 'editor' | 'viewer'",
+    },
+    markdown: '## UserRole\n\nDefines available user roles.',
+    generatedAt: new Date('2024-01-15T10:00:03Z'),
+  },
+]
+
+try {
+  const fileGroups = groupDocsByFile(generatedDocs)
+
+  console.log(`Grouped ${generatedDocs.length} docs into ${fileGroups.length} files:\n`)
+
+  for (const group of fileGroups) {
+    const names = group.docs.map(d => d.element.name).join(', ')
+    console.log(`  📄 ${group.filePath}`)
+    console.log(`     ${group.docs.length} export(s): ${names}\n`)
+  }
+
+  // Expected output:
+  // Grouped 4 docs into 3 files:
+  //
+  //   📄 src/api/users.ts
+  //      2 export(s): fetchUser, createUser
+  //
+  //   📄 src/services/auth.ts
+  //      1 export(s): AuthService
+  //
+  //   📄 src/types/roles.ts
+  //      1 export(s): UserRole
+
+  // Show how you'd use this to write files
+  console.log('--- Ready to write output files ---')
+  for (const group of fileGroups) {
+    const combinedMarkdown = group.docs.map(d => d.markdown).join('\n\n---\n\n')
+    console.log(`Would write ${combinedMarkdown.length} chars to docs for: ${group.filePath}`)
+  }
+} catch (error) {
+  console.error('Failed to group docs:', error)
+}
+```
+
+### `writeDocsByTopic`
+
+```typescript
+async function writeDocsByTopic(docs: GeneratedDoc[], outputDir: string): Promise<{ filesWritten: number; totalDocs: number; topics: Topic[] }>
+```
+
+Use this to write generated documentation files to disk, organized into topic-based subdirectories — ideal for creating structured doc sites where related functions and classes are grouped together.
+
+Instead of dumping all docs into a flat directory, `writeDocsByTopic` automatically clusters your `GeneratedDoc` entries by topic and writes each one into the appropriate subfolder, returning a summary of what was written.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `GeneratedDoc[]` | ✅ | Array of generated documentation objects to organize and write |
+| `outputDir` | `string` | ✅ | Root directory where topic-organized subdirectories and files will be created |
+
+#### Returns
+
+Returns a `Promise` that resolves to an object with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `filesWritten` | `number` | Number of markdown files successfully written to disk |
+| `totalDocs` | `number` | Total number of docs processed (may differ from `filesWritten` if some were skipped) |
+| `topics` | `Topic[]` | Array of topic objects describing how docs were grouped, useful for generating a table of contents |
+
+## Notes
+
+- Output directories are created automatically if they don't exist
+- Each `Topic` in the returned array contains the topic name and the docs assigned to it
+- Docs without an explicit topic may be grouped under a default/uncategorized topic
+- Useful as a final step in a doc generation pipeline after parsing and formatting
+
+**Example:**
+
+```typescript example.ts
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+// ── Inline types (mirrors autodocs internals) ────────────────────────────────
+
+type GeneratedDoc = {
+  elementName: string
+  topic: string
+  filePath: string
+  markdown: string
+}
+
+type Topic = {
+  name: string
+  slug: string
+  docs: GeneratedDoc[]
+}
+
+// ── Inline implementation (mirrors autodocs behaviour) ───────────────────────
+
+function organizeByTopic(docs: GeneratedDoc[]): Topic[] {
+  const map = new Map<string, GeneratedDoc[]>()
+  for (const doc of docs) {
+    const key = doc.topic || 'general'
+    if (!map.has(key)) map.set(key, [])
+    map.get(key)!.push(doc)
+  }
+  return Array.from(map.entries()).map(([name, topicDocs]) => ({
+    name,
+    slug: name.toLowerCase().replace(/\s+/g, '-'),
+    docs: topicDocs,
+  }))
+}
+
+async function writeDocsByTopic(
+  docs: GeneratedDoc[],
+  outputDir: string
+): Promise<{ filesWritten: number; totalDocs: number; topics: Topic[] }> {
+  let filesWritten = 0
+  const topics = organizeByTopic(docs)
+
+  for (const topic of topics) {
+    const topicDir = path.join(outputDir, topic.slug)
+    await fs.mkdir(topicDir, { recursive: true })
+
+    for (const doc of topic.docs) {
+      const fileName = `${doc.elementName.toLowerCase().replace(/\s+/g, '-')}.md`
+      const filePath = path.join(topicDir, fileName)
+      await fs.writeFile(filePath, doc.markdown, 'utf8')
+      filesWritten++
+    }
+  }
+
+  return { filesWritten, totalDocs: docs.length, topics }
+}
+
+// ── Example usage ─────────────────────────────────────────────────────────────
+
+const sampleDocs: GeneratedDoc[] = [
+  {
+    elementName: 'fetchUser',
+    topic: 'API',
+    filePath: 'src/api/fetchUser.ts',
+    markdown: '# fetchUser\n\nFetches a user by ID from the REST API.\n',
+  },
+  {
+    elementName: 'createUser',
+    topic: 'API',
+    filePath: 'src/api/createUser.ts',
+    markdown: '# createUser\n\nCreates a new user record.\n',
+  },
+  {
+    elementName: 'hashPassword',
+    topic: 'Auth',
+    filePath: 'src/auth/hashPassword.ts',
+    markdown: '# hashPassword\n\nHashes a plaintext password using bcrypt.\n',
+  },
+  {
+    elementName: 'formatDate',
+    topic: 'Utils',
+    filePath: 'src/utils/formatDate.ts',
+    markdown: '# formatDate\n\nFormats a Date object into a locale string.\n',
+  },
+]
+
+async function main() {
+  // Write to a temp directory so the example is safe to run anywhere
+  const outputDir = path.join(os.tmpdir(), 'autodocs-example-output')
+
+  try {
+    console.log(`Writing docs to: ${outputDir}`)
+
+    const result = await writeDocsByTopic(sampleDocs, outputDir)
+
+    console.log('\n✅ Done!')
+    console.log(`   Files written : ${result.filesWritten}`)
+    console.log(`   Total docs    : ${result.totalDocs}`)
+    console.log(`   Topics found  : ${result.topics.map(t => t.name).join(', ')}`)
+
+    // Show the directory tree that was created
+    console.log('\n📁 Output structure:')
+    for (const topic of result.topics) {
+      console.log(`  ${outputDir}/${topic.slug}/`)
+      for (const doc of topic.docs) {
+        console.log(`    └─ ${doc.elementName.toLowerCase()}.md`)
+      }
+    }
+
+    // Expected output:
+    // ✅ Done!
+    //    Files written : 4
+    //    Total docs    : 4
+    //    Topics found  : API, Auth, Utils
+    //
+    // 📁 Output structure:
+    //   /tmp/autodocs-example-output/api/
+    //     └─ fetchuser.md
+    //     └─ createuser.md
+    //   /tmp/autodocs-example-output/auth/
+    //     └─ hashpassword.md
+    //   /tmp/autodocs-example-output/utils/
+    //     └─ formatdate.md
+
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Failed to write docs:', error.message)
+    } else {
+      console.error('Unexpected error:', error)
+    }
+    process.exit(1)
+  }
+}
+
+main()
+```
+