ffx/SCRATCHPAD.md

Scratchpad

Goal

• Capture a compact, project-wide list of optimization candidates after a broad scan of the current FFX codebase, tooling, and requirements.

Settled

• The biggest near-term wins are in startup cost, repeated subprocess work, repeated database query patterns, and general repo hygiene.
• This list is intentionally optimization-oriented rather than bug-oriented. Some items below also improve correctness or maintainability, but they were selected because they can reduce runtime cost, operator friction, or iteration overhead.
• A first modern integration slice now exists under tests/integration/subtrack_mapping. Remaining test-suite cleanup is now mostly about migrating and shrinking the legacy harness surface under tests/legacy.
• Shared CLI defaults for container/output tokens now live outside src/ffx/ffx_controller.py, and a focused unit test locks in the lazy-import contract.
• Helper filename and rich-text utilities now use compiled raw regexes plus translate-based filename filtering, with unit coverage for TMDB suffix rewriting and Rich color stripping.
• Process resource limiting now has explicit disabled/default states in the CLI and requirements, and combined CPU-plus-niceness wrapping now executes as cpulimit -- nice -n ... <command> instead of a less explicit prefix chain.
• FFX logger setup now reuses named handlers, and fallback logger access no longer mutates handlers in ordinary constructors and helpers.
• The process wrapper now uses subprocess.run(...) with centralized command formatting plus stable timeout and missing-command error mapping.
• Pattern matching now uses cached compiled regexes plus explicit duplicate-match errors, and pattern creation flows no longer persist zero-track patterns.

Focused Snapshot

• Highest-leverage application optimizations:

  • Decide whether placeholder help/settings screens should ship or disappear.
  • Trim dead helpers and other dormant surface that still looks active.

• Highest-leverage repo and workflow optimizations:

  • Continue migrating the oversized legacy test/combinator surface into focused modern tests so it is easier to run, debug, and extend.

Optimization Candidates

1. Placeholder UI surfaces should either ship or disappear

• src/ffx/help_screen.py and src/ffx/settings_screen.py are placeholders.
• Optimization:
  • Either remove them from the active UI surface or complete them.
  • Avoid paying ongoing maintenance cost for unfinished navigation targets.
• Expected value:
  • Leaner interface.
  • Lower UX ambiguity.

2. Several helper functions are unfinished or dead-weight

• src/ffx/helper.py contains permutateList(...): pass.
• There are many combinator and conversion placeholders across tests and migrations.
• Optimization:
  • Remove dead code, finish it, or isolate it behind a clearly dormant area.
  • Avoid carrying stubbed utility surface that looks reusable but is not.
• Expected value:
  • Smaller mental model.
  • Less time spent re-evaluating inactive paths.

3. Test suite shape is expensive to understand and likely expensive to run

• The project still carries a large legacy matrix of combinator files under tests/legacy, several placeholder pass implementations, and at least one suspicious filename with an embedded space: [tests/legacy/disposition_combinator_2_3 .py](/home/osgw/.local/src/codex/ffx/tests/legacy/disposition_combinator_2_3 .py).
• A first focused replacement slice now exists in tests/integration/subtrack_mapping/test_cli_bundle.py, so the remaining work is migration and consolidation rather than creating the modern test shape from scratch.
• Optimization:
  • Continue replacing broad combinator matrices with focused parametrized integration and unit tests.
  • Retire the bespoke legacy discovery and runner path once equivalent coverage exists.
  • Normalize file naming and test discovery conventions.
• Expected value:
  • Faster contributor onboarding.
  • Easier CI adoption later.

Open

• Should optimization work focus first on operator-perceived latency, internal maintainability, or correctness-risk cleanup that also has performance upside?
• Is the long-term supported model still “local Linux workstation plus Textual UI,” or should optimization decisions bias toward a more scriptable/headless CLI?

Gaps Right Now

• No explicit prioritization owner or milestone for the optimization backlog.
• No benchmark or timing harness exists for startup, probe, DB, or conversion orchestration overhead.
• Repo hygiene is still mixed with generated artifacts and some clearly unfinished files.
• The legacy TMDB-backed Scenario 4 path is currently blocked by a pattern/track regression: Patterns must define at least one track before they can be stored. This surfaced while rerunning TMDB-dependent checks after the zero-track pattern hardening.

