sourcecode 1.30.26__tar.gz → 1.30.28__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.26
+Version: 1.30.28
 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.28-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.28
 ```
 
 ---

{sourcecode-1.30.26 → sourcecode-1.30.28}/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.28-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.28
 ```
 
 ---

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

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

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

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

{sourcecode-1.30.26 → sourcecode-1.30.28}/src/sourcecode/cli.py

@@ -424,7 +424,7 @@ def main(
     no_redact: bool = typer.Option(
         False,
         "--no-redact",
-        help="Disable secret redaction. Use with caution — output may contain sensitive values.",
+        help="Disable secret redaction of output strings. Note: env var values from the OS are never included in output regardless of this flag (security policy).",
     ),
     version: Optional[bool] = typer.Option(
         None,
@@ -437,7 +437,7 @@ def main(
     depth: int = typer.Option(
         4,
         "--depth",
-        help="File tree traversal depth (default: 4). Java/Maven projects auto-adjust to 12.",
+        help="File tree traversal depth (default: 4). Java/Maven projects auto-adjust to a minimum of 12; values below 12 have no effect on Java projects.",
         min=1,
         max=20,
     ),
@@ -1734,6 +1734,11 @@ def prepare_context_cmd(
         help="Emit per-phase timing to stderr (git scan ms, symptom scoring ms, total ms)",
         hidden=True,
     ),
+    fast: bool = typer.Option(
+        False,
+        "--fast",
+        help="Skip deep analysis (content search, test gap discovery, code annotations). Uses manifest/metadata only. Target: < 6 s.",
+    ),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -1808,9 +1813,14 @@ def prepare_context_cmd(
     if since:
         _phase += f" since {since}"
     _progress.start(_phase)
+    if not fast:
+        import sys as _sys
+        if _sys.stderr.isatty():
+            _sys.stderr.write(f"Analyzing ({task})... (deep scan may take 15–35 s for large codebases)\n")
+            _sys.stderr.flush()
     _t0 = _time.perf_counter()
     try:
-        output = builder.build(task, since=since, symptom=symptom)
+        output = builder.build(task, since=since, symptom=symptom, fast=fast)
     finally:
         _progress.finish()
     _t_total = (_time.perf_counter() - _t0) * 1000
@@ -1960,8 +1970,8 @@ def prepare_context_cmd(
                 _sys.stdout.buffer.write(b"\n")
                 _sys.stdout.buffer.flush()
             if copy:
-                _copy_to_clipboard(_nc_json)
-                typer.echo("✓ copied to clipboard", err=True)
+                if _copy_to_clipboard(_nc_json):
+                    typer.echo("✓ copied to clipboard", err=True)
             raise typer.Exit()
         if output.ci_decision:
             out["ci_decision"] = output.ci_decision
@@ -2082,6 +2092,10 @@ def prepare_context_cmd(
         out["symptom_note"] = output.symptom_note
     if output.symptom_explain:
         out["symptom_explain"] = output.symptom_explain
+    if getattr(output, "symptom_hint", None):
+        out["symptom_hint"] = output.symptom_hint
+    if getattr(output, "warnings", None):
+        out["warnings"] = output.warnings
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 

{sourcecode-1.30.26 → sourcecode-1.30.28}/src/sourcecode/prepare_context.py

@@ -335,6 +335,7 @@ class TaskOutput:
     related_notes: list[dict] = field(default_factory=list)        # fix-bug + symptom only
     symptom_note: Optional[str] = None                             # fix-bug: cross-layer synonym note
     symptom_explain: Optional[dict] = None                         # fix-bug: structured evidence breakdown
+    symptom_hint: Optional[str] = None                             # fix-bug: redirect hint when term not found in this module
     # delta-specific impact fields
     impact_summary: Optional[str] = None
     affected_modules: list[str] = field(default_factory=list)
@@ -348,6 +349,7 @@ class TaskOutput:
     error_code: Optional[str] = None
     error_message: Optional[str] = None
     error_hints: list[str] = field(default_factory=list)
+    warnings: list[dict] = field(default_factory=list)             # structured warnings (REF_NOT_FOUND, etc.)
     # CI decision state machine — machine-decidable signal
     ci_decision: Optional[str] = None  # "no_changes" | "analysis_success" | "git_ref_error" | "no_git_repo"
     # git baseline resolution metadata
@@ -683,7 +685,7 @@ class TaskContextBuilder:
     def __init__(self, root: Path) -> None:
         self.root = root
 
-    def build(self, task_name: str, *, since: Optional[str] = None, symptom: Optional[str] = None) -> TaskOutput:
+    def build(self, task_name: str, *, since: Optional[str] = None, symptom: Optional[str] = None, fast: bool = False) -> TaskOutput:
         if task_name not in TASKS:
             raise ValueError(
                 f"Unknown task '{task_name}'. Available: {', '.join(TASKS)}"
@@ -880,7 +882,7 @@ class TaskContextBuilder:
         improvement_opportunities: list[str] = []
         cn_notes_for_ranking: list = []
 
-        if spec.enable_code_notes:
+        if spec.enable_code_notes and not fast:
             from dataclasses import asdict
             from sourcecode.code_notes_analyzer import CodeNotesAnalyzer
 
@@ -1317,6 +1319,7 @@ class TaskContextBuilder:
         related_notes: list[dict] = []
         symptom_note: Optional[str] = None
         symptom_explain: Optional[dict] = None
+        symptom_hint: Optional[str] = None
         if task_name == "fix-bug" and symptom:
             import re as _re
             _camel_expanded = _re.sub(r'([a-z])([A-Z])', r'\1 \2', symptom)
@@ -1537,9 +1540,30 @@ class TaskContextBuilder:
                     ),
                 }
 
+                # BUG #4: LOW confidence + 0 content matches → clear suspected_areas,
+                # emit actionable redirect instead of unrelated files.
+                if _sx_confidence == "LOW" and not _sx_content:
+                    suspected_areas = []
+                    _is_fe_term = any(kw in _FRONTEND_SYMPTOM_MAP for kw in symptom_keywords)
+                    _root_name = self.root.name
+                    if _is_fe_term:
+                        _fe_redirect = (
+                            f"Term {symptom!r} not found in sources under {_root_name!r}. "
+                            f"This appears to be a frontend symptom. "
+                            f"Try: prepare-context fix-bug . --symptom {symptom!r} "
+                            f"(monorepo root) or target a frontend sub-project directly."
+                        )
+                    else:
+                        _fe_redirect = (
+                            f"Term {symptom!r} not found in sources under {_root_name!r}. "
+                            f"Verify the spelling or try a related term. "
+                            f"If this is a frontend symptom, run against the frontend sub-project."
+                        )
+                    symptom_hint = _fe_redirect
+
         # ── 7. Test gaps (generate-tests only) ────────────────────────────
         test_gaps: list[str] = []
-        if task_name == "generate-tests":
+        if task_name == "generate-tests" and not fast:
             def _normalize_test_stem(stem: str) -> str:
                 # Java: FooTest / FooTests → Foo; TestFoo → Foo
                 if stem.endswith("Tests"):
@@ -1683,6 +1707,8 @@ class TaskContextBuilder:
             resolved_since_ref=_delta_baseline.get("resolved_ref") if task_name == "delta" else None,
             resolution_path=_delta_baseline.get("resolution_path") if task_name == "delta" else None,
             diff_validation_status=_delta_baseline.get("diff_validation_status") if task_name == "delta" else None,
+            warnings=_delta_baseline.get("warnings", []) if task_name == "delta" else [],
+            symptom_hint=symptom_hint if task_name == "fix-bug" else None,
         )
 
     def render_prompt(self, output: TaskOutput) -> str:
@@ -3261,6 +3287,7 @@ class TaskContextBuilder:
                         "resolution_path": "head_minus_1_fallback",
                         "diff_validation_status": "invalid_ref",  # original ref unresolved
                         "error": False,
+                        "warnings": [{"code": "REF_NOT_FOUND", "ref": since, "resolved_to": "HEAD~1"}],
                     }
 
             # All stages failed

{sourcecode-1.30.26 → sourcecode-1.30.28}/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.28}/src/sourcecode/serializer.py

@@ -248,6 +248,16 @@ def _compact_git_context(sm: "SourceMap") -> "Optional[dict[str, Any]]":
                 for f, n in _fc.most_common(5)
             ]
             ctx["hotspots_source"] = "recent_commits"
+    if gc.recent_commits:
+        ctx["recent_commits"] = [
+            {
+                "hash": c.hash[:8],
+                "message": (c.message or "")[:80],
+                "date": (c.date or "")[:10],
+                "author": c.author or "",
+            }
+            for c in gc.recent_commits[:5]
+        ]
     return ctx if ctx else None
 
 
@@ -802,13 +812,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 +831,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 +909,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 +922,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)