@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/workflow/review-workflow/__tests__/merge-gate.test.ts

@@ -27,6 +27,7 @@ function approval(overrides: Partial<FileApprovalState>): FileApprovalState {
     approvedBy: [],
     isApproved: false,
     viewerCanApprove: false,
+    inMergeGate: true,
     ...overrides,
   };
 }
@@ -87,38 +88,22 @@ describe('evaluateMergeGate', () => {
     expect(result.reasons[0]).toMatch(/no file changes/i);
   });
 
-  it('ignores md files with no eligible approvers — no warning, no block', () => {
-    // Files outside the access-controlled surface (no roles/users grant
-    // write) are not part of the gate.
+  it('ignores files with no eligible approvers, of any type — no warning, no block', () => {
+    // Nobody could approve these, so counting them would deadlock the request.
     const result = svc.evaluateMergeGate({
       prNumber: 1,
       state: 'open',
       approvals: [
         approval({ path: 'A.md', isApproved: true, approvedBy: [entry({})] }),
         approval({ path: 'Legacy.md', eligibleApprovers: EMPTY_ELIGIBLE }),
-      ],
-    });
-    expect(result.mergeable).toBe(true);
-    expect(result.reasons).toEqual([]);
-    expect(result.warnings).toEqual([]);
-  });
-
-  it('ignores non-md files regardless of eligibility', () => {
-    // TypeScript sources, JSON, images etc. don't participate in the gate.
-    const result = svc.evaluateMergeGate({
-      prNumber: 1,
-      state: 'open',
-      approvals: [
-        approval({ path: 'src/foo.ts', eligibleApprovers: ADMIN_ELIGIBLE }),
         approval({ path: 'assets/logo.png', eligibleApprovers: EMPTY_ELIGIBLE }),
+        approval({ path: 'Makefile', eligibleApprovers: EMPTY_ELIGIBLE }),
       ],
     });
-    expect(result.mergeable).toBe(true);
-    expect(result.reasons).toEqual([]);
-    expect(result.warnings).toEqual([]);
+    expect(result).toEqual({ mergeable: true, reasons: [], warnings: [] });
   });
 
-  it('treats unapproved md-with-eligible-approvers as a warning, not a hard block', () => {
+  it('reports an unapproved file with eligible approvers as a blocking reason and a warning', () => {
     const result = svc.evaluateMergeGate({
       prNumber: 1,
       state: 'open',
@@ -133,14 +118,14 @@ describe('evaluateMergeGate', () => {
         }),
       ],
     });
-    expect(result.mergeable).toBe(true);
-    expect(result.reasons).toEqual([]);
-    expect(result.warnings).toEqual([
-      'Waiting on approval for B.md from Product Manager; Bob <bob@bevel.software>.',
-    ]);
+    const message = 'Waiting on approval for B.md from Product Manager; Bob <bob@bevel.software>.';
+    expect(result.mergeable).toBe(false);
+    expect(result.reasons).toEqual([message]);
+    // The warning list is what an admin bypass merges past and records.
+    expect(result.warnings).toEqual([message]);
   });
 
-  it('distinguishes stale approvals from never-approved in warnings', () => {
+  it('distinguishes stale approvals from never-approved', () => {
     const result = svc.evaluateMergeGate({
       prNumber: 1,
       state: 'open',
@@ -157,12 +142,13 @@ describe('evaluateMergeGate', () => {
         }),
       ],
     });
-    expect(result.mergeable).toBe(true);
+    expect(result.mergeable).toBe(false);
     expect(result.warnings).toContain('Admin need to re-approve A.md after the latest push.');
     expect(result.warnings).toContain('Waiting on approval for B.md from Admin.');
+    expect(result.reasons).toEqual(result.warnings);
   });
 
-  it('surfaces only the hard block when the PR is closed, not soft warnings', () => {
+  it('lists the hard block before the missing approvals when the PR is closed', () => {
     const result = svc.evaluateMergeGate({
       prNumber: 1,
       state: 'closed',
@@ -173,29 +159,13 @@ describe('evaluateMergeGate', () => {
     });
     expect(result.mergeable).toBe(false);
     expect(result.reasons[0]).toMatch(/closed/i);
+    expect(result.reasons).toContain('Waiting on approval for B.md from Admin.');
   });
 
-  it('is case-insensitive on the .md extension check', () => {
-    const result = svc.evaluateMergeGate({
-      prNumber: 1,
-      state: 'open',
-      approvals: [
-        approval({
-          path: 'Knowledge/FOO.MD',
-          eligibleApprovers: ADMIN_ELIGIBLE,
-          approvedBy: [],
-        }),
-      ],
-    });
-    expect(result.warnings).toContain('Waiting on approval for Knowledge/FOO.MD from Admin.');
-  });
-
-  // Regression: roles.yaml is the file that decides Admin membership, but it
-  // isn't a `.md` KB node — so before this gate it slipped through with zero
-  // warnings, and a roles.yaml-only change request could merge into a protected
-  // branch with no approval and no admin check, letting its author self-promote
-  // to Admin. The gate must bind roles.yaml (and access.md) like an md node.
-  it('treats an unapproved roles.yaml change as a warning (privilege-escalation guard)', () => {
+  // Regression: roles.yaml is the file that decides Admin membership. Before it
+  // was gated, a roles.yaml-only change request could merge into a protected
+  // branch with no approval and no admin check, letting its author self-promote.
+  it('blocks an unapproved roles.yaml change (privilege-escalation guard)', () => {
     const result = svc.evaluateMergeGate({
       prNumber: 1,
       state: 'open',
@@ -203,18 +173,12 @@ describe('evaluateMergeGate', () => {
         approval({ path: 'roles.yaml', eligibleApprovers: ADMIN_ELIGIBLE, approvedBy: [] }),
       ],
     });
-    // mergeable stays true (it's a soft warning, bypassable only by an admin in
-    // mergePr) — the point is that the warning EXISTS, so a non-admin merge of a
-    // roles.yaml-only PR is no longer silently waved through.
-    expect(result.warnings).toContain('Waiting on approval for roles.yaml from Admin.');
-    // Pin the non-blocking contract: this PR's guarantee is "warn, don't block".
-    // If evaluateMergeGate ever starts adding blocking reasons or flipping
-    // mergeable to false for an access-config file, these must fail.
-    expect(result.mergeable).toBe(true);
-    expect(result.reasons).toEqual([]);
+    expect(result.mergeable).toBe(false);
+    expect(result.reasons).toEqual(['Waiting on approval for roles.yaml from Admin.']);
+    expect(result.warnings).toEqual(['Waiting on approval for roles.yaml from Admin.']);
   });
 
-  it('treats an unapproved access.md change as a warning, at root and nested', () => {
+  it('blocks an unapproved access.md change, at root and nested', () => {
     const result = svc.evaluateMergeGate({
       prNumber: 1,
       state: 'open',
@@ -223,11 +187,9 @@ describe('evaluateMergeGate', () => {
         approval({ path: 'Knowledge/Sales/access.md', eligibleApprovers: ADMIN_ELIGIBLE, approvedBy: [] }),
       ],
     });
-    expect(result.warnings).toContain('Waiting on approval for access.md from Admin.');
-    expect(result.warnings).toContain('Waiting on approval for Knowledge/Sales/access.md from Admin.');
-    // Same non-blocking contract as roles.yaml: warn, never block.
-    expect(result.mergeable).toBe(true);
-    expect(result.reasons).toEqual([]);
+    expect(result.mergeable).toBe(false);
+    expect(result.reasons).toContain('Waiting on approval for access.md from Admin.');
+    expect(result.reasons).toContain('Waiting on approval for Knowledge/Sales/access.md from Admin.');
   });
 
   it('a roles.yaml change WITH a non-stale eligible approval passes cleanly', () => {
@@ -241,18 +203,68 @@ describe('evaluateMergeGate', () => {
     expect(result).toEqual({ mergeable: true, reasons: [], warnings: [] });
   });
 
-  it('does not gate roles.yaml when no one is eligible to approve it', () => {
-    // Mirrors the md path: a config file with no eligible approver can't be
-    // approved, so it neither warns nor blocks (the merge-gate would otherwise
-    // deadlock on an un-approvable file).
-    const result = svc.evaluateMergeGate({
-      prNumber: 1,
-      state: 'open',
-      approvals: [
-        approval({ path: 'roles.yaml', eligibleApprovers: EMPTY_ELIGIBLE }),
-      ],
+  // The gate is extension-blind: a Markdown note, a binary and an extensionless
+  // file with owners all need an approval, and all pass once they have one.
+  describe('every file type', () => {
+    const KINDS = [
+      ['an extensionless file', 'Knowledge/Ops/Makefile'],
+      ['a binary file', 'Knowledge/Finance/report.pdf'],
+      ['a Markdown file', 'Knowledge/Foo.md'],
+      ['an upper-case Markdown file', 'Knowledge/FOO.MD'],
+    ] as const;
+
+    for (const [kind, path] of KINDS) {
+      it(`blocks ${kind} that lacks an approval`, () => {
+        const result = svc.evaluateMergeGate({
+          prNumber: 1,
+          state: 'open',
+          approvals: [approval({ path, approvedBy: [] })],
+        });
+        expect(result.mergeable).toBe(false);
+        expect(result.reasons).toEqual([`Waiting on approval for ${path} from Admin.`]);
+        expect(result.warnings).toEqual([`Waiting on approval for ${path} from Admin.`]);
+      });
+
+      it(`passes ${kind} that has an approval`, () => {
+        const result = svc.evaluateMergeGate({
+          prNumber: 1,
+          state: 'open',
+          approvals: [approval({ path, isApproved: true, approvedBy: [entry({})] })],
+        });
+        expect(result).toEqual({ mergeable: true, reasons: [], warnings: [] });
+      });
+    }
+
+    it('names exactly the unapproved files in a mixed request', () => {
+      const result = svc.evaluateMergeGate({
+        prNumber: 1,
+        state: 'open',
+        approvals: [
+          approval({ path: 'Knowledge/Foo.md', isApproved: true, approvedBy: [entry({})] }),
+          approval({ path: 'Knowledge/Finance/report.pdf', approvedBy: [] }),
+          approval({ path: 'Knowledge/Ops/Makefile', approvedBy: [] }),
+          approval({ path: 'Knowledge/Unowned.bin', eligibleApprovers: EMPTY_ELIGIBLE }),
+        ],
+      });
+      expect(result.mergeable).toBe(false);
+      expect(result.reasons).toEqual([
+        'Waiting on approval for Knowledge/Finance/report.pdf from Admin.',
+        'Waiting on approval for Knowledge/Ops/Makefile from Admin.',
+      ]);
+      expect(result.warnings).toEqual(result.reasons);
+    });
+
+    it('passes a mixed request once every owned file is approved', () => {
+      const result = svc.evaluateMergeGate({
+        prNumber: 1,
+        state: 'open',
+        approvals: [
+          approval({ path: 'Knowledge/Foo.md', isApproved: true, approvedBy: [entry({})] }),
+          approval({ path: 'Knowledge/Finance/report.pdf', isApproved: true, approvedBy: [entry({})] }),
+          approval({ path: 'Knowledge/Ops/Makefile', isApproved: true, approvedBy: [entry({})] }),
+        ],
+      });
+      expect(result).toEqual({ mergeable: true, reasons: [], warnings: [] });
     });
-    expect(result.mergeable).toBe(true);
-    expect(result.warnings).toEqual([]);
   });
 });

package/src/modules/workflow/review-workflow/approval-lock.ts

@@ -0,0 +1,122 @@
+import { sql } from 'drizzle-orm';
+import type { Database } from '../../database/connection.js';
+
+/**
+ * The lock every writer of `pr_file_approvals` takes, and the one thing that
+ * orders them against each other.
+ *
+ * Three writers exist, in two different modules: a change request bringing
+ * itself up to date copies the approvals its merge did not disturb onto the
+ * new head, a reviewer approves or revokes one file, and account erasure
+ * rewrites an erased person's name and address out of every row they ever
+ * approved. Any two of those interleaved lose something real — a revoke that
+ * comes back, an approval pinned to a head that has already gone, or an erased
+ * address re-inserted onto a new head by a copy that read it a moment before
+ * the erasure landed.
+ *
+ * In the DATABASE, not in this process: two app instances share the rows but
+ * not a mutex.
+ *
+ * WHY NOT `AdvisoryLock` (see `modules/database/advisory-lock.ts`). That
+ * registry keys every lock it owns as (its shared namespace, one id per
+ * concern), which spends the second slot on naming the concern. These locks
+ * need that slot for the change request: approvals of #12 must not queue
+ * behind approvals of #13. Sharing the registry's namespace would put a
+ * request number where its lock ids live, so the approvals of change request
+ * #1 would BE the `Migrations` lock and #3's the `CommitWorker` lease — a
+ * boot migration and a reviewer clicking Approve, excluding each other for no
+ * reason anyone could find from either side. Hence a class of this file's own,
+ * with the request number beneath it. The registry's rule still holds within
+ * it: the two keys below are the whole set, and a third belongs here beside
+ * them rather than as a number at a call site.
+ */
+const APPROVAL_LOCK_CLASS = 4207;
+/**
+ * The key that means EVERY change request. Change request numbers start at 1,
+ * so nothing else claims it.
+ *
+ * Held shared by the per-request writers — they do not exclude each other, the
+ * per-request key does that — and exclusively by the one writer whose reach is
+ * every request at once. That is what makes "all approvals of this person" a
+ * single serialized step rather than a race against whichever copy happens to
+ * be in flight.
+ */
+const EVERY_REQUEST = 0;
+/**
+ * How long a per-request approval write waits before giving up.
+ *
+ * Every body under this lock is a statement or two against rows already in
+ * cache, so a wait anywhere near this is a stuck holder rather than a busy
+ * one — and waiting a stuck holder out would pin a pooled connection for as
+ * long as it lasts, which is how one wedged transaction becomes a backend with
+ * no connections left. Five seconds is far past honest contention and far
+ * short of that.
+ */
+export const APPROVAL_LOCK_TIMEOUT_MS = 5_000;
+/**
+ * The same, for erasure — longer, because erasure must not fail over ordinary
+ * contention. It waits out every per-request writer in flight (each of them
+ * sub-second, and bounded by the timeout above), and gives up only on a holder
+ * that has genuinely wedged. Its transaction is atomic, so giving up erases
+ * nothing and the operator simply runs it again.
+ */
+export const ERASURE_LOCK_TIMEOUT_MS = 30_000;
+/** `lock_timeout` fired — Postgres `lock_not_available`. */
+const LOCK_NOT_AVAILABLE = '55P03';
+
+/** The handle `db.transaction` hands its callback — a `Database` minus the pool. */
+export type ApprovalTx = Parameters<Parameters<Database['transaction']>[0]>[0];
+
+/**
+ * Whether a rejection is that timeout. The driver surfaces the SQLSTATE on the
+ * error itself today; `cause` is checked too so a driver that starts wrapping
+ * its errors does not turn a retryable refusal back into a bare 500.
+ */
+export function isApprovalLockTimeout(err: unknown): boolean {
+  for (let e: unknown = err, depth = 0; e && depth < 3; e = (e as { cause?: unknown }).cause, depth++) {
+    if ((e as { code?: unknown }).code === LOCK_NOT_AVAILABLE) return true;
+  }
+  return false;
+}
+
+/**
+ * Claim one change request's approvals for the rest of `tx`.
+ *
+ * Shared on the every-request key first, then exclusive on this request's:
+ * writers of different requests run side by side, writers of the same one
+ * queue, and an erasure waits for all of them before it starts. The order is
+ * the same in both directions of this file, which is what keeps the pair
+ * deadlock-free.
+ *
+ * Call it as the first thing in the transaction, before any row is read: each
+ * statement in a READ COMMITTED transaction takes a fresh snapshot, so a
+ * select made after the lock sees everything the previous holder committed,
+ * while one made before it sees a world that may already be gone.
+ */
+export async function takeApprovalLock(tx: ApprovalTx, prNumber: number): Promise<void> {
+  // SET takes no bind parameters, so the interval is rendered from a module
+  // constant — never from anything a caller supplies.
+  await tx.execute(sql.raw(`set local lock_timeout = ${APPROVAL_LOCK_TIMEOUT_MS}`));
+  await tx.execute(sql`select pg_advisory_xact_lock_shared(${APPROVAL_LOCK_CLASS}, ${EVERY_REQUEST})`);
+  await tx.execute(sql`select pg_advisory_xact_lock(${APPROVAL_LOCK_CLASS}, ${prNumber})`);
+}
+
+/**
+ * Claim the approvals of EVERY change request for the rest of `tx` — account
+ * erasure, whose rewrite is keyed by a person rather than by a request.
+ *
+ * Exclusive on the every-request key: it waits for every per-request writer in
+ * flight and holds the rest off until the erasure commits. Without it, a
+ * carry-forward that read an approval a moment earlier would re-insert the
+ * erased address onto the new head, after the statement that was supposed to
+ * be the last trace of it.
+ *
+ * Take it BEFORE the statement that anonymizes the rows, not at the top of the
+ * transaction: what it has to cover is that rewrite and everything after it,
+ * and starting later is that many fewer milliseconds of approvals queueing
+ * behind an erasure.
+ */
+export async function takeEveryApprovalLock(tx: ApprovalTx): Promise<void> {
+  await tx.execute(sql.raw(`set local lock_timeout = ${ERASURE_LOCK_TIMEOUT_MS}`));
+  await tx.execute(sql`select pg_advisory_xact_lock(${APPROVAL_LOCK_CLASS}, ${EVERY_REQUEST})`);
+}

package/src/modules/workflow/review-workflow/review-workflow.interface.ts

@@ -8,6 +8,14 @@ import type {
   PullRequestFile,
   PullRequestState,
 } from '@bevel-software/platform-shared';
+import type { ApprovalTx } from './approval-lock.js';
+
+/**
+ * The transaction handle a caller outside this module hands `eraseApprover`.
+ * Re-exported so the caller depends on this contract alone, never on the lock
+ * file behind it.
+ */
+export type { ApprovalTx };
 
 export interface MergeGateInput {
   prNumber: number;
@@ -16,14 +24,19 @@ export interface MergeGateInput {
 }
 
 export interface MergeGateResult {
-  /** False only on hard blocks (PR closed/merged, zero files). Warnings do NOT flip this false. */
+  /** False while any reason remains — a hard block or a missing approval. */
   mergeable: boolean;
-  /** Hard-block reasons — merge cannot proceed until these resolve. */
+  /**
+   * Blocking reasons: hard blocks (PR closed/merged, zero files) followed by
+   * every missing approval. Merge cannot proceed until these resolve, except
+   * that an admin may bypass the missing approvals.
+   */
   reasons: string[];
   /**
-   * Soft warnings — md files with an owner who hasn't approved (or whose
-   * approval is stale). Merge proceeds only when the caller explicitly opts
-   * into bypass; the frontend surfaces these in a confirm dialog.
+   * The missing approvals alone — files of any type with an eligible approver
+   * who hasn't approved (or whose approval is stale). These are the part of
+   * `reasons` an admin may merge past with bypass; the bypassed list is
+   * recorded in the merge commit body.
    */
   warnings: string[];
 }
@@ -119,6 +132,26 @@ export interface IReviewWorkflowService {
     workspaceId: string,
   ): Promise<FileApprovalState[]>;
 
+  /**
+   * Re-pin the per-file approvals a commit did not disturb onto a new head.
+   *
+   * For the merge an update-from-target lands on a proposal's branch: the
+   * approvers did not make that commit, so voiding their approvals over files
+   * whose bytes it never touched would make every automatic update a second
+   * round of review. `changedPaths` is the content verdict — every path that
+   * differs between the two heads — and only a path absent from it keeps its
+   * approval. The approval RULE is unchanged: a row still counts only against
+   * the current head, and the author's own later commit still resets it.
+   *
+   * Idempotent; returns the number of rows written.
+   */
+  carryApprovalsForward(
+    prNumber: number,
+    fromHeadSha: string,
+    toHeadSha: string,
+    changedPaths: string[],
+  ): Promise<number>;
+
   /**
    * Revoke the caller's own approval on one file. Non-author users cannot
    * revoke someone else's approval (403). Idempotent when no matching
@@ -142,6 +175,25 @@ export interface IReviewWorkflowService {
    */
   evaluateMergeGate(input: MergeGateInput): MergeGateResult;
 
+  /**
+   * Rewrite one person out of every approval they ever made, as `erased`.
+   *
+   * Account erasure calls this INSIDE its own transaction (`tx`) rather than
+   * touching the rows itself, because this module owns them and the writers
+   * that race the rewrite are this module's: a reviewer approving or revoking
+   * one file, and a change request copying the approvals its update did not
+   * disturb onto its new head. Both take the approval lock; this takes it
+   * exclusively on every request at once, BEFORE the rewrite, and the caller's
+   * transaction keeps it held until the erasure commits — so a copy that read
+   * the row a moment earlier cannot re-insert the real address onto a new head
+   * after what was supposed to be the last trace of it.
+   *
+   * Bounded (`ERASURE_LOCK_TIMEOUT_MS`): a wedged holder fails the erasure
+   * loudly instead of hanging it, and since the caller's transaction is atomic
+   * a refusal erases nothing — the operator runs it again.
+   */
+  eraseApprover(tx: ApprovalTx, email: string, erased: { email: string; name: string }): Promise<void>;
+
   /**
    * Execute the merge via a local `git merge --no-ff` on the base branch's
    * workspace, pushed to origin (provider-agnostic — no PR API). Re-validates
@@ -167,8 +219,8 @@ export interface IReviewWorkflowService {
     /** Workspace clone — used for the access-tree lookup that gates bypass. */
     workspaceId: string,
     /**
-     * When true, proceed even if soft warnings (unapproved md-with-owner files)
-     * exist. Hard blocks are refused regardless. The bypassed warnings are
+     * When true, proceed even if missing approvals (files of any type with an
+     * eligible approver who hasn't approved) exist. Hard blocks are refused regardless. The bypassed warnings are
      * recorded in the merge commit body for audit. Bypass requires admin
      * write access at `origin/<baseBranch>` (i.e. write on `roles.yaml`) —
      * non-admins get a 403 even when warnings would otherwise be skippable.