@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/executor/merge-tree-classifier.js

@@ -0,0 +1,171 @@
+/**
+ * Deterministic merge classification for `reconcile_overlap` (BAPI-1152).
+ *
+ * Classifies a (child head, required epic SHA) pair with
+ * `git merge-tree --write-tree` BEFORE anything touches the held worktree.
+ * `merge-tree` computes the merge entirely in the object database: it writes a
+ * tree object and reports conflicts, but never touches a working tree, an index,
+ * `HEAD`, or a ref. That is what lets the job decide "clean or conflicted" first
+ * and only then materialize a real merge.
+ *
+ * Output is read in the machine-readable `-z --name-only --messages` form, never
+ * scraped from human text. Verified against git 2.50.1:
+ *
+ *   <tree-oid> NUL <conflicted path> NUL ... NUL NUL
+ *   ( <N> NUL <path 1> NUL ... <path N> NUL <type> NUL <message> NUL )*
+ *
+ * with exit 0 for a clean merge and 1 for a conflicted one. Exit 1 is ALSO what
+ * git returns for an unknown commit — with no tree OID on stdout — so the exit
+ * code alone never decides "conflicted": the parsed tree OID does. Anything that
+ * is not a proven clean or conflicted result is `operational_error`, and the job
+ * fails rather than guessing.
+ *
+ * Every git call is an argv list through the injected `RunCommand` (`execFile`,
+ * `shell: false`); no shell string is ever built.
+ */
+import { normalizeRepoRelativePath } from "../conductor/file-scope-guard.js";
+/** Bound on the conflicted paths recorded. More than this is still `conflicted`. */
+export const MERGE_TREE_MAX_CONFLICTS = 200;
+/** Bound on the informational lines kept per conflicted path. */
+export const MERGE_TREE_MAX_MESSAGES_PER_PATH = 5;
+/** Bound on one message line. */
+export const MERGE_TREE_MESSAGE_MAX_CHARS = 300;
+/** Wall-clock bound on each git call the classifier makes. */
+export const MERGE_TREE_COMMAND_TIMEOUT_MS = 120_000;
+const OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function descriptorFor(type, message) {
+    // The MESSAGE carries git's user-facing spelling ("CONFLICT (content)"); the
+    // type token is an internal name ("CONFLICT (contents)"). Prefer the message's
+    // own prefix so the descriptor matches what an operator sees in `git merge`.
+    const fromMessage = /^(CONFLICT \([^)]*\))/.exec(message.trim());
+    if (fromMessage)
+        return fromMessage[1];
+    return type.trim().length > 0 ? type.trim() : "CONFLICT (unknown)";
+}
+/**
+ * Parse `git merge-tree --write-tree -z --name-only --messages` stdout.
+ *
+ * Exported for the unit tests; `classifyMergeTree` is the runtime entry point.
+ * Returns `null` when stdout does not start with a tree OID — the caller treats
+ * that as an operational error.
+ */
+export function parseMergeTreeOutput(stdout) {
+    const tokens = stdout.split("\0");
+    const treeOid = (tokens[0] ?? "").trim().toLowerCase();
+    if (!OID_RE.test(treeOid))
+        return null;
+    let i = 1;
+    const conflictedPaths = [];
+    while (i < tokens.length && tokens[i] !== "") {
+        conflictedPaths.push(tokens[i]);
+        i += 1;
+    }
+    i += 1; // the empty token separating conflicted paths from messages
+    const byPath = new Map();
+    const record = (rawPath, descriptor, message) => {
+        const path = normalizeRepoRelativePath(rawPath) ?? rawPath;
+        let entry = byPath.get(path);
+        if (!entry) {
+            entry = { path, descriptor: descriptor ?? "CONFLICT (unknown)", messages: [] };
+            byPath.set(path, entry);
+        }
+        else if (descriptor && entry.descriptor === "CONFLICT (unknown)") {
+            entry.descriptor = descriptor;
+        }
+        if (message && entry.messages.length < MERGE_TREE_MAX_MESSAGES_PER_PATH) {
+            entry.messages.push(message.trim().slice(0, MERGE_TREE_MESSAGE_MAX_CHARS));
+        }
+    };
+    while (i < tokens.length) {
+        const countToken = tokens[i];
+        if (countToken === "" || countToken === undefined)
+            break;
+        const count = Number.parseInt(countToken, 10);
+        // A group is `count` paths plus a type and a message; a truncated group ends
+        // the parse rather than reading past stdout.
+        if (!Number.isInteger(count) || count < 0 || i + count + 2 >= tokens.length)
+            break;
+        const paths = tokens.slice(i + 1, i + 1 + count);
+        const type = tokens[i + 1 + count] ?? "";
+        const message = tokens[i + 2 + count] ?? "";
+        i += count + 3;
+        if (!type.startsWith("CONFLICT"))
+            continue;
+        const descriptor = descriptorFor(type, message);
+        // The FIRST path of a multi-path message (e.g. rename/delete names the new
+        // and the old path) is the one git reports as conflicted; the rest are
+        // context. Recording every named path would report a path that no longer
+        // exists in the merge result as conflicted.
+        const conflicted = paths.find((p) => conflictedPaths.includes(p)) ?? paths[0];
+        if (conflicted !== undefined)
+            record(conflicted, descriptor, message);
+    }
+    // A path git listed as conflicted with no CONFLICT message is still conflicted.
+    for (const path of conflictedPaths) {
+        const normalized = normalizeRepoRelativePath(path) ?? path;
+        if (!byPath.has(normalized))
+            record(path, null, null);
+    }
+    const conflicts = Array.from(byPath.values())
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .slice(0, MERGE_TREE_MAX_CONFLICTS);
+    return { treeOid, conflicts };
+}
+/** Verify a commit object is present locally. */
+async function commitPresent(runCommand, repoDir, sha) {
+    try {
+        const result = await runCommand("git", ["cat-file", "-e", `${sha}^{commit}`], {
+            cwd: repoDir,
+            timeoutMs: MERGE_TREE_COMMAND_TIMEOUT_MS,
+        });
+        return result.exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify merging `requiredEpicSha` into `childHead`. Never mutates a worktree,
+ * an index, `HEAD`, or a ref. Both SHAs must already be present in `repoDir`'s
+ * object database (the caller fetches them).
+ */
+export async function classifyMergeTree(runCommand, repoDir, childHead, requiredEpicSha) {
+    for (const sha of [childHead, requiredEpicSha]) {
+        if (!OID_RE.test(sha)) {
+            return { kind: "operational_error", reason: "a merge input is not a full commit SHA" };
+        }
+        if (!(await commitPresent(runCommand, repoDir, sha))) {
+            return {
+                kind: "operational_error",
+                reason: `commit ${sha.slice(0, 12)} is not present in the local object database`,
+            };
+        }
+    }
+    let result;
+    try {
+        result = await runCommand("git", ["merge-tree", "--write-tree", "-z", "--name-only", "--messages", childHead, requiredEpicSha], { cwd: repoDir, timeoutMs: MERGE_TREE_COMMAND_TIMEOUT_MS });
+    }
+    catch {
+        return { kind: "operational_error", reason: "git merge-tree could not be run" };
+    }
+    if (result.exitCode !== 0 && result.exitCode !== 1) {
+        return { kind: "operational_error", reason: `git merge-tree exited ${result.exitCode}` };
+    }
+    const parsed = parseMergeTreeOutput(result.stdout);
+    if (parsed === null) {
+        return { kind: "operational_error", reason: "git merge-tree produced no tree object" };
+    }
+    if (result.exitCode === 0) {
+        return { kind: "clean", treeOid: parsed.treeOid };
+    }
+    if (parsed.conflicts.length === 0) {
+        // Exit 1 WITH a tree but no conflict record: git said "not clean" and did not
+        // say why. Unknown is conflicted, never clean.
+        return {
+            kind: "conflicted",
+            treeOid: parsed.treeOid,
+            conflicts: [{ path: "(unreported)", descriptor: "CONFLICT (unknown)", messages: [] }],
+        };
+    }
+    return { kind: "conflicted", treeOid: parsed.treeOid, conflicts: parsed.conflicts };
+}

package/build/executor/reconcile-overlap-governance.js

@@ -0,0 +1,129 @@
+/**
+ * Governance-region comparison for `reconcile_overlap` (BAPI-1152).
+ *
+ * Before the wrapper pushes, the candidate tree is compared against the
+ * governance-guarded regions the SERVER found in the INPUT epic head
+ * (`required_epic_sha`). A candidate that changes any protected region — its
+ * content OR either marker line — is never pushed: the job reports the
+ * `governance_guard_change_required` fact and the reconciler parks naming the tag.
+ *
+ * This module deliberately does NOT parse the marker grammar. The server owns it
+ * (`api/library/epic_conductor/governance_markers.py`) and ships each region as
+ * its exact BEGIN and END marker lines plus the SHA-256 of the region's content,
+ * markers included. Here a region is located by those exact lines and compared by
+ * hash — never by line number, which an edit above the region would shift without
+ * touching anything it protects. A second grammar implementation would be a
+ * second place for the two to disagree about what is protected.
+ *
+ * Fail-closed everywhere the comparison cannot be proven:
+ *   - the region's file is gone from the candidate (deleted or renamed), binary,
+ *     or unreadable;
+ *   - a marker line is missing, duplicated, or out of order;
+ *   - the server reported the file's marker structure unprovable (unbalanced,
+ *     nested, mismatched, or over the scan bound) and the candidate changes it;
+ *   - the candidate changes a file the server did NOT scan and either side of that
+ *     change contains a marker token — the server made no statement about it.
+ * The last two carry the synthetic tag {@link UNPROVABLE_GOVERNANCE_TAG}, which is
+ * itself valid marker grammar, so the park still names something greppable.
+ */
+import { createHash } from "node:crypto";
+/** The synthetic tag for protection the comparison could not prove. */
+export const UNPROVABLE_GOVERNANCE_TAG = "GOVERNANCE_MARKERS_UNPROVABLE";
+/** The token every governance marker line contains. */
+export const GOVERNANCE_MARKER_TOKEN = "BRIDGE-GOVERNANCE-GUARD-";
+/** Bounds on the reported fact (mirrors the server's result-model bounds). */
+export const GOVERNANCE_FACT_MAX_FINDINGS = 8;
+export const GOVERNANCE_FACT_MAX_PATHS = 8;
+/**
+ * Split text into lines exactly the way Python's `str.splitlines()` does, so the
+ * region hash computed here matches the one the server computed.
+ */
+export function splitLinesLikePython(text) {
+    const lines = text.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/);
+    // `splitlines()` yields no trailing empty entry for a terminal line break.
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function indicesOf(lines, needle) {
+    const out = [];
+    lines.forEach((line, index) => {
+        if (line === needle)
+            out.push(index);
+    });
+    return out;
+}
+/** True when a region is intact in `text`: both markers once, in order, same hash. */
+function regionIntact(text, region) {
+    const lines = splitLinesLikePython(text);
+    const begins = indicesOf(lines, region.beginMarker);
+    const ends = indicesOf(lines, region.endMarker);
+    if (begins.length !== 1 || ends.length !== 1)
+        return false;
+    const [begin] = begins;
+    const [end] = ends;
+    if (end < begin)
+        return false;
+    return sha256(lines.slice(begin, end + 1).join("\n")) === region.contentSha256;
+}
+function containsMarkerToken(read) {
+    // An unreadable or binary side cannot be proven marker-free.
+    if (read.kind === "unreadable" || read.kind === "binary")
+        return true;
+    return read.kind === "text" && read.text.includes(GOVERNANCE_MARKER_TOKEN);
+}
+/**
+ * Compare the candidate against the input epic head's governance regions.
+ * Returns the structured fact, or `null` when nothing protected is touched.
+ */
+export async function scanGovernanceRegions(input) {
+    const hits = new Map();
+    const hit = (tag, path) => {
+        let paths = hits.get(tag);
+        if (!paths) {
+            paths = new Set();
+            hits.set(tag, paths);
+        }
+        paths.add(path);
+    };
+    const changed = new Set(input.changedPaths);
+    for (const region of input.snapshot.regions) {
+        const candidate = await input.readCandidate(region.path);
+        if (candidate.kind !== "text" || !regionIntact(candidate.text, region)) {
+            hit(region.tag, region.path);
+        }
+    }
+    for (const finding of input.snapshot.findings) {
+        if (changed.has(finding.path))
+            hit(UNPROVABLE_GOVERNANCE_TAG, finding.path);
+    }
+    const scanned = new Set(input.snapshot.scannedPaths);
+    for (const path of input.changedPaths) {
+        if (scanned.has(path))
+            continue;
+        const [candidate, original] = await Promise.all([
+            input.readCandidate(path),
+            input.readInput(path),
+        ]);
+        if (containsMarkerToken(candidate) || containsMarkerToken(original)) {
+            hit(UNPROVABLE_GOVERNANCE_TAG, path);
+        }
+    }
+    if (hits.size === 0)
+        return null;
+    const findings = Array.from(hits.entries())
+        .map(([tag, paths]) => ({ tag, paths: Array.from(paths).sort().slice(0, GOVERNANCE_FACT_MAX_PATHS) }))
+        .sort((a, b) => a.tag !== b.tag ? (a.tag < b.tag ? -1 : 1) : (a.paths[0] ?? "") < (b.paths[0] ?? "") ? -1 : 1);
+    const bounded = findings.slice(0, GOVERNANCE_FACT_MAX_FINDINGS);
+    const primary = bounded[0];
+    return {
+        tag: primary.tag,
+        paths: primary.paths,
+        findings: bounded,
+        truncated: findings.length > GOVERNANCE_FACT_MAX_FINDINGS ||
+            Array.from(hits.values()).some((paths) => paths.size > GOVERNANCE_FACT_MAX_PATHS),
+    };
+}