Next

1. Triage the list into quick wins, medium refactors, and long-horizon cleanup.
2. Tackle the cheapest remaining product-surface cleanup first:
   • placeholder UI surfaces and dead helper cleanup.
3. Continue replacing oversized legacy test matrices with focused modern integration and unit coverage.
4. Triage the legacy Scenario 4 pattern/track failure and decide whether to fix the harness, adapt it to the zero-track guard, or retire that path during the ongoing test-suite migration.

Shifted Season Status (2026-04-12)

• Current assessment:

  • The shifted-season subsystem is present end to end and looks feature-complete in shape, but it is not yet hardened.
  • The storage, TUI CRUD surface, and CLI/TMDB filename application path all exist, so this is no longer a stubbed or half-started area.
  • The main gap is correctness and direct verification rather than missing surface area.

• Implemented surface confirmed:

  • Requirements still treat shifted seasons as part of the accepted product surface in requirements/project.md and requirements/architecture.md.
  • Persistence exists via src/ffx/model/shifted_season.py plus the Show.shifted_seasons relationship in src/ffx/model/show.py.
  • CRUD logic exists in src/ffx/shifted_season_controller.py.
  • Textual add/edit/delete flows are wired through src/ffx/shifted_season_details_screen.py, src/ffx/shifted_season_delete_screen.py, and the show details table in src/ffx/show_details_screen.py.
  • CLI conversion applies season shifts before TMDB lookup and output suffix generation in src/ffx/cli.py.

• Verified current behavior:

  • ~/.local/share/ffx.venv/bin/python -m unittest discover -s tests/unit -p 'test_*.py' passed on 2026-04-12: 75 tests in 0.795s.
  • That run emitted ResourceWarning messages for unclosed SQLite connections, so the suite is green but not perfectly clean.
  • There is almost no direct shifted-season coverage in the modern tests:
    • tests/unit/test_cli_rename_only.py stubs ShiftedSeasonController rather than exercising it.
    • tests/unit/test_screen_support.py only verifies controller bootstrap wiring.
  • Net effect: the subsystem is integrated, but its core rules are effectively untested by the current modern suite.

• Reproduced correctness gaps:

  • Overlap validation is broken in src/ffx/shifted_season_controller.py:41 because getOriginalSeason is compared as a method object instead of being called.
  • Reproduction on 2026-04-12 with a temp SQLite DB:
    • Added S1 E1-E10.
    • checkShiftedSeason(...) incorrectly returned True for overlapping S1 E5-E15.
    • addShiftedSeason(...) then stored the overlapping row successfully.
  • updateShiftedSeason(...) in src/ffx/shifted_season_controller.py:93 does not enforce episode ordering, so an invalid range like first_episode=20, last_episode=10 was accepted in the same reproduction.
  • Because src/ffx/shifted_season_controller.py:213 returns the first matching sibling and src/ffx/shifted_season_controller.py:163 applies no explicit ordering, overlapping rows would also make runtime shifting ambiguous.

• Progress summary:

  • Good progress:
    • The subsystem exists across requirements, schema, UI, and conversion flow.
    • It appears fully integrated into the show-editing workflow rather than parked as dead code.
  • Incomplete progress:
    • Validation logic is not trustworthy yet.
    • Modern tests do not currently protect the subsystem's real behavior.
    • User-facing error feedback in the shifted-season screens still has placeholder #TODO: Meldung branches.

• Recommended next slice:

  1. Add direct controller tests for overlap rejection, episode-order validation, and shiftSeason(...) selection behavior.
  2. Fix checkShiftedSeason(...) and add the same range/order validation to updateShiftedSeason(...).
  3. Make sibling selection deterministic or enforce non-overlap strongly enough that ordering no longer matters in practice.
  4. Add at least one focused integration test that proves a stored shifted season changes TMDB lookup and/or generated filename numbering during conversion.

Delete When

• Delete this scratchpad once the optimization backlog is either converted into issues/work items or distilled into durable project guidance.