trekoon 0.2.6 → 0.2.7

package/src/commands/task.ts

@@ -20,19 +20,14 @@ import { unexpectedFailureResult } from "./error-utils";
 import {
   buildTaskReadiness,
   DEFAULT_OPEN_TASK_STATUSES,
-  type DependencyBlocker,
-  READY_REASON_BLOCKED,
-  READY_REASON_READY,
-  type ReadyReason,
   taskStatusPriority,
   type TaskReadinessResult,
-  type TaskReadinessSummary,
   type TaskReadyCandidate,
 } from "./task-readiness";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
-import { type CompactBatchResultContract, type CompactTaskSpec, type SearchEntityMatch, type TaskRecord } from "../domain/types";
+import { type CompactBatchResultContract, type CompactTaskSpec, type SearchEntityMatch, type StatusCascadePlan, type TaskRecord } from "../domain/types";
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
@@ -45,9 +40,14 @@ function formatTask(task: TaskRecord): string {
 const VIEW_MODES = ["table", "compact", "tree", "detail"] as const;
 const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_TASK_LIST_LIMIT = 10;
+const CREATE_OPTIONS = ["epic", "e", "title", "t", "description", "d", "status", "s"] as const;
+const LIST_OPTIONS = ["epic", "e", "status", "s", "limit", "l", "cursor", "all", "view"] as const;
+const SHOW_OPTIONS = ["view", "all"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["epic", "e", "task"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "t"] as const;
+const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
@@ -185,6 +185,44 @@ function appendLine(existing: string, line: string): string {
   return existing.length > 0 ? `${existing}\n${line}` : line;
 }
 
+function isStatusCascadeUpdateStatus(status: string | undefined): status is (typeof STATUS_CASCADE_UPDATE_STATUSES)[number] {
+  return status === "done" || status === "todo";
+}
+
+function buildStatusCascadeData(plan: StatusCascadePlan): Record<string, unknown> {
+  return {
+    mode: "descendants",
+    root: {
+      kind: plan.rootKind,
+      id: plan.rootId,
+    },
+    targetStatus: plan.targetStatus,
+    atomic: plan.atomic,
+    changedIds: plan.changedIds,
+    unchangedIds: plan.unchangedIds,
+    counts: plan.counts,
+  };
+}
+
+function formatStatusCascadeHuman(entityLabel: string, plan: StatusCascadePlan): string {
+  return `Cascade updated ${entityLabel} ${plan.rootId} to ${plan.targetStatus} (${plan.counts.changed} changed, ${plan.counts.unchanged} unchanged; tasks=${plan.counts.changedTasks}, subtasks=${plan.counts.changedSubtasks})`;
+}
+
+function failCascadeStatusUpdate(command: string, entityLabel: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: `${entityLabel} descendant cascade requires --status done or --status todo and does not support --append, --description, or --title.`,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message: `${entityLabel} descendant cascade requires status-only done/todo mode`,
+    },
+  });
+}
+
 function formatTaskListTable(tasks: readonly TaskRecord[]): string {
   const rows = tasks.map((task) => [task.id, task.epicId, task.title, task.status]);
   return formatHumanTable(["ID", "EPIC", "TITLE", "STATUS"], rows, { wrapColumns: [2] });
@@ -426,6 +464,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
 
     switch (subcommand) {
       case "create": {
+        const createUnknownOption = findUnknownOption(parsed, CREATE_OPTIONS);
+        if (createUnknownOption !== undefined) {
+          return unknownOption("task.create", createUnknownOption, CREATE_OPTIONS);
+        }
+
+        const unexpectedCreatePositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedCreatePositionals.length > 0) {
+          return failUnexpectedPositionals("task.create", unexpectedCreatePositionals);
+        }
+
         const missingCreateOption =
           readMissingOptionValue(parsed.missingOptionValues, "epic", "e") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
@@ -502,6 +550,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         });
       }
       case "list": {
+        const listUnknownOption = findUnknownOption(parsed, LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("task.list", listUnknownOption, LIST_OPTIONS);
+        }
+
+        const unexpectedListPositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedListPositionals.length > 0) {
+          return failUnexpectedPositionals("task.list", unexpectedListPositionals);
+        }
+
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "view") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
@@ -660,6 +718,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         });
       }
       case "show": {
+        const showUnknownOption = findUnknownOption(parsed, SHOW_OPTIONS);
+        if (showUnknownOption !== undefined) {
+          return unknownOption("task.show", showUnknownOption, SHOW_OPTIONS);
+        }
+
+        const unexpectedShowPositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedShowPositionals.length > 0) {
+          return failUnexpectedPositionals("task.show", unexpectedShowPositionals);
+        }
+
         const missingShowOption = readMissingOptionValue(parsed.missingOptionValues, "view");
         if (missingShowOption !== undefined) {
           return failMissingOptionValue("task.show", missingShowOption);
@@ -989,6 +1057,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         });
       }
       case "update": {
+        const updateUnknownOption = findUnknownOption(parsed, UPDATE_OPTIONS);
+        if (updateUnknownOption !== undefined) {
+          return unknownOption("task.update", updateUnknownOption, UPDATE_OPTIONS);
+        }
+
+        const unexpectedUpdatePositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedUpdatePositionals.length > 0) {
+          return failUnexpectedPositionals("task.update", unexpectedUpdatePositionals);
+        }
+
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
@@ -1031,7 +1109,35 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const hasBulkTarget = updateAll || ids.length > 0;
+        const cascadeMode = updateAll && taskId.length > 0;
+        if (cascadeMode) {
+          if (title !== undefined || description !== undefined || append !== undefined || !isStatusCascadeUpdateStatus(status)) {
+            return failCascadeStatusUpdate("task.update", "Task", {
+              id: taskId,
+              status,
+              allowedStatuses: [...STATUS_CASCADE_UPDATE_STATUSES],
+              fields: {
+                title: title !== undefined,
+                description: description !== undefined,
+                append: append !== undefined,
+              },
+            });
+          }
+
+          const cascade = mutations.updateTaskStatusCascade(taskId, status);
+          const task = domain.getTaskOrThrow(taskId);
+
+          return okResult({
+            command: "task.update",
+            human: formatStatusCascadeHuman("task", cascade),
+            data: {
+              task,
+              cascade: buildStatusCascadeData(cascade),
+            },
+          });
+        }
+
+        const hasBulkTarget = (updateAll && taskId.length === 0) || ids.length > 0;
         if (hasBulkTarget) {
           if (taskId.length > 0) {
             return failResult({

package/src/domain/mutation-service.ts

@@ -18,8 +18,10 @@ import {
   type SearchField,
   type SearchNode,
   type SearchSummary,
+  type StatusCascadePlan,
   type SubtaskRecord,
   type TaskRecord,
+  DomainError,
 } from "./types";
 
 function countMatches(value: string, searchText: string): number {
@@ -187,6 +189,15 @@ export class MutationService {
     })();
   }
 
+  updateEpicStatusCascade(id: string, status: string): StatusCascadePlan {
+    return this.#db.transaction((): StatusCascadePlan => {
+      const plan = this.#domain.planStatusCascade("epic", id, status);
+      this.#assertCascadeNotBlocked(plan);
+      this.#applyStatusCascadePlan(plan);
+      return plan;
+    })();
+  }
+
   deleteEpic(id: string): void {
     this.#db.transaction((): void => {
       this.#domain.deleteEpic(id);
@@ -277,6 +288,15 @@ export class MutationService {
     })();
   }
 
