Frank Schwenk
90094cf8f8
Phase 0 inventory: ~7 Python modules, no tests/CI/lint, pipeline.py concentration. Roadmap for incremental cleanup without behavior changes. Co-authored-by: Cursor <cursoragent@cursor.com>
69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# Cleanup Plan — live.f12.rocks
|
||
|
||
Phase 0 analysis (2026-07-18). Working branch: `cleanup/code-quality`.
|
||
|
||
## Project snapshot
|
||
|
||
| Area | Detail |
|
||
|------|--------|
|
||
| Stack | Python 3.11 (Docker), FastAPI, gmic, rembg, Docker Compose |
|
||
| Size | ~7 Python modules under `app/`, ~1.3k LOC |
|
||
| Tests | None (pre-cleanup) |
|
||
| Lint/format | None (pre-cleanup) |
|
||
| CI | None |
|
||
| Lockfile | Soft pins in `requirements.txt` only |
|
||
|
||
## Findings (prioritized)
|
||
|
||
1. **No test/CI/lint baseline** — high risk for refactors
|
||
2. **`pipeline.py` god module** (642 LOC) — medium risk; defer split until tests exist
|
||
3. **Meta JSON race** (worker + web concurrent writes) — documented, not fixed (behavior change)
|
||
4. **Dead code**: `blend_layers()` unused
|
||
5. **Duplication**: atomic JSON write ×3, `basicConfig` ×2, bool-env parsing ×2, compose env block ×2
|
||
6. **Double meta read** on index page (`read_status` + `read_manifest`)
|
||
7. **`compare-bg/`** — separate experiment, leave as-is (gitignored cache)
|
||
8. **`make_random.py`** — external reference only, document in ARCHITECTURE
|
||
|
||
## Risk matrix
|
||
|
||
| Area | Risk | Action |
|
||
|------|------|--------|
|
||
| Formatter/linter setup | Low | Phase 1 |
|
||
| Dead code removal | Low | Phase 1 |
|
||
| `.gitignore` / `.python-version` | Low | Phase 1 |
|
||
| Extract `io_utils`, `env_utils` | Low | Phase 2 |
|
||
| Compose env DRY (YAML anchor) | Low | Phase 2 |
|
||
| Meta read dedup in `main.py` | Low | Phase 3 |
|
||
| Magic numbers → config constants | Low | Phase 3 |
|
||
| Characterization tests | Low | Phase 5 (before deeper refactors) |
|
||
| `pipeline.py` split | Medium | **Deferred** — tests first, split later |
|
||
| Meta file locking | Medium–High | **Deferred** — behavior change |
|
||
| Dependency major bumps | Medium | List only, no auto-bump |
|
||
|
||
## Roadmap & commits
|
||
|
||
| Phase | Step | Commit theme |
|
||
|-------|------|--------------|
|
||
| 0 | This file | `docs: add cleanup plan from phase-0 analysis` |
|
||
| 1 | pyproject.toml + ruff | `chore: add pyproject.toml with ruff and pytest config` |
|
||
| 1 | ruff format | `style: apply ruff format to Python sources` |
|
||
| 1 | dead code + gitignore | `chore: remove dead code and extend gitignore` |
|
||
| 2 | io_utils extraction | `refactor: extract atomic JSON helpers to io_utils` |
|
||
| 2 | env_utils + logging | `refactor: share env-bool parsing and logging setup` |
|
||
| 2 | compose DRY | `chore: deduplicate compose environment blocks` |
|
||
| 3 | config constants | `refactor: replace magic numbers with named constants` |
|
||
| 3 | meta read dedup | `refactor: read job meta once in list_jobs` |
|
||
| 4 | dev requirements | `chore: add dev requirements and python version pin` |
|
||
| 4 | Gitea CI | `ci: add lint and test workflow` |
|
||
| 5 | tests | `test: add characterization tests for core modules` |
|
||
| 5 | docs | `docs: update README and add ARCHITECTURE` |
|
||
|
||
## Conscious non-goals
|
||
|
||
- No `pipeline.py` module split in this pass
|
||
- No meta file locking / concurrency fix
|
||
- No dependency major version bumps
|
||
- No changes to `compare-bg/` experiment
|
||
- No deploy CI (manual `docker compose` on boka stays)
|
||
- No behavior changes to gmic/rembg processing logic
|