Eve library

Stub-Indicator Allow-List Conventions

Guide

Revision 1

On this page

Date: 2026-04-27 Owner: eng-platform Implements: V1-P2-0353 (allow-list comment convention) alongside the scanner contracts in V1-P2-0350 (stub-indicator-scan CI) and V1-P2-0351 (silent-random-scan CI). Code: scripts/stub-indicator-scan.sh is the single source of truth for scanner behavior. This document is the human-facing contract.

TL;DR#

The stub-indicator scanner runs in two modes against PR-diff files only. Both modes honor inline // stub:legitimate <reason> and // random:legitimate <reason> opt-out comments on the same line as the hit. New stub-vocabulary or Math.random() use without the marker fails the build; existing hits in untouched files are grandfathered.

Why this exists#

The OSHUN_V1_TODOS_P2.md quality bar (§2.6) requires that every PR's implementation source survive an adversarial grep for stub vocabulary ("in production this would…", "TODO:", "placeholder", Math.random() in deterministic functions, etc.). Two CI jobs enforce this:

  • stub-indicator-scan (V1-P2-0350) — qualitative stub markers
  • silent-random-scan (V1-P2-0351) — Math.random() uses

A small number of lines legitimately match those patterns:

  • Synthetic-data generators that intentionally inject noise (gap-filling.ts:845-847 is the canonical example today).
  • Tests / mocks that deliberately use Math.random for fuzz seeds.
  • Comments documenting historical decisions that include the word placeholder in prose, where the surrounding code is real.
  • TODO: markers tracked against an open ticket and explicitly scheduled.

These are rare, but they exist. The allow-list mechanism exists so the scanner does not have to maintain a global ignore list — every exception is justified, in-place, by the engineer adding it.

The convention#

// stub:legitimate <reason> — qualitative stub markers#

Add to the same line as a hit when one of the §2.6 stub-vocabulary matches is intentional. The trailing reason is required and ungrep-able in absence (// stub:legitimate alone is rejected — without a reason future readers cannot judge whether it still applies).

ts
// TODO: revisit fee-rounding once the FX provider switches // stub:legitimate scheduled in OSHUN-1234

// random:legitimate <reason> — Math.random() uses#

Add to the same line as a Math.random() call when the randomness is intentional and would not be replaced by a deterministic algorithm. Common cases: noise injection in synthetic data, jitter in retry backoff, A/B bucket assignment that's intentionally probabilistic.

ts
const noise = (Math.random() - 0.5) * scale; // random:legitimate gap-filling synthetic data

When to use which#

If the line matches… Use
Anything in the §2.6 stub vocabulary except Math.random() // stub:legitimate <reason>
Math.random() // random:legitimate <reason>
Both on the same line Either tag suppresses the line. Prefer // random:legitimate since the qualitative check has lower base-rate of false positives.

What the reason should be#

A short justification that:

  1. Identifies why the line looks like a stub (e.g. "noise injection", "scheduled cleanup", "vendor doc verbiage in comment").
  2. Either (a) names a tracking ticket, or (b) explains why no follow-up is needed.

Bad reasons (rejected in code review):

  • // stub:legitimate ok — gives the reader nothing.
  • // stub:legitimate temporary — temporary until when?
  • // stub:legitimate Claude said so — does not survive turnover.

Good reasons:

  • // random:legitimate jitter for cluster-deconfliction; deterministic alternative would defeat the purpose
  • // stub:legitimate flagging vendor copy that uses the word 'placeholder'; surrounding code is real
  • // stub:legitimate scheduled in OSHUN-1234 for next sprint

Grandfathered files#

Pre-existing hits in untouched files are grandfathered automatically by the scanner: it only scans files the PR diff touches. There is no global ignore list. If an engineer touches a file that already contains unrelated stub markers, only the new hits introduced by the diff fail the build (because git diff --name-only returns the file but the scanner reports per-line, and an unchanged line that was already there is not "new" — except: the scanner does not currently diff per-line, which means touching a file with old hits triggers them. Mitigation: a follow-up to scripts/stub-indicator-scan.sh adding a --new-only mode that compares matched lines against the base ref). For V1, the practical workaround is to add // stub:legitimate grandfathered, see <lineage doc> to the existing line as part of the PR that touches the file.

This trade-off was deliberately chosen over a global ignore list: allow-list comments live next to the offending code, are visible in review, and rot more visibly than a separate file would.

Counter-examples — what NOT to do#

  • Do not rename a function or argument to dodge the scanner (e.g. _placeholder → _p). The scanner targets the comment vocabulary and the literal Math.random call, not identifier names.
  • Do not wrap the offender in a string concatenation to escape the literal regex ('Math' + '.random'). This is a code-review red flag and reviewers should reject such changes.
  • Do not add a global ignore. There is none on purpose.
  • Do not strip a real TODO: to make CI happy. Either turn the TODO into the actual code change in the same PR, or annotate it with // stub:legitimate <ticket-link>.

Scanner internals#

scripts/stub-indicator-scan.sh is the single source of truth.

  • Inputs: explicit paths, --staged (pre-commit), or --diff=<ref> (CI).
  • Modes: --mode=stubs (default), --mode=random, --mode=all.
  • Test files (*.test.ts, *.spec.ts, *.test.tsx, *.spec.tsx, test_*.py, *_test.py, anything under tests/ or test/) are auto-excluded — they routinely contain stub vocabulary inside fixtures and are not implementation code.
  • node_modules/, dist/, .next/, build/ are auto-excluded.
  • The scanner script itself (scripts/stub-indicator-scan.sh) is excluded so its own pattern strings do not match.
  • Exit codes: 0 clean, 1 actionable hits found, 2 invocation error.

CI workflows that consume the scanner:

  • .github/workflows/stub-indicator-scan.yml — runs --mode=stubs and --mode=random against the PR diff.
  • (V1-P2-0356) future pre-commit hook — runs --staged --mode=all on staged files only, target <2 s.
  • (V1-P2-0357) future PR-comment job — runs --format=pr-comment and posts the result as a sticky review comment.

Changes to scanner behavior must update this document in the same PR.