@thebattlearena/corner 0.9.1-beta.70 → 0.10.0

package/ring/scripts/tech-plan.mjs

@@ -0,0 +1,191 @@
+// «El plan del técnico»: what the wrestler has to do for the deliverable, per bout, in
+// `<bout dir>/plan-tecnico.md`: `## <group>` and bullets `- [<state>] **<title>** <detail> ·
+// origen: <ids>`, the states being pendiente · espera al juez · en curso · hecho. The origin cites
+// findings (B1, F8…), decisions (D1…), questions (E1-3), verdicts or the sparring's card. A group
+// whose name says «tickets» holds what stays out of the delivery. `judges-card.mjs plan` changes a
+// state without editing the file by hand and keeps each change with its time in `plan.jsonl`; a
+// judge's «se mejora» enters the plan as a new point. PURE and zero-dependency.
+
+export const PLAN = 'plan-tecnico.md';
+export const PLAN_LOG = 'plan.jsonl';
+export const PLAN_STATES = ['pendiente', 'espera al juez', 'en curso', 'hecho'];
+const ITEM = /^(\s*-\s+)\[([^\]]+)\]\s+\*\*(.+?)\*\*\s*(.*)$/;
+
+/** Checks a state name, accepting the English ones the referee may type. PURE. */
+export function planState(value) {
+  const aliases = {
+    pending: 'pendiente',
+    waiting: 'espera al juez',
+    'in progress': 'en curso',
+    doing: 'en curso',
+    done: 'hecho',
+  };
+  const state =
+    aliases[String(value).toLowerCase()] ?? String(value).toLowerCase();
+  if (!PLAN_STATES.includes(state))
+    throw new Error(
+      `"${value}" is not a plan state (${PLAN_STATES.join(' · ')})`,
+    );
+  return state;
+}
+
+const isTickets = (name) => /tickets?/i.test(name);
+
+/**
+ * The plan: its title, its groups with their points (numbered across the plan, in order), and the
+ * tickets left out of the delivery. A point's origin ids come from `· origen: a, b`. PURE.
+ */
+export function parsePlan(markdown) {
+  const plan = { title: null, groups: [], tickets: [] };
+  let group = null;
+  let n = 0;
+  String(markdown ?? '')
+    .split('\n')
+    .forEach((line, index) => {
+      const title = /^#\s+(.+)$/.exec(line);
+      if (title && !plan.title) return void (plan.title = title[1].trim());
+      const heading = /^##\s+(.+)$/.exec(line);
+      if (heading) {
+        group = {
+          name: heading[1].trim(),
+          tickets: isTickets(heading[1]),
+          items: [],
+        };
+        if (!group.tickets) plan.groups.push(group);
+        return;
+      }
+      if (!group) return;
+      if (group.tickets) {
+        const ticket = /^\s*-\s+(.+)$/.exec(line);
+        if (ticket) plan.tickets.push(ticket[1].trim());
+        return;
+      }
+      const item = ITEM.exec(line);
+      if (!item) return;
+      const [rest, origin] = item[4].split(/\s+·\s+origen:\s*/);
+      n += 1;
+      group.items.push({
+        n,
+        state: item[2].trim().toLowerCase(),
+        title: item[3].trim(),
+        detail: rest.trim(),
+        origins: origin
+          ? origin
+              .split(/,\s*/)
+              .map((id) => id.trim())
+              .filter(Boolean)
+          : [],
+        line: index,
+      });
+    });
+  return plan;
+}
+
+const itemsOf = (plan) => plan.groups.flatMap((group) => group.items);
+
+/** The point `target` names: its number, or a piece of its title (only one may match). PURE. */
+export function planItem(plan, target) {
+  const items = itemsOf(plan);
+  if (/^\d+$/.test(String(target))) {
+    const found = items.find((item) => item.n === Number(target));
+    if (!found)
+      throw new Error(`the plan has no point ${target} (1–${items.length})`);
+    return found;
+  }
+  const needle = String(target).toLowerCase();
+  const matches = items.filter((item) =>
+    item.title.toLowerCase().includes(needle),
+  );
+  if (matches.length !== 1)
+    throw new Error(
+      matches.length
+        ? `"${target}" matches ${matches.length} points: ${matches.map((item) => `${item.n} ${item.title}`).join('; ')}`
+        : `no point of the plan says "${target}"`,
+    );
+  return matches[0];
+}
+
+/** The plan's Markdown with one point in a new state; nothing else changes. PURE. */
+export function withPlanState(markdown, item, state) {
+  const lines = String(markdown).split('\n');
+  lines[item.line] = lines[item.line].replace(
+    /\[[^\]]+\]/,
+    `[${planState(state)}]`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * The plan's Markdown with a new point at the end of `group` (created before the tickets when it
+ * does not exist), unless a point already cites the same origin. PURE.
+ */
+export function withPlanItem(
+  markdown,
+  { group, title, detail = '', origins = [], state = 'pendiente' },
+) {
+  const plan = parsePlan(markdown);
+  if (
+    origins.length &&
+    itemsOf(plan).some((item) =>
+      origins.every((id) => item.origins.includes(id)),
+    )
+  )
+    return markdown;
+  const bullet = `- [${planState(state)}] **${title}**${detail ? ` ${detail}` : ''}${origins.length ? ` · origen: ${origins.join(', ')}` : ''}`;
+  const lines = String(markdown).replace(/\n+$/, '').split('\n');
+  const existing = plan.groups.find((entry) => entry.name === group);
+  if (existing?.items.length) {
+    lines.splice(existing.items.at(-1).line + 1, 0, bullet);
+    return `${lines.join('\n')}\n`;
+  }
+  const headingAt = lines.findIndex((line) => line.trim() === `## ${group}`);
+  if (headingAt !== -1) {
+    lines.splice(headingAt + 1, 0, bullet);
+    return `${lines.join('\n')}\n`;
+  }
+  const ticketsAt = lines.findIndex((line) => /^##\s+.*tickets?/i.test(line));
+  const block = [`## ${group}`, bullet, ''];
+  if (ticketsAt === -1)
+    return `${[...lines, '', ...block].join('\n').replace(/\n+$/, '')}\n`;
+  lines.splice(ticketsAt, 0, ...block);
+  return `${lines.join('\n')}\n`;
+}
+
+/** The plan log's entries, skipping lines that are not JSON. PURE. */
+export function parsePlanLog(text) {
+  return String(text ?? '')
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * The plan for the page: each point with its last change (`since`, `ref`) from the log, matched by
+ * title, and each group's count of points done. PURE.
+ */
+export function planForPage(markdown, log) {
+  const plan = parsePlan(markdown);
+  const last = {};
+  log.forEach((entry) => (last[entry.title] = entry));
+  return {
+    title: plan.title,
+    tickets: plan.tickets,
+    groups: plan.groups.map((group) => ({
+      name: group.name,
+      done: group.items.filter((item) => item.state === 'hecho').length,
+      total: group.items.length,
+      items: group.items.map(({ line, ...item }) => ({
+        ...item,
+        since: last[item.title]?.at ?? null,
+        ref: last[item.title]?.ref ?? null,
+      })),
+    })),
+  };
+}

package/ring/scripts/verdicts-log.mjs

@@ -0,0 +1,75 @@
+// Logs the judge's verdicts on the contract's endpoints, read from the chronicle page, into the
+// bout (`judges-card.mjs page-verdicts`): each new verdict at the time the judge gave it, the
+// contract state the judge's view saved, and each «se mejora» as a contract finding, so it travels
+// to the wrestler in the rebound. Zero-dependency; the rules are verdicts.mjs.
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { contractSourcesHash } from './contract-endpoints.mjs';
+import { readLedger, withFindings, writeLedger } from './findings.mjs';
+import { routesSourcesHash } from './front-routes.mjs';
+import { addPlanItem } from './tech-plan-log.mjs';
+import { record } from './live.mjs';
+import {
+  improveFinding,
+  pageVerdictDocs,
+  pageVerdictEntries,
+  parseVerdicts,
+  VERDICTS,
+  verdictReport,
+  verdictSummary,
+} from './verdicts.mjs';
+
+export function logPageVerdicts(dir, pr, listing) {
+  const file = join(dir, VERDICTS);
+  const entries = parseVerdicts(
+    existsSync(file) ? readFileSync(file, 'utf8') : '',
+  );
+  const fresh = pageVerdictEntries(entries, pageVerdictDocs(listing), { pr });
+  for (const entry of fresh) appendFileSync(file, `${JSON.stringify(entry)}\n`);
+  const improve = fresh.filter(
+    (entry) => entry.kind === 'verdict' && entry.verdict === 'improve',
+  );
+  const added = improve.length
+    ? writeLedger(
+        dir,
+        withFindings(readLedger(dir), {
+          source: 'contract',
+          range: null,
+          upTo: null,
+          texts: improve.map(improveFinding),
+          at: new Date().toISOString(),
+        }).ledger,
+      )
+    : null;
+  // Each «se mejora» is also a point of the technical plan, with the verdict as its origin.
+  const planned = improve.filter((entry) =>
+    addPlanItem(dir, {
+      group: 'Lo que pidió el juez',
+      title: `${entry.method} ${entry.path}`,
+      detail: entry.comment,
+      origins: [entry.key],
+    }),
+  ).length;
+  for (const entry of fresh.filter((item) => item.kind === 'verdict'))
+    record(dir, {
+      actor: 'juez',
+      state: 'done',
+      label:
+        entry.verdict === 'approved'
+          ? 'aprobó un endpoint'
+          : 'pidió mejorar un endpoint',
+      detail: `${entry.method} ${entry.path}${entry.comment ? ` · ${entry.comment}` : ''}`,
+    });
+  const summary = verdictSummary([...entries, ...fresh], {
+    api: contractSourcesHash(dir),
+    routes: routesSourcesHash(dir),
+  });
+  return {
+    logged: fresh.filter((entry) => entry.kind === 'verdict').length,
+    findings: improve.length,
+    planned,
+    ledgerRevision: added ? added.revision : null,
+    report: verdictReport(summary),
+  };
+}

package/ring/scripts/verdicts.mjs

@@ -0,0 +1,205 @@
+// The judge's verdict on each endpoint of the contract, given from the chronicle page («Endpoints
+// del contrato»: «Se aprueba» or «Se mejora», with a comment and images). The page keeps them in its
+// db (collection `veredictos`), one doc per operation, each with the fingerprint (`hash`) of the
+// operation's contract when the judge gave it; the judge's own view also saves the contract's state
+// (`pr<n>-contrato`: the fingerprint of every operation and of all the embedded spec files). A
+// verdict counts only while its hash is the operation's current one: a rewritten contract asks
+// for a new one. The referee reads the collection with ArtifactData and logs it
+// (`judges-card.mjs page-verdicts`) in `<bout dir>/verdicts.jsonl`; each «se mejora» becomes a
+// contract finding. PURE and zero-dependency.
+
+export const VERDICTS = 'verdicts.jsonl';
+
+/** The verdict and state docs of the page's listing, wherever it nests them. PURE. */
+export function pageVerdictDocs(listing) {
+  const verdicts = [];
+  const states = [];
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) return node.forEach(walk);
+    if (node.kind === 'contract-state' && node.ops)
+      return void states.push(node);
+    if (
+      ['approved', 'improve'].includes(node.verdict) &&
+      node.method &&
+      (node.path || node.url) &&
+      node.key
+    )
+      return void verdicts.push(node);
+    Object.values(node).forEach(walk);
+  };
+  walk(listing);
+  return { verdicts, states };
+}
+
+/** The ledger's entries, skipping lines that are not JSON. PURE. */
+export function parseVerdicts(text) {
+  return String(text ?? '')
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry) => entry && ['verdict', 'state'].includes(entry.kind));
+}
+
+/**
+ * What to log from the page for bout `pr`: the contract state the judge's view saved last (when
+ * newer than the logged one) and every verdict not logged yet, oldest first. PURE.
+ */
+export function pageVerdictEntries(entries, docs, { pr }) {
+  const logged = new Set(entries.map((entry) => entry.source).filter(Boolean));
+  const mine = (doc) => Number(doc.pr) === Number(pr);
+  const fresh = [];
+  // The latest state of each block the page judges: `api` (the endpoints) and `routes`.
+  const latestByBlock = {};
+  docs.states.filter(mine).forEach((state) => {
+    const block = state.block ?? 'api';
+    const previous = latestByBlock[block];
+    if (
+      !previous ||
+      Date.parse(state.computedAt) > Date.parse(previous.computedAt)
+    )
+      latestByBlock[block] = state;
+  });
+  Object.entries(latestByBlock)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .forEach(([block, state]) => {
+      const source = `page:state:${block}@${state.computedAt}`;
+      if (logged.has(source)) return;
+      fresh.push({
+        kind: 'state',
+        block,
+        at: state.computedAt,
+        sourcesHash: state.sourcesHash,
+        ops: state.ops,
+        source,
+      });
+    });
+  docs.verdicts
+    .filter(mine)
+    .map((doc) => ({ doc, source: `page:${doc.key}@${doc.at}` }))
+    .filter(({ source }) => !logged.has(source))
+    .sort((a, b) => Date.parse(a.doc.at) - Date.parse(b.doc.at))
+    .forEach(({ doc, source }) =>
+      fresh.push({
+        kind: 'verdict',
+        key: doc.key,
+        method: doc.method,
+        path: doc.path ?? doc.url,
+        specFile: doc.specFile ?? null,
+        hash: doc.hash,
+        verdict: doc.verdict,
+        comment: String(doc.comment ?? '').trim(),
+        attachments: Array.isArray(doc.attachments) ? doc.attachments : [],
+        at: doc.at,
+        source,
+      }),
+    );
+  return fresh;
+}
+
+/**
+ * Where the contract stands with the judge, from the ledger: the last state the page saved and,
+ * per operation of it, the latest verdict, current only when its hash is the operation's. `total`
+ * counts the operations added or changed; `approved` those with a current «se aprueba»; `improve`
+ * the current «se mejora» (the pending list); `stale` the verdicts the contract outgrew. With
+ * `sourcesHash` (the embedded spec files now), a state of other files is reported as `outdated`.
+ * Null without a state. PURE.
+ */
+export function verdictSummary(entries, sourcesHashes = null) {
+  const latestByBlock = {};
+  entries
+    .filter((entry) => entry.kind === 'state')
+    .forEach((entry) => (latestByBlock[entry.block ?? 'api'] = entry));
+  const blocks = Object.entries(latestByBlock);
+  if (!blocks.length) return null;
+  const hashes =
+    typeof sourcesHashes === 'string'
+      ? { api: sourcesHashes }
+      : (sourcesHashes ?? {});
+  const state = {
+    at: blocks
+      .map(([, entry]) => entry.at)
+      .sort()
+      .at(-1),
+    ops: Object.assign({}, ...blocks.map(([, entry]) => entry.ops ?? {})),
+  };
+  // A hash passed as null is a read that failed: the block counts as outdated, never as verified.
+  const outdatedBlocks = blocks
+    .filter(
+      ([block, entry]) =>
+        Object.hasOwn(hashes, block) &&
+        (hashes[block] === null || entry.sourcesHash !== hashes[block]),
+    )
+    .map(([block]) => block);
+  const latest = {};
+  entries
+    .filter((entry) => entry.kind === 'verdict')
+    .forEach((entry) => (latest[entry.key] = entry));
+  const ops = Object.entries(state.ops ?? {}).filter(([, op]) =>
+    ['added', 'changed'].includes(op.status),
+  );
+  const rows = ops.map(([key, op]) => {
+    const verdict = latest[key];
+    const current = verdict && verdict.hash === op.hash ? verdict : null;
+    return { key, method: op.method, path: op.path, op, verdict, current };
+  });
+  const pick = (verdict) =>
+    rows
+      .filter((row) => row.current?.verdict === verdict)
+      .map(({ key, method, path, current }) => ({
+        key,
+        method,
+        path,
+        at: current.at,
+        comment: current.comment,
+        attachments: current.attachments,
+      }));
+  const approved = pick('approved');
+  return {
+    at: state.at,
+    outdated: outdatedBlocks.length > 0,
+    outdatedBlocks,
+    total: rows.length,
+    approved: approved.length,
+    improve: pick('improve'),
+    stale: rows
+      .filter((row) => row.verdict && !row.current)
+      .map(({ key, method, path }) => ({ key, method, path })),
+    unanswered: rows
+      .filter((row) => !row.verdict)
+      .map(({ key, method, path }) => ({ key, method, path })),
+    complete: rows.length > 0 && approved.length === rows.length,
+  };
+}
+
+/** The contract finding a «se mejora» becomes: it travels to the wrestler in the rebound. PURE. */
+export const improveFinding = (entry) =>
+  `FIX contract ${entry.method} ${entry.path}: ${entry.comment || '(sin comentario)'} (se mejora, el juez, ${entry.at}${entry.attachments.length ? `, imágenes ${entry.attachments.join(', ')}` : ''})`;
+
+/** The line page-verdicts prints on where the contract stands. PURE. */
+export function verdictReport(summary) {
+  if (!summary)
+    return 'no contract state from the page yet: the judge has to open the chronicle once the contract is embedded';
+  if (summary.outdated)
+    return `the page's contract state (${summary.at}) is not the contract embedded now: the judge has to open the republished chronicle before the verdicts count`;
+  const counts = `${summary.approved} of ${summary.total} approved · ${summary.improve.length} se mejora · ${summary.stale.length} outdated · ${summary.unanswered.length} without a verdict`;
+  if (summary.complete)
+    return `${counts}. Every operation is approved with its current fingerprint: approve-contract can run on these contract files.`;
+  return counts;
+}
+
+/**
+ * The scale of the weigh-in: green only with the judge's `approve-contract` and, when the page
+ * has boards to judge (`reviewable`: changed endpoints or routes), every operation of them approved
+ * with its current fingerprint. A reviewable bout without a verdict state yet is not complete.
+ * `reviewable` defaults to whether there is a state. PURE.
+ */
+export const madeWeight = (scale, summary, reviewable = Boolean(summary)) =>
+  scale.madeWeight &&
+  (!reviewable || Boolean(summary?.complete && !summary.outdated));