@erclx/canon 5.31.0 → 5.33.0

package/src/context/wireframe-states.ts

@@ -1,238 +0,0 @@
-import { readFile, readdir, stat } from 'node:fs/promises'
-import { basename, dirname, join, relative } from 'node:path'
-import type { AuditedFolder } from '@/context/folders'
-import { type BodyLine, bodyLines } from '@/markdown/scan'
-
-/** `standards/wireframes.md`'s `## States` heading, matched by text alone. */
-const STATES_HEADING = /^##\s+States\s*$/i
-const SECTION_HEADING = /^##\s+\S/
-const TABLE_ROW = /^\s*\|/
-const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
-
-/** The one exception the standard admits to the states/evidence bijection. */
-const NOT_CAPTURED = 'not captured'
-
-/** A fenced block's opening delimiter naming the `plaintext` info string. */
-const PLAINTEXT_FENCE = /^`{3,}\s*plaintext\s*$/i
-
-export interface StateRow {
-  readonly line: number
-  readonly state: string
-  /** The evidence cell as written, backticks and all. */
-  readonly evidence: string
-}
-
-export interface MissingFolderFinding {
-  readonly line: number
-  readonly state: string
-  /** The cited path, so a report names what to go create or fix. */
-  readonly path: string
-}
-
-export interface UnlistedFolderFinding {
-  /** The evidence root the folder sits under, cited by at least one row. */
-  readonly root: string
-  readonly folder: string
-}
-
-export interface WireframeStatesReport {
-  readonly rel: string
-  readonly rows: readonly StateRow[]
-  /** A row whose evidence cell names a path with no folder at it. */
-  readonly missingFolders: readonly MissingFolderFinding[]
-  /** A folder under a cited root that no row names. */
-  readonly unlistedFolders: readonly UnlistedFolderFinding[]
-  /** Line of the `plaintext` fence, absent from an entry carrying no sketch. */
-  readonly sketchLine?: number
-  /** Whether that sketch sits beside a state whose evidence already exists. */
-  readonly sketchWithEvidence: boolean
-}
-
-function cells(row: string): string[] {
-  const parts = row.split('|')
-  if ((parts[0] ?? '').trim() === '') parts.shift()
-  if ((parts[parts.length - 1] ?? '').trim() === '') parts.pop()
-  return parts.map((cell) => cell.trim())
-}
-
-function columnIndex(headers: readonly string[], name: string): number {
-  return headers.findIndex(
-    (header) => header.toLowerCase() === name.toLowerCase(),
-  )
-}
-
-/**
- * Reads the States table under the `## States` heading, matching its `State`
- * and `Evidence` columns by header text rather than position.
- *
- * Column order is the one part of the standard's own table the standard could
- * still move during its own review, per the plan this ships under. Matching
- * position would break silently on a reorder, where matching text breaks the
- * same way a renamed header would: visibly, by finding nothing.
- */
-export function parseStatesTable(lines: readonly BodyLine[]): StateRow[] {
-  let index = 0
-  while (index < lines.length && !STATES_HEADING.test(lines[index].text)) {
-    index++
-  }
-  if (index >= lines.length) return []
-  index++
-
-  while (index < lines.length && !SECTION_HEADING.test(lines[index].text)) {
-    const separator = lines[index + 1]
-    if (
-      TABLE_ROW.test(lines[index].text) &&
-      separator !== undefined &&
-      TABLE_SEPARATOR.test(separator.text)
-    ) {
-      break
-    }
-    index++
-  }
-  if (
-    index >= lines.length ||
-    SECTION_HEADING.test(lines[index].text) ||
-    !TABLE_ROW.test(lines[index].text)
-  ) {
-    return []
-  }
-
-  const headers = cells(lines[index].text)
-  const stateCol = columnIndex(headers, 'State')
-  const evidenceCol = columnIndex(headers, 'Evidence')
-  if (stateCol === -1 || evidenceCol === -1) return []
-
-  index += 2
-  const rows: StateRow[] = []
-  while (index < lines.length && TABLE_ROW.test(lines[index].text)) {
-    const row = cells(lines[index].text)
-    rows.push({
-      line: lines[index].number,
-      state: row[stateCol] ?? '',
-      evidence: row[evidenceCol] ?? '',
-    })
-    index++
-  }
-
-  return rows
-}
-
-/** Line of the first `plaintext`-fenced sketch, or nothing. */
-export function findSketchLine(lines: readonly BodyLine[]): number | undefined {
-  for (const line of lines) {
-    if (PLAINTEXT_FENCE.test(line.text.trim())) return line.number
-  }
-  return undefined
-}
-
-/**
- * Reads an evidence cell into the path it cites, or nothing for the one cell
- * value the standard exempts from having one.
- */
-function evidencePath(cell: string): string | undefined {
-  const stripped = cell.replace(/^`+|`+$/g, '').trim()
-  if (stripped.toLowerCase() === NOT_CAPTURED) return undefined
-  return stripped.replace(/\/+$/, '')
-}
-
-async function isDirectory(path: string): Promise<boolean> {
-  try {
-    return (await stat(path)).isDirectory()
-  } catch {
-    return false
-  }
-}
-
-async function subfolders(path: string): Promise<string[]> {
-  try {
-    const entries = await readdir(path, { withFileTypes: true })
-    return entries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
-  } catch {
-    return []
-  }
-}
-
-/**
- * Measures one wireframe entry against its own States table.
- *
- * The evidence cell resolves as the literal path it names against `root`,
- * per the plan's operator answer, since the standard puts the path there and a
- * root guessed from convention reads wrong in a monorepo carrying more than
- * one evidence tree.
- *
- * An unlisted folder is reported only under a root at least one row already
- * cites, per the same operator answer, so a project holding evidence with no
- * states table at all reports nothing. `roots` is built from the rows this
- * loop already resolved rather than scanned separately, which is what keeps
- * the two readings in the same pass.
- */
-export async function measureWireframeStates(
-  root: string,
-  rel: string,
-  source: string,
-): Promise<WireframeStatesReport> {
-  const lines = bodyLines(source)
-  const rows = parseStatesTable(lines)
-  const sketchLine = findSketchLine(lines)
-
-  const missingFolders: MissingFolderFinding[] = []
-  const cited = new Map<string, Set<string>>()
-  let anyCaptured = false
-
-  for (const row of rows) {
-    const path = evidencePath(row.evidence)
-    if (path === undefined) continue
-
-    if (!(await isDirectory(join(root, path)))) {
-      missingFolders.push({ line: row.line, state: row.state, path })
-      continue
-    }
-
-    anyCaptured = true
-    const evidenceRoot = dirname(path)
-    const folder = basename(path)
-    const named = cited.get(evidenceRoot) ?? new Set<string>()
-    named.add(folder)
-    cited.set(evidenceRoot, named)
-  }
-
-  const unlistedFolders: UnlistedFolderFinding[] = []
-  for (const [evidenceRoot, named] of cited) {
-    for (const folder of await subfolders(join(root, evidenceRoot))) {
-      if (!named.has(folder)) {
-        unlistedFolders.push({ root: evidenceRoot, folder })
-      }
-    }
-  }
-
-  return {
-    rel,
-    rows,
-    missingFolders,
-    unlistedFolders,
-    ...(sketchLine !== undefined && { sketchLine }),
-    sketchWithEvidence: sketchLine !== undefined && anyCaptured,
-  }
-}
-
-/** Measures every wireframe entry in a resolved `wireframes` folder. */
-export async function measureWireframeFolder(
-  root: string,
-  folder: AuditedFolder,
-): Promise<WireframeStatesReport[]> {
-  const reports: WireframeStatesReport[] = []
-
-  for (const path of folder.entries) {
-    reports.push(
-      await measureWireframeStates(
-        root,
-        relative(root, path),
-        await readFile(path, 'utf8'),
-      ),
-    )
-  }
-
-  return reports
-}

package/src/gov/standard-rules.ts

@@ -1,179 +0,0 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { mkdir, rm, writeFile } from 'node:fs/promises'
-import { basename, join, relative } from 'node:path'
-import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
-import { parseFrontmatter } from '@/indexes/frontmatter'
-
-const STANDARDS_REL = 'standards'
-
-/** The band the generated rules ship in, named for what they point at. */
-export const STANDARD_RULES_BAND = 'standards'
-
-export type StandardRulesResult =
-  | { readonly ok: true; readonly written: readonly string[] }
-  | { readonly ok: false; readonly reason: string }
-
-interface StandardRule {
-  readonly name: string
-  readonly sourceRel: string
-  readonly title: string
-  readonly description: string
-  readonly paths: readonly string[]
-  readonly bullets: readonly string[]
-}
-
-export function standardRulesDir(root: string): string {
-  return join(rulesSourceDir(root), STANDARD_RULES_BAND)
-}
-
-/**
- * Generates one path-scoped rule per standard whose frontmatter carries
- * `paths:`. The standard owns the glob and the operative bullets, so the rule
- * is output, committed beside the authored bands so every reader of
- * `governance/rules/` sees it as an ordinary file.
- *
- * Every standard is read and checked before anything is written, so a refusal
- * leaves the previous output whole rather than half cleared.
- */
-export async function regenStandardRules(
-  root: string,
-): Promise<StandardRulesResult> {
-  const standardsDir = join(root, STANDARDS_REL)
-  if (!existsSync(standardsDir)) return { ok: true, written: [] }
-
-  const reserved = reservedNames(root)
-  const rules: StandardRule[] = []
-
-  for (const file of readdirSync(standardsDir).sort()) {
-    if (!file.endsWith('.md')) continue
-    const read = readStandard(root, file, reserved)
-    if (typeof read === 'string') return { ok: false, reason: read }
-    if (read !== undefined) rules.push(read)
-  }
-
-  const dir = standardRulesDir(root)
-  await rm(dir, { recursive: true, force: true })
-  if (rules.length > 0) await mkdir(dir, { recursive: true })
-
-  const written: string[] = []
-  for (const rule of rules) {
-    const dest = join(dir, `${rule.name}.md`)
-    await writeFile(dest, renderStandardRule(rule))
-    written.push(relative(root, dest))
-  }
-
-  return { ok: true, written }
-}
-
-/**
- * Band folders and authored rule basenames. A bare-word rule name equal to a
- * band would install the whole band through `--add`, and one equal to an
- * authored rule would shadow it in the name index.
- */
-function reservedNames(root: string): {
-  readonly bands: ReadonlySet<string>
-  readonly rules: ReadonlySet<string>
-} {
-  const bands = new Set<string>([STANDARD_RULES_BAND])
-  const rules = new Set<string>()
-
-  for (const rel of listRuleSourcePaths(root)) {
-    const segments = rel.split('/')
-    if (segments.length > 1) bands.add(segments[0])
-    if (segments[0] === STANDARD_RULES_BAND) continue
-    rules.add(basename(rel, '.md'))
-  }
-
-  return { bands, rules }
-}
-
-/** A rule to render, `undefined` for a standard with no `paths:`, or a reason. */
-function readStandard(
-  root: string,
-  file: string,
-  reserved: ReturnType<typeof reservedNames>,
-): StandardRule | string | undefined {
-  const sourceRel = `${STANDARDS_REL}/${file}`
-  const fields = parseFrontmatter(
-    readFileSync(join(root, STANDARDS_REL, file), 'utf8'),
-  )?.fields
-  if (fields === undefined || fields.paths === undefined) return undefined
-
-  const name = basename(file, '.md')
-  if (!isStringList(fields.paths)) {
-    return `${sourceRel}: paths must be a list of strings`
-  }
-  if (fields.rule !== undefined && !isStringList(fields.rule)) {
-    return `${sourceRel}: rule must be a list of strings`
-  }
-  if (reserved.bands.has(name)) {
-    return `${sourceRel}: name collides with a rule band folder`
-  }
-  if (reserved.rules.has(name)) {
-    return `${sourceRel}: name collides with an authored rule`
-  }
-
-  return {
-    name,
-    sourceRel,
-    title: typeof fields.title === 'string' ? fields.title : name,
-    description:
-      typeof fields.description === 'string' ? fields.description : '',
-    paths: fields.paths,
-    bullets: fields.rule ?? [],
-  }
-}
-
-function isStringList(value: unknown): value is string[] {
-  return (
-    Array.isArray(value) && value.every((entry) => typeof entry === 'string')
-  )
-}
-
-function renderStandardRule(rule: StandardRule): string {
-  const scope = rule.description.replace(/\.$/, '')
-  const pointer = [
-    `Follow the ${rule.name} standard for ${lowerFirst(scope)}.`,
-    'It is the single source.',
-    `Read it with \`canon standards ${rule.name}\`.`,
-  ].join(' ')
-
-  return [
-    '---',
-    `# Generated by \`canon gov regen\` from ${rule.sourceRel}. Edit that frontmatter, not this file.`,
-    `description: ${yamlScalar(rule.description)}`,
-    'paths:',
-    ...rule.paths.map((glob) => `  - ${yamlQuoted(glob)}`),
-    '---',
-    '',
-    `# ${rule.title.replace(/\breference$/, 'standards')}`,
-    '',
-    '## Authority',
-    '',
-    ...[pointer, ...rule.bullets].map((bullet) => `- ${bullet}`),
-    '',
-  ].join('\n')
-}
-
-function lowerFirst(text: string): string {
-  return text.charAt(0).toLowerCase() + text.slice(1)
-}
-
-/** Plain when YAML would read it back unchanged, single-quoted otherwise. */
-function yamlScalar(text: string): string {
-  const isPlain =
-    text !== '' &&
-    !/^[-?:,[\]{}#&*!|>'"%@`\s]/.test(text) &&
-    !/: |\s#|:$|\s$/.test(text)
-  return isPlain ? text : yamlQuoted(text)
-}
-
-/**
- * Quoted the way Prettier's `singleQuote` leaves YAML, so the drift check
- * never fights the formatter: single quotes unless the text holds one and
- * double quotes would need no escape.
- */
-function yamlQuoted(text: string): string {
-  if (text.includes("'") && !/["\\]/.test(text)) return `"${text}"`
-  return `'${text.replaceAll("'", "''")}'`
-}

package/src/records/migrate.ts

@@ -1,78 +0,0 @@
-import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import {
-  CATEGORY_BY_TYPE,
-  type FindingRemedy,
-  MEMORY_NAME,
-  memoryType,
-} from '@/records/validate'
-
-export const MIGRATE_REFUSALS = ['field-unrecoverable'] as const
-
-export type MigrateRefusal = (typeof MIGRATE_REFUSALS)[number]
-
-export interface MigrateRepair {
-  readonly ok: true
-  readonly text: string
-}
-
-export interface MigrateRefused {
-  readonly ok: false
-  readonly reason: MigrateRefusal
-  readonly message: string
-}
-
-export type MigrateOutcome = MigrateRepair | MigrateRefused
-
-function refuse(message: string): MigrateRefused {
-  return { ok: false, reason: 'field-unrecoverable', message }
-}
-
-/**
- * Repairs the one recoverable shape of `frontmatter-incomplete`: a memory
- * record missing `category` alone. The value sits in the filename's type
- * prefix already, which is the same fact `checkMemory` derives it from, so a
- * repair here writes back what the record already states rather than a value
- * a transform invented. It re-reads the file rather than trusting a value
- * carried on the `Finding`, so a transform and the check it repairs cannot
- * drift apart.
- */
-function categoryFromName(name: string, text: string): MigrateOutcome {
-  const frontmatter = parseFrontmatter(text)
-  if (!frontmatter) {
-    return refuse(`${name} carries no frontmatter block to add category to.`)
-  }
-
-  if (readField(frontmatter, 'category')) {
-    return refuse(`${name} already carries a category.`)
-  }
-
-  const match = MEMORY_NAME.exec(name)
-  const type = match ? memoryType(match[1]) : undefined
-  if (!type) {
-    return refuse(
-      `${name} is not named <type>-<slug>.md, so category has no type to derive from.`,
-    )
-  }
-
-  const rewritten = frontmatter.raw.replace(
-    /\n---$/,
-    `\ncategory: ${CATEGORY_BY_TYPE[type]}\n---`,
-  )
-
-  return { ok: true, text: rewritten + text.slice(frontmatter.raw.length) }
-}
-
-const TRANSFORMS: Readonly<
-  Record<FindingRemedy, (name: string, text: string) => MigrateOutcome>
-> = {
-  'category-from-name': categoryFromName,
-}
-
-/** Applies the transform a finding's `remedy` names against its own text. */
-export function migrateRecord(
-  remedy: FindingRemedy,
-  name: string,
-  text: string,
-): MigrateOutcome {
-  return TRANSFORMS[remedy](name, text)
-}