code-metadata 0.1.0__py3-none-any.whl

code_metadata/analyzer.py

@@ -0,0 +1,168 @@
+"""Complexity, LOC, dependencies, and test-coverage inference."""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from radon.complexity import cc_visit
+from radon.raw import analyze as raw_analyze
+
+
+# ── complexity via radon ──────────────────────────────────────────────────────
+
+def _radon_complexity_map(source: str) -> dict[str, int]:
+    """Return {function_name: cyclomatic_complexity} for all functions/methods."""
+    try:
+        results = cc_visit(source)
+    except Exception:
+        return {}
+    return {r.name: r.complexity for r in results}
+
+
+def file_raw_metrics(source: str) -> dict:
+    """Return radon raw metrics dict (loc, sloc, comments, blank, multi)."""
+    try:
+        m = raw_analyze(source)
+        return {"loc": m.loc, "sloc": m.sloc, "comments": m.comments, "blank": m.blank}
+    except Exception:
+        return {"loc": 0, "sloc": 0, "comments": 0, "blank": 0}
+
+
+# ── dependency extraction ─────────────────────────────────────────────────────
+
+def _call_names(node: ast.AST) -> list[str]:
+    """Names of all calls made inside a function/method node."""
+    names: list[str] = []
+    for child in ast.walk(node):
+        if isinstance(child, ast.Call):
+            func = child.func
+            if isinstance(func, ast.Name):
+                names.append(func.id)
+            elif isinstance(func, ast.Attribute):
+                # e.g. os.path.join → "os.path.join"
+                parts: list[str] = [func.attr]
+                obj = func.value
+                while isinstance(obj, ast.Attribute):
+                    parts.append(obj.attr)
+                    obj = obj.value
+                if isinstance(obj, ast.Name):
+                    parts.append(obj.id)
+                names.append(".".join(reversed(parts)))
+    return list(dict.fromkeys(names))  # deduplicate, preserve order
+
+
+def extract_all_calls(func_node: ast.AST) -> list[str]:
+    """All bare function/method names called in func_node (for call graph)."""
+    names: list[str] = []
+    for child in ast.walk(func_node):
+        if isinstance(child, ast.Call):
+            func = child.func
+            if isinstance(func, ast.Name):
+                names.append(func.id)
+            elif isinstance(func, ast.Attribute):
+                names.append(func.attr)
+    return list(dict.fromkeys(names))
+
+
+def _type_coverage(fn: dict) -> float:
+    """Fraction of params + return slot that carry type annotations (0.0–1.0)."""
+    params = fn.get("params", [])
+    total = len(params) + 1  # +1 for return type slot
+    typed = sum(1 for p in params if p.get("type_hint")) + (1 if fn.get("return_type") else 0)
+    return round(typed / total, 3) if total else 0.0
+
+
+def extract_dependencies(func_node: ast.AST, imported_names: list[str]) -> list[str]:
+    """Calls made inside func_node that match something imported at module level."""
+    calls = _call_names(func_node)
+    imported_set = set(imported_names)
+    # keep call if its root matches an import name
+    deps: list[str] = []
+    for call in calls:
+        root = call.split(".")[0]
+        if root in imported_set:
+            deps.append(call)
+    return deps
+
+
+# ── test-coverage inference ───────────────────────────────────────────────────
+
+def _test_function_names(test_file: Path) -> set[str]:
+    """Parse a test file and return all function names defined in it."""
+    try:
+        source = test_file.read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(source)
+    except Exception:
+        return set()
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            names.add(node.name)
+    return names
+
+
+def build_test_index(repo_path: str | Path) -> dict[str, list[str]]:
+    """Scan repo for test files; return {func_name: [test_file, ...]}."""
+    root = Path(repo_path)
+    test_files = list(root.rglob("test_*.py")) + list(root.rglob("*_test.py"))
+    index: dict[str, list[str]] = {}
+    for tf in test_files:
+        for name in _test_function_names(tf):
+            # strip leading "test_" to get the target function name
+            target = name[5:] if name.startswith("test_") else name
+            index.setdefault(target, []).append(str(tf))
+    return index
+
+
+# ── main enrichment entry point ───────────────────────────────────────────────
+
+def enrich_file(parsed: dict, source: str, test_index: dict[str, list[str]]) -> dict:
+    """Attach complexity/LOC/deps/test fields to a parsed-file dict (mutates in place).
+
+    Args:
+        parsed: dict from parser.parse_file
+        source: raw source text of the file
+        test_index: from build_test_index, covers the whole repo
+    """
+    complexity_map = _radon_complexity_map(source)
+    raw = file_raw_metrics(source)
+    parsed["sloc"] = raw["sloc"]
+
+    # re-parse for AST nodes so we can walk into function bodies
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        tree = None
+
+    func_nodes: dict[str, ast.AST] = {}
+    if tree:
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                func_nodes[node.name] = node
+
+    imports = parsed.get("imports", [])
+
+    def _enrich_fn(fn: dict) -> dict:
+        name = fn["name"]
+        ast_node = func_nodes.get(name)
+        fn["complexity"] = {
+            "cyclomatic_complexity": complexity_map.get(name, 1),
+            "lines_of_code": fn.get("_loc", 0),
+            "docstring_lines": fn.get("_docstring_lines", 0),
+            "dependencies": extract_dependencies(ast_node, imports) if ast_node else [],
+            "has_test": name in test_index,
+            "test_files": test_index.get(name, []),
+        }
+        fn["type_annotation_coverage"] = _type_coverage(fn)
+        fn["_raw_callees"] = extract_all_calls(ast_node) if ast_node else []
+        fn["callees"] = []   # filled later by call graph pass
+        fn["callers"] = []   # filled later by call graph pass
+        fn.pop("_loc", None)
+        fn.pop("_docstring_lines", None)
+        return fn
+
+    parsed["functions"] = [_enrich_fn(f) for f in parsed.get("functions", [])]
+    for cls in parsed.get("classes", []):
+        cls["methods"] = [_enrich_fn(m) for m in cls.get("methods", [])]
+
+    return parsed

