Migrate from Poetry and pyenv to uv

docs/modules/core.integrity.md

@@ -0,0 +1,77 @@
+# `src/core/integrity.py`
+
+Video integrity checking via FFmpeg.
+
+Detects corrupted or unreadable video files. Two depths:
+
+- **deep** (default): a full `ffmpeg` decode to the null muxer
+  (`-f null`). It actually decodes every frame, so it catches mid-file data
+  corruption (broken GOPs, truncated streams, bad packets). Thorough but slow —
+  it reads and decodes the whole file.
+- **quick**: an `ffprobe` container/stream probe. Fast but shallow — it catches
+  an unreadable container, a truncated header or a missing video stream, but not
+  corruption buried inside otherwise-parseable data.
+
+Both tools ship with FFmpeg; `ffmpeg_available` reports whether they are on the
+PATH so callers can degrade gracefully.
+
+Source: [`src/core/integrity.py`](../../src/core/integrity.py)
+
+## Classes
+
+### `IntegrityResult`
+
+*class · line 30*
+
+```python
+class IntegrityResult:
+```
+
+Outcome of checking one file.
+
+`ok` — the file decoded/probed cleanly.
+`checked` — the check actually ran; False means it couldn't (missing tool,
+missing file), which is *not* the same as "corrupted".
+`error` — a short reason when not `ok`.
+
+## Functions
+
+### `ffmpeg_available`
+
+*function · line 45*
+
+```python
+ffmpeg_available(deep: bool=True) -> bool
+```
+
+Is the required FFmpeg tool (ffmpeg for deep, ffprobe for quick) on PATH?
+
+### `check_video_integrity`
+
+*function · line 50*
+
+```python
+check_video_integrity(path: Path, deep: bool=True, timeout: Optional[int]=None) -> IntegrityResult
+```
+
+Check a single video file for corruption.
+
+Args:
+    path: the video file to check.
+    deep: True → full ffmpeg decode (catches data corruption, slow);
+          False → ffprobe probe (catches unreadable/truncated files, fast).
+    timeout: per-file timeout in seconds (None = no limit).
+
+Returns:
+    An `IntegrityResult`. `checked=False` when the check could not
+    be run at all (tool or file missing) — distinct from a real failure.
+
+### `_first_error_line`
+
+*function · line 108*
+
+```python
+_first_error_line(stderr: str) -> str
+```
+
+First non-empty stderr line, truncated — a compact reason for the report.