+  updateTaskStatusCascade(id: string, status: string): StatusCascadePlan {
+    return this.#db.transaction((): StatusCascadePlan => {
+      const plan = this.#domain.planStatusCascade("task", id, status);
+      this.#assertCascadeNotBlocked(plan);
+      this.#applyStatusCascadePlan(plan);
+      return plan;
+    })();
+  }
+
   deleteTask(id: string): void {
     this.#db.transaction((): void => {
       this.#domain.deleteTask(id);
@@ -458,6 +478,62 @@ export class MutationService {
     return this.#buildScopeReplacementResult(nodes, searchText, replacementText, fields);
   }
 
+  #assertCascadeNotBlocked(plan: StatusCascadePlan): void {
+    if (plan.blockers.length === 0) {
+      return;
+    }
+
+    throw new DomainError({
+      code: "dependency_blocked",
+      message: `${plan.rootKind} cascade cannot transition to ${plan.targetStatus} while dependencies are unresolved`,
+      details: {
+        entity: plan.rootKind,
+        id: plan.rootId,
+        status: plan.targetStatus,
+        atomic: plan.atomic,
+        changedIds: plan.changedIds,
+        unchangedIds: plan.unchangedIds,
+        blockerCount: plan.blockers.length,
+        blockers: plan.blockers,
+        blockedNodeIds: [...new Set(plan.blockers.map((blocker) => blocker.sourceId))],
+        unresolvedDependencyIds: [...new Set(plan.blockers.map((blocker) => blocker.dependsOnId))],
+      },
+    });
+  }
+
+  #applyStatusCascadePlan(plan: StatusCascadePlan): void {
+    for (const change of plan.orderedChanges) {
+      if (change.kind === "epic") {
+        const epic = this.#domain.updateEpic(change.id, { status: change.nextStatus });
+        this.#appendEntityEvent("epic", epic.id, ENTITY_OPERATIONS.epic.updated, {
+          title: epic.title,
+          description: epic.description,
+          status: epic.status,
+        });
+        continue;
+      }
+
+      if (change.kind === "task") {
+        const task = this.#domain.updateTask(change.id, { status: change.nextStatus });
+        this.#appendEntityEvent("task", task.id, ENTITY_OPERATIONS.task.updated, {
+          epic_id: task.epicId,
+          title: task.title,
+          description: task.description,
+          status: task.status,
+        });
+        continue;
+      }
+
+      const subtask = this.#domain.updateSubtask(change.id, { status: change.nextStatus });
+      this.#appendEntityEvent("subtask", subtask.id, ENTITY_OPERATIONS.subtask.updated, {
+        task_id: subtask.taskId,
+        title: subtask.title,
+        description: subtask.description,
+        status: subtask.status,
+      });
+    }
+  }
+
   #applyScopeReplacement(
     nodes: readonly SearchNode[],
     searchText: string,

