mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/cursorPosition.ts

@@ -0,0 +1,176 @@
+// CR114 — where a delivery cursor stands, and what it accepts next.
+//
+// CR067 placed a cursor on the ribbon from a table in `lifecycleRefusal.ts`, beside
+// the order of the story's events. The Builder resume chose its next actions from two
+// other facts, whether a confirmation was pending and whether an item was active, and
+// never read the event. So it offered Prepare at every position with nothing pending,
+// a freshly pulled story's and a closed one's alike, and `build show`, which printed
+// no list, could not disagree with it.
+//
+// This module is the one table of positions. Each event the runtime writes for an
+// item names the ribbon stage a story draws after it, and the steps the runtime
+// accepts next when nothing is pending. The story's event order is its story rows,
+// read in order. The resume and `build show` both choose their list through
+// `allowedNextActions`, and nothing else chooses it.
+//
+// Delivery Story events carry their steps and no stage: CR067 left them off the
+// ribbon, never a guessed stage, and that holds. A position the table does not know
+// is offered no lifecycle step, only the two inspections (CR114, D2): the same rule,
+// applied to the list.
+
+import { isImplementableByDefault } from "./cursorTransitions.ts";
+
+/** Every action a Builder surface can offer: one closed vocabulary (CR114, D1). */
+export const NEXT_ACTIONS = [
+  "adopt_method",
+  "sync_cursor",
+  "inspect_method",
+  "inspect_roadmap",
+  "pull_candidate_if_known",
+  "answer_pending_confirmation",
+  "prepare_active_item",
+  "expand_active_item",
+  "plan_active_item",
+  "implement_active_item",
+  "validate_active_item",
+  "review_active_item_debt",
+  "check_active_item_coherence",
+  "close_active_item",
+] as const;
+
+export type NextAction = (typeof NEXT_ACTIONS)[number];
+
+/** A journey that has adopted no method. */
+export const NOT_ADOPTED_ACTIONS: readonly NextAction[] = ["adopt_method", "inspect_method"];
+
+/** An adopted journey whose delivery cursor was never synced. */
+const NO_CURSOR_ACTIONS: readonly NextAction[] = ["sync_cursor", "inspect_method"];
+
+/** No item pulled, or the item closed: the next move is a Pull. */
+export const NO_ACTIVE_ITEM_ACTIONS: readonly NextAction[] = [
+  "inspect_roadmap",
+  "pull_candidate_if_known",
+  "inspect_method",
+];
+
+/** A confirmation is pending: answering it is the one lifecycle move (CR105, A1). */
+export const PENDING_CONFIRMATION_ACTIONS: readonly NextAction[] = [
+  "answer_pending_confirmation",
+  "inspect_method",
+];
+
+/** The read-only moves every open item's list ends with. */
+const INSPECTIONS: readonly NextAction[] = ["inspect_roadmap", "inspect_method"];
+
+interface Position {
+  /** The ribbon stage a story stands at after the event; `null` off the ribbon. */
+  readonly stage: string | null;
+  /** The steps the runtime accepts next when nothing is pending, or `closed`. */
+  readonly next: readonly NextAction[] | "closed";
+}
+
+/**
+ * The positions, in the order a cursor reaches them: the story's rows first, then the
+ * Delivery Story's. A row with no next step is one the runtime writes with a pending
+ * confirmation, which outranks it. `template_preparation`, which `sync-cursor` writes,
+ * is no item's position, so it has no row.
+ */
+const POSITIONS: ReadonlyArray<readonly [string, Position]> = [
+  ["pull", { stage: "prepare", next: ["prepare_active_item"] }],
+  ["prepare", { stage: "plan", next: ["plan_active_item"] }],
+  ["plan", { stage: "plan", next: [] }],
+  [
+    "plan_approved",
+    { stage: "implement", next: ["implement_active_item", "validate_active_item"] },
+  ],
+  ["implementation_complete", { stage: "validate", next: ["validate_active_item"] }],
+  ["validate", { stage: "validate", next: [] }],
+  ["validation_passed", { stage: "debt_review", next: ["review_active_item_debt"] }],
+  ["review", { stage: "debt_review", next: [] }],
+  [
+    "review_complete",
+    { stage: "done", next: ["check_active_item_coherence", "close_active_item"] },
+  ],
+  ["coherence", { stage: "done", next: [] }],
+  ["coherence_complete", { stage: "done", next: ["close_active_item"] }],
+  ["done", { stage: "done", next: [] }],
+  ["done_complete", { stage: "done", next: "closed" }],
+  ["expand", { stage: null, next: [] }],
+  ["navigator_flow_unit_selected", { stage: null, next: [] }],
+  ["delivery_story_plan", { stage: null, next: [] }],
+  [
+    "delivery_story_plan_approved",
+    { stage: null, next: ["implement_active_item", "validate_active_item"] },
+  ],
+  ["delivery_story_validation", { stage: null, next: [] }],
+  ["delivery_story_validation_complete", { stage: null, next: ["review_active_item_debt"] }],
+  ["delivery_story_review_complete", { stage: null, next: ["close_active_item"] }],
+  ["delivery_story_coherence_complete", { stage: null, next: ["close_active_item"] }],
+  ["delivery_story_done_complete", { stage: null, next: "closed" }],
+];
+
+const POSITION_AFTER: ReadonlyMap<string, Position> = new Map(POSITIONS);
+
+/** A prepared Delivery Story expands next rather than plans: Pull runs its Expand. */
+const DELIVERY_STORY_PREPARED: Position = { stage: "expand", next: ["expand_active_item"] };
+
+/**
+ * A prepared item of any other level: Plan refuses it and Expand never reads it, so
+ * nothing is offered. Its ribbon stands at Plan, where CR067 drew it. Pull accepts only
+ * the three levels, so only a seeded cursor holds one.
+ */
+const UNPLANNABLE_PREPARED: Position = { stage: "plan", next: [] };
+
+/** The story lifecycle's events, in the order a cursor reaches them: the story rows. */
+export const STORY_LIFECYCLE_EVENTS: readonly string[] = POSITIONS.filter(
+  ([, position]) => position.stage !== null,
+).map(([event]) => event);
+
+/** The cursor fields a position is read from. */
+export interface CursorPositionView {
+  readonly activeItem: string | null;
+  readonly activeItemLevel: string | null;
+  readonly pendingConfirmation: string | null;
+  readonly lastDeliveryEvent: string | null;
+}
+
+/**
+ * After Prepare the level decides, by Plan's own predicate: a story plans, a Delivery
+ * Story expands, and any other level is offered nothing (CR114, handoff review).
+ */
+function positionOf(
+  cursor: Pick<CursorPositionView, "lastDeliveryEvent" | "activeItemLevel">,
+): Position | null {
+  const event = cursor.lastDeliveryEvent;
+  if (event === null) return null;
+  if (event === "prepare" && !isImplementableByDefault(cursor.activeItemLevel)) {
+    return cursor.activeItemLevel === "delivery_story"
+      ? DELIVERY_STORY_PREPARED
+      : UNPLANNABLE_PREPARED;
+  }
+  return POSITION_AFTER.get(event) ?? null;
+}
+
+/**
+ * The lifecycle stage the cursor stands at, for the ribbon; `null` for an event the
+ * ribbon does not draw.
+ */
+export function lifecycleStageOf(
+  cursor: Pick<CursorPositionView, "lastDeliveryEvent" | "activeItemLevel">,
+): string | null {
+  return positionOf(cursor)?.stage ?? null;
+}
+
+/**
+ * What the cursor accepts next, in the order to offer it: the one list the resume and
+ * `build show` print. No cursor is `null`; a journey that adopted no method is the
+ * resume's own case, `NOT_ADOPTED_ACTIONS`, since `build show` refuses it.
+ */
+export function allowedNextActions(cursor: CursorPositionView | null): readonly NextAction[] {
+  if (cursor === null) return NO_CURSOR_ACTIONS;
+  if (cursor.pendingConfirmation) return PENDING_CONFIRMATION_ACTIONS;
+  if (!cursor.activeItem) return NO_ACTIVE_ITEM_ACTIONS;
+  const next = positionOf(cursor)?.next ?? [];
+  if (next === "closed") return NO_ACTIVE_ITEM_ACTIONS;
+  return [...next, ...INSPECTIONS];
+}

