@zmnatz/usa-club-rugby-data 0.2.0 → 0.3.0

package/README.md

@@ -23,7 +23,7 @@ const players = await client.players('rocky-gorge'); // a verdict per player per
 const report = await client.eligibility('rocky-gorge'); // the same, grouped by side
 ```
 
-A player record carries `participation` (Match Participation: matches started plus matches entered as a substitute), `eligible`, `reasons` for a failure, `pending` for the matches an eligible player still needs, and per-round detail in `rows[].rounds`.
+A player record carries `participation` (Match Participation: matches started plus matches entered as a substitute), `eligible`, `reasons` for a failure, `pending` for the matches an eligible player still needs, `cautions` when one more upper-side match would end an eligible player's eligibility for the rest of the season, and per-round detail in `rows[].rounds`.
 
 Everything the client does is also a pure function: `clubEligibility(snapshot, fixtures, club, { rules, now })`, `computeBreakdown`, `parseTeamSide`, `possibleFixtures` and so on. The same inputs always give the same verdicts. Pass your own `EligibilityRules` to apply a different season's thresholds; `DEFAULT_RULES` are the 2026-27 Senior Club Regulations (§3.4.2, §3.5).
 

package/dist/eligibility.js

@@ -99,8 +99,10 @@ function evaluate(row, index, rosters, rules, remaining) {
     const isLowest = index === rosters.length - 1;
     const ownLabel = isLowest ? own.label : `${own.label} or lower`;
     const fixturesLeft = sum(rosters.slice(index).map((roster) => remaining[roster.side.teamName] ?? 0));
+    const fixturesKnown = rosters.slice(index).every((roster) => remaining[roster.side.teamName] !== undefined);
     const reasons = [];
     const pending = [];
+    const cautions = [];
     // A two-match minimum is met if the player can still reach it by Super
     // Regionals (Reg 3.5.1(a)); see docs/adr/008-eligibility-rules.md.
     const checkMinimum = (count, matchLabel) => {
@@ -123,10 +125,16 @@ function evaluate(row, index, rosters, rules, remaining) {
             if (count >= rules.upperMatchLimit) {
                 reasons.push(`Played ${count} ${rosters[aboveIndex].side.label} matches — playing ${rules.upperMatchLimit} for an upper side loses ${own.label} eligibility`);
             }
+            else if (count === rules.upperMatchLimit - 1) {
+                cautions.push(`One more ${rosters[aboveIndex].side.label} match (${count} played) loses ${own.label} eligibility for the rest of the season`);
+            }
         }
         if (atOrBelow < sum(above)) {
             reasons.push(`Upper-side participation (${sum(above)}) exceeds ${ownLabel} participation (${atOrBelow})`);
         }
+        else if (atOrBelow === sum(above) && fixturesLeft === 0 && fixturesKnown) {
+            cautions.push(`One more upper-side match loses ${own.label} eligibility for the rest of the season (level at ${atOrBelow} with no ${ownLabel} fixtures left)`);
+        }
     }
     return {
         playerId: row.playerId,
@@ -146,6 +154,7 @@ function evaluate(row, index, rosters, rules, remaining) {
         eligible: reasons.length === 0,
         reasons,
         pending,
+        cautions: reasons.length === 0 ? cautions : [],
     };
 }
 const byName = (a, b) => a.lastName.localeCompare(b.lastName) || a.firstName.localeCompare(b.firstName);
@@ -234,6 +243,7 @@ export function computeBreakdown(rows, sides, rules, remaining = {}) {
                     total: players.length,
                     eligible: players.filter((player) => player.eligible).length,
                     onTrack: players.filter((player) => player.eligible && player.pending.length > 0).length,
+                    caution: players.filter((player) => player.cautions.length > 0).length,
                     competitions: [...roster.competitions].sort(),
                 },
             };

package/dist/types.d.ts

@@ -73,6 +73,10 @@ export interface PlayerEligibility {
     /** Matches an eligible player still needs by Super Regionals; empty when the
      *  minimum is already met. These players are "on track". */
     pending: string[];
+    /** How one more upper-side match would end an eligible player's eligibility
+     *  for this side for the rest of the season; empty otherwise. These players
+     *  are in "Caution". */
+    cautions: string[];
 }
 /** One side's verdicts and summary. */
 export interface SideBreakdown extends Side {
@@ -90,6 +94,8 @@ export interface DivisionSummary {
     eligible: number;
     /** How many of the eligible players still need matches to reach a minimum. */
     onTrack: number;
+    /** How many of the eligible players are in Caution. */
+    caution: number;
     /** Distinct competitions this side's roster spans, sorted. */
     competitions: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zmnatz/usa-club-rugby-data",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "USA Club Rugby senior club teams, players and NCS eligibility from the Rugby Xplorer match record: typed readers for the nightly published data, a rate-limited CMS client, and the reproducible eligibility rules.",
   "keywords": [
     "rugby",