spp-lang 0.0.0-stage → 0.1.0

package/dist/src/language/check.js

@@ -0,0 +1,709 @@
+// The checker: runs every step on a stack of types instead of values, so
+// mistakes show up before a browser starts.
+//
+// It uses the forms the runtime uses, and picks between them the same way:
+// the first whose inputs are on top of the stack. With no conditionals or
+// loops, every step is straight-line code, so one pass is the whole story.
+//
+// A Define's header says what it takes: "Define: Add Text (Item)" takes Text,
+// called Item in its body, so Add : Text ->. Its body is checked with those,
+// and can't take anything else from its caller. What it leaves is worked out.
+//
+// A Define that leaves one thing of a built-in kind is a noun, and makes a
+// kind of its own: "Define: Cart" leaving an Element makes Cart, a narrower
+// Element, which other Defines' headers can take.
+//
+// A word can have several Defines, told apart by what they take. A use runs
+// the first that fits, most particular first, as the runtime does
+// (Definitions in cognate.ts). Two that could always both fit are a mistake
+// in the Defines, so a use never has to guess.
+import path from 'node:path';
+import { notAKind, parse, SppError, specificity, unknownWord } from './cognate.js';
+import { lineCol } from './load.js';
+import { keywordForms, keywords, StepType } from './steps.js';
+import { AnyType, article, NumberType, signature, TableType, TextType, type } from './types.js';
+// ---------------------------------------------------------------- static values
+// The keyword words, for their forms; the checker runs steps itself.
+const KEYWORDS = keywords(async () => { });
+const SymbolType = type('Symbol', 'a symbol', (v) => false);
+// A value a Define's body takes from its caller. members is what it can
+// still be, narrowed by each use; null until something uses it.
+class Var {
+    members = null;
+    phrase = 'a value';
+}
+// A block, waiting for Define to take it.
+class BlockOf {
+    body;
+    scope;
+    origin;
+    constructor(body, scope, origin) {
+        this.body = body;
+        this.scope = scope;
+        this.origin = origin;
+    }
+}
+const membersOf = (ty) => ty instanceof Var ? ty.members : ty instanceof BlockOf ? ['Block'] : ty.name === AnyType.name ? null : ty.members;
+const nameOf = (ty) => membersOf(ty)?.join(' | ') ?? 'Any';
+// A variable is shown as what it's been narrowed to so far.
+const show = (v) => (v.ty instanceof Var ? v.ty.phrase : v.shown);
+const stepOrigin = (step) => ({
+    file: step.file,
+    at: (pos) => ({ line: step.line, column: step.column + pos }),
+});
+const fileOrigin = (v) => ({ file: v.file, at: (pos) => lineCol(v.src, pos) });
+class Mistake extends Error {
+    pos;
+}
+class Scope {
+    parent;
+    builtins;
+    words = new Map();
+    constructor(parent, builtins = null) {
+        this.parent = parent;
+        this.builtins = builtins;
+    }
+    set(known) {
+        this.words.set(known.name.toLowerCase(), known);
+    }
+    lookup(name) {
+        const key = name.toLowerCase();
+        for (let s = this; s; s = s.parent) {
+            const known = s.words.get(key);
+            if (known)
+                return known;
+            const forms = s.builtins?.forms(name);
+            if (s.builtins && forms)
+                return { name: s.builtins.spellings.get(key) ?? name, kind: 'forms', forms };
+        }
+    }
+    *names() {
+        for (let s = this; s; s = s.parent) {
+            for (const known of s.words.values())
+                yield known.name;
+            if (s.builtins)
+                yield* s.builtins.names();
+        }
+    }
+    // Everything visible from here, nearest first, each name once.
+    all() {
+        const seen = new Set();
+        return [...this.names()].flatMap((name) => {
+            const key = name.toLowerCase();
+            if (seen.has(key))
+                return [];
+            seen.add(key);
+            const known = this.lookup(name);
+            return known ? [known] : [];
+        });
+    }
+}
+// The stack a statement runs on. An open stack belongs to an editor's guess
+// at what comes next: reaching below its bottom takes a value that isn't
+// written yet, which becomes one of its inputs. Otherwise the stack is
+// closed; there's nothing below.
+class Sim {
+    open;
+    stack = [];
+    inputs = [];
+    constructor(open) {
+        this.open = open;
+    }
+    // What's i from the top, or undefined if that's below the bottom.
+    peek(i) {
+        return this.stack[this.stack.length - 1 - i];
+    }
+    // A new value from the caller, for a slot below the bottom.
+    fromCaller(want) {
+        const v = new Var();
+        if (want) {
+            v.members = want.members;
+            v.phrase = want.phrase;
+        }
+        this.inputs.push(v);
+        return { ty: v, shown: v.phrase };
+    }
+}
+// ---------------------------------------------------------------- checking
+export function check(files, options) {
+    return analyze(files, options).report;
+}
+// A checked project, which can also be asked about words and types, for
+// an editor. Where a step or a line is given, it's the scope that step, or
+// that line of a Define's body, sees: in a body, what its header takes.
+export class Analysis {
+    report;
+    checker;
+    constructor(checker) {
+        this.checker = checker;
+        this.report = checker.report;
+    }
+    words(at) {
+        return this.checker
+            .scopeFor(at)
+            .all()
+            .map((known) => this.checker.info(known));
+    }
+    word(name, at) {
+        const known = this.checker.scopeFor(at).lookup(name);
+        return known && this.checker.info(known);
+    }
+    // What a value would need to be, written after the code in left: in
+    // "Fill the Field "Email" with ", Fill needs its text. null when it
+    // could be anything, or left can't be read.
+    expected(left, at) {
+        return this.checker.expected(left, this.checker.scopeFor(at));
+    }
+    // Where the Define is that a use of a word, at this place, runs.
+    chosen(file, line, column) {
+        return this.checker.chosen.get(placeKey({ file, line, column }))?.at;
+    }
+}
+const placeKey = (p) => `${p.file}:${p.line}:${p.column}`;
+export function analyze(files, options) {
+    const checker = new Checker(options);
+    checker.check(files);
+    return new Analysis(checker);
+}
+class Checker {
+    options;
+    cwd;
+    defs = [];
+    report = { vocabulary: [], scenarios: new Map() };
+    vocabulary;
+    // what each step, and each line of a Define, sees, for an editor
+    stepScopes = new Map();
+    lineScopes = new Map();
+    // answering an editor, which wants a best guess rather than a mistake
+    guessing = false;
+    // which Define each use of a Defined word runs, by where the use is
+    chosen = new Map();
+    constructor(options) {
+        this.options = options;
+        this.cwd = options.cwd ?? process.cwd();
+    }
+    check(files) {
+        // Every file's Defines share one scope, as they do when the tests run.
+        const vocabulary = new Scope(new Scope(null, this.options.words));
+        this.vocabulary = vocabulary;
+        for (const v of files.flatMap((f) => f.vocabulary)) {
+            const origin = fileOrigin(v);
+            try {
+                const sim = new Sim(false);
+                this.run(v.program, vocabulary, sim, origin);
+                this.settle(sim);
+            }
+            catch (err) {
+                this.report.vocabulary.push(this.diagnose(err, origin));
+            }
+        }
+        // Defines are checked once all of them are known, since a Define can use
+        // one from a later file. Unused ones are checked too.
+        for (const def of this.defs) {
+            this.checkDefine(def);
+            if (def.error)
+                this.report.vocabulary.push(def.error);
+        }
+        this.overloads(vocabulary);
+        for (const { features } of files) {
+            for (const scenario of features.flatMap((f) => f.scenarios)) {
+                const problem = this.scenario(scenario, vocabulary);
+                if (problem)
+                    this.report.scenarios.set(scenario, problem);
+            }
+        }
+        return this.report;
+    }
+    scenario(scenario, vocabulary) {
+        const scope = new Scope(vocabulary);
+        // The scenario's own stack, where each keyword leaves its mode.
+        const modes = new Sim(false);
+        for (const step of scenario.steps) {
+            const origin = stepOrigin(step);
+            this.stepScopes.set(step, scope);
+            try {
+                if (step.error !== undefined)
+                    throw step.error;
+                // Its keyword takes the step, and the mode above it if it needs one.
+                modes.stack.push({ ty: StepType, shown: 'the step' });
+                try {
+                    const forms = keywordForms(KEYWORDS, step.keywordType);
+                    this.call(step.keyword.trim(), forms.map((f) => this.formWay(step.keyword.trim(), f)), modes);
+                }
+                catch (err) {
+                    if (err instanceof Mistake)
+                        err.pos = -step.keyword.length;
+                    throw err;
+                }
+                const sim = new Sim(false);
+                if (typeof step.argument === 'string')
+                    sim.stack.push({ ty: TextType, shown: JSON.stringify(step.argument) });
+                else if (step.argument)
+                    sim.stack.push({ ty: TableType, shown: 'the table' });
+                this.run(step.program ?? [], scope, sim, origin);
+                this.settle(sim);
+            }
+            catch (err) {
+                return this.diagnose(err, origin);
+            }
+        }
+    }
+    settle(sim) {
+        // A noun's value is settled as what it is underneath.
+        const problem = this.options.settle(sim.stack.map((v) => ({ name: nameOf(isType(v.ty) ? root(v.ty) : v.ty), shown: show(v) })));
+        if (problem)
+            throw new Mistake(problem);
+    }
+    // ---------------------------------------------------------------- for editors
+    scopeFor(at) {
+        const scope = at && ('keyword' in at ? this.stepScopes.get(at) : this.lineScopes.get(`${at.file}:${at.line}`));
+        return scope ?? this.vocabulary;
+    }
+    info(known) {
+        const { name } = known;
+        if (known.kind === 'forms') {
+            return {
+                name,
+                kind: 'builtin',
+                signatures: known.forms.map((f) => signature(name, f)),
+                outputs: known.forms.map((f) => (f.output ? membersOf(f.output) : [])),
+            };
+        }
+        if (known.kind === 'value') {
+            return {
+                name,
+                kind: 'value',
+                signatures: [`${name} : ${nameOf(known.val.ty)}`],
+                outputs: [membersOf(known.val.ty)],
+            };
+        }
+        const signatures = [];
+        const outputs = [];
+        for (const def of known.defs) {
+            this.checkDefine(def);
+            if (!def.outputs) {
+                signatures.push(`${name} : (has a mistake)`);
+                continue;
+            }
+            const inputs = def.params.map((p) => p.type.name + (p.name !== p.type.name ? ` (${p.name})` : '')).join(', ');
+            const leaves = def.noun ? def.noun.name : def.outputs.map((o) => nameOf(o.ty)).join(', ');
+            signatures.push(`${name} : ${inputs}${inputs ? ' ' : ''}->${leaves ? ` ${leaves}` : ''}`);
+            const last = def.outputs.at(-1);
+            // A noun leaves its kind, and is offered where what it narrows is wanted.
+            outputs.push(...(def.noun ? [def.noun.members, root(def.noun).members] : [last ? membersOf(last.ty) : []]));
+        }
+        const places = known.defs.map((d) => d.at);
+        return { name, kind: 'define', signatures, outputs, at: places[0], places };
+    }
+    expected(left, scope) {
+        // Whatever's written next runs before left does, so left finds it on
+        // top of the stack: the first thing left takes from below is it.
+        let program;
+        try {
+            program = parse(left);
+        }
+        catch {
+            return null;
+        }
+        const statement = program.at(-1);
+        if (!statement)
+            return null;
+        const sim = new Sim(true);
+        this.guessing = true;
+        try {
+            this.run([statement], new Scope(scope), sim, { file: '', at: () => ({ line: 0, column: 0 }) });
+        }
+        catch {
+            return null;
+        }
+        finally {
+            this.guessing = false;
+        }
+        const next = sim.inputs[0];
+        return next ? { members: next.members, phrase: next.phrase } : null;
+    }
+    diagnose(err, origin, define) {
+        if (!(err instanceof Error))
+            throw err;
+        // Anything but a mistake in the .spp file is a bug in Spec++.
+        if (!(err instanceof Mistake) && err.name !== 'SppError')
+            throw err;
+        const { line, column } = origin.at(err.pos ?? 0);
+        return { file: origin.file, line, column, message: err.message, define };
+    }
+    // Statements run in order, each right to left, as they do for real.
+    run(program, scope, sim, origin) {
+        for (const statement of program) {
+            for (let n = statement.length - 1; n >= 0; n--) {
+                const node = statement[n];
+                try {
+                    this.evaluate(node, scope, sim, origin);
+                }
+                catch (err) {
+                    if (err instanceof Mistake && err.pos === undefined)
+                        err.pos = node.pos;
+                    throw err;
+                }
+            }
+        }
+    }
+    evaluate(node, scope, sim, origin) {
+        switch (node.type) {
+            case 'str':
+                return void sim.stack.push({ ty: TextType, shown: JSON.stringify(node.value) });
+            case 'num':
+                return void sim.stack.push({ ty: NumberType, shown: String(node.value) });
+            case 'sym':
+                return void sim.stack.push({ ty: SymbolType, shown: `\\${node.value}` });
+            case 'block':
+                return void sim.stack.push({ ty: new BlockOf(node.body, scope, origin), shown: 'a block' });
+            case 'define': {
+                const block = this.take(sim, `Define ${node.name}`);
+                if (!(block.ty instanceof BlockOf)) {
+                    throw new Mistake(`Define ${node.name} expected an indented block after a colon, but got ${block.shown}`);
+                }
+                // Its header is checked with its body, once every Define is known,
+                // since it may take a noun Defined later.
+                const def = {
+                    name: node.name,
+                    block: block.ty,
+                    at: { file: origin.file, ...origin.at(node.pos) },
+                    header: node.params,
+                    params: [],
+                    state: 'unchecked',
+                };
+                this.defs.push(def);
+                const here = scope.words.get(node.name.toLowerCase());
+                if (here?.kind === 'define')
+                    return void here.defs.push(def);
+                return scope.set({ name: node.name, kind: 'define', defs: [def] });
+            }
+            case 'word': {
+                const known = scope.lookup(node.name);
+                if (!known)
+                    throw new Mistake(unknownWord(node.name, scope.names()).message);
+                if (known.kind === 'value')
+                    return void sim.stack.push(known.val);
+                if (known.kind === 'forms')
+                    return this.call(node.name, known.forms.map((f) => this.formWay(node.name, f)), sim);
+                const way = this.call(node.name, this.defineWays(known.defs), sim);
+                if (way.def && !this.guessing)
+                    this.chosen.set(placeKey({ file: origin.file, ...origin.at(node.pos) }), way.def);
+                return;
+            }
+        }
+    }
+    // What a Define's header takes, checked.
+    params(def) {
+        const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+        return def.header.map((p, i) => {
+            const at = (message) => Object.assign(new SppError(message), { pos: p.pos });
+            if (def.header.findIndex((q) => same(q.name, p.name)) < i) {
+                throw at(`Two things are called ${p.name}. Name them, as in ${p.kind} (Source) and ${p.kind} (Target)`);
+            }
+            // The name hides the word in the body. That's the point for a noun
+            // taken by its own name, a Cart called Cart; anything else is a mistake.
+            const hidden = def.block.scope.lookup(p.name);
+            if (hidden && !(hidden.kind === 'define' && same(p.name, p.kind))) {
+                throw at(same(p.name, p.kind)
+                    ? `${p.name} is already a word, so name this one, as in ${p.kind} (Item)`
+                    : `${p.name} is already a word, so call this one something else`);
+            }
+            try {
+                return { name: p.name, type: this.kindOf(p.kind, def.block.scope) };
+            }
+            catch (err) {
+                if (err instanceof Mistake && err.pos === undefined)
+                    err.pos = p.pos;
+                throw err;
+            }
+        });
+    }
+    // A kind a header names: a built-in one, or a noun's.
+    kindOf(name, scope) {
+        const builtin = this.options.words.kindOf(name);
+        if (builtin)
+            return builtin;
+        const known = scope.lookup(name);
+        if (known?.kind !== 'define')
+            throw new Mistake(notAKind(name, this.options.words.builtinKinds()));
+        if (known.defs.length > 1)
+            throw new Mistake(`${name} can't be a kind: a noun has one Define, and it has ${known.defs.length}`);
+        const [def] = known.defs;
+        this.checkDefine(def);
+        if (def.error)
+            throw new Mistake(`${def.name} can't be a kind: its Define has a mistake, at ${this.where(def.error)}`);
+        if (!def.noun) {
+            throw new Mistake(`${def.name} can't be a kind: only a noun can, a Define that leaves one thing, like something on the page`);
+        }
+        return def.noun;
+    }
+    // The kind a Define makes of what it leaves, if it's a noun: one thing, of
+    // a built-in kind other than Any. The runtime decides the same, from values.
+    nounOf(def, outputs) {
+        if (outputs.length !== 1 || !isType(outputs[0].ty))
+            return;
+        const have = root(outputs[0].ty).members;
+        const base = [...this.options.words.builtinKinds()].find((k) => k !== AnyType && have.length > 0 && have.every((m) => k.members.includes(m)));
+        if (!base)
+            return;
+        return { name: def.name, phrase: article(def.name), members: [def.name], base, test: (v) => false };
+    }
+    // Each word's Defines, two at a time: a noun can't share its name, since
+    // it's a kind, and two that could always both fit leave a use guessing.
+    overloads(vocabulary) {
+        for (const known of vocabulary.words.values()) {
+            if (known.kind !== 'define')
+                continue;
+            const defs = known.defs.filter((d) => !d.error);
+            for (const [j, b] of defs.entries()) {
+                const a = defs.slice(0, j).find((a) => a.noun || b.noun || clash(a, b));
+                if (!a)
+                    continue;
+                const where = this.where(a.at);
+                const message = a.noun || b.noun
+                    ? `${b.name} is a noun, so it can only have one Define, and there's another at ${where}`
+                    : clash(a, b) === 'same'
+                        ? `${b.name} takes the same things here as at ${where}, so there'd be no telling which one a step means`
+                        : `${b.name} here and at ${where} could both take the same things, and neither takes narrower kinds, so there'd be no telling which one a step means`;
+                b.error = { ...b.at, message, define: b.name };
+                this.report.vocabulary.push(b.error);
+            }
+        }
+    }
+    where(d) {
+        return `${path.relative(this.cwd, d.file)}:${d.line}:${d.column}`;
+    }
+    take(sim, word) {
+        const v = sim.stack.pop();
+        if (v)
+            return v;
+        if (sim.open)
+            return sim.fromCaller();
+        throw new Mistake(`${word} expected a value, but there was nothing left`);
+    }
+    formWay(name, form) {
+        return {
+            inputs: form.inputs.map((t) => ({ members: membersOf(t), phrase: t.phrase, key: t })),
+            outputs: (args) => (form.output ? [{ ty: form.output, shown: [name, ...args.map(show)].join(' ') }] : []),
+        };
+    }
+    // A Define's way: what its header takes, and what its body leaves.
+    // A word's Defines, most particular first, as the runtime orders them.
+    defineWays(defs) {
+        return defs
+            .map((def) => ({ def, way: this.defineWay(def) }))
+            .sort((a, b) => b.way.inputs.length - a.way.inputs.length || specificity(b.def) - specificity(a.def))
+            .map(({ way }) => way);
+    }
+    defineWay(def) {
+        this.checkDefine(def);
+        if (def.error) {
+            throw new Mistake(`${def.name} can't be used: its Define has a mistake, at ${this.where(def.error)}: ${def.error.message}`);
+        }
+        const { outputs, noun } = def;
+        const inputs = def.params.map((p) => ({ members: membersOf(p.type), phrase: p.type.phrase, key: p }));
+        if (noun)
+            return { inputs, outputs: (args) => [{ ty: noun, shown: [def.name, ...args.map(show)].join(' ') }], def };
+        // A vocabulary bug: checkDefine says what a Define leaves.
+        if (!outputs)
+            throw new Error(`Checked ${def.name}'s Define, but it leaves nothing known`);
+        return { inputs, outputs: () => outputs, def };
+    }
+    // Runs a Define's body with what its header takes, by name, and nothing
+    // below that.
+    checkDefine(def) {
+        if (def.state === 'done')
+            return;
+        if (def.state === 'checking')
+            throw new Mistake(`${def.name} uses itself, so it would never finish`);
+        def.state = 'checking';
+        try {
+            def.params = this.params(def);
+            const scope = new Scope(def.block.scope);
+            for (const p of def.params)
+                scope.set({ name: p.name, kind: 'value', val: { ty: p.type, shown: p.name } });
+            // Its header and body see what the header takes.
+            const { origin } = def.block;
+            for (const line of [def.at.line, ...def.block.body.flatMap((s) => (s[0] ? [origin.at(s[0].pos).line] : []))]) {
+                this.lineScopes.set(`${origin.file}:${line}`, scope);
+            }
+            const sim = new Sim(false);
+            this.run(def.block.body, scope, sim, def.block.origin);
+            def.outputs = sim.stack;
+            def.noun = this.nounOf(def, sim.stack);
+        }
+        catch (err) {
+            def.error = this.diagnose(err, def.block.origin, def.name);
+        }
+        finally {
+            def.state = 'done';
+        }
+    }
+    // Calls the way the runtime would pick: the first whose inputs are on top
+    // of the stack.
+    call(name, ways, sim) {
+        const fits = ways.flatMap((way) => {
+            const fit = this.fit(way, sim);
+            return fit ? [{ way, ...fit }] : [];
+        });
+        if (!fits.length)
+            throw this.mismatch(name, ways, sim);
+        // On an open stack, a form with an optional last input, like a query's
+        // Scope, would always fit by taking it from below, or by deciding a
+        // variable must be one. Unless it's known to be there, prefer the form
+        // without it.
+        const shorter = fits.filter((f) => !fits.some((g) => g !== f && g.unsure < f.unsure && isPrefix(g.way.inputs, f.way.inputs)));
+        let [chosen] = shorter;
+        const known = chosen.fresh === 0 && chosen.binds.size === 0;
+        if (shorter.length > 1 && !known) {
+            if (this.guessing) {
+                // For an editor's guess, any of them will do: each input may be any
+                // of what they'd take there.
+                const way = anyOf(shorter.map((f) => f.way));
+                const fit = this.fit(way, sim);
+                // A checker bug: each of them fits, so any of them together does.
+                if (!fit)
+                    throw new Error(`${name}'s forms each fit, but not together`);
+                chosen = { way, ...fit };
+            }
+            else {
+                const alternatives = [...new Set(shorter.map((f) => f.way.inputs.map((w) => w.phrase).join(' and ')))];
+                throw new Mistake(`Can't tell how ${name} is being used here: it could take ${alternatives.join(', or ')}`);
+            }
+        }
+        for (const [v, want] of chosen.binds) {
+            v.members = want.members;
+            v.phrase = want.phrase;
+        }
+        const n = chosen.way.inputs.length;
+        const args = chosen.way.inputs.map((want, i) => sim.peek(i) ?? sim.fromCaller(want));
+        sim.stack.length = Math.max(0, sim.stack.length - n);
+        sim.stack.push(...chosen.way.outputs(args));
+        return chosen.way;
+    }
+    // Whether a way's inputs are on top of the stack, and what that would
+    // narrow the stack's variables to. fresh counts inputs taken from a caller;
+    // unsure counts those plus inputs that are variables.
+    fit(way, sim) {
+        const binds = new Map();
+        let fresh = 0;
+        let unsure = 0;
+        for (let i = 0; i < way.inputs.length; i++) {
+            const want = way.inputs[i];
+            const v = sim.peek(i);
+            if (!v) {
+                if (!sim.open)
+                    return null;
+                fresh++;
+                unsure++;
+                continue;
+            }
+            if (v.ty instanceof Var)
+                unsure++;
+            const wanted = want.members;
+            if (wanted === null)
+                continue;
+            if (v.ty instanceof Var) {
+                const now = binds.get(v.ty)?.members ?? v.ty.members;
+                const narrowed = now === null ? wanted : now.filter((m) => wanted.includes(m));
+                if (!narrowed.length)
+                    return null;
+                binds.set(v.ty, { ...want, members: narrowed });
+            }
+            else if (!accepts(want, v))
+                return null;
+        }
+        return { binds, fresh, unsure };
+    }
+    // Says what was wanted at the first place every way had given up, as the
+    // runtime does.
+    mismatch(name, ways, sim) {
+        let live = ways;
+        for (let i = 0;; i++) {
+            const here = live.filter((w) => w.inputs.length > i);
+            const v = sim.peek(i);
+            const ok = v ? here.filter((w) => accepts(w.inputs[i], v)) : [];
+            if (!ok.length || !here.length) {
+                const wanted = [...new Set(here.map((w) => w.inputs[i].phrase))].join(', or ') || 'something else';
+                return new Mistake(`${name} expected ${wanted}, but ${v ? `got ${show(v)}` : 'there was nothing left'}`);
+            }
+            live = ok;
+        }
+    }
+}
+function accepts(want, v) {
+    const have = membersOf(v.ty);
+    const wanted = want.members;
+    if (wanted === null || have === null)
+        return true;
+    if (v.ty instanceof Var)
+        return have.some((m) => wanted.includes(m));
+    if (have.every((m) => wanted.includes(m)))
+        return true;
+    // A Cart is an Element too.
+    return isType(v.ty) && !!v.ty.base && accepts(want, { ...v, ty: v.ty.base });
+}
+const isType = (ty) => !(ty instanceof Var) && !(ty instanceof BlockOf);
+// Whether two Defines of a word could always both fit: 'same' if they take
+// the same kinds, 'ambiguous' if each is narrower somewhere. They can't both
+// fit if they take different numbers of things, or if at some place neither
+// kind is within the other; and if one is narrower throughout, it's chosen.
+function clash(a, b) {
+    if (a.params.length !== b.params.length)
+        return null;
+    let aNarrower = false;
+    let bNarrower = false;
+    for (const [i, p] of a.params.entries()) {
+        const x = p.type;
+        const y = b.params[i].type;
+        const xInY = within(x, y);
+        const yInX = within(y, x);
+        if (xInY && yInX)
+            continue;
+        if (!xInY && !yInX)
+            return null;
+        if (xInY)
+            aNarrower = true;
+        else
+            bNarrower = true;
+    }
+    return !aNarrower && !bNarrower ? 'same' : aNarrower && bNarrower ? 'ambiguous' : null;
+}
+// Whether every value of kind x is one of kind y: a Cart is an Element, and
+// everything is Any.
+function within(x, y) {
+    if (y.name === AnyType.name || x.name.toLowerCase() === y.name.toLowerCase())
+        return true;
+    return !!x.base && within(x.base, y);
+}
+// What a noun's kind is underneath: Element, for a Cart.
+const root = (t) => (t.base ? root(t.base) : t);
+function anyOf(ways) {
+    const length = Math.max(...ways.map((w) => w.inputs.length));
+    const inputs = Array.from({ length }, (_, i) => {
+        const here = ways.flatMap((w) => (w.inputs[i] ? [w.inputs[i]] : []));
+        // Any value, if any of them takes any value.
+        const known = here.flatMap((w) => (w.members === null ? [] : [w.members]));
+        const members = known.length < here.length ? null : [...new Set(known.flat())];
+        return { members, phrase: [...new Set(here.map((w) => w.phrase))].join(', or '), key: undefined };
+    });
+    return { inputs, outputs: ways[0].outputs };
+}
+function isPrefix(short, long) {
+    return short.length < long.length && short.every((w, i) => w.key === long[i].key);
+}
+// ---------------------------------------------------------------- output
+// A diagnostic as a person reads it: where, the line, and what's wrong.
+export function format(d, source, cwd = process.cwd()) {
+    const text = source.split('\n')[d.line - 1] ?? '';
+    const indent = text.length - text.trimStart().length;
+    const caret = `${' '.repeat(Math.max(0, d.column - 1 - indent))}^`;
+    const where = d.define ? ` (in Define ${d.define})` : '';
+    return [
+        `${path.relative(cwd, d.file)}:${d.line}:${d.column}${where}`,
+        `    ${text.trim()}`,
+        `    ${caret}`,
+        `  ${d.message}`,
+    ].join('\n');
+}