django-orm-lens 1.0.0__py3-none-any.whl

django_orm_lens/__init__.py

@@ -0,0 +1,20 @@
+"""Django ORM Lens — sidebar tree, ER diagrams, and JSON for Django models.
+
+Terminal / editor-agnostic parser for Django models.py files.
+Ships a CLI and an optional MCP server for AI coding agents.
+"""
+
+__version__ = "1.0.0"
+
+from .models import ParsedApp, ParsedField, ParsedModel, WorkspaceIndex
+from .parser import parse_models_file, scan_workspace
+
+__all__ = [
+    "ParsedApp",
+    "ParsedField",
+    "ParsedModel",
+    "WorkspaceIndex",
+    "parse_models_file",
+    "scan_workspace",
+    "__version__",
+]

django_orm_lens/cli.py

@@ -0,0 +1,238 @@
+"""Command-line entry point for ``django-orm-lens``.
+
+Zero-dep argparse CLI. Commands mirror what the VS Code extension does:
+
+  django-orm-lens scan       — walk workspace, list every model
+  django-orm-lens describe   — one model in detail
+  django-orm-lens er         — Mermaid ER diagram (stdout or file)
+  django-orm-lens hover      — compact hover card for one model
+  django-orm-lens list       — flat list ``app.Model`` for shell piping
+  django-orm-lens mcp        — start the MCP stdio server (extras required)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .formatters import format_hover, format_index, format_model
+from .models import ParsedModel, WorkspaceIndex
+from .parser import DEFAULT_EXCLUDES, scan_workspace
+
+
+def _add_scan_flags(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--path",
+        "-p",
+        default=".",
+        help="Workspace root to scan (default: current directory)",
+    )
+    p.add_argument(
+        "--exclude",
+        "-x",
+        action="append",
+        default=None,
+        help="Glob to exclude, repeatable (default: migrations/, venv/, node_modules/)",
+    )
+
+
+def _resolve_excludes(cli_excludes: Optional[Sequence[str]]) -> Sequence[str]:
+    return tuple(cli_excludes) if cli_excludes else DEFAULT_EXCLUDES
+
+
+def _find_model(index: WorkspaceIndex, ref: str) -> Optional[ParsedModel]:
+    if "." in ref:
+        app_name, model_name = ref.split(".", 1)
+        for app in index.apps:
+            if app.name == app_name:
+                for m in app.models:
+                    if m.name == model_name:
+                        return m
+    for app in index.apps:
+        for m in app.models:
+            if m.name == ref:
+                return m
+    return None
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    print(format_index(idx, args.format))
+    return 0
+
+
+def _cmd_describe(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    model = _find_model(idx, args.model)
+    if model is None:
+        print(f"error: model {args.model!r} not found", file=sys.stderr)
+        return 2
+    print(format_model(model, args.format))
+    return 0
+
+
+def _cmd_hover(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    model = _find_model(idx, args.model)
+    if model is None:
+        print(f"error: model {args.model!r} not found", file=sys.stderr)
+        return 2
+    print(format_hover(model))
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    for app in idx.apps:
+        for m in app.models:
+            print(f"{app.name}.{m.name}")
+    return 0
+
+
+def _cmd_er(args: argparse.Namespace) -> int:
+    idx = scan_workspace(args.path, _resolve_excludes(args.exclude))
+    mermaid = _build_mermaid(idx)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(mermaid)
+        print(f"Wrote {args.output}", file=sys.stderr)
+    else:
+        print(mermaid)
+    return 0
+
+
+def _build_mermaid(index: WorkspaceIndex) -> str:
+    lines: List[str] = ["erDiagram"]
+    model_names = {m.name for app in index.apps for m in app.models}
+
+    def safe(s: str) -> str:
+        return "".join(ch if (ch.isalnum() or ch == "_") else "_" for ch in s)
+
+    for app in index.apps:
+        for model in app.models:
+            lines.append(f"  {safe(model.name)} {{")
+            for f in model.fields:
+                if f.is_relation:
+                    continue
+                type_safe = "".join(ch for ch in f.type if ch.isalnum())
+                name_safe = safe(f.name)
+                lines.append(f"    {type_safe} {name_safe}")
+            lines.append("  }")
+
+    for app in index.apps:
+        for model in app.models:
+            for f in model.fields:
+                if not f.is_relation or not f.related_model:
+                    continue
+                target = (
+                    model.name
+                    if f.related_model == "self"
+                    else f.related_model.split(".")[-1]
+                )
+                if target not in model_names:
+                    continue
+                if f.relation_kind == "ManyToManyField":
+                    arrow = "}o--o{"
+                elif f.relation_kind == "OneToOneField":
+                    arrow = "||--||"
+                else:
+                    arrow = "}o--||"
+                lines.append(
+                    f'  {safe(model.name)} {arrow} {safe(target)} : "{f.name}"'
+                )
+    return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="django-orm-lens",
+        description="Static analysis for Django models. Terminal + AI agent friendly.",
+    )
+    p.add_argument(
+        "--version", action="version", version=f"django-orm-lens {__version__}"
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="Scan a workspace for Django models")
+    _add_scan_flags(scan)
+    scan.add_argument(
+        "--format", "-f", choices=("json", "markdown", "table"), default="json"
+    )
+    scan.set_defaults(func=_cmd_scan)
+
+    describe = sub.add_parser(
+        "describe", help="Describe a single model (app.Model or Model)"
+    )
+    _add_scan_flags(describe)
+    describe.add_argument("model", help="Model reference, e.g. blog.Post or Post")
+    describe.add_argument(
+        "--format", "-f", choices=("json", "markdown", "table"), default="markdown"
+    )
+    describe.set_defaults(func=_cmd_describe)
+
+    hover = sub.add_parser("hover", help="Compact hover-card markdown for a model")
+    _add_scan_flags(hover)
+    hover.add_argument("model", help="Model reference, e.g. blog.Post or Post")
+    hover.set_defaults(func=_cmd_hover)
+
+    lst = sub.add_parser("list", help="Flat list of app.Model — pipes well into shell")
+    _add_scan_flags(lst)
+    lst.set_defaults(func=_cmd_list)
+
+    er = sub.add_parser("er", help="Emit a Mermaid ER diagram (stdout or file)")
+    _add_scan_flags(er)
+    er.add_argument(
+        "--output", "-o", default=None, help="Write diagram to file instead of stdout"
+    )
+    er.set_defaults(func=_cmd_er)
+
+    mcp = sub.add_parser(
+        "mcp",
+        help="Run the MCP stdio server (requires 'pip install django-orm-lens[mcp]')",
+    )
+    mcp.set_defaults(func=_cmd_mcp)
+
+    return p
+
+
+def _cmd_mcp(_args: argparse.Namespace) -> int:
+    try:
+        from . import mcp_server
+    except ImportError as e:
+        print(
+            "error: MCP server dependencies not installed.\n"
+            "install with: pip install 'django-orm-lens[mcp]'\n"
+            f"({e})",
+            file=sys.stderr,
+        )
+        return 3
+    return mcp_server.main()
+
+
+def _force_utf8_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (OSError, ValueError):
+                pass
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    _force_utf8_stdio()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

django_orm_lens/formatters.py

@@ -0,0 +1,158 @@
+"""Output formatters for the CLI and MCP server.
+
+Renders a :class:`WorkspaceIndex` (or a single :class:`ParsedModel`) as JSON,
+GitHub-flavoured Markdown, or a plain ASCII table. Zero third-party deps.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import List
+
+from .models import ParsedModel, WorkspaceIndex
+
+
+def format_index(index: WorkspaceIndex, fmt: str = "json") -> str:
+    fmt = fmt.lower()
+    if fmt == "json":
+        return json.dumps(index.to_dict(), indent=2, ensure_ascii=False)
+    if fmt == "markdown":
+        return _index_markdown(index)
+    if fmt == "table":
+        return _index_table(index)
+    raise ValueError(f"Unknown format: {fmt!r}. Use json | markdown | table.")
+
+
+def format_model(model: ParsedModel, fmt: str = "markdown") -> str:
+    fmt = fmt.lower()
+    if fmt == "json":
+        return json.dumps(model.to_dict(), indent=2, ensure_ascii=False)
+    if fmt == "markdown":
+        return _model_markdown(model)
+    if fmt == "table":
+        return _model_table(model)
+    raise ValueError(f"Unknown format: {fmt!r}. Use json | markdown | table.")
+
+
+def format_hover(model: ParsedModel) -> str:
+    """Compact hover-card markdown — identical spirit to the VS Code hover."""
+    lines: List[str] = []
+    bases = ", ".join(model.base_classes) or "models.Model"
+    lines.append(f"**{model.app_name}.{model.name}**")
+    lines.append(f"_{bases}_")
+    scalars = [f for f in model.fields if not f.is_relation]
+    relations = [f for f in model.fields if f.is_relation]
+    if scalars:
+        lines.append("")
+        lines.append("**Fields**")
+        for f in scalars[:12]:
+            lines.append(f"- `{f.name}` — {f.type}")
+        if len(scalars) > 12:
+            lines.append(f"- _…and {len(scalars) - 12} more_")
+    if relations:
+        lines.append("")
+        lines.append("**Relations**")
+        for f in relations:
+            lines.append(
+                f"- `{f.name}` → **{f.related_model or '?'}** _({f.relation_kind})_"
+            )
+    return "\n".join(lines)
+
+
+def _index_markdown(index: WorkspaceIndex) -> str:
+    if not index.apps:
+        return "_No Django models found._"
+    out: List[str] = ["# Django models\n"]
+    for app in index.apps:
+        out.append(
+            f"## {app.name} ({len(app.models)} model{'s' if len(app.models) != 1 else ''})"
+        )
+        for m in app.models:
+            out.append(_model_markdown(m))
+            out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _model_markdown(model: ParsedModel) -> str:
+    bases = ", ".join(model.base_classes) or "models.Model"
+    rows = [
+        f"### `{model.app_name}.{model.name}`",
+        f"_class {model.name}({bases})_",
+        f"`{model.file_path}:{model.line_number + 1}`",
+    ]
+    scalars = [f for f in model.fields if not f.is_relation]
+    relations = [f for f in model.fields if f.is_relation]
+    if scalars:
+        rows.append("\n**Fields**\n")
+        rows.append("| Field | Type | Args |")
+        rows.append("| --- | --- | --- |")
+        for f in scalars:
+            args = _truncate(f.args, 60).replace("|", r"\|")
+            rows.append(f"| `{f.name}` | {f.type} | `{args}` |")
+    if relations:
+        rows.append("\n**Relations**\n")
+        rows.append("| Field | Kind | Target |")
+        rows.append("| --- | --- | --- |")
+        for f in relations:
+            rows.append(
+                f"| `{f.name}` | {f.relation_kind} | **{f.related_model or '?'}** |"
+            )
+    if model.meta:
+        rows.append("\n**Meta**\n")
+        for k, v in model.meta.items():
+            rows.append(f"- `{k}` = {_truncate(v, 80)}")
+    return "\n".join(rows)
+
+
+def _index_table(index: WorkspaceIndex) -> str:
+    header = ("App", "Model", "Fields", "Rels", "File")
+    rows: List[tuple] = []
+    for app in index.apps:
+        for m in app.models:
+            scalars = sum(1 for f in m.fields if not f.is_relation)
+            rels = sum(1 for f in m.fields if f.is_relation)
+            rows.append(
+                (
+                    app.name,
+                    m.name,
+                    str(scalars),
+                    str(rels),
+                    f"{m.file_path}:{m.line_number + 1}",
+                )
+            )
+    return _render_table(header, rows)
+
+
+def _model_table(model: ParsedModel) -> str:
+    header = ("Field", "Type", "Rel", "Target")
+    rows: List[tuple] = []
+    for f in model.fields:
+        rows.append(
+            (
+                f.name,
+                f.type,
+                "yes" if f.is_relation else "",
+                f.related_model or "",
+            )
+        )
+    top = f"{model.app_name}.{model.name}  ({model.file_path}:{model.line_number + 1})\n"
+    return top + _render_table(header, rows)
+
+
+def _render_table(header: tuple, rows: List[tuple]) -> str:
+    all_rows = [header] + rows
+    widths = [max(len(str(r[i])) for r in all_rows) for i in range(len(header))]
+    sep = "  "
+
+    def fmt(r):
+        return sep.join(str(v).ljust(widths[i]) for i, v in enumerate(r))
+
+    lines = [fmt(header), sep.join("-" * w for w in widths)]
+    for r in rows:
+        lines.append(fmt(r))
+    return "\n".join(lines)
+
+
+def _truncate(s: str, n: int) -> str:
+    s = s.replace("\n", " ").strip()
+    return s if len(s) <= n else s[: n - 1] + "…"

django_orm_lens/mcp_server.py

@@ -0,0 +1,188 @@
+"""MCP (Model Context Protocol) stdio server for Django ORM Lens.
+
+Exposes five read-only tools that any MCP-compatible AI agent can call:
+
+* ``list_apps``       — list Django apps with model counts
+* ``list_models``    — flat ``app.Model`` list, optional app filter
+* ``describe_model`` — full field/relation/Meta detail for one model
+* ``find_relations`` — inbound + outbound relations for one model
+* ``er_diagram``     — Mermaid ER diagram string for the whole workspace
+
+The ``mcp`` runtime package is loaded lazily so ``pip install django-orm-lens``
+stays zero-dep. Install with the extras: ``pip install 'django-orm-lens[mcp]'``.
+
+Config: workspace root taken from ``$DJANGO_ORM_LENS_ROOT`` if set, else ``cwd``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Dict, List
+
+from .cli import _build_mermaid
+from .parser import DEFAULT_EXCLUDES, scan_workspace
+
+
+def _workspace_root() -> str:
+    return os.environ.get("DJANGO_ORM_LENS_ROOT") or os.getcwd()
+
+
+def _tool_list_apps(_args: Dict[str, Any]) -> str:
+    idx = scan_workspace(_workspace_root(), DEFAULT_EXCLUDES)
+    return json.dumps(
+        [
+            {"name": a.name, "path": a.path, "models": len(a.models)}
+            for a in idx.apps
+        ],
+        indent=2,
+    )
+
+
+def _tool_list_models(args: Dict[str, Any]) -> str:
+    idx = scan_workspace(_workspace_root(), DEFAULT_EXCLUDES)
+    only_app = (args or {}).get("app")
+    rows: List[str] = []
+    for app in idx.apps:
+        if only_app and app.name != only_app:
+            continue
+        for m in app.models:
+            rows.append(f"{app.name}.{m.name}")
+    return "\n".join(rows) if rows else "(no models)"
+
+
+def _find(idx, ref: str):
+    if "." in ref:
+        an, mn = ref.split(".", 1)
+        for app in idx.apps:
+            if app.name == an:
+                for m in app.models:
+                    if m.name == mn:
+                        return m
+    for app in idx.apps:
+        for m in app.models:
+            if m.name == ref:
+                return m
+    return None
+
+
+def _tool_describe_model(args: Dict[str, Any]) -> str:
+    idx = scan_workspace(_workspace_root(), DEFAULT_EXCLUDES)
+    ref = (args or {}).get("model", "")
+    m = _find(idx, ref)
+    if not m:
+        return f"error: model {ref!r} not found"
+    return json.dumps(m.to_dict(), indent=2)
+
+
+def _tool_find_relations(args: Dict[str, Any]) -> str:
+    idx = scan_workspace(_workspace_root(), DEFAULT_EXCLUDES)
+    ref = (args or {}).get("model", "")
+    m = _find(idx, ref)
+    if not m:
+        return f"error: model {ref!r} not found"
+    out: Dict[str, Any] = {"outbound": [], "inbound": []}
+    for f in m.fields:
+        if f.is_relation:
+            out["outbound"].append(
+                {
+                    "field": f.name,
+                    "kind": f.relation_kind,
+                    "target": f.related_model,
+                }
+            )
+    tail = m.name
+    for app in idx.apps:
+        for other in app.models:
+            if other is m:
+                continue
+            for f in other.fields:
+                if not f.is_relation or not f.related_model:
+                    continue
+                t = f.related_model.split(".")[-1]
+                if t == tail:
+                    out["inbound"].append(
+                        {
+                            "from": f"{app.name}.{other.name}",
+                            "field": f.name,
+                            "kind": f.relation_kind,
+                        }
+                    )
+    return json.dumps(out, indent=2)
+
+
+def _tool_er_diagram(_args: Dict[str, Any]) -> str:
+    idx = scan_workspace(_workspace_root(), DEFAULT_EXCLUDES)
+    return _build_mermaid(idx)
+
+
+TOOLS = {
+    "list_apps": {
+        "handler": _tool_list_apps,
+        "description": "List every Django app in the workspace with model counts.",
+    },
+    "list_models": {
+        "handler": _tool_list_models,
+        "description": "Flat list of app.Model. Optional 'app' filter.",
+    },
+    "describe_model": {
+        "handler": _tool_describe_model,
+        "description": "Full JSON detail for one model: fields, relations, Meta, base classes, file path.",
+    },
+    "find_relations": {
+        "handler": _tool_find_relations,
+        "description": "Outbound (this model → others) and inbound (others → this) relations.",
+    },
+    "er_diagram": {
+        "handler": _tool_er_diagram,
+        "description": "Emit a Mermaid erDiagram for the whole workspace.",
+    },
+}
+
+
+def main() -> int:
+    """Start the MCP stdio server. Lazy-imports the ``mcp`` package."""
+    try:
+        from mcp.server.fastmcp import FastMCP  # type: ignore
+    except ImportError:
+        print(
+            "django-orm-lens MCP requires the 'mcp' package.\n"
+            "install with: pip install 'django-orm-lens[mcp]'",
+            file=sys.stderr,
+        )
+        return 3
+
+    server = FastMCP("django-orm-lens")
+
+    def _register(name: str, description: str, handler):
+        if name == "list_apps":
+            @server.tool(name=name, description=description)
+            def list_apps() -> str:
+                return handler({})
+        elif name == "list_models":
+            @server.tool(name=name, description=description)
+            def list_models(app: str = "") -> str:
+                return handler({"app": app} if app else {})
+        elif name == "describe_model":
+            @server.tool(name=name, description=description)
+            def describe_model(model: str) -> str:
+                return handler({"model": model})
+        elif name == "find_relations":
+            @server.tool(name=name, description=description)
+            def find_relations(model: str) -> str:
+                return handler({"model": model})
+        elif name == "er_diagram":
+            @server.tool(name=name, description=description)
+            def er_diagram() -> str:
+                return handler({})
+
+    for name, spec in TOOLS.items():
+        _register(name, spec["description"], spec["handler"])
+
+    server.run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

django_orm_lens/models.py

@@ -0,0 +1,88 @@
+"""Data classes for parsed Django models.
+
+Mirrors the TypeScript ``types.ts`` shape so the CLI and the VS Code
+extension emit the same camelCase JSON schema.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Literal, Optional
+
+RelationKind = Literal["ForeignKey", "ManyToManyField", "OneToOneField"]
+
+
+@dataclass
+class ParsedField:
+    name: str
+    type: str
+    args: str
+    is_relation: bool
+    line_number: int
+    related_model: Optional[str] = None
+    relation_kind: Optional[RelationKind] = None
+
+    def to_dict(self) -> dict:
+        out = {
+            "name": self.name,
+            "type": self.type,
+            "args": self.args,
+            "isRelation": self.is_relation,
+            "lineNumber": self.line_number,
+        }
+        if self.related_model is not None:
+            out["relatedModel"] = self.related_model
+        if self.relation_kind is not None:
+            out["relationKind"] = self.relation_kind
+        return out
+
+
+@dataclass
+class ParsedModel:
+    name: str
+    app_name: str
+    file_path: str
+    line_number: int
+    base_classes: List[str]
+    fields: List[ParsedField] = field(default_factory=list)
+    meta: Dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "appName": self.app_name,
+            "filePath": self.file_path,
+            "lineNumber": self.line_number,
+            "baseClasses": list(self.base_classes),
+            "fields": [f.to_dict() for f in self.fields],
+            "meta": dict(self.meta),
+        }
+
+
+@dataclass
+class ParsedApp:
+    name: str
+    path: str
+    models: List[ParsedModel] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "path": self.path,
+            "models": [m.to_dict() for m in self.models],
+        }
+
+
+@dataclass
+class WorkspaceIndex:
+    apps: List[ParsedApp] = field(default_factory=list)
+    scanned_at: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "apps": [a.to_dict() for a in self.apps],
+            "scannedAt": self.scanned_at,
+        }
+
+    def total_models(self) -> int:
+        return sum(len(a.models) for a in self.apps)

