@veda-hq/dvara 0.0.0-stage → 0.5.4

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/records.js

@@ -0,0 +1,96 @@
+// What a supervised hook tells its supervisor while it runs: stage markers
+// (`dvara_stage`) and records (`dvara_record`), one line each in files the
+// supervisor names. Parsed here into the history row's fields.
+/**
+ * A duration field. Empty is unmeasured, not zero; text that is not a finite
+ * number is null too, as JSON would have written NaN and Infinity.
+ */
+export const recordedMs = (text) => {
+    if (!text)
+        return null;
+    const ms = Number(text);
+    return Number.isFinite(ms) ? ms : null;
+};
+/**
+ * Records, one tab-separated line each: `refs-source <stdin|none>`,
+ * `ref <local> <remote>`, `stage-input <stage> <kind> <digest>`,
+ * `proof <check> <outcome> <ms>`, and
+ * `proof-reason <check> <reason> <waitMs> <executionMs> <previousExecutionMs>`.
+ * Anything else is ignored.
+ */
+export const parseRecords = (text) => {
+    const declared = new Map();
+    const proof = [];
+    const proofDiagnostics = [];
+    if (text === null)
+        return { pushed: null, declared, proof, proofDiagnostics };
+    const pushed = { source: "none", refs: [] };
+    for (const line of text.split("\n").filter(Boolean)) {
+        const [type, ...f] = line.split("\t");
+        if (type === "refs-source")
+            pushed.source = f[0] ?? "";
+        else if (type === "ref")
+            pushed.refs.push({ local: f[0] ?? "", remote: f[1] ?? "" });
+        else if (type === "stage-input")
+            declared.set(f[0] ?? "", { kind: f[1] ?? "", digest: f[2] ?? "" });
+        else if (type === "proof") {
+            const ms = Number(f[2]);
+            proof.push({
+                check: f[0] ?? "",
+                outcome: f[1] ?? "",
+                ms: Number.isFinite(ms) ? ms : null,
+            });
+        }
+        else if (type === "proof-reason")
+            proofDiagnostics.push({
+                check: f[0] ?? "",
+                reason: f[1] ?? "",
+                waitMs: recordedMs(f[2]),
+                executionMs: recordedMs(f[3]),
+                previousExecutionMs: recordedMs(f[4]),
+            });
+    }
+    return { pushed, declared, proof, proofDiagnostics };
+};
+/**
+ * Stage markers, `<seconds>\t<name>` per line (bash's `$SECONDS`), offset by
+ * the time the hook spent choosing its runtime before the supervisor started,
+ * which becomes a stage of its own. A marker whose time is not a number stays
+ * NaN: JSON writes it as null, which voids its neighbours' durations rather
+ * than inventing them.
+ */
+export const parseStages = (text, bootstrapMs) => {
+    const stages = (text ?? "")
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [seconds, name = ""] = line.split("\t");
+        const at = Number(seconds);
+        return {
+            name,
+            startMs: Number.isFinite(at) ? bootstrapMs + at * 1000 : Number.NaN,
+        };
+    });
+    if (bootstrapMs)
+        stages.unshift({ name: "runtime-selection", startMs: 0 });
+    return stages;
+};
+/** Resident memory (KiB) and process count of `rootPid`'s tree, from a `ps -axo pid=,ppid=,rss=` table. */
+export const treeUsage = (table, rootPid) => {
+    const rows = table
+        .trim()
+        .split("\n")
+        .map((row) => row.trim().split(/\s+/).map(Number));
+    const ids = new Set([rootPid]);
+    // A Set visits what is added while iterating it: a breadth-first walk.
+    for (const id of ids)
+        for (const [pid, ppid] of rows)
+            if (ppid === id && pid !== undefined)
+                ids.add(pid);
+    let rssKiB = 0;
+    for (const [pid, , rss] of rows)
+        if (pid !== undefined && ids.has(pid))
+            rssKiB += rss ?? 0;
+    return { rssKiB, processes: ids.size };
+};