@prestack/thread 0.1.21 → 0.1.23

package/dist/core/descend.ts

@@ -1,1185 +0,0 @@
-import { starts } from '../integrations/cli.ts'
-import { attached, beyond, existsSync, here as answering, kind, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, type Kind } from '../integrations/disk.ts'
-import { dirname, join, relative, resolve } from 'node:path'
-
-import ts from 'typescript'
-
-import type { Finding } from './finding.ts'
-import { SHAPED, ignored } from './init.ts'
-import { ORGANISATION, installed } from './scope.ts'
-import { findTree } from './tree.ts'
-
-const BUILT: ReadonlySet<string> = new Set(
-  ignored()
-    .split('\n')
-    .map((one) => one.trim())
-    .filter((one) => one.endsWith('/'))
-    .map((one) => one.replace(/\/+$/, '')),
-)
-
-const TREE_AT = ((): ReturnType<typeof findTree> | undefined => {
-  try {
-    return findTree()
-  } catch {
-    return undefined
-  }
-})()
-
-const NOWHERE = '/this-app-has-no-tree'
-
-function rooted(): void {
-  if (TREE_AT === undefined) findTree()
-}
-
-export const ROOT = TREE_AT?.at ?? NOWHERE
-export const TREE = `${TREE_AT?.name ?? NOWHERE}/`
-export const THREAD_AT = `${TREE_AT?.name ?? NOWHERE}/thread.ts`
-
-let ignores: readonly string[] | undefined
-let readIgnores = false
-
-function ownIgnores(): readonly string[] | undefined {
-  if (readIgnores) return ignores
-  readIgnores = true
-  if (!attached() && starts('git', ['rev-parse', '--is-inside-work-tree'], { at: ROOT }).ok) {
-    return ignores
-  }
-  try {
-    ignores = readFileSync(join(ROOT, '.gitignore'), 'utf8')
-      .split('\n')
-      .map((one) => one.trim())
-      .filter((one) => one !== '' && !one.startsWith('#') && !one.startsWith('!'))
-      .map((one) => one.replace(/^\/+|\/+$/g, ''))
-      .filter((one) => one !== '' && !one.includes('*'))
-  } catch {
-    ignores = []
-  }
-  return ignores
-}
-
-const asked = new Map<string, boolean>()
-
-export function unkept(at: string): boolean {
-  const held = asked.get(at)
-  if (held !== undefined) return held
-  const own = ownIgnores()
-  const found =
-    own === undefined
-      ? starts('git', ['check-ignore', '-q', '--', at], { at: ROOT }).ok
-      : own.some((one) => at === one || at.startsWith(`${one}/`) || at.split('/').includes(one))
-  asked.set(at, found)
-  return found
-}
-
-export const LISTS = ['declares', 'derives', 'seeds'] as const
-
-export const ROW_LISTS = [...LISTS, 'holds'] as const
-
-const SOURCE = /\.(ts|tsx|mts|cts)$/
-const RUNNER = /^(?:pnpm|npm|yarn) (?:run )?([\w:.-]+)/
-
-export interface Row {
-  readonly at?: string
-  readonly id?: string
-  readonly describes?: string
-  readonly by?: string
-  readonly runs?: string
-
-  readonly requires?: readonly string[]
-  readonly takes?: readonly string[]
-
-  readonly type: string
-  readonly shape?: ts.Type
-  readonly fields: ReadonlyMap<string, ts.Expression>
-  readonly where: string
-}
-
-export interface Pass {
-
-  readonly threaded: ReadonlyMap<
-    string,
-    readonly { readonly list: 'declares' | 'derives' | 'seeds'; readonly by: string; readonly row: Row }[]
-  >
-  readonly mentioned: ReadonlyMap<string, readonly string[]>
-  readonly derived: ReadonlyMap<string, Row>
-
-  readonly stated: ReadonlyMap<string, Row>
-  readonly coined: ReadonlyMap<string, { readonly said: readonly string[]; readonly under: string; readonly from: readonly string[] }>
-  readonly broken: readonly Finding[]
-  readonly findings: readonly Finding[]
-  readonly declarations: number
-  readonly rows: number
-  readonly sources: readonly string[]
-}
-
-export type { Finding }
-
-export function under(pass: Pass, id: string, root: string, seen: Set<string> = new Set()): boolean {
-  if (id === root) return true
-  if (seen.has(id)) return false
-  seen.add(id)
-  return (pass.coined.get(id)?.from ?? []).some((one) => under(pass, one, root, seen))
-}
-
-function here(path: string): string {
-  return relative(ROOT, path).split('\\').join('/')
-}
-
-const CANONICAL = 'threads/'
-
-const BESIDE = /^\.\//
-
-function settle(at: string, where: string): string {
-  if (BESIDE.test(at)) return here(resolve(ROOT, dirname(where), at.slice(2)))
-  if (at.startsWith(CANONICAL)) return here(resolve(ROOT, TREE, at.slice(CANONICAL.length)))
-  return here(resolve(ROOT, at))
-}
-
-function itself(at: string): string {
-  try {
-    return realpathSync(resolve(ROOT, at))
-  } catch {
-    return resolve(ROOT, at)
-  }
-}
-
-function walk(dir: string, out: string[]): string[] {
-  let entries: readonly string[]
-  try {
-    entries = readdirSync(dir)
-  } catch {
-    return out
-  }
-  for (const name of [...entries].sort()) {
-    if (name === '.git' || BUILT.has(name)) continue
-    const path = join(dir, name)
-    let held
-    try {
-      held = statSync(path)
-    } catch {
-      continue
-    }
-    if (held.isDirectory()) walk(path, out)
-    else out.push(here(path))
-  }
-  return out
-}
-
-let scanned: readonly string[] | undefined
-
-export function sources(): readonly string[] {
-  rooted()
-  scanned ??= walk(ROOT, []).sort()
-  return scanned
-}
-
-function imported(program: ts.Program): readonly string[] {
-  const under = `node_modules/${ORGANISATION}/`
-  return program
-    .getSourceFiles()
-    .map((one) => here(one.fileName))
-    .filter((one) => one.includes(under))
-    .sort()
-}
-
-const FALLBACK: ts.CompilerOptions = {
-  target: ts.ScriptTarget.Latest,
-  module: ts.ModuleKind.ESNext,
-  moduleResolution: ts.ModuleResolutionKind.Bundler,
-  jsx: ts.JsxEmit.ReactJSX,
-  strict: true,
-  allowImportingTsExtensions: true,
-  allowJs: true,
-  resolveJsonModule: true,
-}
-
-const CONFIGS = ['tsconfig.json', 'tsconfig.base.json'] as const
-
-const INVARIANT: ts.CompilerOptions = {
-  noEmit: true,
-  noUnusedLocals: true,
-  skipLibCheck: true,
-  allowImportingTsExtensions: true,
-  allowJs: true,
-  jsx: ts.JsxEmit.ReactJSX,
-}
-
-const NEVER: readonly string[] = ['node_modules', 'bower_components', 'jspm_packages']
-
-interface Wanted {
-  readonly under: string
-  readonly ending: string
-}
-
-function bounds(from: string, one: string): Wanted {
-  const star = one.indexOf('*')
-  if (star === -1) return { under: resolve(from, one), ending: '' }
-  const head = one.slice(0, star)
-  const cut = head.lastIndexOf('/')
-  const tail = one.slice(star)
-  const dot = tail.lastIndexOf('.')
-  const end = dot === -1 ? '' : tail.slice(dot)
-  return {
-    under: resolve(from, cut === -1 ? '' : head.slice(0, cut)),
-    ending: end.includes('/') || end.includes('*') ? '' : end,
-  }
-}
-
-function wanted(at: string, only: readonly Wanted[]): boolean {
-  if (only.length === 0) return true
-  return only.some((one) => (at === one.under || at.startsWith(`${one.under}/`)) && at.endsWith(one.ending))
-}
-
-function listing(at: string, take: readonly string[], skip: readonly string[], only: readonly Wanted[], deep: number): readonly string[] {
-  const found: string[] = []
-  if (deep < 0 || !existsSync(at)) return found
-  for (const one of readdirSync(at, { withFileTypes: true })) {
-    const full = join(at, one.name)
-    if (skip.some((each) => full === each || full.startsWith(`${each}/`))) continue
-    if (one.isDirectory()) {
-      if (NEVER.includes(one.name)) continue
-      found.push(...listing(full, take, skip, only, deep - 1))
-    } else if (take.some((each) => one.name.endsWith(each)) && wanted(full, only)) {
-      found.push(full)
-    }
-  }
-  return found
-}
-
-function parsing(from: string): ts.ParseConfigHost {
-  return {
-    useCaseSensitiveFileNames: true,
-    fileExists: (at) => !beyond(at) && existsSync(at),
-    readFile: (at) => {
-      try {
-        return readFileSync(at)
-      } catch {
-        return undefined
-      }
-    },
-    readDirectory: (at, take, skip, only, deep) =>
-      listing(
-        at,
-        take,
-        (skip ?? []).map((one) => resolve(from, one.endsWith('/**') ? one.slice(0, -3) : one)),
-        only.map((one) => bounds(from, one)),
-        deep ?? Number.MAX_SAFE_INTEGER,
-      ),
-  }
-}
-
-export function configured(): { readonly options: ts.CompilerOptions; readonly from: string; readonly trouble?: string } {
-  for (const name of CONFIGS) {
-    const at = join(ROOT, name)
-    if (!existsSync(at)) continue
-
-    const host = parsing(ROOT)
-    const held = ts.readConfigFile(at, host.readFile)
-    if (held.error !== undefined) {
-      return {
-        options: { ...FALLBACK, ...INVARIANT },
-        from: '',
-        trouble: `${name} is there and cannot be read: ${ts.flattenDiagnosticMessageText(held.error.messageText, ' ')}`,
-      }
-    }
-
-    const parsed = ts.parseJsonConfigFileContent(held.config as object, host, dirname(at))
-    const complained = parsed.errors[0]
-    if (complained !== undefined) {
-      return {
-        options: { ...FALLBACK, ...INVARIANT },
-        from: '',
-        trouble: `${name} is there and states no options this gate can use: ${ts.flattenDiagnosticMessageText(complained.messageText, ' ')}`,
-      }
-    }
-
-    return { options: { ...parsed.options, ...INVARIANT }, from: name }
-  }
-  return { options: { ...FALLBACK, ...INVARIANT }, from: '' }
-}
-
-const libraries = new Map<string, ReturnType<ts.CompilerHost['getSourceFile']>>()
-
-const DEPENDENCIES = '/node_' + 'modules/'
-
-export function hosting(options: ts.CompilerOptions): ts.CompilerHost {
-  const host = ts.createCompilerHost(options, true)
-  const lib = host.getDefaultLibLocation?.()
-  const settings = JSON.stringify(options)
-  const toolchain = (at: string): boolean => lib !== undefined && (at === lib || at.startsWith(`${lib}/`))
-  const seen = (at: string): Kind => (beyond(at) ? 'none' : kind(at))
-  return {
-    ...host,
-    getCurrentDirectory: () => ROOT,
-    fileExists: (at) => (toolchain(at) ? host.fileExists(at) : seen(at) === 'file'),
-    directoryExists: (at) => (toolchain(at) ? (host.directoryExists?.(at) ?? false) : seen(at) === 'folder'),
-    readFile: (at) => (toolchain(at) ? host.readFile(at) : seen(at) === 'file' ? readFileSync(at) : undefined),
-    getSourceFile: (at, version) => {
-      const lasting = toolchain(at) ? true : at.includes(DEPENDENCIES)
-      const key = settings + at + JSON.stringify(version)
-      if (lasting && libraries.has(key)) return libraries.get(key)
-      const made = toolchain(at)
-        ? host.getSourceFile(at, version)
-        : seen(at) === 'file'
-          ? ts.createSourceFile(at, readFileSync(at), version, true)
-          : undefined
-      if (lasting) libraries.set(key, made)
-      return made
-    },
-    getDirectories: (at) =>
-      seen(at) === 'folder' ? readdirSync(at, { withFileTypes: true }).filter((one) => one.isDirectory()).map((one) => one.name) : [],
-    realpath: (at) => (toolchain(at) ? (host.realpath?.(at) ?? at) : realpathSync(at)),
-    writeFile: (at, said) => {
-      writeFileSync(at, said)
-    },
-  }
-}
-
-let built: { program: ts.Program; checker: ts.TypeChecker } | undefined
-
-function compiled(): { program: ts.Program; checker: ts.TypeChecker } {
-  rooted()
-  if (built !== undefined) return built
-  const roots = [THREAD_AT, ...sources()].filter((one) => SOURCE.test(one)).map((one) => resolve(ROOT, one))
-  const options = configured().options
-  const program = ts.createProgram([...new Set(roots)], options, hosting(options))
-  built = { program, checker: program.getTypeChecker() }
-  return built
-}
-
-export function uncompiled(): readonly Finding[] {
-  const { program } = compiled()
-  const found: Finding[] = []
-  const INSTALLED = 'node_' + 'modules'
-  for (const file of program.getSourceFiles()) {
-    if (file.isDeclarationFile) continue
-    const at = here(file.fileName)
-    if (at.startsWith('..') || at.split('/').includes(INSTALLED)) continue
-    for (const one of [...program.getSyntacticDiagnostics(file), ...program.getSemanticDiagnostics(file)]) {
-      const start = one.start === undefined ? undefined : file.getLineAndCharacterOfPosition(one.start)
-      found.push({
-        file: at,
-        at: start === undefined ? undefined : { line: start.line + 1, column: start.character + 1 },
-        detail: `will not compile — TS${String(one.code)}: ${ts.flattenDiagnosticMessageText(one.messageText, ' ')}`,
-        instead:
-          'fix the type error. Nothing in this tree is built, served or gated while a file it names does not compile, and every other surface here reads the same program',
-      })
-    }
-  }
-  return found
-}
-
-function threadedType(checker: ts.TypeChecker, program: ts.Program): ts.Type | undefined {
-  const root = program.getSourceFile(resolve(ROOT, THREAD_AT))
-  if (root === undefined) return undefined
-  for (const statement of root.statements) {
-    if (!ts.isImportDeclaration(statement)) continue
-    const bindings = statement.importClause?.namedBindings
-    if (bindings === undefined || !ts.isNamedImports(bindings)) continue
-    for (const one of bindings.elements) {
-      const symbol = checker.getSymbolAtLocation(one.name)
-      if (symbol === undefined) continue
-      const real = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol
-      if (real.name === 'Threaded') return checker.getDeclaredTypeOfSymbol(real)
-    }
-  }
-  return undefined
-}
-
-const source = new Map<string, string | undefined>()
-
-export function read(at: string): string | undefined {
-  if (source.has(at)) return source.get(at)
-  let text: string | undefined
-  try {
-    text = readFileSync(resolve(ROOT, at), 'utf8')
-  } catch {
-    text = undefined
-  }
-  source.set(at, text)
-  return text
-}
-
-const shapes = new WeakMap<object, ReadonlyMap<string, readonly string[]>>()
-
-export function shapesNamed(): ReadonlyMap<string, readonly string[]> {
-  const held = compiled()
-  const known = shapes.get(held)
-  if (known !== undefined) return known
-  const { program, checker } = held
-  const shape = threadedType(checker, program)
-  const found = new Map<string, string[]>()
-  if (shape === undefined) return found
-  for (const at of [...sources(), ...imported(program)]) {
-    if (!SOURCE.test(at)) continue
-    const file = program.getSourceFile(resolve(ROOT, at))
-    if (file === undefined) continue
-    for (const statement of file.statements) {
-      if (!ts.isInterfaceDeclaration(statement) && !ts.isTypeAliasDeclaration(statement)) continue
-      if ((statement.typeParameters ?? []).length > 0) continue
-      const symbol = checker.getSymbolAtLocation(statement.name)
-      if (symbol === undefined) continue
-      const shown = (statement.modifiers ?? []).some((one) => one.kind === ts.SyntaxKind.ExportKeyword)
-      if (!shown && statement.name.text !== 'Threaded') continue
-      const held = ts.isInterfaceDeclaration(statement)
-        ? checker.getDeclaredTypeOfSymbol(symbol)
-        : checker.getTypeAtLocation(statement.name)
-      const named = statement.name.text
-      const shadows = named === 'Threaded'
-      const kind = elementOf(checker, held)
-      if (!shadows && (kind.flags & ts.TypeFlags.Never) !== 0) continue
-      if (!shadows && !checker.isTypeAssignableTo(kind, shape)) continue
-      const where = found.get(named) ?? []
-      const real = itself(at)
-      if (where.some((one) => itself(one) === real)) continue
-      found.set(named, [...where, at])
-    }
-  }
-  shapes.set(held, found)
-  return found
-}
-
-export function threading(): ReadonlySet<string> {
-  return new Set(['Threaded', ...shapesNamed().keys()])
-}
-
-export function shapeFields(
-  named: string,
-  inside?: string,
-): readonly { readonly name: string; readonly required: boolean; readonly list: boolean; readonly map: boolean; readonly worded: boolean; readonly guide: string; readonly record: readonly string[]; readonly objects: boolean }[] {
-  const { program, checker } = compiled()
-  for (const at of [...sources(), ...imported(program)]) {
-    if (!SOURCE.test(at)) continue
-    if (inside !== undefined && !at.split('\\').join('/').endsWith(inside)) continue
-    const file = program.getSourceFile(resolve(ROOT, at))
-    if (file === undefined) continue
-    for (const statement of file.statements) {
-      if (!ts.isInterfaceDeclaration(statement) && !ts.isTypeAliasDeclaration(statement)) continue
-      if (statement.name.text !== named) continue
-      const symbol = checker.getSymbolAtLocation(statement.name)
-      if (symbol === undefined) continue
-      const held = ts.isInterfaceDeclaration(statement)
-        ? checker.getDeclaredTypeOfSymbol(symbol)
-        : checker.getTypeAtLocation(statement.name)
-      const mapped = (kind: ts.Type): boolean =>
-          (kind.isUnion() ? kind.types : [kind]).some(
-            (each) =>
-              (each.flags & ts.TypeFlags.StringLike) === 0 &&
-              checker.getIndexTypeOfType(each, ts.IndexKind.Number) === undefined &&
-              checker.getIndexTypeOfType(each, ts.IndexKind.String) !== undefined,
-          )
-        const listed = (kind: ts.Type): boolean =>
-        (kind.isUnion() ? kind.types : [kind]).some(
-          (each) =>
-              (each.flags & ts.TypeFlags.StringLike) === 0 &&
-              checker.getIndexTypeOfType(each, ts.IndexKind.Number) !== undefined,
-        )
-      return checker.getPropertiesOfType(held).map((one) => {
-        const kind = checker.getTypeOfSymbolAtLocation(one, statement)
-        return {
-          name: one.getName(),
-          required: (one.flags & ts.SymbolFlags.Optional) === 0,
-          list: listed(kind),
-          map: mapped(kind),
-          worded: (kind.isUnion() ? kind.types : [kind]).some((each) => (each.flags & ts.TypeFlags.StringLike) !== 0),
-          guide: ts.displayPartsToString(one.getDocumentationComment(checker)).trim(),
-          record: recordOf(checker, kind),
-          objects: objectsOf(checker, kind),
-        }
-      })
-    }
-  }
-  return []
-}
-
-export interface Field {
-  readonly name: string
-  readonly required: boolean
-  readonly list: boolean
-  readonly map: boolean
-  readonly boolean: boolean
-  readonly worded: boolean
-  readonly guide: string
-  readonly record: readonly string[]
-  readonly objects: boolean
-}
-
-function elementAt(at: string, list: string, within?: number): { readonly type: ts.Type; readonly node: ts.Node } | undefined {
-  const { program, checker } = compiled()
-  const file = program.getSourceFile(resolve(ROOT, at))
-  if (file === undefined) return undefined
-  const threaded = threadedType(checker, program)
-
-  let held: { readonly type: ts.Type; readonly node: ts.Node } | undefined
-
-  const consider = (node: ts.ArrayLiteralExpression): void => {
-    if (held !== undefined) return
-    if (within !== undefined && node.getStart() !== within) return
-    const wanted = checker.getContextualType(node) ?? checker.getTypeAtLocation(node)
-    const kinds = (wanted.isUnionOrIntersection() ? wanted.types : [wanted])
-      .filter((one) => checker.getIndexTypeOfType(one, ts.IndexKind.Number) !== undefined)
-      .map((one) => elementOf(checker, one))
-    const type =
-      kinds.find((one) => threaded !== undefined && checker.isTypeAssignableTo(one, threaded)) ??
-      (kinds.length === 1 ? kinds[0] : undefined)
-    if (type !== undefined) held = { type, node }
-  }
-
-  const visit = (node: ts.Node): void => {
-    if (held !== undefined) return
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === list) {
-      const initial = node.initializer
-      if (initial !== undefined && ts.isArrayLiteralExpression(initial)) consider(initial)
-    }
-    if (ts.isPropertyAssignment(node)) {
-      const key = ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name) ? node.name.text : undefined
-      if (key === list && ts.isArrayLiteralExpression(node.initializer)) consider(node.initializer)
-    }
-    ts.forEachChild(node, visit)
-  }
-
-  visit(file)
-  return held
-}
-
-export function listShape(at: string, list: string): string | undefined {
-  const held = elementAt(at, list)
-  return held === undefined ? undefined : compiled().checker.typeToString(held.type)
-}
-
-export function listFields(at: string, list: string, within?: number): readonly Field[] {
-  const held = elementAt(at, list, within)
-  if (held === undefined) return []
-  const { checker } = compiled()
-  const bare = (kind: ts.Type): readonly ts.Type[] =>
-    (kind.isUnion() ? kind.types : [kind]).filter((each) => (each.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)) === 0)
-  const mapped = (kind: ts.Type): boolean =>
-    bare(kind).some(
-      (each) =>
-        (each.flags & ts.TypeFlags.StringLike) === 0 &&
-        checker.getIndexTypeOfType(each, ts.IndexKind.Number) === undefined &&
-        checker.getIndexTypeOfType(each, ts.IndexKind.String) !== undefined,
-    )
-  const listed = (kind: ts.Type): boolean =>
-    bare(kind).some(
-      (each) => (each.flags & ts.TypeFlags.StringLike) === 0 && checker.getIndexTypeOfType(each, ts.IndexKind.Number) !== undefined,
-    )
-  const flagged = (kind: ts.Type): boolean => {
-    const kinds = bare(kind)
-    return kinds.length > 0 && kinds.every((each) => (each.flags & ts.TypeFlags.BooleanLike) !== 0)
-  }
-  const worded = (kind: ts.Type): boolean => bare(kind).some((each) => (each.flags & ts.TypeFlags.StringLike) !== 0)
-  return checker.getPropertiesOfType(held.type).map((one) => {
-    const kind = checker.getTypeOfSymbolAtLocation(one, held.node)
-    return {
-      name: one.getName(),
-      required: (one.flags & ts.SymbolFlags.Optional) === 0,
-      list: listed(kind),
-      map: mapped(kind),
-      boolean: flagged(kind),
-      worded: worded(kind),
-      guide: ts.displayPartsToString(one.getDocumentationComment(checker)).trim(),
-      record: recordOf(checker, kind),
-      objects: objectsOf(checker, kind),
-    }
-  })
-}
-
-function elementOf(checker: ts.TypeChecker, type: ts.Type): ts.Type {
-  return checker.getIndexTypeOfType(type, ts.IndexKind.Number) ?? type
-}
-
-function objectsOf(checker: ts.TypeChecker, type: ts.Type): boolean {
-  for (const each of type.isUnion() ? type.types : [type]) {
-    if ((each.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.StringLike)) !== 0) continue
-    const held = checker.getIndexTypeOfType(each, ts.IndexKind.Number) ?? each
-    if ((held.isUnion() ? held.types : [held]).every((one) => (one.flags & ts.TypeFlags.Object) !== 0)) return true
-  }
-  return false
-}
-
-function recordOf(checker: ts.TypeChecker, type: ts.Type): readonly string[] {
-  for (const each of type.isUnion() ? type.types : [type]) {
-    if ((each.flags & ts.TypeFlags.StringLike) !== 0 || checker.getIndexTypeOfType(each, ts.IndexKind.Number) === undefined) continue
-    const element = elementOf(checker, each)
-    if ((element.flags & ts.TypeFlags.Object) === 0) return []
-    const fields = checker.getPropertiesOfType(element)
-    const worded = fields.every((one) => {
-      const kind = checker.getNonNullableType(checker.getTypeOfSymbol(one))
-      return (kind.isUnion() ? kind.types : [kind]).every((part) => (part.flags & ts.TypeFlags.StringLike) !== 0)
-    })
-    return worded ? fields.map((one) => one.getName()) : []
-  }
-  return []
-}
-
-export function rowShape(at: string, list: string): string | undefined {
-  const { program, checker } = compiled()
-  const file = program.getSourceFile(resolve(ROOT, at))
-  const threaded = threadedType(checker, program)
-  if (file === undefined || threaded === undefined) return undefined
-
-  let held: ts.Type | undefined
-
-  const consider = (node: ts.ArrayLiteralExpression): void => {
-    if (held !== undefined) return
-    const wanted = checker.getContextualType(node) ?? checker.getTypeAtLocation(node)
-    const each = (wanted.isUnionOrIntersection() ? wanted.types : [wanted]).map((one) => elementOf(checker, one))
-    held = each.find((one) => checker.isTypeAssignableTo(one, threaded))
-  }
-
-  const visit = (node: ts.Node): void => {
-    if (held !== undefined) return
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === list) {
-      const initial = node.initializer
-      if (initial !== undefined && ts.isArrayLiteralExpression(initial)) consider(initial)
-    }
-    if (ts.isPropertyAssignment(node)) {
-      const key = ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name) ? node.name.text : undefined
-      if (key === list && ts.isArrayLiteralExpression(node.initializer)) consider(node.initializer)
-    }
-    ts.forEachChild(node, visit)
-  }
-
-  visit(file)
-  return held === undefined ? undefined : checker.typeToString(held)
-}
-
-function literal(node: ts.Expression | undefined): string | undefined {
-  if (node === undefined) return undefined
-  return ts.isStringLiteralLike(node) ? node.text : undefined
-}
-
-function fieldsOf(node: ts.ObjectLiteralExpression): Map<string, ts.Expression> {
-  const found = new Map<string, ts.Expression>()
-  for (const property of node.properties) {
-    if (!ts.isPropertyAssignment(property)) continue
-    const key = ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name) ? property.name.text : undefined
-    if (key !== undefined) found.set(key, property.initializer)
-  }
-  return found
-}
-
-function wordsOf(node: ts.Expression | undefined): readonly string[] {
-  if (node === undefined || !ts.isArrayLiteralExpression(node)) return []
-  return node.elements.map((one) => literal(one)).filter((one): one is string => one !== undefined)
-}
-
-function rowOf(node: ts.ObjectLiteralExpression, type: string, where: string, shape?: ts.Type): Row {
-  const fields = fieldsOf(node)
-  const named = literal(fields.get('at'))
-  const at = named === undefined ? undefined : settle(named, where)
-  const id = literal(fields.get('id'))
-  const describes = literal(fields.get('describes'))
-  const by = literal(fields.get('by'))
-  const runs = literal(fields.get('runs'))
-  const requires = wordsOf(fields.get('requires'))
-  const takes = wordsOf(fields.get('takes'))
-  return {
-    ...(at === undefined ? {} : { at }),
-    ...(id === undefined ? {} : { id }),
-    ...(describes === undefined ? {} : { describes }),
-    ...(by === undefined ? {} : { by }),
-    ...(runs === undefined ? {} : { runs }),
-    ...(requires.length === 0 ? {} : { requires }),
-    ...(takes.length === 0 ? {} : { takes }),
-    ...(shape === undefined ? {} : { shape }),
-    type,
-    fields,
-    where,
-  }
-}
-
-function unwrap(node: ts.Expression | undefined): ts.Expression | undefined {
-  let held = node
-  for (;;) {
-    if (held === undefined) return undefined
-    if (ts.isParenthesizedExpression(held) || ts.isSatisfiesExpression(held) || ts.isAsExpression(held)) {
-      held = held.expression
-      continue
-    }
-    return held
-  }
-}
-
-interface Held {
-  readonly name: string
-  readonly type: string
-  readonly shape: ts.Type
-  readonly node: ts.ObjectLiteralExpression
-}
-
-export function nodesIn(at: string): readonly Held[] {
-  const { program, checker } = compiled()
-  const threaded = threadedType(checker, program)
-  const file = program.getSourceFile(resolve(ROOT, at))
-  if (file === undefined || threaded === undefined) return []
-
-  const found: Held[] = []
-
-  const take = (name: string, where: ts.Node, initial: ts.Expression | undefined): void => {
-    const held = unwrap(initial)
-    if (held === undefined) return
-
-    const recognised = (one: ts.Type): boolean => (one.flags & ts.TypeFlags.Any) === 0 && checker.isTypeAssignableTo(one, threaded)
-    const declared = checker.getTypeAtLocation(where)
-    const each = (declared.isUnionOrIntersection() ? declared.types : [declared]).map((one) => elementOf(checker, one))
-    const stated = each.find((one) => recognised(one))
-
-    const parts = ts.isArrayLiteralExpression(held) ? held.elements : [held]
-    for (const one of parts) {
-      const object = unwrap(one)
-      if (object === undefined || !ts.isObjectLiteralExpression(object)) continue
-      const mine = checker.getWidenedType(checker.getTypeAtLocation(object))
-      const known = stated ?? (recognised(mine) ? mine : undefined)
-      if (known === undefined) continue
-      found.push({ name, type: checker.typeToString(known), shape: known, node: object })
-    }
-  }
-
-  const step = (statements: readonly ts.Statement[]): void => {
-    for (const statement of statements) {
-      if (ts.isModuleDeclaration(statement) && statement.body !== undefined && ts.isModuleBlock(statement.body)) {
-        step(statement.body.statements)
-        continue
-      }
-      if (ts.isExportAssignment(statement)) {
-        take('default', statement.expression, statement.expression)
-        continue
-      }
-      if (!ts.isVariableStatement(statement)) continue
-      for (const one of statement.declarationList.declarations) {
-        if (!ts.isIdentifier(one.name) || one.initializer === undefined) continue
-        take(one.name.text, one.name, one.initializer)
-      }
-    }
-  }
-
-  step(file.statements)
-  return found
-}
-
-let commands: ReadonlySet<string> | undefined
-
-function scripts(): ReadonlySet<string> {
-  if (commands !== undefined) return commands
-  const found = new Set<string>()
-  try {
-    const held = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8')) as { scripts?: Record<string, unknown> }
-    for (const name of Object.keys(held.scripts ?? {})) found.add(name)
-  } catch {
-    found.clear()
-  }
-  commands = found
-  return found
-}
-
-function mentionsIn(at: string): readonly string[] {
-  const found: string[] = []
-  const step = (node: ts.ObjectLiteralExpression): void => {
-    const fields = fieldsOf(node)
-    for (const list of LISTS) {
-      const value = fields.get(list)
-      if (value === undefined || !ts.isArrayLiteralExpression(value)) continue
-      for (const one of value.elements) {
-        if (!ts.isObjectLiteralExpression(one)) continue
-        const held = literal(fieldsOf(one).get('at'))
-        if (held !== undefined) found.push(settle(held, at))
-        step(one)
-      }
-    }
-  }
-  for (const one of nodesIn(at)) step(one.node)
-  return found
-}
-
-let passed: Pass | undefined
-
-export function reached(): readonly string[] {
-  return [THREAD_AT, ...descend().threaded.keys()]
-}
-
-let world: object = answering()
-
-const worlds = new WeakMap<object, () => void>()
-
-function kept(): () => void {
-  const was = { passed, built, scanned, commands, ignores, readIgnores, source: new Map(source), asked: new Map(asked) }
-  return () => {
-    passed = was.passed
-    built = was.built
-    scanned = was.scanned
-    commands = was.commands
-    ignores = was.ignores
-    readIgnores = was.readIgnores
-    source.clear()
-    for (const [at, text] of was.source) source.set(at, text)
-    asked.clear()
-    for (const [at, ignore] of was.asked) asked.set(at, ignore)
-  }
-}
-
-export function forget(): void {
-  const now = answering()
-  if (now === world) libraries.clear()
-  else {
-    worlds.set(world, kept())
-    world = now
-    const back = worlds.get(now)
-    if (back !== undefined) {
-      back()
-      return
-    }
-  }
-  passed = undefined
-  built = undefined
-  scanned = undefined
-  commands = undefined
-  source.clear()
-  asked.clear()
-  ignores = undefined
-  readIgnores = false
-}
-
-export function descend(): Pass {
-  rooted()
-  if (passed !== undefined) return passed
-
-  const { program, checker } = compiled()
-  const threaded = new Map<string, { list: 'declares' | 'derives' | 'seeds'; by: string; row: Row }[]>()
-  const mentioned = new Map<string, string[]>()
-  const derived = new Map<string, Row>()
-  const stated = new Map<string, Row>()
-  const coined = new Map<string, { said: string[]; under: string; from: string[] }>()
-  const broken: Finding[] = []
-  const findings: Finding[] = []
-  const opened = new Set<string>()
-  const shaped = new Map<string, { type: string; shape?: ts.Type; by: string }>()
-  const made = new Map<string, { by: Set<string>; rows: string[]; where: string }>()
-  const absent = new Map<string, { at: number; by: Set<string>; rows: number }>()
-  const demanded: { row: Row; word: string; list: string }[] = []
-  const thread: { row: Row; command: string }[] = []
-  const offered = new Set<string>()
-  let declarations = 0
-  let rows = 0
-
-  const root = program.getSourceFile(resolve(ROOT, THREAD_AT))
-  if (root === undefined) {
-    broken.push({
-      file: THREAD_AT,
-      detail: 'the root of the tree cannot be read, so nothing below it is reached and every file here reads as unthreaded',
-      instead: 'write the root, or run `thread init`',
-    })
-    passed = { threaded, mentioned, derived, stated, coined, broken, findings, declarations, rows, sources: sources() }
-    return passed
-  }
-
-  const shape = threadedType(checker, program)
-  if (shape === undefined) {
-    broken.push({
-      file: THREAD_AT,
-      detail: 'the root does not resolve `Threaded`, so nothing here can be recognised as a declaration and every file reads as unthreaded',
-      instead: `import \`Threaded\` from \`${SHAPED}\` in the root, or run \`thread init\`. Without the shape there is nothing to hold anything to`,
-    })
-    passed = { threaded, mentioned, derived, stated, coined, broken, findings, declarations, rows, sources: sources() }
-    return passed
-  }
-
-  const said = (by: string): string => (by === '' ? 'the root' : by)
-  const names = (row: Row): string => row.id ?? row.at ?? 'a row stating neither an id nor an at'
-
-  function coin(id: string | undefined, describes: string | undefined, under: string, parent: string): void {
-    if (id === undefined) return
-    const held = coined.get(id) ?? { said: [], under, from: [] }
-    const meaning = describes ?? ''
-    if (!held.said.includes(meaning)) held.said.push(meaning)
-    if (parent !== '' && parent !== id && !held.from.includes(parent)) held.from.push(parent)
-    coined.set(id, held)
-  }
-
-  function judge(row: Row, by: string, list: (typeof LISTS)[number], own: boolean): void {
-    const at = row.where
-
-    for (const field of ['by', 'runs'] as const) {
-      const command = row[field]
-      if (command === undefined) continue
-      if (command.startsWith('thread ')) {
-        if (field === 'by') offered.add(command)
-        else thread.push({ row, command })
-        continue
-      }
-      const held = RUNNER.exec(command)
-      if (held === null || scripts().has(held[1] ?? '')) continue
-      findings.push({
-        file: at,
-        detail: `\`${names(row)}\` states \`${field}: '${command}'\`, and package.json states no \`${held[1] ?? ''}\` script`,
-        instead: 'add the script, or fix the name. A row naming a command is a promise that the command exists',
-      })
-    }
-
-    for (const field of ['requires', 'takes'] as const) {
-      for (const word of wordsOf(row.fields.get(field))) demanded.push({ row, word, list: field })
-    }
-
-    if (list === 'derives' && row.at !== undefined && !own) {
-      const held = made.get(row.at) ?? { by: new Set<string>(), rows: [] as string[], where: at }
-      if (row.by !== undefined) held.by.add(row.by)
-      held.rows.push(names(row))
-      made.set(row.at, held)
-    }
-
-    if (row.at === THREAD_AT && !own) {
-      findings.push({
-        file: at,
-        detail: `\`${names(row)}\` declares \`${THREAD_AT}\`, which is the root`,
-        instead:
-          'delete the row. The root exists by fiat and is the one thing nothing declares — giving it a parent makes its origin a thing the tree answers two ways',
-      })
-    }
-
-    if (row.at === undefined) return
-
-    if (row.at.startsWith('../') || row.at.startsWith('/')) {
-      findings.push({
-        file: at,
-        detail: `\`${names(row)}\` names \`${row.at}\`, which is outside this repository`,
-        instead:
-          'name something inside the tree. A declaration reaches only what this repository holds, and a row pointing past its edge threads a file nobody here can read, change or delete',
-      })
-      return
-    }
-
-    const target = resolve(ROOT, row.at)
-    if (!installed(row.at) && unkept(row.at)) {
-      findings.push({
-        file: at,
-        detail: `\`${names(row)}\` names \`${row.at}\`, which git ignores, so it is on this machine and in no clone of it`,
-        instead:
-          'name a file this repository carries, or stop ignoring it. A row naming an ignored path is answered here and nowhere else, so the descent passes on the disk that wrote it and breaks everywhere the work actually runs',
-      })
-      return
-    }
-    if (!existsSync(target)) {
-
-      const derived = list === 'derives' || row.by !== undefined
-      const said = absent.get(row.at)
-      if (said !== undefined) {
-        said.by.add(names(row))
-        said.rows += 1
-        return
-      }
-      absent.set(row.at, { at: findings.length, by: new Set([names(row)]), rows: 1 })
-      findings.push({
-        file: at,
-        detail: derived
-          ? `\`${names(row)}\` ${list === 'derives' ? 'derives' : 'names'} \`${row.at}\`, and nothing is there yet`
-          : `\`${names(row)}\` names \`${row.at}\`, and nothing is there`,
-        instead: derived
-          ? 'run the generator the row names in `by`. A derived file is absent until it is derived, so this is a warning'
-          : 'write the file, fix the path, or delete the row. A row naming nothing brings nothing into existence',
-        ...(derived ? { severity: 'warning' as const } : {}),
-      })
-    } else if (statSync(target).isDirectory()) {
-      findings.push({
-        file: at,
-        detail: `\`${names(row)}\` names \`${row.at}\`, which is a directory`,
-        instead:
-          'name the file. A directory threads nothing beneath it, so every file under this one still reads as declared by nobody while the row itself looks answered',
-      })
-    }
-
-    const already = shaped.get(row.at)
-    if (already === undefined) {
-      shaped.set(row.at, { type: row.type, shape: row.shape, by })
-      return
-    }
-    if (row.shape === undefined || already.shape === undefined) return
-    if (checker.isTypeAssignableTo(row.shape, already.shape) || checker.isTypeAssignableTo(already.shape, row.shape)) return
-    findings.push({
-      file: at,
-      detail: `\`${row.at}\` is declared \`${row.type}\` by \`${said(by)}\` and \`${already.type}\` by \`${said(already.by)}\`, and neither shape satisfies the other`,
-      instead: 'one address has one shape. Decide what the child is and let both rows say it',
-    })
-  }
-
-  function into(node: ts.ObjectLiteralExpression, type: string, at: string, under: string, parent: string, judged = false): void {
-    declarations += 1
-    const held = rowOf(node, type, at)
-    if (!judged) {
-      coin(held.id, held.describes, under, parent)
-      judge(held, parent, 'declares', true)
-      if (held.id !== undefined && !stated.has(held.id)) stated.set(held.id, held)
-    }
-
-    const by = held.id ?? at
-
-    for (const list of LISTS) {
-      const stated = held.fields.get(list)
-      if (stated === undefined) continue
-
-      const only = ts.isCallExpression(stated) && stated.arguments.length === 1 ? stated.arguments[0] : undefined
-      const value = only !== undefined && ts.isArrayLiteralExpression(only) ? only : stated
-
-      if (!ts.isArrayLiteralExpression(value)) {
-        findings.push({ file: at, detail: `\`${by}\` states a \`${list}\` that is not a list`, instead: `write \`${list}\` as a list of rows` })
-        continue
-      }
-
-      for (const one of value.elements) {
-        const declaration = ts.isIdentifier(one) ? checker.getSymbolAtLocation(one)?.valueDeclaration : undefined
-        const initial = declaration !== undefined && ts.isVariableDeclaration(declaration) ? unwrap(declaration.initializer) : undefined
-        const object = ts.isObjectLiteralExpression(one) ? one : initial !== undefined && ts.isObjectLiteralExpression(initial) ? initial : undefined
-        if (object === undefined) {
-          findings.push({
-            file: at,
-            detail: `\`${by}\` holds something in \`${list}\` that is not a row written out here`,
-            instead: 'write the row inline. A row reached through a name is a row the descent would have to run code to read',
-          })
-          continue
-        }
-        rows += 1
-        const wanted = checker.getContextualType(one)
-        const kind = wanted === undefined ? undefined : elementOf(checker, wanted)
-        const row = rowOf(object, kind === undefined ? type : checker.typeToString(kind), at, kind)
-        coin(row.id, row.describes, under, by)
-        judge(row, by, list, false)
-        if (row.at !== undefined) {
-          threaded.set(row.at, [...(threaded.get(row.at) ?? []), { list, by, row }])
-          if (list === 'derives' && row.id !== undefined) derived.set(row.id, row)
-        }
-        if (LISTS.some((name) => row.fields.has(name))) into(object, row.type, at, under, by, true)
-        if (row.at !== undefined) open(row.at, wanted === undefined ? undefined : elementOf(checker, wanted), under, row.id ?? by, by, list !== 'derives' || row.at.startsWith(TREE))
-      }
-    }
-  }
-
-  function open(at: string, expected: ts.Type | undefined, under: string, parent: string, by: string, reads: boolean): void {
-    const already = opened.has(at)
-    opened.add(at)
-    if (!SOURCE.test(at)) return
-    const file = program.getSourceFile(resolve(ROOT, at))
-    if (file === undefined) return
-    if (!reads) return
-
-    if (!already) {
-      for (const one of program.getSyntacticDiagnostics(file)) {
-        broken.push({
-          file: at,
-          detail: `this file does not parse, so whatever it declares was never read and every child under it reads as absent: ${ts.flattenDiagnosticMessageText(one.messageText, ' ')}`,
-          instead: 'fix the syntax. A file the descent cannot read declares nothing, and nothing below it can be found missing',
-        })
-        break
-      }
-    }
-
-    for (const one of nodesIn(at)) {
-      if (expected !== undefined && !checker.isTypeAssignableTo(one.shape, expected)) {
-        findings.push({
-          file: at,
-          detail: `\`${one.name}\` here is \`${one.type}\`, and \`${said(by)}\` states its child is \`${checker.typeToString(expected)}\``,
-          instead: `annotate it \`${checker.typeToString(expected)}\`, or a shape that satisfies it, or change the row. A parent states the shape of its child, and a child answering with another shape is a child of something else`,
-        })
-        continue
-      }
-      if (already) continue
-      into(one.node, one.type, at, under, parent)
-    }
-  }
-
-  opened.add(THREAD_AT)
-  for (const one of nodesIn(THREAD_AT)) into(one.node, one.type, THREAD_AT, '', '')
-
-  for (const at of [...opened].filter((one) => SOURCE.test(one))) {
-    const file = program.getSourceFile(resolve(ROOT, at))
-    if (file === undefined) continue
-    for (const one of program.getSemanticDiagnostics(file)) {
-      findings.push({
-        file: at,
-        detail: `the compiler refuses this declaration: ${ts.flattenDiagnosticMessageText(one.messageText, ' ')}`,
-        instead:
-          'make the declaration the shape its own type states. A row the compiler will not accept is a row nothing downstream can read',
-      })
-    }
-  }
-
-  for (const [what, held] of made) {
-    if (held.by.size === 0) {
-      findings.push({
-        file: held.where,
-        detail: `\`${what}\` is derived by ${held.rows.length === 1 ? `\`${held.rows[0] ?? ''}\`` : `${String(held.rows.length)} rows`}, and not one of them states a \`by\``,
-        instead:
-          'name the command that writes it on one of those rows. A derived file whose generator is unnamed cannot be compared against what it should be, so drift in it is invisible',
-      })
-      continue
-    }
-    if (held.by.size < 2) continue
-    findings.push({
-      file: held.where,
-      detail: `\`${what}\` is derived by ${[...held.by].map((one) => `\`${one}\``).join(' and ')}`,
-      instead: 'one file has one generator. Two commands writing one address means whichever runs last wins and the other is overwritten in silence',
-    })
-  }
-
-  const answers = (command: string): boolean =>
-    offered.has(command) || [...offered].some((one) => command.startsWith(`${one} --`))
-
-  for (const one of thread) {
-    if (answers(one.command)) continue
-    findings.push({
-      file: one.row.where,
-      detail: `\`${names(one.row)}\` states \`runs: '${one.command}'\`, and no row declares a \`by\` it is a mode of`,
-      instead:
-        'name a command some row brings into existence with a `by`, or a `--` mode of one. A row proving a byproduct proves what another row writes, so the writer has to exist',
-    })
-  }
-
-  for (const one of demanded) {
-    if (coined.has(one.word)) continue
-    findings.push({
-      file: one.row.where,
-      detail: `\`${names(one.row)}\` ${one.list} \`${one.word}\`, and nothing in this tree coins that word`,
-      instead: `declare something with \`id: '${one.word}'\`, or fix the name. A demand naming nothing is met by nothing, and nothing tells you so`,
-    })
-  }
-
-  for (const [word, held] of coined) {
-    const meanings = [...new Set(held.said.filter((one) => one !== ''))]
-    if (meanings.length < 2) continue
-    findings.push({
-      file: THREAD_AT,
-      detail: `\`${word}\` is coined ${String(meanings.length)} times with different meanings: ${meanings.map((one) => `"${one.slice(0, 60)}${one.length > 60 ? '…' : ''}"`).join(' and ')}`,
-      instead: 'one word means one thing. Keep the row that coins it and make the others name what they actually are, or say the same sentence in both',
-    })
-  }
-
-  for (const [name, where] of shapesNamed()) {
-    if (where.length < 2) continue
-    findings.push({
-      file: where[1] ?? THREAD_AT,
-      detail: `\`${name}\` is a shape the tree threads by, and it is declared in ${String(where.length)} places: ${where.join(', ')}`,
-      instead: 'keep one and delete the rest. Whichever the descent reads first decides what every declaration is held to, so a second one silently rewrites the rules for the whole tree',
-    })
-  }
-
-  for (const one of sources()) {
-    if (!SOURCE.test(one)) continue
-    for (const at of mentionsIn(one)) {
-      const held = mentioned.get(at) ?? []
-      if (!held.includes(one)) mentioned.set(at, [...held, one])
-    }
-  }
-
-  for (const [path, held] of absent) {
-    if (held.rows < 2) continue
-    const one = findings[held.at]
-    if (one === undefined) continue
-
-    findings[held.at] = {
-      ...one,
-      detail: `${String(held.rows)} rows derive \`${path}\`, and nothing is there yet — ${[...held.by].sort().join(', ')}`,
-    }
-  }
-
-  passed = { threaded, mentioned, derived, stated, coined, broken, findings, declarations, rows, sources: sources() }
-  return passed
-}