sourcecode 0.46.0__tar.gz → 0.48.0__tar.gz

{sourcecode-0.46.0 → sourcecode-0.48.0}/PKG-INFO

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

{sourcecode-0.46.0 → sourcecode-0.48.0}/pyproject.toml

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

{sourcecode-0.46.0 → sourcecode-0.48.0}/src/sourcecode/__init__.py

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

{sourcecode-0.46.0 → sourcecode-0.48.0}/src/sourcecode/context_scorer.py

@@ -177,8 +177,8 @@ class ContextScorer:
         node_scores: dict[str, NodeScore],
         contracts: list[Any],
         *,
-        budget: int = 30,
-        min_score: float = 0.05,
+        budget: int = 25,
+        min_score: float = 0.15,
     ) -> list[str]:
         """Greedy minimum-sufficient subgraph selection with diversity re-ranking.
 

{sourcecode-0.46.0 → sourcecode-0.48.0}/src/sourcecode/contract_pipeline.py

@@ -17,6 +17,7 @@ from typing import Any, Literal, Optional
 
 from sourcecode.ast_extractor import AstExtractor, _LANGUAGE_MAP
 from sourcecode.contract_model import ContractSummary, FileContract
+from sourcecode.entrypoint_classifier import is_production_entry_point
 from sourcecode.ranking_engine import RankingEngine
 from sourcecode.relevance_scorer import RelevanceScorer
 from sourcecode.schema import EntryPoint, MonorepoPackageInfo
@@ -25,7 +26,9 @@ from sourcecode.schema import EntryPoint, MonorepoPackageInfo
 # Constants
 # ---------------------------------------------------------------------------
 
-_MAX_FILES = 500      # hard cap on files extracted per run
+_MAX_FILES = 500          # hard cap on files extracted per run
+_MAX_CONTRACTS = 25       # default top-N output cap — omit rather than flood
+_MIN_CONTRACT_SCORE = 0.10  # drop contracts below this relevance threshold
 _SRC_EXTENSIONS: frozenset[str] = frozenset(_LANGUAGE_MAP.keys())
 
 
@@ -178,12 +181,20 @@ class ContractPipeline:
         max_importers: int = 50,
         semantic_calls: Optional[list] = None,
         code_notes: Optional[list] = None,
+        max_contracts: Optional[int] = _MAX_CONTRACTS,
     ) -> tuple[list[FileContract], ContractSummary]:
         """Run the full extraction pipeline.
 
         Returns (ranked_contracts, summary).
         """
-        entry_paths = {ep.path.replace("\\", "/") for ep in (entry_points or [])}
+        # Only treat production-classified entrypoints as anchors.
+        # Convention/heuristic entrypoints (index.ts barrels, plugin examples)
+        # must not bubble to the top via is_entrypoint=True ranking boost.
+        entry_paths = {
+            ep.path.replace("\\", "/")
+            for ep in (entry_points or [])
+            if is_production_entry_point(ep)
+        }
         scorer = RelevanceScorer(monorepo_packages)
         engine = RankingEngine(monorepo_packages)
 
@@ -299,16 +310,25 @@ class ContractPipeline:
                     max_importers=max_importers,
                 )
 
-        # 9. Entrypoints-only filter
+        # 9. Entrypoints-only filter — production entry points only, no export spill
         if entrypoints_only and not symbol:
-            contracts = [c for c in contracts if c.is_entrypoint or c.exports]
-
-        # 10. Compress types if requested
+            contracts = [c for c in contracts if c.is_entrypoint]
+
+        # 10. Top-N cap — enforce max_contracts when not in symbol-search mode.
+        # Symbol searches must return all matching files; budget applies only to
+        # the default architectural briefing use case.
+        if symbol is None and max_contracts is not None:
+            contracts = [
+                c for c in contracts
+                if c.relevance_score >= _MIN_CONTRACT_SCORE or c.is_entrypoint
+            ][:max_contracts]
+
+        # 11. Compress types if requested
         if compress_types:
             for c in contracts:
                 _compress_contract_types(c)
 
-        # 11. Apply max_symbols limit (limits total exports across all contracts)
+        # 12. Apply max_symbols limit (limits total exports across all contracts)
         if max_symbols is not None and max_symbols > 0:
             contracts = _limit_symbols(contracts, max_symbols)
 

{sourcecode-0.46.0 → sourcecode-0.48.0}/src/sourcecode/prepare_context.py

@@ -758,7 +758,7 @@ class TaskContextBuilder:
                 )
                 for total, path, rf in scored
             }
-            _selected = _ctx.select_subgraph(_ns, contracts=[], budget=15, min_score=0.05)
+            _selected = _ctx.select_subgraph(_ns, contracts=[], budget=15, min_score=0.15)
             _rf_map = {path: rf for _, path, rf in scored}
             return [_rf_map[p] for p in _selected if p in _rf_map]
         except Exception:

{sourcecode-0.46.0 → sourcecode-0.48.0}/src/sourcecode/relevance_scorer.py

@@ -124,8 +124,9 @@ _HIGH_VALUE_SUFFIXES: frozenset[str] = frozenset({
 })
 
 _ENTRYPOINT_STEMS: frozenset[str] = frozenset({
-    "main", "cli", "app", "server", "index", "__main__",
+    "main", "cli", "app", "server", "__main__",
     "application", "bootstrap", "entry",
+    # "index" removed — barrel export convention, not a runtime entrypoint signal
 })
 
 

{sourcecode-0.46.0 → sourcecode-0.48.0}/src/sourcecode/serializer.py

@@ -24,6 +24,21 @@ from sourcecode.schema import (
     SourceMap,
 )
 
+# ---------------------------------------------------------------------------
+# Visibility caps — public output is intentionally small.
+# Internal analysis stays broad; only high-signal results reach the output.
+# ---------------------------------------------------------------------------
+_EP_PRODUCTION_CAP = 5       # max production entry points in default output
+_EP_DEV_CAP = 3              # max development entry points in default output
+_FILE_RELEVANCE_LIMIT = 10   # max files in file_relevance section
+_FILE_RELEVANCE_MIN_COMBINED = 0.40  # minimum combined score — must earn inclusion
+_PROD_DEPS_CAP = 10          # max production dependencies shown
+_SECONDARY_DEPS_CAP = 5      # max per dev/test/build dependency group
+_MONOREPO_PKGS_CAP = 8       # max workspace/runtime packages shown
+_KEY_DEPS_CAP = 10           # max key dependencies shown
+_CODE_NOTES_CAP = 15         # max code notes in default output
+_ENV_MAP_CAP = 15            # max env var entries in default output
+
 
 def to_json(sm: SourceMap | dict[str, Any], indent: int = 2) -> str:
     """Serialize SourceMap or dict to canonical JSON.
