@thebattlearena/corner 0.8.0 → 0.9.0

package/ring/scripts/sparring-chronicle.mjs

@@ -0,0 +1,470 @@
+// The pure core of a fight's chronicle when it starts at a sparring: two out of three falls. The
+// first fall is the rudo against the judge (rounds closed by each verdict), the second is the
+// defense of the técnicos (vestidor, the team's Tapes, the bell, the mask), the third is the referee
+// bout. It turns the sparring's records into the same timed events as chronicle.mjs (the eight
+// types, classified at the top of that file) and never invents a time. PURE and zero-dependency.
+import { isTime } from './chronicle.mjs';
+
+/**
+ * The moments of a fight that only the referee of the sparring can mark (`sparring.mjs mark`), with
+ * the chronicle type each one becomes.
+ */
+export const MILESTONES = Object.freeze({
+  vestidor: 'bateria',
+  defense: 'juez',
+  bell: 'campana',
+  'mask-kept': 'juez',
+  'mask-lost': 'juez',
+  'no-team': 'juez',
+  referee: 'arbitro',
+});
+
+const MILESTONE_TITLES = {
+  vestidor: 'vestidor (the host gates passed)',
+  defense: 'defense of the técnicos opened',
+  bell: 'bell of the defense',
+  'mask-kept': 'the rudo keeps the mask',
+  'mask-lost': 'the rudo loses the mask',
+  'no-team': 'no second fall: the judge goes on without the team',
+  referee: 'handed to the referee',
+};
+
+/** Milestones that open the second fall, even before a KO is recorded. */
+const SECOND_FALL = ['vestidor', 'defense', 'bell', 'mask-kept', 'mask-lost'];
+
+/**
+ * What a bout opened `--from-sparring` should warn about, or null. PURE. After the KO the sparring
+ * goes through the vestidor (the host gates, then the team's defense) unless the judge said «sin
+ * equipo» (`no-team`); with neither marked, the branch reaches the referee unchecked.
+ */
+export function handOffWarning(state) {
+  const marked = (state.milestones ?? []).map((m) => m.kind);
+  if (['vestidor', 'no-team'].some((kind) => marked.includes(kind)))
+    return null;
+  return `sparring "${state.slug}" reaches the referee without the vestidor (\`sparring.mjs vestidor ${state.slug}\`) and without «sin equipo» (\`sparring.mjs mark ${state.slug} no-team\`): its branch never passed the host gates`;
+}
+export const FALLS = Object.freeze([
+  { n: 1, name: 'first fall · the rudo against the judge' },
+  { n: 2, name: 'second fall · the defense of the técnicos' },
+  { n: 3, name: 'third fall · the referee' },
+]);
+
+/** Throws unless `kind` is a milestone. PURE. */
+export function checkMilestone(kind) {
+  if (!Object.hasOwn(MILESTONES, kind))
+    throw new Error(
+      `"${kind}" is not a fight milestone (${Object.keys(MILESTONES).join(', ')})`,
+    );
+  return kind;
+}
+
+/** The milestone appended to a sparring's state, at the time it is marked. PURE. */
+export function withMilestone(
+  state,
+  kind,
+  note,
+  at = new Date().toISOString(),
+) {
+  checkMilestone(kind);
+  const milestone = { kind, at, ...(note ? { note } : {}) };
+  return { ...state, milestones: [...(state.milestones ?? []), milestone] };
+}
+
+/**
+ * Records a chronicle's link on a bout's or a sparring's state, and stamps `playByPlay.publishedAt`
+ * on every publish to it. The same link again is a republish; a different one is refused. PURE.
+ */
+export function withChronicleUrl(
+  state,
+  url,
+  publishedAt = new Date().toISOString(),
+  owner = 'this bout',
+) {
+  if (!/^https:\/\/claude\.ai\//.test(String(url)))
+    throw new Error('the play-by-play link must be a claude.ai artifact URL');
+  if (state.playByPlayUrl && state.playByPlayUrl !== url)
+    throw new Error(
+      `${owner} already has its chronicle at ${state.playByPlayUrl}; republish to that link instead of creating another`,
+    );
+  return { ...state, playByPlayUrl: url, playByPlay: { publishedAt } };
+}
+
+/** The verdicts of a sparring, oldest first: `history`, else the single `verdict`. PURE. */
+export const verdictsOf = (state) =>
+  state.history ?? (state.verdict ? [state.verdict] : []);
+
+const tapeUrl = (text) =>
+  /https?:\/\/\S*\/t\/[\w-]+/.exec(String(text ?? ''))?.[0] ?? null;
+
+/** The sparring opening, its verdicts and its milestones as events. PURE. */
+export function stateEvents(state) {
+  const source = 'sparring.json';
+  const events = [];
+  if (isTime(state.openedAt))
+    events.push({
+      at: state.openedAt,
+      type: 'arbitro',
+      title: 'sparring opened',
+      detail: state.hypothesis ?? '',
+      ref: state.slug ?? null,
+      source,
+    });
+  for (const verdict of verdictsOf(state).filter((v) => isTime(v.at)))
+    events.push({
+      at: verdict.at,
+      type: 'juez',
+      title: `verdict ${verdict.call}`,
+      detail: verdict.note ?? '',
+      ref: tapeUrl(verdict.note),
+      source,
+      call: verdict.call,
+    });
+  for (const milestone of state.milestones ?? []) {
+    if (!isTime(milestone.at) || !Object.hasOwn(MILESTONES, milestone.kind))
+      continue;
+    events.push({
+      at: milestone.at,
+      type: MILESTONES[milestone.kind],
+      title: MILESTONE_TITLES[milestone.kind],
+      detail: milestone.note ?? '',
+      ref: null,
+      source,
+      milestone: milestone.kind,
+    });
+  }
+  for (const entry of state.repos ?? []) {
+    const preview = entry.preview;
+    if (!preview || !isTime(preview.checkedAt)) continue;
+    events.push(previewEvent(entry.repo, preview.checkedAt, preview));
+  }
+  return events;
+}
+
+const previewEvent = (repo, at, { state, url, environment }) => ({
+  at,
+  type: 'bateria',
+  title: `preview ${repo}`,
+  detail: [state ?? (url ? 'success' : 'unknown'), environment, url]
+    .filter(Boolean)
+    .join(' · '),
+  ref: url ?? null,
+  source: 'sparring.json',
+});
+
+/** `PR <owner/repo>#<n>`: the same title from the feed and from GitHub, so they merge. PURE. */
+const prTitle = (repo, number) => `PR ${repo}#${number}`;
+
+/** Each sparring PR opened, from `gh pr view --json createdAt,url`. PURE. */
+export function prOpenedEvents(prs) {
+  return prs
+    .filter((pr) => isTime(pr.createdAt))
+    .map((pr) => ({
+      at: pr.createdAt,
+      type: 'dado',
+      title: prTitle(pr.repo, pr.number),
+      detail: 'draft opened with the sparring and do-not-merge labels',
+      ref: pr.url ?? null,
+      source: 'gh:pr',
+    }));
+}
+
+/**
+ * The referee's own lines of the sparring's live feed (`live.jsonl`): repos added, PRs opened and
+ * each preview look. The rest of the feed (tool calls, verdicts, milestones) is either noise or
+ * already in sparring.json. The feed keeps only its last lines: what it trimmed is simply absent.
+ * PURE.
+ */
+export function feedEvents(text) {
+  const events = [];
+  for (const line of String(text ?? '').split('\n')) {
+    let raw;
+    try {
+      raw = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (raw?.actor !== 'arbitro' || !isTime(raw.at)) continue;
+    const base = { at: raw.at, ref: raw.url ?? null, source: 'live.jsonl' };
+    if (raw.label === 'sumó un repo')
+      events.push({
+        ...base,
+        type: 'arbitro',
+        title: 'repo added',
+        detail: raw.detail ?? '',
+      });
+    if (raw.label === 'abrió el PR' && raw.pr)
+      events.push({
+        ...base,
+        type: 'dado',
+        title: prTitle(raw.detail, raw.pr),
+        detail: 'draft opened with the sparring and do-not-merge labels',
+      });
+    if (['preview lista', 'sin preview'].includes(raw.label))
+      events.push({
+        ...base,
+        type: 'bateria',
+        title: `preview ${raw.detail}`,
+        detail: [raw.url ? 'success' : raw.reason, raw.url]
+          .filter(Boolean)
+          .join(' · '),
+      });
+  }
+  return events;
+}
+
+/**
+ * The same event told by two records (the feed and GitHub, the feed and sparring.json) is kept
+ * once, the first: same type and title within `windowMs`. PURE.
+ */
+export function dedupe(events, windowMs = 5 * 60_000) {
+  const kept = [];
+  for (const event of [...events].sort(byTime)) {
+    const twin = kept.find(
+      (other) =>
+        other.type === event.type &&
+        other.title === event.title &&
+        Math.abs(Date.parse(other.at) - Date.parse(event.at)) <= windowMs,
+    );
+    if (!twin) kept.push(event);
+  }
+  return kept;
+}
+
+const byTime = (a, b) => Date.parse(a.at) - Date.parse(b.at);
+
+/** `oct` → 10, in Spanish and English (and `set`, Spanish for September). */
+const MONTHS = Object.fromEntries(
+  [
+    'ene feb mar abr may jun jul ago sep oct nov dic',
+    'jan feb mar apr may jun jul aug set oct nov dec',
+  ].flatMap((names) =>
+    names.split(' ').map((name, index) => [name, index + 1]),
+  ),
+);
+
+/** Milliseconds a time zone is ahead of UTC at the instant `ms`. PURE. */
+function zoneOffset(ms, timeZone) {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      hourCycle: 'h23',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    })
+      .formatToParts(new Date(ms))
+      .map((part) => [part.type, part.value]),
+  );
+  const asUtc = Date.UTC(
+    Number(parts.year),
+    Number(parts.month) - 1,
+    Number(parts.day),
+    Number(parts.hour),
+    Number(parts.minute),
+    Number(parts.second),
+  );
+  return asUtc - ms;
+}
+
+/** A wall-clock time in a time zone → ISO (UTC). PURE. */
+export function zonedIso({ year, month, day, hour, minute }, timeZone) {
+  const wall = Date.UTC(year, month - 1, day, hour, minute);
+  const first = wall - zoneOffset(wall, timeZone);
+  return new Date(wall - zoneOffset(first, timeZone)).toISOString();
+}
+
+/**
+ * The time the referee wrote next to a Tape, `(29-oct 11:39, 8 min)`, in the judge's time zone →
+ * ISO. The year is the sparring's (the next one when the date would fall before it opened). Null
+ * when the text holds no such time. PURE.
+ */
+export function parseTapeStamp(text, { openedAt, timeZone }) {
+  const match = /(\d{1,2})[- ]([a-z]{3})[a-z]*\.?,?\s+(\d{1,2}):(\d{2})/i.exec(
+    String(text ?? ''),
+  );
+  const month = match && MONTHS[match[2].toLowerCase()];
+  if (!month || !isTime(openedAt)) return null;
+  const [day, hour, minute] = [match[1], match[3], match[4]].map(Number);
+  const year = new Date(openedAt).getUTCFullYear();
+  const at = zonedIso({ year, month, day, hour, minute }, timeZone);
+  const early = Date.parse(at) < Date.parse(openedAt) - 2 * 86_400_000;
+  return early
+    ? zonedIso({ year: year + 1, month, day, hour, minute }, timeZone)
+    : at;
+}
+
+const cells = (line) =>
+  line
+    .trim()
+    .replace(/^\||\|$/g, '')
+    .split('|')
+    .map((cell) => cell.trim());
+
+const MINUTE = /^\d{1,3}:\d{2}$/;
+
+/**
+ * A round's catalog of blows (`blows-round-<n>.md`): the Tapes it cites and each blow, D (decision),
+ * B (bug), F (missing), Q (question) or R (noise), with its Tape minute. A row of the team's defense
+ * (7 columns: who, Tape · min, category, severity, blow, confirmations) keeps who gave it. The
+ * referee's own rows (A…) are notes, not blows. PURE.
+ */
+export function parseBlows(text, file) {
+  const round = Number(/blows-round-(\d+)\.md$/.exec(file)?.[1]) || null;
+  const lines = String(text ?? '').split('\n');
+  const tapes = [];
+  for (const line of lines.filter((l) => !l.trim().startsWith('|'))) {
+    const re = /Tape (https?:\/\/\S+?)\s*\(([^)]*)\)/g;
+    for (let m = re.exec(line); m; m = re.exec(line))
+      if (!tapes.some((tape) => tape.url === m[1]))
+        tapes.push({ url: m[1], stamp: m[2] });
+  }
+  const blows = lines
+    .filter((line) => /^\|\s*[DBFQR]\d+\s*\|/.test(line))
+    .map((line) => {
+      const row = cells(line);
+      const id = row[0];
+      const team = row.length >= 7;
+      const minute = (team ? /\d{1,3}:\d{2}/.exec(row[2])?.[0] : row[1]) ?? '';
+      return {
+        id,
+        kind: id[0],
+        minute: MINUTE.test(minute) ? minute : null,
+        text: team ? row[5] : row[3],
+        ...(team
+          ? { who: row[1], tape: row[2], severity: row[4] }
+          : { repo: row[4] ?? null }),
+      };
+    });
+  const counts = Object.fromEntries(
+    ['D', 'B', 'F', 'Q', 'R'].map((kind) => [
+      kind,
+      blows.filter((blow) => blow.kind === kind).length,
+    ]),
+  );
+  return { round, file, tapes, blows, counts };
+}
+
+/**
+ * Each Tape a catalog cites becomes the judge's attack at the time written next to it; a Tape
+ * whose time cannot be read is a gap. PURE.
+ */
+export function tapeEvents(catalogs, { openedAt, timeZone }) {
+  const events = [];
+  const gaps = [];
+  const seen = new Set();
+  for (const catalog of catalogs)
+    for (const tape of catalog.tapes) {
+      if (seen.has(tape.url)) continue;
+      seen.add(tape.url);
+      const counts = Object.entries(catalog.counts)
+        .filter(([, n]) => n)
+        .map(([kind, n]) => `${kind}${n}`)
+        .join(' ');
+      const base = {
+        type: 'juez',
+        title: 'Tape attack',
+        detail: [`round ${catalog.round}`, counts, tape.stamp]
+          .filter(Boolean)
+          .join(' · '),
+        ref: tape.url,
+        source: `file:${catalog.file}`,
+      };
+      const at = parseTapeStamp(tape.stamp, { openedAt, timeZone });
+      if (at) events.push({ at, ...base });
+      if (!at) gaps.push({ ...base, between: [null, null] });
+    }
+  return { events, gaps };
+}
+
+/**
+ * Splits a fight into its falls and rounds. Sparring events: the first fall runs from the opening
+ * to the KO, one round per verdict (`s1`, `s2`…; the round after the last verdict is still open);
+ * the second fall (`defense`) starts at the first second-fall milestone or right after the KO,
+ * whichever comes first; the third starts at the hand-off to the referee, at «sin equipo»
+ * (`no-team`: no second fall, the second is marked `skipped`) or at the first event of a bout. Bout events (`fall: 3`, `pr`, numeric `round`) keep their own rounds as `<pr>/<n>`.
+ * `boutRounds` is [{ pr, rounds }] as sliceRounds returned them. PURE.
+ */
+export function sliceFight(events, boutRounds = []) {
+  const sorted = [...events].sort(byTime);
+  const own = sorted.filter((event) => event.fall !== 3);
+  const bouts = sorted.filter((event) => event.fall === 3);
+  const timeOf = (event) => (event ? Date.parse(event.at) : Infinity);
+  const ko = timeOf(own.find((event) => event.call === 'ko'));
+  const second = timeOf(
+    own.find((event) => SECOND_FALL.includes(event.milestone)),
+  );
+  const noTeam = own.find((event) => event.milestone === 'no-team');
+  const third = Math.min(
+    timeOf(own.find((event) => event.milestone === 'referee')),
+    timeOf(noTeam),
+    timeOf(bouts[0]),
+  );
+  const fallOf = (time) => {
+    if (time >= third) return 3;
+    return time >= second || time > ko ? 2 : 1;
+  };
+  const verdicts = own.filter(
+    (event) => event.call && fallOf(Date.parse(event.at)) === 1,
+  );
+  const roundOf = (time) => {
+    const index = verdicts.findIndex((v) => Date.parse(v.at) >= time);
+    return `s${index === -1 ? verdicts.length + 1 : index + 1}`;
+  };
+  const ROUND_OF_FALL = { 2: () => 'defense', 3: () => 'handoff' };
+  const placed = own.map((event) => {
+    const time = Date.parse(event.at);
+    const fall = fallOf(time);
+    return { ...event, fall, round: (ROUND_OF_FALL[fall] ?? roundOf)(time) };
+  });
+  const boutPlaced = bouts.map((event) => ({
+    ...event,
+    round: `${event.pr}/${event.round}`,
+  }));
+  const all = [...placed, ...boutPlaced].sort(byTime);
+  const span = (list) => ({
+    start: list[0]?.at ?? null,
+    end: list.at(-1)?.at ?? null,
+    events: list.length,
+  });
+  const inRound = (n) => all.filter((event) => event.round === n);
+  const rounds = [];
+  const opened = placed.some((e) => e.fall === 1) ? verdicts.length + 1 : 0;
+  for (let k = 1; k <= opened; k += 1) {
+    const verdict = verdicts[k - 1];
+    const list = inRound(`s${k}`);
+    if (!verdict && !list.length) continue;
+    rounds.push({
+      n: `s${k}`,
+      fall: 1,
+      name: `round ${k}`,
+      ...span(list),
+      closed: Boolean(verdict),
+      verdict: verdict?.call ?? null,
+    });
+  }
+  for (const n of ['defense', 'handoff'].filter((n) => inRound(n).length))
+    rounds.push({
+      n,
+      fall: n === 'defense' ? 2 : 3,
+      name: n === 'defense' ? 'the defense of the técnicos' : 'hand-off',
+      ...span(inRound(n)),
+    });
+  for (const { pr, rounds: list } of boutRounds)
+    for (const round of list)
+      rounds.push({
+        ...round,
+        n: `${pr}/${round.n}`,
+        fall: 3,
+        pr,
+        name: `#${pr} ${round.name}`,
+      });
+  const falls = FALLS.map((fall) => ({
+    ...fall,
+    ...span(all.filter((event) => event.fall === fall.n)),
+    ...(fall.n === 2 && noTeam ? { skipped: true } : {}),
+  }));
+  return { falls, rounds, events: all };
+}