project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/vs-code-extension/src/state/types.ts

@@ -0,0 +1,311 @@
+/**
+ * State types for SpecsMD centralized state management.
+ *
+ * This module defines the root state structure as specified in variation-8-2-spec.md.
+ * The state is the single source of truth for all UI components.
+ *
+ * Architecture:
+ *   File System → Parser → StateStore → Selectors → UI Components
+ *
+ * SOLID Principles Applied:
+ * - Single Responsibility: State types are separate from parsing and rendering
+ * - Open/Closed: Extend via new selectors without modifying core types
+ * - Interface Segregation: IStateReader and IStateWriter are separate
+ */
+
+import { Intent, Unit, Story, Bolt, Standard, ArtifactStatus, ActivityEvent } from '../parser/types';
+
+// ============================================================================
+// UI State Types
+// ============================================================================
+
+/**
+ * Tab identifiers for the sidebar.
+ */
+export type TabId = 'bolts' | 'specs' | 'overview';
+
+/**
+ * Activity feed filter options.
+ */
+export type ActivityFilter = 'all' | 'stages' | 'bolts';
+
+/**
+ * Specs tree filter options.
+ * Can be 'all' or any raw status string discovered from unit frontmatter.
+ */
+export type SpecsFilter = string;
+
+/**
+ * UI-specific state that is separate from data state.
+ * This state is persisted in workspaceState.
+ */
+export interface UIState {
+    /** Currently active tab */
+    activeTab: TabId;
+    /** Set of expanded intent IDs in specs tree */
+    expandedIntents: Set<string>;
+    /** Set of expanded unit IDs in specs tree */
+    expandedUnits: Set<string>;
+    /** Set of expanded bolt IDs */
+    expandedBolts: Set<string>;
+    /** Activity feed filter */
+    activityFilter: ActivityFilter;
+    /** Specs tree filter */
+    specsFilter: SpecsFilter;
+    /** Activity section height in pixels */
+    activitySectionHeight: number;
+    /** Whether focus card is expanded */
+    focusCardExpanded: boolean;
+}
+
+// ============================================================================
+// Computed State Types
+// ============================================================================
+
+/**
+ * Progress metrics for the overview.
+ */
+export interface ProgressMetrics {
+    totalIntents: number;
+    totalUnits: number;
+    totalStories: number;
+    totalBolts: number;
+    completedStories: number;
+    completedBolts: number;
+    overallPercent: number;
+}
+
+/**
+ * Bolt statistics for display.
+ */
+export interface BoltStats {
+    active: number;
+    queued: number;
+    done: number;
+    blocked: number;
+}
+
+/**
+ * Action types that can be suggested to the user.
+ */
+export type NextActionType =
+    | 'continue-bolt'
+    | 'start-bolt'
+    | 'complete-stage'
+    | 'unblock-bolt'
+    | 'review-stories'
+    | 'create-bolt'
+    | 'celebrate';
+
+/**
+ * Represents a suggested next action for the user.
+ */
+export interface NextAction {
+    type: NextActionType;
+    priority: number;
+    title: string;
+    description: string;
+    targetId?: string;
+    targetName?: string;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Computed/derived state that is calculated from raw data.
+ * These values are cached and updated when dependencies change.
+ */
+export interface ComputedState {
+    /** Currently selected intent (first intent with active bolts, or first intent) */
+    currentIntent: Intent | null;
+    /** All currently active bolts (in-progress), sorted by most recent */
+    activeBolts: Bolt[];
+    /** Pending bolts ordered by dependency priority */
+    pendingBolts: Bolt[];
+    /** Completed bolts */
+    completedBolts: Bolt[];
+    /** Activity feed events derived from bolt timestamps */
+    activityFeed: ActivityEvent[];
+    /** Overall progress metrics */
+    overallProgress: ProgressMetrics;
+    /** Bolt statistics */
+    boltStats: BoltStats;
+    /** Suggested next actions for the user */
+    nextActions: NextAction[];
+}
+
+// ============================================================================
+// Root State Type
+// ============================================================================
+
+/**
+ * Workspace context information.
+ */
+export interface WorkspaceContext {
+    /** Workspace name */
+    name: string;
+    /** Workspace root path */
+    path: string;
+    /** Path to memory-bank folder */
+    memoryBankPath: string;
+    /** Whether this is a valid irismd project */
+    isProject: boolean;
+}
+
+/**
+ * Root state structure for SpecsMD.
+ * This is the single source of truth for all UI components.
+ *
+ * State is organized into:
+ * 1. Workspace context - environment info
+ * 2. Raw entities - parsed from files (indexed by ID for O(1) lookup)
+ * 3. Computed state - derived values cached for performance
+ * 4. UI state - presentation state (separate from data)
+ */
+export interface SpecsMDState {
+    /** Workspace context */
+    workspace: WorkspaceContext;
+
+    /** Parsed entities indexed by ID */
+    intents: Map<string, Intent>;
+    units: Map<string, Unit>;
+    stories: Map<string, Story>;
+    bolts: Map<string, Bolt>;
+    standards: Map<string, Standard>;
+
+    /** Computed/derived state */
+    computed: ComputedState;
+
+    /** UI presentation state */
+    ui: UIState;
+}
+
+// ============================================================================
+// State Store Interfaces (Interface Segregation Principle)
+// ============================================================================
+
+/**
+ * State change event containing the new state and what changed.
+ */
+export interface StateChangeEvent {
+    state: SpecsMDState;
+    changedPaths: string[];
+}
+
+/**
+ * Listener for state changes.
+ */
+export type StateListener = (event: StateChangeEvent) => void;
+
+/**
+ * Read-only interface for state access.
+ * UI components should depend on this interface.
+ */
+export interface IStateReader {
+    /** Get the current state (immutable) */
+    getState(): Readonly<SpecsMDState>;
+
+    /** Subscribe to state changes */
+    subscribe(listener: StateListener): () => void;
+
+    // Computed value accessors (selector shortcuts)
+    getCurrentIntent(): Intent | null;
+    getActiveBolts(): Bolt[];
+    getPendingBolts(): Bolt[];
+    getActivityFeed(filter?: ActivityFilter): ActivityEvent[];
+    getBoltStats(): BoltStats;
+    getProgressMetrics(): ProgressMetrics;
+    getNextActions(): NextAction[];
+    getTopNextAction(): NextAction | null;
+}
+
+/**
+ * Write interface for state mutations.
+ * Only the parser and message handlers should use this.
+ */
+export interface IStateWriter {
+    /** Set workspace context */
+    setWorkspace(workspace: WorkspaceContext): void;
+
+    /** Update entities from parsed data */
+    setEntities(entities: {
+        intents?: Intent[];
+        units?: Unit[];
+        stories?: Story[];
+        bolts?: Bolt[];
+        standards?: Standard[];
+    }): void;
+
+    /** Update a single bolt */
+    updateBolt(bolt: Bolt): void;
+
+    /** Update UI state */
+    setUIState(updates: Partial<UIState>): void;
+
+    /** Force recomputation of derived state */
+    recompute(): void;
+}
+
+/**
+ * Combined interface for the state store.
+ */
+export interface IStateStore extends IStateReader, IStateWriter {
+    /** Dispose resources */
+    dispose(): void;
+}
+
+// ============================================================================
+// Default Values
+// ============================================================================
+
+export const DEFAULT_UI_STATE: UIState = {
+    activeTab: 'bolts',
+    expandedIntents: new Set(),
+    expandedUnits: new Set(),
+    expandedBolts: new Set(),
+    activityFilter: 'all',
+    specsFilter: 'all',
+    activitySectionHeight: 200,
+    focusCardExpanded: false
+};
+
+export const EMPTY_COMPUTED_STATE: ComputedState = {
+    currentIntent: null,
+    activeBolts: [],
+    pendingBolts: [],
+    completedBolts: [],
+    activityFeed: [],
+    overallProgress: {
+        totalIntents: 0,
+        totalUnits: 0,
+        totalStories: 0,
+        totalBolts: 0,
+        completedStories: 0,
+        completedBolts: 0,
+        overallPercent: 0
+    },
+    boltStats: { active: 0, queued: 0, done: 0, blocked: 0 },
+    nextActions: []
+};
+
+export const EMPTY_WORKSPACE: WorkspaceContext = {
+    name: '',
+    path: '',
+    memoryBankPath: '',
+    isProject: false
+};
+
+/**
+ * Creates an empty initial state.
+ */
+export function createEmptyState(): SpecsMDState {
+    return {
+        workspace: { ...EMPTY_WORKSPACE },
+        intents: new Map(),
+        units: new Map(),
+        stories: new Map(),
+        bolts: new Map(),
+        standards: new Map(),
+        computed: { ...EMPTY_COMPUTED_STATE },
+        ui: { ...DEFAULT_UI_STATE }
+    };
+}

package/src/iris_bundle/frameworks/iris-core/vs-code-extension/src/test/parser/activityFeed.test.ts

@@ -0,0 +1,269 @@
+import * as assert from 'assert';
+import {
+    buildActivityFeed,
+    filterActivityEvents,
+    limitActivityEvents,
+    formatRelativeTime
+} from '../../parser/activityFeed';
+import { Bolt, ArtifactStatus, Stage, ActivityEvent } from '../../parser/types';
+
+/**
+ * Creates a minimal mock bolt for testing.
+ */
+function createMockBolt(overrides: Partial<Bolt>): Bolt {
+    return {
+        id: 'bolt-test-1',
+        unit: 'test-unit',
+        intent: 'test-intent',
+        type: 'simple-construction-bolt',
+        status: ArtifactStatus.Draft,
+        currentStage: null,
+        stages: [],
+        stagesCompleted: [],
+        stories: [],
+        path: '/test/path',
+        filePath: '/test/path/bolt.md',
+        requiresBolts: [],
+        enablesBolts: [],
+        isBlocked: false,
+        blockedBy: [],
+        unblocksCount: 0,
+        ...overrides
+    };
+}
+
+suite('Activity Feed Test Suite', () => {
+
+    suite('buildActivityFeed', () => {
+
+        test('should create bolt-created event from createdAt', () => {
+            const bolts = [
+                createMockBolt({
+                    id: 'bolt-1',
+                    createdAt: new Date('2025-01-15T10:00:00Z')
+                })
+            ];
+            const events = buildActivityFeed(bolts);
+
+            assert.strictEqual(events.length, 1);
+            assert.strictEqual(events[0].type, 'bolt-created');
+            assert.strictEqual(events[0].targetId, 'bolt-1');
+            assert.ok(events[0].text.includes('Created'));
+        });
+
+        test('should create bolt-start event from startedAt', () => {
+            const bolts = [
+                createMockBolt({
+                    id: 'bolt-1',
+                    startedAt: new Date('2025-01-15T11:00:00Z')
+                })
+            ];
+            const events = buildActivityFeed(bolts);
+
+            assert.strictEqual(events.length, 1);
+            assert.strictEqual(events[0].type, 'bolt-start');
+            assert.ok(events[0].text.includes('Started'));
+        });
+
+        test('should create stage-complete events from stage timestamps', () => {
+            const stages: Stage[] = [
+                { name: 'plan', order: 1, status: ArtifactStatus.Complete, completedAt: new Date('2025-01-15T12:00:00Z') },
+                { name: 'implement', order: 2, status: ArtifactStatus.Complete, completedAt: new Date('2025-01-15T14:00:00Z') }
+            ];
+            const bolts = [createMockBolt({ id: 'bolt-1', stages })];
+            const events = buildActivityFeed(bolts);
+
+            assert.strictEqual(events.length, 2);
+            const stageEvents = events.filter(e => e.type === 'stage-complete');
+            assert.strictEqual(stageEvents.length, 2);
+            assert.ok(stageEvents.some(e => e.text.includes('plan')));
+            assert.ok(stageEvents.some(e => e.text.includes('implement')));
+        });
+
+        test('should create bolt-complete event from completedAt', () => {
+            const bolts = [
+                createMockBolt({
+                    id: 'bolt-1',
+                    completedAt: new Date('2025-01-15T16:00:00Z')
+                })
+            ];
+            const events = buildActivityFeed(bolts);
+
+            assert.strictEqual(events.length, 1);
+            assert.strictEqual(events[0].type, 'bolt-complete');
+            assert.ok(events[0].text.includes('Completed'));
+        });
+
+        test('should sort events by timestamp descending (most recent first)', () => {
+            const bolts = [
+                createMockBolt({
+                    id: 'bolt-1',
+                    createdAt: new Date('2025-01-15T10:00:00Z'),
+                    startedAt: new Date('2025-01-15T11:00:00Z'),
+                    completedAt: new Date('2025-01-15T16:00:00Z')
+                })
+            ];
+            const events = buildActivityFeed(bolts);
+
+            assert.strictEqual(events.length, 3);
+            assert.strictEqual(events[0].type, 'bolt-complete');
+            assert.strictEqual(events[1].type, 'bolt-start');
+            assert.strictEqual(events[2].type, 'bolt-created');
+        });
+
+        test('should return empty array for bolts without timestamps', () => {
+            const bolts = [createMockBolt({ id: 'bolt-1' })];
+            const events = buildActivityFeed(bolts);
+
+            assert.strictEqual(events.length, 0);
+        });
+
+        test('should handle multiple bolts', () => {
+            const bolts = [
+                createMockBolt({
+                    id: 'bolt-1',
+                    createdAt: new Date('2025-01-15T10:00:00Z')
+                }),
+                createMockBolt({
+                    id: 'bolt-2',
+                    createdAt: new Date('2025-01-15T09:00:00Z')
+                })
+            ];
+            const events = buildActivityFeed(bolts);
+
+            assert.strictEqual(events.length, 2);
+            assert.strictEqual(events[0].targetId, 'bolt-1'); // More recent first
+            assert.strictEqual(events[1].targetId, 'bolt-2');
+        });
+
+        test('should set correct tags for events', () => {
+            const stages: Stage[] = [
+                { name: 'plan', order: 1, status: ArtifactStatus.Complete, completedAt: new Date('2025-01-15T12:00:00Z') }
+            ];
+            const bolts = [
+                createMockBolt({
+                    id: 'bolt-1',
+                    createdAt: new Date('2025-01-15T10:00:00Z'),
+                    stages
+                })
+            ];
+            const events = buildActivityFeed(bolts);
+
+            const boltEvent = events.find(e => e.type === 'bolt-created');
+            const stageEvent = events.find(e => e.type === 'stage-complete');
+
+            assert.strictEqual(boltEvent?.tag, 'bolt');
+            assert.strictEqual(stageEvent?.tag, 'stage');
+        });
+
+        test('should include icon and iconClass for each event', () => {
+            const bolts = [
+                createMockBolt({
+                    id: 'bolt-1',
+                    createdAt: new Date('2025-01-15T10:00:00Z')
+                })
+            ];
+            const events = buildActivityFeed(bolts);
+
+            assert.ok(events[0].icon);
+            assert.ok(events[0].iconClass);
+        });
+    });
+
+    suite('filterActivityEvents', () => {
+
+        const mockEvents: ActivityEvent[] = [
+            { id: 'e1', type: 'bolt-created', timestamp: new Date(), icon: '+', iconClass: 'bolt-created', text: 'Created bolt-1', targetId: 'bolt-1', targetName: 'bolt-1', tag: 'bolt' },
+            { id: 'e2', type: 'stage-complete', timestamp: new Date(), icon: '✓', iconClass: 'stage-complete', text: 'Completed plan', targetId: 'bolt-1', targetName: 'bolt-1', tag: 'stage' },
+            { id: 'e3', type: 'bolt-complete', timestamp: new Date(), icon: '✔', iconClass: 'bolt-complete', text: 'Completed bolt-1', targetId: 'bolt-1', targetName: 'bolt-1', tag: 'bolt' }
+        ];
+
+        test('should return all events when tag is "all"', () => {
+            const result = filterActivityEvents(mockEvents, 'all');
+            assert.strictEqual(result.length, 3);
+        });
+
+        test('should filter to bolt events only', () => {
+            const result = filterActivityEvents(mockEvents, 'bolt');
+            assert.strictEqual(result.length, 2);
+            assert.ok(result.every(e => e.tag === 'bolt'));
+        });
+
+        test('should filter to stage events only', () => {
+            const result = filterActivityEvents(mockEvents, 'stage');
+            assert.strictEqual(result.length, 1);
+            assert.ok(result.every(e => e.tag === 'stage'));
+        });
+    });
+
+    suite('limitActivityEvents', () => {
+
+        const mockEvents: ActivityEvent[] = [
+            { id: 'e1', type: 'bolt-created', timestamp: new Date(), icon: '+', iconClass: 'bolt-created', text: 'Created bolt-1', targetId: 'bolt-1', targetName: 'bolt-1', tag: 'bolt' },
+            { id: 'e2', type: 'bolt-start', timestamp: new Date(), icon: '▶', iconClass: 'bolt-start', text: 'Started bolt-1', targetId: 'bolt-1', targetName: 'bolt-1', tag: 'bolt' },
+            { id: 'e3', type: 'bolt-complete', timestamp: new Date(), icon: '✔', iconClass: 'bolt-complete', text: 'Completed bolt-1', targetId: 'bolt-1', targetName: 'bolt-1', tag: 'bolt' }
+        ];
+
+        test('should limit to specified count', () => {
+            const result = limitActivityEvents(mockEvents, 2);
+            assert.strictEqual(result.length, 2);
+        });
+
+        test('should return all events if limit exceeds count', () => {
+            const result = limitActivityEvents(mockEvents, 10);
+            assert.strictEqual(result.length, 3);
+        });
+
+        test('should return empty array for limit of 0', () => {
+            const result = limitActivityEvents(mockEvents, 0);
+            assert.strictEqual(result.length, 0);
+        });
+    });
+
+    suite('formatRelativeTime', () => {
+
+        test('should return "Just now" for timestamps within 60 seconds', () => {
+            const now = new Date('2025-01-15T10:00:00Z');
+            const timestamp = new Date('2025-01-15T09:59:30Z');
+
+            assert.strictEqual(formatRelativeTime(timestamp, now), 'Just now');
+        });
+
+        test('should return minutes for timestamps within an hour', () => {
+            const now = new Date('2025-01-15T10:00:00Z');
+            const timestamp = new Date('2025-01-15T09:45:00Z');
+
+            assert.strictEqual(formatRelativeTime(timestamp, now), '15m ago');
+        });
+
+        test('should return hours for timestamps within a day', () => {
+            const now = new Date('2025-01-15T10:00:00Z');
+            const timestamp = new Date('2025-01-15T07:00:00Z');
+
+            assert.strictEqual(formatRelativeTime(timestamp, now), '3h ago');
+        });
+
+        test('should return "Yesterday" for timestamps from previous day', () => {
+            const now = new Date('2025-01-15T10:00:00Z');
+            const timestamp = new Date('2025-01-14T10:00:00Z');
+
+            assert.strictEqual(formatRelativeTime(timestamp, now), 'Yesterday');
+        });
+
+        test('should return days for timestamps within a week', () => {
+            const now = new Date('2025-01-15T10:00:00Z');
+            const timestamp = new Date('2025-01-12T10:00:00Z');
+
+            assert.strictEqual(formatRelativeTime(timestamp, now), '3d ago');
+        });
+
+        test('should return date for timestamps older than a week', () => {
+            const now = new Date('2025-01-15T10:00:00Z');
+            const timestamp = new Date('2025-01-01T10:00:00Z');
+
+            const result = formatRelativeTime(timestamp, now);
+            // Should be a date string, not a relative time
+            assert.ok(result.includes('/') || result.includes('-'));
+        });
+    });
+});