@delurio/cli 0.0.0 → 0.1.1

package/dist/nav.js

@@ -0,0 +1,566 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { evaluate, identifiers, parseExpr } from './expr.js';
+import { GraphError } from './graph.js';
+const PAGE_KINDS = ['screen', 'placeholder', 'missing', 'redirect', 'external'];
+const HOWS = ['auto', 'menu', 'picker', 'user', 'link', 'button'];
+// an entry of the frame (menu, scope picker, person row) is drawn even around a page that refuses the person
+const FRAME_LEVEL = ['menu', 'picker', 'user'];
+export const frameLevel = (e) => FRAME_LEVEL.includes(e.how);
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+// nav.yaml may extend a generated file (nav.extracted.yaml): its pages, guards and entries come first, and the hand-written
+// file adds to them or overrides single fields of a page. A guard may not be defined twice with different text.
+function mergeDocs(base, hand) {
+    const pages = {};
+    for (const [id, p] of Object.entries(base.pages ?? {}))
+        pages[id] = { ...p, ...(own(hand.pages ?? {}, id) ? hand.pages[id] : {}) };
+    for (const [id, p] of Object.entries(hand.pages ?? {})) {
+        if (own(pages, id))
+            continue;
+        if (p.route === undefined)
+            throw new GraphError(`page ${id} is not in the extracted file and gives no route (a misspelt override?)`);
+        pages[id] = p;
+    }
+    const guards = { ...(base.guards ?? {}) };
+    for (const [name, src] of Object.entries(hand.guards ?? {})) {
+        if (own(guards, name) && guards[name] !== src)
+            throw new GraphError(`guard ${name} is written in both the extracted file and nav.yaml, with different text`);
+        guards[name] = src;
+    }
+    return { ...hand, pages, guards, entries: [...(base.entries ?? []), ...(hand.entries ?? [])], source: { ...(base.source ?? {}), ...(hand.source ?? {}) } };
+}
+// `read` takes a path relative to `dir`; the revision diff passes one that reads a git revision instead of the disk
+export function loadNav(dir, locale, read = (file) => readFileSync(join(dir, file), 'utf8')) {
+    const raw = parse(read('nav.yaml'));
+    const doc = raw.extends === undefined ? raw : mergeDocs(parse(read(raw.extends)), raw);
+    const warnings = [];
+    if (doc.kind !== 'nav')
+        throw new GraphError(`${join(dir, 'nav.yaml')} is not a navigation graph (kind: nav is missing)`);
+    const catalogFile = locale === undefined ? doc.catalog : doc.catalog.replace(`${doc.locale}.json`, `${locale}.json`);
+    const catalog = JSON.parse(read(catalogFile));
+    const guards = doc.guards ?? {};
+    const facts = doc.facts ?? {};
+    const sets = doc.sets ?? {};
+    const known = (name) => own(facts, name) || own(guards, name);
+    const checkGuard = (src, where) => {
+        let e;
+        try {
+            e = parseExpr(src);
+        }
+        catch (err) {
+            throw new GraphError(`${where}: ${err.message}`);
+        }
+        for (const name of identifiers(e))
+            if (!known(name))
+                throw new GraphError(`${where}: "${name}" is neither a fact nor a named guard`);
+    };
+    for (const [name, src] of Object.entries(guards))
+        checkGuard(src, `guard ${name}`);
+    const looksLikeKey = (s) => /^[A-Za-z][A-Za-z0-9]*(\.[A-Za-z0-9]+)+$/.test(s);
+    const resolveLabel = (s, where) => {
+        if (own(catalog, s))
+            return { text: catalog[s], key: s };
+        if (looksLikeKey(s))
+            warnings.push(`${where}: "${s}" looks like a catalog key but the catalog has no such key`);
+        return { text: s, key: null };
+    };
+    const frames = doc.frames ?? {};
+    if (Object.keys(frames).length === 0)
+        throw new GraphError('a navigation graph declares its frames (frames:)');
+    for (const [name, f] of Object.entries(frames)) {
+        if (f.shows !== undefined && !own(facts, f.shows.fact))
+            throw new GraphError(`frame ${name} shows the menu named by ${f.shows.fact}, which is not a fact`);
+    }
+    const pages = {};
+    for (const [id, p] of Object.entries(doc.pages)) {
+        if (!PAGE_KINDS.includes(p.kind))
+            throw new GraphError(`page ${id}: unknown kind ${p.kind}`);
+        if (!own(frames, p.frame))
+            throw new GraphError(`page ${id}: unknown frame ${p.frame}`);
+        if (p.opensFor !== undefined)
+            checkGuard(p.opensFor, `page ${id} opensFor`);
+        const title = p.title === undefined ? { text: id, key: null } : resolveLabel(p.title, `page ${id}`);
+        pages[id] = {
+            id,
+            route: p.route,
+            title: title.text,
+            titleKey: title.key,
+            kind: p.kind,
+            frame: p.frame,
+            source: p.source ?? null,
+            opensFor: p.opensFor ?? null,
+            pageCodes: p.pageCodes ?? null,
+            evidence: p.evidence ?? null,
+            refusal: p.refusal ?? null,
+        };
+    }
+    if (pages.start === undefined)
+        throw new GraphError('a navigation graph needs a page called start');
+    const entries = [];
+    const specs = doc.entries ?? [];
+    specs.forEach((s, spec) => {
+        const where = `entry ${spec + 1} (${String(s.to)})`;
+        if (!HOWS.includes(s.how))
+            throw new GraphError(`${where}: unknown how ${s.how}`);
+        if (pages[s.to] === undefined)
+            throw new GraphError(`${where}: goes to ${s.to}, which is not a page`);
+        if (s.when !== undefined)
+            checkGuard(s.when, `${where} when`);
+        const label = s.label === undefined ? { text: '', key: null } : resolveLabel(s.label, where);
+        if (label.text === '' && s.how !== 'auto')
+            throw new GraphError(`${where}: needs a label`);
+        for (const token of Array.isArray(s.from) ? s.from : [s.from]) {
+            const sources = [];
+            let ofFrame = null;
+            if (token.startsWith('frame:')) {
+                const frame = token.slice('frame:'.length);
+                if (!own(frames, frame))
+                    throw new GraphError(`${where}: unknown frame in ${token}`);
+                ofFrame = frame;
+                for (const p of Object.values(pages)) {
+                    if (p.frame === frame)
+                        sources.push({ page: p.id, implicit: null });
+                    // a page whose frame shows the menu of another frame is drawn with this frame's menu when the person's fact names it
+                    const shows = frames[p.frame].shows;
+                    if (shows !== undefined && p.frame !== frame && frames[frame].menu !== undefined)
+                        sources.push({ page: p.id, implicit: `${shows.fact} == '${frame}'` });
+                }
+                if (sources.length === 0)
+                    throw new GraphError(`${where}: no page is in ${token}`);
+            }
+            else {
+                if (pages[token] === undefined)
+                    throw new GraphError(`${where}: starts at ${token}, which is not a page`);
+                sources.push({ page: token, implicit: null });
+            }
+            for (const src of sources) {
+                if (src.page === s.to && frameLevelHow(s.how))
+                    continue; // the page you are on is not a way to itself
+                const parts = [src.implicit, s.when ?? null].filter((x) => x !== null);
+                entries.push({
+                    id: s.id ?? `${src.page}>${s.to}#${spec + 1}`,
+                    spec,
+                    from: src.page,
+                    ofFrame,
+                    to: s.to,
+                    how: s.how,
+                    label: label.text,
+                    labelKey: label.key,
+                    when: parts.length === 0 ? null : parts.length === 1 ? parts[0] : parts.map((x) => `(${x})`).join(' and '),
+                    clicks: s.clicks ?? (s.how === 'auto' ? 0 : 1),
+                    data: s.data === true,
+                    back: s.back === true,
+                    order: entries.length,
+                });
+            }
+        }
+    });
+    const personas = Object.entries(doc.personas).map(([id, p]) => {
+        const f = {};
+        for (const [name, spec] of Object.entries(facts)) {
+            if (!own(p.facts, name))
+                throw new GraphError(`persona ${id} gives no value for ${name}`);
+            let v = p.facts[name];
+            if (spec.of !== undefined) {
+                if (typeof v === 'string') {
+                    if (!own(sets, v))
+                        throw new GraphError(`persona ${id}: ${v} is not a named set`);
+                    v = sets[v];
+                }
+                if (!Array.isArray(v))
+                    throw new GraphError(`persona ${id}: ${name} must be a list`);
+                for (const item of v)
+                    if (!spec.of.includes(String(item)))
+                        throw new GraphError(`persona ${id}: ${String(item)} is not one of the values of ${name}`);
+            }
+            else if (spec.values !== undefined && !spec.values.includes(v)) {
+                throw new GraphError(`persona ${id}: ${String(v)} is not a value of ${name}`);
+            }
+            f[name] = v;
+        }
+        for (const name of Object.keys(p.facts))
+            if (!own(facts, name))
+                throw new GraphError(`persona ${id} gives ${name}, which is not a declared fact`);
+        return { id, title: p.title, say: p.say, facts: f };
+    });
+    const notModeled = doc.notModeled ?? [];
+    notModeled.forEach((x, i) => {
+        if (typeof x !== 'string')
+            throw new GraphError(`notModeled item ${i + 1} is not text (a colon followed by a space turns a line into a map: quote it)`);
+    });
+    const goals = doc.goals ?? [];
+    for (const goal of goals) {
+        if (pages[goal.page] === undefined)
+            throw new GraphError(`goal ${goal.id}: ${goal.page} is not a page`);
+        for (const who of goal.for)
+            if (!personas.some((p) => p.id === who))
+                throw new GraphError(`goal ${goal.id}: ${who} is not a persona`);
+    }
+    return {
+        g: {
+            dir,
+            adapter: doc.extract?.adapter ?? null,
+            frames,
+            menuFrames: Object.entries(frames).filter(([, f]) => f.menu !== undefined).map(([name]) => name),
+            id: doc.id,
+            title: doc.title,
+            status: doc.status,
+            summary: (doc.summary ?? '').trim(),
+            locale: locale ?? doc.locale,
+            source: doc.source ?? {},
+            facts,
+            guards,
+            pages,
+            entries,
+            specs,
+            personas,
+            goals,
+            notModeled,
+            catalog,
+        },
+        warnings,
+    };
+}
+function frameLevelHow(how) {
+    return FRAME_LEVEL.includes(how);
+}
+function lookupFor(g, p, depth) {
+    return (name) => {
+        if (own(p.facts, name))
+            return p.facts[name];
+        const guard = g.guards[name];
+        if (guard === undefined)
+            throw new GraphError(`unknown name "${name}"`);
+        if (depth > 8)
+            throw new GraphError(`guard ${name} nests too deep`);
+        return evaluate(parseExpr(guard), lookupFor(g, p, depth + 1));
+    };
+}
+export function holds(g, p, expr) {
+    return expr === null ? true : Boolean(evaluate(parseExpr(expr), lookupFor(g, p, 0)));
+}
+export const refusedFor = (g, p, page) => {
+    const guard = g.pages[page].opensFor;
+    return guard !== null && !holds(g, p, guard);
+};
+// Fewest clicks from "start"; ties go to the entry written first. Around a page that refuses the person only the frame's own entries work.
+export function walk(g, p) {
+    const best = new Map();
+    const done = new Set();
+    const index = (id) => Object.keys(g.pages).indexOf(id);
+    best.set('start', { page: 'start', clicks: 0, via: null, prev: null, usesData: false });
+    for (;;) {
+        let pick = null;
+        for (const r of best.values()) {
+            if (done.has(r.page))
+                continue;
+            if (pick === null || r.clicks < pick.clicks || (r.clicks === pick.clicks && index(r.page) < index(pick.page)))
+                pick = r;
+        }
+        if (pick === null)
+            break;
+        done.add(pick.page);
+        const refused = refusedFor(g, p, pick.page);
+        for (const e of g.entries) {
+            if (e.from !== pick.page)
+                continue;
+            if (refused && !frameLevel(e))
+                continue;
+            if (!holds(g, p, e.when))
+                continue;
+            const clicks = pick.clicks + e.clicks;
+            const held = best.get(e.to);
+            if (held === undefined || clicks < held.clicks)
+                best.set(e.to, { page: e.to, clicks, via: e, prev: pick.page, usesData: pick.usesData || e.data });
+        }
+    }
+    return best;
+}
+export function pathTo(reach, page) {
+    const out = [];
+    let cur = reach.get(page);
+    while (cur !== undefined && cur.via !== null) {
+        out.unshift(cur.via);
+        cur = cur.prev === null ? undefined : reach.get(cur.prev);
+    }
+    return out;
+}
+export function viewOf(g, p) {
+    const reach = walk(g, p);
+    const standing = {};
+    for (const id of Object.keys(g.pages)) {
+        if (!reach.has(id))
+            standing[id] = 'unreachable';
+        else if (refusedFor(g, p, id))
+            standing[id] = 'refused';
+        else
+            standing[id] = g.pages[id].kind === 'placeholder' ? 'placeholder' : g.pages[id].kind === 'missing' ? 'missing' : 'ok';
+    }
+    const auto = g.entries.find((e) => e.from === 'start' && e.how === 'auto' && holds(g, p, e.when));
+    // a start page that is a screen (not a redirect) is where the person lands when no rule sends them on
+    const landing = auto !== undefined ? auto.to : g.pages.start.kind === 'redirect' ? null : 'start';
+    return { persona: p, reach, standing, landing };
+}
+export const frameReached = (g, v, frame) => Object.values(g.pages).some((pg) => pg.frame === frame && v.standing[pg.id] !== 'unreachable');
+export function menuRows(g, views) {
+    const seen = new Set();
+    const rows = [];
+    for (const e of g.entries) {
+        if (e.how !== 'menu' || seen.has(e.spec))
+            continue;
+        seen.add(e.spec);
+        const frame = e.ofFrame ?? g.pages[e.from].frame;
+        const frameKnown = views.map((v) => frameReached(g, v, frame));
+        rows.push({
+            spec: e.spec,
+            frame,
+            entry: e,
+            frameKnown,
+            cells: views.map((v, i) => {
+                if (!frameKnown[i])
+                    return { shown: false, standing: null };
+                const shown = holds(g, v.persona, g.specs[e.spec].when ?? null);
+                return { shown, standing: shown ? standingAfterMenu(g, v, e.to) : null };
+            }),
+        });
+    }
+    return rows;
+}
+function standingAfterMenu(g, v, page) {
+    if (refusedFor(g, v.persona, page))
+        return 'refused';
+    return g.pages[page].kind === 'placeholder' ? 'placeholder' : g.pages[page].kind === 'missing' ? 'missing' : 'ok';
+}
+const lower = (s) => s.toLocaleLowerCase('tr');
+const word = (g, key) => g.catalog[key] ?? key;
+const quote = (s) => `“${s}”`;
+const joinWords = (xs) => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`);
+// the words on the way in and on arrival name the same thing: one contains the other, or they share a stem
+// (Turkish suffixes: hesap, hesabım)
+function similar(a, b) {
+    if (a.includes(b) || b.includes(a))
+        return true;
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i += 1;
+    return i >= 4 && i >= 0.6 * Math.min(a.length, b.length);
+}
+export function checkGoals(g, views) {
+    const out = [];
+    for (const goal of g.goals) {
+        for (const who of goal.for) {
+            const v = views.find((x) => x.persona.id === who);
+            if (v === undefined)
+                continue;
+            const standing = v.standing[goal.page];
+            const clicks = v.reach.get(goal.page)?.clicks ?? null;
+            const outcome = standing === 'unreachable' ? 'cannot reach' : standing === 'refused' ? 'refused' : standing === 'placeholder' ? 'not built' : standing === 'missing' ? 'does not exist' : (clicks ?? 0) > goal.within ? 'too many clicks' : 'ok';
+            out.push({ goal, persona: v.persona, outcome, clicks });
+        }
+    }
+    return out;
+}
+export function findings(g, views, goals) {
+    const out = [];
+    const rows = menuRows(g, views);
+    const personaTitle = (i) => views[i].persona.title;
+    const who = (xs) => joinWords(xs.map(quote));
+    const menuName = (frame) => (g.frames[frame].menu ?? frame).toLowerCase();
+    // 1. the first page a person sees is not built
+    const landing = views.filter((v) => v.landing !== null && g.pages[v.landing].kind === 'placeholder');
+    if (landing.length > 0) {
+        const targets = [...new Set(landing.map((v) => v.landing))];
+        out.push({
+            level: 'problem',
+            code: 'landing-not-built',
+            say: `${who(landing.map((v) => v.persona.title))} ${landing.length === 1 ? 'lands' : 'land'} on a page that says it is not ready.`,
+            detail: targets.map((t) => {
+                const people = landing.filter((v) => v.landing === t).map((v) => v.persona.title);
+                return `“/” sends ${who(people)} to ${quote(g.pages[t].title)} (${g.pages[t].route}), which answers “${word(g, 'Shell.placeholder')}”`;
+            }),
+        });
+    }
+    // 2. the menu offers an entry and the page behind it refuses
+    const gated = [...new Set(rows.filter((r) => /\bheld\b/.test(g.specs[r.spec].when ?? '')).map((r) => r.entry.label))];
+    const refusedLines = [];
+    views.forEach((v, i) => {
+        for (const frame of g.menuFrames) {
+            const inFrame = rows.filter((r) => r.frame === frame && r.cells[i].shown);
+            const of = (s) => inFrame.filter((r) => r.cells[i].standing === s);
+            if (of('refused').length === 0)
+                continue;
+            const parts = [`${of('ok').length} open`, `${of('refused').length} refuse (${of('refused').map((r) => quote(r.entry.label)).join(', ')})`];
+            if (of('placeholder').length > 0)
+                parts.push(`${of('placeholder').length} are not built`);
+            if (of('missing').length > 0)
+                parts.push(`${of('missing').length} lead to a page that does not exist`);
+            refusedLines.push(`${personaTitle(i)}: the ${menuName(frame)} has ${inFrame.length} ${inFrame.length === 1 ? 'entry' : 'entries'}; ${parts.join(', ')}.`);
+        }
+    });
+    if (refusedLines.length > 0) {
+        out.push({
+            level: 'problem',
+            code: 'menu-refused',
+            say: `The menu offers entries whose page then refuses the person. ${gated.length === 0 ? 'No entry is drawn by permission' : `Only ${who(gated)} ${gated.length === 1 ? 'is' : 'are'} drawn by permission`}; every other entry is drawn for everyone and the page decides.`,
+            detail: refusedLines,
+        });
+    }
+    // 2b. a link or button drawn on a page the person can open leads to a page that refuses them
+    const deadLinks = new Map();
+    views.forEach((v) => {
+        for (const e of g.entries) {
+            if (e.how !== 'link' && e.how !== 'button')
+                continue;
+            if (v.standing[e.from] !== 'ok' && v.standing[e.from] !== 'placeholder')
+                continue;
+            if (!holds(g, v.persona, e.when) || !refusedFor(g, v.persona, e.to))
+                continue;
+            const to = g.pages[e.to];
+            deadLinks.set(`${v.persona.id}|${e.from}|${e.to}|${e.label}`, `${v.persona.title}: ${quote(e.label)} on ${quote(g.pages[e.from].title)} leads to ${quote(to.title)}, which ${to.refusal ?? 'refuses them'}.`);
+        }
+    });
+    if (deadLinks.size > 0) {
+        out.push({ level: 'problem', code: 'link-refused', say: 'A link or button is drawn for a person whose destination then refuses them.', detail: [...deadLinks.values()] });
+    }
+    // 3. a menu entry opens a page that is not built
+    const unbuilt = new Map();
+    rows.forEach((r) => {
+        if (g.pages[r.entry.to].kind !== 'placeholder')
+            return;
+        const hit = unbuilt.get(r.entry.to) ?? { labels: new Set(), who: new Set() };
+        r.cells.forEach((c, i) => {
+            if (c.shown)
+                hit.who.add(personaTitle(i));
+        });
+        hit.labels.add(r.entry.label);
+        unbuilt.set(r.entry.to, hit);
+    });
+    if (unbuilt.size > 0) {
+        out.push({
+            level: 'problem',
+            code: 'menu-not-built',
+            say: `${unbuilt.size} pages that the menus offer say “${word(g, 'Shell.placeholder')}”`,
+            detail: [...unbuilt.entries()].map(([page, hit]) => `${[...hit.labels].map(quote).join(' / ')} (${g.pages[page].route}) is in the menu of ${who([...hit.who])}.`),
+        });
+    }
+    // 3b. a menu entry leads to a page that does not exist
+    const gone = new Map();
+    rows.forEach((r) => {
+        if (g.pages[r.entry.to].kind !== 'missing')
+            return;
+        const hit = gone.get(r.entry.to) ?? { labels: new Set(), who: new Set() };
+        r.cells.forEach((c, i) => {
+            if (c.shown)
+                hit.who.add(personaTitle(i));
+        });
+        hit.labels.add(r.entry.label);
+        gone.set(r.entry.to, hit);
+    });
+    if (gone.size > 0) {
+        out.push({
+            level: 'problem',
+            code: 'menu-missing',
+            say: `${gone.size} ${gone.size === 1 ? 'entry' : 'entries'} in the menus lead to a page that does not exist, so the server answers not found.`,
+            detail: [...gone.entries()].map(([page, hit]) => `${[...hit.labels].map(quote).join(' / ')} (${g.pages[page].route}) is in the menu of ${who([...hit.who])}.`),
+        });
+    }
+    // 4. goals that cannot be done
+    const failed = goals.filter((c) => c.outcome !== 'ok');
+    if (failed.length > 0) {
+        out.push({
+            level: 'problem',
+            code: 'goals',
+            say: `${failed.length} of ${goals.length} things people come to do fail.`,
+            detail: failed.map((c) => `${c.persona.title}, ${lower(c.goal.say)}: ${c.outcome === 'too many clicks' ? `${c.clicks} clicks, the limit is ${c.goal.within}` : c.outcome === 'not built' ? 'the page is not built' : c.outcome === 'does not exist' ? 'the page does not exist' : c.outcome === 'refused' ? (g.pages[c.goal.page].refusal ?? 'the page refuses them') : 'there is no way there'}.`),
+        });
+    }
+    // 5. pages nobody can reach
+    const lost = Object.values(g.pages).filter((p) => p.kind !== 'external' && p.kind !== 'redirect' && views.every((v) => v.standing[p.id] === 'unreachable'));
+    if (lost.length > 0) {
+        out.push({ level: 'problem', code: 'unreachable', say: 'Some pages cannot be reached by any kind of user.', detail: lost.map((p) => `${p.title} (${p.route})`) });
+    }
+    // 6. two entries of one menu open the same page
+    const dup = [];
+    views.forEach((v, i) => {
+        for (const frame of g.menuFrames) {
+            const shown = rows.filter((r) => r.frame === frame && r.cells[i].shown);
+            const byTarget = new Map();
+            for (const r of shown)
+                byTarget.set(r.entry.to, [...(byTarget.get(r.entry.to) ?? []), r.entry.label]);
+            for (const [page, labels] of byTarget)
+                if (labels.length > 1)
+                    dup.push(`${personaTitle(i)}: ${joinWords(labels.map(quote))} both open ${g.pages[page].route}.`);
+        }
+    });
+    if (dup.length > 0)
+        out.push({ level: 'note', code: 'menu-twins', say: 'Two entries in one menu open the same page.', detail: dup });
+    // 7. the words on the way in are not the words on arrival
+    const mismatch = new Map();
+    for (const e of g.entries) {
+        const target = g.pages[e.to];
+        if (e.labelKey === null || e.back || e.how === 'auto' || e.how === 'picker' || target.titleKey === null)
+            continue;
+        const a = lower(e.label);
+        const b = lower(target.title);
+        if (similar(a, b))
+            continue;
+        const where = e.how === 'menu' ? `in the ${menuName(e.ofFrame ?? g.pages[e.from].frame)}` : `${e.how} on ${g.pages[e.from].title}`;
+        mismatch.set(`${e.label}|${e.to}|${e.how === 'menu'}`, `${quote(e.label)} (${where}) opens a page titled ${quote(target.title)}.`);
+    }
+    if (mismatch.size > 0)
+        out.push({ level: 'note', code: 'words-differ', say: 'A link or button is named differently from the page it opens.', detail: [...mismatch.values()].sort() });
+    // 8. different pages that carry the same title
+    const titles = new Map();
+    for (const p of Object.values(g.pages)) {
+        if (p.kind === 'redirect' || p.kind === 'external' || p.frame === 'none')
+            continue;
+        titles.set(lower(p.title), [...(titles.get(lower(p.title)) ?? []), p]);
+    }
+    const same = [...titles.values()].filter((ps) => ps.length > 1);
+    if (same.length > 0) {
+        out.push({
+            level: 'note',
+            code: 'same-title',
+            say: 'Different pages share a title, so two tabs or two history entries cannot be told apart.',
+            detail: same.map((ps) => `${quote(ps[0].title)}: ${ps.map((p) => p.route).join(' and ')}`),
+        });
+    }
+    return out;
+}
+// the permission codes a guard asks `'code' in held` about, named guards followed
+export function guardCodes(g, src, depth = 0) {
+    const out = new Set();
+    const visit = (e) => {
+        switch (e.k) {
+            case 'cmp':
+                if (e.op === 'in' && e.l.k === 'lit' && typeof e.l.v === 'string' && e.r.k === 'id' && e.r.name === 'held')
+                    out.add(e.l.v);
+                visit(e.l);
+                visit(e.r);
+                break;
+            case 'and':
+            case 'or':
+                visit(e.l);
+                visit(e.r);
+                break;
+            case 'not':
+                visit(e.e);
+                break;
+            case 'id': {
+                const guard = g.guards[e.name];
+                if (guard !== undefined && depth < 8)
+                    for (const c of guardCodes(g, guard, depth + 1))
+                        out.add(c);
+                break;
+            }
+            case 'list':
+                e.items.forEach(visit);
+                break;
+            case 'lit':
+                break;
+        }
+    };
+    visit(parseExpr(src));
+    return out;
+}