@erclx/canon 4.74.0 → 4.75.0

package/src/commands/pr.ts

@@ -20,6 +20,11 @@ import {
   treeRoots,
 } from '@/pr/bijection'
 import { type CheckRunListing, collapseChecks } from '@/pr/checks'
+import {
+  findEvidenceCommentId,
+  groupEvidence,
+  renderEvidenceBody,
+} from '@/pr/evidence'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import { KEY_CHANGES } from '@/pr/paths'
 import { type ReviewListing, resolveReviewScope } from '@/pr/review-scope'
@@ -81,6 +86,27 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
     'The reviews on this pull request could not be read. An empty answer here would report a reviewed pull request as never reviewed, which routes the next pass to the whole change, so nothing is reported.',
 }
 
+/**
+ * Why `canon pr evidence` produced no comment body, past the ones
+ * `readIdentity` already owns (`gh-missing`, `gh-failed`, `no-branch`) and the
+ * one `identity.head` owns (`no-object-head`).
+ */
+type EvidenceRefusal =
+  | 'gh-failed'
+  | 'no-base'
+  | 'unreadable-tree'
+  | 'unreadable-changes'
+
+const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
+  'gh-failed':
+    'gh could not answer for this repository. Name the pull request number.',
+  'no-base': 'No base resolves against the trunk. Fetch origin and re-run.',
+  'unreadable-tree':
+    'git could not read the tree at the base commit, so no path could be judged added or changed.',
+  'unreadable-changes':
+    'git could not list what this branch changed, so the set is unknown.',
+}
+
 /** Why the read produced no comparison, ahead of the ones the compare owns. */
 type SourceRefusal =
   | 'gh-missing'
