impact-gate 0.1.0__py3-none-any.whl

impact_gate/__init__.py

@@ -0,0 +1,8 @@
+"""impact-gate — report the change-impact of a change and gate on it.
+
+A lightweight front-end over the change-impact measure (shared, single-sourced with
+Surveyor / the PetClinic-Evolve harness). It scores a change against a base — a
+committed range vs `main`, staged changes, or the working tree — reports the number,
+and warns or blocks when the impact is too high.
+"""
+__version__ = "0.1.0"

impact_gate/baseline.py

@@ -0,0 +1,208 @@
+"""The project baseline: the repo's own per-commit impact distribution, and the
+empirical-Bayes blend of it with the shipped seed prior.
+
+Scope. The walk starts from the merged base branch (default `main`) and follows its
+first-parent mainline, so only landed work is measured; an unmerged in-flight branch is
+never reached, because the walk only ever follows real merge commits.
+
+One observation = one atomic landed change:
+  * a main non-merge commit -> its own diff vs its parent;
+  * a leaf MR (a merged branch with no MRs inside it) -> the net change from the branch
+    start (merge-base of the merge's parents) to the branch tip;
+  * a parent MR (a merged branch that contains MRs) -> its direct commits netted per run
+    between the merges on its spine, each run based at the preceding synced base; every
+    child MR recurses, and a merge that only syncs the parent/main branch in is skipped.
+A merge is never scored as its own diff, so a long-running roll-up cannot inflate things.
+
+Each observation is one composite impact = (Σ mutation + Σ godclass) * files. The
+distribution of that over all observations is the baseline. The gate always grades the
+composite; mutation cost stays a per-file ranking signal (report side), never a rival
+distribution to gate against.
+
+Grading. A change's grade blends its percentile rank in this project distribution (n
+observations) with its rank against the per-language seed table, weighting the project by
+  w = n / (n + K)
+so a shallow history leans on the seed and a deep one trusts itself. K is curve_prior_weight.
+"""
+from __future__ import annotations
+
+import bisect
+import json
+import re
+from dataclasses import dataclass, field
+
+from . import gitio
+from .core.config import MeasureConfig
+from .core.gitplumb import GitRepo
+from .data import load_defaults, rank_in_table, seed_table
+from .engine import score_change
+
+_BD = load_defaults().get("baseline", {})
+
+
+# --------------------------------------------------------------------------- model
+
+@dataclass
+class Baseline:
+    """The project's composite per-observation distribution (ascending)."""
+    n: int
+    dist: list[int] = field(default_factory=list)
+    head: str | None = None
+    base_ref: str | None = None
+
+    def rank(self, value: float) -> float:
+        return _percentile_rank(self.dist, value)
+
+    def to_dict(self) -> dict:
+        return {"_meta": {"tool": "impact-gate", "n": self.n, "head": self.head,
+                          "base_ref": self.base_ref},
+                "distribution": self.dist}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Baseline":
+        meta = d.get("_meta", {})
+        dist = [int(v) for v in (d.get("distribution") or [])]
+        n = int(meta.get("n", len(dist)))
+        return cls(n=n, dist=dist, head=meta.get("head"),
+                   base_ref=meta.get("base_ref"))
+
+
+def _percentile_rank(sorted_vals: list[int], value: float) -> float:
+    """Percentile rank of `value` in an ascending list: fraction below plus half the
+    ties, in [0, 100]. Above every observation -> 100; at or below the smallest -> ~0."""
+    n = len(sorted_vals)
+    if n == 0:
+        return 0.0
+    lo = bisect.bisect_left(sorted_vals, value)
+    hi = bisect.bisect_right(sorted_vals, value)
+    return round((lo + 0.5 * (hi - lo)) / n * 100, 2)
+
+
+# ----------------------------------------------------------------------- the walk
+
+def build_baseline(repo_path: str, mcfg: MeasureConfig | None = None, *,
+                   base_ref: str | None = None, max_commits: int | None = None,
+                   exclude_subject_pattern: str | None = None) -> Baseline:
+    """Walk the merged history of `base_ref` into the project's impact distribution."""
+    mcfg = mcfg or MeasureConfig()
+    base_ref = base_ref or _BD.get("base_ref") or "HEAD"
+    if max_commits is None:
+        max_commits = _BD.get("max_commits")
+    if exclude_subject_pattern is None:
+        exclude_subject_pattern = _BD.get("exclude_subject_pattern")
+    pat = re.compile(exclude_subject_pattern) if exclude_subject_pattern else None
+
+    parents = gitio.rev_parents(repo_path, base_ref)
+    mainline = gitio.mainline_commits(repo_path, base_ref, max_commits)
+    repo = GitRepo(repo_path)
+    comp: list[int] = []
+    seen: set[str] = set()
+
+    def emit(old_rev: str, new_rev: str) -> None:
+        score = score_change(gitio.diff_between(repo, old_rev, new_rev), mcfg)
+        if score.empty:
+            return
+        comp.append(score.impact)
+
+    def walk_mr(merge_sha: str, p1: str, tip: str) -> None:
+        if merge_sha in seen:
+            return
+        seen.add(merge_sha)
+        if pat and pat.search(gitio.commit_subject(repo_path, merge_sha)):
+            return  # naming-convention exclusion: skip this MR entirely
+        start = gitio.merge_base(repo_path, p1, tip) or p1
+        spine = gitio.first_parent_spine(repo_path, start, tip)
+        base = start
+        for c in reversed(spine):                       # oldest first, along the branch
+            cps = parents.get(c) or gitio.rev_parents(repo_path, c).get(c, [])
+            if len(cps) < 2:
+                continue                                # direct commit: extends the run
+            prev = cps[0]                               # branch state just before this merge
+            if prev != base:
+                emit(base, prev)                        # net of the run of direct commits
+            for sec in cps[1:]:
+                if gitio.is_ancestor(repo_path, sec, p1):
+                    continue                            # a sync of parent/main: already counted
+                walk_mr(c, cps[0], sec)                 # a child MR: recurse
+            base = c                                    # advance past the merge
+        if base != tip:
+            emit(base, tip)                             # final run up to the branch tip
+
+    try:
+        for c in mainline:
+            ps = parents.get(c, [])
+            if len(ps) >= 2:                            # an MR landed on the mainline
+                for sec in ps[1:]:
+                    walk_mr(c, ps[0], sec)
+            else:                                       # a direct commit on the mainline
+                emit(ps[0] if ps else gitio.EMPTY_TREE, c)
+    finally:
+        repo.close()
+
+    comp.sort()
+    return Baseline(n=len(comp), dist=comp,
+                    head=gitio.head_sha(repo_path, base_ref), base_ref=base_ref)
+
+
+# ------------------------------------------------------------------- persistence
+
+def save_baseline(baseline: Baseline, path: str) -> None:
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(baseline.to_dict(), fh, indent=1)
+
+
+def load_baseline(path: str) -> Baseline | None:
+    """The cached baseline at `path`, or None if it is missing or unreadable."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return Baseline.from_dict(json.load(fh))
+    except (OSError, ValueError):
+        return None
+
+
+# ------------------------------------------------------------------------ grading
+
+@dataclass
+class Grade:
+    percentile: float            # the blended grade, 0..100
+    value: int                   # the composite impact that was graded
+    seed_percentile: float       # rank against the shipped per-language seed
+    project_percentile: float | None   # rank against project history (None at cold start)
+    weight: float                # w = n / (n + K): the project's share of the blend
+    n: int                       # project observations behind the grade
+    language: str | None
+
+
+def dominant_language(score) -> str | None:
+    """The language driving the change (highest-cost file), else None -> pooled seed."""
+    best, best_cost = None, -1
+    for f in score.files:
+        if f.lang and f.cost > best_cost:
+            best, best_cost = f.lang, f.cost
+    return best
+
+
+def grade_value(value: int, *, language: str | None,
+                baseline: Baseline | None, prior_weight_K: float) -> Grade:
+    seed_pct, seed_vals = seed_table(language)
+    seed_rank = rank_in_table(value, seed_pct, seed_vals)
+    n = baseline.n if baseline else 0
+    if n <= 0:
+        return Grade(seed_rank, value, seed_rank, None, 0.0, 0, language)
+    project_rank = baseline.rank(value)
+    denom = n + prior_weight_K
+    w = n / denom if denom > 0 else 1.0
+    blended = round(w * project_rank + (1 - w) * seed_rank, 2)
+    return Grade(blended, value, round(seed_rank, 2), round(project_rank, 2),
+                 round(w, 4), n, language)
+
+
+def grade_change(score, *, baseline: Baseline | None = None,
+                 prior_weight_K: float = 200) -> Grade:
+    """Grade a scored change by blending its project and seed percentile ranks.
+
+    The graded value is always the composite impact; the seed table is picked by the
+    change's dominant language.
+    """
+    return grade_value(score.impact, language=dominant_language(score),
+                       baseline=baseline, prior_weight_K=prior_weight_K)

impact_gate/cli.py

@@ -0,0 +1,201 @@
+"""impact-gate command line.
+
+  impact-gate score [--mode staged|worktree|range] [--base main] ...
+
+Exit codes: 0 = ok or warn (change allowed), 2 = blocked (impact too high, enforcement
+'block'), 1 = usage/environment error. CI wrappers (GitHub/GitLab/Jenkins) call this
+same command and translate the exit code + JSON into a check result / comment.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+
+from .core.config import MeasureConfig
+
+from . import __version__, baseline, gitio, providers, report
+from .config import ENFORCEMENTS, GateConfig
+from .engine import score_change
+
+
+def _add_score_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--mode", choices=gitio.MODES, default="staged",
+                   help="what to score: 'staged' (the commit you're about to make, "
+                        "default), 'worktree' (uncommitted edits), or 'range' "
+                        "(committed branch vs --base, for CI/PR).")
+    p.add_argument("--base", default="main",
+                   help="base ref for --mode range (default: main). Use e.g. "
+                        "origin/main in CI.")
+    p.add_argument("--repo", default=".", help="path to the git repo (default: .)")
+    p.add_argument("--format", choices=("text", "json", "markdown"), default="text")
+    p.add_argument("--config", help="path to an .impact-gate.yml (else auto-discovered in --repo)")
+    # threshold / enforcement overrides (win over the config file when given)
+    p.add_argument("--warn-at", type=int)
+    p.add_argument("--block-at", type=int)
+    p.add_argument("--enforcement", choices=ENFORCEMENTS)
+    p.add_argument("--tolerance", type=float)
+    p.add_argument("--measure-config", help="Surveyor-style YAML for ignore globs etc.")
+    # grading curve (percentile gate) overrides
+    p.add_argument("--curve", dest="curve_enabled", action="store_const", const=True,
+                   default=None, help="gate on the change's percentile grade against the "
+                   "baseline distribution instead of absolute thresholds")
+    p.add_argument("--baseline-file", dest="baseline_file",
+                   help="project baseline cache to grade against (default: "
+                        ".impact-gate-baseline.json)")
+    p.add_argument("--warn-percentile", dest="warn_percentile", type=float)
+    p.add_argument("--block-percentile", dest="block_percentile", type=float)
+    p.add_argument("--curve-prior-weight", dest="curve_prior_weight", type=float,
+                   help="K in the empirical-Bayes blend w = n/(n+K) between the project "
+                        "baseline and the shipped seed. 0 grades PURELY against the "
+                        "--baseline-file distribution (ignore the seed); large K leans on "
+                        "the seed. Default from config (200).")
+
+
+# Gate knobs an argparse flag may override on top of the config file, when given.
+_OVERRIDE_ATTRS = ("warn_at", "block_at", "enforcement", "tolerance", "measure_config",
+                   "curve_enabled", "baseline_file", "warn_percentile", "block_percentile",
+                   "curve_prior_weight")
+
+
+def _resolve_config(args) -> GateConfig:
+    # Base policy from the policy port (local .impact-gate.yml today); CLI flags are the
+    # outermost layer and win over whatever the provider supplied.
+    cfg = providers.select_policy_provider(args.config, args.repo).policy(args.repo)
+    for attr in _OVERRIDE_ATTRS:
+        val = getattr(args, attr, None)
+        if val is not None:
+            setattr(cfg, attr, val)
+    cfg.validate()
+    return cfg
+
+
+def _cmd_score(args) -> int:
+    cfg = _resolve_config(args)
+    mcfg = MeasureConfig.load(cfg.measure_config)
+    try:
+        changed = gitio.changed_files(args.repo, args.mode, args.base)
+    except gitio.DiffError as e:
+        print(f"impact-gate: {e}", file=sys.stderr)
+        return 1
+
+    score = score_change(changed, mcfg)
+
+    grade = None
+    if cfg.curve_enabled:
+        grades = providers.select_grade_provider(args.repo, cfg.baseline_file,
+                                                 cfg.curve_prior_weight)
+        grade = grades.grade(providers.ChangeSummary.of(score), args.repo)
+        if grade is None:                    # backend unreachable -> shipped-seed only
+            grade = providers.seed_grade(score, cfg.curve_prior_weight)
+        level = cfg.level_for_grade(grade.percentile)
+        blocked = cfg.blocks_grade(grade.percentile)
+    else:
+        level = cfg.level(score.impact)
+        blocked = cfg.blocks(score.impact)
+
+    if args.format == "json":
+        print(report.render_json(score, cfg, level, args.mode, args.base, blocked, grade))
+    elif args.format == "markdown":
+        print(report.render_markdown(score, cfg, level, args.mode, args.base, blocked, grade))
+    else:
+        print(report.render_text(score, cfg, level, args.mode, args.base, blocked, grade))
+        if blocked:
+            print("\nimpact-gate: change BLOCKED. Impact exceeds the block threshold. "
+                  "Simplify the change or refactor the code it touches, then retry.",
+                  file=sys.stderr)
+    return 2 if blocked else 0
+
+
+def _cmd_baseline(args) -> int:
+    """Walk the merged mainline into the project distribution and cache it to disk."""
+    cfg = _resolve_config(args)
+    mcfg = MeasureConfig.load(cfg.measure_config)
+    out_path = os.path.join(args.repo, cfg.baseline_file)
+    try:
+        bl = baseline.build_baseline(
+            args.repo, mcfg,
+            base_ref=args.base_ref,
+            max_commits=args.max_commits,
+            exclude_subject_pattern=args.exclude_subject_pattern,
+        )
+    except (gitio.DiffError, OSError, ValueError,
+            subprocess.CalledProcessError) as e:
+        print(f"impact-gate: could not build baseline (is '{args.base_ref or 'main'}' "
+              f"a branch with history?): {e}", file=sys.stderr)
+        return 1
+    if bl.n == 0:
+        print(f"impact-gate: no landed changes found on '{bl.base_ref}'; nothing to "
+              "baseline. Check --base-ref points at a branch with history.",
+              file=sys.stderr)
+        return 1
+    providers.select_grade_provider(args.repo, cfg.baseline_file,
+                                    cfg.curve_prior_weight).publish(args.repo, bl)
+    print(f"impact-gate: baseline written to {out_path} "
+          f"({bl.n} observations from '{bl.base_ref}').")
+    return 0
+
+
+def _cmd_comment(args) -> int:
+    from . import ghapi
+    token = args.token or os.environ.get("GITHUB_TOKEN")
+    repo = args.repo_slug or os.environ.get("GITHUB_REPOSITORY")
+    pr = args.pr or ghapi.detect_pr_number(os.environ.get("GITHUB_EVENT_PATH"))
+    if not token or not repo or not pr:
+        print("impact-gate: need a token, repo (owner/name), and PR number to comment "
+              "(GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_EVENT_PATH are set in Actions).",
+              file=sys.stderr)
+        return 1
+    body = (open(args.body_file, encoding="utf-8").read()
+            if args.body_file else sys.stdin.read())
+    try:
+        result = ghapi.upsert_pr_comment(ghapi.GitHubAPI(token), repo, int(pr), body)
+    except Exception as e:
+        print(f"impact-gate: could not post PR comment: {e}", file=sys.stderr)
+        return 1
+    print(f"impact-gate: PR comment {result}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="impact-gate",
+                                 description="Report and gate on the change-impact of a change.")
+    ap.add_argument("--version", action="version", version=f"impact-gate {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("score", help="score the current change and gate on it")
+    _add_score_args(s)
+    s.set_defaults(func=_cmd_score)
+
+    b = sub.add_parser("baseline",
+                       help="build and cache the project baseline distribution")
+    b.add_argument("--repo", default=".", help="path to the git repo (default: .)")
+    b.add_argument("--config", help="path to an .impact-gate.yml (else auto-discovered)")
+    b.add_argument("--base-ref", dest="base_ref",
+                   help="mainline branch to walk (default: main, or config's base_ref)")
+    b.add_argument("--max-commits", dest="max_commits", type=int,
+                   help="cap how many recent mainline commits are walked")
+    b.add_argument("--exclude-subject-pattern", dest="exclude_subject_pattern",
+                   help="regex on a merge subject to skip that MR entirely")
+    b.add_argument("--baseline-file", dest="baseline_file",
+                   help="where to write the cache (default: .impact-gate-baseline.json)")
+    b.add_argument("--measure-config", help="Surveyor-style YAML for ignore globs etc.")
+    b.set_defaults(func=_cmd_baseline)
+
+    c = sub.add_parser("comment", help="upsert a sticky PR comment with a report (CI)")
+    c.add_argument("--body-file", help="markdown file to post (default: read stdin)")
+    c.add_argument("--repo-slug", help="owner/name (default: $GITHUB_REPOSITORY)")
+    c.add_argument("--pr", type=int, help="PR number (default: from $GITHUB_EVENT_PATH)")
+    c.add_argument("--token", help="GitHub token (default: $GITHUB_TOKEN)")
+    c.set_defaults(func=_cmd_comment)
+
+    args = ap.parse_args(argv)
+    try:
+        return args.func(args)
+    except ValueError as e:            # config validation, bad args
+        print(f"impact-gate: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

impact_gate/config.py

@@ -0,0 +1,123 @@
+"""Gate configuration: thresholds, enforcement mode, CI-adjustable tolerance.
+
+Resolved in layers (later wins): built-in defaults -> `.impact-gate.yml` in the repo
+-> CLI flags / CI inputs. The built-in defaults are not literals here; they are read
+from `impact_gate/data/defaults.json`, so tuning them is a data edit, not a code change.
+
+Two gating modes coexist. Absolute: `warn_at` / `block_at` are raw composite-impact
+numbers. Curve (`curve_enabled`): a change is graded by its percentile against the
+blended seed + project distribution, and `warn_percentile` / `block_percentile` gate on
+that. The curve fields are wired here; `baseline.py` and the percentile gate consume
+them (a later phase). Absolute stays the fallback when the curve is off or no baseline
+exists yet.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .data import load_defaults
+
+CONFIG_NAMES = (".impact-gate.yml", ".impact-gate.yaml")
+ENFORCEMENTS = ("off", "warn", "block")
+
+# Built-in defaults come from the shipped JSON, never from literals in this file.
+_D = load_defaults()
+_ABS = _D["absolute"]
+_CURVE = _D["curve"]
+
+# The knobs an .impact-gate.yml / CLI flag may override, and their loaders. Absolute and
+# curve knobs share one path so a repo can set either mode's numbers in the same file.
+_SCALAR_KEYS = ("warn_at", "block_at", "enforcement", "tolerance", "measure_config",
+                "curve_enabled", "warn_percentile", "block_percentile",
+                "curve_prior_weight", "baseline_file")
+
+
+@dataclass
+class GateConfig:
+    warn_at: int | None = _ABS["warn_at"]     # impact above which to warn (None = never)
+    block_at: int | None = _ABS["block_at"]   # impact above which to block (None = never)
+    enforcement: str = _D["enforcement"]      # off | warn | block (block = too-high fails)
+    tolerance: float = _D["tolerance"]        # CI multiplier on both thresholds (>1 = looser)
+    measure_config: str | None = None         # optional Surveyor-style YAML (ignore globs)
+    # Grading curve (percentile-based). Consumed once baseline.py + the percentile gate land.
+    # The gate always scores the composite (change-level) impact; the mutation cost is a
+    # per-file signal used to rank which files to consider, not a rival gating metric.
+    curve_enabled: bool = _CURVE["enabled"]           # gate on percentile vs absolute
+    warn_percentile: float = _CURVE["warn_percentile"]
+    block_percentile: float = _CURVE["block_percentile"]
+    curve_prior_weight: float = _CURVE["prior_weight_K"]  # K in w = n / (n + K)
+    baseline_file: str = _CURVE["baseline_file"]      # project distribution cache
+
+    def effective_warn(self) -> float | None:
+        return None if self.warn_at is None else self.warn_at * self.tolerance
+
+    def effective_block(self) -> float | None:
+        return None if self.block_at is None else self.block_at * self.tolerance
+
+    def level(self, impact: float) -> str:
+        """'block' / 'warn' / 'ok' by threshold alone (independent of enforcement)."""
+        b, w = self.effective_block(), self.effective_warn()
+        if b is not None and impact > b:
+            return "block"
+        if w is not None and impact > w:
+            return "warn"
+        return "ok"
+
+    def blocks(self, impact: float) -> bool:
+        """True only when enforcement is 'block' AND the impact clears block_at — the
+        one case that fails the gate. In 'warn' mode a too-high change still passes."""
+        return self.enforcement == "block" and self.level(impact) == "block"
+
+    def level_for_grade(self, percentile: float) -> str:
+        """Curve mode: 'block' / 'warn' / 'ok' from a change's grade percentile. A change
+        at or above `block_percentile` blocks; at or above `warn_percentile` warns."""
+        if percentile >= self.block_percentile:
+            return "block"
+        if percentile >= self.warn_percentile:
+            return "warn"
+        return "ok"
+
+    def blocks_grade(self, percentile: float) -> bool:
+        """Curve analogue of `blocks`: fails the gate only under 'block' enforcement."""
+        return (self.enforcement == "block"
+                and self.level_for_grade(percentile) == "block")
+
+    @classmethod
+    def load(cls, path: str | None = None, repo_path: str = ".") -> "GateConfig":
+        """Load from an explicit path, else the first `.impact-gate.y*ml` in repo_path."""
+        cfg = cls()
+        found = path or _discover(repo_path)
+        if not found:
+            return cfg
+        import yaml  # optional; only needed when a config file exists
+        with open(found) as fh:
+            data = yaml.safe_load(fh) or {}
+        for key in _SCALAR_KEYS:
+            if key in data and data[key] is not None:
+                setattr(cfg, key, data[key])
+        cfg.validate()
+        return cfg
+
+    def validate(self) -> None:
+        if self.enforcement not in ENFORCEMENTS:
+            raise ValueError(f"enforcement must be one of {ENFORCEMENTS}, got "
+                             f"{self.enforcement!r}")
+        if self.tolerance <= 0:
+            raise ValueError("tolerance must be > 0")
+        for name in ("warn_percentile", "block_percentile"):
+            p = getattr(self, name)
+            if not 0 < p < 100:
+                raise ValueError(f"{name} must be within (0, 100), got {p}")
+        if self.warn_percentile > self.block_percentile:
+            raise ValueError("warn_percentile must be <= block_percentile")
+        if self.curve_prior_weight < 0:
+            raise ValueError("curve_prior_weight (K) must be >= 0")
+
+
+def _discover(repo_path: str) -> str | None:
+    for name in CONFIG_NAMES:
+        p = os.path.join(repo_path, name)
+        if os.path.isfile(p):
+            return p
+    return None

impact_gate/core/__init__.py

@@ -0,0 +1,10 @@
+"""Self-contained structural change-impact core.
+
+Vendored so the tool is standalone — no dependency on the (concluded) Surveyor
+bug-finding experiment. Importing this package registers the default lizard plugin.
+"""
+from .units import Unit, get_plugin, register        # noqa: F401
+from . import lizard_plugin                           # noqa: F401  (registers default plugin)
+from .impact import FileImpact, UnitImpact, compute_file_impact  # noqa: F401
+from .config import MeasureConfig                     # noqa: F401
+from .gitplumb import GitRepo, parse_diff             # noqa: F401

impact_gate/core/config.py

@@ -0,0 +1,102 @@
+"""Measure configuration: which files are source, how to group, ignore globs.
+
+Structural-decay focused: languages, ignore globs, test-path heuristics, and the
+rename similarity threshold. (No bug-keyword mining — that belonged to the earlier
+defect-prediction experiment, not to a structural-decay gate.)
+"""
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+
+# Extension -> language label. lizard picks its reader by filename, so this table only
+# decides "is this a source file worth parsing", plus the label used in reports.
+LANG_BY_EXT: dict[str, str] = {
+    ".java": "java",
+    ".cs": "csharp",
+    ".c": "c", ".h": "c", ".cc": "cpp", ".cpp": "cpp", ".cxx": "cpp",
+    ".hpp": "cpp", ".hh": "cpp", ".hxx": "cpp",
+    ".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript",
+    ".ts": "typescript", ".tsx": "typescript",
+    ".py": "python",
+    ".go": "go",
+    ".kt": "kotlin", ".kts": "kotlin",
+    ".swift": "swift",
+    ".rb": "ruby",
+    ".php": "php",
+    ".rs": "rust",
+    ".scala": "scala",
+    ".m": "objectivec", ".mm": "objectivec",
+    ".lua": "lua",
+    ".ttcn": "ttcn",
+}
+
+DEFAULT_IGNORE = [
+    "**/node_modules/**", "**/dist/**", "**/build/**", "**/target/**",
+    "**/out/**", "**/bin/**", "**/obj/**", "**/third_party/**",
+    "**/vendor/**", "**/vendors/**", "**/bower_components/**", "**/webjars/**",
+    "**/.venv/**", "**/venv/**", "**/__pycache__/**", "**/.git/**",
+    "**/*.min.js", "**/*.min.css", "**/*.bundle.js", "**/*.generated.*",
+    "**/generated/**", "**/gen/**",
+]
+
+DEFAULT_TEST_PATTERNS = [
+    "**/test/**", "**/tests/**", "**/__tests__/**", "**/spec/**",
+    "**/*Test.*", "**/*Tests.*", "**/*_test.*", "**/test_*.*",
+    "**/*.test.*", "**/*.spec.*",
+]
+
+
+@dataclass
+class MeasureConfig:
+    ignore: list[str] = field(default_factory=lambda: list(DEFAULT_IGNORE))
+    test_patterns: list[str] = field(default_factory=lambda: list(DEFAULT_TEST_PATTERNS))
+    lang_by_ext: dict[str, str] = field(default_factory=lambda: dict(LANG_BY_EXT))
+    rename_jaccard: float = 0.6     # body token-set similarity to call a rename
+    max_diff_lines: int = 200_000   # skip pathological mega-diffs (generated dumps)
+
+    def ext(self, path: str) -> str:
+        i = path.rfind(".")
+        return path[i:].lower() if i >= 0 else ""
+
+    def is_source(self, path: str) -> bool:
+        return not self.is_ignored(path) and self.ext(path) in self.lang_by_ext
+
+    def language(self, path: str) -> str | None:
+        return self.lang_by_ext.get(self.ext(path))
+
+    def is_ignored(self, path: str) -> bool:
+        # Match each glob against the path, and also with a leading "**/" stripped, so a
+        # pattern like "**/vendor/**" ignores a TOP-LEVEL vendor/ too. fnmatch's "*" spans
+        # "/", but "**/vendor/**" still requires a parent segment before "vendor", which
+        # let a repo-root vendor/ or node_modules/ slip through.
+        for pat in self.ignore:
+            if fnmatch.fnmatch(path, pat):
+                return True
+            if pat.startswith("**/") and fnmatch.fnmatch(path, pat[3:]):
+                return True
+        return False
+
+    def is_test(self, path: str) -> bool:
+        return any(fnmatch.fnmatch(path, pat) for pat in self.test_patterns)
+
+    @classmethod
+    def load(cls, path: str | None) -> "MeasureConfig":
+        cfg = cls()
+        if not path:
+            return cfg
+        import yaml  # optional; only needed when a config file is passed
+        with open(path) as fh:
+            data = yaml.safe_load(fh) or {}
+        for key in ("rename_jaccard", "max_diff_lines"):
+            if key in data:
+                setattr(cfg, key, data[key])
+        # ignore / test_patterns APPEND to the defaults (a config adds, never silently
+        # drops). To start from scratch, set the matching `*_replace` key instead.
+        cfg.ignore = list(data["ignore_replace"]) if "ignore_replace" in data \
+            else cfg.ignore + list(data.get("ignore", []))
+        cfg.test_patterns = list(data["test_patterns_replace"]) if "test_patterns_replace" in data \
+            else cfg.test_patterns + list(data.get("test_patterns", []))
+        if "lang_by_ext" in data:
+            cfg.lang_by_ext.update(data["lang_by_ext"])
+        return cfg