code2okf 0.1.0__py3-none-any.whl

code2okf/clis/inspectokf/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "inspectokf"
+version = "0.1.0"
+description = "Print a directory tree for an OKF wiki folder"
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+inspectokf = "inspectokf.cli:entrypoint"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+test = ["pytest>=8.4"]
+
+# Paths are relative to this file, so they resolve wherever the project is
+# invoked from. pythonpath keeps `import inspectokf` working without an install.
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+# Same rule set as inspectmd: owned here under the zero-overlap rule, not shared.
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "C4", "RET", "PT", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# A test's name is its documentation; a docstring on each of them would be noise.
+# Fixtures and helpers are still expected to explain themselves.
+"tests/*" = ["D100", "D103"]

code2okf/clis/inspectokf/src/inspectokf/__init__.py

@@ -0,0 +1,8 @@
+"""Inspect an OKF wiki directory tree (stdlib only)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("inspectokf")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"

code2okf/clis/inspectokf/src/inspectokf/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m inspectokf`."""
+
+from inspectokf.cli import main
+
+raise SystemExit(main())

code2okf/clis/inspectokf/src/inspectokf/cli.py

@@ -0,0 +1,104 @@
+"""Command-line interface for inspectokf."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from inspectokf import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="inspectokf",
+        description="Print a directory tree for an OKF wiki folder (via tree).",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        type=Path,
+        default=Path("okf"),
+        help="wiki directory to show (default: okf)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-L",
+        "--level",
+        type=int,
+        metavar="N",
+        help="descend at most N directory levels (default: unlimited)",
+    )
+    return parser
+
+
+def _visibly_empty(path: Path) -> bool | None:
+    """Return True if ``path`` has no non-hidden children.
+
+    Returns ``None`` when the directory cannot be listed (caller should exit 2).
+    Dotfiles are ignored so a fresh ``okf/`` that only holds ``.DS_Store``
+    is treated as empty, matching ``tree``'s default of hiding names that start
+    with ``.``.
+    """
+    try:
+        return not any(not child.name.startswith(".") for child in path.iterdir())
+    except OSError as exc:
+        print(f"inspectokf: {exc}", file=sys.stderr)
+        return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse argv and run tree. Returns a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Checked before the path and tree lookups so the message is the same
+    # wherever it is run from, and `tree` need not be installed to get it.
+    # tree rejects 0 itself; catching it here keeps the `inspectokf: ` prefix.
+    level: int | None = args.level
+    if level is not None and level < 1:
+        print(f"inspectokf: --level must be 1 or greater (got {level})", file=sys.stderr)
+        return 2
+
+    path: Path = args.path
+    if not path.is_dir():
+        print(f"inspectokf: not a directory: {path}", file=sys.stderr)
+        return 2
+
+    # Empty / dotfile-only dirs succeed without tree so a fresh wiki cannot fail
+    # on tree exit-code quirks or a missing binary.
+    empty = _visibly_empty(path)
+    if empty is None:
+        return 2
+    if empty:
+        sys.stdout.write(f"{path}\n\n0 directories, 0 files\n")
+        return 0
+
+    tree_bin = shutil.which("tree")
+    if tree_bin is None:
+        print("inspectokf: 'tree' not found on PATH", file=sys.stderr)
+        return 2
+
+    command = [tree_bin]
+    if level is not None:
+        command += ["-L", str(level)]
+    command.append(str(path))
+
+    # Inherit stdio: tree writes directly to this process's stdout/stderr.
+    try:
+        completed = subprocess.run(command, check=False)  # noqa: S603
+    except OSError as exc:
+        print(f"inspectokf: {exc}", file=sys.stderr)
+        return 2
+    return 0 if completed.returncode == 0 else 2
+
+
+def entrypoint() -> None:
+    """Console-script entry: exit with ``main``'s return code."""
+    raise SystemExit(main())

