sourcecode 2.7.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

sourcecode/contract_pipeline.py

@@ -129,7 +129,14 @@ def _resolve_relative(base_dir: str, src: str, path_set: set[str]) -> list[str]:
 # ---------------------------------------------------------------------------
 
 def _get_git_churn(root: Path, file_paths: list[str]) -> dict[str, int]:
-    """Return commit count per file in last 90 days."""
+    """Return commit count per file in last 90 days.
+
+    `git log` paths are repo-root-relative while `file_paths` are relative to the
+    requested scope, so in a monorepo subdirectory the two namespaces never
+    intersect and every file scores zero churn. Translate before matching.
+    """
+    from sourcecode.git_analyzer import git_scope_prefix, to_scope_relative
+
     churn: dict[str, int] = {}
     try:
         result = subprocess.run(
@@ -137,12 +144,16 @@ def _get_git_churn(root: Path, file_paths: list[str]) -> dict[str, int]:
             cwd=root, capture_output=True, text=True,
             encoding="utf-8", errors="replace", timeout=15,
         )
+        prefix = git_scope_prefix(root)
         path_set = set(file_paths)
         counter: Counter[str] = Counter()
         for line in (result.stdout or "").splitlines():
             line = line.strip().replace("\\", "/")
-            if line in path_set:
-                counter[line] += 1
+            scoped = to_scope_relative(line, prefix)
+            if scoped is None:
+                continue
+            if scoped in path_set:
+                counter[scoped] += 1
         churn = dict(counter)
     except Exception:
         pass

sourcecode/detectors/java.py

@@ -487,7 +487,13 @@ class JavaDetector(AbstractDetector):
             frameworks.append(FrameworkDetection(name="Spring Security", source=source))
         if "spring-boot-starter-data-jpa" in text or "spring-data-jpa" in text:
             frameworks.append(FrameworkDetection(name="Spring Data JPA", source=source))
-        if "spring-ldap-core" in text or "spring-security-ldap" in text:
+        # The Boot starter names neither of the module coordinates, so a Boot app
+        # wiring LDAP the standard way declared no LDAP framework at all.
+        if (
+            "spring-ldap-core" in text
+            or "spring-security-ldap" in text
+            or "spring-boot-starter-data-ldap" in text
+        ):
             frameworks.append(FrameworkDetection(name="Spring LDAP", source=source))
         if "spring-aspects" in text or "spring-aop" in text:
             frameworks.append(FrameworkDetection(name="Spring AOP", source=source))

sourcecode/envelope.py