code_metadata/cli.py

@@ -0,0 +1,178 @@
+"""CLI entry point and repo-level orchestration."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from code_metadata.analyzer import build_test_index, enrich_file
+from code_metadata.docstring_scorer import enrich_docstrings
+from code_metadata.exporters import to_csv, to_json
+from code_metadata.git_utils import enrich_git
+from code_metadata.parser import parse_file
+from code_metadata.schema import (
+    ClassMetadata,
+    FileMetadata,
+    FunctionMetadata,
+    RepositoryMetadata,
+)
+
+app = typer.Typer(help="Extract metadata from Python repositories.")
+console = Console(stderr=True)
+
+
+# ── orchestration (importable for tests) ─────────────────────────────────────
+
+def _to_function_metadata(fn: dict) -> FunctionMetadata:
+    return FunctionMetadata.model_validate(fn)
+
+
+def _to_class_metadata(cls: dict) -> ClassMetadata:
+    methods = [_to_function_metadata(m) for m in cls.get("methods", [])]
+    return ClassMetadata.model_validate({**cls, "methods": methods})
+
+
+def _to_file_metadata(parsed: dict) -> FileMetadata:
+    functions = [_to_function_metadata(f) for f in parsed.get("functions", [])]
+    classes = [_to_class_metadata(c) for c in parsed.get("classes", [])]
+    return FileMetadata(
+        file_path=parsed["file_path"],
+        functions=functions,
+        classes=classes,
+        total_lines=parsed.get("total_lines", 0),
+        import_count=len(parsed.get("imports", [])),
+    )
+
+
+def _build_call_graph(all_parsed: list[dict]) -> None:
+    """Compute callers/callees across all files; mutates parsed dicts in place."""
+    all_fn_names: set[str] = set()
+    all_fns: list[dict] = []
+    for parsed in all_parsed:
+        for fn in parsed.get("functions", []):
+            all_fn_names.add(fn["name"])
+            all_fns.append(fn)
+        for cls in parsed.get("classes", []):
+            for m in cls.get("methods", []):
+                all_fn_names.add(m["name"])
+                all_fns.append(m)
+
+    callers: dict[str, list[str]] = {n: [] for n in all_fn_names}
+    for fn in all_fns:
+        raw = fn.pop("_raw_callees", [])
+        callees = [c for c in raw if c in all_fn_names and c != fn["name"]]
+        fn["callees"] = list(dict.fromkeys(callees))
+        for callee in fn["callees"]:
+            callers[callee].append(fn["name"])
+
+    for fn in all_fns:
+        fn["callers"] = list(dict.fromkeys(callers.get(fn["name"], [])))
+
+
+def extract_repo(
+    repo_path: str | Path,
+    include_git: bool = True,
+    summarize: bool = False,
+) -> RepositoryMetadata:
+    """Parse every .py file in repo_path; return RepositoryMetadata."""
+    root = Path(repo_path).resolve()
+    py_files = sorted(root.rglob("*.py"))
+
+    test_index = build_test_index(root)
+
+    # Phase 1: enrich all files (dicts), keep sources for summarizer
+    all_parsed: list[dict] = []
+    sources: list[str] = []
+    for py in py_files:
+        source = py.read_text(encoding="utf-8", errors="replace")
+        parsed = parse_file(py)
+        enrich_file(parsed, source, test_index)
+        enrich_docstrings(parsed)
+        if include_git:
+            enrich_git(parsed)
+        else:
+            for fn in parsed.get("functions", []):
+                fn["git_metadata"] = None
+            for cls in parsed.get("classes", []):
+                cls["git_metadata"] = None
+                for m in cls.get("methods", []):
+                    m["git_metadata"] = None
+        all_parsed.append(parsed)
+        sources.append(source)
+
+    # Phase 2: cross-file call graph
+    _build_call_graph(all_parsed)
+
+    # Phase 3: optional LLM summaries
+    if summarize:
+        from code_metadata.summarizer import enrich_summaries
+        for parsed, source in zip(all_parsed, sources):
+            enrich_summaries(parsed, source)
+
+    # Phase 4: validate into Pydantic schema
+    file_metas: list[FileMetadata] = []
+    for parsed in all_parsed:
+        try:
+            file_metas.append(_to_file_metadata(parsed))
+        except Exception as exc:
+            console.print(f"[yellow]Skipping {Path(parsed['file_path']).name}: {exc}[/yellow]")
+
+    total_functions = sum(
+        len(f.functions) + sum(len(c.methods) for c in f.classes)
+        for f in file_metas
+    )
+    total_classes = sum(len(f.classes) for f in file_metas)
+
+    return RepositoryMetadata(
+        repository_path=str(root),
+        analyzed_at=datetime.now(tz=timezone.utc),
+        total_functions=total_functions,
+        total_classes=total_classes,
+        total_files=len(file_metas),
+        files=file_metas,
+    )
+
+
+# ── CLI commands ──────────────────────────────────────────────────────────────
+
+@app.command()
+def extract(
+    repo_path: Path = typer.Argument(..., help="Path to the Python repository."),
+    format: str = typer.Option("json", "--format", "-f", help="Output format: json or csv."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path."),
+    no_git: bool = typer.Option(False, "--no-git", help="Skip git blame integration."),
+    summarize: bool = typer.Option(False, "--summarize", "-s", help="Add LLM summaries (requires anthropic)."),
+) -> None:
+    """Extract metadata from a Python repository."""
+    if not repo_path.exists():
+        console.print(f"[red]Path not found: {repo_path}[/red]")
+        raise typer.Exit(1)
+
+    console.print(f"Scanning [bold]{repo_path}[/bold] ...")
+    repo = extract_repo(repo_path, include_git=not no_git, summarize=summarize)
+    console.print(
+        f"Found [green]{repo.total_files}[/green] files, "
+        f"[green]{repo.total_functions}[/green] functions, "
+        f"[green]{repo.total_classes}[/green] classes."
+    )
+
+    fmt = format.lower()
+    if fmt == "json":
+        text = to_json(repo, output)
+    elif fmt == "csv":
+        text = to_csv(repo, output)
+    else:
+        console.print(f"[red]Unknown format '{format}'. Use json or csv.[/red]")
+        raise typer.Exit(1)
+
+    if output:
+        console.print(f"Written to [bold]{output}[/bold]")
+    else:
+        typer.echo(text)
+
+
+if __name__ == "__main__":
+    app()

code_metadata/docstring_scorer.py

@@ -0,0 +1,116 @@
+"""Heuristic docstring quality scoring — no LLM, pure string matching."""
+from __future__ import annotations
+
+import re
+from typing import Literal, Optional
+
+DocstringStyle = Literal["numpy", "google", "sphinx", "unstructured", "none"]
+
+# ── style detection ───────────────────────────────────────────────────────────
+
+# Sphinx: :param name:  :type name:  :returns:  :rtype:
+_RE_SPHINX = re.compile(r":(param|type|returns?|rtype)\b")
+
+# NumPy: section headers underlined with dashes
+#   Parameters
+#   ----------
+_RE_NUMPY = re.compile(r"^\s*(Parameters|Returns|Raises|Notes|Examples|Attributes)\s*\n\s*-{3,}", re.MULTILINE)
+
+# Google: "Args:\n    ", "Returns:\n    "
+_RE_GOOGLE = re.compile(r"^\s*(Args|Returns|Raises|Note|Example|Attributes)\s*:\s*\n\s+\S", re.MULTILINE)
+
+# Section presence (style-agnostic)
+_RE_ARGS = re.compile(
+    r"(^\s*(Args|Parameters|Params)\s*[:\n]|:param\s+\w|Parameters\s*\n\s*-{3,})",
+    re.MULTILINE | re.IGNORECASE,
+)
+_RE_RETURNS = re.compile(
+    r"(^\s*(Returns?|Return value)\s*[:\n]|:returns?:|:rtype:|Returns\s*\n\s*-{3,})",
+    re.MULTILINE | re.IGNORECASE,
+)
+_RE_EXAMPLE = re.compile(
+    r"(^\s*(Examples?)\s*[:\n]|>>>\s|\bExample\b)",
+    re.MULTILINE | re.IGNORECASE,
+)
+
+
+def _detect_style(doc: str) -> DocstringStyle:
+    if _RE_SPHINX.search(doc):
+        return "sphinx"
+    if _RE_NUMPY.search(doc):
+        return "numpy"
+    if _RE_GOOGLE.search(doc):
+        return "google"
+    return "unstructured"
+
+
+# ── scoring ───────────────────────────────────────────────────────────────────
+
+def _quality_score(
+    presence: bool,
+    length: int,
+    has_args: bool,
+    has_return: bool,
+    has_example: bool,
+) -> float:
+    if not presence:
+        return 0.0
+    score = 0.2                          # base: docstring exists
+    score += 0.2 if has_args else 0.0
+    score += 0.2 if has_return else 0.0
+    score += 0.2 if has_example else 0.0
+    score += 0.1 if length >= 50 else 0.0
+    score += 0.1 if length >= 200 else 0.0
+    return round(min(score, 1.0), 4)
+
+
+# ── public API ────────────────────────────────────────────────────────────────
+
+def score_docstring(docstring: Optional[str]) -> dict:
+    """Return a DocstringQuality-shaped dict for one function/method/class.
+
+    Args:
+        docstring: raw docstring text, or None.
+
+    Returns:
+        Dict matching the DocstringQuality schema.
+    """
+    if not docstring:
+        return {
+            "presence": False,
+            "length": 0,
+            "has_args_section": False,
+            "has_return_section": False,
+            "has_example": False,
+            "style": "none",
+            "quality_score": 0.0,
+        }
+
+    has_args = bool(_RE_ARGS.search(docstring))
+    has_return = bool(_RE_RETURNS.search(docstring))
+    has_example = bool(_RE_EXAMPLE.search(docstring))
+    length = len(docstring)
+
+    return {
+        "presence": True,
+        "length": length,
+        "has_args_section": has_args,
+        "has_return_section": has_return,
+        "has_example": has_example,
+        "style": _detect_style(docstring),
+        "quality_score": _quality_score(True, length, has_args, has_return, has_example),
+    }
+
+
+def enrich_docstrings(parsed: dict) -> dict:
+    """Attach docstring_quality to every function and class in a parsed-file dict."""
+
+    def _attach_fn(fn: dict) -> dict:
+        fn["docstring_quality"] = score_docstring(fn.get("docstring"))
+        return fn
+
+    parsed["functions"] = [_attach_fn(f) for f in parsed.get("functions", [])]
+    for cls in parsed.get("classes", []):
+        cls["docstring_quality"] = score_docstring(cls.get("docstring"))
+        cls["methods"] = [_attach_fn(m) for m in cls.get("methods", [])]
+    return parsed

code_metadata/exporters.py

@@ -0,0 +1,82 @@
+"""JSON and CSV export for RepositoryMetadata."""
+from __future__ import annotations
+
+import csv
+import io
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from code_metadata.schema import FunctionMetadata, RepositoryMetadata
+
+
+def _fn_rows(repo: RepositoryMetadata) -> list[dict]:
+    """Flatten every function/method to one CSV row each."""
+    rows = []
+    for file in repo.files:
+        def _row(fn: FunctionMetadata) -> dict:
+            git = fn.git_metadata
+            cplx = fn.complexity
+            dq = fn.docstring_quality
+            return {
+                "file_path": fn.file_path,
+                "name": fn.name,
+                "line_number": fn.line_number,
+                "end_line_number": fn.end_line_number,
+                "is_method": fn.is_method,
+                "is_async": fn.is_async,
+                "parent_class": fn.parent_class or "",
+                "decorators": "|".join(fn.decorators),
+                "return_type": fn.return_type or "",
+                "type_annotation_coverage": fn.type_annotation_coverage,
+                "cyclomatic_complexity": cplx.cyclomatic_complexity,
+                "lines_of_code": cplx.lines_of_code,
+                "docstring_lines": cplx.docstring_lines,
+                "has_test": cplx.has_test,
+                "has_docstring": dq.presence,
+                "docstring_score": dq.quality_score,
+                "docstring_style": dq.style,
+                "callees": "|".join(fn.callees),
+                "callers": "|".join(fn.callers),
+                "summary": fn.summary or "",
+                "git_author": git.author if git else "",
+                "git_last_modified": git.last_modified.isoformat() if git else "",
+                "git_commit_count": git.commit_count if git else "",
+            }
+
+        for fn in file.functions:
+            rows.append(_row(fn))
+        for cls in file.classes:
+            for method in cls.methods:
+                rows.append(_row(method))
+    return rows
+
+
+def _json_default(obj):
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    raise TypeError(f"Not serializable: {type(obj)}")
+
+
+def to_json(repo: RepositoryMetadata, output: Optional[str | Path] = None) -> str:
+    """Serialize repo metadata to JSON string; optionally write to file."""
+    text = repo.model_dump_json(indent=2)
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+    return text
+
+
+def to_csv(repo: RepositoryMetadata, output: Optional[str | Path] = None) -> str:
+    """Flatten functions/methods to CSV; optionally write to file."""
+    rows = _fn_rows(repo)
+    if not rows:
+        return ""
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
+    writer.writeheader()
+    writer.writerows(rows)
+    text = buf.getvalue()
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+    return text

code_metadata/git_utils.py

@@ -0,0 +1,134 @@
+"""Git blame integration — cached per file, optional (null on non-git repos)."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+try:
+    import git
+    _GIT_AVAILABLE = True
+except ImportError:
+    _GIT_AVAILABLE = False
+
+
+# ── repo discovery ────────────────────────────────────────────────────────────
+
+@lru_cache(maxsize=16)
+def _find_repo(path: str) -> Optional[object]:
+    """Return a git.Repo for the given path, or None if not a git repo."""
+    if not _GIT_AVAILABLE:
+        return None
+    try:
+        return git.Repo(path, search_parent_directories=True)
+    except Exception:
+        return None
+
+
+def get_repo(path: str | Path) -> Optional[object]:
+    return _find_repo(str(Path(path).resolve()))
+
+
+# ── per-file blame cache ──────────────────────────────────────────────────────
+
+@lru_cache(maxsize=256)
+def _blame_lines(repo_path: str, rel_file: str) -> list[dict]:
+    """Return per-line blame list (1-indexed; index 0 is a dummy placeholder).
+
+    Each entry: {author, author_email, date: datetime, sha: str}
+    One call per file — cached by (repo_path, rel_file).
+    """
+    repo = _find_repo(repo_path)
+    if repo is None:
+        return []
+    try:
+        blame = repo.blame("HEAD", rel_file)
+    except Exception:
+        return []
+
+    lines: list[dict] = [{}]  # index 0 unused so line 1 == lines[1]
+    for commit, file_lines in blame:
+        entry = {
+            "author": commit.author.name,
+            "author_email": commit.author.email,
+            "date": datetime.fromtimestamp(commit.authored_date, tz=timezone.utc),
+            "sha": commit.hexsha,
+        }
+        for _ in file_lines:
+            lines.append(entry)
+    return lines
+
+
+def _commit_count(repo: object, rel_file: str) -> int:
+    try:
+        return sum(1 for _ in repo.iter_commits(paths=rel_file))
+    except Exception:
+        return 0
+
+
+# ── public API ────────────────────────────────────────────────────────────────
+
+def git_metadata_for_lines(
+    file_path: str | Path,
+    start_line: int,
+    end_line: int,
+) -> Optional[dict]:
+    """Return git metadata covering [start_line, end_line] (1-based), or None.
+
+    Picks the most-recent commit in the line range as "last modified".
+    """
+    abs_path = Path(file_path).resolve()
+    repo = get_repo(abs_path)
+    if repo is None:
+        return None
+
+    repo_root = Path(repo.working_tree_dir).resolve()
+    try:
+        rel_file = str(abs_path.relative_to(repo_root))
+    except ValueError:
+        return None
+
+    blame = _blame_lines(str(repo_root), rel_file)
+    if not blame:
+        return None
+
+    # slice lines in range (clamp to available)
+    relevant = [
+        blame[i]
+        for i in range(start_line, min(end_line + 1, len(blame)))
+        if blame[i]
+    ]
+    if not relevant:
+        return None
+
+    # most-recent commit in range
+    latest = max(relevant, key=lambda e: e["date"])
+
+    commit_cnt = _commit_count(repo, rel_file)
+
+    return {
+        "last_modified": latest["date"],
+        "author": latest["author"],
+        "author_email": latest["author_email"],
+        "commit_count": commit_cnt,
+    }
+
+
+def enrich_git(parsed: dict) -> dict:
+    """Attach git_metadata to every function and class in a parsed-file dict."""
+    file_path = parsed.get("file_path", "")
+
+    def _attach(fn: dict) -> dict:
+        fn["git_metadata"] = git_metadata_for_lines(
+            file_path, fn["line_number"], fn["end_line_number"]
+        )
+        return fn
+
+    parsed["functions"] = [_attach(f) for f in parsed.get("functions", [])]
+    for cls in parsed.get("classes", []):
+        cls["methods"] = [_attach(m) for m in cls.get("methods", [])]
+        cls["git_metadata"] = git_metadata_for_lines(
+            file_path, cls["line_number"], cls["end_line_number"]
+        )
+    return parsed

