@erclx/canon 4.30.2 → 4.31.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.30.2",
+  "version": "4.31.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/audits.md

@@ -32,9 +32,9 @@ Each is invoked as the CLI the caller is running rather than as a global `canon`
 
 ## What gates and what reports
 
-Four findings fail the run: an unresolved context citation, a banned character, word, or spelling, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
+Five findings fail the run: an unresolved context citation, a banned character, word, or spelling, a relative link resolving to nothing on disk, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
 
-Three of the four are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
+Four of the five are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
 
 Everything else reports. A heavy bullet, a long entry, a board row nothing resolves, a degradation term in a comment, and an implementation reaching history ahead of its test are judgments a reader settles. A push failing on one of those teaches contributors to route around the stage, which is the split recorded across every audit here and the one this command inherits rather than moves.
 

package/docs/agents/commands.md

@@ -54,7 +54,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon worktrees reclaim`     | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run` (`--json`)                                                                                                                  |
 | `canon comments scan`         | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                                                                             |
 | `canon context audit`         | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                                                                                          |
-| `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                                                                             |
+| `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, or a dead relative link, and report the structural checkpoints                                                                                                    |
 | `canon claude skills audit`   | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                                                                                                     |
 | `canon standards audit`       | Report the corpus against the success-criterion gate `standards/standard.md` states, failing only on a standard new to the branch (`--json`, `--arrivals-only`)                                                                    |
 | `canon claude skills drift`   | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)                                                                                          |

package/docs/agents/markdown-audit.md

@@ -59,6 +59,12 @@ A banned spelling keeps the plain word boundary, hyphens included. The two bans
 
 Two ban shapes stay unmeasured and the report says so on every run. A multi-word ban escapes the harvest by width, whether it carries a placeholder standing in for the rest of the sentence or spells the phrase out in full, and every rule under `## Voice` is a judgment. The bans `## Language` states over what a sentence may claim sit in the first group by construction, since a literal match over a pattern reports the compliant text and reaches none of the violations. A report listing hits without naming those would read as a verdict on the whole standard.
 
+### Links
+
+A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads. A destination is skipped rather than resolved when it is empty, opens with a URL scheme, opens with `#` as a same-file anchor, opens with `/` as a root-absolute reference, or carries `<` as a template placeholder such as `<slug>` or `<name>`. What remains is split on its first `#`, decoded, and resolved against the linking file's own folder, and a destination resolving to nothing on disk reports.
+
+The placeholder exemption is the one live case the corpus needs. Every current instance is a genuine illustration rather than a literal path, and a marker-based override is available for the day a real one needs an exception instead.
+
 ### Bullets, paragraphs, and depth
 
 Bullet weight and depth are the checks that moved off `canon context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
@@ -124,7 +130,7 @@ The condition on that was something identifying a finite verb rather than guessi
 
 ## Exit codes
 
-Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling fails the run. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
+Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
 
 `3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `canon gate run` is right to report it as unmeasured rather than as a pass. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.30.2",
+  "version": "4.31.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/markdown.ts

