feat(symbols): outline one file's structure, top to bottom

Add file_outline() plus a /project/{id}/outline endpoint: where the
definition index spans the whole project alphabetically, this lists a
single file's functions and classes in the order they are written, with
each class's methods nested underneath. It is the view a reader wants on
opening an unfamiliar file — its shape before its detail. Deterministic,
regex-based, no LLM. Covers Python (methods and nested classes nest) and
JS/TS (top-level, flat). 9 tests.

Author: he-yufeng

backend/models.py

@@ -453,6 +453,27 @@ class ReferenceMatches(BaseModel):
     notes: list[str] = []
 
 
+class OutlineNode(BaseModel):
+    name: str
+    qualname: str = ""  # "Class.method" for methods, plain name otherwise
+    kind: str  # function | class | method
+    parent: str | None = None  # enclosing class for a method
+    lang: str = ""  # python | js
+    file: str
+    line: int
+    children: list["OutlineNode"] = []  # a class's methods (and nested classes)
+
+
+class FileOutline(BaseModel):
+    """One file's structure, in source order — the file's table of contents."""
+
+    file: str
+    lang: str = ""  # python | js
+    total: int = 0  # number of definitions, nested ones included
+    outline: list[OutlineNode] = []
+    notes: list[str] = []
+
+
 class GitHubRequest(BaseModel):
     url: str = Field(..., pattern=r"^https?://github\.com/.+/.+")
 

backend/routers/project.py

@@ -36,6 +36,7 @@
     FileDependencies,
     FileGlossary,
     FileInfo,
+    FileOutline,
     GitHubRequest,
     GlossaryTerm,
     HealthScore,
@@ -648,6 +649,23 @@ async def get_references(project_id: str, name: str):
     )
 
 
+@router.get("/project/{project_id}/outline", response_model=FileOutline)
+async def get_file_outline(project_id: str, path: str):
+    """Return one file's structure, top to bottom — its table of contents.
+
+    Deterministic (no LLM): where the definition index spans the whole project
+    alphabetically, this lists just the chosen file's functions and classes in
+    the order they are written, with each class's methods nested underneath, so
+    a reader can see the shape of an unfamiliar file before its detail.
+    """
+    proj = await _resolve_project(project_id)
+    if not proj:
+        raise HTTPException(404, "Project not found")
+
+    result = symbols.file_outline(proj.get("file_contents", {}), path)
+    return FileOutline(**result)
+
+
 @router.get("/project/{project_id}/codemap.md")
 async def get_codemap_markdown(project_id: str):
     """Export the deterministic code map (import-graph analyses) as Markdown."""

backend/services/symbols.py

@@ -57,6 +57,15 @@ def _indent_width(line: str) -> int:
     return len(expanded) - len(expanded.lstrip())
 
 
+def _count_phrase(n: int, kind: str) -> str:
+    """'1 class', '2 classes', '1 function' — grammatical for a plain-language note."""
+    if kind == "class":
+        word = "class" if n == 1 else "classes"
+    else:
+        word = kind if n == 1 else f"{kind}s"
+    return f"{n} {word}"
+
+
 # ---------------------------------------------------------------------------
 # Python
 # ---------------------------------------------------------------------------
@@ -342,3 +351,94 @@ def _reference_notes(
         "missed, and a same-named field on an unrelated object may be counted."
     )
     return notes
+
+
+# ---------------------------------------------------------------------------
+# File outline — one file's structure, in the order it is written
+# ---------------------------------------------------------------------------
+
+
+def file_outline(file_contents: dict[str, str], path: str, *, limit: int = 1000) -> dict:
+    """Return one file's table of contents, in source order.
+
+    Where :func:`build_definition_index` flattens the whole project
+    alphabetically, this answers the question a reader has the moment they open
+    an unfamiliar file: "what is in here, top to bottom?". Top-level functions
+    and classes are listed in the order they appear, and a class carries its
+    methods nested underneath (also in source order), so the shape of the file
+    is visible before any of its detail.
+
+    Returns ``{"file", "lang", "total", "outline", "notes"}``. ``outline`` is a
+    list of entries (see :func:`_entry`) in line order; an entry that can hold
+    nested definitions — a class — gains a ``children`` list with its methods
+    (and any nested classes). ``total`` counts every definition, nested ones
+    included, before the ``limit`` truncation.
+    """
+    content = file_contents.get(path)
+    if content is None:
+        return {
+            "file": path,
+            "lang": _lang(path),
+            "total": 0,
+            "outline": [],
+            "notes": [f"'{path}' is not among the analyzed files."],
+        }
+
+    lang = _lang(path)
+    if lang == "python":
+        defs = _py_definitions(path, content)
+    elif lang == "js":
+        defs = _js_definitions(path, content)
+    else:
+        return {
+            "file": path,
+            "lang": lang,
+            "total": 0,
+            "outline": [],
+            "notes": ["The outline covers Python and JS/TS files; this file is neither."],
+        }
+
+    total = len(defs)
+    classes_by_name: dict[str, dict] = {}
+    outline: list[dict] = []
+    # Walk in source order so a class is always seen before its own members.
+    for d in sorted(defs, key=lambda e: e["line"]):
+        node = dict(d)
+        parent_node = classes_by_name.get(d["parent"]) if d["parent"] else None
+        if parent_node is not None:
+            parent_node["children"].append(node)
+        else:
+            # A method whose class is not itself indexed (an orphan) still gets
+            # surfaced at the top level rather than silently dropped.
+            outline.append(node)
+        if d["kind"] == "class":
+            node["children"] = []
+            classes_by_name[d["name"]] = node
+
+    notes = _outline_notes(path, lang, defs, total)
+    return {
+        "file": path,
+        "lang": lang,
+        "total": total,
+        "outline": outline[:limit],
+        "notes": notes,
+    }
+
+
+def _outline_notes(path: str, lang: str, defs: list[dict], total: int) -> list[str]:
+    name = path.rsplit("/", 1)[-1]
+    if total == 0:
+        return [f"No top-level functions or classes were found in {name}."]
+
+    by_kind: dict[str, int] = {}
+    for d in defs:
+        by_kind[d["kind"]] = by_kind.get(d["kind"], 0) + 1
+    parts = [_count_phrase(by_kind[k], k) for k in sorted(by_kind)]
+    notes = [f"{name} defines {', '.join(parts)}, listed in the order they appear."]
+    if lang == "js":
+        notes.append(
+            "For JS/TS, methods inside a class are not broken out yet; the class "
+            "is listed as a whole."
+        )
+    notes.append("Regex-based outline: runtime-built or re-exported names may be missed.")
+    return notes