code_metadata/parser.py

@@ -0,0 +1,146 @@
+"""AST walker — extracts functions, classes, imports from a Python source file."""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Optional
+
+
+def _annotation_to_str(node: Optional[ast.expr]) -> Optional[str]:
+    if node is None:
+        return None
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return None
+
+
+def _decorator_names(decorator_list: list[ast.expr]) -> list[str]:
+    return [_annotation_to_str(d) or "" for d in decorator_list]
+
+
+def _extract_params(args: ast.arguments) -> list[dict]:
+    params = []
+    all_args = args.posonlyargs + args.args + args.kwonlyargs
+    if args.vararg:
+        all_args.append(args.vararg)
+    if args.kwarg:
+        all_args.append(args.kwarg)
+    for arg in all_args:
+        params.append({
+            "name": arg.arg,
+            "type_hint": _annotation_to_str(arg.annotation),
+        })
+    return params
+
+
+def _count_lines(node: ast.AST) -> int:
+    """Lines spanned by a function/class body (end_lineno - lineno + 1)."""
+    end = getattr(node, "end_lineno", None)
+    start = getattr(node, "lineno", None)
+    if end is not None and start is not None:
+        return end - start + 1
+    return 0
+
+
+def _extract_imports(tree: ast.Module) -> list[str]:
+    """Top-level import names from the module."""
+    names: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                names.append(alias.asname or alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module or ""
+            for alias in node.names:
+                names.append(alias.asname or f"{module}.{alias.name}")
+    return names
+
+
+def _parse_function(
+    node: ast.AsyncFunctionDef | ast.FunctionDef,
+    file_path: str,
+    parent_class: Optional[str] = None,
+    is_method: bool = False,
+) -> dict:
+    docstring = ast.get_docstring(node)
+    docstring_lines = 0
+    if docstring:
+        docstring_lines = docstring.count("\n") + 1
+    return {
+        "name": node.name,
+        "file_path": file_path,
+        "line_number": node.lineno,
+        "end_line_number": getattr(node, "end_lineno", node.lineno),
+        "params": _extract_params(node.args),
+        "return_type": _annotation_to_str(node.returns),
+        "docstring": docstring,
+        "is_method": is_method,
+        "is_async": isinstance(node, ast.AsyncFunctionDef),
+        "decorators": _decorator_names(node.decorator_list),
+        "parent_class": parent_class,
+        # complexity fields filled later by analyzer
+        "_loc": _count_lines(node),
+        "_docstring_lines": docstring_lines,
+    }
+
+
+def _parse_class(node: ast.ClassDef, file_path: str) -> dict:
+    methods = []
+    for item in node.body:
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            methods.append(_parse_function(item, file_path, parent_class=node.name, is_method=True))
+    return {
+        "name": node.name,
+        "file_path": file_path,
+        "line_number": node.lineno,
+        "end_line_number": getattr(node, "end_lineno", node.lineno),
+        "docstring": ast.get_docstring(node),
+        "decorators": _decorator_names(node.decorator_list),
+        "methods": methods,
+        "bases": [_annotation_to_str(b) or "" for b in node.bases],
+    }
+
+
+def parse_file(source_path: str | Path) -> dict:
+    """Parse one Python file; return raw dicts (schema applied later).
+
+    Returns:
+        {
+          "file_path": str,
+          "functions": [...],   # top-level only
+          "classes": [...],
+          "imports": [...],
+          "total_lines": int,
+        }
+    """
+    path = Path(source_path)
+    source = path.read_text(encoding="utf-8", errors="replace")
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as exc:
+        return {
+            "file_path": str(path),
+            "functions": [],
+            "classes": [],
+            "imports": [],
+            "total_lines": source.count("\n") + 1,
+            "parse_error": str(exc),
+        }
+
+    functions: list[dict] = []
+    classes: list[dict] = []
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append(_parse_function(node, str(path)))
+        elif isinstance(node, ast.ClassDef):
+            classes.append(_parse_class(node, str(path)))
+
+    return {
+        "file_path": str(path),
+        "functions": functions,
+        "classes": classes,
+        "imports": _extract_imports(tree),
+        "total_lines": source.count("\n") + 1,
+    }

code_metadata/schema.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ParamMetadata(BaseModel):
+    name: str
+    type_hint: Optional[str] = None
+
+
+class DocstringQuality(BaseModel):
+    presence: bool
+    length: int
+    has_args_section: bool
+    has_return_section: bool
+    has_example: bool
+    style: Literal["numpy", "google", "sphinx", "unstructured", "none"]
+    quality_score: float = Field(ge=0.0, le=1.0)
+
+
+class GitMetadata(BaseModel):
+    last_modified: datetime
+    author: str
+    author_email: str
+    commit_count: int
+
+
+class ComplexityMetrics(BaseModel):
+    cyclomatic_complexity: int
+    lines_of_code: int
+    docstring_lines: int
+    dependencies: list[str]
+    has_test: bool
+    test_files: list[str]
+
+
+class FunctionMetadata(BaseModel):
+    name: str
+    file_path: str
+    line_number: int
+    end_line_number: int
+    params: list[ParamMetadata]
+    return_type: Optional[str] = None
+    docstring: Optional[str] = None
+    is_method: bool
+    is_async: bool
+    decorators: list[str]
+    parent_class: Optional[str] = None
+    complexity: ComplexityMetrics
+    docstring_quality: DocstringQuality
+    git_metadata: Optional[GitMetadata] = None
+    type_annotation_coverage: float = Field(default=0.0, ge=0.0, le=1.0)
+    callees: list[str] = []
+    callers: list[str] = []
+    summary: Optional[str] = None
+
+
+class ClassMetadata(BaseModel):
+    name: str
+    file_path: str
+    line_number: int
+    end_line_number: int
+    docstring: Optional[str] = None
+    decorators: list[str]
+    methods: list[FunctionMetadata]
+    bases: list[str]
+    git_metadata: Optional[GitMetadata] = None
+
+
+class FileMetadata(BaseModel):
+    file_path: str
+    functions: list[FunctionMetadata]
+    classes: list[ClassMetadata]
+    total_lines: int
+    import_count: int
+
+
+class RepositoryMetadata(BaseModel):
+    repository_path: str
+    analyzed_at: datetime
+    language: str = "python"
+    total_functions: int
+    total_classes: int
+    total_files: int
+    files: list[FileMetadata]

code_metadata/summarizer.py

@@ -0,0 +1,50 @@
+"""Optional LLM summarization via Anthropic API (claude-haiku-4-5-20251001)."""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def _client():
+    try:
+        import anthropic
+        return anthropic.Anthropic()
+    except ImportError:
+        raise ImportError("Install anthropic: pip install 'code-metadata[llm]'")
+
+
+def summarize_function(name: str, docstring: Optional[str], source_lines: str) -> str:
+    """Return a one-sentence summary of a function via Claude Haiku."""
+    client = _client()
+    prompt = (
+        f"Summarize this Python function in one sentence (max 20 words). "
+        f"Focus on what it does, not its structure.\n\n"
+        f"Name: {name}\n"
+        f"Docstring: {docstring or 'None'}\n"
+        f"Source:\n{source_lines}\n\n"
+        f"Reply with just the summary sentence, no quotes."
+    )
+    msg = client.messages.create(
+        model="claude-haiku-4-5-20251001",
+        max_tokens=80,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return msg.content[0].text.strip()
+
+
+def enrich_summaries(parsed: dict, source: str) -> dict:
+    """Attach LLM-generated summary to each function/method in a parsed file dict."""
+    lines = source.splitlines()
+
+    def _src(fn: dict) -> str:
+        start = max(0, fn.get("line_number", 1) - 1)
+        end = fn.get("end_line_number", start + 1)
+        return "\n".join(lines[start:end])
+
+    for fn in parsed.get("functions", []):
+        fn["summary"] = summarize_function(fn["name"], fn.get("docstring"), _src(fn))
+
+    for cls in parsed.get("classes", []):
+        for m in cls.get("methods", []):
+            m["summary"] = summarize_function(m["name"], m.get("docstring"), _src(m))
+
+    return parsed

code_metadata-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.5
+Name: code-metadata
+Version: 0.1.0
+Summary: Python repository metadata extractor — AST-based, no LLM
+Requires-Python: >=3.11
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: radon>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.34; extra == 'llm'

code_metadata-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+code_metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_metadata/analyzer.py,sha256=zZIAI_VuGBNRS6DVIrA_VgVEVirBffRer2GFBCizK9A,6721
+code_metadata/cli.py,sha256=5FI0BGadJpczuJytIuWcoXhpksA3YBt8Ot3jVrwyjng,6360
+code_metadata/docstring_scorer.py,sha256=6-r7slmHi4osmFkuwVnDf1K6yaLHPRGWw__4HNsLVyM,4093
+code_metadata/exporters.py,sha256=FSAkAc7au6Dc0V7muJTGRCJvHud-l6PVFeVcRlGHhXw,2940
+code_metadata/git_utils.py,sha256=j_4iky-nMjt-e7YTfzYGyTL084GBakI-G6BBeycOD1Y,4277
+code_metadata/parser.py,sha256=G23AzxDK4pgr7QDsJG4yvwLp1fY4kRWcBwqjqvWjWik,4638
+code_metadata/schema.py,sha256=JzFcIHwYyJ_75981_EcAu8hyBBuofuIt_eX8X2NTmFI,2080
+code_metadata/summarizer.py,sha256=g982lS2T7fupZ9_ajAf34jX5-rPOgiAkgeHJeYZxAhE,1721
+code_metadata-0.1.0.dist-info/METADATA,sha256=apArmH-ybLlaQaxob9IxVyty2-w0sgGTnDJUCMv_yYQ,505
+code_metadata-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+code_metadata-0.1.0.dist-info/entry_points.txt,sha256=sJw3dCa0EgaD7ElIQ3sma91YjnEObFOQedYrkhYM01U,56
+code_metadata-0.1.0.dist-info/RECORD,,

code_metadata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

code_metadata-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+code-metadata = code_metadata.cli:app