@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/dist/regenerate/spec-map.js

@@ -0,0 +1,561 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { withParseCache } from "../plain/parser.js";
+import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS, } from "../plain/spec.js";
+import { configForSpec, conformanceSwitchedOn, readProjectConfig } from "../config.js";
+import { STDLIB_ROOT } from "../plain/stdlib.js";
+import { conformanceDirFor } from "./conformance.js";
+import { chainSpec } from "./loop.js";
+import { modulesRoot, projectDirOf } from "./paths.js";
+import { HISTORY_DIR } from "./lineage.js";
+import { codeTree, readRecord, RECORD_FILE } from "./records.js";
+import { specFilesOf } from "./regenerate.js";
+import { builtTips, resolveRequiresChain } from "./requires.js";
+import { changesBetween, layoutOf, serializeTree } from "./spec-steps.js";
+const itemsOf = (tree, heading) => (tree?.[heading] ?? []).slice();
+/** The sections an item of the code is in, as a page has them: a module below's functional specs among them. */
+const CODE_SECTIONS = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS];
+/** A module's part of a codebase's tree: its own items untagged when it is the codebase, else those tagged with it. */
+function moduleTree(tree, module, own) {
+    const mine = (item) => (own ? item.module === undefined : item.module === module);
+    return {
+        [DEFINITIONS]: itemsOf(tree, DEFINITIONS).filter(mine),
+        [NON_FUNCTIONAL_REQUIREMENTS]: itemsOf(tree, NON_FUNCTIONAL_REQUIREMENTS).filter(mine),
+        [FUNCTIONAL_REQUIREMENTS]: own ? itemsOf(tree, FUNCTIONAL_REQUIREMENTS) : itemsOf(tree, REQUIRED_FUNCTIONAL_SPECS).filter((item) => item.module === module),
+    };
+}
+/** The changes between two serialized trees - git runs for each, so the last ones are kept. */
+const changesSeen = new Map();
+function changesOf(before, after) {
+    const key = `${before}\u0000${after}`;
+    const seen = changesSeen.get(key);
+    if (seen !== undefined)
+        return seen;
+    const changes = changesBetween(before, after);
+    if (changesSeen.size > 64)
+        changesSeen.clear();
+    changesSeen.set(key, changes);
+    return changes;
+}
+const markdownOf = (line) => {
+    try {
+        return JSON.parse(line ?? "").markdown ?? "";
+    }
+    catch {
+        return "";
+    }
+};
+/**
+ * A module's items, from what its code is built from and what its spec says now: every item of the spec in its place,
+ * each built, new or changed, and between them the items taken out that the code still has.
+ *
+ * `spec` and `record` are the codebase's trees - the module's items untagged when `own`, tagged with it otherwise. `full`
+ * is the spec with its acceptance tests and test reqs.
+ */
+export function pageItems(input) {
+    const now = moduleTree(input.spec, input.module, input.own);
+    const before = serializeTree(moduleTree(input.record === null ? null : codeTree(input.record), input.module, input.own));
+    const after = serializeTree(codeTree(now));
+    const changes = changesOf(before, after);
+    // Each item's acceptance tests, by its line in the code's tree.
+    const acceptance = new Map();
+    for (const item of itemsOf(now, FUNCTIONAL_REQUIREMENTS)) {
+        const line = serializeTree(codeTree({ [FUNCTIONAL_REQUIREMENTS]: [item] })).split("\n").find((entry) => entry.startsWith("{"));
+        if (line !== undefined)
+            acceptance.set(line, (item[ACCEPTANCE_TESTS] ?? []).map((test) => test.markdown ?? ""));
+    }
+    // The record's lines, with what is added in front of each and what becomes of each: the spec's order, the ghosts in theirs.
+    const lines = before.split("\n").slice(0, -1);
+    const removedBy = new Map();
+    const addedAt = new Map();
+    for (const change of changes) {
+        if (change.removes !== undefined)
+            removedBy.set(change.removes, change);
+        if (change.kind === "add" && change.inserts !== undefined)
+            addedAt.set(change.inserts.at, [...(addedAt.get(change.inserts.at) ?? []), change]);
+    }
+    const items = [];
+    const push = (section, state, line, wasLine) => {
+        const text = markdownOf(line ?? wasLine);
+        items.push({
+            key: "",
+            section,
+            state,
+            text,
+            ...(state === "changed" ? { was: markdownOf(wasLine) } : {}),
+            acceptance: line !== undefined ? (acceptance.get(line) ?? []) : [],
+            ...(line !== undefined ? { line } : {}),
+            ...(wasLine !== undefined ? { wasLine } : {}),
+        });
+    };
+    let section = "";
+    for (let at = 0; at <= lines.length; at += 1) {
+        for (const change of (addedAt.get(at) ?? []).sort((a, b) => a.inserts.order - b.inserts.order))
+            push(change.section, "new", change.after, undefined);
+        if (at === lines.length)
+            break;
+        const line = lines[at];
+        if (line.startsWith("[")) {
+            section = JSON.parse(line)[0];
+            continue;
+        }
+        const change = removedBy.get(at);
+        if (change?.kind === "change")
+            push(section, "changed", change.after, line);
+        else if (change?.kind === "remove")
+            push(section, "removed", undefined, line);
+        else
+            push(section, "built", line, undefined);
+    }
+    // Test reqs are the conformance tests', never the code's: written for, as the tests record has them, or not yet.
+    const testReqs = new Set(itemsOf(input.tested ?? null, TEST_REQUIREMENTS).map((item) => item.markdown.trim()));
+    if (input.own) {
+        for (const item of itemsOf(input.spec, TEST_REQUIREMENTS)) {
+            items.push({ key: "", section: TEST_REQUIREMENTS, state: "test", text: item.markdown, acceptance: [], ...(testReqs.has(item.markdown.trim()) ? { tests: "now" } : {}) });
+        }
+    }
+    // Conformance tests: of the functional specs, those the tests record has as they read now, as they read before, or taken out.
+    const tested = new Set(itemsOf(input.tested ?? null, FUNCTIONAL_REQUIREMENTS).map((item) => item.markdown.trim()));
+    for (const item of items) {
+        if (item.section !== FUNCTIONAL_REQUIREMENTS || tested.size === 0)
+            continue;
+        if (item.state === "removed") {
+            if (tested.has(item.text.trim()))
+                item.tests = "removed";
+        }
+        else if (tested.has(item.text.trim()))
+            item.tests = "now";
+        else if (item.was !== undefined && tested.has(item.was.trim()))
+            item.tests = "older";
+    }
+    return keyed(items);
+}
+/** Each item's key: its section, whether it is a ghost, its text - and which of the same it is. */
+function keyed(items) {
+    const seen = new Map();
+    for (const item of items) {
+        const base = `${item.section}\n${item.state === "removed" ? "-" : "+"}${item.text.trim()}`;
+        const count = seen.get(base) ?? 0;
+        seen.set(base, count + 1);
+        item.key = count === 0 ? base : `${base}\n${count}`;
+    }
+    return items;
+}
+/** A spec file as the map names it: a template of turri's standard library by its import path, others from the project. */
+export function importLabel(path, projectDir, stdlibRoot = STDLIB_ROOT) {
+    const name = path.startsWith(`${stdlibRoot}/stdlib/`) ? relative(stdlibRoot, path) : relative(projectDir, path) || basename(path);
+    return name.replace(/\.plain$/, "");
+}
+/**
+ * The items laid out as the files have them: the module's own file first - its sections in its order, its definitions
+ * in its order - then each file it imports, the same way. A ghost keeps its place after the item before it.
+ */
+export function layOut(items, files) {
+    const firstLine = (text) => text.trim().split("\n")[0].trim();
+    // Each item's file: the first that has its first line - else the module's own, where a ghost was.
+    const fileOf = (item) => {
+        const line = firstLine(item.text);
+        const at = files.findIndex((file) => file.text.includes(line));
+        return at === -1 ? 0 : at;
+    };
+    const layouts = files.map((file) => layoutOf(file.text));
+    const placed = items.map((item, index) => ({ item, index, file: item.state === "removed" ? -1 : fileOf(item) }));
+    // A ghost goes in the file of the item before it.
+    placed.forEach((entry, at) => {
+        if (entry.file === -1)
+            entry.file = at > 0 ? placed[at - 1].file : 0;
+    });
+    // Within a file, sections in its order; definitions by their concept's place, a ghost just after the one before it.
+    let lastRank = -1;
+    const rank = placed.map((entry) => {
+        if (entry.item.section !== DEFINITIONS)
+            return 0;
+        const concept = /^- :([^:\s]+):/.exec(entry.item.text.trim())?.[1];
+        const found = concept !== undefined && entry.item.state !== "removed" ? layouts[entry.file].concepts.get(concept) : undefined;
+        lastRank = found ?? lastRank + 0.001;
+        return lastRank;
+    });
+    const sectionPlace = (entry) => {
+        const order = layouts[entry.file].sections;
+        const at = order.indexOf(entry.item.section);
+        return at === -1 ? order.length + [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS].indexOf(entry.item.section) : at;
+    };
+    return placed
+        .sort((a, b) => a.file - b.file || sectionPlace(a) - sectionPlace(b) || rank[a.index] - rank[b.index] || a.index - b.index)
+        .map((entry) => (entry.file === 0 ? entry.item : { ...entry.item, file: files[entry.file].label ?? "" }));
+}
+/** Whether a module's codebase has been started: anything in it, or a record. */
+const started = (entry) => {
+    try {
+        if (readdirSync(entry.buildDir).length > 0)
+            return true;
+    }
+    catch {
+        /* no folder */
+    }
+    return readRecord(entry.buildDir) !== null;
+};
+/** The files a module's page is read from: its spec files, its records, and its history - a commit moves the record read. */
+function depsOf(entry, codebase, testsDir) {
+    const history = (dir) => [join(dirname(dir), HISTORY_DIR, "logs", "HEAD"), join(dir, RECORD_FILE)];
+    return [entry.plainFile, ...history(codebase.buildDir), ...history(testsDir), dirname(dirname(codebase.buildDir))];
+}
+/** The chain a file's map reads: where its code lives - its furthest-built tip - or its own requires chain. */
+function chainOf(plainFile) {
+    return builtTips(plainFile)[0] ?? resolveRequiresChain(plainFile, [], undefined, { allowNoFunctionalities: true });
+}
+/**
+ * The pages of the files given, from the files alone: one a module of each file's requires chain, bottom first, each
+ * once. A module below the furthest-built one is read from that one's codebase, whose record has every module's items;
+ * a module above it from its own, empty until its turn comes.
+ */
+export function readSpecMap(files) {
+    return readSpecMapWithDeps(files).pages;
+}
+/** The pages, and the files they were read from: while none of them changes, the pages read the same. */
+export function readSpecMapWithDeps(files) {
+    const deps = new Set(files);
+    const pages = withParseCache(() => {
+        const pages = [];
+        const seen = new Set();
+        for (const file of files) {
+            let chain;
+            try {
+                chain = chainOf(file);
+            }
+            catch (error) {
+                if (!seen.has(file))
+                    pages.push({ module: basename(file, ".plain"), plainFile: file, buildDir: "", imports: [], items: [], error: message(error) });
+                seen.add(file);
+                continue;
+            }
+            const furthest = chain.findLastIndex(started);
+            const specs = new Map();
+            const specOf = (at) => {
+                if (!specs.has(at)) {
+                    try {
+                        specs.set(at, chainSpec(chain.slice(0, at + 1)).tree);
+                    }
+                    catch (error) {
+                        specs.set(at, error instanceof Error ? error : new Error(String(error)));
+                    }
+                }
+                return specs.get(at);
+            };
+            chain.forEach((entry, at) => {
+                if (seen.has(entry.plainFile))
+                    return;
+                seen.add(entry.plainFile);
+                const home = Math.max(at, furthest);
+                const codebase = chain[home];
+                const page = {
+                    module: entry.moduleName,
+                    plainFile: entry.plainFile,
+                    buildDir: codebase.buildDir,
+                    imports: [],
+                    items: [],
+                    ...(entry.requires !== null ? { requires: entry.requires } : {}),
+                    conformance: conformanceOn(entry.plainFile),
+                };
+                const spec = specOf(home);
+                if (spec instanceof Error) {
+                    pages.push({ ...page, error: spec.message });
+                    return;
+                }
+                const projectDir = projectDirOf(entry.plainFile);
+                const record = home <= furthest ? readRecord(codebase.buildDir) : null;
+                const tested = readRecord(conformanceDirFor(entry.moduleName, modulesRoot(projectDir)));
+                const paths = specFilesOf(entry.plainFile);
+                for (const path of [...paths, ...depsOf(entry, codebase, conformanceDirFor(entry.moduleName, modulesRoot(projectDir)))])
+                    deps.add(path);
+                const texts = paths.map((path, index) => ({ ...(index > 0 ? { label: importLabel(path, projectDir) } : {}), text: readText(path) }));
+                const items = pageItems({ module: entry.moduleName, own: home === at, spec, record, tested });
+                pages.push({ ...page, imports: texts.slice(1).map((text) => text.label), items: layOut(items, texts) });
+            });
+        }
+        return pages;
+    });
+    return { pages, deps: [...deps] };
+}
+/** What the files read last are now: each one's time and size, or that it is not there. */
+function fingerprint(paths) {
+    return paths
+        .map((path) => {
+        try {
+            const stat = statSync(path);
+            return `${path}:${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return `${path}:-`;
+        }
+    })
+        .join("\n");
+}
+/** Whether a module's config has its conformance tests on: `conformance-tests:` is all (true) or chosen - off when not set. */
+function conformanceOn(plainFile) {
+    try {
+        return conformanceSwitchedOn(configForSpec(plainFile).conformanceTests);
+    }
+    catch {
+        return false;
+    }
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+const message = (error) => (error instanceof Error ? error.message : String(error));
+/** The lines of a serialized tree, as a set: what a pulse's trees are matched by. */
+const linesSeen = new WeakMap();
+function linesOf(pulse) {
+    let seen = linesSeen.get(pulse);
+    if (seen === undefined) {
+        const set = (text) => new Set(text.split("\n").filter((line) => line.startsWith("{")));
+        // A conformance pulse's trees are the tests record's: its functional specs' lines - each with its number and acceptance tests.
+        const specLines = (text, of = FUNCTIONAL_REQUIREMENTS) => {
+            const out = [];
+            let section = "";
+            for (const line of text.split("\n")) {
+                if (line.startsWith("["))
+                    section = JSON.parse(line)[0];
+                else if (line.startsWith("{") && section === of)
+                    out.push(line);
+            }
+            return out;
+        };
+        // The test reqs it writes tests to follow: those new in it.
+        const testReqs = () => {
+            const before = new Set(specLines(pulse.before, TEST_REQUIREMENTS));
+            return new Set(specLines(pulse.after, TEST_REQUIREMENTS).filter((line) => !before.has(line)).map((line) => markdownOf(line).trim()));
+        };
+        const testing = () => {
+            // What it writes tests for: each functional spec whose line is new - its text, its acceptance tests or its number
+            // changed - by its text; none, and it is the definitions, reqs or test reqs that changed: it tests every one again.
+            const before = new Set(specLines(pulse.before));
+            const after = specLines(pulse.after);
+            const changed = after.filter((line) => !before.has(line));
+            return new Set((changed.length > 0 ? changed : after).map((line) => markdownOf(line).trim()));
+        };
+        seen = pulse.track === "code" ? { before: set(pulse.before), after: set(pulse.after), testing: new Set(), testReqs: new Set() } : { before: new Set(), after: new Set(), testing: testing(), testReqs: testReqs() };
+        linesSeen.set(pulse, seen);
+    }
+    return seen;
+}
+/** A functional spec's first line, as a conformance pulse scheduled ahead of its code names it. */
+const headline = (text) => (text.trim().split("\n")[0] ?? "").replace(/^-\s*/, "").trim();
+/** Whether a conformance pulse writes tests for a functional spec: by its trees, or - scheduled, with none - by the specs it names. */
+function writesTestsFor(pulse, item) {
+    if (pulse.specs !== undefined)
+        return pulse.specs.some((text) => headline(text) === headline(item.text));
+    return linesOf(pulse).testing.has(item.text.trim());
+}
+/** Whether a pulse regenerates an item: brings its line now, or takes out its line in the record. */
+function regenerates(pulse, item) {
+    if (pulse.track !== "code")
+        return false;
+    const lines = linesOf(pulse);
+    if (item.state === "removed")
+        return item.wasLine !== undefined && lines.before.has(item.wasLine) && !lines.after.has(item.wasLine);
+    return item.line !== undefined && lines.after.has(item.line) && !lines.before.has(item.line);
+}
+/**
+ * What a module needs the person for, short, from the loop's reason for a halt: "pulse 3 didn't land - its unit tests
+ * never passed". What to do about it is the chat's to work out with them.
+ */
+function needsText(stuck) {
+    if (stuck.pulse !== undefined) {
+        const what = /was stopped/.test(stuck.why) ? "was stopped" : /did not start/.test(stuck.why) ? "didn't start" : /did not pass/.test(stuck.why) ? "didn't pass" : "didn't land";
+        return `pulse ${stuck.pulse.number} ${what}${stuck.cause !== undefined ? ` - ${stuck.cause}` : ""}`;
+    }
+    if (/planner found no way/.test(stuck.why))
+        return "the planner couldn't cut it into pulses";
+    return stuck.why.split(" - ")[0];
+}
+/**
+ * A test req's mark, from the conformance track: followed by the conformance tests as it reads now, being written
+ * for in the running conformance pulse, planned in one, or not yet - none, where no conformance test is written at all.
+ */
+function testReqMark(item, codebase, page) {
+    if (item.tests === "now")
+        return { mark: "built" };
+    const text = item.text.trim();
+    const pulse = codebase?.pulses.find((candidate) => candidate.track === "conformance" && linesOf(candidate).testReqs.has(text));
+    if (pulse !== undefined)
+        return { mark: pulse.running ? "regenerating" : "planned", pulse };
+    const anyTested = page.items.some((other) => other.tests !== undefined);
+    return { mark: anyTested ? "waiting" : "none" };
+}
+/** The count a page's top line starts with: how many of its functional specs are built as the spec has them. */
+export function countOf(page) {
+    const specs = page.items.filter((item) => item.section === FUNCTIONAL_REQUIREMENTS && item.state !== "removed");
+    return { built: specs.filter((item) => item.state === "built").length, total: specs.length };
+}
+/**
+ * The plan laid over the pages: each item that differs from the code marked with the pulse regenerating it, the pulse
+ * planned to, or - with none - planning, stuck or waiting; and each page's reason on its top line.
+ */
+export function markSpecMap(pages, plan) {
+    return pages.map((page) => {
+        const codebase = plan.codebases.find((entry) => entry.buildDir === page.buildDir);
+        if (page.error !== undefined)
+            return { ...page, items: [], tracked: codebase !== undefined, ...(codebase !== undefined ? { codebase } : {}), status: `its spec does not parse: ${page.error.split("\n")[0]}`, stuck: true };
+        const stuckPulse = codebase?.stuck?.pulse;
+        const failed = stuckPulse !== undefined ? { number: stuckPulse.number, title: "", track: "code", running: false, rowId: "", before: stuckPulse.before, after: stuckPulse.after } : undefined;
+        const conformance = codebase?.pulses.find((pulse) => pulse.running && pulse.track === "conformance");
+        // Test reqs only where conformance tests are on: the loop's word for it - the config, or asked for this session - else the config's.
+        const conformanceIsOn = codebase?.conformance ?? page.conformance !== false;
+        const items = page.items.filter((item) => item.state !== "test" || conformanceIsOn).map((item) => {
+            const testing = conformance !== undefined && item.section === FUNCTIONAL_REQUIREMENTS && item.state !== "removed" && (() => {
+                return linesOf(conformance).testing.has(item.text.trim());
+            })();
+            // Not being tested now: the conformance pulse planned to - its tests written for it as it reads now, or not.
+            const testsPulse = testing || item.section !== FUNCTIONAL_REQUIREMENTS || item.state === "removed"
+                ? undefined
+                : codebase?.pulses.find((pulse) => !pulse.running && pulse.track === "conformance" && writesTestsFor(pulse, item));
+            const extra = testing ? { testing: true } : testsPulse !== undefined ? { testsPulse } : {};
+            if (item.state === "test")
+                return { ...item, ...testReqMark(item, codebase, page), ...extra };
+            if (item.state === "built")
+                return { ...item, mark: "built", ...extra };
+            const pulse = codebase?.pulses.find((candidate) => regenerates(candidate, item));
+            if (pulse !== undefined)
+                return { ...item, mark: pulse.running ? "regenerating" : "planned", pulse, ...extra };
+            if (codebase?.planning === "code")
+                return { ...item, mark: "planning", ...extra };
+            if (codebase?.stuck !== undefined) {
+                // The planner found no plan: every item is stuck. A halt: the items of the pulse that did not land are; the rest wait.
+                if (failed === undefined)
+                    return { ...item, mark: "stuck", ...extra };
+                if (regenerates(failed, item))
+                    return { ...item, mark: "stuck", rolledBack: failed.number, ...extra };
+            }
+            return { ...item, mark: "waiting", ...extra };
+        });
+        const differing = items.filter((item) => item.state === "new" || item.state === "changed" || item.state === "removed").length;
+        const pulses = codebase?.pulses ?? [];
+        const running = pulses.find((pulse) => pulse.running);
+        const last = pulses.at(-1)?.number;
+        const status = codebase === undefined
+            ? differing > 0
+                ? "not asked to build - regenerate plans it"
+                : "all built"
+            : running !== undefined
+                ? // The count is of all the module's pulses: what the running one does follows it, not "conformance pulse 5 of 5".
+                    `pulse ${running.number} of ${last} regenerating${running.track === "conformance" ? " · conformance tests" : ""}`
+                : codebase.planning !== undefined
+                    ? "planning"
+                    : codebase.waitsFor !== undefined
+                        ? `waits for ${codebase.waitsFor}`
+                        : codebase.stuck !== undefined
+                            ? needsText(codebase.stuck)
+                            : pulses.length > 0
+                                ? `pulse ${pulses[0].number} of ${last} next`
+                                : differing === 0
+                                    ? "all built"
+                                    : (codebase.why ?? "waiting");
+        return { ...page, items, tracked: codebase !== undefined, ...(codebase !== undefined ? { codebase } : {}), status, stuck: codebase?.stuck !== undefined && running === undefined };
+    });
+}
+/**
+ * The .plain files the map shows when nothing has been asked for: the project's module from config.turri.yaml, else the
+ * .plain files in the folder that no other one there imports or requires.
+ */
+export function defaultMapFiles(cwd) {
+    // Asked for on every read of the map, every second while regen shows: worked out again only once the folder's .plain
+    // files or its config change - parsing each file's chains takes seconds in a project of many modules.
+    const key = `${resolve(cwd)}\n${folderPrint(cwd)}`;
+    if (keptDefaultFiles?.key === key)
+        return keptDefaultFiles.files;
+    const files = withParseCache(() => findDefaultMapFiles(cwd));
+    keptDefaultFiles = { key, files };
+    return files;
+}
+let keptDefaultFiles;
+/** The folder's .plain files and its config, by name, size and when each changed. */
+function folderPrint(cwd) {
+    try {
+        const names = readdirSync(cwd).filter((name) => name.endsWith(".plain") || /^config(\..+)?\.yaml$/.test(name)).sort();
+        return fingerprint(names.map((name) => join(cwd, name)));
+    }
+    catch {
+        return "";
+    }
+}
+function findDefaultMapFiles(cwd) {
+    try {
+        const module = readProjectConfig(cwd).module;
+        if (module !== undefined && existsSync(resolve(cwd, module)))
+            return [resolve(cwd, module)];
+    }
+    catch {
+        /* no config: the folder's files */
+    }
+    let files;
+    try {
+        files = readdirSync(cwd)
+            .filter((name) => name.endsWith(".plain"))
+            .sort()
+            .map((name) => join(cwd, name));
+    }
+    catch {
+        return [];
+    }
+    const below = new Set();
+    for (const file of files) {
+        try {
+            for (const path of specFilesOf(file).slice(1))
+                below.add(path);
+            for (const entry of resolveRequiresChain(file, [], undefined, { allowNoFunctionalities: true }).slice(0, -1))
+                below.add(resolve(entry.plainFile));
+        }
+        catch {
+            /* a file that does not parse is still shown */
+        }
+    }
+    return files.filter((file) => !below.has(resolve(file)));
+}
+/**
+ * The map as the side panel reads it on every frame: read again from the files and laid over the plan at most every
+ * `every` ms - git runs for the records and the diffs - and the same pages in between.
+ */
+export function createSpecMapSource(options) {
+    const every = options.every ?? 1000;
+    const now = options.now ?? Date.now;
+    let last;
+    // The pages from the files, and what the files were: read again only once one of them changes.
+    let read;
+    return {
+        read() {
+            if (last !== undefined && now() - last.at < every)
+                return last.pages;
+            let pages;
+            // Nothing here may throw: the panel draws from it on every frame, and a frame that throws draws nothing again.
+            try {
+                const plan = options.plan();
+                const files = options.files();
+                const key = files.join("\n");
+                if (read === undefined || read.files !== key || fingerprint(read.deps) !== read.print) {
+                    const fresh = readSpecMapWithDeps(files);
+                    read = { files: key, print: fingerprint(fresh.deps), deps: fresh.deps, pages: fresh.pages };
+                }
+                pages = markSpecMap(read.pages, plan);
+            }
+            catch (error) {
+                pages = last?.pages ?? [];
+                if (pages.length === 0)
+                    pages = [{ module: "spec", plainFile: "", buildDir: "", imports: [], items: [], tracked: false, status: `the map could not be read: ${message(error)}`, stuck: true }];
+            }
+            last = { at: now(), pages };
+            return pages;
+        },
+        /** Read the files again on the next frame, whatever they look like. */
+        refresh() {
+            last = undefined;
+            read = undefined;
+        },
+    };
+}