@infinisys/is-fabric-team 0.1.0 → 0.2.0

package/lib/lanes.js

@@ -0,0 +1,391 @@
+/**
+ * Lanes: the shape of parallel work in the team ledger.
+ *
+ * A lane is one tracked requirement in flight. It owns its own stage, its own
+ * decision and its own evidence, so several asks can be worked on at once
+ * instead of queueing behind a single global cycle. What used to be the cycle's
+ * exclusivity lives in the two places that actually need it: one approved
+ * decision per lane, and a merge queue that lands branches on `master` one at a
+ * time.
+ *
+ * The ledger also keeps `stage`, `activeRequirementId` and `activeDecisionId`.
+ * They mirror the focused lane, so readers written against a single cycle (the
+ * status view, the watchdog, the panel) keep reporting something true.
+ */
+import { stageName } from './status-view.js';
+import { TeamError } from './team-error.js';
+import { requireBounded, requireSeeded } from './ledger-guards.js';
+
+/**
+ * The stage one lane is standing at.
+ *
+ * Every requirement owns its own pointer. The ledger-level `state.stage` stays
+ * as the mirror of the focused lane, and fills in for a requirement written
+ * before lanes existed.
+ *
+ * @param {object} state - ledger state.
+ * @param {object | undefined} requirement - lane record.
+ * @returns {string} stage id.
+ */
+export function laneStage(state, requirement) {
+  if (requirement === undefined) return state.stage ?? 'intake';
+  if (typeof requirement.stage === 'string') return requirement.stage;
+  return requirement.id === state.activeRequirementId ? state.stage : 'intake';
+}
+
+/**
+ * Whether one requirement is still being worked on.
+ *
+ * Ledgers written before lanes existed carry no `status` on the requirement
+ * they were working; it reads as open rather than as a closed record.
+ *
+ * @param {object | undefined} requirement - lane record.
+ * @returns {boolean} true while the lane may still advance.
+ */
+export function laneIsOpen(requirement) {
+  return requirement !== undefined && (requirement.status === undefined || requirement.status === 'open');
+}
+
+/**
+ * Every requirement still being worked on, in intake order.
+ *
+ * @param {object} state - ledger state.
+ * @returns {object[]} open lanes.
+ */
+export function openLanes(state) {
+  return (state.requirements ?? []).filter((requirement) => laneIsOpen(requirement));
+}
+
+/**
+ * The lane the ledger reports on: its focus.
+ *
+ * @param {object} state - ledger state.
+ * @returns {object | undefined} focused lane.
+ */
+export function focusedLane(state) {
+  return openLanes(state).find((requirement) => requirement.id === state.activeRequirementId);
+}
+
+/**
+ * Whether a lane still owns work in flight (a lane at retro has shipped).
+ *
+ * @param {object} state - ledger state.
+ * @param {object | undefined} requirement - lane record.
+ * @returns {boolean} true while the lane has stages ahead of it.
+ */
+export function laneInFlight(state, requirement) {
+  return laneIsOpen(requirement) && laneStage(state, requirement) !== 'retro';
+}
+
+/**
+ * Point the ledger's reported state at one lane.
+ *
+ * Focus is presentation and defaulting, never ownership: every action that
+ * changes a lane takes its id explicitly, and this only decides which lane
+ * `status` leads with and which one an action without an id lands on.
+ *
+ * @param {object} state - ledger state.
+ * @param {string} requirementId - lane to focus.
+ * @returns {object} the focused requirement.
+ * @throws {TeamError} when the requirement does not exist or is closed.
+ */
+export function focusLane(state, requirementId) {
+  const requirement = (state.requirements ?? []).find((candidate) => candidate.id === requirementId);
+  if (requirement === undefined) {
+    throw new TeamError(
+      `unknown requirement "${requirementId}"; there is no lane to focus`,
+      'unknown-requirement',
+    );
+  }
+  if (!laneIsOpen(requirement)) {
+    throw new TeamError(
+      `requirement ${requirement.id} is ${requirement.status ?? 'closed'}; only an open lane takes the focus`,
+      'lane-closed',
+      { status: 409 },
+    );
+  }
+  state.activeRequirementId = requirement.id;
+  state.activeDecisionId = requirement.decisionId ?? null;
+  state.stage = laneStage(state, requirement);
+  return requirement;
+}
+
+/**
+ * Focus the oldest lane that still has work, or report that nothing is running.
+ *
+ * @param {object} state - ledger state.
+ * @returns {object | undefined} the lane that took the focus.
+ */
+export function focusOldestRunning(state) {
+  const next = openLanes(state).find((requirement) => laneInFlight(state, requirement));
+  if (next === undefined) {
+    state.activeRequirementId = null;
+    state.activeDecisionId = null;
+    state.stage = 'intake';
+    return undefined;
+  }
+  return focusLane(state, next.id);
+}
+
+/**
+ * Resolve the lane an action lands on.
+ *
+ * An explicit id always wins. Without one, the focused lane is the default, so
+ * a caller written against the single-cycle ledger keeps working; when no lane
+ * holds the focus the action is refused instead of landing on nothing.
+ *
+ * @param {object} state - ledger state.
+ * @param {string | undefined} requirementId - explicit lane id.
+ * @returns {object} lane record.
+ * @throws {TeamError} when the lane is missing or closed.
+ */
+export function laneFor(state, requirementId) {
+  const requirement = requirementIn(state, requirementId);
+  if (!laneIsOpen(requirement)) {
+    throw new TeamError(
+      `requirement ${requirement.id} is ${requirement.status ?? 'closed'}; only an open lane advances`,
+      'lane-closed',
+      { status: 409 },
+    );
+  }
+  return requirement;
+}
+
+/**
+ * The requirement a caller named, without judging whether it is still open.
+ *
+ * @param {object} state - ledger state.
+ * @param {string | undefined} requirementId - named lane, defaulting to the focus.
+ * @returns {object} requirement record.
+ */
+export function requirementIn(state, requirementId) {
+  const wanted = requirementId ?? state.activeRequirementId;
+  if (wanted === null || wanted === undefined) {
+    throw new TeamError(
+      'no lane is in focus; pass "requirement_id" (open one with intake first)',
+      'no-active-requirement',
+    );
+  }
+  const requirement = (state.requirements ?? []).find((candidate) => candidate.id === wanted);
+  if (requirement === undefined) {
+    throw new TeamError(
+      `unknown requirement "${wanted}"; read "status" for the open lanes`,
+      'unknown-requirement',
+    );
+  }
+  return requirement;
+}
+
+/**
+ * Record where one lane's work lives.
+ *
+ * A lane without a branch and a worktree is a lane every seat edits in the same
+ * directory, which is the serial work the lanes exist to replace. Binding both
+ * is what lets two lanes edit at once: the commit's branch and the command's
+ * directory then name the lane that produced them, so no seat has to claim work
+ * and no reader has to trust the claim.
+ *
+ * @param {object} state - ledger state.
+ * @param {{ requirementId?: string, branch?: string, worktree?: string, mr?: string, member: string, now: string }} input - binding.
+ * @returns {object} the lane row.
+ */
+export function bindLane(state, input) {
+  requireSeeded(state);
+  const requirement = laneFor(state, input.requirementId);
+  if (input.branch !== undefined) {
+    requirement.branch = requireBounded(input.branch, 'branch', 200);
+  }
+  if (input.worktree !== undefined) {
+    requirement.worktree = requireBounded(input.worktree, 'worktree', 500);
+  }
+  if (input.mr !== undefined) {
+    requirement.mergeRequest = parseMergeRef(input.mr);
+  }
+  requirement.boundAt = input.now;
+  requirement.boundBy = input.member;
+  state.updatedAt = input.now;
+  return laneSummaries(state).find((lane) => lane.id === requirement.id);
+}
+
+/**
+ * One row per open lane, for the status view.
+ *
+ * Listing them is what makes parallel work visible: with one global stage a
+ * reader could not tell whether anything else was moving.
+ *
+ * @param {object} state - ledger state.
+ * @returns {object[]} lane rows.
+ */
+export function laneSummaries(state) {
+  return openLanes(state).map((lane) => ({
+    id: lane.id,
+    title: lane.title,
+    stage: laneStage(state, lane),
+    stageName: stageName(laneStage(state, lane)),
+    decisionId: lane.decisionId ?? null,
+    branch: lane.branch ?? null,
+    worktree: lane.worktree ?? null,
+    mr: lane.mergeRequest?.ref ?? null,
+    openedAt: lane.createdAt ?? null,
+    reopens: lane.reopens ?? 0,
+  }));
+}
+
+/**
+ * Put one lane on the merge queue.
+ *
+ * The queue, not the stage, is what keeps `master` buildable: any number of
+ * lanes may reach delivery, and their branches land one at a time.
+ *
+ * @param {object} state - ledger state.
+ * @param {object} requirement - lane record.
+ * @param {string} now - ISO timestamp.
+ * @returns {void}
+ */
+export function enqueueMerge(state, requirement, now) {
+  if (!Array.isArray(state.mergeQueue)) state.mergeQueue = [];
+  if (state.mergeQueue.some((entry) => entry.requirementId === requirement.id)) return;
+  state.mergeQueue.push({
+    requirementId: requirement.id,
+    branch: requirement.branch ?? null,
+    enqueuedAt: now,
+  });
+}
+
+/**
+ * Take one lane off the merge queue.
+ *
+ * @param {object} state - ledger state.
+ * @param {string} requirementId - lane to remove.
+ * @returns {void}
+ */
+export function dropFromMergeQueue(state, requirementId) {
+  if (!Array.isArray(state.mergeQueue)) return;
+  state.mergeQueue = state.mergeQueue.filter((entry) => entry.requirementId !== requirementId);
+}
+
+/**
+ * Deliveries waiting for their turn on `master`.
+ *
+ * @param {object} state - ledger state.
+ * @returns {object[]} queue rows.
+ */
+export function mergeQueueRows(state) {
+  return (state.mergeQueue ?? []).map((entry) => ({ ...entry }));
+}
+
+/**
+ * Fill in the lane fields a ledger written before lanes does not carry.
+ *
+ * Requirements recorded by the older plugin have no `status`, no `stage` and no
+ * `decisionId`; evidence rows have no `requirementId`; a requirement waiting
+ * behind a running cycle is marked `queued`. None of that is corruption, so it
+ * is read into the lane shape instead of refused: the old queue becomes lanes,
+ * and the evidence is attributed to the lane that was open when it was
+ * recorded. A ledger that already has the fields is left untouched.
+ *
+ * @param {object} value - validated ledger.
+ * @returns {void}
+ */
+export function backfillLanes(value) {
+  if (!Array.isArray(value.mergeQueue)) value.mergeQueue = [];
+  for (const requirement of value.requirements) backfillRequirement(value, requirement);
+  if (value.activeRequirementId === null && openLanes(value).length > 0) focusOldestRunning(value);
+  for (const row of value.evidence) {
+    if (row.requirementId === undefined) row.requirementId = laneAt(value, row.at);
+  }
+  for (const requirement of openLanes(value)) {
+    if (laneStage(value, requirement) === 'delivery') {
+      enqueueMerge(value, requirement, value.updatedAt);
+    }
+  }
+}
+
+/**
+ * Fill in one requirement's lane fields.
+ *
+ * @param {object} value - validated ledger.
+ * @param {object} requirement - requirement record.
+ * @returns {void}
+ */
+function backfillRequirement(value, requirement) {
+  if (requirement.status === 'queued') {
+    requirement.status = 'open';
+    requirement.stage = 'intake';
+    delete requirement.queuedAt;
+  }
+  if (requirement.status === undefined) {
+    requirement.status = requirement.id === value.activeRequirementId ? 'open' : 'delivered';
+  }
+  if (requirement.stage === undefined) {
+    requirement.stage = requirement.id === value.activeRequirementId ? value.stage : 'intake';
+  }
+  if (requirement.decisionId === undefined) {
+    requirement.decisionId = newestDecisionId(value, requirement.id);
+  }
+  if (requirement.status === 'open' && requirement.stage === 'retro') {
+    requirement.status = 'delivered';
+    requirement.deliveredAt ??= value.updatedAt;
+  }
+}
+
+/**
+ * Which lane was the open one at a moment in the past.
+ *
+ * Evidence written before lanes carries no requirement id. The lane open at the
+ * time is the newest requirement opened at or before that moment, which is what
+ * a single-cycle ledger always meant; the oldest requirement is the fallback for
+ * a row older than every intake record.
+ *
+ * @param {object} state - ledger state.
+ * @param {unknown} at - ISO timestamp of the row.
+ * @returns {string | null} requirement id.
+ */
+function laneAt(state, at) {
+  const stamp = String(at ?? '');
+  const opened = (state.requirements ?? []).filter(
+    (requirement) => String(requirement.createdAt ?? '') <= stamp,
+  );
+  if (opened.length > 0) return opened.at(-1).id;
+  return (state.requirements ?? [])[0]?.id ?? null;
+}
+
+/**
+ * Newest decision recorded for one requirement.
+ *
+ * @param {object} state - ledger state.
+ * @param {string} requirementId - lane id.
+ * @returns {string | null} decision id.
+ */
+function newestDecisionId(state, requirementId) {
+  const decisions = (state.decisions ?? []).filter(
+    (decision) => decision.requirementId === requirementId,
+  );
+  return decisions.length === 0 ? null : decisions.at(-1).id;
+}
+
+/**
+ * Read a merge-request reference written as `project#iid`.
+ *
+ * Binding the request, not just the branch, is what lets the merge gate check
+ * the lane it is about: a merge is asked of a project and an iid, and nothing
+ * in that call names the requirement.
+ *
+ * @param {string} value - merge-request reference.
+ * @returns {{ project: string, iid: number, ref: string }} parsed reference.
+ * @throws {TeamError} when the text is not `project#iid`.
+ */
+function parseMergeRef(value) {
+  const text = requireBounded(value, 'mr', 200);
+  const hash = text.lastIndexOf('#');
+  const project = hash === -1 ? '' : text.slice(0, hash).trim();
+  const iid = hash === -1 ? NaN : Number(text.slice(hash + 1).trim());
+  if (project === '' || !Number.isInteger(iid) || iid < 1) {
+    throw new TeamError(
+      '"mr" must name the merge request as "project#iid", for example "team/app#42"',
+      'invalid-arguments',
+      { status: 400 },
+    );
+  }
+  return { project, iid, ref: `${project}#${iid}` };
+}

