Files
kaizoku/CODE_REVIEW.md

5.8 KiB

Repository review — 2026-10-12

Reviewed the Python application, HTTP routes, persistence and worker flows, inline browser scripts, provider bridge/adapters, dependency lockfile, Docker configuration, and regression suite. Fixes are included in release 0.53.14.

Findings addressed

Priority Finding and consequence Fix location
High Library finalization failures deleted remaining staged downloads, preventing manual recovery. queue_jobs.py: retain staging after a failed library move.
High Fractional episodes such as 12.5 were named as episode 12, risking replacement or incorrect library numbering. provider_downloader.py: preserve fractional numbers.
High Jellyfin could move a tree into a nested source/target, including files already in the destination. app.py: reject overlapping resolved folders before moving files.
High The locked undici 6.28.0 had published advisories, including a high-severity denial of service. Exploitability through Kaizoku was not established. package-lock.json: update to compatible 6.29.0; audit is clear.
Medium Folder creation and command preparation ran outside the download worker's exception handling, so a permission/path error could terminate the worker. queue_jobs.py: persist a failed job and return to the worker loop.
Medium An exception before process creation could reference an uninitialized process variable and mask the original failure. queue_jobs.py: initialize the process reference before handling runtime failures.
Medium Provider subprocesses had no overall timeout, and watchlist snapshot calls ignored their timeout argument. provider_bridge.py, provider_downloader.py, app.py: share a bounded bridge and forward snapshot timeouts.
Medium ffmpeg returning zero without a nonempty output file was treated as a successful download. provider_downloader.py: return failure for missing/empty outputs on direct and native paths.
Medium Encrypted HLS playlists without a media sequence started IV numbering at one rather than zero. provider_downloader.py: start at zero, as required by RFC 8216 §4.3.3.2.
Medium Subtitle, metadata, and partial files could falsely mark episodes or movies downloaded. app.py: restrict filesystem reconciliation to video suffixes.
Medium Jellyfin independently renamed colliding videos and subtitles, breaking their filename association. app.py: reserve destination names for each video and its sidecars together.
Medium Setting KAIZOKU_PORT changed both the host mapping and application port, while the container mapping still targeted 8421. docker-compose.yaml: keep the internal application port fixed at 8421.

Redundancy and optimization

  • Indexed subtitle companions by directory and video stem instead of scanning all staged files for every video.
  • Reused the already-read watchlist total instead of issuing an identical count query.
  • Removed unused HLS segment-directory creation and deletion; native downloads write directly to a single temporary transport stream.
  • Consolidated duplicated Python provider subprocess implementations.
  • Removed unreferenced episode selection, title variant, bearer-token, cookie-clearing, command lookup, and obsolete destination-name helpers. Retained framework callbacks and SQLite attributes flagged as possible dead code because their consumers are external to the repository.

Providers and dependencies

All three providers were compared with upstream tree ae21244a5f3cabc58bd281fff0b3560cbfb7a0f8. AnimePahe had a same-version 5.0.6 change to recover a stale One Piece UUID from its saved mapping. That change was merged while retaining Kaizoku's stderr diagnostics, mirror handling, search retry limit, and bridge background-sync guard. Anikoto and AniNeko were current. The final provider check reports no pending upstream updates, with recognized local patches for Anikoto and AnimePahe.

The dependency audit identified undici advisories GHSA-3wwx-pv8p-q78v, GHSA-r53p-7pc4-xj5r, and GHSA-rfgv-xxqx-mfg5. After updating undici, npm audit --omit=dev reports zero known vulnerabilities.

Verification and limits

  • Baseline: 294 unittest tests passed. Final suite: 305 tests passed, including new regressions for timeouts, missing outputs, fractional episodes, filesystem detection, and preservation of existing files.
  • Ruff undefined-name/unused-import checks pass; dead-code scan results were manually checked against callers.
  • Node syntax checks pass for all four inline page scripts and all four provider/bridge JavaScript files.
  • Shell syntax checks and git diff --check pass.
  • KAIZOKU_PORT=8080 docker compose config --format json confirms host 8080 maps to container 8421 and the application listens on 8421.
  • Correction in 0.53.15: the earlier test harness selected its temporary state root after importing application paths, and fixtures from the 0.53.14 runs were found in the checkout's .kaizoku/ database. The earlier isolation claim was incorrect; the available evidence does not establish whether pre-existing local records were affected. The harness now sets the environment before imports and verifies all state paths are temporary. No production deployment or service restart was performed.

Live provider playback, a Docker image build, and an actual Jellyfin server transfer were not exercised. Network checks verified upstream source versions and dependency advisories; provider behavior and file-move failures were tested with fixtures. This review does not establish the absence of all defects or cover unsupported HLS formats.