baesian 0.0.0-stage → 1.0.1

package/dist/client/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <!-- viewport-fit=cover: a phone with a notch gives the page its whole screen, and style.css keeps clear of the
+         notch with its safe areas. resizes-content: the on-screen keyboard shrinks the page, rather than covering it. -->
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
+    <title>Baesian</title>
+    <script type="module" crossorigin src="/assets/index-Dwg9e0YR.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-9yf70Vqv.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/facts.js

@@ -0,0 +1,278 @@
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { DEFAULT_IGNORE, pathsOf } from "./gate-paths.js";
+import { matcher } from "./globs.js";
+import { onlyBaesianBlock } from "./hookblock.js";
+/**
+ * Ask livedocs for exported-signature changes (D56). Baesian doesn't parse code itself: livedocs
+ * already has tested Python and TypeScript parsers. Without livedocs, the detector warns and is off.
+ */
+export function livedocsSignatures(cwd, args) {
+    try {
+        const out = execFileSync("livedocs", ["signatures", ...args, "--json", "--repo", cwd], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 64 << 20,
+        });
+        return { changes: JSON.parse(out) };
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT") {
+            return { changes: [], warning: "your preferences name public modules (gate_api), but livedocs isn't installed, so API changes weren't checked (uv tool install livedocs)" };
+        }
+        const why = (err.stderr ?? err.message ?? "").toString().trim().split("\n").at(-1);
+        return { changes: [], warning: `livedocs signatures failed, so API changes weren't checked: ${why}` };
+    }
+}
+/** git's empty tree: the "before" side of a repository's first commit. */
+export const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+function gitRaw(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 << 20 });
+}
+function show(cwd, spec) {
+    try {
+        return gitRaw(cwd, ["show", spec]);
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasRev(cwd, rev) {
+    try {
+        gitRaw(cwd, ["rev-parse", "--verify", "-q", `${rev}^{commit}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseNameStatus(z) {
+    const parts = z.split("\0").filter((p) => p !== "");
+    const out = [];
+    for (let i = 0; i < parts.length;) {
+        const status = parts[i++];
+        if (status.startsWith("R") || status.startsWith("C")) {
+            const oldPath = parts[i++];
+            out.push({ status: status[0], path: parts[i++], oldPath });
+        }
+        else {
+            out.push({ status: status[0], path: parts[i++] });
+        }
+    }
+    return out;
+}
+/** What `git commit` is about to record: the index against HEAD (or the empty tree). */
+export function stagedSnapshot(cwd) {
+    const head = hasRev(cwd, "HEAD");
+    const base = head ? "HEAD" : EMPTY_TREE;
+    return {
+        changes: () => parseNameStatus(gitRaw(cwd, ["diff", "--cached", "--name-status", "-M", "-z", base])),
+        before: (path) => (head ? show(cwd, `HEAD:${path}`) : undefined),
+        after: (path) => show(cwd, `:${path}`),
+        apiChanges: () => livedocsSignatures(cwd, ["--cached"]),
+    };
+}
+/** One commit against its first parent, for CI (M3b). */
+export function commitSnapshot(cwd, commit) {
+    const parent = hasRev(cwd, `${commit}^`) ? `${commit}^` : undefined;
+    return {
+        changes: () => parseNameStatus(gitRaw(cwd, ["diff", "--name-status", "-M", "-z", parent ?? EMPTY_TREE, commit])),
+        before: (path) => (parent ? show(cwd, `${parent}:${path}`) : undefined),
+        after: (path) => show(cwd, `${commit}:${path}`),
+        apiChanges: () => livedocsSignatures(cwd, ["--rev", commit]),
+    };
+}
+export { DEFAULT_IGNORE, DEFAULT_INFRA, DEFAULT_SCHEMA } from "./gate-paths.js";
+/** Breaking changes only (D58): a new export is additive, so it's a two-way door. */
+const BREAKING = new Set(["signature", "removed"]);
+function shorten(text, max = 90) {
+    const one = text.replace(/\s+/g, " ").trim();
+    return one.length > max ? `${one.slice(0, max - 1)}…` : one;
+}
+// ---------------------------------------------------------------- dependencies (D55)
+/** PEP 503 normalisation, so `Pydantic_Core` and `pydantic-core` are the same package. */
+export function normalisePython(name) {
+    return name.toLowerCase().replace(/[-_.]+/g, "-");
+}
+/** The name at the start of a PEP 508 requirement: `httpx[http2]>=0.27; python_version>"3.8"` → `httpx`. */
+export function requirementName(req) {
+    const m = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(req);
+    return m ? normalisePython(m[1]) : undefined;
+}
+const NODE_RUNTIME = ["dependencies", "peerDependencies", "optionalDependencies"];
+function nodeDeps(text) {
+    const pkg = JSON.parse(text);
+    const names = new Set();
+    for (const section of NODE_RUNTIME) {
+        const deps = pkg[section];
+        if (deps && typeof deps === "object")
+            for (const n of Object.keys(deps))
+                names.add(n);
+    }
+    return names;
+}
+function pythonProjectDeps(text) {
+    const doc = parseToml(text);
+    const names = new Set();
+    const add = (req) => {
+        const n = typeof req === "string" ? requirementName(req) : undefined;
+        if (n)
+            names.add(n);
+    };
+    const project = doc.project ?? {};
+    for (const req of project.dependencies ?? [])
+        add(req);
+    for (const extra of Object.values(project["optional-dependencies"] ?? {})) {
+        for (const req of extra ?? [])
+            add(req);
+    }
+    // Poetry's main group is runtime; its other groups (and PEP 735 dependency-groups) are dev (D55).
+    for (const name of Object.keys(doc.tool?.poetry?.dependencies ?? {})) {
+        if (name.toLowerCase() !== "python")
+            names.add(normalisePython(name));
+    }
+    return names;
+}
+function requirementsDeps(text) {
+    const names = new Set();
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.replace(/(^|\s)#.*$/, "").trim();
+        if (!line || line.startsWith("-"))
+            continue; // options, -r includes, -e editables
+        const n = requirementName(line);
+        if (n)
+            names.add(n);
+    }
+    return names;
+}
+function manifestParser(path) {
+    const name = basename(path);
+    if (name === "package.json")
+        return nodeDeps;
+    if (name === "pyproject.toml")
+        return pythonProjectDeps;
+    if (/^requirements.*\.txt$/.test(name) && !/(dev|test|lint|doc)/i.test(name))
+        return requirementsDeps;
+    return undefined;
+}
+function dependencyFacts(snap, change, warnings) {
+    const parse = manifestParser(change.path);
+    if (!parse)
+        return [];
+    const read = (text, side) => {
+        if (text === undefined)
+            return new Set();
+        try {
+            return parse(text);
+        }
+        catch {
+            warnings.push(`couldn't parse the ${side} version of ${change.path}; its dependencies weren't checked`);
+            return undefined;
+        }
+    };
+    const before = read(change.status === "A" ? undefined : snap.before(change.oldPath ?? change.path), "old");
+    const after = read(change.status === "D" ? undefined : snap.after(change.path), "new");
+    if (!before || !after)
+        return [];
+    const facts = [];
+    for (const n of after) {
+        if (!before.has(n))
+            facts.push({ id: `dep:${n}`, kind: "dep", path: change.path, detail: `added to ${change.path}` });
+    }
+    for (const n of before) {
+        if (!after.has(n))
+            facts.push({ id: `dep:${n}`, kind: "dep", path: change.path, detail: `removed from ${change.path}` });
+    }
+    return facts;
+}
+// ---------------------------------------------------------------- the repo's link to the service (B-w4g6c)
+/** The committed config, where a repo names the service and project it syncs with (P16 section 8). */
+export const CONFIG_PATH = ".baesian/config.json";
+/** What ties a repo to a project on the service: where its cards go (B-w4g6c), and which history is the repo's (B-5gnea). */
+const LINK_FIELDS = ["service", "project", "first_commit"];
+/**
+ * Changing where a repo's cards are sent is a gate fact, like a CI file (B-w4g6c): `infra:.baesian/config.json` when a
+ * commit changes the config's service, project or first commit, linking the repo first included. The rest of
+ * `.baesian/` stays out of the gate's sight (`DEFAULT_IGNORE`), and so does the rest of the config: what the gate looks
+ * at is no longer there, but in the preference files, which a commit can't make count (B-qkek1).
+ */
+function linkFact(snap, change, warnings) {
+    if (change.path !== CONFIG_PATH && change.oldPath !== CONFIG_PATH)
+        return undefined;
+    const read = (text, side) => {
+        if (text === undefined)
+            return {};
+        try {
+            const v = JSON.parse(text);
+            return typeof v === "object" && v !== null && !Array.isArray(v) ? v : {};
+        }
+        catch {
+            warnings.push(`couldn't parse the ${side} version of ${CONFIG_PATH}; whether it changes the repo's service or project wasn't checked`);
+            return undefined;
+        }
+    };
+    // Renamed onto the config's path, it had no config before; renamed away, it has none after.
+    const wasThere = change.status !== "A" && (change.oldPath === undefined || change.oldPath === CONFIG_PATH);
+    const before = read(wasThere ? snap.before(CONFIG_PATH) : undefined, "old");
+    const after = read(change.path === CONFIG_PATH && change.status !== "D" ? snap.after(CONFIG_PATH) : undefined, "new");
+    if (!before || !after)
+        return undefined;
+    const moved = LINK_FIELDS.filter((k) => before[k] !== after[k]);
+    if (!moved.length)
+        return undefined;
+    const detail = after.project === undefined ? `unlinked the repo from ${String(before.service)} (project ${String(before.project)})` : before.project === undefined ? `linked the repo to ${String(after.service)} as project ${String(after.project)}` : `changed the repo's ${moved.join(", ")} in ${CONFIG_PATH}`;
+    return { id: `infra:${CONFIG_PATH}`, kind: "infra", path: CONFIG_PATH, detail };
+}
+// ---------------------------------------------------------------- detection
+const VERB = { A: "added", M: "changed", D: "deleted", R: "renamed", C: "copied", T: "changed" };
+export function detectFacts(snap, opts = {}) {
+    const ignored = matcher([...DEFAULT_IGNORE, ...pathsOf(opts, "ignore")]);
+    const isSchema = matcher(pathsOf(opts, "schema"));
+    const isInfra = matcher(pathsOf(opts, "infra"));
+    const warnings = [];
+    const facts = new Map();
+    const add = (f) => {
+        if (!facts.has(f.id))
+            facts.set(f.id, f);
+    };
+    for (const change of snap.changes()) {
+        // Checked before what's ignored: `.baesian/` is, and a repo's own ignores mustn't hide where its cards go (B-w4g6c).
+        const link = linkFact(snap, change, warnings);
+        if (link)
+            add(link);
+        if (ignored(change.path))
+            continue;
+        const verb = VERB[change.status] ?? "changed";
+        const what = change.oldPath ? `${verb} ${change.oldPath} → ${change.path}` : `${verb} ${change.path}`;
+        // A rename counts if either end is in scope: moving a migration out of migrations/ is a decision too.
+        const either = (test) => test(change.path) || (change.oldPath !== undefined && test(change.oldPath));
+        for (const f of dependencyFacts(snap, change, warnings))
+            add(f);
+        if (either(isSchema))
+            add({ id: `schema:${change.path}`, kind: "schema", path: change.path, detail: what });
+        // Baesian's own block, as `baesian init` writes it, isn't a decision anyone made (B-g6ywj); any other hook change is.
+        const ownBlock = (change.status === "A" || change.status === "M") && onlyBaesianBlock(change.path, snap.before(change.path), snap.after(change.path));
+        if (either(isInfra) && !ownBlock)
+            add({ id: `infra:${change.path}`, kind: "infra", path: change.path, detail: what });
+    }
+    const api = pathsOf(opts, "api");
+    if (api.length && snap.apiChanges) {
+        const isApi = matcher(api);
+        const result = snap.apiChanges();
+        if (result.warning)
+            warnings.push(result.warning);
+        for (const c of result.changes) {
+            if (!BREAKING.has(c.kind) || !isApi(c.path) || ignored(c.path))
+                continue;
+            const detail = c.kind === "removed"
+                ? `removed from ${c.path}`
+                : `signature changed in ${c.path}${c.now ? `: ${shorten(c.now)}` : ""}`;
+            add({ id: `api:${c.qualname}`, kind: "api", path: c.path, detail });
+        }
+    }
+    return { facts: [...facts.values()].sort((a, b) => a.id.localeCompare(b.id)), warnings };
+}
+//# sourceMappingURL=facts.js.map

package/dist/folder-storage.js

@@ -0,0 +1,71 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomSuffix } from "./ids.js";
+import { checkPath } from "./storage.js";
+/** A write in progress: a temporary file beside the one it becomes. Never listed. */
+const isTemp = (name) => name.endsWith(".tmp");
+/**
+ * The live layer as a folder on your machine (B-0ag7h): `.git/baesian/`, shared by every worktree of a clone (D34), or a
+ * commit's record read as a layer in CI. A write goes to a temporary file first, so no other process reads half a file.
+ */
+export class FolderStorage {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** The file or folder at a layer path. */
+    at(path) {
+        return checkPath(path, true) === "" ? this.dir : join(this.dir, ...path.split("/"));
+    }
+    read(path) {
+        try {
+            return readFileSync(this.at(path));
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                return undefined;
+            throw e;
+        }
+    }
+    list(dir) {
+        const at = this.at(dir);
+        return existsSync(at) ? readdirSync(at).filter((f) => !isTemp(f)) : [];
+    }
+    /**
+     * Written whole to a temporary file first, then linked into place, which fails if the name is taken: so another process
+     * never reads it half-written. An exclusive create alone made the file visible empty for a moment, which the server's
+     * four-writer test caught once the gate made filing read more of the layer. Where hard links aren't supported, it falls
+     * back to the exclusive create.
+     */
+    create(path, bytes) {
+        const at = this.at(path);
+        mkdirSync(dirname(at), { recursive: true });
+        const tmp = `${at}.${randomSuffix()}.tmp`;
+        writeFileSync(tmp, bytes, { flag: "wx" });
+        try {
+            linkSync(tmp, at);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EPERM" && code !== "ENOTSUP" && code !== "EXDEV" && code !== "ENOSYS")
+                throw e;
+            writeFileSync(at, bytes, { flag: "wx" });
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+    }
+    /** Written to a temporary file and renamed over the old one, which is atomic on one file system. */
+    replace(path, bytes) {
+        const at = this.at(path);
+        mkdirSync(dirname(at), { recursive: true });
+        const tmp = `${at}.${randomSuffix()}.tmp`;
+        writeFileSync(tmp, bytes);
+        renameSync(tmp, at);
+    }
+    remove(path) {
+        rmSync(this.at(path), { force: true });
+    }
+}
+//# sourceMappingURL=folder-storage.js.map

package/dist/frontmatter.js

@@ -0,0 +1,38 @@
+import { parse, stringify } from "yaml";
+const FENCED = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)([\s\S]*)$/;
+/** Split a Markdown file into its YAML frontmatter and body. Frontmatter must be flat (vault convention). */
+export function parseDoc(text) {
+    const m = FENCED.exec(text);
+    if (!m)
+        throw new Error("missing frontmatter: the file must start with a --- block");
+    const meta = parse(m[1] ?? "") ?? {};
+    if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
+        throw new Error("frontmatter must be a mapping of keys to values");
+    }
+    for (const [key, value] of Object.entries(meta)) {
+        const nested = Array.isArray(value)
+            ? value.some((item) => typeof item === "object" && item !== null)
+            : typeof value === "object" && value !== null;
+        if (nested)
+            throw new Error(`frontmatter must be flat: "${key}" holds a nested object`);
+    }
+    return { meta: meta, body: m[2] ?? "" };
+}
+/** Render frontmatter and body back into a Markdown file. Undefined values and empty lists are left out. */
+export function renderDoc(meta, body) {
+    const clean = Object.fromEntries(Object.entries(meta).filter(([, v]) => v !== undefined && !(Array.isArray(v) && v.length === 0)));
+    const yaml = stringify(clean, { lineWidth: 0 }).trimEnd();
+    const text = body.replace(/^\n+/, "");
+    return `---\n${yaml}\n---\n\n${text}${text.endsWith("\n") ? "" : "\n"}`;
+}
+/** The text under a `## Heading` in a Markdown body, up to the next heading of the same or higher level. */
+export function section(body, heading) {
+    const lines = body.split(/\r?\n/);
+    const start = lines.findIndex((l) => l.replace(/\s+$/, "") === `## ${heading}`);
+    if (start < 0)
+        return undefined;
+    const rest = lines.slice(start + 1);
+    const end = rest.findIndex((l) => /^#{1,2}\s/.test(l));
+    return (end < 0 ? rest : rest.slice(0, end)).join("\n").trim();
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/gate-paths.js

@@ -0,0 +1,77 @@
+import { uncovered } from "./globs.js";
+// What the commit gate looks at (D25, D59), and who changes it (B-qkek1): the globs its schema and infra detectors match,
+// the public modules that turn on its api: detector, and the paths it never looks at. The built-in lists are here; a
+// repo changes them only in its preference files, which only the client writes, never in the committed config. A change
+// that makes the gate see less is loosening (D163), told by comparing the globs (`pathsLoosening()`). Pure, with no
+// Node, so the CLI, CI, the relay and the client all read it alike.
+export const DEFAULT_SCHEMA = [
+    "**/migrations/**",
+    "**/*.sql",
+    "**/schema.prisma",
+    "**/*.schema.json",
+    "**/schema.graphql",
+    // A TypeScript schema module: Drizzle's and Convex's are named so, as are Zod schemas for files on disk, like Baesian's own.
+    "**/schema.ts",
+];
+export const DEFAULT_INFRA = [
+    ".github/workflows/**",
+    // Git hooks that are committed run on everyone's machine: changing one is an infra decision (D135).
+    ".githooks/**",
+    ".husky/**",
+    ".gitlab-ci.yml",
+    "**/Dockerfile",
+    "**/Dockerfile.*",
+    "**/docker-compose*.yml",
+    "**/docker-compose*.yaml",
+    "**/compose.yml",
+    "**/compose.yaml",
+    "**/*.tf",
+    "**/wrangler.toml",
+    "**/wrangler.json",
+    "**/wrangler.jsonc",
+    "**/fly.toml",
+    "**/vercel.json",
+    "**/netlify.toml",
+];
+/** Never looked at, whatever a repo sets: a repo's own ignores are added to these. */
+export const DEFAULT_IGNORE = ["**/node_modules/**", ".baesian/**", "**/vendor/**", "**/__fixtures__/**"];
+export const PATH_KINDS = ["schema", "infra", "api", "ignore"];
+/** Each kind's key in a preference file. */
+export const PATH_KEYS = { schema: "gate_schema", infra: "gate_infra", api: "gate_api", ignore: "gate_ignore" };
+/** The built-in list each kind starts from. A repo's ignores are added to `DEFAULT_IGNORE`, which is always applied. */
+const BUILT_IN = { schema: DEFAULT_SCHEMA, infra: DEFAULT_INFRA, api: [], ignore: [] };
+/** The list the gate applies for a kind: the setting's, or the built-in one. For `ignore`, the repo's own, beside `DEFAULT_IGNORE`. */
+export function pathsOf(paths, kind) {
+    return paths[kind] ?? BUILT_IN[kind];
+}
+/**
+ * A list as a preference file keeps it (B-qkek1): trimmed, without blanks or repeats; and left out when it's the built-in
+ * one, in any order, so a file that keeps the defaults means them, whatever later defaults are. An empty schema or infra
+ * list is kept: the gate looks for none.
+ */
+export function pathSetting(kind, list) {
+    const globs = [...new Set(list.map((g) => g.trim()).filter(Boolean))];
+    const built = BUILT_IN[kind];
+    if (globs.length === built.length && built.every((g) => globs.includes(g)))
+        return undefined;
+    return globs;
+}
+/**
+ * What a change to the gate's paths loosens (D163, B-qkek1): a schema, infra or API list that no longer covers every
+ * path the old one did, and paths ignored that weren't before. Told by comparing the globs (`uncovered()`), exactly; a
+ * glob it can't tell about counts as loosening. Each makes the gate see less, so in a hosted repo it takes the passkey.
+ */
+export function pathsLoosening(before, after) {
+    const out = [];
+    const list = (globs) => globs.map((g) => `"${g}"`).join(", ");
+    for (const kind of ["schema", "infra", "api"]) {
+        const lost = uncovered(pathsOf(after, kind), pathsOf(before, kind));
+        if (lost.length)
+            out.push(`it narrows ${PATH_KEYS[kind]}, which no longer covers ${list(lost)}`);
+    }
+    const more = uncovered([...DEFAULT_IGNORE, ...pathsOf(before, "ignore")], pathsOf(after, "ignore"));
+    if (more.length)
+        out.push(`it widens ${PATH_KEYS.ignore} to ${list(more)}`);
+    return out;
+}
+//# sourceMappingURL=gate-paths.js.map