sourcecode 1.35.13__tar.gz → 1.35.14__tar.gz

{sourcecode-1.35.13 → sourcecode-1.35.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.35.13
+Version: 1.35.14
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -39,7 +39,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.35.13-blue)
+![Version](https://img.shields.io/badge/version-1.35.14-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -113,7 +113,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.35.13
+# sourcecode 1.35.14
 ```
 
 ---

{sourcecode-1.35.13 → sourcecode-1.35.14}/README.md

@@ -2,7 +2,7 @@
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.35.13-blue)
+![Version](https://img.shields.io/badge/version-1.35.14-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -76,7 +76,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.35.13
+# sourcecode 1.35.14
 ```
 
 ---

{sourcecode-1.35.13 → sourcecode-1.35.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.35.13"
+version = "1.35.14"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.35.13 → sourcecode-1.35.14}/src/sourcecode/__init__.py

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

{sourcecode-1.35.13 → sourcecode-1.35.14}/src/sourcecode/cli.py

@@ -229,6 +229,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "impact-chain",
         # PR blast-radius report
         "pr-impact",
+        # Class architectural summary
+        "explain",
     }
 )
 
@@ -4179,6 +4181,121 @@ def pr_impact_cmd(
                 typer.echo("✓ copied to clipboard", err=True)
 
 
+# ── Explain Command ───────────────────────────────────────────────────────────
+
+@app.command("explain")
+def explain_cmd(
+    class_name: str = typer.Argument(
+        ...,
+        help="Simple class name to explain (e.g. UserService, OrderController).",
+    ),
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository root (default: current directory)",
+    ),
+    format: str = typer.Option(
+        "text", "--format", "-f",
+        help="Output format: text (default) or json.",
+        show_default=True,
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to clipboard after a successful run.",
+    ),
+) -> None:
+    """Human-readable architectural summary for a class.
+
+    \b
+    Generates a structured explanation derived entirely from static analysis:
+      - Purpose and Spring stereotype
+      - Public methods
+      - Incoming callers (who uses this class)
+      - Outgoing dependencies (what this class calls)
+      - Events published and consumed
+      - @Transactional boundaries
+      - Security constraints (@PreAuthorize, @Secured, etc.)
+      - REST endpoints related
+
+    \b
+    JAVA/SPRING ONLY. Reads from existing CIR — no new parsers.
+
+    \b
+    Examples:
+      sourcecode explain UserService
+      sourcecode explain OrderController /path/to/repo
+      sourcecode explain UserService --format json
+    """
+    import json as _json
+
+    from sourcecode.repository_ir import find_java_files
+    from sourcecode.canonical_ir import build_canonical_ir
+    from sourcecode.spring_model import SpringSemanticModel
+    from sourcecode.explain import explain_class
+
+    target = path.resolve()
+    if not target.exists() or not target.is_dir():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+            hint="Pass an existing repository directory.",
+            expected="A directory path.",
+        )
+        raise typer.Exit(code=1)
+
+    if format not in ("text", "json"):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"Invalid format '{format}'.",
+            hint="format must be: text or json.",
+            expected="text | json",
+        )
+        raise typer.Exit(code=1)
+
+    file_list = find_java_files(target)
+    if not file_list:
+        msg = f"No Java files found in '{target}'. sourcecode explain requires a Java/Spring repository."
+        if format == "json":
+            output = _json.dumps({
+                "error": "no_java_files",
+                "message": msg,
+                "class_name": class_name,
+            }, indent=2)
+        else:
+            output = msg
+        if output_path is not None:
+            output_path.write_text(output, encoding="utf-8")
+        else:
+            sys.stdout.buffer.write(output.encode("utf-8"))
+            sys.stdout.buffer.write(b"\n")
+            sys.stdout.buffer.flush()
+        raise typer.Exit(code=1)
+
+    cir = build_canonical_ir(file_list, target)
+    model = SpringSemanticModel.build(cir)
+    explanation = explain_class(class_name, cir, model)
+
+    if format == "json":
+        output = _json.dumps(explanation.to_dict(), indent=2, ensure_ascii=False)
+    else:
+        output = explanation.render_text()
+
+    if output_path is not None:
+        output_path.write_text(output, encoding="utf-8")
+        typer.echo(f"Explanation written to {output_path}", err=True)
+    else:
+        sys.stdout.buffer.write(output.encode("utf-8"))
+        sys.stdout.buffer.write(b"\n")
+        sys.stdout.buffer.flush()
+
+    if copy and _copy_to_clipboard(output):
+        typer.echo("✓ copied to clipboard", err=True)
+
+
 # ── Enterprise Workflow Commands ──────────────────────────────────────────────
 #
 # These are the five canonical enterprise workflows.  Each is a thin wrapper

