apiforge-analyzer 1.3.6 → 1.3.8

package/dist/cjs/detect.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_FRAMEWORKS = void 0;
 exports.detectFramework = detectFramework;
+exports.detectPythonFramework = detectPythonFramework;
+exports.readTextFile = readTextFile;
 const fs_1 = require("fs");
 const path_1 = require("path");
 /**
@@ -17,6 +19,9 @@ exports.SUPPORTED_FRAMEWORKS = new Set([
     'nextjs-app',
     'vite',
     'react-router',
+    'fastapi',
+    'flask',
+    'django',
 ]);
 const cwd = () => process.cwd();
 function fileExists(rel) {
@@ -102,5 +107,48 @@ function detectFramework(app) {
         return mk('vite', 0.60);
     if (tryResolve('react-router-dom'))
         return mk('react-router', 0.55);
+    // ── Python projects (checked last so no JS project's detection changes) ───
+    const python = detectPythonFramework();
+    if (python)
+        return mk(python, 0.65);
     return mk('unknown', 0);
 }
+const PYTHON_DEPENDENCY_FILES = ['requirements.txt', 'requirements/base.txt', 'pyproject.toml', 'Pipfile', 'setup.py', 'setup.cfg'];
+/**
+ * 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.
+ */
+function detectPythonFramework(dir = cwd()) {
+    if ((0, fs_1.existsSync)((0, path_1.join)(dir, 'manage.py')))
+        return 'django';
+    const deps = PYTHON_DEPENDENCY_FILES
+        .map(file => {
+        try {
+            return readTextFile((0, path_1.join)(dir, file)).toLowerCase();
+        }
+        catch {
+            return '';
+        }
+    })
+        .join('\n');
+    if (/\bfastapi\b/.test(deps))
+        return 'fastapi';
+    if (/\bdjango\b/.test(deps))
+        return 'django';
+    if (/\bflask\b/.test(deps))
+        return 'flask';
+    return 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.
+ */
+function readTextFile(path) {
+    const buf = (0, fs_1.readFileSync)(path);
+    if (buf[0] === 0xff && buf[1] === 0xfe)
+        return buf.subarray(2).toString('utf16le');
+    if (buf[0] === 0xfe && buf[1] === 0xff)
+        return Buffer.from(buf.subarray(2)).swap16().toString('utf16le');
+    return buf.toString('utf-8');
+}

package/dist/cjs/frameworks/python-introspect.js

@@ -0,0 +1,555 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PYTHON_INTROSPECT_SCRIPT = exports.ROUTES_MARKER = void 0;
+exports.ROUTES_MARKER = '__APIFORGE_ROUTES__';
+exports.PYTHON_INTROSPECT_SCRIPT = String.raw `
+import importlib, inspect, json, os, re, sys
+
+MARKER = "__APIFORGE_ROUTES__"
+FRAMEWORK_MODULES = {"flask", "werkzeug", "django", "rest_framework", "fastapi", "starlette"}
+BODY_METHODS = {"POST", "PUT", "PATCH"}
+HTTP_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE"}
+
+# Decorators that register routes or configure DRF/Django rather than guard the handler.
+IGNORED_DECORATORS = {
+    "route", "get", "post", "put", "patch", "delete", "head", "options", "websocket",
+    "api_view", "action", "permission_classes", "authentication_classes", "throttle_classes",
+    "parser_classes", "renderer_classes", "schema", "require_http_methods", "require_GET",
+    "require_POST", "require_safe", "staticmethod", "classmethod", "property", "wraps",
+    "method_decorator",
+}
+AUTH_HINTS = (
+    "auth", "login_required", "permission_required", "jwt_required", "token_required",
+    "staff_member_required", "user_passes_test", "verifytoken", "protect",
+)
+STATUS_TEXT = {
+    400: "Invalid request input", 401: "Authentication required or invalid credentials",
+    403: "Forbidden — insufficient permissions", 404: "Resource not found",
+    409: "Conflict — resource already exists", 422: "Unprocessable entity",
+    429: "Too many requests — rate limit exceeded", 500: "Unexpected server error",
+    503: "Service unavailable",
+}
+
+# ── Handler source scanning (Flask/Django declare none of this) ─────────────
+NAME = r"""['"]([\w\-.]+)['"]"""
+ACCESS = r"(?:\.get(?:list)?\(|\[)\s*"
+BODY_SOURCE = r"request\.(?:json|form|data|POST|get_json\([^)]*\))"
+QUERY_RE = re.compile(r"request\.(?:args|GET|query_params)" + ACCESS + NAME)
+BODY_RE = re.compile(BODY_SOURCE + ACCESS + NAME)
+BODY_VAR_RE = re.compile(r"^\s*(\w+)\s*(?::[^=\n]+)?=\s*(?:" + BODY_SOURCE + r"|json\.loads\(\s*request\.body)", re.M)
+HEADER_RE = re.compile(r"request\.headers" + ACCESS + NAME)
+META_HEADER_RE = re.compile(r"""request\.META(?:\.get\(|\[)\s*['"]HTTP_(\w+)['"]""")
+DECORATOR_RE = re.compile(r"^\s*@([\w.]+)", re.M)
+STATUS_RES = [
+    re.compile(r"\babort\(\s*(\d{3})"),
+    re.compile(r"\bstatus(?:_code)?\s*=\s*(\d{3})\b"),
+    re.compile(r"\bHTTP_(\d{3})_"),
+    re.compile(r"^\s*return\b[^\n]*,\s*(\d{3})\s*(?:#[^\n]*)?$", re.M),
+]
+STATUS_NAMES = {
+    "get_object_or_404": 404, "Http404": 404, "HttpResponseNotFound": 404,
+    "HttpResponseBadRequest": 400, "HttpResponseForbidden": 403,
+    "HttpResponseNotAllowed": 405, "HttpResponseServerError": 500,
+}
+DECLARED_METHODS_RE = re.compile(r"@require_http_methods\(\s*\[([^\]]*)\]")
+
+
+def unique(items):
+    seen = []
+    for item in items:
+        if item and item not in seen:
+            seen.append(item)
+    return seen
+
+
+def is_user_code(fn):
+    module = getattr(fn, "__module__", None) or ""
+    return bool(module) and module.split(".")[0] not in FRAMEWORK_MODULES
+
+
+def unwrap(fn):
+    try:
+        return inspect.unwrap(fn)
+    except (ValueError, TypeError):
+        return fn
+
+
+def get_source(fn):
+    fn = unwrap(fn)
+    if fn is None or not is_user_code(fn):
+        return ""
+    try:
+        return inspect.getsource(fn)
+    except (OSError, TypeError):
+        return ""
+
+
+def docstring(fn):
+    fn = unwrap(fn)
+    if fn is None or not is_user_code(fn):
+        return "", ""
+    first, _, rest = (inspect.getdoc(fn) or "").strip().partition("\n")
+    return first.strip(), rest.strip()
+
+
+def declared_methods(source):
+    match = DECLARED_METHODS_RE.search(source)
+    if match:
+        return unique(m.upper() for m in re.findall(r"""['"](\w+)['"]""", match.group(1)))
+    if "@require_POST" in source:
+        return ["POST"]
+    if "@require_GET" in source or "@require_safe" in source:
+        return ["GET"]
+    return []
+
+
+def scan_source(source):
+    body = list(BODY_RE.findall(source))
+    for var in sorted(set(BODY_VAR_RE.findall(source))):
+        body += re.findall(r"\b" + re.escape(var) + ACCESS + NAME, source)
+    headers = list(HEADER_RE.findall(source))
+    headers += ["-".join(p.capitalize() for p in raw.split("_")) for raw in META_HEADER_RE.findall(source)]
+    statuses = [int(code) for pattern in STATUS_RES for code in pattern.findall(source)]
+    statuses += [code for name, code in STATUS_NAMES.items() if re.search(r"\b" + name + r"\b", source)]
+    header = source.split("def ", 1)[0]
+    decorators = [n.rsplit(".", 1)[-1] for n in DECORATOR_RE.findall(header)]
+    return {
+        "query": unique(QUERY_RE.findall(source)),
+        "body": unique(body),
+        "headers": unique(headers),
+        "statuses": sorted({s for s in statuses if 100 <= s < 600}),
+        "decorators": unique(n for n in decorators if n not in IGNORED_DECORATORS),
+    }
+
+
+def looks_like_auth(names):
+    return any(hint in name.lower() for name in names for hint in AUTH_HINTS)
+
+
+def path_parameter(name, type_="string", fmt=None):
+    schema = {"type": type_}
+    if fmt:
+        schema["format"] = fmt
+    return {"name": name, "in": "path", "required": True, "type": type_, "schema": schema,
+            "description": "Required path parameter: " + name + "."}
+
+
+def build_route(framework, method, path, handler, path_params, operation_id,
+                middleware=(), auth=False, request_body=None):
+    """Route for frameworks that don't describe their own params (Flask, Django)."""
+    scan = scan_source(get_source(handler))
+    summary, description = docstring(handler)
+    names = unique(list(middleware) + scan["decorators"])
+    auth_required = bool(auth or looks_like_auth(names))
+    takes_body = method in BODY_METHODS
+    body_fields = scan["body"] if takes_body else []
+    if takes_body and request_body:
+        schema = request_body["content"]["application/json"]["schema"]
+        body_fields = unique(list(schema.get("properties", {})) + body_fields)
+    route = {
+        "method": method, "path": path, "routeKey": method + " " + path, "tag": "",
+        "operationId": operation_id, "summary": summary, "description": description,
+        "middleware": names, "authRequired": auth_required, "hasAuth": auth_required,
+        "pathParams": [p["name"] for p in path_params], "queryParams": scan["query"],
+        "requestBodyFields": body_fields, "headerParams": scan["headers"],
+        "responseStatuses": scan["statuses"], "parameters": list(path_params),
+        "linkedPaths": [], "framework": framework,
+    }
+    if takes_body and request_body:
+        route["requestBody"] = request_body
+    return route
+
+
+# ── FastAPI: the app's own OpenAPI document carries the real Pydantic schemas ─
+FASTAPI_PARAM = re.compile(r"\{(\w+)(?::\w+)?\}")
+
+
+def deref(node, spec, seen=()):
+    """Inline local $refs so the backend sees schema properties directly."""
+    if isinstance(node, list):
+        return [deref(item, spec, seen) for item in node]
+    if not isinstance(node, dict):
+        return node
+    ref = node.get("$ref")
+    if isinstance(ref, str) and ref.startswith("#/"):
+        if ref in seen:
+            return {"type": "object", "description": "Recursive reference to " + ref.rsplit("/", 1)[-1] + "."}
+        target = spec
+        for part in ref[2:].split("/"):
+            target = target.get(part, {}) if isinstance(target, dict) else {}
+        merged = dict(target)
+        merged.update({k: v for k, v in node.items() if k != "$ref"})
+        return deref(merged, spec, seen + (ref,))
+    return {key: deref(value, spec, seen) for key, value in node.items()}
+
+
+def schema_type(schema):
+    if schema.get("type"):
+        return schema["type"]
+    for option in schema.get("anyOf") or schema.get("oneOf") or []:
+        if option.get("type") and option["type"] != "null":
+            return option["type"]
+    return "string"
+
+
+def analyze_fastapi(app):
+    spec = app.openapi()
+    live_routes = {}
+    for live in getattr(app, "routes", []):
+        path_format = getattr(live, "path_format", None) or getattr(live, "path", None)
+        for method in getattr(live, "methods", None) or ():
+            live_routes[(path_format, method.upper())] = live
+
+    global_auth = bool(spec.get("security"))
+    routes = []
+    for raw_path, item in (spec.get("paths") or {}).items():
+        path = FASTAPI_PARAM.sub(r":\1", raw_path)
+        shared = deref(item.get("parameters") or [], spec)
+        for method, operation in item.items():
+            method = method.upper()
+            if method not in HTTP_METHODS or not isinstance(operation, dict):
+                continue
+            operation = deref(operation, spec)
+            live = live_routes.get((raw_path, method))
+            routes.append(fastapi_route(path, method, operation, shared, live, global_auth))
+
+    # Sub-applications attached with app.mount() have their own OpenAPI document.
+    for live in getattr(app, "routes", []):
+        sub_app = getattr(live, "app", None)
+        if type(live).__name__ == "Mount" and hasattr(sub_app, "openapi"):
+            prefix = (getattr(live, "path", "") or "").rstrip("/")
+            for route in analyze_fastapi(sub_app):
+                route["path"] = prefix + route["path"]
+                route["routeKey"] = route["method"] + " " + route["path"]
+                routes.append(route)
+    return routes
+
+
+def fastapi_route(path, method, operation, shared, live, global_auth):
+    parameters = []
+    for p in shared + (operation.get("parameters") or []):
+        schema = p.get("schema") or {}
+        location = p.get("in", "query")
+        parameters.append({
+            "name": p["name"], "in": location, "required": bool(p.get("required", location == "path")),
+            "type": schema_type(schema), "schema": schema,
+            "description": p.get("description") or location.capitalize() + " parameter: " + p["name"] + ".",
+        })
+    responses = dict(operation.get("responses") or {})
+    request_body = operation.get("requestBody")
+
+    handler = getattr(live, "endpoint", None)
+    scan = scan_source(get_source(handler))
+    # HTTPException(status_code=...) raised inside the handler never reaches OpenAPI.
+    for code in scan["statuses"]:
+        responses.setdefault(str(code), {"description": STATUS_TEXT.get(code, "HTTP " + str(code))})
+
+    middleware = []
+    for dependency in getattr(getattr(live, "dependant", None), "dependencies", None) or []:
+        call = getattr(dependency, "call", None)
+        if call is not None:
+            middleware.append(getattr(call, "__name__", None) or type(call).__name__)
+    middleware = unique(middleware)
+    auth = bool(operation["security"]) if "security" in operation else global_auth
+    auth = auth or looks_like_auth(middleware)
+
+    operation_id = operation.get("operationId", "")
+    if live is not None:
+        name = getattr(live, "name", "") or ""
+        methods = getattr(live, "methods", None) or ()
+        operation_id = getattr(live, "operation_id", None) or (name if len(methods) <= 1 else name + "_" + method.lower())
+
+    body_fields = []
+    for media in ((request_body or {}).get("content") or {}).values():
+        body_fields = list(((media or {}).get("schema") or {}).get("properties") or {})
+        break
+
+    route = {
+        "method": method, "path": path, "routeKey": method + " " + path,
+        "tag": (operation.get("tags") or [""])[0], "operationId": operation_id,
+        "summary": operation.get("summary", ""), "description": operation.get("description", ""),
+        "middleware": middleware, "authRequired": auth, "hasAuth": auth,
+        "pathParams": [p["name"] for p in parameters if p["in"] == "path"],
+        "queryParams": [p["name"] for p in parameters if p["in"] == "query"],
+        "headerParams": unique([p["name"] for p in parameters if p["in"] == "header"] + scan["headers"]),
+        "requestBodyFields": body_fields,
+        "responseStatuses": sorted(int(code) for code in responses if code.isdigit()),
+        "parameters": parameters, "linkedPaths": [], "framework": "fastapi",
+    }
+    if operation.get("tags"):
+        route["tags"] = operation["tags"]
+    if request_body:
+        route["requestBody"] = request_body
+    if responses:
+        route["responses"] = responses
+    return route
+
+
+# ── Flask: app.url_map is the table Flask itself dispatches from ────────────
+FLASK_PARAM = re.compile(r"<(?:(\w+)(?:\([^)]*\))?:)?(\w+)>")
+FLASK_TYPES = {"int": ("integer", None), "float": ("number", None), "uuid": ("string", "uuid")}
+
+
+def analyze_flask(app):
+    routes = []
+    for rule in sorted(app.url_map.iter_rules(), key=lambda r: (r.rule, r.endpoint)):
+        if rule.endpoint == "static" or rule.endpoint.endswith(".static"):
+            continue
+        params = []
+
+        def replace(match, params=params):
+            type_, fmt = FLASK_TYPES.get(match.group(1) or "string", ("string", None))
+            params.append(path_parameter(match.group(2), type_, fmt))
+            return ":" + match.group(2)
+
+        path = FLASK_PARAM.sub(replace, rule.rule)
+        view = app.view_functions.get(rule.endpoint)
+        view_class = getattr(view, "view_class", None)
+        class_decorators = [getattr(d, "__name__", "") for d in getattr(view_class, "decorators", None) or []]
+        methods = sorted(set(rule.methods or ()) - {"HEAD", "OPTIONS"})
+        name = rule.endpoint.rsplit(".", 1)[-1]
+        for method in methods:
+            # MethodView: document the per-method handler, not the generic dispatcher.
+            handler = getattr(view_class, method.lower(), None) if view_class else None
+            routes.append(build_route(
+                "flask", method, path, handler or view, params,
+                name if len(methods) == 1 else name + "_" + method.lower(),
+                middleware=class_decorators,
+            ))
+    return routes
+
+
+# ── Django / DRF: walk the root URLconf resolver ──────────────────────────────
+# Admin, DRF's browsable-API login and the debug toolbar aren't part of the user's API.
+DJANGO_SKIP_NAMESPACES = {"admin", "rest_framework", "djdt"}
+DJANGO_PARAM = re.compile(r"<(?:(\w+):)?(\w+)>")
+DJANGO_TYPES = {"int": ("integer", None), "uuid": ("string", "uuid")}
+AUTH_MIXINS = {"LoginRequiredMixin", "PermissionRequiredMixin", "UserPassesTestMixin"}
+SERIALIZER_TYPES = {
+    "BooleanField": "boolean", "IntegerField": "integer", "FloatField": "number",
+    "DecimalField": "number", "ListField": "array", "ManyRelatedField": "array",
+    "ListSerializer": "array", "DictField": "object", "JSONField": "object", "Serializer": "object",
+}
+
+
+def analyze_django():
+    import django
+    from django.apps import apps
+    if not apps.ready:
+        django.setup()
+    from django.urls import get_resolver
+
+    routes = []
+    for path, params, pattern in walk_urls(get_resolver().url_patterns, "", []):
+        routes.extend(django_routes(path, params, pattern))
+    return routes
+
+
+def walk_urls(patterns, prefix, params):
+    from django.urls import URLPattern, URLResolver
+    for pattern in patterns:
+        piece, piece_params = convert_django_pattern(pattern.pattern)
+        if piece is None:
+            continue
+        if isinstance(pattern, URLResolver):
+            if {pattern.namespace, pattern.app_name} & DJANGO_SKIP_NAMESPACES:
+                continue
+            yield from walk_urls(pattern.url_patterns, prefix + piece, params + piece_params)
+        elif isinstance(pattern, URLPattern):
+            yield "/" + re.sub(r"/{2,}", "/", (prefix + piece).lstrip("/")), params + piece_params, pattern
+
+
+def convert_django_pattern(pattern):
+    from django.urls.resolvers import RegexPattern, RoutePattern
+    raw = str(pattern)
+    if isinstance(pattern, RoutePattern):
+        params = []
+
+        def replace(match):
+            type_, fmt = DJANGO_TYPES.get(match.group(1) or "str", ("string", None))
+            params.append(path_parameter(match.group(2), type_, fmt))
+            return ":" + match.group(2)
+
+        return DJANGO_PARAM.sub(replace, raw), params
+    if isinstance(pattern, RegexPattern):
+        # DRF's format_suffix_patterns duplicates every route as '.json' etc.
+        if "(?P<format>" in raw:
+            return None, []
+        return regex_to_path(raw)
+    return raw, []  # LocalePrefixPattern: the language prefix
+
+
+def regex_to_path(regex):
+    """'^users/(?P<pk>[^/.]+)/$' -> ('users/:pk/', [pk])."""
+    regex = re.sub(r"^\^|(?:\$|\\Z)$", "", regex)
+    out, params, i = [], [], 0
+    while i < len(regex):
+        if regex.startswith("(?P<", i):
+            name_end = regex.index(">", i)
+            name = regex[i + 4:name_end]
+            depth, j = 1, name_end + 1
+            while j < len(regex) and depth:
+                if regex[j] == "\\":
+                    j += 2
+                    continue
+                depth += {"(": 1, ")": -1}.get(regex[j], 0)
+                j += 1
+            out.append(":" + name)
+            params.append(path_parameter(name))
+            i = j
+        else:
+            out.append(regex[i])
+            i += 1
+    return re.sub(r"\\(.)", r"\1", "".join(out).replace("/?", "/")), params
+
+
+def django_routes(path, params, pattern):
+    callback = pattern.callback
+    view_class = getattr(callback, "view_class", None) or getattr(callback, "cls", None)
+    actions = getattr(callback, "actions", None)  # DRF ViewSet: {'get': 'list', ...}
+    base_name = pattern.name or getattr(callback, "__name__", "view")
+
+    if actions and view_class:
+        handlers = {m.upper(): (getattr(view_class, a, None), base_name + "_" + a) for m, a in actions.items()}
+    elif view_class:
+        methods = [m for m in view_class.http_method_names if m not in ("head", "options") and hasattr(view_class, m)]
+        handlers = {m.upper(): (getattr(view_class, m), base_name if len(methods) == 1 else base_name + "_" + m)
+                    for m in methods}
+    else:
+        methods = declared_methods(get_source(callback)) or ["GET"]
+        handlers = {m: (callback, base_name if len(methods) == 1 else base_name + "_" + m.lower()) for m in methods}
+
+    middleware, auth = [], False
+    if view_class is not None:
+        for permission in getattr(view_class, "permission_classes", None) or []:
+            pname = getattr(permission, "__name__", None) or type(permission).__name__
+            if pname != "AllowAny":
+                middleware.append(pname)
+        middleware += [b.__name__ for b in view_class.__mro__ if b.__name__ in AUTH_MIXINS]
+        auth = bool(middleware)
+    request_body = serializer_body(view_class)
+
+    return [
+        build_route("django", method, path, user_function(handler), params, operation_id,
+                    middleware=middleware, auth=auth, request_body=request_body)
+        for method, (handler, operation_id) in sorted(handlers.items())
+    ]
+
+
+def serializer_body(view_class):
+    serializer_class = getattr(view_class, "serializer_class", None)
+    if serializer_class is None:
+        return None
+    try:
+        fields = serializer_class().fields
+    except Exception:  # serializers that need context/instance to build their fields
+        return None
+    properties, required = {}, []
+    for name, field in fields.items():
+        if getattr(field, "read_only", False):
+            continue
+        type_ = next((SERIALIZER_TYPES[b.__name__] for b in type(field).__mro__ if b.__name__ in SERIALIZER_TYPES), "string")
+        prop = {"type": type_}
+        if getattr(field, "help_text", None):
+            prop["description"] = str(field.help_text)
+        properties[name] = prop
+        if getattr(field, "required", False):
+            required.append(name)
+    if not properties:
+        return None
+    schema = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return {"required": True, "content": {"application/json": {"schema": schema}}}
+
+
+def user_function(fn):
+    """DRF's @api_view wraps the user's function in a generated handler; find the original."""
+    if fn is None or is_user_code(unwrap(fn)):
+        return fn
+    for cell in getattr(fn, "__closure__", None) or ():
+        try:
+            value = cell.cell_contents
+        except ValueError:
+            continue
+        if callable(value) and is_user_code(value):
+            return value
+    return fn
+
+
+# ── Entry ─────────────────────────────────────────────────────────────────────
+def load_app(target, factory):
+    module_name, _, attr_path = target.partition(":")
+    app = importlib.import_module(module_name)
+    for attr in (attr_path or "app").split("."):
+        app = getattr(app, attr)
+    return app() if factory else app
+
+
+def collect(framework, app):
+    if framework == "django":
+        return analyze_django()
+    return analyze_fastapi(app) if framework == "fastapi" else analyze_flask(app)
+
+
+def main():
+    opts = json.loads(os.environ["APIFORGE_PY_OPTIONS"])
+    sys.path.insert(0, os.path.abspath(opts.get("appDir") or "."))
+    real_stdout = sys.stdout
+    sys.stdout = sys.stderr  # prints from the user's app must not corrupt the JSON line
+
+    framework = opts["framework"]
+    app = None
+    if framework == "django":
+        if opts.get("djangoSettings"):
+            os.environ["DJANGO_SETTINGS_MODULE"] = opts["djangoSettings"]
+        if opts.get("app"):
+            load_app(opts["app"], False)  # e.g. mysite.wsgi:application, which runs django.setup()
+    else:
+        app = load_app(opts["app"], opts.get("factory"))
+    routes = collect(framework, app)
+
+    real_stdout.write(MARKER + json.dumps(routes, default=str) + "\n")
+    real_stdout.flush()
+
+
+def report_from_server(app):
+    """Injected mode: the user's own start command loaded the app and the CLI's
+    snippet exec'd this script with it. Writes the status file the CLI polls;
+    never raises, so a failure here can't take the user's server down."""
+    status_file = os.environ["APIFORGE_STATUS_FILE"]
+    try:
+        # Django: the snippet runs in manage.py before the command (and so before
+        # main() sets this); analyze_django() then runs django.setup() itself.
+        if os.environ.get("APIFORGE_DJANGO_SETTINGS"):
+            os.environ.setdefault("DJANGO_SETTINGS_MODULE", os.environ["APIFORGE_DJANGO_SETTINGS"])
+        payload = {"status": "collected", "routes": collect(os.environ["APIFORGE_FRAMEWORK"], app)}
+    except Exception as exc:
+        payload = {"status": "error", "error": type(exc).__name__ + ": " + str(exc)}
+    tmp = status_file + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(payload, fh, default=str)
+    os.replace(tmp, status_file)
+
+
+if "APIFORGE_APP" in globals():
+    report_from_server(APIFORGE_APP)
+else:
+    main()
+`;