129 lines
6.5 KiB
Markdown
129 lines
6.5 KiB
Markdown
# Technical review: video-library-manager
|
||
|
||
## Metadata
|
||
|
||
| Field | Value |
|
||
|--------|--------|
|
||
| Repository path | `dl-organizer` (package `vlm`) |
|
||
| Verification date (UTC) | 2026-04-07 |
|
||
| Git revision verified | `working tree (post-refactor)` |
|
||
| Test run | `pytest -q` → **507 passed** |
|
||
|
||
## Scope
|
||
|
||
- Source: `src/vlm/**/*.py`, `tests/`
|
||
- Config: `pyproject.toml`
|
||
- Assumption: single-user local library; artifacts semi-trusted; no formal threat model in repo.
|
||
|
||
## Executive summary
|
||
|
||
The planned hardening work is complete and the suite is green. The earlier review findings around unsafe move/rename sources, silent duplicate fallback, exact-string duplicate joins, quarantine run aborts, ambiguous `find` partial-success handling, and dict-typed plan loading are all addressed in the current codebase. The remaining observation is low-priority packaging overlap: `textual` is still declared in both the `dev` and `tui` optional extras, even though the runtime optional-boundary bug is fixed.
|
||
|
||
Weighted score (0–10): **9.0**.
|
||
|
||
## Score rubric
|
||
|
||
| Criterion | Score | Notes |
|
||
|-----------|-------|--------|
|
||
| Module boundaries / pipeline | 8.8 | Commands → domain modules remain explicit and well-separated. |
|
||
| Execution safety (filesystem) | 9.0 | Source and destination root checks are enforced for move/rename execution (`src/vlm/executor.py:204-249`). |
|
||
| Planning / duplicate logic | 9.0 | Duplicate resolution now fails explicitly on bad inputs and canonicalizes path matching (`src/vlm/duplicate_resolve.py:16-58`, `src/vlm/planner.py:42-57`, `src/vlm/planner.py:151-203`). |
|
||
| Data I/O & validation | 9.0 | Validated plan JSON now flows through a typed construction boundary (`src/vlm/io.py:247-326`). |
|
||
| Error handling consistency | 9.0 | Unsupported quarantine categories return failed results; execute loop contains per-operation exceptions (`src/vlm/quarantine.py:116-140`, `src/vlm/executor.py:108-130`). |
|
||
| Test signal | 9.2 | Full suite is green and regression coverage targets the hardened edges. |
|
||
| Dependencies | 8.5 | Runtime dependency posture is lean, but `textual` remains duplicated across optional extras (`pyproject.toml:12-20`). |
|
||
|
||
## Resolved findings
|
||
|
||
### F1 [Resolved] Move/rename source now constrained to `library_root`
|
||
|
||
**Evidence:** `src/vlm/executor.py:204-249`, `tests/test_path_safety.py:76-137`.
|
||
|
||
Execution now rejects crafted or hand-edited plans whose move/rename source or destination escapes the configured library root.
|
||
|
||
---
|
||
|
||
### F2 [Resolved] `by_quality` no longer silently falls back to first item
|
||
|
||
**Evidence:** `src/vlm/duplicate_resolve.py:44-58`, `src/vlm/planner.py:187-203`, `tests/test_duplicate_resolve.py:223-230`, `tests/test_planner.py:619-669`.
|
||
|
||
Missing or misaligned quality data now raises an explicit resolver error, and planning converts the group into manual review instead of quietly selecting index `0`.
|
||
|
||
---
|
||
|
||
### F3 [Resolved] Duplicate group ↔ identities join no longer depends on exact string equality
|
||
|
||
**Evidence:** `src/vlm/planner.py:42-57`, `src/vlm/planner.py:152-169`, `tests/test_planner.py:672-720`.
|
||
|
||
Canonical path keys are used consistently for duplicate-group matching and quality-comparison lookup.
|
||
|
||
---
|
||
|
||
### F4 [Resolved] Quarantine failures no longer abort the whole execute pass
|
||
|
||
**Evidence:** `src/vlm/quarantine.py:116-140`, `src/vlm/executor.py:108-130`, `tests/test_quarantine.py:84-110`, `tests/test_executor.py:951-1004`.
|
||
|
||
Unsupported quarantine categories now produce failed `OperationResult`s, and the execute loop continues after unexpected per-operation failures.
|
||
|
||
---
|
||
|
||
### F5 [Resolved] `find` non-zero exit behavior is now explicit
|
||
|
||
**Evidence:** `src/vlm/scanner.py:158-214`, `tests/test_scanner.py:140-186`.
|
||
|
||
Partial stdout is retained with an explicit warning; a non-zero exit with no stdout yields an empty deterministic result.
|
||
|
||
---
|
||
|
||
### F6 [Low] Optional dependency overlap remains
|
||
|
||
**Evidence:** `pyproject.toml:12-20`.
|
||
|
||
`textual` is still listed in both `dev` and `tui`. This is now a packaging/documentation concern only; the runtime issue was removed by the guarded import strategy in `src/vlm/review_tui.py:16-30` and lazy CLI import in `src/vlm/cli.py:567-602`.
|
||
|
||
---
|
||
|
||
### F7 [Resolved] Validated JSON no longer remains dict-typed at the hot execution boundary
|
||
|
||
**Evidence:** `src/vlm/io.py:247-326`, `tests/test_io.py:112-203`.
|
||
|
||
Plan loading now validates schema shape and immediately constructs an `ExecutionPlan` object.
|
||
|
||
---
|
||
|
||
### F8 [Resolved] Unknown duplicate strategy no longer defaults to first item
|
||
|
||
**Evidence:** `src/vlm/duplicate_resolve.py:54-58`, `tests/test_duplicate_resolve.py:233-237`.
|
||
|
||
Unexpected strategy strings now fail explicitly via `DuplicateResolutionError`.
|
||
|
||
## Verified strengths
|
||
|
||
| Claim | Evidence |
|
||
|--------|----------|
|
||
| Optional TUI boundary is runtime-safe | `src/vlm/cli.py:567-602`, `src/vlm/review_tui.py:16-30`, `tests/test_cli_review_plan.py:237-343` |
|
||
| Path component sanitization and planner root checks remain in place | `src/vlm/planner.py:42-57`, `src/vlm/planner.py:151-203` |
|
||
| Quarantine manifest two-phase flow remains intact | `src/vlm/quarantine.py:221-320` |
|
||
| JSON artifact validation still exists and now feeds a typed plan path | `src/vlm/io.py:165-326` |
|
||
| Parallel ffprobe behavior remains available when metadata extraction is enabled | `src/vlm/scanner.py:85-101` |
|
||
|
||
## Priority order
|
||
|
||
1. Optional-extra cleanup (`pyproject.toml:12-20`) if packaging clarity is important.
|
||
2. Otherwise, current review items are complete and the main focus can shift to new feature work.
|
||
|
||
## Verification log (current codebase)
|
||
|
||
| Statement in this doc | Checked against |
|
||
|------------------------|-----------------|
|
||
| TUI runtime boundary | `src/vlm/cli.py:567-602`, `src/vlm/review_tui.py:16-30`, `tests/test_cli_review_plan.py:237-343` |
|
||
| Move/rename source + destination checks | `src/vlm/executor.py:204-249`, `tests/test_path_safety.py:76-137` |
|
||
| Quarantine failure contract + execute containment | `src/vlm/quarantine.py:116-140`, `src/vlm/executor.py:108-130`, `tests/test_executor.py:951-1004` |
|
||
| Duplicate resolver fail-fast behavior | `src/vlm/duplicate_resolve.py:16-58`, `tests/test_duplicate_resolve.py:223-237` |
|
||
| Duplicate path normalization | `src/vlm/planner.py:42-57`, `src/vlm/planner.py:152-169`, `tests/test_planner.py:672-720` |
|
||
| Scanner partial-result contract | `src/vlm/scanner.py:158-214`, `tests/test_scanner.py:140-186` |
|
||
| Typed plan I/O boundary | `src/vlm/io.py:247-326`, `tests/test_io.py:112-203` |
|
||
| Full-suite baseline | `pytest -q` on 2026-04-07 → **507 passed** |
|
||
|
||
This document reflects the current post-refactor state rather than the pre-refactor defect list.
|