@erclx/canon 4.0.0

package/src/intake/folder.ts

@@ -0,0 +1,320 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, join, relative } from 'node:path'
+import {
+  INDEX_FILE,
+  type IntakeItem,
+  isMalformed,
+  isUnread,
+  readItems,
+  writeAnswerLine,
+} from '@/intake/items'
+
+export const INTAKE_REFUSALS = [
+  'no-intake',
+  'no-folder',
+  'ambiguous-slug',
+  'no-cluster',
+  'no-item',
+  'answered',
+  'bad-input',
+] as const
+
+export type IntakeRefusal = (typeof INTAKE_REFUSALS)[number]
+
+export interface IntakeRefused {
+  readonly ok: false
+  readonly reason: IntakeRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export interface FolderSummary {
+  readonly slug: string
+  readonly items: number
+  readonly open: number
+  readonly unread: number
+  /** Items carrying no answer slot, which no route here can answer. */
+  readonly malformed: number
+}
+
+export interface ClusterItems {
+  readonly cluster: string
+  readonly items: readonly IntakeItem[]
+}
+
+export interface FolderListed {
+  readonly ok: true
+  readonly folders: readonly FolderSummary[]
+}
+
+export interface FolderRead {
+  readonly ok: true
+  readonly slug: string
+  readonly clusters: readonly ClusterItems[]
+}
+
+export interface AnswerWritten {
+  readonly ok: true
+  readonly slug: string
+  readonly cluster: string
+  readonly path: string
+  readonly answered: readonly Selection[]
+}
+
+export type ListOutcome = FolderListed | IntakeRefused
+export type ReadOutcome = FolderRead | IntakeRefused
+export type AnswerOutcome = AnswerWritten | IntakeRefused
+
+export interface Selection {
+  readonly label: string
+  readonly answer: string
+}
+
+function refuse(
+  reason: IntakeRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): IntakeRefused {
+  return { ok: false, reason, message, detail }
+}
+
+export function intakeDir(root: string): string {
+  return join(root, '.claude', 'intake')
+}
+
+/**
+ * Cluster files in read order, which is the numbering the folder carries. The
+ * index is dropped because it answers nothing, so every remaining file is one a
+ * selection can land in.
+ */
+export async function listClusters(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith('.md') &&
+        entry.name !== INDEX_FILE,
+    )
+    .map((entry) => entry.name)
+    .sort()
+}
+
+async function listSlugs(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+type SlugMatch =
+  | { readonly kind: 'matched'; readonly name: string }
+  | { readonly kind: 'ambiguous'; readonly names: readonly string[] }
+  | { readonly kind: 'none' }
+
+/**
+ * A folder carries a `<nn>-<slug>` name, but a caller names the topic alone.
+ * An exact match wins first, since it is what a name with no ordinal, or one
+ * already copied in full from a listing, resolves against. Otherwise the one
+ * entry whose name is an ordinal ahead of the given slug wins, which is what
+ * lets a topic keep working as its folder's identity gains a prefix. Two or
+ * more such entries is a collision the caller needs told apart from a typo,
+ * not a folder silently picked or silently missing.
+ */
+function matchSlug(names: readonly string[], slug: string): SlugMatch {
+  if (names.includes(slug)) return { kind: 'matched', name: slug }
+
+  const suffixed = names.filter(
+    (name) => name === `${extractOrdinal(name)}-${slug}`,
+  )
+
+  if (suffixed.length === 1) return { kind: 'matched', name: suffixed[0] }
+  if (suffixed.length > 1) return { kind: 'ambiguous', names: suffixed }
+  return { kind: 'none' }
+}
+
+function extractOrdinal(name: string): string {
+  return /^\d{2,}-/.exec(name)?.[0].slice(0, -1) ?? ''
+}
+
+async function openFolder(
+  root: string,
+  slug: string,
+): Promise<string | IntakeRefused> {
+  const dir = intakeDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
+  }
+
+  const names = await listSlugs(dir)
+  const match = matchSlug(names, slug)
+
+  if (match.kind === 'none') {
+    return refuse('no-folder', `No intake folder named ${slug}.`, names)
+  }
+
+  if (match.kind === 'ambiguous') {
+    return refuse(
+      'ambiguous-slug',
+      `More than one intake folder matches ${slug}.`,
+      match.names,
+    )
+  }
+
+  return join(dir, match.name)
+}
+
+/** Counts per folder, which is what a session picks a folder to work from. */
+export async function listFolders(root: string): Promise<ListOutcome> {
+  const dir = intakeDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
+  }
+
+  const slugs = await listSlugs(dir)
+
+  const folders = await Promise.all(
+    slugs.map(async (slug) => {
+      const clusters = await readClusters(join(dir, slug))
+      const items = clusters.flatMap((cluster) => cluster.items)
+
+      return {
+        slug,
+        items: items.length,
+        open: items.filter((item) => item.open !== undefined).length,
+        unread: items.filter(isUnread).length,
+        malformed: items.filter(isMalformed).length,
+      }
+    }),
+  )
+
+  return { ok: true, folders }
+}
+
+async function readClusters(folder: string): Promise<ClusterItems[]> {
+  const names = await listClusters(folder)
+
+  return Promise.all(
+    names.map(async (cluster) => ({
+      cluster,
+      items: readItems(await readFile(join(folder, cluster), 'utf8')),
+    })),
+  )
+}
+
+/** Every item in a folder, grouped by the cluster file that holds it. */
+export async function readFolder(
+  root: string,
+  slug: string,
+): Promise<ReadOutcome> {
+  const opened = await openFolder(root, slug)
+  if (typeof opened !== 'string') return opened
+
+  return {
+    ok: true,
+    slug: basename(opened),
+    clusters: await readClusters(opened),
+  }
+}
+
+/**
+ * Lands a batch of selections in one cluster file.
+ *
+ * The batch is scoped to a cluster and applied in one read-modify-write because
+ * the alternative is a call per selection, and four of those against the same
+ * file race on the read and drop every answer but the last.
+ */
+export async function answerItems(
+  root: string,
+  slug: string,
+  cluster: string,
+  selections: readonly Selection[],
+): Promise<AnswerOutcome> {
+  const opened = await openFolder(root, slug)
+  if (typeof opened !== 'string') return opened
+
+  const name = cluster.endsWith('.md') ? cluster : `${cluster}.md`
+
+  if (name === INDEX_FILE) {
+    return refuse(
+      'no-cluster',
+      `${INDEX_FILE} is the index and carries no answer slot.`,
+    )
+  }
+
+  const path = join(opened, name)
+
+  if (!existsSync(path)) {
+    return refuse(
+      'no-cluster',
+      `No cluster named ${name} in ${slug}.`,
+      await listClusters(opened),
+    )
+  }
+
+  const broken = selections.filter((selection) =>
+    /[\r\n]/.test(selection.answer),
+  )
+
+  if (broken.length > 0) {
+    return refuse(
+      'bad-input',
+      `An answer is one line, so item ${broken.map((entry) => entry.label).join(', ')} cannot carry a line break.`,
+      broken.map((entry) => entry.label),
+    )
+  }
+
+  let text = await readFile(path, 'utf8')
+  const items = readItems(text)
+
+  const find = (label: string) =>
+    items.find((item) => item.label === label.toLowerCase())
+
+  const missing = selections.filter(
+    (selection) => find(selection.label)?.answerLine === undefined,
+  )
+
+  if (missing.length > 0) {
+    return refuse(
+      'no-item',
+      `${name} carries no answer slot for item ${missing.map((entry) => entry.label).join(', ')}.`,
+      items.map((item) => `${item.label}. ${item.title}`),
+    )
+  }
+
+  const filled = selections.filter(
+    (selection) => find(selection.label)?.answer !== undefined,
+  )
+
+  if (filled.length > 0) {
+    return refuse(
+      'answered',
+      `${name} item ${filled.map((entry) => entry.label).join(', ')} already carries an answer.`,
+      filled.map(
+        (entry) => `${entry.label}. ${find(entry.label)?.answer ?? ''}`,
+      ),
+    )
+  }
+
+  for (const selection of selections) {
+    const item = find(selection.label)
+    if (item?.answerLine === undefined) continue
+    text = writeAnswerLine(text, item.answerLine, selection.answer)
+  }
+
+  await writeFile(path, text)
+
+  return {
+    ok: true,
+    slug: basename(opened),
+    cluster: name,
+    path,
+    answered: selections,
+  }
+}

package/src/intake/items.ts

@@ -0,0 +1,174 @@
+import { bodyLines } from '@/markdown/scan'
+
+/**
+ * The index points at items and answers nothing itself, so it carries no
+ * answer slot for this verb to reach. It also displays the item format inside a
+ * fence, which the fence walk already masks, so skipping it by name is about
+ * what the file is rather than about the block it holds.
+ */
+export const INDEX_FILE = '00-overview.md'
+
+/**
+ * An item heading, labeled per cluster file rather than per folder.
+ *
+ * The label carries an optional letter suffix because a pass that splits one
+ * finding after the fact numbers the halves `3a` and `3b` rather than
+ * renumbering every item below them. A pattern accepting digits alone parses
+ * such a file without complaint and drops those items, leaving them
+ * unanswerable through this verb with nothing reporting the gap.
+ */
+const HEADING = /^###\s+(\d+[a-z]*)\.\s*(.*)$/i
+
+/** A bolded field bullet, which is every line an item carries. */
+const FIELD = /^-\s+\*\*([^*]+):\*\*\s*(.*)$/
+
+/**
+ * Any heading, which ends the item above it.
+ *
+ * A numbered `###` is tested first and opens the next item, so what reaches
+ * here is a heading that is not an item and therefore closes the one open. The
+ * narrower test for `##` alone let a `### Notes` block stay inside the item
+ * above it, and the stray slot such a block carries then displaced the real
+ * one, leaving the item reading as answered while its own slot sat empty and
+ * sending a write into the wrong section.
+ */
+const SECTION = /^#{1,6}\s/
+
+export interface IntakeItem {
+  /** The label as the heading spells it, such as `3` or `3a`. */
+  readonly label: string
+  readonly title: string
+  /** Line the heading sits on, 1-based against the whole file. */
+  readonly line: number
+  /** Line the answer slot sits on, absent when the item carries no slot. */
+  readonly answerLine: number | undefined
+  /** Text in the slot, absent when the slot is empty and the item is unread. */
+  readonly answer: string | undefined
+  readonly open: string | undefined
+  readonly suggested: string | undefined
+  readonly worth: string | undefined
+}
+
+interface Draft {
+  label: string
+  title: string
+  line: number
+  answerLine: number | undefined
+  answer: string | undefined
+  open: string | undefined
+  suggested: string | undefined
+  worth: string | undefined
+}
+
+function seal(draft: Draft): IntakeItem {
+  return { ...draft }
+}
+
+/**
+ * Reads every item a cluster file holds, in file order.
+ *
+ * The walk runs over `bodyLines` rather than a raw split so the item format
+ * block a folder copies into its own files parses as the sample it is. A
+ * heading counted out of a fence shifts nothing on its own, but it offers an
+ * answer slot no reader owns and the write-back would land inside the sample.
+ */
+export function readItems(text: string): IntakeItem[] {
+  const items: IntakeItem[] = []
+  let draft: Draft | undefined
+
+  for (const line of bodyLines(text)) {
+    if (line.fenced) continue
+
+    const heading = HEADING.exec(line.text)
+
+    if (heading) {
+      if (draft) items.push(seal(draft))
+      draft = {
+        label: heading[1].toLowerCase(),
+        title: heading[2].trim(),
+        line: line.number,
+        answerLine: undefined,
+        answer: undefined,
+        open: undefined,
+        suggested: undefined,
+        worth: undefined,
+      }
+      continue
+    }
+
+    if (!draft) continue
+
+    if (SECTION.test(line.text)) {
+      items.push(seal(draft))
+      draft = undefined
+      continue
+    }
+
+    const field = FIELD.exec(line.text)
+    if (!field) continue
+
+    const value = field[2].trim()
+
+    switch (field[1].trim().toLowerCase()) {
+      case 'you':
+        draft.answerLine = line.number
+        draft.answer = value === '' ? undefined : value
+        break
+      case 'open':
+        draft.open = value
+        break
+      case 'suggested':
+        draft.suggested = value
+        break
+      case 'worth it':
+        draft.worth = value
+        break
+    }
+  }
+
+  if (draft) items.push(seal(draft))
+
+  return items
+}
+
+/**
+ * Puts a selection in one item's slot, leaving every other line as it was.
+ *
+ * The rewrite replaces the whole line rather than patching inside it, which is
+ * the reason this is a verb at all. A stream editor expands an unescaped
+ * ampersand in the replacement to the whole match and exits zero on a
+ * non-match, so an answer carrying one would rewrite the line it anchored to
+ * and a missed slot would report success with the answer lost.
+ *
+ * The answer occupies one line, and the caller owes that guarantee. A line
+ * break splices a bare continuation into the item matching none of the patterns
+ * the reader tests, so the slot reads back as the text before the break while
+ * the item counts as answered, which puts correcting it behind the refusal on
+ * an item that already carries one.
+ */
+export function writeAnswerLine(
+  text: string,
+  answerLine: number,
+  answer: string,
+): string {
+  const lines = text.split('\n')
+  lines[answerLine - 1] = `- **You:** ${answer}`
+  return lines.join('\n')
+}
+
+/** An item nobody has reached, which is an empty slot rather than a missing one. */
+export function isUnread(item: IntakeItem): boolean {
+  return item.answerLine !== undefined && item.answer === undefined
+}
+
+/**
+ * An item carrying no slot at all, which the format says ships on every one.
+ *
+ * Such an item is neither unread nor answered, and counting it as either hides
+ * it: as answered it drops out of the work a reader is told remains, and as
+ * unread it joins a list whose every entry the answer verb then refuses. It is
+ * reported on its own so the file gets fixed.
+ */
+export function isMalformed(item: IntakeItem): boolean {
+  return item.answerLine === undefined
+}

package/src/inventory/config.ts

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Where a project declares what an inventory walks, spelled once.
+ *
+ * It sits at the project root rather than under `.claude/`, because the routes
+ * and the element queries describe the application rather than the agent
+ * surface, and a target reads them the way it reads any other build input.
+ */
+export const CONFIG_REL = 'inventory.toml'
+
+/** One measurable treatment and the elements that carry it, as the project spells them. */
+export interface InventorySubject {
+  readonly name: string
+  readonly query: string
+}
+
+export interface InventoryConfig {
+  readonly baseUrl: string
+  readonly routes: readonly string[]
+  readonly subjects: readonly InventorySubject[]
+}
+
+/**
+ * Why a config could not be used, which is never the same as a walk that read
+ * nothing.
+ *
+ * Every value here is a refusal rather than an empty listing, because a listing
+ * with no rows reads as a site giving one consistent answer, which is the
+ * report an unconfigured project would get for free and the exact wrong reading.
+ */
+export type ConfigRefusal =
+  | 'no-config'
+  | 'unreadable-config'
+  | 'no-base-url'
+  | 'no-routes'
+  | 'no-subjects'
+
+export type ConfigRead =
+  | { readonly kind: 'config'; readonly config: InventoryConfig }
+  | { readonly kind: 'refused'; readonly reason: ConfigRefusal }
+
+function readSubjects(table: unknown): InventorySubject[] {
+  if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+    return []
+  }
+
+  const subjects: InventorySubject[] = []
+  for (const [name, value] of Object.entries(table)) {
+    if (typeof value !== 'object' || value === null) continue
+    const query = (value as Record<string, unknown>).query
+    if (typeof query !== 'string' || query === '') continue
+    subjects.push({ name, query })
+  }
+
+  return subjects
+}
+
+/**
+ * Parses config text, so a caller holding the bytes skips the filesystem.
+ *
+ * A malformed route or subject is dropped rather than refused, matching the row
+ * handling in `@/labels/map`: one bad entry should not blind the walk to the
+ * other twenty. What that costs is a typo reading as an entry nobody wrote,
+ * which the listing surfaces from the other side as a route with no elements.
+ */
+export function parseInventoryConfig(source: string): ConfigRead {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  } catch {
+    return { kind: 'refused', reason: 'unreadable-config' }
+  }
+
+  const baseUrl = parsed['base-url']
+  if (typeof baseUrl !== 'string' || baseUrl === '') {
+    return { kind: 'refused', reason: 'no-base-url' }
+  }
+
+  const routes = Array.isArray(parsed.routes)
+    ? parsed.routes.filter(
+        (route): route is string => typeof route === 'string' && route !== '',
+      )
+    : []
+  if (routes.length === 0) return { kind: 'refused', reason: 'no-routes' }
+
+  const subjects = readSubjects(parsed.subjects)
+  if (subjects.length === 0) return { kind: 'refused', reason: 'no-subjects' }
+
+  return { kind: 'config', config: { baseUrl, routes, subjects } }
+}
+
+/** Reads the config a project declares at `root`, or says why it could not. */
+export function readInventoryConfig(root: string): ConfigRead {
+  let source: string
+  try {
+    source = readFileSync(join(root, CONFIG_REL), 'utf8')
+  } catch {
+    return { kind: 'refused', reason: 'no-config' }
+  }
+
+  return parseInventoryConfig(source)
+}
+
+/**
+ * Joins a base and a route into the address a walk opens.
+ *
+ * Concatenation rather than `new URL(route, base)`, because the resolver reads
+ * a leading slash as absolute and drops any path the base already carries, so a
+ * project served under a subdirectory would have every route walk the origin.
+ */
+export function routeUrl(baseUrl: string, route: string): string {
+  const base = baseUrl.replace(/\/+$/, '')
+  const path = route.startsWith('/') ? route : `/${route}`
+  return `${base}${path}`
+}

