splitsmith 0.2.0__py3-none-any.whl

splitsmith/overlay_theme.py

@@ -0,0 +1,146 @@
+"""Color palette for the alpha overlay renderer.
+
+Two presets ship today:
+
+- ``splitsmith`` (default): tokens lifted from the web UI's
+  ``src/splitsmith/ui_static/src/styles/index.css`` ``@theme`` block --
+  the Shot Timer brand palette. Built into
+  ``src/splitsmith/data/overlay_theme.json`` by
+  ``scripts/build_overlay_theme.py`` so the overlay can't silently drift
+  from the rest of the design system.
+- ``clean``: a neutral white-on-amber palette with a pure-black stroke.
+  No brand colours; useful when the overlay needs to read against any
+  background without identifying the tool.
+
+The JSON mirror is intentional: parsing CSS at runtime would mean a CSS
+parser as a runtime dep, and the overlay only needs a handful of tokens.
+Re-run the build script after touching ``index.css``.
+
+Bundled fonts (Antonio + JetBrains Mono, SIL OFL 1.1) live under
+``src/splitsmith/data/fonts/`` so the ``splitsmith`` theme renders
+deterministic typography without depending on whatever the host machine
+happens to have installed. The numeric readouts use JetBrains Mono Bold
+today; Antonio is bundled for future templates that mix in display
+labels.
+
+Down the line, swapping PIL for a Skia-based renderer would buy proper
+HarfBuzz shaping (kerning, ligatures, condensed-face width control)
+which only starts to matter once the template grows real label content.
+The font names already live in the JSON so that swap doesn't need new
+tokens.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib import resources
+from typing import Literal
+
+ThemeName = Literal["splitsmith", "clean"]
+"""Stable identifiers exposed in the export request + CLI."""
+
+THEME_NAMES: tuple[ThemeName, ...] = ("splitsmith", "clean")
+
+RGB = tuple[int, int, int]
+
+
+class OverlayThemeError(RuntimeError):
+    """Raised when the design-system JSON is missing or malformed."""
+
+
+@dataclass(frozen=True)
+class OverlayTheme:
+    """Palette + font name hints used by ``DefaultTemplate``.
+
+    All colors are 8-bit RGB tuples; alpha is applied at draw time by the
+    template (the last-split label fades, shadows track foreground alpha,
+    etc.). Font names are advisory: today they only matter when the caller
+    also passes ``font_name=None`` so the template can fall back to a
+    sensible default for the theme.
+    """
+
+    name: ThemeName
+    ink: RGB
+    split: RGB
+    stroke: RGB
+    accent: RGB
+    font_display: str
+    font_mono: str
+
+    @property
+    def shadow(self) -> RGB:
+        """Drop shadow color. Today this matches the stroke -- a dark halo
+        reads cleanly on both bright and busy backgrounds. Kept as a
+        property so a future variant can carry an explicit token without
+        churning callers."""
+        return self.stroke
+
+
+_CLEAN = OverlayTheme(
+    name="clean",
+    ink=(255, 255, 255),
+    split=(255, 220, 80),
+    stroke=(0, 0, 0),
+    accent=(255, 45, 45),
+    font_display="Antonio",
+    font_mono="JetBrains Mono",
+)
+
+
+def _load_splitsmith() -> OverlayTheme:
+    try:
+        with (
+            resources.files("splitsmith.data")
+            .joinpath("overlay_theme.json")
+            .open("r", encoding="utf-8") as fh
+        ):
+            data = json.load(fh)
+    except (FileNotFoundError, OSError) as exc:
+        raise OverlayThemeError("overlay_theme.json missing; run scripts/build_overlay_theme.py") from exc
+    except json.JSONDecodeError as exc:
+        raise OverlayThemeError(f"overlay_theme.json is not valid JSON: {exc}") from exc
+
+    colors = data.get("colors") or {}
+    fonts = data.get("fonts") or {}
+    try:
+        return OverlayTheme(
+            name="splitsmith",
+            ink=_rgb(colors, "ink"),
+            split=_rgb(colors, "split"),
+            stroke=_rgb(colors, "stroke"),
+            accent=_rgb(colors, "accent"),
+            font_display=str(fonts.get("display", "Antonio")),
+            font_mono=str(fonts.get("mono", "JetBrains Mono")),
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        raise OverlayThemeError(f"overlay_theme.json malformed: {exc}") from exc
+
+
+def _rgb(colors: dict, role: str) -> RGB:
+    raw = colors[role]
+    if not isinstance(raw, (list, tuple)) or len(raw) != 3:
+        raise ValueError(f"{role!r} must be a 3-element list, got {raw!r}")
+    r, g, b = (int(v) for v in raw)
+    for v in (r, g, b):
+        if not 0 <= v <= 255:
+            raise ValueError(f"{role!r} channel out of 0..255 range: {raw!r}")
+    return r, g, b
+
+
+def load_theme(name: ThemeName) -> OverlayTheme:
+    """Resolve a theme name to its palette. Cached at the module level so
+    repeated stage exports don't re-read the JSON. Raises
+    ``OverlayThemeError`` for unknown names or a missing splitsmith JSON
+    artefact."""
+    if name == "clean":
+        return _CLEAN
+    if name == "splitsmith":
+        global _SPLITSMITH
+        if _SPLITSMITH is None:
+            _SPLITSMITH = _load_splitsmith()
+        return _SPLITSMITH
+    raise OverlayThemeError(f"unknown theme {name!r}; expected one of {THEME_NAMES}")
+
+
+_SPLITSMITH: OverlayTheme | None = None

splitsmith/relink.py

@@ -0,0 +1,245 @@
+"""Relink registered video sources after they move on disk.
+
+Project ``raw/<name>`` entries are typically symlinks to the original
+recordings; ``project.json`` stores the relative ``raw/<name>`` path.
+When the originals move (e.g. onto a network share with a different
+folder layout), nothing in ``project.json`` needs to change -- only the
+symlink targets under ``raw/``.
+
+This module provides pure helpers used by both the API and tests:
+
+- :func:`inspect_links` reports the per-video link status (ok / broken /
+  missing / not-a-symlink) for the current project.
+- :func:`index_search_root` recursively walks a folder and indexes
+  videos by lowercase basename.
+- :func:`plan_relink` matches the project's registered videos against
+  that index, defaulting to the single-candidate match when the basename
+  is unique inside the search root.
+- :func:`apply_relink` rewrites the symlinks atomically (delete + create
+  in one step, mirroring ``ln -sfn``).
+
+All functions are pure aside from :func:`apply_relink`, which is the
+single place that mutates the filesystem.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from .ui.project import VIDEO_EXTENSIONS, MatchProject
+
+LinkStatus = Literal["ok", "broken", "missing_link", "not_a_symlink"]
+
+
+@dataclass(frozen=True)
+class LinkInfo:
+    """Filesystem state of one ``raw/<name>`` entry.
+
+    ``target`` is the symlink target as stored on disk (may be relative).
+    ``status`` reduces the four-state matrix to a single label the UI
+    can colour-code.
+    """
+
+    video_id: str
+    name: str
+    link_path: Path
+    target: Path | None
+    is_symlink: bool
+    target_exists: bool
+    status: LinkStatus
+
+
+@dataclass(frozen=True)
+class RelinkCandidate:
+    """One row in the relink plan: registered video + matches found in
+    the search root.
+
+    ``chosen_path`` defaults to the only candidate when exactly one was
+    found, leaves ``None`` for zero or many (the UI surfaces ambiguity).
+    """
+
+    video_id: str
+    name: str
+    link_path: Path
+    current_target: Path | None
+    current_status: LinkStatus
+    candidates: list[Path] = field(default_factory=list)
+    chosen_path: Path | None = None
+
+    @property
+    def ambiguous(self) -> bool:
+        return len(self.candidates) > 1
+
+    @property
+    def found(self) -> bool:
+        return bool(self.candidates)
+
+
+@dataclass(frozen=True)
+class AppliedRelink:
+    """Result of one applied symlink rewrite."""
+
+    video_id: str
+    name: str
+    link_path: Path
+    previous_target: Path | None
+    new_target: Path
+
+
+def _link_status(link_path: Path) -> tuple[LinkStatus, Path | None, bool, bool]:
+    """Inspect a ``raw/<name>`` entry. Returns ``(status, target,
+    is_symlink, target_exists)``.
+
+    Uses ``os.path.islink`` semantics via ``Path.is_symlink`` -- a broken
+    symlink is detected as a symlink whose target doesn't resolve.
+    """
+    if not link_path.exists() and not link_path.is_symlink():
+        return "missing_link", None, False, False
+    if link_path.is_symlink():
+        target = Path(link_path.readlink())
+        # Resolve relative targets against the link's parent so we report
+        # the actual file we're pointing at.
+        resolved = target if target.is_absolute() else (link_path.parent / target).resolve()
+        target_exists = resolved.exists()
+        return ("ok" if target_exists else "broken"), target, True, target_exists
+    # Plain file -- not a symlink. Could be a registered copy (link_mode
+    # = "copy") or a stray. Either way relinking doesn't apply.
+    return "not_a_symlink", None, False, link_path.exists()
+
+
+def inspect_links(project: MatchProject, root: Path) -> list[LinkInfo]:
+    """Report current link status for every registered video.
+
+    Stages are walked in declaration order and each video appears once;
+    if the same path is registered to multiple roles, the first
+    occurrence wins (matches :meth:`MatchProject.all_videos`).
+    """
+    raw_dir = project.raw_path(root)
+    out: list[LinkInfo] = []
+    seen: set[str] = set()
+    for video in project.all_videos():
+        link_path = (root / video.path) if not video.path.is_absolute() else video.path
+        # Project paths are stored as ``raw/<name>``; the registry only
+        # ever points inside ``raw_dir``. Resolving against root keeps
+        # the helper correct even if the user has overridden ``raw_dir``.
+        if not link_path.is_absolute():
+            link_path = raw_dir / link_path.name
+        key = str(link_path)
+        if key in seen:
+            continue
+        seen.add(key)
+        status, target, is_symlink, target_exists = _link_status(link_path)
+        out.append(
+            LinkInfo(
+                video_id=video.video_id,
+                name=link_path.name,
+                link_path=link_path,
+                target=target,
+                is_symlink=is_symlink,
+                target_exists=target_exists,
+                status=status,
+            )
+        )
+    return out
+
+
+def index_search_root(search_root: Path) -> dict[str, list[Path]]:
+    """Recursively index video files under ``search_root`` by
+    lowercase basename.
+
+    Multiple files with the same basename in different subfolders are
+    all collected; callers surface the ambiguity to the user. Only files
+    with extensions in :data:`VIDEO_EXTENSIONS` are indexed.
+
+    Symlinks inside the search root are followed via ``rglob`` default
+    behaviour (``Path.rglob`` does not follow dir symlinks by default,
+    which is what we want -- avoids cycles on network shares).
+    """
+    if not search_root.exists():
+        raise FileNotFoundError(f"search root does not exist: {search_root}")
+    if not search_root.is_dir():
+        raise NotADirectoryError(f"search root is not a directory: {search_root}")
+    index: dict[str, list[Path]] = {}
+    for entry in search_root.rglob("*"):
+        if not entry.is_file():
+            continue
+        if entry.suffix.lower() not in VIDEO_EXTENSIONS:
+            continue
+        index.setdefault(entry.name.lower(), []).append(entry.resolve())
+    # Stable order so dry-run output is deterministic for tests.
+    for paths in index.values():
+        paths.sort()
+    return index
+
+
+def plan_relink(
+    links: list[LinkInfo],
+    index: dict[str, list[Path]],
+) -> list[RelinkCandidate]:
+    """Build a relink plan: each registered video gets the candidate
+    paths found in the search root (matched by lowercase basename).
+
+    ``chosen_path`` is filled in only when exactly one candidate exists
+    *and* it differs from the current target. The UI can override on
+    apply.
+    """
+    out: list[RelinkCandidate] = []
+    for info in links:
+        candidates = list(index.get(info.name.lower(), []))
+        chosen: Path | None = None
+        if len(candidates) == 1:
+            single = candidates[0]
+            # Skip the no-op case so the apply step doesn't re-write
+            # an already-correct symlink.
+            if info.target is None or info.target.resolve() != single:
+                chosen = single
+        out.append(
+            RelinkCandidate(
+                video_id=info.video_id,
+                name=info.name,
+                link_path=info.link_path,
+                current_target=info.target,
+                current_status=info.status,
+                candidates=candidates,
+                chosen_path=chosen,
+            )
+        )
+    return out
+
+
+def apply_relink(
+    decisions: list[tuple[Path, Path]],
+) -> list[AppliedRelink]:
+    """Rewrite each symlink to its new target (``ln -sfn`` equivalent).
+
+    ``decisions`` is a list of ``(link_path, new_target)`` pairs. The
+    new target is stored as an absolute path so the symlink survives
+    project-root moves. The previous target is captured for the
+    response so the UI can show a "was -> now" diff.
+
+    Refuses to operate on entries that exist and are not symlinks (the
+    ``not_a_symlink`` status). Callers should filter those out first.
+    """
+    applied: list[AppliedRelink] = []
+    for link_path, new_target in decisions:
+        new_target_abs = new_target if new_target.is_absolute() else new_target.resolve()
+        previous: Path | None = None
+        if link_path.is_symlink():
+            previous = Path(link_path.readlink())
+            link_path.unlink()
+        elif link_path.exists():
+            raise ValueError(f"refusing to overwrite non-symlink at {link_path} (status not_a_symlink)")
+        link_path.parent.mkdir(parents=True, exist_ok=True)
+        link_path.symlink_to(new_target_abs)
+        applied.append(
+            AppliedRelink(
+                video_id="",  # filled in by callers that know the project
+                name=link_path.name,
+                link_path=link_path,
+                previous_target=previous,
+                new_target=new_target_abs,
+            )
+        )
+    return applied

