Skip to content

Commit 285be0a

Browse files
pythoninthegrassclaude
pythoninthegrass
and
claude
committed
chore(backlog): add roam health improvement tasks (score 53/100)
Parent task TASK-285 with 11 subtasks covering dependency cycles, god components, dead exports, complexity hotspots (CC 610/438/291), and debt hotspots for library-browser, index, settings, and tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 8020d4d commit 285be0a

12 files changed

Lines changed: 436 additions & 0 deletions

‎backlog/tasks/task-285 - Improve-codebase-health-from-roam-score-53-100.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
id: TASK-285
3+
title: Improve codebase health from roam score 53/100
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:04'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
dependencies: []
11+
references:
12+
- crates/mt-tauri/src/library/commands.rs
13+
- app/frontend/js/components/library-browser.js
14+
- app/frontend/js/stores/library.js
15+
- app/frontend/main.js
16+
priority: medium
17+
---
18+
19+
## Description
20+
21+
<!-- SECTION:DESCRIPTION:BEGIN -->
22+
Roam analysis (2026-02-24) identified a health score of 53/100 for the mt codebase. This parent task tracks all remediation work for the notable issues and debt hotspots identified.
23+
24+
**Notable issues:**
25+
- 3 dependency cycles
26+
- 11 god components (degree > 20)
27+
- 247 dead exports
28+
- 22 critical-complexity symbols
29+
30+
**Debt hotspots (churn x complexity):**
31+
1. `app/frontend/js/components/library-browser.js` — debt score 1051
32+
2. `app/frontend/views/library.html` — debt score 1005
33+
3. `app/frontend/index.html` — debt score 992
34+
4. `app/frontend/tests/library.spec.js` — debt score 815
35+
5. `app/frontend/views/settings.html` — debt score 811
36+
37+
**Complexity hotspots:**
38+
- `createLibraryBrowser` CC 610
39+
- `initTauriDragDrop` CC 438
40+
- `createLibraryStore` CC 291
41+
42+
Run `roam health` and `roam understand` to get current metrics. Target is health score >= 70.
43+
<!-- SECTION:DESCRIPTION:END -->
44+
45+
## Acceptance Criteria
46+
<!-- AC:BEGIN -->
47+
- [ ] #1 Roam health score reaches 70 or above
48+
- [ ] #2 All subtasks are completed or triaged
49+
- [ ] #3 No critical-complexity symbols remain (CC > 300)
50+
<!-- AC:END -->

‎backlog/tasks/task-285.01 - Resolve-3-dependency-cycles.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
id: TASK-285.01
3+
title: Resolve 3 dependency cycles
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
dependencies: []
11+
parent_task_id: TASK-285
12+
priority: medium
13+
---
14+
15+
## Description
16+
17+
<!-- SECTION:DESCRIPTION:BEGIN -->
18+
Roam health analysis found 3 dependency cycles in the codebase. Cycles create tight coupling, make testing harder, and inflate build times.
19+
20+
Run `roam health` to identify the specific cycles. Use `roam trace <source> <target>` to understand the dependency paths involved. Break cycles by extracting shared interfaces, inverting dependencies, or restructuring modules.
21+
22+
**Context:** This is part of the roam health improvement initiative (TASK-285). Current health score is 53/100.
23+
<!-- SECTION:DESCRIPTION:END -->
24+
25+
## Acceptance Criteria
26+
<!-- AC:BEGIN -->
27+
- [ ] #1 roam health reports 0 dependency cycles
28+
- [ ] #2 No new cycles introduced (verified by roam health)
29+
<!-- AC:END -->

‎backlog/tasks/task-285.02 - Reduce-god-components-11-identified.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
id: TASK-285.02
3+
title: Reduce god components (11 identified)
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
dependencies: []
11+
parent_task_id: TASK-285
12+
priority: medium
13+
---
14+
15+
## Description
16+
17+
<!-- SECTION:DESCRIPTION:BEGIN -->
18+
Roam health analysis found 11 god components (symbols with degree > 20). God components are tightly coupled to many other symbols, making them fragile and hard to change safely.
19+
20+
Run `roam health` to list all god components with their degree and category. Use `roam context <name>` and `roam impact <name>` to understand each component's role before refactoring. Consider extracting responsibilities into smaller, focused modules.
21+
22+
**Context:** This is part of the roam health improvement initiative (TASK-285). Current health score is 53/100.
23+
<!-- SECTION:DESCRIPTION:END -->
24+
25+
## Acceptance Criteria
26+
<!-- AC:BEGIN -->
27+
- [ ] #1 God component count reduced to 5 or fewer
28+
- [ ] #2 No god component has degree > 30
29+
- [ ] #3 Existing tests still pass after refactoring
30+
<!-- AC:END -->

‎backlog/tasks/task-285.03 - Clean-up-247-dead-exports.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
id: TASK-285.03
3+
title: Clean up 247 dead exports
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
dependencies: []
11+
parent_task_id: TASK-285
12+
priority: low
13+
---
14+
15+
## Description
16+
17+
<!-- SECTION:DESCRIPTION:BEGIN -->
18+
Roam health analysis found 247 dead exports — symbols that are exported but never imported anywhere. Dead exports add noise, inflate bundle size, and mislead developers about public API surface.
19+
20+
Run `roam dead-code` (or `roam health --json` and inspect the dead_exports section) to get the full list. Remove exports that are genuinely unused. For symbols that are used externally (e.g., by tests, scripts, or runtime reflection), verify before removing.
21+
22+
**Approach:**
23+
1. Get the full dead export list from roam
24+
2. Categorize by file/module
25+
3. Remove in batches, running tests after each batch
26+
4. Re-run `roam health` to confirm dead export count drops
27+
28+
**Context:** This is part of the roam health improvement initiative (TASK-285). Current health score is 53/100.
29+
<!-- SECTION:DESCRIPTION:END -->
30+
31+
## Acceptance Criteria
32+
<!-- AC:BEGIN -->
33+
- [ ] #1 Dead export count reduced to under 50
34+
- [ ] #2 No runtime regressions (all tests pass)
35+
- [ ] #3 roam health dead_exports metric reflects the cleanup
36+
<!-- AC:END -->

