@turri-dev/cli 0.1.27 → 0.1.28-next.d5f2680

package/dist/regenerate/advisor-runs.js

@@ -0,0 +1,327 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { advisorModel, configForSpec, readProjectConfig, stackOf, testDirOf } from "../config.js";
+import { plainFileParser } from "../plain/parser.js";
+import { ACCEPTANCE_TESTS, CONFORMANCE_TESTS, FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS } from "../plain/spec.js";
+import { tipsAbove } from "../plain/check.js";
+import { conformanceTestsOnIn } from "../conformance-switch.js";
+import { isStdlibModule } from "../plain/stdlib.js";
+import { outsideJobs, withStopSignal } from "./activity.js";
+import { advisorEntry, isCurrent, markDelivered, pendingEntries, putAdvisorEntry, removeAdvisorEntry, textHash, undeliveredEntries, } from "./advisor-records.js";
+import { firstLine, record } from "./ledger.js";
+import { projectDirOf, resolveTemplateDirs } from "./paths.js";
+import { advise as adviseByModel } from "./test-advisor.js";
+/**
+ * When the test advisor runs, and on what (docs/test-advisor.md). It watches what the work loop looks at - every
+ * ***plain change the loop sees, as it sees it - and takes each functional spec that is new or whose text changed since
+ * its code was built (its code record), has no scenarios, and has no entry in the advisor's file for that text. A
+ * project already built, with no advisor file, is looked at not at all: only what changes from now on is.
+ *
+ * Each is marked `pending` in the advisor's file then and there, and judged in the background - two at a time at most,
+ * outside `parallel-jobs` and the lanes: no pulse waits for it, and it never steers or stops one. Its work is clear of
+ * any pulse: no panel, no log, no stop of a pulse's reaches it. A functional spec whose text changes while it is judged
+ * has that work thrown away - whoever changed it - and the new text starts again. What `pending` is left as turri quits,
+ * the next start in the chat or a host picks up.
+ *
+ * The advisor decides and writes nothing in the ***plain: what it made of a functional spec is kept in its file and
+ * handed on (`onVerdict`) to the chat the person looks at, which writes the scenarios on a yes. A yes not yet handed to a
+ * chat stays marked undelivered, and is handed on again at the next start.
+ *
+ * It is made only where the session starts in the chat or a host (extension.ts) - never for a headless command, nor
+ * pi's print, json and rpc modes - and does nothing in a project whose `test-advisor:` is false.
+ */
+/** How many functional specs the advisor works on at once. */
+export const ADVISOR_PARALLEL = 2;
+/** The functional spec's own place in a module, as its own .plain file has it now - or nothing. */
+function currentItem(plainFile, funcId) {
+    try {
+        const [, tree] = plainFileParser(basename(plainFile), resolveTemplateDirs(plainFile), { allowNoFunctionalities: true, testDir: testDirOf(plainFile) });
+        return (tree[FUNCTIONAL_REQUIREMENTS] ?? []).find((item) => item.id === funcId);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a functional spec has scenarios of any kind: then it is tested as the person wants, and today's review covers it. */
+export function hasScenarios(item) {
+    const of = (key) => (item?.[key] ?? []).length;
+    return of(CONFORMANCE_TESTS) + of(ACCEPTANCE_TESTS) > 0;
+}
+/** The project's AGENTS.md, whole: its own words on what matters. */
+function agentsText(project) {
+    const file = join(project, "AGENTS.md");
+    try {
+        return existsSync(file) ? [readFileSync(file, "utf8")] : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether a project wants the advisor: it conformance tests (`conformance-tests: true`), and its `test-advisor:` is not false. */
+function wanted(project) {
+    try {
+        return conformanceTestsOnIn(project) && readProjectConfig(project, stackOf(project)).testAdvisor !== false;
+    }
+    catch {
+        return true;
+    }
+}
+export function createTestAdvisor(options = {}) {
+    const enabled = options.enabled ?? wanted;
+    const advise = options.advise ?? adviseByModel;
+    const parallel = options.parallel ?? ADVISOR_PARALLEL;
+    const queue = [];
+    const running = new Map();
+    let idleWaiters = [];
+    let stopped = false;
+    const keyOf = (project, module, funcId) => `${project}\0${module}:${funcId}`;
+    const settleIdle = () => {
+        if (queue.length > 0 || running.size > 0)
+            return;
+        const waiters = idleWaiters;
+        idleWaiters = [];
+        for (const resolveIdle of waiters)
+            resolveIdle();
+    };
+    /** The work on a functional spec thrown away: its text is not what it was judging any more. */
+    const drop = (key, hash) => {
+        const at = queue.findIndex((work) => work.key === key && work.hash !== hash);
+        if (at !== -1)
+            queue.splice(at, 1);
+        const work = running.get(key);
+        if (work !== undefined && work.hash !== hash && work.dropped !== true) {
+            work.dropped = true;
+            work.controller.abort();
+        }
+    };
+    /** Take a functional spec, marked pending at once - unless the same text is taken already. Whether it was taken. */
+    const take = (given) => {
+        const key = keyOf(given.project, given.module, given.funcId);
+        drop(key, given.hash);
+        if (queue.some((work) => work.key === key) || running.get(key)?.hash === given.hash)
+            return false;
+        putAdvisorEntry(given.project, given.module, relative(given.project, given.plainFile), {
+            funcId: given.funcId,
+            hash: given.hash,
+            state: "pending",
+            tip: relative(given.project, given.tip),
+            ...(given.asked !== undefined ? { asked: given.asked } : {}),
+        });
+        queue.push({ ...given, key, controller: new AbortController() });
+        pump();
+        return true;
+    };
+    const pump = () => {
+        if (stopped)
+            return;
+        while (running.size < parallel) {
+            // A new text waits for the work on its old one to unwind; the rest go on past it.
+            const at = queue.findIndex((work) => !running.has(work.key));
+            if (at === -1)
+                break;
+            const work = queue.splice(at, 1)[0];
+            running.set(work.key, work);
+            // Clear of any pulse the loop was looking for, and stopped by its own signal alone.
+            void outsideJobs(() => withStopSignal(work.controller.signal, () => run(work))).finally(() => {
+                if (running.get(work.key) === work)
+                    running.delete(work.key);
+                pump();
+                settleIdle();
+            });
+        }
+        settleIdle();
+    };
+    const spec = (work) => `${work.module}:${work.funcId}`;
+    const place = (work) => ({ project: work.project, module: work.module });
+    /** A verdict handed on to the chat: a yes kept undelivered in the advisor's file until a chat has it. */
+    const handOn = (given) => {
+        if (options.onVerdict === undefined)
+            return;
+        const { project, module, funcId, plainFile, hash } = given;
+        try {
+            options.onVerdict({
+                ...given,
+                testFile: relative(project, join(testDirOf(plainFile), module, `${funcId}.plain`)),
+                current: () => {
+                    const item = currentItem(plainFile, funcId);
+                    return item !== undefined && textHash(item.markdown) === hash && !hasScenarios(item) && advisorEntry(project, module, funcId)?.hash === hash;
+                },
+                delivered: () => markDelivered(project, module, funcId, hash),
+            });
+        }
+        catch {
+            /* a chat that throws as it is told: the yes stays undelivered, for the next start */
+        }
+    };
+    const run = async (work) => {
+        const config = (() => {
+            try {
+                return configForSpec(work.plainFile);
+            }
+            catch {
+                return {};
+            }
+        })();
+        const model = advisorModel(config);
+        const entryOf = (state, more = {}) => {
+            putAdvisorEntry(work.project, work.module, relative(work.project, work.plainFile), {
+                funcId: work.funcId,
+                hash: work.hash,
+                state,
+                tip: relative(work.project, work.tip),
+                ...(model !== undefined ? { model } : {}),
+                ...more,
+            });
+        };
+        try {
+            // The setting turns off only what a change starts: the chat's asking stands.
+            if (work.asked === undefined && !enabled(work.project))
+                return;
+            const subject = {
+                module: work.module,
+                funcId: work.funcId,
+                text: work.text,
+                moduleText: readFileSync(work.plainFile, "utf8"),
+                ...(resolve(work.tip) !== resolve(work.plainFile) && existsSync(work.tip) ? { testedIn: { module: basename(work.tip).replace(/\.plain$/, ""), text: readFileSync(work.tip, "utf8") } } : {}),
+                context: [...agentsText(work.project), ...(options.context?.(work.plainFile) ?? [])],
+                ...(work.asked?.reason !== undefined ? { reason: work.asked.reason } : {}),
+            };
+            const report = await advise(subject, { cwd: work.project, ...(model !== undefined ? { model } : {}) });
+            if (work.controller.signal.aborted)
+                throw new Error("stopped");
+            record({ kind: "advisor.classified", spec: spec(work), verdict: report.verdict, questions: report.questions.map((answered) => answered.question), asked: work.asked !== undefined }, place(work));
+            // A yes is kept undelivered until a chat has it; a no is only a line, and nothing is lost when it is not drawn.
+            entryOf(report.verdict, { report, ...(report.verdict === "yes" && options.onVerdict !== undefined ? { undelivered: true } : {}) });
+            handOn({ project: work.project, module: work.module, funcId: work.funcId, plainFile: work.plainFile, tip: work.tip, hash: work.hash, report });
+        }
+        catch (error) {
+            if (work.dropped === true) {
+                record({ kind: "advisor.dropped", spec: spec(work) }, place(work));
+                return;
+            }
+            // Stopped with the session: left pending, for the next start.
+            if (stopped || work.controller.signal.aborted)
+                return;
+            const reason = firstLine(error instanceof Error ? error.message : String(error), 300);
+            entryOf("failed", { reason });
+            record({ kind: "advisor.failed", spec: spec(work), reason }, place(work));
+        }
+    };
+    const advisor = {
+        seen(look) {
+            if (stopped)
+                return;
+            const tip = look.chain.at(-1);
+            if (tip === undefined)
+                return;
+            const project = projectDirOf(tip.plainFile);
+            if (!enabled(project))
+                return;
+            const built = new Map();
+            const builtItems = (section) => (look.built[section] ?? []);
+            for (const item of builtItems(FUNCTIONAL_REQUIREMENTS))
+                built.set(`${tip.moduleName}:${item.id}`, (item.markdown ?? "").trim());
+            for (const item of builtItems(REQUIRED_FUNCTIONAL_SPECS))
+                built.set(`${item.module}:${item.id}`, (item.markdown ?? "").trim());
+            const items = (section, own) => (look.tree[section] ?? []).map((item) => ({ item, module: own ? tip.moduleName : (item.module ?? "") }));
+            for (const { item, module } of [...items(REQUIRED_FUNCTIONAL_SPECS, false), ...items(FUNCTIONAL_REQUIREMENTS, true)]) {
+                if (module === "" || isStdlibModule(module))
+                    continue;
+                const entry = look.chain.find((link) => link.moduleName === module);
+                if (entry === undefined)
+                    continue;
+                const text = item.markdown.trim();
+                const hash = textHash(text);
+                const key = keyOf(project, module, item.id);
+                // Work on a text that is no more is thrown away, wherever the change came from.
+                drop(key, hash);
+                // Built as it is now: neither new nor changed.
+                if (built.get(`${module}:${item.id}`) === text)
+                    continue;
+                // Scenarios of any kind: tested as the person wants, and today's review covers it.
+                if (hasScenarios(item))
+                    continue;
+                // Judged already, for this text - or being judged now.
+                const known = advisorEntry(project, module, item.id);
+                if (isCurrent(known, hash) && (known.state !== "pending" || running.has(key) || queue.some((work) => work.key === key)))
+                    continue;
+                take({ project, module, funcId: item.id, plainFile: resolve(entry.plainFile), tip: resolve(tip.plainFile), text, hash });
+            }
+        },
+        resume(project) {
+            if (stopped)
+                return;
+            // Conformance tests off: the advisor is off with them - nothing pending is picked up, not even what the chat asked for.
+            if (options.enabled === undefined && !conformanceTestsOnIn(project))
+                return;
+            // With the setting off, only what the chat asked for is picked up.
+            const wants = enabled(project);
+            for (const pending of pendingEntries(project)) {
+                if (!wants && pending.entry.asked === undefined)
+                    continue;
+                const plainFile = resolve(project, pending.plainFile);
+                const item = currentItem(plainFile, pending.entry.funcId);
+                // Gone, or given scenarios meanwhile: nothing is left to pick up.
+                if (item === undefined || hasScenarios(item)) {
+                    removeAdvisorEntry(project, pending.module, pending.entry.funcId);
+                    continue;
+                }
+                const text = item.markdown.trim();
+                take({
+                    project,
+                    module: pending.module,
+                    funcId: item.id,
+                    plainFile,
+                    tip: resolve(project, pending.entry.tip ?? pending.plainFile),
+                    text,
+                    hash: textHash(text),
+                    ...(pending.entry.asked !== undefined ? { asked: pending.entry.asked } : {}),
+                });
+            }
+            // A yes no chat had when turri quit: handed on now, while it is still about the functional spec as it is.
+            for (const kept of undeliveredEntries(project)) {
+                const { entry } = kept;
+                const plainFile = resolve(project, kept.plainFile);
+                const item = currentItem(plainFile, entry.funcId);
+                if (entry.report === undefined || item === undefined || textHash(item.markdown) !== entry.hash || hasScenarios(item)) {
+                    markDelivered(project, kept.module, entry.funcId, entry.hash);
+                    continue;
+                }
+                handOn({ project, module: kept.module, funcId: entry.funcId, plainFile, tip: resolve(project, entry.tip ?? kept.plainFile), hash: entry.hash, report: entry.report });
+            }
+        },
+        idle() {
+            if (queue.length === 0 && running.size === 0)
+                return Promise.resolve();
+            return new Promise((resolveIdle) => idleWaiters.push(resolveIdle));
+        },
+        taking(project) {
+            const mine = (work) => project === undefined || resolve(work.project) === resolve(project);
+            return [...new Set([...running.values(), ...queue].filter(mine).map((work) => `${work.module}:${work.funcId}`))];
+        },
+        evaluate(asked) {
+            const plainFile = resolve(asked.plainFile);
+            const project = projectDirOf(plainFile);
+            const item = currentItem(plainFile, asked.funcId);
+            if (item === undefined)
+                return "missing";
+            if (hasScenarios(item))
+                return "scenarios";
+            const text = item.markdown.trim();
+            const hash = textHash(text);
+            const known = advisorEntry(project, asked.module, asked.funcId);
+            // The tip its scenarios are tested in: given, else known, else the module at the top of a chain it is in - itself when none is.
+            const tip = asked.tip ?? (known?.tip !== undefined ? resolve(project, known.tip) : (tipsAbove(asked.module, project)[0]?.file ?? plainFile));
+            const reason = asked.reason?.trim();
+            const taken = take({ project, module: asked.module, funcId: asked.funcId, plainFile, tip: resolve(tip), text, hash, asked: reason !== undefined && reason !== "" ? { reason } : {} });
+            return taken ? "started" : "already";
+        },
+        stop() {
+            stopped = true;
+            queue.length = 0;
+            for (const work of running.values())
+                work.controller.abort();
+        },
+    };
+    return advisor;
+}

package/dist/regenerate/base-folder.d.ts

@@ -0,0 +1,68 @@
+import { BASE_RECORD_FILE } from "./paths.ts";
+export { BASE_RECORD_FILE };
+/**
+ * A base folder (`base-folder:` in config.turri.yaml, a stack's own in its file): what a codebase that requires no other
+ * module starts from instead of nothing - an existing codebase to build on, files to use (images, animations, fonts), or
+ * both. It is copied in once, before the codebase's first pulse, and never written to; what was copied is recorded beside
+ * the code record, and goes up the chain with the code, so every coding agent of the chain is told where its codebase
+ * started (prompt.ts). It is not kept in step: a change to it is said (`baseFolderDrift`), and a codebase regenerated from
+ * scratch starts from it again. The ***plain is untouched by it: it may refer to the folder in prose, and link into it.
+ */
+export interface BaseRecord {
+    /** The folder as `base-folder:` named it. */
+    folder: string;
+    /** The content of what was copied: its files' paths and bytes. */
+    hash: string;
+    /** The files copied, by path in the codebase. */
+    files: string[];
+}
+/** Raised before a pulse starts when the base folder its codebase is to start from is not there. */
+export declare class MissingBaseFolderError extends Error {
+    readonly moduleName: string;
+    constructor(moduleName: string, named: string, path: string);
+}
+/** The base folder a module's codebase starts from - its stack's over the project's - as named and as a path; none when the config names none. */
+export declare function baseFolderOf(plainFile: string): {
+    named: string;
+    path: string;
+} | undefined;
+/**
+ * The files of a base folder, by path in it, sorted: in a git work tree what git sees - tracked, and untracked that it
+ * does not ignore - so no dependencies or build output; otherwise every file but those of the folders never copied.
+ */
+export declare function baseFiles(folder: string): string[];
+/** What a base folder holds now, as one hash: each file's path and bytes. */
+export declare function hashBase(folder: string, files?: string[]): string;
+/** What a codebase started from, when it started from a base folder. */
+export declare function readBaseRecord(buildDir: string): BaseRecord | undefined;
+/** Carry what a codebase started from up to one built on it, with its code (requires.ts copyRequiredCode). */
+export declare function carryBaseRecord(from: string, to: string): void;
+/**
+ * Start an empty codebase that requires no other module from its base folder, when the config names one: the folder's
+ * files copied in, what was copied recorded, and committed. Nothing when the config names none. A base folder that is not
+ * there stops the pulse before it starts.
+ */
+export declare function seedFromBaseFolder(buildDir: string, plainFile: string, moduleName: string): BaseRecord | undefined;
+/**
+ * How a codebase's base folder stands against what it started from: undefined when they agree, or it started from none
+ * and the config names none; otherwise a line saying what moved - the folder named now another, its files changed, or
+ * it gone - and that regenerating from scratch starts again from it.
+ */
+export declare function baseFolderDrift(buildDir: string, plainFile: string): string | undefined;
+/**
+ * What a codebase started from, as its coding agents are told: the base folder as named, and the files that came from
+ * it that are in the codebase still - a module built on another is told those of its own. None when it started from
+ * no base folder.
+ */
+export declare function baseOfCodebase(buildDir: string): {
+    folder: string;
+    files: string[];
+} | undefined;
+/**
+ * Where a file the ***plain links is in the codebase, when it is one the base folder held and the codebase has still:
+ * its path there - the agent uses it from there, and never copies it. The base folder is the one the codebase started
+ * from, by its record, from the project's folder.
+ */
+export declare function inCodebaseOf(file: string, buildDir: string, plainFile: string): string | undefined;
+/** A base folder named for a module and not there: what `parse` and `doctor` say of it. None when it is there, or none is named. */
+export declare function missingBaseFolder(plainFile: string): string | undefined;

package/dist/regenerate/base-folder.js

@@ -0,0 +1,168 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { CONFIG_KEYS, configForSpec } from "../config.js";
+import { recordHistory } from "./lineage.js";
+import { BASE_RECORD_FILE, projectDirOf } from "./paths.js";
+export { BASE_RECORD_FILE };
+/** Raised before a pulse starts when the base folder its codebase is to start from is not there. */
+export class MissingBaseFolderError extends Error {
+    moduleName;
+    constructor(moduleName, named, path) {
+        super([
+            `Stopped before building ${moduleName}: its codebase is to start from the base folder ${named} (${CONFIG_KEYS.baseFolder}: in config.turri.yaml), ` +
+                `and ${existsSync(path) ? "that is not a folder" : "there is no such folder"} - ${path}.`,
+            "",
+            `Make the folder, or name the right one in ${CONFIG_KEYS.baseFolder}:, by path from the project's folder - or take the key out to start from nothing. Then build again.`,
+        ].join("\n"));
+        this.name = "MissingBaseFolderError";
+        this.moduleName = moduleName;
+    }
+}
+/** The base folder a module's codebase starts from - its stack's over the project's - as named and as a path; none when the config names none. */
+export function baseFolderOf(plainFile) {
+    const named = configForSpec(plainFile).baseFolder;
+    if (named === undefined)
+        return undefined;
+    return { named, path: resolve(projectDirOf(resolve(plainFile)), named) };
+}
+/** Folders never copied from a base folder that git does not keep: its history, installed dependencies, caches. */
+const NOT_COPIED = new Set([".git", "node_modules", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".turri", "plain_modules"]);
+/**
+ * The files of a base folder, by path in it, sorted: in a git work tree what git sees - tracked, and untracked that it
+ * does not ignore - so no dependencies or build output; otherwise every file but those of the folders never copied.
+ */
+export function baseFiles(folder) {
+    const inGit = spawnSync("git", ["-C", folder, "rev-parse", "--is-inside-work-tree"], { encoding: "utf8" });
+    if (inGit.status === 0 && inGit.stdout.trim() === "true") {
+        const listed = spawnSync("git", ["-C", folder, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "."], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+        if (listed.status === 0) {
+            // A tracked file deleted in the work tree is listed, and not there to copy.
+            return [...new Set(listed.stdout.split("\0").filter((path) => path !== ""))].filter((path) => isFile(join(folder, path))).sort();
+        }
+    }
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            if (NOT_COPIED.has(entry))
+                continue;
+            const full = join(dir, entry);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else
+                found.push(relative(folder, full).split(sep).join("/"));
+        }
+    };
+    walk(folder);
+    return found.sort();
+}
+const isFile = (path) => {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** What a base folder holds now, as one hash: each file's path and bytes. */
+export function hashBase(folder, files = baseFiles(folder)) {
+    const hash = createHash("sha256");
+    for (const file of files) {
+        hash.update(file).update("\0");
+        hash.update(readFileSync(join(folder, file))).update("\0");
+    }
+    return hash.digest("hex");
+}
+/** What a codebase started from, when it started from a base folder. */
+export function readBaseRecord(buildDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(buildDir, BASE_RECORD_FILE), "utf8"));
+        return typeof parsed.folder === "string" && typeof parsed.hash === "string" && Array.isArray(parsed.files) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Carry what a codebase started from up to one built on it, with its code (requires.ts copyRequiredCode). */
+export function carryBaseRecord(from, to) {
+    if (existsSync(join(from, BASE_RECORD_FILE)) && !existsSync(join(to, BASE_RECORD_FILE)))
+        copyFileSync(join(from, BASE_RECORD_FILE), join(to, BASE_RECORD_FILE));
+}
+/**
+ * Start an empty codebase that requires no other module from its base folder, when the config names one: the folder's
+ * files copied in, what was copied recorded, and committed. Nothing when the config names none. A base folder that is not
+ * there stops the pulse before it starts.
+ */
+export function seedFromBaseFolder(buildDir, plainFile, moduleName) {
+    const base = baseFolderOf(plainFile);
+    if (base === undefined)
+        return undefined;
+    if (!existsSync(base.path) || !statSync(base.path).isDirectory())
+        throw new MissingBaseFolderError(moduleName, base.named, base.path);
+    const files = baseFiles(base.path);
+    mkdirSync(buildDir, { recursive: true });
+    for (const file of files) {
+        const target = join(buildDir, file);
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(join(base.path, file), target);
+    }
+    const record = { folder: base.named, hash: hashBase(base.path, files), files };
+    writeFileSync(join(buildDir, BASE_RECORD_FILE), `${JSON.stringify(record, null, 2)}\n`);
+    recordHistory(buildDir, `start from the base folder ${base.named}`, `${files.length} file${files.length === 1 ? "" : "s"} copied in`);
+    return record;
+}
+/**
+ * How a codebase's base folder stands against what it started from: undefined when they agree, or it started from none
+ * and the config names none; otherwise a line saying what moved - the folder named now another, its files changed, or
+ * it gone - and that regenerating from scratch starts again from it.
+ */
+export function baseFolderDrift(buildDir, plainFile) {
+    const record = readBaseRecord(buildDir);
+    const base = baseFolderOf(plainFile);
+    const again = "regenerate it from scratch to start again from it";
+    if (record === undefined) {
+        if (base === undefined)
+            return undefined;
+        if (existsSync(buildDir) && readdirSync(buildDir).length > 0)
+            return `its base folder is ${base.named}, but its codebase did not start from one - ${again}`;
+        return existsSync(base.path) && statSync(base.path).isDirectory() ? undefined : `its base folder ${base.named} is not there - its first pulse stops until it is`;
+    }
+    if (base === undefined)
+        return `its codebase started from the base folder ${record.folder}, which ${CONFIG_KEYS.baseFolder}: no longer names - it is built on what was copied`;
+    if (base.named !== record.folder)
+        return `its base folder is now ${base.named}, but its codebase started from ${record.folder} - ${again}`;
+    if (!existsSync(base.path) || !statSync(base.path).isDirectory())
+        return `its base folder ${base.named} is gone - its codebase is built on what was copied from it`;
+    return hashBase(base.path) !== record.hash ? `its base folder ${base.named} changed since its codebase started from it - ${again}` : undefined;
+}
+/**
+ * What a codebase started from, as its coding agents are told: the base folder as named, and the files that came from
+ * it that are in the codebase still - a module built on another is told those of its own. None when it started from
+ * no base folder.
+ */
+export function baseOfCodebase(buildDir) {
+    const record = readBaseRecord(buildDir);
+    if (record === undefined)
+        return undefined;
+    return { folder: record.folder, files: record.files.filter((file) => isFile(join(buildDir, file))) };
+}
+/**
+ * Where a file the ***plain links is in the codebase, when it is one the base folder held and the codebase has still:
+ * its path there - the agent uses it from there, and never copies it. The base folder is the one the codebase started
+ * from, by its record, from the project's folder.
+ */
+export function inCodebaseOf(file, buildDir, plainFile) {
+    const base = baseOfCodebase(buildDir);
+    if (base === undefined)
+        return undefined;
+    const at = relative(resolve(projectDirOf(resolve(plainFile)), base.folder), resolve(file)).split(sep).join("/");
+    return !at.startsWith("../") && at !== ".." && base.files.includes(at) ? at : undefined;
+}
+/** A base folder named for a module and not there: what `parse` and `doctor` say of it. None when it is there, or none is named. */
+export function missingBaseFolder(plainFile) {
+    const base = baseFolderOf(plainFile);
+    if (base === undefined || (existsSync(base.path) && statSync(base.path).isDirectory()))
+        return undefined;
+    return `its base folder ${base.named} (${CONFIG_KEYS.baseFolder}:) is ${existsSync(base.path) ? "not a folder" : "not there"} - its codebase's first pulse stops until it is`;
+}

package/dist/regenerate/cases.d.ts

@@ -1,9 +1,12 @@
 import type { JobCases } from "./drift.ts";
-/** What the coding agent does, case by case. */
-export declare function codeCasesBlock(cases: JobCases): string[];
+/**
+ * What the coding agent does, case by case. `fromBase`: the codebase started from a base folder - nothing is built from
+ * the specification, but the folder is not empty, and a project in it is built on, never set up anew.
+ */
+export declare function codeCasesBlock(cases: JobCases, fromBase?: boolean): string[];
 /** What the unit reviewer holds the work to, case by case - in place of its checks, when the job is mechanical. */
 export declare function codeReviewCasesBlock(cases: JobCases): string[];
-/** What the conformance agent does, case by case. */
-export declare function conformanceCasesBlock(cases: JobCases): string[];
-/** What the conformance test reviewer holds the tests to, when the job is mechanical: in place of its checks. */
-export declare function conformanceReviewCasesBlock(cases: JobCases): string[];
+/** What the conformance agent does, case by case - scenario by scenario, when the job has them. */
+export declare function conformanceCasesBlock(cases: JobCases, module?: string): string[];
+/** What the conformance test reviewer holds the tests to: scenario by scenario - or, when the job is mechanical, in place of its checks. */
+export declare function conformanceReviewCasesBlock(cases: JobCases, module?: string): string[];