@ihelpee/prumo-plugin-python-fastapi 0.0.0-stage → 0.9.0

package/python/ast_extractor.py

@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+"""
+Prumo AST Extractor para Python/FastAPI — contrato canônico JSON v1.
+
+Spec: docs/especificacao-prumo-python.md §1.4. Este script é DADO do gate,
+não implementador da lei: ele apenas serializa AST em JSON. A decisão de
+"é violação?" fica 100% no core Node — a lei permanece única.
+
+Invariantes deste arquivo (atômicos, da spec):
+  R1.1 — apenas stdlib (`ast`, `json`, `sys`, `pathlib`). Import de terceiros
+         é falha de build.
+  R1.2 — nunca executa `import`/`exec`/`eval` do código analisado. Apenas
+         `ast.parse`. O subprocesso é o isolador: a análise é estática, o app
+         nunca dá boot.
+  R1.3 — arquivo com SyntaxError NÃO derruba o run: emite
+         { "path", "error": "syntax" } e sai com código 0.
+
+Uso:  python3 ast_extractor.py --files <path> [<path> ...]
+Saída: um único JSON no stdout: {"version": 1, "files": [...]}
+"""
+
+import ast
+import json
+import sys
+from pathlib import Path
+
+VERSION = 1
+
+HTTP_METHODS = {"get", "post", "put", "patch", "delete"}
+
+# Kwargs de Field(...) que constituem constraint de domínio (Pydantic v2;
+# `regex` é o nome v1 — R3.6).
+FIELD_CONSTRAINT_KWARGS = {
+    "gt", "ge", "lt", "le",
+    "min_length", "max_length",
+    "pattern", "regex",
+    "min_items", "max_items",
+    "multiple_of", "decimal_places",
+    "min_digits", "max_digits",
+    "allow_inf_nan", "strict",
+}
+
+# Tipos/constraints que já são constraint por construção (R3.6).
+CONSTRAINED_TYPES = {
+    "EmailStr", "PhoneEmail", "AnyUrl", "HttpUrl",
+    "conint", "constr", "confloat", "condecimal", "conlist", "conset",
+    "PositiveInt", "NonNegativeInt", "NegativeInt", "NonPositiveInt",
+    "PositiveFloat", "NonNegativeFloat", "NegativeFloat",
+    "FilePath", "DirectoryPath", "UUID4", "UUID", "DateTime",
+}
+
+# Anotações de parâmetro que NÃO são body model (FastAPI builtins).
+NON_BODY_ANNOTATIONS = {
+    "str", "int", "float", "bool", "bytes", "complex",
+    "dict", "list", "set", "tuple", "frozenset",
+    "Request", "WebSocket", "Response", "BackgroundTasks", "BackgroundTask",
+    "UploadFile", "Form", "File", "Query", "Path", "Header", "Cookie",
+    "Body", "Depends", "Security", "HTTPException",
+}
+
+
+def _name_of(node):
+    """Nome legível de um nó: Name.id, Attribute.attr, Subscript base."""
+    if node is None:
+        return ""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Subscript):
+        return _name_of(node.value)
+    if isinstance(node, ast.Call):
+        return _name_of(node.func)
+    return ""
+
+
+def _dotted(node):
+    """Cadeia pontuada completa de um Attribute/Name (ex.: `importlib.import_module`)."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        prefix = _dotted(node.value)
+        return f"{prefix}.{node.attr}" if prefix else node.attr
+    return ""
+
+
+def _call_name(node):
+    if isinstance(node, ast.Call):
+        return _name_of(node.func)
+    return ""
+
+
+def _field_has_constraint(node):
+    """Call a Field(...) com ao menos um kwarg de constraint de domínio."""
+    if not isinstance(node, ast.Call):
+        return False
+    if _call_name(node) != "Field":
+        return False
+    return any(k.arg in FIELD_CONSTRAINT_KWARGS for k in node.keywords)
+
+
+def _annotation_constrained(ann):
+    """A anotação carrega constraint? (Field em Annotated, tipos con*, EmailStr, unions)."""
+    if ann is None:
+        return False
+    if isinstance(ann, ast.BinOp):  # X | None
+        return _annotation_constrained(ann.left) or _annotation_constrained(ann.right)
+    if isinstance(ann, ast.Subscript):
+        base = _name_of(ann.value)
+        if base == "Annotated":
+            sl = ann.slice
+            elts = sl.elts if isinstance(sl, ast.Tuple) else [sl]
+            for extra in elts[1:]:
+                if _field_has_constraint(extra):
+                    return True
+                if _name_of(extra) in CONSTRAINED_TYPES:
+                    return True
+                if isinstance(extra, ast.Call) and _name_of(extra.func) in CONSTRAINED_TYPES:
+                    return True
+            return False
+        if base in {"Optional", "Union"}:
+            sl = ann.slice
+            elts = sl.elts if isinstance(sl, ast.Tuple) else [sl]
+            return any(_annotation_constrained(e) for e in elts)
+        return _annotation_constrained(ann.value)
+    if isinstance(ann, ast.Call):  # conint(gt=0)
+        return _name_of(ann.func) in CONSTRAINED_TYPES
+    return _name_of(ann) in CONSTRAINED_TYPES
+
+
+def _depends_inner(call):
+    """Depends(X) -> 'X' (Name, Attribute base, ou func de Call: Depends(HTTPBearer()))."""
+    if not (isinstance(call, ast.Call) and _call_name(call) == "Depends"):
+        return None
+    if not call.args:
+        return "Depends"
+    arg = call.args[0]
+    if isinstance(arg, ast.Call):
+        return _name_of(arg.func) or "Depends"
+    return _name_of(arg) or "Depends"
+
+
+def _param_depends(fn):
+    """R3.1: Depends(X) em default de parâmetro OU em Annotated[X, Depends(...)]."""
+    out = []
+    positional = list(fn.args.posonlyargs) + list(fn.args.args)
+    # defaults de posicionais alinham com os ÚLTIMOS N args (ast padrão).
+    defaults = list(fn.args.defaults)
+    pad = [None] * (len(positional) - len(defaults)) + defaults
+    kwonly = list(fn.args.kwonlyargs)
+    kwdefaults = list(fn.args.kw_defaults)
+    pairs = list(zip(positional, pad)) + list(zip(kwonly, kwdefaults))
+    for a, default in pairs:
+        dep = _depends_inner(default)
+        if dep:
+            out.append(dep)
+        ann = a.annotation
+        if isinstance(ann, ast.Subscript) and _name_of(ann.value) == "Annotated":
+            sl = ann.slice
+            elts = sl.elts if isinstance(sl, ast.Tuple) else [sl]
+            for extra in elts[1:]:
+                dep = _depends_inner(extra)
+                if dep:
+                    out.append(dep)
+    return out
+
+
+def _body_annotation(fn):
+    """Primeira anotação de parâmetro que é candidata a Pydantic model (body)."""
+    args = list(fn.args.posonlyargs) + list(fn.args.args) + list(fn.args.kwonlyargs)
+    for a in args:
+        ann = a.annotation
+        if ann is None:
+            continue
+        name = _name_of(ann)
+        if not name or name in NON_BODY_ANNOTATIONS:
+            continue
+        # Annotated[Model, Body(...)] -> Model
+        if isinstance(ann, ast.Subscript) and _name_of(ann.value) == "Annotated":
+            sl = ann.slice
+            elts = sl.elts if isinstance(sl, ast.Tuple) else [sl]
+            name = _name_of(elts[0]) if elts else name
+        if name and name not in NON_BODY_ANNOTATIONS:
+            return name
+    return None
+
+
+def _dependencies_kw(call):
+    """dependencies=[Depends(X), ...] -> [X, ...] (R3.2/R3.3)."""
+    out = []
+    for k in call.keywords:
+        if k.arg != "dependencies" or not isinstance(k.value, ast.List):
+            continue
+        for elt in k.value.elts:
+            dep = _depends_inner(elt)
+            out.append(dep if dep else _name_of(elt))
+    return [d for d in out if d]
+
+
+def _route_from_decorators(fn):
+    """Decorators @app.post / @router.put / @api_router.delete (FastAPI)."""
+    routes = []
+    for dec in fn.decorator_list:
+        if not isinstance(dec, ast.Call) or not isinstance(dec.func, ast.Attribute):
+            continue
+        method = dec.func.attr.upper()
+        if dec.func.attr.lower() not in HTTP_METHODS:
+            continue
+        prefix = _dotted(dec.func.value)  # 'app', 'router', 'module.router'
+        path = ""
+        if dec.args and isinstance(dec.args[0], ast.Constant) and isinstance(dec.args[0].value, str):
+            path = dec.args[0].value
+        response_model = None
+        for k in dec.keywords:
+            if k.arg == "response_model":
+                if isinstance(k.value, ast.Constant) and isinstance(k.value.value, str):
+                    response_model = k.value.value
+                else:
+                    response_model = _name_of(k.value) or None
+        routes.append({
+            "method": method,
+            "path": path,
+            "handler": fn.name,
+            "decorators": [f"{prefix}.{dec.func.attr}" if prefix else dec.func.attr],
+            "router_var": prefix.split(".")[-1] if prefix else "",
+            "router_dependencies": _dependencies_kw(dec),
+            "param_depends": _param_depends(fn),
+            "body_model": _body_annotation(fn),
+            "response_model": response_model,
+            "line": dec.lineno,
+        })
+    return routes
+
+
+def _is_pydantic_model(classdef):
+    for b in classdef.bases:
+        if _name_of(b) in {"BaseModel", "BaseSettings"}:
+            return True
+    return False
+
+
+def _collect_validators(classdef):
+    """(campos citados por @field_validator/@validator, model_validator presente)."""
+    cited = set()
+    model_level = False
+    for item in classdef.body:
+        if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for dec in item.decorator_list:
+            dname = _call_name(dec) if isinstance(dec, ast.Call) else _name_of(dec)
+            if dname in {"field_validator", "validator"} and isinstance(dec, ast.Call):
+                for a in dec.args:
+                    if isinstance(a, ast.Constant) and isinstance(a.value, str):
+                        cited.add(a.value)
+            if dname in {"model_validator", "root_validator"}:
+                model_level = True
+    return cited, model_level
+
+
+def _extract_model(classdef):
+    cited, model_level = _collect_validators(classdef)
+    fields = []
+    for item in classdef.body:
+        if not isinstance(item, ast.AnnAssign) or not isinstance(item.target, ast.Name):
+            continue
+        fname = item.target.id
+        has_constraint = _annotation_constrained(item.annotation) or _field_has_constraint(item.value)
+        has_validator = model_level or fname in cited
+        fields.append({
+            "name": fname,
+            "annotation": _name_of(item.annotation),
+            "has_constraint": has_constraint,
+            "has_validator": has_validator,
+        })
+    return {
+        "name": classdef.name,
+        "bases": [_name_of(b) for b in classdef.bases],
+        "line": classdef.lineno,
+        "fields": fields,
+    }
+
+
+def _module_of(rel_path):
+    """'app/orders/router.py' -> 'app.orders.router'; __init__.py -> pacote."""
+    p = rel_path[:-3] if rel_path.endswith(".py") else rel_path
+    parts = p.replace("\\", "/").split("/")
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _resolve_relative(file_module_parts, level, module):
+    """R2.3: resolve `from ..x import y` contra o pacote do arquivo."""
+    base = list(file_module_parts)  # partes do diretório do módulo
+    drop = level - 1
+    if drop > len(base):
+        return None
+    if drop:
+        base = base[: len(base) - drop]
+    parts = base + (module.split(".") if module else [])
+    return ".".join(parts) if parts else None
+
+
+def _extract_imports(tree, rel_path):
+    imports = []
+    parts = _module_of(rel_path).split(".") if _module_of(rel_path) else []
+    dir_parts = parts[:-1] if parts else []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append({
+                    "module": alias.name,
+                    "names": [alias.asname or alias.name],
+                    "relative": False,
+                    "line": node.lineno,
+                })
+        elif isinstance(node, ast.ImportFrom):
+            if node.level and node.level > 0:
+                resolved = _resolve_relative(dir_parts, node.level, node.module or "")
+                if resolved is None:
+                    continue
+                imports.append({
+                    "module": resolved,
+                    "names": [a.asname or a.name for a in node.names],
+                    "relative": True,
+                    "line": node.lineno,
+                })
+            else:
+                imports.append({
+                    "module": node.module or "",
+                    "names": [a.asname or a.name for a in node.names],
+                    "relative": False,
+                    "line": node.lineno,
+                })
+    return imports
+
+
+def _extract_dynamic_imports(tree):
+    """R2.4 anti-burla: importlib.import_module('...') e __import__('...')."""
+    out = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        dotted = _dotted(node.func)
+        is_dynamic = dotted == "__import__" or dotted.endswith("importlib.import_module") or dotted == "import_module"
+        if not is_dynamic or not node.args:
+            continue
+        first = node.args[0]
+        if isinstance(first, ast.Constant) and isinstance(first.value, str):
+            out.append({"expr": f"{dotted}({first.value!r})", "module": first.value, "line": node.lineno})
+    return out
+
+
+def _extract_router_defs(tree):
+    """`router = APIRouter(dependencies=[...])` (R3.3, camada de definição)."""
+    routers = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assign) or not isinstance(node.value, ast.Call):
+            continue
+        if _call_name(node.value) != "APIRouter":
+            continue
+        for t in node.targets:
+            if isinstance(t, ast.Name):
+                routers.append({"var": t.id, "dependencies": _dependencies_kw(node.value)})
+    return routers
+
+
+def _extract_include_routers(tree):
+    """`app.include_router(x, dependencies=[...])` (R3.3, camada de montagem)."""
+    out = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
+            continue
+        if node.func.attr != "include_router" or not node.args:
+            continue
+        target = _dotted(node.args[0])
+        if not target:
+            continue
+        out.append({"target": target, "dependencies": _dependencies_kw(node)})
+    return out
+
+
+def _extract_file(path, root):
+    rel = str(path.relative_to(root)) if root in path.parents or path == root else str(path)
+    rel = rel.replace("\\", "/")
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return {"path": rel, "error": "unreadable"}
+    try:
+        tree = ast.parse(source, filename=rel)
+    except SyntaxError:
+        # R1.3: nunca derruba o run, nunca stack trace no stdout.
+        return {"path": rel, "error": "syntax"}
+
+    pydantic_v1 = any(
+        imp["module"] == "pydantic.v1" or imp["module"].startswith("pydantic.v1.")
+        for imp in _extract_imports(tree, rel)
+    )
+
+    routes = []
+    models = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            routes.extend(_route_from_decorators(node))
+        elif isinstance(node, ast.ClassDef) and _is_pydantic_model(node):
+            models.append(_extract_model(node))
+
+    return {
+        "path": rel,
+        "imports": _extract_imports(tree, rel),
+        "dynamic_imports": _extract_dynamic_imports(tree),
+        "routes": routes,
+        "models": models,
+        "routers": _extract_router_defs(tree),
+        "include_routers": _extract_include_routers(tree),
+        "pydantic_v1": pydantic_v1,
+    }
+
+
+def main(argv):
+    if "--files" not in argv:
+        print(json.dumps({"version": VERSION, "files": []}))
+        return 0
+    idx = argv.index("--files")
+    root = Path.cwd()
+    files = []
+    for raw in argv[idx + 1:]:
+        p = Path(raw)
+        if not p.is_absolute():
+            p = root / p
+        files.append(p)
+    out = [_extract_file(p, root) for p in files]
+    print(json.dumps({"version": VERSION, "files": out}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))