skrypt-ai 0.3.4 → 0.4.0

package/dist/template/src/app/docs/scanner/content-type.md

@@ -0,0 +1,599 @@
+# Content-type.ts
+
+## Functions
+
+### `classifyElement`
+
+```typescript
+function classifyElement(element: APIElement): ContentClassification
+```
+
+Use this to determine what type of documentation an API element needs — whether it should be documented as an API reference, a guide, or a tutorial — so you can route elements to the correct documentation generator automatically.
+
+This function analyzes an `APIElement` and returns a `ContentClassification` indicating the most appropriate documentation style, along with reasoning scores and explanations for the decision.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `element` | `APIElement` | ✅ | The API element to classify (function, class, type, etc.) |
+
+## Returns
+
+Returns a `ContentClassification` object containing:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'api' \| 'guide' \| 'tutorial'` | The recommended documentation type |
+| `reasons` | `string[]` | Human-readable explanations for the classification |
+| `scores` | `{ api: number, guide: number, tutorial: number }` | Numeric confidence scores for each type |
+
+The classification with the **highest score** wins. If scores are tied, `api` takes precedence over `guide`, which takes precedence over `tutorial`.
+
+**Example:**
+
+```typescript example.ts
+// ---- Inline types (do not import from autodocs) ----
+type APIElementKind = 'function' | 'class' | 'interface' | 'type' | 'variable' | 'enum'
+
+interface APIElement {
+  name: string
+  kind: APIElementKind
+  description?: string
+  parameters?: { name: string; type: string; description?: string }[]
+  returns?: { type: string; description?: string }
+  examples?: string[]
+  complexity?: 'low' | 'medium' | 'high'
+  tags?: string[]
+}
+
+interface ContentClassification {
+  type: 'api' | 'guide' | 'tutorial'
+  reasons: string[]
+  scores: {
+    api: number
+    guide: number
+    tutorial: number
+  }
+}
+
+// ---- Simulated classifyElement implementation ----
+function classifyElement(element: APIElement): ContentClassification {
+  const reasons: string[] = []
+  let apiScore = 0
+  let guideScore = 0
+  let tutorialScore = 0
+
+  // Simple functions/types with clear signatures lean toward API docs
+  if (element.kind === 'function' || element.kind === 'type' || element.kind === 'interface') {
+    apiScore += 2
+    reasons.push(`Kind "${element.kind}" is well-suited for API reference documentation`)
+  }
+
+  // Classes with high complexity benefit from a guide
+  if (element.kind === 'class') {
+    guideScore += 2
+    reasons.push('Classes often require conceptual explanation — guide recommended')
+  }
+
+  // Elements with examples suggest tutorial potential
+  if (element.examples && element.examples.length > 0) {
+    tutorialScore += element.examples.length
+    reasons.push(`${element.examples.length} example(s) found — tutorial content possible`)
+  }
+
+  // High complexity pushes toward guide or tutorial
+  if (element.complexity === 'high') {
+    guideScore += 2
+    tutorialScore += 1
+    reasons.push('High complexity suggests a guide or tutorial would help users')
+  }
+
+  // Parameters increase API doc value
+  if (element.parameters && element.parameters.length > 0) {
+    apiScore += element.parameters.length
+    reasons.push(`${element.parameters.length} parameter(s) documented — strong API reference candidate`)
+  }
+
+  // Tags like 'quickstart' or 'walkthrough' push toward tutorial
+  if (element.tags?.includes('quickstart') || element.tags?.includes('walkthrough')) {
+    tutorialScore += 3
+    reasons.push('Tags indicate this element is intended as a walkthrough or quickstart')
+  }
+
+  const scores = { api: apiScore, guide: guideScore, tutorial: tutorialScore }
+
+  let type: 'api' | 'guide' | 'tutorial' = 'api'
+  if (guideScore > apiScore && guideScore >= tutorialScore) type = 'guide'
+  else if (tutorialScore > apiScore && tutorialScore > guideScore) type = 'tutorial'
+
+  return { type, reasons, scores }
+}
+
+// ---- Example usage ----
+async function main() {
+  try {
+    // Example 1: A simple utility function → expect API classification
+    const utilFunction: APIElement = {
+      name: 'formatDate',
+      kind: 'function',
+      description: 'Formats a Date object into a locale string',
+      parameters: [
+        { name: 'date', type: 'Date', description: 'The date to format' },
+        { name: 'locale', type: 'string', description: 'BCP 47 locale string' }
+      ],
+      returns: { type: 'string', description: 'Formatted date string' },
+      complexity: 'low'
+    }
+
+    const result1 = classifyElement(utilFunction)
+    console.log('=== formatDate (simple function) ===')
+    console.log('Type:', result1.type)           // Expected: 'api'
+    console.log('Scores:', result1.scores)        // Expected: { api: 4, guide: 0, tutorial: 0 }
+    console.log('Reasons:', result1.reasons)
+    console.log()
+
+    // Example 2: A complex class → expect guide classification
+    const complexClass: APIElement = {
+      name: 'QueryBuilder',
+      kind: 'class',
+      description: 'Fluent interface for constructing database queries',
+      complexity: 'high',
+      examples: ['builder.select("*").from("users").where("id = 1").build()']
+    }
+
+    const result2 = classifyElement(complexClass)
+    console.log('=== QueryBuilder (complex class) ===')
+    console.log('Type:', result2.type)           // Expected: 'guide'
+    console.log('Scores:', result2.scores)        // Expected: { api: 0, guide: 4, tutorial: 2 }
+    console.log('Reasons:', result2.reasons)
+    console.log()
+
+    // Example 3: A tagged walkthrough function → expect tutorial classification
+    const walkthroughFn: APIElement = {
+      name: 'setupAuthFlow',
+      kind: 'function',
+      description: 'Walks through setting up OAuth2 authentication end-to-end',
+      complexity: 'medium',
+      tags: ['quickstart', 'walkthrough'],
+      examples: [
+        'setupAuthFlow({ provider: "github" })',
+        'setupAuthFlow({ provider: "google", scopes: ["email"] })'
+      ]
+    }
+
+    const result3 = classifyElement(walkthroughFn)
+    console.log('=== setupAuthFlow (walkthrough) ===')
+    console.log('Type:', result3.type)           // Expected: 'tutorial'
+    console.log('Scores:', result3.scores)        // Expected: { api: 2, guide: 0, tutorial: 7 }
+    console.log('Reasons:', result3.reasons)
+
+  } catch (error) {
+    console.error('Classification failed:', error)
+  }
+}
+
+main()
+```
+
+### `classifyElements`
+
+```typescript
+function classifyElements(elements: APIElement[]): Map<ContentType, APIElement[]>
+```
+
+Use this to sort a mixed list of documentation elements into typed groups — API references, guides, tutorials, and overviews — in a single pass.
+
+Instead of manually filtering arrays for each content type, `classifyElements` returns a `Map` keyed by content type so you can immediately access any group by name.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elements` | `APIElement[]` | ✅ | Array of documentation elements to classify. Each element must have enough metadata for type detection (e.g., `kind`, `tags`, or `category` fields). |
+
+### Returns
+
+A `Map<ContentType, APIElement[]>` where:
+
+| Key | Value |
+|-----|-------|
+| `"api"` | Elements classified as API references (functions, classes, types) |
+| `"guide"` | Elements classified as how-to guides |
+| `"tutorial"` | Elements classified as step-by-step tutorials |
+| `"overview"` | Elements classified as high-level overviews or introductions |
+
+All four keys are always present in the returned map — groups with no matching elements return an empty array, so you never need to guard against `undefined`.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type ContentType = 'api' | 'guide' | 'tutorial' | 'overview'
+
+interface APIElement {
+  id: string
+  title: string
+  kind: ContentType
+  tags?: string[]
+}
+
+// ── Inline implementation matching the real function's behavior ────────────
+
+function classifyElements(elements: APIElement[]): Map<ContentType, APIElement[]> {
+  const groups = new Map<ContentType, APIElement[]>([
+    ['api',      []],
+    ['guide',    []],
+    ['tutorial', []],
+    ['overview', []],
+  ])
+
+  for (const element of elements) {
+    const bucket = groups.get(element.kind)
+    if (bucket) {
+      bucket.push(element)
+    }
+  }
+
+  return groups
+}
+
+// ── Realistic usage example ────────────────────────────────────────────────
+
+const docElements: APIElement[] = [
+  { id: 'fn-001', title: 'createUser()',          kind: 'api',      tags: ['users', 'auth'] },
+  { id: 'fn-002', title: 'deleteUser()',          kind: 'api',      tags: ['users'] },
+  { id: 'gd-001', title: 'Authentication Guide',  kind: 'guide',    tags: ['auth'] },
+  { id: 'tu-001', title: 'Build Your First App',  kind: 'tutorial', tags: ['quickstart'] },
+  { id: 'tu-002', title: 'Deploy to Production',  kind: 'tutorial', tags: ['deployment'] },
+  { id: 'ov-001', title: 'Platform Overview',     kind: 'overview', tags: ['intro'] },
+]
+
+async function main() {
+  try {
+    const classified = classifyElements(docElements)
+
+    // Access each group directly by content type
+    const apiDocs   = classified.get('api')      ?? []
+    const guides    = classified.get('guide')    ?? []
+    const tutorials = classified.get('tutorial') ?? []
+    const overviews = classified.get('overview') ?? []
+
+    console.log('=== Classified Documentation Elements ===\n')
+
+    console.log(`API References (${apiDocs.length}):`)
+    apiDocs.forEach(el => console.log(`  • [${el.id}] ${el.title}`))
+
+    console.log(`\nGuides (${guides.length}):`)
+    guides.forEach(el => console.log(`  • [${el.id}] ${el.title}`))
+
+    console.log(`\nTutorials (${tutorials.length}):`)
+    tutorials.forEach(el => console.log(`  • [${el.id}] ${el.title}`))
+
+    console.log(`\nOverviews (${overviews.length}):`)
+    overviews.forEach(el => console.log(`  • [${el.id}] ${el.title}`))
+
+    // All four keys are always present — even for empty categories
+    const emptyElements: APIElement[] = []
+    const emptyMap = classifyElements(emptyElements)
+    console.log('\nEmpty input still returns all keys:', [...emptyMap.keys()])
+
+    // Expected output:
+    // === Classified Documentation Elements ===
+    //
+    // API References (2):
+    //   • [fn-001] createUser()
+    //   • [fn-002] deleteUser()
+    //
+    // Guides (1):
+    //   • [gd-001] Authentication Guide
+    //
+    // Tutorials (2):
+    //   • [tu-001] Build Your First App
+    //   • [tu-002] Deploy to Production
+    //
+    // Overviews (1):
+    //   • [ov-001] Platform Overview
+    //
+    // Empty input still returns all keys: [ 'api', 'guide', 'tutorial', 'overview' ]
+
+  } catch (error) {
+    console.error('Classification failed:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `getRecommendedStructure`
+
+```typescript
+function getRecommendedStructure(elements: APIElement[]): {
+  sections: { name: string; type: ContentType; elements: APIElement[] }[]
+  stats: { api: number; guide: number; tutorial: number; overview: number }
+}
+```
+
+Use this to automatically organize a list of API elements into a recommended documentation structure — grouping them into logical sections (API reference, guides, tutorials, overviews) and providing a count breakdown by content type.
+
+This is ideal when you have a mixed set of API elements and want a ready-made layout for generating a documentation site or navigation structure.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `elements` | `APIElement[]` | ✅ Yes | Array of API elements (functions, classes, types, etc.) to analyze and organize |
+
+## Returns
+
+An object with two properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `sections` | `{ name: string; type: ContentType; elements: APIElement[] }[]` | Ordered list of recommended documentation sections, each with a display name, content type, and the elements that belong to it |
+| `stats` | `{ api: number; guide: number; tutorial: number; overview: number }` | Count of elements assigned to each content type category |
+
+### `ContentType` values
+- `"api"` — Reference documentation for functions, classes, and types
+- `"guide"` — How-to and conceptual content
+- `"tutorial"` — Step-by-step walkthroughs
+- `"overview"` — High-level introductory content
+
+### When sections are empty
+If no elements match a particular content type, that section will either be omitted or appear with an empty `elements` array — use `stats` to quickly check which categories have content before rendering.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type ContentType = 'api' | 'guide' | 'tutorial' | 'overview'
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'type' | 'variable' | 'module'
+  description?: string
+  tags?: string[]
+}
+
+type RecommendedStructure = {
+  sections: { name: string; type: ContentType; elements: APIElement[] }[]
+  stats: { api: number; guide: number; tutorial: number; overview: number }
+}
+
+// ── Simulated implementation of getRecommendedStructure ───────────────────
+
+function classifyElement(el: APIElement): ContentType {
+  const tags = el.tags ?? []
+  if (tags.includes('tutorial')) return 'tutorial'
+  if (tags.includes('guide')) return 'guide'
+  if (tags.includes('overview') || el.kind === 'module') return 'overview'
+  return 'api'
+}
+
+function getRecommendedStructure(elements: APIElement[]): RecommendedStructure {
+  const buckets: Record<ContentType, APIElement[]> = {
+    overview: [],
+    guide: [],
+    tutorial: [],
+    api: [],
+  }
+
+  for (const el of elements) {
+    buckets[classifyElement(el)].push(el)
+  }
+
+  const sectionMeta: { type: ContentType; name: string }[] = [
+    { type: 'overview',  name: 'Overview'       },
+    { type: 'guide',     name: 'Guides'          },
+    { type: 'tutorial',  name: 'Tutorials'       },
+    { type: 'api',       name: 'API Reference'   },
+  ]
+
+  const sections = sectionMeta
+    .filter(({ type }) => buckets[type].length > 0)
+    .map(({ type, name }) => ({ name, type, elements: buckets[type] }))
+
+  const stats = {
+    api:      buckets.api.length,
+    guide:    buckets.guide.length,
+    tutorial: buckets.tutorial.length,
+    overview: buckets.overview.length,
+  }
+
+  return { sections, stats }
+}
+
+// ── Example usage ──────────────────────────────────────────────────────────
+
+const elements: APIElement[] = [
+  {
+    name: 'AuthClient',
+    kind: 'class',
+    description: 'Handles authentication flows',
+  },
+  {
+    name: 'createToken',
+    kind: 'function',
+    description: 'Generates a signed JWT token',
+  },
+  {
+    name: 'TokenOptions',
+    kind: 'interface',
+    description: 'Options passed to createToken',
+  },
+  {
+    name: 'Getting Started',
+    kind: 'module',
+    description: 'Introduction to the auth library',
+    tags: ['overview'],
+  },
+  {
+    name: 'Securing Routes',
+    kind: 'module',
+    description: 'How to protect API endpoints',
+    tags: ['guide'],
+  },
+  {
+    name: 'Build a Login Flow',
+    kind: 'module',
+    description: 'Step-by-step login implementation',
+    tags: ['tutorial'],
+  },
+]
+
+async function main() {
+  try {
+    const { sections, stats } = getRecommendedStructure(elements)
+
+    console.log('📊 Content stats:', stats)
+    // Output: { api: 3, guide: 1, tutorial: 1, overview: 1 }
+
+    console.log('\n📚 Recommended sections:')
+    for (const section of sections) {
+      console.log(`\n  [${section.type.toUpperCase()}] ${section.name}`)
+      for (const el of section.elements) {
+        console.log(`    • ${el.name} (${el.kind})`)
+      }
+    }
+    /*
+      Output:
+      [OVERVIEW] Overview
+        • Getting Started (module)
+      [GUIDE] Guides
+        • Securing Routes (module)
+      [TUTORIAL] Tutorials
+        • Build a Login Flow (module)
+      [API] API Reference
+        • AuthClient (class)
+        • createToken (function)
+        • TokenOptions (interface)
+    */
+
+    // Practical use: only render sections that have content
+    const hasApiDocs = stats.api > 0
+    console.log('\n✅ Has API reference docs:', hasApiDocs)
+    // Output: true
+
+  } catch (error) {
+    console.error('Failed to build documentation structure:', error)
+  }
+}
+
+main()
+```
+
+### `getPromptForContentType`
+
+```typescript
+function getPromptForContentType(type: ContentType): string
+```
+
+Use this to get the appropriate documentation generation prompt string for a given content type, so you can pass the right instructions to an LLM when auto-generating docs for APIs, components, functions, or other code elements.
+
+This function acts as a prompt router — given a content type identifier, it returns a tailored prompt string that instructs a documentation generator on what to include and how to format the output for that specific type.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `ContentType` | ✅ | The category of content to document. Determines which prompt template is returned. |
+
+### `ContentType` Values
+
+| Value | Description |
+|-------|-------------|
+| `'api'` | REST API endpoints or API reference elements |
+| `'component'` | UI components (e.g., React, Vue) |
+| `'function'` | Standalone functions or methods |
+| `'class'` | Classes and their members |
+
+### Returns
+
+Returns a `string` containing a structured prompt with documentation instructions tailored to the given content type. The prompt includes guidance on what sections to cover (e.g., parameters, return values, usage examples).
+
+**Example:**
+
+```typescript example.ts
+// Inline the ContentType definition — no external imports needed
+type ContentType = 'api' | 'component' | 'function' | 'class'
+
+// Self-contained implementation matching the autodocs behavior
+function getPromptForContentType(type: ContentType): string {
+  switch (type) {
+    case 'api':
+      return `Generate detailed API reference documentation. Include:
+- Clear parameter descriptions with types
+- Return value documentation
+- HTTP method and endpoint details
+- Request/response examples
+- Error codes and handling`
+
+    case 'component':
+      return `Generate component documentation. Include:
+- Props table with types and defaults
+- Usage examples with JSX
+- Event handlers and callbacks
+- Accessibility considerations`
+
+    case 'function':
+      return `Generate function documentation. Include:
+- Parameter names, types, and descriptions
+- Return type and value description
+- Usage examples
+- Edge cases and error handling`
+
+    case 'class':
+      return `Generate class documentation. Include:
+- Constructor parameters
+- Public methods and properties
+- Inheritance and interfaces
+- Instantiation examples`
+
+    default:
+      throw new Error(`Unsupported content type: ${type}`)
+  }
+}
+
+// --- Example usage ---
+
+const contentTypes: ContentType[] = ['api', 'component', 'function', 'class']
+
+async function main() {
+  try {
+    for (const type of contentTypes) {
+      const prompt = getPromptForContentType(type)
+
+      console.log(`\n=== Prompt for type: "${type}" ===`)
+      console.log(prompt)
+    }
+
+    // Practical use: feed the prompt into an LLM call
+    const targetType: ContentType = 'function'
+    const docPrompt = getPromptForContentType(targetType)
+
+    const llmRequest = {
+      model: 'gpt-4',
+      systemPrompt: docPrompt,
+      userContent: 'function add(a: number, b: number): number { return a + b }',
+    }
+
+    console.log('\n=== LLM Request Payload ===')
+    console.log(JSON.stringify(llmRequest, null, 2))
+    // Output:
+    // {
+    //   "model": "gpt-4",
+    //   "systemPrompt": "Generate function documentation. Include:\n- Parameter names...",
+    //   "userContent": "function add(a: number, b: number): number { return a + b }"
+    // }
+
+  } catch (error) {
+    console.error('Failed to get prompt:', error)
+  }
+}
+
+main()
+```
+