root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(FN-3165): document roadmap plugin extraction

Browse Source 
- Update architecture docs to reflect roadmap ownership in plugins/fusion-plugin-roadmap instead of @fusion/core
- Clarify storage table docs so roadmap tables are described as plugin-owned schema hooks
- Rewrite FN-1675 audit section to remove obsolete core-roadmap test references and point to current plugin/dashboard test commands
- Add a changeset for @runfusion/fusion documenting the roadmap extraction doc cleanup

Fusion-Task-Id: FN-3165
This commit is contained in:
Fusion
2026-05-08 22:29:24 -07:00
committed by gsxdsm
parent 12bad74955
commit b41cb84a7a
4 changed files with 19 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.changeset/FN-3165-removal.md Normal file
View File

@@ -0,0 +1,5 @@
---
"@runfusion/fusion": patch
---
Remove roadmap ownership from `@fusion/core` by deleting remaining roadmap type exports and keeping roadmap contracts in the roadmap plugin package (`@fusion-plugin-examples/roadmap`).

9
docs/architecture.md
View File

@@ -177,12 +177,8 @@ Concrete references:
- Core schema tables include: `tasks`, `config`, `workflow_steps`, `activityLog`, `archivedTasks`, `automations`, `agents`, `agentHeartbeats`, approval tables (`approval_requests`, `approval_request_audit_events`), `task_documents`, `task_document_revisions`, mission hierarchy tables (`missions`, `milestones`, `slices`, `mission_features`, `mission_events`), plugin/routine tables (`plugins`, `routines`), roadmap tables (`roadmaps`, `roadmap_milestones`, `roadmap_features`), insight tables (`project_insights`, `project_insight_runs`), research tables (`research_runs`, `research_exports`, `research_run_events`), eval tables (`eval_runs`, `eval_task_results`, `eval_run_events`), todo tables (`todo_lists`, `todo_items`), `__meta`
- Migration-created tables include: `ai_sessions`, `messages`, `agentRatings`, `chat_sessions`, `chat_messages`, `runAuditEvents`, `mission_contract_assertions`, `mission_feature_assertions`, `mission_validator_runs`, `mission_validator_failures`, `mission_fix_feature_lineage`
- `ai_sessions.status` lifecycle includes `draft` (pre-start planning session), then `generating`, `awaiting_input`, terminal `complete` / `error`
- **Standalone roadmap model**: `packages/core/src/roadmap-types.ts`, `roadmap-ordering.ts`, `roadmap-store.ts`
- Roadmap-first entity types (`Roadmap`, `RoadmapMilestone`, `RoadmapFeature`)
- Pure ordering helpers for contiguous 0-based milestone/feature order and deterministic cross-milestone feature moves
- `RoadmapStore` for CRUD operations, deterministic ordering, and atomic reorder/move operations
- Dashboard API routes in `packages/dashboard/src/roadmap-routes.ts`
- Exported from `@fusion/core` for downstream persistence/API/UI work
- **Roadmap feature ownership**: roadmap contracts, ordering/handoff helpers, and persistence live in `plugins/fusion-plugin-roadmap` (package `@fusion-plugin-examples/roadmap`) rather than `@fusion/core`
- Dashboard route adapter remains in `packages/dashboard/src/roadmap-routes.ts` and consumes the plugin API
- **CentralCore**: `packages/core/src/central-core.ts`
- Global project registry, health, central activity feed, global concurrency
- Backed by `packages/core/src/central-db.ts` (`~/.fusion/fusion-central.db`)
@@ -197,7 +193,6 @@ Concrete references:
- `ReflectionStore` (`reflection-store.ts`) — agent reflection records and performance snapshots
- `PluginStore` (`plugin-store.ts`) — plugin registry/state/settings persistence
- `RoutineStore` (`routine-store.ts`) — recurring routine definitions and run history
- `RoadmapStore` (`roadmap-store.ts`) — standalone roadmap CRUD with deterministic ordering and atomic reorder/move operations
- `TodoStore` (`todo-store.ts`) — project-scoped todo lists/items with completion, reorder, and composite list+items queries
- `EvalStore` (`eval-store.ts`) — eval run persistence, per-task eval results with durable snapshots, and append-only run event trails

6
docs/storage.md
View File

@@ -189,9 +189,9 @@ Additional backend notes:
| `mission_events` | Mission event log with ordered sequence numbers and metadata payloads. |
| `plugins` | Plugin registry, lifecycle state, dependency metadata, and settings blobs. |
| `routines` | Routine definitions (trigger config, steps/command, catch-up policy, run history, and persisted `agentId` ownership metadata). Legacy databases missing routine fields (including `agentId`) are backfilled during init-time compatibility migration. |
| `roadmaps` | Standalone roadmap metadata. |
| `roadmap_milestones` | Milestones within roadmaps (`roadmapId` FK). |
| `roadmap_features` | Features within roadmap milestones (`milestoneId` FK). |
| `roadmaps` | Roadmap plugin metadata (owned/registered by `plugins/fusion-plugin-roadmap`). |
| `roadmap_milestones` | Milestones within roadmaps (`roadmapId` FK), owned/registered by roadmap plugin schema hooks. |
| `roadmap_features` | Features within roadmap milestones (`milestoneId` FK), owned/registered by roadmap plugin schema hooks. |
| `project_insights` | Extracted project insights with fingerprint-based deduplication and provenance metadata. |
| `project_insight_runs` | Insight extraction run history with durable lifecycle metadata (`lifecycle` JSON includes terminalReason/cause, failureClass, retryable flag, cancellationRequestedAt, timeoutAt, retry lineage fields). Terminal rows are immutable for state transitions. |
| `project_insight_run_events` | Append-only per-run lifecycle trail (`seq`, `type`, `message`, optional `status`/`classification`/`metadata`) used by cancel/retry/timeout auditing and API inspection. |