sourcecode-1.35.14/src/sourcecode/explain.py

@@ -0,0 +1,483 @@
+"""explain.py — Human-readable architectural summary for a Java class.
+
+Usage:
+    cir = build_canonical_ir(find_java_files(root), root)
+    model = SpringSemanticModel.build(cir)
+    result = explain_class("UserService", cir, model)
+    print(result.render_text())
+
+Derives all data from existing CIR + SpringSemanticModel — no new parsers.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+    from sourcecode.spring_model import SpringSemanticModel
+
+
+_STEREOTYPE_DESC: dict[str, str] = {
+    "service": "Spring @Service — business logic layer",
+    "repository": "Spring @Repository — data access layer",
+    "controller": "Spring @Controller — MVC request handler",
+    "restcontroller": "Spring @RestController — REST request handler",
+    "component": "Spring @Component — general-purpose bean",
+    "configuration": "Spring @Configuration — bean factory / config",
+    "bean": "Spring @Bean — managed component",
+}
+
+_SECURITY_ANNOTATION_PREFIXES = (
+    "@PreAuthorize", "@PostAuthorize", "@Secured", "@RolesAllowed",
+    "@PermitAll", "@DenyAll",
+)
+
+_DEFAULT_PROPAGATION = "REQUIRED"
+
+
+def _simple(fqn: str) -> str:
+    """pkg.Foo#bar → Foo#bar; pkg.Foo → Foo."""
+    if "." not in fqn and "#" not in fqn:
+        return fqn
+    # Strip package prefix before simple class name
+    if "#" in fqn:
+        cls_part, method = fqn.rsplit("#", 1)
+        return f"{cls_part.rsplit('.', 1)[-1]}#{method}"
+    return fqn.rsplit(".", 1)[-1]
+
+
+def _method_name(fqn: str) -> str:
+    """pkg.Foo#bar → bar."""
+    return fqn.rsplit("#", 1)[-1] if "#" in fqn else fqn
+
+
+# ---------------------------------------------------------------------------
+# Output model
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ClassExplanation:
+    """Structured architectural summary for a single class."""
+
+    class_name: str
+    class_fqn: str
+    stereotype: str
+    purpose: str
+    public_methods: list[str] = field(default_factory=list)
+    incoming_callers: list[str] = field(default_factory=list)
+    outgoing_deps: list[str] = field(default_factory=list)
+    events_published: list[str] = field(default_factory=list)
+    events_consumed: list[str] = field(default_factory=list)
+    transactions: list[str] = field(default_factory=list)
+    security_constraints: list[str] = field(default_factory=list)
+    rest_endpoints: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def render_text(self) -> str:
+        lines: list[str] = [f"## {self.class_name}", ""]
+
+        if self.class_fqn != self.class_name:
+            lines += [f"**FQN:** `{self.class_fqn}`", ""]
+
+        lines += ["**Purpose:**", self.purpose, ""]
+
+        def _section(title: str, items: list[str]) -> None:
+            if not items:
+                return
+            lines.append(f"**{title}:**")
+            for item in items:
+                lines.append(f"* {item}")
+            lines.append("")
+
+        _section("Public Methods", self.public_methods)
+        _section("Used By", self.incoming_callers)
+        _section("Calls", self.outgoing_deps)
+        _section("Publishes", self.events_published)
+        _section("Consumes", self.events_consumed)
+        _section("Transactions", self.transactions)
+        _section("Security", self.security_constraints)
+        _section("REST Endpoints", self.rest_endpoints)
+        _section("Warnings", self.warnings)
+
+        return "\n".join(lines).rstrip()
+
+    def to_dict(self) -> dict:
+        return {
+            "class_name": self.class_name,
+            "class_fqn": self.class_fqn,
+            "stereotype": self.stereotype,
+            "purpose": self.purpose,
+            "public_methods": self.public_methods,
+            "incoming_callers": self.incoming_callers,
+            "outgoing_deps": self.outgoing_deps,
+            "events_published": self.events_published,
+            "events_consumed": self.events_consumed,
+            "transactions": self.transactions,
+            "security_constraints": self.security_constraints,
+            "rest_endpoints": self.rest_endpoints,
+            "warnings": self.warnings,
+        }
+
+
+# ---------------------------------------------------------------------------
+# FQN resolution
+# ---------------------------------------------------------------------------
+
+def _resolve_fqn(class_name: str, cir: "CanonicalRepositoryIR") -> tuple[str, list[str]]:
+    """Find all class FQNs matching simple class_name in cir.symbols.
+
+    Returns (best_fqn, all_matches).
+    best_fqn is empty string when no match found.
+    """
+    suffix_dot = f".{class_name}"
+    suffix_hash = f"{class_name}#"
+    matches: list[str] = []
+
+    for sym in (getattr(cir, "symbols", None) or []):
+        if not isinstance(sym, str):
+            continue
+        if "#" in sym:
+            continue  # method symbol — skip
+        # Exact match or package-qualified match
+        if sym == class_name or sym.endswith(suffix_dot):
+            matches.append(sym)
+
+    # Also scan raw_ir graph nodes for class symbols (more reliable for kind)
+    raw_nodes = _get_raw_nodes(cir)
+    node_fqns: set[str] = set()
+    for node in raw_nodes:
+        fqn = node.get("fqn") or ""
+        if "#" in fqn:
+            continue
+        kind = node.get("symbol_kind") or node.get("type") or ""
+        if kind not in ("class", "interface", "enum", "annotation", ""):
+            continue
+        if fqn == class_name or fqn.endswith(suffix_dot):
+            node_fqns.add(fqn)
+
+    # Merge — prefer node_fqns when available
+    all_fqns = list(dict.fromkeys(list(node_fqns) + matches))
+
+    if not all_fqns:
+        return "", []
+    return all_fqns[0], all_fqns
+
+
+def _get_raw_nodes(cir: "CanonicalRepositoryIR") -> list[dict]:
+    raw_ir = getattr(cir, "_raw_ir", None) or {}
+    return (raw_ir.get("graph") or {}).get("nodes") or []
+
+
+# ---------------------------------------------------------------------------
+# Section builders
+# ---------------------------------------------------------------------------
+
+def _build_purpose(
+    class_fqn: str,
+    raw_nodes: list[dict],
+    stereotype: str,
+    cir: "CanonicalRepositoryIR",
+    model: "SpringSemanticModel",
+) -> str:
+    # Collect class-level annotations from raw_ir node
+    class_anns: list[str] = []
+    parent_sig = ""
+    for node in raw_nodes:
+        if node.get("fqn") == class_fqn:
+            class_anns = node.get("annotations") or []
+            break
+
+    # Inheritance
+    parent_sig = model.inheritance.immediate_parent(class_fqn)
+
+    # Base description from stereotype
+    desc = _STEREOTYPE_DESC.get(stereotype, "")
+
+    # Enrich with class-level @Transactional
+    tx_class = model.tx_index.class_level.get(class_fqn)
+    if tx_class:
+        desc = f"{desc}. Class-level @Transactional ({tx_class.propagation})" if desc else f"@Transactional ({tx_class.propagation})"
+
+    # Enrich with parent
+    if parent_sig:
+        parent_simple = _simple(parent_sig.split("<")[0])
+        if desc:
+            desc = f"{desc}. Extends {parent_simple}"
+        else:
+            desc = f"Extends {parent_simple}"
+
+    # Fallback: derive from annotations present
+    if not desc:
+        role_anns = [a for a in class_anns if a in (
+            "@Service", "@Repository", "@Controller", "@RestController",
+            "@Component", "@Configuration",
+        )]
+        if role_anns:
+            desc = f"{role_anns[0]} bean"
+
+    return desc or "No stereotype detected — may be a plain class or utility."
+
+
+def _build_public_methods(class_fqn: str, raw_nodes: list[dict]) -> list[str]:
+    """Return public method names for class_fqn from raw_ir nodes."""
+    prefix = class_fqn + "#"
+    methods: list[str] = []
+    for node in raw_nodes:
+        fqn = node.get("fqn") or ""
+        if not fqn.startswith(prefix):
+            continue
+        kind = node.get("symbol_kind") or node.get("type") or ""
+        if kind not in ("method", "endpoint", "constructor", ""):
+            continue
+        modifiers: list[str] = node.get("modifiers") or []
+        if "public" not in modifiers and "protected" not in modifiers:
+            continue
+        method_name = fqn[len(prefix):]
+        if method_name and not method_name.startswith("<"):
+            methods.append(method_name)
+    return sorted(set(methods))
+
+
+def _build_callers(class_fqn: str, cir: "CanonicalRepositoryIR") -> list[str]:
+    """DI dependents + reverse call graph callers, deduplicated, simple names."""
+    seen: set[str] = set()
+    result: list[str] = []
+
+    # DI injection dependents
+    for fqn in (getattr(cir, "injection_graph", None) and cir.injection_graph.dependents_of(class_fqn) or []):
+        s = _simple(fqn)
+        if s not in seen:
+            seen.add(s)
+            result.append(s)
+
+    # Direct call reverse graph: reverse_graph[target] → {type → [callers]}
+    rev: dict = (getattr(cir, "reverse_graph", None) or {}).get(class_fqn) or {}
+    for callers in rev.values():
+        for caller_fqn in (callers or []):
+            # Strip method part to get class
+            cls_fqn = caller_fqn.rsplit("#", 1)[0] if "#" in caller_fqn else caller_fqn
+            if cls_fqn == class_fqn:
+                continue
+            s = _simple(cls_fqn)
+            if s not in seen:
+                seen.add(s)
+                result.append(s)
+
+    return result
+
+
+def _build_deps(class_fqn: str, cir: "CanonicalRepositoryIR") -> list[str]:
+    """DI injected dependencies, simple names."""
+    deps = (getattr(cir, "injection_graph", None) and cir.injection_graph.dependencies_of(class_fqn) or [])
+    return sorted({_simple(d) for d in deps})
+
+
+def _build_events_published(class_fqn: str, model: "SpringSemanticModel") -> list[str]:
+    """Event types published by this class (any method of the class)."""
+    prefix = class_fqn + "#"
+    result: list[str] = []
+    for event_type, publishers in model.event_graph.publishers.items():
+        for pub in publishers:
+            if pub == class_fqn or pub.startswith(prefix):
+                result.append(_simple(event_type))
+                break
+    return sorted(set(result))
+
+
+def _build_events_consumed(class_fqn: str, model: "SpringSemanticModel") -> list[str]:
+    """Event types consumed/listened by this class."""
+    prefix = class_fqn + "#"
+    result: list[str] = []
+    for event_type, listeners in model.event_graph.listeners.items():
+        for lst in listeners:
+            if lst == class_fqn or lst.startswith(prefix):
+                result.append(_simple(event_type))
+                break
+    return sorted(set(result))
+
+
+def _build_transactions(class_fqn: str, model: "SpringSemanticModel") -> list[str]:
+    """Transaction boundaries for this class."""
+    result: list[str] = []
+
+    # Class-level
+    cls_tx = model.tx_index.class_level.get(class_fqn)
+    if cls_tx:
+        label = f"@Transactional (class-level, {cls_tx.propagation})"
+        if cls_tx.read_only:
+            label += ", readOnly"
+        result.append(label)
+
+    # Method-level
+    for boundary in (model.tx_index.by_class.get(class_fqn) or []):
+        method = _method_name(boundary.symbol)
+        label = method + "()"
+        extras: list[str] = []
+        if boundary.propagation != _DEFAULT_PROPAGATION:
+            extras.append(boundary.propagation)
+        if boundary.read_only:
+            extras.append("readOnly")
+        if extras:
+            label += f" [{', '.join(extras)}]"
+        result.append(label)
+
+    return result
+
+
+def _build_security(
+    class_fqn: str,
+    raw_nodes: list[dict],
+    cir: "CanonicalRepositoryIR",
+) -> list[str]:
+    """Security annotations from method-level nodes + cir.security_index."""
+    seen: set[str] = set()
+    result: list[str] = []
+
+    prefix = class_fqn + "#"
+
+    # From cir.security_index (handler_symbol → CanonicalSecurity)
+    for handler_sym, sec in (getattr(cir, "security_index", None) or {}).items():
+        if not (handler_sym == class_fqn or handler_sym.startswith(prefix)):
+            continue
+        policy = getattr(sec, "policy", "") or ""
+        roles = getattr(sec, "roles", []) or []
+        method = _method_name(handler_sym)
+        if roles:
+            label = f"{method}(): {policy} ({', '.join(roles)})"
+        else:
+            label = f"{method}(): {policy}"
+        if label not in seen:
+            seen.add(label)
+            result.append(label)
+
+    # From raw_ir method annotations
+    for node in raw_nodes:
+        fqn = node.get("fqn") or ""
+        if not fqn.startswith(prefix):
+            continue
+        anns: list[str] = node.get("annotations") or []
+        for ann in anns:
+            if any(ann.startswith(p) for p in _SECURITY_ANNOTATION_PREFIXES):
+                method = _method_name(fqn)
+                label = f"{method}(): {ann}"
+                if label not in seen:
+                    seen.add(label)
+                    result.append(label)
+
+    return result
+
+
+def _build_endpoints(class_fqn: str, model: "SpringSemanticModel") -> list[str]:
+    """REST endpoints declared on this controller class."""
+    endpoints = model.endpoint_index.endpoints_for(class_fqn)
+    result: list[str] = []
+    for ep in endpoints:
+        method = getattr(ep, "method", "") or "?"
+        path = getattr(ep, "path", "") or "?"
+        result.append(f"{method} {path}")
+    return sorted(set(result))
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def explain_class(
+    class_name: str,
+    cir: "CanonicalRepositoryIR",
+    model: "SpringSemanticModel",
+) -> ClassExplanation:
+    """Build a ClassExplanation for class_name from existing CIR + model.
+
+    Never raises — wraps all derivation in try/except.
+    """
+    warnings: list[str] = []
+
+    try:
+        class_fqn, all_matches = _resolve_fqn(class_name, cir)
+    except Exception:
+        class_fqn, all_matches = "", []
+
+    if not class_fqn:
+        return ClassExplanation(
+            class_name=class_name,
+            class_fqn=class_name,
+            stereotype="unknown",
+            purpose="Class not found in repository symbols.",
+            warnings=[f"'{class_name}' not found in CIR symbols. Is this a Java/Kotlin repo?"],
+        )
+
+    if len(all_matches) > 1:
+        warnings.append(
+            f"Ambiguous: {len(all_matches)} classes named '{class_name}'. "
+            f"Showing first: {class_fqn}"
+        )
+
+    raw_nodes = _get_raw_nodes(cir)
+
+    try:
+        stereotype = model.bean_graph.get_stereotype(class_fqn) or "unknown"
+    except Exception:
+        stereotype = "unknown"
+
+    try:
+        purpose = _build_purpose(class_fqn, raw_nodes, stereotype, cir, model)
+    except Exception:
+        purpose = f"{stereotype} class"
+
+    try:
+        public_methods = _build_public_methods(class_fqn, raw_nodes)
+    except Exception:
+        public_methods = []
+
+    try:
+        incoming_callers = _build_callers(class_fqn, cir)
+    except Exception:
+        incoming_callers = []
+
+    try:
+        outgoing_deps = _build_deps(class_fqn, cir)
+    except Exception:
+        outgoing_deps = []
+
+    try:
+        events_published = _build_events_published(class_fqn, model)
+    except Exception:
+        events_published = []
+
+    try:
+        events_consumed = _build_events_consumed(class_fqn, model)
+    except Exception:
+        events_consumed = []
+
+    try:
+        transactions = _build_transactions(class_fqn, model)
+    except Exception:
+        transactions = []
+
+    try:
+        security_constraints = _build_security(class_fqn, raw_nodes, cir)
+    except Exception:
+        security_constraints = []
+
+    try:
+        rest_endpoints = _build_endpoints(class_fqn, model)
+    except Exception:
+        rest_endpoints = []
+
+    return ClassExplanation(
+        class_name=class_name,
+        class_fqn=class_fqn,
+        stereotype=stereotype,
+        purpose=purpose,
+        public_methods=public_methods,
+        incoming_callers=incoming_callers,
+        outgoing_deps=outgoing_deps,
+        events_published=events_published,
+        events_consumed=events_consumed,
+        transactions=transactions,
+        security_constraints=security_constraints,
+        rest_endpoints=rest_endpoints,
+        warnings=warnings,
+    )