swimparse 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,10 @@ Reads swim-meet result files — **SDIF v3** (`.sd3`) and **Hy-Tek** (`.hy3`)
 one `NormalizedMeet` JSON shape, so tools consume a single contract instead of
 re-implementing fixed-width parsing twice.
 
+It also reads the other end of a meet: **Hy-Tek meet-setup files** (`.ev3` / `.hyv`) —
+the event list, session schedule, entry fees and qualifying cuts — as a
+`NormalizedMeetSetup`.
+
 - **Zero dependencies.** Plain ESM — browser, Node, and CI unchanged.
 - **Lossless.** Every swim is kept: placing or not, exhibition, DQ, no-show — plus
   birthdates, seed times, relay legs, splits and DQ reasons.
@@ -22,23 +26,24 @@ everything else.
 
 | Concern | Where it belongs |
 |---|---|
-| SDIF / HY3 record layouts, times, dates, format detection | **swimparse** |
-| The `NormalizedMeet` contract | **swimparse** |
+| SDIF / HY3 / EV3 / HYV record layouts, times, dates, format detection | **swimparse** |
+| The `NormalizedMeet` and `NormalizedMeetSetup` contracts | **swimparse** |
 | Age bands, age-up date, age-group labels for swimmers | your league layer |
 | Scoring: point values, which relays count, team totals | your league layer |
 | Canonical team codes / alias mapping | your league layer |
 | Stripping or aggregating PII | your league layer |
-| Qualifying standards, records, personal bests | your application |
+| Whether a swimmer meets a cut, course conversions, records, personal bests | your application |
 
 ## Install
 
-Consumed as a pinned git dependency:
-
-```json
-"dependencies": { "swimparse": "github:g0rgonus/swimparse#v0.1.0" }
+```sh
+npm install swimparse
 ```
 
-Pin to a tag or SHA for reproducibility. `npm ci` clones it in CI with no publish step.
+Zero dependencies, so there is nothing else to pull in.
+
+Releases are published from CI with [provenance](https://docs.npmjs.com/generating-provenance-statements),
+so every version on npm can be traced to the commit and workflow run that built it.
 
 ## Usage
 
@@ -49,12 +54,36 @@ const meet = parse(fileText, { filename: 'GG_at_WW.hy3' }); // auto-detects form
 const meet = parse(fileText, { format: 'sdif-v3' });        // or force one
 ```
 
+Meet-setup files go through `parseSetup` instead — they hold events, not results, so
+they parse to a different shape rather than an empty `NormalizedMeet`:
+
+```js
+import { parseSetup, qualifyingStandards } from 'swimparse';
+
+const setup = parseSetup(fileText, { filename: 'Meet Events-2026 Champs.ev3' });
+setup.events[0].qualifyingTimes;   // { LCM, SCM, SCY } — the event's cut per course
+qualifyingStandards(setup);        // flat cut table: one row per event that has one
+```
+
+`qualifyingTimes` is the file verbatim. `qualifyingStandards()` is the cut table you
+would publish, and makes exactly one judgement the parse does not: a meet that does not
+accept a course may fill that column with a placeholder (`0.01`, `1.00`) on every event
+rather than leaving it blank, and those are dropped along with any row left with
+nothing real.
+
+If you are consuming the cuts, read
+**[docs/qualifying-cuts.md](docs/qualifying-cuts.md)** first — the output shape, and the
+four things that are easy to get wrong (course keys, what `null` means, comparing on
+`seconds`, and where the meet's rules end and yours begin).
+
 CLI:
 
 ```bash
 swimparse meet.hy3 --pretty       # NormalizedMeet JSON to stdout
 swimparse meet.sd3 -o meet.json   # to a file
 swimparse a.sd3 b.hy3 -d out/     # one <name>.json per input
+swimparse events.ev3 --pretty     # NormalizedMeetSetup JSON
+swimparse events.ev3 --cuts       # just the qualifying-time table
 ```
 
 ## The NormalizedMeet contract
@@ -83,6 +112,40 @@ for the full typedefs. Highlights:
 | Points | stored | absent (reads `0`) |
 | Names | 28-char field | wider, less truncation |
 
+## The NormalizedMeetSetup contract
+
+`{ format, source, meet, sessions, events }` — see [`src/model.js`](src/model.js). A
+setup file is the meet before anyone has entered it, so `events[]` here are event
+*definitions*, not results.
+
+- **`event.qualifyingTimes`** is `{ LCM, SCM, SCY }` — the same cut expressed in each
+  course, each a `SwimTime` or `null`. A meet that sets no cuts (most invitationals)
+  parses to all-null, and `qualifyingStandards()` returns `[]`. The two file flavours
+  store those three columns in different orders — the `.hyv` rotates them to start at
+  the meet's own course — so read them from here, keyed by course, rather than by
+  column position.
+- **`event.course`** is the event's own course as stated in the file (`.ev3` only).
+- **`meet.qualifyingSince`** is the start of the period a cut may be swum in (`.ev3`
+  only). Inferred from the files rather than from a spec — see `src/setup.js`.
+- **`event.round`** is `finals` or `prelims`; `rounds` is 1 for timed finals, 2 for
+  prelims-plus-finals (`.ev3` only).
+- **`sessions`** is the day/start-time schedule, collapsed out of the per-event stamps.
+  A session id may be alphanumeric (`"2G"` — session 2, girls). `.hyv` carries no
+  schedule, so it parses to `[]`.
+- **Event numbers keep their age-group letter** (`"1A"`, `"1B"`, `"1C"`).
+
+### ev3 vs hyv
+
+Meet Manager exports both together in one zip and they describe the same events. The
+`.ev3` is the richer file — sessions, day, event order, start times, relay legs,
+sanction number, venue address, entry deadline. The `.hyv` is the Team Manager import
+file: events, ages, fees and cuts only. swimparse parses both, and the test suite
+asserts they agree event-for-event.
+
+Note that SDIF also defines an `.ev3` meet-events file, which is fixed-width and a
+different format. Detection sniffs content, so a fixed-width `.ev3` still routes to
+the SDIF adapter.
+
 ## Privacy
 
 The lossless rule means output carries **`swimmers[].birthDate` and `usasId` whenever the
@@ -96,10 +159,13 @@ needs exact ages). Putting that choice in the parser would force one answer on e
 Test fixtures in this repo are synthetic — every identity is a public figure with a
 shifted birth year; see [`test/fixtures/README.md`](test/fixtures/README.md).
 