‎backlog/tasks/task-285.04 - Reduce-complexity-of-createLibraryBrowser-CC-610.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
id: TASK-285.04
3+
title: Reduce complexity of createLibraryBrowser (CC 610)
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
- complexity
11+
dependencies: []
12+
references:
13+
- app/frontend/js/components/library-browser.js
14+
- app/frontend/views/library.html
15+
parent_task_id: TASK-285
16+
priority: high
17+
---
18+
19+
## Description
20+
21+
<!-- SECTION:DESCRIPTION:BEGIN -->
22+
The `createLibraryBrowser` function in `app/frontend/js/components/library-browser.js` has a cognitive complexity of 610 — the highest in the codebase. This makes it extremely difficult to reason about, test, and modify safely.
23+
24+
**Location:** `app/frontend/js/components/library-browser.js` (also the #1 debt hotspot with score 1051, churn 13k)
25+
26+
Run `roam context createLibraryBrowser --task refactor` to understand its callers, callees, and dependencies. Use `roam preflight createLibraryBrowser` before making changes to assess blast radius.
27+
28+
**Approach:** Extract cohesive groups of functionality into separate functions or sub-components. The Alpine.js component factory pattern used in this codebase makes it natural to split into smaller stores/components.
29+
30+
**Context:** This is part of the roam health improvement initiative (TASK-285). Current health score is 53/100.
31+
<!-- SECTION:DESCRIPTION:END -->
32+
33+
## Acceptance Criteria
34+
<!-- AC:BEGIN -->
35+
- [ ] #1 createLibraryBrowser CC reduced below 150
36+
- [ ] #2 All existing library browser E2E tests pass
37+
- [ ] #3 No functionality regressions in library browsing
38+
<!-- AC:END -->

‎backlog/tasks/task-285.05 - Reduce-complexity-of-initTauriDragDrop-CC-438.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
id: TASK-285.05
3+
title: Reduce complexity of initTauriDragDrop (CC 438)
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
- complexity
11+
dependencies: []
12+
references:
13+
- app/frontend/main.js
14+
- app/frontend/index.html
15+
parent_task_id: TASK-285
16+
priority: medium
17+
---
18+
19+
## Description
20+
21+
<!-- SECTION:DESCRIPTION:BEGIN -->
22+
The `initTauriDragDrop` function in `app/frontend/main.js` has a cognitive complexity of 438 — the second highest in the codebase.
23+
24+
**Location:** `app/frontend/main.js` (debt score 992 for index.html which likely wires this up)
25+
26+
Run `roam context initTauriDragDrop --task refactor` to understand its dependencies. Use `roam preflight initTauriDragDrop` before making changes.
27+
28+
**Approach:** Extract drag-drop event handlers, state management, and UI feedback into separate modules. Consider a state machine pattern for drag-drop lifecycle.
29+
30+
**Context:** This is part of the roam health improvement initiative (TASK-285). Current health score is 53/100.
31+
<!-- SECTION:DESCRIPTION:END -->
32+
33+
## Acceptance Criteria
34+
<!-- AC:BEGIN -->
35+
- [ ] #1 initTauriDragDrop CC reduced below 100
36+
- [ ] #2 Drag-and-drop functionality works correctly (manual test + any existing E2E tests)
37+
- [ ] #3 No regressions in file/track dropping behavior
38+
<!-- AC:END -->

‎backlog/tasks/task-285.06 - Reduce-complexity-of-createLibraryStore-CC-291.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
id: TASK-285.06
3+
title: Reduce complexity of createLibraryStore (CC 291)
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
- complexity
11+
dependencies: []
12+
references:
13+
- app/frontend/js/stores/library.js
14+
parent_task_id: TASK-285
15+
priority: medium
16+
---
17+
18+
## Description
19+
20+
<!-- SECTION:DESCRIPTION:BEGIN -->
21+
The `createLibraryStore` function in `app/frontend/js/stores/library.js` has a cognitive complexity of 291 — the third highest in the codebase.
22+
23+
**Location:** `app/frontend/js/stores/library.js` (churn 6.9k, 43 commits, coupled to 55 files)
24+
25+
Run `roam context createLibraryStore --task refactor` to understand its role. It's a key abstraction (high PageRank, fan-out 18). Use `roam preflight createLibraryStore` before making changes.
26+
27+
**Approach:** Extract distinct responsibilities (sorting, filtering, pagination, selection, search) into composable sub-stores or utility modules. The Alpine.js store pattern supports composition.
28+
29+
**Context:** This is part of the roam health improvement initiative (TASK-285). Current health score is 53/100.
30+
<!-- SECTION:DESCRIPTION:END -->
31+
32+
## Acceptance Criteria
33+
<!-- AC:BEGIN -->
34+
- [ ] #1 createLibraryStore CC reduced below 100
35+
- [ ] #2 All existing library-related tests pass
36+
- [ ] #3 No regressions in library store behavior (sorting, filtering, search, etc.)
37+
<!-- AC:END -->

‎backlog/tasks/task-285.07 - Address-debt-hotspot-views-library.html-score-1005.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
id: TASK-285.07
3+
title: 'Address debt hotspot: views/library.html (score 1005)'
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
dependencies: []
11+
references:
12+
- app/frontend/views/library.html
13+
- app/frontend/js/components/library-browser.js
14+
parent_task_id: TASK-285
15+
priority: medium
16+
---
17+
18+
## Description
19+
20+
<!-- SECTION:DESCRIPTION:BEGIN -->
21+
Roam identified `app/frontend/views/library.html` as the #2 debt hotspot (score 1005, complexity 23.8, churn 4.2k). High template complexity in HTML views typically indicates too much logic embedded in the template layer.
22+
23+
**Location:** `app/frontend/views/library.html`
24+
25+
Run `roam file app/frontend/views/library.html` to see the file skeleton. Examine Alpine.js directives for complex inline expressions that should be extracted to the component JS.
26+
27+
**Approach:** Move complex Alpine.js expressions and inline logic from the template into `library-browser.js` component methods. Keep templates declarative with simple bindings.
28+
29+
**Context:** This is part of the roam health improvement initiative (TASK-285). Closely related to the createLibraryBrowser complexity task.
30+
<!-- SECTION:DESCRIPTION:END -->
31+
32+
## Acceptance Criteria
33+
<!-- AC:BEGIN -->
34+
- [ ] #1 Template complexity reduced (roam reports lower complexity for this file)
35+
- [ ] #2 Inline Alpine.js expressions extracted to named methods
36+
- [ ] #3 Library view renders and functions correctly
37+
<!-- AC:END -->

‎backlog/tasks/task-285.08 - Address-debt-hotspot-index.html-score-992.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
id: TASK-285.08
3+
title: 'Address debt hotspot: index.html (score 992)'
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
dependencies: []
11+
references:
12+
- app/frontend/index.html
13+
parent_task_id: TASK-285
14+
priority: medium
15+
---
16+
17+
## Description
18+
19+
<!-- SECTION:DESCRIPTION:BEGIN -->
20+
Roam identified `app/frontend/index.html` as the #3 debt hotspot (score 992, complexity 4.9, churn 20.2k — highest churn in the entire codebase at 79 commits, coupled to 69 files).
21+
22+
**Location:** `app/frontend/index.html`
23+
24+
The extremely high churn suggests this file changes with nearly every feature. Run `roam file app/frontend/index.html` to understand its structure.
25+
26+
**Approach:** Extract inline scripts, event wiring, and component initialization into separate modules. Reduce coupling by moving feature-specific markup into view partials/components. The goal is to reduce how often this file needs to change.
27+
28+
**Context:** This is part of the roam health improvement initiative (TASK-285).
29+
<!-- SECTION:DESCRIPTION:END -->
30+
31+
## Acceptance Criteria
32+
<!-- AC:BEGIN -->
33+
- [ ] #1 Coupling partners reduced from 69 (target: under 40)
34+
- [ ] #2 Inline scripts extracted to JS modules
35+
- [ ] #3 Application loads and functions correctly
36+
<!-- AC:END -->

‎backlog/tasks/task-285.09 - Address-debt-hotspot-library.spec.js-score-815.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
id: TASK-285.09
3+
title: 'Address debt hotspot: library.spec.js (score 815)'
4+
status: To Do
5+
assignee: []
6+
created_date: '2026-02-24 00:05'
7+
labels:
8+
- tech-debt
9+
- code-health
10+
- testing
11+
dependencies: []
12+
references:
13+
- app/frontend/tests/library.spec.js
14+
parent_task_id: TASK-285
15+
priority: low
16+
---
17+
18+
## Description
19+
20+
<!-- SECTION:DESCRIPTION:BEGIN -->
21+
Roam identified `app/frontend/tests/library.spec.js` as the #4 debt hotspot (score 815, complexity 4.0, churn 20.3k). High churn in a test file suggests the tests are tightly coupled to implementation details, requiring changes whenever the code changes.
22+
23+
**Location:** `app/frontend/tests/library.spec.js`
24+
25+
**Approach:** Refactor tests to be more behavior-oriented (test user-visible outcomes, not implementation details). Extract shared test helpers and fixtures. Consider splitting into focused test files per feature area (search, sort, filter, etc.).
26+
27+
**Context:** This is part of the roam health improvement initiative (TASK-285). Should be done after or alongside the createLibraryBrowser complexity reduction.
28+
<!-- SECTION:DESCRIPTION:END -->
29+
30+
## Acceptance Criteria
31+
<!-- AC:BEGIN -->
32+
- [ ] #1 Test file split into focused test modules or significantly simplified
33+
- [ ] #2 Tests verify behavior rather than implementation details
34+
- [ ] #3 All tests pass and coverage is maintained or improved
35+
<!-- AC:END -->

0 commit comments

Comments
 (0)