diff --git a/docs/superpowers/specs/2026-04-27-market-filenames-data-dimension-design.md b/docs/superpowers/specs/2026-04-27-market-filenames-data-dimension-design.md index ade0db6..fbc0726 100644 --- a/docs/superpowers/specs/2026-04-27-market-filenames-data-dimension-design.md +++ b/docs/superpowers/specs/2026-04-27-market-filenames-data-dimension-design.md @@ -1,62 +1,60 @@ -# Market filenames data-dimension design +# Go filenames consistency design ## Context -`internal/data/market` currently has mixed filename semantics (`trading_pairs.go`, `future_price.go`, `spot_price.go`, `alpha_tokens.go`). -This slows code navigation because filenames do not consistently communicate data dimension. +The repository has inconsistent `.go` filename semantics in multiple areas (domain-oriented names, endpoint/history-oriented names, mixed singular/plural forms). +This slows code navigation because filenames do not consistently communicate data dimension or responsibility. -Goal: refactor market package filenames to consistent data-dimension naming, and align function placement with filename responsibility, without changing runtime behavior. +Goal: refactor `.go` filenames across the whole repository to a consistent naming model, and align declaration placement with filename responsibility, without changing runtime behavior. ## Scope -Applies only to files in `internal/data/market`. +Applies to all `.go` files in the repository. In scope: -- Rename files to consistent names by data dimension. -- Mechanical updates needed due to file rename/move. -- Move functions between renamed files when needed so file responsibility is clear. +- Rename `.go` files to consistent, responsibility-first names. +- Mechanical updates required by rename/move. +- Move declarations between files when needed so file responsibility is clear. Out of scope: - Any behavior or logic changes. +- Non-`.go` files. - New feature work. -- Refactors outside `internal/data/market` except mechanical references. ## Requirements -1. File naming in market package is consistent by data dimension. -2. Target filenames: - - `spot_pairs.go` - - `futures_pairs.go` - - `spot_prices.go` - - `futures_prices.go` - - keep `alpha_tokens.go` -3. Function placement matches filename responsibility. +1. `.go` filename naming is consistent across the repository. +2. Filenames follow responsibility-first conventions: + - data-dimension names where applicable (`spot_*`, `futures_*`, etc.) + - pluralized collection-oriented files (`*_pairs.go`, `*_prices.go`) + - avoid endpoint/history-oriented naming that obscures responsibility. +3. Declarations in each file match filename responsibility. 4. No public/package behavior change. -5. Resulting PR focuses on refactor readability and low review noise. +5. Resulting PR remains reviewable by grouping changes mechanically and keeping logic untouched. ## Design ### Naming model -Use pluralized, data-dimension based filenames: -- `*_pairs.go` for symbol/pair resolution concerns. -- `*_prices.go` for price retrieval/processing concerns. - -### File-level responsibilities - -- `spot_pairs.go`: Spot pair/symbol resolution code. -- `futures_pairs.go`: Futures pair/symbol resolution code. -- `spot_prices.go`: Spot price read/transform code. -- `futures_prices.go`: Futures price read/transform code. -- `alpha_tokens.go`: Alpha-token specific logic (unchanged file name). +Use a responsibility-first naming model for all `.go` files: +- A reader should infer the primary responsibility from filename alone. +- Prefer domain/data-dimension names over transport/implementation-history names. +- Use consistent singular/plural convention based on file content (entity vs collection). ### Refactor mechanics -1. Rename existing files to target names using git-aware rename. -2. Inspect each renamed file for responsibility mismatch. -3. Move declarations to the matching file when mismatch exists. -4. Keep function signatures and call behavior unchanged. -5. Apply only mechanical import/reference updates if any are required. +1. Inventory `.go` files by package and classify naming inconsistencies. +2. Define target filename map package-by-package. +3. Rename files with git-aware rename operations. +4. Move declarations when file content does not match filename responsibility. +5. Keep signatures and bodies unchanged. +6. Apply only mechanical reference/import updates required by moves. + +### Execution strategy for reviewability + +- Use focused commits by package or subsystem. +- Keep each commit behavior-neutral. +- Separate any necessary declaration moves from broad rename waves when this improves diff readability. ## Error handling and behavior @@ -65,21 +63,23 @@ Existing control flow and error behavior remain unchanged. ## Testing and verification -1. Run package tests for market-related code. -2. Run project test command used by repository. -3. Confirm no functional diff beyond file rename/moves. -4. Final check: each renamed file contains only code matching its data dimension. +1. Run project tests after each major package/subsystem batch. +2. Run full project test command before PR. +3. Confirm no functional diff beyond rename/move/mechanical updates. +4. Final check: each renamed file contains declarations aligned with its responsibility. ## Risks and mitigations - Risk: accidental behavior change while moving declarations. - - Mitigation: keep signatures/body unchanged; validate with tests. -- Risk: review noise from mixed mechanical and logic edits. - - Mitigation: avoid logic edits entirely; keep commit focused on naming/responsibility alignment. + - Mitigation: keep signatures/bodies unchanged and validate with tests per batch. +- Risk: review noise from repo-wide scope. + - Mitigation: package-grouped commits, strict mechanical-only edits, and explicit PR summary. +- Risk: large PR becomes hard to review. + - Mitigation: preserve commit structure and provide a clear rename map in PR description. ## Success criteria -- Market package filenames follow the target naming scheme. -- Code in each file matches its filename responsibility. +- `.go` filenames are consistent and responsibility-first across the repo. +- Declarations in each file align with filename responsibility. - Tests pass with no behavior regression. -- PR is reviewable as a refactor-only change set. +- PR is understandable through structured, behavior-neutral commits.