@@ -1,9 +1,11 @@
+import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { dirname, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
+import { decodePath, findBrokenLinks, type LinkFinding } from '@/markdown/links'
 import {
   type BanFinding,
   type BanSets,
@@ -47,6 +49,7 @@ interface AuditCommandOptions {
 interface FileReport {
   readonly rel: string
   readonly bans: readonly BanFinding[]
+  readonly links: readonly LinkFinding[]
   readonly structure: StructureReport
 }
 
@@ -74,12 +77,13 @@ export function register(program: Command): void {
         'Exit codes:',
         '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
-        '  2  a banned character, word, or spelling is present',
+        '  2  a banned character, word, or spelling is present, or a relative',
+        '     link resolves to nothing on disk',
         '  3  a shipped ban set is empty, so the run measured nothing',
         '',
-        'A ban hit is a fact and gates unconditionally. Bullet, paragraph, and',
-        'depth weight are judgments a reader settles, so all three report and',
-        'none of them fails a run.',
+        'A ban hit and a dead link are each a fact and gate unconditionally.',
+        'Bullet, paragraph, and depth weight are judgments a reader settles,',
+        'so all three report and none of them fails a run.',
         '',
         'Cadence reports the same way and carries one more caveat. Its range is',
         'drawn from prose a person reads, so terse reference prose sits below',
@@ -143,10 +147,14 @@ async function runAudit(
 
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
-      const lines = bodyLines(await readFile(resolve(root, rel), 'utf8'))
+      const abs = resolve(root, rel)
+      const lines = bodyLines(await readFile(abs, 'utf8'))
       return {
         rel,
         bans: scanBans(lines, bans),
+        links: findBrokenLinks(lines, (path) =>
+          existsSync(resolve(dirname(abs), path)),
+        ),
         structure: measureStructure(rel, lines, checkpoints),
       }
     }),
@@ -155,6 +163,7 @@ async function runAudit(
   intro('canon markdown audit')
   reportScope(scope.files, scope.unmatched)
   reportBans(reports, bans, empty)
+  reportLinks(reports, root)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
@@ -187,6 +196,7 @@ async function runAudit(
         entries: reports.map((report) => ({
           path: report.rel,
           bans: report.bans,
+          links: report.links,
           longestRun: report.structure.longestRun,
           longestRunLine: report.structure.longestRunLine,
           heavyBullets: report.structure.heavyBullets,
@@ -203,6 +213,7 @@ async function runAudit(
 
   const gating = isGating({
     bans: reports.flatMap((report) => report.bans),
+    links: reports.flatMap((report) => report.links),
     structure: reports.map((report) => report.structure),
   })
 
@@ -304,6 +315,59 @@ function reportBans(
   )
 }
 
+/**
+ * Names both the destination as written and the path it resolved to, since
+ * the second is what an editor can go check and the first is what a fix
+ * touches.
+ */
+function resolvedLinkPath(
+  root: string,
+  rel: string,
+  destination: string,
+): string {
+  const path = decodePath(destination)
+  if (path === undefined) return '(destination carries a malformed encoding)'
+  return relative(root, resolve(dirname(resolve(root, rel)), path))
+}
+
+function reportLinks(reports: readonly FileReport[], root: string): void {
+  logStep('Links')
+  logInfo(
+    "A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads.",
+  )
+  logInfo(
+    'A destination carrying a template placeholder in angle brackets reads as an illustration rather than a literal path.',
+  )
+
+  const carrying = reports
+    .filter((report) => report.links.length > 0)
+    .sort((a, b) => b.links.length - a.links.length)
+
+  if (carrying.length === 0) {
+    logInfo('No relative link resolving to nothing on disk.')
+    return
+  }
+
+  const total = carrying.reduce((sum, report) => sum + report.links.length, 0)
+  logWarn(
+    `${plural(total, 'dead link')} across ${plural(carrying.length, 'file')}`,
+  )
+  logWarn('This fails the run. Every other check below reports.')
+  pipeOutput(
+    carrying
+      .map(
+        (report) =>
+          `${report.rel}  ${plural(report.links.length, 'link')}\n${report.links
+            .map(
+              (found) =>
+                `  :${found.line}:${found.column + 1}  ${found.destination}  -> ${resolvedLinkPath(root, report.rel, found.destination)}`,
+            )
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 function reportBullets(
   reports: readonly FileReport[],
   checkpoints: Checkpoints,

package/src/gate/measures.ts

@@ -297,7 +297,7 @@ export const markdownBans: Measure = async (ctx) => {
     return {
       emissions: [output(frame.all)],
       failure:
-        'Markdown prose carries a banned character, word, or spelling. Rewrite the sentence, and reach for a code span only where the token is genuinely an identifier under discussion.',
+        'Markdown prose carries a banned character, word, or spelling, or a relative link resolves to nothing on disk. Rewrite the sentence or fix the link, and reach for a code span only where the token is genuinely an identifier under discussion.',
     }
   }
 

package/src/markdown/gate.ts

@@ -1,9 +1,12 @@
+import type { LinkFinding } from '@/markdown/links'
 import type { BanFinding } from '@/markdown/scan'
 import type { StructureReport } from '@/markdown/structure'
 
 export interface GateInput {
   /** Every ban hit across every file measured, flattened. */
   readonly bans: readonly BanFinding[]
+  /** Every dead relative link across every file measured, flattened. */
+  readonly links: readonly LinkFinding[]
   /**
    * Every structural measure the run made, read by nothing here.
    *
@@ -18,11 +21,12 @@ export interface GateInput {
 /**
  * Whether the audit found something that should fail the caller.
  *
- * A banned character, word, or spelling is a fact rather than a threshold, so
- * it 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, word, or spelling 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.
  */
-export function isGating({ bans }: GateInput): boolean {
-  return bans.length > 0
+export function isGating({ bans, links }: GateInput): boolean {
+  return bans.length > 0 || links.length > 0
 }

package/src/markdown/links.ts

@@ -0,0 +1,73 @@
+import { type BodyLine, LINK, maskCodeSpans } from '@/markdown/scan'
+
+export interface LinkFinding {
+  readonly line: number
+  readonly column: number
+  readonly destination: string
+}
+
+const SCHEME = /^[a-z][a-z0-9+.-]*:/
+
+function isSkipped(destination: string): boolean {
+  return (
+    destination === '' ||
+    SCHEME.test(destination) ||
+    destination.startsWith('#') ||
+    destination.startsWith('/') ||
+    destination.includes('<')
+  )
+}
+
+/**
+ * The path half of a destination, decoded, or undefined on a malformed
+ * percent-encoding.
+ *
+ * `decodeURIComponent` throws on a stray `%` not followed by two hex digits,
+ * and a destination is text an author typed rather than a value this command
+ * controls, so a throw here is reachable from any markdown file in the
+ * corpus. Exported so `src/commands/markdown.ts` decodes a destination for
+ * display the same way this decodes one for resolution, rather than a second
+ * definition of the same fallible call.
+ */
+export function decodePath(destination: string): string | undefined {
+  try {
+    return decodeURIComponent(destination.split('#')[0] ?? '')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reports a relative link whose destination resolves to nothing on disk.
+ *
+ * `exists` stays injected rather than calling `existsSync` here, so a test
+ * asserts against a fake corpus rather than real paths on disk.
+ */
+export function findBrokenLinks(
+  lines: readonly BodyLine[],
+  exists: (path: string) => boolean,
+): LinkFinding[] {
+  const found: LinkFinding[] = []
+
+  for (const line of lines) {
+    if (line.fenced) continue
+    const text = maskCodeSpans(line.text)
+
+    for (const match of text.matchAll(LINK)) {
+      const open = match[0].indexOf('](')
+      const destination = match[0].slice(open + 2, -1)
+      if (isSkipped(destination)) continue
+
+      const path = decodePath(destination)
+      if (path !== undefined && exists(path)) continue
+
+      found.push({
+        line: line.number,
+        column: (match.index ?? 0) + open + 2,
+        destination,
+      })
+    }
+  }
+
+  return found
+}

package/src/markdown/scan.ts

@@ -20,7 +20,17 @@ const FRONTMATTER = /^---\n[\s\S]*?\n---\n?/
  * rewrite of the sentence can remove.
  */
 const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
-const LINK_DESTINATION = /\]\([^)]*\)/g
+
+/**
+ * A destination body, reaching one level of balanced parentheses so
+ * `file(1).md` is not truncated at its first close paren. A plain `[^)]*`
+ * ends the whole match there, which reads a legitimate destination as
+ * unterminated and, in `src/markdown/links.ts`, reports it broken. CommonMark
+ * permits an unescaped destination to carry matched parentheses, and one
+ * level is what every destination measured in this corpus needs.
+ */
+const LINK_TARGET = String.raw`(?:[^()]|\([^()]*\))*`
+const LINK_DESTINATION = new RegExp(String.raw`\]\(${LINK_TARGET}\)`, 'g')
 const AUTOLINK = /<[^>\s]+>/g
 
 /**
@@ -31,8 +41,14 @@ const AUTOLINK = /<[^>\s]+>/g
  * the destination. The narrower pattern still runs after this one, since a link
  * wrapped across two source lines puts its opening bracket on a line this one
  * never matches.
+ *
+ * Exported so `src/markdown/links.ts` matches a destination against the same
+ * pattern rather than a second definition of the same shape. Take it through
+ * `replace` or `matchAll` alone. Both clone the pattern before reading
+ * `lastIndex`, where `test` or `exec` would mutate the shared instance and
+ * leave the other module's next match starting from a nonzero offset.
  */
-const LINK = /\[([^\]]*)\]\([^)]*\)/g
+export const LINK = new RegExp(String.raw`\[([^\]]*)\]\(${LINK_TARGET}\)`, 'g')
 
 export interface BodyLine {
   readonly number: number

package/standards/markdown.md

@@ -101,6 +101,7 @@ When frontmatter carries a short `title` or `description` used for catalog displ
 
 - Use descriptive anchor text for links. Avoid `click here` or `read more`.
 - Wrap file references in backticks by default. Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) and in an index file, whose rows exist to be followed. Never repeat the path verbatim as the label.
+- A relative link's destination resolves against the filesystem, over the same corpus the ban scan reads. A destination carrying a template placeholder in angle brackets, such as `<slug>` or `<name>`, reads as an illustration rather than a literal path and is exempt.
 
 ## Examples