auto-claude: subtask-1-3 - Create roadmap-state-utils.ts with state name constants, settled states, and mapping utilities

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-14 00:33:14 +01:00
parent 906b1f29c4
commit fa4e29f591
1 changed files with 99 additions and 0 deletions
@@ -0,0 +1,99 @@
+/**
+ * Shared XState roadmap state utilities.
+ *
+ * Provides type-safe state names, settled states, and mapping helpers
+ * derived from the roadmap machine definitions. Used by roadmap-store
+ * and roadmap hooks to avoid duplicate constants.
+ */
+import type { RoadmapGenerationStatus, RoadmapFeatureStatus } from '../types/roadmap';
+
+/**
+ * All XState generation state names.
+ *
+ * IMPORTANT: These must match the state keys in roadmap-generation-machine.ts.
+ * If you add/remove a state in the machine, update this array.
+ */
+export const GENERATION_STATE_NAMES = [
+  'idle', 'analyzing', 'discovering', 'generating', 'complete', 'error'
+] as const;
+
+export type GenerationStateName = typeof GENERATION_STATE_NAMES[number];
+
+/**
+ * All XState feature state names.
+ *
+ * IMPORTANT: These must match the state keys in roadmap-feature-machine.ts.
+ * If you add/remove a state in the machine, update this array.
+ */
+export const FEATURE_STATE_NAMES = [
+  'under_review', 'planned', 'in_progress', 'done'
+] as const;
+
+export type FeatureStateName = typeof FEATURE_STATE_NAMES[number];
+
+/**
+ * Generation states where the machine has settled — the generation is
+ * complete or has errored. Stale progress events should NOT overwrite
+ * these states, as XState is the source of truth.
+ */
+export const GENERATION_SETTLED_STATES: ReadonlySet<string> = new Set<GenerationStateName>([
+  'complete', 'error'
+]);
+
+/**
+ * Feature states where the machine has settled — the feature is done.
+ * Stale task lifecycle events should NOT overwrite this state.
+ */
+export const FEATURE_SETTLED_STATES: ReadonlySet<string> = new Set<FeatureStateName>([
+  'done'
+]);
+
+/**
+ * Maps an XState generation state to the RoadmapGenerationStatus phase.
+ *
+ * The generation machine states map 1:1 to the phase union type, so this
+ * is a type-safe identity mapping with a fallback for unknown states.
+ */
+export function mapGenerationStateToPhase(
+  state: string
+): RoadmapGenerationStatus['phase'] {
+  switch (state) {
+    case 'idle':
+      return 'idle';
+    case 'analyzing':
+      return 'analyzing';
+    case 'discovering':
+      return 'discovering';
+    case 'generating':
+      return 'generating';
+    case 'complete':
+      return 'complete';
+    case 'error':
+      return 'error';
+    default:
+      return 'idle';
+  }
+}
+
+/**
+ * Maps an XState feature state to the RoadmapFeatureStatus type.
+ *
+ * The feature machine states map 1:1 to the status union type, so this
+ * is a type-safe identity mapping with a fallback for unknown states.
+ */
+export function mapFeatureStateToStatus(
+  state: string
+): RoadmapFeatureStatus {
+  switch (state) {
+    case 'under_review':
+      return 'under_review';
+    case 'planned':
+      return 'planned';
+    case 'in_progress':
+      return 'in_progress';
+    case 'done':
+      return 'done';
+    default:
+      return 'under_review';
+  }
+}