From 4888025390ce97f3c1e3bf0dbb931bb45d6b5be9 Mon Sep 17 00:00:00 2001 From: kiannidev <156195510+kiannidev@users.noreply.github.com> Date: Sun, 5 Jul 2026 18:45:14 +0200 Subject: [PATCH] feat(engine): add isPlanBlocked plan DAG helper Pure deadlock predicate mirroring planProgress blocked status for miner and dashboard progress summaries. Co-authored-by: Cursor --- packages/gittensory-engine/README.md | 1 + packages/gittensory-engine/src/index.ts | 1 + .../gittensory-engine/src/plan-blocked.ts | 26 ++++++ test/unit/plan-blocked.test.ts | 90 +++++++++++++++++++ 4 files changed, 118 insertions(+) create mode 100644 packages/gittensory-engine/src/plan-blocked.ts create mode 100644 test/unit/plan-blocked.test.ts diff --git a/packages/gittensory-engine/README.md b/packages/gittensory-engine/README.md index be54700a5c..0488b037ea 100644 --- a/packages/gittensory-engine/README.md +++ b/packages/gittensory-engine/README.md @@ -536,6 +536,7 @@ dashboard progress summaries: - `hasPlanRunningSteps(plan)` — any step is `running` - `hasPlanSkippedSteps(plan)` — any step is `skipped` - `hasPlanCompletedSteps(plan)` — any step is `completed` +- `isPlanBlocked(plan)` — pending steps remain but none are runnable (deadlock; mirrors `planProgress`'s `blocked` status) ## Opportunity competition diff --git a/packages/gittensory-engine/src/index.ts b/packages/gittensory-engine/src/index.ts index 9c926fd903..cd0b25a1b5 100644 --- a/packages/gittensory-engine/src/index.ts +++ b/packages/gittensory-engine/src/index.ts @@ -146,6 +146,7 @@ export { hasPlanPendingSteps } from "./plan-pending.js"; export { hasPlanRunningSteps } from "./plan-running.js"; export { hasPlanSkippedSteps } from "./plan-skipped.js"; export { hasPlanCompletedSteps } from "./plan-completed.js"; +export { isPlanBlocked } from "./plan-blocked.js"; export * from "./plan-templates.js"; export * from "./portfolio/queue.js"; export { diff --git a/packages/gittensory-engine/src/plan-blocked.ts b/packages/gittensory-engine/src/plan-blocked.ts new file mode 100644 index 0000000000..f2fd3b65e2 --- /dev/null +++ b/packages/gittensory-engine/src/plan-blocked.ts @@ -0,0 +1,26 @@ +import type { PlanDag, PlanStep, PlanStepStatus } from "./plan-export.js"; + +const isDone = (status: PlanStepStatus): boolean => status === "completed" || status === "skipped"; + +function nextReadySteps(plan: PlanDag): PlanStep[] { + const statusById = new Map(plan.steps.map((step) => [step.id, step.status])); + return plan.steps.filter( + (step) => step.status === "pending" && step.dependsOn.every((dep) => isDone(statusById.get(dep) ?? "pending")), + ); +} + +/** + * Return whether the plan is deadlocked: pending steps remain but none are runnable. Mirrors the `blocked` + * branch of hosted `planProgress` — failed or running plans are not considered blocked. Pure. + */ +export function isPlanBlocked(plan: PlanDag): boolean { + const total = plan.steps.length; + if (total === 0) return false; + const completed = plan.steps.filter((step) => step.status === "completed").length; + const skipped = plan.steps.filter((step) => step.status === "skipped").length; + if (completed + skipped === total) return false; + if (plan.steps.some((step) => step.status === "failed")) return false; + if (plan.steps.some((step) => step.status === "running")) return false; + const pending = plan.steps.some((step) => step.status === "pending"); + return pending && nextReadySteps(plan).length === 0; +} diff --git a/test/unit/plan-blocked.test.ts b/test/unit/plan-blocked.test.ts new file mode 100644 index 0000000000..00fb5685e4 --- /dev/null +++ b/test/unit/plan-blocked.test.ts @@ -0,0 +1,90 @@ +import { describe, expect, it } from "vitest"; + +import { isPlanBlocked } from "../../packages/gittensory-engine/src/plan-blocked"; +import type { PlanStep } from "../../packages/gittensory-engine/src/plan-export"; + +function step(over: Partial & { id: string; title: string }): PlanStep { + return { + actionClass: undefined, + dependsOn: [], + status: "pending", + attempts: 0, + maxAttempts: 3, + lastError: null, + ...over, + }; +} + +describe("isPlanBlocked", () => { + it("returns false for an empty plan", () => { + expect(isPlanBlocked({ steps: [] })).toBe(false); + }); + + it("returns false when pending steps are still runnable", () => { + expect( + isPlanBlocked({ + steps: [ + step({ id: "a", title: "Build", status: "pending" }), + step({ id: "b", title: "Test", status: "pending", dependsOn: ["a"] }), + ], + }), + ).toBe(false); + }); + + it("returns true for a cyclic deadlock with no ready steps", () => { + expect( + isPlanBlocked({ + steps: [ + step({ id: "a", title: "A", dependsOn: ["b"] }), + step({ id: "b", title: "B", dependsOn: ["a"] }), + ], + }), + ).toBe(true); + }); + + it("returns false when a step failed (failed takes precedence over blocked)", () => { + expect( + isPlanBlocked({ + steps: [ + step({ id: "a", title: "A", dependsOn: ["b"], status: "failed" }), + step({ id: "b", title: "B", dependsOn: ["a"] }), + ], + }), + ).toBe(false); + }); + + it("returns false when a step is running", () => { + expect( + isPlanBlocked({ + steps: [ + step({ id: "a", title: "A", dependsOn: ["b"], status: "running" }), + step({ id: "b", title: "B", dependsOn: ["a"] }), + ], + }), + ).toBe(false); + }); + + it("returns false when every step is completed or skipped", () => { + expect( + isPlanBlocked({ + steps: [ + step({ id: "a", title: "Build", status: "completed" }), + step({ id: "b", title: "Deploy", status: "skipped" }), + ], + }), + ).toBe(false); + }); + + it("is exported from the package barrel", async () => { + const barrel = await import("../../packages/gittensory-engine/src/index"); + expect(typeof barrel.isPlanBlocked).toBe("function"); + expect( + barrel.isPlanBlocked({ + steps: [ + step({ id: "a", title: "A", dependsOn: ["b"] }), + step({ id: "b", title: "B", dependsOn: ["a"] }), + ], + }), + ).toBe(true); + }); +});