package/ts/src/builder/cursorTransitions.ts

@@ -0,0 +1,77 @@
+// CV22.DS7.US8 plateau 3 — state shared by every Ariad lifecycle event.
+//
+// Python keeps Pull, Expand, Prepare, Plan, Approve, Validate, Review, Coherence,
+// and Done in one 2,303-line `lifecycle.py`, which is argparse accretion rather
+// than design. The port is one module per event over this shared base, so a reader
+// looking for what Pull does opens `pull.ts` instead of scrolling past Done.
+//
+// What belongs here is only what more than one event needs: the normalization
+// rules, the level vocabulary, and the Delivery Story ancestor lookup Pull uses to
+// decide whether release intent survives a re-pull.
+
+import { pyStrip } from "#util/pythonText.ts";
+import type { BuilderDeliveryCursor } from "./deliveryCursor.ts";
+
+/** Python `_ALLOWED_PULL_LEVELS`, in declaration order — the error message quotes it. */
+export const ALLOWED_PULL_LEVELS = ["delivery_story", "user_story", "technical_story"] as const;
+
+/** Python `lifecycle._normalize_required`. */
+export function normalizeRequired(value: string | null | undefined, fieldName: string): string {
+  const normalized = typeof value === "string" ? pyStrip(value) : "";
+  if (!normalized) throw new Error(`${fieldName} must not be empty`);
+  return normalized;
+}
+
+/** Python `_is_implementable_by_default`: a Delivery Story is never implementable. */
+export function isImplementableByDefault(level: string | null): boolean {
+  return level === "user_story" || level === "technical_story";
+}
+
+/**
+ * Python `release_intent.delivery_story_code_for_item`.
+ *
+ * Finds the first `DS<n>` / `DS-<n>` segment, case-insensitively, and returns the
+ * code up to and including it — so `CV22.DS7.US8` belongs to `CV22.DS7`, and a
+ * code with no Delivery Story segment belongs to nothing.
+ *
+ * Lives here rather than in a `releaseIntent.ts` that does not exist yet: Pull is
+ * its first caller, and Scope F's release-intent leaf will import it from here
+ * instead of growing a second copy.
+ */
+export function deliveryStoryCodeForItem(itemCode: string | null): string | null {
+  if (!itemCode) return null;
+  const parts = itemCode
+    .split(".")
+    .map((part) => pyStrip(part))
+    .filter((part) => part !== "");
+  for (const [index, part] of parts.entries()) {
+    // `re.fullmatch(r"DS-?\d+", part, re.IGNORECASE)`. `\d` is ASCII-only in both
+    // engines here: Python's pattern is a `str` pattern without `re.UNICODE`
+    // semantics for `fullmatch` on digits it would widen, and JavaScript's `\d`
+    // is ASCII by definition. An Arabic-Indic digit matches in neither.
+    if (/^DS-?\d+$/i.test(part)) {
+      return parts.slice(0, index + 1).join(".");
+    }
+  }
+  return null;
+}
+
+/**
+ * The cursor fields Pull carries forward unchanged: the cadence, which belongs to the
+ * journey and not to any item.
+ *
+ * Python repeated these arguments at each call site, and the repetition is where a
+ * port silently drops one: omitting `cadence_profile` does not fail, it quietly resets
+ * the Navigator's cadence to null on the next Pull. The flow unit was carried here too,
+ * to whatever item came next; it belongs to the Delivery Story it was chosen for, and
+ * Pull decides it by that rule (CR117).
+ */
+export function carriedForward(cursor: BuilderDeliveryCursor): {
+  cadenceProfile: string | null;
+  cadenceLimits: readonly string[];
+} {
+  return {
+    cadenceProfile: cursor.cadenceProfile,
+    cadenceLimits: cursor.cadenceLimits,
+  };
+}