motief/docs/plans/2026-04-24-003-consolidate-config-sources-plan.md

title	type	status	date
refactor: Consolidate duplicate config sources	refactor	active	2026-04-24

Consolidate Duplicate Config Sources

Overview

There are two config files: config.py (51 lines at repo root) and analysis/config.py (13K). The root config defines base Config dataclass with env vars; analysis/config.py contains SVD themes, party lists, colors, and explorer constants. This divergence is confusing and risks stale data.

Problem Frame

• Two sources of truth for configuration
• config.py is small and may be overlooked
• analysis/config.py is large and contains both constants and dynamic config
• Risk of updating one but not the other

Requirements Trace

• R1. Single canonical config module
• R2. All existing imports continue to work (backward compatibility)
• R3. No behavior changes
• R4. Tests pass after consolidation

Scope Boundaries

Included:

• Audit both config files
• Decide on canonical location
• Migrate root config into analysis/config.py or re-export
• Update imports

Excluded:

• Changing config values
• Adding new config options
• Refactoring analysis/config.py beyond import consolidation

Key Technical Decisions

• Canonical location: analysis/config.py — it already contains most config and is imported by many modules
• Backward compatibility: Root config.py becomes a thin re-export shim: from analysis.config import Config

Implementation Units

• U1. Audit config usage

Goal: Map which modules import from which config file.

Requirements: R1

Dependencies: None

Files:

• Read: config.py, analysis/config.py

Approach:

• grep -rn "from config import\|import config" --include="*.py"
• grep -rn "from analysis.config import\|import analysis.config" --include="*.py"
• Document findings

Test expectation: none — research unit.

Verification:

• Complete list of import sites

---

• U2. Migrate root config into analysis/config.py

Goal: Move Config dataclass and env var logic to analysis/config.py.

Requirements: R1, R2, R3

Dependencies: U1

Files:

• Modify: analysis/config.py
• Modify: config.py (re-export shim)

Approach:

• Move Config dataclass to analysis/config.py
• Keep root config.py as: from analysis.config import Config
• Ensure no circular imports

Execution note: Test-first — write a test that imports both config and analysis.config and verifies they expose the same Config class.

Test scenarios:

• Happy path: from config import Config still works
• Happy path: from analysis.config import Config works
• Integration: Both paths return the same object

Verification:

• uv run python -c "from config import Config; from analysis.config import Config as AC; assert Config is AC"
• All tests pass

---

• U3. Update import sites

Goal: Standardize imports to use analysis/config.py directly.

Requirements: R1

Dependencies: U2

Files:

• Modify: Files that import from root config.py

Approach:

• Replace from config import Config with from analysis.config import Config
• Mechanical change, one file at a time

Test scenarios:

• Integration: All modified files import successfully
• Regression: All tests pass

Verification:

• grep -rn "from config import" --include="*.py" returns nothing (except shim)
• Full test suite passes

---

Risks & Dependencies

Risk	Mitigation
Circular imports	analysis/config.py must not import from modules that import it
Hidden dynamic imports	Search thoroughly; test all import paths

Sources & References

• config.py
• analysis/config.py