@prestack/thread 0.0.1 → 0.0.3

package/dist/core/descend.ts

@@ -0,0 +1,1001 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+
+import ts from 'typescript'
+
+import type { Finding } from './finding.ts'
+import { ignored } from './init.ts'
+import { NAMED, ORGANISATION } 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`
+
+const OWN_IGNORES: readonly string[] | undefined = (() => {
+  if (spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: ROOT, stdio: 'ignore' }).status === 0) {
+    return undefined
+  }
+  try {
+    return 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 {
+    return []
+  }
+})()
+
+const asked = new Map<string, boolean>()
+
+export function unkept(at: string): boolean {
+  const held = asked.get(at)
+  if (held !== undefined) return held
+  const found =
+    OWN_IGNORES === undefined
+      ? spawnSync('git', ['check-ignore', '-q', '--', at], { cwd: ROOT, stdio: 'ignore' }).status === 0
+      : OWN_IGNORES.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
+
+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 shipped(): readonly string[] {
+  const out: string[] = []
+  const base = join(ROOT, 'node_modules', ORGANISATION)
+  let entries: readonly string[]
+  try {
+    entries = readdirSync(base)
+  } catch {
+    return out
+  }
+  for (const name of [...entries].sort()) walk(join(base, name, 'src'), out)
+  return out
+}
+
+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,
+  skipLibCheck: true,
+  allowImportingTsExtensions: true,
+  allowJs: true,
+  jsx: ts.JsxEmit.ReactJSX,
+}
+
+export function configured(): { readonly options: ts.CompilerOptions; readonly from: string; readonly trouble?: string } {
+  for (const name of CONFIGS) {
+    const at = join(ROOT, name)
+    if (!ts.sys.fileExists(at)) continue
+
+    const held = ts.readConfigFile(at, ts.sys.readFile.bind(ts.sys))
+    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, ts.sys, 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: '' }
+}
+
+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(), ...shipped()].filter((one) => SOURCE.test(one)).map((one) => resolve(ROOT, one))
+  const program = ts.createProgram([...new Set(roots)], configured().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
+}
+
+export function shapesNamed(): ReadonlyMap<string, readonly string[]> {
+  const { program, checker } = compiled()
+  const shape = threadedType(checker, program)
+  const found = new Map<string, string[]>()
+  if (shape === undefined) return found
+  for (const at of [...sources(), ...shipped()]) {
+    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])
+    }
+  }
+  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 }[] {
+  const { program, checker } = compiled()
+  for (const at of [...sources(), ...shipped()]) {
+    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(),
+        }
+      })
+    }
+  }
+  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
+}
+
+function elementAt(at: string, list: string): { 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
+    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): readonly Field[] {
+  const held = elementAt(at, list)
+  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(),
+    }
+  })
+}
+
+function elementOf(checker: ts.TypeChecker, type: ts.Type): ts.Type {
+  return checker.getIndexTypeOfType(type, ts.IndexKind.Number) ?? type
+}
+
+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()]
+}
+
+export function forget(): void {
+  passed = undefined
+  built = undefined
+  scanned = undefined
+  commands = undefined
+  source.clear()
+}
+
+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 \`${NAMED}/thread\` 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 (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) {
+        if (!ts.isObjectLiteralExpression(one)) {
+          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(one, 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(one, row.type, at, under, by, true)
+        if (row.at !== undefined) open(row.at, wanted === undefined ? undefined : elementOf(checker, wanted), under, row.id ?? by, by)
+      }
+    }
+  }
+
+  function open(at: string, expected: ts.Type | undefined, under: string, parent: string, by: string): 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 (!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(), ...shipped()]) {
+    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
+}