jellyplex-sync 0.2.2__tar.gz → 0.3.1__tar.gz

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jellyplex-sync
-Version: 0.2.2
+Version: 0.3.1
 Summary: Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror
 Author: Stefan Schönberger
 Author-email: Stefan Schönberger <stefan@sniner.dev>
@@ -18,7 +18,7 @@ Description-Content-Type: text/markdown
 
 Can't decide between Jellyfin and Plex? This tool might help. It synchronizes your **movie library** between Jellyfin and Plex formats in **both directions** — without duplicating any files. Instead, it uses **hardlinks** to mirror your collection efficiently, saving storage while keeping both libraries in sync.
 
-> ⚠️ **0.2.0 is a major rewrite.** Subcommands, new materializer options, machine-readable `--json` output, default-sync-everything behavior, and a renamed model field (`tags` → `labels` in the Python API). If you depend on the old shape, **try the new version with `--dry-run` first**, and pin to a `0.1.x` release if anything looks off. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
+> ⚠️ **0.3.0 is another major rewrite.** The internals are reorganised into a clean `discover → plan → realize` pipeline with an immutable Plan as a first-class concept. User-visible: a new **`plan` subcommand** that shows what a sync would do (text or `--json`) without touching anything, and **video-level clashes now auto-resolve with a hash suffix** instead of aborting the movie. The `sync` and `diff` CLI is unchanged. If you depend on the old shape, **try the new version with `--dry-run` first**. Cautious users can pin to a `0.2.x` (or even `0.1.x`) release until they're comfortable. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
 
 ## Overview
 
