grift-cli 0.5.0__py3-none-any.whl

tep_core/data/v2026.09/distributions.json

@@ -0,0 +1,110 @@
+{
+  "version": "v2026.09",
+  "analysis_scope": "repo",
+  "definition_version": "tep-v0.5.0-2026-08-22",
+  "tool_version": "0.5.0",
+  "pin_list_hash": "2a55849fd379283d",
+  "measured_at": "2026-08-21T17:00:53Z",
+  "ok_repos": 47,
+  "metrics": {
+    "test_cochange": {
+      "n": 33,
+      "min": 0.0,
+      "q1": 0.1181,
+      "median": 0.2328,
+      "q3": 0.3019,
+      "max": 0.5078,
+      "values": [
+        0.0,
+        0.0026,
+        0.0071,
+        0.0123,
+        0.0306,
+        0.0369,
+        0.08,
+        0.1113,
+        0.1249,
+        0.1274,
+        0.1372,
+        0.1471,
+        0.1682,
+        0.1993,
+        0.1995,
+        0.2143,
+        0.2328,
+        0.2331,
+        0.2363,
+        0.2395,
+        0.2528,
+        0.2588,
+        0.2739,
+        0.2766,
+        0.2859,
+        0.3178,
+        0.3285,
+        0.4154,
+        0.4257,
+        0.4438,
+        0.4754,
+        0.4964,
+        0.5078
+      ]
+    },
+    "corrective_rework": {
+      "n": 42,
+      "min": 0.0,
+      "q1": 0.0329,
+      "median": 0.0614,
+      "q3": 0.1031,
+      "max": 0.3846,
+      "values": [
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0013,
+        0.0142,
+        0.0271,
+        0.0289,
+        0.0342,
+        0.0419,
+        0.047,
+        0.0477,
+        0.0491,
+        0.0491,
+        0.0528,
+        0.0554,
+        0.0571,
+        0.0581,
+        0.0594,
+        0.0633,
+        0.0649,
+        0.0667,
+        0.0672,
+        0.0721,
+        0.073,
+        0.073,
+        0.0852,
+        0.0926,
+        0.0975,
+        0.102,
+        0.1063,
+        0.1106,
+        0.1337,
+        0.1338,
+        0.1499,
+        0.1546,
+        0.1717,
+        0.1951,
+        0.1971,
+        0.3846
+      ]
+    },
+    "survival_index": {
+      "n": 0,
+      "values": []
+    }
+  }
+}

tep_core/gitutil.py

@@ -0,0 +1,112 @@
+"""Git subprocess helpers. Standard library only."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_GIT_TIMEOUT_SECONDS = 120
+
+
+class GitError(RuntimeError):
+    pass
+
+
+@dataclass
+class GitCommit:
+    sha: str
+    author_email: str
+    parents: tuple[str, ...]
+    date: str  # YYYY-MM-DD
+    subject: str
+    files: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def is_merge(self) -> bool:
+        return len(self.parents) > 1
+
+
+def _run_git(repo: Path, args: list[str], timeout: int = _GIT_TIMEOUT_SECONDS) -> str:
+    try:
+        result = subprocess.run(  # noqa: S603
+            ["git", "-c", "safe.directory=*", "-C", str(repo), *args],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise GitError(f"git {' '.join(args)} timed out") from exc
+    if result.returncode != 0:
+        raise GitError(result.stderr.strip() or f"git {' '.join(args)} failed")
+    return result.stdout
+
+
+def rev_parse(repo: Path, rev: str = "HEAD") -> str:
+    return _run_git(repo, ["rev-parse", rev]).strip()
+
+
+def remote_url(repo: Path, name: str = "origin") -> str | None:
+    try:
+        url = _run_git(repo, ["remote", "get-url", name]).strip()
+    except GitError:
+        return None
+    return url or None
+
+
+def repository_identity(repo: Path, *, include_local_path: bool) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "name": repo.name,
+        "remote": remote_url(repo),
+    }
+    if include_local_path:
+        payload["path"] = str(repo.resolve())
+    return payload
+
+
+def read_commits(repo: Path, *, include_files: bool = False) -> list[GitCommit]:
+    """Read commit metadata. File names are optional (vendor heuristic)."""
+    fmt = "%H%x1f%ae%x1f%P%x1f%ad%x1f%s"
+    args = ["log", f"--format={fmt}", "--date=short"]
+    if include_files:
+        args.append("--name-only")
+    raw = _run_git(repo, args)
+    return _parse_log(raw, include_files=include_files)
+
+
+def _parse_log(raw: str, *, include_files: bool) -> list[GitCommit]:
+    commits: list[GitCommit] = []
+    current: GitCommit | None = None
+    files: list[str] = []
+
+    def flush() -> None:
+        nonlocal current, files
+        if current is None:
+            return
+        current.files = tuple(files)
+        commits.append(current)
+        current = None
+        files = []
+
+    for line in raw.splitlines():
+        if "\x1f" in line:
+            flush()
+            parts = line.split("\x1f")
+            if len(parts) != 5:
+                continue
+            sha, email, parents, date, subject = parts
+            current = GitCommit(
+                sha=sha,
+                author_email=email,
+                parents=tuple(p for p in parents.split() if p),
+                date=date,
+                subject=subject,
+            )
+            files = []
+            continue
+        if include_files and current is not None and line.strip():
+            files.append(line.strip())
+    flush()
+    return commits

tep_core/identity.py

@@ -0,0 +1,109 @@
+"""Load `.tep/identity.toml` (identity-v1).
+
+Vocabulary is shared with Grift actor_attributions:
+canonical_id, emails, github_login, attribution_state.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import tomllib
+
+from tep_core.version import IDENTITY_SCHEMA_VERSION
+
+ATTRIBUTION_STATES = frozenset({"verified", "claimed", "inferred", "unresolved", "external", "bot"})
+TENANT_STATES = frozenset({"verified", "claimed", "inferred"})
+
+
+@dataclass(frozen=True)
+class Actor:
+    canonical_id: str
+    emails: tuple[str, ...]
+    github_login: str | None
+    attribution_state: str
+
+
+@dataclass
+class IdentityConfig:
+    schema_version: str = IDENTITY_SCHEMA_VERSION
+    email_patterns: tuple[re.Pattern[str], ...] = ()
+    actors: tuple[Actor, ...] = ()
+    source_path: Path | None = None
+    pending_attribution: bool = True
+    _email_to_actor: dict[str, Actor] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        mapping: dict[str, Actor] = {}
+        for actor in self.actors:
+            for email in actor.emails:
+                mapping[email.lower()] = actor
+        self._email_to_actor = mapping
+
+    @property
+    def actor_count(self) -> int:
+        return len(self.actors)
+
+    def actor_for_email(self, email: str) -> Actor | None:
+        return self._email_to_actor.get(email.lower())
+
+    def is_tenant_email(self, email: str) -> bool:
+        actor = self.actor_for_email(email)
+        if actor is not None and actor.attribution_state in TENANT_STATES:
+            return True
+        return any(pattern.search(email) for pattern in self.email_patterns)
+
+    def state_for_email(self, email: str) -> str:
+        actor = self.actor_for_email(email)
+        if actor is not None:
+            return actor.attribution_state
+        if any(pattern.search(email) for pattern in self.email_patterns):
+            return "inferred"
+        return "unresolved"
+
+
+def empty_identity() -> IdentityConfig:
+    return IdentityConfig(pending_attribution=True)
+
+
+def load_identity(path: Path | None) -> IdentityConfig:
+    if path is None or not path.is_file():
+        return empty_identity()
+    with path.open("rb") as handle:
+        data = tomllib.load(handle)
+    raw_patterns = list(data.get("tenant", {}).get("email_patterns", []) or [])
+    patterns = tuple(re.compile(p, re.I) for p in raw_patterns)
+    actors: list[Actor] = []
+    for row in data.get("actors", []) or []:
+        state = str(row.get("attribution_state", "unresolved"))
+        if state not in ATTRIBUTION_STATES:
+            raise ValueError(f"unknown attribution_state: {state}")
+        emails = tuple(str(e) for e in (row.get("emails") or []) if e)
+        actors.append(
+            Actor(
+                canonical_id=str(row.get("canonical_id") or ""),
+                emails=emails,
+                github_login=row.get("github_login"),
+                attribution_state=state,
+            )
+        )
+    pending = not patterns and not actors
+    return IdentityConfig(
+        schema_version=str(data.get("schema_version") or IDENTITY_SCHEMA_VERSION),
+        email_patterns=patterns,
+        actors=tuple(actors),
+        source_path=path,
+        pending_attribution=pending,
+    )
+
+
+def discover_identity(repo: Path, explicit: Path | None) -> IdentityConfig:
+    if explicit is not None:
+        return load_identity(explicit)
+    candidates = [repo / ".tep" / "identity.toml", Path.cwd() / ".tep" / "identity.toml"]
+    for candidate in candidates:
+        if candidate.is_file():
+            return load_identity(candidate)
+    return empty_identity()