package/src/inventory/group.ts

@@ -0,0 +1,76 @@
+/**
+ * How many elements a row names before it stops naming them. A row exists to
+ * say how many answers a site gives, and the elements under it are there to
+ * make one findable rather than to enumerate the set.
+ */
+export const SAMPLE_LIMIT = 3
+
+/**
+ * Names a bounded head of a list and says how many it left out, so a treatment
+ * carried by fifty routes reads as fifty rather than as the three named.
+ *
+ * `total` arrives separately because the two lists reach here differently. A
+ * row's samples are already capped when they are collected, so their own length
+ * cannot say how many elements the row covers, while its routes arrive whole.
+ */
+export function abbreviate(entries: readonly string[], total: number): string {
+  const head = entries.slice(0, SAMPLE_LIMIT)
+  const elided = total - head.length
+  return elided > 0 ? `${head.join(', ')} and ${elided} more` : head.join(', ')
+}
+
+/** One element as the walk read it, on the route it was read from. */
+export interface Reading {
+  readonly route: string
+  readonly selector: string
+  readonly treatment: string
+}
+
+/** One answer the site gives, and what carries it. */
+export interface TreatmentGroup {
+  readonly treatment: string
+  readonly count: number
+  readonly routes: readonly string[]
+  readonly samples: readonly string[]
+}
+
+/**
+ * Turns a per-element walk into a per-answer listing, which is the whole point
+ * of the command.
+ *
+ * Grouping by the component instead was the obvious shape and it reports what a
+ * reader already knows, that a site has buttons and links. Grouping by the
+ * computed answer reports the thing nobody can see while building, which is
+ * that five components resolved to five different rings.
+ *
+ * Order is heaviest first, then by treatment, so the dominant answer leads and
+ * two runs over one site report one order rather than whatever the walk hit.
+ */
+export function groupByTreatment(
+  readings: readonly Reading[],
+): readonly TreatmentGroup[] {
+  const byTreatment = new Map<
+    string,
+    { count: number; routes: string[]; samples: string[] }
+  >()
+
+  for (const { route, selector, treatment } of readings) {
+    const row = byTreatment.get(treatment) ?? {
+      count: 0,
+      routes: [],
+      samples: [],
+    }
+    row.count += 1
+    if (!row.routes.includes(route)) row.routes.push(route)
+    if (row.samples.length < SAMPLE_LIMIT) row.samples.push(selector)
+    byTreatment.set(treatment, row)
+  }
+
+  return [...byTreatment.entries()]
+    .map(([treatment, row]) => ({ treatment, ...row }))
+    .sort(
+      (left, right) =>
+        right.count - left.count ||
+        left.treatment.localeCompare(right.treatment),
+    )
+}