@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/epic-contract-context.js

@@ -0,0 +1,326 @@
+/**
+ * epic-contract-context — the MCP side of epic-aware review resolution (BAPI-1428).
+ *
+ * Three jobs live here, kept out of `index.ts` so they can be unit-tested:
+ *
+ * 1. **The switch.** `EPIC_CONTRACT_CONTEXT_ENABLED` is the same default-ON
+ *    variable the Python service reads
+ *    (`api/library/tickets/epic_contract_context_config_lib.py`). It is
+ *    independent of delivery readiness and of tool-surface gating.
+ * 2. **Transport.** Building the context request, and turning a complete
+ *    transport failure into a disclosed, degraded result instead of an error,
+ *    so an unreachable context service never stops a review.
+ * 3. **The structured resolution result.** Parsing and validating the fenced
+ *    `bapi-epic-contract-resolution` block that `evaluate-and-recommend.md`
+ *    writes into `<KEY>-review-and-resolution.md`, and deciding whether terminal
+ *    decision capture may proceed. Capture is refused only while a finding is
+ *    recorded as an unresolved mandatory incompatibility.
+ *
+ * The resolution duty is not duplicated here: it is the canonical
+ * `api/library/tickets/epic_contract_resolution_duty.md`, bundled verbatim into
+ * `SHARED_RESOURCES` (`shared-resources.generated.ts`) by
+ * `scripts/bundle-pipelines.js`.
+ */
+import { parseDefaultOnEnvFlag } from "./env-flags.js";
+import { isValidTicketKey } from "./ticket-key-utils.js";
+/** The single switch, shared with the Python service. */
+export const EPIC_CONTRACT_CONTEXT_ENV_VAR = "EPIC_CONTRACT_CONTEXT_ENABLED";
+/** The fenced-block info string the structured result is written under. */
+export const EPIC_RESOLUTION_FENCE = "bapi-epic-contract-resolution";
+/** Version of the structured result this module reads and validates. */
+export const EPIC_RESOLUTION_SCHEMA_VERSION = 1;
+/** Bundled resource name of the canonical resolution duty. */
+export const EPIC_CONTRACT_DUTY_RESOURCE = "epic-contract-resolution-duty.md";
+/**
+ * Whether epic-contract resolution is on for new reviews in this process.
+ *
+ * `env` defaults to `process.env`; tests inject an explicit object.
+ */
+export function epicContractContextEnabled(env = process.env) {
+    return parseDefaultOnEnvFlag(env[EPIC_CONTRACT_CONTEXT_ENV_VAR]);
+}
+/**
+ * Build the context route's request body. Optional selectors are omitted when
+ * absent rather than sent as null or empty values.
+ */
+export function buildEpicContractContextBody(args, repoName) {
+    const body = {
+        repo_name: repoName,
+        ticket_key: args.ticket_key.trim().toUpperCase(),
+    };
+    if (args.policy_token)
+        body.policy_token = args.policy_token;
+    if (args.sibling_keys && args.sibling_keys.length > 0)
+        body.sibling_keys = args.sibling_keys;
+    if (args.children_cursor)
+        body.children_cursor = args.children_cursor;
+    if (args.page_limit !== undefined)
+        body.page_limit = args.page_limit;
+    if (args.include_parent !== undefined)
+        body.include_parent = args.include_parent;
+    if (args.excerpts && args.excerpts.length > 0)
+        body.excerpts = args.excerpts;
+    if (args.revalidate && args.revalidate.length > 0)
+        body.revalidate = args.revalidate;
+    return body;
+}
+/** The result returned when the switch is off and no starting-policy token was supplied. */
+export function disabledContextResult(ticketKey) {
+    return {
+        status: "disabled",
+        subject_key: ticketKey.trim().toUpperCase(),
+        policy_enabled: false,
+        coverage: { complete: false, gaps: [] },
+        note: "Epic-contract resolution is switched off for new reviews. Continue the ordinary review; " +
+            "recorded decisions are unaffected.",
+    };
+}
+/**
+ * The degraded result for a complete transport failure.
+ *
+ * The review continues with the evidence it already has. Fallback telemetry is
+ * reported as `unavailable`: this process has no authenticated, non-admin
+ * diagnostic channel it could use instead, and it never claims a report was
+ * delivered when it was not.
+ */
+export function transportFailureResult(ticketKey, duty) {
+    return {
+        status: "degraded",
+        subject_key: ticketKey.trim().toUpperCase(),
+        parent: null,
+        inventory: null,
+        siblings: [],
+        revalidations: [],
+        coverage: {
+            fetched: [],
+            partial: [],
+            missing_or_failed: [],
+            unhydrated: [],
+            complete: false,
+            gaps: [
+                {
+                    reason: "read_failed",
+                    ticket_key: null,
+                    detail: "The epic-contract context service could not be reached.",
+                },
+            ],
+        },
+        telemetry: { status: "unavailable", reported_gap_count: 0 },
+        duty: duty ?? null,
+        note: "No epic contract was retrieved. Disclose this gap, resolve with the ticket and code " +
+            "evidence you have, and do not claim any parent or sibling contract was checked.",
+    };
+}
+const FENCE_PATTERN = new RegExp("^```" + EPIC_RESOLUTION_FENCE + "[ \\t]*\\r?\\n([\\s\\S]*?)\\r?\\n```[ \\t]*$", "gm");
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const STATUSES = new Set([
+    "settled",
+    "mandatory_incompatibility",
+    "not_applicable",
+    "disabled",
+]);
+const RESOLUTIONS = new Set([
+    "accepted",
+    "adapted",
+    "rejected",
+    "alternative",
+    "unresolved",
+]);
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+function validateFinding(raw, index, errors) {
+    const where = `findings[${index}]`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push(`${where} must be an object`);
+        return null;
+    }
+    const f = raw;
+    if (typeof f.id !== "string" || !f.id.trim())
+        errors.push(`${where}.id must be a non-empty string`);
+    if (!isStringArray(f.source_ids))
+        errors.push(`${where}.source_ids must be a string array`);
+    if (typeof f.resolution !== "string" || !RESOLUTIONS.has(f.resolution)) {
+        errors.push(`${where}.resolution is not a recognized value`);
+    }
+    if (f.status !== "settled" && f.status !== "mandatory_incompatibility") {
+        errors.push(`${where}.status must be settled or mandatory_incompatibility`);
+    }
+    const cited = Array.isArray(f.cited_sources) ? f.cited_sources : null;
+    if (!cited) {
+        errors.push(`${where}.cited_sources must be an array`);
+    }
+    else {
+        cited.forEach((c, i) => {
+            const s = c;
+            if (!s ||
+                typeof s.ticket_key !== "string" ||
+                !isValidTicketKey(s.ticket_key) ||
+                typeof s.content_sha256 !== "string" ||
+                !SHA256_PATTERN.test(s.content_sha256)) {
+                errors.push(`${where}.cited_sources[${i}] needs a ticket_key and a 64-hex content_sha256`);
+            }
+        });
+    }
+    if (f.status === "mandatory_incompatibility") {
+        if (f.resolution !== "unresolved") {
+            errors.push(`${where} is a mandatory incompatibility, so its resolution must be unresolved`);
+        }
+        if (!isStringArray(f.conflicting_obligations) || f.conflicting_obligations.length < 2) {
+            errors.push(`${where}.conflicting_obligations must cite at least two obligations`);
+        }
+        if (!isStringArray(f.attempted_alternatives) || f.attempted_alternatives.length < 1) {
+            errors.push(`${where}.attempted_alternatives must list what was tried`);
+        }
+        if (typeof f.recommended_resolution !== "string" || !f.recommended_resolution.trim()) {
+            errors.push(`${where}.recommended_resolution must name the recommended decision`);
+        }
+        if (cited && cited.length < 1) {
+            errors.push(`${where}.cited_sources must cite the conflicting contracts`);
+        }
+    }
+    else if (f.resolution === "unresolved") {
+        errors.push(`${where} is settled, so its resolution cannot be unresolved`);
+    }
+    return errors.length > 0 ? null : f;
+}
+/**
+ * Validate a decoded structured result. Returns the typed result or the list of
+ * problems found; never throws.
+ */
+export function validateEpicResolution(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { found: true, ok: false, errors: ["the block must be a JSON object"] };
+    }
+    const r = raw;
+    if (r.version !== EPIC_RESOLUTION_SCHEMA_VERSION) {
+        errors.push(`version must be ${EPIC_RESOLUTION_SCHEMA_VERSION}`);
+    }
+    if (typeof r.subject_key !== "string" || !isValidTicketKey(r.subject_key)) {
+        errors.push("subject_key must be a ticket key");
+    }
+    if (r.generation !== null && !(Number.isInteger(r.generation) && r.generation > 0)) {
+        errors.push("generation must be a positive integer or null");
+    }
+    if (r.source_bundle_sha256 !== null &&
+        !(typeof r.source_bundle_sha256 === "string" && SHA256_PATTERN.test(r.source_bundle_sha256))) {
+        errors.push("source_bundle_sha256 must be 64 lowercase hex or null");
+    }
+    const policy = r.policy;
+    if (!policy || typeof policy.enabled !== "boolean" || !Number.isInteger(policy.policy_version)) {
+        errors.push("policy must carry enabled and policy_version");
+    }
+    if (typeof r.status !== "string" || !STATUSES.has(r.status)) {
+        errors.push("status is not a recognized value");
+    }
+    const coverage = r.coverage;
+    if (!coverage || typeof coverage.complete !== "boolean" || !isStringArray(coverage.gaps)) {
+        errors.push("coverage must carry complete and a gaps string array");
+    }
+    const findings = [];
+    if (!Array.isArray(r.findings)) {
+        errors.push("findings must be an array");
+    }
+    else {
+        r.findings.forEach((raw, i) => {
+            const findingErrors = [];
+            const finding = validateFinding(raw, i, findingErrors);
+            errors.push(...findingErrors);
+            if (finding)
+                findings.push(finding);
+        });
+        const ids = new Set();
+        for (const f of findings) {
+            if (ids.has(f.id))
+                errors.push(`finding id ${f.id} is duplicated`);
+            ids.add(f.id);
+        }
+    }
+    if (errors.length === 0) {
+        const anyConflict = findings.some((f) => f.status === "mandatory_incompatibility");
+        if (anyConflict && r.status !== "mandatory_incompatibility") {
+            errors.push("a finding is a mandatory incompatibility, so status must be mandatory_incompatibility");
+        }
+        if (!anyConflict && r.status === "mandatory_incompatibility") {
+            errors.push("status is mandatory_incompatibility but no finding records one");
+        }
+    }
+    if (errors.length > 0)
+        return { found: true, ok: false, errors };
+    return { found: true, ok: true, result: r };
+}
+/**
+ * Find and validate the structured result in a review-and-resolution document.
+ *
+ * `{found: false}` when the document has no block — every standalone review,
+ * and every review from before this feature. More than one block is refused:
+ * a capture must never have to choose between two records.
+ */
+export function parseEpicResolutionBlock(markdown) {
+    const matches = [...markdown.matchAll(FENCE_PATTERN)];
+    if (matches.length === 0)
+        return { found: false };
+    if (matches.length > 1) {
+        return { found: true, ok: false, errors: ["the document has more than one resolution block"] };
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(matches[0][1]);
+    }
+    catch {
+        return { found: true, ok: false, errors: ["the resolution block is not valid JSON"] };
+    }
+    return validateEpicResolution(decoded);
+}
+/**
+ * Decide whether terminal decision capture may proceed for this document.
+ *
+ * Capture proceeds when the document has no block (unrelated callers are
+ * unaffected), or when its block is valid, belongs to this ticket and
+ * generation, and records no unresolved mandatory incompatibility.
+ */
+export function evaluateEpicCaptureGate(markdown, ticketNumber, generation) {
+    if (markdown === null)
+        return { allowed: true };
+    const parsed = parseEpicResolutionBlock(markdown);
+    if (!parsed.found)
+        return { allowed: true };
+    if (!parsed.ok) {
+        return {
+            allowed: false,
+            reason: "epic_resolution_malformed",
+            message: "The epic-contract resolution block in the review-and-resolution document is not valid. " +
+                "Fix the block, then capture again.",
+            errors: parsed.errors,
+        };
+    }
+    const result = parsed.result;
+    if (result.subject_key.toUpperCase() !== ticketNumber.trim().toUpperCase()) {
+        return {
+            allowed: false,
+            reason: "epic_resolution_malformed",
+            message: "The epic-contract resolution block names a different ticket.",
+        };
+    }
+    if (result.generation !== null && result.generation !== generation) {
+        return {
+            allowed: false,
+            reason: "epic_resolution_generation_mismatch",
+            message: "The epic-contract resolution was recorded against a different review generation. " +
+                "Wait for the review again and re-adjudicate against the current documents.",
+        };
+    }
+    const blocked = result.findings.filter((f) => f.status === "mandatory_incompatibility");
+    if (blocked.length > 0) {
+        return {
+            allowed: false,
+            reason: "epic_contract_incompatibility_unresolved",
+            message: "A finding is recorded as an unresolved mandatory incompatibility between epic contracts. " +
+                "Present the conflicting obligations and the recommended resolution; capture after an " +
+                "explicit resolving decision is recorded in the block.",
+            finding_ids: blocked.map((f) => f.id),
+        };
+    }
+    return { allowed: true };
+}