codesize 1.0.0__py3-none-any.whl

codesize/cli.py

@@ -0,0 +1,169 @@
+# ----------------------------------------------------------------------------------------
+#   cli.py
+#   ------
+#
+#   Command-line interface entry point for codesize. Supports Python, Go,
+#   Rust, and Elixir.
+#
+#   (c) 2026 WaterJuice — Unlicense; see LICENSE in the project root.
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Mar 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import sys
+import traceback
+from pathlib import Path
+from codesize.output import display_stats
+from codesize.scanner import scan_directory
+from codesize.version import VERSION_STR
+from .argbuilder import ArgsParser
+from .argbuilder import Namespace
+
+# ----------------------------------------------------------------------------------------
+#   Constants
+# ----------------------------------------------------------------------------------------
+
+LICENSE_TEXT = """\
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>"""
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+def parse_args(argv: list[str]) -> Namespace:
+    """Parse command-line arguments."""
+    p = ArgsParser(
+        prog="codesize",
+        description=(
+            f"codesize: {VERSION_STR}\n"
+            "(c) 2026 WaterJuice. Unlicense.\n\n"
+            "Analyse code statistics in a directory.\n"
+            "Supports Python, Go, Rust, and Elixir."
+        ),
+        version=f"codesize: {VERSION_STR}\npython: {sys.version.split()[0]}",
+    )
+    p.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="Directory to scan (default: current directory)",
+    )
+    p.add_argument(
+        "--license",
+        action="version",
+        version=LICENSE_TEXT,
+        help="show license and exit",
+    )
+
+    # Output format options (mutually exclusive)
+    format_group = p.add_mutex_group()
+    format_group.add_argument(
+        "--plain",
+        action="store_true",
+        help="Plain text output (no box or colours)",
+    )
+    format_group.add_argument(
+        "--json",
+        action="store_true",
+        help="JSON output",
+    )
+
+    return p.parse(argv)
+
+
+# ----------------------------------------------------------------------------------------
+def main(argv: list[str] | None = None) -> int:
+    """
+    Main entry point for the codesize CLI.
+
+    Parameters:
+        argv: Command line arguments (without program name). If None, uses sys.argv[1:].
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    try:
+        return _main_inner(argv)
+    except KeyboardInterrupt:
+        print()
+        print("---- Manually Terminated ----")
+        print()
+        return 1
+    except SystemExit:
+        raise
+    except BaseException as e:
+        t = "-----------------------------------------------------------------------------\n"
+        t += "UNHANDLED EXCEPTION OCCURRED!!\n"
+        t += "\n"
+        t += traceback.format_exc()
+        t += "\n"
+        t += f"EXCEPTION: {type(e)} {e}\n"
+        t += "-----------------------------------------------------------------------------\n"
+        t += "\n"
+        print(t, file=sys.stderr)
+        return 1
+
+
+# ----------------------------------------------------------------------------------------
+def _main_inner(argv: list[str]) -> int:
+    """Inner main function that does the actual work."""
+    args = parse_args(argv)
+    directory = Path(args.directory).resolve()
+
+    if not directory.exists():
+        print(f"Error: Directory '{directory}' does not exist.", file=sys.stderr)
+        return 1
+
+    if not directory.is_dir():
+        print(f"Error: '{directory}' is not a directory.", file=sys.stderr)
+        return 1
+
+    # Determine output format
+    if args.json:
+        output_format = "json"
+    elif args.plain:
+        output_format = "plain"
+    else:
+        output_format = "box"
+
+    stats = scan_directory(directory)
+    display_stats(stats, directory, output_format)
+    return 0

codesize/output.py

@@ -0,0 +1,281 @@
+# ----------------------------------------------------------------------------------------
+#   output.py
+#   ---------
+#
+#   Output formatting with ASCII box and optional ANSI colour support.
+#   Displays per-language breakdown and totals.
+#
+#   (c) 2026 WaterJuice — Unlicense; see LICENSE in the project root.
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Mar 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import json
+import sys
+from pathlib import Path
+from typing import Literal
+from codesize.scanner import CodeStats
+from codesize.scanner import LangStats
+
+# ----------------------------------------------------------------------------------------
+#   Constants
+# ----------------------------------------------------------------------------------------
+
+# ANSI colour codes
+RESET = "\033[0m"
+BOLD = "\033[1m"
+CYAN = "\033[36m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+MAGENTA = "\033[35m"
+
+# Column colours (Files, Size, Lines, Code)
+COL_COLOURS = (CYAN, GREEN, YELLOW, MAGENTA)
+
+# Box drawing characters
+BOX_TOP_LEFT = "╭"
+BOX_TOP_RIGHT = "╮"
+BOX_BOTTOM_LEFT = "╰"
+BOX_BOTTOM_RIGHT = "╯"
+BOX_HORIZONTAL = "─"
+BOX_VERTICAL = "│"
+BOX_TEE_LEFT = "├"
+BOX_TEE_RIGHT = "┤"
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+def use_colour() -> bool:
+    """Determine if ANSI colour should be used."""
+    return sys.stdout.isatty()
+
+
+# ----------------------------------------------------------------------------------------
+def colour(text: str, *codes: str) -> str:
+    """Apply ANSI colour codes to text if output is a terminal."""
+    if not use_colour():
+        return text
+    return "".join(codes) + text + RESET
+
+
+# ----------------------------------------------------------------------------------------
+def format_size(kb: float) -> str:
+    """Format size with appropriate unit."""
+    if kb >= 1024:
+        return f"{kb / 1024:.2f} MB"
+    return f"{kb:.2f} KB"
+
+
+# ----------------------------------------------------------------------------------------
+def format_number(n: int) -> str:
+    """Format number with thousand separators."""
+    return f"{n:,}"
+
+
+# ----------------------------------------------------------------------------------------
+def display_stats(
+    stats: CodeStats, directory: Path, output_format: Literal["box", "plain", "json"]
+) -> None:
+    """Display statistics in the specified format."""
+    if output_format == "json":
+        display_json(stats, directory)
+    elif output_format == "plain":
+        display_plain(stats, directory)
+    else:
+        display_box(stats, directory)
+
+
+# ----------------------------------------------------------------------------------------
+def _lang_to_dict(lang: LangStats) -> dict[str, int | float]:
+    """Convert language stats to a dictionary for JSON output."""
+    return {
+        "files": lang.num_files,
+        "total_bytes": lang.total_bytes,
+        "total_kb": round(lang.total_kb, 2),
+        "total_lines": lang.total_lines,
+        "code_lines": lang.code_lines,
+    }
+
+
+# ----------------------------------------------------------------------------------------
+def display_json(stats: CodeStats, directory: Path) -> None:
+    """Display statistics as JSON."""
+    data: dict[str, object] = {
+        "directory": directory.name,
+        "languages": {lang.name: _lang_to_dict(lang) for lang in stats.languages},
+    }
+    if len(stats.languages) > 1:
+        data["total"] = _lang_to_dict(stats.total)
+    print(json.dumps(data, indent=2))
+
+
+# ----------------------------------------------------------------------------------------
+def display_plain(stats: CodeStats, directory: Path) -> None:
+    """Display statistics as plain text."""
+    print(f"Code Stats: {directory.name}")
+    if not stats.languages:
+        print("No supported code files found.")
+        return
+    for lang in stats.languages:
+        print(
+            f"{lang.name}: {format_number(lang.num_files)} files, "
+            f"{format_size(lang.total_kb)}, "
+            f"{format_number(lang.total_lines)} lines, "
+            f"{format_number(lang.code_lines)} code lines"
+        )
+    if len(stats.languages) > 1:
+        total = stats.total
+        print(
+            f"Total: {format_number(total.num_files)} files, "
+            f"{format_size(total.total_kb)}, "
+            f"{format_number(total.total_lines)} lines, "
+            f"{format_number(total.code_lines)} code lines"
+        )
+
+
+# ----------------------------------------------------------------------------------------
+def display_box(stats: CodeStats, directory: Path) -> None:
+    """Display statistics in a formatted ASCII box with per-language breakdown."""
+    if not stats.languages:
+        print()
+        print("No supported code files found.")
+        print()
+        return
+
+    title = f" Code Stats: {directory.name} "
+    show_total = len(stats.languages) > 1
+
+    # Build data rows: (label, files, size, lines, code)
+    headers = ("", "Files", "Size", "Lines", "Code")
+    rows: list[tuple[str, ...]] = []
+    for lang in stats.languages:
+        rows.append(
+            (
+                lang.name,
+                format_number(lang.num_files),
+                format_size(lang.total_kb),
+                format_number(lang.total_lines),
+                format_number(lang.code_lines),
+            )
+        )
+
+    total = stats.total
+    total_row = (
+        "Total",
+        format_number(total.num_files),
+        format_size(total.total_kb),
+        format_number(total.total_lines),
+        format_number(total.code_lines),
+    )
+
+    all_rows = list(rows)
+    if show_total:
+        all_rows.append(total_row)
+
+    # Calculate column widths
+    num_cols = len(headers)
+    col_widths: list[int] = []
+    for i in range(num_cols):
+        w = len(headers[i])
+        for r in all_rows:
+            w = max(w, len(r[i]))
+        col_widths.append(w)
+
+    # Format a content line (plain text, no borders or colours)
+    def make_line(row: tuple[str, ...]) -> str:
+        parts = [f"  {row[0].ljust(col_widths[0])}"]
+        for i in range(1, num_cols):
+            parts.append(f"  {row[i].rjust(col_widths[i])}")
+        parts.append("  ")
+        return "".join(parts)
+
+    # Calculate inner width (between vertical bars)
+    all_lines = [make_line(r) for r in all_rows] + [make_line(headers)]
+    inner_width = max(len(title), max(len(s) for s in all_lines))
+
+    # Box parts
+    top_border = BOX_TOP_LEFT + BOX_HORIZONTAL * inner_width + BOX_TOP_RIGHT
+    bottom_border = BOX_BOTTOM_LEFT + BOX_HORIZONTAL * inner_width + BOX_BOTTOM_RIGHT
+    separator = BOX_TEE_LEFT + BOX_HORIZONTAL * inner_width + BOX_TEE_RIGHT
+
+    # Print header
+    print()
+    print(colour(top_border, BOLD))
+
+    # Title line
+    title_padded = title.center(inner_width)
+    print(
+        colour(BOX_VERTICAL, BOLD)
+        + colour(title_padded, BOLD, CYAN)
+        + colour(BOX_VERTICAL, BOLD)
+    )
+
+    # Separator
+    print(colour(separator, BOLD))
+
+    # Header row
+    header_line = make_line(headers).ljust(inner_width)
+    if use_colour():
+        print(
+            colour(BOX_VERTICAL, BOLD)
+            + colour(header_line, BOLD)
+            + colour(BOX_VERTICAL, BOLD)
+        )
+    else:
+        print(BOX_VERTICAL + header_line + BOX_VERTICAL)
+
+    # Data rows (language rows + optional total)
+    def print_data_row(row: tuple[str, ...], bold_label: bool = False) -> None:
+        plain = make_line(row)
+        padded = plain.ljust(inner_width)
+        if use_colour():
+            # Label column
+            label = row[0].ljust(col_widths[0])
+            if bold_label:
+                label = colour(label, BOLD)
+            # Value columns — each gets its own colour
+            values = ""
+            for i in range(1, num_cols):
+                col_colour = COL_COLOURS[(i - 1) % len(COL_COLOURS)]
+                values += "  " + colour(row[i].rjust(col_widths[i]), BOLD, col_colour)
+            values += "  "
+            # Trailing padding to match inner_width
+            visible_len = (
+                2
+                + col_widths[0]
+                + sum(2 + col_widths[i] for i in range(1, num_cols))
+                + 2
+            )
+            padding = " " * max(0, inner_width - visible_len)
+            print(
+                colour(BOX_VERTICAL, BOLD)
+                + f"  {label}{values}{padding}"
+                + colour(BOX_VERTICAL, BOLD)
+            )
+        else:
+            print(BOX_VERTICAL + padded + BOX_VERTICAL)
+
+    for row in rows:
+        print_data_row(row)
+
+    # Total row (only if multiple languages)
+    if show_total:
+        print(colour(separator, BOLD))
+        print_data_row(total_row, bold_label=True)
+
+    # Footer
+    print(colour(bottom_border, BOLD))
+    print()

codesize/scanner.py

@@ -0,0 +1,237 @@
+# ----------------------------------------------------------------------------------------
+#   scanner.py
+#   ----------
+#
+#   Scans directories for code files and collects statistics.
+#   Supports Python, Go, Rust, and Elixir.
+#
+#   (c) 2026 WaterJuice — Unlicense; see LICENSE in the project root.
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Mar 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import os
+from dataclasses import dataclass
+from dataclasses import field
+from pathlib import Path
+
+# ----------------------------------------------------------------------------------------
+#   Language Definitions
+# ----------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Language:
+    """Configuration for a supported programming language."""
+
+    name: str
+    extensions: tuple[str, ...]
+    line_comment: str
+    block_comment_start: str | None = None
+    block_comment_end: str | None = None
+    docstring_markers: tuple[str, ...] = ()
+
+
+LANGUAGES: tuple[Language, ...] = (
+    Language("Python", (".py",), "#", docstring_markers=('"""', "'''")),
+    Language("Go", (".go",), "//", block_comment_start="/*", block_comment_end="*/"),
+    Language("Rust", (".rs",), "//", block_comment_start="/*", block_comment_end="*/"),
+    Language("Elixir", (".ex", ".exs"), "#", docstring_markers=('"""',)),
+)
+
+# ----------------------------------------------------------------------------------------
+#   Data Classes
+# ----------------------------------------------------------------------------------------
+
+
+@dataclass
+class LangStats:
+    """Statistics for files of a single language."""
+
+    name: str
+    num_files: int = 0
+    total_bytes: int = 0
+    total_lines: int = 0
+    code_lines: int = 0
+
+    @property
+    def total_kb(self) -> float:
+        """Return total size in kilobytes."""
+        return self.total_bytes / 1024
+
+
+@dataclass
+class CodeStats:
+    """Statistics for all code files in a directory."""
+
+    languages: list[LangStats] = field(default_factory=lambda: list[LangStats]())
+
+    @property
+    def total(self) -> LangStats:
+        """Return combined statistics across all languages."""
+        return LangStats(
+            name="Total",
+            num_files=sum(lang.num_files for lang in self.languages),
+            total_bytes=sum(lang.total_bytes for lang in self.languages),
+            total_lines=sum(lang.total_lines for lang in self.languages),
+            code_lines=sum(lang.code_lines for lang in self.languages),
+        )
+
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+def _is_code_line(stripped: str, comment_prefix: str) -> bool:
+    """Determine if a line is a code line (not blank or decorative comment)."""
+    if not stripped:
+        return False
+    if stripped.startswith(comment_prefix):
+        # Count comments with meaningful content, but not bare markers or separator lines
+        comment_body = stripped[len(comment_prefix) :]
+        return any(ch.isalnum() for ch in comment_body)
+    return True
+
+
+# ----------------------------------------------------------------------------------------
+def count_lines(filepath: Path, lang: Language) -> tuple[int, int]:
+    """
+    Count total lines and code lines in a file.
+
+    Handles single-line comments, block comments, and docstrings/heredocs
+    according to the language configuration.
+
+    Returns:
+        Tuple of (total_lines, code_lines).
+    """
+    total_lines = 0
+    code_lines = 0
+    in_block_comment = False
+    block_end: str | None = None
+    in_docstring = False
+    docstring_marker: str | None = None
+
+    try:
+        content = filepath.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return 0, 0
+
+    for line in content.splitlines():
+        total_lines += 1
+        stripped = line.strip()
+
+        # Inside a block comment (/* ... */)
+        if in_block_comment:
+            if block_end and block_end in stripped:
+                in_block_comment = False
+                block_end = None
+            continue
+
+        # Inside a docstring/heredoc
+        if in_docstring:
+            if docstring_marker and docstring_marker in stripped:
+                in_docstring = False
+                docstring_marker = None
+            continue
+
+        # Check for start of block comment
+        if lang.block_comment_start and stripped.startswith(lang.block_comment_start):
+            rest = stripped[len(lang.block_comment_start) :]
+            if lang.block_comment_end and lang.block_comment_end not in rest:
+                in_block_comment = True
+                block_end = lang.block_comment_end
+            continue
+
+        # Check for docstring/heredoc markers (Python: starts with """, Elixir: ends with """)
+        found_marker = False
+        for marker in lang.docstring_markers:
+            starts = stripped.startswith(marker)
+            ends = stripped.endswith(marker)
+            if starts or ends:
+                if starts:
+                    rest = stripped[len(marker) :]
+                else:
+                    rest = stripped[: -len(marker)]
+                if marker not in rest:
+                    in_docstring = True
+                    docstring_marker = marker
+                found_marker = True
+                break
+        if found_marker:
+            continue
+
+        if _is_code_line(stripped, lang.line_comment):
+            code_lines += 1
+
+    return total_lines, code_lines
+
+
+# ----------------------------------------------------------------------------------------
+def scan_directory(directory: Path) -> CodeStats:
+    """
+    Scan a directory recursively for code files and collect statistics.
+
+    Uses os.walk with hidden-directory pruning for fast traversal. Skips
+    directories starting with a dot (e.g. .venv, .git). Only includes
+    languages that have at least one file.
+
+    Args:
+        directory: The directory to scan.
+
+    Returns:
+        CodeStats object containing per-language and total statistics.
+    """
+    # Build extension lookup
+    extension_map: dict[str, Language] = {}
+    for lang in LANGUAGES:
+        for ext in lang.extensions:
+            extension_map[ext] = lang
+
+    # Walk once, pruning hidden dirs, collecting and processing files
+    lang_stats: dict[str, LangStats] = {}
+
+    for dirpath, dirnames, filenames in os.walk(directory):
+        # Prune hidden directories in-place so os.walk doesn't descend into them
+        dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+
+        for filename in filenames:
+            ext = os.path.splitext(filename)[1]
+            lang = extension_map.get(ext)
+            if lang is None:
+                continue
+
+            filepath = Path(dirpath, filename)
+
+            if lang.name not in lang_stats:
+                lang_stats[lang.name] = LangStats(name=lang.name)
+            stats = lang_stats[lang.name]
+            stats.num_files += 1
+
+            try:
+                stats.total_bytes += filepath.stat().st_size
+            except OSError:
+                pass
+
+            lines, code = count_lines(filepath, lang)
+            stats.total_lines += lines
+            stats.code_lines += code
+
+    # Preserve language ordering from LANGUAGES
+    languages: list[LangStats] = []
+    for lang in LANGUAGES:
+        if lang.name in lang_stats:
+            languages.append(lang_stats[lang.name])
+
+    return CodeStats(languages=languages)