@@ -0,0 +1,193 @@
+"""One response envelope for every machine-consumable command.
+
+A consumer that reads two commands' output had no way to answer basic questions
+about either one: which version produced it, against which scope, from which
+analyzer, and whether two files in front of it came from the same run. Some
+commands carried a `schema_version`, most carried nothing, and no command
+carried run identity at all.
+
+`_meta` answers those questions in the same shape everywhere:
+
+    {
+      "schema_version": "1.0",          # the command's payload contract
+      "envelope_version": "1",          # the shape of this block
+      "tool_version": "2.7.0",
+      "command": "retrieve endpoint-inventory",
+      "scope": {"path": "/repo/api", "repo_root": "/repo", "prefix": "api/"},
+      "run_id": "9f2c…"                 # (tool, analyzer, tree state, scope)
+    }
+
+`run_id` is deterministic: the same tool analysing the same tree at the same
+scope produces the same id, and any change to the analyzer, the commit, the
+working tree's cleanliness or the scope produces a different one. It carries no
+timestamp, so two consecutive runs on an unchanged tree are byte-identical —
+the property a CI verdict and a signed report both need.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+from pathlib import Path
+from typing import Any, Optional
+
+#: Shape of the `_meta` block itself. Bump when a field's meaning changes.
+ENVELOPE_VERSION = "1"
+
+_META_KEY = "_meta"
+
+#: Published schemas, by name. Shipped with the package so a consumer can pin
+#: against the exact contract the installed version emits.
+SCHEMA_DIR = Path(__file__).resolve().parent / "schemas"
+
+
+def available_schemas() -> "list[str]":
+    """Names of the published schemas, sorted."""
+    if not SCHEMA_DIR.is_dir():
+        return []
+    return sorted(p.name[: -len(".schema.json")] for p in SCHEMA_DIR.glob("*.schema.json"))
+
+
+def load_schema(name: str) -> "dict[str, Any]":
+    """Read a published schema by name (e.g. "envelope-v1"). Raises FileNotFoundError."""
+    import json
+
+    path = SCHEMA_DIR / f"{name}.schema.json"
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _git(args: list[str], cwd: Path) -> str:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(cwd), *args],
+            capture_output=True, text=True, timeout=5,
+        )
+    except Exception:
+        return ""
+    return (result.stdout or "").strip() if result.returncode == 0 else ""
+
+
+def _tree_state(target: Path) -> "tuple[str, str, str]":
+    """(repo_root, scope_prefix, tree_id) for *target*, empty strings when not a repo.
+
+    `tree_id` is the commit plus a dirty marker: two runs on the same commit with
+    the same working tree agree, and an edited working tree never reuses the
+    clean commit's identity.
+    """
+    root = _git(["rev-parse", "--show-toplevel"], target)
+    if not root:
+        return "", "", ""
+    prefix = _git(["rev-parse", "--show-prefix"], target)
+    head = _git(["rev-parse", "HEAD"], target) or "no-commit"
+    dirty = _git(["status", "--porcelain"], target)
+    tree_id = head if not dirty else f"{head}+dirty:{hashlib.sha256(dirty.encode()).hexdigest()[:12]}"
+    return root, prefix, tree_id
+
+
+def _config_state(target: Path, repo_root: str) -> str:
+    """Digest of the repo configuration that changes what the analyzer reports.
+
+    `sourcecode.config.json` teaches the scanner a project's own authorization
+    annotations, so two runs on the same commit with different configuration
+    produce different findings. A run identity that ignored it would claim the
+    two runs were the same run.
+    """
+    try:
+        from sourcecode.security_config import CONFIG_FILENAME
+    except Exception:
+        return ""
+    for base in (Path(repo_root) if repo_root else None, target):
+        if base is None:
+            continue
+        candidate = base / CONFIG_FILENAME
+        try:
+            if candidate.is_file():
+                return hashlib.sha256(candidate.read_bytes()).hexdigest()[:12]
+        except OSError:
+            continue
+    return "none"
+
+
+def build_meta(
+    command: str,
+    target: "Optional[Path]" = None,
+    *,
+    schema_version: "Optional[str]" = None,
+    extra: "Optional[dict[str, Any]]" = None,
+) -> "dict[str, Any]":
+    """Assemble the `_meta` block. Never raises — a degraded envelope beats none."""
+    from sourcecode import __version__
+
+    meta: dict[str, Any] = {
+        "envelope_version": ENVELOPE_VERSION,
+        "tool_version": __version__,
+        "command": command,
+    }
+    if schema_version:
+        meta["schema_version"] = schema_version
+
+    analyzer = ""
+    try:
+        from sourcecode.cache import analyzer_fingerprint
+
+        analyzer = analyzer_fingerprint()
+    except Exception:
+        pass
+
+    repo_root = prefix = tree_id = config_id = ""
+    if target is not None:
+        try:
+            resolved = Path(target).resolve()
+            scope: dict[str, Any] = {"path": str(resolved)}
+            if resolved.is_dir():
+                repo_root, prefix, tree_id = _tree_state(resolved)
+                config_id = _config_state(resolved, repo_root)
+            if repo_root:
+                scope["repo_root"] = repo_root
+                # "" at the repository root; "api/" inside a module. The namespace
+                # every path in the payload is relative to.
+                scope["prefix"] = prefix
+            meta["scope"] = scope
+        except Exception:
+            pass
+
+    # The manifest run_id is computed over, published so a consumer can see WHY
+    # two runs differ instead of only that they do — and so a reproduction can be
+    # attempted against the same inputs.
+    if analyzer or tree_id or config_id:
+        inputs: dict[str, Any] = {}
+        if analyzer:
+            inputs["analyzer"] = analyzer
+        if tree_id:
+            inputs["tree"] = tree_id
+        if config_id:
+            inputs["config"] = config_id
+        meta["inputs"] = inputs
+
+    meta["run_id"] = hashlib.sha256(
+        "\x00".join([
+            meta["tool_version"], analyzer, command,
+            schema_version or "", repo_root, prefix, tree_id, config_id,
+        ]).encode()
+    ).hexdigest()[:16]
+
+    if extra:
+        meta.update(extra)
+    return meta
+
+
+def attach_meta(payload: "dict[str, Any]", meta: "dict[str, Any]") -> "dict[str, Any]":
+    """Merge *meta* into ``payload["_meta"]`` without overwriting what is there.
+
+    Commands that already publish provenance (cache source, changed-only state,
+    token economy) keep their fields: this adds identity, it does not replace
+    what a command knows about its own run.
+    """
+    existing = payload.get(_META_KEY)
+    if isinstance(existing, dict):
+        merged = dict(meta)
+        merged.update(existing)
+        payload[_META_KEY] = merged
+    else:
+        payload[_META_KEY] = dict(meta)
+    return payload

sourcecode/format_contract.py

@@ -8,10 +8,16 @@ Every CLI command that emits machine-consumable output validates its
   * invalid-format errors share an identical envelope shape and exit code.
 
 The registry value is an *ordered* tuple; element ``0`` is the command's
-default and matches its Typer option default. Defaults are intentionally NOT
-changed when centralizing — ``explain`` and ``pr-impact`` keep their
-human-facing ``text`` default — to avoid breaking existing scripts. The strict
-guarantee is on ``-f json``, which every command supports.
+default and matches its Typer option default. The strict guarantee is on
+``-f json``, which every command supports.
+
+``explain`` keeps a human-facing ``text`` default: it emits prose for a reader,
+and infers ``json`` from an ``--output`` file extension. ``pr-impact`` does not.
+It is a gating command — it carries ``--fail-on`` and a meaningful exit code, so
+its consumer is a pipeline, and a pipeline cannot parse prose. It defaulted to
+``text`` while every other machine-consumable command defaulted to ``json``,
+which made scripted use a trap. Scripts that relied on the old default must now
+pass ``--format text`` explicitly.
 
 Exit-code policy: an invalid ``--format`` is an argument-validation error and
 exits with code ``2`` for every command (matching the documented
@@ -36,7 +42,7 @@ FORMAT_REGISTRY: "dict[str, tuple[str, ...]]" = {
     "baseline-diff": ("json", "yaml"),
     "baseline-trend": ("json", "yaml"),
     "impact-chain": ("json", "yaml"),
-    "pr-impact": ("text", "json"),
+    "pr-impact": ("json", "text"),
     "migrate-check": ("json", "text"),
     "spring-audit": ("json", "yaml", "github-comment"),
     "explain": ("text", "json"),

sourcecode/git_analyzer.py

@@ -76,6 +76,49 @@ def _run_git(args: list[str], cwd: Path, timeout: int = 15) -> tuple[str, int]:
     return result.stdout or "", result.returncode
 
 
+def git_scope_prefix(path: Path) -> str:
+    """Position of *path* inside its git repository, "" when it IS the repo root.
+
+    Git reports every path relative to the repository root; the rest of the engine
+    addresses files relative to the requested scope. In a monorepo subdirectory
+    those two namespaces never intersect, so churn, hotspots and changed-file sets
+    silently come back empty and root-relative paths leak into scoped output.
+    Every git path must cross this seam before the engine sees it.
+
+    Returns a prefix with a trailing slash (e.g. "api/"), as `git rev-parse
+    --show-prefix` does.
+    """
+    try:
+        stdout, rc = _run_git(["rev-parse", "--show-prefix"], path, timeout=5)
+    except Exception:
+        return ""
+    return stdout.strip() if rc == 0 else ""
+
+
+def to_scope_relative(git_path: str, prefix: str) -> "str | None":
+    """Translate a repo-root-relative git path into the scope namespace.
+
+    Returns None when the file lives outside the requested scope — it belongs to a
+    sibling module and must not appear in this scope's results.
+    """
+    if not prefix:
+        return git_path
+    if git_path.startswith(prefix):
+        return git_path[len(prefix):] or None
+    return None
+
+
+def _scope_paths(paths: list[str], prefix: str) -> list[str]:
+    if not prefix:
+        return paths
+    out: list[str] = []
+    for p in paths:
+        rel = to_scope_relative(p, prefix)
+        if rel:
+            out.append(rel)
+    return out
+
+
 class GitAnalyzer:
     """Extrae contexto temporal del repositorio git."""
 
@@ -112,6 +155,10 @@ class GitAnalyzer:
         except subprocess.TimeoutExpired:
             return GitContext(requested=True, limitations=["git_timeout"])
 
+        # Everything git reports below is repo-root-relative; the caller addresses
+        # files relative to `path`. Translate at this seam, once.
+        prefix = git_scope_prefix(path)
+
         try:
             stdout, _ = _run_git(["rev-parse", "--abbrev-ref", "HEAD"], path, timeout=5)
             branch = stdout.strip() or None
@@ -129,7 +176,7 @@ class GitAnalyzer:
                 path,
                 timeout=15,
             )
-            recent_commits = _parse_commits(stdout)
+            recent_commits = _parse_commits(stdout, prefix)
         except subprocess.TimeoutExpired:
             limitations.append("commits_timeout")
         except Exception as exc:
@@ -147,7 +194,7 @@ class GitAnalyzer:
                 path,
                 timeout=30,
             )
-            change_hotspots = _parse_hotspots(stdout)
+            change_hotspots = _parse_hotspots(stdout, prefix)
         except subprocess.TimeoutExpired:
             limitations.append("hotspots_timeout")
             hotspots_status = "failed"
@@ -172,7 +219,7 @@ class GitAnalyzer:
                     path,
                     timeout=30,
                 )
-                change_hotspots = _parse_hotspots(stdout)
+                change_hotspots = _parse_hotspots(stdout, prefix)
                 if change_hotspots:
                     hotspot_method = "absolute_log_fallback"
                     limitations.append(
@@ -184,7 +231,7 @@ class GitAnalyzer:
 
         try:
             stdout, _ = _run_git(["status", "--porcelain"], path, timeout=10)
-            uncommitted = _parse_uncommitted(stdout)
+            uncommitted = _parse_uncommitted(stdout, prefix)
         except subprocess.TimeoutExpired:
             limitations.append("status_timeout")
         except Exception as exc:
@@ -217,7 +264,7 @@ class GitAnalyzer:
         )
 
 
-def _parse_commits(output: str) -> list:
+def _parse_commits(output: str, prefix: str = "") -> list:
     from sourcecode.schema import CommitRecord
 
     commits = []
@@ -231,11 +278,14 @@ def _parse_commits(output: str) -> list:
         if len(parts) < 4:
             continue
         hash_val, message, author, date_str = parts
-        files = [
-            ln.strip()
-            for ln in lines[1:]
-            if ln.strip() and not ln.startswith("__COMMIT__")
-        ][:_MAX_FILES_PER_COMMIT]
+        files = _scope_paths(
+            [
+                ln.strip()
+                for ln in lines[1:]
+                if ln.strip() and not ln.startswith("__COMMIT__")
+            ],
+            prefix,
+        )[:_MAX_FILES_PER_COMMIT]
         commits.append(
             CommitRecord(
                 hash=hash_val[:8],
@@ -272,7 +322,7 @@ def _is_hotspot_admin(path: str) -> bool:
     return False
 
 
-def _parse_hotspots(output: str | None) -> list:
+def _parse_hotspots(output: str | None, prefix: str = "") -> list:
     from sourcecode.schema import ChangeHotspot
 
     if not output:
@@ -301,6 +351,12 @@ def _parse_hotspots(output: str | None) -> list:
         # Skip git artifact lines that are not file paths: flags (-o, --), separators, etc.
         if line.startswith("-") or not ("/" in line or "." in line):
             continue
+        # Cross the namespace seam before anything counts or is emitted: files in
+        # sibling modules are not this scope's hotspots.
+        scoped = to_scope_relative(line, prefix)
+        if scoped is None:
+            continue
+        line = scoped
         if _is_hotspot_admin(line):
             continue
         file_counts[line] += 1
@@ -317,7 +373,7 @@ def _parse_hotspots(output: str | None) -> list:
     ]
 
 
-def _parse_uncommitted(output: str) -> "UncommittedChanges":
+def _parse_uncommitted(output: str, prefix: str = "") -> "UncommittedChanges":
     from sourcecode.schema import UncommittedChanges
 
     staged, unstaged, untracked = [], [], []
@@ -329,6 +385,12 @@ def _parse_uncommitted(output: str) -> "UncommittedChanges":
         # Renamed files: git porcelain v1 produces "old -> new"; keep only the new path.
         if x == "R" and " -> " in filepath:
             filepath = filepath.split(" -> ", 1)[1]
+        # `git status --porcelain` is always repo-root-relative, even when run from
+        # a subdirectory: translate, and drop files outside the requested scope.
+        _scoped = to_scope_relative(filepath, prefix)
+        if _scoped is None:
+            continue
+        filepath = _scoped
         if x == "?" and y == "?":
             untracked.append(filepath)
         else: