Skip to content

refactor: isolate lossless cut planning - #2

Closed
anaschatz wants to merge 2 commits into
mainfrom
codex/maintainability-lossless-cut-planning
Closed

refactor: isolate lossless cut planning#2
anaschatz wants to merge 2 commits into
mainfrom
codex/maintainability-lossless-cut-planning

Conversation

@anaschatz

@anaschatz anaschatz commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Problem

shorts_generator/local/clipper.py mixed pure lossless-cut command/key/path
planning with environment state, filesystem cache orchestration and FFmpeg
execution. The planning contract was difficult to review independently without
risking output behavior or existing test patch points.

Scope

  • add 12 characterization tests before extraction
  • extract only pure command, cache-key and cache-path planning into
    shorts_generator/local/lossless_cut_planning.py
  • keep source identity I/O, cache hit/miss/touch/prune, temporary cleanup,
    logging and subprocess execution in clipper.py
  • retain every existing clipper.py facade name, signature, default, return
    shape, log and exception behavior
  • add the bounded engineering slice report

Base: 92988d82ae93845be42cc98cf0f0fd3600ef65a6

Head: 490304c9dd4d304df598f09293c8e61b41d04f23

Non-goals

No caption, highlight, Node, migration, API, infrastructure, provider, product
default, retry/fallback or video-output changes. No caller migration and no new
runtime dependency.

Dependency boundary

Before:

callers -> clipper.py
             |- command/key/path planning
             |- filesystem/cache orchestration
             `- subprocess execution

After:

callers -> clipper.py compatibility facade -> lossless_cut_planning.py
             |                              (standard-library pure leaf)
             |- filesystem/cache orchestration
             `- subprocess execution

The leaf does not import clipper.py, OpenCV, provider code or environment
configuration and performs no I/O, logging or process execution.

Measured production change

  • production boundary: 130,371 -> 130,418 LOC, net +47 (about 0.036%)
  • clipper.py: 7,609 -> 7,599 LOC, net -10
  • new pure module: 57 LOC
  • production diff: +70 / -23
  • two production modules changed; no dependency added

The small positive delta is the explicit module interface plus compatibility
facade overhead. The planning implementation is not duplicated.

Exact regression evidence

  • focused lossless/BF/highlights tests: 88 passed before the final purity check;
    12/12 dedicated characterization tests pass
  • npm run lint: pass
  • npm run build: pass
  • npm test: 1,690 total; 1,683 pass; 7 explicit skips; 0 fail
  • Python discovery: 513/513 pass (baseline 501; +12 characterization tests)
  • isolated Python modules: 52/52 pass (baseline 51/51)
  • HookGate quality: 96.2981 before and after; hard guardrails pass
  • fixture fingerprint: 37ef626b9901ad2eeb1056d47954d88cdf2ede6430cc80e449bd5f9c7a91f9c9, unchanged
  • metric fingerprint: d62ce934e038d9026263ce2be7efa5f0c6e3ffac8a583d7b23b609540a5f4fe9, unchanged
  • git diff --check: pass
  • no generated artifacts or import cycle added

Characterization freezes exact FFmpeg argv, timestamp/fps rounding, FFV1/PCM
mapping, stable cache key/path, source identity, spaces in paths, hit/miss,
disabled/zero-byte cache behavior, one execution attempt, logs, return values,
failure propagation and partial cleanup.

No deterministic video was rendered for a pixel/byte comparison, so this PR
does not claim pixel-identical output. It claims unchanged exact planning
contracts and full regression parity.

Next slice

Recommended separately: characterize and isolate import-time cache/environment
configuration. Do not start caption planning, Real-ESRGAN process planning or
highlights.py candidate discovery inside this PR.

@anaschatz

Copy link
Copy Markdown
Owner Author

Superseded by #3. The original PR retained a synthetic secret-like test string in its commit range, so the clean replacement was created from main without force-pushing or adding a gitleaks allowlist.

@anaschatz anaschatz closed this Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant