@erclx/canon 5.34.0 → 5.35.0

package/governance/rules/tooling/765-spelling.md

@@ -1,19 +0,0 @@
----
-description: Route .cspell/ dictionary additions to the right seeded file and keep each sorted
-paths:
-  - '.cspell/**'
----
-
-# Spelling standards
-
-## Dictionary routing
-
-- Rewrite a typo rather than adding it. Add only a real term.
-- Add a term from a tool, library, or platform the project depends on to `.cspell/tech-stack.txt`, whether it is the dependency's own name or vocabulary from its config, API, or spec.
-- Add jargon, an acronym, a handle, or another project-specific term to `.cspell/project-terms.txt`.
-- Leave a dictionary declared `addWords: false` alone. It mirrors a closed set maintained elsewhere in the project rather than approved vocabulary, so route a word there through whatever maintains that set instead of editing the dictionary file.
-- Add a third dictionary only when cspell still flags a term neither file covers. Declare its path in `cspell.json` with `addWords: true` before adding words to it.
-
-## File shape
-
-- Keep every dictionary file sorted alphabetically.

package/governance/stacks/astro.toml

@@ -1,2 +0,0 @@
-extends = "node"
-rules = ["210-astro", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "465-interface-casing","470-motion"]

package/governance/stacks/nextjs.toml

@@ -1,2 +0,0 @@
-extends = "react"
-rules = ["230-nextjs"]

package/governance/stacks/node-server.toml

@@ -1,2 +0,0 @@
-extends = "node"
-rules = ["360-security-server", "370-database"]

package/governance/stacks/python-fastapi.toml

@@ -1,2 +0,0 @@
-extends = "python"
-rules = ["220-fastapi"]

package/governance/stacks/react.toml

@@ -1,2 +0,0 @@
-extends = "node"
-rules = ["200-react", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "465-interface-casing","470-motion"]

package/src/commands/standards.ts

