@prestack/thread 0.0.1

package/dist/core/descend.js

@@ -0,0 +1,879 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { ignored } from "./init.js";
+import { NAMED, ORGANISATION } from "./scope.js";
+import { findTree } from "./tree.js";
+const BUILT = new Set(ignored()
+    .split('\n')
+    .map((one) => one.trim())
+    .filter((one) => one.endsWith('/'))
+    .map((one) => one.replace(/\/+$/, '')));
+const TREE_AT = (() => {
+    try {
+        return findTree();
+    }
+    catch {
+        return undefined;
+    }
+})();
+const NOWHERE = '/this-app-has-no-tree';
+function rooted() {
+    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`;
+export const LISTS = ['declares', 'derives', 'seeds'];
+const SOURCE = /\.(ts|tsx|mts|cts)$/;
+const RUNNER = /^(?:pnpm|npm|yarn) (?:run )?([\w:.-]+)/;
+export function under(pass, id, root, seen = new Set()) {
+    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) {
+    return relative(ROOT, path).split('\\').join('/');
+}
+const CANONICAL = 'threads/';
+const BESIDE = /^\.\//;
+function settle(at, where) {
+    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) {
+    try {
+        return realpathSync(resolve(ROOT, at));
+    }
+    catch {
+        return resolve(ROOT, at);
+    }
+}
+function walk(dir, out) {
+    let entries;
+    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;
+export function sources() {
+    rooted();
+    scanned ??= walk(ROOT, []).sort();
+    return scanned;
+}
+function shipped() {
+    const out = [];
+    const base = join(ROOT, 'node_modules', ORGANISATION);
+    let entries;
+    try {
+        entries = readdirSync(base);
+    }
+    catch {
+        return out;
+    }
+    for (const name of [...entries].sort())
+        walk(join(base, name, 'src'), out);
+    return out;
+}
+const FALLBACK = {
+    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'];
+const INVARIANT = {
+    noEmit: true,
+    skipLibCheck: true,
+    allowImportingTsExtensions: true,
+    allowJs: true,
+    jsx: ts.JsxEmit.ReactJSX,
+};
+export function configured() {
+    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, 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;
+function compiled() {
+    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() {
+    const { program } = compiled();
+    const found = [];
+    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, program) {
+    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();
+export function read(at) {
+    if (source.has(at))
+        return source.get(at);
+    let text;
+    try {
+        text = readFileSync(resolve(ROOT, at), 'utf8');
+    }
+    catch {
+        text = undefined;
+    }
+    source.set(at, text);
+    return text;
+}
+export function shapesNamed() {
+    const { program, checker } = compiled();
+    const shape = threadedType(checker, program);
+    const found = new Map();
+    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() {
+    return new Set(['Threaded', ...shapesNamed().keys()]);
+}
+export function shapeFields(named, inside) {
+    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) => (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) => (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 [];
+}
+function elementAt(at, list) {
+    const { program, checker } = compiled();
+    const file = program.getSourceFile(resolve(ROOT, at));
+    if (file === undefined)
+        return undefined;
+    const threaded = threadedType(checker, program);
+    let held;
+    const consider = (node) => {
+        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) => {
+        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, list) {
+    const held = elementAt(at, list);
+    return held === undefined ? undefined : compiled().checker.typeToString(held.type);
+}
+export function listFields(at, list) {
+    const held = elementAt(at, list);
+    if (held === undefined)
+        return [];
+    const { checker } = compiled();
+    const bare = (kind) => (kind.isUnion() ? kind.types : [kind]).filter((each) => (each.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)) === 0);
+    const mapped = (kind) => 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) => bare(kind).some((each) => (each.flags & ts.TypeFlags.StringLike) === 0 && checker.getIndexTypeOfType(each, ts.IndexKind.Number) !== undefined);
+    const flagged = (kind) => {
+        const kinds = bare(kind);
+        return kinds.length > 0 && kinds.every((each) => (each.flags & ts.TypeFlags.BooleanLike) !== 0);
+    };
+    const worded = (kind) => 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, type) {
+    return checker.getIndexTypeOfType(type, ts.IndexKind.Number) ?? type;
+}
+export function rowShape(at, list) {
+    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;
+    const consider = (node) => {
+        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) => {
+        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) {
+    if (node === undefined)
+        return undefined;
+    return ts.isStringLiteralLike(node) ? node.text : undefined;
+}
+function fieldsOf(node) {
+    const found = new Map();
+    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) {
+    if (node === undefined || !ts.isArrayLiteralExpression(node))
+        return [];
+    return node.elements.map((one) => literal(one)).filter((one) => one !== undefined);
+}
+function rowOf(node, type, where, shape) {
+    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) {
+    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;
+    }
+}
+export function nodesIn(at) {
+    const { program, checker } = compiled();
+    const threaded = threadedType(checker, program);
+    const file = program.getSourceFile(resolve(ROOT, at));
+    if (file === undefined || threaded === undefined)
+        return [];
+    const found = [];
+    const take = (name, where, initial) => {
+        const held = unwrap(initial);
+        if (held === undefined)
+            return;
+        const recognised = (one) => (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) => {
+        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;
+function scripts() {
+    if (commands !== undefined)
+        return commands;
+    const found = new Set();
+    try {
+        const held = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8'));
+        for (const name of Object.keys(held.scripts ?? {}))
+            found.add(name);
+    }
+    catch {
+        found.clear();
+    }
+    commands = found;
+    return found;
+}
+function mentionsIn(at) {
+    const found = [];
+    const step = (node) => {
+        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;
+export function reached() {
+    return [THREAD_AT, ...descend().threaded.keys()];
+}
+export function forget() {
+    passed = undefined;
+    built = undefined;
+    scanned = undefined;
+    commands = undefined;
+    source.clear();
+}
+export function descend() {
+    rooted();
+    if (passed !== undefined)
+        return passed;
+    const { program, checker } = compiled();
+    const threaded = new Map();
+    const mentioned = new Map();
+    const derived = new Map();
+    const stated = new Map();
+    const coined = new Map();
+    const broken = [];
+    const findings = [];
+    const opened = new Set();
+    const shaped = new Map();
+    const made = new Map();
+    const absent = new Map();
+    const demanded = [];
+    const thread = [];
+    const offered = new Set();
+    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) => (by === '' ? 'the root' : by);
+    const names = (row) => row.id ?? row.at ?? 'a row stating neither an id nor an at';
+    function coin(id, describes, under, parent) {
+        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, by, list, own) {
+        const at = row.where;
+        for (const field of ['by', 'runs']) {
+            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']) {
+            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(), rows: [], 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 (!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' } : {}),
+            });
+        }
+        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, type, at, under, parent, judged = false) {
+        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, expected, under, parent, by) {
+        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) => 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;
+}