refactor(engine): extrai métricas puras de Race.tsx para src/lib/metrics.ts (#32)

[caioross]

Contexto

A honestidade das métricas (WPM, precisão, erros, progresso) é a verdade sagrada do domínio (spec §0.3). Até aqui todo o cálculo morava inline em src/components/Race.tsx, impossível de testar por unidade — o único "teste" era uma cópia da lógica em .claude/skills/cr-typing-engine/scripts/validate-metrics.mjs, sujeita a divergir em silêncio do código de produção.

O que mudou e por quê

Extrai as quatro funções puras e determinísticas para src/lib/metrics.ts (fonte única de verdade) e cobre com src/lib/metrics.test.ts:

• countCorrectChars(typed, code) — loop char-a-char; typed > code não estoura.
• computeWpm(correctChars, elapsedMin) — ~5 chars/palavra; elapsedMin ≤ 0.001 → 0.
• computeAccuracy(errors, totalKeystrokes) — precisão honesta (Engine/Honestidade: "Precisão 100%" coexiste com "Erros 1" — arredondamento mascara erro e rótulo confunde #20): errors === 0 → 100, senão floor com teto de 99%, clamp [0,100].
• computeProgress(typedLen, codeLen) — [0,1], codeLen === 0 → 0.

Race.tsx passa a importar e usar essas funções; correctChars segue no useMemo (área sagrada HANDBOOK §2 — nenhuma alocação/loop novo por keystroke no hot path).

Extração 1:1 — zero mudança de número na tela

O Parecer do Conselho antecipava uma contradição ("copie 1:1" × "nunca 100 com erro") porque avaliou uma revisão antiga com Math.round. Divergência: a correção de honestidade da #20 já está na main (Race.tsx já usava Math.floor + teto de 99%). Logo esta fatia é um refactor puro, byte-a-byte — nenhuma corrida mostra número diferente de antes. Os testes apenas pinam as invariantes já vigentes; não há impacto visível a declarar.

Como foi validado (gate real)

• pnpm typecheck ✅
• pnpm build ✅
• pnpm test ✅ — 34/34 (13 novos em metrics.test.ts + 21 de room.test.ts)
• node .claude/skills/cr-typing-engine/scripts/validate-metrics.mjs ✅ 37/0
• node scripts/validate-persistence.mjs ✅ 33/0
• pnpm lint = N/A (repo sem config ESLint; a CI não roda lint)

Riscos

Baixos. Refactor sem mudança de comportamento; a UI renderiza os mesmos valores. Diff mínimo (3 arquivos, +138/−15). Numa fatia futura, validate-metrics.mjs pode passar a importar de metrics.ts para eliminar de vez a duplicação de harness (fora do escopo mínimo aqui).

Segui o plano do Conselho, com uma divergência declarada: como a honestidade #20 já estava na main, não houve mudança de número nem necessidade de Closes #20.

Closes #32

[vercel]

@caioross is attempting to deploy a commit to the caioross' projects team on Vercel, but is not a member of this team. To resolve this issue, you can:

• Make your repository public. Collaboration is free for open source and public repositories.
• Upgrade to pro and add @caioross as a member. A Pro subscription is required to access Vercel's collaborative features.
  • If you're the owner of the team, click here to upgrade and add @caioross as a member.
  • If you're the user who initiated this build request, click here to request access.
  • If you're already a member of the caioross' projects team, make sure that your Vercel account is connected to your GitHub account.

To read more about collaboration on Vercel, click here.

[gemini-code-assist]

Code Review

This pull request extracts typing metrics calculation logic (countCorrectChars, computeWpm, computeAccuracy, and computeProgress) from the Race component into a dedicated metrics utility file, accompanied by a comprehensive unit test suite. Feedback was provided to optimize the countCorrectChars function by limiting the loop iteration to the minimum length of the typed and target strings, avoiding unnecessary comparisons with undefined.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Atualmente, o loop percorre todo o comprimento de typed. Se typed for maior que code, o código tentará acessar índices fora dos limites de code (retornando undefined), o que é ineficiente e conceitualmente incorreto. Embora a comparação com undefined resulte em false e não quebre a lógica, é mais seguro e eficiente limitar a iteração ao menor comprimento entre as duas strings usando Math.min(typed.length, code.length).

Suggested change

	export function countCorrectChars(typed: string, code: string): number {
	let c = 0;
	for (let i = 0; i < typed.length; i++) if (typed[i] === code[i]) c++;
	return c;
	}
	export function countCorrectChars(typed: string, code: string): number {
	let c = 0;
	const minLength = Math.min(typed.length, code.length);
	for (let i = 0; i < minLength; i++) {
	if (typed[i] === code[i]) c++;
	}
	return c;
	}

[caioross]

🩺 Parecer do PR Doctor — APROVADA (§7.3 Normal)

Classificação: normal (refactor de engine com validate-metrics verde; não toca API de salas, persistência nem migração). Diff lido inteiro (3 arquivos, Race.tsx + metrics.ts + metrics.test.ts), head 769ebe3.

Conferido linha a linha (extração é 1:1, não há mudança de número na tela):

• computeAccuracy (src/lib/metrics.ts:31) reproduz byte-a-byte o Math.floor + teto 99% que já estava na main — a honestidade da Engine/Honestidade: "Precisão 100%" coexiste com "Erros 1" — arredondamento mascara erro e rótulo confunde #20 não regride e não é reintroduzida em dobro.
• computeWpm mantém o guard elapsedMin > 0.001; computeProgress mantém codeLen === 0 → 0 e o clamp em 1; countCorrectChars mantém o loop char-a-char sem estourar quando typed > code.
• Área sagrada preservada (src/components/Race.tsx:58): correctChars continua no useMemo com as mesmas dependências — nenhuma alocação ou loop novo por keystroke no hot path.

Gate reproduzido localmente no worktree da branch (não confiei só no corpo do PR):

• pnpm typecheck ✅
• pnpm test ✅ 34/34 (13 de metrics.test.ts + 21 de room.test.ts)
• node .claude/skills/cr-typing-engine/scripts/validate-metrics.mjs ✅ 37 passaram, 0 falharam
• CI Install, typecheck & build ✅. O check Vercel vermelho é infra de permissão da conta ("Git author caioross must have access to the project"), idêntico em todas as PRs abertas — não é falha de build.

Closes #32 está correto: a issue é a extração inteira, não uma fatia. Mergeando em squash.