@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/monorepo/scripts/backlog/graph.ts

@@ -0,0 +1,386 @@
+/**
+ * graph.ts — the pure renderer behind the `backlog-dependency-graph` capability: a flat-list view
+ * of which open backlog tasks are ready to start and which wait for another one, derived from each
+ * task's declared `dependencies` and nothing else.
+ *
+ * Implements `specs/backlog-dependency-graph/spec.md` — "Flat-list view of open-task
+ * dependencies", "On-demand query of the view", "Graph-holder task mirrors the view" — per
+ * design.md decision 1 (flat list over a tree: dependencies form a DAG, and a tree repeats a task
+ * with two parents) and decision 7 (hand-written logic, test-first, over literal `Board` fixtures).
+ *
+ * `renderDependencyGraph`, `renderHolderDescription`, `decideGraphWrite` and `runGraphCli` are all
+ * pure over their inputs — `runGraphCli` takes its board, its board-writer and its stdio as
+ * injected `GraphCliEffects`, so it needs nothing from `dispatch.js`. `graph-cli.ts` (this
+ * capability's ONLY module that imports `dispatch.js`) binds those effects to the real world:
+ * `types.ts`'s wiring-direction rule ("entry.ts cannot import from dispatch.ts — that is the
+ * direction the wiring runs") applies here too, since `maintenance.ts`'s step 5b already imports
+ * this module for `decideGraphWrite` — a `graph.ts` that itself imported `dispatch.js` would close
+ * the cycle graph → dispatch → entry → maintenance → graph.
+ */
+import {
+  BOARD_STATUSES,
+  GRAPH_HOLDER_LABEL,
+  TASK_STATUS,
+  type Board,
+  type Task,
+  type TaskStatus,
+} from './types.js';
+
+/** The four board columns that count as "open" — a `Done` task is never a reason to wait. */
+const OPEN_STATUSES: readonly TaskStatus[] = BOARD_STATUSES.filter(
+  (status) => status !== TASK_STATUS.DONE,
+);
+
+/** Numeric-aware id comparator, so `T-9` sorts before `T-106` — the tie-break design.md decision 1 requires. */
+function compareTaskId(a: string, b: string): number {
+  return a.localeCompare(b, undefined, { numeric: true });
+}
+
+interface OpenTaskInfo {
+  task: Task;
+  /**
+   * Ids this task waits for: an unresolved or not-yet-`Done` declared dependency, merged with any
+   * of its own open subtasks (view rule only — `guards.ts`'s dependency guard and `parent.ts` are
+   * untouched, and a subtask never "waits for" its own parent this way).
+   */
+  openDependencyIds: string[];
+}
+
+function isOpen(task: Task): boolean {
+  return OPEN_STATUSES.includes(task.status);
+}
+
+/** The task's declared dependencies that are still a reason to wait — an unknown id counts as one. */
+function openDependenciesOf(task: Task, board: Board): string[] {
+  return task.dependsOn.filter((dependencyId) => {
+    const dependency = board.tasksById[dependencyId];
+    return !dependency || dependency.status !== TASK_STATUS.DONE;
+  });
+}
+
+/** This task's own subtasks that are still open — a `Done` subtask is not a reason to wait. */
+function openSubtaskIdsOf(task: Task, board: Board): string[] {
+  return Object.values(board.tasksById)
+    .filter((candidate) => candidate.parentId === task.id && isOpen(candidate))
+    .map((candidate) => candidate.id);
+}
+
+/** Every open task on the board, holder excluded, with its open dependencies precomputed once. */
+function openTasksOf(board: Board): OpenTaskInfo[] {
+  return Object.values(board.tasksById)
+    .filter((task) => isOpen(task) && !task.isGraphHolder)
+    .map((task) => ({
+      task,
+      // A `Set` both deduplicates an id declared as BOTH a `dependsOn` entry and derived from being
+      // an open subtask, and normalizes the merge order — `formatWaitsFor` sorts the result anyway.
+      openDependencyIds: [
+        ...new Set([...openDependenciesOf(task, board), ...openSubtaskIdsOf(task, board)]),
+      ],
+    }));
+}
+
+function formatWaitsFor(openDependencyIds: readonly string[], board: Board): string {
+  return [...openDependencyIds]
+    .sort(compareTaskId)
+    .map((id) => (board.tasksById[id] ? id : `${id} (desconocida)`))
+    .join(', ');
+}
+
+/**
+ * Orders the waiting section with Kahn's algorithm: a task is listed only after every waiting task
+ * it names. A dependency cycle cannot be ordered — its members are appended last, in id order,
+ * still naming what they wait for (design.md decision 1). Ties elsewhere are broken by numeric id
+ * so identical boards render identical text (decision 7's determinism requirement).
+ */
+function orderWaitingSection(waiting: readonly OpenTaskInfo[]): OpenTaskInfo[] {
+  const waitingIds = new Set(waiting.map((entry) => entry.task.id));
+  const byId = new Map(waiting.map((entry) => [entry.task.id, entry]));
+  // In-degree here counts only edges INTO a waiting task FROM another waiting task — a dependency
+  // on a ready or unknown task needs no ordering edge: the ready section always prints first, and
+  // an unknown id is not a node at all.
+  const remainingDependencies = new Map(
+    waiting.map((entry) => [
+      entry.task.id,
+      new Set(entry.openDependencyIds.filter((id) => waitingIds.has(id))),
+    ]),
+  );
+
+  const ordered: OpenTaskInfo[] = [];
+  const placed = new Set<string>();
+  for (;;) {
+    const ready = [...remainingDependencies.entries()]
+      .filter(([id, deps]) => !placed.has(id) && deps.size === 0)
+      .map(([id]) => id)
+      .sort(compareTaskId);
+    if (ready.length === 0) {
+      break;
+    }
+    for (const id of ready) {
+      ordered.push(byId.get(id)!);
+      placed.add(id);
+    }
+    for (const deps of remainingDependencies.values()) {
+      for (const id of ready) {
+        deps.delete(id);
+      }
+    }
+  }
+
+  // Whatever is left never reached in-degree zero: a cycle. Appended last, in id order.
+  const cycleMembers = waiting
+    .filter((entry) => !placed.has(entry.task.id))
+    .sort((a, b) => compareTaskId(a.task.id, b.task.id));
+
+  return [...ordered, ...cycleMembers];
+}
+
+/**
+ * Renders the flat-list view of open-task dependencies: the ready section, then the waiting
+ * section, each task on one self-contained line. A section header is omitted when it would have no
+ * entries — a fully-Done board (or one with no open tasks in that half) renders no dangling header.
+ */
+export function renderDependencyGraph(board: Board): string {
+  const openTasks = openTasksOf(board);
+  const ready = openTasks
+    .filter((entry) => entry.openDependencyIds.length === 0)
+    .sort((a, b) => compareTaskId(a.task.id, b.task.id));
+  const waiting = orderWaitingSection(openTasks.filter((entry) => entry.openDependencyIds.length > 0));
+
+  const sections: string[] = [];
+  if (ready.length > 0) {
+    sections.push(
+      [
+        'LISTAS — sin dependencias abiertas',
+        ...ready.map((entry) => `  ${entry.task.id} [${entry.task.status}]`),
+      ].join('\n'),
+    );
+  }
+  if (waiting.length > 0) {
+    sections.push(
+      [
+        'EN ESPERA',
+        ...waiting.map(
+          (entry) =>
+            `  ${entry.task.id} [${entry.task.status}]  espera a: ${formatWaitsFor(entry.openDependencyIds, board)}`,
+        ),
+      ].join('\n'),
+    );
+  }
+  return sections.join('\n');
+}
+
+/**
+ * The graph-holder task's fixed Spanish header: states that only DECLARED links are shown — "lista"
+ * means no declared open dependency, not no conflict — that the view informs about order and does
+ * not authorize queueing, and that the text is generated and must never be edited by hand.
+ * `renderHolderDescription` prepends it to the rendered list, for the CLI's `--write` and for the
+ * maintenance pass's holder refresh alike.
+ *
+ * No backticks: the terminal board's detail popup lifts every inline-code span out of its sentence
+ * and prints it below the paragraph, which leaves the sentence with a hole in it.
+ */
+export const GRAPH_HOLDER_HEADER =
+  'Solo muestra dependencias DECLARADAS: que una tarea aparezca en "LISTAS" significa que no tiene ' +
+  'ninguna dependencia abierta declarada, no que no haya conflicto con otro trabajo en curso.\n\n' +
+  'Esta vista informa sobre el orden; no autoriza a encolar ninguna tarea.\n\n' +
+  'Esta descripción está GENERADA por el comando pnpm backlog:graph — no la edites a mano, la ' +
+  'próxima pasada la sobrescribe.';
+
+/** The holder's full description: the fixed header, then the rendered flat list. */
+export function renderHolderDescription(board: Board): string {
+  const body = renderDependencyGraph(board);
+  return body ? `${GRAPH_HOLDER_HEADER}\n\n${body}` : GRAPH_HOLDER_HEADER;
+}
+
+/** Every task id carrying the `board:graph` label, sorted numerically — empty when none does. */
+export function listGraphHolderIds(board: Board): string[] {
+  return Object.values(board.tasksById)
+    .filter((task) => task.isGraphHolder)
+    .map((task) => task.id)
+    .sort(compareTaskId);
+}
+
+/**
+ * The ambiguity notice written to EACH `board:graph` holder while more than one task carries the
+ * label — plain text, no backticks: the terminal board's detail popup lifts every inline-code span
+ * out of its sentence and prints it below the paragraph, leaving the sentence with a hole in it
+ * (the same reason `GRAPH_HOLDER_HEADER` avoids them). Exported so both `graph.test.ts` and
+ * `maintenance.test.ts` assert its exact shape without duplicating the prose.
+ */
+export function ambiguousHolderNotice(ids: readonly string[]): string {
+  const sortedIds = [...ids].sort(compareTaskId).join(', ');
+  return (
+    `Más de una tarea lleva la etiqueta board:graph: ${sortedIds}. Quita la etiqueta de todas menos ` +
+    'una para que la vista de dependencias pueda generarse de nuevo — esta descripción no se ' +
+    'refresca mientras la ambigüedad siga abierta.'
+  );
+}
+
+export type GraphWriteDecision =
+  | { kind: 'no-holder' }
+  | { kind: 'ambiguous'; ids: string[]; writes: Array<{ id: string; description: string }> }
+  | { kind: 'incomplete' }
+  | { kind: 'unchanged'; id: string }
+  | { kind: 'write'; id: string; description: string };
+
+/**
+ * Decides whether `--write` (or the maintenance pass's own refresh, group 4) has anything to do,
+ * without performing any I/O itself. `currentDescriptionOf` is called at most once per holder: once
+ * for the single-holder case, and once PER holder id for the ambiguous case, to decide which of
+ * them still need the notice written (write-on-difference, same rule as the single-holder case) —
+ * zero holders never needs it at all. Skipped over an incomplete board read
+ * (`Board.complete === false`): a view derived from part of the board would show a waiting task as
+ * ready (design.md decision 5).
+ */
+export function decideGraphWrite(
+  board: Board,
+  currentDescriptionOf: (id: string) => string,
+): GraphWriteDecision {
+  if (board.complete === false) {
+    return { kind: 'incomplete' };
+  }
+  const holderIds = listGraphHolderIds(board);
+  if (holderIds.length === 0) {
+    return { kind: 'no-holder' };
+  }
+  if (holderIds.length > 1) {
+    const notice = ambiguousHolderNotice(holderIds);
+    const writes = holderIds
+      .filter((id) => currentDescriptionOf(id).trim() !== notice.trim())
+      .map((id) => ({ id, description: notice }));
+    return { kind: 'ambiguous', ids: holderIds, writes };
+  }
+  const id = holderIds[0];
+  const description = renderHolderDescription(board);
+  const current = currentDescriptionOf(id).trim();
+  return description.trim() === current ? { kind: 'unchanged', id } : { kind: 'write', id, description };
+}
+
+// ── CLI behaviour (`pnpm backlog:graph`) — pure over injected effects ─────────
+
+/**
+ * Every effect `runGraphCli` needs from the outside world, injected so the argv gate and the
+ * effect dispatch are testable without a real board, a real `backlog` CLI, or real stdio —
+ * `graph.test.ts`'s `runGraphCli` suite exercises this directly with recording fakes.
+ */
+export interface GraphCliEffects {
+  /** The board as it stands right now — already resolved against the main checkout. */
+  loadBoard: () => Board;
+  /**
+   * The holder's CURRENT description text, or `''` when it has none. Called at most once, only for
+   * a single-holder, complete-board read. May THROW — a failed underlying board read must be told
+   * apart from a genuinely empty description (see `dispatch.ts`'s `realBacklog.readDescription`),
+   * and `runGraphCli` reports that throw as a failed run rather than treating it as "nothing to do".
+   */
+  readDescription: (id: string) => string;
+  /** Replaces the holder's description outright. Called at most once, only for a `write` decision. May throw. */
+  writeDescription: (id: string, description: string) => void;
+  print: (line: string) => void;
+  reportError: (line: string) => void;
+}
+
+/** `runGraphCli`'s result: `0` covers every "nothing left to do" outcome, never a partial one. */
+export const GRAPH_CLI_EXIT = {
+  OK: 0,
+  FAILURE: 1,
+} as const;
+
+export type GraphCliExitCode = (typeof GRAPH_CLI_EXIT)[keyof typeof GRAPH_CLI_EXIT];
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The whole `backlog:graph` behaviour — argv gate, the view print, the incomplete-board warning,
+ * then effect dispatch on `decideGraphWrite`'s verdict — as ONE testable function returning an exit
+ * code. `graph-cli.ts`'s `main()` is the thin shell that binds these effects to the real world and
+ * turns the returned code into `process.exitCode`; nothing here reads `process.argv`,
+ * `process.env`, or spawns a process itself.
+ *
+ * A scripted caller cannot otherwise tell "refreshed" from "refused": every failure path below —
+ * an unrecognized argument, a partial board read, more than one holder, a failed read or write —
+ * reports on stderr AND returns `GRAPH_CLI_EXIT.FAILURE`, never a silent `0`.
+ */
+export function runGraphCli(argv: readonly string[], effects: GraphCliEffects): GraphCliExitCode {
+  // A bare `--` is pnpm's own argument separator, not an argument the command declares — some pnpm
+  // versions pass it through literally (`pnpm backlog:graph -- --write` → argv `['--', '--write']`),
+  // others swallow it. Either way it names nothing to refuse.
+  const declaredArgs = argv.filter((arg) => arg !== '--');
+  const unknownArgs = declaredArgs.filter((arg) => arg !== '--write');
+  if (unknownArgs.length > 0) {
+    effects.reportError(
+      `backlog:graph: argumento no reconocido "${unknownArgs[0]}". Uso: pnpm backlog:graph [--write]. No se escribe nada.`,
+    );
+    return GRAPH_CLI_EXIT.FAILURE;
+  }
+  const write = declaredArgs.includes('--write');
+
+  const board = effects.loadBoard();
+  const incomplete = board.complete === false;
+  if (incomplete) {
+    // BEFORE the view: a reader must hit the caveat before trusting what "LISTAS" says below.
+    effects.reportError(
+      'backlog:graph: la lectura del tablero fue parcial — la vista de abajo puede mostrar como ' +
+        '"LISTAS" una tarea que en realidad espera a otra que no se pudo leer.',
+    );
+  }
+  effects.print(renderDependencyGraph(board) || '(sin tareas abiertas)');
+
+  if (incomplete) {
+    return GRAPH_CLI_EXIT.FAILURE;
+  }
+  if (!write) {
+    return GRAPH_CLI_EXIT.OK;
+  }
+
+  let decision: GraphWriteDecision;
+  try {
+    decision = decideGraphWrite(board, effects.readDescription);
+  } catch (error) {
+    effects.reportError(
+      `backlog:graph: no se pudo leer la descripción actual del holder: ${errorMessage(error)}`,
+    );
+    return GRAPH_CLI_EXIT.FAILURE;
+  }
+
+  switch (decision.kind) {
+    case 'ambiguous':
+      // Each holder's write is independent: one throwing must not cost the other its notice.
+      for (const holderWrite of decision.writes) {
+        try {
+          effects.writeDescription(holderWrite.id, holderWrite.description);
+        } catch (error) {
+          effects.reportError(
+            `backlog:graph: no se pudo escribir el aviso de ambigüedad en ${holderWrite.id}: ${errorMessage(error)}`,
+          );
+        }
+      }
+      effects.reportError(
+        `backlog:graph: hay más de un holder (${GRAPH_HOLDER_LABEL}): ${decision.ids.join(', ')}. Quita la etiqueta de todas menos una.`,
+      );
+      return GRAPH_CLI_EXIT.FAILURE;
+    case 'incomplete':
+      // Unreachable in practice: `incomplete` above already returned. Kept so the switch stays
+      // exhaustive over `GraphWriteDecision`'s full union.
+      effects.reportError('backlog:graph: la lectura del tablero fue parcial; no se refresca el holder.');
+      return GRAPH_CLI_EXIT.FAILURE;
+    case 'write':
+      try {
+        effects.writeDescription(decision.id, decision.description);
+      } catch (error) {
+        effects.reportError(
+          `backlog:graph: no se pudo escribir la descripción del holder: ${errorMessage(error)}`,
+        );
+        return GRAPH_CLI_EXIT.FAILURE;
+      }
+      effects.print(`backlog:graph: holder ${decision.id} refrescado.`);
+      return GRAPH_CLI_EXIT.OK;
+    case 'unchanged':
+      effects.print(`backlog:graph: holder ${decision.id} ya está al día.`);
+      return GRAPH_CLI_EXIT.OK;
+    case 'no-holder':
+      effects.print(`backlog:graph: ninguna tarea lleva ${GRAPH_HOLDER_LABEL}; nada que refrescar.`);
+      return GRAPH_CLI_EXIT.OK;
+  }
+}