git-undigest 0.2.0__py3-none-any.whl

git_undigest/__init__.py

@@ -0,0 +1,290 @@
+"""git-undigest: reconstruct a full repository from a GitIngest-style digest.
+
+Public API:
+    reconstruct: Parse a digest and write the resulting files to disk.
+    validate: Validate a digest without writing anything.
+    inspect: Produce a human-oriented summary of a digest's contents.
+    stats: Produce numeric statistics about a digest.
+    list_files: List every file path contained in a digest.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import utils
+from .exceptions import (
+    BinaryDecodeError,
+    ChecksumMismatchError,
+    DigestIntegrityError,
+    DigestParseError,
+    DuplicateFileError,
+    FileExistsConflictError,
+    FileSizeLimitError,
+    FileWriteError,
+    GitUndigestError,
+    InvalidDigestError,
+    NotImplementedFeatureError,
+    PathTraversalError,
+    UnsupportedFormatError,
+)
+from .models import (
+    DigestFile,
+    DigestSummary,
+    FileEntry,
+    ReconstructionResult,
+    Repository,
+    StatsResult,
+    WriteResult,
+)
+from .parser import iter_files, parse_digest, parse_digest_text, parse_stream
+from .validator import validate_summary
+from .writer import reconstruct_files, reconstruct_files_stream
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "reconstruct",
+    "validate",
+    "inspect",
+    "stats",
+    "list_files",
+    "parse_digest",
+    "parse_digest_text",
+    "parse_stream",
+    "iter_files",
+    "reconstruct_files",
+    "reconstruct_files_stream",
+    "__version__",
+    # Models
+    "DigestFile",
+    "DigestSummary",
+    "FileEntry",
+    "ReconstructionResult",
+    "Repository",
+    "StatsResult",
+    "WriteResult",
+    # Exceptions
+    "GitUndigestError",
+    "DigestParseError",
+    "InvalidDigestError",
+    "PathTraversalError",
+    "DuplicateFileError",
+    "ChecksumMismatchError",
+    "FileWriteError",
+    "FileExistsConflictError",
+    "FileSizeLimitError",
+    "BinaryDecodeError",
+    "DigestIntegrityError",
+    "UnsupportedFormatError",
+    "NotImplementedFeatureError",
+]
+
+
+def reconstruct(
+    digest_path: str | Path,
+    output: str | Path = "output",
+    *,
+    overwrite: bool = False,
+    skip_existing: bool = False,
+    backup: bool = False,
+    dry_run: bool = False,
+    format_name: str | None = None,
+) -> ReconstructionResult:
+    """Reconstruct a full repository from a digest file.
+
+    Uses streaming internally — the digest is parsed and written
+    line-by-line without loading the entire file into memory.
+
+    Args:
+        digest_path: Path to the GitIngest-style digest file.
+        output: Directory to reconstruct the repository into.
+        overwrite: Overwrite existing files instead of erroring.
+        skip_existing: Skip existing files instead of erroring.
+        backup: Back up existing files to ``*.bak`` before overwriting.
+        dry_run: Report what would happen without writing anything.
+        format_name: Optional explicit digest format name. Auto-detected
+            if omitted.
+
+    Returns:
+        A :class:`ReconstructionResult` describing what was written (or
+        would be written, in dry-run mode).
+
+    Raises:
+        InvalidDigestError: If the digest is empty, unreadable, or
+            structurally invalid.
+        DigestParseError: If the digest format is recognized but a section
+            is malformed.
+        DuplicateFileError: If the digest contains duplicate file paths.
+        PathTraversalError: If any file path is unsafe.
+        FileExistsConflictError: If a target file exists and no overwrite
+            policy was given.
+        FileWriteError: If a filesystem operation fails.
+
+    Example:
+        >>> from git_undigest import reconstruct
+        >>> result = reconstruct("digest.txt", output="repo")
+        >>> result.output_dir
+        'repo'
+    """
+    entries = parse_stream(digest_path, format_name=format_name)
+    return reconstruct_files_stream(
+        entries,
+        output,
+        overwrite=overwrite,
+        skip_existing=skip_existing,
+        backup=backup,
+        dry_run=dry_run,
+    )
+
+
+def validate(
+    digest_path: str | Path, *, format_name: str | None = None
+) -> DigestSummary:
+    """Validate a digest file without writing anything to disk.
+
+    Args:
+        digest_path: Path to the digest file.
+        format_name: Optional explicit digest format name.
+
+    Returns:
+        The parsed and validated :class:`DigestSummary`, if valid.
+
+    Raises:
+        InvalidDigestError: If the digest is empty or structurally invalid.
+        DigestParseError: If a section is malformed.
+        DuplicateFileError: If duplicate file paths are present.
+        PathTraversalError: If any file path is empty or unsafe.
+    """
+    summary = parse_digest(digest_path, format_name=format_name)
+    validate_summary(summary)
+    return summary
+
+
+def inspect(
+    digest_path: str | Path, *, format_name: str | None = None
+) -> dict[str, Any]:
+    """Produce a human-oriented summary of a digest's contents.
+
+    Args:
+        digest_path: Path to the digest file.
+        format_name: Optional explicit digest format name.
+
+    Returns:
+        A dictionary with keys ``repo_name``, ``file_count``,
+        ``languages`` (dict of language -> file count), ``largest_files``
+        (list of ``(path, size)`` tuples, largest first, top 10), and
+        ``tree`` (a rendered directory tree string).
+    """
+    summary = validate(digest_path, format_name=format_name)
+
+    languages: dict[str, int] = {}
+    for f in summary.files:
+        lang = utils.detect_language(f.extension)
+        if lang:
+            languages[lang] = languages.get(lang, 0) + 1
+
+    largest = sorted(summary.files, key=lambda f: f.size, reverse=True)[:10]
+
+    return {
+        "repo_name": summary.repo_name,
+        "file_count": summary.file_count,
+        "languages": dict(sorted(languages.items(), key=lambda kv: -kv[1])),
+        "largest_files": [(f.path, f.size) for f in largest],
+        "tree": render_tree(summary),
+    }
+
+
+def stats(digest_path: str | Path, *, format_name: str | None = None) -> StatsResult:
+    """Compute numeric statistics about a digest.
+
+    Args:
+        digest_path: Path to the digest file.
+        format_name: Optional explicit digest format name.
+
+    Returns:
+        A populated :class:`StatsResult`.
+    """
+    summary = validate(digest_path, format_name=format_name)
+
+    ext_counts: dict[str, int] = {}
+    for f in summary.files:
+        key = f.extension or "(no extension)"
+        ext_counts[key] = ext_counts.get(key, 0) + 1
+
+    total_chars = sum(len(f.content) for f in summary.files)
+
+    if summary.files:
+        largest = max(summary.files, key=lambda f: f.size)
+        largest_path: str | None = largest.path
+        largest_size = largest.size
+    else:
+        largest_path = None
+        largest_size = 0
+
+    file_count = summary.file_count
+    avg = (summary.total_bytes / file_count) if file_count else 0.0
+
+    return StatsResult(
+        file_count=file_count,
+        folder_count=len(summary.directories),
+        total_bytes=summary.total_bytes,
+        largest_file=largest_path,
+        largest_file_size=largest_size,
+        average_file_size=avg,
+        extension_counts=dict(sorted(ext_counts.items(), key=lambda kv: -kv[1])),
+        estimated_tokens=utils.estimate_tokens(total_chars),
+    )
+
+
+def list_files(digest_path: str | Path, *, format_name: str | None = None) -> list[str]:
+    """List every file path contained in a digest.
+
+    Args:
+        digest_path: Path to the digest file.
+        format_name: Optional explicit digest format name.
+
+    Returns:
+        A sorted list of file paths.
+    """
+    summary = validate(digest_path, format_name=format_name)
+    return sorted(f.path for f in summary.files)
+
+
+def render_tree(summary: DigestSummary) -> str:
+    """Render a directory tree string for a digest summary.
+
+    Args:
+        summary: The parsed digest.
+
+    Returns:
+        A multi-line string depicting the directory/file hierarchy.
+    """
+    root: dict[str, dict[str, Any] | None] = {}
+    for f in summary.files:
+        parts = f.path.split("/")
+        node = root
+        for part in parts[:-1]:
+            existing = node.get(part)
+            if existing is None:
+                existing = {}
+                node[part] = existing
+            node = existing
+        node[parts[-1]] = None
+
+    lines = [f"{summary.repo_name}/"]
+
+    def _walk(node: dict[str, dict[str, Any] | None], prefix: str) -> None:
+        entries = sorted(node.items(), key=lambda kv: (kv[1] is None, kv[0]))
+        for idx, (name, child) in enumerate(entries):
+            is_last = idx == len(entries) - 1
+            connector = "└── " if is_last else "├── "
+            suffix = "/" if isinstance(child, dict) else ""
+            lines.append(f"{prefix}{connector}{name}{suffix}")
+            if isinstance(child, dict):
+                extension = "    " if is_last else "│   "
+                _walk(child, prefix + extension)
+
+    _walk(root, "")
+    return "\n".join(lines)

git_undigest/checksum.py

@@ -0,0 +1,72 @@
+"""Checksum utilities.
+
+Provides SHA-256 hashing helpers used for integrity verification. Full
+digest-embedded checksum verification is a designed-but-not-yet-implemented
+feature (see :func:`verify_checksum`), since the GitIngest format itself
+does not currently embed per-file checksums.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from .exceptions import ChecksumMismatchError, NotImplementedFeatureError
+
+
+def sha256_text(content: str) -> str:
+    """Compute the SHA-256 hex digest of a text string (UTF-8 encoded).
+
+    Args:
+        content: The text content to hash.
+
+    Returns:
+        The hex-encoded SHA-256 digest.
+    """
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def sha256_bytes(data: bytes) -> str:
+    """Compute the SHA-256 hex digest of raw bytes.
+
+    Args:
+        data: The raw bytes to hash.
+
+    Returns:
+        The hex-encoded SHA-256 digest.
+    """
+    return hashlib.sha256(data).hexdigest()
+
+
+def verify_checksum(path: str, content: str, expected_checksum: str) -> None:
+    """Verify file content against an expected SHA-256 checksum.
+
+    This is a placeholder for future digest formats that embed per-file
+    checksums. The current GitIngest text format has no such field, so
+    callers should not invoke this unless they have an external checksum
+    manifest.
+
+    Args:
+        path: The file path, used for error reporting.
+        content: The file's text content.
+        expected_checksum: The expected SHA-256 hex digest.
+
+    Raises:
+        ChecksumMismatchError: If the computed checksum does not match.
+    """
+    actual = sha256_text(content)
+    if actual != expected_checksum:
+        raise ChecksumMismatchError(path, expected_checksum, actual)
+
+
+def verify_checksum_manifest(*_args: object, **_kwargs: object) -> None:
+    """Verify an entire reconstruction against a SHA-256 checksum manifest.
+
+    Designed interface for a future feature where a digest is accompanied
+    by a manifest file mapping paths to expected checksums.
+
+    Raises:
+        NotImplementedFeatureError: Always, until implemented.
+    """
+    raise NotImplementedFeatureError(
+        "Checksum manifest verification is not yet implemented."
+    )