@@ -289,6 +315,46 @@ export function register(program: Command): void {
     .action(async (number: string | undefined, opts: ReadOptions) => {
       process.exitCode = await runReviewState(number, opts)
     })
+
+  pr.command('evidence')
+    .description(
+      "Render a before/after comparison for the pull request's changed evidence images",
+    )
+    .argument('[number]', 'Pull request to read, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Compares the merge base with the trunk against the current head, never',
+        'the previous push against the new one, so the comment never claims more',
+        'than the branch currently shows. A path counts as evidence when one of',
+        'its segments is literally `evidence` and the filename carries an image',
+        'extension (png, jpg, jpeg, gif, webp, avif, svg). A README, a capture',
+        'script, or a raw data file kept beside the images is left out rather',
+        'than rendered as a broken embed.',
+        '',
+        'Read `reason` on the JSON record before posting anything:',
+        '  ok           a body was rendered, with `commentId` set when a marked',
+        '               comment already exists and should be edited in place',
+        '  no-evidence  nothing in the diff carries an evidence/ segment, which',
+        '               is an ordinary, silent no-op rather than a refusal',
+        '',
+        'Exit codes:',
+        '  0  read, whether it produced a body or reported no-evidence',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr evidence --json',
+        '  canon pr evidence 1341 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: ReadOptions) => {
+      process.exitCode = await runEvidence(number, opts)
+    })
 }
 
 interface PullRequestRead {
@@ -1019,6 +1085,160 @@ async function runReviewState(
   return 0
 }
 
+/**
+ * Every path `git ls-tree` reports for `ref`, or undefined when the read
+ * failed. One call for the whole tree rather than one `cat-file -e` per
+ * evidence path, since existence at base is checked once per changed path and
+ * a batch read is one round trip instead of many.
+ */
+async function listTreePaths(
+  root: string,
+  ref: string,
+): Promise<Set<string> | undefined> {
+  const result = await $`git -C ${root} ls-tree -r --name-only ${ref}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return undefined
+  return new Set(result.text().split('\n').filter(Boolean))
+}
+
+async function runEvidence(
+  number: string | undefined,
+  opts: ReadOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr evidence')
+
+  const read = await readIdentity(root, number)
+  if (read.kind === 'refused') {
+    return refuseWith(read.reason, PULL_REFUSALS[read.reason], emitJson, root)
+  }
+
+  const { identity } = read
+  if (identity.head === undefined) {
+    return refuseWith(
+      'no-object-head',
+      PULL_REFUSALS['no-object-head'],
+      emitJson,
+      root,
+    )
+  }
+
+  const base = await resolveBaseRef(root)
+  if (base === undefined) {
+    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
+  }
+
+  const [changed, baseTree] = await Promise.all([
+    listChangedFiles(root, base),
+    listTreePaths(root, base),
+  ])
+  if (changed === undefined) {
+    return refuseWith(
+      'unreadable-changes',
+      EVIDENCE_REFUSALS['unreadable-changes'],
+      emitJson,
+      root,
+    )
+  }
+  if (baseTree === undefined) {
+    return refuseWith(
+      'unreadable-tree',
+      EVIDENCE_REFUSALS['unreadable-tree'],
+      emitJson,
+      root,
+    )
+  }
+
+  const grouped = await groupEvidence(changed, async (path) =>
+    baseTree.has(path),
+  )
+
+  if (grouped.kind === 'refused') {
+    logStep('Skipped')
+    logInfo(
+      'No changed path carries an evidence/ segment, so there is nothing to post.',
+    )
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          ...(identity.number !== undefined && { number: identity.number }),
+          reason: 'no-evidence',
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  const repoRow = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
+  const repo =
+    repoRow === null
+      ? undefined
+      : (JSON.parse(repoRow) as { nameWithOwner?: string }).nameWithOwner
+
+  if (repo === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+
+  const body = renderEvidenceBody(grouped.states, repo, base, identity.head)
+
+  let commentId: number | undefined
+  if (identity.number !== undefined) {
+    const commentsRow = await gh(root, [
+      'pr',
+      'view',
+      String(identity.number),
+      '--json',
+      'comments',
+    ])
+    if (commentsRow !== null) {
+      try {
+        const parsed = JSON.parse(commentsRow) as {
+          comments?: readonly { url?: string; body: string }[]
+        }
+        commentId = findEvidenceCommentId(parsed.comments ?? [])
+      } catch {
+        commentId = undefined
+      }
+    }
+  }
+
+  const caseCount = grouped.states.reduce((n, s) => n + s.items.length, 0)
+
+  logStep('Scope')
+  logInfo(
+    `${plural(caseCount, 'case')} across ${plural(grouped.states.length, 'state')}`,
+  )
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(identity.number !== undefined && { number: identity.number }),
+        reason: 'ok',
+        base,
+        head: identity.head,
+        body,
+        ...(commentId !== undefined && { commentId }),
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command

package/src/design/base.css

@@ -136,3 +136,62 @@
 *::-webkit-scrollbar-corner {
   background: transparent;
 }
+
+/* hand-drawn-figure
+   The hand-drawn SVG diagram figure and its caption, sized wider than the
+   reading measure and cleared past an outline rail on a wide viewport. */
+
+/* ---- Figures: hand-drawn, and wider than the measure ---- */
+
+:root {
+  --figure-hand: 'Virgil', 'Excalifont', cursive;
+  --figure-wide: 64rem;
+}
+
+figure {
+  margin: 2.75rem 0;
+  width: var(--figure-wide);
+  max-width: 92vw;
+  margin-left: 50%;
+  transform: translateX(-50%);
+}
+
+figure svg {
+  width: 100%;
+  height: auto;
+  display: block;
+}
+
+/* CSS beats an SVG presentation attribute, so the diagrams pick up the
+   hand face without editing a single lesson. */
+figure svg text {
+  font-family: var(--figure-hand);
+}
+
+figcaption {
+  font-family: var(--figure-hand);
+  font-size: 1rem;
+  color: var(--color-muted);
+  margin: 1rem auto 0;
+  line-height: 1.5;
+  max-width: 52rem;
+}
+
+/* A figure breaks the measure and must still clear an outline rail. Deriving
+   the ceiling from the viewport does not hold, since a rail positioned from
+   the centre keeps overlapping as the window widens, so the ceiling is fixed
+   instead. */
+@media (min-width: 1421px) {
+  figure {
+    max-width: 54rem;
+  }
+}
+
+@media (max-width: 640px) {
+  figure {
+    width: 100%;
+    max-width: 100%;
+    margin-left: 0;
+    transform: none;
+  }
+}

package/src/design/components.ts

@@ -119,7 +119,86 @@ const SCROLLBAR: Component = {
 }`,
 }
 
-export const COMPONENTS: readonly Component[] = [STATUS, SCROLLBAR]
+/**
+ * The hand-drawn SVG diagram figure and its caption, sized wider than the
+ * reading measure and cleared past an outline rail on a wide viewport.
+ * Promoted out of `TEACH_COMPONENTS` per
+ * `.canon/groundwork/86-portable-hand-drawn-figures/06-decision.md` item 4:
+ * any project can draw one hand-drawn-styled figure without teach's own quiz
+ * and schedule machinery. It could not move as `TEACH_FIGURES` as-is, since
+ * that component's `reads` list named `--teach-hand` and `--teach-wide`
+ * while only `TEACH_CHROME` declared them, so this component declares its
+ * own `--figure-hand` and `--figure-wide` defaults rather than borrowing
+ * undeclared custom properties from a teach-only sibling.
+ */
+const HAND_DRAWN_FIGURE: Component = {
+  name: 'hand-drawn-figure',
+  note: [
+    'The hand-drawn SVG diagram figure and its caption, sized wider than the',
+    'reading measure and cleared past an outline rail on a wide viewport.',
+  ].join('\n   '),
+  reads: ['--color-muted', '--figure-hand', '--figure-wide'],
+  rules: `/* ---- Figures: hand-drawn, and wider than the measure ---- */
+
+:root {
+  --figure-hand: 'Virgil', 'Excalifont', cursive;
+  --figure-wide: 64rem;
+}
+
+figure {
+  margin: 2.75rem 0;
+  width: var(--figure-wide);
+  max-width: 92vw;
+  margin-left: 50%;
+  transform: translateX(-50%);
+}
+
+figure svg {
+  width: 100%;
+  height: auto;
+  display: block;
+}
+
+/* CSS beats an SVG presentation attribute, so the diagrams pick up the
+   hand face without editing a single lesson. */
+figure svg text {
+  font-family: var(--figure-hand);
+}
+
+figcaption {
+  font-family: var(--figure-hand);
+  font-size: 1rem;
+  color: var(--color-muted);
+  margin: 1rem auto 0;
+  line-height: 1.5;
+  max-width: 52rem;
+}
+
+/* A figure breaks the measure and must still clear an outline rail. Deriving
+   the ceiling from the viewport does not hold, since a rail positioned from
+   the centre keeps overlapping as the window widens, so the ceiling is fixed
+   instead. */
+@media (min-width: 1421px) {
+  figure {
+    max-width: 54rem;
+  }
+}
+
+@media (max-width: 640px) {
+  figure {
+    width: 100%;
+    max-width: 100%;
+    margin-left: 0;
+    transform: none;
+  }
+}`,
+}
+
+export const COMPONENTS: readonly Component[] = [
+  STATUS,
+  SCROLLBAR,
+  HAND_DRAWN_FIGURE,
+]
 
 const TEACH_CHROME: Component = {
   name: 'teach-chrome',
@@ -153,7 +232,6 @@ const TEACH_CHROME: Component = {
   --teach-mono: 'Cascadia Code', ui-monospace, monospace;
   --teach-measure: 52rem;
   --teach-chrome: 52rem;
-  --teach-wide: 64rem;
   --teach-mast-h: 4.4rem;
   --teach-shadow: 0 1px 2px rgba(20, 20, 20, 0.04);
   --color-teach-accent-bg: color-mix(in srgb, var(--color-accent) 14%, var(--color-background));
@@ -1126,53 +1204,6 @@ const TEACH_OUTLINE: Component = {
 @media (max-width: 1420px) { .outline { display: none; } }`,
 }
 
-const TEACH_FIGURES: Component = {
-  name: 'teach-figures',
-  note: [
-    'The hand-drawn SVG diagram figure and its caption, sized wider than the',
-    'reading measure and cleared past the outline rail on a wide viewport.',
-  ].join('\n   '),
-  reads: ['--color-muted', '--teach-hand', '--teach-measure', '--teach-wide'],
-  rules: `/* ---- Figures: hand-drawn, and wider than the measure ---- */
-
-figure {
-  margin: 2.75rem 0;
-  width: var(--teach-wide);
-  max-width: 92vw;
-  margin-left: 50%;
-  transform: translateX(-50%);
-}
-
-figure svg { width: 100%; height: auto; display: block; }
-
-/* CSS beats an SVG presentation attribute, so the diagrams pick up the
-   hand face without editing a single lesson. */
-figure svg text { font-family: var(--teach-hand); }
-
-figcaption {
-  font-family: var(--teach-hand);
-  font-size: 1rem;
-  color: var(--color-muted);
-  margin: 1rem auto 0;
-  line-height: 1.5;
-  max-width: var(--teach-measure);
-}
-
-/* A figure breaks the measure and must still clear the outline rail. The rail
-   starts at \`50% + 26rem + 2.5rem\`, so a figure centred on the same axis may
-   reach 27rem from centre and no further, which is 54rem wide with a 1.5rem
-   gap left over. Deriving it from the viewport was the earlier attempt and it
-   does not hold: the rail is positioned from the centre, not from the edge, so
-   a wider window moved both and kept the overlap. */
-@media (min-width: 1421px) {
-  figure { max-width: 54rem; }
-}
-
-@media (max-width: 640px) {
-  figure { width: 100%; max-width: 100%; margin-left: 0; transform: none; }
-}`,
-}
-
 const TEACH_REFERENCES: Component = {
   name: 'teach-references',
   note: [
@@ -1269,7 +1300,6 @@ export const TEACH_COMPONENTS: readonly Component[] = [
   TEACH_QUIZ,
   TEACH_GLOSSARY,
   TEACH_OUTLINE,
-  TEACH_FIGURES,
   TEACH_REFERENCES,
 ]