sourcecode 1.51.0__py3-none-any.whl → 1.53.0__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.51.0"
+__version__ = "1.53.0"

sourcecode/cli.py

@@ -219,7 +219,7 @@ _HELP = _build_help_text()
 _SUBCOMMANDS: frozenset[str] = frozenset(
     {
         "telemetry", "prepare-context", "version", "config",
-        "repo-ir", "mcp", "endpoints", "impact",
+        "repo-ir", "mcp", "endpoints", "impact", "export",
         # Enterprise workflow commands
         "onboard", "modernize", "fix-bug", "review-pr",
         # License / auth
@@ -3804,6 +3804,30 @@ def impact_cmd(
 # canonical single-source-of-truth endpoint extractor.
 
 
+def _group_endpoints_by_controller(endpoints: "list[dict]") -> "dict":
+    """Group endpoints by their controller FQN into a structured API surface.
+
+    Returns ``{"by_controller": {fqn: [{method, path, return_type}, ...]},
+    "controller_count": int, "total": int}``. Controllers and their routes are
+    ordered deterministically (controllers by name, routes by path then method).
+    """
+    by_ctrl: "dict[str, list[dict]]" = {}
+    for ep in endpoints:
+        ctrl = ep.get("controller", "") or "<unknown>"
+        by_ctrl.setdefault(ctrl, []).append({
+            "method": ep.get("method", ""),
+            "path": ep.get("path", ""),
+            "return_type": ep.get("return_type", "void"),
+        })
+    for ctrl in by_ctrl:
+        by_ctrl[ctrl].sort(key=lambda r: (r["path"], r["method"]))
+    ordered = {k: by_ctrl[k] for k in sorted(by_ctrl)}
+    return {
+        "by_controller": ordered,
+        "controller_count": len(ordered),
+        "total": len(endpoints),
+    }
+
 
 @app.command("endpoints")
 def endpoints_cmd(
@@ -3844,6 +3868,10 @@ def endpoints_cmd(
         False, "--no-cache",
         help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
     ),
+    by_controller: bool = typer.Option(
+        False, "--by-controller",
+        help="Group endpoints by controller class (structured API surface for C4/Container synthesis).",
+    ),
 ) -> None:
     """Extract REST API endpoint surface from Java source files.
 
@@ -3929,6 +3957,11 @@ def endpoints_cmd(
             "undocumented_before_filter": _undoc_before,
         }
 
+    if by_controller:
+        _grouped = _group_endpoints_by_controller(data.get("endpoints", []))
+        data["by_controller"] = _grouped["by_controller"]
+        data["controller_count"] = _grouped["controller_count"]
+
     output = _serialize_dict(data, format)
 
     _emit_command_output(output, output_path, copy,
@@ -3938,6 +3971,362 @@ def endpoints_cmd(
     _nudge()
 
 
+# ── export ──────────────────────────────────────────────────────────────────
+
+def _group_symbols_by_directory(nodes: "list[dict]") -> "dict":
+    """Group repo-ir graph nodes by source directory with path:line refs.
+
+    Returns ``{dir: [{symbol, kind, ref}]}`` ordered deterministically (dirs by
+    name, symbols by ref). ``ref`` is ``source_file:line`` when the line is known,
+    otherwise just ``source_file``. This is the per-directory, file:line-anchored
+    code-level export — the file:line-anchored input an architecture/code-map
+    consumer needs to proceed by file write instead of per-directory LLM reads.
+    """
+    import posixpath
+    by_dir: "dict[str, list[dict]]" = {}
+    for n in nodes:
+        sf = n.get("source_file") or ""
+        if not sf:
+            continue
+        d = posixpath.dirname(sf) or "."
+        ln = n.get("line")
+        ref = f"{sf}:{ln}" if ln else sf
+        by_dir.setdefault(d, []).append({
+            "symbol": n.get("canonical_name") or n.get("fqn"),
+            "kind": n.get("symbol_kind"),
+            "ref": ref,
+        })
+    for d in by_dir:
+        by_dir[d].sort(key=lambda r: r["ref"])
+    return {k: by_dir[k] for k in sorted(by_dir)}
+
+
+def _build_module_graph(nodes: "list[dict]", edges: "list[dict]") -> "dict":
+    """Roll class-level relation edges up into a module→module dependency graph.
+
+    A *module* is the source directory of a symbol (same grouping key as
+    ``--by-directory``), giving C4 a container/component-level dependency view.
+    Every node FQN maps to its module; each edge whose endpoints resolve to two
+    *different* modules contributes one inter-module dependency, aggregated by
+    ``(from, to)`` with a hit count and the set of underlying edge types.
+
+    Edges whose endpoints are not internal nodes (e.g. imports of external
+    library types) are skipped — only resolvable, internal module→module
+    dependencies are reported. Returns ``{nodes, edges, summary}`` deterministically.
+    """
+    import posixpath
+
+    fqn_to_module: "dict[str, str]" = {}
+    module_symbols: "dict[str, int]" = {}
+    for n in nodes:
+        sf = n.get("source_file") or ""
+        if not sf:
+            continue
+        mod = posixpath.dirname(sf) or "."
+        fqn = n.get("fqn")
+        if fqn:
+            fqn_to_module[fqn] = mod
+        module_symbols[mod] = module_symbols.get(mod, 0) + 1
+
+    # (from_mod, to_mod) -> {"count": int, "types": set[str]}
+    agg: "dict[tuple[str, str], dict]" = {}
+    for e in edges:
+        fm = fqn_to_module.get(e.get("from"))
+        tm = fqn_to_module.get(e.get("to"))
+        if fm is None or tm is None or fm == tm:
+            continue
+        slot = agg.setdefault((fm, tm), {"count": 0, "types": set()})
+        slot["count"] += 1
+        et = e.get("type")
+        if et:
+            slot["types"].add(et)
+
+    graph_edges = [
+        {
+            "from": fm,
+            "to": tm,
+            "count": slot["count"],
+            "types": sorted(slot["types"]),
+        }
+        for (fm, tm), slot in sorted(agg.items())
+    ]
+    out_deg: "dict[str, int]" = {}
+    in_deg: "dict[str, int]" = {}
+    for ed in graph_edges:
+        out_deg[ed["from"]] = out_deg.get(ed["from"], 0) + 1
+        in_deg[ed["to"]] = in_deg.get(ed["to"], 0) + 1
+    graph_nodes = [
+        {
+            "module": mod,
+            "symbol_count": module_symbols[mod],
+            "out_degree": out_deg.get(mod, 0),
+            "in_degree": in_deg.get(mod, 0),
+        }
+        for mod in sorted(module_symbols)
+    ]
+    return {
+        "nodes": graph_nodes,
+        "edges": graph_edges,
+        "summary": {
+            "module_count": len(graph_nodes),
+            "edge_count": len(graph_edges),
+        },
+    }
+
+
+# Build-system markers that identify a deployable/buildable unit (C4 container).
+_BUILD_MARKERS: "tuple[str, ...]" = (
+    "pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle",
+)
+
+
+def _detect_containers(root: "Path") -> "list[dict]":
+    """Detect build-module roots as C4 containers (deployable/buildable units).
+
+    A *container* is a directory holding a recognized build file
+    (Maven/Gradle). Detection is purely structural — no build is run. Returns
+    ``[{root, build_file}]`` (relative paths, deterministic order). Empty when no
+    build files are found; the caller records that as a limitation rather than
+    fabricating containers.
+    """
+    import os
+    found: "list[dict]" = []
+    seen: "set[str]" = set()
+    _SKIP = {".git", "node_modules", "target", "build", ".gradle", ".idea", "dist"}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP and not d.startswith(".")]
+        for marker in _BUILD_MARKERS:
+            if marker in filenames:
+                rel = os.path.relpath(dirpath, root).replace(os.sep, "/")
+                rel = "." if rel == "." else rel
+                if rel in seen:
+                    continue
+                seen.add(rel)
+                found.append({"root": rel, "build_file": marker})
+                break
+    found.sort(key=lambda c: c["root"])
+    return found
+
+
+def _directory_hashes(file_list: "list[str]", root: "Path") -> "dict[str, str]":
+    """Content-addressed sha256 per source directory for incremental consumers.
+
+    Hash inputs are the directory's source files as ``(relpath, bytes)`` in
+    sorted order, so the digest is stable across runs and changes iff a file in
+    that directory changes. A consumer compares hashes to skip unchanged
+    directories. Tool-agnostic: just a map ``{dir: sha256[:16]}``.
+    """
+    import hashlib
+    import posixpath
+    by_dir: "dict[str, list[str]]" = {}
+    for rel in file_list:
+        d = posixpath.dirname(rel) or "."
+        by_dir.setdefault(d, []).append(rel)
+    out: "dict[str, str]" = {}
+    for d in sorted(by_dir):
+        h = hashlib.sha256()
+        for rel in sorted(by_dir[d]):
+            h.update(rel.encode("utf-8"))
+            h.update(b"\0")
+            try:
+                h.update((root / rel).read_bytes())
+            except OSError:
+                h.update(b"<unreadable>")
+            h.update(b"\0")
+        out[d] = h.hexdigest()[:16]
+    return out
+
+
+def _build_c4_export(
+    root: "Path",
+    file_list: "list[str]",
+    nodes: "list[dict]",
+    edges: "list[dict]",
+    endpoints: "list[dict]",
+    integrations: "dict",
+) -> "dict":
+    """Assemble a unified, tool-agnostic C4 architecture export + incremental manifest.
+
+    Maps the four already-built views onto the open C4 model (a public notation,
+    not a product): code (L4), components (L3/L2), context external systems (L1),
+    plus build-module containers and an interface-contract API surface. The
+    ``manifest`` carries per-directory content hashes so a downstream consumer can
+    process incrementally. No third-party tool or format is hardcoded.
+    """
+    by_directory = _group_symbols_by_directory(nodes)
+    module_graph = _build_module_graph(nodes, edges)
+    api_surface = _group_endpoints_by_controller(endpoints)
+    containers = _detect_containers(root)
+
+    limitations: "list[str]" = []
+    if not containers:
+        limitations.append(
+            "No build files (Maven/Gradle) found; containers not derived. "
+            "Treat the repository as a single implicit container."
+        )
+
+    return {
+        "schema_version": "c4-v1",
+        "c4": {
+            "context": {
+                "system": {"name": root.name, "file_count": len(file_list)},
+                "external_systems": integrations,
+            },
+            "containers": containers,
+            "components": module_graph,
+            "code": by_directory,
+        },
+        "api_surface": api_surface,
+        "manifest": {
+            "directory_hashes": _directory_hashes(file_list, root),
+            "generated": {
+                "tool": "sourcecode",
+                "schema": "c4-v1",
+                "file_count": len(file_list),
+            },
+        },
+        "limitations": limitations,
+    }
+
+
+@app.command("export")
+def export_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path to export (default: current directory)",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+    by_directory: bool = typer.Option(
+        False, "--by-directory",
+        help="Group symbols by source directory with path:line refs (C4 code-level export).",
+    ),
+    module_graph: bool = typer.Option(
+        False, "--module-graph",
+        help="Emit a module→module dependency graph (C4 container/component level).",
+    ),
+    integrations: bool = typer.Option(
+        False, "--integrations",
+        help="Detect outbound integrations (HTTP/LDAP/JMS clients) with file:line evidence.",
+    ),
+    c4: bool = typer.Option(
+        False, "--c4",
+        help="Unified C4 architecture export (context/containers/components/code) "
+             "+ per-directory incremental manifest. Vendor-neutral.",
+    ),
+) -> None:
+    """Export structured, tool-agnostic codebase views for downstream tooling.
+
+    Output is plain JSON/YAML that any consumer (architecture-doc generators,
+    diagram renderers, code-search agents) can ingest. Section labels map to the
+    open C4 model (an open architecture notation, not a product) but the schema
+    is vendor-neutral.
+
+    \b
+    --by-directory   One group per source directory, each symbol carrying a
+                     path:line reference — the file:line-anchored code map that
+                     lets a consumer proceed by file write instead of per-dir reads.
+    --module-graph   Module→module dependency graph (container/component level)
+                     rolled up from class-level relation edges.
+    --integrations   Outbound integrations (RestTemplate/WebClient/Feign/LDAP/JMS)
+                     with file:line evidence — external-system dependency arrows.
+    --c4             Unified architecture document mapped onto the open C4 model
+                     (context/containers/components/code) + an API surface and a
+                     per-directory content-hash manifest for incremental consumers.
+
+    The section flags compose; pass several to emit multiple sections in one
+    document. --c4 assembles the full architecture export on its own.
+    """
+    from sourcecode.repository_ir import build_repo_ir, find_java_files
+
+    _enforce_format("export", format)
+
+    root = path.resolve()
+    if not root.is_dir():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{root}' is not a valid directory.",
+            path=str(root),
+            hint="Pass an existing repository directory.",
+            expected="A directory path.",
+        )
+        raise typer.Exit(1)
+
+    if not (by_directory or module_graph or integrations or c4):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "export requires a mode flag.",
+            path=str(root),
+            hint="Pass --c4 for the full architecture export, or one of "
+                 "--by-directory / --module-graph / --integrations for a section.",
+            expected="--c4 | --by-directory | --module-graph | --integrations",
+        )
+        raise typer.Exit(1)
+
+    file_list = [
+        f for f in find_java_files(root)
+        if "/test/" not in f and "/tests/" not in f
+    ]
+
+    if c4:
+        # Unified architecture export: assembles every section + manifest.
+        from sourcecode.integration_detector import detect_integrations
+        from sourcecode.repository_ir import extract_java_endpoints
+        ir = build_repo_ir(file_list, root)
+        graph = ir.get("graph", {})
+        endpoints = extract_java_endpoints(root).get("endpoints", [])
+        data = _build_c4_export(
+            root,
+            file_list,
+            graph.get("nodes", []),
+            graph.get("edges", []),
+            endpoints,
+            detect_integrations(file_list, root),
+        )
+        output = _serialize_dict(data, format)
+        _emit_command_output(output, output_path, copy,
+                             success_msg=f"C4 architecture export written to {output_path}")
+        from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+        _nudge()
+        return
+
+    data: "dict" = {}
+    # IR is only needed for the symbol/graph-derived views, not for the
+    # source-scanned integration detector.
+    if by_directory or module_graph:
+        ir = build_repo_ir(file_list, root)
+        graph = ir.get("graph", {})
+        nodes = graph.get("nodes", [])
+        if by_directory:
+            grouped = _group_symbols_by_directory(nodes)
+            data["by_directory"] = grouped
+            data["directory_count"] = len(grouped)
+            data["symbol_count"] = sum(len(v) for v in grouped.values())
+        if module_graph:
+            data["module_graph"] = _build_module_graph(nodes, graph.get("edges", []))
+
+    if integrations:
+        from sourcecode.integration_detector import detect_integrations
+        data["integrations"] = detect_integrations(file_list, root)
+
+    output = _serialize_dict(data, format)
+    _emit_command_output(output, output_path, copy,
+                         success_msg=f"Export written to {output_path}")
+
+    from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+    _nudge()
+
+
 @app.command("validation")
 def validation_cmd(
     path: Path = typer.Argument(

sourcecode/format_contract.py

@@ -27,6 +27,7 @@ FORMAT_REGISTRY: "dict[str, tuple[str, ...]]" = {
     "repo-ir": ("json", "yaml"),
     "impact": ("json", "yaml"),
     "endpoints": ("json", "yaml"),
+    "export": ("json", "yaml"),
     "validation": ("json", "yaml"),
     "impact-chain": ("json", "yaml"),
     "pr-impact": ("text", "json"),

sourcecode/integration_detector.py

@@ -0,0 +1,163 @@
+"""Outgoing-integration detection for the C4/BMB export pipeline.
+
+Scans Java source for *outbound* integration points — the edges a C4 Context
+diagram needs to draw arrows from this system to external systems. Detection is
+deterministic source-text matching (same approach as the JNDI datasource scan in
+``serializer.py``); it never executes code and never resolves runtime values.
+
+Covered clients:
+
+  * HTTP   — ``RestTemplate``, ``WebClient``, ``@FeignClient`` (declarative)
+  * LDAP   — ``LdapTemplate``
+  * JMS    — ``JmsTemplate``, ActiveMQ connection factories
+
+Each hit is reported with a ``file:line`` evidence anchor and, when a literal URL
+or logical name is present on the same construct, a ``target``. URLs assembled at
+runtime (concatenated strings, property placeholders) yield a ``null`` target —
+honest absence rather than a guess.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+# A URL/endpoint literal for any scheme we care about.
+_URL_RE = re.compile(r'"((?:https?|ldaps?|tcp|amqp|jms|nio)://[^"]*)"')
+# First string literal on a line (fallback target, e.g. WebClient.create("x")).
+_STR_RE = re.compile(r'"([^"]+)"')
+
+# Declarative HTTP client. Attrs may span multiple lines, so matched on full text.
+_FEIGN_RE = re.compile(r"@FeignClient\s*\(([^)]*)\)", re.DOTALL)
+_ATTR_URL_RE = re.compile(r'url\s*=\s*"([^"]*)"')
+_ATTR_NAME_RE = re.compile(r'(?:name|value)\s*=\s*"([^"]*)"')
+_FIRST_LITERAL_RE = re.compile(r'^\s*"([^"]*)"')
+
+# token -> (kind, client). Matched as whole-word usage outside imports/comments.
+_TOKEN_CLIENTS: "tuple[tuple[str, str, str], ...]" = (
+    ("RestTemplate", "http", "resttemplate"),
+    ("WebClient", "http", "webclient"),
+    ("LdapTemplate", "ldap", "ldaptemplate"),
+    ("JmsTemplate", "jms", "jmstemplate"),
+    ("ActiveMQConnectionFactory", "jms", "activemq"),
+)
+_TOKEN_RES = tuple(
+    (re.compile(r"\b" + re.escape(tok) + r"\b"), kind, client)
+    for tok, kind, client in _TOKEN_CLIENTS
+)
+
+
+def _line_of(text: str, idx: int) -> int:
+    """1-based line number of character offset ``idx`` in ``text``."""
+    return text.count("\n", 0, idx) + 1
+
+
+def _extract_target(line: str) -> Optional[str]:
+    """Best-effort literal target on a usage line: a scheme URL, else first string."""
+    m = _URL_RE.search(line)
+    if m:
+        return m.group(1)
+    m = _STR_RE.search(line)
+    if m:
+        return m.group(1)
+    return None
+
+
+def detect_integrations(file_paths: "list[str]", root: Path) -> dict:
+    """Detect outbound integrations across ``file_paths`` (relative to ``root``).
+
+    Returns ``{"integrations": [...], "by_kind": {kind: count}, "count": N}`` with
+    integrations sorted by ``(kind, client, evidence)`` for deterministic output.
+    Each integration is ``{kind, client, target, evidence}`` where ``evidence`` is
+    ``relpath:line`` and ``target`` is a literal URL/name or ``None``.
+    """
+    seen: "set[tuple[str, str, Optional[str], str]]" = set()
+    records: "list[dict]" = []
+
+    def _add(kind: str, client: str, target: Optional[str], rel: str, line: int) -> None:
+        evidence = f"{rel}:{line}"
+        key = (kind, client, target, evidence)
+        if key in seen:
+            return
+        seen.add(key)
+        records.append({
+            "kind": kind,
+            "client": client,
+            "target": target,
+            "evidence": evidence,
+        })
+
+    for rel in file_paths:
+        try:
+            text = (root / rel).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        # @FeignClient — capture attrs even when spread across lines.
+        for m in _FEIGN_RE.finditer(text):
+            attrs = m.group(1)
+            url_m = _ATTR_URL_RE.search(attrs)
+            name_m = _ATTR_NAME_RE.search(attrs)
+            first_m = _FIRST_LITERAL_RE.search(attrs)
+            target = (
+                url_m.group(1) if url_m
+                else name_m.group(1) if name_m
+                else first_m.group(1) if first_m
+                else None
+            )
+            _add("http", "feign", target, rel, _line_of(text, m.start()))
+
+        # Token clients — per line, skipping imports/package/comment noise.
+        # First pass records the declaration site and any variable name bound to
+        # the client, so a later call site (where the URL literal usually lives)
+        # can be attributed back to the client.
+        var_to_client: "dict[str, tuple[str, str]]" = {}
+        lines = text.splitlines()
+        for lineno, line in enumerate(lines, start=1):
+            stripped = line.lstrip()
+            if (
+                stripped.startswith("import ")
+                or stripped.startswith("package ")
+                or stripped.startswith("//")
+                or stripped.startswith("*")
+                or stripped.startswith("/*")
+            ):
+                continue
+            for token_re, kind, client in _TOKEN_RES:
+                m = token_re.search(line)
+                if not m:
+                    continue
+                _add(kind, client, _extract_target(line), rel, lineno)
+                tok = m.group(0)
+                # `Type name` (field/local decl) and `name = new Type(` forms.
+                decl = re.search(re.escape(tok) + r"\s+(\w+)\b", line)
+                if decl:
+                    var_to_client[decl.group(1)] = (kind, client)
+                asgn = re.search(r"(\w+)\s*=\s*new\s+" + re.escape(tok), line)
+                if asgn:
+                    var_to_client[asgn.group(1)] = (kind, client)
+
+        # Second pass: a call on a tracked client variable carrying a URL literal
+        # is reported as a hit at the call site (the URL endpoint C4 wants).
+        if var_to_client:
+            for lineno, line in enumerate(lines, start=1):
+                url = _URL_RE.search(line)
+                if not url:
+                    continue
+                for var, (kind, client) in var_to_client.items():
+                    if re.search(r"\b" + re.escape(var) + r"\s*\.", line):
+                        _add(kind, client, url.group(1), rel, lineno)
+                        break
+
+    records.sort(key=lambda r: (r["kind"], r["client"], r["evidence"]))
+
+    by_kind: "dict[str, int]" = {}
+    for r in records:
+        by_kind[r["kind"]] = by_kind.get(r["kind"], 0) + 1
+
+    return {
+        "integrations": records,
+        "by_kind": {k: by_kind[k] for k in sorted(by_kind)},
+        "count": len(records),
+    }

sourcecode/repository_ir.py

@@ -48,6 +48,7 @@ class SymbolRecord:
     symbol_kind: str = ""       # class|interface|enum|annotation|method|constructor|field|endpoint|bean
     canonical_name: str = ""    # pkg.Class#method(Type1,Type2) — human-readable
     source_file: str = ""       # alias for declaring_file (IR output contract)
+    line: Optional[int] = None  # 1-based source line of the declaration
     signature: str = ""         # (Type1,Type2)->ReturnType for methods; type for fields
     param_types: list[str] = field(default_factory=list)
     return_type: str = ""
@@ -696,8 +697,12 @@ def _extract_symbols(
     # here makes the regex work without changing the per-line brace-depth counter.
     _raw_lines = source.splitlines()
     _joined: list[str] = []
+    # Parallel list: 1-based source line where each _joined entry STARTS, so symbol
+    # declarations can carry their source line through the join/normalize transforms.
+    _joined_lines: list[int] = []
     _i = 0
     while _i < len(_raw_lines):
+        _start = _i  # 0-based source index where this joined entry begins
         _line = _raw_lines[_i]
         _stripped = _line.strip()
         if (_CLASS_KW_RE.search(_stripped) and '{' not in _stripped
@@ -713,6 +718,7 @@ def _extract_symbols(
                 if '{' in _cont:
                     break
             _joined.append(_buf)
+            _joined_lines.append(_start + 1)
         elif (
             (_METHOD_DECL_RE.match(_stripped) or _CONSTRUCTOR_DECL_RE.match(_stripped))
             and _net_parens(_stripped) > 0
@@ -731,15 +737,20 @@ def _extract_symbols(
                 _bal += _net_parens(_cont)
                 _i += 1
             _joined.append(_buf)
+            _joined_lines.append(_start + 1)
         else:
             _joined.append(_line)
+            _joined_lines.append(_start + 1)
             _i += 1
 
     # P1 fix: normalize multiline annotations (e.g. @RequestMapping(\n  value="..."\n))
     # into single lines so the per-line regex can capture annotation args correctly.
-    _normalized_lines = _normalize_multiline_annotations(_joined)
+    _normalized_lines, _normalized_src_lines = _normalize_multiline_annotations(
+        _joined, _joined_lines
+    )
 
-    for line in _normalized_lines:
+    for _ni, line in enumerate(_normalized_lines):
+        cur_line = _normalized_src_lines[_ni] if _ni < len(_normalized_src_lines) else None
         stripped = line.strip()
 
         if in_block_comment:
@@ -821,6 +832,7 @@ def _extract_symbols(
                 symbol_kind=sym_kind,
                 canonical_name=fqn,
                 source_file=rel_path,
+                line=cur_line,
                 signature=" ".join(_sig_parts),
                 annotation_values=dict(pending_ann_values),
             ))
@@ -888,6 +900,7 @@ def _extract_symbols(
                         symbol_kind=_sym_kind,
                         canonical_name=_canonical,
                         source_file=rel_path,
+                        line=cur_line,
                         signature=_signature,
                         param_types=_param_types,
                         return_type=_ret_raw,
@@ -923,6 +936,7 @@ def _extract_symbols(
                     symbol_kind="constructor",
                     canonical_name=f"{class_fqn}#{_class_simple}({_param_str})",
                     source_file=rel_path,
+                    line=cur_line,
                     signature=f"({_param_str})->void",
                     param_types=_ctor_param_types,
                     return_type="void",
@@ -958,6 +972,7 @@ def _extract_symbols(
                             symbol_kind="field",
                             canonical_name=fqn,
                             source_file=rel_path,
+                            line=cur_line,
                             signature=f"{ftype} {fname}",
                         ))
                         pending_anns = []
@@ -1514,6 +1529,34 @@ def _build_relations(
                         evidence={"type": "method_call", "value": f"new {_tgt.split('.')[-1]}(...)"},
                     ))
 
+    # ── Static-utility calls: `Type.method(...)` edges (G-2 / static-call gap) ──
+    # A static call `AnnotationHelper.foo(...)` couples the calling class to the
+    # utility type, but the call/DI graph misses it: only an `imports` edge is
+    # recorded (and impact-chain skips imports), so a static helper showed 0
+    # callers and impact-chain reported a false-confident "no blast radius".
+    # Mirror the instantiation scan: regex over comment-stripped source, resolve the
+    # receiver type via the import map (so JDK/unresolved receivers like Math/LOGGER
+    # yield None and are skipped), attribute at class level. Unlike `instantiates`
+    # this INCLUDES controllers — a controller statically calling a utility is a real
+    # caller and has no `returns`-edge overlap. Emitted as `calls` (traversed by the
+    # caller BFS). Instance calls go through lower-case variables and never match.
+    if _class_syms:
+        _call_targets: set[str] = set()
+        for _m in re.finditer(r'\b([A-Z]\w*)\.\w+\s*\(', _source_no_comments):
+            _ct_fqn = _resolve_dep_type(_m.group(1))
+            if _ct_fqn:
+                _call_targets.add(_ct_fqn)
+        for cls_sym in _class_syms:
+            for _tgt in sorted(_call_targets):
+                if _tgt != cls_sym.symbol:
+                    edges.append(RelationEdge(
+                        from_symbol=cls_sym.symbol,
+                        to_symbol=_tgt,
+                        type="calls",
+                        confidence="medium",
+                        evidence={"type": "method_call", "value": f"{_tgt.split('.')[-1]}.…(…)"},
+                    ))
+
     seen: set[tuple[str, str, str]] = set()
     unique: list[RelationEdge] = []
     for e in edges:
@@ -1742,7 +1785,7 @@ def _resolve_ann_path_expr(ann_args: str, constants: dict[str, str]) -> str:
     return ann_args
 
 
-def _normalize_multiline_annotations(lines: list[str]) -> list[str]:
+def _normalize_multiline_annotations(lines, line_nums=None):
     """Merge multiline annotation spans into a single line.
 
     Handles annotations split across lines because their args span multiple lines:
@@ -1754,10 +1797,13 @@ def _normalize_multiline_annotations(lines: list[str]) -> list[str]:
     Merges into: '@RequestMapping(value = "/add", method = RequestMethod.GET)'
     """
     result: list[str] = []
+    result_lines: list[int] = []
     buf: list[str] = []
+    buf_line: Optional[int] = None
     paren_depth = 0
 
-    for line in lines:
+    for _idx, line in enumerate(lines):
+        src_line = line_nums[_idx] if (line_nums is not None and _idx < len(line_nums)) else None
         stripped = line.strip()
         if buf:
             # Continuation of a multiline annotation
@@ -1765,7 +1811,9 @@ def _normalize_multiline_annotations(lines: list[str]) -> list[str]:
             paren_depth += stripped.count("(") - stripped.count(")")
             if paren_depth <= 0:
                 result.append(" ".join(buf))
+                result_lines.append(buf_line if buf_line is not None else (src_line or 0))
                 buf = []
+                buf_line = None
                 paren_depth = 0
         elif stripped.startswith("@") and "(" in stripped:
             opens = stripped.count("(")
@@ -1773,16 +1821,24 @@ def _normalize_multiline_annotations(lines: list[str]) -> list[str]:
             if opens > closes:
                 # Unbalanced — start collecting continuation lines
                 buf = [stripped]
+                buf_line = src_line
                 paren_depth = opens - closes
             else:
                 result.append(line)
+                result_lines.append(src_line or 0)
         else:
             result.append(line)
+            result_lines.append(src_line or 0)
 
     # Flush any dangling buffer (shouldn't happen in well-formed code)
     if buf:
-        result.extend(buf)
-    return result
+        for _bi, _bl in enumerate(buf):
+            result.append(_bl)
+            result_lines.append(buf_line if buf_line is not None else 0)
+
+    if line_nums is None:
+        return result
+    return result, result_lines
 
 
 def _parse_route_path(args_str: str) -> str:
@@ -2615,6 +2671,7 @@ def _assemble(
             "symbol_kind": s.symbol_kind,
             "canonical_name": s.canonical_name or s.symbol,
             "source_file": s.declaring_file,
+            "line": s.line,
             "signature": s.signature,
             "type": s.type,
             "role": spring_role_map.get(s.symbol, "other"),
@@ -2981,6 +3038,7 @@ def _build_route_surface(
                     "effective_class": cls_fqn,
                     "path": full_path,
                     "method": method,
+                    "return_type": (sym.return_type.strip() if sym.return_type else "void"),
                     "stable_id": sym.stable_id,
                     "inheritance_depth": 0,
                 }
@@ -3000,6 +3058,10 @@ def _build_route_surface(
         _parent_sec_by_sym: dict[str, object] = {
             r["symbol"]: r.get("security_annotations") for r in routes
         }
+        # Build lookup for return_type from phase-2 routes (inherited methods reuse parent's)
+        _parent_rt_by_sym: dict[str, str] = {
+            r["symbol"]: r.get("return_type", "void") for r in routes
+        }
 
         for cls_simple, data in class_info.items():
             if not any(data["prefixes"]):
@@ -3038,6 +3100,7 @@ def _build_route_surface(
                                     "effective_class": data["fqn"],
                                     "path": full_path,
                                     "method": verb,
+                                    "return_type": _parent_rt_by_sym.get(declaring_sym, "void"),
                                     "stable_id": stable_id,
                                     "inheritance_depth": depth,
                                     "security_annotations": _parent_sec_by_sym.get(declaring_sym),
@@ -3750,6 +3813,9 @@ def _recover_openapi_spec_routes(
                 "path": op.path,
                 "controller": ctrl_simple,
                 "handler": handler,
+                # Response type is not parsed from the OpenAPI spec (only request
+                # bodies are). "unknown" is honest here — these are spec-sourced.
+                "return_type": "unknown",
                 "source": "openapi-spec",
                 # Security for generated controllers is declared in the spec /
                 # enforced by the filter chain, not by per-endpoint annotations.
@@ -3925,6 +3991,7 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
             "path": route["path"],
             "controller": controller,
             "handler": handler,
+            "return_type": route.get("return_type", "void"),
         }
         # Use security_annotations already extracted by _build_route_surface
         # via the canonical _route_security_from_sym extractor.

sourcecode/spring_impact.py

@@ -872,10 +872,35 @@ class ImpactOrchestrator:
                 "An empty result is NOT proof the type is unused."
             )
 
+        # G-2 residual guard: something imports this symbol but no call/DI/instantiation
+        # edge resolved to it. With static-call edges now extracted, the common static
+        # utility case is covered; this catches what remains (static imports invoked
+        # without a qualifier, reflection, method references) — usages the call-graph
+        # cannot bind. An empty blast radius here is NOT proof of dead code, so it must
+        # not be reported as a high-confidence "safe to change".
+        unresolved_ref_blind_spot = False
+        if (
+            empty_blast
+            and class_level_seed
+            and not framework_di_blind_spot
+            and not value_type_blind_spot
+        ):
+            _rev = cir.reverse_graph.get(resolved_symbol) or {}
+            _importers = sorted(set(_rev.get("imports") or []))
+            if _importers:
+                unresolved_ref_blind_spot = True
+                warnings.append(
+                    f"Unresolved inbound references (G-2): {len(_importers)} in-repo "
+                    "file(s) import this symbol but no call/DI/instantiation edge "
+                    "resolves to it — the usage may be a static import, reflection, or "
+                    "method reference the call-graph does not model. 0 callers is NOT "
+                    "proof this symbol is unused."
+                )
+
         confidence: str
         if resolution == "not_found":
             confidence = "low"
-        elif framework_di_blind_spot or value_type_blind_spot:
+        elif framework_di_blind_spot or value_type_blind_spot or unresolved_ref_blind_spot:
             confidence = "low"
         elif resolution == "partial" or confidence_reducing:
             confidence = "medium"
@@ -908,6 +933,7 @@ class ImpactOrchestrator:
                 "blind_spots": (
                     (["framework_di"] if framework_di_blind_spot else [])
                     + (["value_type"] if value_type_blind_spot else [])
+                    + (["unresolved_refs"] if unresolved_ref_blind_spot else [])
                 ),
                 "external_supertypes": external_supertypes,
             },

{sourcecode-1.51.0.dist-info → sourcecode-1.53.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.51.0
+Version: 1.53.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.50.0-blue)
+![Version](https://img.shields.io/badge/version-1.53.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 ---
@@ -114,7 +114,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.44.0
+# sourcecode 1.53.0
 ```
 
 ---
@@ -364,9 +364,10 @@ sourcecode impact OrderService . --depth 2                 # limit BFS depth
 ```bash
 sourcecode endpoints /path/to/repo
 sourcecode endpoints /path/to/repo --output endpoints.json
+sourcecode endpoints /path/to/repo --by-controller
 ```
 
-Extracts all Spring MVC (`@GetMapping`, `@PostMapping`, `@RequestMapping`, etc.) and JAX-RS (`@GET`, `@POST`, `@Path`) endpoint methods. Returns HTTP method, path, controller class, and handler method.
+Extracts all Spring MVC (`@GetMapping`, `@PostMapping`, `@RequestMapping`, etc.) and JAX-RS (`@GET`, `@POST`, `@Path`) endpoint methods. Returns HTTP method, path, controller class, and handler method. Each endpoint also carries its `return_type`. `--by-controller` groups the surface per controller (`{by_controller, controller_count, total}`) for an API-surface view.
 
 **Functional / WebFlux routing (honest limitation).** Routes registered via the functional DSL — `route().GET("/path", handler)` / `RouterFunction` / `CustomEndpoint`, common in reactive Spring apps — are **not** modeled (their real paths depend on `nest()`/group-version prefixes that can't be resolved statically). Rather than emit partial paths that would mislead, the output reports a `functional_routing` block (`files`, `route_registrations`, `modeled: false`) plus a warning. When the annotation surface is empty but functional routes exist, the warning explicitly tells you not to read it as "no endpoints". Annotation-based (MVC/JAX-RS) repos are unaffected.
 
@@ -387,6 +388,26 @@ Extracts all Spring MVC (`@GetMapping`, `@PostMapping`, `@RequestMapping`, etc.)
 
 Matching endpoints then report `policy: "custom"` with `annotation`, `resourceName`, and `requiredLevel`, and are no longer counted in `no_security_signal`. Repos without the config behave exactly as before.
 
+### `export` — architecture views for downstream tooling
+
+```bash
+sourcecode export /path/to/repo --by-directory      # code map, path:line refs
+sourcecode export /path/to/repo --module-graph       # module→module dependencies
+sourcecode export /path/to/repo --integrations       # outbound HTTP/LDAP/JMS clients
+sourcecode export /path/to/repo --c4                  # unified architecture + manifest
+```
+
+Emits **structured, tool-agnostic** codebase views as plain JSON/YAML — the kind of input an architecture-doc generator, diagram renderer, or code-search agent can consume directly instead of walking the tree file by file. Section labels map to the open [C4 model](https://c4model.com) (an open architecture notation, not a product); the schema is vendor-neutral.
+
+| Flag | Output |
+|------|--------|
+| `--by-directory` | One group per source directory, each symbol with a `source_file:line` reference. |
+| `--module-graph` | `{nodes, edges, summary}` — directories as modules, inter-module dependencies rolled up from class-level relation edges with hit counts + edge types. |
+| `--integrations` | Outbound integrations (`RestTemplate`, `WebClient`, `@FeignClient`, `LdapTemplate`, `JmsTemplate`, ActiveMQ) with `file:line` evidence and a literal `target` URL/name when present. |
+| `--c4` | Unified document: `c4.{context, containers, components, code}` + `api_surface` + a `manifest` with per-directory content hashes for **incremental** consumers (skip directories whose hash is unchanged). |
+
+The section flags compose (pass several for one multi-section document); `--c4` assembles the full export on its own. URLs assembled at runtime yield `target: null` (honest absence, never a guess); containers are derived from build files (Maven/Gradle) and reported as a limitation when none are found.
+
 ### `spring-audit` — Spring semantic audit [free]
 
 ```bash

{sourcecode-1.51.0.dist-info → sourcecode-1.53.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=_wGmSIirvZbvcf9uQNlNJs_jaX8mbucBaAgRR5jo_YA,103
+sourcecode/__init__.py,sha256=iHGCfyboU5livWODKEj-u8oT6BwJInerv6YHn28vXno,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=liCwQmLgb5vplohy8arjYxs_HOIv5C9MjLh_gY6bc5Q,44115
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
@@ -7,7 +7,7 @@ sourcecode/cache.py,sha256=1V3vsaODAa2UBJAC0xpvxpmRdriCezQx5Q8JCcfgziE,31892
 sourcecode/canonical_ir.py,sha256=DEwucOPJguLsVtg5cV8mWXNi112l5jmBhv73KGGebVk,24849
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=hKzg-nQ47htqqIUzSGvYxv15cXrA3KgICTwJmdqal0o,8095
-sourcecode/cli.py,sha256=ne0Ok-IYVn5-_sg4XLm5CS6jn58z78RezFbc9DOdOFE,257430
+sourcecode/cli.py,sha256=IZ_TcUzd-rUFoIYMgkOcGP-FqiYoOGPxZ3sjPkEp4OM,272648
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -24,10 +24,11 @@ sourcecode/explain.py,sha256=dVG35YBlpRmbtOXSmspEhoIwDMVApPmLISBy3iigUSc,16913
 sourcecode/file_chunker.py,sha256=3vkM3mDQ5eE_yTPvUgjyjpGFBIjkW6_mrBmIbrylnA8,16444
 sourcecode/file_classifier.py,sha256=A0fEABqtfVu1MfoaxnPAvGpZgneGgVXlJDhT74NYXxE,15314
 sourcecode/flow_analyzer.py,sha256=dSiuY4w49k29jW_EPXUOND9B5uVbuCA7kjnuHi-pIWA,28781
-sourcecode/format_contract.py,sha256=7iCFqUVAR9R-NS1HVoccV2-prAbBv_IAQNHejP2zdJs,3434
+sourcecode/format_contract.py,sha256=1cTNqwP8geA2hbQoBHUPgX3_vSh3l8guJT_jmgEnFF8,3466
 sourcecode/fqn_utils.py,sha256=XLU7zDkNBXz_RZkIUNfpPmp1nekWtqP-fxV92tDV1vg,2158
 sourcecode/git_analyzer.py,sha256=JStxTQXNjBWi_wLdwhsZs9mT-v50cSJIz4Agzn6Kh9I,13362
 sourcecode/graph_analyzer.py,sha256=DHR8fY69oU_Pi4SYaWboX6EoEFrctQKB9dsjpqwGMzw,62403
+sourcecode/integration_detector.py,sha256=ZJqrGwvZ4ee2JTGhlazKk67aZi173HxkhNpl8Yntpd8,6503
 sourcecode/license.py,sha256=i_X1bYdobL_z9OVuLiycnWEFSaaNhcKKuTd6G55U3_k,20747
 sourcecode/mcp_nudge.py,sha256=5ELU_ixzh6uA83NXLOZT8h00OhL53okfQdji3jyKOjg,2917
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
@@ -44,7 +45,7 @@ sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
-sourcecode/repository_ir.py,sha256=eBC8Jh1rBH8xE46atHmdGNQxcjuROyUCr0iCuhqviUc,210340
+sourcecode/repository_ir.py,sha256=n1H0OROkD1dHvpWAtDoYNHGlTkVhQpYIFqIQ3jf3mgs,214101
 sourcecode/ris.py,sha256=RcqLVwC-doFcKKViYDkCjZLBqf_wzLES7-F6vHEeWzE,20419
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
@@ -54,7 +55,7 @@ sourcecode/semantic_analyzer.py,sha256=4OdG6tTSnTvq3_dSWMbQu8Ad1ndSCKeG-b9qM4hIx
 sourcecode/serializer.py,sha256=TGzftrSKitZrtl6Hh-R05s4KdTOxwTmph_lGDbo2Wzg,125015
 sourcecode/spring_event_topology.py,sha256=5_ON_21Le5zbG-1GRc5GLIi5HJfy_QjcXLVPC5WeUGQ,18055
 sourcecode/spring_findings.py,sha256=G7Or2lKBUQbcTDqudLvSs9XvNg_YoAa-_lBOG_ULs8E,5457
-sourcecode/spring_impact.py,sha256=WUbBw6Ne9esN_KczIs9BCJdRAmjDKtU6E2_auo-771s,44865
+sourcecode/spring_impact.py,sha256=5ooAVO-gg1rL-wRaT9_V8ra8edq5TAKu-kp4sAEoS_U,46343
 sourcecode/spring_model.py,sha256=zOAgFmrRbG4a6KLm1TJl55aWMyPNsz3OS3FSczqPG6A,16594
 sourcecode/spring_security_audit.py,sha256=XtPJ1SXlZJ8k6VYmaWuAp7Bbir4UmreAL7doIGQ5I7o,20595
 sourcecode/spring_semantic.py,sha256=O1nKSGVzlukuxLHQVuCPxc-XrcrMFxwlHA20_dmEGgM,13307
@@ -101,8 +102,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
 sourcecode/telemetry/filters.py,sha256=NHa5T-6DaZduQPFuC34jOqHWQgSizM-Ygq8aZ4j19ng,5834
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-1.51.0.dist-info/METADATA,sha256=v-FRo1rN-BioZGvKK-WIC7mT3R-q3lQvXqyBXYj0s4U,34684
-sourcecode-1.51.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.51.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.51.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.51.0.dist-info/RECORD,,
+sourcecode-1.53.0.dist-info/METADATA,sha256=Ahvq7n0P2M28DyG8mqksS-g11VTDnqDCjdPSZ23NjH0,36719
+sourcecode-1.53.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.53.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.53.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.53.0.dist-info/RECORD,,