@danypops/papyrus 0.1.0 → 0.2.0

package/src/task-service.ts

@@ -1,8 +1,10 @@
+import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
 import { validateChecklist, type Checklist } from "./domain/checklist.ts";
 import type { Gate, GateResult } from "./domain/gate.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import type { GateRunner } from "./ports/gate-runner.ts";
+import { assertDependencyEdgeAllowed } from "./task-execution.ts";
 
 export interface TaskFilter {
 	status?: string;
@@ -25,10 +27,17 @@ export interface CreateTaskInput {
 
 export type TaskTransition = "start" | "fail" | "retry";
 
+export interface TaskBlockage {
+	artifact: Artifact;
+	dependencyIds: string[];
+}
+
 export interface TaskCompletion {
 	artifact: Artifact;
 	gates: GateResult[];
 	completed: boolean;
+	started: Artifact[];
+	blocked: TaskBlockage[];
 }
 
 export interface TaskNode {
@@ -63,6 +72,9 @@ export class Tasks {
 	}
 
 	create(input: CreateTaskInput): Artifact {
+		if ((input.dependsOn?.length ?? 0) > TASK_EXECUTION_MAX_DEGREE) {
+			throw new Error(`task cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+		}
 		if (input.parentId) this.require(input.parentId);
 		for (const dependency of input.dependsOn ?? []) this.require(dependency);
 		const extra: Record<string, unknown> = { ...(input.extra ?? {}) };
@@ -87,7 +99,14 @@ export class Tasks {
 	}
 
 	graph(filter: TaskFilter = {}): TaskGraph {
-		const tasks = this.list(filter);
+		const requestedLimit = filter.limit ?? TASK_EXECUTION_MAX_NODES + 1;
+		if (!Number.isInteger(requestedLimit) || requestedLimit < 1 || requestedLimit > TASK_EXECUTION_MAX_NODES + 1) {
+			throw new Error(`task graph limit must be between 1 and ${TASK_EXECUTION_MAX_NODES + 1}`);
+		}
+		const tasks = this.list({ ...filter, limit: requestedLimit });
+		if (tasks.length > TASK_EXECUTION_MAX_NODES) {
+			throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
+		}
 		const byId = new Map(tasks.map((task) => [task.id, task]));
 		const nodes = new Map(tasks.map((task) => [task.id, {
 			task,
@@ -95,7 +114,15 @@ export class Tasks {
 			childIds: [] as string[],
 			dependencyIds: [] as string[],
 		}]));
-		for (const edge of this.artifacts.relationships({ kind: "task", artifactIds: [...byId.keys()] })) {
+		const relationships = this.artifacts.relationships({
+			kind: "task",
+			artifactIds: [...byId.keys()],
+			limit: TASK_EXECUTION_MAX_EDGES + 1,
+		});
+		if (relationships.length > TASK_EXECUTION_MAX_EDGES) {
+			throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_EDGES} relationships`);
+		}
+		for (const edge of relationships) {
 			if (!byId.has(edge.from) || !byId.has(edge.to)) continue;
 			const parentId = edge.relation === "contains" ? edge.from : edge.relation === "part_of" ? edge.to : undefined;
 			const childId = edge.relation === "contains" ? edge.to : edge.relation === "part_of" ? edge.from : undefined;
@@ -125,22 +152,30 @@ export class Tasks {
 		const task = this.require(id);
 		const transition = TASK_TRANSITIONS[action];
 		if (!transition.from.includes(task.status)) throw new Error(`cannot ${action} task from ${task.status}`);
+		if (action === "start") {
+			const blocking = this.dependencyIds(id).filter((dependencyId) => this.require(dependencyId).status !== "done");
+			if (blocking.length > 0) throw new Error(`task "${id}" is blocked by dependencies: ${blocking.join(", ")}`);
+		}
 		return this.artifacts.setStatus(id, transition.to)!;
 	}
 
 	complete(id: string): TaskCompletion {
 		const task = this.requireActive(id);
 		const results = this.gates.run(id);
-		if (results.some((gate) => !gate.passed)) return { artifact: task, gates: results, completed: false };
-		return { artifact: this.artifacts.setStatus(id, "done")!, gates: results, completed: true };
+		if (results.some((gate) => !gate.passed)) {
+			return { artifact: task, gates: results, completed: false, started: [], blocked: [] };
+		}
+		return this.finish(id, results);
 	}
 
 	async completeAsync(id: string): Promise<TaskCompletion> {
 		this.requireActive(id);
 		const results = await this.gates.runAsync(id);
-		if (results.some((gate) => !gate.passed)) return { artifact: this.require(id), gates: results, completed: false };
+		if (results.some((gate) => !gate.passed)) {
+			return { artifact: this.require(id), gates: results, completed: false, started: [], blocked: [] };
+		}
 		const current = this.requireActive(id);
-		return { artifact: this.artifacts.setStatus(current.id, "done")!, gates: results, completed: true };
+		return this.finish(current.id, results);
 	}
 
 	runGates(id: string): Promise<GateResult[]> {
@@ -156,6 +191,17 @@ export class Tasks {
 	depend(id: string, dependencyId: string): Artifact {
 		this.require(id);
 		this.require(dependencyId);
+		const graph = this.graph();
+		assertDependencyEdgeAllowed(graph, id, dependencyId);
+		const node = graph.nodes.find((entry) => entry.task.id === id)!;
+		if (node.dependencyIds.includes(dependencyId)) return this.show(id);
+		if (node.dependencyIds.length >= TASK_EXECUTION_MAX_DEGREE) {
+			throw new Error(`task "${id}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+		}
+		const successorCount = graph.nodes.filter((entry) => entry.dependencyIds.includes(dependencyId)).length;
+		if (successorCount >= TASK_EXECUTION_MAX_DEGREE) {
+			throw new Error(`task "${dependencyId}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} successors`);
+		}
 		this.artifacts.link({ from: id, relation: "depends_on", to: dependencyId });
 		return this.show(id);
 	}
@@ -168,6 +214,52 @@ export class Tasks {
 		return this.show(parentId);
 	}
 
+	private relationships(id: string) {
+		const relationships = this.artifacts.relationships({
+			kind: "task",
+			artifactIds: [id],
+			limit: TASK_EXECUTION_MAX_EDGES + 1,
+		});
+		if (relationships.length > TASK_EXECUTION_MAX_EDGES) {
+			throw new Error(`task "${id}" exceeds ${TASK_EXECUTION_MAX_EDGES} relationships`);
+		}
+		return relationships;
+	}
+
+	private dependencyIds(id: string): string[] {
+		const ids = this.relationships(id)
+			.filter((edge) => edge.relation === "depends_on" && edge.from === id)
+			.map((edge) => edge.to);
+		if (ids.length > TASK_EXECUTION_MAX_DEGREE) {
+			throw new Error(`task "${id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+		}
+		return ids;
+	}
+
+	private finish(id: string, gates: GateResult[]): TaskCompletion {
+		const successorIds = this.relationships(id)
+			.filter((edge) => edge.relation === "depends_on" && edge.to === id)
+			.map((edge) => edge.from);
+		if (successorIds.length > TASK_EXECUTION_MAX_DEGREE) {
+			throw new Error(`task "${id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} successors`);
+		}
+		const artifact = this.artifacts.setStatus(id, "done")!;
+		const started: Artifact[] = [];
+		const blocked: TaskBlockage[] = [];
+		for (const successorId of successorIds) {
+			const successor = this.require(successorId);
+			if (successor.status !== "pending") continue;
+			const dependencyIds = this.dependencyIds(successorId)
+				.filter((dependencyId) => this.require(dependencyId).status !== "done");
+			if (dependencyIds.length > 0) {
+				blocked.push({ artifact: successor, dependencyIds });
+				continue;
+			}
+			started.push(this.artifacts.setStatus(successorId, "active")!);
+		}
+		return { artifact, gates, completed: true, started, blocked };
+	}
+
 	private requireActive(id: string): Artifact {
 		const task = this.require(id);
 		if (task.status !== "active") throw new Error(`cannot complete task from ${task.status}`);

package/src/version.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+
+function packageVersion(): string {
+	const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as unknown;
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+		throw new Error("Papyrus package manifest must be an object");
+	}
+	const version = (manifest as Record<string, unknown>)["version"];
+	if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+		throw new Error("Papyrus package manifest has an invalid version");
+	}
+	return version;
+}
+
+/** Runtime package version; package.json is the single release source of truth. */
+export const VERSION = packageVersion();