@veda-hq/dvara 0.5.0 → 0.5.4

package/README.md

@@ -81,6 +81,19 @@ field is optional; an unknown field is an error.
 | `baseRefs`   | `origin/main`, `origin/develop`, `origin/master` | the refs tried for the base a run is judged against            |
 | `stages`     | `{}`                                             | each hook's stages in order; `dvara stages <hook>` prints them |
 
+`records`, an object, holds the settings of `dvara records` and `dvara frozen`
+(below). Each field is optional; an unknown one is an error.
+
+| Field            | Default                        | Meaning                                                                                                                  |
+| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `baseline`       | `.dvara/records-baseline.json` | the per-file baseline, relative to the root; read from git, so it must be tracked (un-ignore it if `.dvara/` is ignored) |
+| `skip`           | `[]`                           | path prefixes no rule reads, such as a checker's own fixtures                                                            |
+| `frozen`         | `{"paths": [], "except": []}`  | `paths`: prefixes `dvara frozen` refuses changing and no rule reads; `except`: exact paths under them that stay editable |
+| `identityPaths`  | `[]`                           | regular expressions for the paths where a commit must be cited by its full id (`EVIDENCE-01`); none by default           |
+| `repository`     | `null`                         | `owner/name` on GitHub: its commit URLs are this repository's, every other repository's are not checked                  |
+| `allowPaths`     | `[]`                           | regular expressions for machine paths that are durable by agreement, matched from where the path starts: anchor with `^` |
+| `packageManager` | `null`                         | `pnpm`, `npm` or `yarn`: the other managers' install commands are refused; `null` checks none                            |
+
 The environment it reads: `DVARA_MODE=preflight` (a preflight's rows get kind
 `preflight`), `DVARA_BACKGROUND=1` (started detached), `DVARA_MEASUREMENT_CONTEXT=manual-benchmark`,
 `DVARA_BOOTSTRAP_SECONDS` (seconds the hook spent selecting its runtime before
@@ -112,11 +125,78 @@ export function exitDisposition(
 ): { code: number; status: string } | null;
 ```
 
+## The record gate: `dvara records`
+
+Committed text should not cite what stops meaning anything once the session
+that wrote it ends. The gate reads every text file that is not source code, a
+binary, a lockfile (`*.lock`, `pnpm-lock.yaml`, `package-lock.json`), a
+symlink or a submodule, a skipped or frozen path, the baseline or the config,
+and refuses (rule `EVIDENCE-02`, one finding per line):
+
+- a `file://` URL, a `/Users/<name>` or `/home/<name>` home path, a sandbox temp
+  root (`/private/tmp/`, `/private/var/`, `/var/folders/`), a literal `.git/`
+  path, or an agent-process marker ("I am Agent 3");
+- another package manager's install command, when `packageManager` names one.
+  A clause that says not to ("never run `npm install`") is no finding.
+
+Where `identityPaths` match, it also refuses (rule `EVIDENCE-01`) a commit cited
+by less than its full 40-hex id, since git lengthens abbreviations as history
+grows and clones disagree on their length:
+
+- `abbreviated-id`: a 7–39 hex token the line makes a commit (after a commit
+  word, backticked on its own, in an `a..b` range, cut off with an ellipsis, or
+  in a short commit URL of `repository`), unless the line names it another kind
+  of hash (digest, sha256, checksum, …);
+- `abbreviating-command`: a git command that prints abbreviations
+  (`--oneline`, `%h`, `--abbrev-commit`, `rev-parse --short`);
+- `unresolved-id`: a full id the change adds that is not a commit in this
+  repository, compared with the ids the file cited at the merge base. No
+  baseline holds these: they are new by construction.
+
+In Markdown, a fence's captured output is not read for tokens; its command
+lines are (`$ ` lines of a transcript, every line of an `sh` fence). Fences are
+found by CommonMark's rules (mdast-util-from-markdown), so a fence in a quote or
+a list item counts.
+
+Files written before the gate existed are held by the baseline: each file's
+count per rule, which may only fall. A new finding in a legacy file, a fix that
+leaves its allowance in place, an entry for a file that is gone or not read,
+and a baseline edit that raises a count or adds a file are all refused; a
+rename git detects carries its entry forward.
+
+```sh
+dvara records --staged                 # pre-commit: the index, against the first baseRefs that resolves
+dvara records --base origin/main       # CI: the files the branch changed, at HEAD
+dvara records --all [--base REF]       # every tracked file at HEAD
+dvara records --all --write-baseline   # record today's counts
+dvara records --all --survey           # counts per rule and check
+```
+
+Exit 0: clean or within the baseline; 1: refused; 2: could not run. Inside the
+package the gate takes any list of rules, `(path, text, tree) => Finding[]`;
+the command runs the list `rulesFor` in `src/records/rules.ts` returns.
+
+## Frozen paths: `dvara frozen`
+
+A path under one of `records.frozen.paths` is history: no commit adds, changes
+or deletes a file there, except the exact `records.frozen.except` paths.
+
+```sh
+dvara frozen --staged                    # pre-commit, merge commits included
+dvara frozen --base origin/main [--head REF]   # CI: what the branch changes since its merge base
+```
+
+In a merge, a path staged exactly as a merged-in parent has it is that
+parent's change and passes; a hand resolution counts. With no frozen paths
+configured it passes without asking git. Exit 0, 1 or 2 as above.
+
 ## Commands
 
 ```sh
 dvara run <hook-file> [hook args…]   # run a git hook under the supervisor
 dvara stages <hook>                  # the stages .dvara.json lists for it
 dvara shell <stages|keep-going>      # the path of a shell helper
+dvara records <--staged | --all [--base REF] [--write-baseline | --survey] | --base REF>
+dvara frozen <--staged | --base REF [--head REF]>
 dvara --version
 ```

package/dist/cli.js

@@ -3,12 +3,19 @@
 import { readFileSync, realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { loadConfig } from "./config.js";
+import { configName, loadConfig } from "./config.js";
+import { frozen, parseArgs as parseFrozenArgs, USAGE as FROZEN_USAGE, } from "./records/frozen.js";
+import { parseArgs as parseRecordsArgs, records, USAGE as RECORDS_USAGE, } from "./records/gate.js";
+import { runner } from "./records/git.js";
 import { supervise } from "./supervisor.js";
 export const USAGE = [
     "usage: dvara run <hook-file> [hook args…]   run a git hook under the supervisor",
     "       dvara stages <hook>                  the hook stages the config lists, one per line",
     "       dvara shell <stages|keep-going>      the path of a shell helper to source",
+    "       dvara records <--staged | --all [--base REF] [--write-baseline | --survey] | --base REF>",
+    "                                            the record gate: no new non-durable paths, a baseline that only falls",
+    "       dvara frozen <--staged | --base REF [--head REF]>",
+    "                                            refuse changes to the frozen paths",
     "       dvara --version",
 ].join("\n");
 const SHELL_HELPERS = new Set(["stages", "keep-going"]);
@@ -18,6 +25,38 @@ export const ownVersion = () => {
 };
 /** The path of a shell helper this package ships. */
 export const shellHelper = (name) => resolve(import.meta.dirname, "..", "shell", `${name}.sh`);
+/**
+ * `dvara records` or `dvara frozen` at the root `cwd`: 2 on bad arguments, a
+ * config it cannot read, or git failing.
+ */
+const checkCommand = (command, args, { io, cwd, env }) => {
+    const parsed = command === "records" ? parseRecordsArgs(args) : parseFrozenArgs(args);
+    if ("error" in parsed) {
+        io.err(`dvara ${command}: ${parsed.error}`);
+        io.err(command === "records" ? RECORDS_USAGE : FROZEN_USAGE);
+        return 2;
+    }
+    try {
+        const config = loadConfig(cwd, env);
+        const repo = { cwd, env };
+        if ("mode" in parsed)
+            return records(parsed, repo, io.out, {
+                records: config.records,
+                baseRefs: config.baseRefs,
+                own: [configName(env)],
+            });
+        const result = frozen(parsed, runner(repo), config.records.frozen, env);
+        for (const line of result.stdout)
+            io.out(line);
+        for (const line of result.stderr)
+            io.err(line);
+        return result.code;
+    }
+    catch (error) {
+        io.err(`dvara ${command}: ${error.message}`);
+        return 2;
+    }
+};
 /** Runs one command; resolves with the process's exit code. */
 export const run = async (argv, context) => {
     const { io, cwd, env } = context;
@@ -32,6 +71,8 @@ export const run = async (argv, context) => {
         io.out(shellHelper(rest[0] ?? ""));
         return 0;
     }
+    if (command === "records" || command === "frozen")
+        return checkCommand(command, rest, context);
     if ((command === "run" && rest.length > 0) ||
         (command === "stages" && rest.length === 1)) {
         // Git runs every hook at the top of the working tree.

package/dist/config.js

@@ -1,20 +1,117 @@
 // A repository's dvara settings: `.dvara.json` at its root, or the file
 // DVARA_CONFIG names (relative to the root). Every field is optional.
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, posix, resolve } from "node:path";
+export const PACKAGE_MANAGERS = ["pnpm", "npm", "yarn"];
 export const DEFAULTS = {
     historyDir: ".dvara",
     quietHooks: ["pre-commit"],
     watchdog: null,
     baseRefs: ["origin/main", "origin/develop", "origin/master"],
     stages: {},
+    records: {
+        baseline: ".dvara/records-baseline.json",
+        skip: [],
+        frozen: { paths: [], except: [] },
+        identityPaths: [],
+        repository: null,
+        allowPaths: [],
+        packageManager: null,
+    },
 };
 export const CONFIG_FILE = ".dvara.json";
+/** The config file's name relative to the root, as `loadConfig` reads it. */
+export const configName = (env) => posix.normalize(env.DVARA_CONFIG || CONFIG_FILE);
 const strings = (value, field) => {
     if (!Array.isArray(value) || !value.every((v) => typeof v === "string"))
         throw new Error(`${field} must be a list of strings`);
     return value;
 };
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const onlyKnown = (entries, known, field) => {
+    for (const key of Object.keys(entries))
+        if (!known.includes(key))
+            throw new Error(`unknown field ${field}${key}`);
+};
+/** Whether `path`, normalized, leaves the root: `..`, `../x`, `a/../../x`. */
+const escapes = (path) => {
+    const normal = posix.normalize(path);
+    return normal === ".." || normal.startsWith("../");
+};
+/**
+ * Repository-relative path prefixes or paths: none empty, none absolute, none
+ * leaving the root (git prints no path there, so it would match nothing).
+ */
+const repoPaths = (value, field) => {
+    const list = strings(value, field);
+    for (const path of list)
+        if (path === "" || isAbsolute(path) || escapes(path))
+            throw new Error(`${field} must hold repository-relative paths`);
+    return list;
+};
+const patterns = (value, field) => strings(value, field).map((source, i) => {
+    try {
+        return new RegExp(source);
+    }
+    catch (error) {
+        throw new Error(`${field}[${i}] is not a regular expression: ${error.message}`);
+    }
+});
+const parseRecordsConfig = (value) => {
+    if (!isObject(value))
+        throw new Error("records must be an object");
+    onlyKnown(value, Object.keys(DEFAULTS.records), "records.");
+    const records = { ...DEFAULTS.records };
+    if ("baseline" in value) {
+        const path = value.baseline;
+        // Compared with the paths git prints: `./a/../b.json` is `b.json`. A
+        // folder (`.`, `archive/`) names no tracked file, so it is no baseline.
+        const normal = typeof path === "string" ? posix.normalize(path) : "";
+        if (typeof path !== "string" ||
+            path === "" ||
+            isAbsolute(path) ||
+            escapes(path) ||
+            normal === "." ||
+            normal.endsWith("/"))
+            throw new Error("records.baseline must be a file path inside the repository");
+        records.baseline = normal;
+    }
+    if ("skip" in value)
+        records.skip = repoPaths(value.skip, "records.skip");
+    if ("frozen" in value) {
+        const frozen = value.frozen;
+        if (!isObject(frozen))
+            throw new Error("records.frozen must be an object");
+        onlyKnown(frozen, ["paths", "except"], "records.frozen.");
+        records.frozen = {
+            paths: "paths" in frozen
+                ? repoPaths(frozen.paths, "records.frozen.paths")
+                : [],
+            except: "except" in frozen
+                ? repoPaths(frozen.except, "records.frozen.except")
+                : [],
+        };
+    }
+    if ("identityPaths" in value)
+        records.identityPaths = patterns(value.identityPaths, "records.identityPaths");
+    if ("repository" in value) {
+        const repository = value.repository;
+        if (repository !== null &&
+            (typeof repository !== "string" || !/^[\w.-]+\/[\w.-]+$/.test(repository)))
+            throw new Error('records.repository must be "owner/name" or null');
+        records.repository = repository;
+    }
+    if ("allowPaths" in value)
+        records.allowPaths = patterns(value.allowPaths, "records.allowPaths");
+    if ("packageManager" in value) {
+        const manager = value.packageManager;
+        if (manager !== null &&
+            !PACKAGE_MANAGERS.includes(manager))
+            throw new Error(`records.packageManager must be one of ${PACKAGE_MANAGERS.join(", ")}, or null`);
+        records.packageManager = manager;
+    }
+    return records;
+};
 /** The settings in `text` over the defaults; a field of the wrong type is an error, an unknown one too. */
 export const parseConfig = (text) => {
     const raw = JSON.parse(text);
@@ -49,6 +146,8 @@ export const parseConfig = (text) => {
             out[hook] = strings(names, `stages.${hook}`);
         config.stages = out;
     }
+    if ("records" in entries)
+        config.records = parseRecordsConfig(entries.records);
     return config;
 };
 /**

package/dist/records/baseline.js

@@ -0,0 +1,152 @@
+// The ratchet for files written before the gate existed.
+//
+// A legacy file's current count of findings per rule is recorded here, and the
+// gate holds each count where it is or lower. Three refusals keep the numbers
+// honest:
+//
+// - a file over its recorded count (a new violation in a legacy file);
+// - a file under it (the fix lands with the lower number, so it cannot creep
+//   back up to the old allowance), and an entry for a file that is gone or
+//   that the gate does not read;
+// - a baseline edit that raises a count or adds a file, other than a rename
+//   git detects in the same change carrying its entry forward at the same or
+//   lower counts.
+//
+// The commit that adds the baseline has no earlier one to compare with; the
+// gate then checks every file it names, so each entry must equal the tree.
+import { RULE_IDS } from "./types.js";
+/**
+ * A map keyed by repository path with no prototype: a tracked file named
+ * `__proto__` or `constructor` is an entry like any other.
+ */
+export const pathMap = () => Object.create(null);
+/** A JSON object: not an array, not null. */
+const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isRuleId = (rule) => RULE_IDS.includes(rule);
+/** The baseline in `text`; `where` names it in errors. Absent or blank is empty. */
+export const parseBaseline = (text, where) => {
+    if (text === null || text.trim() === "")
+        return { files: pathMap() };
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${where}: ${error.message}`);
+    }
+    if (!isJsonObject(raw) || !("files" in raw))
+        throw new Error(`${where}: expected {"files": {...}}`);
+    const files = raw.files;
+    if (!isJsonObject(files))
+        throw new Error(`${where}: "files" must be an object`);
+    const out = pathMap();
+    for (const [path, counts] of Object.entries(files)) {
+        if (!isJsonObject(counts))
+            throw new Error(`${where}: ${path} must map rule ids to counts`);
+        const entry = {};
+        for (const [rule, count] of Object.entries(counts)) {
+            if (!isRuleId(rule))
+                throw new Error(`${where}: ${path} names unknown rule ${rule}`);
+            if (typeof count !== "number" || !Number.isInteger(count) || count < 1)
+                throw new Error(`${where}: ${path} ${rule} must be a positive integer`);
+            entry[rule] = count;
+        }
+        out[path] = entry;
+    }
+    return { files: out };
+};
+/** The baseline as committed: paths sorted, zero counts and empty entries dropped. */
+export const renderBaseline = (baseline) => {
+    const files = pathMap();
+    for (const path of Object.keys(baseline.files).sort()) {
+        const counts = {};
+        for (const rule of RULE_IDS) {
+            const count = baseline.files[path]?.[rule];
+            if (count !== undefined && count > 0)
+                counts[rule] = count;
+        }
+        if (Object.keys(counts).length > 0)
+            files[path] = counts;
+    }
+    return `${JSON.stringify({ files }, null, 2)}\n`;
+};
+export const countFindings = (findings) => {
+    const out = new Map();
+    for (const finding of findings) {
+        const counts = out.get(finding.file) ?? {};
+        counts[finding.rule] = (counts[finding.rule] ?? 0) + 1;
+        out.set(finding.file, counts);
+    }
+    return out;
+};
+/** Compare the checked files' findings with their allowances. */
+export const ratchet = (checked, findings, baseline) => {
+    const result = { over: [], under: [] };
+    const held = findings.filter((f) => f.ratchet !== false);
+    const counts = countFindings(held);
+    // A finding no baseline may hold is over, whatever the file's allowance.
+    const unheld = findings.filter((f) => f.ratchet === false);
+    for (const file of new Set(unheld.map((f) => f.file))) {
+        for (const rule of RULE_IDS) {
+            const mine = unheld.filter((f) => f.file === file && f.rule === rule);
+            if (mine.length === 0)
+                continue;
+            result.over.push({
+                file,
+                rule,
+                allowed: 0,
+                now: mine.length,
+                findings: mine,
+            });
+        }
+    }
+    for (const file of checked) {
+        const now = counts.get(file) ?? {};
+        const allowed = baseline.files[file] ?? {};
+        for (const rule of RULE_IDS) {
+            const n = now[rule] ?? 0;
+            const a = allowed[rule] ?? 0;
+            if (n > a)
+                result.over.push({
+                    file,
+                    rule,
+                    allowed: a,
+                    now: n,
+                    findings: held.filter((f) => f.file === file && f.rule === rule),
+                });
+            else if (n < a)
+                result.under.push({ file, rule, allowed: a, now: n });
+        }
+    }
+    return result;
+};
+/** Baseline entries for files `exists` does not vouch for. */
+export const staleEntries = (baseline, exists) => Object.keys(baseline.files).filter((path) => !exists(path));
+/**
+ * Refusals for a baseline edit that raises any allowance. A new entry is
+ * accepted only as a rename git detected in the same change (`renames`, new
+ * path to old path), whose old entry is removed and whose counts are no
+ * higher: fixing one legacy file must not fund a violation in another.
+ */
+export const baselineIncreases = (before, after, renames = new Map()) => {
+    const problems = [];
+    const carriesForward = (from, counts) => {
+        const old = before.files[from];
+        return (!(from in after.files) &&
+            old !== undefined &&
+            RULE_IDS.every((rule) => (counts[rule] ?? 0) <= (old[rule] ?? 0)));
+    };
+    for (const [path, counts] of Object.entries(after.files)) {
+        const old = before.files[path];
+        if (old === undefined) {
+            const from = renames.get(path);
+            if (from === undefined || !carriesForward(from, counts))
+                problems.push(`${path}: a new baseline entry; fix the file instead of recording its findings`);
+            continue;
+        }
+        for (const rule of RULE_IDS)
+            if ((counts[rule] ?? 0) > (old[rule] ?? 0))
+                problems.push(`${path}: ${rule} raised from ${old[rule] ?? 0} to ${counts[rule] ?? 0}; counts only fall`);
+    }
+    return problems;
+};

package/dist/records/frozen.js

@@ -0,0 +1,161 @@
+// `dvara frozen`: frozen paths refuse changes. Nothing adds, changes or
+// deletes a file under one of `records.frozen.paths`, except the exact paths
+// `records.frozen.except` keeps editable.
+//
+//   --staged               pre-commit, merge commits included: what the index
+//                          changes against HEAD. In a merge, a path staged
+//                          exactly as a merged-in parent has it is that
+//                          parent's change, judged where it was made, and
+//                          passes; content no parent had (a hand resolution)
+//                          counts. The branch check sees the rest.
+//   --base REF [--head REF]
+//                          the branch check: what HEAD (or --head) changes
+//                          since its merge base with REF.
+//
+// Exit 0: no frozen path changes. 1: refused. 2: could not run.
+import { existsSync, readFileSync } from "node:fs";
+import { parseArgs as parseFlags } from "node:util";
+import { isFrozenPath } from "./scope.js";
+export const USAGE = "usage: dvara frozen --staged | --base REF [--head REF]";
+/** The mode `args` ask for, or what is wrong with them. */
+export const parseArgs = (args) => {
+    let values;
+    try {
+        ({ values } = parseFlags({
+            args: [...args],
+            options: {
+                staged: { type: "boolean" },
+                base: { type: "string" },
+                head: { type: "string" },
+            },
+            strict: true,
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        return { error: error.message };
+    }
+    const { staged, base, head } = values;
+    if (staged && base === undefined && head === undefined)
+        return { kind: "staged" };
+    if (!staged && base !== undefined)
+        return { kind: "range", base, head: head ?? "HEAD" };
+    return { error: "give --staged, or --base REF [--head REF]" };
+};
+/** `git diff --name-status -z` output, as status and path pairs. */
+export const parseNameStatus = (out) => {
+    const fields = out.split("\0");
+    const changes = [];
+    for (let i = 0; i + 1 < fields.length; i += 2)
+        changes.push({ status: fields[i] ?? "", path: fields[i + 1] ?? "" });
+    return changes;
+};
+const DIFF = ["diff", "--name-status", "--no-renames", "-z"];
+const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+const GITHEAD = "GITHEAD_";
+/** The SHA lines of the git-dir file `name`; none when it is absent. */
+const gitFileShas = (git, name) => {
+    const file = git([
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-path",
+        name,
+    ]).trim();
+    if (!existsSync(file))
+        return [];
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .filter((line) => SHA.test(line));
+};
+/** The tree of git's own clean merge of HEAD and `head`; none on a conflict. */
+export const mergedTree = (git, head) => {
+    try {
+        return git(["merge-tree", "--write-tree", "--no-messages", "HEAD", head])
+            .split("\n")[0]
+            ?.trim();
+    }
+    catch {
+        // merge-tree exits 1 on a conflict; with no clean merge to compare,
+        // `head` is not trusted, the stricter answer.
+        return undefined;
+    }
+};
+/**
+ * Whether the index is exactly a clean merge of HEAD and `heads`, so it holds
+ * no content those commits do not: the tree git's default strategy writes to
+ * AUTO_MERGE before pre-merge-commit runs, or, for one merged commit under any
+ * strategy, git's own merge of HEAD and it.
+ */
+export const isCleanMerge = (git, heads) => {
+    const trees = gitFileShas(git, "AUTO_MERGE");
+    const [only] = heads;
+    if (heads.length === 1 && only !== undefined) {
+        const tree = mergedTree(git, only);
+        if (tree !== undefined)
+            trees.push(tree);
+    }
+    return trees.some((tree) => git(["diff", "--cached", "--name-only", tree]) === "");
+};
+/**
+ * The commits a merge in progress takes in; none outside a merge. A merge
+ * finished by `git commit` lists them in MERGE_HEAD. A clean `git merge` runs
+ * pre-merge-commit before it writes MERGE_HEAD, and names each merged commit
+ * only in the `GITHEAD_<sha>` variable it sets for its hooks. Anyone can set
+ * such a variable, so those commits count only when the index is a clean
+ * merge of them.
+ */
+export const mergeHeads = (git, env) => {
+    const heads = new Set(gitFileShas(git, "MERGE_HEAD"));
+    const named = Object.keys(env)
+        .filter((name) => name.startsWith(GITHEAD))
+        .map((name) => name.slice(GITHEAD.length))
+        .filter((sha) => SHA.test(sha));
+    if (isCleanMerge(git, named))
+        for (const sha of named)
+            heads.add(sha);
+    return [...heads];
+};
+/** What `mode` changes, before the frozen filter. */
+export const changes = (git, mode, env = {}) => {
+    if (mode.kind === "range")
+        return parseNameStatus(git([...DIFF, `${mode.base}...${mode.head}`]));
+    const staged = parseNameStatus(git([...DIFF, "--cached"]));
+    const kept = mergeHeads(git, env).map((sha) => new Set(parseNameStatus(git([...DIFF, "--cached", sha])).map((c) => c.path)));
+    return staged.filter((change) => kept.every((paths) => paths.has(change.path)));
+};
+/** The verdict on `frozen`, the frozen changes of `mode`. */
+export const report = (mode, frozen, paths) => {
+    if (frozen.length === 0)
+        return {
+            code: 0,
+            stdout: ["✅ frozen: no frozen path changes"],
+            stderr: [],
+        };
+    const undo = mode.kind === "staged"
+        ? "Unstage them (git restore --staged -- <path>), then commit again."
+        : // The range is `base...head`, the changes since the merge base: the
+            // content to go back to is the merge base's, not what base has today.
+            // The refs stay out of the command: a ref may hold shell syntax, and
+            // this line is meant to be copied.
+            `Drop them from the branch: restore each path to its content at the merge base with ${mode.base} (git restore --source=<merge base> --staged --worktree -- <path>; git merge-base names it), then commit.`;
+    return {
+        code: 1,
+        stdout: [],
+        stderr: [
+            `❌ frozen: ${mode.kind === "staged" ? "this commit" : `this branch (since ${mode.base})`} changes ${frozen.length} file(s) under ${paths.paths.join(", ")}:`,
+            ...frozen.map((change) => `     ${change.status} ${change.path}`),
+            "   These paths are frozen: no file there is added, changed or deleted.",
+            ...(paths.except.length === 0
+                ? []
+                : [`   Still editable: ${paths.except.join(", ")}.`]),
+            `   ${undo}`,
+        ],
+    };
+};
+/** The verdict for `mode` in the repository `git` runs in; a failing git throws. */
+export const frozen = (mode, git, paths, env = {}) => {
+    // Nothing frozen: nothing to ask git.
+    if (paths.paths.length === 0)
+        return { code: 0, stdout: ["✅ frozen: no paths are frozen"], stderr: [] };
+    return report(mode, changes(git, mode, env).filter((change) => isFrozenPath(change.path, paths)), paths);
+};