tep_core/lineage.py

@@ -0,0 +1,22 @@
+"""Lineage: has_upstream_lineage = is_fork OR bool(parent)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Lineage:
+    is_fork: bool = False
+    parent: str | None = None
+
+    @property
+    def has_upstream_lineage(self) -> bool:
+        return self.is_fork or bool(self.parent)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "is_fork": self.is_fork,
+            "parent": self.parent,
+            "has_upstream_lineage": self.has_upstream_lineage,
+        }

tep_core/observation.py

@@ -0,0 +1,34 @@
+"""Observed vs not_observed. Zero is a legal observed value."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Observed:
+    value: Any
+    unit: str
+    sample_size: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "kind": "observed",
+            "value": self.value,
+            "unit": self.unit,
+        }
+        if self.sample_size is not None:
+            payload["sample_size"] = self.sample_size
+        return payload
+
+
+@dataclass(frozen=True)
+class NotObserved:
+    reason: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"kind": "not_observed", "reason": self.reason}
+
+
+Observation = Observed | NotObserved

tep_core/origin.py

@@ -0,0 +1,158 @@
+"""Origin classifier (revised taxonomy: SO2 8-class + unresolved/bot + P0-d-2)."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+
+from tep_core.gitutil import GitCommit
+from tep_core.identity import IdentityConfig
+from tep_core.lineage import Lineage
+from tep_core.observation import NotObserved, Observed
+
+# Grift migration 000073 + 000075 vocabulary.
+ORIGIN_CLASSES = (
+    "inherited_upstream",
+    "upstream_sync",
+    "tenant_unique",
+    "tenant_merge_or_sync",
+    "tenant_derivative",
+    "external_upstream_contribution",
+    "template_inherited",
+    "generated_or_vendor",
+    "ambiguous_origin",
+    "unresolved",
+    "bot",
+)
+
+ALWAYS_OBSERVED = frozenset(
+    {
+        "tenant_unique",
+        "inherited_upstream",
+        "generated_or_vendor",
+        "ambiguous_origin",
+        "unresolved",
+        "bot",
+    }
+)
+
+BOT_EMAIL_RE = re.compile(
+    r"\[bot\]@|^action@github\.com$|^github-actions|^dependabot|^renovate",
+    re.I,
+)
+
+_VENDOR_PREFIXES = (
+    "vendor/",
+    "node_modules/",
+    "third_party/",
+    "third-party/",
+)
+_VENDOR_SUFFIXES = (
+    ".min.js",
+    ".min.css",
+    ".pb.go",
+)
+
+
+def is_bot_email(email: str) -> bool:
+    return BOT_EMAIL_RE.search(email) is not None
+
+
+def is_undecidable_email(email: str) -> bool:
+    """True when origin cannot be attributed even with more identity config."""
+    return not email.strip()
+
+
+def is_vendor_path(path: str) -> bool:
+    lowered = path.replace("\\", "/").lstrip("./")
+    if any(lowered.startswith(prefix) for prefix in _VENDOR_PREFIXES):
+        return True
+    return any(lowered.endswith(suffix) for suffix in _VENDOR_SUFFIXES)
+
+
+def is_vendor_only(commit: GitCommit) -> bool:
+    if not commit.files:
+        return False
+    return all(is_vendor_path(path) for path in commit.files)
+
+
+@dataclass
+class OriginResult:
+    counts: Counter[str] = field(default_factory=Counter)
+    bot_commits: int = 0
+    tenant_dates: list[str] = field(default_factory=list)
+    tenant_day_counts: Counter[str] = field(default_factory=Counter)
+    classes_by_sha: dict[str, str] = field(default_factory=dict)
+
+    def origin_observations(
+        self,
+        *,
+        template_provided: bool,
+        parent_repo_provided: bool,
+        has_upstream_lineage: bool,
+    ) -> dict[str, dict[str, object]]:
+        payload: dict[str, dict[str, object]] = {}
+        for name in ORIGIN_CLASSES:
+            if name == "upstream_sync" and not has_upstream_lineage:
+                payload[name] = NotObserved("no_upstream_lineage").to_dict()
+            elif name == "tenant_merge_or_sync" and has_upstream_lineage:
+                payload[name] = NotObserved("lineage_present").to_dict()
+            elif name in ALWAYS_OBSERVED or name in {
+                "upstream_sync",
+                "tenant_merge_or_sync",
+            }:
+                payload[name] = Observed(self.counts[name], "commits").to_dict()
+            elif name == "template_inherited" and not template_provided:
+                payload[name] = NotObserved("template_not_provided").to_dict()
+            elif (
+                name
+                in {
+                    "tenant_derivative",
+                    "external_upstream_contribution",
+                }
+                and not parent_repo_provided
+            ):
+                payload[name] = NotObserved("parent_repo_not_provided").to_dict()
+            else:
+                payload[name] = Observed(self.counts[name], "commits").to_dict()
+        return payload
+
+
+def classify_commits(
+    commits: list[GitCommit],
+    identity: IdentityConfig,
+    lineage: Lineage,
+) -> OriginResult:
+    result = OriginResult()
+    has_lineage = lineage.has_upstream_lineage
+
+    for commit in commits:
+        email = commit.author_email
+        actor = identity.actor_for_email(email)
+        if is_bot_email(email) or (actor is not None and actor.attribution_state == "bot"):
+            result.bot_commits += 1
+            result.counts["bot"] += 1
+            result.classes_by_sha[commit.sha] = "bot"
+            continue
+        if is_vendor_only(commit):
+            result.counts["generated_or_vendor"] += 1
+            result.classes_by_sha[commit.sha] = "generated_or_vendor"
+            continue
+        tenant = identity.is_tenant_email(email)
+        if tenant:
+            if commit.is_merge:
+                klass = "upstream_sync" if has_lineage else "tenant_merge_or_sync"
+            else:
+                klass = "tenant_unique"
+                result.tenant_dates.append(commit.date)
+                result.tenant_day_counts[commit.date] += 1
+        elif has_lineage:
+            klass = "inherited_upstream"
+        elif is_undecidable_email(email):
+            klass = "ambiguous_origin"
+        else:
+            klass = "unresolved"
+        result.counts[klass] += 1
+        result.classes_by_sha[commit.sha] = klass
+    return result

tep_core/paths.py

@@ -0,0 +1,48 @@
+"""Path roles for test co-change and rework (clean-room)."""
+
+from __future__ import annotations
+
+import re
+
+TEST_PATH_RE = re.compile(
+    r"(^|/)(tests|test|__tests__|spec)/"
+    r"|(^|/)(test_[^/]+|_test)\.py$"
+    r"|_test\.go$"
+    r"|\.spec\.(ts|tsx|js|jsx)$"
+    r"|\.test\.(ts|tsx|js|jsx)$"
+    r"|_spec\.rb$",
+    re.I,
+)
+
+DOC_OR_CONFIG_RE = re.compile(
+    r"\.(md|rst)$"
+    r"|(^|/)(docs|documentation|\.github)(/|$)"
+    r"|(^|/)(LICENSE|CHANGELOG|CONTRIBUTING)",
+    re.I,
+)
+
+
+def normalize(path: str) -> str:
+    return path.replace("\\", "/").lstrip("./")
+
+
+def is_test_path(path: str) -> bool:
+    return bool(TEST_PATH_RE.search(normalize(path)))
+
+
+def is_doc_or_config_path(path: str) -> bool:
+    p = normalize(path)
+    if is_test_path(p):
+        return False
+    return bool(DOC_OR_CONFIG_RE.search(p))
+
+
+def is_prod_path(path: str) -> bool:
+    return not is_test_path(path) and not is_doc_or_config_path(path)
+
+
+def split_paths(files: tuple[str, ...] | list[str]) -> tuple[list[str], list[str], list[str]]:
+    prod = [f for f in files if is_prod_path(f)]
+    tests = [f for f in files if is_test_path(f)]
+    docs = [f for f in files if is_doc_or_config_path(f)]
+    return prod, tests, docs

tep_core/reference.py

@@ -0,0 +1,76 @@
+"""Reference distribution lookup. Same-scope only. n<30 suppresses position."""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+from tep_core.observation import NotObserved
+from tep_core.scope import require_same_scope
+
+REFERENCE_VERSION = "v2026.09"
+MIN_N = 30
+_DATA = Path(__file__).resolve().parent / "data" / "v2026.09" / "distributions.json"
+
+
+@lru_cache(maxsize=1)
+def load_distributions() -> dict:
+    if not _DATA.is_file():
+        return {
+            "version": REFERENCE_VERSION,
+            "analysis_scope": "repo",
+            "metrics": {},
+        }
+    return json.loads(_DATA.read_text(encoding="utf-8"))
+
+
+def _quantile_index(sorted_values: list[float], value: float) -> int:
+    """1-based decile in 1..10 (ceil of 10 * fraction at-or-below)."""
+    if not sorted_values:
+        return 1
+    below = sum(1 for item in sorted_values if item <= value)
+    frac = below / len(sorted_values)
+    decile = int(frac * 10)
+    if decile < 1:
+        return 1
+    if decile > 10:
+        return 10
+    return decile
+
+
+def interpret_metric(
+    *,
+    report_scope: str,
+    metric_id: str,
+    observation: dict,
+) -> dict[str, object]:
+    dist = load_distributions()
+    if report_scope != "repo":
+        return NotObserved("scope_is_tenant").to_dict()
+    require_same_scope(report_scope, str(dist.get("analysis_scope") or "repo"))
+    if observation.get("kind") != "observed":
+        return NotObserved("metric_not_observed").to_dict()
+    inner = observation.get("all_time") or observation
+    if inner.get("kind") != "observed" or inner.get("value") is None:
+        return NotObserved("metric_not_observed").to_dict()
+    population = inner.get("population")
+    if inner.get("narrate_rate") is False or (isinstance(population, int) and population < 20):
+        return NotObserved("insufficient_population").to_dict()
+    block = (dist.get("metrics") or {}).get(metric_id) or {}
+    values = list(block.get("values") or [])
+    n = int(block.get("n") or len(values))
+    if n < MIN_N:
+        return NotObserved("reference_too_small").to_dict()
+    value = float(inner["value"])
+    decile = _quantile_index(sorted(values), value)
+    return {
+        "kind": "observed",
+        "reference_version": dist.get("version", REFERENCE_VERSION),
+        "analysis_scope": "repo",
+        "n": n,
+        "decile": decile,
+        "value": value,
+        "unit": inner.get("unit", "ratio"),
+        "metric_id": metric_id,
+    }