@@ -30,6 +30,8 @@ The script scans the source library, parses each movie folder for metadata (titl
 
 > ⚠️ **Movies only:** This script is designed exclusively for **movie libraries**. It does **not** support TV shows or miniseries. However, this is usually not a limitation in practice: for shows, Jellyfin and Plex use very similar directory structures, so you can typically point both apps to the same library without issues.
 
+> ⚠️ **Stacked / multi-part movies are not supported:** Plex's multi-part filename suffixes (`pt1`/`pt2`, `cd1`/`cd2`, `disc1`/`disc2`) are not recognized — each part is treated as a separate video, which will likely confuse the target scanner. Pre-join multi-disc releases with `mkvmerge` before adding them to your library.
+
 > ⚠️ **Hardlinks require a shared filesystem:** Source and target paths must live on the **same filesystem**. Hardlinks cannot span filesystems or physical disks. If they don't, switch to `--copy`. On Unraid's classic array this is a real concern — see the [Unraid section](#unraid-user-scripts) for details before running this tool there.
 
 ## Installation
@@ -60,10 +62,11 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into two subcommands:
+The CLI is split into three subcommands:
 
 - **`sync`** — mirror a source library into the target layout (the historical operation; this is also the default if you omit the subcommand).
 - **`diff`** — read-only comparison of source and target. No filesystem changes. Useful before deleting your source after a migration.
+- **`plan`** — show the Plan a sync would execute (text or `--json`), without touching either side. Pre-flight check before sync, or machine-readable input for tooling.
 
 ### `sync`
 
@@ -140,22 +143,56 @@ Verify a target is a complete mirror before deleting the source:
 jellyplex-sync diff ~/Media/Jellyfin ~/Media/Plex
 ```
 
+### `plan`
+
+```bash
+jellyplex-sync plan [OPTIONS] /path/to/source/library /path/to/target/library
+```
+
+Shows the Plan a sync would execute — every movie folder, every translated video filename, every loose file, every asset subdirectory — without touching either filesystem. Useful as a pre-flight check ("will any movies clash? what gets translated?") or as a machine-readable input for tooling with `--json`.
+
+Unlike `sync` and `diff`, the target directory does **not** need to exist. The whole point of `plan` is to answer "what WOULD happen" *before* any setup.
+
+Exit codes:
+
+- `0` — Plan produced successfully. Clashes and translation losses are reported but counted as informational, not failures.
+- `2` — setup error (source missing, format undetectable).
+
+#### Example
+
+Pre-flight a sync, see exactly which target filenames would be created:
+
+```bash
+jellyplex-sync plan ~/Media/Plex ~/Media/Jellyfin
+```
+
+Machine-readable, with `jq` to find videos that needed disambiguation:
+
+```bash
+jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
+    | jq '.movies[].videos[] | select(.disambiguation) | {source, target_name, disambiguation}'
+```
+
 ### JSON output
 
-Both subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
+All three subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
 
 The schema (still evolving — pin a version when consuming):
 
-- `operation`: `"sync"` or `"diff"`.
-- `exit_code`: the process exit code, mirrored in the document for convenience.
+- `operation`: `"sync"`, `"diff"`, or `"plan"`.
+- `exit_code` (sync, diff): the process exit code, mirrored in the document for convenience.
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
-- `summary` (sync only): counters for `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`.
+- `summary`: counters; the set of fields depends on the operation.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`, `clashes`.
+  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
 - `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove`. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
+- `clashes` (sync only): movie-level video clashes the disambiguator couldn't resolve at all. Normally empty since the hash-fallback resolves the practical cases.
 - `diff`-specific fields: `movies_only_in_source`, `movies_only_in_target`, `differing_movies`, `in_sync`.
+- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case.
 
 #### `jq` examples
 
@@ -239,6 +276,8 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Loose top-level files** — Sidecar files (`.nfo`, posters, external subtitles, plain notes) at the top of a movie folder are synced 1:1 by default since 0.2.0. Pre-0.2.0 they were silently dropped — which made the tool unsafe for migrations. Dot-files (`.DS_Store`, `.stversions`, …) stay excluded.
 - **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
+- **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
+- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped, the clashing folders are listed, and you're asked to rename one side.
 
 ## Library layouts
 
@@ -264,7 +303,7 @@ Each movie must reside in its own folder, with optional subfolders for extras. D
 
 #### Special filename handling
 
-Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [DEV.md](./DEV.md).
+Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [SPECS.md](./SPECS.md).
 
 ### Plex
 

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.1}/README.md

@@ -2,7 +2,7 @@
 
 Can't decide between Jellyfin and Plex? This tool might help. It synchronizes your **movie library** between Jellyfin and Plex formats in **both directions** — without duplicating any files. Instead, it uses **hardlinks** to mirror your collection efficiently, saving storage while keeping both libraries in sync.
 
-> ⚠️ **0.2.0 is a major rewrite.** Subcommands, new materializer options, machine-readable `--json` output, default-sync-everything behavior, and a renamed model field (`tags` → `labels` in the Python API). If you depend on the old shape, **try the new version with `--dry-run` first**, and pin to a `0.1.x` release if anything looks off. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
+> ⚠️ **0.3.0 is another major rewrite.** The internals are reorganised into a clean `discover → plan → realize` pipeline with an immutable Plan as a first-class concept. User-visible: a new **`plan` subcommand** that shows what a sync would do (text or `--json`) without touching anything, and **video-level clashes now auto-resolve with a hash suffix** instead of aborting the movie. The `sync` and `diff` CLI is unchanged. If you depend on the old shape, **try the new version with `--dry-run` first**. Cautious users can pin to a `0.2.x` (or even `0.1.x`) release until they're comfortable. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
 
 ## Overview
 
@@ -14,6 +14,8 @@ The script scans the source library, parses each movie folder for metadata (titl
 
 > ⚠️ **Movies only:** This script is designed exclusively for **movie libraries**. It does **not** support TV shows or miniseries. However, this is usually not a limitation in practice: for shows, Jellyfin and Plex use very similar directory structures, so you can typically point both apps to the same library without issues.
 
+> ⚠️ **Stacked / multi-part movies are not supported:** Plex's multi-part filename suffixes (`pt1`/`pt2`, `cd1`/`cd2`, `disc1`/`disc2`) are not recognized — each part is treated as a separate video, which will likely confuse the target scanner. Pre-join multi-disc releases with `mkvmerge` before adding them to your library.
+
 > ⚠️ **Hardlinks require a shared filesystem:** Source and target paths must live on the **same filesystem**. Hardlinks cannot span filesystems or physical disks. If they don't, switch to `--copy`. On Unraid's classic array this is a real concern — see the [Unraid section](#unraid-user-scripts) for details before running this tool there.
 
 ## Installation
@@ -44,10 +46,11 @@ docker build -t jellyplex-sync .
 
 ## Usage
 
-The CLI is split into two subcommands:
+The CLI is split into three subcommands:
 
 - **`sync`** — mirror a source library into the target layout (the historical operation; this is also the default if you omit the subcommand).
 - **`diff`** — read-only comparison of source and target. No filesystem changes. Useful before deleting your source after a migration.
+- **`plan`** — show the Plan a sync would execute (text or `--json`), without touching either side. Pre-flight check before sync, or machine-readable input for tooling.
 
 ### `sync`
 
@@ -124,22 +127,56 @@ Verify a target is a complete mirror before deleting the source:
 jellyplex-sync diff ~/Media/Jellyfin ~/Media/Plex
 ```
 
+### `plan`
+
+```bash
+jellyplex-sync plan [OPTIONS] /path/to/source/library /path/to/target/library
+```
+
+Shows the Plan a sync would execute — every movie folder, every translated video filename, every loose file, every asset subdirectory — without touching either filesystem. Useful as a pre-flight check ("will any movies clash? what gets translated?") or as a machine-readable input for tooling with `--json`.
+
+Unlike `sync` and `diff`, the target directory does **not** need to exist. The whole point of `plan` is to answer "what WOULD happen" *before* any setup.
+
+Exit codes:
+
+- `0` — Plan produced successfully. Clashes and translation losses are reported but counted as informational, not failures.
+- `2` — setup error (source missing, format undetectable).
+
+#### Example
+
+Pre-flight a sync, see exactly which target filenames would be created:
+
+```bash
+jellyplex-sync plan ~/Media/Plex ~/Media/Jellyfin
+```
+
+Machine-readable, with `jq` to find videos that needed disambiguation:
+
+```bash
+jellyplex-sync plan --json ~/Media/Plex ~/Media/Jellyfin \
+    | jq '.movies[].videos[] | select(.disambiguation) | {source, target_name, disambiguation}'
+```
+
 ### JSON output
 
-Both subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
+All three subcommands accept `--json` for machine-readable output. The document goes to **stdout**; logs continue to go to stderr. Under `--json`, INFO logs are suppressed unless you pass `--verbose` or `--debug`, so the output pipes cleanly into tools like `jq` without filtering.
 
 The schema (still evolving — pin a version when consuming):
 
-- `operation`: `"sync"` or `"diff"`.
-- `exit_code`: the process exit code, mirrored in the document for convenience.
+- `operation`: `"sync"`, `"diff"`, or `"plan"`.
+- `exit_code` (sync, diff): the process exit code, mirrored in the document for convenience.
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
-- `summary` (sync only): counters for `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`.
+- `summary`: counters; the set of fields depends on the operation.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`, `clashes`.
+  - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
 - `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove`. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
+- `clashes` (sync only): movie-level video clashes the disambiguator couldn't resolve at all. Normally empty since the hash-fallback resolves the practical cases.
 - `diff`-specific fields: `movies_only_in_source`, `movies_only_in_target`, `differing_movies`, `in_sync`.
+- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case.
 
 #### `jq` examples
 
@@ -223,6 +260,8 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Loose top-level files** — Sidecar files (`.nfo`, posters, external subtitles, plain notes) at the top of a movie folder are synced 1:1 by default since 0.2.0. Pre-0.2.0 they were silently dropped — which made the tool unsafe for migrations. Dot-files (`.DS_Store`, `.stversions`, …) stay excluded.
 - **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
+- **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
+- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped, the clashing folders are listed, and you're asked to rename one side.
 
 ## Library layouts
 
@@ -248,7 +287,7 @@ Each movie must reside in its own folder, with optional subfolders for extras. D
 
 #### Special filename handling
 
-Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [DEV.md](./DEV.md).
+Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [SPECS.md](./SPECS.md).
 
 ### Plex
 

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jellyplex-sync"
-version = "0.2.2"
+version = "0.3.1"
 description = "Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror"
 authors = [{ name = "Stefan Schönberger", email = "stefan@sniner.dev" }]
 requires-python = ">=3.11"

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.1}/src/jellyplex_sync/__init__.py

@@ -8,6 +8,7 @@ from .library import (
     Drop,
     DropError,
     FileEvent,
+    FolderClash,
     IgnoredEntry,
     LibraryReader,
     LibraryWriter,
@@ -27,6 +28,13 @@ from .model import (
     MovieInfo,
     VideoInfo,
 )
+from .plan import (
+    DisambiguationNote,
+    Plan,
+    PlannedAsset,
+    PlannedFile,
+    PlannedMovie,
+)
 from .plex import (
     PlexLibraryReader,
     PlexLibraryWriter,
@@ -35,6 +43,7 @@ from .sync import (
     DiffEntry,
     DiffResult,
     diff,
+    plan,
     sync,
 )
 
@@ -44,10 +53,12 @@ __all__ = [
     "CopyMaterializer",
     "DiffEntry",
     "DiffResult",
+    "DisambiguationNote",
     "Drop",
     "DropError",
     "FileEvent",
     "FileMaterializer",
+    "FolderClash",
     "ForceCopyMaterializer",
     "HardlinkMaterializer",
     "IgnoredEntry",
@@ -58,6 +69,10 @@ __all__ = [
     "LoggingReporter",
     "MovieClash",
     "MovieInfo",
+    "Plan",
+    "PlannedAsset",
+    "PlannedFile",
+    "PlannedMovie",
     "PlexLibraryReader",
     "PlexLibraryWriter",
     "Reporter",
@@ -65,5 +80,6 @@ __all__ = [
     "VideoInfo",
     "dedupe_drops",
     "diff",
+    "plan",
     "sync",
 ]

{jellyplex_sync-0.2.2 → jellyplex_sync-0.3.1}/src/jellyplex_sync/cli/sync.py

@@ -7,7 +7,7 @@ import sys
 
 import jellyplex_sync as jp
 
-_SUBCOMMANDS = {"sync", "diff"}
+_SUBCOMMANDS = {"sync", "diff", "plan"}
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -90,6 +90,13 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     _add_io_args(diff_p)
 
+    plan_p = sub.add_parser(
+        "plan",
+        parents=[common],
+        help="Show the Plan a sync would execute, without touching the target.",
+    )
+    _add_io_args(plan_p)
+
     return parser
 
 
@@ -156,6 +163,8 @@ def main() -> None:
         result = _do_sync(args)
     elif args.command == "diff":
         result = _do_diff(args)
+    elif args.command == "plan":
+        result = _do_plan(args)
     else:
         parser.error(f"unknown command: {args.command!r}")
         result = 2
@@ -242,6 +251,26 @@ def _do_diff(args: argparse.Namespace) -> int:
         return 99
 
 
+def _do_plan(args: argparse.Namespace) -> int:
+    from jellyplex_sync.sync import plan as plan_fn
+
+    try:
+        return plan_fn(
+            args.source,
+            args.target,
+            debug=args.debug,
+            source_format=args.source_format,
+            target_format=args.target_format,
+            as_json=args.json,
+        )
+    except KeyboardInterrupt:
+        logging.info("INTERRUPTED")
+        return 10
+    except Exception as exc:
+        logging.error("Exception: %s", exc)
+        return 99
+
+
 def _resolve_formats_for_json(args: argparse.Namespace) -> tuple[str, str]:
     """Re-run the same format resolution `sync()` did so the JSON payload
     reports the formats that were actually used. Returns ('?', '?') if

jellyplex_sync-0.3.1/src/jellyplex_sync/compare.py

@@ -0,0 +1,82 @@
+"""Plan-vs.-actual comparison: derive a DiffResult from a Plan.
+
+The classic `diff` subcommand answers "is the target in sync with what
+the source would produce?" In the 0.3 pipeline this becomes trivially
+expressible: build the Plan (no I/O on target), then compare it to
+whatever currently sits on the target filesystem.
+
+The shape of `DiffResult` is preserved from sync.py so the public CLI
+output and `--json` schema don't move. `drops` is left empty here —
+they belong to the Reporter the caller fed to the Planner; the caller
+can stitch them onto the DiffResult if they want them in the document.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from .plan import Plan
+from .sync import DiffEntry, DiffResult, MovieOnlyInSource
+
+
+def compare(plan: Plan) -> DiffResult:
+    """Compare `plan` against the actual contents of `plan.target_root`.
+
+    Pure: reads the target filesystem, returns a DiffResult, mutates
+    nothing. Walks one level deep into each movie folder — same depth
+    as the pre-0.3 diff implementation."""
+    planned_folder_names = {m.target_folder.name for m in plan.movies}
+    planned_by_name = {m.target_folder.name: m for m in plan.movies}
+
+    actual: dict[str, set[str]] = {}
+    if plan.target_root.is_dir():
+        for entry in plan.target_root.iterdir():
+            if not entry.is_dir():
+                continue
+            actual[entry.name] = {sub.name for sub in entry.iterdir()}
+
+    only_in_source_names = sorted(planned_folder_names - actual.keys())
+    only_in_source = tuple(
+        MovieOnlyInSource(
+            source_folder=planned_by_name[name].source_path.name,
+            expected_target=name,
+        )
+        for name in only_in_source_names
+    )
+
+    only_in_target = tuple(sorted(actual.keys() - planned_folder_names))
+
+    differing: list[DiffEntry] = []
+    for name in sorted(planned_folder_names & actual.keys()):
+        pm = planned_by_name[name]
+        expected_files = (
+            {pf.target_name for pf in pm.videos}
+            | {pf.target_name for pf in pm.loose_files}
+            | {a.folder_name for a in pm.assets}
+        )
+        src_only = tuple(sorted(expected_files - actual[name]))
+        tgt_only = tuple(sorted(actual[name] - expected_files))
+        if src_only or tgt_only:
+            differing.append(
+                DiffEntry(
+                    target_movie_name=name,
+                    only_in_source=src_only,
+                    only_in_target=tgt_only,
+                )
+            )
+
+    return DiffResult(
+        movies_only_in_source=only_in_source,
+        movies_only_in_target=only_in_target,
+        differing_movies=tuple(differing),
+        ignored=tuple(plan.ignored),
+    )
+
+
+def _planned_target_folder(plan: Plan, name: str) -> pathlib.Path | None:
+    """Helper: find the absolute target folder for a planned-movie name,
+    if any. Convenience for callers that want to print full paths."""
+    for m in plan.movies:
+        if m.target_folder.name == name:
+            return m.target_folder
+    return None

jellyplex_sync-0.3.1/src/jellyplex_sync/disambig.py

@@ -0,0 +1,190 @@
+"""Disambiguation: turn potentially-colliding target names into unique ones.
+
+A Disambiguator is the layer that owns the answer to "what happens when
+two source videos in the same movie folder want to write to the same
+target filename?" — a real concern for the lossy Plex→Jellyfin
+translation, where `[1080p] [remux].mkv` and `[1080p].mkv` both collapse
+to `- BD.mkv`.
+
+Two implementations ship today:
+
+- `NaiveDisambiguator` preserves the pre-0.3 behaviour: if two videos
+  collide, the whole movie is unresolvable and gets reported as a
+  `MovieClash`. Useful for strict modes where the user wants the abort.
+
+- `HashFallbackDisambiguator` is the always-succeeds default: on
+  collision, it asks the Writer for the same names again with a short
+  hash of the source filename appended. Source filenames are
+  filesystem-unique within their folder, so a hash derived from them
+  is unique too (modulo a vanishingly small SHA-256 collision).
+
+A future `LabelPullbackDisambiguator` could be added that progressively
+keeps dropped labels in priority order before falling through to the
+hash — see planning/0.3-ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import pathlib
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Protocol
+
+from .library import CollectingReporter, LibraryWriter, MovieClash, Reporter
+from .model import MovieInfo, VideoInfo
+from .plan import DisambiguationNote
+
+
+@dataclass(frozen=True)
+class DisambiguationResult:
+    """Outcome of disambiguating one movie's videos.
+
+    `names` maps each accepted source path to its final target filename;
+    `notes` records why a name deviates from the Writer's naive output
+    (None if the naive name was already unique). `unresolved` lists any
+    clashes the disambiguator could not solve — affected sources are
+    absent from `names`."""
+
+    names: dict[pathlib.Path, str]
+    notes: dict[pathlib.Path, DisambiguationNote | None]
+    unresolved: tuple[MovieClash, ...] = ()
+
+
+class Disambiguator(Protocol):
+    def disambiguate(
+        self,
+        movie: MovieInfo,
+        videos: list[tuple[VideoInfo, pathlib.Path]],
+        writer: LibraryWriter,
+        reporter: Reporter,
+        *,
+        movie_folder: str,
+    ) -> DisambiguationResult: ...
+
+
+class NaiveDisambiguator:
+    """Calls `writer.video_name()` once per video. If two videos produce
+    the same name, those videos are excluded from `names` and reported
+    as a `MovieClash` — matching pre-0.3 behaviour where the whole
+    movie was skipped on clash."""
+
+    def disambiguate(
+        self,
+        movie: MovieInfo,
+        videos: list[tuple[VideoInfo, pathlib.Path]],
+        writer: LibraryWriter,
+        reporter: Reporter,
+        *,
+        movie_folder: str,
+    ) -> DisambiguationResult:
+        rendered: dict[pathlib.Path, str] = {}
+        for info, source in videos:
+            rendered[source] = writer.video_name(movie, info, reporter)
+
+        groups: dict[str, list[pathlib.Path]] = defaultdict(list)
+        for source, name in rendered.items():
+            groups[name].append(source)
+
+        names: dict[pathlib.Path, str] = {}
+        notes: dict[pathlib.Path, DisambiguationNote | None] = {}
+        unresolved: list[MovieClash] = []
+        for name, sources in groups.items():
+            if len(sources) == 1:
+                names[sources[0]] = name
+                notes[sources[0]] = None
+            else:
+                unresolved.append(
+                    MovieClash(
+                        movie_folder=movie_folder,
+                        target_filename=name,
+                        source_filenames=tuple(s.name for s in sources),
+                    )
+                )
+        return DisambiguationResult(
+            names=names, notes=notes, unresolved=tuple(unresolved)
+        )
+
+
+class HashFallbackDisambiguator:
+    """On collision, re-renders the colliding videos with a short hash of
+    their source filename appended. Source filenames are unique within a
+    folder (FS guarantee), so the rendered names are unique modulo a
+    SHA-256 collision in the truncated prefix — negligible at the
+    default 8 hex chars (~10⁻⁹ for typical folder sizes).
+
+    The hash strategy lives on a per-file `DisambiguationNote` so the
+    --json output and `plan` subcommand can surface "this name was
+    hashed because of a clash" without the user having to compare names
+    by hand."""
+
+    def __init__(self, *, hash_length: int = 8):
+        if hash_length < 4 or hash_length > 64:
+            raise ValueError("hash_length must be between 4 and 64 hex chars")
+        self._hash_length = hash_length
+
+    def disambiguate(
+        self,
+        movie: MovieInfo,
+        videos: list[tuple[VideoInfo, pathlib.Path]],
+        writer: LibraryWriter,
+        reporter: Reporter,
+        *,
+        movie_folder: str,
+    ) -> DisambiguationResult:
+        # First pass: probe naive names with a throwaway reporter so we
+        # can detect collisions without double-counting drops.
+        probe = CollectingReporter()
+        naive: dict[pathlib.Path, str] = {}
+        for info, source in videos:
+            naive[source] = writer.video_name(movie, info, probe)
+
+        groups: dict[str, list[tuple[VideoInfo, pathlib.Path]]] = defaultdict(list)
+        for info, source in videos:
+            groups[naive[source]].append((info, source))
+
+        names: dict[pathlib.Path, str] = {}
+        notes: dict[pathlib.Path, DisambiguationNote | None] = {}
+        unresolved: list[MovieClash] = []
+
+        for naive_name, group in groups.items():
+            if len(group) == 1:
+                info, source = group[0]
+                # Re-render with the real reporter to deliver the drops.
+                names[source] = writer.video_name(movie, info, reporter)
+                notes[source] = None
+                continue
+
+            rendered: dict[pathlib.Path, str] = {}
+            for info, source in group:
+                h = _short_hash(source.name, self._hash_length)
+                rendered[source] = writer.video_name(
+                    movie, info, reporter, hash_suffix=h
+                )
+
+            if len(set(rendered.values())) != len(rendered):
+                # Hash itself collided — pathological, but still surface
+                # it cleanly rather than silently corrupting the plan.
+                unresolved.append(
+                    MovieClash(
+                        movie_folder=movie_folder,
+                        target_filename=naive_name,
+                        source_filenames=tuple(s.name for _, s in group),
+                    )
+                )
+                continue
+
+            for _info, source in group:
+                names[source] = rendered[source]
+                notes[source] = DisambiguationNote(
+                    strategy="hash_suffix",
+                    detail=f"hash from source filename '{source.name}'",
+                )
+
+        return DisambiguationResult(
+            names=names, notes=notes, unresolved=tuple(unresolved)
+        )
+
+
+def _short_hash(s: str, length: int) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()[:length]