git_undigest/cli.py

@@ -0,0 +1,251 @@
+"""Command-line interface for git-undigest.
+
+Commands:
+    git-undigest DIGEST [OUTPUT]      Reconstruct a repository.
+    git-undigest validate DIGEST      Validate a digest without writing.
+    git-undigest inspect DIGEST       Show a human summary of the digest.
+    git-undigest list DIGEST          List all files in the digest.
+    git-undigest stats DIGEST         Show numeric statistics.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import inspect as inspect_api
+from . import list_files as list_files_api
+from . import reconstruct as reconstruct_api
+from . import stats as stats_api
+from . import validate as validate_api
+from .exceptions import GitUndigestError
+from .models import ReconstructionResult
+from .utils import human_size
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="git-undigest",
+        description=(
+            "Reconstruct a full repository from a GitIngest-style digest " "file."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=_version_string())
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    def add_common_overwrite_flags(sp: argparse.ArgumentParser) -> None:
+        group = sp.add_mutually_exclusive_group()
+        group.add_argument(
+            "--overwrite",
+            action="store_true",
+            help="Overwrite existing files instead of erroring.",
+        )
+        group.add_argument(
+            "--skip-existing",
+            action="store_true",
+            help="Skip files that already exist instead of erroring.",
+        )
+        sp.add_argument(
+            "--backup",
+            action="store_true",
+            help="Back up existing files to '<name>.bak' before writing.",
+        )
+        sp.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Show what would happen without writing anything.",
+        )
+        sp.add_argument(
+            "--force",
+            action="store_true",
+            help="Alias for --overwrite.",
+        )
+        verbosity = sp.add_mutually_exclusive_group()
+        verbosity.add_argument(
+            "--verbose", action="store_true", help="Print detailed per-file output."
+        )
+        verbosity.add_argument(
+            "--quiet", action="store_true", help="Suppress non-essential output."
+        )
+
+    # Default reconstruction: `git-undigest digest.txt [output]`
+    recon = subparsers.add_parser(
+        "reconstruct", help="Reconstruct a repository from a digest (default command)."
+    )
+    recon.add_argument("digest", help="Path to the digest file.")
+    recon.add_argument(
+        "output",
+        nargs="?",
+        default="output",
+        help="Output directory (default: output).",
+    )
+    add_common_overwrite_flags(recon)
+
+    validate_p = subparsers.add_parser("validate", help="Validate a digest file.")
+    validate_p.add_argument("digest", help="Path to the digest file.")
+
+    inspect_p = subparsers.add_parser(
+        "inspect", help="Show repository name, languages, tree, and largest files."
+    )
+    inspect_p.add_argument("digest", help="Path to the digest file.")
+
+    list_p = subparsers.add_parser("list", help="List every file in the digest.")
+    list_p.add_argument("digest", help="Path to the digest file.")
+
+    stats_p = subparsers.add_parser(
+        "stats", help="Show numeric statistics about a digest."
+    )
+    stats_p.add_argument("digest", help="Path to the digest file.")
+
+    return parser
+
+
+def _version_string() -> str:
+    from . import __version__
+
+    return f"git-undigest {__version__}"
+
+
+def _print_reconstruction_result(
+    result: ReconstructionResult, *, verbose: bool, quiet: bool
+) -> None:
+    if quiet:
+        return
+
+    if verbose:
+        for r in result.results:
+            label = {
+                "created": "CREATE",
+                "would_create": "WOULD CREATE",
+                "overwritten": "OVERWRITE",
+                "would_overwrite": "WOULD OVERWRITE",
+                "skipped": "SKIP",
+                "backed_up": "BACKUP",
+            }.get(r.action, r.action.upper())
+            print(f"  [{label}] {r.path}")
+
+    for w in result.warnings:
+        print(f"warning: {w}", file=sys.stderr)
+
+    prefix = "Would write" if result.dry_run else "Wrote"
+    print(
+        f"{prefix} {len(result.created)} created, "
+        f"{len(result.overwritten)} overwritten, "
+        f"{len(result.skipped)} skipped, "
+        f"{len(result.backed_up)} backed up "
+        f"({human_size(result.total_bytes_written)}) to {result.output_dir}"
+    )
+
+
+def _cmd_reconstruct(args: argparse.Namespace) -> int:
+    result = reconstruct_api(
+        args.digest,
+        args.output,
+        overwrite=args.overwrite or args.force,
+        skip_existing=args.skip_existing,
+        backup=args.backup,
+        dry_run=args.dry_run,
+    )
+    _print_reconstruction_result(result, verbose=args.verbose, quiet=args.quiet)
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    summary = validate_api(args.digest)
+    print(f"OK: digest is valid ({summary.file_count} files).")
+    return 0
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    info = inspect_api(args.digest)
+    print(f"Repository: {info['repo_name']}")
+    print(f"Files: {info['file_count']}")
+    if info["languages"]:
+        print("Languages:")
+        for lang, count in info["languages"].items():
+            print(f"  {lang}: {count}")
+    if info["largest_files"]:
+        print("Largest files:")
+        for path, size in info["largest_files"]:
+            print(f"  {human_size(size):>10}  {path}")
+    print("Directory tree:")
+    print(info["tree"])
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    for path in list_files_api(args.digest):
+        print(path)
+    return 0
+
+
+def _cmd_stats(args: argparse.Namespace) -> int:
+    s = stats_api(args.digest)
+    print(f"Files:            {s.file_count}")
+    print(f"Folders:          {s.folder_count}")
+    print(f"Total size:       {human_size(s.total_bytes)}")
+    if s.largest_file:
+        print(f"Largest file:     {s.largest_file} ({human_size(s.largest_file_size)})")
+    print(f"Average size:     {human_size(s.average_file_size)}")
+    print(f"Estimated tokens: {s.estimated_tokens:,}")
+    if s.extension_counts:
+        print("Extensions:")
+        for ext, count in s.extension_counts.items():
+            print(f"  .{ext}: {count}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``git-undigest`` console script.
+
+    Args:
+        argv: Optional argument list (defaults to ``sys.argv[1:]``).
+
+    Returns:
+        Process exit code: 0 on success, 1 on a handled error, 2 on
+        argument-parsing errors (raised by argparse itself).
+    """
+    raw_args = sys.argv[1:] if argv is None else argv
+
+    # Support the bare `git-undigest digest.txt [output]` form by
+    # injecting the implicit "reconstruct" subcommand when the first
+    # token isn't a known subcommand or flag.
+    known_commands = {"reconstruct", "validate", "inspect", "list", "stats"}
+    args_to_parse = list(raw_args)
+    if (
+        args_to_parse
+        and args_to_parse[0] not in known_commands
+        and not args_to_parse[0].startswith("-")
+    ):
+        args_to_parse = ["reconstruct", *args_to_parse]
+    elif not args_to_parse:
+        args_to_parse = ["--help"]
+
+    parser = _build_parser()
+    args = parser.parse_args(args_to_parse)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    handlers = {
+        "reconstruct": _cmd_reconstruct,
+        "validate": _cmd_validate,
+        "inspect": _cmd_inspect,
+        "list": _cmd_list,
+        "stats": _cmd_stats,
+    }
+
+    try:
+        return handlers[args.command](args)
+    except GitUndigestError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())