feat: add breadcrumbs mode to collapse single-child directory chains

Directories that form a single-child chain (one subdir, no files) are
collapsed into a single tile whose header shows the full path separated
by ' / ' (e.g. src / dirplot / fonts). Middle segments are replaced by
'…' when the label is too wide to fit.

- scanner: apply_breadcrumbs() collapses chains bottom-up; root is never merged
- render: _truncate_breadcrumb() elides middle segments for PNG labels
- svg_render: _truncate_breadcrumb_svg() same logic for SVG labels
- main: --breadcrumbs/--no-breadcrumbs (-b/-B), default on
- tests: four unit tests covering chain, no-file-sibling, multi-child, and partial-chain cases
- fix: assert img is not None before paste to satisfy mypy

Author: deeplook

src/dirplot/main.py

@@ -19,6 +19,7 @@
 from dirplot.s3 import build_tree_s3, is_s3_path, make_s3_client, parse_s3_path
 from dirplot.scanner import (
     Node,
+    apply_breadcrumbs,
     apply_log_sizes,
     build_tree,
     build_tree_multi,
@@ -346,6 +347,15 @@ def main(
         "--password",
         help="Password for encrypted archives. Prompted interactively if not supplied and needed.",
     ),
+    breadcrumbs: bool = typer.Option(
+        True,
+        "--breadcrumbs/--no-breadcrumbs",
+        "-b/-B",
+        help=(
+            "Collapse single-subdirectory chains into breadcrumb labels"
+            " (e.g. foo / bar / baz). Default: on."
+        ),
+    ),
 ) -> None:
     """Create a nested treemap bitmap for a directory tree."""
     if not roots:
