CVR parsers for the ballot-export CSV and JSON formats

[ArendPeter]

Parent

Part of #1603.

What to build

Two new CVR parser functions — one for CSV, one for JSON — that accept the same shape the election's own ballot-data export produces, with a voter_id column/field added, so an admin can round-trip an export back in with voter_ids filled in. Each parser validates the file's structure against the target election up front (whole-file reject on mismatch) and handles voter_id per the open/closed election rules. The existing ranked-CVR parser is rewired onto the same output shape so there's one consistent parser interface.

This ticket is parsing/validation logic only, verified via unit tests — it isn't wired into any dialog yet (that's a later ticket).

Acceptance criteria

• Common parser signature, no runtime registry — caller picks a parser by file extension:

  type CvrParser = (fileText: string, election: Election) => {
      ballots: (NewBallotWithVoterID | undefined)[]; // undefined = a row skipped/rejected during parsing
      errors: ParseError[];
  }

• CSV parser: accepts the election's existing ballot-data export header with a voter_id column prepended — voter_id, ballot_id, precinct, <one column per race/candidate>, [overvote_rank, has_duplicate_rank for ranked races]. voter_id may be blank per row.
• JSON parser: accepts { Election, Ballots: (AnonymizedBallot & { voter_id?: string })[] }, ignoring a Results field if present.
• Structural validation is a whole-file reject, before any row is parsed:
  • CSV: match column headers against candidate names per race (name-matching only — the export never writes internal race/candidate IDs). An unrecognized column, or a race with zero matched candidate columns, rejects the entire file.
  • JSON: compare the embedded Election.races against the target election's races directly by ID.
• voter_id handling:
  • Open elections (voter-ID authentication enabled): a blank voter_id is auto-generated by the parser before the row is returned (never left blank — the roll-lookup path would otherwise fall back to the uploading admin's own user id, silently collapsing every voter-id-less row onto one roll entry).
  • Closed elections: a voter_id must resolve to an existing roll entry; a missing/non-matching one is a per-row rejection (returned as undefined in ballots plus a corresponding entry in errors), not a whole-file reject.
• Each parser (including the rewired ranked-CVR one) computes race order and encodes each row into wire format internally using computeRaceOrder/encodeBallotRow from Extract shared upload utilities and rewire Upload Elections onto them #1605, returning ready-to-upload NewBallotWithVoterID rows directly.
• Unit tests: valid round-trip of an exported file (CSV and JSON), a column/structure mismatch producing a whole-file reject (both formats), a closed-election missing/invalid voter_id producing a per-row error, an open-election blank voter_id being auto-generated.
• The existing (currently unused) useUploadBallots API hook's request body is fixed to include the race_order field the endpoint actually expects.

Blocked by

#1605 (needs computeRaceOrder/encodeBallotRow extracted first).

[ArendPeter]

Summary

Adds two CVR parsers (parseCsvBallots, parseJsonBallots) in packages/shared/src/utils/cvrParsers.ts that accept the ballot-data export shape (CSV or JSON) with a voter_id column/field added, plus 18 backend unit tests covering the acceptance criteria. Both parsers share a common CvrParser signature and return { ballots, errors } where per-row failures leave ballots[i] = undefined and structural failures reject the whole file (row: -1). Also adds race_order to the useUploadBallots request-body type in useAPI.ts to match the endpoint, and includes a light refactor pass on the parser (hoisted per-row header lookups out of the loop, dropped an intermediate raceVoteMap in favor of building Vote[] directly, consolidated duplicate imports). Parsers are not wired into any UI yet — that's issue #1610.

Manual QA Steps

• From the repo root, run cd packages/backend && npx jest cvrParsers and confirm all 18 tests pass.
• Run the full backend suite: cd packages/backend && npx jest. Expect 229 passing.
• Type-check the shared package: npm run build -w @equal-vote/star-vote-shared. Expect no errors.
• Type-check the backend: npm run build -w @equal-vote/star-vote-backend. Expect no errors.
• Skim packages/shared/src/utils/cvrParsers.ts and confirm the four exported names remain: parseCsvBallots, parseJsonBallots, computeRaceOrder, plus the ParseError/CvrParseResult/CvrParser types. (encodeBallotRow is now file-private — it wasn't used anywhere except internally.)
• Confirm useUploadBallots in packages/frontend/src/hooks/useAPI.ts now includes race_order: RaceCandidateOrder[] in its request-body type.

Notes

• No runtime code paths use these parsers yet — no browser QA is possible until Upload Ballots dialog on Manage Voters #1610 wires them into an upload dialog.
• The CSV parser associates overvote_rank/has_duplicate_rank columns positionally with the last preceding ranked (IRV/STV) race. Multi-race CSVs with more than one ranked race would benefit from an integration test once Upload Ballots dialog on Manage Voters #1610 exercises that path in practice.
• Package-lock touched by npm normalization (dropped libc fields from a handful of @rollup/rolldown-binding-* optional deps); no dependency versions changed.

🤖 Generated with Claude Code