@@ -1,278 +0,0 @@
-import { resolve } from 'node:path'
-import type { Command } from 'commander'
-import {
-  auditExitCode,
-  auditStandards,
-  type StandardsAudit,
-} from '@/standards/audit'
-import { listStandardEntries } from '@/standards/list'
-import { listStandards, readStandard, resolveStandard } from '@/standards/read'
-import {
-  frameError,
-  intro,
-  logError,
-  logInfo,
-  logStep,
-  logWarn,
-  outro,
-  pipeOutput,
-  plural,
-} from '@/cli/ui'
-
-interface StandardsListOptions {
-  readonly json?: boolean
-}
-
-interface StandardsAuditOptions {
-  readonly json?: boolean
-  readonly arrivalsOnly?: boolean
-}
-
-export function register(program: Command): void {
-  const standards = program
-    .command('standards')
-    .description('Standards commands (list, audit, <name>)')
-    .argument('[name]', 'Standard to print, by name with or without .md')
-    .helpOption('-h, --help', 'Show this help message')
-    .addHelpText(
-      'after',
-      [
-        '',
-        'A name resolves under standards/ at the working root, then the corpus',
-        'inside the canon package. No standard installs into a project, so the',
-        'package corpus is what answers there. The frame names the copy it read.',
-        '',
-        'Examples:',
-        '  canon standards markdown',
-        '  canon standards markdown.md',
-        '',
-      ].join('\n'),
-    )
-    .action((name: string | undefined, _options: unknown, cmd: Command) => {
-      if (name === undefined) {
-        // Registering an action replaces commander's own no-action fallback,
-        // which writes this help to stderr. Help is UI rather than data, and
-        // the default here is stdout.
-        cmd.outputHelp({ error: true })
-        process.exitCode = 1
-        return
-      }
-
-      process.exitCode = print(name)
-    })
-
-  standards
-    .command('list')
-    .description('List the standards with their descriptions and jurisdiction')
-    .helpOption('-h, --help', 'Show this help message')
-    .option('--json', 'Emit machine-readable JSON')
-    .action((opts: StandardsListOptions) => {
-      process.exitCode = runStandardsList(opts)
-    })
-
-  standards
-    .command('audit')
-    .description(
-      'Report the corpus against the success-criterion gate standards/standard.md states',
-    )
-    .argument('[path]', 'Project root, defaulting to the current directory')
-    .helpOption('-h, --help', 'Show this help message')
-    .option('--json', 'Add a machine-readable record on stdout')
-    .option(
-      '--arrivals-only',
-      'Run the gating check for standards new on this branch alone',
-    )
-    .addHelpText(
-      'after',
-      [
-        '',
-        'Exit codes:',
-        '  0  the audit completed with every arriving standard carrying the section',
-        '  1  refused, with the reason on stderr',
-        '  2  a standard new to this branch carries no success-criterion section',
-        '',
-        'A standard already in the corpus without the section is a known gap',
-        'standards/standard.md names, not a violation, so only an arrival fails.',
-        '',
-        'Examples:',
-        '  canon standards audit',
-        '  canon standards audit --json',
-        '  canon standards audit --arrivals-only',
-        '',
-      ].join('\n'),
-    )
-    .action(async (path: string | undefined, opts: StandardsAuditOptions) => {
-      process.exitCode = await runStandardsAudit(path, opts)
-    })
-}
-
-/**
- * Reads the working root first, the way `canon standards <name>` does, so a
- * project's own standards list beside the package corpus. The `--json` record
- * is the one thing on stdout and the frame opens only on the text path.
- */
-function runStandardsList(opts: StandardsListOptions): number {
-  const standards = listStandardEntries(process.cwd())
-
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify({ standards })}\n`)
-    return 0
-  }
-
-  intro('canon standards')
-  logStep('Standards')
-  for (const each of standards) logInfo(`${each.name} : ${each.description}`)
-  outro()
-  return 0
-}
-
-/**
- * Writes the standard to stdout and every frame line to stderr, so a caller
- * capturing the output with `$(...)` receives the document alone.
- *
- * The root is the caller's directory rather than the toolkit's, since a
- * repository that authors standards governs its own copy and the package copy
- * answers everywhere else.
- */
-function print(name: string): number {
-  intro('canon standards')
-
-  const root = process.cwd()
-  const resolved = resolveStandard(root, name)
-
-  if (!resolved) {
-    logWarn(`Unknown standard: ${name}`)
-    logStep('Available standards')
-    for (const each of listStandards(root)) logInfo(each)
-    logError("Run 'canon standards list' for descriptions.")
-    outro()
-    return 1
-  }
-
-  logStep(resolved.source)
-  process.stdout.write(readStandard(resolved))
-  outro()
-  return 0
-}
-
-/**
- * Measures the corpus at the cwd rather than the toolkit root the catalog
- * reads, so a linked worktree audits its own branch instead of `main`.
- */
-async function runStandardsAudit(
-  path: string | undefined,
-  opts: StandardsAuditOptions,
-): Promise<number> {
-  const root = resolve(path ?? process.cwd())
-  const gateOnly = opts.arrivalsOnly ?? false
-  const audit = await auditStandards(root)
-
-  if (audit.kind === 'refused') {
-    const message =
-      audit.reason === 'no-corpus'
-        ? `No standards/ under ${root}.`
-        : audit.reason === 'no-base'
-          ? 'No merge base against main resolved.'
-          : 'Could not read which standards arrived on this branch.'
-
-    if (gateOnly) {
-      frameError(message)
-    } else {
-      intro('canon standards audit')
-      logStep('Refused')
-      logWarn(message)
-      outro()
-    }
-
-    if (opts.json) {
-      process.stdout.write(
-        `${JSON.stringify({ root, reason: audit.reason, message })}\n`,
-      )
-    }
-
-    return auditExitCode(audit)
-  }
-
-  if (gateOnly) {
-    reportArrivalGate(audit)
-  } else {
-    intro('canon standards audit')
-    reportCorpus(audit)
-    outro()
-  }
-
-  if (opts.json) {
-    process.stdout.write(
-      `${JSON.stringify({
-        root,
-        base: audit.base,
-        standards: audit.standards,
-        withCriterion: audit.withCriterion,
-        withoutCriterion: audit.withoutCriterion,
-        arrivals: audit.arrivals,
-        arrivalsWithoutCriterion: audit.arrivalsWithoutCriterion,
-      })}\n`,
-    )
-  }
-
-  return auditExitCode(audit)
-}
-
-/**
- * Prints nothing when every arriving standard carries the section.
- *
- * `--arrivals-only` is what `verify.sh` runs on every push, and that script
- * pipes a stage's whole output into its own frame. A passing gate that
- * printed its frame would nest one inside the other on every contributor's
- * push.
- */
-function reportArrivalGate(
-  audit: Extract<StandardsAudit, { kind: 'measured' }>,
-): void {
-  const missing = audit.arrivalsWithoutCriterion
-  if (missing.length === 0) return
-
-  intro('canon standards audit')
-  logError(
-    missing.length === 1
-      ? '1 standard new to this branch carries no success-criterion section'
-      : `${missing.length} standards new to this branch carry no success-criterion section`,
-  )
-  pipeOutput(missing.join('\n'))
-  outro()
-}
-
-function reportCorpus(
-  audit: Extract<StandardsAudit, { kind: 'measured' }>,
-): void {
-  logStep('Corpus')
-  logInfo(`${plural(audit.standards.length, 'standard')} at standards/`)
-  logInfo(
-    `${plural(audit.withCriterion.length, 'standard')} carrying a success criterion`,
-  )
-
-  logStep('Known gaps')
-  if (audit.withoutCriterion.length === 0) {
-    logInfo('None. Every standard carries the section.')
-  } else {
-    pipeOutput(audit.withoutCriterion.join('\n'))
-  }
-
-  logStep('Arrivals since main')
-  if (audit.arrivals.length === 0) {
-    logInfo('No standard new to this branch.')
-    return
-  }
-
-  if (audit.arrivalsWithoutCriterion.length === 0) {
-    logInfo(
-      `${plural(audit.arrivals.length, 'standard')} arrived, every one carrying the section.`,
-    )
-    return
-  }
-
-  logError(
-    `${plural(audit.arrivalsWithoutCriterion.length, 'standard')} arrived carrying no success-criterion section`,
-  )
-  pipeOutput(audit.arrivalsWithoutCriterion.join('\n'))
-}

package/src/labels/spelling.ts

@@ -1,120 +0,0 @@
-import { existsSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { execa } from 'execa'
-
-/**
- * Why no unknown-word list was produced, which is never the same as a clean
- * one.
- *
- * `no-binary` is the binary being absent anywhere from the root upward.
- * `cspell` is a devDependency of this repository alone, per
- * `775-dependencies.md`'s ban on importing a transitive-only package, so a
- * target project that never adopted it gets no coverage from this check
- * rather than a network fetch or a forced new dependency.
- *
- * `check-failed` is the binary running and returning neither of the two
- * codes it defines, clean or issues found. `reject: false` is right, because
- * a findings exit is the ordinary outcome for half of this check's runs, but
- * discarding the code outright folded a crash, a bad config, or an
- * unreadable dictionary into the same empty-stdout shape a clean title
- * produces. Reading it the way `spawnAudit` in `src/audits/run.ts` reads its
- * own child processes is what tells the two apart.
- */
-export type SpellingRefusal = 'no-binary' | 'check-failed'
-
-export type SpellingScan =
-  | { readonly kind: 'checked'; readonly unknownWords: readonly string[] }
-  | {
-      readonly kind: 'unavailable'
-      readonly reason: 'no-binary'
-      readonly probedFrom: string
-    }
-  | {
-      readonly kind: 'unavailable'
-      readonly reason: 'check-failed'
-      readonly message: string
-    }
-
-const CSPELL_EXIT_CLEAN = 0
-const CSPELL_EXIT_ISSUES_FOUND = 1
-
-/**
- * Reads `cspell stdin --words-only --unique`'s stdout into a clean list.
- *
- * `--unique` already dedupes on cspell's side, so this exists for the same
- * reason `parseAdvisories` exists beside `auditDependencies`: a pure function
- * over a fixture string is a unit test that needs no binary on the machine
- * running it, where the trailing blank line an empty scan's stdout carries
- * is what actually needs the trim-and-filter below.
- */
-export function parseUnknownWords(stdout: string): string[] {
-  return stdout
-    .split(/\r?\n/)
-    .map((word) => word.trim())
-    .filter((word) => word.length > 0)
-}
-
-/**
- * Walks from `root` up to the filesystem root looking for a resolved
- * `cspell` binary, stopping at the first `node_modules/.bin/cspell` found.
- *
- * A caller running `canon labels scan` from a subdirectory of the checkout,
- * rather than from its own root, is what a single `join(root, …)` check
- * missed: `node_modules` sits at the checkout root, so the check found
- * nothing, the title went unchecked, and the command exited 0 with no path
- * naming what was probed or where it stopped looking.
- */
-function resolveCspellBinary(root: string): string | undefined {
-  let dir = resolve(root)
-
-  while (true) {
-    const candidate = join(dir, 'node_modules', '.bin', 'cspell')
-    if (existsSync(candidate)) return candidate
-
-    const parent = dirname(dir)
-    if (parent === dir) return undefined
-    dir = parent
-  }
-}
-
-/**
- * Shells this repository's own resolved `cspell` binary against a title over
- * stdin, rather than a bare `execa('cspell', …)`.
- *
- * `bun src/cli.ts labels scan` is the exact invocation `phase-label-gate.yml`
- * uses, and it runs outside `bun run`, so `node_modules/.bin` is not on
- * `PATH` and a bare spawn throws `ENOENT`. Resolving the binary path directly
- * under `root`, or an ancestor of it, is what a caller running from this
- * checkout needs, and it is also what keeps the check from reaching a
- * `bunx` fallback that could fetch `cspell` from the network on a machine
- * that never asked for it.
- */
-export async function scanTitleSpelling(
-  title: string,
-  root: string,
-): Promise<SpellingScan> {
-  const binary = resolveCspellBinary(root)
-
-  if (binary === undefined) {
-    return { kind: 'unavailable', reason: 'no-binary', probedFrom: root }
-  }
-
-  const result = await execa(
-    binary,
-    ['stdin', '--words-only', '--unique', '--no-progress', '--no-summary'],
-    { cwd: root, input: title, reject: false },
-  )
-
-  if (
-    result.exitCode !== CSPELL_EXIT_CLEAN &&
-    result.exitCode !== CSPELL_EXIT_ISSUES_FOUND
-  ) {
-    return {
-      kind: 'unavailable',
-      reason: 'check-failed',
-      message: result.stderr.trim().split('\n').pop() || 'no output on stderr',
-    }
-  }
-
-  return { kind: 'checked', unknownWords: parseUnknownWords(result.stdout) }
-}

package/src/standards/audit.ts

@@ -1,146 +0,0 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
-import { basename, join } from 'node:path'
-import { $ } from 'bun'
-import { gitEnv } from '@/git/env'
-import { resolveBaseRef } from '@/git/files'
-import { INDEX_FILE, standardsSourceDir } from '@/standards/read'
-
-/** Returned when a standard new to this branch states no success criterion under either heading `CRITERION_HEADING` accepts, the gating check. */
-export const EXIT_MISSING_CRITERION = 2
-
-/**
- * Matched at any casing, level-2 only, in either heading the corpus writes a
- * criterion under.
- *
- * `standards/standard.md` states the rule under `## Success criterion` and
- * templates the section itself as `## What a working <document type> looks
- * like`, and the template wins where the two disagree, which that file says in
- * as many words. Reading the rule group's own heading as the one to match is
- * what the first spelling here did, and no standard in the corpus carries a
- * criterion under it: 12 of 28 use the templated form and `standard.md` alone
- * carries the literal words, over its rules about criteria rather than over its
- * own. Nothing caught that, because the gate reads a standard new since the
- * merge base and none had arrived since it shipped.
- */
-const CRITERION_HEADING =
-  /^##\s+(?:success criterion|what a working .+ looks like)\s*$/im
-
-/**
- * The reasons an audit produces no reading. `no-corpus` is the ordinary state
- * of a target that authors no standards of its own, the same absence the
- * skills audit reads as its own `no-corpus`. The other two are a broken git
- * invocation rather than a project stating nothing.
- */
-export type StandardsAuditRefusal =
-  | 'no-corpus'
-  | 'no-base'
-  | 'unreadable-arrivals'
-
-export type StandardsAudit =
-  | {
-      readonly kind: 'measured'
-      readonly base: string
-      readonly standards: readonly string[]
-      readonly withCriterion: readonly string[]
-      readonly withoutCriterion: readonly string[]
-      readonly arrivals: readonly string[]
-      readonly arrivalsWithoutCriterion: readonly string[]
-    }
-  | { readonly kind: 'refused'; readonly reason: StandardsAuditRefusal }
-
-/**
- * Measures the corpus authored at `standards/` under `root` against the
- * `## Success criterion` gate `standards/standard.md` states, and names which
- * of those files are new since the branch's merge base.
- *
- * Reads the working-root corpus alone, never the packaged fallback
- * `src/standards/read.ts` falls through to for a name lookup, since a target
- * with no authored standards of its own has nothing here to gate.
- */
-export async function auditStandards(root: string): Promise<StandardsAudit> {
-  const dir = standardsSourceDir(root)
-  if (!existsSync(dir)) return { kind: 'refused', reason: 'no-corpus' }
-
-  const standards = readdirSync(dir, { withFileTypes: true })
-    .filter(
-      (entry) =>
-        entry.isFile() &&
-        entry.name.endsWith('.md') &&
-        entry.name !== INDEX_FILE,
-    )
-    .map((entry) => entry.name)
-    .sort()
-
-  const withCriterion: string[] = []
-  const withoutCriterion: string[] = []
-  for (const name of standards) {
-    const body = readFileSync(join(dir, name), 'utf8')
-    ;(CRITERION_HEADING.test(body) ? withCriterion : withoutCriterion).push(
-      name,
-    )
-  }
-
-  const base = await resolveBaseRef(root)
-  if (base === undefined) return { kind: 'refused', reason: 'no-base' }
-
-  const arrived = await arrivedStandards(root, base)
-  if (arrived === undefined) {
-    return { kind: 'refused', reason: 'unreadable-arrivals' }
-  }
-
-  const arrivals = standards.filter((name) => arrived.has(name))
-  const arrivalsWithoutCriterion = arrivals.filter((name) =>
-    withoutCriterion.includes(name),
-  )
-
-  return {
-    kind: 'measured',
-    base,
-    standards,
-    withCriterion,
-    withoutCriterion,
-    arrivals,
-    arrivalsWithoutCriterion,
-  }
-}
-
-/**
- * Only an arrival missing the section sets a failing code. Every other
- * standard without one is a known gap `standards/standard.md` names rather
- * than a violation, so failing the push on the 26 already there teaches
- * contributors to route around the stage.
- */
-export function auditExitCode(audit: StandardsAudit): number {
-  if (audit.kind === 'refused') return 1
-  return audit.arrivalsWithoutCriterion.length > 0 ? EXIT_MISSING_CRITERION : 0
-}
-
-/**
- * Filenames under `standards/` present in the working tree and absent at
- * `base`: a plain add, with rename detection forced off so a standard moved
- * into the corpus from elsewhere counts the same as one authored fresh.
- */
-async function arrivedStandards(
-  root: string,
-  base: string,
-): Promise<Set<string> | undefined> {
-  const [added, untracked] = await Promise.all([
-    $`git -C ${root} diff --no-renames --name-only --diff-filter=A ${base} -- standards`
-      .env(gitEnv())
-      .quiet()
-      .nothrow(),
-    $`git -C ${root} ls-files --others --exclude-standard -- standards`
-      .env(gitEnv())
-      .quiet()
-      .nothrow(),
-  ])
-
-  if (added.exitCode !== 0 || untracked.exitCode !== 0) return undefined
-
-  const paths = [
-    ...added.text().split('\n'),
-    ...untracked.text().split('\n'),
-  ].filter(Boolean)
-
-  return new Set(paths.map((path) => basename(path)))
-}

package/src/standards/list.ts

@@ -1,33 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import { resolveAllStandards } from '@/standards/read'
-import { appliesTo } from '@/standards/scope'
-
-export interface StandardEntry {
-  readonly name: string
-  readonly description: string
-  readonly appliesTo: string[]
-  /** The whole file, frontmatter included. */
-  readonly content: string
-  /** The root-labeled path `canon standards <name>` would read. */
-  readonly source: string
-}
-
-/**
- * Lists every standard a resolve reaches, the first root winning, so a project
- * standard shows beside the toolkit's and a local override of a package name
- * shows once, as the local copy.
- */
-export function listStandardEntries(root: string): StandardEntry[] {
-  return resolveAllStandards(root).map(({ name, path, source }) => {
-    const content = readFileSync(path, 'utf8')
-
-    return {
-      name,
-      description: readField(parseFrontmatter(content), 'description') ?? '',
-      appliesTo: appliesTo(content),
-      content,
-      source,
-    }
-  })
-}