@thebattlearena/corner 0.9.0 → 0.10.0

package/ring/scripts/play-by-play.mjs

@@ -8,14 +8,22 @@
 // A fight that starts at a sparring is one chronicle (fight.mjs): `--sparring <slug>`, or a bout
 // opened `--from-sparring <slug>`, prints the sparring's falls and every bout of it as the third.
 //
-// Output: { pr, repo, boutDir, generatedAt, timezone, copilotOnHead, rounds, events, score, gaps,
-// notes }. Every event carries its real time (`at`, plus `local` HH:MM in --tz) and its `source`.
+//   node play-by-play.mjs embed <page.html> [<bout dir>/db-diagram.html…] [--contract <bout dir>…]
+//                     [--interview <bout dir>…]   (the questions' context for «Ver más información»)
+//                     [--routes <bout dir>…]      (a frontend bout's «Rutas del frontend»)
+//                     [--plan <bout dir>…]        («El plan del técnico», from plan-tecnico.md)
+//                     after writing the page: each bout's diagram and endpoints go after their
+//                     placeholders, and the page's scripts at its end (page-embed.mjs)
+//
+// Output: { pr, repo, boutDir, generatedAt, timezone, copilotOnHead, weighIn, interview, rounds,
+// events, score, gaps, notes }. `weighIn` and `interview` are the bout's preparation, told before
+// its first round (preparation.mjs); the events they tell carry `stage`. Every event carries its real time (`at`, plus `local` HH:MM in --tz) and its `source`.
 // Anything without a recorded time goes to `gaps` with the two known times around it; nothing is
 // ever given an invented time. --extra adds times the human or another tool provides (an array of
 // { at, type, title, detail, ref }, inline or in a file), always marked `provided`.
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 
 import {
   checkEvents,
@@ -34,11 +42,33 @@ import {
   boutDir,
   isMain,
   projectDir,
+  RING_ROOT,
   readState,
   repoSlug,
   slugFromRemote,
 } from './config.mjs';
 import { collectFight } from './fight.mjs';
+import {
+  INTERVIEW,
+  contextWarnings,
+  pageContexts,
+  parseInterview,
+  withLocalTimes,
+  withStages,
+} from './preparation.mjs';
+import {
+  collectContractSources,
+  endpointsBlock,
+} from './contract-endpoints.mjs';
+import { collectFrontRoutes, routesBlock } from './front-routes.mjs';
+import { collectPreparation } from './preparation-collect.mjs';
+import { planBlock } from './tech-plan-log.mjs';
+import {
+  embedBlocks,
+  embedContexts,
+  embedDiagrams,
+  embedScripts,
+} from './page-embed.mjs';
 
 const run = (bin, args, cwd) =>
   execFileSync(bin, args, {
@@ -82,7 +112,109 @@ export function readExtra(value) {
 }
 
 const USAGE =
-  'usage: play-by-play.mjs <pr> [--repo <owner/name>] | --sparring <slug>; [--tz <zone>] [--extra <json|file>] [--no-gh]';
+  'usage: play-by-play.mjs <pr> [--repo <owner/name>] | --sparring <slug>; [--tz <zone>] [--extra <json|file>] [--no-gh] | embed <page.html> [<bout dir>/db-diagram.html…] [--contract <bout dir>…] [--interview <bout dir>…] [--routes <bout dir>…] [--plan <bout dir>…]';
+
+/**
+ * `embed <page> [<bout dir>/db-diagram.html…] [--contract <bout dir>…]`: puts each bout's diagram
+ * after its `ring:db-diagram #<pr>` placeholder (the bout's number is its directory's name), each
+ * bout's «Endpoints del contrato» after its `ring:api-contract #<pr>` placeholder, and the page's
+ * scripts at its end (page-embed.mjs). Run it after every rewrite of the page.
+ */
+const FLAGS = ['--contract', '--interview', '--routes', '--plan'];
+
+function embed(argv) {
+  const warnings = [];
+  const [page] = argv;
+  if (!page) throw new Error(USAGE);
+  const valuesOf = (flag) =>
+    argv.flatMap((arg, index) => (argv[index - 1] === flag ? [arg] : []));
+  const contracts = valuesOf('--contract');
+  const interviews = valuesOf('--interview');
+  const routeDirs = valuesOf('--routes');
+  const planDirs = valuesOf('--plan');
+  const diagrams = argv
+    .slice(1)
+    .filter(
+      (arg, index, rest) =>
+        !FLAGS.includes(arg) && !FLAGS.includes(rest[index - 1]),
+    );
+  const byPr = Object.fromEntries(
+    diagrams.map((path) => [
+      basename(dirname(path)),
+      readFileSync(path, 'utf8'),
+    ]),
+  );
+  const specs = Object.fromEntries(
+    contracts.map((dir) => {
+      const sources = collectContractSources(dir);
+      return [String(sources.pr), endpointsBlock(sources)];
+    }),
+  );
+  let after = embedDiagrams(readFileSync(page, 'utf8'), byPr);
+  after = embedBlocks(after, 'api-contract', specs);
+  const routeBlocks = Object.fromEntries(
+    routeDirs.map((dir) => {
+      const routes = collectFrontRoutes(dir);
+      return [String(routes.pr), routesBlock(routes)];
+    }),
+  );
+  after = embedBlocks(after, 'front-routes', routeBlocks);
+  const planBlocks = Object.fromEntries(
+    planDirs.map((dir) => {
+      const block = planBlock(dir);
+      return [String(block.pr), block.html];
+    }),
+  );
+  after = embedBlocks(after, 'tech-plan', planBlocks);
+  const contexts = Object.assign(
+    {},
+    ...interviews.map((dir) => {
+      const file = join(dir, INTERVIEW);
+      const entries = parseInterview(
+        existsSync(file) ? readFileSync(file, 'utf8') : '',
+      );
+      const pr = readState(dir).pr;
+      const empty = contextWarnings(pr, entries);
+      warnings.push(
+        ...empty.map(
+          (id) =>
+            `${id}: its context has no «## Contexto <n> · …» section for those questions, so they do not show «Ver más información»`,
+        ),
+      );
+      return pageContexts(pr, entries);
+    }),
+  );
+  after = embedContexts(after, contexts);
+  const missing = [
+    ...Object.keys(byPr).map((pr) => `ring:db-diagram #${pr}`),
+    ...Object.keys(specs).map((pr) => `ring:api-contract #${pr}`),
+    ...Object.keys(routeBlocks).map((pr) => `ring:front-routes #${pr}`),
+    ...Object.keys(planBlocks).map((pr) => `ring:tech-plan #${pr}`),
+  ].filter((marker) => !after.includes(`<!-- ${marker} -->`));
+  if (missing.length)
+    throw new Error(`${page} has no placeholder <!-- ${missing[0]} -->`);
+  const template = (name) =>
+    readFileSync(
+      join(RING_ROOT, 'skills', 'play-by-play', 'templates', name),
+      'utf8',
+    );
+  after = embedScripts(after, {
+    css: template('blocks.css'),
+    form: template('interview-form.js'),
+    endpoints: template('endpoints-view.js'),
+    panel: template('now-panel.js'),
+  });
+  writeFileSync(page, after);
+  return {
+    page,
+    diagrams: Object.keys(byPr).map(Number),
+    contracts: Object.keys(specs).map(Number),
+    routes: Object.keys(routeBlocks).map(Number),
+    plans: Object.keys(planBlocks).map(Number),
+    contexts: Object.keys(contexts),
+    warnings,
+  };
+}
 
 const timezoneOf = (argv) =>
   option(argv, 'tz') ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -109,8 +241,9 @@ export function collectBout([pr, ...argv]) {
   const read = (name) =>
     existsSync(join(dir, name)) ? readFileSync(join(dir, name), 'utf8') : '';
 
+  const decisionsText = read('decisions.md');
   const decisions = parseLedger(
-    read('decisions.md'),
+    decisionsText,
     'decisions',
     'file:decisions.md',
   );
@@ -235,6 +368,18 @@ export function collectBout([pr, ...argv]) {
     gaps.push(...extra.gaps);
   }
 
+  const preparation = collectPreparation({
+    dir,
+    state,
+    opened,
+    decisionsText,
+    notes,
+  });
+  events = withStages(
+    [...events, ...preparation.events],
+    preparation.interview,
+    preparation.scale,
+  );
   const sliced = sliceRounds(events);
   events = sliced.events.map((event) => ({
     ...event,
@@ -248,6 +393,7 @@ export function collectBout([pr, ...argv]) {
     timezone,
     opened,
     copilotOnHead: onHead,
+    ...withLocalTimes(preparation, (at) => localTime(at, timezone)),
     rounds: sliced.rounds,
     events,
     score: score(events, sliced.rounds),
@@ -274,7 +420,9 @@ function collect(argv) {
 
 if (isMain(import.meta.url)) {
   try {
-    console.log(JSON.stringify(collect(process.argv.slice(2)), null, 2));
+    const argv = process.argv.slice(2);
+    const result = argv[0] === 'embed' ? embed(argv.slice(1)) : collect(argv);
+    console.log(JSON.stringify(result, null, 2));
   } catch (error) {
     console.error(
       `play-by-play: ${String(error.stderr || error.message).trim()}`,

package/ring/scripts/preparation-collect.mjs

@@ -0,0 +1,177 @@
+// Reads a bout's preparation from its records (the interview ledger, decisions.md, findings.json,
+// db-diagram.html) and from git (the size of the deliverable), and hands it to the pure rules of
+// preparation.mjs. Read-only and zero-dependency. What goes inside the page (the diagram, the
+// endpoints, the scripts) is page-embed.mjs.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  collectContractSources,
+  contractSourcesHash,
+} from './contract-endpoints.mjs';
+import { readLedger } from './findings.mjs';
+import { collectFrontRoutes, routesSourcesHash } from './front-routes.mjs';
+import {
+  contractFindings,
+  INTERVIEW,
+  interviewEvents,
+  interviewOf,
+  parseInterview,
+  parseShortstat,
+  preparationEnd,
+  scaleOf,
+} from './preparation.mjs';
+import {
+  madeWeight,
+  parseVerdicts,
+  VERDICTS,
+  verdictSummary,
+} from './verdicts.mjs';
+
+export const DIAGRAM = 'db-diagram.html';
+
+const git = (dir, args) =>
+  execFileSync('git', ['-C', dir, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024,
+  }).trim();
+
+/** `origin/<base>` when the remote has it, else the local branch, else null. */
+function baseRef(worktree, base) {
+  for (const ref of [`origin/${base}`, base]) {
+    try {
+      git(worktree, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+      return ref;
+    } catch {
+      // try the next one
+    }
+  }
+  return null;
+}
+
+/**
+ * The deliverable's size against the stack base: as it was weighed (the tip when the bout opened)
+ * and now. Null when the worktree is gone or the base cannot be found.
+ */
+function sizeOf(state, opened, notes) {
+  if (!state.worktree || !existsSync(state.worktree)) return null;
+  const base = baseRef(state.worktree, state.base);
+  if (!base) {
+    notes.push(`pesaje: no base ${state.base} in the worktree; no size`);
+    return null;
+  }
+  const stat = (tip) =>
+    parseShortstat(
+      git(state.worktree, ['diff', '--shortstat', `${base}...${tip}`]),
+    );
+  const openTip = opened
+    ? git(state.worktree, ['rev-list', '-1', `--before=${opened}`, 'HEAD'])
+    : '';
+  return {
+    base,
+    atOpen: openTip ? { sha: openTip.slice(0, 9), ...stat(openTip) } : null,
+    now: {
+      sha: git(state.worktree, ['rev-parse', '--short=9', 'HEAD']),
+      ...stat('HEAD'),
+    },
+  };
+}
+
+/** The wrestler's first commit after the bout opened, or null. */
+function firstCommitAt(state, opened) {
+  if (!opened || !state.worktree || !existsSync(state.worktree)) return null;
+  const times = git(state.worktree, [
+    'log',
+    '--no-merges',
+    `--since=${opened}`,
+    '--format=%cI',
+    'HEAD',
+  ])
+    .split('\n')
+    .filter(Boolean);
+  return times.at(-1) ?? null;
+}
+
+/**
+ * Whether the page has a board for the judge: changed endpoints or changed routes. When they
+ * cannot be read (the worktree is gone) it says so in `notes` and answers true, so the scale
+ * stays red instead of greening without the verdicts.
+ */
+function hasBoards(dir, notes) {
+  try {
+    return (
+      collectContractSources(dir).roots.length > 0 ||
+      collectFrontRoutes(dir).routes.length > 0
+    );
+  } catch (error) {
+    notes.push(
+      `pesaje: could not read the contract or routes boards (${error.message}); the scale waits for the verdicts`,
+    );
+    return true;
+  }
+}
+
+/**
+ * The bout's preparation: `weighIn` (promotion, size, diagram, contract findings, scale),
+ * `interview`, and the interview's timed events. `notes` collects what could not be read.
+ */
+export function collectPreparation({
+  dir,
+  state,
+  opened,
+  decisionsText,
+  notes,
+}) {
+  const read = (name) =>
+    existsSync(join(dir, name)) ? readFileSync(join(dir, name), 'utf8') : '';
+  const entries = parseInterview(read(INTERVIEW));
+  const scale = scaleOf(decisionsText);
+  const until = preparationEnd(scale, firstCommitAt(state, opened));
+  const verdictEntries = parseVerdicts(read(VERDICTS));
+  const verdicts = verdictEntries.length
+    ? verdictSummary(verdictEntries, {
+        api: contractSourcesHash(dir),
+        routes: routesSourcesHash(dir),
+      })
+    : null;
+  const diagramPath = join(dir, DIAGRAM);
+  const diagram = existsSync(diagramPath)
+    ? {
+        path: diagramPath,
+        drawnAt: statSync(diagramPath).mtime.toISOString(),
+        placeholder: `<!-- ring:db-diagram #${state.pr} -->`,
+      }
+    : null;
+  if (!entries.length)
+    notes.push(
+      `entrevista: no ${INTERVIEW}; escalations and answers are logged with \`judges-card.mjs log <pr> escalation|answer\``,
+    );
+  return {
+    weighIn: {
+      promotion: {
+        pr: state.pr,
+        branch: state.branch,
+        base: state.base,
+        worktree: state.worktree,
+      },
+      size: sizeOf(state, opened, notes),
+      diagram,
+      contractFindings: contractFindings(readLedger(dir), until),
+      verdicts,
+      scale: {
+        ...scale,
+        approvedByJudge: scale.madeWeight,
+        madeWeight: madeWeight(
+          scale,
+          verdicts,
+          scale.madeWeight ? hasBoards(dir, notes) : Boolean(verdicts),
+        ),
+      },
+    },
+    interview: interviewOf(entries, decisionsText, until),
+    events: interviewEvents(entries, until),
+    scale,
+  };
+}