balladeer 0.0.4 → 1.0.0

package/dist/touch-map.js

@@ -0,0 +1,487 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The touch map: which files each promise's verifier actually executed.
+ *
+ * A promise's scope surfaces are what somebody wrote down when they agreed it.
+ * They are a guess about which files matter, they age, and nobody rewrites them
+ * when a module moves. What a verifier executed is not a guess: it is the file
+ * list V8 recorded while the check ran. So an agent asking "which promises does
+ * this change touch" gets an answer measured from the repository in front of it
+ * rather than one somebody typed months ago.
+ *
+ * Two rules hold the whole feature up, and both are structural rather than
+ * remembered. The map is written under `.continuity/` and nothing in this
+ * command sends it anywhere: it names a customer's file tree, which is the one
+ * thing Balladeer promises never to receive. And every entry carries the digest
+ * of the verifier that produced it, so a map computed against a verifier that
+ * has since changed reads as stale rather than as fact.
+ */
+/** The directory a repository keeps its promises, packages and map in. */
+export const CONTINUITY_DIRECTORY = ".continuity";
+/** Where a promise's sealed files live. Everything under it is the verifier itself. */
+export const PROMISE_TREE_ROOT = ".continuity/promises";
+/** Where the sealed packages live, one JSON file per promise. */
+export const PACKAGE_DIRECTORY = ".continuity/packages";
+/** Where the scaffold leaves the readable draft each package was sealed from. */
+export const DRAFT_DIRECTORY = ".continuity/drafts";
+/** The map itself, beside the packages it was computed from. */
+export const TOUCH_MAP_FILE = ".continuity/touch-map.json";
+/** The document's own version, so a reader can refuse one it does not understand. */
+export const TOUCH_MAP_SCHEMA = "balladeer-touch-map/v1";
+/**
+ * What one map may hold.
+ *
+ * A repository with a thousand promises and a hundred thousand files would
+ * otherwise write a document nothing can open. The caps are stated in the
+ * document when they bite, because a map that quietly stopped early would be
+ * read as "nothing else is touched", which is the one thing it must never say
+ * by accident.
+ */
+export const TOUCH_MAP_LIMITS = {
+    /** Files one map names. */
+    files: 5000,
+    /** Promises listed under one file. */
+    promisesPerFile: 50,
+    /** Characters of one repository-relative path. */
+    path: 400,
+    /** Characters of one promise's claim, as `affected` prints it. */
+    claim: 200,
+};
+/** A promise id as the runner spells it. Anything else is not one of ours. */
+const PROMISE_ID = /^prom_[a-z0-9]{8,64}$/;
+function readableString(value, limit) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    // Bounded, and stripped of anything that could reflow a terminal: this text
+    // came out of a file in the customer's repository and is about to be printed.
+    return trimmed.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, limit);
+}
+/**
+ * The first sentence of a stored outcome, never crossing a paragraph break.
+ *
+ * The same rule the promise index uses, written out rather than imported: this
+ * package is published with no dependency of its own, and `affected` prints a
+ * claim from a file on the customer's disk with no server in the conversation.
+ */
+export function firstSentence(value) {
+    const paragraph = value
+        .trim()
+        .split(/\n\s*\n/)[0]
+        ?.trim() ?? "";
+    if (!paragraph)
+        return "";
+    const match = /^[\s\S]*?[.!?](?=\s+[A-Z0-9"“(]|\s*$)/.exec(paragraph);
+    return (match?.[0] ?? paragraph).trim();
+}
+function claimOf(promise) {
+    const stored = readableString(promise?.oneSentenceOutcome, TOUCH_MAP_LIMITS.claim);
+    if (stored !== undefined)
+        return stored;
+    const outcome = readableString(promise?.observableOutcome, 4000);
+    if (outcome === undefined)
+        return undefined;
+    const derived = firstSentence(outcome);
+    if (derived === "")
+        return undefined;
+    return derived.length <= TOUCH_MAP_LIMITS.claim
+        ? derived
+        : `${derived.slice(0, TOUCH_MAP_LIMITS.claim - 3).trimEnd()}...`;
+}
+function verifierTarget(value) {
+    const spec = value;
+    const executable = typeof spec?.executable === "string" ? spec.executable : undefined;
+    if (executable === undefined || executable === "")
+        return undefined;
+    if (!Array.isArray(spec?.args) || !spec.args.every((arg) => typeof arg === "string"))
+        return undefined;
+    return {
+        executable,
+        args: [...spec.args],
+        ...(typeof spec.cwd === "string" ? { cwd: spec.cwd } : {}),
+        ...(typeof spec.timeoutMs === "number" && Number.isFinite(spec.timeoutMs)
+            ? { timeoutMs: spec.timeoutMs }
+            : {}),
+    };
+}
+/**
+ * Every promise this checkout has a sealed package for, in id order.
+ *
+ * It reads the package files and nothing else, so it works with no network, no
+ * credential, and no runner checkout. A file that is not a readable sealed
+ * package is skipped rather than reported: a half-written draft in that
+ * directory is not a promise, and refusing to map the other promises because of
+ * it would be worse than leaving it out.
+ *
+ * The claim is read from the draft the scaffold leaves beside the package when
+ * there is one, because that is the readable copy a person edits, and from the
+ * package itself when there is not.
+ */
+export function readLocalPackages(root) {
+    let entries;
+    try {
+        entries = readdirSync(join(root, PACKAGE_DIRECTORY));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith(".json"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(root, PACKAGE_DIRECTORY, entry), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const promise = parsed.promise;
+        const promiseId = typeof promise?.id === "string" ? promise.id : undefined;
+        if (promiseId === undefined || !PROMISE_ID.test(promiseId))
+            continue;
+        const verifier = parsed.verifier;
+        const target = verifierTarget(verifier?.target);
+        const materials = Array.isArray(parsed.materials) ? parsed.materials : [];
+        const materialPaths = materials
+            .map((material) => material?.path)
+            .filter((path) => typeof path === "string")
+            .sort();
+        let draft;
+        try {
+            draft = JSON.parse(readFileSync(join(root, DRAFT_DIRECTORY, `${promiseId}.json`), "utf8"));
+        }
+        catch {
+            draft = undefined;
+        }
+        const draftPromise = draft?.promise;
+        const title = readableString(draftPromise?.title, 160) ?? readableString(promise?.title, 160);
+        const claim = claimOf(draftPromise) ?? claimOf(promise);
+        found.push({
+            promiseId,
+            packageFile: `${PACKAGE_DIRECTORY}/${entry}`,
+            // A package with no runnable target is still a promise this checkout
+            // holds, and `touch-map` has to say it could not run rather than pretend
+            // it was never there.
+            target: target ?? { executable: "", args: [] },
+            materialPaths,
+            ...(title === undefined ? {} : { title }),
+            ...(claim === undefined ? {} : { claim }),
+        });
+    }
+    return found.sort((left, right) => left.promiseId.localeCompare(right.promiseId));
+}
+/** JSON with its object keys in sorted order, so the same input digests the same. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function fileDigest(root, path) {
+    try {
+        return `sha256:${createHash("sha256")
+            .update(readFileSync(join(root, path)))
+            .digest("hex")}`;
+    }
+    catch {
+        // A locked material that is not there is a fact about the verifier as much
+        // as its bytes are, and it has to change the digest: a map computed while
+        // the fixture existed must not read current once somebody deleted it.
+        return "missing";
+    }
+}
+/**
+ * The digest a map entry was computed under.
+ *
+ * It covers exactly what decides which files a verifier executes: how the
+ * verifier is invoked, and the bytes of every file the package locks. It is
+ * taken from the files on disk rather than from the digests the package
+ * declares, so both ways a verifier can change move it: a reseal, and an edit
+ * nobody has sealed yet.
+ *
+ * It is deliberately not the package digest. That moves when somebody fixes a
+ * typo in the promise's title, and a map that read stale after a wording change
+ * would be rebuilt so often that nobody would trust the word.
+ */
+export function verifierDigest(root, pkg) {
+    const material = pkg.materialPaths.map((path) => ({ path, digest: fileDigest(root, path) }));
+    const body = canonicalJson({
+        target: {
+            executable: pkg.target.executable,
+            args: [...pkg.target.args],
+            cwd: pkg.target.cwd ?? ".",
+        },
+        materials: material,
+    });
+    return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+/** A path in the map's own spelling: repository-relative, forward slashes. */
+export function repositoryPath(root, absolute) {
+    const relativePath = relative(root, absolute);
+    if (relativePath === "" || isAbsolute(relativePath))
+        return undefined;
+    const posix = relativePath.split(sep).join("/");
+    if (posix.startsWith("../"))
+        return undefined;
+    return posix;
+}
+/**
+ * Whether a file this verifier executed belongs in the map.
+ *
+ * The promise tree is out, because those files are the verifier: a map that
+ * said "this promise touches its own verifier" would answer every question with
+ * itself. Installed dependencies are out too. They are executed by everything,
+ * they are nobody's change, and a map that carried them would be mostly
+ * `node_modules` and would blow the size cap before it reached the first file
+ * anybody edits.
+ */
+export function mappablePath(path) {
+    if (path.length > TOUCH_MAP_LIMITS.path)
+        return false;
+    if (path.startsWith(`${PROMISE_TREE_ROOT}/`))
+        return false;
+    return !path.split("/").includes("node_modules");
+}
+/**
+ * The repository files one coverage document says were executed, before any
+ * exclusion.
+ *
+ * V8 records every script the process loaded, including Node's own internals
+ * and anything outside this repository. A script counts as executed when any of
+ * its ranges ran at least once, which is true of a module the verifier merely
+ * imported: importing it runs its top level, and a verifier that imports a file
+ * has read the behavior in it.
+ *
+ * The promise's own tree is still in this answer, because it is what proves the
+ * verifier ran at all. `mappablePath` is what takes it back out before anything
+ * is written down.
+ */
+export function executedPaths(root, document) {
+    const result = document?.result;
+    if (!Array.isArray(result))
+        return [];
+    const paths = new Set();
+    for (const script of result) {
+        const url = script?.url;
+        if (typeof url !== "string" || !url.startsWith("file://"))
+            continue;
+        const functions = script.functions;
+        if (!Array.isArray(functions))
+            continue;
+        const ran = functions.some((fn) => {
+            const ranges = fn?.ranges;
+            return (Array.isArray(ranges) &&
+                ranges.some((range) => {
+                    const count = range?.count;
+                    return typeof count === "number" && count > 0;
+                }));
+        });
+        if (!ran)
+            continue;
+        let absolute;
+        try {
+            absolute = fileURLToPath(url);
+        }
+        catch {
+            continue;
+        }
+        const path = repositoryPath(root, absolute);
+        if (path === undefined || path.length > TOUCH_MAP_LIMITS.path)
+            continue;
+        paths.add(path);
+    }
+    return [...paths].sort();
+}
+/** Every coverage document V8 left in one directory, unparsed ones skipped. */
+export function readCoverageDirectory(directory) {
+    let entries;
+    try {
+        entries = readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+    const documents = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith(".json"))
+            continue;
+        try {
+            const full = join(directory, entry);
+            if (!statSync(full).isFile())
+                continue;
+            documents.push(JSON.parse(readFileSync(full, "utf8")));
+        }
+        catch {
+            continue;
+        }
+    }
+    return documents;
+}
+/**
+ * The map document, assembled from what each verifier executed.
+ *
+ * Ordering is total and by name at every level, so two runs over an unchanged
+ * repository produce the same bytes and a diff shows a behavior change rather
+ * than a shuffle.
+ */
+export function buildTouchMap(input) {
+    const byPath = new Map();
+    let truncated = false;
+    for (const promise of input.covered) {
+        for (const path of promise.paths) {
+            const entries = byPath.get(path) ?? [];
+            if (entries.length >= TOUCH_MAP_LIMITS.promisesPerFile) {
+                truncated = true;
+                continue;
+            }
+            entries.push({ promiseId: promise.promiseId, verifierDigest: promise.verifierDigest });
+            byPath.set(path, entries);
+        }
+    }
+    const paths = [...byPath.keys()].sort();
+    if (paths.length > TOUCH_MAP_LIMITS.files)
+        truncated = true;
+    const files = paths.slice(0, TOUCH_MAP_LIMITS.files).map((path) => ({
+        path,
+        promises: [...byPath.get(path)].sort((left, right) => left.promiseId.localeCompare(right.promiseId)),
+    }));
+    return {
+        schemaVersion: TOUCH_MAP_SCHEMA,
+        generatedAt: input.generatedAt,
+        truncated,
+        promises: [...input.covered]
+            .map((promise) => ({
+            promiseId: promise.promiseId,
+            verifierDigest: promise.verifierDigest,
+            files: promise.paths.length,
+        }))
+            .sort((left, right) => left.promiseId.localeCompare(right.promiseId)),
+        files,
+        unmapped: [...input.unmapped].sort((left, right) => left.promiseId.localeCompare(right.promiseId)),
+    };
+}
+/** The document as it is written: two-space JSON with a trailing newline. */
+export function serializeTouchMap(map) {
+    return `${JSON.stringify(map, null, 2)}\n`;
+}
+/** The same document with the timestamp removed, which is what "unchanged" means. */
+export function touchMapBody(map) {
+    const { generatedAt: _ignored, ...rest } = map;
+    return canonicalJson(rest);
+}
+/** The map this checkout holds, or why there is nothing to read. */
+export function readTouchMap(root) {
+    let text;
+    try {
+        text = readFileSync(join(root, TOUCH_MAP_FILE), "utf8");
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { kind: "unreadable" };
+    }
+    if (parsed?.schemaVersion !== TOUCH_MAP_SCHEMA)
+        return { kind: "unreadable" };
+    if (!Array.isArray(parsed.files) || !Array.isArray(parsed.promises))
+        return { kind: "unreadable" };
+    return { kind: "map", map: parsed };
+}
+/**
+ * Which promises a set of paths touches, and which of those answers have aged.
+ *
+ * Staleness is per entry rather than per map. A repository where one verifier
+ * was repaired this morning still has a true answer for every other promise in
+ * it, and marking the whole map stale would throw those away.
+ */
+export function affectedPaths(map, paths, currentDigests, details) {
+    const byPath = new Map(map.files.map((file) => [file.path, file.promises]));
+    return paths.map((path) => {
+        const entries = byPath.get(path) ?? [];
+        return {
+            path,
+            promises: entries.map((entry) => {
+                const current = currentDigests.get(entry.promiseId);
+                const detail = details.get(entry.promiseId);
+                return {
+                    promiseId: entry.promiseId,
+                    // A promise whose package has gone is stale, not current: the map
+                    // still names it and nothing on disk can confirm the answer.
+                    stale: current === undefined || current !== entry.verifierDigest,
+                    ...(detail?.title === undefined ? {} : { title: detail.title }),
+                    ...(detail?.claim === undefined ? {} : { claim: detail.claim }),
+                };
+            }),
+        };
+    });
+}
+/**
+ * The environment a verifier is measured in.
+ *
+ * The same closed allow-list the pinned runner gives a verifier, plus the two
+ * variables this measurement needs: where V8 writes coverage, and where a
+ * native-protocol verifier writes its verdict. It is an allow-list rather than
+ * a subtraction so a control-plane token, a cloud credential, or anything else
+ * this terminal happens to hold cannot reach a customer's verifier because
+ * somebody forgot to name it.
+ */
+export function touchMapEnvironment(environment, coverageDirectory, resultPath) {
+    const allowed = [
+        "PATH",
+        "HOME",
+        "TMPDIR",
+        "TMP",
+        "TEMP",
+        "LANG",
+        "LC_ALL",
+        "LC_CTYPE",
+        "TZ",
+        "SYSTEMROOT",
+    ];
+    const clean = {};
+    for (const key of allowed) {
+        const value = environment[key];
+        if (typeof value === "string" && value.length > 0)
+            clean[key] = value;
+    }
+    clean.NODE_V8_COVERAGE = coverageDirectory;
+    if (resultPath !== undefined)
+        clean.BALLADEER_RESULT_PATH = resultPath;
+    return clean;
+}
+/**
+ * Whether this release can measure a verifier invoked that way.
+ *
+ * Node only, for now. Coverage is collected by the runtime executing the
+ * verifier, so every language needs its own collector, and a command that
+ * guessed would map a Python verifier to nothing and call it an empty answer.
+ * The others are named as unmapped instead, which is a thing a person can read.
+ */
+export function measurableWithNode(target) {
+    if (target.executable === "")
+        return false;
+    const name = target.executable.split(/[\\/]/).pop() ?? "";
+    return name === "node" || name === "node.exe" || target.executable === process.execPath;
+}
+/** The working directory a verifier runs in, or nothing when it leaves the repository. */
+export function verifierCwd(root, target) {
+    const cwd = resolve(root, target.cwd ?? ".");
+    const inside = relative(root, cwd);
+    if (inside !== "" && (inside.startsWith("..") || isAbsolute(inside)))
+        return undefined;
+    return cwd;
+}