feat(enrichment): add TODO/FIXME/HACK marker tracker analyzer

[jason020818]

Closes #2016

What

A new local REES analyzer, todoMarker, that surfaces TODO/FIXME/HACK/XXX markers a PR ADDS in comments — with the tag, file:line, and a truncated note — so a reviewer sees the change is shipping acknowledged-incomplete work. Pure compute over added lines, no network.

Detection (stateless, precision-first, false-negative-biased)

A marker is reported only when both hold, so ordinary code and prose never false-positive:

• UPPERCASE tag (the marker convention): a lowercase todo identifier, a // fixme lowercase note, or a private field this.#todo is never flagged.
• Comment-anchored: the tag is immediately preceded on the same line by a comment lead-in — //, #, /*, or <!-- at start-of-line or after whitespace, or a bare * only at the start of the trimmed line (the JSDoc continuation). Requiring a token boundary keeps this.#TODO (a . precedes #) and base * TODO (a * mid-expression) out; an uppercase TODO used as a bare identifier in code is not matched.
• String-stripped first (via secret-log.ts's codeOnly): a marker inside a string literal (const s = "// TODO") is not a hit.

\b after the tag keeps TODOS/XXXL out; the note drops a trailing *//--> and is truncated to 120 chars. A bare marker inside a multi-line block comment whose opener is on a previous line (a line with no lead-in of its own) is intentionally not matched — missing it is the safe direction, and the common * TODO continuation form still anchors on the leading *. Added lines only, line-cited via hunk headers, with the shared \ No newline line-counter fix; findings capped (maxFindings: 25) per file and globally.

Registration

Registered as a local descriptor (category quality, cost local, requires ["files"]) with an inline render(), following the terminology descriptor shape. All wiring updated: types.ts (TodoMarkerFinding + todoMarker? key), render.ts, analyzer-registry.test.ts, root src/review/enrichment-analyzer-names.ts, root test/unit/enrichment-wire.test.ts, and the generated analyzer-metadata.json / rees-analyzers.ts / .env.example via node scripts/generate-analyzer-metadata.mjs.

Tests

review-enrichment/test/todo-marker.test.ts (14 tests) covers: each tag across comment styles (//, #, /*, JSDoc *, <!--) with notes, a bare marker with no note, uppercase-only (lowercase identifier/note and this.#todo not flagged), comment-anchored (an uppercase TODO in code, base * TODO, and arr.push(TODO) not flagged), a marker inside a string not flagged, TODOS/XXXL word-boundary rejection, trailing block-comment/HTML-close stripping, note truncation to the cap, added-line scanning with exact locations, added-lines-only with line-number accuracy across mixed hunks, the per-file cap + maxFindings: 0, the entrypoint's global cap across files, the no-files case, and the rendered brief section. Analyzer metadata is regenerated and committed.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-05 01:02:19 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This adds a local todoMarker analyzer and wires it through the descriptor registry, rendered brief output, generated metadata, UI analyzer docs, env example, and analyzer-name resolution. The core scanner is bounded, added-line-only, and line counting handles removed/context/no-newline rows correctly; the tests exercise detection, caps, render output, and registry wiring. I do not see a reachable correctness defect in the visible diff.

Nits — 5 non-blocking

• nit: review-enrichment/src/analyzers/todo-marker.ts:29 treats `# TODO` as a comment anchor across every file type, which can flag Markdown headings or other prose files even though the docs promise ordinary prose never false-positives; either document that tradeoff or gate `#` by file type if you want the precision claim to hold.
• nit: review-enrichment/src/analyzers/todo-marker.ts:38 truncates with `slice(0, MAX_NOTE_CHARS)` without indicating truncation, so the rendered note can look complete when it was cut mid-sentence.
• review-enrichment/src/analyzers/todo-marker.ts:29: add a test for a Markdown-style `# TODO` line and either accept/document it or adjust the `#` lead-in behavior.
• review-enrichment/src/analyzers/todo-marker.ts:38: consider appending an ellipsis within the 120-character cap when a note is truncated so reviewers can tell it was shortened.
• 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	#2016
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: 441 registered-repo PR(s), 266 merged, 7 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jaso0n0818; Gittensor profile; 441 PR(s), 7 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: jaso0n0818
• 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: 441 PR(s), 7 issue(s).
• Related work: Titles/paths share 8 meaningful terms. (issue #2019, issue #2018)
• Related work: Titles/paths share 6 meaningful terms. (issue #2015, issue #2017)
• Related work: Titles/paths share 6 meaningful terms. (issue #2015, issue #2018)
• 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 94.13%. Comparing base (3875335) to head (a72d6f4).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3287   +/-   ##
=======================================
  Coverage   94.13%   94.13%           
=======================================
  Files         276      276           
  Lines       30236    30236           
  Branches    11016    11016           
=======================================
  Hits        28464    28464           
  Misses       1127     1127           
  Partials      645      645           

Files with missing lines	Coverage Δ
src/review/enrichment-analyzer-names.ts	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.