@webiny/api-workflows 0.0.0-unstable.a4f3e4ea8b → 0.0.0-unstable.a85ef555b2

package/domain/review/Review.js

@@ -0,0 +1,702 @@
+import { Result } from "@webiny/feature/api";
+import { canPickReviewer } from "../workflow/canPickReviewer.js";
+import { REVIEW_STEP_TYPE } from "../workflow/stepTypes.js";
+import { ReviewActorNotUserError, ReviewAlreadyOwnerError, ReviewInvalidStateError, ReviewNotCandidateError, ReviewNotOwnerError, ReviewRequesterCannotReviewError, ReviewStepNotCurrentError, ReviewStepNotReassignableError, ReviewStepNotTakeableError, ReviewValidationError } from "./errors.js";
+const REQUESTER_OWNER_REASON = "The resolved owner is the requester, who cannot review their own content.";
+const REVIEW_TITLE_MIN_LENGTH = 5;
+const REJECT_COMMENT_MIN_LENGTH = 10;
+class Review {
+    constructor(data){
+        this.data = data;
+        this.facts = [];
+    }
+    static fromData(data) {
+        return new Review(structuredClone(data));
+    }
+    static request(params) {
+        if (!params.workflow.models.includes(params.model)) return Result.fail(new ReviewValidationError(`The workflow "${params.workflow.name}" is not bound to the model "${params.model}".`));
+        if (0 === params.workflow.steps.length) return Result.fail(new ReviewValidationError(`The workflow "${params.workflow.name}" has no steps.`));
+        const requestedTitle = params.requestedTitle?.trim() ?? "";
+        if (requestedTitle && requestedTitle.length < REVIEW_TITLE_MIN_LENGTH) return Result.fail(new ReviewValidationError(`The review title must have at least ${REVIEW_TITLE_MIN_LENGTH} characters.`));
+        const picks = new Map();
+        for (const pick of params.picks){
+            const step = params.workflow.steps.find((item)=>item.id === pick.stepId);
+            if (!step) return Result.fail(new ReviewValidationError(`Step "${pick.stepId}" does not exist in workflow "${params.workflow.name}".`));
+            if (!canPickReviewer(step)) return Result.fail(new ReviewValidationError(`Step "${step.title}" does not allow picking a reviewer.`));
+            if (picks.has(step.id)) return Result.fail(new ReviewValidationError(`Step "${step.title}" has more than one pick.`));
+            picks.set(step.id, pick.userId);
+        }
+        const steps = params.workflow.steps.map((step)=>({
+                ...structuredClone(step),
+                state: "pending",
+                owner: null,
+                comment: null,
+                pickedUserId: picks.get(step.id) ?? null,
+                candidateTeamIds: [],
+                assignmentSource: null,
+                assignment: null,
+                reachedOn: null,
+                startedOn: null,
+                finishedOn: null,
+                taskId: null,
+                runs: [],
+                issues: []
+            }));
+        const review = new Review({
+            id: params.id,
+            workflowId: params.workflow.id,
+            model: params.model,
+            targetId: params.targetId,
+            targetRevisionId: params.targetRevisionId,
+            title: requestedTitle || params.title,
+            isActive: true,
+            state: "inProgress",
+            currentStepId: null,
+            currentStepState: null,
+            currentStepType: null,
+            currentOwnerId: null,
+            currentCandidateTeamIds: [],
+            targetContext: structuredClone(params.targetContext),
+            workflow: {
+                name: params.workflow.name,
+                models: [
+                    ...params.workflow.models
+                ]
+            },
+            steps,
+            createdBy: {
+                ...params.requester
+            },
+            cancelledBy: null,
+            createdOn: params.now,
+            savedOn: params.now,
+            lastChangedOn: params.now
+        });
+        review.facts.push({
+            type: "requested",
+            occurredOn: params.now,
+            actor: {
+                ...params.requester
+            }
+        });
+        return Result.ok(review);
+    }
+    get id() {
+        return this.data.id;
+    }
+    get actionableStepId() {
+        return this.findCurrentStep()?.id ?? null;
+    }
+    toData() {
+        return structuredClone(this.data);
+    }
+    isRequestedBy(actor) {
+        return "user" === actor.type && actor.id === this.data.createdBy.id;
+    }
+    getRunningTaskId() {
+        const step = this.findCurrentStep();
+        if (!step || "inReview" !== step.state) return null;
+        return step.taskId;
+    }
+    getTaskIds() {
+        const taskIds = [];
+        for (const step of this.data.steps){
+            for (const run of step.runs)if (run.taskId) taskIds.push(run.taskId);
+            if (step.taskId) taskIds.push(step.taskId);
+        }
+        return taskIds;
+    }
+    getStepToReach() {
+        if ("inProgress" !== this.data.state) return null;
+        const step = this.findCurrentStep();
+        if (!step || "pending" !== step.state) return null;
+        return structuredClone(step);
+    }
+    reach(params) {
+        const current = this.getCurrentStepIn("reach", "pending");
+        if (current.isFail()) return Result.fail(current.error);
+        const step = current.value;
+        if (step.type !== REVIEW_STEP_TYPE) return Result.fail(this.createInvalidStateError("reach", step));
+        const resolution = this.withoutRequesterOwner(params.resolution);
+        step.candidateTeamIds = [
+            ...resolution.candidateTeamIds
+        ];
+        step.assignment = structuredClone(resolution.assignment);
+        step.assignmentSource = resolution.assignment.source;
+        step.reachedOn = params.now;
+        if (resolution.owner) {
+            step.owner = {
+                ...resolution.owner
+            };
+            step.state = "inReview";
+            step.startedOn = params.now;
+        } else {
+            step.owner = null;
+            step.state = "awaiting";
+        }
+        this.facts.push({
+            type: "stepReached",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            owner: step.owner ? {
+                ...step.owner
+            } : null,
+            change: {
+                stepId: step.id,
+                fromState: "pending",
+                toState: step.state
+            },
+            assignment: structuredClone(resolution.assignment),
+            taskId: null,
+            records: structuredClone(resolution.records)
+        });
+        return Result.ok();
+    }
+    reachRun(params) {
+        const current = this.getCurrentStepIn("reach", "pending");
+        if (current.isFail()) return Result.fail(current.error);
+        const step = current.value;
+        if (step.type === REVIEW_STEP_TYPE) return Result.fail(this.createInvalidStateError("reach", step));
+        step.candidateTeamIds = [];
+        step.assignment = null;
+        step.assignmentSource = null;
+        step.owner = {
+            ...params.owner
+        };
+        step.state = "inReview";
+        step.reachedOn = params.now;
+        step.startedOn = params.now;
+        step.taskId = params.taskId;
+        this.facts.push({
+            type: "stepReached",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            owner: {
+                ...params.owner
+            },
+            change: {
+                stepId: step.id,
+                fromState: "pending",
+                toState: "inReview"
+            },
+            assignment: null,
+            taskId: params.taskId,
+            records: []
+        });
+        return Result.ok();
+    }
+    checkStart(params) {
+        return Review.toCheck(this.guardStart(params));
+    }
+    start(params) {
+        const guard = this.guardStart(params);
+        if (guard.isFail()) return Result.fail(guard.error);
+        const step = guard.value;
+        step.owner = {
+            ...params.actor
+        };
+        step.state = "inReview";
+        step.startedOn = params.now;
+        step.assignmentSource = "poolStart";
+        step.assignment = {
+            source: "poolStart"
+        };
+        this.facts.push({
+            type: "stepStarted",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            change: {
+                stepId: step.id,
+                fromState: "awaiting",
+                toState: "inReview"
+            },
+            records: [
+                {
+                    kind: "outcome",
+                    userId: params.actor.id,
+                    source: "poolStart",
+                    ruleId: null,
+                    by: null,
+                    reason: null
+                }
+            ]
+        });
+        return Result.ok();
+    }
+    checkTakeOver(params) {
+        return Review.toCheck(this.guardTakeOver(params));
+    }
+    takeOver(params) {
+        const guard = this.guardTakeOver(params);
+        if (guard.isFail()) return Result.fail(guard.error);
+        const { step, owner: previousOwner } = guard.value;
+        step.owner = {
+            ...params.actor
+        };
+        step.assignmentSource = "takeOver";
+        step.assignment = {
+            source: "takeOver",
+            by: {
+                ...params.actor
+            }
+        };
+        this.facts.push({
+            type: "stepTakenOver",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            change: {
+                stepId: step.id,
+                fromState: "inReview",
+                toState: "inReview"
+            },
+            previousOwner: {
+                ...previousOwner
+            },
+            notifyPreviousOwner: params.notifyPreviousOwner ?? true,
+            records: [
+                {
+                    kind: "outcome",
+                    userId: params.actor.id,
+                    source: "takeOver",
+                    ruleId: null,
+                    by: {
+                        ...params.actor
+                    },
+                    reason: null
+                }
+            ]
+        });
+        return Result.ok();
+    }
+    checkApprove(params) {
+        return Review.toCheck(this.getOwnedStep("approve", params));
+    }
+    approve(params) {
+        const current = this.getOwnedStep("approve", params);
+        if (current.isFail()) return Result.fail(current.error);
+        const step = current.value;
+        const comment = params.comment?.trim() || null;
+        step.state = "approved";
+        step.comment = comment;
+        step.issues = (params.issues ?? []).map((issue)=>({
+                ...issue
+            }));
+        step.finishedOn = params.now;
+        this.facts.push({
+            type: "stepApproved",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            change: {
+                stepId: step.id,
+                fromState: "inReview",
+                toState: "approved"
+            },
+            comment
+        });
+        if (this.data.steps.every((item)=>"approved" === item.state)) {
+            this.data.state = "approved";
+            this.facts.push({
+                type: "approved",
+                occurredOn: params.now,
+                actor: {
+                    ...params.actor
+                }
+            });
+        }
+        return Result.ok();
+    }
+    checkReject(params) {
+        return Review.toCheck(this.getOwnedStep("reject", params));
+    }
+    reject(params) {
+        const current = this.getOwnedStep("reject", params);
+        if (current.isFail()) return Result.fail(current.error);
+        const comment = params.comment?.trim() ?? "";
+        if (comment.length < REJECT_COMMENT_MIN_LENGTH) return Result.fail(new ReviewValidationError(`A rejection needs a comment of at least ${REJECT_COMMENT_MIN_LENGTH} characters.`));
+        const step = current.value;
+        step.state = "rejected";
+        step.comment = comment;
+        step.issues = (params.issues ?? []).map((issue)=>({
+                ...issue
+            }));
+        step.finishedOn = params.now;
+        this.data.state = "rejected";
+        this.facts.push({
+            type: "stepRejected",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            change: {
+                stepId: step.id,
+                fromState: "inReview",
+                toState: "rejected"
+            },
+            comment
+        });
+        return Result.ok();
+    }
+    checkCancel() {
+        return Review.toCheck(this.guardCancel());
+    }
+    cancel(params) {
+        const guard = this.guardCancel();
+        if (guard.isFail()) return Result.fail(guard.error);
+        const step = guard.value;
+        this.data.state = "cancelled";
+        this.data.cancelledBy = {
+            ...params.actor
+        };
+        this.facts.push({
+            type: "cancelled",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            stepId: step?.id ?? null,
+            stepState: step?.state ?? null,
+            reason: params.reason ?? null
+        });
+        return Result.ok();
+    }
+    checkReassign(params) {
+        return Review.toCheck(this.guardReassign(params));
+    }
+    checkReassignTo(params) {
+        return Review.toCheck(this.guardReassignTo(params));
+    }
+    reassign(params) {
+        const guard = this.guardReassignTo({
+            stepId: params.stepId,
+            userId: params.owner.id
+        });
+        if (guard.isFail()) return Result.fail(guard.error);
+        const step = guard.value;
+        if (this.isRequestedBy(params.owner)) return Result.fail(new ReviewRequesterCannotReviewError({
+            reviewId: this.data.id,
+            stepId: step.id
+        }));
+        const previousOwner = step.owner;
+        const fromState = step.state;
+        step.owner = {
+            ...params.owner
+        };
+        if ("awaiting" === fromState) {
+            step.state = "inReview";
+            step.startedOn = params.now;
+        }
+        step.assignmentSource = "reassign";
+        step.assignment = {
+            source: "reassign",
+            by: {
+                ...params.actor
+            }
+        };
+        this.facts.push({
+            type: "stepReassigned",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            change: {
+                stepId: step.id,
+                fromState,
+                toState: "inReview"
+            },
+            owner: {
+                ...params.owner
+            },
+            previousOwner: previousOwner ? {
+                ...previousOwner
+            } : null,
+            records: [
+                {
+                    kind: "outcome",
+                    userId: params.owner.id,
+                    source: "reassign",
+                    ruleId: null,
+                    by: {
+                        ...params.actor
+                    },
+                    reason: null
+                }
+            ]
+        });
+        return Result.ok();
+    }
+    fail(params) {
+        const guard = this.guardFail(params.stepId);
+        if (guard.isFail()) return Result.fail(guard.error);
+        const step = guard.value;
+        if ("failed" === step.state) return Result.ok();
+        const fromState = step.state;
+        step.state = "failed";
+        step.comment = params.reason;
+        step.finishedOn = params.now;
+        this.facts.push({
+            type: "stepFailed",
+            occurredOn: params.now,
+            actor: {
+                ...step.owner ?? this.data.createdBy
+            },
+            change: {
+                stepId: step.id,
+                fromState,
+                toState: "failed"
+            },
+            reason: params.reason
+        });
+        return Result.ok();
+    }
+    checkRestart(params) {
+        return Review.toCheck(this.guardRestart(params));
+    }
+    restart(params) {
+        const guard = this.guardRestart(params);
+        if (guard.isFail()) return Result.fail(guard.error);
+        const step = guard.value;
+        const previousTaskId = step.taskId;
+        step.runs.push({
+            taskId: step.taskId,
+            startedOn: step.startedOn ?? step.reachedOn ?? step.finishedOn ?? params.now,
+            finishedOn: step.finishedOn,
+            outcome: "failed",
+            reason: step.comment
+        });
+        step.state = "pending";
+        step.comment = null;
+        step.taskId = null;
+        step.issues = [];
+        step.reachedOn = null;
+        step.startedOn = null;
+        step.finishedOn = null;
+        this.facts.push({
+            type: "stepRestarted",
+            occurredOn: params.now,
+            actor: {
+                ...params.actor
+            },
+            change: {
+                stepId: step.id,
+                fromState: "failed",
+                toState: "pending"
+            },
+            previousTaskId
+        });
+        return Result.ok();
+    }
+    prepareForSave() {
+        const lastFact = this.facts[this.facts.length - 1];
+        if (lastFact && Date.parse(lastFact.occurredOn) > Date.parse(this.data.lastChangedOn)) this.data.lastChangedOn = lastFact.occurredOn;
+        const current = this.resolveCurrentStep();
+        if (!current) {
+            this.data.isActive = false;
+            this.data.currentStepId = null;
+            this.data.currentStepState = null;
+            this.data.currentStepType = null;
+            this.data.currentOwnerId = null;
+            this.data.currentCandidateTeamIds = [];
+            return;
+        }
+        this.data.isActive = true;
+        this.data.state = Review.deriveState(current);
+        this.data.currentStepId = current.id;
+        this.data.currentStepState = current.state;
+        this.data.currentStepType = current.type;
+        this.data.currentOwnerId = current.owner?.type === "user" ? current.owner.id : null;
+        this.data.currentCandidateTeamIds = [
+            ...current.candidateTeamIds
+        ];
+    }
+    getSystemWorkflow() {
+        const current = this.resolveCurrentStep();
+        if (!current) return null;
+        return {
+            workflowId: this.data.workflowId,
+            reviewState: Review.deriveState(current),
+            stepId: current.id,
+            stepName: current.title,
+            stepState: current.state
+        };
+    }
+    pullFacts() {
+        return this.facts.splice(0, this.facts.length);
+    }
+    guardStart(params) {
+        const current = this.getRequestedStepIn("start", "awaiting", params.stepId);
+        if (current.isFail()) return Result.fail(current.error);
+        const step = current.value;
+        const reviewer = this.checkReviewer(step, params);
+        if (reviewer.isFail()) return Result.fail(reviewer.error);
+        return Result.ok(step);
+    }
+    guardTakeOver(params) {
+        const current = this.getRequestedStepIn("takeOver", "inReview", params.stepId);
+        if (current.isFail()) return Result.fail(current.error);
+        const step = current.value;
+        const owner = step.owner;
+        if (!owner || "user" !== owner.type) return Result.fail(new ReviewStepNotTakeableError({
+            reviewId: this.data.id,
+            stepId: step.id,
+            ownerType: owner?.type ?? null
+        }));
+        const reviewer = this.checkReviewer(step, params);
+        if (reviewer.isFail()) return Result.fail(reviewer.error);
+        if (owner.id === params.actor.id) return Result.fail(new ReviewAlreadyOwnerError({
+            reviewId: this.data.id,
+            stepId: step.id
+        }));
+        return Result.ok({
+            step,
+            owner
+        });
+    }
+    guardCancel() {
+        const step = this.findCurrentStep();
+        if ("inProgress" !== this.data.state) return Result.fail(this.createInvalidStateError("cancel", step));
+        return Result.ok(step);
+    }
+    guardReassign(params) {
+        const awaiting = this.getRequestedStepIn("reassign", "awaiting", params.stepId);
+        if (awaiting.isOk()) return Result.ok(awaiting.value);
+        const inReview = this.getRequestedStepIn("reassign", "inReview", params.stepId);
+        if (inReview.isFail()) return Result.fail(inReview.error);
+        const step = inReview.value;
+        if (step.owner?.type !== "user") return Result.fail(new ReviewStepNotReassignableError({
+            reviewId: this.data.id,
+            stepId: step.id,
+            ownerType: step.owner?.type ?? null
+        }));
+        return Result.ok(step);
+    }
+    guardReassignTo(params) {
+        const guard = this.guardReassign(params);
+        if (guard.isFail()) return Result.fail(guard.error);
+        const step = guard.value;
+        if (step.owner?.type === "user" && step.owner.id === params.userId) return Result.fail(new ReviewAlreadyOwnerError({
+            reviewId: this.data.id,
+            stepId: step.id
+        }));
+        return Result.ok(step);
+    }
+    guardFail(stepId) {
+        const step = this.findCurrentStep();
+        if ("inProgress" === this.data.state && step && step.id !== stepId) return Result.fail(new ReviewStepNotCurrentError({
+            reviewId: this.data.id,
+            stepId,
+            currentStepId: step.id
+        }));
+        const failable = step?.state === "pending" || step?.state === "inReview" || step?.state === "failed";
+        if ("inProgress" !== this.data.state || !step || !failable) return Result.fail(this.createInvalidStateError("fail", step));
+        return Result.ok(step);
+    }
+    guardRestart(params) {
+        return this.getRequestedStepIn("restart", "failed", params.stepId);
+    }
+    static toCheck(guard) {
+        if (guard.isFail()) return Result.fail(guard.error);
+        return Result.ok();
+    }
+    findCurrentStep() {
+        return this.data.steps.find((step)=>"approved" !== step.state) ?? null;
+    }
+    getCurrentStepIn(transition, stepState) {
+        const step = this.findCurrentStep();
+        if ("inProgress" !== this.data.state || !step || step.state !== stepState) return Result.fail(this.createInvalidStateError(transition, step));
+        return Result.ok(step);
+    }
+    createInvalidStateError(transition, step) {
+        return new ReviewInvalidStateError({
+            reviewId: this.data.id,
+            transition,
+            reviewState: this.data.state,
+            stepId: step?.id ?? null,
+            stepState: step?.state ?? null
+        });
+    }
+    getRequestedStepIn(transition, stepState, stepId) {
+        const current = this.findCurrentStep();
+        if ("inProgress" === this.data.state && current && current.id !== stepId) return Result.fail(new ReviewStepNotCurrentError({
+            reviewId: this.data.id,
+            stepId,
+            currentStepId: current.id
+        }));
+        return this.getCurrentStepIn(transition, stepState);
+    }
+    withoutRequesterOwner(resolution) {
+        const owner = resolution.owner;
+        if (!owner || !this.isRequestedBy(owner)) return resolution;
+        return {
+            owner: null,
+            candidateTeamIds: [
+                ...resolution.candidateTeamIds
+            ],
+            assignment: {
+                source: "pool",
+                reason: REQUESTER_OWNER_REASON
+            },
+            records: [
+                ...resolution.records.filter((record)=>"skip" === record.kind),
+                {
+                    kind: "outcome",
+                    userId: null,
+                    source: "pool",
+                    ruleId: null,
+                    by: null,
+                    reason: REQUESTER_OWNER_REASON
+                }
+            ]
+        };
+    }
+    resolveCurrentStep() {
+        if ("cancelled" === this.data.state) return null;
+        return this.findCurrentStep() ?? this.data.steps.at(-1) ?? null;
+    }
+    getOwnedStep(transition, params) {
+        const current = this.getRequestedStepIn(transition, "inReview", params.stepId);
+        if (current.isFail()) return Result.fail(current.error);
+        const step = current.value;
+        const actor = params.actor;
+        const owner = step.owner;
+        if (!owner || owner.type !== actor.type || owner.id !== actor.id) return Result.fail(new ReviewNotOwnerError({
+            reviewId: this.data.id,
+            stepId: step.id
+        }));
+        return Result.ok(step);
+    }
+    static deriveState(current) {
+        if ("rejected" === current.state) return "rejected";
+        if ("approved" === current.state) return "approved";
+        return "inProgress";
+    }
+    checkReviewer(step, params) {
+        if ("user" !== params.actor.type) return Result.fail(new ReviewActorNotUserError({
+            reviewId: this.data.id,
+            stepId: step.id,
+            actorType: params.actor.type
+        }));
+        if (this.isRequestedBy(params.actor)) return Result.fail(new ReviewRequesterCannotReviewError({
+            reviewId: this.data.id,
+            stepId: step.id
+        }));
+        const isCandidate = params.actorTeamIds.some((teamId)=>step.candidateTeamIds.includes(teamId));
+        if (!isCandidate) return Result.fail(new ReviewNotCandidateError({
+            reviewId: this.data.id,
+            stepId: step.id
+        }));
+        return Result.ok();
+    }
+}
+export { REJECT_COMMENT_MIN_LENGTH, REVIEW_TITLE_MIN_LENGTH, Review };
+
+//# sourceMappingURL=Review.js.map