code2okf/clis/merkleokf/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "merkleokf"
+version = "0.1.0"
+description = "Print a Merkle hash tree for an OKF wiki folder"
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+merkleokf = "merkleokf.cli:entrypoint"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+test = ["pytest>=8.4"]
+
+# Paths are relative to this file, so they resolve wherever the project is
+# invoked from. pythonpath keeps `import merkleokf` working without an install.
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+# Same rule set as sizeokf: owned here under the zero-overlap rule, not shared.
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "C4", "RET", "PT", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# A test's name is its documentation; a docstring on each of them would be noise.
+# Fixtures and helpers are still expected to explain themselves.
+"tests/*" = ["D100", "D103"]

code2okf/clis/merkleokf/src/merkleokf/__init__.py

@@ -0,0 +1,8 @@
+"""Print a Merkle hash tree for an OKF wiki folder (stdlib only)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("merkleokf")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"

code2okf/clis/merkleokf/src/merkleokf/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m merkleokf`."""
+
+from merkleokf.cli import main
+
+raise SystemExit(main())

code2okf/clis/merkleokf/src/merkleokf/cli.py

@@ -0,0 +1,121 @@
+"""Command-line interface for merkleokf."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from merkleokf import __version__
+from merkleokf.merkle import Entry, collect, hash_file, short
+
+
+def escape_display_path(path: str) -> str:
+    """Escape controls so a path stays one table cell (no newlines or ANSI)."""
+    out: list[str] = []
+    for ch in path:
+        code = ord(ch)
+        if ch == "\\":
+            out.append("\\\\")
+        elif ch == "\n":
+            out.append("\\n")
+        elif ch == "\r":
+            out.append("\\r")
+        elif ch == "\t":
+            out.append("\\t")
+        elif code < 0x20 or code == 0x7F:
+            out.append(f"\\x{code:02x}")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def format_table(entries: Sequence[Entry]) -> str:
+    """Render entries as a fixed-width table, one row per file or directory."""
+    if not entries:
+        return "(no Markdown files)\n"
+
+    headers = ("Hash", "Files", "Path")
+    rows = [(short(e.digest), f"{e.files:,}", escape_display_path(e.path)) for e in entries]
+
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+
+    def fmt(cells: tuple[str, ...]) -> str:
+        # Only the count is right-aligned; hashes are fixed width already.
+        return "  ".join(
+            cell.rjust(widths[i]) if i == 1 else cell.ljust(widths[i]) for i, cell in enumerate(cells)
+        ).rstrip()
+
+    lines = [fmt(headers), fmt(tuple("-" * w for w in widths))]
+    lines.extend(fmt(row) for row in rows)
+    return "\n".join(lines) + "\n"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="merkleokf",
+        description="Print a Merkle hash tree for an OKF wiki folder, or the hash of one file.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        type=Path,
+        default=Path("okf"),
+        help="wiki directory or Markdown file to hash (default: okf)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-L",
+        "--level",
+        type=int,
+        metavar="N",
+        help=(
+            "list entries at most N directory levels deep "
+            "(default: unlimited; 0 = walk root only; ignored for a file)"
+        ),
+    )
+    parser.add_argument(
+        "--nolog",
+        action="store_true",
+        help="ignore the walk root's log.md (omit from listing and digests; ignored for a file)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse argv and print the Merkle tree. Returns a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Checked before the path so the message is the same wherever it is run from.
+    level: int | None = args.level
+    if level is not None and level < 0:
+        print(f"merkleokf: --level must be 0 or greater (got {level})", file=sys.stderr)
+        return 2
+
+    path: Path = args.path
+
+    if path.is_file():
+        sys.stdout.write(f"{short(hash_file(path))}  {escape_display_path(path.name)}\n")
+        return 0
+
+    if not path.is_dir():
+        print(f"merkleokf: not a file or directory: {path}", file=sys.stderr)
+        return 2
+
+    entries, _ = collect(path, max_level=level, nolog=args.nolog)
+    sys.stdout.write(format_table(entries))
+    return 0
+
+
+def entrypoint() -> None:
+    """Console-script entry: exit with ``main``'s return code."""
+    raise SystemExit(main())

code2okf/clis/merkleokf/src/merkleokf/merkle.py