splitsmith/report.py

@@ -0,0 +1,258 @@
+"""Human-readable per-stage analysis reports + anomaly flagging.
+
+Anomaly rules (from SPEC.md):
+- Beep-to-last-shot window differs from official ``stage.time_seconds`` by >500 ms.
+- Any split <80 ms (likely double-detection of a single shot).
+- Any split >3 s within the stage window (likely a missed shot, or a long transition).
+- Shot count outside a "typical IPSC stage" band (informational, not a hard error).
+
+ASCII-only output (per CLAUDE.md): tags use ``[OK]``, ``[!]``, etc. instead of
+Unicode glyphs so the report renders the same in any terminal / pager.
+
+Two flavours of the anomaly check live here:
+
+- :func:`detect_anomalies_structured` returns :class:`Anomaly` records
+  carrying ``kind`` + ``shot_number`` + ``time`` so the audit screen can
+  render clickable entries that jump to the offending marker (issue #42).
+- :func:`detect_anomalies` is the legacy string-list shape used by the
+  CLI / report.txt; it stringifies the structured output so the rendered
+  report bytes are unchanged.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+from .config import ReportFiles, Shot, SplitColorThresholds, StageAnalysis
+
+# Anomaly thresholds.
+_OFFICIAL_TIME_TOLERANCE_S = 0.500  # beep -> last shot vs stage.time_seconds
+_DOUBLE_DETECTION_MAX_S = 0.080  # min legitimate split
+_LONG_PAUSE_MAX_S = 3.000  # split above this is suspicious within the stage window
+_SLOW_DRAW_S = 1.500  # shot 1 split greater than this gets a slow-draw note
+_TYPICAL_ROUND_RANGE = (8, 32)  # informational shot-count band
+
+
+AnomalyKind = Literal[
+    "no_shots",
+    "stage_time_mismatch",
+    "double_detection",
+    "long_pause",
+    "shot_count_low",
+    "shot_count_high",
+]
+AnomalySeverity = Literal["info", "warn"]
+
+
+class Anomaly(BaseModel):
+    """Structured anomaly emitted by :func:`detect_anomalies_structured`.
+
+    ``kind`` tags the rule so the SPA can group / filter without parsing
+    ``message``. ``shot_number`` (1-based, matches :class:`Shot.shot_number`)
+    and ``time`` (seconds from beep) are populated for shot-bound anomalies
+    so the audit screen can scroll to the offending marker on click.
+    Stage-level anomalies (count band, no shots) leave both null.
+    """
+
+    kind: AnomalyKind
+    severity: AnomalySeverity
+    message: str
+    shot_number: int | None = None
+    time: float | None = None
+
+
+def detect_anomalies_structured(
+    shots: list[Shot],
+    beep_time: float,  # noqa: ARG001 -- kept for symmetry with caller; absolute beep time
+    stage_time: float,
+) -> list[Anomaly]:
+    """Return structured :class:`Anomaly` records; empty list means "all clean"."""
+    anomalies: list[Anomaly] = []
+
+    if not shots:
+        anomalies.append(
+            Anomaly(
+                kind="no_shots",
+                severity="warn",
+                message="No shots detected in the stage window.",
+            )
+        )
+        return anomalies
+
+    last_after_beep = shots[-1].time_from_beep
+    delta = last_after_beep - stage_time
+    if abs(delta) > _OFFICIAL_TIME_TOLERANCE_S:
+        anomalies.append(
+            Anomaly(
+                kind="stage_time_mismatch",
+                severity="warn",
+                message=(
+                    f"Last detected shot is {abs(delta) * 1000:.0f} ms "
+                    f"{'after' if delta > 0 else 'before'} official stage time "
+                    f"({last_after_beep:.3f} s vs {stage_time:.3f} s)."
+                ),
+                shot_number=shots[-1].shot_number,
+                time=last_after_beep,
+            )
+        )
+
+    for s in shots[1:]:  # shot 1's "split" is the draw, not a real split
+        if s.split < _DOUBLE_DETECTION_MAX_S:
+            anomalies.append(
+                Anomaly(
+                    kind="double_detection",
+                    severity="warn",
+                    message=(
+                        f"Shot {s.shot_number} split is {s.split * 1000:.0f} ms "
+                        f"(< {_DOUBLE_DETECTION_MAX_S * 1000:.0f} ms): "
+                        f"possible double-detection."
+                    ),
+                    shot_number=s.shot_number,
+                    time=s.time_from_beep,
+                )
+            )
+        elif s.split > _LONG_PAUSE_MAX_S:
+            anomalies.append(
+                Anomaly(
+                    kind="long_pause",
+                    severity="warn",
+                    message=(
+                        f"Shot {s.shot_number} split is {s.split:.3f} s "
+                        f"(> {_LONG_PAUSE_MAX_S:.1f} s): missed shot or long transition?"
+                    ),
+                    shot_number=s.shot_number,
+                    time=s.time_from_beep,
+                )
+            )
+
+    lo, hi = _TYPICAL_ROUND_RANGE
+    if not (lo <= len(shots) <= hi):
+        is_low = len(shots) < lo
+        anomalies.append(
+            Anomaly(
+                kind="shot_count_low" if is_low else "shot_count_high",
+                severity="info",
+                message=(
+                    f"Detected {len(shots)} shots; typical IPSC stages have {lo}-{hi}. "
+                    f"Review for "
+                    f"{'missed shots' if is_low else 'false positives (echoes / other bays)'}."
+                ),
+            )
+        )
+
+    return anomalies
+
+
+def detect_anomalies(
+    shots: list[Shot],
+    beep_time: float,
+    stage_time: float,
+) -> list[str]:
+    """Return human-readable anomaly strings; empty list means "all clean".
+
+    Thin wrapper over :func:`detect_anomalies_structured` so the report.txt
+    bullet rendering stays byte-identical to its pre-#42 output.
+    """
+    return [a.message for a in detect_anomalies_structured(shots, beep_time, stage_time)]
+
+
+def render_report(
+    analysis: StageAnalysis,
+    files: ReportFiles | None = None,
+    *,
+    color_thresholds: SplitColorThresholds | None = None,
+) -> str:
+    """Render the SPEC.md-shaped per-stage report as a single ASCII string."""
+    files = files or ReportFiles()
+    thresholds = color_thresholds or SplitColorThresholds()
+
+    stage = analysis.stage
+    shots = analysis.shots
+
+    lines: list[str] = []
+    lines.append(f'Stage {stage.stage_number} -- "{stage.stage_name}"')
+    lines.append(f"Official time:        {stage.time_seconds:.3f}s")
+    lines.append(f"Detected beep at:     {analysis.beep_time:.3f}s")
+
+    if shots:
+        last = shots[-1]
+        delta_ms = (last.time_from_beep - stage.time_seconds) * 1000.0
+        match_marker = "[OK]" if abs(delta_ms) <= _OFFICIAL_TIME_TOLERANCE_S * 1000 else "[!]"
+        lines.append(
+            f"Detected last shot:   {last.time_absolute:.3f}s "
+            f"({last.time_from_beep:.3f}s after beep) -- "
+            f"{'matches' if match_marker == '[OK]' else 'differs from'} "
+            f"official by {abs(delta_ms):.0f}ms {match_marker}"
+        )
+    lines.append(f"Detected {len(shots)} shot{'s' if len(shots) != 1 else ''}.")
+    lines.append("")
+
+    lines.append("Splits:")
+    if not shots:
+        lines.append("  (none)")
+    else:
+        for s in shots:
+            lines.append(_render_shot_line(s, thresholds))
+    lines.append("")
+
+    lines.append("Anomalies:")
+    if analysis.anomalies:
+        for a in analysis.anomalies:
+            lines.append(f"  - {a}")
+    else:
+        lines.append("  None.")
+    lines.append("")
+
+    if files.video or files.csv or files.fcpxml:
+        lines.append("Files:")
+        if files.video:
+            lines.append(f"  Video:  {files.video}")
+        if files.csv:
+            lines.append(f"  CSV:    {files.csv}")
+        if files.fcpxml:
+            lines.append(f"  FCPXML: {files.fcpxml}")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _render_shot_line(s: Shot, thresholds: SplitColorThresholds) -> str:
+    label_parts: list[str] = []
+    if s.shot_number == 1:
+        label_parts.append("draw")
+    elif s.split > thresholds.transition_min:
+        label_parts.append("transition")
+    label = f" ({', '.join(label_parts)})" if label_parts else ""
+    flag = _shot_flag(s, thresholds)
+    return f"  Shot {s.shot_number:>2}{label:<14}: {s.split:.3f}s  {flag}".rstrip()
+
+
+def _shot_flag(s: Shot, thresholds: SplitColorThresholds) -> str:
+    if s.shot_number == 1:
+        return "[!] slow draw" if s.split > _SLOW_DRAW_S else "[OK]"
+    if s.split < _DOUBLE_DETECTION_MAX_S:
+        return "[!] possible double"
+    if s.split > _LONG_PAUSE_MAX_S:
+        return "[!] long pause"
+    if s.split > thresholds.transition_min:
+        return ""  # transitions speak for themselves; no good/bad call
+    if s.split <= thresholds.green_max:
+        return "[OK]"
+    if s.split <= thresholds.yellow_max:
+        return "[~] yellow"
+    return "[!] red"
+
+
+def write_report(
+    analysis: StageAnalysis,
+    files: ReportFiles | None,
+    output_path: Path,
+    *,
+    color_thresholds: SplitColorThresholds | None = None,
+) -> None:
+    """Write the rendered report to ``output_path``."""
+    output_path.write_text(
+        render_report(analysis, files, color_thresholds=color_thresholds), encoding="utf-8"
+    )