grift-cli 0.5.0__py3-none-any.whl

tep_core/report.py

@@ -0,0 +1,219 @@
+"""Markdown rendering. Units required. No grade vocabulary. No person scorecards."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# P0-d-2: first-party merges are not narrated as upstream_sync.
+_ORIGIN_ORDER = (
+    "tenant_unique",
+    "tenant_merge_or_sync",
+    "upstream_sync",
+    "inherited_upstream",
+    "unresolved",
+    "ambiguous_origin",
+    "tenant_derivative",
+    "external_upstream_contribution",
+    "template_inherited",
+    "generated_or_vendor",
+    "bot",
+)
+
+_DISPLAY_NAME = {
+    "tenant_merge_or_sync": "merge commits (PR flow)",
+}
+
+_SKIP_NOT_OBSERVED = frozenset({"upstream_sync", "tenant_merge_or_sync"})
+
+
+def _fmt_obs(obs: dict[str, Any], *, fallback: str = "not observed") -> str:
+    if obs.get("kind") == "not_observed":
+        return f"not observed ({obs.get('reason', 'unspecified')})"
+    value = obs.get("value")
+    unit = obs.get("unit", "")
+    sample = obs.get("sample_size")
+    if sample is not None:
+        return f"{value} {unit} (n={sample} days)"
+    return f"{value} {unit}".strip() if unit else fallback
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    prov = report["provenance"]
+    identity = report["identity"]
+    lineage = report["lineage"]
+    origin = report["origin"]
+    activity = report["activity"]
+    core = report["core_activity_period"]
+    tests = report["test_frameworks"]
+    repo = report.get("repository") or {}
+
+    lines: list[str] = [
+        "# TEP analysis",
+        "",
+        "## Provenance",
+        f"- method: {prov.get('method_name') or 'TEP'}",
+        f"- tool: {prov['tool_name']} {prov['tool_version']}",
+        f"- definition version: {prov['definition_version']}",
+        f"- analyzed commit SHA: `{prov['analyzed_commit_sha']}`",
+        f"- analyzed at: {prov['analyzed_at']}",
+        "",
+        "## Repository",
+        f"- name: {repo.get('name') or 'unknown'}",
+        f"- remote: {repo.get('remote') or 'none'}",
+        "",
+        "## Lineage",
+        f"- is_fork: {str(lineage['is_fork']).lower()}",
+        f"- parent: {lineage['parent'] or 'none'}",
+        f"- has_upstream_lineage: {str(lineage['has_upstream_lineage']).lower()}",
+        "",
+        "## Identity",
+        (
+            f"- pending_attribution: {str(identity['pending_attribution']).lower()} "
+            f"({identity['actor_count']} configured actors)"
+        ),
+        "",
+        "## Origin (commits)",
+    ]
+    for name in _ORIGIN_ORDER:
+        obs = origin.get(name)
+        if not obs:
+            continue
+        if obs.get("kind") == "not_observed" and name in _SKIP_NOT_OBSERVED:
+            continue
+        if (
+            name == "inherited_upstream"
+            and not lineage.get("has_upstream_lineage")
+            and obs.get("kind") == "observed"
+            and obs.get("value") == 0
+        ):
+            continue
+        label = _DISPLAY_NAME.get(name, name)
+        lines.append(f"- {label}: {_fmt_obs(obs)}")
+    lines += [
+        "",
+        "## Activity (tenant_unique commits)",
+        f"- tenant commits: {_fmt_obs(activity['tenant_commits'])}",
+        f"- active days: {_fmt_obs(activity['active_days'])}",
+        f"- commits per active day: {_fmt_obs(activity['commits_per_active_day'])}",
+        (
+            "- commits per active day (median): "
+            f"{_fmt_obs(activity['commits_per_active_day_median'])}"
+        ),
+        f"- active days (13 weeks): {_fmt_obs(activity['active_days_13w'])}",
+        "",
+        "## Core activity period",
+    ]
+    if core.get("kind") == "not_observed":
+        lines.append(f"- not observed ({core.get('reason')})")
+    else:
+        share_pct = round(float(core["share"]) * 100, 1)
+        lines.append(
+            f"- {core['start']} to {core['end']} "
+            f"({share_pct} percent of tenant_unique commits; {core['unit']}; "
+            f"definition {core['definition_version']})"
+        )
+        if activity["commits_per_active_day_median"].get("sample_size", 99) < 5:
+            lines.append("- comparison narrative omitted: median sample size is below 5 days")
+    lines += ["", "## Test frameworks"]
+    if tests.get("kind") == "not_observed":
+        lines.append(f"- not observed ({tests.get('reason')})")
+    else:
+        names = ", ".join(tests.get("names") or []) or "none named"
+        lines.append(f"- observed: {names} (boolean {tests.get('value')})")
+    lines += ["", "## Test co-change", f"- {_fmt_metric_block(report.get('test_cochange'))}"]
+    interp = report.get("interpretation") or {}
+    lines += _fmt_interp_line("co-change", interp.get("test_cochange"))
+    lines += ["", "## Rework", *_fmt_rework_lines(report.get("rework"))]
+    lines += _fmt_interp_line("corrective rework", interp.get("corrective_rework"))
+    lines += ["", "## Survival (tau=180 days)", f"- {_fmt_metric_block(report.get('survival'))}"]
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _fmt_metric_block(obs: dict[str, Any] | None) -> str:
+    if not obs:
+        return "not observed (missing)"
+    if obs.get("kind") == "not_observed":
+        return f"not observed ({obs.get('reason')})"
+    if "all_time" in obs:
+        block = obs["all_time"]
+        if block.get("kind") == "not_observed":
+            return f"all-time not observed ({block.get('reason')})"
+        rate = block.get("value")
+        pop = block.get("population")
+        unit = block.get("unit", "ratio")
+        narrate = block.get("narrate_rate", True)
+        if not narrate:
+            return (
+                "all-time not narrated (insufficient_population; "
+                f"{pop}コミット中{block.get('cochanged')}件)"
+            )
+        return f"all-time {rate} {unit} (population {pop} commits)"
+    if "corrective_rework_rate" in obs:
+        return _fmt_rework_lines(obs)[0].lstrip("- ")
+    if "survival_index" in obs:
+        return (
+            f"survival index {obs['survival_index']} {obs.get('unit')} "
+            f"(tau {obs.get('tau_days')} days; {obs.get('files_sampled')} files; "
+            f"{obs.get('lines_sampled')} lines)"
+        )
+    return "observed"
+
+
+def _fmt_rework_lines(obs: dict[str, Any] | None) -> list[str]:
+    if not obs:
+        return ["- not observed (missing)"]
+    if obs.get("kind") == "not_observed":
+        return [f"- not observed ({obs.get('reason')})"]
+    corr = obs.get("corrective_rework_rate") or {}
+    touch = obs.get("path_retouch_rate") or {}
+    window = obs.get("window_days")
+    lines: list[str] = []
+    if corr.get("kind") == "observed":
+        if corr.get("narrate_rate", True):
+            lines.append(
+                f"- corrective rework (observational, subject-convention dependent; "
+                f"not an evidence claim): {corr.get('value')} {corr.get('unit')} "
+                f"({corr.get('corrective_commits')} of {corr.get('population')} "
+                f"commits; {window} day window)"
+            )
+            lines.append(
+                "- limit: corrective rework is fresh-work stability "
+                "(recent paths needing an immediate fix/revert); "
+                "it is not a bug count"
+            )
+        else:
+            lines.append(
+                "- corrective rework (observational, subject-convention dependent; "
+                "not an evidence claim): not narrated (insufficient_population; "
+                f"{corr.get('population')}コミット中{corr.get('corrective_commits')}件)"
+            )
+            lines.append(
+                "- limit: corrective rework is fresh-work stability "
+                "(recent paths needing an immediate fix/revert); "
+                "it is not a bug count"
+            )
+    touch_pop = touch.get("population")
+    if isinstance(touch_pop, int) and touch_pop < 20:
+        lines.append(
+            "- path retouch (observational, not an evidence claim): "
+            "not narrated (insufficient_population; "
+            f"{touch_pop}コミット中{touch.get('retouch_commits')}件)"
+        )
+    else:
+        lines.append(
+            "- path retouch (observational, not an evidence claim): "
+            f"{touch.get('value')} {touch.get('unit')} "
+            f"({touch.get('retouch_commits')} of {touch.get('population')} commits)"
+        )
+    return lines or ["- observed"]
+
+
+def _fmt_interp_line(label: str, obs: dict[str, Any] | None) -> list[str]:
+    if not obs or obs.get("kind") != "observed":
+        return []
+    return [
+        f"- {label} {obs.get('value')} ({obs.get('analysis_scope')} scope) — "
+        f"reference corpus {obs.get('reference_version')} (n={obs.get('n')}) "
+        f"decile {obs.get('decile')}"
+    ]

tep_core/rework.py

@@ -0,0 +1,117 @@
+"""Rework metrics among production commits in the analysis scope (H-4 / WP1b-1).
+
+path_retouch_rate and corrective_rework_rate are observational only.
+corrective_rework_rate depends on commit-subject conventions (fix/revert) and
+must not be used as an evidence claim (measurement confounding: conventional
+commit culture inflates detection). Line-level rework is deferred to v0.6.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+
+from tep_core.gitutil import GitCommit
+from tep_core.observation import NotObserved
+from tep_core.origin import OriginResult
+from tep_core.paths import split_paths
+from tep_core.scope import DEFAULT_SCOPE, population_shas
+
+REWORK_DEFINITION_VERSION = "rework-v1.1-2026-08-22"
+REWORK_WINDOW_DAYS = 21
+
+# Conventional-commit and common prose: fix / hotfix / bug / revert.
+_CORRECTIVE_SUBJECT_RE = re.compile(
+    r"^(revert\b|fix(\b|\(|:|!)|hotfix\b|bugfix\b|bug(\b|\(|:)|fixes\s+#)",
+    re.I,
+)
+
+
+def _parse_day(value: str) -> date:
+    year, month, day = (int(part) for part in value.split("-"))
+    return date(year, month, day)
+
+
+def is_corrective_subject(subject: str) -> bool:
+    return bool(_CORRECTIVE_SUBJECT_RE.search(subject) or "This reverts commit" in subject)
+
+
+def rework_metrics(
+    commits: list[GitCommit],
+    origin: OriginResult,
+    *,
+    pending_attribution: bool,
+    scope: str = DEFAULT_SCOPE,
+) -> dict[str, object]:
+    shas = population_shas(commits, origin, scope)
+    if scope == "tenant" and pending_attribution and not shas:
+        return NotObserved("pending_attribution").to_dict()
+    if not shas:
+        return NotObserved(
+            "no_tenant_commits" if scope == "tenant" else "no_human_commits"
+        ).to_dict()
+    if not any(c.files for c in commits):
+        return NotObserved("commit_paths_unavailable").to_dict()
+
+    prod_commits = [c for c in commits if c.sha in shas and split_paths(c.files)[0]]
+    if not prod_commits:
+        return NotObserved("no_production_commits").to_dict()
+
+    chrono = sorted(prod_commits, key=lambda c: c.date)
+    last_touch: dict[str, date] = {}
+    retouch = 0
+    corrective = 0
+    for commit in chrono:
+        prod, _, _ = split_paths(commit.files)
+        day = _parse_day(commit.date)
+        recent_path = False
+        for path in prod:
+            prev = last_touch.get(path)
+            if prev is not None and (day - prev).days <= REWORK_WINDOW_DAYS:
+                recent_path = True
+            last_touch[path] = day
+        if recent_path:
+            retouch += 1
+            if is_corrective_subject(commit.subject):
+                corrective += 1
+
+    reverts = sum(
+        1
+        for c in commits
+        if c.sha in shas
+        and is_corrective_subject(c.subject)
+        and (c.subject.lower().startswith("revert") or "This reverts commit" in c.subject)
+    )
+    population = len(prod_commits)
+    return {
+        "kind": "observed",
+        "definition_version": REWORK_DEFINITION_VERSION,
+        "analysis_scope": scope,
+        "window_days": REWORK_WINDOW_DAYS,
+        "evidence_claim": None,
+        "corrective_rework_rate": {
+            "kind": "observed",
+            "value": round(corrective / population, 4),
+            "unit": "ratio",
+            "corrective_commits": corrective,
+            "population": population,
+            "narrate_rate": population >= 20,
+            "evidence_claim": False,
+        },
+        "path_retouch_rate": {
+            "kind": "observed",
+            "value": round(retouch / population, 4),
+            "unit": "ratio",
+            "retouch_commits": retouch,
+            "population": population,
+            "evidence_claim": False,
+        },
+        "revert_rate": {
+            "kind": "observed",
+            "value": round(reverts / max(len(shas), 1), 4),
+            "unit": "ratio",
+            "reverts": reverts,
+            "population": len(shas),
+        },
+        "line_rework": NotObserved("deferred_to_v0.6").to_dict(),
+    }

