skrypt-ai 0.3.4 → 0.4.1

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

@@ -0,0 +1,469 @@
+# Python.ts
+
+## Classes
+
+### `PythonScanner`
+
+```typescript
+class PythonScanner implements Scanner
+```
+
+Use this to scan Python source files and extract structured metadata (functions, classes, imports, etc.) by delegating parsing to a Python3 subprocess.
+
+`PythonScanner` implements the `Scanner` interface and is the go-to handler for any `.py` file in an autodocs pipeline. It spawns a `python3` process running an internal parser script and returns a `ScanResult` with the extracted symbols and structure.
+
+---
+
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `languages` | `string[]` | Always `['python']` — declares which languages this scanner handles |
+
+---
+
+### Methods
+
+#### `canHandle(filePath)`
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | `string` | ✅ | Path to the file to check |
+
+**Returns:** `boolean` — `true` if the file ends with `.py`, `false` otherwise. Use this as a fast pre-check before calling `scanFile`.
+
+---
+
+#### `scanFile(filePath)`
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | `string` | ✅ | Absolute or relative path to the `.py` file to parse |
+
+**Returns:** `Promise<ScanResult>` — resolves with the parsed structure of the file (symbols, classes, functions, imports, etc.). Resolves (never rejects) even on parse failure — check the result for error fields.
+
+> ⚠️ **Requires `python3`** to be available on the system `PATH`. The scanner spawns a subprocess for every file scanned — avoid calling it in tight loops without concurrency control.
+
+---
+
+**Example:**
+
+```typescript example.ts
+import { spawn } from 'child_process'
+import { writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// --- Inline types (mirrors autodocs Scanner interface) ---
+type ScanResult = {
+  filePath: string
+  language: string
+  symbols?: Array<{ name: string; kind: string; line: number }>
+  error?: string
+}
+
+interface Scanner {
+  languages: string[]
+  canHandle(filePath: string): boolean
+  scanFile(filePath: string): Promise<ScanResult>
+}
+
+// --- Self-contained PythonScanner implementation ---
+class PythonScanner implements Scanner {
+  languages = ['python']
+
+  canHandle(filePath: string): boolean {
+    return filePath.endsWith('.py')
+  }
+
+  async scanFile(filePath: string): Promise<ScanResult> {
+    // Inline parser script as a string — no external .py file needed
+    const parserScript = `
+import ast, json, sys
+
+def scan(path):
+    try:
+        with open(path, 'r') as f:
+            source = f.read()
+        tree = ast.parse(source)
+        symbols = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                symbols.append({'name': node.name, 'kind': 'function', 'line': node.lineno})
+            elif isinstance(node, ast.ClassDef):
+                symbols.append({'name': node.name, 'kind': 'class', 'line': node.lineno})
+        print(json.dumps({'filePath': path, 'language': 'python', 'symbols': symbols}))
+    except Exception as e:
+        print(json.dumps({'filePath': path, 'language': 'python', 'error': str(e)}))
+
+scan(sys.argv[1])
+`
+    // Write the inline parser to a temp file
+    const parserPath = join(tmpdir(), `_autodocs_parser_${process.pid}.py`)
+    writeFileSync(parserPath, parserScript)
+
+    return new Promise((resolve) => {
+      let stdout = ''
+      let stderr = ''
+
+      const proc = spawn('python3', [parserPath, filePath], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+
+      proc.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
+      proc.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+
+      proc.on('close', (code: number) => {
+        try { unlinkSync(parserPath) } catch { /* cleanup best-effort */ }
+
+        if (code !== 0 || !stdout.trim()) {
+          resolve({
+            filePath,
+            language: 'python',
+            error: stderr.trim() || `python3 exited with code ${code}`,
+          })
+          return
+        }
+
+        try {
+          resolve(JSON.parse(stdout.trim()) as ScanResult)
+        } catch {
+          resolve({ filePath, language: 'python', error: 'Failed to parse scanner output' })
+        }
+      })
+
+      proc.on('error', (err: Error) => {
+        resolve({ filePath, language: 'python', error: err.message })
+      })
+    })
+  }
+}
+
+// --- Demo ---
+async function main() {
+  const scanner = new PythonScanner()
+
+  // Write a sample Python file to scan
+  const samplePy = join(tmpdir(), 'sample_autodocs.py')
+  writeFileSync(samplePy, `
+class DataProcessor:
+    def __init__(self, config):
+        self.config = config
+
+    def process(self, data):
+        return [x * 2 for x in data]
+
+async def fetch_records(url: str) -> list:
+    pass
+
+def helper():
+    return True
+`)
+
+  console.log('canHandle(".py"):', scanner.canHandle(samplePy))   // true
+  console.log('canHandle(".js"):', scanner.canHandle('index.js')) // false
+
+  try {
+    const result = await scanner.scanFile(samplePy)
+    console.log('\nScan result:')
+    console.log(JSON.stringify(result, null, 2))
+    // Expected output:
+    // {
+    //   "filePath": "/tmp/sample_autodocs.py",
+    //   "language": "python",
+    //   "symbols": [
+    //     { "name": "DataProcessor", "kind": "class",    "line": 2 },
+    //     { "name": "__init__",      "kind": "function", "line": 3 },
+    //     { "name": "process",       "kind": "function", "line": 6 },
+    //     { "name": "fetch_records", "kind": "function", "line": 9 },
+    //     { "name": "helper",        "kind": "function", "line": 12 }
+    //   ]
+    // }
+  } catch (error) {
+    console.error('Scan failed unexpectedly:', error)
+  } finally {
+    try { unlinkSync(samplePy) } catch { /* cleanup */ }
+  }
+}
+
+main()
+```
+
+### Methods
+
+#### `canHandle`
+
+```typescript
+canHandle(filePath: string): boolean
+```
+
+Use this to quickly check whether a given file path should be processed by the Python scanner before committing to a full file scan.
+
+Call `canHandle` as a pre-flight check to filter out non-Python files in a pipeline, avoiding unnecessary scan overhead.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | The file path to evaluate. Can be a relative path, absolute path, or just a filename. |
+
+### Returns
+
+| Value | Condition |
+|-------|-----------|
+| `true` | The `filePath` ends with `.py` |
+| `false` | The `filePath` ends with any other extension (or no extension) |
+
+**Example:**
+
+```typescript example.ts
+// Inline implementation of PythonScanner.canHandle
+class PythonScanner {
+  languages = ['python']
+
+  canHandle(filePath: string): boolean {
+    return filePath.endsWith('.py')
+  }
+}
+
+// Simulate a list of files discovered in a project directory
+const discoveredFiles = [
+  '/project/src/main.py',
+  '/project/src/utils.py',
+  '/project/src/config.json',
+  '/project/src/README.md',
+  '/project/src/server.ts',
+  '/project/scripts/deploy.py',
+  '/project/scripts/build.sh',
+]
+
+const scanner = new PythonScanner()
+
+try {
+  // Filter only the files this scanner can handle
+  const pythonFiles = discoveredFiles.filter((file) => scanner.canHandle(file))
+
+  console.log('All discovered files:', discoveredFiles.length)
+  console.log('Python files to scan:', pythonFiles)
+  // Output:
+  // All discovered files: 7
+  // Python files to scan: [
+  //   '/project/src/main.py',
+  //   '/project/src/utils.py',
+  //   '/project/scripts/deploy.py'
+  // ]
+
+  // Spot-check individual cases
+  console.log('\nSpot checks:')
+  console.log(scanner.canHandle('analysis.py'))     // true
+  console.log(scanner.canHandle('analysis.py.bak')) // false — .bak wins
+  console.log(scanner.canHandle('script.ts'))        // false
+  console.log(scanner.canHandle(''))                 // false
+} catch (error) {
+  console.error('Unexpected error during file filtering:', error)
+}
+```
+
+#### `scanFile`
+
+```typescript
+async scanFile(filePath: string): Promise<ScanResult>
+```
+
+Use this to scan a Python source file and extract structured metadata — functions, classes, imports, and other code elements — by running a Python parser subprocess and returning the results asynchronously.
+
+This is the core method of `PythonScanner`. It delegates parsing to a `python3` child process, making it suitable for deep, AST-level analysis of `.py` files without reimplementing Python parsing in TypeScript.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✅ | Absolute or relative path to the `.py` file to scan |
+
+## Returns
+
+Returns a `Promise<ScanResult>` that resolves when the Python subprocess completes.
+
+| Scenario | Result |
+|----------|--------|
+| File parsed successfully | Resolves with a `ScanResult` containing extracted code metadata |
+| File not found / parse error | Resolves (or rejects) with an error-state `ScanResult` or throws |
+| Non-`.py` file passed | Undefined behavior — use `canHandle(filePath)` to guard first |
+
+### `ScanResult` Shape (typical)
+```ts
+{
+  filePath: string        // path that was scanned
+  language: string        // e.g. "python"
+  functions: string[]     // extracted function names
+  classes: string[]       // extracted class names
+  imports: string[]       // top-level imports
+  errors: string[]        // any parse errors encountered
+}
+```
+
+## Notes
+- Internally spawns `python3` as a subprocess — ensure Python 3 is available in the runtime environment.
+- Always call `canHandle(filePath)` before `scanFile()` to confirm the file is a `.py` file.
+- The method is async; always `await` it or chain `.then()`.
+
+**Example:**
+
+```typescript example.ts
+import { spawn } from 'child_process'
+import { writeFileSync, unlinkSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// --- Inline types (mirrors the real ScanResult shape) ---
+interface ScanResult {
+  filePath: string
+  language: string
+  functions: string[]
+  classes: string[]
+  imports: string[]
+  errors: string[]
+}
+
+// --- Inline PythonScanner (self-contained, no external imports) ---
+class PythonScanner {
+  canHandle(filePath: string): boolean {
+    return filePath.endsWith('.py')
+  }
+
+  async scanFile(filePath: string): Promise<ScanResult> {
+    // Inline parser script: prints JSON to stdout
+    const inlineParserScript = `
+import ast, json, sys
+
+def scan(path):
+    try:
+        with open(path, 'r') as f:
+            source = f.read()
+        tree = ast.parse(source)
+        functions = [n.name for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]
+        classes   = [n.name for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]
+        imports   = []
+        for n in ast.walk(tree):
+            if isinstance(n, ast.Import):
+                imports += [a.name for a in n.names]
+            elif isinstance(n, ast.ImportFrom):
+                imports.append(n.module or '')
+        print(json.dumps({
+            "filePath": path,
+            "language": "python",
+            "functions": functions,
+            "classes": classes,
+            "imports": imports,
+            "errors": []
+        }))
+    except Exception as e:
+        print(json.dumps({
+            "filePath": path,
+            "language": "python",
+            "functions": [],
+            "classes": [],
+            "imports": [],
+            "errors": [str(e)]
+        }))
+
+scan(sys.argv[1])
+`
+    // Write the inline parser to a temp file
+    const parserPath = join(tmpdir(), `_scanner_parser_${Date.now()}.py`)
+    writeFileSync(parserPath, inlineParserScript)
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn('python3', [parserPath, filePath], {
+        stdio: ['ignore', 'pipe', 'pipe']
+      })
+
+      let stdout = ''
+      let stderr = ''
+
+      proc.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
+      proc.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+
+      proc.on('close', (code: number) => {
+        try { unlinkSync(parserPath) } catch { /* cleanup best-effort */ }
+
+        if (code !== 0) {
+          return reject(new Error(`python3 exited with code ${code}: ${stderr}`))
+        }
+        try {
+          const result: ScanResult = JSON.parse(stdout.trim())
+          resolve(result)
+        } catch {
+          reject(new Error(`Failed to parse scanner output: ${stdout}`))
+        }
+      })
+
+      proc.on('error', (err: Error) => {
+        try { unlinkSync(parserPath) } catch { /* cleanup best-effort */ }
+        reject(new Error(`Failed to spawn python3: ${err.message}`))
+      })
+    })
+  }
+}
+
+// --- Sample .py file to scan ---
+const samplePyPath = join(tmpdir(), `sample_${Date.now()}.py`)
+writeFileSync(samplePyPath, `
+import os
+import json
+from pathlib import Path
+
+class DataProcessor:
+    def __init__(self, config: dict):
+        self.config = config
+
+    def process(self, data: list) -> list:
+        return [item.strip() for item in data]
+
+def load_config(path: str) -> dict:
+    with open(path) as f:
+        return json.load(f)
+
+def main():
+    config = load_config("config.json")
+    processor = DataProcessor(config)
+    print(processor.process(["hello ", " world"]))
+`)
+
+// --- Run the scanner ---
+async function main() {
+  const scanner = new PythonScanner()
+
+  // Guard: only scan .py files
+  if (!scanner.canHandle(samplePyPath)) {
+    console.error('File is not a Python file — skipping.')
+    process.exit(1)
+  }
+
+  try {
+    console.log(`Scanning: ${samplePyPath}\n`)
+    const result = await scanner.scanFile(samplePyPath)
+
+    console.log('Scan complete!')
+    console.log('Language :', result.language)
+    console.log('Classes  :', result.classes)
+    console.log('Functions:', result.functions)
+    console.log('Imports  :', result.imports)
+    console.log('Errors   :', result.errors)
+
+    // Expected output:
+    // Language : python
+    // Classes  : [ 'DataProcessor' ]
+    // Functions: [ '__init__', 'process', 'load_config', 'main' ]
+    // Imports  : [ 'os', 'json', 'pathlib' ]
+    // Errors   : []
+  } catch (error) {
+    console.error('Scan failed:', error instanceof Error ? error.message : error)
+  } finally {
+    try { unlinkSync(samplePyPath) } catch { /* cleanup */ }
+  }
+}
+
+main()
+```
+