@veda-hq/dvara 0.5.4 → 0.5.16

package/README.md

@@ -29,8 +29,21 @@ file in your repository; dvara runs it.
   attaches to each run; it may stop a hung hook and decide the verdict. Without
   one, or when it fails to load, the hook runs exactly as it would anyway.
 
-Every one of these is fail-open: telemetry, quiet output and the watchdog never
-change a hook's verdict.
+- **A stage list, if you keep one.** `stages`, or the JSON file `stageList`
+  names (inside an installed package, say), gives each hook's stage names in
+  order. A passing run that marks a stage its hook's list does not have, or
+  marks one out of the list's order, is refused (exit 1) with the reason. So is
+  a run of a hook in `stageListRequired` (default `pre-push`) that marks a
+  stage and whose list file cannot be read, so a missing package never lets a
+  push that ran its stages through silently; any other hook passes then, with a
+  warning that its stages were not checked. A
+  stage may be marked again where it stands, a name may
+  appear more than once in a list, and dvara's own `startup` and
+  `runtime-selection` need no entry. A run that marks no stage reads no list.
+
+Telemetry, quiet output and a watchdog that fails to load never change a
+hook's verdict. Only a signal, an enforcing watchdog's stop and the stage list
+do.
 
 ## A hook under dvara
 
@@ -73,13 +86,15 @@ rename it in its messages (default "preflight" and "Preflight").
 `.dvara.json` at the repository's root, or the file `DVARA_CONFIG` names. Every
 field is optional; an unknown field is an error.
 
-| Field        | Default                                          | Meaning                                                        |
-| ------------ | ------------------------------------------------ | -------------------------------------------------------------- |
-| `historyDir` | `.dvara`                                         | where the history, the quiet log and scratch files go          |
-| `quietHooks` | `["pre-commit"]`                                 | hooks whose passing output is one line                         |
-| `watchdog`   | `null`                                           | a watchdog module, relative to the root                        |
-| `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 |
+| Field               | Default                                          | Meaning                                                                                           |
+| ------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `historyDir`        | `.dvara`                                         | where the history, the quiet log and scratch files go                                             |
+| `quietHooks`        | `["pre-commit"]`                                 | hooks whose passing output is one line                                                            |
+| `watchdog`          | `null`                                           | a watchdog module, relative to the root                                                           |
+| `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, which a passing run must keep to; `dvara stages <hook>` prints them  |
+| `stageList`         | `null`                                           | a JSON file holding the same map instead, relative to the root and read when a run ends; not both |
+| `stageListRequired` | `["pre-push"]`                                   | hooks a list file that cannot be read refuses; any other hook passes with a warning               |
 
 `records`, an object, holds the settings of `dvara records` and `dvara frozen`
 (below). Each field is optional; an unknown one is an error.

package/dist/cli.js

