apiforge-analyzer 1.3.6 → 1.3.8

package/dist/esm/frameworks/python.js

@@ -0,0 +1,171 @@
+/**
+ * FastAPI / Flask / Django (+ DRF) analyzer
+ *
+ * Python apps can't be handed to analyze() as a JS object, so this runs the
+ * user's own interpreter (their venv, so their dependencies resolve), imports
+ * the app, and reads the framework's live route table — see
+ * python-introspect.ts. Nothing is injected into the user's code and no server
+ * is started. Returns the same Route[] as every other analyzer; enrichment and
+ * upload happen in index.ts / uploader.ts exactly as for Express or Fastify.
+ *
+ * The `npx apiforge` CLI instead works like its Node flow: it injects a snippet
+ * into the file returned in PythonAppCandidate.file and runs the user's own
+ * start command (see pythonFlow in cli.ts).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { PYTHON_INTROSPECT_SCRIPT, ROUTES_MARKER } from './python-introspect.js';
+const SKIP_DIRS = new Set([
+    '.git', '.venv', 'venv', 'env', '.env', 'node_modules', '__pycache__', 'site-packages',
+    '.tox', '.mypy_cache', '.pytest_cache', 'dist', 'build', 'migrations',
+]);
+/**
+ * Analyze a Python web app's routes
+ */
+export async function analyzePython(options) {
+    let appDir = options.appDir || process.cwd();
+    let { app, factory, djangoSettings } = options;
+    // Fill in whatever the caller left out from the project layout.
+    if (options.framework === 'django' ? !app && !djangoSettings && !process.env.DJANGO_SETTINGS_MODULE : !app) {
+        const [candidate] = findPythonApps(options.framework, appDir);
+        if (!candidate) {
+            throw new Error(options.framework === 'django'
+                ? 'Django settings not found — pass djangoSettings (e.g. "mysite.settings")'
+                : `${options.framework} app not found — pass pythonApp (e.g. "main:app")`);
+        }
+        ;
+        ({ app, factory, djangoSettings, appDir } = candidate);
+    }
+    const pythonPath = options.pythonPath || findPythonInterpreter(appDir);
+    const stdout = await runPython(pythonPath, appDir, {
+        framework: options.framework, app, factory, djangoSettings, appDir,
+    }, options.timeoutMs ?? 60000);
+    const line = stdout.split(/\r?\n/).find(l => l.startsWith(ROUTES_MARKER));
+    if (!line)
+        throw new Error('Python analyzer produced no output');
+    return JSON.parse(line.slice(ROUTES_MARKER.length));
+}
+function runPython(pythonPath, cwd, opts, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(pythonPath, ['-'], {
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                APIFORGE_PY_OPTIONS: JSON.stringify(opts),
+                PYTHONIOENCODING: 'utf-8',
+                // Don't leave __pycache__ folders behind in the user's project.
+                PYTHONDONTWRITEBYTECODE: '1',
+            },
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString('utf-8'); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf-8'); });
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Python analyzer timed out after ${Math.round(timeoutMs / 1000)}s`));
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(new Error(err.code === 'ENOENT'
+                ? `Python interpreter not found: "${pythonPath}" — activate your virtualenv or set APIFORGE_PYTHON`
+                : err.message));
+        });
+        child.on('close', code => {
+            clearTimeout(timer);
+            if (code === 0)
+                return resolve(stdout);
+            // The last traceback line is the actual error (ModuleNotFoundError: ..., etc.)
+            const lastLine = stderr.trim().split(/\r?\n/).pop() || `exited with code ${code}`;
+            reject(new Error(`Python analyzer failed: ${lastLine}`));
+        });
+        child.stdin.end(PYTHON_INTROSPECT_SCRIPT);
+    });
+}
+/**
+ * The interpreter that has the project's dependencies installed:
+ * APIFORGE_PYTHON → active virtualenv → a venv inside the project → system python.
+ */
+export function findPythonInterpreter(projectDir = process.cwd()) {
+    if (process.env.APIFORGE_PYTHON)
+        return process.env.APIFORGE_PYTHON;
+    const inVenv = (venvDir) => process.platform === 'win32'
+        ? path.join(venvDir, 'Scripts', 'python.exe')
+        : path.join(venvDir, 'bin', 'python');
+    const candidates = [
+        process.env.VIRTUAL_ENV,
+        ...['.venv', 'venv', 'env'].map(dir => path.join(projectDir, dir)),
+    ].filter(Boolean).map(dir => inVenv(dir));
+    return candidates.find(p => fs.existsSync(p)) || (process.platform === 'win32' ? 'python' : 'python3');
+}
+/**
+ * Find where the app object (FastAPI/Flask) or settings module (Django) lives.
+ */
+export function findPythonApps(framework, projectDir = process.cwd()) {
+    const files = listPythonFiles(projectDir, 3);
+    if (framework === 'django') {
+        const candidates = [];
+        for (const file of files.filter(f => path.basename(f) === 'manage.py')) {
+            const content = fs.readFileSync(file, 'utf-8');
+            const match = content.match(/DJANGO_SETTINGS_MODULE['"]\s*,\s*['"]([\w.]+)['"]/);
+            if (match) {
+                const appDir = path.dirname(file);
+                // The CLI injects into manage.py itself: every runserver goes through it, whereas
+                // wsgi.py is only loaded when settings.WSGI_APPLICATION points at it.
+                candidates.push({ label: `${match[1]}  (${path.relative(projectDir, file) || 'manage.py'})`, djangoSettings: match[1], appDir, file });
+            }
+        }
+        return candidates;
+    }
+    const ctor = framework === 'fastapi' ? 'FastAPI' : 'Flask';
+    const instanceRe = new RegExp(`^(\\w+)\\s*(?::\\s*\\w+\\s*)?=\\s*(?:\\w+\\.)?${ctor}\\(`, 'gm');
+    const candidates = [];
+    for (const file of files) {
+        const content = fs.readFileSync(file, 'utf-8');
+        if (!content.includes(ctor))
+            continue;
+        // src/ layout: import from inside src/ so the app's own absolute imports resolve
+        const rel = path.relative(projectDir, file).split(path.sep);
+        const appDir = rel[0] === 'src' ? path.join(projectDir, 'src') : projectDir;
+        if (rel[0] === 'src')
+            rel.shift();
+        const module = rel.join('.').replace(/\.py$/, '').replace(/\.__init__$/, '');
+        for (const match of content.matchAll(instanceRe)) {
+            candidates.push({ label: `${module}:${match[1]}`, app: `${module}:${match[1]}`, appDir, file });
+        }
+        if (framework === 'flask' && !content.match(instanceRe)) {
+            const factory = content.match(/^def\s+(create_app|make_app)\s*\(/m);
+            if (factory)
+                candidates.push({ label: `${module}:${factory[1]}()`, app: `${module}:${factory[1]}`, factory: true, appDir, file });
+        }
+    }
+    // Top-level entry files first: main.py / app.py beat a FastAPI() in some sub-module
+    return candidates.sort((a, b) => depth(a.app) - depth(b.app));
+}
+function depth(app) {
+    return (app || '').split(':')[0].split('.').length;
+}
+function listPythonFiles(dir, maxDepth, level = 0) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (level < maxDepth && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                files.push(...listPythonFiles(full, maxDepth, level + 1));
+            }
+        }
+        else if (entry.isFile() && entry.name.endsWith('.py')) {
+            files.push(full);
+        }
+    }
+    return files;
+}

package/dist/esm/index.js

@@ -10,6 +10,7 @@ import { analyzeVite } from './frameworks/vite.js';
 import { analyzeReactRouter } from './frameworks/react-router.js';
 import { analyzeNestJS } from './frameworks/nestjs.js';
 import { analyzeFastify } from './frameworks/fastify.js';
+import { analyzePython } from './frameworks/python.js';
 import { detectFramework, SUPPORTED_FRAMEWORKS } from './detect.js';
 import { exportToJSON } from './export.js';
 import { uploadRoutes, writeStatusFile } from './uploader.js';
@@ -167,6 +168,18 @@ export async function analyze(app, options) {
             case 'react-router':
                 routes = await analyzeReactRouter(options.nextDir || 'src/routes.tsx');
                 break;
+            case 'fastapi':
+            case 'flask':
+            case 'django':
+                routes = await analyzePython({
+                    framework: framework,
+                    app: options.pythonApp,
+                    factory: options.pythonFactory,
+                    pythonPath: options.pythonPath,
+                    djangoSettings: options.djangoSettings,
+                    appDir: options.nextDir,
+                });
+                break;
             // No default: unsupported frameworks are rejected above, before this
             // try block, so a thrown error here isn't silently swallowed into `[]`.
         }
@@ -212,7 +225,7 @@ export async function analyze(app, options) {
     return routes;
 }
 // Re-exports for library consumers
-export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter, analyzeNestJS, analyzeFastify };
+export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter, analyzeNestJS, analyzeFastify, analyzePython };
 export { exportToJSON } from './export.js';
 export { uploadRoutes } from './uploader.js';
 export { detectFramework } from './detect.js';
@@ -226,6 +239,7 @@ export default {
     analyzeVite,
     analyzeReactRouter,
     analyzeNestJS,
+    analyzePython,
     exportToJSON,
     uploadRoutes,
     detectFramework,

package/dist/types/detect.d.ts

@@ -1,4 +1,4 @@
-export type Framework = 'express' | 'fastify' | 'koa' | 'hapi' | 'nestjs' | 'nextjs-pages' | 'nextjs-app' | 'vite' | 'react-router' | 'unknown';
+export type Framework = 'express' | 'fastify' | 'koa' | 'hapi' | 'nestjs' | 'nextjs-pages' | 'nextjs-app' | 'vite' | 'react-router' | 'fastapi' | 'flask' | 'django' | 'unknown';
 export interface FrameworkInfo {
     name: Framework;
     version?: string;
@@ -13,3 +13,14 @@ export interface FrameworkInfo {
  */
 export declare const SUPPORTED_FRAMEWORKS: ReadonlySet<Framework>;
 export declare function detectFramework(app?: any): FrameworkInfo;
+/**
+ * Detect a Python web framework from manage.py / dependency files.
+ * Python apps are never passed to analyze() as an object, so this is file-based only.
+ */
+export declare function detectPythonFramework(dir?: string): 'fastapi' | 'flask' | 'django' | null;
+/**
+ * Read a text file honouring a UTF-16 BOM. Windows PowerShell 5.1's
+ * `pip freeze > requirements.txt` writes UTF-16 LE, which read as UTF-8
+ * interleaves NUL bytes and hides every package name.
+ */
+export declare function readTextFile(path: string): string;

package/dist/types/frameworks/python-introspect.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Python side of the FastAPI / Flask / Django analyzers (see python.ts).
+ *
+ * Reads the framework's live route table — the Python equivalent of walking
+ * app._router.stack in express.ts. Runs in one of two modes:
+ *  - analyze(): piped to the user's interpreter on stdin; imports the app and
+ *    prints raw Route objects as one JSON line prefixed with ROUTES_MARKER.
+ *  - CLI: exec'd by the snippet the CLI injects into the user's entry file
+ *    (APIFORGE_APP set), inside their own running server; writes the routes
+ *    to APIFORGE_STATUS_FILE, like the Node snippet's collection mode.
+ * Enrichment and upload stay in TS either way.
+ *
+ * Kept as an embedded string (not a .py file) so the existing tsc-only build
+ * ships it without any copy step. String.raw keeps regex backslashes intact —
+ * the Python below must not contain backticks or a dollar-brace sequence.
+ */
+export declare const ROUTES_MARKER = "__APIFORGE_ROUTES__";
+export declare const PYTHON_INTROSPECT_SCRIPT: string;

package/dist/types/frameworks/python.d.ts

@@ -0,0 +1,52 @@
+/**
+ * FastAPI / Flask / Django (+ DRF) analyzer
+ *
+ * Python apps can't be handed to analyze() as a JS object, so this runs the
+ * user's own interpreter (their venv, so their dependencies resolve), imports
+ * the app, and reads the framework's live route table — see
+ * python-introspect.ts. Nothing is injected into the user's code and no server
+ * is started. Returns the same Route[] as every other analyzer; enrichment and
+ * upload happen in index.ts / uploader.ts exactly as for Express or Fastify.
+ *
+ * The `npx apiforge` CLI instead works like its Node flow: it injects a snippet
+ * into the file returned in PythonAppCandidate.file and runs the user's own
+ * start command (see pythonFlow in cli.ts).
+ */
+import { Route } from '../export.js';
+export type PythonFramework = 'fastapi' | 'flask' | 'django';
+export interface PythonAnalyzerOptions {
+    framework: PythonFramework;
+    /** App import path, e.g. 'main:app', 'app:create_app' (with factory), 'mysite.wsgi:application'. */
+    app?: string;
+    /** Call `app` as a factory (Flask's create_app pattern). */
+    factory?: boolean;
+    /** Django settings module, e.g. 'mysite.settings'. Defaults to DJANGO_SETTINGS_MODULE / manage.py. */
+    djangoSettings?: string;
+    /** Interpreter to run. Defaults to findPythonInterpreter(). */
+    pythonPath?: string;
+    /** Directory the app is imported from. Defaults to process.cwd(). */
+    appDir?: string;
+    timeoutMs?: number;
+}
+export interface PythonAppCandidate {
+    label: string;
+    app?: string;
+    factory?: boolean;
+    djangoSettings?: string;
+    appDir: string;
+    /** File the CLI injects its snippet into: the module defining the app, or Django's manage.py. */
+    file?: string;
+}
+/**
+ * Analyze a Python web app's routes
+ */
+export declare function analyzePython(options: PythonAnalyzerOptions): Promise<Route[]>;
+/**
+ * The interpreter that has the project's dependencies installed:
+ * APIFORGE_PYTHON → active virtualenv → a venv inside the project → system python.
+ */
+export declare function findPythonInterpreter(projectDir?: string): string;
+/**
+ * Find where the app object (FastAPI/Flask) or settings module (Django) lives.
+ */
+export declare function findPythonApps(framework: PythonFramework, projectDir?: string): PythonAppCandidate[];

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ import { analyzeVite } from './frameworks/vite.js';
 import { analyzeReactRouter } from './frameworks/react-router.js';
 import { analyzeNestJS } from './frameworks/nestjs.js';
 import { analyzeFastify } from './frameworks/fastify.js';
+import { analyzePython } from './frameworks/python.js';
 import { detectFramework } from './detect.js';
 import { exportToJSON } from './export.js';
 import { uploadRoutes } from './uploader.js';
@@ -41,9 +42,17 @@ export interface AnalyzerOptions {
     }>;
     /** JSON file keyed by "METHOD /path" carrying summary/description/tags/deprecated/errors overrides for what can't be inferred. */
     annotationsPath?: string;
+    /** App import path, e.g. 'main:app' or 'app:create_app'. Auto-detected when omitted. */
+    pythonApp?: string;
+    /** Treat pythonApp as an app factory and call it (Flask create_app pattern). */
+    pythonFactory?: boolean;
+    /** Python interpreter with the app's dependencies. Defaults to APIFORGE_PYTHON / the project's venv. */
+    pythonPath?: string;
+    /** Django settings module, e.g. 'mysite.settings'. Defaults to the one manage.py sets. */
+    djangoSettings?: string;
 }
 export declare function analyze(app: any, options: AnalyzerOptions): Promise<any[]>;
-export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter, analyzeNestJS, analyzeFastify };
+export { analyzeExpress, analyzeNextPages, analyzeNextApp, analyzeVite, analyzeReactRouter, analyzeNestJS, analyzeFastify, analyzePython };
 export { exportToJSON } from './export.js';
 export { uploadRoutes } from './uploader.js';
 export type { Route } from './export.js';
@@ -58,6 +67,7 @@ declare const _default: {
     analyzeVite: typeof analyzeVite;
     analyzeReactRouter: typeof analyzeReactRouter;
     analyzeNestJS: typeof analyzeNestJS;
+    analyzePython: typeof analyzePython;
     exportToJSON: typeof exportToJSON;
     uploadRoutes: typeof uploadRoutes;
     detectFramework: typeof detectFramework;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiforge-analyzer",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Universal API documentation generator for Express, Next.js, Vite, React Router, and Node.js",
   "type": "module",
   "main": "./dist/cjs/index.js",