tep_core/scope.py

@@ -0,0 +1,38 @@
+"""Analysis scope: tenant (evidence) vs repo (process / reference distribution)."""
+
+from __future__ import annotations
+
+from tep_core.gitutil import GitCommit
+from tep_core.origin import OriginResult
+
+SCOPES = ("tenant", "repo")
+DEFAULT_SCOPE = "tenant"
+TENANT_ORIGIN = frozenset({"tenant_unique"})
+
+
+class ScopeMismatchError(ValueError):
+    """Comparing values computed under different analysis scopes is forbidden."""
+
+
+def require_same_scope(left: str, right: str) -> None:
+    if left != right:
+        raise ScopeMismatchError(
+            f"scope mismatch: {left!r} vs {right!r} — reference lookup is same-scope only"
+        )
+
+
+def population_shas(
+    commits: list[GitCommit],
+    origin: OriginResult,
+    scope: str,
+) -> set[str]:
+    """SHAs eligible for co-change/rework. Merge and bot are always excluded."""
+    if scope not in SCOPES:
+        raise ValueError(f"unknown scope: {scope}")
+    if scope == "tenant":
+        return {sha for sha, klass in origin.classes_by_sha.items() if klass in TENANT_ORIGIN}
+    return {
+        commit.sha
+        for commit in commits
+        if origin.classes_by_sha.get(commit.sha) != "bot" and not commit.is_merge
+    }

