SubMiner/backlog/tasks/task-85 - Refactor-large-files-for-maintainability-and-readability.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	dependencies	priority	ordinal
TASK-85	Refactor large files for maintainability and readability	Done		2026-02-19 09:46	2026-02-22 07:49	architecture refactor maintainability		medium	88000

Description

This task tracked decomposition of historically oversized/high-coupling core files (src/main.ts, src/anki-integration.ts, src/config/service.ts, src/core/services/immersion-tracker-service.ts) plus launcher generated-artifact workflow guardrails and verification.

Suggestions

• Use seam tests before each extraction.
• Keep src/main.ts + src/anki-integration.ts as thin composition/coordinator layers.
• Formalize subminer as generated artifact only.

Action Steps

1. Add file-budget guardrails and baseline report.
2. Split src/main.ts into runtime domain modules (ongoing; major wiring extracted).
3. Split src/anki-integration.ts into focused collaborators (started; constructor composition decomposed).
4. Split src/config/service.ts by load/migrate/validate/warn phases (started; load/apply flow decomposition in place).
5. Split immersion tracker service by state, persistence, sync responsibilities.
6. Clarify generated launcher artifact workflow and docs.
7. Run full build/test gate and publish maintainability report.

Progress Notes

• 2026-02-20: Large src/main.ts composition slices extracted into runtime handler modules (startup, CLI, tray/window/bootstrap, shortcuts, OSD/secondary-sub, numeric/overlay shortcut lifecycle, and related seams) with focused parity tests.
• 2026-02-20: src/anki-integration.ts constructor decomposed into targeted private factory/config methods (normalizeConfig, createKnownWordCache, createPollingRunner, createCardCreationService, createFieldGroupingService) to reduce orchestration complexity.
• 2026-02-20: src/config/service.ts load/apply duplication reduced by introducing applyResolvedConfig, resolveExistingConfigPath, and parseConfigContent.
• 2026-02-20: added src/main/runtime/domains/* barrels plus src/main/runtime/registry.ts; migrated src/main.ts runtime import paths to domain barrels and added check:main-fanin guardrail script.
• 2026-02-21: extracted additional src/main.ts deps-builder orchestration into composer modules (jellyfin-remote, anilist-setup) with focused tests; tightened main fan-in guard (<=110 import lines, <=11 unique paths).
• Remaining gap for TASK-85/TASK-94: continue composer extraction for startup/overlay/ipc/shortcuts to reach fully thin composition root.
• Validation checkpoint: bun run build and focused suites (dist/config/config.test.js, dist/anki-integration.test.js) passing.
• Current strategy: prioritize high-ROI extractions (behavioral seams and churn-heavy hotspots) over further low-impact micro-shuffles.

Acceptance Criteria

• #1 src/main.ts reduced to orchestration-focused module with extracted runtime domains
• #2 src/anki-integration.ts reduced to facade with helper collaborators
• #3 Config and immersion tracker services decomposed without behavior regressions
• #4 subminer generated artifact ownership/workflow documented and enforced
• #5 Full build + config/core tests pass after refactor

Implementation Notes

TASK-95 completion slice evidence: decomposed three non-main hotspots and reduced LOC in each targeted file.

TASK-95 LOC deltas: src/anki-integration.ts -407 (1722 -> 1315), src/config/service.ts -1492 (1591 -> 99), src/core/services/immersion-tracker-service.ts -361 (1470 -> 1109).

TASK-95 extracted collaborators: src/anki-integration/field-grouping-merge.ts, src/config/{load.ts,parse.ts,warnings.ts,resolve.ts}, src/core/services/immersion-tracker/{types.ts,reducer.ts,queue.ts,maintenance.ts,query.ts}.

TASK-95 verification evidence: bun run build, bun run test:config:dist, bun run test:core:dist, bun run check:file-budgets completed with no failing tests.

2026-02-21 finalization evidence: src/main.ts currently 2878 LOC; runtime fan-in guard passes at 85 import lines / 10 unique runtime paths (bun run check:main-fanin).

Main-entrypoint scope validation for this task is fan-in/orchestration behavior, not absolute LOC target.

Launcher generated artifact workflow now strictly enforced end-to-end: scripts/verify-generated-launcher.sh fails on stale repo-root ./subminer; CI and release workflows verify dist/launcher/subminer and run the verifier script; release checksum/upload paths updated to dist/launcher/subminer.

Docs policy updated in docs/development.md and docs/installation.md to state repo-root ./subminer is stale/unsupported and generated path must be dist/launcher/subminer.

Final verification gate passed: bun run build && bun run test:config:dist && bun run test:core:dist && bun run check:file-budgets && bun run check:main-fanin.

TASK-85 AC/DoD ownership map:

• AC#1 (src/main.ts orchestration-focused runtime domains): TASK-94 (primary), TASK-71 (supporting predecessor)
• AC#2 (src/anki-integration.ts facade + collaborators): TASK-95
• AC#3 (config + immersion decomposition with no regressions): TASK-95
• AC#4 (generated launcher ownership/workflow documented + enforced): TASK-85 parent finalization evidence
• AC#5 (full build + config/core tests pass): shared verification evidence in TASK-95, TASK-94, and final TASK-85 gate
• DoD#1 (plan executed/decomposed): TASK-94 + TASK-95
• DoD#2 (regression coverage for extracted seams): TASK-94 + TASK-95
• DoD#3 (docs updated): TASK-71 architecture docs + TASK-85 launcher workflow docs

Remaining Scope (ordered):

1. Execution scope: none (all TASK-85 AC/DoD complete).
2. Process hygiene: TASK-93 closure synchronization and provenance note alignment.

Final Summary

Closed remaining TASK-85 scope by enforcing generated launcher ownership (dist/launcher/subminer) across local verification, CI, release packaging/checksums, and contributor docs. Revalidated refactor integrity with full build + config/core test gates plus maintainability guardrails (check:file-budgets, check:main-fanin) and marked parent AC/DoD complete.

Definition of Done

• #1 Plan at docs/plans/2026-02-19-repo-maintainability-refactor-plan.md executed or decomposed into child tasks
• #2 Regression coverage added for extracted seams
• #3 Docs updated for architecture and contributor workflow changes