@prestack/thread 0.1.3 → 0.1.5

package/dist/core/answers.ts

@@ -1,999 +0,0 @@
-import { createHash, randomBytes } from 'node:crypto'
-import { existsSync, readFileSync, rmSync, writeFileSync } from './files.ts'
-import { tmpdir } from 'node:os'
-import { dirname, join, relative } from 'node:path'
-import { argv, env, exit, stderr, stdin, stdout } from 'node:process'
-import { createInterface } from 'node:readline'
-import { pathToFileURL } from 'node:url'
-import { CONSTRAINTS } from '../integrity/constraint.ts'
-import type { Row } from './descend.ts'
-import { LISTS, descend, listFields, listShape, shapeFields, shapesNamed, type Field } from './descend.ts'
-import { quoted, valuesIn } from './rows.ts'
-import type { Tree } from './tree.ts'
-
-export const RECEIPT = '--receipt'
-
-export const ENDS = '.'
-
-export const FROM = '--from'
-
-export const CHAINED = '--chained'
-
-export const BODY = 'body'
-
-export const WRITES = 'writes'
-
-export const asFlag = (key: string): string => `--${key}`
-
-export function refuse(because: string): never {
-  stderr.write(`create: ${because}\n`)
-  exit(1)
-}
-
-export function slug(one: string): string {
-  return one
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '_')
-    .replace(/^_+|_+$/g, '')
-}
-
-export function within(root: string, path: string): string {
-  return relative(root, path).split('\\').join('/')
-}
-
-const NAMED = /^([a-z][A-Za-z0-9_.-]*):[ \t]?(.*)$/
-
-export function parsed(text: string): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
-  const lines = text.split('\n')
-  const found: { at: number; key: string; value: string }[] = []
-  for (let at = 0; at < lines.length; at += 1) {
-    const line = lines[at] ?? ''
-    if (line.trim() === '' || line.trimStart().startsWith('#')) continue
-    const held = NAMED.exec(line)
-    if (held === null) {
-      refuse(
-        `line ${String(at + 1)} is neither blank nor an answer: ${JSON.stringify(line.slice(0, 60))}. ` +
-          'Every answer is written `name: value`, and a body is written under `body:` and ended by a line ' +
-          `holding only ${ENDS}.`,
-      )
-    }
-    const key = held[1] ?? ''
-    if (key !== 'body') {
-      found.push({ at: at + 1, key, value: (held[2] ?? '').trim() })
-      continue
-    }
-
-    const body: string[] = []
-    const beside = held[2] ?? ''
-    if (beside.trim() !== '') body.push(beside)
-    let shut = false
-    for (at += 1; at < lines.length; at += 1) {
-      if ((lines[at] ?? '').trim() === ENDS) {
-        shut = true
-        break
-      }
-      body.push(lines[at] ?? '')
-    }
-    if (!shut) {
-      refuse(
-        `the \`body:\` opened on line ${String(found.length === 0 ? 1 : at)} is never closed — a body ends at a ` +
-          `line holding only ${ENDS}, and this one runs to the end of the input.`,
-      )
-    }
-    found.push({ at: at + 1, key, value: body.join('\n').trim() })
-  }
-  return found
-}
-
-export function scoped(
-  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-  opens: string,
-): {
-  readonly own: readonly { readonly at: number; readonly key: string; readonly value: string }[]
-  readonly each: readonly (readonly { readonly at: number; readonly key: string; readonly value: string }[])[]
-} {
-  const own: { at: number; key: string; value: string }[] = []
-  const each: { at: number; key: string; value: string }[][] = []
-  const lists = new Set<string>(LISTS)
-  let mine = false
-  for (const one of given) {
-    if (one.key === opens) {
-      each.push([one])
-      mine = true
-      continue
-    }
-    if (lists.has(one.key)) {
-      mine = false
-      continue
-    }
-    if (mine) (each[each.length - 1] ?? []).push(one)
-    else if (each.length === 0) own.push(one)
-  }
-  return { own, each }
-}
-
-const locate = (one: { readonly at: number; readonly key: string }): string =>
-  one.at > 0 ? `line ${String(one.at)}` : `\`--${one.key}\``
-
-export interface Asked {
-  readonly at: string
-  readonly guide: string
-  readonly asks?: string
-  readonly optional?: boolean
-  readonly list?: boolean
-  readonly map?: boolean
-  readonly boolean?: boolean
-  readonly worded?: boolean
-}
-
-export interface Said {
-  readonly guide: string
-  readonly asks?: string
-  readonly optional?: boolean
-}
-
-export const named = (all: readonly Asked[]): readonly string[] => all.map((one) => one.at)
-
-export const prompted = (one: Asked): string =>
-  one.asks ?? `${one.at} — ${one.guide}${one.optional === true ? ', or blank' : ''}: `
-
-export type Given = { readonly at: number; readonly key: string; readonly value: string }
-
-export interface Child {
-  readonly id: string
-  readonly at: string
-  readonly describes: string
-  readonly by?: string
-  readonly runs?: string
-  readonly body?: string
-  readonly writes?: string
-}
-
-export interface Stated {
-  readonly field: string
-  readonly said: string
-  readonly list: boolean
-  readonly map?: boolean
-  readonly boolean?: boolean
-  readonly worded?: boolean
-}
-
-export const mapped = (one: { readonly map?: boolean; readonly worded?: boolean }, said: string): boolean =>
-  one.map === true && !(one.worded === true && !said.includes('='))
-
-export const CARRIES: readonly string[] = ['cites', 'requires', 'takes', 'by', 'runs']
-
-export function ownAnswers(all: readonly Given[]): readonly Given[] {
-  const opens = new Set<string>(LISTS)
-  const at = all.findIndex((one) => opens.has(one.key))
-  return at === -1 ? all : all.slice(0, at)
-}
-
-export async function stating(
-  asks: readonly Asked[],
-  all: readonly Given[],
-  piped: boolean,
-  ask: (name: string, asks: string) => Promise<string>,
-  line: () => Promise<string | undefined>,
-  settled: readonly string[],
-): Promise<{ readonly stated: readonly Stated[]; readonly kids: ReadonlyMap<string, readonly Child[]> }> {
-  const own = ownAnswers(all)
-  const skip = new Set<string>([...settled, ...LISTS])
-  const stated: Stated[] = []
-  for (const one of asks) {
-    if (skip.has(one.at)) continue
-    const given = (piped ? (answer(own, one.at) ?? '') : await ask(one.at, prompted(one))).trim()
-    if (given === '') continue
-    stated.push({ field: one.at, said: given, list: one.list === true, map: one.map === true, boolean: one.boolean === true, worded: one.worded === true })
-  }
-
-  if (piped) return { stated, kids: childrenIn(all) }
-
-  const kids = new Map<string, readonly Child[]>()
-  for (const list of LISTS) {
-    if (!asks.some((one) => one.at === list)) continue
-    const found = await children(list, all, ask, line)
-    if (found.length > 0) kids.set(list, found)
-  }
-  return { stated, kids }
-}
-
-export function arrayValue(pad: string, key: string, said: string, found: readonly Child[] | undefined): string {
-  if (found === undefined || found.length === 0) return asList(said)
-  const lines = rowLines(pad, [], new Map([[key, found]]))
-  return ['[', ...lines.slice(1, -1), `${pad}]`].join('\n')
-}
-
-const BARE = /^[A-Za-z_$][A-Za-z0-9_$]*$/
-
-const NUMBER = /^-?\d+(?:\.\d+)?$/
-
-const nested = (held: Readonly<Record<string, unknown>>): string => {
-  const pairs = Object.entries(held).map(([key, value]) => {
-    const name = BARE.test(key) ? key : quoted(key)
-    if (typeof value === 'object' && value !== null) return `${name}: ${nested(value as Readonly<Record<string, unknown>>)}`
-    const said = String(value)
-    return `${name}: ${NUMBER.test(said) ? said : quoted(said)}`
-  })
-  return pairs.length === 0 ? '{}' : `{ ${pairs.join(', ')} }`
-}
-
-export const asMap = (said: string): string => {
-  const held: Record<string, unknown> = {}
-  for (const one of said.split(',').map((each) => each.trim()).filter((each) => each !== '')) {
-    const at = one.indexOf('=')
-    if (at < 1) {
-      refuse(
-        `\`${one}\` is one entry of a name-and-value field, and it states no value. Write each one as ` +
-          '`name=value`, separated by commas — `core=*` says that package at any version, and a dot in the name ' +
-          'nests it: `dark.background=colour-surface`. Nothing was written.',
-      )
-    }
-    const path = one.slice(0, at).trim().split('.')
-    const last = path[path.length - 1] ?? ''
-    let into = held
-    for (const step of path.slice(0, -1)) {
-      const next = into[step]
-      if (next !== undefined && (typeof next !== 'object' || next === null)) {
-        refuse(`\`${one}\` nests under \`${step}\`, and \`${step}\` is already given a value of its own. One or the other. Nothing was written.`)
-      }
-      if (next === undefined) into[step] = {}
-      into = into[step] as Record<string, unknown>
-    }
-    if (typeof into[last] === 'object' && into[last] !== null) {
-      refuse(`\`${one}\` gives \`${last}\` a value, and entries already nest under it. One or the other. Nothing was written.`)
-    }
-    into[last] = one.slice(at + 1).trim()
-  }
-  return nested(held)
-}
-
-export function gathered(all: readonly Given[], fields: readonly Field[]): readonly Given[] {
-  const maps = new Set(fields.filter((one) => one.map).map((one) => one.name))
-  const entries = new Map<string, { readonly at: number; readonly parts: string[] }>()
-  for (const one of all) {
-    const dot = one.key.indexOf('.')
-    if (dot === -1 || !maps.has(one.key.slice(0, dot))) continue
-    const head = one.key.slice(0, dot)
-    const held = entries.get(head) ?? { at: one.at, parts: [] }
-    held.parts.push(`${one.key.slice(dot + 1)}=${one.value}`)
-    entries.set(head, held)
-  }
-  const written = new Set<string>()
-  const out: Given[] = []
-  for (const one of all) {
-    const dot = one.key.indexOf('.')
-    const head = dot === -1 ? one.key : one.key.slice(0, dot)
-    if (dot === -1 || !entries.has(head)) {
-      out.push(one)
-      continue
-    }
-    if (written.has(head)) continue
-    written.add(head)
-    const held = entries.get(head)
-    out.push({ at: held?.at ?? one.at, key: head, value: (held?.parts ?? []).join(', ') })
-  }
-  return out
-}
-
-const asList = (said: string): string =>
-  `[${said
-    .split(',')
-    .map((one) => one.trim())
-    .filter((one) => one !== '')
-    .map(quoted)
-    .join(', ')}]`
-
-export const asBoolean = (said: string): string => {
-  const word = said.trim().toLowerCase()
-  if (word === 'yes' || word === 'y' || word === 'true') return 'true'
-  if (word === 'no' || word === 'n' || word === 'false') return 'false'
-  refuse(`\`${said}\` is not an answer to a yes-or-no field. Say yes or no. Nothing was written.`)
-}
-
-export function rowLines(
-  pad: string,
-  stated: readonly Stated[],
-  kids: ReadonlyMap<string, readonly Child[]>,
-): readonly string[] {
-  const kid = (one: Child): readonly string[] => [
-    `${pad}  {`,
-    `${pad}    id: ${quoted(one.id)},`,
-    `${pad}    at: ${quoted(one.at)},`,
-    `${pad}    describes: ${quoted(one.describes)},`,
-    ...(one.by === undefined || one.by === '' ? [] : [`${pad}    by: ${quoted(one.by)},`]),
-    ...(one.runs === undefined || one.runs === '' ? [] : [`${pad}    runs: ${quoted(one.runs)},`]),
-    `${pad}    version: 1,`,
-    `${pad}  },`,
-  ]
-  return [
-    ...stated.map(
-      (one) =>
-        `${pad}${one.field}: ${
-          mapped(one, one.said) ? asMap(one.said) : one.list ? asList(one.said) : one.boolean === true ? asBoolean(one.said) : quoted(one.said)
-        },`,
-    ),
-    ...[...kids].flatMap(([list, found]) => [`${pad}${list}: [`, ...found.flatMap(kid), `${pad}],`]),
-  ]
-}
-
-export function withChildren(row: string, lines: readonly string[]): string {
-  if (lines.length === 0) return row
-  const all = row.split('\n')
-  let at = all.length - 1
-  while (at >= 0 && (all[at] ?? '').trim() !== '},' && (all[at] ?? '').trim() !== '}') at -= 1
-  if (at < 0) {
-    refuse(
-      'the row just written has no closing brace on a line of its own, so what it declares has nowhere to go. ' +
-        'Nothing more was written, because adding the row and dropping its children quietly is the one outcome ' +
-        'nobody could see.',
-    )
-  }
-  return [...all.slice(0, at), ...lines, ...all.slice(at)].join('\n')
-}
-
-export function childrenIn(all: readonly Given[]): ReadonlyMap<string, readonly Child[]> {
-  const found = new Map<string, readonly Child[]>()
-  for (const list of LISTS) {
-    const each: Child[] = []
-    for (const group of scoped(all, list).each) {
-      const id = (answer(group, list) ?? '').trim()
-      if (id === '') continue
-      const at = (answer(group, 'at') ?? '').trim()
-      const describes = (answer(group, 'describes') ?? '').trim()
-      if (at === '' || describes === '') {
-        refuse(
-          `\`${list} ${id}\` names no ${at === '' ? 'file' : 'meaning'}. Every row says which file it is about and ` +
-            'what that file is, and one missing either is a row the next person cannot act on. Nothing more was written.',
-        )
-      }
-      const body = (answer(group, BODY) ?? '').trim()
-      const writes = (answer(group, WRITES) ?? '').trim()
-      each.push({
-        id,
-        at,
-        describes,
-        ...(writes === '' ? {} : { writes }),
-        ...(list === 'declares'
-          ? {}
-          : { by: (answer(group, 'by') ?? '').trim(), runs: (answer(group, 'runs') ?? '').trim() }),
-        ...(body === '' ? {} : { body }),
-      })
-    }
-    if (each.length > 0) found.set(list, each)
-  }
-  return found
-}
-
-export const BODIED: readonly string[] = ['declares', 'seeds']
-
-export const WRITTEN: readonly string[] = ['derives', 'seeds']
-
-export function seeding(kids: ReadonlyMap<string, readonly Child[]>, root: string): readonly string[] {
-  const said: string[] = []
-  for (const list of BODIED) {
-    for (const one of kids.get(list) ?? []) {
-      const into = join(root, one.at)
-      const there = existsSync(into)
-
-      if (one.body === undefined || one.body === '') {
-        said.push(
-          there
-            ? `${one.at} was already on disk, and the row now names it.`
-            : `${one.at} is declared and nothing is in it yet — write it with ` +
-              `\`${TYPED} edit ${one.at} --from <path>\`.`,
-        )
-        continue
-      }
-
-      if (there) {
-        said.push(
-          `${one.at} was already on disk, so the body you wrote was NOT put over it. Nothing was lost — ` +
-            `\`${TYPED} read ${one.at}\` prints what is there.`,
-        )
-        continue
-      }
-
-        writeFileSync(into, one.body.endsWith('\n') ? one.body : `${one.body}\n`, 'utf8')
-      said.push(`wrote ${one.at} with the body you gave it.`)
-    }
-  }
-  return said
-}
-
-const ASKED: Readonly<Record<string, string>> = {
-  declares: 'name each file a person writes that this one owns',
-  derives: 'name each file a command writes from this one, and the command that writes it',
-  seeds: 'name each file a command shapes here',
-}
-
-export async function children(
-  list: string,
-  all: readonly Given[],
-  ask: (name: string, asks: string) => Promise<string>,
-  line: () => Promise<string | undefined>,
-): Promise<readonly Child[]> {
-  const written = WRITTEN.includes(list)
-  const out: Child[] = []
-
-  const owed = (id: string, at: string, describes: string): void => {
-    if (at !== '' && describes !== '') return
-    refuse(
-      `\`${list} ${id}\` names no ${at === '' ? 'file' : 'meaning'}. Every row says which file it is about and what ` +
-        'that file is, and one missing either is a row the next person cannot act on. Nothing more was written.',
-    )
-  }
-
-  const bodies = [
-    ...(written ? [`${asFlag(WRITES)} is the generator's own body — the code that writes the template`] : []),
-    ...(BODIED.includes(list) ? [`${asFlag(BODY)} is the body of the file itself`] : []),
-  ]
-  stdout.write(
-    `\n  ${list} — ${ASKED[list] ?? ''}. ` +
-      (bodies.length === 0
-        ? ''
-        : `Each one takes ${bodies.length === 1 ? 'one body' : `${String(bodies.length)} bodies, and they are never the same text`}: ` +
-          `${bodies.join('; ')}. `) +
-      'A blank id ends the list.\n',
-  )
-  for (;;) {
-    const id = (await ask(list, `  ${list} — id, or blank to stop: `)).trim()
-    if (id === '') break
-    const at = (await ask('at', '    at — the file this names: ')).trim()
-    const describes = (await ask('describes', '    describes — what that file is, to somebody who has not opened it: ')).trim()
-    owed(id, at, describes)
-    const by = written ? (await ask('by', '    by — the command that writes it: ')).trim() : undefined
-    const runs = written ? (await ask('runs', '    runs — the command that catches it drifting: ')).trim() : undefined
-    const writes = written
-      ? await bodied(`the generator behind \`${by ?? 'that command'}\` — this is ${asFlag(WRITES)}`, '', false, all, line)
-      : undefined
-    const body = BODIED.includes(list)
-      ? await bodied(`${at} itself — this is ${asFlag(BODY)}`, '', false, all, line)
-      : undefined
-    out.push({
-      id,
-      at,
-      describes,
-      ...(written ? { by, runs } : {}),
-      ...(writes === undefined ? {} : { writes }),
-      ...(body === undefined ? {} : { body }),
-    })
-  }
-  return out
-}
-
-export async function bodied(
-  what: string,
-  shows: string,
-  piped: boolean,
-  all: readonly Given[],
-  line: () => Promise<string | undefined>,
-): Promise<string | undefined> {
-  const from = argv[argv.indexOf(FROM) + 1]
-  if (argv.includes(FROM) && from !== undefined && !from.startsWith('-')) {
-    try {
-      return refuse(`${FROM} seeds the body out of a file, and a file is not a receipt: nothing here checked it and no descent reached it. Give the body with ${asFlag(BODY)} on the command. Nothing was written.`)
-    } catch {
-      refuse(
-        `\`${FROM} ${from}\` names a file nothing could read, so there is no body to seed and nothing was ` +
-          `written. Write it first, then run this again — or drop ${FROM} and type the body when it is asked for.`,
-      )
-    }
-  }
-  if (piped) {
-    const said = answer(all, BODY)
-    return said === undefined || said.trim() === '' ? undefined : said
-  }
-  if (shows.trim() === '') stdout.write(`  body — write what goes in ${what}.\n`)
-  else {
-    stdout.write(`  body — what a ${what} is handed looks like this:\n`)
-    for (const one of shows.split('\n')) stdout.write(`    ${one}\n`)
-  }
-  stdout.write(
-    `  write yours, then a line holding only ${ENDS}. A first line of ${ENDS} leaves it unwritten, and\n` +
-      `  \`${TYPED} trials\` reports it unproven until somebody writes it.\n` +
-      `  Or give ${FROM} <path> instead and the file at that path is what gets seeded, which is the one\n` +
-      '  form that needs no terminal.\n',
-  )
-  const held: string[] = []
-  for (;;) {
-    const next = await line()
-    if (next === undefined || next.trim() === ENDS) break
-    held.push(next)
-  }
-  const written = held.join('\n').trim()
-  return written === '' ? undefined : written
-}
-
-export function only(
-  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-  allowed: readonly string[],
-  where: string,
-): void {
-  unasked(ownAnswers(given), allowed, where)
-}
-
-export function unasked(
-  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-  allowed: readonly string[],
-  where: string,
-): void {
-  for (const one of given) {
-    if (CARRIES.includes(one.key) || one.key === WRITES) continue
-    if (allowed.includes(one.key)) continue
-    refuse(
-      `${locate(one)} answers \`${one.key}\`, and ${where} takes ${allowed.map((each) => `\`${each}\``).join(', ')}. ` +
-        'Nothing was written.',
-    )
-  }
-}
-
-export function answer(
-  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-  key: string,
-): string | undefined {
-  const found = given.filter((one) => one.key === key)
-  if (found.length > 1) {
-    refuse(
-      `\`${key}\` is answered ${String(found.length)} times: ${found.map((one) => locate(one)).join(', ')}. ` +
-        'Nothing was written.',
-    )
-  }
-  const held = found[0]?.value
-  return held === undefined ? undefined : guarded(key, held)
-}
-
-export function accepted(
-  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-): string {
-  if (given.length === 0) return 'nothing was accepted before it'
-  return `accepted so far: ${given.map((one) => `${one.key} (${locate(one)})`).join(', ')}`
-}
-
-export function needed(
-  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-  key: string,
-  where: string,
-): string {
-  const held = answer(given, key)
-  if (held === undefined || held === '') {
-    refuse(`${where} states no \`${key}\`, and it is not optional. ${accepted(given)}. Nothing was written.`)
-  }
-  return held
-}
-
-export function wrapped(text: string, pad: string): readonly string[] {
-  const lines: string[] = []
-  let held = ''
-  for (const word of text.split(/\s+/).filter((one) => one !== '')) {
-    if (held !== '' && `${held} ${word}`.length > 92) {
-      lines.push(`${pad}${held}`)
-      held = word
-    } else held = held === '' ? word : `${held} ${word}`
-  }
-  if (held !== '') lines.push(`${pad}${held}`)
-  return lines
-}
-
-export function marked(parts: readonly string[]): string {
-  return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 6)
-}
-
-export interface Told {
-  readonly on: string
-  readonly said: string
-}
-
-export interface Declared {
-  readonly at: string
-  readonly list: string
-  readonly shape: string | undefined
-  readonly fields: readonly Field[]
-  readonly describes: string
-  readonly holds: number
-  readonly cites: readonly Told[]
-  readonly top: { readonly id: string; readonly describes: string } | undefined
-  readonly files?: string
-}
-
-const citesOf = (held: unknown): readonly Told[] =>
-  Array.isArray(held)
-    ? held.filter(
-        (one): one is Told =>
-          one !== null && typeof one === 'object' && typeof (one as Told).on === 'string' && typeof (one as Told).said === 'string',
-      )
-    : []
-
-const NAMED_SHAPE = /^[A-Za-z_][A-Za-z0-9_]*$/
-
-const rowLike = (one: unknown): one is Row =>
-  one !== null && typeof one === 'object' && typeof (one as Row).id === 'string' && typeof (one as Row).describes === 'string'
-
-const kinded = (shape: string): string =>
-  shape
-    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-    .toLowerCase()
-
-const oneOf = (list: string): string => {
-  const word = list.toLowerCase().split('_').join('-')
-  return word.endsWith('s') ? word.slice(0, -1) : word
-}
-
-export async function declared(tree: Tree): Promise<ReadonlyMap<string, Declared>> {
-  const found = new Map<string, Declared>()
-  const walked = new Set<string>()
-
-  const says = new Map<string, string>()
-
-  const parents = new Map<string, Row & { readonly cites?: unknown }>()
-
-  const sheetsBy = new Map<string, Set<string>>()
-
-  const meant = (shape: string | undefined, sheetAt: string): string => {
-    if (shape === undefined) return ''
-    try {
-      const named = shapesNamed()
-      for (const at of named.get(shape) ?? []) {
-        if (at === sheetAt) continue
-        let others = 0
-        for (const [, files] of named) if (files.includes(at)) others += 1
-        if (others !== 1) continue
-        const told = says.get(at)
-        if (told !== undefined && told !== '') return told
-      }
-    } catch {
-      return ''
-    }
-    return ''
-  }
-
-  const sheet = (one: unknown): string | undefined => {
-    const at = (one as Row | undefined)?.at
-    return typeof at === 'string' && at.startsWith(`${tree.name}/`) && at.endsWith('.ts') ? at : undefined
-  }
-
-  const walk = async (at: string, top: Declared['top']): Promise<void> => {
-    if (walked.has(at)) return
-    walked.add(at)
-
-    let read: Record<string, unknown>
-    try {
-      read = valuesIn(readFileSync(join(tree.at, at))) as Record<string, unknown>
-    } catch {
-      return
-    }
-
-    for (const [name, value] of Object.entries(read)) {
-      const node = value as
-        | { readonly id?: unknown; readonly describes?: unknown; readonly cites?: unknown; readonly declares?: unknown; readonly holds?: unknown; readonly files?: unknown }
-        | undefined
-      const lists: readonly { readonly list: string; readonly rows: readonly unknown[] }[] = Array.isArray(value)
-        ? [{ list: name, rows: value }]
-        : (['holds', 'declares'] as const).flatMap((list) => {
-            const rows = node?.[list]
-            return Array.isArray(rows) ? [{ list, rows }] : []
-          })
-      const rowed = lists.filter((one) => one.rows.every(rowLike))
-      const first = rowed[0]
-      if (first === undefined) continue
-
-      if (Array.isArray(value)) {
-        const noun = oneOf(name)
-        sheetsBy.set(name, new Set([...(sheetsBy.get(name) ?? []), at]))
-        if (!found.has(noun)) {
-          found.set(noun, {
-            at,
-            list: name,
-            shape: listShape(at, name),
-            fields: listFields(at, name),
-            describes: '',
-            holds: first.rows.length,
-            cites: [],
-            top,
-          })
-        }
-      } else if (at !== within(tree.at, tree.root)) {
-        const files = typeof node?.files === 'string' && node.files !== '' ? node.files : undefined
-        const held = files === undefined ? first : (rowed.find((one) => one.list === 'declares') ?? first)
-        const kind = listShape(at, held.list)
-        const noun =
-          kind === undefined || (kind === 'Threaded' && files === undefined)
-            ? undefined
-            : kind !== 'Threaded' && NAMED_SHAPE.test(kind)
-              ? kinded(kind)
-              : typeof node?.id === 'string' && node.id !== ''
-                ? node.id
-                : undefined
-        if (typeof noun === 'string' && noun !== '' && !found.has(noun)) {
-          found.set(noun, {
-            at,
-            list: held.list,
-            shape: kind,
-            fields: listFields(at, held.list),
-            describes: typeof node?.describes === 'string' ? node.describes : '',
-            holds: held.rows.length,
-            cites: citesOf(node?.cites),
-            top,
-            ...(files === undefined ? {} : { files }),
-          })
-        }
-      }
-      for (const one of rowed.flatMap((each) => each.rows)) {
-        const where = (one as Row).at
-        const told = (one as Row).describes
-        if (typeof where === 'string' && typeof told === 'string' && !says.has(where)) says.set(where, told)
-        const next = sheet(one)
-        if (next === undefined) continue
-        const row = one as Row & { readonly cites?: unknown }
-        if (!parents.has(next)) parents.set(next, row)
-        await walk(next, top ?? { id: typeof row.id === 'string' ? row.id : '', describes: typeof row.describes === 'string' ? row.describes : '' })
-      }
-    }
-  }
-
-  await walk(within(tree.at, tree.root), undefined)
-
-  const out = new Map<string, Declared>()
-  for (const [noun, one] of found) {
-    const parent = parents.get(one.at)
-    const said = typeof parent?.describes === 'string' ? parent.describes : ''
-    const owned = (sheetsBy.get(one.list)?.size ?? 0) <= 1
-    out.set(noun, {
-      ...one,
-      describes: one.describes !== '' ? one.describes : owned && said !== '' ? said : meant(one.shape, one.at),
-      cites: one.cites.length > 0 ? one.cites : citesOf(parent?.cites),
-    })
-  }
-  return out
-}
-
-export function nouns(all: readonly Row[], verb = 'create'): ReadonlyMap<string, string> {
-  const found = new Map<string, string>()
-  const opens = `thread ${verb} `
-  for (const one of all) {
-    const by = one.by
-    if (typeof by !== 'string' || !by.startsWith(opens)) continue
-    const word = by.slice(opens.length).trim()
-    if (word === '' || typeof one.at !== 'string') continue
-    const already = found.get(word)
-    if (already !== undefined && already !== one.at) {
-      refuse(
-        `two rows both state \`by: 'thread ${verb} ${word}'\` — ${already} and ${one.at} — so which one answers a ` +
-          `${word} is whichever was written first. One noun, one file.`,
-      )
-    }
-    found.set(word, one.at)
-  }
-  return found
-}
-
-export function asking(
-  held: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-): {
-  readonly piped: boolean
-  readonly ask: (
-    key: string,
-    question: string,
-    from?: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-  ) => Promise<string>
-
-  readonly line: () => Promise<string | undefined>
-  readonly shut: () => void
-} {
-  const piped = answered()
-  const rl = piped ? undefined : createInterface({ input: stdin, output: stdout })
-  const lines = rl?.[Symbol.asyncIterator]()
-  return {
-    piped,
-    ask: async (key, question, from = held) => {
-      const already = answer(from, key)
-      if (already !== undefined) return guarded(key, already)
-      if (piped) return ''
-      stdout.write(question)
-      const next = await lines?.next()
-      return next === undefined || next.done === true ? '' : guarded(key, next.value.trim())
-    },
-    line: async () => {
-      const next = await lines?.next()
-      return next === undefined || next.done === true ? undefined : next.value
-    },
-    shut: () => rl?.close(),
-  }
-}
-
-const ANSWERS = '--answers'
-
-function fromFile(): string | undefined {
-  const at = argv.indexOf(ANSWERS)
-  if (at === -1) return undefined
-  const path = argv[at + 1]
-  if (path === undefined || path.startsWith('-')) {
-    refuse(`${ANSWERS} needs the path of a file holding the answers, one \`name: value\` to a line.`)
-  }
-  try {
-    return readFileSync(path, 'utf8')
-  } catch {
-    refuse(`${ANSWERS} names ${path}, and there is no file there to read the answers from.`)
-  }
-}
-
-const OWN = '--own'
-const CHECK = '--check'
-
-function flagged(): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
-  const found: { at: number; key: string; value: string }[] = []
-  for (let at = 2; at < argv.length; at += 1) {
-    const one = argv[at] ?? ''
-    if (
-      !one.startsWith('--') ||
-      one === RECEIPT ||
-      one === ANSWERS ||
-      one === OWN ||
-      one === CHECK ||
-      one === FROM ||
-      one === CHAINED
-    )
-      continue
-    const value = argv[at + 1]
-    if (value === undefined || value.startsWith('-')) {
-      refuse(`\`${one}\` was given no value — an answer given as a flag is \`${one} value\`, with the value right after it.`)
-    }
-    found.push({ at: 0, key: one.slice(2), value })
-    at += 1
-  }
-  return found
-}
-
-export function answered(): boolean {
-  return argv.includes(ANSWERS) || stdin.isTTY !== true
-}
-
-export function given(): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
-  const flags = flagged()
-  const fromFlag = new Set(flags.map((one) => one.key))
-
-  const held = fromFile()
-  if (held !== undefined) return read([...flags, ...parsed(held).filter((one) => !fromFlag.has(one.key))])
-
-  const text = handed()
-  if (text === undefined) return read(flags)
-
-  return read([...flags, ...parsed(text).filter((one) => !fromFlag.has(one.key))])
-}
-
-const FROM_END = '-from'
-
-function read(
-  all: readonly { readonly at: number; readonly key: string; readonly value: string }[],
-): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
-  return all.map((one) => {
-    if (!one.key.endsWith(FROM_END)) return one
-    const key = one.key.slice(0, -FROM_END.length)
-    if (key === '') return one
-    if (all.some((each) => each.key === key)) {
-      refuse(
-        `\`${asFlag(key)}\` and \`${asFlag(one.key)}\` both answer ${key}, and they do not have to agree. ` +
-          'Give one of them. Nothing was written.',
-      )
-    }
-    try {
-      return refuse(`${asFlag(key)}${FROM_END} takes what this writes out of a file, and a file is not a receipt: nothing here checked it and no descent reached it. Give the text on the command with ${asFlag(key)}. Nothing was written.`)
-    } catch {
-      refuse(
-        `\`${asFlag(one.key)} ${one.value}\` names a file nothing could read, so there is no ${key} to write and ` +
-          `nothing was written. Write that file first, or give the text itself with ${asFlag(key)}.`,
-      )
-    }
-  })
-}
-
-let stood: string | undefined
-let taken = false
-
-export function handed(): string | undefined {
-  if (taken) return stood
-  taken = true
-  if (stdin.isTTY === true) return undefined
-  try {
-    stood = readFileSync(0, 'utf8')
-  } catch {
-    stood = undefined
-  }
-  return stood
-}
-
-export const TYPED = 'thread'
-
-export const CARRIED: readonly { readonly verb: string; readonly typed: string; readonly does: string }[] = [
-  { verb: 'read', typed: `${TYPED} read <row>`, does: 'prints every field a row states' },
-  { verb: 'edit', typed: `${TYPED} edit <row> --<field> <value>`, does: 'changes any field it was declared with' },
-  { verb: 'remove', typed: `${TYPED} edit <row> --remove`, does: 'takes the row out of the tree' },
-]
-
-const elsewhere = CARRIED.map((one) => `\`${one.typed}\` ${one.does}`)
-
-export function wordsIn(offered: readonly string[]): readonly string[] {
-  const values = new Set([argv[argv.indexOf(RECEIPT) + 1], argv[argv.indexOf(ANSWERS) + 1], ...flagged().map((one) => one.value)])
-  const words = argv.slice(2).filter((one) => !one.startsWith('-') && !values.has(one))
-  const first = words[0]
-  if (offered.length === 0 || first === undefined || offered.includes(first)) return words
-  const carried = CARRIED.find((one) => one.verb === first)
-  if (carried !== undefined) {
-    refuse(
-      `\`${first}\` is not a word this command answers, because every row in this tree has it and it is ` +
-        `answered in one place rather than once per thing. \`${carried.typed}\` ${carried.does}, whatever ` +
-        'declared it, and it finds the row by its id or by the mark printed beside it. Nothing was written, ' +
-        'and nothing was read.',
-    )
-  }
-  refuse(
-    `\`${first}\` is not one of the things this command does. It does: ${offered.join(', ')}. ` +
-      `Reading, changing and removing a row are done elsewhere, because they reach every row rather than ` +
-      `only this one's: ${elsewhere.join('; ')}. ` +
-      'Run it with none of those to see what already exists and exactly what each of them asks for. ' +
-      'Nothing was written, and nothing was read.',
-  )
-}
-
-const ANNOUNCED: readonly { readonly what: string; readonly pattern: RegExp }[] = [
-  { what: 'a Stripe secret key', pattern: /\bsk_(?:live|test)_[A-Za-z0-9]{16,}/ },
-  { what: 'a Stripe restricted key', pattern: /\brk_(?:live|test)_[A-Za-z0-9]{16,}/ },
-  { what: 'a GitHub token', pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/ },
-  { what: 'a GitHub personal access token', pattern: /\bgithub_pat_[A-Za-z0-9_]{30,}/ },
-  { what: 'an AWS access key id', pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/ },
-  { what: 'a Slack token', pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}/ },
-  { what: 'an OpenAI key', pattern: /\bsk-[A-Za-z0-9_-]{32,}/ },
-  { what: 'an Anthropic key', pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
-  { what: 'a Google API key', pattern: /\bAIza[A-Za-z0-9_-]{35}\b/ },
-  { what: 'a JSON web token', pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
-  { what: 'a private key', pattern: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
-  { what: 'a password inside a connection string', pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s:/@]{6,}@/ },
-]
-
-const ASSIGNED = /\b(?:secret|password|passwd|api_?key|apikey|access_?token|auth_?token|private_?key|client_?secret|credential)s?\b\s*[:=]\s*(['"`])([^'"`\n]{16,})\1/gi
-
-const MIXED = /^(?=.*[a-z])(?=.*[A-Z0-9])[A-Za-z0-9_+/=.-]{16,}$/
-
-const NOT = [
-  /^(?:sec|pub)_[a-z0-9_]+$/,
-  /^\$\{/,
-  /^(?:x{3,}|X{3,}|\.{3,}|<[^>]+>|change[-_]?me|your[-_]|example|placeholder|redacted|todo|test|dummy|sample|fake|dGhpcyBpcyBub3QgYSBzZWNyZXQ)/i,
-]
-
-function guarded(key: string, value: string): string {
-  const carried = credentialIn(value)
-  if (carried !== undefined) {
-    refuse(
-      `\`${key}\` holds ${carried}. A credential is never typed into a declaration — not in a describes, not ` +
-        'anywhere but a secret. Declare it with `thread create secret`, name it where the thing that needs it ' +
-        'states what it requires, and it is resolved through the vault at the moment it is used and never ' +
-        'written down. Nothing was written.',
-    )
-  }
-  const address = ADDRESS.exec(value)
-  if (address !== null) {
-    refuse(
-      `\`${key}\` holds the address \`${address[0]}\`. An address is a secret here, not a sentence — the same ` +
-        'thing behind another host is another environment, and one written into a declaration is one nothing ' +
-        'can point elsewhere. Declare it with `thread create secret` and name it where the thing that needs it ' +
-        'states what it requires. Nothing was written.',
-    )
-  }
-  return value
-}
-
-const ADDRESS = /\b[a-z][a-z0-9+.-]*:\/\/[^\s'"`)]+/i
-
-export function credentialIn(text: string): string | undefined {
-  for (const one of ANNOUNCED) {
-    if (one.pattern.test(text)) return one.what
-  }
-  for (const found of text.matchAll(ASSIGNED)) {
-    const value = found[2] ?? ''
-    if (NOT.some((each) => each.test(value))) continue
-    if (!MIXED.test(value)) continue
-    return `a ${(found[0].split(/[:=]/)[0] ?? '').trim()} written down as a literal ${String(value.length)} characters long`
-  }
-  return undefined
-}