pr-docent 0.1.1 → 0.2.1

package/src/short-scenes.js

@@ -0,0 +1,127 @@
+// How a short looks: the scene markup and styles shared by the extension's live player and the
+// MP4 renderer, so a short looks the same in both. Pure string building — no DOM, no chrome.*.
+// Everything is laid out on a 1080x1920 frame (.short-frame) that players scale to fit.
+
+import { revealSteps } from "./short.js";
+
+export const FRAME_WIDTH = 1080;
+export const FRAME_HEIGHT = 1920;
+
+/** The opening card, the picture scenes, and the closing card. */
+export function sceneList(short) {
+  return [
+    { kind: "card", headline: short.title, narration: short.hook, opening: true },
+    ...short.scenes,
+    { kind: "card", headline: short.title, narration: short.outro, opening: false },
+  ];
+}
+
+/** How many elements [scene] reveals one at a time (cards show all at once). */
+export function sceneSteps(scene) {
+  return scene.kind === "card" ? 1 : revealSteps(scene);
+}
+
+/**
+ * Where to start reading [text] to land near [fraction] of the way through it: the start of the
+ * word there, since speech can only start at a character offset and a cut word sounds broken.
+ */
+export function wordStartAt(text, fraction) {
+  const at = Math.floor(Math.min(Math.max(fraction, 0), 1) * text.length);
+  if (at >= text.length) return 0;
+  const space = text.lastIndexOf(" ", at);
+  return space < 0 ? 0 : space + 1;
+}
+
+const esc = (value) => String(value ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+
+/** Classes for the [i]th element when [shown] are visible: hidden until its turn, lit when it arrives. */
+const reveal = (i, shown) => (i >= shown ? " hidden" : i === shown - 1 ? " current" : "");
+
+function diagram(scene, shown, changedLabel) {
+  const badge = (status) => (status === "new" ? '<em class="tag new">NEW</em>' : status === "changed" ? `<em class="tag changed">${esc(changedLabel)}</em>` : "");
+  if (scene.kind === "flow") {
+    return `<div class="flow">${scene.steps.map((step, i) => `
+      ${i > 0 ? `<div class="arrow${reveal(i, shown)}">${scene.links[i - 1] ? `<span>${esc(scene.links[i - 1])}</span>` : ""}</div>` : ""}
+      <div class="node ${step.status}${reveal(i, shown)}"><div class="ico">${esc(step.icon)}</div>
+        <div><b>${esc(step.label)}${badge(step.status)}</b>${step.detail ? `<small>${esc(step.detail)}</small>` : ""}</div></div>`).join("")}</div>`;
+  }
+  if (scene.kind === "compare") {
+    const side = (value, cls, i) => `<div class="side ${cls}${reveal(i, shown)}"><p class="side-label">${esc(value.label)}</p>
+      <ul>${value.items.map((item) => `<li>${esc(item)}</li>`).join("")}</ul></div>`;
+    return `<div class="compare">${side(scene.before, "before", 0)}<div class="arrow${reveal(1, shown)}"></div>${side(scene.after, "after", 1)}</div>`;
+  }
+  if (scene.kind === "structure") {
+    return `<div class="structure">${scene.groups.map((group, i) => `
+      <div class="group${reveal(i, shown)}"><p class="group-label">${esc(group.label)}</p><div class="chips">${group.items.map((item) =>
+        `<span class="chip ${item.status}">${item.icon ? `${esc(item.icon)} ` : ""}${esc(item.label)}${badge(item.status)}</span>`).join("")}</div></div>`).join("")}</div>`;
+  }
+  if (scene.kind === "points") {
+    return `<div class="points">${scene.points.map((point, i) => `
+      <div class="point${reveal(i, shown)}"><div class="ico">${esc(point.icon || "•")}</div><p>${esc(point.text)}</p></div>`).join("")}</div>`;
+  }
+  return "";
+}
+
+/** The inside of a .short-frame for [scene] with [shown] of its elements visible. */
+export function sceneMarkup(scene, { short, shown }) {
+  const { owner, repo, number } = short.pr;
+  const changedLabel = /[가-힣]/.test(JSON.stringify(short)) ? "수정" : "Changed";
+  const main = scene.kind === "card"
+    ? `<div class="card"><p class="repo">${esc(scene.opening ? `${owner}/${repo} #${number}` : `github.com/${owner}/${repo}/pull/${number}`)}</p><h1>${esc(scene.headline)}</h1></div>`
+    : `<h2>${esc(scene.headline)}</h2><div class="stage">${diagram(scene, shown, changedLabel)}</div>`;
+  return `<header>PR Docent <span>· ${esc(`${owner}/${repo} #${number}`)}</span></header>
+    <main>${main}</main>
+    <footer><p class="subtitle">${esc(scene.narration)}</p></footer>`;
+}
+
+export const SHORT_CSS = `
+  .short-frame, .short-frame * { box-sizing: border-box; margin: 0; padding: 0; }
+  .short-frame { width: ${FRAME_WIDTH}px; height: ${FRAME_HEIGHT}px; overflow: hidden; display: flex; flex-direction: column;
+    background: linear-gradient(160deg, #161b22 0%, #0d1117 55%, #1f1235 100%); color: #f0f6fc;
+    font-family: -apple-system, "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans KR", sans-serif; word-break: keep-all; }
+  .short-frame header { padding: 64px 72px 0; font-size: 30px; color: #a78bfa; font-weight: 700; }
+  .short-frame header span { color: #8b949e; font-weight: 500; }
+  .short-frame main { flex: 1; display: flex; flex-direction: column; padding: 0 72px; }
+  .short-frame .card { margin: auto 0; }
+  .short-frame .card .repo { font-size: 34px; color: #8b949e; margin-bottom: 28px; }
+  .short-frame .card h1 { font-size: 80px; line-height: 1.25; font-weight: 800; }
+  .short-frame h2 { padding-top: 56px; font-size: 66px; line-height: 1.25; font-weight: 800; color: #f0f6fc; }
+  .short-frame .stage { flex: 1; display: flex; align-items: center; justify-content: center; }
+  .short-frame .hidden { opacity: 0; }
+  .short-frame .current { box-shadow: 0 0 0 4px rgba(167, 139, 250, .55), 0 0 48px rgba(130, 80, 223, .55); }
+  .short-frame .node, .short-frame .side, .short-frame .group, .short-frame .point, .short-frame .arrow { transition: opacity .45s ease, box-shadow .45s ease; }
+  .short-frame .tag { font-style: normal; margin-left: 14px; font-size: 22px; padding: 4px 12px; border-radius: 999px; vertical-align: middle; }
+  .short-frame .tag.new { background: #8250df; } .short-frame .tag.changed { background: #9a6700; }
+  .short-frame .ico { font-size: 60px; width: 80px; text-align: center; flex: none; }
+  .short-frame .flow { width: 100%; display: flex; flex-direction: column; align-items: center; }
+  .short-frame .node { width: 100%; border-radius: 28px; padding: 28px 36px; background: #161b22; border: 3px solid #30363d; display: flex; gap: 26px; align-items: center; }
+  .short-frame .node b { display: block; font-size: 44px; }
+  .short-frame .node small { display: block; font-size: 30px; color: #8b949e; margin-top: 6px; }
+  .short-frame .node.new { border-color: #8250df; background: rgba(130, 80, 223, .14); }
+  .short-frame .node.changed { border-color: #bf8700; background: rgba(191, 135, 0, .12); }
+  .short-frame .arrow { height: 76px; width: 6px; background: #484f58; position: relative; margin: 6px 0 14px; flex: none; }
+  .short-frame .arrow::after { content: ""; position: absolute; bottom: -10px; left: -12px; border: 15px solid transparent; border-top-color: #484f58; }
+  .short-frame .arrow.current { box-shadow: none; }
+  .short-frame .arrow span { position: absolute; left: 32px; top: 18px; white-space: nowrap; font-size: 28px; color: #8b949e; }
+  .short-frame .compare { width: 100%; display: flex; flex-direction: column; align-items: center; }
+  .short-frame .side { width: 100%; border-radius: 28px; padding: 34px 40px; border: 3px solid #30363d; background: #161b22; }
+  .short-frame .side.before { opacity: .75; } .short-frame .side.before.hidden { opacity: 0; }
+  .short-frame .side.after { border-color: #8250df; background: rgba(130, 80, 223, .14); }
+  .short-frame .side-label { font-size: 32px; font-weight: 700; color: #a78bfa; margin-bottom: 16px; }
+  .short-frame .side.before .side-label { color: #8b949e; }
+  .short-frame .side li { list-style: none; font-size: 42px; line-height: 1.5; font-weight: 600; }
+  .short-frame .side li::before { content: "· "; color: #8b949e; }
+  .short-frame .structure { width: 100%; display: flex; flex-direction: column; gap: 34px; }
+  .short-frame .group { border-radius: 28px; padding: 30px 34px; border: 3px dashed #30363d; }
+  .short-frame .group-label { font-size: 32px; font-weight: 700; color: #8b949e; margin-bottom: 18px; }
+  .short-frame .chips { display: flex; flex-wrap: wrap; gap: 16px; }
+  .short-frame .chip { font-size: 38px; font-weight: 700; padding: 16px 26px; border-radius: 20px; background: #161b22; border: 3px solid #30363d; }
+  .short-frame .chip.new { border-color: #8250df; background: rgba(130, 80, 223, .16); }
+  .short-frame .chip.changed { border-color: #bf8700; background: rgba(191, 135, 0, .12); }
+  .short-frame .points { width: 100%; display: flex; flex-direction: column; gap: 30px; }
+  .short-frame .point { display: flex; gap: 26px; align-items: center; border-radius: 28px; padding: 34px 36px; background: #161b22; border: 3px solid #30363d; }
+  .short-frame .point p { font-size: 46px; line-height: 1.35; font-weight: 700; }
+  .short-frame footer { padding: 0 64px 96px; }
+  .short-frame .subtitle { background: rgba(13, 17, 23, .86); border: 2px solid #8250df; border-radius: 28px; padding: 30px 40px;
+    font-size: 42px; line-height: 1.4; font-weight: 700; text-align: center; }
+`;

package/src/short.js

@@ -0,0 +1,158 @@
+// Shorts: a 30-45 second vertical video that explains a pull request to teammates who won't
+// review it (planners, other teams) with pictures instead of code. Written from the PR's tour,
+// rendered by the local host. Pure functions — no DOM, no chrome.*, no file system.
+//
+// A short (version 1):
+// {
+//   "version": 1,
+//   "pr": { "owner": "...", "repo": "...", "number": 42 },
+//   "title": "...", "hook": "What changes and why, in one sentence.",   // the opening card
+//   "scenes": [ ...one of the kinds below... ],
+//   "outro": "What it means or what to watch for, in one sentence."      // the closing card
+// }
+// Every scene has "headline" (a few words, shown large) and "narration" (read aloud, subtitled).
+//   flow:      "steps": [{ "icon", "label", "detail", "status" }], "links": ["label between steps", ...]
+//   compare:   "before": { "label", "items": [...] }, "after": { "label", "items": [...] }
+//   structure: "groups": [{ "label", "items": [{ "icon", "label", "status" }] }]
+//   points:    "points": [{ "icon", "text" }]
+// status is "new", "changed" or "same" (default) and marks what this pull request adds or changes.
+
+export const SHORT_LIMITS = {
+  minScenes: 2, maxScenes: 4, titleChars: 40, headlineChars: 24, sentenceChars: 80,
+  labelChars: 16, detailChars: 24, itemChars: 28, pointChars: 32,
+};
+export const SCENE_KINDS = ["flow", "compare", "structure", "points"];
+const STATUSES = ["new", "changed", "same"];
+
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+
+/** Validates and normalizes raw JSON. Returns { short, errors }; short is null when there are errors. */
+export function parseShort(raw) {
+  const errors = [];
+  const fail = (message) => errors.push(message);
+  if (!raw || typeof raw !== "object") return { short: null, errors: ["Short must be a JSON object"] };
+  if (raw.version !== 1) fail(`Unsupported short version: ${raw.version}`);
+  const pr = raw.pr || {};
+  if (!pr.owner || !pr.repo || !Number.isInteger(pr.number)) fail("pr.owner, pr.repo and pr.number are required");
+  for (const field of ["title", "hook", "outro"]) if (!text(raw[field])) fail(`${field} is required`);
+  if (!Array.isArray(raw.scenes)) fail("scenes must be a list");
+
+  const scenes = (raw.scenes || []).map((scene, i) => {
+    const where = `scenes[${i}]`;
+    const kind = scene?.kind;
+    if (!SCENE_KINDS.includes(kind)) fail(`${where}.kind must be one of ${SCENE_KINDS.join(", ")}`);
+    if (!text(scene?.headline)) fail(`${where}.headline is required`);
+    if (!text(scene?.narration)) fail(`${where}.narration is required`);
+    const status = (value, at) => {
+      const s = value ?? "same";
+      if (!STATUSES.includes(s)) fail(`${at}.status must be one of ${STATUSES.join(", ")}`);
+      return s;
+    };
+    const list = (value, at) => {
+      if (!Array.isArray(value) || value.length === 0) fail(`${at} must be a non-empty list`);
+      return Array.isArray(value) ? value : [];
+    };
+    const base = { kind, headline: text(scene?.headline), narration: text(scene?.narration) };
+    if (kind === "flow") {
+      const steps = list(scene.steps, `${where}.steps`).map((step, s) => ({
+        icon: text(step?.icon), label: text(step?.label), detail: text(step?.detail), status: status(step?.status, `${where}.steps[${s}]`),
+      }));
+      steps.forEach((step, s) => !step.label && fail(`${where}.steps[${s}].label is required`));
+      return { ...base, steps, links: (Array.isArray(scene.links) ? scene.links : []).map(text) };
+    }
+    if (kind === "compare") {
+      const side = (value, name) => ({ label: text(value?.label), items: list(value?.items, `${where}.${name}.items`).map(text) });
+      return { ...base, before: side(scene.before, "before"), after: side(scene.after, "after") };
+    }
+    if (kind === "structure") {
+      const groups = list(scene.groups, `${where}.groups`).map((group, g) => ({
+        label: text(group?.label),
+        items: list(group?.items, `${where}.groups[${g}].items`).map((item, j) => ({
+          icon: text(item?.icon), label: text(item?.label), status: status(item?.status, `${where}.groups[${g}].items[${j}]`),
+        })),
+      }));
+      return { ...base, groups };
+    }
+    if (kind === "points") {
+      return { ...base, points: list(scene.points, `${where}.points`).map((point) => ({ icon: text(point?.icon), text: text(point?.text) })) };
+    }
+    return base;
+  });
+
+  if (errors.length) return { short: null, errors };
+  return {
+    short: { version: 1, pr: { owner: pr.owner, repo: pr.repo, number: pr.number }, title: text(raw.title), hook: text(raw.hook), scenes, outro: text(raw.outro) },
+    errors: [],
+  };
+}
+
+/** Problems that would make the video long or crowded on a phone screen. */
+export function checkShort(short, limits = SHORT_LIMITS) {
+  const errors = [];
+  const tooLong = (value, max, where) => {
+    if (value.length > max) errors.push(`${where} is ${value.length} characters; at most ${max}: "${value.slice(0, 24)}…"`);
+  };
+  const count = (n, min, max, where) => {
+    if (n < min || n > max) errors.push(`${where}: ${n}; use ${min}-${max}`);
+  };
+  count(short.scenes.length, limits.minScenes, limits.maxScenes, "scenes (the opening and closing cards come on top)");
+  tooLong(short.title, limits.titleChars, "title");
+  tooLong(short.hook, limits.sentenceChars, "hook");
+  tooLong(short.outro, limits.sentenceChars, "outro");
+  short.scenes.forEach((scene, i) => {
+    const where = `scenes[${i}] (${scene.kind})`;
+    tooLong(scene.headline, limits.headlineChars, `${where} headline`);
+    tooLong(scene.narration, limits.sentenceChars, `${where} narration`);
+    if (scene.kind === "flow") {
+      count(scene.steps.length, 2, 5, `${where} steps`);
+      scene.steps.forEach((step, s) => {
+        tooLong(step.label, limits.labelChars, `${where} steps[${s}].label`);
+        tooLong(step.detail, limits.detailChars, `${where} steps[${s}].detail`);
+      });
+      if (scene.links.length > scene.steps.length - 1) errors.push(`${where}: ${scene.links.length} links for ${scene.steps.length} steps; at most one between each pair`);
+      scene.links.forEach((link, l) => tooLong(link, limits.labelChars, `${where} links[${l}]`));
+    } else if (scene.kind === "compare") {
+      for (const name of ["before", "after"]) {
+        tooLong(scene[name].label, limits.labelChars, `${where} ${name}.label`);
+        count(scene[name].items.length, 1, 3, `${where} ${name}.items`);
+        scene[name].items.forEach((item, j) => tooLong(item, limits.itemChars, `${where} ${name}.items[${j}]`));
+      }
+    } else if (scene.kind === "structure") {
+      count(scene.groups.length, 1, 3, `${where} groups`);
+      count(scene.groups.reduce((n, g) => n + g.items.length, 0), 1, 8, `${where} items in all groups`);
+      scene.groups.forEach((group, g) => {
+        tooLong(group.label, limits.labelChars, `${where} groups[${g}].label`);
+        group.items.forEach((item, j) => tooLong(item.label, limits.labelChars, `${where} groups[${g}].items[${j}].label`));
+      });
+    } else if (scene.kind === "points") {
+      count(scene.points.length, 2, 3, `${where} points`);
+      scene.points.forEach((point, p) => tooLong(point.text, limits.pointChars, `${where} points[${p}]`));
+    }
+  });
+  return errors;
+}
+
+/** How many elements a scene reveals one at a time while its sentence is read. */
+export function revealSteps(scene) {
+  if (scene.kind === "flow") return scene.steps.length;
+  if (scene.kind === "compare") return 2;
+  if (scene.kind === "structure") return scene.groups.length;
+  if (scene.kind === "points") return scene.points.length;
+  return 1;
+}
+
+/** The short for [pr] among the code blocks of the PR's comments, or null (like findTourInBlocks). */
+export function findShortInBlocks(blocks, { owner, repo, number }) {
+  let found = null;
+  for (const text of blocks) {
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    const forThisPr = raw?.version === 1 && raw.pr?.owner === owner && raw.pr?.repo === repo && raw.pr?.number === number;
+    if (forThisPr && Array.isArray(raw.scenes) && typeof raw.hook === "string") found = raw;
+  }
+  return found;
+}

package/src/tour.js

@@ -17,6 +17,36 @@
 
 export const LEVELS = ["focus", "skim", "skip"];
 
+const SHA = /^[0-9a-f]{40}$/;
+
+/**
+ * The commits a tour was made for, when its generator recorded them: the PR's head commit and the
+ * diff's base (the merge base with the target branch). Written by the tools, never by Claude.
+ */
+function revisionOf(pr) {
+  return SHA.test(pr.head ?? "") ? { head: pr.head, ...(SHA.test(pr.base ?? "") ? { base: pr.base } : {}) } : {};
+}
+
+/**
+ * Whether a tour still matches the PR, given the PR's current { head, base, commits }:
+ * "current"; "added" (new commits on top); "rewritten" (force push, rebase, fixup: the tour's
+ * head is gone from the PR's commits); "base" (same commits against a different base, such as a
+ * retargeted PR); "unknown" (the tour doesn't say, or the PR couldn't be read).
+ * Commit ids cover all history below them, so an unchanged head means unchanged commits.
+ */
+export function tourFreshness(tourPr, current) {
+  if (!tourPr?.head || !current?.head) return "unknown";
+  if (tourPr.head !== current.head) return current.commits?.includes(tourPr.head) ? "added" : "rewritten";
+  return tourPr.base && current.base && tourPr.base !== current.base ? "base" : "current";
+}
+
+/** Of the tour made here and the one posted in the comments, the one to play: a current one first, then the local one. */
+export function pickTour(local, posted, current) {
+  const fresh = (raw) => raw && tourFreshness(raw.pr, current) === "current";
+  if (fresh(local) || !fresh(posted)) return local ?? posted;
+  return posted;
+}
+
 /** Validates and normalizes raw JSON. Returns { tour, errors }; tour is null when there are errors. */
 export function parseTour(raw) {
   const errors = [];
@@ -52,7 +82,7 @@ export function parseTour(raw) {
   return {
     tour: {
       version: 1,
-      pr: { owner: pr.owner, repo: pr.repo, number: pr.number },
+      pr: { owner: pr.owner, repo: pr.repo, number: pr.number, ...revisionOf(pr) },
       title: String(raw.title ?? ""),
       summary: String(raw.summary ?? ""),
       chapters,
@@ -155,14 +185,20 @@ export function findTourInBlocks(blocks, { owner, repo, number }) {
     } catch {
       continue;
     }
-    if (raw?.version === 1 && raw.pr?.owner === owner && raw.pr?.repo === repo && raw.pr?.number === number) found = raw;
+    const forThisPr = raw?.version === 1 && raw.pr?.owner === owner && raw.pr?.repo === repo && raw.pr?.number === number;
+    if (forThisPr && Array.isArray(raw.chapters)) found = raw; // a short in the same comment has scenes instead
   }
   return found;
 }
 
 /** "ko" when the tour's text has Hangul, otherwise "en": the language to narrate it in. */
 export function tourLanguage(tour) {
-  const text = [tour.title, tour.summary, ...flattenSteps(tour).flatMap((s) => [s.note, s.point])].join(" ");
+  const text = [
+    tour.title,
+    tour.summary,
+    ...tour.chapters.flatMap((c) => [c.title, c.summary]),
+    ...flattenSteps(tour).flatMap((s) => [s.note, s.point]),
+  ].join(" ");
   return /[가-힣]/.test(text) ? "ko" : "en";
 }