skrypt-ai 0.3.4 → 0.4.1

package/dist/template/src/app/docs/scanner/index.md

@@ -0,0 +1,212 @@
+# Index.ts
+
+## Functions
+
+### `scanDirectory`
+
+```typescript
+async function scanDirectory(dir: string, options: ScanOptions = {}): Promise<ScanAllResult>
+```
+
+Use this to recursively scan a directory (or single file) and extract all API elements — functions, classes, types, and exports — across multiple languages including Python, TypeScript, JavaScript, Go, and Rust.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✅ Yes | Path to the directory or single file to scan |
+| `options` | `ScanOptions` | ❌ No | Configuration options to control which files are included or excluded |
+| `options.include` | `string[]` | ❌ No | Glob patterns for files to scan. Defaults to `['**/*.py', '**/*.ts', '**/*.js', '**/*.go', '**/*.rs']` |
+| `options.exclude` | `string[]` | ❌ No | Glob patterns for files to skip. Defaults to `['**/node_modules/**', '**/__pycache__/**', '**/dist/**']` |
+
+## Returns
+
+Returns a `Promise<ScanAllResult>` that resolves to an object containing all discovered API elements grouped by file. Rejects if the provided path does not exist or cannot be read.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `files` | `ScanResult[]` | Array of per-file scan results, each containing extracted API elements |
+| `totalFiles` | `number` | Total number of files successfully scanned |
+| `errors` | `string[]` | Any non-fatal errors encountered during scanning |
+
+## Notes
+
+- Passing a **single file path** instead of a directory is supported — the scanner will detect the file extension and apply the appropriate language parser.
+- Files matching `exclude` patterns are silently skipped and do not appear in `errors`.
+- Use `options.include` to narrow scans to a specific language (e.g., `['**/*.ts']`) for faster results in large monorepos.
+
+### `scanFile`
+
+```typescript
+async function scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to analyze a single source file and extract structured metadata — functions, classes, types, and other code constructs — without scanning an entire directory.
+
+`scanFile` automatically detects the file's language, selects the appropriate scanner, and returns a normalized `ScanResult` regardless of whether the file is Python, TypeScript, or another supported language.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the source file to scan |
+
+## Returns
+
+Returns `Promise<ScanResult>` — resolves with a structured result containing:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `filePath` | `string` | The original file path passed in |
+| `language` | `string` | Detected language (`"typescript"`, `"python"`, etc.) |
+| `functions` | `FunctionInfo[]` | All top-level and exported functions found |
+| `classes` | `ClassInfo[]` | All class definitions found |
+| `exports` | `string[]` | Named exports from the file |
+| `errors` | `string[]` | Any parse errors encountered (non-fatal) |
+
+> **Note:** If no scanner is found for the file extension, `scanFile` returns a default result with an empty `functions` and `classes` array rather than throwing. Always check `errors` for partial failures.
+
+**Example:**
+
+```typescript example.ts
+// Inline types to simulate the autodocs ScanResult shape
+type FunctionInfo = {
+  name: string
+  signature: string
+  docstring?: string
+  lineStart: number
+  lineEnd: number
+}
+
+type ClassInfo = {
+  name: string
+  methods: FunctionInfo[]
+  lineStart: number
+  lineEnd: number
+}
+
+type ScanResult = {
+  filePath: string
+  language: string
+  functions: FunctionInfo[]
+  classes: ClassInfo[]
+  exports: string[]
+  errors: string[]
+}
+
+// Simulated scanner implementations (mirrors autodocs internal behavior)
+const LANGUAGE_MAP: Record<string, string> = {
+  '.ts': 'typescript',
+  '.tsx': 'typescript',
+  '.js': 'javascript',
+  '.py': 'python',
+}
+
+function detectLanguage(filePath: string): string {
+  const ext = filePath.slice(filePath.lastIndexOf('.'))
+  return LANGUAGE_MAP[ext] ?? 'unknown'
+}
+
+// Simulated scanFile — mirrors the real function's behavior
+async function scanFile(filePath: string): Promise<ScanResult> {
+  const language = detectLanguage(filePath)
+
+  if (language === 'unknown') {
+    // Unsupported file type: return a safe default (no throw)
+    return {
+      filePath,
+      language: 'unknown',
+      functions: [],
+      classes: [],
+      exports: [],
+      errors: [`No scanner available for file: ${filePath}`],
+    }
+  }
+
+  // Simulate parsed output for a TypeScript file
+  if (language === 'typescript') {
+    return {
+      filePath,
+      language: 'typescript',
+      functions: [
+        {
+          name: 'getUserById',
+          signature: 'async function getUserById(id: string): Promise<User>',
+          docstring: 'Fetch a user record by their unique ID.',
+          lineStart: 12,
+          lineEnd: 24,
+        },
+        {
+          name: 'formatUserName',
+          signature: 'function formatUserName(user: User): string',
+          lineStart: 26,
+          lineEnd: 31,
+        },
+      ],
+      classes: [
+        {
+          name: 'UserService',
+          methods: [
+            {
+              name: 'create',
+              signature: 'async create(data: CreateUserDto): Promise<User>',
+              lineStart: 45,
+              lineEnd: 58,
+            },
+          ],
+          lineStart: 40,
+          lineEnd: 80,
+        },
+      ],
+      exports: ['getUserById', 'formatUserName', 'UserService'],
+      errors: [],
+    }
+  }
+
+  // Fallback for other supported languages
+  return {
+    filePath,
+    language,
+    functions: [],
+    classes: [],
+    exports: [],
+    errors: [],
+  }
+}
+
+// --- Usage ---
+async function main() {
+  const targetFile = process.env.SCAN_TARGET || './src/users/userService.ts'
+
+  try {
+    console.log(`Scanning: ${targetFile}\n`)
+    const result = await scanFile(targetFile)
+
+    console.log(`Language:  ${result.language}`)
+    console.log(`Functions: ${result.functions.length}`)
+    console.log(`Classes:   ${result.classes.length}`)
+    console.log(`Exports:   ${result.exports.join(', ')}`)
+
+    if (result.errors.length > 0) {
+      console.warn('Scan warnings:', result.errors)
+    }
+
+    console.log('\nFull result:')
+    console.log(JSON.stringify(result, null, 2))
+
+    // Expected output:
+    // Language:  typescript
+    // Functions: 2
+    // Classes:   1
+    // Exports:   getUserById, formatUserName, UserService
+  } catch (error) {
+    // scanFile itself won't throw for unsupported files,
+    // but may throw on filesystem errors (file not found, permission denied)
+    console.error('Scan failed unexpectedly:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+

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

@@ -0,0 +1,307 @@
+## Classes
+
+### `GoScanner`
+
+```typescript
+class GoScanner implements Scanner
+```
+
+Use this to scan Go source files and extract API elements — functions, methods, structs, and interfaces — for automated documentation generation pipelines.
+
+`GoScanner` implements the `Scanner` interface and targets `.go` files, automatically skipping test files (`_test.go`).
+
+## Methods
+
+### `canHandle(filePath: string): boolean`
+Returns `true` if the file path ends in `.go` and is not a test file. Use this to check compatibility before scanning.
+
+### `scanFile(filePath: string): Promise<ScanResult>`
+Reads and parses a Go source file, returning all discovered API elements.
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the `.go` source file to scan |
+
+#### Returns
+
+`scanFile` returns a `Promise<ScanResult>` containing:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `elements` | `APIElement[]` | All extracted functions, methods, types, and interfaces |
+| `filePath` | `string` | The path of the scanned file |
+| `language` | `string` | Always `"go"` for this scanner |
+
+Each `APIElement` includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Identifier name (e.g. `"NewServer"`) |
+| `kind` | `string` | One of `"function"`, `"method"`, `"type"`, `"interface"` |
+| `signature` | `string` | Full Go signature string |
+| `parameters` | `Parameter[]` | Parsed parameter list |
+| `docstring` | `string \| undefined` | Leading comment block, if present |
+
+## Notes
+- Test files (`*_test.go`) are **automatically excluded** — `canHandle` returns `false` for them
+- `languages` property is `['go']`, used by scanner registries to route files to the correct handler
+- Throws if the file cannot be read (e.g. missing file, permission error)
+
+### Methods
+
+#### `canHandle`
+
+```typescript
+canHandle(filePath: string): boolean
+```
+
+Use this to check whether a Go source file should be processed by the `GoScanner` — it returns `true` for `.go` files that are **not** test files (`_test.go`).
+
+This is useful when routing files through a scanner pipeline, letting you skip unsupported or test files before attempting a full scan.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the file being evaluated |
+
+#### Returns
+
+| Value | Condition |
+|-------|-----------|
+| `true` | File ends in `.go` **and** does not contain `_test.go` |
+| `false` | File is not a `.go` file, or is a Go test file (`_test.go`) |
+
+### Notes
+- Test files (e.g., `auth_test.go`, `parser_test.go`) are explicitly excluded and return `false`
+- Only the file path string is checked — no filesystem access occurs
+
+**Example:**
+
+```typescript example.ts
+// Inline implementation of GoScanner.canHandle for a self-contained example
+class GoScanner {
+  languages = ['go']
+
+  canHandle(filePath: string): boolean {
+    return /\.go$/.test(filePath) && !filePath.includes('_test.go')
+  }
+}
+
+const scanner = new GoScanner()
+
+const testCases: Array<{ path: string; expected: boolean; label: string }> = [
+  { path: 'internal/auth/handler.go',      expected: true,  label: 'standard Go source file' },
+  { path: 'internal/auth/handler_test.go', expected: false, label: 'Go test file (excluded)' },
+  { path: 'cmd/main.go',                   expected: true,  label: 'main package file' },
+  { path: 'src/utils/parser.ts',           expected: false, label: 'TypeScript file (wrong ext)' },
+  { path: 'README.md',                     expected: false, label: 'markdown file' },
+  { path: 'pkg/models/user_test.go',       expected: false, label: 'nested test file (excluded)' },
+]
+
+try {
+  console.log('GoScanner.canHandle() results:\n')
+
+  for (const { path, expected, label } of testCases) {
+    const result = scanner.canHandle(path)
+    const status = result === expected ? '✅' : '❌'
+    console.log(`${status} ${label}`)
+    console.log(`   Path:     ${path}`)
+    console.log(`   Returns:  ${result}\n`)
+  }
+
+  // Typical use in a file-routing pipeline
+  const filesToProcess = [
+    'pkg/api/routes.go',
+    'pkg/api/routes_test.go',
+    'pkg/api/middleware.go',
+    'docs/overview.md',
+  ]
+
+  const scannable = filesToProcess.filter(f => scanner.canHandle(f))
+  console.log('Files queued for scanning:', scannable)
+  // Output: [ 'pkg/api/routes.go', 'pkg/api/middleware.go' ]
+
+} catch (error) {
+  console.error('Unexpected error during canHandle check:', error)
+}
+```
+
+#### `scanFile`
+
+```typescript
+async scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to extract API elements from a Go source file, returning all discovered functions, types, and parameters in a structured result.
+
+`scanFile` reads and parses a `.go` file (excluding test files), identifying exported API elements and collecting any parse errors encountered during scanning.
+
+> **Note:** Only handles non-test Go files (`.go` extension, not `_test.go`). Use `canHandle(filePath)` to verify compatibility before calling.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the `.go` source file to scan |
+
+#### Returns
+
+Returns a `Promise<ScanResult>` that resolves to:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `elements` | `APIElement[]` | All discovered API elements (functions, types, etc.) |
+| `errors` | `string[]` | Non-fatal parse errors encountered during scanning |
+| `filePath` | `string` | The original file path that was scanned |
+
+**Throws** if the file cannot be read (e.g., file not found, permission denied).
+
+**Example:**
+
+```typescript example.ts
+import { readFileSync, writeFileSync, unlinkSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// --- Inline types (mirrors the real library's types) ---
+interface Parameter {
+  name: string
+  type: string
+}
+
+interface APIElement {
+  name: string
+  kind: 'function' | 'type' | 'method'
+  parameters: Parameter[]
+  returnType?: string
+  doc?: string
+}
+
+interface ScanResult {
+  filePath: string
+  elements: APIElement[]
+  errors: string[]
+}
+
+// --- Self-contained GoScanner implementation ---
+class GoScanner {
+  canHandle(filePath: string): boolean {
+    return /\.go$/.test(filePath) && !filePath.includes('_test.go')
+  }
+
+  async scanFile(filePath: string): Promise<ScanResult> {
+    const source = readFileSync(filePath, 'utf-8')
+    const elements: APIElement[] = []
+    const errors: string[] = []
+    const lines = source.split('\n')
+
+    // Match exported Go functions: func FuncName(params) returnType
+    const funcRegex = /^func\s+([A-Z][a-zA-Z0-9]*)\s*\(([^)]*)\)\s*([^\s{]*)/
+    // Match exported types: type TypeName struct/interface
+    const typeRegex = /^type\s+([A-Z][a-zA-Z0-9]*)\s+(struct|interface)/
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim()
+
+      const funcMatch = funcRegex.exec(line)
+      if (funcMatch) {
+        const [, name, rawParams, returnType] = funcMatch
+        const parameters: Parameter[] = rawParams
+          .split(',')
+          .map(p => p.trim())
+          .filter(Boolean)
+          .map(p => {
+            const parts = p.split(/\s+/)
+            return parts.length >= 2
+              ? { name: parts[0], type: parts[1] }
+              : { name: p, type: 'unknown' }
+          })
+
+        elements.push({ name, kind: 'function', parameters, returnType: returnType || 'void' })
+        continue
+      }
+
+      const typeMatch = typeRegex.exec(line)
+      if (typeMatch) {
+        const [, name] = typeMatch
+        elements.push({ name, kind: 'type', parameters: [] })
+      }
+    }
+
+    return { filePath, elements, errors }
+  }
+}
+
+// --- Example usage ---
+const sampleGoSource = `
+package api
+
+// UserService handles user operations.
+type UserService struct{}
+
+// GetUser retrieves a user by ID.
+func GetUser(id string, includeDeleted bool) error {
+  return nil
+}
+
+// CreateUser adds a new user to the system.
+func CreateUser(name string, age int) string {
+  return ""
+}
+`
+
+async function main() {
+  // Write a temporary .go file to scan
+  const tmpFile = join(tmpdir(), 'example_service.go')
+
+  try {
+    writeFileSync(tmpFile, sampleGoSource, 'utf-8')
+
+    const scanner = new GoScanner()
+
+    // Verify the file is compatible before scanning
+    if (!scanner.canHandle(tmpFile)) {
+      throw new Error(`File is not a scannable Go source: ${tmpFile}`)
+    }
+
+    const result = await scanner.scanFile(tmpFile)
+
+    console.log('Scanned file:', result.filePath)
+    console.log(`Found ${result.elements.length} API elements:\n`)
+
+    for (const el of result.elements) {
+      if (el.kind === 'function') {
+        const params = el.parameters.map(p => `${p.name} ${p.type}`).join(', ')
+        console.log(`  [${el.kind}] ${el.name}(${params}) → ${el.returnType}`)
+      } else {
+        console.log(`  [${el.kind}] ${el.name}`)
+      }
+    }
+
+    if (result.errors.length > 0) {
+      console.warn('\nParse errors:', result.errors)
+    }
+
+    // Expected output:
+    // Scanned file: /tmp/example_service.go
+    // Found 3 API elements:
+    //   [type]     UserService
+    //   [function] GetUser(id string, includeDeleted bool) → error
+    //   [function] CreateUser(name string, age int) → string
+
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      console.error('File not found - check the path and try again')
+    } else {
+      console.error('Scan failed:', error)
+    }
+  } finally {
+    // Clean up temp file
+    try { unlinkSync(tmpFile) } catch {}
+  }
+}
+
+main()
+```
+