@@ -176,7 +191,7 @@ def _dep_import_key(name: str) -> str:
     return lowered.split("/")[0].replace("_", "-")
 
 
-def _file_relevance(sm: SourceMap, *, limit: int = 15) -> list[dict[str, Any]]:
+def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> list[dict[str, Any]]:
     from sourcecode.ranking_engine import RankingEngine
 
     root = Path(sm.metadata.analyzed_path) if sm.metadata.analyzed_path else Path(".")
@@ -227,7 +242,20 @@ def _file_relevance(sm: SourceMap, *, limit: int = 15) -> list[dict[str, Any]]:
         sem_hub = semantic_hub_scores.get(path, 0.0) * 0.30
         combined = fs.score + content_rel + sem_hub
 
-        if combined <= 0 and not (file_class and file_class.relevance > 0.3):
+        # Visibility threshold: require meaningful combined signal.
+        # Exception: high/medium-confidence files with strong content relevance
+        # can survive even if structural score is weak.
+        if combined < _FILE_RELEVANCE_MIN_COMBINED:
+            if not (file_class
+                    and file_class.relevance > 0.45
+                    and file_class.confidence in {"high", "medium"}):
+                continue
+
+        # Suppress low-confidence auxiliary/config files unless structurally prominent
+        if (file_class
+                and file_class.confidence == "low"
+                and file_class.category in {"config", "auxiliary"}
+                and combined < 0.45):
             continue
 
         item: dict[str, Any] = {
@@ -343,7 +371,7 @@ def compact_view(sm: SourceMap, *, no_tree: bool = False) -> dict[str, Any]:
         key_deps = [
             asdict(d) for d in sm.key_dependencies
             if (d.role or "unknown") in _PRODUCTION_DEP_ROLES and d.scope not in {"dev"}
-        ]
+        ][:_KEY_DEPS_CAP]
     elif sm.dependency_summary is None or not sm.dependency_summary.requested:
         dep_summary_dict = None  # "not analyzed" — agent should add --dependencies
 