package/src/domain/tracker-domain.ts

@@ -12,6 +12,7 @@ import {
   type CompactTaskBatchCreateResult,
   type CompactTaskSpec,
   type DependencyRecord,
+  type DependencyNodeKind,
   DomainError,
   type EpicTreeDetailed,
   type EpicRecord,
@@ -23,6 +24,11 @@ import {
   type SearchFieldMatch,
   type SearchNode,
   type SearchSummary,
+  type StatusCascadeBlocker,
+  type StatusCascadeChange,
+  type StatusCascadePlan,
+  type StatusCascadeRootKind,
+  type StatusCascadeScopeNode,
   type SubtaskRecord,
   type TaskTreeDetailed,
   type TaskRecord,
@@ -66,7 +72,7 @@ interface ReverseDependencyRow {
 
 interface UnresolvedDependencyBlocker {
   readonly id: string;
-  readonly kind: "task" | "subtask";
+  readonly kind: DependencyNodeKind;
   readonly status: string;
 }
 
@@ -656,6 +662,40 @@ export class TrackerDomain {
     };
   }
 
+  planStatusCascade(rootKind: StatusCascadeRootKind, rootId: string, targetStatus: string): StatusCascadePlan {
+    const normalizedTargetStatus = assertNonEmpty("status", targetStatus);
+    const scope = this.#collectStatusCascadeScope(rootKind, rootId);
+    const scopeIdSet = new Set(scope.map((node) => node.id));
+    const orderedChanges = this.#orderStatusCascadeChanges(scope, normalizedTargetStatus);
+    const changedIds = orderedChanges.map((change) => change.id);
+    const changedIdSet = new Set(changedIds);
+    const unchangedIds = scope
+      .filter((node) => !changedIdSet.has(node.id))
+      .map((node) => node.id);
+    const blockers = this.#collectStatusCascadeBlockers(orderedChanges, scopeIdSet, changedIdSet, normalizedTargetStatus);
+
+    return {
+      rootKind,
+      rootId,
+      targetStatus: normalizedTargetStatus,
+      atomic: true,
+      scope,
+      orderedChanges,
+      changedIds,
+      unchangedIds,
+      blockers,
+      counts: {
+        scope: scope.length,
+        changed: orderedChanges.length,
+        unchanged: unchangedIds.length,
+        blockers: blockers.length,
+        changedEpics: orderedChanges.filter((change) => change.kind === "epic").length,
+        changedTasks: orderedChanges.filter((change) => change.kind === "task").length,
+        changedSubtasks: orderedChanges.filter((change) => change.kind === "subtask").length,
+      },
+    };
+  }
+
   collectEpicSearchScope(epicId: string): readonly SearchNode[] {
     const tree = this.buildEpicTreeDetailed(epicId);
 
@@ -1266,9 +1306,217 @@ export class TrackerDomain {
     return row !== null;
   }
 
+  #collectStatusCascadeScope(rootKind: StatusCascadeRootKind, rootId: string): StatusCascadeScopeNode[] {
+    if (rootKind === "task") {
+      const tree = this.buildTaskTreeDetailed(rootId);
+      return [
+        {
+          kind: "task",
+          id: tree.id,
+          parentId: tree.epicId,
+          status: tree.status,
+        },
+        ...tree.subtasks.map((subtask) => ({
+          kind: "subtask" as const,
+          id: subtask.id,
+          parentId: subtask.taskId,
+          status: subtask.status,
+        })),
+      ];
+    }
+
+    const tree = this.buildEpicTreeDetailed(rootId);
+    return [
+      {
+        kind: "epic",
+        id: tree.id,
+        status: tree.status,
+      },
+      ...tree.tasks.flatMap((task) => [
+        {
+          kind: "task" as const,
+          id: task.id,
+          parentId: task.epicId,
+          status: task.status,
+        },
+        ...task.subtasks.map((subtask) => ({
+          kind: "subtask" as const,
+          id: subtask.id,
+          parentId: subtask.taskId,
+          status: subtask.status,
+        })),
+      ]),
+    ];
+  }
+
+  #orderStatusCascadeChanges(scope: readonly StatusCascadeScopeNode[], targetStatus: string): StatusCascadeChange[] {
+    const changes = scope
+      .filter((node) => node.status !== targetStatus)
+      .map((node) => {
+        const change: StatusCascadeChange = {
+          kind: node.kind,
+          id: node.id,
+          previousStatus: node.status,
+          nextStatus: targetStatus,
+          ...(node.parentId === undefined ? {} : { parentId: node.parentId }),
+        };
+        return change;
+      });
+
+    if (targetStatus !== "done") {
+      return changes;
+    }
+
+    return this.#topologicallyOrderDoneCascadeChanges(changes);
+  }
+
+  #topologicallyOrderDoneCascadeChanges(changes: readonly StatusCascadeChange[]): StatusCascadeChange[] {
+    const indexById = new Map<string, number>();
+    const changeById = new Map<string, StatusCascadeChange>();
+    const dependencyTargetsBySource = new Map<string, Set<string>>();
+    const dependents = new Map<string, Set<string>>();
+    const indegree = new Map<string, number>();
+
+    changes.forEach((change, index) => {
+      indexById.set(change.id, index);
+      changeById.set(change.id, change);
+      indegree.set(change.id, 0);
+
+      if (change.kind !== "task" && change.kind !== "subtask") {
+        return;
+      }
+
+      const dependencyTargets = new Set(this.listDependencies(change.id).map((dependency) => dependency.dependsOnId));
+      dependencyTargetsBySource.set(change.id, dependencyTargets);
+    });
+
+    const addEdge = (fromId: string, toId: string): void => {
+      if (fromId === toId || !changeById.has(fromId) || !changeById.has(toId)) {
+        return;
+      }
+
+      const neighbors = dependents.get(fromId) ?? new Set<string>();
+      if (neighbors.has(toId)) {
+        return;
+      }
+
+      neighbors.add(toId);
+      dependents.set(fromId, neighbors);
+      indegree.set(toId, (indegree.get(toId) ?? 0) + 1);
+    };
+
+    for (const change of changes) {
+      const dependencyTargets = dependencyTargetsBySource.get(change.id);
+
+      if (change.kind === "subtask" && change.parentId !== undefined && !dependencyTargets?.has(change.parentId)) {
+        addEdge(change.id, change.parentId);
+      }
+
+      if (change.kind === "task" && change.parentId !== undefined && !dependencyTargets?.has(change.parentId)) {
+        addEdge(change.id, change.parentId);
+      }
+
+      if (change.kind !== "task" && change.kind !== "subtask") {
+        continue;
+      }
+
+      for (const dependencyTargetId of dependencyTargets ?? []) {
+        addEdge(dependencyTargetId, change.id);
+      }
+    }
+
+    const ordered: StatusCascadeChange[] = [];
+    const ready = changes
+      .filter((change) => (indegree.get(change.id) ?? 0) === 0)
+      .sort((left, right) => (indexById.get(left.id) ?? 0) - (indexById.get(right.id) ?? 0));
+
+    while (ready.length > 0) {
+      const next = ready.shift();
+      if (next === undefined) {
+        continue;
+      }
+
+      ordered.push(next);
+      for (const dependentId of dependents.get(next.id) ?? []) {
+        const remaining = (indegree.get(dependentId) ?? 0) - 1;
+        indegree.set(dependentId, remaining);
+        if (remaining !== 0) {
+          continue;
+        }
+
+        const dependent = changeById.get(dependentId);
+        if (dependent === undefined) {
+          continue;
+        }
+
+        ready.push(dependent);
+        ready.sort((left, right) => (indexById.get(left.id) ?? 0) - (indexById.get(right.id) ?? 0));
+      }
+    }
+
+    if (ordered.length !== changes.length) {
+      throw new DomainError({
+        code: "invalid_dependency",
+        message: "unable to determine dependency-safe cascade order",
+        details: {
+          changedIds: changes.map((change) => change.id),
+        },
+      });
+    }
+
+    return ordered;
+  }
+
+  #collectStatusCascadeBlockers(
+    changes: readonly StatusCascadeChange[],
+    scopeIdSet: ReadonlySet<string>,
+    changedIdSet: ReadonlySet<string>,
+    targetStatus: string,
+  ): StatusCascadeBlocker[] {
+    if (!DEPENDENCY_GATED_STATUSES.has(targetStatus)) {
+      return [];
+    }
+
+    const blockers: StatusCascadeBlocker[] = [];
+    for (const change of changes) {
+      if (change.kind !== "task" && change.kind !== "subtask") {
+        continue;
+      }
+
+      for (const dependency of this.listDependencies(change.id)) {
+        const dependencyStatus =
+          dependency.dependsOnKind === "task"
+            ? this.getTaskOrThrow(dependency.dependsOnId).status
+            : this.getSubtaskOrThrow(dependency.dependsOnId).status;
+        const inScope = scopeIdSet.has(dependency.dependsOnId);
+        const willCascade = targetStatus === "done" && changedIdSet.has(dependency.dependsOnId);
+        if (dependencyStatus === "done" || willCascade) {
+          continue;
+        }
+
+        blockers.push({
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+          dependsOnStatus: dependencyStatus,
+          inScope,
+          willCascade,
+        });
+      }
+    }
+
+    return blockers.sort(
+      (left, right) =>
+        left.sourceId.localeCompare(right.sourceId) ||
+        left.dependsOnId.localeCompare(right.dependsOnId) ||
+        left.dependsOnKind.localeCompare(right.dependsOnKind),
+    );
+  }
+
   private assertNoUnresolvedDependenciesForStatusTransition(
     id: string,
-    kind: "task" | "subtask",
+    kind: DependencyNodeKind,
     existingStatus: string,
     nextStatus: string,
   ): void {

package/src/domain/types.ts

@@ -192,6 +192,57 @@ export interface SearchNode {
   readonly description: string;
 }
 
+export type StatusCascadeRootKind = Extract<NodeKind, "epic" | "task">;
+export type DependencyNodeKind = Extract<NodeKind, "task" | "subtask">;
+
+export interface StatusCascadeScopeNode {
+  readonly kind: NodeKind;
+  readonly id: string;
+  readonly parentId?: string;
+  readonly status: string;
+}
+
+export interface StatusCascadeChange {
+  readonly kind: NodeKind;
+  readonly id: string;
+  readonly parentId?: string;
+  readonly previousStatus: string;
+  readonly nextStatus: string;
+}
+
+export interface StatusCascadeBlocker {
+  readonly sourceId: string;
+  readonly sourceKind: DependencyNodeKind;
+  readonly dependsOnId: string;
+  readonly dependsOnKind: DependencyNodeKind;
+  readonly dependsOnStatus: string;
+  readonly inScope: boolean;
+  readonly willCascade: boolean;
+}
+
+export interface StatusCascadeCounts {
+  readonly scope: number;
+  readonly changed: number;
+  readonly unchanged: number;
+  readonly blockers: number;
+  readonly changedEpics: number;
+  readonly changedTasks: number;
+  readonly changedSubtasks: number;
+}
+
+export interface StatusCascadePlan {
+  readonly rootKind: StatusCascadeRootKind;
+  readonly rootId: string;
+  readonly targetStatus: string;
+  readonly atomic: true;
+  readonly scope: ReadonlyArray<StatusCascadeScopeNode>;
+  readonly orderedChanges: ReadonlyArray<StatusCascadeChange>;
+  readonly changedIds: ReadonlyArray<string>;
+  readonly unchangedIds: ReadonlyArray<string>;
+  readonly blockers: ReadonlyArray<StatusCascadeBlocker>;
+  readonly counts: StatusCascadeCounts;
+}
+
 export interface DomainErrorShape {
   readonly code: string;
   readonly message: string;