feat(review): add deterministic per-PR review-effort estimator

[GildardoDev]

Summary

Adds a pure, deterministic per-PR review-effort estimator as src/review/review-effort.ts: given the changed files and their patches, it weights each file's added-line count by its category, adds a fixed per-file overhead, and maps the total to a 1-5 complexity band plus a rounded minutes estimate. No AI, no IO. Standalone (no wiring); consumed by the ROI and unified-comment surfaces in follow-up issues.

Closes #2068

Deliverables

• estimateReviewEffort(files): { band: 1 | 2 | 3 | 4 | 5; minutes: number } - pure and deterministic.
• Inputs derive from addedLineCount (src/review/review-diff.ts) and classifyChangedFile category weights (src/signals/path-matchers.ts): genuine source costs the most to review; machine-produced/imported content (minified/generated/vendored/lockfiles) the least; docs/config/tests sit in between. The weighting is a single auditable Record<ChangedFileCategory, number> table, not a branch chain.
• Deliberate, documented band cut points; minutes are half the weighted effort, floored at 1.

Validation

• Unit tests cover the empty change set, a file with no patch (per-file overhead only), each of the five bands across rising source volume, the minutes derivation, category weighting, and multi-file summation.
• 100% statement + branch + function coverage on the new module; npm run typecheck is clean.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-04 05:39:01 UTC}

2 files · 1 AI reviewer · no blockers · readiness 62/100 · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
This adds a standalone deterministic estimator that combines added-line counts, path category weights, and fixed per-file overhead into a 1-5 band plus minutes. The implementation is small, pure, and covered for the main arithmetic paths, and the full file content shows the imported helpers are present from existing modules. The most notable detail is that empty input intentionally returns one minute via the global floor, which is tested but slightly broader than the nearby comment describes.

Nits — 5 non-blocking

• nit: src/review/review-effort.ts:39 says the one-minute floor is for any non-empty review, but estimateReviewEffort([]) also returns one minute; align the comment with the intentional empty-input behavior.
• nit: test/unit/review-effort.test.ts:35 only exercises docs and lockfile as non-source categories; a compact table test would better pin the auditable CATEGORY_WEIGHT contract across config, test, generated, minified, vendored, dependency_manifest, and other.
• src/review/review-effort.ts:39: change the minutes comment to state that the estimator always returns at least one minute, including an empty file list, or special-case empty input if zero minutes is the desired contract.
• test/unit/review-effort.test.ts:35: add a table-driven category-weight test so future edits to classifyChangedFile or CATEGORY_WEIGHT cannot silently skew the documented category behavior.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2068
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 258 registered-repo PR(s), 183 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	GildardoDev; Gittensor profile; 258 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: GildardoDev
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 258 PR(s), 0 issue(s).
• Related work: Titles/paths share 10 meaningful terms. (issue #2038, issue #2039)
• Related work: Titles/paths share 10 meaningful terms. (issue #2038, issue #2040)
• Related work: Titles/paths share 11 meaningful terms. (issue #2039, issue #2040)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.05%. Comparing base (b469e5a) to head (5192c23).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2924   +/-   ##
=======================================
  Coverage   96.05%   96.05%           
=======================================
  Files         258      259    +1     
  Lines       28448    28460   +12     
  Branches    10349    10350    +1     
=======================================
+ Hits        27326    27338   +12     
  Misses        489      489           
  Partials      633      633           

Files with missing lines	Coverage Δ
src/review/review-effort.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.