tep_core/survival.py

@@ -0,0 +1,73 @@
+"""Repo-level time-decayed survival (EIS-style, tau=180d). No person scorecards."""
+
+from __future__ import annotations
+
+import math
+import re
+from pathlib import Path
+
+from tep_core.gitutil import GitError, _run_git
+from tep_core.observation import NotObserved
+
+SURVIVAL_DEFINITION_VERSION = "survival-v1-2026-08-22"
+TAU_DAYS = 180
+TAU_SECONDS = TAU_DAYS * 86400
+SRC_EXT = (".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".vue", ".svelte", ".astro", ".swift")
+EXCLUDE = re.compile(r"node_modules/|vendor/|dist/|build/|\.min\.|generated")
+DEFAULT_MAX_FILES = 40
+BLAME_TIMEOUT = 12
+
+
+def survival_metrics(
+    repo: Path,
+    *,
+    enabled: bool,
+    max_files: int = DEFAULT_MAX_FILES,
+) -> dict[str, object]:
+    if not enabled:
+        return NotObserved("survival_scan_disabled").to_dict()
+    try:
+        listed = _run_git(repo, ["ls-files"]).splitlines()
+        head_ts = int(_run_git(repo, ["log", "-1", "--format=%at"]).strip() or "0")
+    except GitError:
+        return NotObserved("git_unavailable").to_dict()
+
+    files = [f for f in listed if f.endswith(SRC_EXT) and not EXCLUDE.search(f)]
+    if not files:
+        return NotObserved("no_source_files").to_dict()
+
+    step = max(1, len(files) // max_files)
+    sample = files[::step][:max_files]
+    weights = 0.0
+    lines = 0
+    scanned = 0
+    for path in sample:
+        try:
+            out = _run_git(
+                repo,
+                ["blame", "--line-porcelain", "HEAD", "--", path],
+                timeout=BLAME_TIMEOUT,
+            )
+        except GitError:
+            continue
+        if not out:
+            continue
+        scanned += 1
+        for line in out.splitlines():
+            if line.startswith("author-time "):
+                ts = int(line.split()[1])
+                age = max(0, head_ts - ts)
+                weights += math.exp(-age / TAU_SECONDS)
+                lines += 1
+    if lines == 0 or scanned == 0:
+        return NotObserved("blame_unavailable").to_dict()
+    return {
+        "kind": "observed",
+        "definition_version": SURVIVAL_DEFINITION_VERSION,
+        "tau_days": TAU_DAYS,
+        "files_sampled": scanned,
+        "source_files": len(files),
+        "lines_sampled": lines,
+        "survival_index": round(weights / lines, 4),
+        "unit": "dimensionless",
+    }

tep_core/tests_observed.py

@@ -0,0 +1,102 @@
+"""Test-framework observation at HEAD. not_observed != 0."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from tep_core.observation import NotObserved
+
+FRAMEWORK_MARKERS = (
+    "vitest",
+    "jest",
+    "playwright",
+    "cypress",
+    "mocha",
+    "jasmine",
+    "pytest",
+    "unittest",
+    "nyc",
+    "testing-library",
+    "ava",
+    "karma",
+    "selenium",
+    "testify",
+    "ginkgo",
+)
+
+TEST_DIRECTORIES = (
+    "tests",
+    "test",
+    "__tests__",
+    "spec",
+)
+
+_QUOTED_TOKEN = re.compile(r"[\"']([A-Za-z0-9_.-]+)")
+
+
+def _package_json_names(root: Path) -> set[str]:
+    path = root / "package.json"
+    if not path.is_file():
+        return set()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return set()
+    keys = {
+        **(data.get("dependencies") or {}),
+        **(data.get("devDependencies") or {}),
+    }
+    return {str(name).lower() for name in keys}
+
+
+def _quoted_tokens(text: str) -> set[str]:
+    return {match.group(1).lower() for match in _QUOTED_TOKEN.finditer(text)}
+
+
+def _manifest_names(root: Path) -> set[str]:
+    names: set[str] = set()
+    names |= _package_json_names(root)
+    for rel in ("pyproject.toml", "tox.ini", "setup.cfg", "Pipfile", "go.mod", "Gemfile"):
+        path = root / rel
+        if path.is_file():
+            names |= _quoted_tokens(path.read_text(encoding="utf-8", errors="replace"))
+    for req in root.glob("requirements*.txt"):
+        names |= _quoted_tokens(req.read_text(encoding="utf-8", errors="replace"))
+        for line in req.read_text(encoding="utf-8", errors="replace").splitlines():
+            token = re.split(r"[<>=!~;\s]", line.strip(), maxsplit=1)[0].lower()
+            if token:
+                names.add(token)
+    return names
+
+
+def _matched_markers(package_names: set[str]) -> list[str]:
+    found: list[str] = []
+    for marker in FRAMEWORK_MARKERS:
+        if any(marker in pkg for pkg in package_names):
+            found.append(marker)
+    return found
+
+
+def _test_directories(root: Path) -> list[str]:
+    found: list[str] = []
+    for name in TEST_DIRECTORIES:
+        candidate = root / name
+        if candidate.is_dir():
+            found.append(name)
+    return found
+
+
+def observe_test_frameworks(root: Path) -> dict[str, object]:
+    names = _matched_markers(_manifest_names(root))
+    directories = _test_directories(root)
+    if not names and not directories:
+        return NotObserved("no_test_framework_or_directory").to_dict()
+    return {
+        "kind": "observed",
+        "value": True,
+        "names": names,
+        "directories": directories,
+        "unit": "boolean",
+    }

tep_core/version.py

@@ -0,0 +1,6 @@
+__version__ = "0.5.0"
+DEFINITION_VERSION = "tep-v0.5.0-2026-08-22"
+ORIGIN_DEFINITION_VERSION = "origin-v1.1-2026-08-22"
+ACTIVITY_DEFINITION_VERSION = "activity-v1-2026-08-16"
+CORE_ACTIVITY_DEFINITION_VERSION = "core-activity-v1-2026-08-16"
+IDENTITY_SCHEMA_VERSION = "identity-v1"