OpenVelo Agent
129 lines
8.5 KiB
Markdown
129 lines
8.5 KiB
Markdown
# Implementation Plan: Scoreboard Score Graph — Safe rendering under invalid/reversed event window (Job 912)
|
|
|
|
## 1. Architectural Reconnaissance
|
|
|
|
- **Codebase style & conventions:**
|
|
- Backend: NestJS 10 + TypeORM, SQLite (`backend/src/...`).
|
|
- Frontend: Angular 20 standalone components with Signals, `ChangeDetectionStrategy.OnPush`, `@if`/`@for` control flow, `signal()`/`computed()` for state.
|
|
- Pure helpers live in `frontend/src/app/features/scoreboard/scoreboard.pure.ts` and are the canonical test surface; components stay presentation-only.
|
|
- Existing `ScoreGraphComponent` uses the legacy `@Input()` + `@if/*ngIf` mix; we will not refactor it (out of scope) — only fix the broken math.
|
|
- **Data Layer:** SQLite via TypeORM. The bug lives entirely in the frontend projection. No DB migration is required. (The root cause is bad admin-entered `eventStartUtc`/`eventEndUtc` values persisted in the `setting` table — we do NOT silently rewrite them; we harden the renderer.)
|
|
- **Test Framework & Structure:**
|
|
- Jest 29 with `ts-jest` and two projects in `tests/jest.config.js` (`backend` + `frontend`).
|
|
- Frontend project uses `jsdom`, `tests/frontend/jest.setup.ts`, and `transformIgnorePatterns` allow-listing `@angular`, `rxjs`, `tslib`.
|
|
- Tests live under `tests/frontend/` (already convention) — e.g. `tests/frontend/scoreboard.pure.spec.ts` exists and follows this pattern. We will add a sibling `tests/frontend/score-graph-projection.spec.ts`.
|
|
- Single test command: `npm test` (or scoped `npm run test:frontend`).
|
|
- **Required Tools & Dependencies:** None new. Existing stack (Jest 29, jsdom, `@angular/common`, `@angular/core`) is sufficient.
|
|
|
|
## 2. Impacted Files
|
|
|
|
### To Modify
|
|
- `frontend/src/app/features/scoreboard/scoreboard.pure.ts`
|
|
- Add a pure helper `projectGraphPoints(view, series, dims)` that returns clamped SVG `points` strings for a single series. Encapsulates the X/Y math so the bug cannot recur in the component template. Pure, deterministic, fully unit-testable.
|
|
- Add a small helper `isValidEventWindow(startUtc, endUtc)` returning `true` only when both timestamps parse and `endMs > startMs`.
|
|
- `frontend/src/app/features/scoreboard/score-graph.component.ts`
|
|
- Replace inline `pointsAttr()` with a call to `projectGraphPoints(view, s, dims)` and a single `points` getter computed up front (via a `computed()` over `view`) so the bug fix is a single source of truth.
|
|
- Switch the per-series `<polyline>` binding from a method call to a precomputed `string` per series (Angular calls methods on every change-detection cycle, so hoisting into `computed()` also helps OnPush perf).
|
|
- No template/TDD-required structural changes beyond `[attr.points]="linePoints(s)"` consuming the hoisted value.
|
|
|
|
### To Create
|
|
- `tests/frontend/score-graph-projection.spec.ts`
|
|
- Unit tests for the new pure helper covering:
|
|
1. Happy path (start < end, normal window) — unchanged coordinates.
|
|
2. Reversed window (`endUtc < startUtc`) — every projected X coordinate falls inside `[padL, padL + innerW]` and no coordinate exceeds plausible SVG bounds.
|
|
3. Equal start/end (zero span) — handled gracefully (no NaN/Infinity, all points clamp to the right edge).
|
|
4. Invalid `Date` strings — points string is empty / coordinates stay finite.
|
|
|
|
## 3. Proposed Changes
|
|
|
|
### Step 1 — Pure helper in `scoreboard.pure.ts`
|
|
|
|
Add two exports:
|
|
|
|
```ts
|
|
export interface GraphProjectionDims {
|
|
width: number;
|
|
height: number;
|
|
padL: number;
|
|
padR: number;
|
|
padT: number;
|
|
padB: number;
|
|
}
|
|
|
|
export function isValidEventWindow(
|
|
startUtc: string | null,
|
|
endUtc: string | null,
|
|
): boolean {
|
|
if (!startUtc || !endUtc) return false;
|
|
const s = new Date(startUtc).getTime();
|
|
const e = new Date(endUtc).getTime();
|
|
if (!Number.isFinite(s) || !Number.isFinite(e)) return false;
|
|
return e > s;
|
|
}
|
|
|
|
export function projectGraphPoints(
|
|
view: Pick<GraphView, 'startUtc' | 'endUtc'>,
|
|
series: GraphSeries,
|
|
dims: GraphProjectionDims,
|
|
): string {
|
|
if (!isValidEventWindow(view.startUtc, view.endUtc)) return '';
|
|
const startMs = new Date(view.startUtc!).getTime();
|
|
const endMs = new Date(view.endUtc!).getTime();
|
|
const span = endMs - startMs;
|
|
const innerW = dims.width - dims.padL - dims.padR;
|
|
const innerH = dims.height - dims.padT - dims.padB;
|
|
|
|
let maxVal = 0;
|
|
for (const s of series.points) if (s.value > maxVal) maxVal = s.value;
|
|
if (maxVal <= 0) maxVal = 1;
|
|
|
|
const left = dims.padL;
|
|
const right = dims.padL + innerW;
|
|
const top = dims.padT;
|
|
const bottom = dims.padT + innerH;
|
|
|
|
return series.points
|
|
.map((p) => {
|
|
const ms = new Date(p.tUtc).getTime();
|
|
if (!Number.isFinite(ms)) return `${left.toFixed(2)},${bottom.toFixed(2)}`;
|
|
const rawX = ((ms - startMs) / span) * innerW;
|
|
const x = Math.min(right, Math.max(left, rawX));
|
|
const rawY = (p.value / maxVal) * innerH;
|
|
const y = top + Math.max(0, Math.min(innerH, innerH - rawY));
|
|
return `${x.toFixed(2)},${y.toFixed(2)}`;
|
|
})
|
|
.join(' ');
|
|
}
|
|
```
|
|
|
|
Why this fixes the bug:
|
|
- `isValidEventWindow` short-circuits the case `endUtc < startUtc` (the persisted repro). The component then renders the existing `Not started`/`No solves yet` empty branch instead of emitting absurd polylines. We do not silently mutate the persisted settings — we just refuse to render an off-canvas chart for an invalid window.
|
|
- `Math.min/Math.max` clamp surviving X coordinates into `[padL, width - padR]` so future regressions that still produce a malformed span (zero, NaN) cannot escape the SVG viewport.
|
|
- NaN guards prevent the `toFixed(2)`-on-`NaN` failure mode that previously produced strings like `40.00,292.00`.
|
|
|
|
### Step 2 — Component refactor in `score-graph.component.ts`
|
|
|
|
- Replace the `@Input() view` with a `signal`-style getter via `ngOnChanges`/`input()` semantics: keep `@Input() view: GraphView | null = null;` (existing pattern) but add a `computed` `seriesWithPoints` that maps each series to `{ ...s, pointsAttr: projectGraphPoints(view, s, dims) }`. Use an explicit `dims: GraphProjectionDims` constant built from the existing `width/height/padL/padR/padT/padB` so the magic numbers are declared once.
|
|
- Replace the `[attr.points]="pointsAttr(s)"` binding with `[attr.points]="line.pointsAttr"` and iterate over `seriesWithPoints()` instead of `view.series`. (Template keeps `*ngFor` — we are not upgrading to `@for` per job scope.)
|
|
- Keep all existing `data-testid` markers and the three empty states (`unconfigured` / `countdown` / running-with-empty-series) — the fix is a no-op for those branches.
|
|
|
|
### Step 3 — No backend / no DB changes
|
|
|
|
The persisted bad data (start > end) stays as-is. The renderer now refuses to project points outside the SVG and gracefully returns empty for the invalid window. We will NOT auto-swap start/end at the backend because that would silently rewrite admin input.
|
|
|
|
## 4. Test Strategy
|
|
|
|
- **Target Unit Test File:** `tests/frontend/score-graph-projection.spec.ts` (new). It mirrors the existing `tests/frontend/scoreboard.pure.spec.ts` style: plain Jest, no TestBed needed (pure helper), no Angular bootstrap, no DOM rendering.
|
|
- **Mocking Strategy:**
|
|
- No mocks required — the helper is a pure function over primitives and date strings.
|
|
- No HTTP, no time mocking (the helper accepts timestamps as arguments; we pin them in fixtures).
|
|
- **Tests to include (minimal, focused):**
|
|
1. `isValidEventWindow` returns `false` when `endUtc < startUtc`, `false` when equal, `false` for non-finite Date strings, `true` only when `end > start`.
|
|
2. `projectGraphPoints` with the documented repro (`startUtc=2026-07-23T00:00:00.000Z`, `endUtc=2026-07-22T00:00:00.000Z`) returns the empty string — explicitly asserting the bug-class fix.
|
|
3. `projectGraphPoints` with a normal window returns coordinates where the first point's X is `padL` and the last X is at or below `padL + innerW` (regression guard).
|
|
4. `projectGraphPoints` with `startUtc === endUtc` (zero-span edge) returns only finite, in-bounds X coordinates (no `Infinity`, no negative).
|
|
- **Negative coverage deliberately omitted:** we do not mount the Angular component (no TestBed, no fixture) — that keeps the suite fast and matches the rule "Frontend tests focus on logic, not visuals."
|
|
- **Run command:** `npm test` (executes all projects) or `npm run test:frontend` for the frontend project only. Both commands already work in this repo.
|
|
|
|
## Status
|
|
Not yet implemented. Pure helper `projectGraphPoints` / `isValidEventWindow` do not exist in `scoreboard.pure.ts`; the bug is reproducible from the current `pointsAttr()` method on line 117 of `score-graph.component.ts`. |