codebread 1.0.0__py3-none-any.whl

codebread/parsers/javascript_parser.py

@@ -0,0 +1,371 @@
+"""JavaScript / TypeScript extractor (regex + brace matching).
+
+Handles: function declarations, arrow/const functions, classes + methods,
+imports, Express/Fastify/Koa route definitions, NestJS decorators,
+fetch/axios API calls, and Mongoose/Prisma/Sequelize/Knex/raw-SQL DB usage.
+Also parses the <script> block of .vue / .svelte single-file components.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+
+from ..models import (ApiCall, DbRef, FileInfo, FunctionInfo, Route,
+                      TableInfo, describe)
+
+JS_KEYWORDS = {
+    "if", "for", "while", "switch", "catch", "return", "typeof", "new",
+    "function", "await", "async", "else", "do", "try", "throw", "delete",
+    "in", "of", "instanceof", "void", "yield", "case", "break", "continue",
+    "super", "this", "import", "export", "default", "constructor",
+}
+
+RE_FUNC_DECL = re.compile(
+    r"^[ \t]*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*"
+    r"([A-Za-z_$][\w$]*)\s*\(([^)]*)\)", re.MULTILINE)
+RE_ARROW = re.compile(
+    r"^[ \t]*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*"
+    r"(?::[^=]{0,80})?=\s*(?:async\s*)?"
+    r"(?:\(([^)]*)\)|([A-Za-z_$][\w$]*))\s*(?::\s*[\w<>\[\]., |]+)?\s*=>",
+    re.MULTILINE)
+RE_CLASS = re.compile(
+    r"^[ \t]*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+"
+    r"([A-Za-z_$][\w$]*)(?:\s+extends\s+([\w$.]+))?", re.MULTILINE)
+RE_METHOD = re.compile(
+    r"^[ \t]*(?:public\s+|private\s+|protected\s+|readonly\s+)*"
+    r"(?:static\s+)?(?:async\s+)?\*?\s*([A-Za-z_$][\w$]*)\s*\(([^)]*)\)\s*"
+    r"(?::\s*[\w<>\[\]., |&{}]+)?\s*\{", re.MULTILINE)
+RE_IMPORT = re.compile(
+    r"""(?:import\s+(?:[\w${},*\s]+\s+from\s+)?|require\s*\(\s*)"""
+    r"""['"]([^'"]+)['"]""")
+RE_ROUTE = re.compile(
+    r"\b(?:app|router|server|api|fastify|routes?)\s*\.\s*"
+    r"(get|post|put|delete|patch|all|options|head)\s*\(\s*[`'\"]([^`'\"]+)[`'\"]"
+    r"\s*,\s*([A-Za-z_$][\w$.]*)?", re.IGNORECASE)
+RE_NEST_ROUTE = re.compile(
+    r"@(Get|Post|Put|Delete|Patch|All)\s*\(\s*(?:[`'\"]([^`'\"]*)[`'\"])?\s*\)")
+RE_FETCH = re.compile(r"\bfetch\s*\(\s*[`'\"]([^`'\"]+)[`'\"]")
+RE_FETCH_METHOD = re.compile(r"method\s*:\s*[`'\"](\w+)[`'\"]", re.IGNORECASE)
+RE_AXIOS = re.compile(
+    r"\b(?:axios|http|api|apiClient|client|\$http)\s*\.\s*"
+    r"(get|post|put|delete|patch)\s*\(\s*[`'\"]([^`'\"]+)[`'\"]",
+    re.IGNORECASE)
+RE_AXIOS_OBJ = re.compile(
+    r"\baxios\s*\(\s*\{[^}]*?url\s*:\s*[`'\"]([^`'\"]+)[`'\"]", re.DOTALL)
+RE_MONGOOSE = re.compile(r"mongoose\.model\s*\(\s*[`'\"](\w+)[`'\"]")
+RE_MONGOOSE_SCHEMA = re.compile(
+    r"new\s+(?:mongoose\.)?Schema\s*\(\s*\{([^}]*)\}", re.DOTALL)
+RE_PRISMA = re.compile(
+    r"\bprisma\.(\w+)\.(findMany|findUnique|findFirst|create|createMany|"
+    r"update|updateMany|delete|deleteMany|upsert|count|aggregate)\b")
+RE_SEQUELIZE = re.compile(r"sequelize\.define\s*\(\s*[`'\"](\w+)[`'\"]")
+RE_KNEX = re.compile(r"\bknex\s*\(\s*[`'\"](\w+)[`'\"]")
+RE_TYPEORM_ENTITY = re.compile(r"@Entity\s*\(\s*(?:[`'\"](\w+)[`'\"])?\s*\)")
+RE_SQL = re.compile(
+    r"\b(SELECT|INSERT|UPDATE|DELETE)\b[\s\S]{0,200}?"
+    r"\b(?:FROM|INTO|UPDATE|JOIN)\s+[`\"\[]?([A-Za-z_][A-Za-z0-9_.]*)",
+    re.IGNORECASE)
+RE_MODEL_OP = re.compile(
+    r"\b([A-Z][\w$]*)\.(find|findOne|findById|findAll|findMany|create|"
+    r"insertMany|updateOne|updateMany|findByIdAndUpdate|findByIdAndDelete|"
+    r"deleteOne|deleteMany|destroy|save|aggregate|countDocuments)\b")
+RE_CALL = re.compile(r"(?<![\w$.])([A-Za-z_$][\w$]*)\s*\(")
+
+OP_MAP = {"create": "insert", "insertmany": "insert", "save": "insert",
+          "update": "update", "updateone": "update", "updatemany": "update",
+          "findbyidandupdate": "update", "delete": "delete",
+          "deleteone": "delete", "deletemany": "delete", "destroy": "delete",
+          "findbyidanddelete": "delete"}
+
+
+def _strip_comments(text: str) -> str:
+    """Blank out comments and (roughly) string contents so structural regexes
+    don't fire inside them — but keep offsets/line numbers identical."""
+    out = list(text)
+    i, n = 0, len(text)
+    in_str: Optional[str] = None
+    while i < n:
+        c = text[i]
+        if in_str:
+            if c == "\\":
+                i += 2
+                continue
+            if c == in_str:
+                in_str = None
+            i += 1
+            continue
+        if c in "'\"`":
+            in_str = c
+            i += 1
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "/":
+            j = text.find("\n", i)
+            j = n if j == -1 else j
+            for k in range(i, j):
+                out[k] = " "
+            i = j
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "*":
+            j = text.find("*/", i + 2)
+            j = n if j == -1 else j + 2
+            for k in range(i, j):
+                if out[k] != "\n":
+                    out[k] = " "
+            i = j
+            continue
+        i += 1
+    return "".join(out)
+
+
+def _match_brace(text: str, open_idx: int) -> int:
+    """Index of the `}` matching the `{` at open_idx. -1 if unbalanced."""
+    depth = 0
+    i, n = open_idx, len(text)
+    in_str: Optional[str] = None
+    while i < n:
+        c = text[i]
+        if in_str:
+            if c == "\\":
+                i += 2
+                continue
+            if c == in_str:
+                in_str = None
+        elif c in "'\"`":
+            in_str = c
+        elif c == "/" and i + 1 < n and text[i + 1] == "/":
+            nl = text.find("\n", i)
+            if nl == -1:
+                return -1
+            i = nl
+        elif c == "/" and i + 1 < n and text[i + 1] == "*":
+            end = text.find("*/", i + 2)
+            if end == -1:
+                return -1
+            i = end + 1
+        elif c == "{":
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0:
+                return i
+        i += 1
+    return -1
+
+
+def _line_of(text: str, idx: int) -> int:
+    return text.count("\n", 0, idx) + 1
+
+
+def _body_range(clean: str, start_idx: int) -> Tuple[int, int]:
+    """(start, end) offsets of the function body starting at/after start_idx."""
+    brace = clean.find("{", start_idx)
+    arrow = clean.find("=>", start_idx)
+    if arrow != -1 and (brace == -1 or arrow < brace):
+        after = arrow + 2
+        b2 = clean.find("{", after)
+        nl = clean.find("\n", after)
+        if b2 != -1 and (nl == -1 or b2 < nl) and clean[after:b2].strip() == "":
+            end = _match_brace(clean, b2)
+            return (b2, end if end != -1 else min(len(clean), b2 + 400))
+        # expression-body arrow fn: body = rest of statement (approx one line)
+        end = nl if nl != -1 else len(clean)
+        return (after, end)
+    if brace == -1:
+        return (start_idx, min(len(clean), start_idx + 200))
+    end = _match_brace(clean, brace)
+    return (brace, end if end != -1 else min(len(clean), brace + 2000))
+
+
+def _extract_script(text: str) -> str:
+    """For .vue/.svelte: keep only <script> content, preserving line offsets."""
+    out_lines = [""] * (text.count("\n") + 1)
+    for m in re.finditer(r"<script[^>]*>([\s\S]*?)</script>", text,
+                         re.IGNORECASE):
+        start_line = text.count("\n", 0, m.start(1))
+        for i, line in enumerate(m.group(1).split("\n")):
+            if start_line + i < len(out_lines):
+                out_lines[start_line + i] = line
+    return "\n".join(out_lines)
+
+
+def _scan_body(raw_body: str, base_line: int, fn: FunctionInfo):
+    """Populate calls / api_calls / db_refs from a function body (raw text)."""
+    for m in RE_FETCH.finditer(raw_body):
+        window = raw_body[m.end():m.end() + 220]
+        mm = RE_FETCH_METHOD.search(window)
+        method = mm.group(1).upper() if mm else "GET"
+        fn.api_calls.append(ApiCall(method=method, url=m.group(1),
+                                    line=base_line + raw_body.count("\n", 0, m.start())))
+    for m in RE_AXIOS.finditer(raw_body):
+        fn.api_calls.append(ApiCall(method=m.group(1).upper(), url=m.group(2),
+                                    line=base_line + raw_body.count("\n", 0, m.start())))
+    for m in RE_AXIOS_OBJ.finditer(raw_body):
+        fn.api_calls.append(ApiCall(method="ANY", url=m.group(1),
+                                    line=base_line + raw_body.count("\n", 0, m.start())))
+    for m in RE_PRISMA.finditer(raw_body):
+        fn.db_refs.append(DbRef(table=m.group(1),
+                                op=OP_MAP.get(m.group(2).lower(), "query"),
+                                via="orm",
+                                line=base_line + raw_body.count("\n", 0, m.start())))
+    for m in RE_MODEL_OP.finditer(raw_body):
+        name = m.group(1)
+        if name in ("Object", "Array", "JSON", "Math", "Promise", "Date",
+                    "Number", "String", "Boolean", "Map", "Set", "Symbol",
+                    "Reflect", "Proxy", "RegExp", "Error", "Intl"):
+            continue
+        fn.db_refs.append(DbRef(table=name,
+                                op=OP_MAP.get(m.group(2).lower(), "query"),
+                                via="orm",
+                                line=base_line + raw_body.count("\n", 0, m.start())))
+    for m in RE_KNEX.finditer(raw_body):
+        fn.db_refs.append(DbRef(table=m.group(1), op="query", via="orm",
+                                line=base_line + raw_body.count("\n", 0, m.start())))
+    for m in RE_SQL.finditer(raw_body):
+        fn.db_refs.append(DbRef(table=m.group(2), op=m.group(1).lower(),
+                                via="sql",
+                                line=base_line + raw_body.count("\n", 0, m.start())))
+    clean_body = _strip_comments(raw_body)
+    seen = set(fn.calls)
+    for m in RE_CALL.finditer(clean_body):
+        name = m.group(1)
+        if name in JS_KEYWORDS or name == fn.name or name in seen:
+            continue
+        seen.add(name)
+        fn.calls.append(name)
+    # de-dup db refs
+    seen_db = set()
+    fn.db_refs = [d for d in fn.db_refs
+                  if not ((d.table, d.op) in seen_db or seen_db.add((d.table, d.op)))]
+
+
+def parse_javascript(info: FileInfo, text: str, language: str) -> None:
+    if language in ("vue", "svelte"):
+        text = _extract_script(text)
+    clean = _strip_comments(text)
+    covered: List[Tuple[int, int]] = []  # body ranges already owned by a fn
+
+    for m in RE_IMPORT.finditer(text):
+        info.imports.append(m.group(1))
+    info.imports = sorted(set(info.imports))
+
+    def add_function(name: str, params: str, decl_start: int,
+                     parent_class: str = ""):
+        body_start, body_end = _body_range(clean, decl_start)
+        fn = FunctionInfo(
+            name=name,
+            params=[p.strip() for p in params.split(",") if p.strip()],
+            line=_line_of(text, decl_start),
+            end_line=_line_of(text, min(body_end, len(text) - 1) if text else 0),
+            parent_class=parent_class,
+            kind="method" if parent_class else "function",
+        )
+        raw_body = text[body_start:body_end + 1]
+        _scan_body(raw_body, fn.line - 1 + text[decl_start:body_start].count("\n"),
+                   fn)
+        # routes attached via decorator on the preceding lines (NestJS)
+        prefix = text[max(0, decl_start - 200):decl_start]
+        nm = RE_NEST_ROUTE.search(prefix)
+        if nm:
+            fn.routes.append(Route(method=nm.group(1).upper(),
+                                   path="/" + (nm.group(2) or "").strip("/"),
+                                   line=fn.line))
+        fn.description = describe(fn, raw_body[:600])
+        info.functions.append(fn)
+        covered.append((decl_start, body_end))
+        return fn
+
+    # classes first (so methods get parent_class and aren't re-matched)
+    for cm in RE_CLASS.finditer(clean):
+        cls_name = cm.group(1)
+        brace = clean.find("{", cm.end())
+        if brace == -1:
+            continue
+        cend = _match_brace(clean, brace)
+        if cend == -1:
+            continue
+        # TypeORM @Entity above the class -> table definition
+        prefix = clean[max(0, cm.start() - 160):cm.start()]
+        em = RE_TYPEORM_ENTITY.search(prefix)
+        if em:
+            body_txt = text[brace:cend]
+            cols = re.findall(r"@(?:Primary\w*Column|Column|OneToMany|"
+                              r"ManyToOne|ManyToMany|OneToOne)[^\n]*\n\s*"
+                              r"([A-Za-z_$][\w$]*)", body_txt)
+            info.tables.append(TableInfo(name=em.group(1) or cls_name.lower(),
+                                         model=cls_name, fields=cols,
+                                         line=_line_of(text, cm.start()),
+                                         source=info.path))
+        for mm in RE_METHOD.finditer(clean[brace:cend]):
+            name = mm.group(1)
+            if name in JS_KEYWORDS:
+                continue
+            add_function(name, mm.group(2), brace + mm.start(), cls_name)
+        covered.append((cm.start(), cend))
+
+    def in_class(idx: int) -> bool:
+        return any(s <= idx <= e for s, e in covered)
+
+    for m in RE_FUNC_DECL.finditer(clean):
+        if not in_class(m.start()):
+            add_function(m.group(1), m.group(2), m.start())
+    for m in RE_ARROW.finditer(clean):
+        if not in_class(m.start()):
+            add_function(m.group(1), m.group(2) or m.group(3) or "", m.start())
+
+    # route definitions (Express-style) — attach to enclosing fn or file level
+    for m in RE_ROUTE.finditer(clean):
+        route = Route(method=m.group(1).upper(),
+                      path=m.group(2),
+                      line=_line_of(text, m.start()),
+                      handler=(m.group(3) or "").split(".")[-1])
+        owner = None
+        for fn in info.functions:
+            if fn.line <= route.line <= max(fn.end_line, fn.line):
+                if owner is None or fn.line > owner.line:
+                    owner = fn
+        if owner is not None and not route.handler:
+            owner.routes.append(route)
+        else:
+            info.routes.append(route)
+
+    # DB model definitions at file level
+    for m in RE_MONGOOSE.finditer(clean):
+        fields: List[str] = []
+        sm = RE_MONGOOSE_SCHEMA.search(clean)
+        if sm:
+            fields = re.findall(r"([A-Za-z_$][\w$]*)\s*:", sm.group(1))[:20]
+        info.tables.append(TableInfo(name=m.group(1).lower(), model=m.group(1),
+                                     fields=fields,
+                                     line=_line_of(text, m.start()),
+                                     source=info.path))
+    for m in RE_SEQUELIZE.finditer(clean):
+        info.tables.append(TableInfo(name=m.group(1), model=m.group(1),
+                                     line=_line_of(text, m.start()),
+                                     source=info.path))
+
+    # file-level API calls (outside any extracted function)
+    def outside_functions(line: int) -> bool:
+        return not any(f.line <= line <= max(f.end_line, f.line)
+                       for f in info.functions)
+
+    for m in RE_FETCH.finditer(text):
+        line = _line_of(text, m.start())
+        if outside_functions(line):
+            info.api_calls.append(ApiCall(method="GET", url=m.group(1),
+                                          line=line))
+    for m in RE_AXIOS.finditer(text):
+        line = _line_of(text, m.start())
+        if outside_functions(line):
+            info.api_calls.append(ApiCall(method=m.group(1).upper(),
+                                          url=m.group(2), line=line))
+
+    # module-level calls (top-level script code outside any function)
+    seen_top = set()
+    for m in RE_CALL.finditer(clean):
+        name = m.group(1)
+        if name in JS_KEYWORDS or name in seen_top:
+            continue
+        if outside_functions(_line_of(text, m.start())):
+            seen_top.add(name)
+            info.calls.append(name)
+    info.calls = info.calls[:40]

codebread/parsers/python_parser.py

@@ -0,0 +1,291 @@
+"""Python extractor built on the stdlib `ast` module.
+
+Extracts functions/classes/methods with params + return annotations,
+call targets, Flask/FastAPI/Django routes, outgoing HTTP calls
+(requests/httpx/aiohttp/urllib), ORM models (SQLAlchemy/Django/peewee/
+tortoise) and raw SQL usage.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from typing import List, Optional
+
+from ..models import (ApiCall, DbRef, FileInfo, FunctionInfo, Route,
+                      TableInfo, describe)
+
+HTTP_VERBS = {"get", "post", "put", "delete", "patch", "head", "options"}
+ROUTE_ATTRS = HTTP_VERBS | {"route", "api_route", "websocket"}
+ROUTE_OWNERS = {"app", "router", "api", "bp", "blueprint", "urlpatterns"}
+HTTP_LIBS = {"requests", "httpx", "aiohttp", "session", "client", "urllib3"}
+ORM_BASES = {"model", "base", "document", "declarativebase", "basemodel_db"}
+SQL_RE = re.compile(
+    r"\b(SELECT|INSERT|UPDATE|DELETE)\b[\s\S]{0,200}?\b(?:FROM|INTO|UPDATE|JOIN)\s+"
+    r"[`\"\[]?([A-Za-z_][A-Za-z0-9_.]*)", re.IGNORECASE)
+FIELD_CALL_RE = re.compile(r"(Column|Field)$", re.IGNORECASE)
+
+
+def _unparse(node) -> str:
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def _name_of(func) -> str:
+    """Dotted name of a call target, e.g. requests.get -> 'requests.get'."""
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        base = _name_of(func.value)
+        return f"{base}.{func.attr}" if base else func.attr
+    if isinstance(func, ast.Call):
+        return _name_of(func.func)
+    return ""
+
+
+def _str_arg(call: ast.Call) -> str:
+    for a in call.args:
+        if isinstance(a, ast.Constant) and isinstance(a.value, str):
+            return a.value
+        if isinstance(a, ast.JoinedStr):  # f-string url
+            parts = []
+            for v in a.values:
+                if isinstance(v, ast.Constant):
+                    parts.append(str(v.value))
+                else:
+                    parts.append("{param}")
+            return "".join(parts)
+    return ""
+
+
+def _params(node) -> List[str]:
+    out = []
+    args = node.args
+    for a in list(args.posonlyargs) + list(args.args) + list(args.kwonlyargs):
+        p = a.arg
+        if a.annotation is not None:
+            ann = _unparse(a.annotation)
+            if ann:
+                p += f": {ann}"
+        out.append(p)
+    if args.vararg:
+        out.append("*" + args.vararg.arg)
+    if args.kwarg:
+        out.append("**" + args.kwarg.arg)
+    return [p for p in out if p not in ("self", "cls")]
+
+
+def _route_from_decorator(dec) -> Optional[Route]:
+    if not isinstance(dec, ast.Call):
+        return None
+    name = _name_of(dec.func)
+    if "." not in name:
+        return None
+    owner, attr = name.rsplit(".", 1)
+    owner_base = owner.split(".")[-1].lower()
+    if attr.lower() not in ROUTE_ATTRS:
+        return None
+    if owner_base not in ROUTE_OWNERS and not owner_base.endswith("router"):
+        return None
+    path = _str_arg(dec)
+    if not path:
+        return None
+    method = attr.upper() if attr.lower() in HTTP_VERBS else "ANY"
+    # Flask: @app.route('/x', methods=['GET','POST'])
+    for kw in dec.keywords:
+        if kw.arg == "methods" and isinstance(kw.value, (ast.List, ast.Tuple)):
+            ms = [e.value for e in kw.value.elts
+                  if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+            if ms:
+                method = "/".join(m.upper() for m in ms)
+    return Route(method=method, path=path, line=dec.lineno)
+
+
+def _scan_calls(node, fn: FunctionInfo, source_seg: str):
+    """Collect callee names, HTTP calls, and DB touches inside a function."""
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Call):
+            dotted = _name_of(sub.func)
+            if not dotted:
+                continue
+            head = dotted.split(".")[0]
+            tail = dotted.split(".")[-1]
+            low_head, low_tail = head.lower(), tail.lower()
+
+            # outgoing HTTP call: requests.get(url), httpx.post(...)
+            if low_tail in HTTP_VERBS and low_head in HTTP_LIBS:
+                url = _str_arg(sub)
+                if url:
+                    fn.api_calls.append(ApiCall(method=tail.upper(), url=url,
+                                                line=sub.lineno))
+                continue
+            if dotted in ("urllib.request.urlopen", "urlopen"):
+                url = _str_arg(sub)
+                if url:
+                    fn.api_calls.append(ApiCall(method="GET", url=url,
+                                                line=sub.lineno))
+                continue
+
+            # ORM usage: session.query(User), User.objects.filter(...),
+            # db.session.add(user), Model.select() ...
+            if low_tail == "query" and sub.args:
+                model = _name_of(sub.args[0].func if isinstance(sub.args[0], ast.Call)
+                                 else sub.args[0])
+                if model and model[0].isupper():
+                    fn.db_refs.append(DbRef(table=model, op="query",
+                                            via="orm", line=sub.lineno))
+            elif ".objects." in dotted:
+                model = dotted.split(".objects.")[0].split(".")[-1]
+                op = {"create": "insert", "update": "update",
+                      "delete": "delete"}.get(low_tail, "query")
+                if model and model[0].isupper():
+                    fn.db_refs.append(DbRef(table=model, op=op,
+                                            via="orm", line=sub.lineno))
+            elif low_tail in ("execute", "executemany", "read_sql",
+                              "read_sql_query"):
+                sql = _str_arg(sub)
+                m = SQL_RE.search(sql or "")
+                if m:
+                    fn.db_refs.append(DbRef(table=m.group(2),
+                                            op=m.group(1).lower(),
+                                            via="sql", line=sub.lineno))
+
+            # record the plain callee name for the call graph
+            if head and head not in ("self", "cls"):
+                fn.calls.append(head if "." not in dotted else tail)
+            else:
+                fn.calls.append(tail)
+
+        # raw SQL sitting in a string constant
+        elif isinstance(sub, ast.Constant) and isinstance(sub.value, str):
+            if len(sub.value) > 12:
+                m = SQL_RE.search(sub.value)
+                if m:
+                    fn.db_refs.append(DbRef(table=m.group(2),
+                                            op=m.group(1).lower(),
+                                            via="sql",
+                                            line=getattr(sub, "lineno", fn.line)))
+    # de-dup while keeping order
+    seen = set()
+    fn.calls = [c for c in fn.calls
+                if c and not (c in seen or seen.add(c))]
+    seen_db = set()
+    fn.db_refs = [d for d in fn.db_refs
+                  if not ((d.table, d.op) in seen_db or seen_db.add((d.table, d.op)))]
+
+
+def _make_function(node, source: str, parent_class: str = "") -> FunctionInfo:
+    fn = FunctionInfo(
+        name=node.name,
+        params=_params(node),
+        returns=_unparse(node.returns) if node.returns else "",
+        line=node.lineno,
+        end_line=getattr(node, "end_lineno", node.lineno) or node.lineno,
+        doc=ast.get_docstring(node) or "",
+        parent_class=parent_class,
+        kind="method" if parent_class else "function",
+    )
+    for dec in node.decorator_list:
+        r = _route_from_decorator(dec)
+        if r:
+            fn.routes.append(r)
+    _scan_calls(node, fn, source)
+    try:
+        seg = ast.get_source_segment(source, node) or ""
+    except Exception:
+        seg = ""
+    fn.description = describe(fn, seg)
+    return fn
+
+
+def _model_from_class(node: ast.ClassDef) -> Optional[TableInfo]:
+    """SQLAlchemy / Django / peewee / tortoise model -> TableInfo."""
+    base_names = []
+    for b in node.bases:
+        base_names.append(_name_of(b).split(".")[-1].lower())
+    is_model = any(b in ORM_BASES or b.endswith("model") for b in base_names)
+    if not is_model:
+        return None
+    table = node.name.lower()
+    fields: List[str] = []
+    for item in node.body:
+        if isinstance(item, ast.Assign):
+            targets = [t.id for t in item.targets if isinstance(t, ast.Name)]
+            if targets and targets[0] == "__tablename__" and \
+                    isinstance(item.value, ast.Constant):
+                table = str(item.value.value)
+                continue
+            if targets and isinstance(item.value, ast.Call):
+                callee = _name_of(item.value.func).split(".")[-1]
+                if FIELD_CALL_RE.search(callee) or callee in (
+                        "relationship", "ForeignKey", "ManyToManyField"):
+                    fields.append(targets[0])
+        elif isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+            fields.append(item.target.id)
+    return TableInfo(name=table, model=node.name, fields=fields,
+                     line=node.lineno)
+
+
+def parse_python(info: FileInfo, text: str) -> None:
+    try:
+        tree = ast.parse(text)
+    except SyntaxError as exc:
+        info.warnings.append(f"Python syntax error at line {exc.lineno}: "
+                             f"{exc.msg} — file skipped.")
+        return
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            if isinstance(node, ast.Import):
+                info.imports.extend(a.name for a in node.names)
+            elif node.module:
+                info.imports.append(node.module)
+
+    def visit_body(body, parent_class=""):
+        for node in body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                info.functions.append(_make_function(node, text, parent_class))
+                # nested defs
+                inner = [n for n in node.body
+                         if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
+                if inner:
+                    visit_body(inner, parent_class)
+            elif isinstance(node, ast.ClassDef):
+                model = _model_from_class(node)
+                if model:
+                    model.source = info.path
+                    info.tables.append(model)
+                visit_body(node.body, parent_class=node.name)
+
+    visit_body(tree.body)
+
+    # Django urls.py: path('users/', views.user_list) -> route + handler name
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            callee = _name_of(node.func).split(".")[-1]
+            if callee in ("path", "re_path", "url") and len(node.args) >= 2:
+                p = _str_arg(node)
+                handler = _name_of(node.args[1]).split(".")[-1]
+                if p and handler:
+                    info.routes.append(Route(method="ANY", path="/" + p.strip("/"),
+                                             line=node.lineno, handler=handler))
+
+    # module-level calls (script-style code outside any def)
+    fn_ranges = [(f.line, max(f.end_line, f.line)) for f in info.functions]
+    seen_top = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        line = getattr(node, "lineno", 0)
+        if any(s <= line <= e for s, e in fn_ranges):
+            continue
+        dotted = _name_of(node.func)
+        name = dotted.split(".")[0] if "." not in dotted else \
+            dotted.split(".")[-1]
+        if name and name not in seen_top:
+            seen_top.add(name)
+            info.calls.append(name)
+    info.calls = info.calls[:40]
+
+    info.imports = sorted(set(info.imports))