jackherd 1.16.0 → 1.17.0

package/recipes/sources/sentry.ts

@@ -1,12 +1,18 @@
 // Copy to scripts/sources/sentry.ts in your repository; the recipe recipes/sentry.md says what to fill in.
+// The watcher shows this line with the exit code; it never carries the token or a URL.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const token = process.env.SENTRY_AUTH_TOKEN
-if (!token) process.exit(1)
+if (!token) fail('SENTRY_AUTH_TOKEN not set')
 
 const response = await fetch(
   'https://<host>/api/0/projects/<org>/<project>/issues/?query=is:unresolved&statsPeriod=24h',
   { headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(20_000) },
 )
-if (!response.ok) process.exit(1)
+if (!response.ok) fail(`HTTP ${response.status}`)
 console.log(JSON.stringify(await response.json()))
 
 export {}

package/recipes/sources.md

@@ -79,7 +79,7 @@ first run of this source: baseline, nothing reported; later a new or changed ent
 watcher state not read or changed; a running watcher takes a new source over at its next cycle
 ```
 
-**Keep a personal source.** A source can live in `~/.jackherd/sources.json` instead of the repository: `{ "$schema": "…/schemas/sources.schema.json", "sources": [ … ] }`, entries as above. It runs in every repository where the watcher starts, after the repository's `watch.sources`. On a name clash the repository's source wins and the personal one is skipped with a note. A personal source runs with `~/.jackherd/` as its working directory, so its script is `~/.jackherd/sources/<name>.ts` and its command `["bun", "sources/<name>.ts"]`. `jh watch source <name> --dry-run` finds it too and prints `origin: personal, <path>`; a draft file runs as a repository source, in the main checkout and without the keychain.
+**Keep a personal source.** A source can live in `~/.jackherd/sources.json` instead of the repository: `{ "$schema": "…/schemas/sources.schema.json", "sources": [ … ] }`, entries as above. It runs in every repository where the watcher starts, after the repository's `watch.sources`, unless it carries `"repos": ["owner/name"]` (one to twenty, unique without regard to case): then it runs only where the main checkout's `origin` names one of them, and elsewhere the watcher notes `<name>: not for this repo` (`<name>: no origin` when the checkout has none). `repos` belongs in the personal file only; the repository's config refuses it. `jh watch source <name> --dry-run` of a left-out source prints the note and exits 2 without running anything. On a name clash the repository's source wins and the personal one is skipped with a note. A personal source runs with `~/.jackherd/` as its working directory, so its script is `~/.jackherd/sources/<name>.ts` and its command `["bun", "sources/<name>.ts"]`. `jh watch source <name> --dry-run` finds it too and prints `origin: personal, <path>`; a draft file runs as a repository source, in the main checkout and without the keychain.
 
 **Keep a secret for a source.** `"secrets": ["NAME"]` (up to 10 names, `A-Z`, digits and `_`, starting with a letter) puts those variables into the environment of the source's command, and nowhere else. For a personal source each value comes from the keychain (service `jackherd`), else from the watcher's own environment; a repository source gets them from the watcher's environment only, never from the keychain. A value that is found nowhere fails the run with `secret missing: NAME`, an unreachable keychain with `secret store unavailable`; other sources go on. The script reads the value from `process.env` and never prints it.
 
@@ -91,6 +91,8 @@ jh secret delete NAME
 
 **Show entries as content.** `"show": "entries"` opens the source's entries in a herd block of their own under "Your turn", headed by its `label`, instead of the folded row in `Sources`. For a source whose entries are the day's content, such as a calendar; not together with `ticket`.
 
-The watcher and the herd read the repository's config and the personal file again each cycle (about a minute): a new, changed or removed source counts without a restart, a new one runs at once. A changed file that is invalid keeps the previous sources and prints `sources not reloaded: <file>: <reason>`. The rest of the config is read when the watcher starts.
+The watcher and the herd read the repository's config and the personal file again each cycle (about a minute): a new, changed or removed source counts without a restart, a new one runs at once. A changed file that is invalid keeps the previous sources and prints `sources not reloaded: <file>: <reason>`. `deploy`, `feedback`, `previews` and `checks` follow the same way; a change that applies prints `config reloaded: <parts>`, an invalid one keeps every value and prints `config not reloaded: <file>: <reason>`. The board and the language are read when the watcher starts.
+
+**Say why a source failed.** A failing command may print one stdout line `jackherd-reason: <reason>` (a status, a missing variable); the watcher shows the last such line as `exit 1: <reason>`, with the values of the source's `secrets` and URL credentials masked, cut to 160 characters. stderr is never read. Name no token in it.
 
 Three limits stand: the watcher cannot make a command read only, so name only commands that read. A source in `.jackherd/config.json` runs for everyone who starts the watcher in the repository, at the same level of trust as `check.checks` and hooks. The watcher reads the config of the main checkout, never the one of a lane's worktree; a dry run started inside a worktree reads that worktree's config first. And `jh watch source … --dry-run` runs whatever command its draft names, so it never belongs in a permission allowlist.

package/schemas/jackherd.schema.json

@@ -143,6 +143,10 @@
         "lockFile": {
           "type": "string",
           "pattern": "^(?![/-])(?!(?:.*\\/)?\\.\\.(?:\\/|$))[A-Za-z0-9._/-]+$"
+        },
+        "minFreeGb": {
+          "type": "number",
+          "exclusiveMinimum": 0
         }
       },
       "additionalProperties": false
@@ -645,6 +649,15 @@
               "show": {
                 "type": "string",
                 "const": "entries"
+              },
+              "repos": {
+                "minItems": 1,
+                "maxItems": 20,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+                }
               }
             },
             "required": [
@@ -699,6 +712,28 @@
               "type": "integer",
               "minimum": 1,
               "maximum": 9
+            },
+            "standing": {
+              "type": "object",
+              "properties": {
+                "tools": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "pattern": "^mcp__[A-Za-z0-9_-]+__execute_sql$"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "enum": [
+                      "stage"
+                    ]
+                  }
+                }
+              },
+              "required": [
+                "tools"
+              ],
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
@@ -929,6 +964,38 @@
             "maximum": 9007199254740991
           }
         },
+        "openBoxes": {
+          "default": "fail",
+          "type": "string",
+          "enum": [
+            "fail",
+            "warn",
+            "off"
+          ]
+        },
+        "lintPointers": {
+          "type": "object",
+          "properties": {
+            "level": {
+              "default": "warn",
+              "type": "string",
+              "enum": [
+                "warn",
+                "fail",
+                "off"
+              ]
+            },
+            "exclude": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        },
         "looseTests": {
           "default": false,
           "type": "boolean"

package/schemas/sources.schema.json

@@ -126,6 +126,15 @@
           "show": {
             "type": "string",
             "const": "entries"
+          },
+          "repos": {
+            "minItems": 1,
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+            }
           }
         },
         "required": [

package/src/approval/checked.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { isRecord } from '../shared/is-record'
+import type { ApprovalRequestFile } from '../watch/approvals'
+
+/** What `jh approval show|checked` prints and how it ends: 0 shown, 1 wrong arguments, 2 no such open request. */
+export type ApprovalReport = { exitCode: number; stdout: string[]; stderr: string[] }
+
+type RequestCall = Pick<ApprovalRequestFile, 'lane' | 'cwd' | 'tool' | 'input'>
+
+const VERBS = new Set(['show', 'checked'])
+const USAGE = 'Usage: jh approval show|checked <id> <hash>'
+const ID = /^[0-9a-f]{12}$/
+const HASH = /^[0-9a-f]{16}$/
+
+/** JSON with the keys of every object sorted, as the approval gate hook hashes a call. */
+const canonicalJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isRecord(value))
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(',')}}`
+  return JSON.stringify(value) ?? 'null'
+}
+
+/** The hash of a call as the approval gate hook writes it (`callHash`, which this package does not import; contract test). */
+export const requestHash = ({ lane, cwd, tool, input }: RequestCall): string =>
+  createHash('sha256').update(canonicalJson({ lane, cwd, tool, input })).digest('hex').slice(0, 16)
+
+const refused = (exitCode: number, line: string): ApprovalReport => ({ exitCode, stdout: [], stderr: [line] })
+
+/** The request as the coordinator reads it before it marks it: every field the lane wrote, made safe to print. */
+const shown = ({ id, hash, lane, tool, cwd, input }: ApprovalRequestFile): string[] => [
+  `approval ${id} ${hash}`,
+  `lane: ${terminalSafe(lane)}`,
+  `tool: ${terminalSafe(tool)}`,
+  `cwd: ${terminalSafe(cwd)}`,
+  'input:',
+  ...(JSON.stringify(input, null, 2) ?? 'null').split('\n').map(terminalSafe),
+]
+
+/**
+ * `jh approval show <id> <hash>` and `jh approval checked <id> <hash>`: print the open request whose id and hash these
+ * are, and whose content its hash covers, and end with 0; otherwise say why and end with 2. Neither writes anything.
+ * `show` is for reading; a successful `checked` in the coordinator's transcript is the mark the approval gate hook
+ * reads as "the coordinator checked exactly this call", so it comes after the check, never before.
+ */
+export const approvalReport = (args: readonly string[], requests: readonly ApprovalRequestFile[]): ApprovalReport => {
+  const [verb, id, hash, ...rest] = args
+  if (!VERBS.has(verb ?? '') || !ID.test(id ?? '') || !HASH.test(hash ?? '') || rest.length > 0)
+    return refused(1, USAGE)
+  const request = requests.find((candidate) => candidate.id === id && candidate.usedAt === null)
+  if (request === undefined) return refused(2, `no open request ${id}`)
+  if (request.hash !== hash)
+    return refused(2, `request ${id} has hash ${request.hash}, not ${hash}: it changed, look at it again`)
+  if (requestHash(request) !== hash)
+    return refused(2, `request ${id} does not match its hash: it was changed by hand, ask the user`)
+  return { exitCode: 0, stdout: shown(request), stderr: [] }
+}