package/lib/ledger-guards.js

@@ -0,0 +1,57 @@
+/**
+ * Guards every lane mutation runs first: the ledger is seeded, and the text a
+ * caller hands in is trimmed to a bound rather than stored raw.
+ */
+import { TeamError } from './team-error.js';
+
+/**
+ * Trim an optional string and enforce its bound.
+ *
+ * @param {unknown} value - candidate text.
+ * @param {string} field - field name for the error.
+ * @param {number} max - maximum accepted characters.
+ * @returns {string | undefined} trimmed text, or undefined when empty.
+ */
+export function optionalBounded(value, field, max) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw new TeamError(`"${field}" must be a string`, 'invalid-arguments', { status: 400 });
+  }
+  const text = value.trim();
+  if (text === '') return undefined;
+  if (text.length > max) {
+    throw new TeamError(`"${field}" exceeds ${max} characters`, 'invalid-arguments', { status: 400 });
+  }
+  return text;
+}
+
+/**
+ * Trim a required string and enforce its bound.
+ *
+ * @param {unknown} value - candidate text.
+ * @param {string} field - field name for the error.
+ * @param {number} max - maximum accepted characters.
+ * @returns {string} trimmed text.
+ */
+export function requireBounded(value, field, max) {
+  const text = optionalBounded(value, field, max);
+  if (text === undefined) {
+    throw new TeamError(`"${field}" is required`, 'invalid-arguments', { status: 400 });
+  }
+  return text;
+}
+
+/**
+ * Fail unless the team has been seeded with a GitFox project.
+ *
+ * @param {object} state - ledger state.
+ * @returns {void}
+ */
+export function requireSeeded(state) {
+  if (state.seeded !== true) {
+    throw new TeamError(
+      'The team is not seeded. The Lead must call infinity_team action "bootstrap" with the GitFox project first.',
+      'not-seeded',
+    );
+  }
+}

