@erclx/canon 4.0.0

package/src/markdown/files.ts

@@ -0,0 +1,102 @@
+import { existsSync, statSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+import { listRepositoryFiles } from '@/git-files'
+
+const MARKDOWN = /\.md$/
+
+/**
+ * `unavailable` is a distinct state from an empty scope.
+ *
+ * A bare run takes its corpus from git, and a git that cannot answer would
+ * otherwise resolve zero files and report every one of them clean.
+ */
+export type FileScope =
+  | {
+      readonly kind: 'resolved'
+      readonly files: readonly string[]
+      /** Arguments matching no markdown file, which is a typo rather than a pass. */
+      readonly unmatched: readonly string[]
+    }
+  | { readonly kind: 'unavailable' }
+
+/**
+ * Every reason `canon markdown audit` refuses for.
+ *
+ * None is an ordinary absence. `no-git` is a broken checkout the way it is
+ * for the secret scan, and a tree tracked by git carrying no markdown file at
+ * all, or an argument matching none, is a corpus this run could not build
+ * rather than a target that adopted none of the convention this check reads.
+ */
+export type MarkdownAuditRefusal = 'no-git' | 'no-markdown' | 'no-match'
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** Compiles the pattern once rather than per candidate. */
+function matchGlob(files: readonly string[], pattern: string): string[] {
+  const glob = new Bun.Glob(pattern)
+  return files.filter((each) => glob.match(each))
+}
+
+/**
+ * Resolves the arguments to a markdown file list, repo-relative and sorted.
+ *
+ * The corpus is what git lists rather than a directory walk, which is what
+ * keeps `node_modules` and the gitignored session-scratch folders out without
+ * naming either. A directory argument narrows that list by prefix and a
+ * pattern narrows it by match, so the three argument shapes read one corpus
+ * and a file only the working tree has is in scope on the branch adding it.
+ *
+ * An explicit file path is taken as given. A caller naming one file means it,
+ * and refusing a path git does not list would make the verb unusable against a
+ * gitignored draft a session wants measured before it commits.
+ */
+export async function resolveMarkdown(
+  root: string,
+  args: readonly string[],
+): Promise<FileScope> {
+  const listed = await listRepositoryFiles(root)
+  if (!listed) return { kind: 'unavailable' }
+
+  const markdown = listed.filter((rel) => MARKDOWN.test(rel))
+
+  if (args.length === 0) {
+    return { kind: 'resolved', files: markdown, unmatched: [] }
+  }
+
+  const files = new Set<string>()
+  const unmatched: string[] = []
+
+  for (const arg of args) {
+    const absolute = resolve(root, arg)
+    const rel = relative(root, absolute)
+
+    if (!isDirectory(absolute) && MARKDOWN.test(arg) && !arg.includes('*')) {
+      if (existsSync(absolute)) files.add(rel)
+      else unmatched.push(arg)
+      continue
+    }
+
+    // An empty `rel` is the root itself, where the prefix below matches nothing
+    // and would report the whole tree as an argument that resolved to no file.
+    const matched = isDirectory(absolute)
+      ? rel === ''
+        ? markdown
+        : markdown.filter((each) => each === rel || each.startsWith(`${rel}/`))
+      : matchGlob(markdown, arg)
+
+    if (matched.length === 0) {
+      unmatched.push(arg)
+      continue
+    }
+
+    for (const each of matched) files.add(each)
+  }
+
+  return { kind: 'resolved', files: [...files].sort(), unmatched }
+}

package/src/markdown/gate.ts

@@ -0,0 +1,28 @@
+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 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.
+   */
+  readonly structure: readonly StructureReport[]
+}
+
+/**
+ * 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.
+ */
+export function isGating({ bans }: GateInput): boolean {
+  return bans.length > 0
+}

package/src/markdown/scan.ts