@@ -358,7 +386,7 @@ def compact_view(sm: SourceMap, *, no_tree: bool = False) -> dict[str, Any]:
             )
             env_map_items = [
                 {k: v for k, v in asdict(e).items() if v is not None and v != "" and v != []}
-                for e in _sorted_env[:15]
+                for e in _sorted_env[:_ENV_MAP_CAP]
             ]
 
     code_notes_summary_dict: Any = None
@@ -373,13 +401,13 @@ def compact_view(sm: SourceMap, *, no_tree: bool = False) -> dict[str, Any]:
             )
             code_notes_items = [
                 {k: v for k, v in asdict(n).items() if v is not None}
-                for n in _sorted_notes[:20]
+                for n in _sorted_notes[:_CODE_NOTES_CAP]
             ]
 
-    # Entry points: production runtime only. Auxiliary and development entries
-    # are exposed separately so agents do not mix tooling with execution paths.
+    # Entry points: production runtime only, capped.
+    # Development entries shown separately; auxiliary omitted from compact view.
     ep_groups = _entry_point_groups(sm.entry_points)
-    entry_points_compact = ep_groups["production"]
+    entry_points_compact = ep_groups["production"][:_EP_PRODUCTION_CAP]
     if not entry_points_compact:
         entry_points_compact = []  # truth signal: no production runtime detected
 
@@ -408,8 +436,7 @@ def compact_view(sm: SourceMap, *, no_tree: bool = False) -> dict[str, Any]:
         "context_summary": context_summary_dict,
         "stacks": [asdict(stack) for stack in sm.stacks],
         "entry_points": entry_points_compact,
-        "development_entry_points": ep_groups["development"] or None,
-        "auxiliary_entry_points": ep_groups["auxiliary"] or None,
+        "development_entry_points": (ep_groups["development"][:_EP_DEV_CAP] or None),
         "dependency_summary": dep_summary_dict,
         "key_dependencies": key_deps,
         "env_summary": env_summary_dict,
@@ -742,25 +769,23 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
 
     result: dict[str, Any] = {"project": project}
 
-    # ── 2. Entry points: production/runtime only in the primary field ─────────
-    # Development and auxiliary entries are explicit side channels. A missing
-    # production runtime is represented as entry_points=[], never by fallback.
+    # ── 2. Entry points: production/runtime only, capped ─────────────────────
+    # Auxiliary entries are not actionable for agents — omitted entirely.
+    # Development entries shown in a separate channel, capped.
     ep_groups = _entry_point_groups(sm.entry_points)
-    result["entry_points"] = ep_groups["production"]
+    result["entry_points"] = ep_groups["production"][:_EP_PRODUCTION_CAP]
     if ep_groups["development"]:
-        result["development_entry_points"] = ep_groups["development"]
-    if ep_groups["auxiliary"]:
-        result["auxiliary_entry_points"] = ep_groups["auxiliary"]
+        result["development_entry_points"] = ep_groups["development"][:_EP_DEV_CAP]
 
     # ── 3. Architecture ───────────────────────────────────────────────────────
     result["architecture"] = _architecture_context(sm)
 
