@erclx/canon 5.37.0 → 5.39.0

package/src/markdown/density.ts

@@ -0,0 +1,258 @@
+import { type BodyLine, visibleText } from '@/markdown/scan'
+import { bulletStacks, CAP } from '@/markdown/stacks'
+import {
+  BLOCKQUOTE,
+  CHECKPOINTS,
+  HEADING,
+  isSectionMarker,
+  LIST_ITEM,
+  TABLE_ROW,
+} from '@/markdown/structure'
+
+/** The most prose paragraphs one stretch may carry before a list, table, or heading breaks it. */
+export const PARAGRAPH_RUN = 2
+
+/** The deepest heading level a document may use. */
+export const HEADING_DEPTH = 3
+
+export type DensityKind =
+  | 'paragraph-length'
+  | 'paragraph-run'
+  | 'bullet-length'
+  | 'bullet-run'
+  | 'heading-depth'
+  | 'h3-opening'
+
+export interface DensityFinding {
+  readonly kind: DensityKind
+  /** The line of the block that breaches, or of a run's first block. */
+  readonly line: number
+  /** What was measured, or null for the H3 opening, which is a shape rather than a count. */
+  readonly value: number | null
+  readonly limit: number | null
+}
+
+/**
+ * A block as a reader meets it. `other` is everything that is neither prose,
+ * a list item, nor a heading, being a table, a fence, a blockquote, a section
+ * marker, and raw HTML, and each one breaks a paragraph run.
+ */
+type Block =
+  | { readonly kind: 'heading'; readonly line: number; readonly level: number }
+  | { readonly kind: 'paragraph'; readonly line: number; readonly text: string }
+  | { readonly kind: 'item'; readonly line: number; readonly text: string }
+  | { readonly kind: 'other'; readonly line: number; readonly table: boolean }
+
+/**
+ * Splits the body into the blocks the six limits read.
+ *
+ * Its own walk rather than `paragraphBlocks` in `src/markdown/structure.ts`,
+ * because the two disagree on one construct and the disagreement is the point.
+ * That walk reads an indented paragraph under a list item as a paragraph, and
+ * here it belongs to the item: it counts toward the bullet's length and never
+ * toward a paragraph run, since a reader sees it inside the list.
+ *
+ * A nested item is left out of its parent, as `heavyBullets` leaves it, and so
+ * is everything indented under the nested item. An indented fence inside an
+ * item stays with the item, and a column-zero one ends it.
+ */
+function blocksOf(lines: readonly BodyLine[]): Block[] {
+  const blocks: Block[] = []
+  let paragraph: { line: number; parts: string[] } | undefined
+  let item: { line: number; parts: string[]; nested: boolean } | undefined
+  let inFence = false
+  let afterBlank = false
+
+  const closeParagraph = (): void => {
+    if (paragraph) {
+      blocks.push({
+        kind: 'paragraph',
+        line: paragraph.line,
+        text: paragraph.parts.join(' '),
+      })
+    }
+    paragraph = undefined
+  }
+
+  const closeItem = (): void => {
+    if (item) {
+      blocks.push({ kind: 'item', line: item.line, text: item.parts.join(' ') })
+    }
+    item = undefined
+  }
+
+  const closeAll = (): void => {
+    closeParagraph()
+    closeItem()
+  }
+
+  for (const line of lines) {
+    const raw = line.text
+    const text = raw.trim()
+    const indented = /^\s/.test(raw)
+
+    if (line.fenced) {
+      // The opening delimiter decides who owns the block. `bodyLines` marks a
+      // delimiter and the body alike, so the opener is the first fenced line.
+      if (!inFence) {
+        if (!(item && indented)) {
+          closeAll()
+          blocks.push({ kind: 'other', line: line.number, table: false })
+        }
+      }
+      inFence = true
+      afterBlank = false
+      continue
+    }
+    inFence = false
+
+    if (text === '') {
+      closeParagraph()
+      afterBlank = true
+      continue
+    }
+
+    if (indented && item) {
+      if (LIST_ITEM.test(raw)) item.nested = true
+      else if (!item.nested && !TABLE_ROW.test(raw)) item.parts.push(text)
+      afterBlank = false
+      continue
+    }
+
+    if (HEADING.test(raw)) {
+      closeAll()
+      blocks.push({
+        kind: 'heading',
+        line: line.number,
+        level: (raw.match(/^#+/)?.[0] ?? '').length,
+      })
+    } else if (!indented && LIST_ITEM.test(raw)) {
+      closeAll()
+      item = {
+        line: line.number,
+        parts: [text.replace(LIST_ITEM, '')],
+        nested: false,
+      }
+    } else if (
+      TABLE_ROW.test(raw) ||
+      BLOCKQUOTE.test(raw) ||
+      isSectionMarker(raw) ||
+      text.startsWith('<')
+    ) {
+      closeAll()
+      blocks.push({
+        kind: 'other',
+        line: line.number,
+        table: TABLE_ROW.test(raw),
+      })
+    } else if (paragraph) {
+      paragraph.parts.push(text)
+    } else if (item && !afterBlank) {
+      // A lazy continuation, which renders inside the item above it.
+      item.parts.push(text)
+    } else {
+      closeItem()
+      paragraph = { line: line.number, parts: [text] }
+    }
+
+    afterBlank = false
+  }
+
+  closeAll()
+
+  return blocks
+}
+
+/**
+ * Every breach of the six density limits, in line order.
+ *
+ * Each limit is a count rather than a judgment, so a finding is a fact a scan
+ * settles and the caller decides whether it gates. The limits are a 350-character
+ * paragraph, 2 paragraphs in a row, a 200-character bullet, 5 plain bullets in
+ * a row, no heading past H3, and a paragraph or a table as the first block
+ * under every H3. The two length numbers are `CHECKPOINTS`, so the advisory
+ * Bullets and Paragraphs sections and this measure read one number, and the
+ * bullet run is `bulletStacks`, so a bold-labeled run stays exempt here too.
+ */
+export function densityFindings(lines: readonly BodyLine[]): DensityFinding[] {
+  const found: DensityFinding[] = []
+  const blocks = blocksOf(lines)
+  let run: { line: number; count: number } | undefined
+
+  const closeRun = (): void => {
+    if (run && run.count > PARAGRAPH_RUN) {
+      found.push({
+        kind: 'paragraph-run',
+        line: run.line,
+        value: run.count,
+        limit: PARAGRAPH_RUN,
+      })
+    }
+    run = undefined
+  }
+
+  for (const [index, block] of blocks.entries()) {
+    if (block.kind !== 'paragraph') closeRun()
+
+    if (block.kind === 'paragraph') {
+      run ??= { line: block.line, count: 0 }
+      run.count++
+      const length = visibleText(block.text).length
+      if (length > CHECKPOINTS.paragraph) {
+        found.push({
+          kind: 'paragraph-length',
+          line: block.line,
+          value: length,
+          limit: CHECKPOINTS.paragraph,
+        })
+      }
+    } else if (block.kind === 'item') {
+      const length = visibleText(block.text).length
+      if (length > CHECKPOINTS.bullet) {
+        found.push({
+          kind: 'bullet-length',
+          line: block.line,
+          value: length,
+          limit: CHECKPOINTS.bullet,
+        })
+      }
+    } else if (block.kind === 'heading') {
+      if (block.level > HEADING_DEPTH) {
+        found.push({
+          kind: 'heading-depth',
+          line: block.line,
+          value: block.level,
+          limit: HEADING_DEPTH,
+        })
+      }
+      if (block.level === 3 && !opensWithLead(blocks[index + 1])) {
+        found.push({
+          kind: 'h3-opening',
+          line: block.line,
+          value: null,
+          limit: null,
+        })
+      }
+    }
+  }
+
+  closeRun()
+
+  for (const stack of bulletStacks(lines)) {
+    found.push({
+      kind: 'bullet-run',
+      line: stack.line,
+      value: stack.count,
+      limit: CAP,
+    })
+  }
+
+  return found.sort((a, b) => a.line - b.line)
+}
+
+/** Whether the block under an H3 is the paragraph or table the limit asks for. */
+function opensWithLead(next: Block | undefined): boolean {
+  if (next === undefined) return false
+  if (next.kind === 'paragraph') return true
+  return next.kind === 'other' && next.table
+}

package/src/markdown/gate.ts

@@ -1,10 +1,20 @@
 import type { ColonFinding } from '@/markdown/colons'
+import type { DensityFinding } from '@/markdown/density'
 import type { HeadingCaseFinding } from '@/markdown/heading-case'
 import type { LinkFinding } from '@/markdown/links'
+import type { ReferenceShapeFinding } from '@/markdown/reference-shape'
 import type { BanFinding } from '@/markdown/scan'
-import type { StackFinding } from '@/markdown/stacks'
+import { GATED_PATHS } from '@/markdown/scope'
 import type { StructureReport } from '@/markdown/structure'
 
+export interface GatedDensityFinding extends DensityFinding {
+  readonly gating: boolean
+}
+
+export interface GatedReferenceShapeFinding extends ReferenceShapeFinding {
+  readonly gating: boolean
+}
+
 export interface GateInput {
   /** Every ban hit across every file measured, flattened. */
   readonly bans: readonly BanFinding[]
@@ -13,10 +23,11 @@ export interface GateInput {
   /**
    * Every structural measure the run made, read by nothing here.
    *
-   * Naming it is what makes the split checkable: bullet, paragraph, and depth
-   * weight are judgments a reader settles, and a push failing on one teaches a
-   * contributor to route around the stage. A signature taking the ban list
-   * alone states the same rule and leaves no place to assert it.
+   * Naming it is what makes the split checkable: depth weight, cadence, and the
+   * sentence count are judgments a reader settles, and a push failing on one
+   * teaches a contributor to route around the stage. The bullet and paragraph
+   * weight a reader settles here are the advisory half, and the same numbers
+   * gate through `density` below, which knows the path each one sits on.
    */
   readonly structure: readonly StructureReport[]
   /**
@@ -33,25 +44,53 @@ export interface GateInput {
    */
   readonly headingCase: readonly HeadingCaseFinding[]
   /**
-   * Every run of plain bullets past the cap, read by nothing here.
+   * Every density finding, each marked with whether its path gates.
    *
-   * The stage that gates it is `bullet-stacks` in `src/gate/stages.ts`, which
-   * reads a scope of tracked files. This audit also runs on plans and
-   * groundwork records kept out of version control, where a long list is not
-   * a defect, which is the reason `documentCeiling` gates apart from it too.
+   * The mark is decided by the caller from `src/markdown/scope.ts`, since only
+   * the caller knows the path and whether the tree is a canon checkout. A plan,
+   * a groundwork record, and a rule carry no density finding at all, and an
+   * in-scope path under no gated prefix carries one marked `gating: false`.
+   */
+  readonly density: readonly GatedDensityFinding[]
+  /**
+   * Every reference shape finding, each marked with whether its path gates.
+   * Only a page whose frontmatter carries `kind: reference` has any.
    */
-  readonly bulletStacks: readonly StackFinding[]
+  readonly referenceShape: readonly GatedReferenceShapeFinding[]
 }
 
 /**
  * Whether the audit found something that should fail the caller.
  *
- * A banned character and a relative link resolving to
- * nothing on disk are both facts rather than a threshold, so either gates
- * unconditionally and there is no widened mode to reach for. The standards
- * decide what counts as banned, which keeps this answering how many rather
- * than which.
+ * A banned character and a relative link resolving to nothing on disk are both
+ * facts rather than a threshold, so either gates unconditionally and there is
+ * no widened mode to reach for. A density finding is a fact too, a count
+ * against a fixed number, and it gates wherever the caller marked its path as
+ * gated, and so does a reference shape finding. The standards decide what
+ * counts as banned, which keeps this answering how many rather than which.
+ */
+export function isGating({
+  bans,
+  links,
+  density,
+  referenceShape,
+}: GateInput): boolean {
+  return (
+    bans.length > 0 ||
+    links.length > 0 ||
+    density.some((finding) => finding.gating) ||
+    referenceShape.some((finding) => finding.gating)
+  )
+}
+
+/**
+ * Whether a reference shape finding on this path fails the run, under the
+ * prefixes density gates on. A page is opted in by its own marker, so the
+ * density scope and the always-gated bullet run have nothing to add here.
  */
-export function isGating({ bans, links }: GateInput): boolean {
-  return bans.length > 0 || links.length > 0
+export function referenceShapeGates(
+  rel: string,
+  gated: readonly string[] = GATED_PATHS,
+): boolean {
+  return gated.some((prefix) => rel.startsWith(prefix))
 }

package/src/markdown/reference-shape.ts

@@ -0,0 +1,103 @@
+import { bodyLines } from '@/markdown/scan'
+import { TABLE_ROW } from '@/markdown/structure'
+
+/** The H2 sections a reference page may hold below its opening. */
+export const REFERENCE_SECTIONS: readonly string[] = [
+  'Output',
+  'Refusals',
+  'See also',
+]
+
+export type ReferenceShapeKind =
+  | 'extra-section'
+  | 'section-order'
+  | 'subsection'
+  | 'flag-table'
+
+export interface ReferenceShapeFinding {
+  readonly kind: ReferenceShapeKind
+  readonly line: number
+  /** The heading text, or the first header cell of a flag table. */
+  readonly text: string
+}
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/
+const MARKER = /^kind:\s*(["']?)reference\1\s*$/m
+const HEADING = /^(#{2,3})\s+(.*?)(?:\s+#+)?\s*$/
+const SEPARATOR_ROW = /^\s*\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*$/
+
+/**
+ * A first header cell naming flags or options, read with its code span and
+ * emphasis stripped. Only the first column is read, so a refusal table headed
+ * `Reason` stays out of reach whatever its later columns say.
+ */
+const FLAG_HEADER = /^(?:flags?|options?)$/i
+
+/** Whether the page's frontmatter opts it into the reference shape. */
+export function isReferencePage(source: string): boolean {
+  const frontmatter = FRONTMATTER.exec(source)
+  return frontmatter !== null && MARKER.test(frontmatter[1])
+}
+
+/**
+ * Every breach of the reference shape on a page marked `kind: reference`, in
+ * line order, and nothing on an unmarked page.
+ *
+ * The shape is an opening holding the command, then `## Output`,
+ * `## Refusals`, and `## See also`, each at most once and in that order, though
+ * a page may leave one out, with no H3 and no table of flags, since
+ * `--help` already prints them. The check reads headings and table headers
+ * outside fences and leaves the opening to a reader.
+ */
+export function referenceShapeFindings(
+  source: string,
+): ReferenceShapeFinding[] {
+  if (!isReferencePage(source)) return []
+
+  const found: ReferenceShapeFinding[] = []
+  const lines = bodyLines(source)
+  let lastSection = -1
+
+  for (const [index, line] of lines.entries()) {
+    if (line.fenced) continue
+
+    const heading = HEADING.exec(line.text)
+    if (heading) {
+      const [, marks, text] = heading
+      if (marks.length === 3) {
+        found.push({ kind: 'subsection', line: line.number, text })
+      } else {
+        const position = REFERENCE_SECTIONS.indexOf(text)
+        if (position === -1) {
+          found.push({ kind: 'extra-section', line: line.number, text })
+        } else if (position <= lastSection) {
+          found.push({ kind: 'section-order', line: line.number, text })
+        } else {
+          lastSection = position
+        }
+      }
+      continue
+    }
+
+    const previous = lines[index - 1]
+    const next = lines[index + 1]
+    const opensTable =
+      TABLE_ROW.test(line.text) &&
+      !(previous && !previous.fenced && TABLE_ROW.test(previous.text)) &&
+      next !== undefined &&
+      SEPARATOR_ROW.test(next.text)
+    if (!opensTable) continue
+
+    const first = firstCell(line.text)
+    if (FLAG_HEADER.test(first)) {
+      found.push({ kind: 'flag-table', line: line.number, text: first })
+    }
+  }
+
+  return found
+}
+
+function firstCell(row: string): string {
+  const cells = row.trim().replace(/^\|/, '').split('|')
+  return (cells[0] ?? '').replace(/[`*_]/g, '').trim()
+}

package/src/markdown/scope.ts

@@ -0,0 +1,174 @@
+import type { DensityKind } from '@/markdown/density'
+
+/** The surfaces the retired bullet-stacks stage held, per `ALWAYS_GATED`. */
+const BULLET_RUN_SCOPE = [
+  /^canon\/context\/.+\.md$/,
+  /^docs\/.+\.md$/,
+  /^(?:claude|\.claude)\/skills\/[^/]+\/SKILL\.md$/,
+  /^(?:claude|\.claude)\/skills\/[^/]+\/references\/.+\.md$/,
+]
+
+/**
+ * The tracked documents the density limits hold: the context entries, the docs
+ * pages, the skill bodies and references of both skill trees, the tooling
+ * seeds and stack references, the wiki, and the two root guides.
+ *
+ * Rules stay out, since a rule is one imperative per bullet. So do
+ * `CLAUDE.md`, the requirement and design records, a seed carrying one of
+ * those three names, the changelog, the examples, and every `.canon/` record,
+ * each with a shape and cap of its own. Named here and nowhere else, so the
+ * audit, the gate stage reading its exit, and their tests read one scope.
+ */
+const DENSITY_SCOPE = [
+  ...BULLET_RUN_SCOPE,
+  /^tooling\/[^/]+\/seeds\/(?:.+\/)?(?!(?:CLAUDE|REQUIREMENTS|DESIGN)\.md$)[^/]+\.md$/,
+  /^tooling\/[^/]+\/reference\.md$/,
+  /^wiki\/.+\.md$/,
+  /^(?:README|CONTRIBUTING)\.md$/,
+]
+
+/**
+ * The path prefixes whose density findings fail a run, each added by the
+ * rewrite batch that brought its folders to zero.
+ *
+ * It describes this repository's rewrite progress and nothing about a target's
+ * corpus, which is why the audit reads it only inside a canon checkout.
+ */
+export const GATED_PATHS: readonly string[] = [
+  'canon/context/claude-plugin/',
+  'canon/context/claude-internal/',
+  'canon/context/features/',
+  'canon/context/cli/',
+  'canon/context/sandbox/',
+  'canon/context/governance/',
+  'canon/context/tooling/',
+  'canon/context/web.md',
+  'canon/context/context-model.md',
+  'canon/context/design.md',
+  'canon/context/index.md',
+  'claude/skills/api-design/SKILL.md',
+  'claude/skills/auto-ship/SKILL.md',
+  'claude/skills/backlog-triage/SKILL.md',
+  'claude/skills/backlog-triage/references/apply.md',
+  'claude/skills/build-in-slices/SKILL.md',
+  'claude/skills/canon-cli/SKILL.md',
+  'claude/skills/canon-feedback-triage/SKILL.md',
+  'claude/skills/canon-feedback/SKILL.md',
+  'claude/skills/canvas-board/SKILL.md',
+  'claude/skills/ci-workflow/SKILL.md',
+  'claude/skills/code-craft/SKILL.md',
+  'claude/skills/codebase-layout/SKILL.md',
+  'claude/skills/context-fold/SKILL.md',
+  'claude/skills/create-rule/SKILL.md',
+  'claude/skills/create-skill/SKILL.md',
+  'claude/skills/decision-escalate/SKILL.md',
+  'claude/skills/deploy-app/SKILL.md',
+  'claude/skills/deprecation-migration/SKILL.md',
+  'claude/skills/design-taste/SKILL.md',
+  'claude/skills/docs-sync/SKILL.md',
+  'claude/skills/document-health/SKILL.md',
+  'claude/skills/draft-and-pick/SKILL.md',
+  'claude/skills/draft-doc/SKILL.md',
+  'claude/skills/draft-figure/SKILL.md',
+  'claude/skills/draft-identity/SKILL.md',
+  'claude/skills/draft-identity/references/card-route.md',
+  'claude/skills/draft-ready/SKILL.md',
+  'claude/skills/draft-screencast/SKILL.md',
+  'claude/skills/draft-screencast/references/beats-template.md',
+  'claude/skills/draft-slides/SKILL.md',
+  'claude/skills/git-branch/SKILL.md',
+  'claude/skills/git-commit/SKILL.md',
+  'claude/skills/git-followup/SKILL.md',
+  'claude/skills/git-issue/SKILL.md',
+  'claude/skills/git-pr/SKILL.md',
+  'claude/skills/git-ship/SKILL.md',
+  'claude/skills/git-ship/references/ci-watch.md',
+  'claude/skills/git-split/SKILL.md',
+  'claude/skills/git-split/references/independent.md',
+  'claude/skills/git-split/references/stacked.md',
+  'claude/skills/git-stage/SKILL.md',
+  'claude/skills/git-worktree/SKILL.md',
+  'claude/skills/git-worktree/references/cleanup.md',
+  'claude/skills/markdown-craft/SKILL.md',
+  'claude/skills/plan-feature/SKILL.md',
+  'claude/skills/plan-feature/references/batches.md',
+  'claude/skills/plan-groundwork/SKILL.md',
+  'claude/skills/plan-groundwork/references/output.md',
+  'claude/skills/plan-intake-answer/SKILL.md',
+  'claude/skills/plan-intake/SKILL.md',
+  'claude/skills/read-frames/SKILL.md',
+  'claude/skills/record-screencast/SKILL.md',
+  'claude/skills/review-address/SKILL.md',
+  'claude/skills/review-address/references/rebase-only.md',
+  'claude/skills/review-craft/SKILL.md',
+  'claude/skills/review-pr/SKILL.md',
+  'claude/skills/review-ui/SKILL.md',
+  'claude/skills/review-ui/references/hosted-preview.md',
+  'claude/skills/role-orchestrator/SKILL.md',
+  'claude/skills/role-orchestrator/references/orchestrator-filing.md',
+  'claude/skills/role-planner/SKILL.md',
+  'claude/skills/role-reviewer/SKILL.md',
+  'claude/skills/role-worker/SKILL.md',
+  'claude/skills/search-craft/SKILL.md',
+  'claude/skills/session-compact/SKILL.md',
+  'claude/skills/session-map/SKILL.md',
+  'claude/skills/session-relay/SKILL.md',
+  'claude/skills/session-resume/SKILL.md',
+  'claude/skills/session-worktree/SKILL.md',
+  'claude/skills/systematic-debugging/SKILL.md',
+  'claude/skills/target-check/SKILL.md',
+  'claude/skills/target-setup/SKILL.md',
+  'claude/skills/task-board/SKILL.md',
+  'claude/skills/task-board/references/create-report.md',
+  'claude/skills/task-complete/SKILL.md',
+  'claude/skills/teach-workspace/SKILL.md',
+  'claude/skills/test-craft/SKILL.md',
+  'claude/skills/test-first/SKILL.md',
+  'claude/skills/ui-checklist/SKILL.md',
+  'claude/skills/ux-audit/SKILL.md',
+  'claude/skills/ux-measure/SKILL.md',
+  'claude/skills/video-craft/SKILL.md',
+  'claude/skills/write-human/SKILL.md',
+  'claude/skills/youtube-transcripts/SKILL.md',
+  'docs/agents/indexes.md',
+  'docs/agents/install-and-sync.md',
+  'docs/agents/migrate.md',
+  'docs/agents/output-shape.md',
+  'docs/agents/overview.md',
+  'docs/agents/targets.md',
+  'canon/context/development/',
+  'canon/context/ci/',
+  'canon/context/scripts/',
+  '.claude/skills/internal-',
+]
+
+/**
+ * The limit that gates before any folder is listed, and the surfaces it gates
+ * on. A run of more than 5 plain bullets failed the push in the context
+ * entries, the docs pages, and the skill bodies and references through a stage
+ * of its own before this measure existed, and waiting on `GATED_PATHS` would
+ * reopen that hole. The seeds, the stack references, the wiki, and the root
+ * guides were never held to it, and seven runs in the stack references would
+ * fail the push on the day this lands, so those wait for their batch.
+ */
+const ALWAYS_GATED: readonly DensityKind[] = ['bullet-run']
+
+/** Whether a path takes density findings at all. */
+export function inDensityScope(rel: string): boolean {
+  return DENSITY_SCOPE.some((pattern) => pattern.test(rel))
+}
+
+/** Whether a density finding of this kind on this path fails the run. */
+export function densityGates(
+  rel: string,
+  kind: DensityKind,
+  gated: readonly string[] = GATED_PATHS,
+): boolean {
+  if (!inDensityScope(rel)) return false
+  if (
+    ALWAYS_GATED.includes(kind) &&
+    BULLET_RUN_SCOPE.some((pattern) => pattern.test(rel))
+  )
+    return true
+  return gated.some((prefix) => rel.startsWith(prefix))
+}