@veda-hq/dvara 0.5.0 → 0.5.16

package/dist/records/markdown.js

@@ -0,0 +1,115 @@
+// Where a Markdown file's fenced code blocks are, line by line: the one
+// reading EVIDENCE-01 needs to tell commands from captured output. Which
+// lines open and close a fence is CommonMark's answer, from
+// mdast-util-from-markdown; the lines stay the file's own, so every finding
+// keeps its source line.
+import { fromMarkdown } from "mdast-util-from-markdown";
+/** A regular expression match's group: '' when it did not take part. */
+export const group = (match, index) => match[index] ?? "";
+/** 1-based line `n` of `lines`: '' past the end. */
+const lineAt = (lines, n) => lines[n - 1] ?? "";
+/** A fenced block's opener, read where mdast places the code node. */
+const FENCE_MARKER = /^(`{3,}|~{3,})/;
+/** A closer: the opener's character, alone on its line. */
+const FENCE_CLOSER = /^\s*(`+|~+)\s*$/;
+/**
+ * A line with its `quotes` blockquote markers taken off: a fence inside a
+ * quote (`> ```text`) is a fence, and its body lines carry the same `> `.
+ * mdast counts the quotes, so a marker may sit at every indent: a quote nested
+ * in a list item starts past the item's own indentation.
+ */
+const unquote = (line, quotes) => {
+    let inner = line;
+    for (let depth = 0; depth < quotes; depth += 1) {
+        inner = inner.replace(/^[ \t]*> ?/, "");
+    }
+    return inner;
+};
+export const parseMarkdown = (text) => {
+    const lines = text.split(/\r?\n/);
+    // Frontmatter is not Markdown: a `---` block on the first line is skipped,
+    // and its lines are never in a fence.
+    let offset = 0;
+    if (lines[0]?.trim() === "---") {
+        const end = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+        if (end !== -1)
+            offset = end + 1;
+    }
+    const fences = [];
+    const inFence = new Array(lines.length + 1).fill(false);
+    const readFence = (node, parent, quotes) => {
+        // mdast gives every code node its position and value.
+        const { start, end } = node.position;
+        const value = node.value;
+        const n = start.line + offset;
+        // An indented code block starts at its indentation, not at a marker.
+        const marker = FENCE_MARKER.exec(lineAt(lines, n).slice(start.column - 1));
+        if (marker === null)
+            return;
+        const inner = (at) => unquote(lineAt(lines, at), quotes);
+        const last = end.line + offset;
+        const closer = FENCE_CLOSER.exec(inner(last));
+        const bodyLines = value === "" ? 0 : value.split("\n").length;
+        // Closed: the last line is a closer mdast left out of the body (a
+        // closer-shaped line indented as body text stays in it). A one-line
+        // fence has no body line to leave out, so it is never closed. A closed
+        // fence's value holds the lines between the markers, never one more:
+        // trailing blank lines count, and a lone blank line is '' (0 < 2).
+        const closed = closer !== null &&
+            group(closer, 1).startsWith(group(marker, 1).charAt(0)) &&
+            group(closer, 1).length >= group(marker, 1).length &&
+            bodyLines !== last - n;
+        // Unclosed, a fence runs to the end of its container: the document's
+        // last line, or the line before mdast's end when that is a line start.
+        let close = last;
+        if (!closed && parent.type === "root")
+            close = lines.length;
+        else if (!closed && end.column === 1)
+            close = last - 1;
+        const body = [];
+        for (let at = n + 1; at <= (closed ? close - 1 : close); at += 1) {
+            body.push({ n: at, text: inner(at) });
+        }
+        for (let at = n; at <= close; at += 1)
+            inFence[at] = true;
+        fences.push({
+            open: n,
+            close,
+            lang: (node.lang ?? "").toLowerCase(),
+            body,
+        });
+    };
+    const visit = (node, parent, quotes) => {
+        if (node.type === "code")
+            readFence(node, parent, quotes);
+        const inner = quotes + (node.type === "blockquote" ? 1 : 0);
+        for (const child of node.children ?? [])
+            visit(child, node, inner);
+    };
+    // A lone CR is a line ending to CommonMark but not to `lines`: it is read
+    // as a space.
+    const root = fromMarkdown(lines.slice(offset).join("\n").replaceAll("\r", " "));
+    visit(root, root, 0);
+    return { lines, fences, inFence };
+};
+const SCRIPT_LANGS = new Set(["sh", "bash", "zsh", "shell"]);
+const TRANSCRIPT_LANGS = new Set([
+    "",
+    "text",
+    "txt",
+    "console",
+    "shell-session",
+    "output",
+    "log",
+    "plaintext",
+]);
+/**
+ * A fence by its info string: `script` (`sh`, `bash`, …) is commands to run,
+ * every line; `transcript` (none, `text`, `console`, …) has `$ ` command
+ * lines and what they printed; `source` (`ts`, `json`, …) quotes a file.
+ */
+export const fenceKind = (fence) => {
+    if (SCRIPT_LANGS.has(fence.lang))
+        return "script";
+    return TRANSCRIPT_LANGS.has(fence.lang) ? "transcript" : "source";
+};