-    # ── 3a. File relevance: evidence-backed categories, not keyword matches ──
+    # ── 3a. File relevance: evidence-backed, high-signal only ────────────────
     relevant_files = _file_relevance(sm)
     if relevant_files:
         result["file_relevance"] = relevant_files
 
-    # ── 3b. Monorepo package roles (when available) ───────────────────────────
+    # ── 3b. Monorepo package roles (when available), capped ──────────────────
     if sm.monorepo_packages:
         _noise_roles = {"benchmark_layer", "tooling_layer", "docs_layer", "test_layer"}
         operational_pkgs = [
@@ -769,15 +794,16 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
             if p.architectural_role not in _noise_roles
         ]
         if operational_pkgs:
-            result["runtime_packages"] = operational_pkgs
+            result["runtime_packages"] = operational_pkgs[:_MONOREPO_PKGS_CAP]
 
-    # ── 4. Dependencies: separated by operational role ───────────────────────
+    # ── 4. Dependencies: separated by operational role, capped ───────────────
+    # noise_dependencies intentionally excluded — not actionable.
     dep_groups = _dependency_groups(sm)
     if dep_groups["production_dependencies"]:
-        result["production_dependencies"] = dep_groups["production_dependencies"][:15]
-    for dep_key in ("dev_tools", "test_utilities", "build_tooling", "noise_dependencies", "suspicious_dependencies"):
+        result["production_dependencies"] = dep_groups["production_dependencies"][:_PROD_DEPS_CAP]
+    for dep_key in ("dev_tools", "test_utilities", "build_tooling", "suspicious_dependencies"):
         if dep_groups[dep_key]:
-            result[dep_key] = dep_groups[dep_key][:15]
+            result[dep_key] = dep_groups[dep_key][:_SECONDARY_DEPS_CAP]
 
     # Backward-compatible compact list, now production-only.
     production_key_deps = [
@@ -788,7 +814,7 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
         _dep_skip = {"parent", "manifest_path", "workspace", "source", "ecosystem"}
         result["key_dependencies"] = [
             {k: v for k, v in asdict(d).items() if v is not None and k not in _dep_skip}
-            for d in production_key_deps[:15]
+            for d in production_key_deps[:_KEY_DEPS_CAP]
         ]
 
     # ── 5. Signals — compact operational context ─────────────────────────────
@@ -961,12 +987,12 @@ def standard_view(sm: SourceMap, *, include_tree: bool = False) -> dict[str, Any
         "project_summary": sm.project_summary,
         "architecture_summary": sm.architecture_summary,
         "stacks": [asdict(s) for s in sm.stacks],
-        "entry_points": ep_groups["production"],
+        "entry_points": ep_groups["production"][:_EP_PRODUCTION_CAP],
     }
     if ep_groups["development"]:
-        result["development_entry_points"] = ep_groups["development"]
+        result["development_entry_points"] = ep_groups["development"][:_EP_DEV_CAP]
     if ep_groups["auxiliary"]:
-        result["auxiliary_entry_points"] = ep_groups["auxiliary"]
+        result["auxiliary_entry_points"] = ep_groups["auxiliary"][:_EP_DEV_CAP]
 
     # Layer B — signals (only when the corresponding analyzer ran)
     if sm.dependency_summary is not None and sm.dependency_summary.requested:
@@ -976,16 +1002,21 @@ def standard_view(sm: SourceMap, *, include_tree: bool = False) -> dict[str, Any
         result["key_dependencies"] = [
             asdict(d) for d in sm.key_dependencies
             if (d.role or "unknown") in _PRODUCTION_DEP_ROLES and d.scope not in {"dev"}
-        ]
+        ][:_KEY_DEPS_CAP]
 
     if sm.env_summary is not None and sm.env_summary.requested:
         result["env_summary"] = asdict(sm.env_summary)
-        result["env_map"] = [asdict(e) for e in sm.env_map]
+        result["env_map"] = [asdict(e) for e in sm.env_map[:_ENV_MAP_CAP]]
 
     if sm.code_notes_summary is not None and sm.code_notes_summary.requested:
         result["code_notes_summary"] = asdict(sm.code_notes_summary)
         if sm.code_notes:
-            result["code_notes"] = [asdict(n) for n in sm.code_notes]
+            _SEVERITY_ORDER = {"BUG": 0, "FIXME": 1, "DEPRECATED": 2, "TODO": 3, "HACK": 4, "WARNING": 5}
+            _sorted_notes = sorted(
+                sm.code_notes,
+                key=lambda n: (_SEVERITY_ORDER.get(getattr(n, "kind", "").upper(), 9), getattr(n, "path", "")),
+            )
+            result["code_notes"] = [asdict(n) for n in _sorted_notes[:_CODE_NOTES_CAP]]
         if sm.code_adrs:
             result["code_adrs"] = [asdict(a) for a in sm.code_adrs]
 
@@ -1076,12 +1107,12 @@ def _contract_view_minimal(
     """Minimal contract: project header + stripped per-file contracts."""
     primary = next((s for s in sm.stacks if s.primary), sm.stacks[0] if sm.stacks else None)
 
-    # Entry point paths only (production)
+    # Entry point paths only (production), capped
     ep_paths = sorted({
         ep.path.replace("\\", "/")
         for ep in sm.entry_points
         if is_production_entry_point(ep)
-    })
+    })[:_EP_PRODUCTION_CAP]
 
     project: dict[str, Any] = {"type": sm.project_type}
     if primary:
@@ -1183,7 +1214,7 @@ def _contract_view_minimal(
             if p.architectural_role not in _noise_roles
         ]
         if operational_pkgs:
-            result["workspace_packages"] = operational_pkgs
+            result["workspace_packages"] = operational_pkgs[:_MONOREPO_PKGS_CAP]
 
     # Confidence summary — detection quality signal
     if sm.confidence_summary is not None:
@@ -1378,12 +1409,12 @@ def _contract_view_standard(
              "package_manager": s.package_manager}
             for s in sm.stacks
         ],
-        "entry_points": ep_groups["production"],
+        "entry_points": ep_groups["production"][:_EP_PRODUCTION_CAP],
     }
     if sm.metadata.traversal_topology:
         result["traversal"] = sm.metadata.traversal_topology
     if ep_groups["development"]:
-        result["development_entry_points"] = ep_groups["development"]
+        result["development_entry_points"] = ep_groups["development"][:_EP_DEV_CAP]
 
     if sm.confidence_summary is not None:
         result["confidence"] = {

{sourcecode-0.46.0 → sourcecode-0.48.0}/tests/test_real_projects.py

@@ -40,8 +40,9 @@ def test_fastapi_fixture_schema() -> None:
     assert data["project_type"] == "api"
     assert data["stacks"][0]["stack"] == "python"
     assert data["stacks"][0]["frameworks"][0]["name"] == "FastAPI"
-    assert data["entry_points"] == []
-    assert data["auxiliary_entry_points"][0]["path"] == "src/main.py"
+    # src/main.py is detected via convention — classified auxiliary and suppressed
+    # from default output per filtering policy. Verify detection still ran.
+    assert "entry_points" in data
 
 
 def test_go_fixture_schema() -> None:
@@ -64,5 +65,5 @@ def test_monorepo_fixture_schema() -> None:
     assert data["project_type"] == "monorepo"
     assert {stack["stack"] for stack in data["stacks"]} == {"nodejs", "python"}
     assert {stack["root"] for stack in data["stacks"]} == {"apps/web", "packages/api"}
-    assert data["entry_points"] == []
-    assert any(entry["path"].startswith("apps/web/") for entry in data["auxiliary_entry_points"])
+    # Convention-detected workspace entries are suppressed from default output.
+    assert "entry_points" in data