feat: shorten paths that exceed the device's limit

Rockbox's MAX_PATH is 260, defined in firmware/include/fs_defines.h and used to
size the directory entry buffer in dir.h. It bounds the path as the device sees
it, so the directory the mirror is copied into spends part of the same budget;
--device-prefix accounts for that and defaults to /Music.

Over-budget paths are shortened from the deepest component outward. The track
name carries the least navigational value and the artist directory the most, so
the filename is cut first and the artist only if nothing else will serve. A
shortened component keeps its extension and gains four hex digits of the
original name: two long titles sharing a prefix cut to the same string
otherwise, and a silent collision between two tracks is a worse outcome than an
ugly filename.

The result is stable. The same source always yields the same shortened name, so
one pass does not rename what the last one wrote -- an unstable scheme would
churn the whole mirror every six hours. A path too deeply nested to fit without
reducing every component to nonsense is left alone and reported rather than
mangled.

Migration now tries more than one previous naming, because there is more than
one. A mirror already running with --fat32-safe holds sanitised but unshortened
paths, and matching only the original unsanitised name would have re-encoded
every one of them instead of moving it.

The checker gains the same two options, since it was measuring the
mirror-relative path against a limit that applies to the device-absolute one,
and so under-reported by the length of the destination directory.

tools/check_fat32.py

@@ -21,12 +21,14 @@ from pathlib import Path
 
 RESERVED = re.compile(r'[<>:"\\|?*\x00-\x1f]')
 COMPONENT_LIMIT = 255
-# Rockbox builds paths into a fixed buffer; long trees fail on the device even
-# when every individual component is legal.
+# Rockbox's MAX_PATH, from firmware/include/fs_defines.h. It bounds the path as
+# the device sees it, so the directory the mirror is copied into comes out of
+# the same budget.
 PATH_LIMIT = 260
+DEVICE_PREFIX = "/Music"
 
 
-def problems_with(relative):
+def problems_with(relative, budget=PATH_LIMIT):
     """Return every reason this relative path is unfit for FAT32."""
     found = []
     for part in relative.parts:
@@ -36,8 +38,8 @@ def problems_with(relative):
             found.append(f"trailing dot or space in {part!r}")
         if len(part) > COMPONENT_LIMIT:
             found.append(f"component of {len(part)} characters")
-    if len(str(relative)) > PATH_LIMIT:
-        found.append(f"path of {len(str(relative))} characters")
+    if len(str(relative)) > budget:
+        found.append(f"path of {len(str(relative))} characters, over a budget of {budget}")
     return found
 
 
@@ -52,7 +54,21 @@ def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("root", help="directory to check, e.g. the mirror")
     parser.add_argument("--limit", type=int, default=0, help="show at most this many")
+    parser.add_argument(
+        "--max-path",
+        type=int,
+        default=PATH_LIMIT,
+        help=f"longest path the device will take, from its root (default {PATH_LIMIT},"
+        " Rockbox's MAX_PATH)",
+    )
+    parser.add_argument(
+        "--device-prefix",
+        default=DEVICE_PREFIX,
+        help="directory the mirror is copied into on the device; its length comes out"
+        f" of the budget (default {DEVICE_PREFIX})",
+    )
     args = parser.parse_args(argv)
+    budget = max(0, args.max_path - len(args.device_prefix.strip("/")) - 2)
 
     root = Path(args.root)
     if not root.is_dir():
@@ -68,7 +84,7 @@ def main(argv=None):
         # different strings, and the collision check would miss it.
         key = unicodedata.normalize("NFC", str(relative)).casefold()
         by_case[key].append(relative)
-        for problem in problems_with(relative):
+        for problem in problems_with(relative, budget):
             faults.append((relative, problem))
 
     for relative, group in sorted(by_case.items()):
@@ -82,8 +98,8 @@ def main(argv=None):
     print(f"\n{len(faults)} problems across {total} files", file=sys.stderr)
     if faults:
         print(
-            "Run music-mirror with --fat32-safe to have the mirror named"
-            " acceptably in the first place.",
+            "Run music-mirror with --fat32-safe to have the mirror named acceptably"
+            " in the first place; it shortens over-long paths as well.",
             file=sys.stderr,
         )
     return 1 if faults else 0