@bridge_gpt/mcp-server 0.2.54 → 0.2.55

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),
+    };
+}