builder-assistant-engineer 0.2.0

package/dist/gates/contract.js

@@ -0,0 +1,339 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { UserError } from "../core/errors.js";
+import { readTextIfExists, writeText } from "../core/fs.js";
+import { gitPaths, isGitRepo } from "../core/git.js";
+import { BAE_IGNORED } from "../core/gitignore.js";
+import { asRecord, parseObject } from "../core/json.js";
+import { scanFiles } from "../digest/walk.js";
+import { t } from "../i18n/index.js";
+import { inScope } from "../review/scope.js";
+import { ignoreMatcher, untrackedFiles } from "./ignore-rules.js";
+import { AGENT_FILES, BAE_SCRATCH, createdIsViolation, executedBy, GIT_FILES, isRunnerConfig, kindOf, repoProtected, sectionsOf, setupReferences, shadowCandidates, WATCHED_DIRS, } from "./protected-files.js";
+export { isAcceptableKind, TASKS_DIR } from "./protected-files.js";
+const LOG_HEADING = /^##[ \t]+(log|registro|bitácora|bitacora)[ \t]*$/i;
+const SECTION_HEADING = /^##(?!#)/;
+const FRONTMATTER = /^---\n([\s\S]*?)\n---[ \t]*(?:\n|$)/;
+const MAX_PROTECTED_CHARS = 1_000_000;
+const PACKAGE_KEYS = ["jest", "mocha", "ava", "eslintConfig", "prettier", "babel", "c8", "nyc"];
+const ROOT_TOOLCHAIN = [
+    ".npmrc",
+    ".yarnrc",
+    ".yarnrc.yml",
+    ".envrc",
+    "bunfig.toml",
+    ".pnpmfile.cjs",
+];
+export async function collectProtected(cwd, inputs = { suite: [], verification: [], own: [] }) {
+    const listing = await repoFiles(cwd);
+    const scripts = asRecord(parseObject((await readTextIfExists(absolute(cwd, "package.json"))) ?? "")?.scripts);
+    const suite = executedBy(inputs.suite, scripts);
+    const verification = executedBy(inputs.verification, scripts);
+    const own = (path) => inScope(path, inputs.own);
+    const candidates = [
+        ...(await watchedFiles(cwd)),
+        ...listing.filter(repoProtected),
+        ...suite.files,
+        ...verification.files.filter((path) => !own(path)),
+        ...(await rootToolchain(cwd)),
+        ...(await gitFiles(cwd)),
+    ];
+    const result = {};
+    for (const path of [...new Set(candidates)].sort()) {
+        const text = await readTextIfExists(absolute(cwd, path)).catch(() => undefined);
+        if (text === undefined || text.length > MAX_PROTECTED_CHARS || !tracked(path, text))
+            continue;
+        if (path === ".gitignore" && onlyBaeEntries(text))
+            continue;
+        result[path] = text;
+        if (!isRunnerConfig(path))
+            continue;
+        for (const reference of setupReferences(path, text)) {
+            const setup = await readTextIfExists(absolute(cwd, reference)).catch(() => undefined);
+            if (setup !== undefined && setup.length <= MAX_PROTECTED_CHARS)
+                result[reference] = setup;
+        }
+    }
+    const existing = new Set(listing);
+    const shadows = shadowCandidates({
+        files: [],
+        modules: [...suite.modules, ...verification.modules],
+        make: suite.make || verification.make,
+    }).filter((entry) => entry.endsWith("/")
+        ? !listing.some((path) => path.startsWith(entry))
+        : !existing.has(entry) && !Object.hasOwn(result, entry));
+    return { protected: result, shadows };
+}
+export async function checkContract(cwd, state) {
+    const captured = state.protected;
+    const changes = [];
+    for (const [path, before] of Object.entries(captured)) {
+        const linked = (await lstat(absolute(cwd, path)).catch(() => undefined))?.isSymbolicLink();
+        const after = linked
+            ? undefined
+            : await readTextIfExists(absolute(cwd, path)).catch(() => undefined);
+        const change = compare(path, kindOf(path, state.taskPath), before, after);
+        if (change)
+            changes.push({ ...change, fingerprint: fingerprint(after) });
+    }
+    const created = (path, kind) => ({
+        path,
+        kind,
+        change: "created",
+        detail: "",
+        restored: null,
+        fingerprint: fingerprint(path),
+    });
+    for (const path of await watchedFiles(cwd)) {
+        if (!Object.hasOwn(captured, path))
+            changes.push(created(path, kindOf(path, state.taskPath)));
+    }
+    for (const path of await gitFiles(cwd)) {
+        if (Object.hasOwn(captured, path))
+            continue;
+        if ((await readTextIfExists(absolute(cwd, path)).catch(() => undefined)) !== undefined) {
+            changes.push(created(path, "gitdir"));
+        }
+    }
+    const reported = new Set(changes.map((change) => change.path));
+    for (const path of await currentFiles(cwd, state.ignore)) {
+        if (reported.has(path) || Object.hasOwn(captured, path))
+            continue;
+        if (state.shadows.some((entry) => (entry.endsWith("/") ? path.startsWith(entry) : path === entry))) {
+            changes.push(created(path, "shadow"));
+        }
+        else if (createdIsViolation(path)) {
+            changes.push(created(path, kindOf(path, state.taskPath)));
+        }
+    }
+    return changes;
+}
+export async function restoreContract(cwd, changes) {
+    const failed = [];
+    for (const change of changes) {
+        const target = absolute(cwd, change.path);
+        try {
+            await rm(target, { force: true, recursive: true });
+            if (change.restored !== null)
+                await writeText(target, change.restored);
+        }
+        catch {
+            failed.push(change.path);
+        }
+    }
+    if (failed.length > 0)
+        throw new UserError(t("contract.restoreFailed", { files: failed.join(", ") }));
+}
+export function taskContract(text) {
+    const unix = text.replace(/\r\n/g, "\n");
+    const match = FRONTMATTER.exec(unix);
+    const lines = (match?.[1] ?? "").split("\n");
+    const status = lines.findIndex((line) => /^status[ \t]*:/.test(line));
+    const front = lines.filter((_, index) => index !== status).join("\n");
+    const body = match ? unix.slice(match[0].length) : unix;
+    return `${front}\n---\n${splitLog(body).kept.join("\n")}`.replace(/\s+$/, "");
+}
+export function spliceLog(captured, current) {
+    const log = splitLog(current.replace(/\r\n/g, "\n")).log;
+    const output = [];
+    let inLog = false;
+    let inserted = false;
+    let fenced = false;
+    for (const line of captured.replace(/\r\n/g, "\n").split("\n")) {
+        if (!fenced && SECTION_HEADING.test(line))
+            inLog = LOG_HEADING.test(line.trimEnd());
+        if (/^\s*(```|~~~)/.test(line))
+            fenced = !fenced;
+        if (!inLog) {
+            output.push(line);
+            continue;
+        }
+        if (!inserted)
+            output.push(...log);
+        inserted = true;
+    }
+    if (!inserted && log.length > 0)
+        output.push("", ...log);
+    return output.join("\n");
+}
+function splitLog(body) {
+    const kept = [];
+    const log = [];
+    let inLog = false;
+    let fenced = false;
+    for (const line of body.split("\n")) {
+        if (!fenced && SECTION_HEADING.test(line))
+            inLog = LOG_HEADING.test(line.trimEnd());
+        if (/^\s*(```|~~~)/.test(line))
+            fenced = !fenced;
+        (inLog ? log : kept).push(line);
+    }
+    return { kept, log };
+}
+export function withoutLog(text) {
+    return splitLog(unix(text)).kept.join("\n").trimEnd();
+}
+function compare(path, kind, before, after) {
+    const base = { path, kind, detail: "" };
+    if (after === undefined)
+        return { ...base, change: "deleted", restored: before };
+    if (kind === "task") {
+        if (taskContract(before) === taskContract(after))
+            return undefined;
+        return { ...base, change: "modified", restored: spliceLog(before, after) };
+    }
+    if (kind === "scripts") {
+        const keys = packageChanges(before, after);
+        if (keys.length === 0)
+            return undefined;
+        const detail = keys.join(", ");
+        return { ...base, detail, change: "modified", restored: restorePackage(before, after) };
+    }
+    const headers = sectionsOf(path);
+    if (kind === "runner" && headers) {
+        const changed = headers.filter((header) => (sectionOf(after, header) ?? "") !== (sectionOf(before, header) ?? ""));
+        if (changed.length === 0)
+            return undefined;
+        const restored = changed.reduce((text, header) => replaceSection(text, header, sectionOf(before, header) ?? ""), after);
+        return { ...base, detail: changed.join(", "), change: "modified", restored };
+    }
+    if (unix(before) === unix(after))
+        return undefined;
+    return { ...base, change: "modified", restored: before };
+}
+function packageChanges(before, after) {
+    const previous = parseObject(before) ?? {};
+    const current = parseObject(after);
+    if (!current)
+        return ["package.json"];
+    const scripts = asRecord(previous.scripts);
+    const now = asRecord(current.scripts);
+    const hooks = Object.keys(now).filter((key) => !(key in scripts) && /^(pre|post)./.test(key) && key.replace(/^(pre|post)/, "") in scripts);
+    return [
+        ...Object.keys(scripts)
+            .filter((key) => now[key] !== scripts[key])
+            .map((key) => `scripts.${key}`),
+        ...hooks.map((key) => `scripts.${key}`),
+        ...PACKAGE_KEYS.filter((key) => key in previous && JSON.stringify(current[key]) !== JSON.stringify(previous[key])),
+    ];
+}
+function restorePackage(before, after) {
+    const previous = parseObject(before) ?? {};
+    const current = parseObject(after);
+    if (!current)
+        return before;
+    const restored = { ...current };
+    if (previous.scripts !== undefined) {
+        const scripts = asRecord(previous.scripts);
+        const kept = Object.entries(asRecord(current.scripts)).filter(([key]) => !(/^(pre|post)./.test(key) && key.replace(/^(pre|post)/, "") in scripts));
+        restored.scripts = { ...Object.fromEntries(kept), ...scripts };
+    }
+    for (const key of PACKAGE_KEYS.filter((name) => name in previous))
+        restored[key] = previous[key];
+    const indent = /\n([ \t]+)"/.exec(after)?.[1] ?? "  ";
+    return `${JSON.stringify(restored, null, indent)}${after.endsWith("\n") ? "\n" : ""}`;
+}
+function sectionOf(text, prefix) {
+    const tables = tablesOf(text).filter((table) => matchesTable(table.name, prefix));
+    if (tables.length === 0)
+        return undefined;
+    return tables.map((table) => table.lines.join("\n").trimEnd()).join("\n\n");
+}
+function replaceSection(text, prefix, section) {
+    const kept = tablesOf(text)
+        .filter((table) => !matchesTable(table.name, prefix))
+        .map((table) => table.lines.join("\n").trimEnd())
+        .filter((block) => block !== "");
+    return `${[...kept, ...(section ? [section] : [])].join("\n\n")}\n`;
+}
+function tablesOf(text) {
+    const tables = [{ name: "", lines: [] }];
+    for (const line of unix(text).split("\n")) {
+        const header = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(?:[#;].*)?$/.exec(line)?.[1];
+        if (header !== undefined)
+            tables.push({ name: header.trim(), lines: [] });
+        tables.at(-1)?.lines.push(line);
+    }
+    return tables;
+}
+function matchesTable(name, prefix) {
+    return (name === prefix || [".", "-", ":"].some((separator) => name.startsWith(`${prefix}${separator}`)));
+}
+async function walk(cwd, dir) {
+    if (BAE_SCRATCH.some((prefix) => `${dir}/`.startsWith(prefix)))
+        return [];
+    const entries = await listDir(absolute(cwd, dir));
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = `${dir}/${entry.name}`;
+        if (entry.isDirectory())
+            return walk(cwd, path);
+        return entry.isFile() || entry.isSymbolicLink() ? [path] : [];
+    }));
+    return nested.flat();
+}
+async function listDir(path) {
+    try {
+        return await readdir(path, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function absolute(cwd, path) {
+    return join(cwd, ...path.split("/"));
+}
+function fingerprint(text) {
+    return createHash("sha1")
+        .update(text ?? "deleted")
+        .digest("hex")
+        .slice(0, 12);
+}
+function unix(text) {
+    return text.replace(/\r\n/g, "\n");
+}
+function onlyBaeEntries(text) {
+    const lines = unix(text)
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return lines.every((line) => BAE_IGNORED.includes(line));
+}
+function tracked(path, text) {
+    const headers = sectionsOf(path);
+    return headers === undefined || headers.some((header) => sectionOf(text, header) !== undefined);
+}
+async function watchedFiles(cwd) {
+    const files = (await Promise.all(WATCHED_DIRS.map((dir) => walk(cwd, dir)))).flat();
+    const agents = await Promise.all(AGENT_FILES.map(async (path) => (await readTextIfExists(absolute(cwd, path)).catch(() => undefined)) === undefined
+        ? []
+        : [path]));
+    return [...files, ...agents.flat()].filter((path) => !BAE_SCRATCH.some((prefix) => path.startsWith(prefix)));
+}
+async function gitFiles(cwd) {
+    const info = await stat(join(cwd, ".git")).catch(() => undefined);
+    return info?.isDirectory() ? GIT_FILES.map((name) => `.git/${name}`) : [];
+}
+async function repoFiles(cwd) {
+    if (await isGitRepo(cwd)) {
+        return (await gitPaths(cwd, ["ls-files", "--cached", "--others", "--exclude-standard"])) ?? [];
+    }
+    return (await scanFiles(cwd)).files.map((file) => file.path);
+}
+async function currentFiles(cwd, ignore) {
+    const scanned = async () => (await scanFiles(cwd)).files.map((file) => file.path);
+    const root = await rootToolchain(cwd);
+    if (!(await isGitRepo(cwd)))
+        return [...(await scanned()), ...root];
+    const [tracked, untracked] = await Promise.all([
+        gitPaths(cwd, ["ls-files", "--cached"]),
+        untrackedFiles(cwd, ignoreMatcher(ignore)),
+    ]);
+    if (!tracked || !untracked)
+        return [...(await scanned()), ...root];
+    return [...new Set([...tracked, ...untracked, ...root])];
+}
+async function rootToolchain(cwd) {
+    const found = await Promise.all(ROOT_TOOLCHAIN.map(async (name) => (await lstat(absolute(cwd, name)).catch(() => undefined)) ? [name] : []));
+    return found.flat();
+}

package/dist/gates/enforce.js

@@ -0,0 +1,143 @@
+import { join } from "node:path";
+import { readTextIfExists } from "../core/fs.js";
+import { flaggedFiles, git } from "../core/git.js";
+import { asRecord, parseObject } from "../core/json.js";
+import { t } from "../i18n/index.js";
+import { capturedTask, formatFindings } from "../review/run.js";
+import { inScope, scopePaths } from "../review/scope.js";
+import { exclusionKeys } from "../review/tests.js";
+import { checkContract, isAcceptableKind, restoreContract, } from "./contract.js";
+import { accept, findingId } from "./findings.js";
+import { runnerHint } from "./results.js";
+import { expandCommand, TEST_RUNNERS } from "./runners.js";
+const MESSAGES = {
+    task: "contract.task",
+    tasks: "contract.tasks",
+    bae: "contract.bae",
+    agents: "contract.agents",
+    gitignore: "contract.gitignore",
+    scripts: "contract.scripts",
+    runner: "contract.runner",
+    memory: "contract.memory",
+    git: "contract.git",
+    gitdir: "contract.gitdir",
+    toolchain: "contract.toolchain",
+    shadow: "contract.shadow",
+};
+const RUNNER_KEYS = ["jest", "mocha", "ava", "vitest"];
+const RISKY_SETTINGS = [
+    /^\s*(script-shell|shell|node-options|ignore-scripts|yarnPath|preload)\s*[=:]/m,
+    /^\s*\[test\]/m,
+    /^\s*plugins\s*:/m,
+];
+export async function enforceContract(ctx, capture, acceptance) {
+    const changes = await checkContract(ctx.cwd, {
+        protected: capture.protected,
+        shadows: capture.shadows,
+        ignore: capture.ignore,
+        taskPath: capture.path,
+    });
+    const flags = await newIndexFlags(ctx.cwd, capture);
+    if (changes.length === 0 && flags.length === 0)
+        return { blocked: false, report: "", notes: [] };
+    const scope = scopePaths(capturedTask(capture));
+    const findings = await Promise.all(changes.map(async (change) => {
+        const listed = acceptable(change, scope);
+        const finding = contractFinding(change);
+        if (!listed) {
+            return settled(change, accept(acceptance, finding, listed));
+        }
+        const after = await readTextIfExists(join(ctx.cwd, ...change.path.split("/")));
+        const weaker = weakening(change.kind, capture.protected[change.path] ?? "", after);
+        if (!weaker) {
+            return {
+                ...finding,
+                severity: "major",
+                message: `${finding.message} ${t("contract.scoped")}`,
+            };
+        }
+        return settled(change, accept(acceptance, { ...finding, message: `${finding.message} ${weaker}` }, true));
+    }));
+    const restore = changes.filter((_, index) => findings[index]?.severity === "blocker");
+    await restoreContract(ctx.cwd, restore);
+    if (flags.length > 0) {
+        await git(ctx.cwd, [
+            "update-index",
+            "--no-assume-unchanged",
+            "--no-skip-worktree",
+            "--",
+            ...flags,
+        ]);
+        findings.push({
+            severity: "blocker",
+            id: findingId("contract", "index", flags.join(",")),
+            message: t("contract.indexFlags", { files: flags.join(", ") }),
+        });
+    }
+    const blocked = restore.length > 0 || flags.length > 0;
+    const list = formatFindings(findings);
+    if (blocked)
+        ctx.prompter.warn(t("contract.failed"));
+    ctx.prompter.note(list, t("contract.title"));
+    return {
+        blocked,
+        report: `## ${t("contract.title")}\n\n${list}`,
+        notes: findings.filter((finding) => finding.severity === "major"),
+    };
+}
+function weakening(kind, before, after) {
+    if (kind === "toolchain") {
+        const keys = RISKY_SETTINGS.filter((pattern) => pattern.test(after ?? "") && !pattern.test(before));
+        return keys.length > 0 ? t("contract.weakerToolchain") : undefined;
+    }
+    if (kind !== "scripts" && kind !== "runner")
+        return undefined;
+    const added = (text, previous) => exclusionKeys(text).filter((key) => !exclusionKeys(previous).includes(key));
+    if (kind === "runner") {
+        const keys = added(after ?? "", before);
+        return keys.length > 0 ? t("contract.weakerRunner", { keys: keys.join(", ") }) : undefined;
+    }
+    const old = parseObject(before) ?? {};
+    const now = parseObject(after ?? "") ?? {};
+    const scripts = asRecord(old.scripts);
+    const current = asRecord(now.scripts);
+    const dropped = Object.keys(scripts).flatMap((name) => {
+        if (typeof scripts[name] !== "string")
+            return [];
+        if (typeof current[name] !== "string")
+            return [`scripts.${name}`];
+        const tools = (map) => runnerHint(expandCommand(`npm run ${name}`, { scripts: map }));
+        const now = tools(current);
+        const tests = now.some((tool) => TEST_RUNNERS.has(tool));
+        const lost = tools(scripts).filter((tool) => !now.includes(tool) && !(tests && TEST_RUNNERS.has(tool)));
+        return lost.length > 0 ? [`scripts.${name} (${lost.join(", ")})`] : [];
+    });
+    const keys = RUNNER_KEYS.filter((key) => key in old).flatMap((key) => added(JSON.stringify(now[key] ?? ""), JSON.stringify(old[key])));
+    if (dropped.length > 0)
+        return t("contract.weakerScripts", { scripts: dropped.join(", ") });
+    return keys.length > 0 ? t("contract.weakerRunner", { keys: keys.join(", ") }) : undefined;
+}
+async function newIndexFlags(cwd, capture) {
+    if (!capture.git)
+        return [];
+    const flagged = (await flaggedFiles(cwd)) ?? [];
+    const known = new Set(capture.flagged);
+    return flagged.filter((path) => !known.has(path));
+}
+function contractFinding(change) {
+    return {
+        severity: "blocker",
+        id: findingId("contract", change.path, change.detail, change.fingerprint ?? ""),
+        file: change.path,
+        message: t(MESSAGES[change.kind], { path: change.path, detail: change.detail }),
+    };
+}
+function settled(change, finding) {
+    const done = finding.severity !== "blocker"
+        ? t("findings.accepted")
+        : t(change.change === "created" ? "contract.removed" : "contract.restored");
+    return { ...finding, message: `${finding.message} ${done}` };
+}
+function acceptable(change, scope) {
+    return isAcceptableKind(change.kind) && inScope(change.path, scope);
+}

package/dist/gates/findings.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+export function findingId(kind, ...parts) {
+    const hash = createHash("sha1")
+        .update([kind, ...parts].join("\u0000"))
+        .digest("hex");
+    return `${kind}-${hash.slice(0, 8)}`;
+}
+export function newAcceptance(ids = []) {
+    return { ids: new Set([...ids].map((id) => id.trim().toLowerCase())), accepted: [] };
+}
+export function accept(acceptance, finding, allowed) {
+    if (!allowed || !finding.id || !acceptance.ids.has(finding.id))
+        return finding;
+    const accepted = { ...finding, severity: "minor" };
+    acceptance.accepted.push(accepted);
+    return accepted;
+}