@erclx/canon 5.46.0 → 5.47.0

package/src/labels/density.ts

@@ -0,0 +1,363 @@
+import {
+  type DensityFinding,
+  type DensityKind,
+  densityFindings,
+} from '@/markdown/density'
+import { type BodyLine, bodyLines, visibleText } from '@/markdown/scan'
+import { CHECKPOINTS, LIST_ITEM } from '@/markdown/structure'
+
+/**
+ * The four counted limits a pull request section carries. The heading limits
+ * of `densityFindings()` are left out, since a body takes no subheading at all
+ * and `subheading` reports that once.
+ */
+const COUNTED = [
+  'paragraph-length',
+  'paragraph-run',
+  'bullet-length',
+  'bullet-run',
+] as const satisfies readonly DensityKind[]
+
+type CountedKind = (typeof COUNTED)[number]
+
+export type BodyDensityKind = CountedKind | 'subheading' | 'mixed-form'
+
+function isCounted(kind: DensityKind): kind is CountedKind {
+  return (COUNTED as readonly DensityKind[]).includes(kind)
+}
+
+export interface BodyDensityFinding {
+  /** The H2 the finding sits under, without its hashes, or null before the first. */
+  readonly section: string | null
+  readonly kind: BodyDensityKind
+  /** The line in the whole body, not in its section. */
+  readonly line: number
+  readonly value: number | null
+  readonly limit: number | null
+}
+
+const H2 = /^##\s+(.*?)\s*$/
+const SUBHEADING = /^(#{3,6})\s/
+const BOLD_ONLY = /^(\*\*|__)[^*_].*\1\s*$/
+const BOLD_LED = /^(\*\*|__)\S/
+
+interface Section {
+  readonly name: string | null
+  readonly lines: readonly BodyLine[]
+}
+
+/**
+ * Every density breach in a pull request body, graded per H2 section after
+ * the shape `claude/skills/git-pr/references/pr.md` states.
+ *
+ * `densityFindings()` stays the docs measure, so the PR exemptions live here
+ * as splits around it rather than as options on it. Testing takes no counted
+ * limit, since its checkboxes count as a bullet run. Key changes splits at
+ * each bold label alone on its own block, whatever its length, and Technical context
+ * at each bold-led paragraph, so a lead-in starts a new run. Technical
+ * context also reports mixing bullets with paragraphs.
+ */
+export function bodyDensity(body: string): BodyDensityFinding[] {
+  const found: BodyDensityFinding[] = []
+
+  for (const section of sectionsOf(bodyLines(body))) {
+    found.push(...subheadings(section))
+    if (section.name === 'Testing') continue
+
+    const chunks =
+      section.name === 'Key changes'
+        ? splitAt(section.lines, opensBlock(section.lines, BOLD_ONLY), true)
+        : section.name === 'Technical context'
+          ? splitAt(section.lines, opensBlock(section.lines, BOLD_LED), false)
+          : [section.lines]
+
+    for (const chunk of chunks) {
+      for (const finding of densityFindings(chunk)) {
+        const { kind } = finding
+        if (!isCounted(kind)) continue
+        found.push({ section: section.name, ...finding, kind })
+      }
+    }
+
+    if (section.name === 'Technical context') {
+      const mixed = mixedForm(section.lines)
+      if (mixed !== undefined) {
+        found.push({
+          section: section.name,
+          kind: 'mixed-form',
+          line: mixed,
+          value: null,
+          limit: null,
+        })
+      }
+    }
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}
+
+/**
+ * The opening headings of the posts a canon skill writes to a pull request,
+ * after `.canon/groundwork/170-github-comment-density/04-post-catalog.md`. A
+ * body opening on any other heading is not a post this reader grades.
+ */
+export const POST_HEADINGS = [
+  'Evidence',
+  'Review',
+  'Review closed',
+  'UI review',
+  'UI review closed',
+  'Review response',
+  'Post-review findings',
+  'Rebase',
+] as const
+
+export type PostDensityKind = CountedKind | 'heading-depth'
+
+export interface PostDensityFinding extends Omit<BodyDensityFinding, 'kind'> {
+  readonly kind: PostDensityKind
+}
+
+const LENGTHS: readonly DensityKind[] = ['paragraph-length', 'bullet-length']
+const NESTED_ITEM = /^(\s+)(?:[-*+]|\d+\.)\s+(.*)$/
+const CHECKBOX = /^\s*[-*+]\s+\[[ xX]\]/
+const FOOTER = /^🤖/
+
+/**
+ * Every density breach in a post a skill writes to a pull request, keyed on
+ * its opening H2, or none when that heading is not in `POST_HEADINGS`.
+ *
+ * A post allows H3s, which the UI review groups its verdicts under, so only a
+ * heading past H3 reports. The `🤖` footer and the marker never report, and a
+ * table never does. Inside `<details>` a block takes the length limits alone,
+ * since a reader opens it on purpose. A bold-led paragraph starts a new
+ * paragraph run, and a checklist box under `What to look at` takes no length
+ * limit, since a driver needs its route, action, and result.
+ *
+ * A nested item is measured as a bullet of its own, which `densityFindings()`
+ * leaves out of its parent, so a finding's subject and its evidence never sum.
+ */
+export function postDensity(body: string): PostDensityFinding[] {
+  const lines = bodyLines(body).map((line) =>
+    !line.fenced && FOOTER.test(line.text) ? { ...line, text: '' } : line,
+  )
+  if (!opensOnPostHeading(lines)) return []
+
+  const found: PostDensityFinding[] = []
+  const text = new Map(lines.map((line) => [line.number, line.text]))
+
+  for (const section of sectionsOf(lines)) {
+    const { outside, inside } = foldedApart(section.lines)
+    const measured = [
+      ...splitAt(outside, opensBlock(outside, BOLD_LED), false).flatMap(
+        (chunk) => densityFindings(chunk),
+      ),
+      ...densityFindings(inside).filter(({ kind }) => LENGTHS.includes(kind)),
+      ...nestedLengths(section.lines),
+    ]
+
+    for (const finding of measured) {
+      const { kind } = finding
+      if (!isCounted(kind) && kind !== 'heading-depth') continue
+      if (
+        section.name === 'What to look at' &&
+        kind === 'bullet-length' &&
+        CHECKBOX.test(text.get(finding.line) ?? '')
+      ) {
+        continue
+      }
+      found.push({ section: section.name, ...finding, kind })
+    }
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}
+
+/** Whether the body's first H2 outside a fence is one of `POST_HEADINGS`. */
+export function isPost(body: string): boolean {
+  return opensOnPostHeading(bodyLines(body))
+}
+
+function opensOnPostHeading(lines: readonly BodyLine[]): boolean {
+  const opening = lines.find((line) => !line.fenced && H2.test(line.text))
+  const heading = opening && H2.exec(opening.text)?.[1]
+  return (POST_HEADINGS as readonly string[]).includes(heading ?? '')
+}
+
+/**
+ * Parts a section into the lines outside `<details>` and the lines inside it.
+ * The tags stay outside, where each breaks a paragraph run as raw HTML does.
+ */
+function foldedApart(lines: readonly BodyLine[]): {
+  outside: BodyLine[]
+  inside: BodyLine[]
+} {
+  const outside: BodyLine[] = []
+  const inside: BodyLine[] = []
+  let depth = 0
+
+  for (const line of lines) {
+    const tag = line.fenced ? '' : line.text.trim()
+    if (tag.startsWith('<details')) {
+      depth++
+      outside.push(line)
+    } else if (tag.startsWith('</details')) {
+      depth = Math.max(0, depth - 1)
+      outside.push(line)
+    } else if (depth > 0) {
+      inside.push(line)
+    } else {
+      outside.push(line)
+    }
+  }
+
+  return { outside, inside }
+}
+
+/**
+ * A `bullet-length` finding for each nested item past the bullet limit, its
+ * length taken over the item and the lines indented under it that open no
+ * item of their own.
+ */
+function nestedLengths(lines: readonly BodyLine[]): DensityFinding[] {
+  const found: DensityFinding[] = []
+
+  for (const [index, line] of lines.entries()) {
+    const match = line.fenced ? null : NESTED_ITEM.exec(line.text)
+    if (!match) continue
+
+    const indent = match[1].length
+    const parts = [match[2].trim()]
+    for (const next of lines.slice(index + 1)) {
+      const lead = /^\s*/.exec(next.text)?.[0].length ?? 0
+      if (next.fenced || next.text.trim() === '' || lead <= indent) break
+      if (LIST_ITEM.test(next.text)) break
+      parts.push(next.text.trim())
+    }
+
+    const length = visibleText(parts.join(' ')).length
+    if (length > CHECKPOINTS.bullet) {
+      found.push({
+        kind: 'bullet-length',
+        line: line.number,
+        value: length,
+        limit: CHECKPOINTS.bullet,
+      })
+    }
+  }
+
+  return found
+}
+
+function sectionsOf(lines: readonly BodyLine[]): Section[] {
+  const sections: Section[] = []
+  let current: { name: string | null; lines: BodyLine[] } = {
+    name: null,
+    lines: [],
+  }
+
+  for (const line of lines) {
+    const heading = line.fenced ? null : H2.exec(line.text)
+    if (heading) {
+      sections.push(current)
+      current = { name: heading[1], lines: [] }
+    } else {
+      current.lines.push(line)
+    }
+  }
+  sections.push(current)
+
+  return sections.filter((section) => section.lines.length > 0)
+}
+
+function subheadings(section: Section): BodyDensityFinding[] {
+  return section.lines.flatMap((line) => {
+    const match = line.fenced ? null : SUBHEADING.exec(line.text)
+    if (!match) return []
+    return [
+      {
+        section: section.name,
+        kind: 'subheading' as const,
+        line: line.number,
+        value: match[1].length,
+        limit: 2,
+      },
+    ]
+  })
+}
+
+/**
+ * Cuts a section into chunks at each line the test picks, never inside a
+ * fence. `drop` leaves the picked line out of both chunks, as a bold label
+ * that only names the group below it.
+ */
+function splitAt(
+  lines: readonly BodyLine[],
+  breaks: (line: BodyLine, index: number) => boolean,
+  drop: boolean,
+): BodyLine[][] {
+  const chunks: BodyLine[][] = [[]]
+
+  for (const [index, line] of lines.entries()) {
+    if (!line.fenced && breaks(line, index)) {
+      chunks.push(drop ? [] : [line])
+    } else {
+      chunks[chunks.length - 1].push(line)
+    }
+  }
+
+  return chunks
+}
+
+/**
+ * Picks a line matching the pattern that opens a block, after a blank line or
+ * at the section start. A line directly under a bullet or a paragraph renders
+ * as its lazy continuation, so it breaks nothing.
+ */
+function opensBlock(
+  lines: readonly BodyLine[],
+  pattern: RegExp,
+): (line: BodyLine, index: number) => boolean {
+  return (line, index) =>
+    pattern.test(line.text) &&
+    (index === 0 || lines[index - 1].text.trim() === '')
+}
+
+/**
+ * The line of the first block of whichever form appears second, when a
+ * section carries both bullets and paragraphs, else undefined.
+ *
+ * A column-zero line directly under an item with no blank between is a lazy
+ * continuation of that item, not a paragraph.
+ */
+function mixedForm(lines: readonly BodyLine[]): number | undefined {
+  let firstItem: number | undefined
+  let firstParagraph: number | undefined
+  let previous: 'blank' | 'item' | 'paragraph' | 'other' = 'blank'
+
+  for (const line of lines) {
+    const text = line.text
+    if (line.fenced) {
+      previous = 'other'
+      continue
+    }
+    if (text.trim() === '') {
+      previous = 'blank'
+      continue
+    }
+    if (/^\s/.test(text)) continue
+
+    if (LIST_ITEM.test(text)) {
+      firstItem ??= line.number
+      previous = 'item'
+    } else if (/^(#|\||>|<)/.test(text)) {
+      previous = 'other'
+    } else if (previous === 'blank' || previous === 'other') {
+      firstParagraph ??= line.number
+      previous = 'paragraph'
+    }
+  }
+
+  if (firstItem === undefined || firstParagraph === undefined) return undefined
+  return Math.max(firstItem, firstParagraph)
+}

package/src/pr/evidence.ts

@@ -5,7 +5,7 @@ const EVIDENCE_SEGMENT = 'evidence'
 const EVIDENCE_OPEN_LIMIT = 6
 
 /** Length of the commit names the visible line shows, the width `git` abbreviates to. */
-const SHORT_SHA_LENGTH = 7
+export const SHORT_SHA_LENGTH = 7
 
 /** Prefix of the trailing marker this module writes and reads back. */
 const MARKER_PREFIX = '<!-- pr-evidence:'

package/src/pr/rest.ts

@@ -42,6 +42,7 @@ export interface PullIdentity {
   readonly head?: string
   readonly base?: string
   readonly mergeState?: string
+  readonly body?: string
 }
 
 export type BranchPull =
@@ -70,6 +71,7 @@ export function identityOf(row: RestPull): PullIdentity {
     ...(row.head?.sha !== undefined && { head: row.head.sha }),
     ...(row.base?.ref !== undefined && { base: row.base.ref }),
     ...(mergeState !== undefined && { mergeState }),
+    ...(typeof row.body === 'string' && { body: row.body }),
   }
 }
 

package/src/pr/tick.ts

@@ -3,9 +3,98 @@ import {
   CHECKLIST_START,
   parseBoxLine,
   readChecklistBoxes,
+  SHORT_SHA_LENGTH,
   writeBoxLine,
 } from '@/pr/evidence'
 
+const UI_PASS_MARKER = '<!-- pr-ui-pass -->'
+const TESTING_HEADING = /^## Testing\s*$/
+const SECTION_HEADING = /^## /
+const REVIEWER_HEADING = /^## For the reviewer\s*$/
+const UI_PASS_HEAD = /at `([0-9a-f]+)`/
+
+/** What the UI pass line reports, either a pass or a reset to a head nobody has driven. */
+export type UiPassSummary =
+  | {
+      readonly kind: 'passed'
+      /** Driven boxes ticked, taste boxes excluded. */
+      readonly passed: number
+      /** Boxes a driver can run, taste boxes excluded. */
+      readonly total: number
+      readonly taste: number
+      readonly head: string
+    }
+  | { readonly kind: 'reset'; readonly head: string }
+
+/**
+ * The one `## Testing` line a UI pass owns. It is ticked only when every box
+ * a driver can run passed, so a failed box never reads as done, and taste
+ * boxes are counted apart so a full pass never reads as one box failed.
+ */
+export function uiPassLine(summary: UiPassSummary): string {
+  const at = `\`${summary.head.slice(0, SHORT_SHA_LENGTH)}\``
+  if (summary.kind === 'reset') {
+    return `- [ ] UI pass, not run at ${at} ${UI_PASS_MARKER}`
+  }
+  const taste =
+    summary.taste === 0
+      ? ''
+      : `${summary.taste} taste ${summary.taste === 1 ? 'box' : 'boxes'} left to the operator`
+  if (summary.total === 0) {
+    return `- [ ] UI pass, no box a driver can run, ${taste} at ${at} ${UI_PASS_MARKER}`
+  }
+  const box = summary.passed === summary.total ? 'x' : ' '
+  const tail = taste === '' ? '' : `, ${taste}`
+  return `- [${box}] UI pass, ${summary.passed} of ${summary.total} boxes passed at ${at}${tail} ${UI_PASS_MARKER}`
+}
+
+/** The short sha the marked line names, absent when the body carries no such line. */
+export function readUiPassHead(body: string): string | undefined {
+  const line = body.split('\n').find((row) => row.includes(UI_PASS_MARKER))
+  return line === undefined ? undefined : UI_PASS_HEAD.exec(line)?.[1]
+}
+
+/**
+ * Puts the UI pass line in a pull request body and touches nothing else.
+ * The marked line is replaced where it stands, else appended to the end of
+ * `## Testing`, which is created ahead of `## For the reviewer` when absent.
+ */
+export function writeUiPassLine(body: string, summary: UiPassSummary): string {
+  const line = uiPassLine(summary)
+  const lines = body.split('\n')
+
+  const marked = lines.findIndex((row) => row.includes(UI_PASS_MARKER))
+  if (marked !== -1) {
+    lines[marked] = line
+    return lines.join('\n')
+  }
+
+  const heading = lines.findIndex((row) => TESTING_HEADING.test(row))
+  if (heading === -1) {
+    const reviewer = lines.findIndex((row) => REVIEWER_HEADING.test(row))
+    if (reviewer === -1) {
+      return `${body.trimEnd()}\n\n## Testing\n\n${line}\n`
+    }
+    lines.splice(reviewer, 0, '## Testing', '', line, '')
+    return lines.join('\n')
+  }
+
+  const next = lines.findIndex(
+    (row, index) => index > heading && SECTION_HEADING.test(row),
+  )
+  let last = next === -1 ? lines.length - 1 : next - 1
+  while (last > heading && lines[last]?.trim() === '') last -= 1
+
+  if (last > heading) {
+    lines.splice(last + 1, 0, line)
+  } else if (lines[heading + 1] === '') {
+    lines.splice(heading + 2, 0, line)
+  } else {
+    lines.splice(heading + 1, 0, '', line)
+  }
+  return lines.join('\n')
+}
+
 export type TickRefusal = 'no-checklist' | 'no-box' | 'taste-box'
 
 export type TickResult =

package/src/sessions/live.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readlinkSync } from 'node:fs'
+import { createConnection } from 'node:net'
 import type { SessionRecord } from '@/sessions/registry'
 
 /**
@@ -35,6 +36,12 @@ export interface LivenessProbes {
   readonly ownDomain?: () => string | null
   /** Whether the messaging socket a foreign record names still exists. */
   readonly socketExists?: (path: string) => boolean
+  /**
+   * Whether something accepts a connection on the socket within the timeout.
+   * Async, so `liveness()` never calls it and a caller with no use for it, such
+   * as the gate's lock, states nothing.
+   */
+  readonly listens?: (path: string, timeoutMs: number) => Promise<boolean>
 }
 
 /**
@@ -74,11 +81,30 @@ function ownDomain(): string | null {
   }
 }
 
+/**
+ * Connects and closes without writing, so the peer sees no bytes. The socket is
+ * destroyed on connect rather than waited on, since a listener that accepts and
+ * never closes would otherwise hold the probe open past its timeout.
+ */
+function listens(path: string, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection(path)
+    const settle = (accepted: boolean): void => {
+      socket.destroy()
+      resolve(accepted)
+    }
+    socket.setTimeout(timeoutMs, () => settle(false))
+    socket.once('connect', () => settle(true))
+    socket.once('error', () => settle(false))
+  })
+}
+
 export const SYSTEM_PROBES: LivenessProbes = {
   procStartOf,
   responds,
   ownDomain,
   socketExists: existsSync,
+  listens,
 }
 
 /**

package/src/sessions/resolve.ts

@@ -23,11 +23,18 @@ export interface ResolvedSession {
   readonly kind: string
   readonly status: string
   /**
-   * What decided the row was live. `socket` means the record belongs to another
-   * pid namespace and only its messaging socket answered, so the row can be a
-   * crashed session's leftover and no start time backs it.
+   * What decided the row was live. `pid` is a start time matched or a pid that
+   * answered, `socket` means the record belongs to another pid namespace and
+   * only its messaging socket file existed, so the row can be a crashed
+   * session's leftover, and `listener` means the messaging socket accepted a
+   * connection, which confirms the row wherever the start time cannot be read.
    */
