sourcecode 1.30.26__tar.gz → 1.30.27__tar.gz

{sourcecode-1.30.26 → sourcecode-1.30.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.26
+Version: 1.30.27
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -221,7 +221,7 @@ Description-Content-Type: text/markdown
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.26-blue)
+![Version](https://img.shields.io/badge/version-1.30.27-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -257,7 +257,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.26
+# sourcecode 1.30.27
 ```
 
 ---

{sourcecode-1.30.26 → sourcecode-1.30.27}/README.md

@@ -2,7 +2,7 @@
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.26-blue)
+![Version](https://img.shields.io/badge/version-1.30.27-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -38,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.26
+# sourcecode 1.30.27
 ```
 
 ---

{sourcecode-1.30.26 → sourcecode-1.30.27}/pyproject.toml

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

{sourcecode-1.30.26 → sourcecode-1.30.27}/src/sourcecode/__init__.py

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

{sourcecode-1.30.26 → sourcecode-1.30.27}/src/sourcecode/ranking_engine.py

@@ -251,3 +251,95 @@ class RankingEngine:
 
     def is_auxiliary(self, path: str) -> bool:
         return self._scorer.is_auxiliary(path)
+
+
+# ---------------------------------------------------------------------------
+# Mandatory scoring formula — deterministic 5-component impact model
+# ---------------------------------------------------------------------------
+
+# runtime_impact: execution-path role of the file
+_RUNTIME_IMPACT: dict[str | None, float] = {
+    "api_endpoint": 1.0,        # @RestController / @Controller
+    "security": 1.0,             # @EnableWebSecurity / security filters
+    "runtime_core": 1.0,         # confirmed production entrypoint
+    "cli_entrypoint": 1.0,
+    "exception_handler": 0.8,    # @ControllerAdvice
+    "business_logic": 0.7,       # @Service (with or without @Transactional)
+    "api_layer": 0.7,            # API framework import (non-annotation evidence)
+    "data_access": 0.5,          # @Repository / @Mapper
+    "database_layer": 0.5,       # DB framework import
+    "infrastructure": 0.5,       # infra dependency import
+    "configuration": 0.4,        # @Configuration
+    "application_logic": 0.3,    # code defs + imports, no framework annotation
+    "domain_model": 0.3,         # @Entity / domain models
+    "dto": 0.2,                  # @Data / pure data carriers
+    "build_system": 0.15,
+    "tests": 0.1,
+    "tooling": 0.05,
+    None: 0.15,                  # unclassified source file
+}
+
+# framework_signal_strength: annotation / import evidence quality
+# Spring annotation → 0.3; security component → +0.2 (total 0.5); import only → 0.2
+_FRAMEWORK_SIGNAL: dict[str | None, float] = {
+    "security": 0.5,             # Spring Security annotation + security component
+    "api_endpoint": 0.3,         # @RestController / @Controller
+    "exception_handler": 0.3,    # @ControllerAdvice
+    "business_logic": 0.3,       # @Service
+    "data_access": 0.3,          # @Repository / @Mapper
+    "configuration": 0.3,        # @Configuration
+    "domain_model": 0.3,         # JPA @Entity
+    "dto": 0.3,                  # Lombok @Data
+    "api_layer": 0.2,            # framework import (weaker than annotation)
+    "database_layer": 0.2,
+    "infrastructure": 0.2,
+}
+
+# Normalization ceiling per evidence tier — used when spread < 0.40
+_NORM_TARGET_HI: dict[str, float] = {
+    "api_endpoint": 0.90,
+    "security": 0.90,
+    "exception_handler": 0.82,
+    "business_logic": 0.80,
+    "api_layer": 0.80,
+    "data_access": 0.70,
+    "database_layer": 0.70,
+    "infrastructure": 0.70,
+    "configuration": 0.65,
+}
+
+
+def resolve_runtime_impact(category: str | None) -> float:
+    """Map FileClassifier category → runtime_impact [0.0, 1.0]."""
+    return _RUNTIME_IMPACT.get(category, _RUNTIME_IMPACT[None])
+
+
+def resolve_framework_signal(category: str | None) -> float:
+    """Map FileClassifier category → framework_signal_strength [0.0, 0.5]."""
+    return _FRAMEWORK_SIGNAL.get(category, 0.0)
+
+
+def compute_impact_score(
+    runtime_impact: float,
+    dependency_centrality: float,
+    framework_signal_strength: float,
+    change_type_severity: float,
+    test_risk_factor: float,
+) -> float:
+    """Mandatory weighted scoring formula.
+
+    score = 0.35×runtime_impact + 0.25×dependency_centrality
+          + 0.20×framework_signal_strength + 0.10×change_type_severity
+          + 0.10×test_risk_factor
+
+    All inputs [0.0, 1.0]. Output clamped [0.0, 1.0].
+    Deterministic: same inputs always produce same output.
+    """
+    raw = (
+        0.35 * runtime_impact
+        + 0.25 * dependency_centrality
+        + 0.20 * framework_signal_strength
+        + 0.10 * change_type_severity
+        + 0.10 * test_risk_factor
+    )
+    return max(0.0, min(1.0, raw))

{sourcecode-1.30.26 → sourcecode-1.30.27}/src/sourcecode/serializer.py

@@ -802,13 +802,13 @@ def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> lis
                 semantic_hub_scores[p] = h.get("importance_score", 0.0) / max_importance
 
     entry_paths = {ep.path for ep in sm.entry_points}
-    # REST/MVC controllers are HTTP surface — surface before @Transactional services
-    _rest_ctrl_paths = {
-        ep.path for ep in sm.entry_points
-        if getattr(ep, "kind", "") in {"rest_controller", "mvc_controller"}
-    }
     scored: list[tuple[float, dict[str, Any]]] = []
 
+    from sourcecode.ranking_engine import (
+        compute_impact_score, resolve_runtime_impact, resolve_framework_signal,
+        _NORM_TARGET_HI,
+    )
+
     for path in sm.file_paths:
         file_class = classifier.classify(path)
         fs = engine.score(
@@ -821,78 +821,64 @@ def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> lis
         if fs.score < -50:  # hard noise
             continue
 
-        content_rel = file_class.relevance if file_class else 0.0
-        # Semantic hub bonus: normalised call-graph centrality adds up to +0.30
-        sem_hub = semantic_hub_scores.get(path, 0.0) * 0.30
-        pre_bonus_combined = fs.score + content_rel + sem_hub
-        # REST controller boost: surface above @Transactional service files
-        if path in _rest_ctrl_paths:
-            pre_bonus_combined += 2.0
-
-        # M3: Structural importance scoring — SORT ORDER ONLY.
-        # These bonuses drive ranking but must NOT inflate the displayed score.
         stem = Path(path).stem
-        stem_lower = stem.lower()
-        path_lower = path.lower()
-        sort_bonus = 0.0
-        # +10 application entry points
-        if path in entry_paths and any(
-            k in stem for k in ("Application", "Main", "Initializer", "Bootstrap", "Startup")
-        ):
-            sort_bonus = 10.0
-        # +8 known base/infrastructure classes
-        elif any(k in stem for k in (
-            "GenericRestController", "GenericCRUDRestController", "GenericController",
-            "AkitaBaseService", "BaseService", "FilterConfig", "AbstractController",
-        )):
-            sort_bonus = 8.0
-        # +6 security configuration
-        elif any(k in stem for k in (
-            "SecurityConfig", "SecurityStrategy", "WebSecurityConfig", "SecurityFilter",
-            "JwtFilter", "AuthConfig", "SecurityConfiguration",
-        )):
-            sort_bonus = 6.0
-        # +2 shared utilities
-        elif any(k in path_lower for k in ("util", "shared", "common", "helper", "constant")):
-            sort_bonus = 2.0
-
-        sort_key = pre_bonus_combined + sort_bonus
-
-        # Visibility threshold: require meaningful combined signal.
-        # Exception: high/medium-confidence files with strong content relevance
-        # can survive even if structural score is weak.
-        if sort_key < _FILE_RELEVANCE_MIN_COMBINED:
+        cat = file_class.category if file_class else None
+
+        # ── Component 1: runtime_impact — execution-path role ─────────────────
+        runtime_impact = resolve_runtime_impact(cat)
+
+        # ── Component 2: dependency_centrality — call-graph importance ─────────
+        # Entry points treat external HTTP/CLI callers as high centrality.
+        # Isolated files (no semantic data) score 0.0 — negative weighting by omission.
+        dep_centrality = semantic_hub_scores.get(path, 0.0)
+        if path in entry_paths:
+            dep_centrality = max(dep_centrality, 0.8)
+
+        # ── Component 3: framework_signal_strength — annotation quality ─────────
+        fw_signal = resolve_framework_signal(cat)
+
+        # ── Component 4: change_type_severity — git churn as structural proxy ───
+        churn = git_churn.get(path, 0)
+        change_sev = min(churn / max(max_churn, 1), 1.0) * 0.8
+
+        # ── Component 5: test_risk_factor — no per-file coverage data ──────────
+        test_risk = 0.2
+
+        formula_raw = compute_impact_score(
+            runtime_impact, dep_centrality, fw_signal, change_sev, test_risk
+        )
+
+        # T1 override: confirmed production entrypoints → 0.92–1.00.
+        # Only runtime_core / cli_entrypoint categories justify scores ≥ 0.92.
+        if path in entry_paths and cat in ("runtime_core", "cli_entrypoint"):
+            score_val = round(
+                min(1.0, max(0.92, file_class.relevance if file_class else 0.92)), 3
+            )
+        else:
+            score_val = round(formula_raw, 3)
+
+        # Visibility threshold: formula score or high-relevance content exception.
+        if score_val < _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
+        # Suppress low-confidence auxiliary/config files
         if (file_class
                 and file_class.confidence == "low"
                 and file_class.category in {"config", "auxiliary"}
-                and sort_key < 0.45):
+                and score_val < 0.45):
             continue
 
-        # Detect whether structural signals (fan_in, churn, etc.) are present
-        # beyond the base path-relevance reason — used by fallback tier.
-        structural_signal_reasons = [
-            r for r in fs.reasons
-            if r not in ("source file", "workspace source root", "runtime entrypoint")
-            and "path" not in r.lower()
-        ]
-        has_structural = bool(structural_signal_reasons)
-
-        # Tiered display score: evidence-gated, tier-capped.
-        # pre_bonus_combined is used (M3 sort_bonus excluded).
-        score_val = _tiered_display_score(
-            pre_bonus_combined, file_class, path, entry_paths, has_structural,
-        )
-        # relevance: raw evidence strength from FileClassifier (content signal only)
+        # relevance: content evidence only — intentionally diverges from score
+        # when dep_centrality or churn are non-zero (score ≠ relevance invariant)
         relevance_val = round(file_class.relevance, 3) if file_class else round(
-            min(0.39, max(0.10, pre_bonus_combined / 2.0)), 3
+            min(0.39, max(0.10, runtime_impact)), 3
         )
 
+        # sem_hub retained for signal reporting only — not used in score formula
+        sem_hub = semantic_hub_scores.get(path, 0.0) * 0.30
         ranking_reasons = [r for r in fs.reasons if r != "source file"]
         if sem_hub >= 0.15:
             ranking_reasons.append("call graph hub")
@@ -913,7 +899,7 @@ def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> lis
         if ranking_reasons:
             item["ranking_reasons"] = ranking_reasons
 
-        # Override metadata for known M3 base controller classes
+        # Override: universal base controller classes score as runtime_core
         if any(k in stem for k in ("GenericRestController", "GenericCRUDRestController")):
             item["category"] = "runtime_core"
             item["score"] = 0.95
@@ -926,11 +912,38 @@ def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> lis
             item["ranking_reasons"] = ["universal base class", "exception handling contract"]
             item["signals"] = [{"type": "framework_annotation", "strength": "strong"}]
 
-        scored.append((sort_key, item))
+        # sort_key = final score (rank consistency: score order = output order)
+        scored.append((item["score"], item))
 
-    # Deterministic sort: sort_key desc, then path asc
+    # Initial sort: score desc, path asc for deterministic tie-break
     scored.sort(key=lambda x: (-x[0], x[1]["path"]))
 
+    # Normalization: enforce minimum spread ≥ 0.4 among non-T1 files.
+    # T1 files (confirmed entrypoints, 0.92–1.0) are excluded — already correct.
+    # Prevents score compression when structural signals (--semantics, git) absent.
+    _nonep = [(sk, it) for sk, it in scored if it["path"] not in entry_paths]
+    if len(_nonep) > 1:
+        _vals = [it["score"] for _, it in _nonep]
+        _lo, _hi = min(_vals), max(_vals)
+        _spread = _hi - _lo
+        if _spread < 0.40:
+            _top_cat = max(_nonep, key=lambda x: x[1]["score"])[1].get("category", "")
+            _target_hi = _NORM_TARGET_HI.get(_top_cat, 0.60)
+            _target_lo = max(0.10, _target_hi - 0.50)
+            if _spread > 0:
+                _scale = (_target_hi - _target_lo) / _spread
+                for _, it in _nonep:
+                    it["score"] = round(
+                        max(0.0, min(1.0, _target_lo + (it["score"] - _lo) * _scale)), 3
+                    )
+            else:
+                _mid = round((_target_hi + _target_lo) / 2.0, 3)
+                for _, it in _nonep:
+                    it["score"] = _mid
+
+    # Re-sort by final score to guarantee rank consistency after normalization
+    scored.sort(key=lambda x: (-x[1]["score"], x[1]["path"]))
+
     # Diversity cap: at most half the budget from any single category.
     # Prevents 10/10 controllers drowning out services, repositories, domain.
     _CAT_CAP = max(1, limit // 2)

{sourcecode-1.30.26 → sourcecode-1.30.27}/tests/test_scoring_calibration.py

@@ -52,12 +52,14 @@ class TestTierEnforcement:
     """Score tiers must be respected regardless of M3 sort bonuses."""
 
     def test_security_filter_capped_below_one(self, tmp_path: Path):
-        """SecurityFilter.java (M3 +6 sort bonus) must not reach score=1.0.
-
-        FileClassifier classifies this as application_logic (T5 ≤ 0.54) because
-        @Component is not in the stereotype annotation list and Java imports like
-        org.springframework.* don't match the prefix-based API import check.
-        The fix ensures the M3 sort bonus stays out of the display score.
+        """SecurityFilter.java must not reach score=1.0.
+
+        FileClassifier classifies this as application_logic because @Component is
+        not in the stereotype list and the Spring import prefix doesn't match.
+        Formula score: runtime_impact=0.3 (application_logic) + test_risk=0.2
+        contribution → well below old inflated 1.0.  No lower-bound floor is
+        enforced for isolated files; low score is correct when structural signals
+        (dep_centrality, churn) are absent.
         """
         from sourcecode.serializer import _file_relevance
 
@@ -72,13 +74,15 @@ class TestTierEnforcement:
 
         if path in items:
             score = items[path]["score"]
-            # application_logic (T5): capped at 0.54, well below old inflated 1.0
+            # application_logic with no structural signals: formula gives low score.
+            # Ceiling: must never reach 0.54+ (no annotation evidence for that tier).
             assert score <= 0.54, (
-                f"SecurityFilter (application_logic T5) must be ≤ 0.54, got {score}. "
-                f"M3 +6 sort bonus must not inflate display score."
+                f"SecurityFilter (application_logic) must be ≤ 0.54, got {score}. "
+                f"No annotation evidence justifies a higher score."
             )
-            assert score >= 0.38, (
-                f"SecurityFilter with code defs + imports should be ≥ 0.38, got {score}"
+            # Floor: any classified file must score above noise floor.
+            assert score >= 0.10, (
+                f"SecurityFilter score must be ≥ 0.10 (noise floor), got {score}"
             )
 
     def test_confirmed_entrypoint_in_high_tier(self, tmp_path: Path):