agileflow 2.91.0 → 2.92.1

package/scripts/lib/story-state-machine.js

@@ -0,0 +1,437 @@
+/**
+ * AgileFlow CLI - Story State Machine
+ *
+ * Enforces valid status transitions for user stories and maintains an audit trail.
+ * Prevents invalid state changes and provides clear error messages.
+ *
+ * Valid Status Values:
+ * - ready: Story is defined and ready to be worked on
+ * - in_progress: Story is actively being worked on
+ * - in_review: Story implementation complete, awaiting review
+ * - blocked: Story cannot proceed due to external dependency
+ * - completed: Story is done and verified
+ * - archived: Story has been archived (historical)
+ *
+ * Valid Transitions:
+ * - ready → in_progress, blocked
+ * - in_progress → in_review, blocked, ready
+ * - in_review → completed, in_progress, blocked
+ * - blocked → ready, in_progress, in_review
+ * - completed → archived, in_progress (reopened)
+ * - archived → (terminal - no transitions out)
+ */
+
+// Valid story statuses - SINGLE SOURCE OF TRUTH
+// All validators should import these constants instead of hardcoding
+const VALID_STATUSES = ['ready', 'in_progress', 'in_review', 'blocked', 'completed', 'archived'];
+
+// Statuses that indicate a story is "done" (for metrics and epic completion checks)
+const COMPLETED_STATUSES = ['completed', 'archived'];
+
+// Define valid state transitions
+// Key = from state, Value = array of valid "to" states
+const TRANSITIONS = {
+  ready: ['in_progress', 'blocked'],
+  in_progress: ['in_review', 'blocked', 'ready'],
+  in_review: ['completed', 'in_progress', 'blocked'],
+  blocked: ['ready', 'in_progress', 'in_review'],
+  completed: ['archived', 'in_progress'],
+  archived: [], // Terminal state
+};
+
+// Audit trail storage
+let auditTrail = [];
+
+/**
+ * Check if a status is valid
+ * @param {string} status - Status to check
+ * @returns {boolean} True if valid
+ */
+function isValidStatus(status) {
+  return VALID_STATUSES.includes(status);
+}
+
+/**
+ * Check if a transition is valid
+ * @param {string} fromStatus - Current status
+ * @param {string} toStatus - Target status
+ * @returns {boolean} True if transition is valid
+ */
+function isValidTransition(fromStatus, toStatus) {
+  // Same status is always valid (no-op)
+  if (fromStatus === toStatus) {
+    return true;
+  }
+
+  // Check if fromStatus has defined transitions
+  if (!TRANSITIONS[fromStatus]) {
+    return false;
+  }
+
+  // Check if toStatus is in the valid transitions list
+  return TRANSITIONS[fromStatus].includes(toStatus);
+}
+
+/**
+ * Get valid transitions from a status
+ * @param {string} fromStatus - Current status
+ * @returns {Array<string>} Array of valid target statuses
+ */
+function getValidTransitions(fromStatus) {
+  return TRANSITIONS[fromStatus] || [];
+}
+
+/**
+ * Create an audit entry
+ * @param {string} storyId - Story identifier
+ * @param {string} fromStatus - Previous status
+ * @param {string} toStatus - New status
+ * @param {Object} [metadata] - Additional metadata
+ * @returns {Object} Audit entry
+ */
+function createAuditEntry(storyId, fromStatus, toStatus, metadata = {}) {
+  return {
+    story_id: storyId,
+    from_status: fromStatus,
+    to_status: toStatus,
+    transitioned_at: new Date().toISOString(),
+    transitioned_by: metadata.actor || 'system',
+    reason: metadata.reason || null,
+    metadata: metadata.extra || {},
+  };
+}
+
+/**
+ * Log transition to audit trail
+ * @param {Object} entry - Audit entry
+ */
+function logAuditEntry(entry) {
+  auditTrail.push(entry);
+}
+
+/**
+ * Get audit trail
+ * @param {Object} [filter] - Optional filter
+ * @param {string} [filter.storyId] - Filter by story ID
+ * @param {string} [filter.fromStatus] - Filter by from status
+ * @param {string} [filter.toStatus] - Filter by to status
+ * @returns {Array} Filtered audit entries
+ */
+function getAuditTrail(filter = {}) {
+  let entries = [...auditTrail];
+
+  if (filter.storyId || filter.story_id) {
+    const id = filter.storyId || filter.story_id;
+    entries = entries.filter(e => e.story_id === id);
+  }
+  if (filter.fromStatus || filter.from_status) {
+    const status = filter.fromStatus || filter.from_status;
+    entries = entries.filter(e => e.from_status === status);
+  }
+  if (filter.toStatus || filter.to_status) {
+    const status = filter.toStatus || filter.to_status;
+    entries = entries.filter(e => e.to_status === status);
+  }
+
+  return entries;
+}
+
+/**
+ * Clear audit trail (for testing)
+ */
+function clearAuditTrail() {
+  auditTrail = [];
+}
+
+/**
+ * Transition a story to a new status
+ * @param {Object} story - Story object with at least { id, status }
+ * @param {string} toStatus - Target status
+ * @param {Object} [options] - Transition options
+ * @param {string} [options.actor] - Who is making the transition
+ * @param {string} [options.reason] - Reason for transition
+ * @param {boolean} [options.force=false] - Force transition even if invalid
+ * @returns {{ success: boolean, story: Object, error: string | null, auditEntry: Object | null }}
+ */
+function transition(story, toStatus, options = {}) {
+  const { actor = 'system', reason = null, force = false } = options;
+
+  // Validate inputs
+  if (!story || typeof story !== 'object') {
+    return {
+      success: false,
+      story: null,
+      error: 'Invalid story object',
+      auditEntry: null,
+    };
+  }
+
+  const storyId = story.id || story.storyId || 'unknown';
+  const fromStatus = story.status || 'ready';
+
+  // Validate target status
+  if (!isValidStatus(toStatus)) {
+    return {
+      success: false,
+      story,
+      error: `Invalid status: "${toStatus}". Valid statuses are: ${VALID_STATUSES.join(', ')}`,
+      auditEntry: null,
+    };
+  }
+
+  // Check transition validity
+  if (!force && !isValidTransition(fromStatus, toStatus)) {
+    const validTargets = getValidTransitions(fromStatus);
+    return {
+      success: false,
+      story,
+      error: `Invalid transition: ${fromStatus} → ${toStatus}. Valid transitions from "${fromStatus}" are: ${validTargets.join(', ') || 'none'}`,
+      auditEntry: null,
+    };
+  }
+
+  // Same status is a no-op
+  if (fromStatus === toStatus) {
+    return {
+      success: true,
+      story,
+      error: null,
+      auditEntry: null,
+    };
+  }
+
+  // Create audit entry
+  const auditEntry = createAuditEntry(storyId, fromStatus, toStatus, {
+    actor,
+    reason,
+    extra: { forced: force && !isValidTransition(fromStatus, toStatus) },
+  });
+
+  // Log to audit trail
+  logAuditEntry(auditEntry);
+
+  // Update story
+  const updatedStory = {
+    ...story,
+    status: toStatus,
+    transitioned_at: auditEntry.transitioned_at,
+    transitioned_by: auditEntry.transitioned_by,
+  };
+
+  // Add history entry if story has history array
+  if (Array.isArray(story.history)) {
+    updatedStory.history = [
+      ...story.history,
+      {
+        from: fromStatus,
+        to: toStatus,
+        at: auditEntry.transitioned_at,
+        by: auditEntry.transitioned_by,
+        reason,
+      },
+    ];
+  }
+
+  return {
+    success: true,
+    story: updatedStory,
+    error: null,
+    auditEntry,
+  };
+}
+
+/**
+ * Batch transition multiple stories
+ * @param {Array<Object>} stories - Array of story objects
+ * @param {string} toStatus - Target status
+ * @param {Object} [options] - Transition options
+ * @returns {{ success: boolean, results: Array, errors: Array }}
+ */
+function batchTransition(stories, toStatus, options = {}) {
+  const results = [];
+  const errors = [];
+
+  for (const story of stories) {
+    const result = transition(story, toStatus, options);
+    results.push(result);
+    if (!result.success) {
+      errors.push({ story_id: story.id || 'unknown', error: result.error });
+    }
+  }
+
+  return {
+    success: errors.length === 0,
+    results,
+    errors,
+  };
+}
+
+/**
+ * Get status workflow documentation
+ * @returns {Object} Workflow documentation
+ */
+function getWorkflowDoc() {
+  return {
+    statuses: VALID_STATUSES,
+    transitions: TRANSITIONS,
+    description: {
+      ready: 'Story is defined and ready to be worked on',
+      in_progress: 'Story is actively being worked on',
+      in_review: 'Story implementation complete, awaiting review',
+      blocked: 'Story cannot proceed due to external dependency',
+      completed: 'Story is done and verified',
+      archived: 'Story has been archived (historical)',
+    },
+  };
+}
+
+/**
+ * Validate a story object has required fields
+ * @param {Object} story - Story to validate
+ * @returns {{ valid: boolean, errors: Array<string> }}
+ */
+function validateStory(story) {
+  const errors = [];
+
+  if (!story) {
+    errors.push('Story is null or undefined');
+    return { valid: false, errors };
+  }
+
+  if (!story.id && !story.storyId) {
+    errors.push('Story must have an id or storyId field');
+  }
+
+  if (story.status && !isValidStatus(story.status)) {
+    errors.push(`Invalid status: ${story.status}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Check if all stories in an epic are complete
+ * @param {Object} statusData - Full status.json data
+ * @param {string} epicId - Epic ID to check
+ * @returns {{ allComplete: boolean, total: number, completed: number, remaining: Array }}
+ */
+function checkEpicCompletion(statusData, epicId) {
+  const epic = statusData.epics?.[epicId];
+  if (!epic) {
+    return { allComplete: false, total: 0, completed: 0, remaining: [] };
+  }
+
+  const storyIds = epic.stories || [];
+  const completedStatuses = ['completed', 'done', 'archived'];
+  const completed = [];
+  const remaining = [];
+
+  for (const storyId of storyIds) {
+    const story = statusData.stories?.[storyId];
+    if (story && completedStatuses.includes(story.status)) {
+      completed.push(storyId);
+    } else {
+      remaining.push(storyId);
+    }
+  }
+
+  return {
+    allComplete: remaining.length === 0 && storyIds.length > 0,
+    total: storyIds.length,
+    completed: completed.length,
+    remaining,
+  };
+}
+
+/**
+ * Auto-complete an epic if all its stories are done
+ * @param {Object} statusData - Full status.json data (will be mutated)
+ * @param {string} epicId - Epic ID to check and potentially complete
+ * @returns {{ updated: boolean, epic: Object | null, message: string }}
+ */
+function autoCompleteEpic(statusData, epicId) {
+  const epic = statusData.epics?.[epicId];
+  if (!epic) {
+    return { updated: false, epic: null, message: `Epic ${epicId} not found` };
+  }
+
+  // Already complete
+  if (epic.status === 'complete' || epic.status === 'completed') {
+    return { updated: false, epic, message: `Epic ${epicId} already complete` };
+  }
+
+  const { allComplete, total, completed } = checkEpicCompletion(statusData, epicId);
+
+  if (allComplete) {
+    epic.status = 'complete';
+    epic.completed_at = new Date().toISOString(); // Use full ISO 8601 format
+    statusData.updated_at = new Date().toISOString();
+    return {
+      updated: true,
+      epic,
+      message: `Epic ${epicId} auto-completed (${completed}/${total} stories done)`,
+    };
+  }
+
+  return {
+    updated: false,
+    epic,
+    message: `Epic ${epicId} not complete yet (${completed}/${total} stories done)`,
+  };
+}
+
+/**
+ * Find epics that should be marked complete but aren't
+ * @param {Object} statusData - Full status.json data
+ * @returns {Array<{ epicId: string, completed: number, total: number }>}
+ */
+function findIncompleteEpics(statusData) {
+  const incompleteEpics = [];
+
+  for (const [epicId, epic] of Object.entries(statusData.epics || {})) {
+    if (epic.status === 'complete' || epic.status === 'completed') {
+      continue;
+    }
+
+    const { allComplete, total, completed } = checkEpicCompletion(statusData, epicId);
+    if (allComplete) {
+      incompleteEpics.push({ epicId, completed, total });
+    }
+  }
+
+  return incompleteEpics;
+}
+
+module.exports = {
+  // Constants
+  VALID_STATUSES,
+  COMPLETED_STATUSES,
+  TRANSITIONS,
+
+  // Validation
+  isValidStatus,
+  isValidTransition,
+  getValidTransitions,
+  validateStory,
+
+  // Transitions
+  transition,
+  batchTransition,
+
+  // Audit trail
+  createAuditEntry,
+  logAuditEntry,
+  getAuditTrail,
+  clearAuditTrail,
+
+  // Documentation
+  getWorkflowDoc,
+
+  // Epic completion
+  checkEpicCompletion,
+  autoCompleteEpic,
+  findIncompleteEpics,
+};