-  readonly via: 'pid' | 'socket'
+  readonly via: 'pid' | 'socket' | 'listener'
+  /**
+   * How this row alone was decided, so a caller scoping the roster derives its
+   * confidence over the rows it keeps rather than over the whole machine.
+   */
+  readonly confidence: Confidence
   readonly startedAt: string | null
   /**
    * The stamp the record carries beside `status`, kept alongside the dwell it
@@ -80,6 +87,22 @@ export type SessionReport =
       readonly sessions: readonly ResolvedSession[]
     }
 
+/**
+ * The weakest confidence among the rows, so one read tells a caller whether
+ * every row it holds is an identity. A caller scoping the roster calls this on
+ * the rows it keeps, since one unrelated row it dropped must not weaken it.
+ */
+export function confidenceOf(
+  sessions: readonly Pick<ResolvedSession, 'confidence'>[],
+): Confidence {
+  return sessions.every((session) => session.confidence === 'confirmed')
+    ? 'confirmed'
+    : 'unverified'
+}
+
+/** A live socket here accepted in 2 ms, and every probe runs in parallel. */
+const LISTEN_TIMEOUT_MS = 250
+
 export interface ResolveOptions {
   readonly dir?: string
   readonly probes?: LivenessProbes
@@ -181,6 +204,7 @@ function present(
   located: Located,
   now: number,
   via: ResolvedSession['via'],
+  confidence: Confidence,
 ): ResolvedSession {
   return {
     name: record.name,
@@ -190,6 +214,7 @@ function present(
     kind: record.kind ?? 'unknown',
     status: record.status ?? 'unknown',
     via,
+    confidence,
     startedAt:
       record.startedAt === undefined
         ? null
@@ -228,8 +253,11 @@ export async function resolveSessions(
 
   if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
 
-  const live: { record: SessionRecord; via: ResolvedSession['via'] }[] = []
-  let confidence: Confidence = 'confirmed'
+  const live: {
+    record: SessionRecord
+    via: ResolvedSession['via']
+    confidence: Confidence
+  }[] = []
   let foreignDead = 0
 
   for (const record of registry.records) {
@@ -238,20 +266,43 @@ export async function resolveSessions(
       if (state.foreign) foreignDead += 1
       continue
     }
-    if (state.confidence === 'unverified') confidence = 'unverified'
-    live.push({ record, via: state.foreign ? 'socket' : 'pid' })
+    live.push({
+      record,
+      via: state.foreign ? 'socket' : 'pid',
+      confidence: state.confidence,
+    })
   }
 
+  // Only a row the start time left unverified is probed, so a machine that reads
+  // /proc pays nothing. An accept proves the session is running where a pid
+  // answering or a socket file existing does not.
+  const upgraded = await Promise.all(
+    live.map(async (row) => {
+      const socket = row.record.messagingSocketPath
+      if (
+        row.confidence === 'confirmed' ||
+        socket === undefined ||
+        probes.listens === undefined
+      ) {
+        return row
+      }
+      const accepted = await probes.listens(socket, LISTEN_TIMEOUT_MS)
+      return accepted
+        ? { ...row, via: 'listener' as const, confidence: 'confirmed' as const }
+        : row
+    }),
+  )
+
   const sessions = await Promise.all(
-    live.map(async ({ record, via }) =>
-      present(record, await find(record.cwd), now, via),
+    upgraded.map(async ({ record, via, confidence }) =>
+      present(record, await find(record.cwd), now, via, confidence),
     ),
   )
 
   return {
     kind: 'resolved',
     dir: registry.dir,
-    confidence,
+    confidence: confidenceOf(sessions),
     foreignDead,
     sessions,
   }