@@ -0,0 +1,295 @@
+/**
+ * A fence opens on a run of three or more backticks or tildes and closes on a
+ * run of the same character at least as long. Length matters: a ```` block
+ * displaying a ``` example closes on neither of the inner delimiters, and a
+ * walker toggling on any run reads the second inner fence as an opening and
+ * inverts the rest of the file.
+ */
+const FENCE = /^(`{3,}|~{3,})/
+
+/** Anchored at position 0, so a `---` block inside a fenced template is body. */
+const FRONTMATTER = /^---\n[\s\S]*?\n---\n?/
+
+/**
+ * Inline code, a link destination, and an autolink, the three spans holding
+ * text a reader is shown rather than told.
+ *
+ * The bans this masking serves are stated with backticked examples, so a
+ * standard quoting its own banned character would report itself without it. A
+ * link destination is masked because a query string carries a semicolon that no
+ * rewrite of the sentence can remove.
+ */
+const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
+const LINK_DESTINATION = /\]\([^)]*\)/g
+const AUTOLINK = /<[^>\s]+>/g
+
+/**
+ * A whole inline link, capturing the anchor text a reader is shown.
+ *
+ * `LINK_DESTINATION` covers the span both measures drop and this covers the
+ * brackets only the weight measure drops, which a reader is no more shown than
+ * 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.
+ */
+const LINK = /\[([^\]]*)\]\([^)]*\)/g
+
+export interface BodyLine {
+  readonly number: number
+  readonly text: string
+  /** True on a fence delimiter and on every line between one pair. */
+  readonly fenced: boolean
+  /**
+   * Which fenced block the line sits in, counted from one, and undefined
+   * outside one. Two blocks written with nothing between them are one
+   * contiguous run of fenced lines, so this is the only field telling them
+   * apart. Counting from one keeps the outside answer from reading as a block.
+   *
+   * The name carries the fence because `block` alone already names a run of
+   * `BodyLine` values in `src/markdown/structure.ts`, and one word meaning both
+   * an aggregate of lines and an index on each line reads as a bug.
+   */
+  readonly fenceBlock: number | undefined
+}
+
+export type BanKind = 'character' | 'word' | 'spelling'
+
+export interface BanFinding {
+  readonly line: number
+  readonly column: number
+  readonly kind: BanKind
+  /** The term as the standard states it, so a report names what to look up. */
+  readonly term: string
+}
+
+export interface BanSets {
+  readonly characters: readonly string[]
+  readonly words: readonly string[]
+  readonly spellings: readonly string[]
+}
+
+/**
+ * Marks which lines sit inside a fence without dropping them, and which block
+ * each of those lines belongs to.
+ *
+ * Each measure excludes a fence for its own reason and needs a different
+ * response. The depth measure skips a fenced line so an example cannot break
+ * the run around it, bullet folding treats one as a break so a bullet does not
+ * absorb the block below it, and the ban scan ignores it outright. Returning
+ * the mark rather than a filtered list is what lets one walk serve all three.
+ *
+ * The block index answers the consumer that has to decide per block rather
+ * than per contiguous run, since two adjacent blocks are indistinguishable
+ * through the mark alone. It is counted here because the walk already holds
+ * the opening delimiter, and a consumer parsing its own would be the second
+ * fence walker this repository consolidated away.
+ */
+function markFences(texts: readonly string[], offset: number): BodyLine[] {
+  const lines: BodyLine[] = []
+  let fence: string | undefined
+  let fenceBlock = 0
+
+  for (const [index, text] of texts.entries()) {
+    const match = FENCE.exec(text.trim())
+    let fenced = false
+
+    if (fence) {
+      fenced = true
+      const closes =
+        match && match[1][0] === fence[0] && match[1].length >= fence.length
+      if (closes) fence = undefined
+    } else if (match) {
+      fenced = true
+      fence = match[1]
+      fenceBlock += 1
+    }
+
+    lines.push({
+      number: offset + index + 1,
+      text,
+      fenced,
+      fenceBlock: fenced ? fenceBlock : undefined,
+    })
+  }
+
+  return lines
+}
+
+/**
+ * Drops the frontmatter while keeping every surviving line's original number,
+ * so a finding points at the line an editor opens rather than at an offset into
+ * the body.
+ */
+export function bodyLines(source: string): BodyLine[] {
+  const match = source.match(FRONTMATTER)
+  const offset = match ? match[0].split('\n').length - 1 : 0
+
+  return markFences(
+    source
+      .slice(match ? match[0].length : 0)
+      .replace(/\n$/, '')
+      .split('\n'),
+    offset,
+  )
+}
+
+/**
+ * Drops every fenced block from raw text, frontmatter included as content.
+ *
+ * The record validators read whole files whose frontmatter is part of what they
+ * check, so this walks the source as given rather than through `bodyLines`.
+ */
+export function linesOutsideFences(text: string): string[] {
+  return markFences(text.split('\n'), 0)
+    .filter((line) => !line.fenced)
+    .map((line) => line.text)
+}
+
+/** Blanks a span while holding its width, so a column stays where it was. */
+function blank(match: string): string {
+  return ' '.repeat(match.length)
+}
+
+/**
+ * Blanks an inline code span alone, holding its width.
+ *
+ * Split from `maskDisplayed` for a reader who wants the narrower exclusion.
+ * A link destination often carries the one thing such a reader is after, such
+ * as a version-shaped token inside a generated compare link, where a code
+ * span is uniformly a quotation and never the claim itself.
+ */
+export function maskCodeSpans(text: string): string {
+  return text.replace(CODE_SPAN, blank)
+}
+
+/**
+ * Replaces displayed spans with spaces of equal width.
+ *
+ * Equal width is what keeps a reported column pointing at the character an
+ * editor puts the cursor on, which a plain deletion would shift left by
+ * everything masked ahead of it on the line.
+ */
+export function maskDisplayed(text: string): string {
+  return maskCodeSpans(text)
+    .replace(LINK_DESTINATION, blank)
+    .replace(AUTOLINK, blank)
+}
+
+/**
+ * Drops the spans a reader is never shown, returning the text they read.
+ *
+ * This is what a weight measure counts, and it is deliberately not
+ * `maskDisplayed`. That one holds each span's width so a ban finding can name a
+ * column, which leaves behind the very characters a weight measure exists to
+ * discount. The two also disagree on the span set: a backticked path is text a
+ * reader reads and stays counted here, while the ban scan blanks it so a
+ * standard quoting its own banned character does not report itself. One file
+ * therefore holds two answers to what a reader sees, each correct for its own
+ * measure, and collapsing them into one helper breaks whichever loses.
+ *
+ * A code span is walked around rather than through, since keeping it counted
+ * and then dropping spans from inside it takes back the decision. The
+ * placeholders this repository writes are the case: a reader is shown all of
+ * `.claude/context/<domain>.md` and the autolink pattern reaches the angle
+ * brackets in the middle of it.
+ */
+export function visibleText(text: string): string {
+  const drop = (segment: string): string =>
+    segment
+      .replace(LINK, '$1')
+      .replace(LINK_DESTINATION, '')
+      .replace(AUTOLINK, '')
+
+  let visible = ''
+  let read = 0
+
+  for (const span of text.matchAll(CODE_SPAN)) {
+    visible += drop(text.slice(read, span.index)) + span[0]
+    read = span.index + span[0].length
+  }
+
+  return visible + drop(text.slice(read))
+}
+
+function escape(term: string): string {
+  return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Bounds a banned word on a word character or a hyphen either side.
+ *
+ * `\b` sits after a hyphen, so a banned word ending a hyphenated compound
+ * reports from inside it: `allows` came back out of `auto-allows`. A compound
+ * is one word to a reader, and the ban is on the word rather than on a morpheme
+ * of it. Stripping hyphens before matching was the alternative and it joins the
+ * compound into a token neither half reaches.
+ *
+ * A spelling ban takes `wordBoundary` instead. This is not that rule with a
+ * wider fence, since the two bans target different things.
+ */
+function bannedWord(term: string): RegExp {
+  return new RegExp(`(?<![\\w-])${escape(term)}(?![\\w-])`, 'gi')
+}
+
+/**
+ * Bounds a banned spelling on a word character alone, hyphens included.
+ *
+ * A word ban targets the word, so a compound reading as one word is correct.
+ * A spelling ban targets the orthography inside it, and a compound is exactly
+ * where the orthography still sits: `behaviour-driven` carries the banned
+ * spelling as plainly as `behaviour` does, and rejecting a hyphen here would
+ * leave the usual spelling of that phrase unreported.
+ */
+function bannedSpelling(term: string): RegExp {
+  return new RegExp(`\\b${escape(term)}\\b`, 'gi')
+}
+
+/**
+ * Finds every banned term outside a fence, a code span, and a link.
+ *
+ * A word ban matches in either casing, since the standard states each in
+ * lowercase and bans the word rather than a spelling of it. A closed set of
+ * whole words separates the check from the pattern that produced most of the
+ * intake's false positives: `exercises` and `promises` end in the banned
+ * suffix and are not the banned words, and a closed set never reaches them.
+ */
+export function scanBans(
+  lines: readonly BodyLine[],
+  bans: BanSets,
+): BanFinding[] {
+  const found: BanFinding[] = []
+
+  const patterns: { kind: BanKind; term: string; pattern: RegExp }[] = [
+    ...bans.words.map((term) => ({
+      kind: 'word' as const,
+      term,
+      pattern: bannedWord(term),
+    })),
+    ...bans.spellings.map((term) => ({
+      kind: 'spelling' as const,
+      term,
+      pattern: bannedSpelling(term),
+    })),
+  ]
+
+  for (const line of lines) {
+    if (line.fenced) continue
+    const text = maskDisplayed(line.text)
+
+    for (const term of bans.characters) {
+      let column = text.indexOf(term)
+      while (column !== -1) {
+        found.push({ line: line.number, column, kind: 'character', term })
+        column = text.indexOf(term, column + term.length)
+      }
+    }
+
+    for (const { kind, term, pattern } of patterns) {
+      for (const match of text.matchAll(pattern)) {
+        found.push({ line: line.number, column: match.index, kind, term })
+      }
+    }
+  }
+
+  return found.sort((a, b) => a.line - b.line || a.column - b.column)
+}