@@ -0,0 +1,145 @@
+"""Build a Merkle hash tree over an OKF wiki.
+
+Every ``*.md`` file is hashed over its **raw bytes**, and every directory over
+its children's digests, so a change to any leaf propagates to exactly one chain
+of parent directories and nowhere else. That is what makes change localisation
+cheap: compare one root hash, and if it moved, descend into the single subtree
+whose hash also moved.
+
+Raw bytes, not frontmatter-stripped content: this is the integrity tool, so a
+timestamp bump counts as a change. ``sizeokf`` is the one that measures prose.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+DISPLAY_WIDTH = 12
+"""Hex characters shown per digest. 48 bits — collision odds ~8e-11 at 217 files,
+~2e-7 at 10,000. Full digests are always computed; only the display truncates."""
+
+
+def hash_file(path: Path) -> bytes:
+    """SHA-256 over a file's raw bytes.
+
+    An unreadable file is reported on stderr and contributes an all-zero digest
+    rather than aborting the walk — one bad page must not cost the rest.
+    """
+    try:
+        return hashlib.sha256(path.read_bytes()).digest()
+    except OSError as exc:
+        print(f"merkleokf: skipping {path}: {exc}", file=sys.stderr)
+        return bytes(32)
+
+
+def short(digest: bytes) -> str:
+    """Truncate a digest to its displayed hex prefix."""
+    return digest.hex()[:DISPLAY_WIDTH]
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One listed file or directory, with its digest."""
+
+    path: str
+    """Display path, rooted at the walk target's name. Directories end in ``/``."""
+
+    is_dir: bool
+    digest: bytes
+    """Full SHA-256. For a directory, the Merkle digest over its children."""
+
+    files: int
+    """Markdown files covered. Always 1 for a file."""
+
+    depth: int
+    """1 for entries directly inside the root; 0 for the root itself."""
+
+
+def collect(
+    root: Path, *, max_level: int | None = None, nolog: bool = False
+) -> tuple[list[Entry], Entry]:
+    """Walk ``root``, returning ``(listed_entries, root_entry)``.
+
+    ``listed_entries`` always includes ``root_entry``. Directory digests always
+    cover the full subtree regardless of ``max_level``; the level only decides
+    which non-root entries get listed. ``max_level=0`` lists only the walk root;
+    ``max_level=1`` lists the entries directly inside ``root``, matching
+    ``inspectokf -L 1``.
+
+    When ``nolog`` is true, the walk root's own ``log.md`` is omitted entirely
+    (not listed and not mixed into digests), whatever the root directory is
+    named. Nested ``log.md`` files, and ``log.md`` under any other root, are
+    still hashed.
+    """
+    entries: list[Entry] = []
+    prefix = f"{root.name}/"
+
+    def walk(directory: Path, depth: int) -> tuple[bytes, int]:
+        """Return ``(digest, files)`` for ``directory``, recording listed entries."""
+        # Sorted so the digest is reproducible across filesystems, which do not
+        # agree on readdir order.
+        children = sorted(directory.iterdir(), key=lambda p: p.name)
+        acc = hashlib.sha256()
+        files = 0
+
+        for child in children:
+            if child.name.startswith("."):
+                continue
+            # is_dir() follows symlinks; is_symlink() first keeps cycles out.
+            if child.is_symlink():
+                continue
+
+            if child.is_dir():
+                digest, child_files = walk(child, depth + 1)
+                files += child_files
+                # The type tag keeps a file and a directory of the same name
+                # apart; the name keeps a pure rename from being invisible.
+                acc.update(b"d" + child.name.encode("utf-8") + digest)
+                listed = Entry(
+                    path=f"{prefix}{child.relative_to(root)}/",
+                    is_dir=True,
+                    digest=digest,
+                    files=child_files,
+                    depth=depth,
+                )
+            elif child.suffix == ".md":
+                # Anchored to the walk root itself, not to any directory named
+                # "okf": a nested okf/ keeps its own log.md, as the docstring
+                # promises, and the walk root's log.md is skipped whatever the
+                # root directory happens to be called.
+                if nolog and child.name == "log.md" and child.parent == root:
+                    continue
+                digest = hash_file(child)
+                files += 1
+                acc.update(b"f" + child.name.encode("utf-8") + digest)
+                listed = Entry(
+                    path=f"{prefix}{child.relative_to(root)}",
+                    is_dir=False,
+                    digest=digest,
+                    files=1,
+                    depth=depth,
+                )
+            else:
+                continue
+
+            if max_level is None or depth <= max_level:
+                entries.append(listed)
+
+        return acc.digest(), files
+
+    root_digest, root_files = walk(root, 1)
+    root_entry = Entry(
+        path=prefix,
+        is_dir=True,
+        digest=root_digest,
+        files=root_files,
+        depth=0,
+    )
+    entries.append(root_entry)
+
+    # Alphabetical, so two runs diff line by line — the whole point of hashing.
+    entries.sort(key=lambda e: e.path)
+    return entries, root_entry