package/src/approval/command.ts

@@ -0,0 +1,16 @@
+import { mainCheckout } from '../plans/git'
+import { readApprovalRequests } from '../watch/approvals'
+import { approvalReport } from './checked'
+
+/** `jh approval show|checked <id> <hash>`: read a held call, and the coordinator's mark that it checked it (`approvalReport`). */
+export const run = (args: string[]): number => {
+  try {
+    const report = approvalReport(args, readApprovalRequests(mainCheckout(process.cwd())))
+    for (const line of report.stdout) console.log(line)
+    for (const line of report.stderr) console.error(line)
+    return report.exitCode
+  } catch (error) {
+    console.error(`jh approval: ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}

package/src/check/command.ts

@@ -3,17 +3,21 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { planRootsIn } from '../../kit/hooks/hooks/shared/boards'
+import { laneOf } from '../../kit/hooks/hooks/shared/lane'
 import { findProjectRoot, globalConfigPath, locateConfigFile, MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
+import { installedReferenceHint } from '../lane/skill-hint'
 import { mainCheckout } from '../plans/git'
 import { baseRefOf } from '../plans/settings'
+import { REFERENCE } from '../watch/reference-paths'
 import { type ChangedFile, parsePorcelain, STATUS_COMMAND } from './changes'
 import { deferralArrowCheck } from './deferral-arrows'
 import { runCheck, runProcess } from './execute'
 import { matchesAnyGlob } from './glob'
+import { lintPointerCheck } from './lint-pointers'
 import { parallelArgument, parallelReportLines } from './parallel-report'
 import { type CheckPlan, type CheckStack, checkStackOf, type Filesystem, isSlow, planChecks } from './plan'
-import { planStructureChecks } from './plan-structure-check'
+import { laneOpenBoxesCheck, planStructureChecks } from './plan-structure-check'
 import { publicContentCheck } from './public-content-check'
 import {
   artifactResult,
@@ -29,6 +33,7 @@ import {
 } from './report'
 import { type CheckResult, RUN_MODE, type RunMode, runModeOf } from './result'
 import { isWorkspaceManifest, kitCopyPaths, WORKSPACE_LIST_FILE, WORKSPACE_MANIFEST } from './roots'
+import { DEFAULT_LINT_POINTERS } from './schema'
 import { type CheckSettings, CONFIG_PATH, noStackFallbackOf, parseCheckSettings, stackOf } from './settings'
 import { skillBudgetCheck } from './skill-budgets'
 
@@ -199,11 +204,50 @@ const planRootsOf = (root: string, worktreeDirectory: string): string[] => {
   }
 }
 
-/** The checks jackherd runs itself beside the configured ones: public content, deferral arrows, skill budgets, plan structure. */
-const ownChecksOf = (root: string, paths: readonly string[], settings: CheckSettings, home: string) => [
+/** The lane a checkout is for: the first directory below the main checkout's worktree directory; null outside one. */
+const laneOfCheckout = (root: string, worktreeDirectory: string): string | null => {
+  try {
+    return laneOf({ cwd: root, main: mainCheckout(root), worktreeDirectory })
+  } catch {
+    return null
+  }
+}
+
+/** The open boxes of the lane's phase, left out for a checkout that is no lane's. */
+const openBoxesCheckOf = (root: string, settings: CheckSettings): CheckResult | null => {
+  const lane = laneOfCheckout(root, settings.worktreeDirectory)
+  return lane === null
+    ? null
+    : laneOpenBoxesCheck({
+        root,
+        lane,
+        planDirectory: settings.planDirectory,
+        board: settings.board,
+        language: settings.planLanguage,
+        level: settings.check.openBoxes,
+        baseOf: contentAt(root, baseRefOf(settings)),
+      })
+}
+
+/** The checks jackherd runs itself beside the configured ones: public content, deferral arrows, skill budgets, lint pointers, plan structure. */
+const ownChecksOf = (
+  root: string,
+  paths: readonly string[],
+  settings: CheckSettings,
+  home: string,
+  kitCopies: readonly string[],
+) => [
+  openBoxesCheckOf(root, settings),
   publicContentCheck(root, paths, settings.check.publicContent, home),
   deferralArrowCheck(root, paths, settings.planDirectory),
   skillBudgetCheck(root, settings.check.skillBudgets, settings.skillPrefix),
+  lintPointerCheck(
+    root,
+    paths,
+    settings.check.lintPointers ?? DEFAULT_LINT_POINTERS,
+    kitCopies,
+    contentAt(root, 'HEAD'),
+  ),
   ...planStructureChecks({
     root,
     paths,
@@ -228,8 +272,9 @@ const checkChanges = async (
 ): Promise<CheckResult[] | string> => {
   const stack = checkStackOf(stackOf(settings.stack))
   let plan: CheckPlan
+  let kitCopies: string[]
   try {
-    const kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
+    kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
     plan = planChecks(
       files,
       {
@@ -253,7 +298,7 @@ const checkChanges = async (
     testCommandResult(settings.commands.test, settings.stack),
     missingTestCommandResult(settings.commands.test, settings.stack),
     namedTestResult(plan.sourcesWithoutNamedTest),
-    ...ownChecksOf(root, plan.paths, settings, home),
+    ...ownChecksOf(root, plan.paths, settings, home, kitCopies),
   ])
 }
 
@@ -282,7 +327,7 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
   }
   print(settings.notes)
   if (files.length === 0) {
-    console.log('Nothing changed.')
+    console.log(`Nothing changed.${installedReferenceHint(root, REFERENCE.events, home)}`)
     return 0
   }
   const results = await checkChanges(files, root, settings, runModeOf(args), home)

package/src/check/lint-pointers.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { matchesAnyGlob } from './glob'
+import {
+  changedBlocksOf,
+  LINT_MARKER,
+  LINT_NONE,
+  LINT_POINTER_STATE,
+  LINT_POINTERS_NAME,
+  type LintFinding,
+  lintFindingsOf,
+} from './lint-shaped'
+import { CHECK_STATUS, type CheckResult } from './result'
+import { LINT_POINTERS_LEVEL, type LintPointersConfig, type LintPointersLevel } from './schema'
+
+/** The texts a project writes its rules in: rule files and the instruction files. Skills carry commands, the hooks' field. */
+const LINT_POINTER_GLOBS = ['**/rules/**/*.md', '**/CLAUDE.md', '**/AGENTS.md'] as const
+
+export const isLintPointerPath = (path: string): boolean => matchesAnyGlob(path, LINT_POINTER_GLOBS)
+
+type PathFinding = LintFinding & { path: string }
+
+const WAY_THROUGH = `Write the lint rule and name it with \`${LINT_MARKER}<rule id>\`, or write \`${LINT_MARKER}${LINT_NONE} <reason>\` where it stays prose.`
+
+const HINTS = {
+  [LINT_POINTER_STATE.missing]: '',
+  [LINT_POINTER_STATE.noId]: ` (\`${LINT_MARKER}\` names no rule id)`,
+  [LINT_POINTER_STATE.noReason]: ` (\`${LINT_MARKER}${LINT_NONE}\` needs a reason)`,
+  [LINT_POINTER_STATE.pointed]: '',
+} as const
+
+const lineOf = ({ path, line, shape, excerpt, state }: PathFinding): string =>
+  `${path}:${line} ${shape}: "${excerpt}"${HINTS[state]}`
+
+const detailOf = (findings: readonly PathFinding[]): string =>
+  findings.length === 0
+    ? 'every lint-shaped rule block points at its lint rule'
+    : [...findings.map(lineOf), WAY_THROUGH].join('\n')
+
+const statusOf = (findings: readonly PathFinding[], level: LintPointersLevel): CheckResult['status'] => {
+  if (findings.length === 0) return CHECK_STATUS.pass
+  return level === LINT_POINTERS_LEVEL.fail ? CHECK_STATUS.fail : CHECK_STATUS.warn
+}
+
+/**
+ * The new or changed blocks of the changed rule files that carry a rule a linter could check (an import path,
+ * a literal comparison, a comment form, a banned call) and name no lint rule. Kit copies and `exclude` are not
+ * read; `previousOf` answers a path with the file as `HEAD` holds it. Null when no such file changed or the level is off.
+ */
+export const lintPointerCheck = (
+  root: string,
+  paths: readonly string[],
+  settings: LintPointersConfig,
+  kitCopies: readonly string[],
+  previousOf: (path: string) => string | null,
+): CheckResult | null => {
+  const files = paths.filter(
+    (path) =>
+      isLintPointerPath(path) &&
+      !kitCopies.includes(path) &&
+      !matchesAnyGlob(path, settings.exclude) &&
+      existsSync(join(root, path)),
+  )
+  if (settings.level === LINT_POINTERS_LEVEL.off || files.length === 0) return null
+  const started = Date.now()
+  const findings = files.flatMap((path) =>
+    lintFindingsOf(changedBlocksOf(readFileSync(join(root, path), 'utf8'), previousOf(path))).map((found) => ({
+      ...found,
+      path,
+    })),
+  )
+  return {
+    name: LINT_POINTERS_NAME,
+    command: `${files.length} changed rule ${files.length === 1 ? 'file' : 'files'}, new or changed blocks`,
+    status: statusOf(findings, settings.level),
+    detail: detailOf(findings),
+    durationMs: Date.now() - started,
+  }
+}

package/src/check/lint-shaped.ts

@@ -0,0 +1,196 @@
+/** The `Lint pointers` result name; the kit texts that name the check are held against it. */
+export const LINT_POINTERS_NAME = 'Lint pointers'
+
+/** The inline-code prefix of a pointer: `` `lint:<rule id>` `` names the linter rule that checks the block's rule. */
+export const LINT_MARKER = 'lint:'
+
+/** `` `lint:none` `` plus a reason: the rule stays prose on purpose. */
+export const LINT_NONE = 'none'
+
+/** The kinds of rule a linter can check. */
+export const LINT_SHAPE = {
+  importPath: 'import path',
+  literalComparison: 'literal comparison',
+  commentForm: 'comment form',
+  bannedCall: 'banned call',
+} as const
+
+export type LintShape = (typeof LINT_SHAPE)[keyof typeof LINT_SHAPE]
+
+/** Whether and how a block points at its lint rule. */
+export const LINT_POINTER_STATE = {
+  pointed: 'pointed',
+  missing: 'missing',
+  noId: 'noId',
+  noReason: 'noReason',
+} as const
+
+export type LintPointerState = (typeof LINT_POINTER_STATE)[keyof typeof LINT_POINTER_STATE]
+
+export type Block = { line: number; text: string }
+
+export type LintFinding = { line: number; shape: LintShape; state: LintPointerState; excerpt: string }
+
+const EXCERPT_LENGTH = 100
+
+const GAP = 40
+const BEFORE_SIGNAL = new RegExp(
+  `\\b(?:never|no|not|don't|avoid|instead of|forbidden)\\b([\\p{L}\\p{N}\\s,'’/*()-]{0,${GAP}})\`([^\`\\n]+)\``,
+  'giu',
+)
+const AFTER_SIGNAL = /`([^`\n]+)`[^`\n]{0,25}\b(?:forbidden|banned|refused|never|not allowed|stay out)\b/gi
+const POINTER_SPAN = new RegExp(`\`${LINT_MARKER}([^\`\\n]*)\``, 'g')
+const EXAMPLE_MARK = '❌'
+const IMPORT_WORD = /\b(?:imports?|imported|importing|require)\b/i
+const SCOPED_MODULE = /^(?:@[\w.-]+\/[\w./-]+|~\/[\w./-]+|\.{1,2}\/[\w./-]+)$/
+const PLAIN_MODULE = /^[\w.-]+\/[\w./-]+$/
+const COMPARISON = /(?:===?|!==?)\s*['"`][^'"`]+['"`]/
+const COMMENT_SPAN = /^(?:\/\/|\/\*|<!--|#(?:\s|$)|--(?:\s|$))/
+const CALL_SPAN = /^(?:[\w$]+(?:\.[\w$]+)*|\.[\w$]+)\(/
+const INLINE_CODE = /`([^`\n]+)`/g
+const FENCE = /^\s*```/
+const HEADING = /^#{1,6}\s/
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s/
+const TABLE_ROW = /^\s*\|/
+const WORD = /[\p{L}\p{N}]{2,}/u
+
+const spansOf = (text: string): string[] => [...text.matchAll(INLINE_CODE)].map(([, span]) => span.trim())
+
+const frontmatterEnd = (lines: readonly string[]): number => {
+  if (lines[0]?.trim() !== '---') return 0
+  const close = lines.findIndex((line, index) => index > 0 && line.trim() === '---')
+  return close === -1 ? 0 : close + 1
+}
+
+const isSingleLine = (line: string): boolean => HEADING.test(line) || TABLE_ROW.test(line)
+
+const startsBlock = (line: string): boolean => isSingleLine(line) || LIST_ITEM.test(line)
+
+/**
+ * The blocks of a Markdown text: a paragraph, a list item with its continuation lines, a table row or a
+ * heading, outside code. A code block belongs to the block before it; the frontmatter falls away. `line` is 1-based.
+ */
+export const blocksOf = (markdown: string): Block[] => {
+  const lines = markdown.split('\n')
+  const blocks: { line: number; lines: string[] }[] = []
+  let continuing = false
+  let inFence = false
+  const open = (index: number, line: string) => {
+    blocks.push({ line: index + 1, lines: [line] })
+    continuing = !isSingleLine(line)
+  }
+  for (let index = frontmatterEnd(lines); index < lines.length; index++) {
+    const line = lines[index]
+    const last = blocks.at(-1)
+    if (inFence) {
+      last?.lines.push(line)
+      inFence = !FENCE.test(line)
+    } else if (FENCE.test(line)) {
+      if (last) last.lines.push(line)
+      else open(index, line)
+      inFence = true
+    } else if (line.trim() === '') continuing = false
+    else if (startsBlock(line) || !continuing) open(index, line)
+    else last?.lines.push(line)
+  }
+  return blocks.map(({ line, lines: blockLines }) => ({ line, text: blockLines.join('\n') }))
+}
+
+const splitByFence = (text: string): { prose: string[]; code: string[] } => {
+  const split = { prose: [] as string[], code: [] as string[] }
+  let inFence = false
+  for (const line of text.split('\n')) {
+    if (FENCE.test(line)) inFence = !inFence
+    else (inFence ? split.code : split.prose).push(line)
+  }
+  return split
+}
+
+const proseLinesOf = (text: string): string[] => splitByFence(text).prose
+
+const codeLinesOf = (text: string): string[] => splitByFence(text).code
+
+/** An inline-code span a rule forbids, the words between the signal and the span, and whether the signal followed it. */
+type ForbiddenSpan = { span: string; gap: string; trailing: boolean }
+
+/**
+ * The spans a block marks as forbidden: right after a signal word (`never`, `no`, `not`, `avoid` …, at most
+ * {@link GAP} characters of plain words in between), before `forbidden` or `banned`, or on a line with a `❌`.
+ * A span far from every signal belongs to a sentence that merely mentions it.
+ */
+const forbiddenSpansOf = (text: string): ForbiddenSpan[] => {
+  const prose = proseLinesOf(text)
+  const marked = prose.filter((line) => line.includes(EXAMPLE_MARK)).join('\n')
+  const proseText = prose.join('\n')
+  return [
+    ...[...proseText.matchAll(BEFORE_SIGNAL)].map(([, gap, span]) => ({ span: span.trim(), gap, trailing: false })),
+    ...[...proseText.matchAll(AFTER_SIGNAL)].map(([, span]) => ({ span: span.trim(), gap: '', trailing: true })),
+    ...spansOf(marked).map((span) => ({ span, gap: '', trailing: false })),
+  ]
+}
+
+const isModule = ({ span, gap, trailing }: ForbiddenSpan, text: string): boolean =>
+  (SCOPED_MODULE.test(span) && (trailing || IMPORT_WORD.test(text))) ||
+  (PLAIN_MODULE.test(span) && IMPORT_WORD.test(gap))
+
+const markedCodeComparison = (text: string): boolean =>
+  codeLinesOf(text).some((line) => line.includes(EXAMPLE_MARK) && COMPARISON.test(line))
+
+const hasShape = {
+  [LINT_SHAPE.importPath]: (text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some((entry) => isModule(entry, text)),
+  [LINT_SHAPE.literalComparison]: (text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some(({ span }) => COMPARISON.test(span)) || markedCodeComparison(text),
+  [LINT_SHAPE.commentForm]: (_text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some(({ span }) => COMMENT_SPAN.test(span)),
+  [LINT_SHAPE.bannedCall]: (_text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some(({ span }) => CALL_SPAN.test(span)),
+} as const
+
+/**
+ * The kinds of lint-checkable rule a block carries: an inline-code span of that kind that a signal word
+ * forbids, or, for a literal comparison, a code line marked `❌`.
+ */
+export const lintShapesOf = (text: string): LintShape[] => {
+  const forbidden = forbiddenSpansOf(text)
+  return Object.values(LINT_SHAPE).filter((shape) => hasShape[shape](text, forbidden))
+}
+
+const isNoneMarker = (id: string): boolean => id === LINT_NONE || id.startsWith(`${LINT_NONE} `)
+
+const pointerStateOfMatch = (match: RegExpMatchArray, text: string): LintPointerState => {
+  const id = match[1].trim()
+  if (id === '') return LINT_POINTER_STATE.noId
+  if (!isNoneMarker(id)) return LINT_POINTER_STATE.pointed
+  const reason = `${id.slice(LINT_NONE.length)} ${text.slice((match.index ?? 0) + match[0].length)}`
+  return WORD.test(reason) ? LINT_POINTER_STATE.pointed : LINT_POINTER_STATE.noReason
+}
+
+/** Whether a block names its lint rule: `` `lint:<id>` ``, or `` `lint:none` `` with a reason in the block. */
+export const lintPointerStateOf = (text: string): LintPointerState => {
+  const marked = [...text.matchAll(POINTER_SPAN)]
+  if (marked.length === 0) return LINT_POINTER_STATE.missing
+  const states = marked.map((match) => pointerStateOfMatch(match, text))
+  return states.includes(LINT_POINTER_STATE.pointed) ? LINT_POINTER_STATE.pointed : states[0]
+}
+
+const excerptOf = (text: string): string => {
+  const first = text.split('\n')[0].trim()
+  return first.length > EXCERPT_LENGTH ? `${first.slice(0, EXCERPT_LENGTH - 1)}…` : first
+}
+
+/** The blocks that carry a lint-checkable rule and do not point at its lint rule. */
+export const lintFindingsOf = (blocks: readonly Block[]): LintFinding[] =>
+  blocks.flatMap(({ line, text }) => {
+    const [shape] = lintShapesOf(text)
+    const state = lintPointerStateOf(text)
+    return shape && state !== LINT_POINTER_STATE.pointed ? [{ line, shape, state, excerpt: excerptOf(text) }] : []
+  })
+
+const normalized = (text: string): string => text.replace(/\s+/g, ' ').trim()
+
+/** The blocks of `current` whose text `previous` (the file as `HEAD` holds it; null for a new file) lacks. */
+export const changedBlocksOf = (current: string, previous: string | null): Block[] => {
+  const known = new Set(previous === null ? [] : blocksOf(previous).map(({ text }) => normalized(text)))
+  return blocksOf(current).filter(({ text }) => !known.has(normalized(text)))
+}