@@ -559,6 +569,9 @@ def main(
     if subtrees:
         root_node = prune_to_subtrees(root_node, set(subtrees))
 
+    if breadcrumbs:
+        root_node = apply_breadcrumbs(root_node)
+
     t_scan = time.monotonic() - t_scan_start
     if log:
         apply_log_sizes(root_node)

src/dirplot/render.py

@@ -160,6 +160,26 @@ def _truncate(
     return name[:lo] + ellipsis
 
 
+def _truncate_breadcrumb(
+    name: str, draw: ImageDraw.ImageDraw, font: ImageFont.FreeTypeFont, max_w: int
+) -> str:
+    """Truncate a breadcrumb label (`` / ``-separated parts) to fit *max_w* pixels.
+
+    Tries the full label first, then collapses middle segments to ``…``, and
+    finally falls back to ``_truncate`` for plain names or when even the
+    ``first / … / last`` form is too long.
+    """
+    parts = name.split(" / ")
+    if len(parts) <= 1:
+        return _truncate(name, draw, font, max_w)
+    if _text_w(draw, name, font) <= max_w:
+        return name
+    candidate = parts[0] + " / … / " + parts[-1]
+    if _text_w(draw, candidate, font) <= max_w:
+        return candidate
+    return _truncate(candidate, draw, font, max_w)
+
+
 def _apply_cushion(img: Image.Image, x: int, y: int, w: int, h: int) -> None:
     """Apply van Wijk-style quadratic cushion shading to a tile in-place."""
     if w < 4 or h < 4:
@@ -257,6 +277,7 @@ def draw_node(
                     spacing=0,
                 )
                 rotated = tmp.rotate(90, expand=True)
+                assert img is not None
                 img.paste(rotated, (x, y), mask=rotated)
             else:
                 # Horizontal label: available text-run = w-4, constraining dim = h-4
@@ -279,7 +300,9 @@ def draw_node(
     # Header label — height driven by the font size
     header_h = font.size + 4
     if h > 2 + header_h:
-        label = _truncate(root_label if root_label is not None else node.name, draw, font, w - 8)
+        label = _truncate_breadcrumb(
+            root_label if root_label is not None else node.name, draw, font, w - 8
+        )
         draw.text(
             (x + w // 2, y + 2 + header_h // 2),
             label,

src/dirplot/scanner.py

@@ -182,6 +182,32 @@ def count_nodes(node: Node) -> tuple[int, int]:
     return files, dirs
 
 
+def _apply_breadcrumbs_recursive(node: Node) -> Node:
+    """Recursively collapse single-subdirectory chains (internal helper)."""
+    node.children = [_apply_breadcrumbs_recursive(c) for c in node.children]
+    dir_children = [c for c in node.children if c.is_dir]
+    file_children = [c for c in node.children if not c.is_dir]
+    if node.is_dir and len(dir_children) == 1 and len(file_children) == 0:
+        child = dir_children[0]
+        node.name = f"{node.name} / {child.name}"
+        node.children = child.children
+    return node
+
+
+def apply_breadcrumbs(node: Node) -> Node:
+    """Collapse single-subdirectory chains into one node with a combined name.
+
+    A directory that has exactly one directory child and no file children is
+    merged with that child: the names are joined with `` / `` and the child's
+    children become this node's children.  The process is bottom-up so chains
+    of any length accumulate naturally.
+
+    The root node itself is never collapsed — only its descendants are.
+    """
+    node.children = [_apply_breadcrumbs_recursive(c) for c in node.children]
+    return node
+
+
 def collect_extensions(node: Node) -> list[str]:
     """Return a flat list of file extensions under *node*."""
     if not node.is_dir:

src/dirplot/svg_render.py

@@ -247,6 +247,25 @@ def _truncate(name: str, font_size: int, max_w: float) -> str:
     return name[: max(0, max_chars - 1)] + "\u2026"
 
 
+def _truncate_breadcrumb_svg(name: str, font_size: int, max_w: float) -> str:
+    """Truncate a breadcrumb label (`` / ``-separated parts) to fit *max_w*.
+
+    Tries the full label first, then collapses middle segments to ``…``, and
+    finally falls back to ``_truncate`` for plain names or when even the
+    ``first / … / last`` form is too long.
+    """
+    char_w = font_size * _CHAR_ASPECT
+    parts = name.split(" / ")
+    if len(parts) <= 1:
+        return _truncate(name, font_size, max_w)
+    if len(name) * char_w <= max_w:
+        return name
+    candidate = parts[0] + " / \u2026 / " + parts[-1]
+    if len(candidate) * char_w <= max_w:
+        return candidate
+    return _truncate(candidate, font_size, max_w)
+
+
 # ---------------------------------------------------------------------------
 # Recursive draw
 # ---------------------------------------------------------------------------
@@ -367,7 +386,9 @@ def _draw_node_svg(
         )
         d.append(hdr)
 
-        label = _truncate(root_label if root_label is not None else node.name, font_size, w - 8)
+        label = _truncate_breadcrumb_svg(
+            root_label if root_label is not None else node.name, font_size, w - 8
+        )
         hclip = drawsvg.ClipPath()
         hclip.append(drawsvg.Rectangle(x + 2, y + 2, w - 4, header_h))
         d.append(hclip)

tests/test_scanner.py

@@ -6,6 +6,7 @@
 
 from dirplot.scanner import (
     Node,
+    apply_breadcrumbs,
     build_tree,
     build_tree_multi,
     collect_extensions,
@@ -229,3 +230,80 @@ def test_build_tree_multi_single_delegates(tmp_path: Path) -> None:
     root = build_tree_multi([tmp_path])
     assert root.path == tmp_path
     assert len(root.children) == 1
+
+
+# ---------------------------------------------------------------------------
+# apply_breadcrumbs
+# ---------------------------------------------------------------------------
+
+
+def _make_dir(name: str, children: list[Node] | None = None) -> Node:
+    return Node(name=name, path=Path(name), size=1, is_dir=True, children=children or [])
+
+
+def _make_file(name: str) -> Node:
+    return Node(name=name, path=Path(name), size=1, is_dir=False, extension=".txt")
+
+
+def test_breadcrumbs_collapses_chain() -> None:
+    # root → a → b → c → [file.txt]; root is never collapsed, but a/b/c merge
+    file_node = _make_file("file.txt")
+    c = _make_dir("c", [file_node])
+    b = _make_dir("b", [c])
+    a = _make_dir("a", [b])
+    root = _make_dir("root", [a])
+
+    result = apply_breadcrumbs(root)
+
+    assert result.name == "root"  # root itself is never collapsed
+    assert len(result.children) == 1
+    merged = result.children[0]
+    assert merged.name == "a / b / c"
+    assert len(merged.children) == 1
+    assert merged.children[0].name == "file.txt"
+
+
+def test_breadcrumbs_no_collapse_with_files() -> None:
+    # root → a → [file.txt, subdir]  — a has file child, must not collapse
+    file_node = _make_file("file.txt")
+    subdir = _make_dir("subdir", [_make_file("inner.txt")])
+    a = _make_dir("a", [file_node, subdir])
+    root = _make_dir("root", [a])
+
+    result = apply_breadcrumbs(root)
+
+    assert result.name == "root"
+    child = result.children[0]
+    assert child.name == "a"
+    assert {c.name for c in child.children} == {"file.txt", "subdir"}
+
+
+def test_breadcrumbs_no_collapse_multi_children() -> None:
+    # root → a → [dir1, dir2]  — a has two dir children, must not collapse
+    dir1 = _make_dir("dir1", [_make_file("x.txt")])
+    dir2 = _make_dir("dir2", [_make_file("y.txt")])
+    a = _make_dir("a", [dir1, dir2])
+    root = _make_dir("root", [a])
+
+    result = apply_breadcrumbs(root)
+
+    assert result.name == "root"
+    child = result.children[0]
+    assert child.name == "a"
+    assert {c.name for c in child.children} == {"dir1", "dir2"}
+
+
+def test_breadcrumbs_partial_chain() -> None:
+    # root → a → b → [dir1, dir2]  — b has two children, so a/b merges but stops there
+    dir1 = _make_dir("dir1", [_make_file("x.txt")])
+    dir2 = _make_dir("dir2", [_make_file("y.txt")])
+    b = _make_dir("b", [dir1, dir2])
+    a = _make_dir("a", [b])
+    root = _make_dir("root", [a])
+
+    result = apply_breadcrumbs(root)
+
+    assert result.name == "root"
+    child = result.children[0]
+    assert child.name == "a / b"
+    assert {c.name for c in child.children} == {"dir1", "dir2"}