skrypt-ai 0.4.2 → 0.6.0

package/dist/template/content/docs/types.md

@@ -0,0 +1,531 @@
+---
+title: "Types & Interfaces"
+description: "Type definitions and interfaces"
+---
+
+<CardGroup cols={2}>
+  <Card title="TypeScriptScanner" icon="cube" href="#typescriptscanner">
+    Scans TS/JS source files
+  </Card>
+  <Card title="canHandle" icon="code" href="#canhandle">
+    Checks file scanner compatibility
+  </Card>
+  <Card title="scanFile" icon="code" href="#scanfile">
+    Extracts API elements from files
+  </Card>
+</CardGroup>
+
+
+## `TypeScriptScanner`
+
+```typescript
+class TypeScriptScanner implements Scanner
+```
+
+Use this to scan TypeScript and JavaScript source files and extract API elements (functions, classes, parameters, and metadata) for automated documentation generation.
+
+`TypeScriptScanner` implements the `Scanner` interface and uses the TypeScript compiler API to parse and analyze `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, and `.cjs` files. It skips declaration files (`.d.ts`) automatically.
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `languages` | `string[]` | Always `['typescript', 'javascript']` — the languages this scanner supports |
+
+## Methods
+
+### `canHandle(filePath: string): boolean`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the file to check |
+
+**Returns:** `true` if the file has a supported extension (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`) **and** is not a `.d.ts` declaration file. Use this before calling `scanFile` to avoid unsupported file errors.
+
+---
+
+### `scanFile(filePath: string): Promise<ScanResult>`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Path to the source file to scan and parse |
+
+**Returns:** A `Promise<ScanResult>` containing:
+- `language` — `'typescript'` for `.ts`/`.tsx` files, `'javascript'` for all others
+- `elements` — Array of `APIElement` objects representing discovered functions, classes, interfaces, and their parameters
+- `filePath` — The original file path passed in
+
+**Throws:** If the file cannot be read from disk or the TypeScript compiler fails to parse it.
+
+## Notes
+- Declaration files (`.d.ts`) are explicitly excluded from scanning even though they use the `.ts` extension
+- The scanner reads files synchronously from disk before parsing — ensure the file exists before calling `scanFile`
+- Best used as part of a pipeline: call `canHandle` first, then `scanFile` only on supported files
+
+### Example
+
+```typescript example.ts
+// ─── Inline types (mirrors the real Scanner/ScanResult interface) ───────────
+
+type Parameter = {
+  name: string
+  type: string
+  required: boolean
+  description?: string
+}
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'interface' | 'method' | 'variable'
+  parameters?: Parameter[]
+  returnType?: string
+  description?: string
+}
+
+type ScanResult = {
+  filePath: string
+  language: string
+  elements: APIElement[]
+}
+
+// ─── Simulated TypeScriptScanner (self-contained, no external imports) ───────
+
+class TypeScriptScanner {
+  languages = ['typescript', 'javascript']
+
+  canHandle(filePath: string): boolean {
+    return /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) && !filePath.includes('.d.ts')
+  }
+
+  async scanFile(filePath: string): Promise<ScanResult> {
+    const language =
+      filePath.endsWith('.ts') || filePath.endsWith('.tsx') ? 'typescript' : 'javascript'
+
+    // Simulated parse result — in production this uses the TypeScript compiler API
+    const simulatedElements: APIElement[] = [
+      {
+        name: 'createUser',
+        kind: 'function',
+        parameters: [
+          { name: 'username', type: 'string', required: true, description: 'Unique username' },
+          { name: 'email', type: 'string', required: true, description: 'User email address' },
+          { name: 'role', type: 'string', required: false, description: 'Optional user role' },
+        ],
+        returnType: 'Promise<User>',
+        description: 'Creates a new user account',
+      },
+      {
+        name: 'UserService',
+        kind: 'class',
+        description: 'Handles all user-related operations',
+      },
+    ]
+
+    return {
+      filePath,
+      language,
+      elements: simulatedElements,
+    }
+  }
+}
+
+// ─── Usage example ────────────────────────────────────────────────────────────
+
+const scanner = new TypeScriptScanner()
+
+const filesToCheck = [
+  'src/services/userService.ts',
+  'src/utils/helpers.js',
+  'src/types/models.d.ts',   // ← should be skipped
+  'src/config/settings.json', // ← should be skipped
+]
+
+async function main() {
+  try {
+    console.log('Supported languages:', scanner.languages)
+    // Output: Supported languages: [ 'typescript', 'javascript' ]
+
+    for (const file of filesToCheck) {
+      const supported = scanner.canHandle(file)
+      console.log(`\ncanHandle('${file}') → ${supported}`)
+
+      if (!supported) {
+        console.log('  ↳ Skipping unsupported or declaration file')
+        continue
+      }
+
+      const result = await scanner.scanFile(file)
+
+      console.log(`  ↳ Language : ${result.language}`)
+      console.log(`  ↳ Elements found: ${result.elements.length}`)
+
+      for (const el of result.elements) {
+        console.log(`     • [${el.kind}] ${el.name}`)
+        if (el.parameters && el.parameters.length > 0) {
+          for (const param of el.parameters) {
+            const req = param.required ? 'required' : 'optional'
+            console.log(`       - ${param.name}: ${param.type} (${req})`)
+          }
+        }
+      }
+    }
+
+    // Expected output for userService.ts:
+    // canHandle('src/services/userService.ts') → true
+    //   ↳ Language : typescript
+    //   ↳ Elements found: 2
+    //      • [function] createUser
+    //        - username: string (required)
+    //        - email: string (required)
+    //        - role: string (optional)
+    //      • [class] UserService
+
+  } catch (error) {
+    console.error('Scanner failed:', error instanceof Error ? error.message : error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="canHandle" icon="link" href="#canhandle">
+    Uses
+  </Card>
+  <Card title="scanFile" icon="link" href="#scanfile">
+    Uses
+  </Card>
+  <Card title="canHandle" icon="link" href="#canhandle">
+    Used by
+  </Card>
+</CardGroup>
+
+---
+
+
+## `canHandle`
+
+```typescript
+canHandle(filePath: string): boolean
+```
+
+Use this to quickly determine whether a file path is a TypeScript/JavaScript source file that the scanner can process — filtering out declaration files (`.d.ts`) automatically.
+
+Returns `true` for `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, and `.cjs` files. Returns `false` for `.d.ts` declaration files and any other file types.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | The file path (relative or absolute) to check for scanner compatibility |
+
+### Returns
+
+| Value | Condition |
+|-------|-----------|
+| `true` | File ends with `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, or `.cjs` — and is **not** a `.d.ts` declaration file |
+| `false` | File is a `.d.ts` declaration file, or has any other extension (`.py`, `.json`, `.md`, etc.) |
+
+### Notes
+- Declaration files (`.d.ts`) are explicitly excluded even though they end in `.ts`
+- Both relative paths (`./src/index.ts`) and absolute paths (`/home/user/project/app.js`) are supported
+- Only the file extension is evaluated — the file does not need to exist on disk
+
+### Example
+
+```typescript example.ts
+// Inline implementation matching TypeScriptScanner.canHandle behavior
+class TypeScriptScanner {
+  languages = ['typescript', 'javascript']
+
+  canHandle(filePath: string): boolean {
+    return /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) && !filePath.includes('.d.ts')
+  }
+}
+
+const scanner = new TypeScriptScanner()
+
+const testFiles = [
+  // Expected: true
+  { path: 'src/index.ts',              expected: true  },
+  { path: 'src/components/Button.tsx', expected: true  },
+  { path: 'dist/bundle.js',            expected: true  },
+  { path: 'src/App.jsx',               expected: true  },
+  { path: 'server/loader.mjs',         expected: true  },
+  { path: 'legacy/module.cjs',         expected: true  },
+
+  // Expected: false — declaration files are excluded
+  { path: 'dist/index.d.ts',           expected: false },
+  { path: 'types/global.d.ts',         expected: false },
+
+  // Expected: false — unsupported extensions
+  { path: 'README.md',                 expected: false },
+  { path: 'config/settings.json',      expected: false },
+  { path: 'scripts/build.py',          expected: false },
+]
+
+console.log('TypeScriptScanner.canHandle() results:\n')
+
+let allPassed = true
+
+for (const { path, expected } of testFiles) {
+  const result = scanner.canHandle(path)
+  const status = result === expected ? '✅ PASS' : '❌ FAIL'
+  if (result !== expected) allPassed = false
+
+  console.log(`${status}  canHandle("${path}") => ${result}`)
+}
+
+console.log(`\nAll tests passed: ${allPassed}`)
+
+// Expected output:
+// ✅ PASS  canHandle("src/index.ts") => true
+// ✅ PASS  canHandle("src/components/Button.tsx") => true
+// ✅ PASS  canHandle("dist/bundle.js") => true
+// ✅ PASS  canHandle("src/App.jsx") => true
+// ✅ PASS  canHandle("server/loader.mjs") => true
+// ✅ PASS  canHandle("legacy/module.cjs") => true
+// ✅ PASS  canHandle("dist/index.d.ts") => false
+// ✅ PASS  canHandle("types/global.d.ts") => false
+// ✅ PASS  canHandle("README.md") => false
+// ✅ PASS  canHandle("config/settings.json") => false
+// ✅ PASS  canHandle("scripts/build.py") => false
+//
+// All tests passed: true
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="GoScanner" icon="link" href="/docs/other#goscanner">
+    Uses
+  </Card>
+  <Card title="scanFile" icon="link" href="#scanfile">
+    Uses
+  </Card>
+  <Card title="scanFile" icon="link" href="#scanfile">
+    Uses
+  </Card>
+  <Card title="PythonScanner" icon="link" href="/docs/other#pythonscanner">
+    Uses
+  </Card>
+  <Card title="scanFile" icon="link" href="#scanfile">
+    Uses
+  </Card>
+  <Card title="RustScanner" icon="link" href="/docs/other#rustscanner">
+    Uses
+  </Card>
+</CardGroup>
+
+---
+
+
+## `scanFile`
+
+```typescript
+async scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to extract API elements (functions, classes, methods, parameters) from a TypeScript or JavaScript source file for documentation generation or code analysis.
+
+`scanFile` parses a `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, or `.cjs` file and returns a structured `ScanResult` containing all discovered API elements. It automatically detects whether to treat the file as TypeScript or JavaScript based on the file extension.
+
+> **Note:** Does not handle `.d.ts` declaration files — use `canHandle()` to pre-check a file path before scanning.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the source file to scan. Must be a `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, or `.cjs` file. |
+
+## Returns
+
+Returns `Promise<ScanResult>` — resolves with a structured object containing:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `filePath` | `string` | The path of the scanned file |
+| `language` | `'typescript' \| 'javascript'` | Detected language based on file extension |
+| `elements` | `APIElement[]` | All discovered functions, classes, methods, and their parameters |
+| `error?` | `string` | Present if the file could not be parsed; `elements` will be empty |
+
+**Throws:** Does not throw — errors are captured and returned in the `ScanResult.error` field.
+
+### Example
+
+```typescript example.ts
+import { readFileSync, writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+
+// --- Inline types (mirrors the real ScanResult shape) ---
+type Parameter = {
+  name: string
+  type: string
+  required: boolean
+  description?: string
+}
+
+type APIElement = {
+  name: string
+  kind: 'function' | 'class' | 'method' | 'interface'
+  parameters: Parameter[]
+  returnType?: string
+  description?: string
+  isExported: boolean
+}
+
+type ScanResult = {
+  filePath: string
+  language: 'typescript' | 'javascript'
+  elements: APIElement[]
+  error?: string
+}
+
+// --- Simulated TypeScriptScanner (self-contained, no external imports) ---
+class TypeScriptScanner {
+  canHandle(filePath: string): boolean {
+    return /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) && !filePath.includes('.d.ts')
+  }
+
+  async scanFile(filePath: string): Promise<ScanResult> {
+    const language =
+      filePath.endsWith('.ts') || filePath.endsWith('.tsx') ? 'typescript' : 'javascript'
+
+    try {
+      const source = readFileSync(filePath, 'utf-8')
+
+      // Simplified regex-based extraction for demonstration
+      const elements: APIElement[] = []
+
+      // Match exported functions: export function name(params): ReturnType
+      const fnRegex = /export\s+(async\s+)?function\s+(\w+)\s*\(([^)]*)\)\s*(?::\s*([\w<>\[\]|]+))?/g
+      let match: RegExpExecArray | null
+
+      while ((match = fnRegex.exec(source)) !== null) {
+        const [, , name, rawParams, returnType] = match
+
+        const parameters: Parameter[] = rawParams
+          .split(',')
+          .map((p) => p.trim())
+          .filter(Boolean)
+          .map((p) => {
+            const [paramName, paramType] = p.split(':').map((s) => s.trim())
+            const required = !paramName.includes('?')
+            return {
+              name: paramName.replace('?', ''),
+              type: paramType || 'unknown',
+              required,
+            }
+          })
+
+        elements.push({
+          name,
+          kind: 'function',
+          parameters,
+          returnType: returnType || 'void',
+          isExported: true,
+        })
+      }
+
+      return { filePath, language, elements }
+    } catch (err) {
+      return {
+        filePath,
+        language,
+        elements: [],
+        error: err instanceof Error ? err.message : 'Unknown error',
+      }
+    }
+  }
+}
+
+// --- Demo: create a temp file and scan it ---
+async function main() {
+  const scanner = new TypeScriptScanner()
+  const tempFile = join(process.cwd(), '_demo_scan_target.ts')
+
+  // Write a sample TypeScript file to scan
+  const sampleSource = `
+export async function fetchUser(userId: string, includeProfile?: boolean): Promise<User> {
+  return db.users.find(userId)
+}
+
+export function formatDate(date: Date, locale: string): string {
+  return date.toLocaleDateString(locale)
+}
+`
+  writeFileSync(tempFile, sampleSource, 'utf-8')
+
+  try {
+    // Guard: only scan supported file types
+    if (!scanner.canHandle(tempFile)) {
+      console.error('File type not supported:', tempFile)
+      return
+    }
+
+    const result = await scanner.scanFile(tempFile)
+
+    if (result.error) {
+      console.error('Scan failed:', result.error)
+      return
+    }
+
+    console.log('Language detected:', result.language)
+    // Output: Language detected: typescript
+
+    console.log('Elements found:', result.elements.length)
+    // Output: Elements found: 2
+
+    for (const el of result.elements) {
+      console.log(`\n[${el.kind}] ${el.name} → ${el.returnType}`)
+      for (const param of el.parameters) {
+        console.log(`  param: ${param.name} (${param.type}) required=${param.required}`)
+      }
+    }
+    // Output:
+    // [function] fetchUser → Promise<User>
+    //   param: userId (string) required=true
+    //   param: includeProfile (boolean) required=false
+    //
+    // [function] formatDate → string
+    //   param: date (Date) required=true
+    //   param: locale (string) required=true
+
+  } catch (error) {
+    console.error('Unexpected error during scan:', error)
+  } finally {
+    unlinkSync(tempFile) // clean up temp file
+  }
+}
+
+main()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="canHandle" icon="link" href="#canhandle">
+    Uses
+  </Card>
+  <Card title="canHandle" icon="link" href="#canhandle">
+    Uses
+  </Card>
+  <Card title="canHandle" icon="link" href="#canhandle">
+    Uses
+  </Card>
+  <Card title="canHandle" icon="link" href="#canhandle">
+    Uses
+  </Card>
+  <Card title="GoScanner" icon="link" href="/docs/other#goscanner">
+    Used by
+  </Card>
+  <Card title="canHandle" icon="link" href="#canhandle">
+    Used by
+  </Card>
+</CardGroup>
+
+---
+

