sourcecode 0.42.0__tar.gz → 0.43.0__tar.gz

{sourcecode-0.42.0 → sourcecode-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.42.0
+Version: 0.43.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004

{sourcecode-0.42.0 → sourcecode-0.43.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "0.42.0"
+version = "0.43.0"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-0.42.0 → sourcecode-0.43.0}/src/sourcecode/__init__.py

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

{sourcecode-0.42.0 → sourcecode-0.43.0}/src/sourcecode/cli.py

@@ -181,6 +181,7 @@ _OPTIONS_WITH_VALUE: frozenset[str] = frozenset({
     "--dependency-depth",
     "--rank-by",
     "--symbol",
+    "--max-importers",
 })
 
 
@@ -594,6 +595,17 @@ def main(
         "--symbol",
         help="Contract mode: extract localized context for a specific symbol name. Returns defining file + all importers.",
     ),
+    max_importers: int = typer.Option(
+        50,
+        "--max-importers",
+        help=(
+            "Maximum importer files returned by --symbol (default: 50). "
+            "Popular symbols can have hundreds of importers — this prevents output explosion. "
+            "Defining files are never truncated. Override: --symbol Foo --max-importers 200."
+        ),
+        min=1,
+        max=10000,
+    ),
     copy: bool = typer.Option(
         False,
         "--copy",
@@ -770,6 +782,21 @@ def main(
         code_notes = True
         no_tree = True  # agents never need the raw file tree
         typer.echo("[agent] dependencies env-map code-notes (no-tree)", err=True)
+        # Warn about flags that are computed but excluded from agent_view output
+        _agent_suppressed: list[str] = []
+        if full_metrics:
+            _agent_suppressed.append("--full-metrics")
+        if graph_modules:
+            _agent_suppressed.append("--graph-modules")
+        if docs:
+            _agent_suppressed.append("--docs")
+        if _agent_suppressed:
+            typer.echo(
+                f"[agent] warning: {', '.join(_agent_suppressed)} computed but excluded "
+                "from --agent output — agent_view does not include these sections. "
+                "Remove these flags to skip unnecessary computation.",
+                err=True,
+            )
 
     scanner = AdaptiveScanner(target, topology=_topology, base_depth=effective_depth)
     raw_tree = scanner.scan_tree()
@@ -1343,6 +1370,7 @@ def main(
             changed_only=changed_only,
             symbol=symbol,
             compress_types=compress_types,
+            max_importers=max_importers,
         )
         sm = _replace(sm, file_contracts=_contracts, contract_summary=_contract_summary)
         if symbol is not None and len(_contracts) == 0:

{sourcecode-0.42.0 → sourcecode-0.43.0}/src/sourcecode/contract_model.py

@@ -109,3 +109,4 @@ class ContractSummary:
     method_breakdown: dict[str, int] = field(default_factory=dict)
     ranked_by: str = "relevance"
     limitations: list[str] = field(default_factory=list)
+    symbol_truncation: Optional[dict] = None  # set when --symbol truncates importers

{sourcecode-0.42.0 → sourcecode-0.43.0}/src/sourcecode/contract_pipeline.py

@@ -175,6 +175,7 @@ class ContractPipeline:
         changed_only: bool = False,
         symbol: Optional[str] = None,
         compress_types: bool = False,
+        max_importers: int = 50,
     ) -> tuple[list[FileContract], ContractSummary]:
         """Run the full extraction pipeline.
 
@@ -279,17 +280,19 @@ class ContractPipeline:
         contracts = self._rank(contracts, rank_by)
 
         # 8. Symbol filter — keep files that define or import the symbol
+        _symbol_truncation: Optional[dict] = None
         if symbol:
-            contracts = _filter_by_symbol(contracts, symbol)
+            contracts, _symbol_truncation = _filter_by_symbol(contracts, symbol, max_importers=max_importers)
             # When shallow scan missed the defining file (deep monorepo), fall back
             # to a grep-based filesystem search over the full directory tree.
             if not contracts:
-                contracts = self._symbol_deep_scan(
+                contracts, _symbol_truncation = self._symbol_deep_scan(
                     root, symbol,
                     known_paths=set(src_paths),
                     entry_paths=entry_paths,
                     changed_files=changed_files,
                     engine=engine,
+                    max_importers=max_importers,
                 )
 
         # 9. Entrypoints-only filter
@@ -313,6 +316,7 @@ class ContractPipeline:
             method_breakdown=dict(method_counts),
             ranked_by=rank_by,
             limitations=limitations,
+            symbol_truncation=_symbol_truncation,
         )
         return contracts, summary
 
@@ -332,7 +336,8 @@ class ContractPipeline:
         entry_paths: set[str],
         changed_files: set[str],
         engine: RankingEngine,
-    ) -> list[FileContract]:
+        max_importers: int = 50,
+    ) -> tuple[list[FileContract], dict]:
         """Grep-based fallback when the shallow scan missed the defining files.
 
         Searches the full directory tree for source files containing *symbol*,
@@ -356,7 +361,7 @@ class ContractPipeline:
             contract.ranking_reasons = fs.reasons
             extra.append(contract)
 
-        return _filter_by_symbol(extra, symbol)
+        return _filter_by_symbol(extra, symbol, max_importers=max_importers)
 
 
 # ---------------------------------------------------------------------------
@@ -412,7 +417,11 @@ def _limit_symbols(contracts: list[FileContract], max_symbols: int) -> list[File
 # Symbol-aware filter
 # ---------------------------------------------------------------------------
 
-def _filter_by_symbol(contracts: list[FileContract], symbol: str) -> list[FileContract]:
+def _filter_by_symbol(
+    contracts: list[FileContract],
+    symbol: str,
+    max_importers: int = 50,
+) -> tuple[list[FileContract], dict]:
     """Return contracts that define, import, or structurally reference *symbol*.
 
     Four tiers applied in order:
@@ -423,6 +432,8 @@ def _filter_by_symbol(contracts: list[FileContract], symbol: str) -> list[FileCo
        function signatures (word-boundary). Only used when tiers 1-3 fail.
 
     Defining contracts are ranked first; importers and references follow.
+    max_importers caps tier 3 results to prevent output explosion on popular symbols.
+    Returns (contracts, truncation_metadata).
     """
     sym_l = symbol.lower()
     word_re = re.compile(
@@ -466,8 +477,14 @@ def _filter_by_symbol(contracts: list[FileContract], symbol: str) -> list[FileCo
 
     # Tier 3: import matching (case-insensitive when no definers found)
     ci_imports = len(defining) == 0
-    importer_paths = {c.path for c in contracts if _imports_sym(c, case=ci_imports)}
-    importers = [c for c in contracts if c.path in importer_paths and c.path not in defining_paths]
+    all_importer_paths = {c.path for c in contracts if _imports_sym(c, case=ci_imports)}
+    all_importers = [c for c in contracts if c.path in all_importer_paths and c.path not in defining_paths]
+
+    # Apply importer cap — definers are never truncated
+    total_importers = len(all_importers)
+    truncated = total_importers > max_importers
+    importers = all_importers[:max_importers] if truncated else all_importers
+    importer_paths = {c.path for c in importers}
 
     # Tier 4: type-reference matching (only when tiers 1-3 yield nothing)
     references: list[FileContract] = []
@@ -483,12 +500,27 @@ def _filter_by_symbol(contracts: list[FileContract], symbol: str) -> list[FileCo
             seen.add(c.path)
             merged.append(c)
 
-    return sorted(merged, key=lambda c: (
+    result = sorted(merged, key=lambda c: (
         c.path not in defining_paths,
         c.path not in importer_paths,
         -c.relevance_score,
     ))
 
+    truncation: dict = {
+        "symbol": symbol,
+        "definers_found": len(defining),
+        "importers_found": total_importers,
+        "importers_returned": len(importers),
+        "references_found": len(references),
+        "total_returned": len(result),
+        "truncated": truncated,
+    }
+    if truncated:
+        truncation["truncation_reason"] = "max_importers_limit"
+        truncation["override_hint"] = f"--symbol {symbol} --max-importers {total_importers}"
+
+    return result, truncation
+
 
 # ---------------------------------------------------------------------------
 # Deep symbol scan — grep-based fallback for shallow-scanned repos

{sourcecode-0.42.0 → sourcecode-0.43.0}/src/sourcecode/serializer.py

@@ -722,8 +722,10 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
     # production runtime is represented as entry_points=[], never by fallback.
     ep_groups = _entry_point_groups(sm.entry_points)
     result["entry_points"] = ep_groups["production"]
-    result["development_entry_points"] = ep_groups["development"]
-    result["auxiliary_entry_points"] = ep_groups["auxiliary"]
+    if ep_groups["development"]:
+        result["development_entry_points"] = ep_groups["development"]
+    if ep_groups["auxiliary"]:
+        result["auxiliary_entry_points"] = ep_groups["auxiliary"]
 
     # ── 3. Architecture ───────────────────────────────────────────────────────
     result["architecture"] = _architecture_context(sm)
@@ -888,6 +890,23 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
     if analysis_gaps:
         result["analysis_gaps"] = analysis_gaps
 
+    # ── 8. Agent mode metadata — explicit transparency about auto-enabled/suppressed flags ──
+    _auto_enabled: list[str] = ["--dependencies", "--env-map", "--code-notes"]
+    _suppressed: list[str] = []
+    if sm.metrics_summary is not None and sm.metrics_summary.requested:
+        _suppressed.append("--full-metrics")
+    if sm.module_graph is not None and sm.module_graph.summary.requested:
+        _suppressed.append("--graph-modules")
+    if sm.doc_summary is not None and sm.doc_summary.requested:
+        _suppressed.append("--docs")
+    agent_mode_meta: dict[str, Any] = {
+        "auto_enabled": _auto_enabled,
+    }
+    if _suppressed:
+        agent_mode_meta["suppressed_flags"] = _suppressed
+        agent_mode_meta["suppressed_note"] = "computed but excluded from agent_view"
+    result["agent_mode"] = agent_mode_meta
+
     return result
 
 
@@ -918,9 +937,11 @@ def standard_view(sm: SourceMap, *, include_tree: bool = False) -> dict[str, Any
         "architecture_summary": sm.architecture_summary,
         "stacks": [asdict(s) for s in sm.stacks],
         "entry_points": ep_groups["production"],
-        "development_entry_points": ep_groups["development"],
-        "auxiliary_entry_points": ep_groups["auxiliary"],
     }
+    if ep_groups["development"]:
+        result["development_entry_points"] = ep_groups["development"]
+    if ep_groups["auxiliary"]:
+        result["auxiliary_entry_points"] = ep_groups["auxiliary"]
 
     # Layer B — signals (only when the corresponding analyzer ran)
     if sm.dependency_summary is not None and sm.dependency_summary.requested:
@@ -1125,6 +1146,8 @@ def _contract_view_minimal(
             summary["degraded"] = True
             summary["degraded_hint"] = "install sourcecode[ast] for full TS/JS extraction"
         result["summary"] = summary
+        if cs.symbol_truncation:
+            result["symbol_query"] = cs.symbol_truncation
 
     return result
 
@@ -1404,6 +1427,8 @@ def _contract_view_standard(
         }
         if cs.limitations:
             result["contract_summary"]["limitations"] = cs.limitations
+        if cs.symbol_truncation:
+            result["symbol_query"] = cs.symbol_truncation
 
     return result
 

sourcecode-0.43.0/tests/test_block5_quality.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+"""Tests for block 5 quality improvements:
+1. --symbol truncation via max_importers
+2. agent_view suppressed flags metadata
+3. Empty entry point lists omitted from output
+4. symbol_query in contract views
+"""
+
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, Optional
+
+import pytest
+
+from sourcecode.contract_model import (
+    ContractSummary,
+    ExportRecord,
+    FileContract,
+    ImportRecord,
+)
+from sourcecode.contract_pipeline import _filter_by_symbol
+from sourcecode.schema import (
+    AnalysisMetadata,
+    DocSummary,
+    EntryPoint,
+    MetricsSummary,
+    ModuleGraph,
+    ModuleGraphSummary,
+    SourceMap,
+    StackDetection,
+)
+from sourcecode.serializer import agent_view, standard_view, contract_view
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_definer(path: str, symbol: str) -> FileContract:
+    c = FileContract(path=path, language="python")
+    c.exports = [ExportRecord(name=symbol, kind="class")]
+    return c
+
+
+def _make_importer(path: str, symbol: str) -> FileContract:
+    c = FileContract(path=path, language="python")
+    c.imports = [ImportRecord(source="mymodule", symbols=[symbol])]
+    return c
+
+
+def _make_sm(**kwargs: Any) -> SourceMap:
+    """Minimal SourceMap for serializer tests."""
+    defaults: dict[str, Any] = {
+        "metadata": AnalysisMetadata(analyzed_path="/tmp/test"),
+        "stacks": [StackDetection(stack="python", primary=True)],
+        "entry_points": [],
+        "file_paths": [],
+        "project_type": "python",
+        "project_summary": "test project",
+        "architecture_summary": "simple",
+    }
+    defaults.update(kwargs)
+    return SourceMap(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# 1. --symbol truncation: max_importers caps output
+# ---------------------------------------------------------------------------
+
+def test_symbol_truncation_limits_importers() -> None:
+    """max_importers=2 with 5 importers → truncated=True, only 2 importers returned."""
+    definer = _make_definer("mymodule.py", "MyClass")
+    importers = [_make_importer(f"user{i}.py", "MyClass") for i in range(5)]
+
+    result, meta = _filter_by_symbol([definer] + importers, "MyClass", max_importers=2)
+
+    assert meta["truncated"] is True
+    assert meta["importers_found"] == 5
+    assert meta["importers_returned"] == 2
+    assert meta["definers_found"] == 1
+    # Definer + 2 importers = 3 total
+    assert meta["total_returned"] == 3
+    assert meta["truncation_reason"] == "max_importers_limit"
+    assert "override_hint" in meta
+    # Result list matches total_returned
+    assert len(result) == 3
+
+
+def test_symbol_no_truncation_small() -> None:
+    """When importers are under the cap, truncated=False."""
+    definer = _make_definer("mymodule.py", "SmallClass")
+    importers = [_make_importer(f"user{i}.py", "SmallClass") for i in range(3)]
+
+    result, meta = _filter_by_symbol([definer] + importers, "SmallClass", max_importers=50)
+
+    assert meta["truncated"] is False
+    assert meta["importers_found"] == 3
+    assert meta["importers_returned"] == 3
+    assert "truncation_reason" not in meta
+    assert "override_hint" not in meta
+
+
+def test_symbol_definers_not_truncated() -> None:
+    """Defining files are always included even when importers are capped to 0."""
+    definer = _make_definer("core.py", "CoreClass")
+    importers = [_make_importer(f"consumer{i}.py", "CoreClass") for i in range(10)]
+
+    result, meta = _filter_by_symbol([definer] + importers, "CoreClass", max_importers=0)
+
+    # Even with max_importers=0, the definer must be in the result
+    result_paths = {c.path for c in result}
+    assert "core.py" in result_paths
+    assert meta["definers_found"] == 1
+    assert meta["importers_returned"] == 0
+    assert meta["truncated"] is True
+
+
+# ---------------------------------------------------------------------------
+# 4. agent_view suppressed flags metadata
+# ---------------------------------------------------------------------------
+
+def test_agent_view_suppressed_flags_detected() -> None:
+    """When metrics_summary.requested=True, agent_view includes it in suppressed_flags."""
+    sm = _make_sm(
+        metrics_summary=MetricsSummary(requested=True, file_count=5),
+    )
+    result = agent_view(sm)
+
+    assert "agent_mode" in result
+    am = result["agent_mode"]
+    assert "--full-metrics" in am.get("suppressed_flags", [])
+    assert am.get("suppressed_note") == "computed but excluded from agent_view"
+
+
+def test_agent_view_suppressed_graph_modules() -> None:
+    """When module_graph.summary.requested=True, --graph-modules appears in suppressed_flags."""
+    mg = ModuleGraph(summary=ModuleGraphSummary(requested=True))
+    sm = _make_sm(module_graph=mg)
+    result = agent_view(sm)
+
+    am = result["agent_mode"]
+    assert "--graph-modules" in am.get("suppressed_flags", [])
+
+
+def test_agent_view_suppressed_docs() -> None:
+    """When doc_summary.requested=True, --docs appears in suppressed_flags."""
+    sm = _make_sm(doc_summary=DocSummary(requested=True))
+    result = agent_view(sm)
+
+    am = result["agent_mode"]
+    assert "--docs" in am.get("suppressed_flags", [])
+
+
+def test_agent_view_no_suppressed_flags() -> None:
+    """agent_view with no suppressed flags doesn't include suppressed_flags key."""
+    sm = _make_sm()
+    result = agent_view(sm)
+
+    assert "agent_mode" in result
+    am = result["agent_mode"]
+    assert "suppressed_flags" not in am
+    assert "--dependencies" in am.get("auto_enabled", [])
+
+
+def test_agent_view_auto_enabled_always_present() -> None:
+    """auto_enabled list always contains the three flags agent mode enables."""
+    sm = _make_sm()
+    result = agent_view(sm)
+
+    am = result["agent_mode"]
+    assert set(am["auto_enabled"]) == {"--dependencies", "--env-map", "--code-notes"}
+
+
+# ---------------------------------------------------------------------------
+# 6 & 7. Empty entry point lists omitted from output
+# ---------------------------------------------------------------------------
+
+def test_agent_view_empty_ep_lists_omitted() -> None:
+    """When no dev/auxiliary entry points, those keys are absent from agent_view output."""
+    sm = _make_sm(entry_points=[])
+    result = agent_view(sm)
+
+    assert "development_entry_points" not in result
+    assert "auxiliary_entry_points" not in result
+    # production list still present (can be empty)
+    assert "entry_points" in result
+
+
+def test_agent_view_dev_ep_present_when_nonempty() -> None:
+    """When a dev entry point exists, development_entry_points appears in agent_view."""
+    dev_ep = EntryPoint(
+        path="webpack.config.js",
+        stack="nodejs",
+        classification="development",
+        entrypoint_type="development",
+        runtime_relevance="low",
+    )
+    sm = _make_sm(entry_points=[dev_ep])
+    result = agent_view(sm)
+
+    assert "development_entry_points" in result
+
+
+def test_standard_view_empty_ep_lists_omitted() -> None:
+    """When no dev/auxiliary entry points, those keys are absent from standard_view."""
+    sm = _make_sm(entry_points=[])
+    result = standard_view(sm)
+
+    assert "development_entry_points" not in result
+    assert "auxiliary_entry_points" not in result
+    assert "entry_points" in result
+
+
+def test_standard_view_dev_ep_present_when_nonempty() -> None:
+    """When a dev entry point exists, it appears in standard_view."""
+    dev_ep = EntryPoint(
+        path="webpack.config.js",
+        stack="nodejs",
+        classification="development",
+        entrypoint_type="development",
+        runtime_relevance="low",
+    )
+    sm = _make_sm(entry_points=[dev_ep])
+    result = standard_view(sm)
+
+    assert "development_entry_points" in result
+
+
+# ---------------------------------------------------------------------------
+# 8. symbol_query in contract output
+# ---------------------------------------------------------------------------
+
+def test_symbol_query_in_contract_minimal_view() -> None:
+    """Truncation metadata appears in minimal contract output when truncated."""
+    trunc = {
+        "symbol": "MyClass",
+        "definers_found": 1,
+        "importers_found": 100,
+        "importers_returned": 50,
+        "references_found": 0,
+        "total_returned": 51,
+        "truncated": True,
+        "truncation_reason": "max_importers_limit",
+        "override_hint": "--symbol MyClass --max-importers 100",
+    }
+    cs = ContractSummary(
+        mode="contract",
+        total_files=200,
+        extracted_files=51,
+        symbol_truncation=trunc,
+    )
+    sm = _make_sm(contract_summary=cs, file_contracts=[])
+    result = contract_view(sm, depth="minimal")
+
+    assert "symbol_query" in result
+    sq = result["symbol_query"]
+    assert sq["truncated"] is True
+    assert sq["symbol"] == "MyClass"
+    assert sq["importers_found"] == 100
+
+
+def test_symbol_query_absent_when_not_truncated() -> None:
+    """symbol_query is absent when symbol_truncation is None."""
+    cs = ContractSummary(
+        mode="contract",
+        total_files=10,
+        extracted_files=3,
+        symbol_truncation=None,
+    )
+    sm = _make_sm(contract_summary=cs, file_contracts=[])
+    result = contract_view(sm, depth="minimal")
+
+    assert "symbol_query" not in result
+
+
+def test_symbol_query_in_contract_standard_view() -> None:
+    """Truncation metadata appears in standard contract output when truncated."""
+    trunc = {
+        "symbol": "Foo",
+        "definers_found": 1,
+        "importers_found": 75,
+        "importers_returned": 50,
+        "references_found": 0,
+        "total_returned": 51,
+        "truncated": True,
+        "truncation_reason": "max_importers_limit",
+        "override_hint": "--symbol Foo --max-importers 75",
+    }
+    cs = ContractSummary(
+        mode="standard",
+        total_files=150,
+        extracted_files=51,
+        symbol_truncation=trunc,
+    )
+    sm = _make_sm(contract_summary=cs, file_contracts=[])
+    result = contract_view(sm, depth="standard")
+
+    assert "symbol_query" in result
+    sq = result["symbol_query"]
+    assert sq["truncated"] is True
+    assert sq["symbol"] == "Foo"