@veda-hq/dvara 0.0.0-stage → 0.5.4

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);
+};