94
docs/test-audit-report.md
View File

@@ -271,94 +271,18 @@ Created from this audit:
# FN-1675 Roadmap Regression Test Coverage
_Date: 2026-04-16_
_Date: 2026-04-16 (updated 2026-05-08)_
## Summary
Roadmap ownership has moved out of `@fusion/core` into `plugins/fusion-plugin-roadmap` (`@fusion-plugin-examples/roadmap`).
Added comprehensive regression test coverage for the standalone roadmap feature set across core persistence, dashboard API routes, and frontend hook/component layers.
- Core roadmap tests/fixtures referenced in earlier drafts (`packages/core/src/roadmap-*.ts` and `packages/core/src/__tests__/roadmap-*.test.ts`) were removed during plugin extraction.
- Dashboard roadmap adapter coverage remains at `packages/dashboard/src/__tests__/roadmap-routes.routes.test.ts`.
- Roadmap domain/ordering/handoff/store coverage now belongs with plugin package tests.
## Coverage Matrix
### Core Persistence (`packages/core/src/`)
| Test File | Tests | Coverage Areas |
|-----------|-------|---------------|
| `roadmap-store.test.ts` | 86 | CRUD operations, reorder (milestone/feature), cross-milestone move, hierarchy operations, export/handoff, **persistence re-instantiation**, **negative ordering tests** |
| `roadmap-ordering.test.ts` | 14 | Pure ordering helpers, deterministic tie-breaker resolution, **boundary tests (negative/NaN/Infinity targetOrderIndex)**, **contiguous orderIndex verification** |
| `roadmap-handoff.test.ts` | 20 | Handoff mapping functions, source lineage preservation, deterministic ordering |
**Key additions:**
- Persistence re-instantiation tests verifying data survives database close/reopen
- Boundary tests for `targetOrderIndex` clamping (negative, NaN, Infinity)
- Negative tests for roadmapId/fromMilestoneId mismatches
- Explicit contiguous orderIndex assertions for all reorder/move operations
### Dashboard Routes (`packages/dashboard/src/`)
| Test File | Tests | Coverage Areas |
|-----------|-------|---------------|
| `roadmap-routes.routes.test.ts` | 30 | CRUD endpoints, reorder/move, suggestions (mocked), handoff, project scoping, **validation error (400) tests** |
| `roadmap-suggestions.test.ts` | 65 | Input validation, AI output normalization, failure behavior |
**Key additions:**
- 400 validation error tests for roadmap/milestone/feature creation
- 400 validation error tests for reorder payloads
### Dashboard Hooks (`packages/dashboard/app/hooks/`)
| Test File | Tests | Coverage Areas |
|-----------|-------|---------------|
| `useRoadmaps.test.ts` | 52 | State management, CRUD, reorder/move with optimistic updates, rollback on failure, **handoff/fetch**, **stale async guard**, **no-op suppression** |
**Key additions:**
- Handoff/fetch tests (fetchHandoff, clearHandoff, project-context clearing)
- Stale async response rejection for handoff fetches
- No-op suppression tests for reorder/move operations
### Dashboard API Wrapper (`packages/dashboard/app/`)
| Test File | Tests | Coverage Areas |
|-----------|-------|---------------|
| `api.test.ts` | 14 (roadmap-specific) | Roadmap API wrappers, 204 void handling, projectId propagation, reorder/move/suggestion/handoff endpoints |
## Test Quality Notes
- **Persistence tests** use isolated temp directories with proper cleanup
- **Stale async guard** tests use version-ref pattern matching `useTasks` patterns
- **No-op suppression** prevents unnecessary API calls for no-position-change operations
- **Validation tests** cover both happy-path and error-path assertions
- **Boundary tests** cover edge cases (negative, NaN, Infinity indices)
## Files Modified
### Core (`packages/core/src/`)
- `roadmap-store.test.ts` — +349 lines (persistence, negative ordering, listFeatureTaskPlanningHandoffs, getMissionPlanningHandoff)
- `roadmap-ordering.test.ts` — +4 tests (boundary conditions)
### Dashboard Routes (`packages/dashboard/src/`)
- `roadmap-routes.routes.test.ts` — +65 lines (400 validation tests)
### Dashboard Hooks (`packages/dashboard/app/hooks/`)
- `useRoadmaps.ts` — Fixed stale closure bug (use `projectIdRef.current`)
- `useRoadmaps.test.ts` — +313 lines (handoff tests, no-op suppression tests)
## Test Execution
Use plugin/dashboard scoped commands instead of core roadmap commands:
```bash
# Core roadmap tests
pnpm --filter @fusion/core exec vitest run src/roadmap-store.test.ts src/roadmap-ordering.test.ts src/roadmap-handoff.test.ts
# Dashboard route tests
pnpm --filter @fusion/dashboard exec vitest run src/roadmap-routes.routes.test.ts src/roadmap-suggestions.test.ts
# Dashboard hook tests
pnpm --filter @fusion/dashboard exec vitest run app/hooks/__tests__/useRoadmaps.test.ts
# All roadmap tests (combined)
pnpm --filter @fusion/core exec vitest run src/roadmap
pnpm --filter @fusion/dashboard exec vitest run src/roadmap app/api.test.ts -t roadmap
pnpm --filter @fusion-plugin-examples/roadmap test
pnpm --filter @fusion/dashboard exec vitest run src/__tests__/roadmap-routes.routes.test.ts
pnpm --filter @fusion/dashboard exec vitest run app/__tests__/api-settings.test.ts -t roadmap
```
## Coverage Verification
All 120 core roadmap tests pass, 95 dashboard route/suggestion tests pass, 52 hook tests pass.