code-migration

当您在各层之间移动逻辑、弃用旧有模式、重构职责，或强制落实规范的所有者时，可选用此技能。确保迁移过程完整，杜绝遗留代码与新旧共存的情况。

SKILL.md

--- frontmatter

name: code-migration
description: Use when moving logic between layers, deprecating patterns, refactoring responsibilities, or enforcing canonical owners. Ensures migrations are complete with no legacy coexistence.

Code Migration

Core principle: When you move responsibility from A to B, delete A.

Half-migrations are technical debt. If files_helper.py and path_comp.py both construct paths, every developer must learn which one to use. That ambiguity is the bug.

Migration Checklist

When moving logic from one location to another:

• Move the code to its canonical location
• Update all call sites (use grep, not hope)
• Update skills that reference the old location
• Add ruff rules to ban imports from the old location
• Delete the old code (not deprecate - delete)
• Run validate_skills.py to catch stale references
• Run tests to confirm nothing broke

If you can't check all boxes, the migration isn't done.

Canonical Owners

Every responsibility has exactly ONE canonical owner:

Responsibility	Canonical Owner	NOT
Library path construction	`path_comp.py`	`files_helper.py`
Wall-clock timestamps	`time_helper.now_ms()`	`time.time()`
Monotonic intervals	`time_helper.internal_ms()`	`time.monotonic()`
Essentia calls	`ml_backend_essentia_comp.py`	anywhere else
Logging setup	`logging_helper.get_logger()`	`logging.getLogger()`
Config access	Injected `AppConfig`	`os.environ`, `config.yaml`

If two places can do the same thing, one of them is wrong.

Enforcement Stack

Migrations are enforced at every layer:

1. Ruff Rules (Syntax-Level)

Ban dangerous imports before code runs:

toml

# ruff.toml
[lint.flake8-tidy-imports.banned-api]
"time.time".msg = "Use nomarr.helpers.time_helper.now_ms() for timestamps"
"builtins.print".msg = "Use logging via get_logger()"

2. Import-Linter (Architecture-Level)

Prevent layer violations:

code

helpers cannot import from services
workflows cannot import from interfaces
only ml_backend_essentia_comp.py may import essentia

3. Skills (Documentation-Level)

Every skill documents what IS canonical, not what WAS.

4. validate_skills.py (Tooling-Level)

Catches stale references in skills:

bash

python scripts/validate_skills.py --check-refs

Anti-Patterns

Deprecation Warnings

python

# ❌ Wrong - deprecation is procrastination
import warnings
warnings.warn("Use path_comp instead", DeprecationWarning)

If it's deprecated, delete it. Pre-alpha means no backwards compatibility.

Keeping It Around Just In Case

python

# ❌ Wrong - dead code that looks alive
def old_path_builder(path: str) -> str:
    """DEPRECATED: Use path_comp.build_library_path_from_input()"""
    ...

Delete it. Git remembers.

TODO: Remove After Migration

python

# ❌ Wrong - TODOs are lies
# TODO: Remove this once all callers use the new API
def legacy_function():
    ...

Remove it now. The migration isn't done until it's gone.

Wrapper For Compatibility

python

# ❌ Wrong - shims become permanent
def get_path(path: str) -> str:
    """Compatibility wrapper."""
    return path_comp.build_library_path_from_input(path).absolute

Update the callers directly.

Migration Workflow

Step 1: Identify the Migration

bash

# Find all usages of the old pattern
python scripts/discover_import_chains.py nomarr.helpers.files_helper

# Or grep for specific functions
grep -r "build_path" nomarr/

Step 2: Create the Canonical Location

Move the logic to its proper layer (components for business logic, helpers for pure utilities).

Step 3: Update All Call Sites

bash

# Find all files that import the old module
grep -r "from nomarr.helpers.files_helper import" nomarr/

Step 4: Ban the Old Pattern (If Still Exists)

If old code still exists and has callers, add a temporary ruff ban to prevent new usages:

toml

# Add to ruff.toml during migration
[lint.flake8-tidy-imports.banned-api]
"nomarr.helpers.files_helper.build_path".msg = "Use path_comp.build_library_path_from_input()"

Remove the ban after deleting the old code. Bans for deleted patterns are garbage.

Step 5: Delete the Old Code

bash

git rm nomarr/helpers/old_module.py

Step 6: Update Skills

bash

python scripts/validate_skills.py --check-refs

Step 7: Verify Migration Complete

bash

# Check that all traces are gone
python scripts/check_migration.py nomarr.helpers.old_module

# If migration plan included a ruff ban, verify it exists
python scripts/check_migration.py nomarr.helpers.old_module --expect-ban

# Full QC
python scripts/run_qc.py
pytest

Decision Framework

When you find duplicate responsibilities:

code

Q: Is there a clear canonical owner?
├─ No  → Decide which location should own it
└─ Yes → Q: Does the old location still exist?
         ├─ Yes → Delete it. Update callers first if needed.
         └─ No  → Good. Verify skills and rules match reality.

When someone proposes keeping both:

code

"Can we keep the old one for compatibility?"
→ No. Pre-alpha. Delete it.

"What if something still uses it?"
→ Find it and update it. That's the migration.

"What if we need it later?"
→ Git remembers. Delete it.

Validation

Before considering a migration complete, run:

bash

python scripts/check_migration.py nomarr.old.pattern

The script validates:

• Old code is deleted, not deprecated
• No imports of the old module remain
• No skill references to old pattern
• No # TODO: remove comments remain
• (With --expect-ban) Ruff ban exists

Manual checks:

• No wrapper/shim functions exist
• Tests pass

The migration is done when there's no trace of the old pattern.