@zmnatz/usa-club-rugby-data 0.2.0 → 0.4.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.d.ts

@@ -35,3 +35,11 @@ export declare function clubsInRows(rows: PlayerRow[]): Club[];
  *  are combined into a single total; rows with no id cannot be joined and are
  *  excluded. */
 export declare function computeBreakdown(rows: PlayerRow[], sides: Side[], rules: EligibilityRules, remaining?: RemainingMatches): EligibilityBreakdown;
+/** Where a player stands on a side, most urgent first. */
+export declare const VERDICT_STATUSES: readonly ['ineligible', 'caution', 'on-track', 'eligible'];
+export type VerdictStatus = (typeof VERDICT_STATUSES)[number];
+/** A verdict as one status. Ineligible outranks Caution, and Caution outranks On
+ *  Track, which a player can still recover from. */
+export declare function verdictStatus(player: Pick<PlayerEligibility, 'eligible' | 'pending' | 'cautions'>): VerdictStatus;
+/** A status's place in `VERDICT_STATUSES`, for sorting: lowest is most urgent. */
+export declare function verdictRank(player: Pick<PlayerEligibility, 'eligible' | 'pending' | 'cautions'>): number;

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(),
                 },
             };
@@ -241,3 +251,18 @@ export function computeBreakdown(rows, sides, rules, remaining = {}) {
         ignoredTeamNames: [...new Set(rows.map((row) => row.teamName).filter((name) => !teamNames.has(name)))],
     };
 }
+/** Where a player stands on a side, most urgent first. */
+export const VERDICT_STATUSES = ['ineligible', 'caution', 'on-track', 'eligible'];
+/** A verdict as one status. Ineligible outranks Caution, and Caution outranks On
+ *  Track, which a player can still recover from. */
+export function verdictStatus(player) {
+    if (!player.eligible)
+        return 'ineligible';
+    if (player.cautions.length > 0)
+        return 'caution';
+    return player.pending.length > 0 ? 'on-track' : 'eligible';
+}
+/** A status's place in `VERDICT_STATUSES`, for sorting: lowest is most urgent. */
+export function verdictRank(player) {
+    return VERDICT_STATUSES.indexOf(verdictStatus(player));
+}

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.4.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",