+**Meet-setup files are the exception**: they contain no swimmers at all, so a
+`NormalizedMeetSetup` is safe to publish as-is.
+
 ## Tests
 
 ```bash
-node --test    # golden snapshots + SDIF↔HY3 cross-agreement
+node --test    # golden snapshots + SDIF↔HY3 and EV3↔HYV cross-agreement
 ```
 
 ## License

package/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 /**
- * swimparse CLI — turn .sd3/.hy3 files into NormalizedMeet JSON.
+ * swimparse CLI — turn .sd3/.hy3 results, or .ev3/.hyv meet setups, into JSON.
  *
  *   swimparse meet.hy3                     # JSON to stdout
  *   swimparse meet.sd3 -o meet.json        # JSON to a file
  *   swimparse a.sd3 b.hy3 -d out/          # one <name>.json per input, into out/
  *   swimparse meet.hy3 --pretty            # 2-space indented
+ *   swimparse events.ev3                   # NormalizedMeetSetup JSON
+ *   swimparse events.ev3 --cuts            # just the qualifying-time table
  *
  * PRIVACY: the output contains swimmer birthdates and registration ids exactly
  * as the source file carries them. For a youth meet that is PII for minors —
@@ -14,7 +16,7 @@
 
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { basename, join, extname } from 'node:path';
-import { parse } from './src/index.js';
+import { parse, parseSetup, detectFormat, qualifyingStandards } from './src/index.js';
 
 function main(argv) {
     const args = argv.slice(2);
@@ -22,12 +24,14 @@ function main(argv) {
     let outFile = null;
     let outDir = null;
     let pretty = false;
+    let cuts = false;
 
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (a === '-o' || a === '--out') outFile = args[++i];
         else if (a === '-d' || a === '--out-dir') outDir = args[++i];
         else if (a === '--pretty') pretty = true;
+        else if (a === '--cuts') cuts = true;
         else if (a === '-h' || a === '--help') return help(0);
         else if (a.startsWith('-')) return fail(`unknown option: ${a}`);
         else inputs.push(a);
@@ -39,15 +43,21 @@ function main(argv) {
     if (outDir) mkdirSync(outDir, { recursive: true });
 
     for (const file of inputs) {
-        const meet = parse(readFileSync(file, 'latin1'), { filename: file });
-        const json = JSON.stringify(meet, null, indent);
+        const content = readFileSync(file, 'latin1');
+        const format = detectFormat(content, file);
+        const isSetup = format === 'ev3' || format === 'hyv';
+        if (cuts && !isSetup) return fail(`--cuts needs a meet-setup file (.ev3/.hyv); ${file} is ${format || 'unrecognized'}`);
+
+        const meet = isSetup ? parseSetup(content, { filename: file }) : parse(content, { filename: file });
+        const json = JSON.stringify(cuts ? qualifyingStandards(meet) : meet, null, indent);
+        const summary = `${meet.format}, ${meet.events.length} events`;
         if (outDir) {
             const name = basename(file, extname(file)) + '.json';
             writeFileSync(join(outDir, name), json);
-            process.stderr.write(`wrote ${join(outDir, name)} (${meet.format}, ${meet.events.length} events)\n`);
+            process.stderr.write(`wrote ${join(outDir, name)} (${summary})\n`);
         } else if (outFile) {
             writeFileSync(outFile, json);
-            process.stderr.write(`wrote ${outFile} (${meet.format}, ${meet.events.length} events)\n`);
+            process.stderr.write(`wrote ${outFile} (${summary})\n`);
         } else {
             process.stdout.write(json + '\n');
         }
@@ -57,15 +67,18 @@ function main(argv) {
 
 function help(codeNum) {
     process.stdout.write(
-        'Usage: swimparse <file...> [-o out.json | -d out-dir] [--pretty]\n' +
-        '  Parses SDIF (.sd3) or Hy-Tek (.hy3) results into NormalizedMeet JSON.\n' +
+        'Usage: swimparse <file...> [-o out.json | -d out-dir] [--pretty] [--cuts]\n' +
+        '  Parses SDIF (.sd3) or Hy-Tek (.hy3) results into NormalizedMeet JSON, and\n' +
+        '  Hy-Tek meet-setup files (.ev3/.hyv) into NormalizedMeetSetup JSON.\n' +
         '  -o, --out <path>      write a single input to this file\n' +
         '  -d, --out-dir <dir>   write one <name>.json per input into this directory\n' +
         '      --pretty          2-space indented JSON\n' +
+        '      --cuts            setup files only: emit just the qualifying-time table\n' +
         '\n' +
-        '  Output carries swimmer birthdates as they appear in the file. Sanitize\n' +
-        '  before publishing. Age banding, scoring, and team-code mapping are league\n' +
-        '  policy and are not performed here.\n'
+        '  Result output carries swimmer birthdates as they appear in the file —\n' +
+        '  sanitize before publishing. Setup files contain no personal data.\n' +
+        '  Age banding, scoring, and team-code mapping are league policy and are\n' +
+        '  not performed here.\n'
     );
     return codeNum;
 }

package/docs/qualifying-cuts.md

@@ -0,0 +1,94 @@
+# Qualifying cuts from a meet-setup file
+
+What `qualifyingStandards()` gives you, what it deliberately does not, and the four
+mistakes that are easy to make with it.
+
+## The shape
+
+One row per event that states a real cut. This is verbatim output, not an illustration:
+
+```json
+{
+  "eventNumber": "55",
+  "description": "Girls 13-14 50m Freestyle",
+  "gender": "F",
+  "ageGroup": { "label": "13-14", "lower": 13, "upper": 14 },
+  "distance": 50,
+  "stroke": "Freestyle",
+  "LCM": { "text": "29.49", "seconds": 29.49 },
+  "SCM": { "text": "28.89", "seconds": 28.89 },
+  "SCY": { "text": "25.89", "seconds": 25.89 }
+}
+```
+
+`LCM` / `SCM` / `SCY` are the same standard stated three ways — one per course — each a
+`SwimTime` (`{ text, seconds }`) or `null`. Every other field describes the event and
+matches what the result adapters emit for the same event, so a cut row joins to a parsed
+result on `description`, or on `eventNumber` within one meet.
+
+```js
+import { parseSetup, qualifyingStandards } from 'swimparse';
+
+const setup = parseSetup(readFileSync('Meet Events-2026 Champs.ev3', 'latin1'));
+const cuts = qualifyingStandards(setup);
+```
+
+Or from the CLI — `swimparse events.ev3 --cuts`, which is the same array. To publish it
+as a table:
+
+```bash
+swimparse events.ev3 --cuts \
+  | jq -r '["Event","LCM","SCM","SCY"], (.[] | [.description, .LCM.text, .SCM.text, .SCY.text]) | @csv'
+```
+
+## Four things to get right
+
+**1. Read by course key, never by column position.** The `.ev3` and `.hyv` of the same
+meet order their three time columns differently — the `.hyv` rotates them to start at
+the meet's own course. swimparse resolves that for you; downstream code that
+re-flattens these rows back into a fixed 3-column layout must carry the course label
+with each value or it will re-introduce the bug.
+
+**2. `null` means the meet stated no cut in that course.** It does not mean "any time
+qualifies", and it is not an invitation to convert a time from another course.
+**swimparse never converts between courses** — a converted time is a rule the meet
+either accepts or does not, and only the meet announcement says which. If a swimmer's
+only time is SCY and the SCY cut is `null`, the honest answer to "do they qualify" is
+*this file cannot tell you*.
+
+A course can also be refused loudly rather than left blank: a meet may fill a column it
+does not accept with a placeholder like `0.01`. `qualifyingStandards()` drops those, so
+they arrive as `null` here — but `setup.events[].qualifyingTimes` keeps them verbatim,
+which is where to look if you need to know the difference between "not stated" and
+"stated as unusable".
+
+**3. Compare on `seconds`, display `text`.** `seconds` is a float rounded to hundredths;
+`text` is the canonical `M:SS.ss` form. Never string-compare times.
+
+**4. Meeting a cut is your rule, not the file's.** swimparse reports the standard; it
+has no opinion on whether a swimmer meets it. Whether an equal time qualifies, whether a
+bonus or unqualified entry is allowed, how many events a swimmer may enter, and whether
+the swim happened inside the eligible period are all meet rules that live in the meet
+announcement. `meet.qualifyingSince` is the file's own start-of-period date when it
+states one — it is inferred from sample files rather than from a published spec, so
+treat it as a hint to check against the announcement, not as authority.
+
+```js
+// The comparison itself is one line; the judgement around it is yours.
+const qualifies = (swimSeconds, cut) => cut != null && swimSeconds <= cut.seconds;
+```
+
+## What is absent, and why
+
+Relays usually carry no cut at all, so they usually do not appear in this table. Events
+a meet deliberately leaves open — bonus or unqualified events — do not appear either,
+and are indistinguishable here from events the meet forgot to configure. If you need
+every event whether cut or not, iterate `setup.events` instead and read
+`qualifyingTimes` yourself; `qualifyingStandards()` is the convenience view, not the
+whole file.
+
+## Stability
+
+The field names above are the contract. Additions are possible; renames or a change of
+meaning are not, without a major version. Two rules will not change:
+`qualifyingStandards()` stays filtered and `events[].qualifyingTimes` stays verbatim.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "swimparse",
-  "version": "0.1.0",
-  "description": "Parses SDIF v3 (.sd3) and Hy-Tek (.hy3) swim-meet result files into one NormalizedMeet JSON contract. Zero dependencies; runs in the browser, Node, and CI.",
+  "version": "0.2.0",
+  "description": "Parses SDIF v3 (.sd3) and Hy-Tek (.hy3) swim-meet result files into one NormalizedMeet JSON contract, and Hy-Tek meet-setup files (.ev3/.hyv) — events, sessions and qualifying cuts — into a NormalizedMeetSetup. Zero dependencies; runs in the browser, Node, and CI.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
     "./sdif": "./src/sdif.js",
-    "./hy3": "./src/hy3.js"
+    "./hy3": "./src/hy3.js",
+    "./setup": "./src/setup.js"
   },
   "bin": {
     "swimparse": "cli.js"
@@ -15,7 +16,8 @@
   "files": [
     "src/",
     "cli.js",
-    "README.md"
+    "README.md",
+    "docs/"
   ],
   "scripts": {
     "test": "node --test"
@@ -31,7 +33,11 @@
     "sdif",
     "sd3",
     "hy3",
+    "ev3",
+    "hyv",
     "hy-tek",
+    "meet-events",
+    "time-standards",
     "meet-results",
     "parser",
     "swim-meet"

package/src/detect.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * `ev3` and `hyv` are meet SETUP files (events, no results) — parse those with
+ * parseSetup(), not parse().
+ *
  * @param {string} content
  * @param {string} [filename] optional, used only as a tie-breaker
- * @returns {'sdif-v3'|'hy3'|null}
+ * @returns {'sdif-v3'|'hy3'|'ev3'|'hyv'|null}
  */
 export function detectFormat(content, filename) {
     const firstLines = String(content).split(/\r?\n/, 5);
@@ -20,10 +23,19 @@ export function detectFormat(content, filename) {
     if (firstLines.some((l) => l.startsWith('B11') || l.startsWith('D0') || l.startsWith('D3'))) return 'sdif-v3';
     if (firstLines.some((l) => l.startsWith('D1') || l.startsWith('E1'))) return 'hy3';
 
+    // Meet-setup exports are semicolon-delimited rather than fixed-width. The
+    // ev3 flavour terminates every record with `*>`; the hyv flavour does not.
+    // Checked after the record-code sniffs above so a fixed-width SDIF .ev3
+    // still routes to the SDIF adapter.
+    const delimited = firstLines.filter((l) => l.split(';').length >= 10);
+    if (delimited.length >= 2) return delimited.some((l) => l.trimEnd().endsWith('*>')) ? 'ev3' : 'hyv';
+
     if (filename) {
         const ext = filename.toLowerCase().split('.').pop();
         if (ext === 'hy3') return 'hy3';
         if (ext === 'sd3' || ext === 'cl2' || ext === 'txt') return 'sdif-v3';
+        if (ext === 'ev3') return 'ev3';
+        if (ext === 'hyv') return 'hyv';
     }
     return null;
 }

package/src/index.js

@@ -1,32 +1,40 @@
 /**
  * swimparse — public entry point.
  *
- * Parse SDIF v3 (.sd3) or Hy-Tek (.hy3) meet results into one NormalizedMeet.
+ * Parse SDIF v3 (.sd3) or Hy-Tek (.hy3) meet results into one NormalizedMeet,
+ * and Hy-Tek meet-setup files (.ev3/.hyv) into one NormalizedMeetSetup.
  * Zero dependencies; runs in the browser, Node, and CI.
  *
- *   import { parse, detectFormat } from 'swimparse';
- *   const meet = parse(fileText, { filename: 'GG_at_WW.hy3' });
+ *   import { parse, parseSetup, detectFormat } from 'swimparse';
+ *   const meet  = parse(fileText, { filename: 'GG_at_WW.hy3' });
+ *   const setup = parseSetup(eventsText, { filename: 'MeetEvents.ev3' });
  *
- * SCOPE: this library reads meet-result files and emits JSON. That is all it
- * does. It has no concept of a league — no age bands, no scoring rules, no team
- * registry, no qualifying standards. Those are league policy and belong to the
- * application consuming this output.
+ * SCOPE: this library reads meet files and emits JSON. That is all it does. It
+ * has no concept of a league — no age bands, no scoring rules, no team registry,
+ * and no opinion about whether a given swimmer meets a cut. A setup file states
+ * its own qualifying times and those are read like any other field, but applying
+ * them is league policy and belongs to the application consuming this output.
  *
- * PRIVACY: the output is a lossless superset of the source file, so it CARRIES
+ * PRIVACY: a parsed RESULT file is a lossless superset of its source, so it CARRIES
  * SWIMMER BIRTHDATES (`swimmers[].birthDate`, individual `results[].birthDate`)
  * and USA-S registration ids. For youth meets that is PII for minors — treat
  * every parse result as confidential until your application has stripped or
  * aggregated it. swimparse deliberately does not do that for you: what counts as
  * safe is a league decision (a summer league publishes age-group labels; a
  * USA-Swimming tool needs exact ages), so it belongs to the consumer.
+ *
+ * Meet-SETUP files (.ev3/.hyv) are the exception: they describe a meet nobody has
+ * entered yet, so a NormalizedMeetSetup contains no personal data at all.
  */
 
 import { parseSdif } from './sdif.js';
 import { parseHy3 } from './hy3.js';
+import { parseEv3, parseHyv } from './setup.js';
 import { detectFormat } from './detect.js';
 
 export { parseSdif } from './sdif.js';
 export { parseHy3 } from './hy3.js';
+export { parseEv3, parseHyv, qualifyingStandards } from './setup.js';
 export { detectFormat } from './detect.js';
 export * from './model.js';
 export * from './constants.js';
@@ -45,5 +53,28 @@ export function parse(content, opts = {}) {
     const format = opts.format || detectFormat(content, opts.filename);
     if (format === 'sdif-v3') return parseSdif(content);
     if (format === 'hy3') return parseHy3(content);
+    if (format === 'ev3' || format === 'hyv') {
+        throw new Error(`swimparse: this is a Hy-Tek meet SETUP file (.${format}) — it holds events, not results. Use parseSetup().`);
+    }
     throw new Error('swimparse: could not detect meet-result format (expected SDIF .sd3 or Hy-Tek .hy3)');
 }
+
+/**
+ * Parses a Hy-Tek meet-setup file — the event list, sessions and qualifying
+ * cuts a meet is built from, before anyone has entered it.
+ *
+ * @param {string} content
+ * @param {Object} [opts]
+ * @param {'ev3'|'hyv'} [opts.format] force a format, skipping detection
+ * @param {string} [opts.filename] used as a detection tie-breaker
+ * @returns {import('./model.js').NormalizedMeetSetup}
+ */
+export function parseSetup(content, opts = {}) {
+    const format = opts.format || detectFormat(content, opts.filename);
+    if (format === 'ev3') return parseEv3(content);
+    if (format === 'hyv') return parseHyv(content);
+    if (format === 'sdif-v3' || format === 'hy3') {
+        throw new Error(`swimparse: this is a meet RESULT file (${format}), not a setup file. Use parse().`);
+    }
+    throw new Error('swimparse: could not detect meet-setup format (expected Hy-Tek .ev3 or .hyv)');
+}

package/src/model.js

@@ -84,6 +84,96 @@
  * @property {(IndividualResult|RelayResult)[]} results
  */
 
+/**
+ * The NormalizedMeetSetup contract — what a meet-SETUP file (.ev3/.hyv) holds.
+ *
+ * A setup file is the meet before it has entrants: the event list, the session
+ * schedule, the entry fees, and the qualifying cuts. There are no swimmers and
+ * no results in it, so it is a different shape from NormalizedMeet rather than
+ * an empty one — `events[]` here are event *definitions*, not event results.
+ *
+ * It carries no personal data at all, which makes it the one swimparse output
+ * that is safe to publish as-is.
+ *
+ * @typedef {Object} NormalizedMeetSetup
+ * @property {'ev3'|'hyv'} format
+ * @property {Object} source                  Producing software (header record).
+ * @property {string} [source.software]
+ * @property {string} [source.version]
+ * @property {string|null} [source.createdAt] ISO date the file was exported.
+ * @property {SetupMeetInfo} meet
+ * @property {SetupSession[]} sessions        Empty for hyv, which has no sessions.
+ * @property {SetupEvent[]} events
+ */
+
+/**
+ * @typedef {Object} SetupMeetInfo
+ * @property {string} name
+ * @property {string} rawName
+ * @property {string} [hostName]              Host or facility as printed.
+ * @property {string|null} startDate          ISO "YYYY-MM-DD".
+ * @property {string|null} endDate
+ * @property {string|null} [ageUpDate]        The date ages are computed as of.
+ * @property {string|null} [course]           'SCY' | 'LCM' | 'SCM'.
+ * @property {string} [sanction]              LSC sanction number (ev3 only).
+ * @property {string|null} [entryDeadline]    ISO (ev3 only).
+ * @property {string|null} [qualifyingSince]  Start of the period a cut may be
+ *                                            swum in — INFERRED from the files,
+ *                                            not from a spec (ev3 only).
+ * @property {Object} [location]              Address fields (ev3 only).
+ */
+
+/**
+ * @typedef {Object} SetupSession
+ * @property {string} id                      As numbered in the file — may be
+ *                                            alphanumeric ("1", "2G").
+ * @property {number|null} day                1-based day of the meet.
+ * @property {string|null} startTime          24-hour "HH:MM".
+ * @property {number} eventCount
+ */
+
+/**
+ * @typedef {Object} SetupEvent
+ * @property {string} number                  As printed, letter and all ("1A").
+ * @property {'individual'|'relay'} type
+ * @property {'finals'|'prelims'|null} round  'prelims' = prelims feeding a final.
+ * @property {number|null} rounds             1 = timed finals, 2 = prelims+finals
+ *                                            (ev3 only).
+ * @property {'M'|'F'|'X'} gender
+ * @property {number|null} distance
+ * @property {string} stroke                  Canonical stroke name.
+ * @property {string|null} course             The event's own course as stated in
+ *                                            the file — 'SCY' | 'LCM' | 'SCM'.
+ *                                            ev3 only; the hyv states none.
+ * @property {{label:string, lower:number, upper:number}} ageGroup
+ * @property {string} description             Human label, same form the result
+ *                                            adapters produce.
+ * @property {number|null} relayLegs          Legs per relay (ev3 only).
+ * @property {number|null} entryFee           As stored, in the meet's currency.
+ * @property {{LCM: SwimTime|null, SCM: SwimTime|null, SCY: SwimTime|null}} qualifyingTimes
+ *                                            The event's cut in each course — the
+ *                                            same standard, stated three ways. All
+ *                                            null when the meet sets no cuts. Kept
+ *                                            verbatim, including the placeholder a
+ *                                            meet may fill an unaccepted course
+ *                                            with; qualifyingStandards() drops
+ *                                            those.
+ * @property {{id:string, day:number|null, order:number|null, startTime:string|null}|null} session
+ */
+
+/**
+ * @typedef {Object} QualifyingStandard
+ * @property {string} eventNumber
+ * @property {string} description
+ * @property {'M'|'F'|'X'} gender
+ * @property {{label:string, lower:number, upper:number}} ageGroup
+ * @property {number|null} distance
+ * @property {string} stroke
+ * @property {SwimTime|null} LCM
+ * @property {SwimTime|null} SCM
+ * @property {SwimTime|null} SCY
+ */
+
 /**
  * @typedef {Object} IndividualResult
  * @property {'individual'} kind

package/src/setup.js

@@ -0,0 +1,341 @@
+/**
+ * Hy-Tek meet-SETUP adapter (.ev3 / .hyv) → NormalizedMeetSetup.
+ *
+ * A setup file is the meet's event list before anyone has entered it: no
+ * swimmers, no entries, no results. Meet Manager exports the pair together in
+ * one zip — `.ev3` (the richer one: sessions, day, event order, start times)
+ * and `.hyv` (the Team Manager import file: the same events, fewer columns).
+ *
+ * Neither is fixed-width. Both are **semicolon-delimited**, CP-1252, CRLF: one
+ * header record, then one record per event. `.ev3` records carry a trailing
+ * `*>` terminator, and its header carries a trailing checksum.
+ *
+ *   ev3  1;1A;F;1;I;G;0;8;400;E;0;;;N;12;;;;;;;1;1;1;05:00PM;Y;5;4;1;0*>
+ *   hyv  1A;F;F;I;0;8;400;5;;;;12;;;;;;
+ *
+ * NOTE ON THE NAME `.ev3`: SDIF also defines a meet-events file with that
+ * extension, fixed-width like `.sd3`. That is a different format; detect.js
+ * sniffs content, so a fixed-width `.ev3` still routes to the SDIF adapter.
+ *
+ * The three qualifying-time columns are the SAME cut in the three courses,
+ * verified column-for-column against Virginia Swimming's published 2025-2028
+ * Age Group Championship QT table (LCM / SCM / SCY), whose rows the fixture
+ * meets reproduce exactly. The two files order those columns differently:
+ *
+ *   ev3  col 16 = LCM, col 18 = SCM, col 20 = SCY — FIXED, whatever the meet's
+ *        own course. Confirmed against an SCY meet and an LCM meet.
+ *   hyv  cols 9, 13, 15 — ROTATED to start at the meet's own course, then
+ *        cycling Y → L → S. An SCY meet reads (SCY, LCM, SCM); an LCM meet
+ *        reads (LCM, SCM, SCY). Both confirmed; the SCM rotation (SCM, SCY,
+ *        LCM) follows the same cycle but has not been seen in a real file.
+ *
+ * A course column a meet does not accept can be BLANKET-FILLED with a
+ * placeholder rather than left empty: the Eastern Zone fixture carries 0.01 or
+ * 1.00 in its SCM column on all 108 events, relays included. Those are stated
+ * times, so `qualifyingTimes` keeps them verbatim — dropping file data is not
+ * this layer's call — but `qualifyingStandards()` filters them, since a table
+ * of cuts is useless with them in. See that function.
+ *
+ * Each qualifying time is preceded by an always-empty column (ev3 15/17/19,
+ * hyv 8/12/14/16), almost certainly the matching "no faster than" limit that
+ * Meet Manager pairs with every cut. Empty in every sample, so its meaning is
+ * unconfirmed and it is not emitted.
+ *
+ * Columns deliberately left unread because the samples could not pin them down:
+ * ev3 10, 11, 12, 13 (constant), and the per-session trio 26/27/28.
+ */
+
+import { HY3_STROKE, SDIF_STROKE, STROKE, GENDER_DISPLAY, COURSE, ageGroup } from './constants.js';
+import { timeFromText, normalizeDate } from './times.js';
+
+/** Event-sex code → canonical gender. ev3 uses G/B, hyv uses F/M. */
+const EVENT_SEX = { G: 'F', B: 'M', F: 'F', M: 'M', X: 'X' };
+
+/** Round code → canonical round. 'P' means prelims feeding a final. */
+const ROUND = { F: 'finals', P: 'prelims' };
+
+/** A relay's stroke code means the relay stroke, not the individual one. */
+const RELAY_STROKE_EV3 = { A: STROKE.FREESTYLE, E: STROKE.MEDLEY };
+const RELAY_STROKE_HYV = { 1: STROKE.FREESTYLE, 5: STROKE.MEDLEY };
+
+const clean = (s) => (s == null ? '' : String(s).trim());
+
+/** "MM/DD/YYYY" → ISO "YYYY-MM-DD". */
+const isoDate = (raw) => normalizeDate(clean(raw).replace(/\//g, ''));
+
+/** "05:00PM" → "17:00". Returns null for anything else. */
+function clockTime(raw) {
+    const m = /^(\d{1,2}):(\d{2})\s*([AP])M$/i.exec(clean(raw));
+    if (!m) return null;
+    let hour = parseInt(m[1], 10) % 12;
+    if (m[3].toUpperCase() === 'P') hour += 12;
+    return `${String(hour).padStart(2, '0')}:${m[2]}`;
+}
+
+const int = (raw) => {
+    const v = parseInt(clean(raw), 10);
+    return Number.isNaN(v) ? null : v;
+};
+
+const num = (raw) => {
+    const v = parseFloat(clean(raw));
+    return Number.isNaN(v) ? null : v;
+};
+
+/** Meet Manager writes an unset date as the Unix epoch. */
+const EPOCH_SENTINEL = /^01\/01\/1970$/;
+
+/**
+ * Below this, a "qualifying time" is a placeholder for a course the meet does
+ * not accept, not a standard: no swim of any distance is a second long, and the
+ * Eastern Zone fixture blanket-fills its SCM column with 0.01/1.00 on nearly
+ * every event, relays included.
+ */
+const PLACEHOLDER_CUT_SECONDS = 1;
+
+/** Splits a record, dropping the ev3 `*>` terminator from the last field. */
+const fields = (line) => line.replace(/\*>\s*$/, '').split(';');
+
+const records = (content) =>
+    String(content)
+        .split(/\r?\n/)
+        .filter((l) => l.trim() !== '')
+        .map(fields);
+
+/**
+ * Builds the shared event shape from already-decoded parts.
+ * `description` matches the result adapters', so an event parsed from a setup
+ * file and the same event parsed from a result file read identically.
+ */
+function buildEvent({ number, type, round, rounds, gender, distance, stroke, course, lower, upper, entryFee, qualifyingTimes, relayLegs, session }) {
+    const ag = ageGroup(lower, upper);
+    const agLabel = type === 'relay' && ag.label === 'Open' ? '' : ag.label;
+    const description = `${GENDER_DISPLAY[gender]} ${agLabel} ${distance}m ${stroke}${type === 'relay' ? ' Relay' : ''}`
+        .replace(/\s+/g, ' ')
+        .trim();
+    return {
+        number,
+        type,
+        round,
+        rounds,
+        gender,
+        distance,
+        stroke,
+        course,
+        ageGroup: ag,
+        description,
+        relayLegs,
+        entryFee,
+        qualifyingTimes,
+        session,
+    };
+}
+
+/** { LCM, SCM, SCY } from three raw time strings, any of which may be blank. */
+const qualTimes = (lcm, scm, scy) => ({
+    LCM: timeFromText(lcm),
+    SCM: timeFromText(scm),
+    SCY: timeFromText(scy),
+});
+
+/** The cycle the hyv rotates its qualifying-time columns through. */
+const COURSE_CYCLE = ['Y', 'L', 'S'];
+
+/**
+ * Reads the hyv's three qualifying-time columns, which start at the meet's own
+ * course and cycle from there — see the header note.
+ * @param {string} courseCode single-char meet course from the hyv header
+ * @param {string[]} f the record's fields
+ */
+function hyvQualTimes(courseCode, f) {
+    const start = Math.max(0, COURSE_CYCLE.indexOf(courseCode));
+    const times = { LCM: null, SCM: null, SCY: null };
+    [9, 13, 15].forEach((col, i) => {
+        times[COURSE[COURSE_CYCLE[(start + i) % COURSE_CYCLE.length]]] = timeFromText(f[col]);
+    });
+    return times;
+}
+
+/** Collapses the per-event session stamps into the meet's session list. */
+function deriveSessions(events) {
+    const byId = new Map();
+    for (const ev of events) {
+        const s = ev.session;
+        if (!s) continue;
+        if (!byId.has(s.id)) byId.set(s.id, { id: s.id, day: s.day, startTime: s.startTime, eventCount: 0 });
+        byId.get(s.id).eventCount += 1;
+    }
+    return [...byId.values()];
+}
+
+/**
+ * Flattens a setup's qualifying cuts into one row per event that has one.
+ *
+ * The cuts are already on `setup.events[].qualifyingTimes`; this is the shape
+ * you want when the cuts *are* the thing you came for — a standards table to
+ * publish, diff against last season's, or check entries against. Events with no
+ * cut configured (the relays, in most meets) are left out.
+ *
+ * THE ONE PLACE THIS LAYER JUDGES THE DATA: a placeholder time in a course the
+ * meet does not accept is dropped here (see PLACEHOLDER_CUT_SECONDS), and a row
+ * left with nothing real goes with it. `event.qualifyingTimes` still carries
+ * every value the file stated — read that instead if you want the file verbatim.
+ *
+ * Beyond that, reading the file is all that happens: no conversion between
+ * courses, no "does this swimmer qualify" — that is the consumer's call.
+ *
+ * @param {NormalizedMeetSetup} setup
+ * @returns {QualifyingStandard[]}
+ */
+export function qualifyingStandards(setup) {
+    const real = (t) => (t && t.seconds > PLACEHOLDER_CUT_SECONDS ? t : null);
+    return (setup.events || [])
+        .map((ev) => ({
+            eventNumber: ev.number,
+            description: ev.description,
+            gender: ev.gender,
+            ageGroup: ev.ageGroup,
+            distance: ev.distance,
+            stroke: ev.stroke,
+            LCM: real(ev.qualifyingTimes && ev.qualifyingTimes.LCM),
+            SCM: real(ev.qualifyingTimes && ev.qualifyingTimes.SCM),
+            SCY: real(ev.qualifyingTimes && ev.qualifyingTimes.SCY),
+        }))
+        .filter((row) => row.LCM || row.SCM || row.SCY);
+}
+
+/**
+ * Parses a Meet Manager `.ev3` meet-events export.
+ * @param {string} content
+ * @returns {import('./model.js').NormalizedMeetSetup}
+ */
+export function parseEv3(content) {
+    const [head, ...rows] = records(content);
+    if (!head) throw new Error('swimparse: empty .ev3 file');
+
+    const name = clean(head[0]);
+    const meet = {
+        name,
+        rawName: name,
+        hostName: clean(head[1]) || undefined,
+        startDate: isoDate(head[2]),
+        endDate: isoDate(head[3]),
+        ageUpDate: isoDate(head[4]),
+        course: COURSE[clean(head[5]).charAt(0)] || null,
+        sanction: clean(head[14]) || undefined,
+        entryDeadline: isoDate(head[23]),
+        // INFERRED, not confirmed against a spec: header field 16 reads
+        // 11/01/2024 in both Virginia championships (whose standards are the
+        // published 2025-2028 set), 08/06/2025 in the Eastern Zone meet (just
+        // after the 2025 zone championships), and the epoch sentinel in the one
+        // meet that sets no cuts at all. That is what a qualifying-period start
+        // looks like. Treated as unset when it reads as the epoch.
+        qualifyingSince: EPOCH_SENTINEL.test(clean(head[16])) ? null : isoDate(head[16]),
+        location: {
+            address: clean(head[24]) || undefined,
+            city: clean(head[26]) || undefined,
+            state: clean(head[27]) || undefined,
+            postalCode: clean(head[28]) || undefined,
+            country: clean(head[29]) || undefined,
+            lsc: clean(head[30]) || undefined,
+        },
+    };
+
+    const events = rows.map((f) => {
+        const type = clean(f[4]) === 'R' ? 'relay' : 'individual';
+        const strokeCode = clean(f[9]);
+        const stroke = (type === 'relay' && RELAY_STROKE_EV3[strokeCode]) || HY3_STROKE[strokeCode] || `Stroke ${strokeCode}`;
+        return buildEvent({
+            number: clean(f[1]) || clean(f[0]),
+            type,
+            round: ROUND[clean(f[2])] || null,
+            rounds: int(f[3]),
+            gender: EVENT_SEX[clean(f[5])] || 'X',
+            distance: int(f[8]),
+            stroke,
+            lower: clean(f[6]),
+            upper: clean(f[7]),
+            course: COURSE[clean(f[25])] || null,
+            entryFee: num(f[14]),
+            qualifyingTimes: qualTimes(f[16], f[18], f[20]),
+            relayLegs: type === 'relay' ? int(f[29]) : null,
+            session: {
+                id: clean(f[21]),
+                day: int(f[23]),
+                order: int(f[22]),
+                startTime: clockTime(f[24]),
+            },
+        });
+    });
+
+    return {
+        format: 'ev3',
+        source: {
+            software: clean(head[9]) || undefined,
+            version: clean(head[11]) || undefined,
+            createdAt: isoDate(head[12]),
+        },
+        meet,
+        sessions: deriveSessions(events),
+        events,
+    };
+}
+
+/**
+ * Parses a Meet Manager `.hyv` meet-events export (the Team Manager import
+ * file). Same events as the `.ev3`, without sessions, days or start times.
+ * @param {string} content
+ * @returns {import('./model.js').NormalizedMeetSetup}
+ */
+export function parseHyv(content) {
+    const [head, ...rows] = records(content);
+    if (!head) throw new Error('swimparse: empty .hyv file');
+
+    const name = clean(head[0]);
+    const courseCode = clean(head[4]).charAt(0);
+    const meet = {
+        name,
+        rawName: name,
+        hostName: clean(head[5]) || undefined,
+        startDate: isoDate(head[1]),
+        endDate: isoDate(head[2]),
+        ageUpDate: isoDate(head[3]),
+        course: COURSE[courseCode] || null,
+    };
+
+    const events = rows.map((f) => {
+        const type = clean(f[3]) === 'R' ? 'relay' : 'individual';
+        const strokeCode = clean(f[7]);
+        const stroke = (type === 'relay' && RELAY_STROKE_HYV[strokeCode]) || SDIF_STROKE[strokeCode] || `Stroke ${strokeCode}`;
+        // hyv writes an open-ended upper age as 0; ev3 writes 109.
+        const upper = clean(f[5]) === '0' ? '109' : clean(f[5]);
+        return buildEvent({
+            number: clean(f[0]),
+            type,
+            round: ROUND[clean(f[1])] || null,
+            rounds: null,
+            gender: EVENT_SEX[clean(f[2])] || 'X',
+            distance: int(f[6]),
+            stroke,
+            lower: clean(f[4]),
+            upper,
+            course: null, // the hyv states no per-event course
+            entryFee: num(f[11]),
+            qualifyingTimes: hyvQualTimes(courseCode, f),
+            relayLegs: null,
+            session: null,
+        });
+    });
+
+    return {
+        format: 'hyv',
+        source: {
+            software: clean(head[7]) || undefined,
+            version: clean(head[8]) || undefined,
+            createdAt: null,
+        },
+        meet,
+        sessions: [],
+        events,
+    };
+}