culprit 0.1.0__tar.gz

culprit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noordeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

culprit-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: culprit
+Version: 0.1.0
+Summary: Root-cause analysis for a PR or branch: classify feature vs bugfix, find the introducing commit (suspect set) or the blast radius.
+Author: Noordeen
+License: MIT
+Project-URL: Homepage, https://github.com/noordeen123/culprit
+Project-URL: Repository, https://github.com/noordeen123/culprit
+Project-URL: Issues, https://github.com/noordeen123/culprit/issues
+Keywords: git,rca,root-cause,pull-request,regression,blame
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: api
+Requires-Dist: anthropic>=0.40; extra == "api"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# culprit
+
+Root-cause analysis for a pull request or branch.
+
+`culprit` looks at a PR (or the current branch), decides whether it's a **bugfix**
+or a **feature**, then:
+
+- **Bugfix** → finds the commit that *introduced* the bug. It blames the lines the
+  fix removed/changed at the base revision and ranks the commits that last touched
+  them (the **suspect set**), then explains why it broke and whether the fix is
+  complete.
+- **Feature** → maps the **blast radius**: who imports the changed modules, which
+  tests cover them, and which touched files live in high-risk shared/core areas.
+
+It is **read-only** — it never modifies your repo or the PR.
+
+## Why the split design
+
+The deterministic git work (diff parsing, `git blame` / `git log -L`, the
+suspect set, the reverse-import map) lives in a plain Python engine that emits
+**structured JSON**. The only LLM step — the "why it broke" narrative — is
+isolated behind a `ReasoningAdapter`:
+
+- **HarnessAdapter** — used by the Claude Code skill. Returns the structured
+  result + a markdown skeleton; the agent writes the narrative. No API key.
+- **ClaudeAPIAdapter** — used standalone. Calls the Claude API
+  (`claude-opus-4-8` by default, `--fast` → `claude-sonnet-4-6`).
+
+Same engine, two frontends.
+
+## Install
+
+```bash
+pip install -e .            # engine + CLI
+pip install -e ".[api]"     # + Claude API reasoning layer (anthropic SDK)
+```
+
+PR metadata uses the GitHub CLI when available: `brew install gh && gh auth login`.
+For **public repos you don't even need `gh`** — `rca --pr N` falls back to the
+unauthenticated REST API (**GitHub and GitLab**) for metadata plus a read-only
+`git fetch` of the PR/MR head (set `GITHUB_TOKEN` / `GITLAB_TOKEN` to raise rate
+limits). With neither, culprit uses local git (base vs head) — fully offline,
+minus PR title/labels.
+
+### Any host, any language
+
+- **Hosts:** deep links (commit / PR / file) are generated for **GitHub, GitLab,
+  Bitbucket, and Gitea**; the suspect-set + line-evolution timeline work on *any*
+  git repo regardless of host. For a self-hosted forge the URL can't disambiguate,
+  so set `host = "gitlab"` (or `github`/`bitbucket`/`gitea`) in `.culprit.toml`, or
+  `CULPRIT_HOST`.
+- **Languages:** suspect/timeline are language-agnostic (pure `git blame`/`log -L`).
+  Blast-radius + test-gap detect imports across JS/TS, Python, Go, Java/Kotlin,
+  Ruby, C/C++, C#, PHP, Rust, Scala, Swift (quoted *and* bare/dotted import forms).
+
+## Usage
+
+```bash
+rca                      # current branch vs the configured base (or latest commit)
+rca --last               # just the latest commit ("the change I just made")
+rca --pr 16786           # a specific GitHub PR (uses the PR's own base)
+rca --repo /path --base main
+rca --mode api --fast    # standalone reasoning via the Claude API
+rca --json               # structured result only
+rca --html report.html --open   # self-contained visual report (timeline UI)
+```
+
+### Visual HTML report
+
+`--html PATH` writes a **single self-contained HTML file** (inline CSS/JS, data
+embedded, no CDN — opens offline, shareable, CI-attachable). For a bugfix it
+renders a **line-evolution timeline**: for each line the fix touched, every commit
+that ever changed those lines, from creation → … → **the commit that broke it
+(red)** → **the fix (green)**, each step expandable to its diff.
+
+```bash
+rca --pr 16889 --html rca.html --open                 # narrative via --mode api if key set
+rca --pr 16889 --html rca.html --narrative-file why.md # embed a pre-written narrative
+```
+
+The timeline needs no API key. The "Analysis" prose comes from `--narrative-file`
+(e.g. written by the Claude Code `/rca` skill) or from `--mode api`.
+
+The report also includes: a **TL;DR banner** naming the prime suspect and how long
+the bug lived before the fix; **GitHub deep links** on every commit / PR / file
+(derived from `origin`); **weight bars** ranking the suspects; **expand/collapse-all**
+and a **per-file filter** for the timeline; and a one-click **copy-as-markdown** to
+paste into the PR.
+
+### Choosing the base branch
+
+The base differs per repo (`main`, `master`, `develop`, a long-lived release
+branch, …). Resolution order:
+`--base <ref>` → `CULPRIT_BASE` env → `.culprit.toml` (`base = "..."`) → the latest
+commit. The static HTML report is generated for one base (shown in the footer with a
+regenerate hint). For an **interactive base picker**, use `serve` mode:
+
+```bash
+rca serve --repo /path/to/repo     # opens http://127.0.0.1:8722
+```
+
+It launches a local web app (stdlib only — no extra deps) with a form: enter a
+PR/branch, **pick the base from a dropdown** (pre-filled from `.culprit.toml`,
+the repo's default branch, then all local/remote branches), choose
+classification + reasoning, and run a fresh analysis that renders the same visual
+report. The base picker repopulates when you point it at a different repo. Binds
+to localhost only.
+
+### Base branch
+
+In local mode (no PR), culprit needs a base to diff against. Resolution order:
+
+1. `--base <ref>` on the CLI
+2. `CULPRIT_BASE` environment variable
+3. `base = "..."` in a `.culprit.toml` at the repo root
+4. otherwise the latest commit (`HEAD~1`)
+
+So pin your repo's real base once and forget it:
+
+```toml
+# .culprit.toml
+base = "origin/main"   # whatever your repo is actually cut from
+```
+
+`--last` always forces the latest-commit view regardless of config.
+
+## Tests
+
+```bash
+pip install -e ".[dev]" && pytest
+```

culprit-0.1.0/README.md

@@ -0,0 +1,131 @@
+# culprit
+
+Root-cause analysis for a pull request or branch.
+
+`culprit` looks at a PR (or the current branch), decides whether it's a **bugfix**
+or a **feature**, then:
+
+- **Bugfix** → finds the commit that *introduced* the bug. It blames the lines the
+  fix removed/changed at the base revision and ranks the commits that last touched
+  them (the **suspect set**), then explains why it broke and whether the fix is
+  complete.
+- **Feature** → maps the **blast radius**: who imports the changed modules, which
+  tests cover them, and which touched files live in high-risk shared/core areas.
+
+It is **read-only** — it never modifies your repo or the PR.
+
+## Why the split design
+
+The deterministic git work (diff parsing, `git blame` / `git log -L`, the
+suspect set, the reverse-import map) lives in a plain Python engine that emits
+**structured JSON**. The only LLM step — the "why it broke" narrative — is
+isolated behind a `ReasoningAdapter`:
+
+- **HarnessAdapter** — used by the Claude Code skill. Returns the structured
+  result + a markdown skeleton; the agent writes the narrative. No API key.
+- **ClaudeAPIAdapter** — used standalone. Calls the Claude API
+  (`claude-opus-4-8` by default, `--fast` → `claude-sonnet-4-6`).
+
+Same engine, two frontends.
+
+## Install
+
+```bash
+pip install -e .            # engine + CLI
+pip install -e ".[api]"     # + Claude API reasoning layer (anthropic SDK)
+```
+
+PR metadata uses the GitHub CLI when available: `brew install gh && gh auth login`.
+For **public repos you don't even need `gh`** — `rca --pr N` falls back to the
+unauthenticated REST API (**GitHub and GitLab**) for metadata plus a read-only
+`git fetch` of the PR/MR head (set `GITHUB_TOKEN` / `GITLAB_TOKEN` to raise rate
+limits). With neither, culprit uses local git (base vs head) — fully offline,
+minus PR title/labels.
+
+### Any host, any language
+
+- **Hosts:** deep links (commit / PR / file) are generated for **GitHub, GitLab,
+  Bitbucket, and Gitea**; the suspect-set + line-evolution timeline work on *any*
+  git repo regardless of host. For a self-hosted forge the URL can't disambiguate,
+  so set `host = "gitlab"` (or `github`/`bitbucket`/`gitea`) in `.culprit.toml`, or
+  `CULPRIT_HOST`.
+- **Languages:** suspect/timeline are language-agnostic (pure `git blame`/`log -L`).
+  Blast-radius + test-gap detect imports across JS/TS, Python, Go, Java/Kotlin,
+  Ruby, C/C++, C#, PHP, Rust, Scala, Swift (quoted *and* bare/dotted import forms).
+
+## Usage
+
+```bash
+rca                      # current branch vs the configured base (or latest commit)
+rca --last               # just the latest commit ("the change I just made")
+rca --pr 16786           # a specific GitHub PR (uses the PR's own base)
+rca --repo /path --base main
+rca --mode api --fast    # standalone reasoning via the Claude API
+rca --json               # structured result only
+rca --html report.html --open   # self-contained visual report (timeline UI)
+```
+
+### Visual HTML report
+
+`--html PATH` writes a **single self-contained HTML file** (inline CSS/JS, data
+embedded, no CDN — opens offline, shareable, CI-attachable). For a bugfix it
+renders a **line-evolution timeline**: for each line the fix touched, every commit
+that ever changed those lines, from creation → … → **the commit that broke it
+(red)** → **the fix (green)**, each step expandable to its diff.
+
+```bash
+rca --pr 16889 --html rca.html --open                 # narrative via --mode api if key set
+rca --pr 16889 --html rca.html --narrative-file why.md # embed a pre-written narrative
+```
+
+The timeline needs no API key. The "Analysis" prose comes from `--narrative-file`
+(e.g. written by the Claude Code `/rca` skill) or from `--mode api`.
+
+The report also includes: a **TL;DR banner** naming the prime suspect and how long
+the bug lived before the fix; **GitHub deep links** on every commit / PR / file
+(derived from `origin`); **weight bars** ranking the suspects; **expand/collapse-all**
+and a **per-file filter** for the timeline; and a one-click **copy-as-markdown** to
+paste into the PR.
+
+### Choosing the base branch
+
+The base differs per repo (`main`, `master`, `develop`, a long-lived release
+branch, …). Resolution order:
+`--base <ref>` → `CULPRIT_BASE` env → `.culprit.toml` (`base = "..."`) → the latest
+commit. The static HTML report is generated for one base (shown in the footer with a
+regenerate hint). For an **interactive base picker**, use `serve` mode:
+
+```bash
+rca serve --repo /path/to/repo     # opens http://127.0.0.1:8722
+```
+
+It launches a local web app (stdlib only — no extra deps) with a form: enter a
+PR/branch, **pick the base from a dropdown** (pre-filled from `.culprit.toml`,
+the repo's default branch, then all local/remote branches), choose
+classification + reasoning, and run a fresh analysis that renders the same visual
+report. The base picker repopulates when you point it at a different repo. Binds
+to localhost only.
+
+### Base branch
+
+In local mode (no PR), culprit needs a base to diff against. Resolution order:
+
+1. `--base <ref>` on the CLI
+2. `CULPRIT_BASE` environment variable
+3. `base = "..."` in a `.culprit.toml` at the repo root
+4. otherwise the latest commit (`HEAD~1`)
+
+So pin your repo's real base once and forget it:
+
+```toml
+# .culprit.toml
+base = "origin/main"   # whatever your repo is actually cut from
+```
+
+`--last` always forces the latest-commit view regardless of config.
+
+## Tests
+
+```bash
+pip install -e ".[dev]" && pytest
+```

culprit-0.1.0/culprit/__init__.py

@@ -0,0 +1,9 @@
+"""culprit — root-cause analysis for a PR or branch.
+
+Repo-agnostic engine: deterministic git/PR analysis that emits structured JSON.
+The only LLM step (the "why it broke" narrative) is isolated behind
+``culprit.reasoning`` so the same engine drives both the Claude Code skill
+(harness reasons) and the standalone CLI (Claude API reasons).
+"""
+
+__version__ = "0.1.0"

culprit-0.1.0/culprit/_proc.py

@@ -0,0 +1,46 @@
+"""Thin, read-only subprocess helpers for git and gh.
+
+Every command here is read-only by construction. Nothing in culprit ever
+mutates the target repository or the PR.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import List, Optional
+
+
+class ProcError(RuntimeError):
+    """A subprocess exited non-zero."""
+
+    def __init__(self, cmd: List[str], returncode: int, stderr: str):
+        self.cmd = cmd
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__("`{}` exited {}: {}".format(" ".join(cmd), returncode, stderr.strip()))
+
+
+def run(cmd: List[str], cwd: Optional[str] = None, check: bool = True) -> str:
+    """Run a command and return stdout. Raise ProcError on failure when check."""
+    proc = subprocess.run(
+        cmd,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if check and proc.returncode != 0:
+        raise ProcError(cmd, proc.returncode, proc.stderr)
+    return proc.stdout
+
+
+def git(args: List[str], repo: str, check: bool = True) -> str:
+    return run(["git", "-C", repo] + args, check=check)
+
+
+def have_gh() -> bool:
+    return shutil.which("gh") is not None
+
+
+def gh(args: List[str], repo: str, check: bool = True) -> str:
+    return run(["gh"] + args, cwd=repo, check=check)

culprit-0.1.0/culprit/blast_radius.py

@@ -0,0 +1,124 @@
+"""Feature path: what can this change break?
+
+For each changed source file, find who imports it (reverse-import map), which
+tests cover those modules, and which touched files live in shared/core areas
+(high blast radius). Heuristic but grounded — the reasoning layer ranks risk
+and recommends the test surface from this structured map.
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+from . import _proc
+
+DEFAULT_SOURCE_GLOBS = [
+    "*.js", "*.jsx", "*.ts", "*.tsx", "*.mjs", "*.cjs", "*.vue", "*.svelte",
+    "*.py", "*.go", "*.rb", "*.java", "*.kt", "*.scala", "*.cs", "*.php",
+    "*.rs", "*.c", "*.h", "*.cc", "*.cpp", "*.hpp", "*.m", "*.swift",
+]
+# Test-file conventions across ecosystems: JS spec/test, Python test_*/*_test,
+# Go *_test.go, Java/Kotlin/C# *Test/*Tests, Ruby *_spec, plus test dirs.
+DEFAULT_TEST_RE = re.compile(
+    r"(\.spec\.|\.test\.|_test\.|_spec\.|/__tests__/|(^|/)cypress/|(^|/)tests?/"
+    r"|(^|/)test_[^/]*\.(py|rb)$|Tests?\.(java|kt|cs|scala|swift)$|_test\.go$)", re.I)
+HIGH_RISK_RE = re.compile(r"(^|/)(shared|common|core|lib|utils?|helpers?|base|hooks|store)(/|$)", re.I)
+
+_INDEX_RE = re.compile(r"(^|/)(index|__init__|mod)\.[^/]+$")
+
+
+def _module_token(path: str) -> str:
+    """The identifier other files most likely import this module by."""
+    if _INDEX_RE.search(path):
+        # package entry files (index.js / __init__.py / mod.go) are imported by dir name
+        return os.path.basename(os.path.dirname(path)) or os.path.basename(path)
+    return os.path.splitext(os.path.basename(path))[0]
+
+
+def _importers(repo: str, token: str, exclude: str, source_globs: List[str]) -> List[str]:
+    if not token:
+        return []
+    tok = re.escape(token)
+    # An import-ish line that references the token as a delimited path segment.
+    # Covers JS/TS (`import x from '…/token'`, `require('…token…')`), Python
+    # (`from a.token import x`, `import a.token`), Java (`import a.b.Token;`),
+    # Go/Ruby/C (`"…/token"`, `<token.h>`). Uses POSIX classes only — git grep -E
+    # has no \w / \b, so token boundaries are spelled [^A-Za-z0-9_].
+    pat = r"(import|require|include|from|use).*[^A-Za-z0-9_]{}([^A-Za-z0-9_]|$)".format(tok)
+    args = ["grep", "-l", "-I", "-E", "-e", pat, "--"] + source_globs
+    out = _proc.git(args, repo, check=False)
+    return [f for f in out.splitlines() if f.strip() and f != exclude]
+
+
+def test_gap(changed_files: List[str], repo: str,
+             source_globs: Optional[List[str]] = None, max_files: int = 60) -> Dict[str, Any]:
+    """For a bugfix: which changed (non-test) files have no covering tests.
+
+    A regression usually slips through because the touched code isn't tested.
+    Reuses the reverse-import map to find test files that import each module.
+    """
+    source_globs = source_globs or DEFAULT_SOURCE_GLOBS
+    files = [f for f in changed_files if f]
+    notes: List[str] = []
+    if len(files) > max_files:
+        notes.append("{} files; checked the first {}".format(len(files), max_files))
+        files = files[:max_files]
+    covering = set()
+    untested: List[str] = []
+    for path in files:
+        if DEFAULT_TEST_RE.search(path):
+            continue  # the changed file is itself a test
+        token = _module_token(path)
+        tests = [i for i in _importers(repo, token, path, source_globs) if DEFAULT_TEST_RE.search(i)]
+        if tests:
+            covering.update(tests)
+        else:
+            untested.append(path)
+    return {"untested": untested, "covering_tests": sorted(covering), "notes": notes}
+
+
+def analyze(ctx: Dict[str, Any], repo: str,
+            source_globs: Optional[List[str]] = None,
+            max_dependents: int = 50, max_files: int = 200) -> Dict[str, Any]:
+    source_globs = source_globs or DEFAULT_SOURCE_GLOBS
+    changed = [f for f in ctx.get("changed_files", []) if f]
+    notes: List[str] = []
+    if len(changed) > max_files:
+        notes.append("changeset has {} files; mapping dependents for the first {} "
+                     "(narrow the base or analyze one commit)".format(len(changed), max_files))
+        changed = changed[:max_files]
+
+    dependents: Dict[str, List[str]] = {}
+    covering_tests = set()
+    high_risk: List[str] = []
+
+    for path in changed:
+        if DEFAULT_TEST_RE.search(path):
+            covering_tests.add(path)  # the change itself touches a test
+        if HIGH_RISK_RE.search(path):
+            high_risk.append(path)
+
+        token = _module_token(path)
+        imps = _importers(repo, token, path, source_globs)[:max_dependents]
+        if imps:
+            dependents[path] = imps
+        for imp in imps:
+            if DEFAULT_TEST_RE.search(imp):
+                covering_tests.add(imp)
+
+    # A changed file with many dependents is also high-risk even outside shared/.
+    for path, imps in dependents.items():
+        if len(imps) >= 10 and path not in high_risk:
+            high_risk.append(path)
+
+    ranked = sorted(dependents.items(), key=lambda kv: len(kv[1]), reverse=True)
+    return {
+        "changed_files": changed,
+        "dependents": dict(ranked),
+        "dependent_counts": {p: len(v) for p, v in ranked},
+        "covering_tests": sorted(covering_tests),
+        "high_risk": high_risk,
+        "total_dependents": sum(len(v) for v in dependents.values()),
+        "notes": notes,
+    }

culprit-0.1.0/culprit/classify.py

@@ -0,0 +1,87 @@
+"""Classify a change as a bugfix or a feature, with evidence.
+
+Deterministic scoring over branch name, PR labels, and commit/title prefixes.
+The verdict is advisory: the Claude Code harness (or the API reasoning layer)
+makes the final call, but the score + evidence give it grounded signal instead
+of guessing.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Tuple
+
+_BUG_BRANCH = re.compile(r"^(bug|bugfix|fix|hotfix|patch)[/\-_]", re.I)
+_FEAT_BRANCH = re.compile(r"^(feat|feature|enhancement|chore|refactor)[/\-_]", re.I)
+
+# Leading [\W_]* tolerates real-world prefixes like "- fix:", "🚀 feat:", ": fixes".
+_BUG_PREFIX = re.compile(r"^[\W_]*(bug\s*)?fix(es|ed)?\b|^[\W_]*hotfix\b|^[\W_]*patch\b", re.I)
+_FEAT_PREFIX = re.compile(r"^[\W_]*(feat|feature|add|implement|introduce|chore|refactor)\b", re.I)
+
+_BUG_LABELS = {"bug", "bugfix", "regression", "defect", "hotfix"}
+_FEAT_LABELS = {"feature", "enhancement", "feat", "improvement"}
+
+
+def _add(evidence: List[str], score: int, delta: int, msg: str) -> int:
+    evidence.append(msg)
+    return score + delta
+
+
+def classify(ctx: Dict[str, Any]) -> Dict[str, Any]:
+    """Return {verdict, confidence, evidence, score} from a pr_context dict."""
+    score = 0  # positive → bugfix, negative → feature
+    evidence: List[str] = []
+
+    branch = ctx.get("head_ref") or ""
+    if _BUG_BRANCH.match(branch):
+        score = _add(evidence, score, 2, "branch '{}' uses a fix/bug prefix".format(branch))
+    elif _FEAT_BRANCH.match(branch):
+        score = _add(evidence, score, -2, "branch '{}' uses a feat/feature prefix".format(branch))
+
+    labels = [str(l).lower() for l in (ctx.get("labels") or [])]
+    for lab in labels:
+        if lab in _BUG_LABELS:
+            score = _add(evidence, score, 3, "PR label '{}' indicates a bug".format(lab))
+        elif lab in _FEAT_LABELS:
+            score = _add(evidence, score, -3, "PR label '{}' indicates a feature".format(lab))
+
+    title = ctx.get("title") or ""
+    if title:
+        if _BUG_PREFIX.search(title):
+            score = _add(evidence, score, 2, "PR title '{}' reads like a fix".format(title))
+        elif _FEAT_PREFIX.search(title):
+            score = _add(evidence, score, -2, "PR title '{}' reads like a feature".format(title))
+
+    bug_commits = 0
+    feat_commits = 0
+    for c in ctx.get("commits", []):
+        subj = c.get("subject") or ""
+        if _BUG_PREFIX.search(subj):
+            bug_commits += 1
+        elif _FEAT_PREFIX.search(subj):
+            feat_commits += 1
+    if bug_commits or feat_commits:
+        if bug_commits > feat_commits:
+            score = _add(evidence, score, 1,
+                         "{} of {} commit subjects look like fixes".format(
+                             bug_commits, len(ctx.get("commits", []))))
+        elif feat_commits > bug_commits:
+            score = _add(evidence, score, -1,
+                         "{} of {} commit subjects look like features".format(
+                             feat_commits, len(ctx.get("commits", []))))
+
+    if score > 0:
+        verdict = "bugfix"
+    elif score < 0:
+        verdict = "feature"
+    else:
+        verdict = "unknown"
+
+    # Confidence scales with the margin; capped at a readable 0.95.
+    confidence = min(0.95, 0.5 + 0.1 * abs(score)) if verdict != "unknown" else 0.0
+
+    return {
+        "verdict": verdict,
+        "confidence": round(confidence, 2),
+        "score": score,
+        "evidence": evidence,
+    }