package/dist/template/docs.json

@@ -1,6 +1,6 @@
 {
-  "name": "API Documentation",
-  "description": "Documentation generated with Skrypt",
+  "name": "Skrypt",
+  "description": "AI-powered documentation generation",
   "theme": {
     "primaryColor": "#3b82f6",
     "accentColor": "#8b5cf6",
@@ -8,26 +8,28 @@
   },
   "navigation": [
     {
-      "group": "Getting Started",
+      "group": "Overview",
+      "icon": "BookOpen",
       "pages": [
-        { "title": "Introduction", "path": "/docs" },
-        { "title": "Installation", "path": "/docs/installation" },
-        { "title": "Quick Start", "path": "/docs/quickstart" }
+        { "title": "Introduction", "path": "/docs" }
       ]
     },
     {
       "group": "API Reference",
+      "icon": "Code",
       "pages": [
-        { "title": "Overview", "path": "/docs/api" },
-        { "title": "Authentication", "path": "/docs/api/auth" },
-        { "title": "Endpoints", "path": "/docs/api/endpoints" }
+        { "title": "Core API", "path": "/docs/core" },
+        { "title": "Tools & Utilities", "path": "/docs/tools" },
+        { "title": "Types & Interfaces", "path": "/docs/types" },
+        { "title": "Integrations", "path": "/docs/integrations" },
+        { "title": "Other", "path": "/docs/other" }
       ]
     }
   ],
   "footer": {
     "links": [
-      { "title": "GitHub", "url": "https://github.com" },
-      { "title": "Discord", "url": "https://discord.com" }
+      { "title": "GitHub", "url": "https://github.com/debgotwired/skrypt" },
+      { "title": "npm", "url": "https://www.npmjs.com/package/skrypt-ai" }
     ]
   }
 }

