bDS/REFACTOR_DUPLICATION.md

Refactor Plan: Duplication Reduction

Date: 2026-02-15
Scope: Reduce high-impact code duplication in production and test-adjacent areas while preserving behavior.

Objectives

• Eliminate high-risk duplication that can cause drift or inconsistent behavior.
• Keep changes incremental and reviewable via phase-based PRs.
• Follow strict TDD and repository requirements (npm test and npm run build green at each phase).

Working Rules (applies to every phase)

1. Write failing tests first (Red).
2. Implement minimal code to pass (Green).
3. Refactor while staying green.
4. Run full test suite: npm test.
5. Run full build: npm run build.
6. Do not change behavior unless explicitly planned in acceptance criteria.

---

Phase 1 — Consolidate Electron API Contract (Highest ROI)

Problem

electronAPI shape is duplicated across multiple files and can drift:

• src/main/preload.ts
• src/renderer/types/electron.d.ts
• Overlapping app/store type surfaces in src/renderer/store/appStore.ts

Goal

Create one canonical API contract and consume it from both preload and renderer type declarations.

Tasks

• Add shared contract module (suggested: src/shared/electronApi.ts).
• Move reusable API interfaces/types there.
• Update src/main/preload.ts to use the shared type(s) where applicable.
• Update src/renderer/types/electron.d.ts to reference the shared contract.
• Remove duplicate preload-local ElectronAPI declarations if no longer needed.

Acceptance Criteria

• Single source of truth for electronAPI contract shape.
• No contract mismatch between preload and renderer types.
• Typecheck/build pass with no API regressions.

Risks / Notes

• Ambient type import patterns in .d.ts files can be tricky; keep changes minimal and explicit.

---

Phase 2 — Extract Common Tag Mutation Workflow

Problem

TagEngine repeats similar logic in:

• deleteTag
• mergeTags
• renameTag

Repeated steps include finding posts, parsing/updating tags JSON, syncing published files, and progress reporting.

Goal

Refactor shared behavior into private helpers while preserving all task/event semantics.

Tasks

• In src/main/engine/TagEngine.ts, add private helpers for:
  • query posts containing a tag,
  • transform tag arrays,
  • persist post tag updates + file sync,
  • shared progress calculation/reporting.
• Update deleteTag, mergeTags, and renameTag to compose helpers.
• Expand/adjust tests in tests/engine/TagEngine.test.ts to protect behavior.

Acceptance Criteria

• Public method behavior and events unchanged.
• Reduced duplicate blocks in TagEngine.
• Existing and new tests pass.

Risks / Notes

• Must preserve task progress percentages/messages expected by UI.

---

Phase 3 — Unify Single/Batch Post-Media Operations

Problem

PostMediaEngine duplicates linking/unlinking logic across single and batch methods:

• linkMediaToPost vs linkManyToPost
• unlinkMediaFromPost vs unlinkManyFromPost

Goal

Create common primitives and make single/batch methods compose them.

Tasks

• In src/main/engine/PostMediaEngine.ts, extract private primitives:
  • create/delete relation rows,
  • update media sidecar linkedPostIds (add/remove),
  • shared sort-order handling where applicable.
• Refactor single and batch methods to reuse primitives.
• Add parity tests in tests/engine/PostMediaEngine.test.ts.

Acceptance Criteria

• No behavior regressions in link/unlink semantics.
• Event behavior preserved (mediaLinked/mediaUnlinked vs batch events).
• Duplicate logic materially reduced.

Risks / Notes

• Preserve ordering and skip logic for already-linked media.

---

Phase 4 — Consolidate Project Mapping and Guard Clauses

Problem

ProjectEngine repeats:

• default-project delete protection checks,
• DB row → ProjectData mapping in several methods.

Goal

Centralize repetitive mapping and guard logic.

Tasks

• In src/main/engine/ProjectEngine.ts, add:
  • assertDeletableProject(id) (or equivalent guard helper),
  • mapDbProjectToProjectData(row) mapper.
• Replace repeated mapping/guard code in:
  • deleteProject, deleteProjectWithData,
  • getProject, getAllProjects, getActiveProject.
• Validate with tests/engine/ProjectEngine.test.ts.

Acceptance Criteria

• Same return shapes and delete behavior as before.
• Less repeated mapping/guard logic.

Risks / Notes

• Keep null/undefined normalization unchanged for optional fields.

---

Phase 5 — Extract Metadata Sync Loop Scaffolding

Problem

MetadataDiffEngine has near-identical loop scaffolding in:

• syncDbToFile
• syncFileToDb

Includes progress reporting, success/failure accounting, and event-loop yielding.

Goal

Abstract common iteration mechanics into one helper with operation-specific callbacks.

Tasks

• In src/main/engine/MetadataDiffEngine.ts, add a generic internal iterator helper that handles:
  • per-item execution,
  • success/fail accounting,
  • periodic progress updates,
  • periodic setImmediate yielding.
• Refactor both sync methods to use it.
• Verify with tests/engine/MetadataDiffEngine.test.ts.

Acceptance Criteria

• Same visible progress and final result semantics.
• Reduced duplicated loop/control-flow code.

Risks / Notes

• Progress message cadence should remain compatible with UI expectations.

---

Phase 6 — Deduplicate Shared Color Utility in Renderer

Problem

getContrastColor is duplicated in:

• src/renderer/components/TagInput/TagInput.tsx
• src/renderer/components/TagsView/TagsView.tsx

Goal

Move color contrast logic into a shared renderer utility.

Tasks

• Add utility module (suggested: src/renderer/utils/color.ts).
• Replace local implementations in both components.
• Add focused tests (suggested: tests/renderer/utils/color.test.ts).

Acceptance Criteria

• No visual behavior change.
• One implementation for contrast-color calculation.

Risks / Notes

• Verify support for both 3-char and 6-char hex inputs.

---

Suggested Delivery Sequence

1. Phase 1 (API contract)
2. Phase 2 (TagEngine)
3. Phase 3 (PostMediaEngine)
4. Phase 4 (ProjectEngine)
5. Phase 5 (MetadataDiffEngine)
6. Phase 6 (Renderer utility)

Rationale: start with highest blast-radius drift risk, then engine-level duplication, then UI utility cleanup.

---

Definition of Done (overall)

• All phases merged with passing tests/build at each step.
• No unresolved failing tests.
• Clone report shows meaningful reduction in production hotspots.
• Public behavior remains stable unless a change is explicitly approved.