tests/test_symbols.py

@@ -4,6 +4,7 @@
 
 from backend.services.symbols import (
     build_definition_index,
+    file_outline,
     find_definition,
     find_references,
 )
@@ -250,3 +251,96 @@ def test_blank_query(self):
         result = find_references({"a.py": "x = 1\n"}, "  ")
         assert result["total"] == 0
         assert result["references"] == []
+
+
+# ---------------------------------------------------------------------------
+# File outline — one file's structure, in source order
+# ---------------------------------------------------------------------------
+
+
+class TestFileOutline:
+    def test_methods_nest_under_their_class(self):
+        code = """\
+class Scanner:
+    def __init__(self, root):
+        self.root = root
+
+    def scan(self):
+        return []
+
+
+def helper(x):
+    return x
+"""
+        result = file_outline({"scanner.py": code}, "scanner.py")
+        assert result["lang"] == "python"
+        assert result["total"] == 4  # class + 2 methods + 1 function
+
+        top = result["outline"]
+        assert [n["name"] for n in top] == ["Scanner", "helper"]
+
+        scanner = top[0]
+        assert scanner["kind"] == "class"
+        assert [c["name"] for c in scanner["children"]] == ["__init__", "scan"]
+        assert all(c["kind"] == "method" for c in scanner["children"])
+        assert top[1]["kind"] == "function"
+        assert top[1].get("children", []) == []  # only classes carry children
+
+    def test_source_order_is_preserved(self):
+        code = "def a():\n    pass\n\n\nclass B:\n    pass\n\n\ndef c():\n    pass\n"
+        result = file_outline({"m.py": code}, "m.py")
+        assert [n["name"] for n in result["outline"]] == ["a", "B", "c"]
+        assert [n["line"] for n in result["outline"]] == [1, 5, 9]
+
+    def test_nested_class_nests_under_its_parent(self):
+        code = """\
+class Outer:
+    def m(self):
+        pass
+
+    class Inner:
+        def n(self):
+            pass
+"""
+        result = file_outline({"m.py": code}, "m.py")
+        outer = result["outline"][0]
+        names = [c["name"] for c in outer["children"]]
+        assert names == ["m", "Inner"]
+        inner = next(c for c in outer["children"] if c["name"] == "Inner")
+        assert [c["name"] for c in inner["children"]] == ["n"]
+
+    def test_javascript_top_level_in_order(self):
+        code = "export function load(){}\nconst save = () => {};\nclass Store {}\n"
+        result = file_outline({"app.ts": code}, "app.ts")
+        assert result["lang"] == "js"
+        assert [n["name"] for n in result["outline"]] == ["load", "save", "Store"]
+
+    def test_singular_counts_read_naturally(self):
+        code = "class A:\n    def m(self):\n        pass\n"
+        result = file_outline({"a.py": code}, "a.py")
+        assert "1 class" in result["notes"][0]
+        assert "1 method" in result["notes"][0]
+        assert "1 classes" not in result["notes"][0]
+
+    def test_missing_path_is_reported(self):
+        result = file_outline({"a.py": "x = 1\n"}, "b.py")
+        assert result["total"] == 0
+        assert result["outline"] == []
+        assert any("not among the analyzed files" in n for n in result["notes"])
+
+    def test_unsupported_language_is_reported(self):
+        result = file_outline({"notes.md": "# title\n"}, "notes.md")
+        assert result["total"] == 0
+        assert any("Python and JS/TS" in n for n in result["notes"])
+
+    def test_empty_file_has_no_definitions(self):
+        result = file_outline({"a.py": "x = 1\ny = 2\n"}, "a.py")
+        assert result["total"] == 0
+        assert result["outline"] == []
+        assert any("No top-level functions or classes" in n for n in result["notes"])
+
+    def test_limit_truncates_top_level_but_total_counts_all(self):
+        code = "".join(f"def f{i}():\n    pass\n" for i in range(10))
+        result = file_outline({"a.py": code}, "a.py", limit=3)
+        assert result["total"] == 10
+        assert len(result["outline"]) == 3