package/dist/template/mdx-components.tsx

@@ -1,4 +1,5 @@
 import type { MDXComponents } from 'mdx/types'
+import { Children, isValidElement, type ReactNode } from 'react'
 import {
   Card,
   CardGroup,
@@ -26,8 +27,31 @@ import {
   H4,
   ParamTable,
   Schema,
+  Mermaid,
 } from '@/components/mdx'
 
+/** Wrapper for <pre> that routes mermaid code blocks to the Mermaid component */
+function PreWithMermaid(props: { children: ReactNode; className?: string }) {
+  let isMermaid = false
+  let codeText = ''
+
+  Children.forEach(props.children, (child) => {
+    if (isValidElement(child) && child.type === 'code') {
+      const childProps = child.props as { className?: string; children?: string }
+      if (childProps.className?.includes('language-mermaid')) {
+        isMermaid = true
+        codeText = childProps.children || ''
+      }
+    }
+  })
+
+  if (isMermaid) {
+    return <Mermaid chart={codeText} />
+  }
+
+  return <HighlightedCode {...props} />
+}
+
 export function useMDXComponents(components: MDXComponents): MDXComponents {
   return {
     // Custom components
@@ -51,8 +75,9 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
     Step,
     ParamTable,
     Schema,
-    // Override default elements - use syntax-highlighted code
-    pre: HighlightedCode,
+    Mermaid,
+    // Override default elements - use syntax-highlighted code (with mermaid routing)
+    pre: PreWithMermaid,
     h1: H1,
     h2: H2,
     h3: H3,

package/dist/template/package.json

@@ -10,6 +10,9 @@
     "start": "next start"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^1.0.0",
+    "@ai-sdk/openai": "^1.0.0",
+    "@ai-sdk/react": "^1.0.0",
     "@codesandbox/sandpack-react": "^2.20.0",
     "@mdx-js/loader": "^3.1.0",
     "@mdx-js/react": "^3.1.0",
@@ -19,13 +22,16 @@
     "clsx": "^2.1.0",
     "gray-matter": "^4.0.3",
     "lucide-react": "^0.500.0",
+    "mermaid": "^11.13.0",
     "next": "^15.3.0",
     "next-mdx-remote": "^6.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
+    "ai": "^4.0.0",
     "shiki": "^3.0.0",
+    "streamdown": "^1.0.0",
     "tailwind-merge": "^3.0.0",
     "yaml": "^2.8.2"
   },