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

package/dist/regenerate/lineage.js

@@ -0,0 +1,384 @@
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { reportActivity } from "./activity.js";
+import { projectRootOf } from "./paths.js";
+/**
+ * Version history for each module's generated code and tests.
+ *
+ * A module folder - `plain_modules/<module>`, holding `code/` and `tests/` - is a git
+ * repository whose git directory is `.plaingit` rather than `.git`. Everything git does
+ * works as usual; the name is what keeps it from being an embedded repository inside the
+ * project's own, so the generated code stays plain files to the outer repo. Only the harness
+ * writes it: the agents' fences cover `code/` and `tests/`, and `.plaingit` sits beside them.
+ *
+ * A commit is made after every step that changes the module - a render, a regeneration, a
+ * conformance run, a regression repair, a spec change, a start from the module below - with
+ * a message saying what it was. History is a record of the work, never a gate on it: a git
+ * failure is swallowed, not raised.
+ */
+export const HISTORY_DIR = ".plaingit";
+const AUTHOR = ["-c", "user.name=turri", "-c", "user.email=turri@localhost", "-c", "commit.gpgsign=false"];
+/**
+ * Kept out of history: the history itself - git skips only a folder named `.git` on its own -
+ * installed dependencies, and caches.
+ */
+const EXCLUDED = [
+    `/${HISTORY_DIR}/`,
+    ".turri/",
+    "node_modules/",
+    ".venv/",
+    "venv/",
+    "__pycache__/",
+    "*.pyc",
+    ".pytest_cache/",
+    ".mypy_cache/",
+    ".ruff_cache/",
+    "target/",
+    ".cargo/",
+    ".DS_Store",
+];
+function git(moduleDir, args, input) {
+    return spawnSync("git", [...AUTHOR, "--git-dir", join(moduleDir, HISTORY_DIR), "--work-tree", moduleDir, ...args], {
+        cwd: moduleDir,
+        encoding: "utf8",
+        input,
+    });
+}
+/** The module folder a build or tests directory belongs to. */
+export function moduleDirOf(dir) {
+    return dirname(dir);
+}
+/** Keep the project's own repository from committing the history's objects. */
+function ignoreInProject(moduleDir) {
+    const root = projectRootOf(moduleDir);
+    if (!existsSync(join(root, ".git")))
+        return;
+    const ignore = join(root, ".gitignore");
+    const pattern = `plain_modules/**/${HISTORY_DIR}/`;
+    const current = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+    if (current.split("\n").some((line) => line.trim() === pattern))
+        return;
+    appendFileSync(ignore, `${current === "" || current.endsWith("\n") ? "" : "\n"}${pattern}\n`);
+}
+function ensureHistory(moduleDir) {
+    const gitDir = join(moduleDir, HISTORY_DIR);
+    if (existsSync(gitDir))
+        return true;
+    mkdirSync(moduleDir, { recursive: true });
+    if (git(moduleDir, ["init", "-q"]).status !== 0)
+        return false;
+    mkdirSync(join(gitDir, "info"), { recursive: true });
+    writeFileSync(join(gitDir, "info", "exclude"), `${EXCLUDED.join("\n")}\n`);
+    ignoreInProject(moduleDir);
+    return true;
+}
+/**
+ * Commit whatever the step changed in the module folder that `dir` - its build or its tests
+ * directory - belongs to. Nothing changed, nothing is committed. Returns the commit, if any.
+ */
+export function recordHistory(dir, subject, body) {
+    try {
+        const moduleDir = moduleDirOf(dir);
+        if (!existsSync(moduleDir) || !ensureHistory(moduleDir))
+            return undefined;
+        git(moduleDir, ["add", "-A"]);
+        if (git(moduleDir, ["diff", "--cached", "--quiet"]).status === 0)
+            return undefined;
+        const message = body ? `${subject}\n\n${body.trim()}\n` : subject;
+        if (git(moduleDir, ["commit", "-q", "-F", "-"], message).status !== 0)
+            return undefined;
+        return head(dir);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The notes the harness writes once a pulse has ended, committed - or the next pulse, putting the module back to its last
+ * commit, would take them away. Into the pulse's own commit when it landed one - `landedSince` (ms), when it started - so
+ * the history keeps a commit a pulse; a commit of their own otherwise - a pulse rolled back leaves its line, and nothing
+ * else.
+ */
+export function commitNotes(dir, file, subject, landedSince) {
+    try {
+        const moduleDir = moduleDirOf(dir);
+        if (!existsSync(moduleDir) || !ensureHistory(moduleDir))
+            return;
+        const path = [basename(dir), file].join("/");
+        git(moduleDir, ["add", "--", path]);
+        if (git(moduleDir, ["diff", "--cached", "--quiet"]).status === 0)
+            return;
+        const last = Number(git(moduleDir, ["log", "-1", "--format=%ct"]).stdout.trim()) * 1000;
+        const ownCommit = landedSince !== undefined && Number.isFinite(last) && last >= Math.floor(landedSince / 1000) * 1000;
+        git(moduleDir, ownCommit ? ["commit", "-q", "--amend", "--no-edit"] : ["commit", "-q", "-F", "-"], ownCommit ? undefined : subject);
+    }
+    catch {
+        // History is a record, not a gate.
+    }
+}
+/**
+ * Put a module back to its last commit before work starts on it.
+ *
+ * Every step commits what it did, so a module with changes nobody committed is one whose last
+ * step never finished - turri was stopped or restarted mid-job - and holds half-written
+ * code the next render would build on. Its last commit is the last known good state, so the
+ * working tree is reset to it: changed files restored, files nothing committed removed. What
+ * history does not track stays - installed dependencies, caches - so nothing needs installing
+ * again. A module with no commit yet has no good state to go back to and is left alone -
+ * `startWork` gives it one.
+ *
+ * Returns the paths that were put back or removed, relative to the module folder.
+ */
+/**
+ * The tests folder's build output too - ignored, so a clean leaves it: reports and classes of tests
+ * that are no longer there tell whoever looks that they are. The code's is kept: it can be a cache
+ * worth having, and the code is what is built from.
+ */
+function cleanTestsBuild(moduleDir) {
+    if (existsSync(join(moduleDir, "tests")))
+        git(moduleDir, ["clean", "-q", "-fdX", "--", "tests"]);
+}
+export function resetToLastCommit(dir) {
+    try {
+        const moduleDir = moduleDirOf(dir);
+        if (!existsSync(join(moduleDir, HISTORY_DIR)) || head(dir) === undefined)
+            return [];
+        const status = git(moduleDir, ["status", "--porcelain", "--untracked-files=all"]);
+        if (status.status !== 0)
+            return [];
+        const changed = status.stdout
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .map((line) => line.slice(3));
+        cleanTestsBuild(moduleDir);
+        if (changed.length === 0)
+            return [];
+        git(moduleDir, ["reset", "-q", "--hard", "HEAD"]);
+        git(moduleDir, ["clean", "-q", "-fd"]);
+        return changed;
+    }
+    catch {
+        return [];
+    }
+}
+/** The module's commit, made first when it has none: what is there, as found, or an empty one. */
+function ensureCommit(moduleDir) {
+    mkdirSync(moduleDir, { recursive: true });
+    if (!ensureHistory(moduleDir))
+        return undefined;
+    const current = git(moduleDir, ["rev-parse", "HEAD"]);
+    if (current.status === 0)
+        return current.stdout.trim();
+    git(moduleDir, ["add", "-A"]);
+    git(moduleDir, ["commit", "-q", "--allow-empty", "-m", "the module as turri found it"]);
+    const made = git(moduleDir, ["rev-parse", "HEAD"]);
+    return made.status === 0 ? made.stdout.trim() : undefined;
+}
+/**
+ * The start of every unit of work that writes a module's code or tests: each module folder it
+ * writes back at its last commit - saying so when that undid anything - and that commit kept, to
+ * go back to if the work fails. A module with no commit yet is given one first, so there always
+ * is one.
+ */
+export function startWork(dirs, moduleName) {
+    const modules = [];
+    for (const moduleDir of [...new Set(dirs.map(moduleDirOf))]) {
+        try {
+            const commit = ensureCommit(moduleDir);
+            if (commit === undefined)
+                continue;
+            const undone = resetToLastCommit(join(moduleDir, "code"));
+            if (undone.length > 0) {
+                const shown = undone.slice(0, 5).join(", ");
+                reportActivity(`${moduleName}: back to its last commit - ${undone.length} change${undone.length === 1 ? "" : "s"} an unfinished ` +
+                    `run left behind undone (${shown}${undone.length > 5 ? ", …" : ""})`);
+            }
+            modules.push({ moduleDir, commit });
+        }
+        catch {
+            // History is a record, not a gate: without it, the work goes on.
+        }
+    }
+    return { modules };
+}
+/**
+ * Where work already under way is now, to go back to if what comes next fails - without
+ * putting anything back first: what is uncommitted belongs to the work that is under way.
+ */
+export function markWork(dirs) {
+    const modules = [];
+    for (const moduleDir of [...new Set(dirs.map(moduleDirOf))]) {
+        try {
+            const commit = ensureCommit(moduleDir);
+            if (commit !== undefined)
+                modules.push({ moduleDir, commit });
+        }
+        catch {
+            // History is a record, not a gate.
+        }
+    }
+    return { modules };
+}
+/**
+ * Undo a unit of work that failed: every module folder it wrote back at the commit it started
+ * from - its changes, the files it added and any commit it made since, gone. What history does
+ * not track stays: installed dependencies, caches.
+ */
+export function abandonWork(start, moduleName, why) {
+    for (const { moduleDir, commit } of start?.modules ?? []) {
+        try {
+            const moved = git(moduleDir, ["rev-parse", "HEAD"]).stdout.trim() !== commit;
+            const status = git(moduleDir, ["status", "--porcelain", "--untracked-files=all"]).stdout.trim();
+            if (!moved && status === "")
+                continue;
+            git(moduleDir, ["reset", "-q", "--hard", commit]);
+            git(moduleDir, ["clean", "-q", "-fd"]);
+            cleanTestsBuild(moduleDir);
+            reportActivity(`${moduleName}: ${why} - ${basename(moduleDir)} is back where the work started`);
+        }
+        catch {
+            // Nothing to undo with.
+        }
+    }
+}
+/**
+ * A file of a module as its last commit has it - `file` relative to `dir`, its build or its tests
+ * folder - or undefined when there is no history, no commit, or the file is not in it.
+ */
+export function committedText(dir, file) {
+    try {
+        const moduleDir = moduleDirOf(dir);
+        if (!existsSync(join(moduleDir, HISTORY_DIR)))
+            return undefined;
+        const path = [basename(dir), file].join("/");
+        const shown = git(moduleDir, ["show", `HEAD:${path}`]);
+        return shown.status === 0 ? shown.stdout : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Commit these paths of a module, and nothing else of it - removed, added or changed. Whatever else is in the folder,
+ * uncommitted - what an interrupted job left - stays as it is, for the next unit of work to put back. Returns the commit.
+ */
+export function commitPaths(moduleDir, paths, subject) {
+    if (paths.length === 0 || !existsSync(join(moduleDir, HISTORY_DIR)))
+        return undefined;
+    git(moduleDir, ["add", "-A", "--", ...paths]);
+    if (git(moduleDir, ["diff", "--cached", "--quiet", "--", ...paths]).status === 0)
+        return undefined;
+    if (git(moduleDir, ["commit", "-q", "-m", subject, "--", ...paths]).status !== 0)
+        return undefined;
+    return git(moduleDir, ["rev-parse", "HEAD"]).stdout.trim() || undefined;
+}
+/** Bring a history's exclude list up to the one it is made with now. */
+export function refreshExcludes(moduleDir) {
+    const exclude = join(moduleDir, HISTORY_DIR, "info", "exclude");
+    if (!existsSync(join(moduleDir, HISTORY_DIR)))
+        return;
+    mkdirSync(dirname(exclude), { recursive: true });
+    writeFileSync(exclude, `${EXCLUDED.join("\n")}\n`);
+}
+/** The current commit of a module's history, if it has one. */
+export function head(dir) {
+    const moduleDir = moduleDirOf(dir);
+    if (!existsSync(join(moduleDir, HISTORY_DIR)))
+        return undefined;
+    const result = git(moduleDir, ["rev-parse", "--short", "HEAD"]);
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+/** The module's history, newest first, one line per commit. */
+export function historyLog(dir, limit = 30) {
+    const moduleDir = moduleDirOf(dir);
+    if (!existsSync(join(moduleDir, HISTORY_DIR)))
+        return `No history for ${basename(moduleDir)} yet.`;
+    const result = git(moduleDir, ["log", `-${limit}`, "--format=%h  %ad  %s", "--date=format:%Y-%m-%d %H:%M"]);
+    return result.status === 0 && result.stdout.trim() !== "" ? result.stdout.trimEnd() : `No history for ${basename(moduleDir)} yet.`;
+}
+/** One commit in full: its message and what it changed. */
+export function historyShow(dir, commit) {
+    const moduleDir = moduleDirOf(dir);
+    const result = git(moduleDir, ["show", "--stat", "--patch", "--format=%h %ad%n%n%B", "--date=format:%Y-%m-%d %H:%M", commit]);
+    return result.status === 0 ? result.stdout : result.stderr.trim() || `No commit ${commit}.`;
+}
+/** Kept out of a work's diff: the harness's own files, and lockfiles - long, generated, and nothing to review. */
+const NOT_REVIEWED = /(^|\/)(\.turri\.json|\.turri-notes\.md|package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|uv\.lock|poetry\.lock|Pipfile\.lock|Cargo\.lock|go\.sum|composer\.lock|Gemfile\.lock)$/;
+/** How much of a work's diff is shown whole; past it, the rest is named, to be read from the files. */
+const WORK_DIFF_MAX = 80_000;
+/**
+ * What the work under way changed in `dir` - the code folder, or the tests folder - since the module's last
+ * commit: a unified diff of every file changed, and every new file whole. Every unit of work starts from that
+ * commit, so this is exactly what its agents wrote. Lockfiles and the harness's own files are left out. Empty when
+ * there is no history, or nothing changed.
+ */
+export function workDiff(dir) {
+    const moduleDir = moduleDirOf(dir);
+    if (!existsSync(join(moduleDir, HISTORY_DIR)))
+        return "";
+    const folder = basename(dir);
+    // Paths relative to `dir`, where the agent reading the diff works.
+    const within = (path) => (path.startsWith(`${folder}/`) ? path.slice(folder.length + 1) : path);
+    const changed = git(moduleDir, ["diff", "HEAD", "--no-color", "--name-only", "--", folder]).stdout.split("\n").filter(Boolean).map(within);
+    const added = git(moduleDir, ["ls-files", "--others", "--exclude-standard", "--", folder]).stdout.split("\n").filter(Boolean).map(within);
+    const parts = [];
+    for (const file of changed.filter((path) => !NOT_REVIEWED.test(path))) {
+        parts.push(git(moduleDir, ["diff", "HEAD", "--no-color", `--relative=${folder}`, "--", `${folder}/${file}`]).stdout.trimEnd());
+    }
+    // A new file, whole: git diff of it against nothing.
+    for (const file of added.filter((path) => !NOT_REVIEWED.test(path))) {
+        parts.push(spawnSync("git", ["diff", "--no-index", "--no-color", "--", "/dev/null", file], { cwd: dir, encoding: "utf8" }).stdout.trimEnd());
+    }
+    const diff = parts.filter(Boolean).join("\n");
+    if (diff.length <= WORK_DIFF_MAX)
+        return diff;
+    const shown = diff.slice(0, WORK_DIFF_MAX);
+    const cut = shown.lastIndexOf("\ndiff --git ");
+    const kept = cut > 0 ? shown.slice(0, cut) : shown;
+    const rest = [...changed, ...added].filter((path) => !NOT_REVIEWED.test(path) && !kept.includes(` b/${path}\n`));
+    return `${kept}\n\n(the diff goes on past what is shown: read these files whole - ${rest.join(", ")})`;
+}
+/**
+ * The work in `dir` as it is now - the code folder, or the tests folder - as a git tree, without a commit and without
+ * touching the module's index: what a review saw, so the next review is shown only what changed since. Undefined
+ * when there is no history.
+ */
+export function workSnapshot(dir) {
+    const moduleDir = moduleDirOf(dir);
+    if (!existsSync(join(moduleDir, HISTORY_DIR)))
+        return undefined;
+    const folder = basename(dir);
+    // An index of its own, so the module's - what the next commit is made from - is never touched.
+    const env = { ...process.env, GIT_INDEX_FILE: join(moduleDir, HISTORY_DIR, "turri-snapshot-index") };
+    const run = (args) => spawnSync("git", ["--git-dir", join(moduleDir, HISTORY_DIR), "--work-tree", moduleDir, ...args], { cwd: moduleDir, encoding: "utf8", env });
+    if (run(["read-tree", "--empty"]).status !== 0)
+        return undefined;
+    if (run(["add", "-A", "--", folder]).status !== 0)
+        return undefined;
+    const tree = run(["write-tree"]);
+    return tree.status === 0 ? tree.stdout.trim() : undefined;
+}
+/**
+ * What changed in `dir` since a snapshot of it (`workSnapshot`): a unified diff of every file changed, added or
+ * removed since, as `workDiff` shows the whole work. Empty when nothing changed, or there is no history.
+ */
+export function diffSinceSnapshot(dir, snapshot) {
+    const now = workSnapshot(dir);
+    if (now === undefined)
+        return "";
+    if (now === snapshot)
+        return "";
+    const moduleDir = moduleDirOf(dir);
+    const folder = basename(dir);
+    const files = git(moduleDir, ["diff", "--no-color", "--name-only", `--relative=${folder}`, snapshot, now, "--", folder]).stdout.split("\n").filter((path) => path !== "" && !NOT_REVIEWED.test(path));
+    const parts = files.map((file) => git(moduleDir, ["diff", "--no-color", `--relative=${folder}`, snapshot, now, "--", `${folder}/${file}`]).stdout.trimEnd());
+    const diff = parts.filter(Boolean).join("\n");
+    if (diff.length <= WORK_DIFF_MAX)
+        return diff;
+    const shown = diff.slice(0, WORK_DIFF_MAX);
+    const cut = shown.lastIndexOf("\ndiff --git ");
+    const kept = cut > 0 ? shown.slice(0, cut) : shown;
+    const rest = files.filter((path) => !kept.includes(` b/${path}\n`));
+    return `${kept}\n\n(the diff goes on past what is shown: read these files whole - ${rest.join(", ")})`;
+}