package/lib/open-work.js

@@ -20,7 +20,7 @@
  * as stale instead of open.
  */
 import { problemStatus } from './problem-gate.js';
-import { activeDecision } from './team-core.js';
+import { decisionOf, laneStage, openLanes } from './team-core.js';
 
 /** How long a pending review stays actionable after it was opened. */
 export const REVIEW_TTL_MS = 24 * 60 * 60 * 1000;
@@ -43,16 +43,30 @@ export function openWork(state, options = {}) {
   if (state === null || typeof state !== 'object' || state.seeded !== true) return [];
   const now = timestamp(options.now, Date.now());
   const reviewTtlMs = options.reviewTtlMs ?? REVIEW_TTL_MS;
-  const problem = problemStatus(state);
-  const requirement = activeRequirement(state, problem);
   /** @type {OpenItem[]} */
   const items = [];
-  if (requirement !== undefined && !problem.resolved) {
-    items.push(requirementItem(requirement, problem));
+  for (const requirement of openLanes(state)) {
+    items.push(...laneWork(state, requirement, now, reviewTtlMs));
   }
-  const decision = decisionItem(activeDecision(state));
+  return items;
+}
+
+/**
+ * The open work of one lane, in the order it has to be taken.
+ *
+ * @param {object} state - team ledger.
+ * @param {object} requirement - one open lane.
+ * @param {number} now - current epoch milliseconds.
+ * @param {number} ttl - review lifetime.
+ * @returns {OpenItem[]} items owed by that lane.
+ */
+function laneWork(state, requirement, now, ttl) {
+  const problem = problemStatus(state, requirement);
+  const items = [];
+  if (!problem.resolved) items.push(requirementItem(requirement, problem));
+  const decision = decisionItem(decisionOf(state, requirement));
   if (decision !== undefined) items.push(decision);
-  items.push(...reviewItems(state, requirement, now, reviewTtlMs));
+  items.push(...reviewItems(state, requirement, now, ttl));
   const workflow = workflowItem(state, requirement, problem);
   if (workflow !== undefined) items.push(workflow);
   return items;
@@ -90,13 +104,12 @@ function reviewItems(state, requirement, now, ttl) {
  * @returns {OpenItem | undefined} workflow item.
  */
 function workflowItem(state, requirement, problem) {
-  if (requirement === undefined || !problem.resolved || state.stage === 'retro') {
-    return undefined;
-  }
+  const stage = laneStage(state, requirement);
+  if (!problem.resolved || stage === 'retro') return undefined;
   return {
     kind: 'workflow',
-    ref: state.stage,
-    text: `the cycle is still at "${state.stage}" — its checks are green, so delivery and retro remain`,
+    ref: requirement.id,
+    text: `${requirement.id} is still at "${stage}" — its checks are green, so delivery and retro remain`,
   };
 }
 
@@ -116,26 +129,13 @@ export function staleReviews(state, options = {}) {
   if (state === null || typeof state !== 'object' || state.seeded !== true) return [];
   const now = timestamp(options.now, Date.now());
   const reviewTtlMs = options.reviewTtlMs ?? REVIEW_TTL_MS;
-  const problem = problemStatus(state);
-  const requirement = activeRequirement(state, problem);
+  const lanes = openLanes(state);
   return (state.reviews ?? []).filter((review) => {
     if (review.status !== 'pending') return false;
-    if (requirement === undefined) return true;
-    return !reviewBelongsToCycle(review, requirement, now, reviewTtlMs);
+    return !lanes.some((lane) => reviewBelongsToCycle(review, lane, now, reviewTtlMs));
   });
 }
 
-/**
- * The requirement the active cycle belongs to, if there is one.
- *
- * @param {object} state - ledger state.
- * @param {ReturnType<typeof problemStatus>} problem - gate view over it.
- * @returns {object | undefined} requirement record.
- */
-function activeRequirement(state, problem) {
-  return (state.requirements ?? []).find((candidate) => candidate.id === problem.requirementId);
-}
-
 /**
  * Whether one pending review still belongs to the active cycle.
  *