django_orm_lens/parser.py

@@ -0,0 +1,314 @@
+"""Django models.py parser — Python port of the VS Code extension parser.
+
+Static regex-based parser. Zero third-party deps. Produces the same schema
+as the TypeScript ``src/parser.ts`` so tools can consume either interchangeably.
+
+Key semantics preserved from the TS parser:
+* multi-line ``class X(A, B):`` inheritance;
+* non-model class filter (``ModelAdmin`` / ``ModelForm`` / ``Serializer`` etc.);
+* per-class indent width detection (2/4/tab all work);
+* both ``models.CharField(...)`` and bare ``CharField(...)`` imports;
+* balanced-paren reader for multi-line field arg blocks;
+* first-arg extraction for FK/O2O/M2M ``related_model``;
+* ``class Meta:`` attribute capture.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Iterable, List, Sequence, Tuple
+
+from .models import (
+    ParsedApp,
+    ParsedField,
+    ParsedModel,
+    WorkspaceIndex,
+)
+
+RELATION_TYPES: Tuple[str, ...] = ("ForeignKey", "ManyToManyField", "OneToOneField")
+
+CLASS_RE = re.compile(r"^class\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)\s*:")
+CLASS_START_RE = re.compile(r"^class\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(")
+
+NON_MODEL_TAIL = re.compile(
+    r"^(ModelAdmin|ModelForm|ModelSerializer|ModelChoiceField|"
+    r"ModelMultipleChoiceField|Serializer|Form|Admin|View|ViewSet|"
+    r"Manager|QuerySet|Config|AppConfig|Response|Handler|Middleware|"
+    r"Backend|Command)$"
+)
+
+BARE_FIELD_TYPES = "|".join(
+    [
+        "CharField", "TextField", "SlugField", "EmailField", "URLField", "UUIDField",
+        "IntegerField", "BigIntegerField", "SmallIntegerField",
+        "PositiveIntegerField", "PositiveSmallIntegerField", "PositiveBigIntegerField",
+        "FloatField", "DecimalField",
+        "BooleanField", "NullBooleanField",
+        "DateTimeField", "DateField", "TimeField", "DurationField",
+        "JSONField", "BinaryField",
+        "FileField", "ImageField", "FilePathField",
+        "GenericIPAddressField",
+        "AutoField", "BigAutoField", "SmallAutoField",
+        "ForeignKey", "OneToOneField", "ManyToManyField",
+    ]
+)
+
+
+def _read_multiline_class(lines: Sequence[str], start: int):
+    buffer = lines[start]
+    depth = 0
+    saw_open = False
+    for i in range(start, len(lines)):
+        src = lines[i] if i == start else lines[i].lstrip()
+        for ch in src:
+            if ch == "(":
+                depth += 1
+                saw_open = True
+            elif ch == ")":
+                depth -= 1
+        if i > start:
+            buffer += " " + src
+        if saw_open and depth == 0:
+            m = CLASS_RE.match(buffer)
+            if m:
+                return m, i
+            return None
+    return None
+
+
+def _detect_class_indent(lines: Sequence[str], class_line_idx: int) -> int:
+    end = min(class_line_idx + 30, len(lines))
+    for i in range(class_line_idx + 1, end):
+        m = re.match(r"^([\t ]+)\S", lines[i])
+        if m:
+            return len(m.group(1))
+    return 4
+
+
+def _build_body_regexes(indent: int):
+    w = r"\s{" + str(indent) + r"}"
+    w2 = r"\s{" + str(indent * 2) + r"}"
+    return {
+        "FIELD_RE": re.compile(
+            rf"^{w}([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*models\.([A-Za-z_][A-Za-z0-9_]*)\s*\("
+        ),
+        "BARE_FIELD_RE": re.compile(
+            rf"^{w}([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*({BARE_FIELD_TYPES})\s*\("
+        ),
+        "META_START_RE": re.compile(rf"^{w}class\s+Meta\s*(?:\([^)]*\))?\s*:"),
+        "META_ITEM_RE": re.compile(
+            rf"^{w2}([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(.+?)\s*(#.*)?$"
+        ),
+        "META_BODY_RE": re.compile(r"^\s{" + str(indent * 2) + r",}"),
+    }
+
+
+def _extract_related(args_block: str):
+    stripped = args_block.strip()
+    m = re.match(
+        r"^(?:to\s*=\s*)?(?:'([^']+)'|\"([^\"]+)\"|([A-Za-z_][A-Za-z0-9_.]*))",
+        stripped,
+    )
+    if not m:
+        return None
+    raw = m.group(1) or m.group(2) or m.group(3)
+    if not raw:
+        return None
+    if raw == "self":
+        return "self"
+    return raw.strip("'\"")
+
+
+def _read_balanced_args(lines: Sequence[str], start: int):
+    open_idx = lines[start].index("(")
+    depth = 0
+    buf = ""
+    for i in range(start, len(lines)):
+        src = lines[i][open_idx:] if i == start else lines[i]
+        for ch in src:
+            if ch == "(":
+                depth += 1
+            elif ch == ")":
+                depth -= 1
+                if depth == 0:
+                    return (buf + ")").lstrip("("), i
+            buf += ch
+        buf += "\n"
+    return buf.lstrip("("), len(lines) - 1
+
+
+def _looks_like_model(base_classes: List[str]) -> bool:
+    for b in base_classes:
+        tail = b.split(".")[-1]
+        if NON_MODEL_TAIL.match(tail):
+            return False
+    for b in base_classes:
+        tail = b.split(".")[-1]
+        if NON_MODEL_TAIL.match(tail):
+            continue
+        if re.search(r"models\.Model$", b):
+            return True
+        if re.match(
+            r"^(Model|AbstractModel|AbstractBaseModel|TimeStampedModel|PolymorphicModel)$",
+            tail,
+        ):
+            return True
+        if re.match(r"^Abstract[A-Z]", tail):
+            return True
+        if re.search(r"Mixin$", tail):
+            return True
+    return False
+
+
+def parse_models_file(file_path: str, content: str) -> List[ParsedModel]:
+    """Parse a single models.py-style file. Returns 0..N Django model classes."""
+    lines = content.splitlines()
+    models: List[ParsedModel] = []
+    parent = os.path.basename(os.path.dirname(file_path))
+    if parent == "models":
+        app_name = os.path.basename(os.path.dirname(os.path.dirname(file_path)))
+    else:
+        app_name = parent or "app"
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        class_match = CLASS_RE.match(line)
+        class_header_end = i
+        if not class_match and CLASS_START_RE.match(line):
+            joined = _read_multiline_class(lines, i)
+            if joined:
+                class_match, class_header_end = joined
+        if not class_match:
+            i += 1
+            continue
+
+        model_name = class_match.group(1)
+        base_classes = [
+            s.strip() for s in class_match.group(2).split(",") if s.strip()
+        ]
+        if not _looks_like_model(base_classes):
+            i += 1
+            continue
+
+        model = ParsedModel(
+            name=model_name,
+            app_name=app_name,
+            file_path=file_path,
+            line_number=i,
+            base_classes=base_classes,
+        )
+
+        indent = _detect_class_indent(lines, class_header_end)
+        rx = _build_body_regexes(indent)
+
+        j = class_header_end + 1
+        while j < len(lines):
+            inner = lines[j]
+            if re.match(r"^class\s+", inner) and not re.match(r"^\s+class", inner):
+                break
+            if not inner.strip():
+                j += 1
+                continue
+
+            if rx["META_START_RE"].match(inner):
+                k = j + 1
+                while k < len(lines):
+                    ml = lines[k]
+                    if ml and not rx["META_BODY_RE"].match(ml) and ml.strip():
+                        break
+                    m2 = rx["META_ITEM_RE"].match(ml)
+                    if m2:
+                        model.meta[m2.group(1)] = m2.group(2).strip()
+                    k += 1
+                j = k
+                continue
+
+            fm = rx["FIELD_RE"].match(inner) or rx["BARE_FIELD_RE"].match(inner)
+            if fm:
+                fname, ftype = fm.group(1), fm.group(2)
+                args_block, end_idx = _read_balanced_args(lines, j)
+                is_rel = ftype in RELATION_TYPES
+                field = ParsedField(
+                    name=fname,
+                    type=ftype,
+                    args=args_block.rstrip(")").strip(),
+                    is_relation=is_rel,
+                    line_number=j,
+                )
+                if is_rel:
+                    field.relation_kind = ftype  # type: ignore[assignment]
+                    field.related_model = _extract_related(args_block.rstrip(")"))
+                model.fields.append(field)
+                j = end_idx + 1
+                continue
+
+            j += 1
+
+        models.append(model)
+        i = j
+
+    return models
+
+
+def _iter_python_files(root: Path, excludes: Sequence[str]) -> Iterable[Path]:
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+        for name in filenames:
+            if name == "models.py" or (
+                os.path.basename(dirpath) == "models"
+                and name.endswith(".py")
+                and name != "__init__.py"
+            ):
+                full = Path(dirpath) / name
+                rel_posix = full.relative_to(root).as_posix()
+                if any(fnmatch(rel_posix, pat) for pat in excludes):
+                    continue
+                yield full
+
+
+def _app_dir_for(fs_path: str) -> Tuple[str, str]:
+    parent = os.path.dirname(fs_path)
+    parent_name = os.path.basename(parent)
+    if parent_name == "models":
+        grand = os.path.dirname(parent)
+        return grand, os.path.basename(grand)
+    return parent, parent_name
+
+
+DEFAULT_EXCLUDES = (
+    "**/migrations/**",
+    "**/node_modules/**",
+    "**/venv/**",
+    "**/.venv/**",
+    "**/env/**",
+)
+
+
+def scan_workspace(
+    root: str, exclude_globs: Sequence[str] = DEFAULT_EXCLUDES
+) -> WorkspaceIndex:
+    """Walk ``root``, parse every ``models.py`` (or ``models/*.py``), return an index."""
+    root_path = Path(root).resolve()
+    apps: dict = {}
+    for py in _iter_python_files(root_path, exclude_globs):
+        try:
+            content = py.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        models = parse_models_file(str(py), content)
+        if not models:
+            continue
+        app_dir, app_name = _app_dir_for(str(py))
+        app = apps.get(app_dir)
+        if app is None:
+            app = ParsedApp(name=app_name, path=app_dir)
+            apps[app_dir] = app
+        app.models.extend(models)
+
+    sorted_apps = sorted(apps.values(), key=lambda a: a.name)
+    return WorkspaceIndex(apps=sorted_apps, scanned_at=int(time.time() * 1000))

django_orm_lens-1.0.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: django-orm-lens
+Version: 1.0.0
+Summary: Static analysis + MCP server for Django models. Sidebar tree, ER diagrams, and JSON output for terminals and AI coding agents.
+Author: frowningdev
+License: MIT
+Project-URL: Homepage, https://github.com/FROWNINGdev/django-orm-lens
+Project-URL: Repository, https://github.com/FROWNINGdev/django-orm-lens
+Project-URL: Bug Tracker, https://github.com/FROWNINGdev/django-orm-lens/issues
+Project-URL: Changelog, https://github.com/FROWNINGdev/django-orm-lens/blob/main/CHANGELOG.md
+Project-URL: VS Code Marketplace, https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens
+Keywords: django,orm,models,er-diagram,mermaid,mcp,ai-agents,cursor,aider,code-analysis,static-analysis
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+
+# django-orm-lens
+
+**Static analysis + MCP server for Django models.** Terminal- and AI-agent-friendly.
+
+Ships with a zero-dependency parser, a JSON/Markdown/table CLI, and an optional
+MCP (Model Context Protocol) server so any AI coding agent — Cursor, Aider,
+Continue, and any other MCP client — can navigate your Django schema without
+importing Django or spinning up your app.
+
+Companion to the [Django ORM Lens VS Code
+extension](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens).
+
+---
+
+## Install
+
+```bash
+# Core CLI (zero third-party deps)
+pip install django-orm-lens
+
+# With the MCP server (adds the `mcp` package)
+pip install "django-orm-lens[mcp]"
+```
+
+Requires Python **3.9+**. Works on Linux, macOS, and Windows.
+
+---
+
+## CLI usage
+
+```bash
+# Scan a Django project for models (JSON, Markdown, or table)
+django-orm-lens scan -f json
+django-orm-lens scan -f markdown
+django-orm-lens scan -f table
+
+# Describe one model
+django-orm-lens describe blog.Post
+django-orm-lens describe Post -f json
+
+# Compact hover card (great for pipeing into your editor)
+django-orm-lens hover blog.Post
+
+# Flat list — pipes into fzf, grep, etc.
+django-orm-lens list | fzf
+
+# Emit a Mermaid ER diagram
+django-orm-lens er > schema.mmd
+django-orm-lens er -o schema.mmd
+```
+
+Every command accepts `--path <dir>` and repeatable `--exclude <glob>`. Defaults
+skip `migrations/`, `venv/`, `.venv/`, `env/`, and `node_modules/`.
+
+---
+
+## MCP server — for AI coding agents
+
+The MCP server exposes five read-only tools that any MCP-compatible agent can
+call while it edits your Django project:
+
+| Tool | Purpose |
+| --- | --- |
+| `list_apps` | Every Django app in the workspace with model counts |
+| `list_models` | Flat `app.Model` list, optional app filter |
+| `describe_model` | Full field / relation / Meta detail for one model |
+| `find_relations` | Inbound + outbound relations for one model |
+| `er_diagram` | Mermaid `erDiagram` string for the whole workspace |
+
+### Start the server manually
+
+```bash
+django-orm-lens-mcp     # dedicated entry point
+# or
+django-orm-lens mcp     # subcommand
+```
+
+By default the server scans the current working directory. Override with
+`DJANGO_ORM_LENS_ROOT=/abs/path/to/project`.
+
+### Register it with an agent
+
+**Cursor** — add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "django-orm-lens": {
+      "command": "django-orm-lens-mcp",
+      "env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" }
+    }
+  }
+}
+```
+
+**Aider / Continue.dev / Zed / any MCP client** — same shape, the tool is
+generic. Point `command` at the installed `django-orm-lens-mcp` binary and set
+the workspace root via env.
+
+---
+
+## Why?
+
+Django's ORM is Python, and Python is dynamic. AI agents that only see
+`models.py` as raw text miss:
+
+* which fields belong to which model;
+* the direction and cardinality of every relation;
+* what `Meta.ordering`, `unique_together`, and `constraints` actually contain;
+* which app owns which model when the project uses split `models/` packages.
+
+`django-orm-lens` gives them a **static, deterministic, JSON view** of the
+schema — no Django boot, no database, no side effects. And you get a nice CLI
+for humans too.
+
+---
+
+## Programmatic API
+
+```python
+from django_orm_lens import scan_workspace
+
+index = scan_workspace(".")
+for app in index.apps:
+    for model in app.models:
+        print(f"{app.name}.{model.name} — {len(model.fields)} fields")
+
+# The full parsed tree serialises to the same JSON schema the VS Code
+# extension emits, so tools can share it interchangeably.
+import json
+json.dumps(index.to_dict(), indent=2)
+```
+
+---
+
+## Links
+
+* Repo: <https://github.com/FROWNINGdev/django-orm-lens>
+* Issues: <https://github.com/FROWNINGdev/django-orm-lens/issues>
+* Changelog: <https://github.com/FROWNINGdev/django-orm-lens/blob/main/CHANGELOG.md>
+* VS Code extension: <https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens>
+
+MIT licensed.

django_orm_lens-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+django_orm_lens/__init__.py,sha256=HtZqQzZE51oetdnT6F7LClqDygBnu0EaTOfcpoQyuHY,514
+django_orm_lens/cli.py,sha256=hBATgRTvghvFiAMcQGj44optc-2ZzHsLIIytOGTu4jg,7691
+django_orm_lens/formatters.py,sha256=oebE8GemJSTwvaQZt_tj5KEhraQ8-4alTzLp54pUPHY,5307
+django_orm_lens/mcp_server.py,sha256=XPiZmrzxKoag4xvTpoGU0JpoSXCpu4dr4GeqmIjn3Q8,6137
+django_orm_lens/models.py,sha256=-T-rQy4098qtgQ_w-B0HJ_Q_jra6E776It0eo7x1Ees,2282
+django_orm_lens/parser.py,sha256=PG0F1lygRFCyPyKZDS14_46gO9l-5s2DXTqy2QacluU,10265
+django_orm_lens/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_orm_lens-1.0.0.dist-info/METADATA,sha256=uwu37iSfvEf6VVL99EhYH6qtw76hIVojO5VQbx9eUtg,6327
+django_orm_lens-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+django_orm_lens-1.0.0.dist-info/entry_points.txt,sha256=uAzPJOMfKD9GBi2oauTuDuO4EiLg-DLCBolc7G95F4Y,115
+django_orm_lens-1.0.0.dist-info/top_level.txt,sha256=2AUW2B4dABPbsiR418KRG8bIQLBlNtHfl26DCLSikX8,16
+django_orm_lens-1.0.0.dist-info/RECORD,,

django_orm_lens-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_orm_lens-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+django-orm-lens = django_orm_lens.cli:main
+django-orm-lens-mcp = django_orm_lens.mcp_server:main

django_orm_lens-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+django_orm_lens