@@ -7,6 +7,7 @@ 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 { listFor, readStageLists } from "./stages.js";
 import { supervise } from "./supervisor.js";
 export const USAGE = [
     "usage: dvara run <hook-file> [hook args…]   run a git hook under the supervisor",
@@ -85,7 +86,15 @@ export const run = async (argv, context) => {
             return 2;
         }
         if (command === "stages") {
-            for (const name of config.stages[rest[0] ?? ""] ?? [])
+            let lists;
+            try {
+                lists = readStageLists(cwd, config);
+            }
+            catch (error) {
+                io.err(error.message);
+                return 2;
+            }
+            for (const name of lists ? (listFor(lists, rest[0] ?? "") ?? []) : [])
                 io.out(name);
             return 0;
         }

package/dist/config.js

@@ -2,6 +2,7 @@
 // DVARA_CONFIG names (relative to the root). Every field is optional.
 import { readFileSync } from "node:fs";
 import { isAbsolute, posix, resolve } from "node:path";
+import { parseStageLists } from "./stages.js";
 export const PACKAGE_MANAGERS = ["pnpm", "npm", "yarn"];
 export const DEFAULTS = {
     historyDir: ".dvara",
@@ -9,6 +10,8 @@ export const DEFAULTS = {
     watchdog: null,
     baseRefs: ["origin/main", "origin/develop", "origin/master"],
     stages: {},
+    stageList: null,
+    stageListRequired: ["pre-push"],
     records: {
         baseline: ".dvara/records-baseline.json",
         skip: [],
@@ -137,15 +140,25 @@ export const parseConfig = (text) => {
     }
     if ("baseRefs" in entries)
         config.baseRefs = strings(entries.baseRefs, "baseRefs");
-    if ("stages" in entries) {
-        const stages = entries.stages;
-        if (typeof stages !== "object" || stages === null || Array.isArray(stages))
-            throw new Error("stages must map each hook to its stage names");
-        const out = {};
-        for (const [hook, names] of Object.entries(stages))
-            out[hook] = strings(names, `stages.${hook}`);
-        config.stages = out;
+    if ("stages" in entries)
+        config.stages = parseStageLists(entries.stages, "stages");
+    if ("stageList" in entries) {
+        const path = entries.stageList;
+        if (path !== null &&
+            (typeof path !== "string" ||
+                path === "" ||
+                isAbsolute(path) ||
+                escapes(path) ||
+                // Read with the platform's resolve: on Windows `..\x` and `C:x` leave the root.
+                path.includes("\\") ||
+                /^[A-Za-z]:/.test(path)))
+            throw new Error("stageList must be a file path inside the repository, with / separators, or null");
+        if (path !== null && "stages" in entries)
+            throw new Error("give stages or stageList, not both");
+        config.stageList = path;
     }
+    if ("stageListRequired" in entries)
+        config.stageListRequired = strings(entries.stageListRequired, "stageListRequired");
     if ("records" in entries)
         config.records = parseRecordsConfig(entries.records);
     return config;

package/dist/stages.js

@@ -0,0 +1,106 @@
+// Each hook's stage names, in the order they run, and the check a passing run
+// must pass: every stage it marks is in its hook's list, in the list's order.
+// The lists are `stages` in the config, or the JSON file `stageList` names
+// (inside an installed package, say), read when the run ends: a pre-commit
+// that installs dependencies first finds the file its install put there.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** The stages dvara marks itself, which no list names. */
+export const OWN_STAGES = new Set([
+    "startup",
+    "runtime-selection",
+]);
+/** A name a stage file line can carry: not empty, no tab or line break (records.ts splits on them). */
+const isStageName = (name) => typeof name === "string" && name !== "" && !/[\t\r\n]/.test(name);
+/** Each hook's names, from `value`; anything else is an error naming `field`. */
+export const parseStageLists = (value, field) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(`${field} must map each hook to its stage names`);
+    const entries = Object.entries(value).map(([hook, names]) => {
+        if (!Array.isArray(names) || !names.every(isStageName))
+            throw new Error(`${field}.${hook} must be a list of stage names`);
+        return [hook, names];
+    });
+    // fromEntries defines each key as its own, `__proto__` included.
+    return Object.fromEntries(entries);
+};
+/** `hook`'s own list, never one inherited from Object's prototype (`toString`). */
+export const listFor = (lists, hook) => Object.hasOwn(lists, hook) ? lists[hook] : undefined;
+/**
+ * The lists a run is checked against: the file `stageList` names, else
+ * `stages`, else null (no lists: nothing is checked). A file that cannot be
+ * read or parsed is an error naming it.
+ */
+export const readStageLists = (root, config) => {
+    if (config.stageList === null)
+        return Object.keys(config.stages).length > 0 ? config.stages : null;
+    const path = resolve(root, config.stageList);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`dvara: cannot read the stage list ${path}: ${error.message}. Is the package that ships it installed?`);
+    }
+    try {
+        return parseStageLists(JSON.parse(text), "the stage list");
+    }
+    catch (error) {
+        throw new Error(`dvara: ${path}: ${error.message}`);
+    }
+};
+/**
+ * Why `marked` breaks `hook`'s list, or null when it keeps to it. A stage may
+ * be marked again where it stands (a loop), and a name may appear more than
+ * once in a list; each mark takes the first place at or after the last one's.
+ */
+export const stageViolation = (hook, marked, lists) => {
+    const names = marked.filter((name) => !OWN_STAGES.has(name));
+    if (names.length === 0)
+        return null;
+    const list = listFor(lists, hook);
+    if (list === undefined)
+        return `${hook} marked stage "${names[0]}", but the stage list has no ${hook} list`;
+    let at = 0;
+    for (const [index, name] of names.entries()) {
+        const found = list.indexOf(name, at);
+        if (found >= 0) {
+            at = found;
+            continue;
+        }
+        if (!list.includes(name))
+            return `${hook} marked stage "${name}", which its stage list does not have`;
+        return `${hook} marked stage "${name}" after "${names[index - 1] ?? ""}", out of its stage list's order`;
+    }
+    return null;
+};
+const PASS = { refusal: null, warning: null };
+/**
+ * What the stage list says of a passing run of `hook` that marked `marked`.
+ * With no stage of its own marked nothing is read. A list that cannot be read
+ * refuses a hook in `required`, since a check that cannot run must not pass
+ * there; any other hook passes with a warning saying it was not checked.
+ */
+export const stageVerdict = (hook, marked, lists, required) => {
+    if (marked.every((name) => OWN_STAGES.has(name)))
+        return PASS;
+    let read;
+    try {
+        read = lists();
+    }
+    catch (error) {
+        const message = error.message;
+        return required.includes(hook)
+            ? { refusal: message, warning: null }
+            : {
+                refusal: null,
+                warning: `${message} ${hook}'s stages were not checked.`,
+            };
+    }
+    if (read === null)
+        return PASS;
+    const violation = stageViolation(hook, marked, read);
+    return violation === null
+        ? PASS
+        : { refusal: `dvara: ${violation}.`, warning: null };
+};

package/dist/supervisor.js

@@ -7,9 +7,12 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 // The hook supervisor: runs a git hook under bash, forwards the terminal's
-// signals to it, and writes one history row per run. It never changes the
-// hook's verdict except to report a signalled run as cancelled; every failure
-// of its own (telemetry, watchdog, quiet output) is fail-open.
+// signals to it, and writes one history row per run. It changes the hook's
+// verdict only to report a signalled run as cancelled, to let an enforcing
+// watchdog's stop decide it, and to refuse a passing run that broke its stage
+// list (stages.ts), or, for a hook in stageListRequired, whose list cannot be
+// read. Every other failure of its
+// own (telemetry, watchdog, quiet output) is fail-open.
 import { execFileSync, spawn, spawnSync, } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
@@ -19,6 +22,7 @@ import { pathToFileURL } from "node:url";
 import { hookKind, invocationContext, perfLevelNames } from "./context.js";
 import { isQuiet, successLine, successNotices } from "./quiet.js";
 import { parseRecords, parseStages, treeUsage } from "./records.js";
+import { readStageLists, stageVerdict } from "./stages.js";
 /** Exit code per signal, shared by the pre-launch path and the exit handler. */
 export const SIGNAL_EXIT_CODES = {
     SIGINT: 130,
@@ -278,9 +282,19 @@ export const supervise = async ([hook, ...args], options) => {
         if (imposed)
             code = imposed.code;
         const ended = Date.now();
+        const marks = parseStages(readOrNull(events), bootstrapMs);
+        // Only a run that would pass is checked: a failure keeps its own story.
+        const { refusal, warning } = code === 0 && !imposed && !signal
+            ? stageVerdict(hookName, marks.map((mark) => mark.name), () => readStageLists(root, config), config.stageListRequired)
+            : { refusal: null, warning: null };
+        if (refusal !== null)
+            code = 1;
         if (quiet)
             report(code, ended - started);
-        const marks = parseStages(readOrNull(events), bootstrapMs);
+        if (refusal !== null)
+            stderr(`${refusal}\n`);
+        if (warning !== null)
+            stderr(`⚠️  ${warning}\n`);
         const { pushed, declared, proof, proofDiagnostics } = parseRecords(readOrNull(records));
         const verdict = (last) => imposed
             ? imposed.status
@@ -310,7 +324,7 @@ export const supervise = async ([hook, ...args], options) => {
                 durationMs: ended - started,
                 exitCode: code,
                 signal,
-                error,
+                error: error ?? refusal ?? warning ?? undefined,
                 status: verdict(false),
                 branch,
                 fingerprint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/dvara",
-  "version": "0.5.4",
+  "version": "0.5.16",
   "description": "Git hooks for repositories coding agents work in: runs each hook under a supervisor that times its stages, forwards signals and keeps one history row per run, with quiet output on success and a keep-going mode for preflights.",
   "keywords": [
     "git hooks",