package/dist/records/paths.js

@@ -0,0 +1,103 @@
+import { isCodePath } from "./scope.js";
+/** Each manager's install commands; a global install is not a dependency. */
+const INSTALL = {
+    npm: String.raw `npm\s+(install|i|ci|add)`,
+    yarn: String.raw `yarn\s+(install|add)`,
+    pnpm: String.raw `pnpm\s+(install|i|add)`,
+};
+const installPattern = (manager) => {
+    const others = Object.keys(INSTALL).filter((m) => m !== manager);
+    return {
+        check: "install-command",
+        re: new RegExp(String.raw `\b(${others.map((m) => INSTALL[m]).join("|")})\b(?!\s+(-g|--global)\b)`),
+        what: `${others.join("/")} install: this repository installs with ${manager} only`,
+        negatable: true,
+    };
+};
+/**
+ * Everywhere a reader may follow text: prose, data and configuration. Code
+ * is not this rule's to read: a path there is a fixture, or a URI scheme the
+ * code handles.
+ */
+const patterns = (manager) => [
+    {
+        check: "file-url",
+        // `file://<placeholder>/…` is already anonymised by its writer.
+        re: /\bfile:\/\/(?!<)/i,
+        what: "a file:// URL resolves only on the machine that wrote it",
+        path: true,
+    },
+    {
+        check: "home-path",
+        re: /(?<![\w.~-])\/Users\/(?!Shared\b)[A-Za-z0-9._-]+/,
+        what: "a /Users/<name> home path names one machine and its operator",
+        path: true,
+    },
+    {
+        check: "home-path",
+        // The hosted CI runner's home is the same on every run. The name ends at
+        // a path boundary: `/`, the line's end, a space or punctuation (a
+        // sentence's closing `.` is not part of it).
+        re: /(?<![\w.~-])\/home\/(?!runner\b)[a-z_][a-z0-9._-]*?(?:\/|(?=$|[^\w.-]|\.(?!\w)))/,
+        what: "a /home/<name> path names one machine and its operator",
+        path: true,
+    },
+    {
+        check: "temp-root",
+        re: /(?<![\w.-])\/(private\/tmp|private\/var|var\/folders)\//,
+        what: "a sandbox temp root is gone after the session",
+        path: true,
+    },
+    {
+        check: "git-path",
+        // An entry under `.git/` of every kind (`FETCH_HEAD`, `packed-refs`, …);
+        // a bare mention of the folder, `.git/` alone, names no path in it.
+        re: /(?<![\w-])\.git\/[\w.-]+/,
+        what: "a literal .git/ path is not the repository layout (worktrees move it)",
+        path: true,
+    },
+    ...(manager === null ? [] : [installPattern(manager)]),
+    {
+        check: "agent-marker",
+        re: /\b(I am|I'm|as) Agent[\s-]*\d+\b/i,
+        what: "an agent-process marker is session narration, not a record",
+    },
+];
+const NEGATION = /\b(never|not|no|don't|do not|instead of|rather than|refuse[sd]?|forbid(s|den)?|ban(s|ned)?)\b/i;
+/** Whether the clause a match sits in says not to do it. */
+const negated = (text, at) => {
+    // A negation covers its own clause only: in "never npm install; run yarn
+    // install", the second instruction stands.
+    const clauses = text.slice(0, at).split(/[;.!?]|\bbut\b/i);
+    return NEGATION.test(clauses.at(-1) ?? "");
+};
+const scan = (file, text, list, allowed) => {
+    const found = [];
+    text.split(/\r?\n/).forEach((line, i) => {
+        // One finding per line: `file:///Users/…` is one non-durable reference.
+        for (const pattern of list) {
+            // No pattern carries the `g` flag (`exec` would then keep state
+            // across lines), so each scan takes a global copy.
+            const match = [
+                ...line.matchAll(new RegExp(pattern.re.source, `${pattern.re.flags}g`)),
+            ].find((m) => !(pattern.negatable && negated(line, m.index)) &&
+                !(pattern.path && allowed.some((a) => a.test(line.slice(m.index)))));
+            if (!match)
+                continue;
+            found.push({
+                rule: "EVIDENCE-02",
+                check: pattern.check,
+                file,
+                line: i + 1,
+                message: `${pattern.what}: "${match[0]}"`,
+            });
+            break;
+        }
+    });
+    return found;
+};
+/** EVIDENCE-02 under these settings: `allowPaths` and `packageManager`. */
+export const durablePaths = (records) => {
+    const list = patterns(records.packageManager);
+    return (file, text) => isCodePath(file) ? [] : scan(file, text, list, records.allowPaths);
+};

package/dist/records/rules.js

@@ -0,0 +1,10 @@
+import { commitIdentity } from "./identity.js";
+import { durablePaths } from "./paths.js";
+/**
+ * The rule set for these settings: EVIDENCE-02 everywhere text is read, and
+ * EVIDENCE-01 where `records.identityPaths` match (none by default).
+ */
+export const rulesFor = (records) => [
+    durablePaths(records),
+    commitIdentity(records),
+];

package/dist/records/scope.js

@@ -0,0 +1,26 @@
+/**
+ * A frozen path: under one of `frozen.paths` and not one of the exact
+ * `frozen.except` paths, which stay editable.
+ */
+export const isFrozenPath = (path, frozen) => frozen.paths.some((prefix) => path.startsWith(prefix)) &&
+    !frozen.except.includes(path);
+/**
+ * Files never scanned as text: binaries, lockfiles and generated bundles.
+ * Everything else a repository tracks is text a reader may follow.
+ */
+const NOT_TEXT = /(\.(png|jpe?g|gif|webp|ico|icns|pdf|zip|gz|tgz|br|woff2?|ttf|otf|eot|mp4|mov|mp3|wav|jar|keystore|jks|p12|der|so|dylib|a|bin|db|sqlite|tflite|onnx|pbxproj|xcworkspacedata|lock)|pnpm-lock\.yaml|package-lock\.json)$/i;
+export const isTextPath = (path) => !NOT_TEXT.test(path);
+/**
+ * Source files, by extension in either case (`main.C`): the path denylist
+ * does not read code.
+ */
+export const isCodePath = (path) => /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|py|sh|bash|zsh|rb|swift|kt|java|m|mm|h|c|cc|cpp|go|rs|sql|prisma|css|scss)$/i.test(path);
+/**
+ * Whether any rule reads `path`: not a binary, not a frozen path, not under a
+ * skipped prefix, and none of `own`, the gate's own files (its baseline and
+ * the config, which quote the very shapes the rules refuse).
+ */
+export const isReadPath = (path, records, own) => isTextPath(path) &&
+    !own.includes(path) &&
+    !records.skip.some((prefix) => path.startsWith(prefix)) &&
+    !isFrozenPath(path, records.frozen);

package/dist/records/types.js

@@ -0,0 +1,4 @@
+// What the record rules share: the findings they report and the tree they ask
+// about. Every rule is pure: the tree arrives as functions, so the same rule
+// checks the index at pre-commit and a commit in CI.
+export const RULE_IDS = ["EVIDENCE-01", "EVIDENCE-02"];

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.0",
+  "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",
@@ -42,10 +42,13 @@
     "@types/node": "24.19.2",
     "typescript": "7.0.2"
   },
+  "dependencies": {
+    "mdast-util-from-markdown": "2.0.3"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude=src/**/*.test.ts --test-coverage-include=src/**/*.ts src/**/*.test.ts",
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude='src/**/*.test.ts' --test-coverage-include='src/**/*.ts' 'src/**/*.test.ts'",
     "smoke": "node dist/cli.js --version && node dist/cli.js shell stages",
     "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke"
   }