locdu 0.1.0__tar.gz

locdu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Müller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

locdu-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: locdu
+Version: 0.1.0
+Summary: ncdu for lines of code: browse where the lines in a codebase are
+Author: Kevin Müller
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kevmiota/locdu
+Project-URL: Issues, https://github.com/kevmiota/locdu/issues
+Keywords: loc,lines of code,cloc,ncdu,tui,curses
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# locdu
+
+ncdu for lines of code. Scans a directory, counts the lines of every text file and lets
+you drill into the tree interactively, largest first. Pure Python standard library, no
+dependencies; Linux and macOS (needs curses).
+
+```
+locdu [DIR] [-x GLOB]... [-m lines|code|files] [-p [-d N] [-n N]] [--ncdu FILE]
+```
+
+## Install
+
+With [pipx](https://pipx.pypa.io) (Ubuntu: `sudo apt install pipx && pipx ensurepath`):
+
+```sh
+pipx install locdu                                   # from PyPI
+pipx install git+https://github.com/kevmiota/locdu   # latest main
+```
+
+`uv tool install locdu` works too.
+
+As a Debian/Ubuntu package, from the
+[releases page](https://github.com/kevmiota/locdu/releases):
+
+```sh
+sudo apt install ./locdu_0.1.0_all.deb
+```
+
+Without pip, from a clone (needs only `python3`):
+
+```sh
+./install.sh               # copies to ~/.local/share/locdu, launcher in ~/.local/bin
+./install.sh --uninstall
+```
+
+## What gets counted
+
+- In a git repo: the files git knows about, tracked and untracked, minus `.gitignore`,
+  including nested repos and submodules. Elsewhere, in a folder git ignores, or with
+  `--no-git`: everything except `node_modules`, `dist`, `build`, `.venv`, `vendor` and
+  similar below DIR.
+- Skipped by default: lockfiles, `*.min.js`, `*.min.css`, `*.map`
+  (`--no-default-excludes` counts them). Add your own with `-x`, repeatable:
+  a name or glob matches anywhere (`-x docs -x '*.md'`), a path matches relative
+  to DIR (`-x src/generated`).
+- Binary files (a NUL byte in the first 8 KB), text files over 50 MB and symlinks
+  are skipped.
+- `lines` = all lines, `code` = non-blank lines. Comments count as code; use
+  `scc` or `tokei` if you need comments separated.
+
+## Keys
+
+| Key | |
+|---|---|
+| arrows, `hjkl`, enter, backspace | navigate |
+| `m` | metric: lines, code lines, files |
+| `s` / `n` | sort by count / name, again to reverse |
+| `t` | file types in the current directory |
+| `e` | open the file in `$EDITOR`, recounted afterwards |
+| `d` / `u` | hide from the view / undo; nothing on disk is touched |
+| `r` | rescan |
+| `?` / `q` | help / quit |
+
+## Without the UI
+
+```sh
+locdu -p -d 2 -n 10           # tree, two levels, top 10 per directory
+locdu | less                  # prints automatically when stdout is not a terminal
+locdu --ncdu - | ncdu -f -    # hand the counts to ncdu (shown as sizes)
+```
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests -v
+```

locdu-0.1.0/README.md

@@ -0,0 +1,76 @@
+# locdu
+
+ncdu for lines of code. Scans a directory, counts the lines of every text file and lets
+you drill into the tree interactively, largest first. Pure Python standard library, no
+dependencies; Linux and macOS (needs curses).
+
+```
+locdu [DIR] [-x GLOB]... [-m lines|code|files] [-p [-d N] [-n N]] [--ncdu FILE]
+```
+
+## Install
+
+With [pipx](https://pipx.pypa.io) (Ubuntu: `sudo apt install pipx && pipx ensurepath`):
+
+```sh
+pipx install locdu                                   # from PyPI
+pipx install git+https://github.com/kevmiota/locdu   # latest main
+```
+
+`uv tool install locdu` works too.
+
+As a Debian/Ubuntu package, from the
+[releases page](https://github.com/kevmiota/locdu/releases):
+
+```sh
+sudo apt install ./locdu_0.1.0_all.deb
+```
+
+Without pip, from a clone (needs only `python3`):
+
+```sh
+./install.sh               # copies to ~/.local/share/locdu, launcher in ~/.local/bin
+./install.sh --uninstall
+```
+
+## What gets counted
+
+- In a git repo: the files git knows about, tracked and untracked, minus `.gitignore`,
+  including nested repos and submodules. Elsewhere, in a folder git ignores, or with
+  `--no-git`: everything except `node_modules`, `dist`, `build`, `.venv`, `vendor` and
+  similar below DIR.
+- Skipped by default: lockfiles, `*.min.js`, `*.min.css`, `*.map`
+  (`--no-default-excludes` counts them). Add your own with `-x`, repeatable:
+  a name or glob matches anywhere (`-x docs -x '*.md'`), a path matches relative
+  to DIR (`-x src/generated`).
+- Binary files (a NUL byte in the first 8 KB), text files over 50 MB and symlinks
+  are skipped.
+- `lines` = all lines, `code` = non-blank lines. Comments count as code; use
+  `scc` or `tokei` if you need comments separated.
+
+## Keys
+
+| Key | |
+|---|---|
+| arrows, `hjkl`, enter, backspace | navigate |
+| `m` | metric: lines, code lines, files |
+| `s` / `n` | sort by count / name, again to reverse |
+| `t` | file types in the current directory |
+| `e` | open the file in `$EDITOR`, recounted afterwards |
+| `d` / `u` | hide from the view / undo; nothing on disk is touched |
+| `r` | rescan |
+| `?` / `q` | help / quit |
+
+## Without the UI
+
+```sh
+locdu -p -d 2 -n 10           # tree, two levels, top 10 per directory
+locdu | less                  # prints automatically when stdout is not a terminal
+locdu --ncdu - | ncdu -f -    # hand the counts to ncdu (shown as sizes)
+```
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests -v
+```

locdu-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "locdu"
+dynamic = ["version"]
+description = "ncdu for lines of code: browse where the lines in a codebase are"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kevin Müller" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["loc", "lines of code", "cloc", "ncdu", "tui", "curses"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console :: Curses",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/kevmiota/locdu"
+Issues = "https://github.com/kevmiota/locdu/issues"
+
+[project.scripts]
+locdu = "locdu.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "locdu.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

locdu-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

locdu-0.1.0/src/locdu/__init__.py

@@ -0,0 +1,3 @@
+"""locdu: ncdu for lines of code."""
+
+__version__ = "0.1.0"

locdu-0.1.0/src/locdu/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

locdu-0.1.0/src/locdu/cli.py

@@ -0,0 +1,91 @@
+"""Command line entry point."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .output import fmt, render_text, to_ncdu
+from .scan import DEFAULT_EXCLUDES, METRICS, scan
+
+EPILOG = """\
+examples:
+  locdu                          browse the current directory
+  locdu ~/work/client/repo -x docs -x '*.md'
+  locdu -p -d 2 -n 10            print the top 10 per directory, two levels deep
+  locdu --ncdu - | ncdu -f -     hand the counts to ncdu
+
+In a git repo, the file list comes from git (tracked + untracked, minus .gitignore).
+Lockfiles, *.min.js, *.min.css and *.map are skipped unless --no-default-excludes is set.
+"""
+
+
+def _progress(done: int, total: int) -> None:
+    if done < total:
+        sys.stderr.write(f"\rscanning {fmt(done)}/{fmt(total)} files")
+    else:
+        sys.stderr.write("\r\033[K")
+    sys.stderr.flush()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="locdu",
+        description="ncdu for lines of code: see where the lines in a codebase are.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument("dir", nargs="?", default=".", help="directory to scan (default: .)")
+    ap.add_argument("-x", "--exclude", action="append", default=[], metavar="GLOB",
+                    help="skip files/dirs matching GLOB (a name anywhere, or a path relative to DIR); repeatable")
+    ap.add_argument("--no-default-excludes", action="store_true",
+                    help="also count lockfiles, *.min.js, *.min.css and *.map")
+    ap.add_argument("--no-git", action="store_true",
+                    help="walk the directory instead of asking git for the file list")
+    ap.add_argument("-m", "--metric", choices=METRICS, default="lines",
+                    help="lines (all), code (non-blank) or files (default: lines)")
+    ap.add_argument("-p", "--print", dest="print_tree", action="store_true",
+                    help="print a tree instead of the interactive view (default when output is not a terminal)")
+    ap.add_argument("-d", "--depth", type=int, default=1, metavar="N", help="with --print: levels to show (default: 1)")
+    ap.add_argument("-n", "--top", type=int, default=None, metavar="N", help="with --print: at most N entries per directory")
+    ap.add_argument("--ncdu", metavar="FILE", help="write ncdu's JSON format to FILE (- for stdout), for `ncdu -f`")
+    ap.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    patterns = [p.rstrip("/") for p in args.exclude if p.rstrip("/")]
+    if not args.no_default_excludes:
+        patterns += DEFAULT_EXCLUDES
+    interactive = not (args.print_tree or args.ncdu) and sys.stdin.isatty() and sys.stdout.isatty()
+
+    def do_scan(show_progress: bool):
+        progress = _progress if show_progress and sys.stderr.isatty() else None
+        return scan(args.dir, patterns, use_git=not args.no_git, progress=progress)
+
+    try:
+        result = do_scan(show_progress=True)
+        if args.ncdu:
+            data = to_ncdu(result.root, args.metric)
+            if args.ncdu == "-":
+                json.dump(data, sys.stdout)
+            else:
+                with open(args.ncdu, "w", encoding="utf-8") as f:
+                    json.dump(data, f)
+        elif interactive:
+            from .tui import run
+
+            run(result, lambda: do_scan(show_progress=False), args.metric)
+        else:
+            print(render_text(result.root, args.metric, max(1, args.depth), args.top))
+    except NotADirectoryError as e:
+        print(f"locdu: not a directory: {e}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    return 0

locdu-0.1.0/src/locdu/output.py

@@ -0,0 +1,61 @@
+"""Non-interactive output: a text tree and ncdu's JSON export format."""
+from __future__ import annotations
+
+import os
+import time
+
+from . import __version__
+from .scan import Node
+
+
+def fmt(n: int) -> str:
+    return f"{n:,}".replace(",", "'")
+
+
+def printable(text: str) -> str:
+    """Show bytes of non-UTF-8 file names as \\xNN instead of failing to encode them."""
+    return os.fsencode(text).decode("utf-8", "backslashreplace")
+
+
+def sorted_children(node: Node, metric: str) -> list[Node]:
+    return sorted(node.children.values(), key=lambda n: (-n.value(metric), n.name.lower()))
+
+
+def render_text(root: Node, metric: str = "lines", depth: int = 1, top: int | None = None) -> str:
+    total = root.value(metric)
+    width = len(fmt(total))
+    out = [f"{fmt(total)} {metric} in {fmt(root.files)} files  {root.name}"]
+
+    def walk(node: Node, level: int) -> None:
+        kids = sorted_children(node, metric)
+        shown = kids[:top] if top else kids
+        indent = "  " * level
+        for kid in shown:
+            value = kid.value(metric)
+            pct = 100 * value / total if total else 0.0
+            suffix = "/" if kid.is_dir else ""
+            out.append(f"{fmt(value):>{width}}  {pct:5.1f}%  {indent}{kid.name}{suffix}")
+            if kid.is_dir and level + 1 < depth:
+                walk(kid, level + 1)
+        if len(kids) > len(shown):
+            out.append(f"{'':>{width}}          {indent}... {len(kids) - len(shown)} more")
+
+    walk(root, 0)
+    return printable("\n".join(out))
+
+
+def to_ncdu(root: Node, metric: str = "lines") -> list:
+    """ncdu export format; the metric goes into the size fields, so `ncdu -f` shows it as size."""
+
+    def emit(node: Node, name: str) -> list:
+        entries: list = [{"name": name}]
+        for kid in sorted(node.children.values(), key=lambda n: n.name):
+            if kid.is_dir:
+                entries.append(emit(kid, kid.name))
+            else:
+                value = kid.value(metric)
+                entries.append({"name": kid.name, "asize": value, "dsize": value})
+        return entries
+
+    meta = {"progname": "locdu", "progver": __version__, "timestamp": int(time.time())}
+    return [1, 0, meta, emit(root, root.name)]

locdu-0.1.0/src/locdu/scan.py

@@ -0,0 +1,233 @@
+"""Find files, count their lines and build the directory tree."""
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+import stat
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from typing import Callable, Iterable
+
+METRICS = ("lines", "code", "files")
+
+# Only used without git; in a git repo, .gitignore decides.
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", ".next", ".nuxt", ".turbo", ".cache",
+    "dist", "build", "coverage", ".venv", "venv", "__pycache__", "vendor",
+}
+
+DEFAULT_EXCLUDES = [
+    "pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock", "bun.lockb",
+    "composer.lock", "Cargo.lock", "poetry.lock", "uv.lock", "Gemfile.lock", "go.sum",
+    "*.min.js", "*.min.css", "*.map",
+]
+
+SNIFF_BYTES = 8192
+MAX_BYTES = 50 * 2**20  # bigger text files are data dumps, not code
+
+
+class Node:
+    """A file or directory. Directory counts are the sums of their children."""
+
+    __slots__ = ("name", "parent", "children", "lines", "code", "files")
+
+    def __init__(self, name: str, parent: Node | None = None, is_dir: bool = False):
+        self.name = name
+        self.parent = parent
+        self.children: dict[str, Node] | None = {} if is_dir else None
+        self.lines = 0
+        self.code = 0
+        self.files = 0
+
+    @property
+    def is_dir(self) -> bool:
+        return self.children is not None
+
+    def value(self, metric: str) -> int:
+        return getattr(self, metric)
+
+    def relpath(self) -> str:
+        parts = []
+        node = self
+        while node.parent is not None:
+            parts.append(node.name)
+            node = node.parent
+        return "/".join(reversed(parts))
+
+    def find(self, relpath: str) -> Node | None:
+        node = self
+        for part in filter(None, relpath.split("/")):
+            if not node.is_dir or part not in node.children:
+                return None
+            node = node.children[part]
+        return node
+
+    def _add_to_ancestors(self, lines: int, code: int, files: int) -> None:
+        node = self.parent
+        while node is not None:
+            node.lines += lines
+            node.code += code
+            node.files += files
+            node = node.parent
+
+    def detach(self) -> None:
+        """Take this node out of the tree (view only) and update the totals above it."""
+        del self.parent.children[self.name]
+        self._add_to_ancestors(-self.lines, -self.code, -self.files)
+
+    def reattach(self) -> None:
+        self.parent.children[self.name] = self
+        self._add_to_ancestors(self.lines, self.code, self.files)
+
+    def set_counts(self, lines: int, code: int) -> None:
+        """Replace a file's counts, e.g. after it was edited."""
+        delta_lines, delta_code = lines - self.lines, code - self.code
+        self.lines, self.code = lines, code
+        self._add_to_ancestors(delta_lines, delta_code, 0)
+
+
+@dataclass
+class ScanResult:
+    root: Node
+    skipped: int  # binary or larger than MAX_BYTES
+
+
+def count_lines(path: str) -> tuple[int, int] | None:
+    """(lines, non-blank lines) of a text file; None if it is binary, too large or unreadable."""
+    try:
+        with open(path, "rb") as f:
+            data = f.read(SNIFF_BYTES)
+            if b"\0" in data or os.fstat(f.fileno()).st_size > MAX_BYTES:
+                return None
+            data += f.read()
+    except OSError:
+        return None
+    if not data:
+        return 0, 0
+    lines = data.count(b"\n") + (not data.endswith(b"\n"))
+    code = sum(1 for line in data.split(b"\n") if line.strip())
+    return lines, code
+
+
+def exclude_matcher(patterns: Iterable[str]) -> Callable[[str], bool]:
+    """Test for relative paths: a pattern matches any single path component, or a path prefix."""
+    patterns = list(patterns)
+    if not patterns:
+        return lambda relpath: False
+    regex = re.compile("|".join(fnmatch.translate(p) for p in patterns))
+
+    def is_excluded(relpath: str) -> bool:
+        parts = relpath.split("/")
+        candidates = parts + ["/".join(parts[:i]) for i in range(2, len(parts) + 1)]
+        return any(regex.match(c) for c in candidates)
+
+    return is_excluded
+
+
+def list_files(root: str, use_git: bool = True) -> list[str]:
+    """Candidate file paths relative to root."""
+    if use_git:
+        try:
+            out = subprocess.run(
+                ["git", "-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+                capture_output=True,
+                check=True,
+            ).stdout
+        except (OSError, subprocess.CalledProcessError):
+            pass
+        else:
+            paths = []
+            for p in sorted({os.fsdecode(p).rstrip("/") for p in out.split(b"\0")} - {"", "."}):
+                full = os.path.join(root, p)
+                if os.path.isdir(full) and not os.path.islink(full):
+                    # A submodule or nested repo: git lists only the directory, not its files.
+                    paths.extend(f"{p}/{q}" for q in list_files(full))
+                else:
+                    paths.append(p)
+            if paths:
+                return paths
+        # Not a repo, or git lists nothing here (e.g. a folder in .gitignore): walk it.
+
+    paths = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS)
+        rel = os.path.relpath(dirpath, root)
+        prefix = "" if rel == "." else rel.replace(os.sep, "/") + "/"
+        paths.extend(prefix + f for f in sorted(filenames))
+    return paths
+
+
+def _count_regular(path: str) -> tuple[int, int] | None | bool:
+    """False for anything that is not a regular file (symlinks, deleted files, submodules)."""
+    try:
+        if not stat.S_ISREG(os.lstat(path).st_mode):
+            return False
+    except OSError:
+        return False
+    return count_lines(path)
+
+
+def _insert(root: Node, relpath: str, lines: int, code: int) -> None:
+    *dirs, name = relpath.split("/")
+    node = root
+    for d in dirs:
+        child = node.children.get(d)
+        if child is None:
+            child = node.children[d] = Node(d, node, is_dir=True)
+        node = child
+    leaf = node.children[name] = Node(name, node)
+    leaf.lines, leaf.code, leaf.files = lines, code, 1
+    leaf._add_to_ancestors(lines, code, 1)
+
+
+def scan(
+    root_dir: str,
+    excludes: Iterable[str] = (),
+    use_git: bool = True,
+    progress: Callable[[int, int], None] | None = None,
+) -> ScanResult:
+    root_dir = os.path.abspath(root_dir)
+    if not os.path.isdir(root_dir):
+        raise NotADirectoryError(root_dir)
+    is_excluded = exclude_matcher(excludes)
+    kept = [p for p in list_files(root_dir, use_git) if not is_excluded(p)]
+
+    root = Node(root_dir, is_dir=True)
+    skipped = 0
+    workers = min(32, (os.cpu_count() or 1) * 4)
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        counts = pool.map(lambda p: _count_regular(os.path.join(root_dir, p)), kept)
+        for i, (relpath, result) in enumerate(zip(kept, counts), 1):
+            if result is None:
+                skipped += 1
+            elif result is not False:
+                _insert(root, relpath, *result)
+            if progress and i % 500 == 0:
+                progress(i, len(kept))
+    if progress:
+        progress(len(kept), len(kept))
+    return ScanResult(root, skipped)
+
+
+def file_type(name: str) -> str:
+    """Extension in lower case, or the whole name for files without one (Dockerfile, .gitignore)."""
+    ext = os.path.splitext(name)[1]
+    return ext.lower() if ext else name
+
+
+def by_file_type(node: Node) -> list[tuple[str, int, int, int]]:
+    """(type, lines, code, files) for every file type below node."""
+    stats: dict[str, list[int]] = {}
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        if n.is_dir:
+            stack.extend(n.children.values())
+        else:
+            s = stats.setdefault(file_type(n.name), [0, 0, 0])
+            s[0] += n.lines
+            s[1] += n.code
+            s[2] += 1
+    return [(k, *v) for k, v in stats.items()]