code2okf/clis/sizeokf/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "sizeokf"
+version = "0.1.0"
+description = "Report content word counts for an OKF wiki folder"
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+sizeokf = "sizeokf.cli:entrypoint"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+test = ["pytest>=8.4"]
+
+# Paths are relative to this file, so they resolve wherever the project is
+# invoked from. pythonpath keeps `import sizeokf` working without an install.
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+# Same rule set as inspectokf: owned here under the zero-overlap rule, not shared.
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "C4", "RET", "PT", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# A test's name is its documentation; a docstring on each of them would be noise.
+# Fixtures and helpers are still expected to explain themselves.
+"tests/*" = ["D100", "D103"]

code2okf/clis/sizeokf/src/sizeokf/__init__.py

@@ -0,0 +1,8 @@
+"""Report sizes for an OKF wiki folder (stdlib only)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("sizeokf")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"

code2okf/clis/sizeokf/src/sizeokf/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m sizeokf`."""
+
+from sizeokf.cli import main
+
+raise SystemExit(main())

code2okf/clis/sizeokf/src/sizeokf/cli.py

@@ -0,0 +1,93 @@
+"""Command-line interface for sizeokf."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from sizeokf import __version__
+from sizeokf.sizes import Entry, collect
+
+
+def format_table(entries: Sequence[Entry]) -> str:
+    """Render entries as a fixed-width table, one row per file or directory."""
+    if not entries:
+        return "(no Markdown files)\n"
+
+    headers = ("Words", "Files", "Path")
+    rows = [(f"{e.words:,}", f"{e.files:,}", e.path) for e in entries]
+
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+
+    def fmt(cells: tuple[str, ...]) -> str:
+        # Counts right-aligned so magnitudes line up; the path column trails.
+        return "  ".join(
+            cell.rjust(widths[i]) if i < 2 else cell.ljust(widths[i]) for i, cell in enumerate(cells)
+        ).rstrip()
+
+    lines = [fmt(headers), fmt(tuple("-" * w for w in widths))]
+    lines.extend(fmt(row) for row in rows)
+    return "\n".join(lines) + "\n"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sizeokf",
+        description="Report Markdown content word counts for an OKF wiki folder, excluding YAML frontmatter.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        type=Path,
+        default=Path("okf"),
+        help="wiki directory to measure (default: okf)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-L",
+        "--level",
+        type=int,
+        metavar="N",
+        help="list entries at most N directory levels deep (default: unlimited; 0 = walk root only)",
+    )
+    parser.add_argument(
+        "--nolog",
+        action="store_true",
+        help="ignore okf/log.md (omit from listing and totals)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse argv and print the size table. Returns a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Checked before the path so the message is the same wherever it is run from.
+    level: int | None = args.level
+    if level is not None and level < 0:
+        print(f"sizeokf: --level must be 0 or greater (got {level})", file=sys.stderr)
+        return 2
+
+    path: Path = args.path
+    if not path.is_dir():
+        print(f"sizeokf: not a directory: {path}", file=sys.stderr)
+        return 2
+
+    entries, _ = collect(path, max_level=level, nolog=args.nolog)
+    sys.stdout.write(format_table(entries))
+    return 0
+
+
+def entrypoint() -> None:
+    """Console-script entry: exit with ``main``'s return code."""
+    raise SystemExit(main())