@bevel-software/platform-core-backend 0.1.0

package/dist/modules/workflow/review-workflow/review-workflow.interface.d.ts

@@ -0,0 +1,137 @@
+import type { AuthUser, CancelPrResult, FileApprovalState, MergePrResult, PostPrCommentInput, PrReviewComment, PullRequestFile, PullRequestState } from '@bevel-software/platform-shared';
+export interface MergeGateInput {
+    prNumber: number;
+    state: PullRequestState;
+    approvals: FileApprovalState[];
+}
+export interface MergeGateResult {
+    /** False only on hard blocks (PR closed/merged, zero files). Warnings do NOT flip this false. */
+    mergeable: boolean;
+    /** Hard-block reasons — merge cannot proceed until these resolve. */
+    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.
+     */
+    warnings: string[];
+}
+/**
+ * Owns the Bevel-side review state for a PR: comments (phase 2), per-file
+ * approvals (phase 3), and the merge gate (phase 4). GitHub stays authoritative
+ * for the diff + eventual merge; everything in this interface is in-app state
+ * the team uses to decide whether the merge should fire.
+ */
+export interface IReviewWorkflowService {
+    /** List all comments for a PR, oldest first. */
+    listComments(prNumber: number): Promise<PrReviewComment[]>;
+    /** Post a new comment. Shape of `input` decides whether it's general, file-level, or inline. */
+    postComment(prNumber: number, user: AuthUser, input: PostPrCommentInput, headSha: string): Promise<PrReviewComment>;
+    /**
+     * Edit an existing comment. Only the original author may edit — 403 otherwise.
+     * `prNumber` scopes the lookup so a caller can't touch a comment from a
+     * different PR via a guessed id; the comment must belong to this PR.
+     */
+    editComment(commentId: string, prNumber: number, user: AuthUser, body: string): Promise<PrReviewComment>;
+    /**
+     * Delete a comment. Only the original author may delete — 403 otherwise.
+     * Replies are preserved (orphaned to the thread root). `prNumber` scopes the
+     * lookup so a caller can't cross PRs via a guessed id.
+     */
+    deleteComment(commentId: string, prNumber: number, user: AuthUser): Promise<void>;
+    /**
+     * Compose the per-file approval state for a PR detail response. Resolves
+     * the eligible approver set against **the PR's base branch on origin**
+     * (e.g. `origin/current-company-state`), then joins approval rows from
+     * the DB, marking stale approvals and flagging self-approvals.
+     *
+     * Why base, not head: the PR's head can carry arbitrary edits to
+     * `roles.yaml` or `access.md`, so resolving against head would let a PR
+     * author grant themselves approval rights by editing access config in
+     * their own branch. The base is fast-forward-only (protected branches
+     * are gated by their own PR review), so it's the authoritative source
+     * for "who has write access to this path right now."
+     *
+     * `workspaceId` is optional. When omitted (or when the access lookup
+     * fails — e.g. the workspace hasn't fetched `origin/<base>` yet), the
+     * result is still one `FileApprovalState` per input file but with empty
+     * eligibility. Downstream the merge gate treats empty-eligibility entries
+     * as silent (outside the gate), so a missing workspace degrades to
+     * "PR detail renders, approval gating unavailable" rather than a hard
+     * failure.
+     */
+    getApprovalStates(prNumber: number, files: PullRequestFile[], headSha: string, baseBranch: string, prAuthorIdHash: string | null, workspaceId?: string, 
+    /**
+     * Email of the user viewing the PR. When provided, each returned state
+     * carries `viewerCanApprove` populated from the access tree at
+     * `origin/<baseBranch>`. Omitted (or absent workspace) → `viewerCanApprove`
+     * defaults to `false` everywhere.
+     */
+    viewerEmail?: string): Promise<FileApprovalState[]>;
+    /**
+     * Approve one file. Requires the caller to hold `write` on the path per
+     * the access tree on `origin/<baseBranch>` (403 otherwise). Idempotent —
+     * approving twice on the same headSha is a no-op. Returns the fresh
+     * composite state for all files.
+     */
+    approveFile(prNumber: number, path: string, user: AuthUser, files: PullRequestFile[], headSha: string, baseBranch: string, prAuthorIdHash: string | null, workspaceId: string): Promise<FileApprovalState[]>;
+    /**
+     * Revoke the caller's own approval on one file. Non-author users cannot
+     * revoke someone else's approval (403). Idempotent when no matching
+     * approval exists.
+     */
+    unapproveFile(prNumber: number, path: string, user: AuthUser, files: PullRequestFile[], headSha: string, baseBranch: string, prAuthorIdHash: string | null, workspaceId: string): Promise<FileApprovalState[]>;
+    /**
+     * Pure derivation of the merge gate from PR state + per-file approvals.
+     * Exposed as a method (not a free function) so the HTTP response and the
+     * merge route re-validate via the same code path.
+     */
+    evaluateMergeGate(input: MergeGateInput): MergeGateResult;
+    /**
+     * 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
+     * the gate server-side first (don't trust the caller's cached
+     * `mergeableInBevel`), writes a row to `pr_merge_log` bracketing the attempt,
+     * flips the `change_requests` row to `merged`, and tags the merge commit with
+     * the real triggerer so the audit trail lives on the commit. Conflicts throw
+     * `ChangeRequestConflictsError` (409) with the conflicting paths.
+     *
+     * **Merge authority invariant**: this method is the *only* backend code path
+     * that lands a change request on a protected branch.
+     */
+    mergePr(prNumber: number, user: AuthUser, 
+    /** Fresh detail fetched within the request — used for the gate and the head SHA. */
+    headSha: string, approvals: FileApprovalState[], state: PullRequestState, prTitle: string, 
+    /** The PR's base branch — used to resolve admin status at `origin/<base>` for bypass. */
+    baseBranch: string, 
+    /** 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
+     * 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.
+     */
+    opts?: {
+        bypass?: boolean;
+    }): Promise<MergePrResult>;
+    /**
+     * Close a change request without merging — flips the `change_requests` row to
+     * `closed` (guarded on `state = 'open'`). Authorized when the caller is the PR
+     * author (hash-matched against `authorIdHash`) OR an admin on the base branch
+     * (write on `roles.yaml` at `origin/<baseBranch>` — the same predicate
+     * `mergePr`'s bypass uses). Refused with 422 when the CR is already merged or
+     * closed. The source branch is left intact.
+     */
+    cancelPr(prNumber: number, user: AuthUser, 
+    /** The PR's current state per a fresh `getPrDetail` fetch. */
+    state: PullRequestState, 
+    /** Hash of the PR-author email from the body marker — null when absent. */
+    authorIdHash: string | null, 
+    /** The PR's base branch — used to resolve admin authority at `origin/<base>`. */
+    baseBranch: string, 
+    /** Workspace clone — used for the access-tree lookup that gates admin authority. */
+    workspaceId: string): Promise<CancelPrResult>;
+}
+//# sourceMappingURL=review-workflow.interface.d.ts.map

package/dist/modules/workflow/review-workflow/review-workflow.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-workflow.interface.d.ts","sourceRoot":"","sources":["../../../../src/modules/workflow/review-workflow/review-workflow.interface.ts"],"names":[],"mappings":"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"}

package/dist/modules/workflow/review-workflow/review-workflow.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=review-workflow.interface.js.map

package/dist/modules/workflow/review-workflow/review-workflow.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-workflow.interface.js","sourceRoot":"","sources":["../../../../src/modules/workflow/review-workflow/review-workflow.interface.ts"],"names":[],"mappings":""}

package/dist/modules/workflow/review-workflow/review-workflow.service.d.ts

@@ -0,0 +1,26 @@
+import type { AuthUser, CancelPrResult, FileApprovalState, MergePrResult, PostPrCommentInput, PrReviewComment, PullRequestFile, PullRequestState } from '@bevel-software/platform-shared';
+import type { Database } from '../../database/connection.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { GitService } from '../git/git.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IReviewWorkflowService, MergeGateInput, MergeGateResult } from './review-workflow.interface.js';
+export declare class ReviewWorkflowService implements IReviewWorkflowService {
+    private readonly db;
+    private readonly accessControl;
+    private readonly workspaceService;
+    private readonly git;
+    constructor(db: Database, accessControl: IAccessControl, workspaceService: WorkspaceService, git: GitService);
+    listComments(prNumber: number): Promise<PrReviewComment[]>;
+    postComment(prNumber: number, user: AuthUser, input: PostPrCommentInput, headSha: string): Promise<PrReviewComment>;
+    editComment(commentId: string, prNumber: number, user: AuthUser, body: string): Promise<PrReviewComment>;
+    deleteComment(commentId: string, prNumber: number, user: AuthUser): Promise<void>;
+    getApprovalStates(prNumber: number, files: PullRequestFile[], headSha: string, baseBranch: string, prAuthorIdHash: string | null, workspaceId?: string, viewerEmail?: string): Promise<FileApprovalState[]>;
+    approveFile(prNumber: number, path: string, user: AuthUser, files: PullRequestFile[], headSha: string, baseBranch: string, prAuthorIdHash: string | null, workspaceId: string): Promise<FileApprovalState[]>;
+    evaluateMergeGate(input: MergeGateInput): MergeGateResult;
+    mergePr(prNumber: number, user: AuthUser, headSha: string, approvals: FileApprovalState[], state: PullRequestState, prTitle: string, baseBranch: string, workspaceId: string, opts?: {
+        bypass?: boolean;
+    }): Promise<MergePrResult>;
+    cancelPr(prNumber: number, user: AuthUser, state: PullRequestState, authorIdHash: string | null, baseBranch: string, workspaceId: string): Promise<CancelPrResult>;
+    unapproveFile(prNumber: number, path: string, user: AuthUser, files: PullRequestFile[], headSha: string, baseBranch: string, prAuthorIdHash: string | null, workspaceId: string): Promise<FileApprovalState[]>;
+}
+//# sourceMappingURL=review-workflow.service.d.ts.map

package/dist/modules/workflow/review-workflow/review-workflow.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-workflow.service.d.ts","sourceRoot":"","sources":["../../../../src/modules/workflow/review-workflow/review-workflow.service.ts"],"names":[],"mappings":"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"}