topmark 0.1.0__py3-none-any.whl

topmark/__init__.py

@@ -0,0 +1,14 @@
+# topmark:header:start
+#
+#   file         : __init__.py
+#   file_relpath : src/topmark/__init__.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark package.
+
+Provides tools and utilities for evaluating and benchmarking models and algorithms.
+"""

topmark/cli/__init__.py

@@ -0,0 +1,23 @@
+# topmark:header:start
+#
+#   file         : __init__.py
+#   file_relpath : src/topmark/cli/__init__.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark CLI package.
+
+This package groups all Click command definitions and supporting utilities
+for the TopMark command-line interface.
+
+Typical usage:
+    The console script entry point is defined in ``pyproject.toml`` as::
+
+        [project.scripts]
+        topmark = "topmark.cli.main:cli"
+
+All subcommands live in :mod:`topmark.cli.commands`.
+"""

topmark/cli/cli_types.py

@@ -0,0 +1,299 @@
+# topmark:header:start
+#
+#   file         : cli_types.py
+#   file_relpath : src/topmark/cli/cli_types.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""Shared CLI parameter types and argument parsing helpers for TopMark.
+
+This module serves as the central container for shared CLI argument types, validators,
+and helpers in TopMark. It defines the ArgsNamespace TypedDict for consistent
+argument passing throughout the CLI, as well as reusable validator functions and
+custom Click parameter types for argument parsing (such as file paths and globs).
+These utilities ensure robust and uniform handling of CLI parameters
+across all TopMark commands and subcommands.
+"""
+
+import glob
+import logging
+from enum import Enum
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Iterable,
+    NoReturn,
+    Protocol,
+    TypedDict,
+    TypeVar,
+    cast,
+)
+
+import click
+
+from topmark.rendering.formats import HeaderOutputFormat
+
+if TYPE_CHECKING:
+    # Type-only import so we can reference the symbol in annotations
+    from click.shell_completion import CompletionItem as ClickCompletionItem
+
+    class ParamTypeBase(Protocol):
+        """Typed base to avoid subclassing Any when Click lacks stubs."""
+
+        name: str
+
+else:
+    # At runtime, subclass the real Click type
+    ParamTypeBase = click.ParamType  # type: ignore[assignment]
+
+# Type variable bounded to Enum for generic EnumParam
+E = TypeVar("E", bound=Enum)
+
+
+class ArgsNamespace(TypedDict, total=False):
+    """Namespace for parsed CLI arguments and options in TopMark.
+
+    This TypedDict is used to represent all relevant CLI arguments and options
+    passed through TopMark commands and subcommands. It facilitates type-safe
+    access and transfer of parsed CLI state, including global options, config
+    file overrides, file selection, filtering, and formatting flags.
+
+    Attributes:
+        log_level: Verbosity level for logging.
+        no_config: Whether to ignore local config files.
+        config_files: List of extra config file paths.
+        files: List of file paths to process.
+        stdin: Whether to read file paths from stdin.
+        include_patterns: Glob patterns of files to include.
+        include_from: Files containing include patterns.
+        exclude_patterns: Glob patterns of files to exclude.
+        exclude_from: Files containing exclude patterns.
+        file_types: Restrict to given file types.
+        relative_to: Root directory for relative paths.
+        align_fields: Align header fields with colons.
+        header_format: Header output format (file type aware, plain, or json).
+    """
+
+    # Global options: retrieve from ctx.obj
+    log_level: int
+
+    # TopMark Command
+    # command: TopMarkCommand
+
+    # Command options: config
+    no_config: bool | None
+    config_files: list[str] | None
+
+    # Command arguments
+    files: list[str]
+
+    # Command options: common_file_and_filtering_options
+    stdin: bool | None
+    include_patterns: list[str] | None
+    include_from: list[str] | None
+    exclude_patterns: list[str] | None
+    exclude_from: list[str] | None
+    file_types: list[str] | None
+    relative_to: str | None
+
+    # Command options: formatting
+    align_fields: bool | None
+    header_format: HeaderOutputFormat | None
+
+
+def build_args_namespace(
+    *,
+    log_level: int = logging.WARNING,
+    # command: TopMarkCommand = TopMarkCommand.NONE,
+    no_config: bool | None = None,
+    config_files: list[str] | None = None,
+    files: list[str] | None = None,
+    stdin: bool | None = None,
+    include_patterns: list[str] | None = None,
+    include_from: list[str] | None = None,
+    exclude_patterns: list[str] | None = None,
+    exclude_from: list[str] | None = None,
+    file_types: list[str] | None = None,
+    relative_to: str | None = None,
+    align_fields: bool | None = None,
+    header_format: HeaderOutputFormat | None = None,
+) -> ArgsNamespace:
+    """Build an ArgsNamespace dictionary for CLI argument passing.
+
+    Args:
+        log_level: Verbosity level for logging.
+        no_config: Whether to ignore local config files.
+        config_files: List of extra config file paths.
+        files: List of file paths to process.
+        stdin: Whether to read file paths from stdin.
+        include_patterns: Glob patterns of files to include.
+        include_from: Files containing include patterns.
+        exclude_patterns: Glob patterns of files to exclude.
+        exclude_from: Files containing exclude patterns.
+        file_types: Restrict to given file types.
+        relative_to: Root directory for relative paths.
+        align_fields: Align header fields with colons.
+        header_format: Header output format (native, plain, or json).
+
+    Returns:
+        Dictionary of CLI argument values for use throughout the CLI.
+    """
+    return {
+        "log_level": log_level,
+        # "command": command,
+        "no_config": no_config,
+        "config_files": config_files,
+        "files": files if files is not None else [],
+        "stdin": stdin,
+        "include_patterns": include_patterns,
+        "include_from": include_from,
+        "exclude_patterns": exclude_patterns,
+        "exclude_from": exclude_from,
+        "file_types": file_types,
+        "relative_to": relative_to,
+        "align_fields": align_fields,
+        "header_format": header_format,
+    }
+
+
+# --- Example custom Click parameter types and validators for TopMark CLI ---
+
+# HeaderFormatParam: Click callback for validating header format option
+
+
+class EnumParam(ParamTypeBase, Generic[E]):
+    """A Click parameter type that converts a string to a member of a given Enum."""
+
+    # Add instance variable annotations for maximum clarity
+    enum_cls: type[E]
+    name: str
+    choices: list[str]
+
+    def __init__(self, enum_cls: type[E]):
+        """Initialize the EnumParam instance."""
+        self.enum_cls = enum_cls
+        self.name = self.enum_cls.__name__.lower()
+        # Assume the enum exposes string-valued members (e.g., HeaderOutputFormat)
+        self.choices = [cast(str, getattr(e, "value", str(e))) for e in self.enum_cls]
+
+    def _fail_noreturn(
+        self,
+        message: str,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> NoReturn:
+        """Raise a BadParameter with a NoReturn signature (clear to type checkers)."""
+        raise click.BadParameter(message, param=param, ctx=ctx)
+
+    def convert(
+        self,
+        value: str | None,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> E | None:
+        """Converts a string to a member of the Enum."""
+        if value is None:
+            return None
+
+        # Case-insensitive lookup by the enum's string value
+        lookup: dict[str, E] = {
+            cast(str, getattr(choice, "value", str(choice))).lower(): choice
+            for choice in cast(Iterable[E], self.enum_cls)
+        }
+
+        key = value.lower()
+        if key in lookup:
+            return lookup[key]
+
+        # Raise a BadParameter exception for invalid input
+        self._fail_noreturn(
+            f"Invalid value '{value}'. Must be one of: {', '.join(self.choices)}",
+            param,
+            ctx,
+        )
+
+    def shell_complete(
+        self,
+        ctx: click.Context,  # pylint: disable=unused-argument
+        param: click.Parameter,  # pylint: disable=unused-argument
+        incomplete: str,
+    ) -> list["ClickCompletionItem"]:
+        """Tab completion for Click.
+
+        Bash: `eval "$(_TOPMARK_COMPLETE=bash_source topmark)"`
+        Zsh: `eval "$(_TOPMARK_COMPLETE=zsh_source topmark)"`
+        """
+        # Runtime import to avoid import-time dependency for non-completion paths
+        from click.shell_completion import (
+            CompletionItem as RuntimeCompletionItem,
+        )  # Click 8.x
+
+        prefix = (incomplete or "").lower()
+        items: list["ClickCompletionItem"] = []
+        for e in cast(Iterable[E], self.enum_cls):
+            val = str(getattr(e, "value", e))
+            if val.lower().startswith(prefix):
+                items.append(RuntimeCompletionItem(val))
+        return items
+
+    def __repr__(self) -> str:
+        """Return a string representation."""
+        return f"EnumParam({self.enum_cls.__name__})"
+
+
+def FileTypeParam(
+    ctx: click.Context,  # pylint: disable=unused-argument
+    param: click.Parameter,  # pylint: disable=unused-argument
+    value: Any,
+) -> Path | None:
+    """Validator: Ensure a CLI argument is a valid file path.
+
+    Validates and converts the CLI argument to a Path, raising an error if it does not exist
+    or is not a file.
+
+    Args:
+        ctx: Click context.
+        param: The Click parameter.
+        value: The CLI argument value to validate.
+
+    Returns:
+        The validated file path, or None if value is None.
+
+    Raises:
+        click.BadParameter: If the file does not exist or is not a file.
+    """
+    if value is None:
+        return None
+    path = Path(value)
+    # Check if the path exists and is a file.
+    if not path.exists() or not path.is_file():
+        raise click.BadParameter(f"File not found or not a file: {value}")
+    return path
+
+
+def GlobParam(
+    ctx: click.Context,  # pylint: disable=unused-argument
+    param: click.Parameter,  # pylint: disable=unused-argument
+    value: Any,
+) -> list[Path]:
+    """Validator: Expand a glob pattern CLI argument to a list of file paths.
+
+    Expands the given glob pattern string into a list of Path objects matching the pattern.
+
+    Args:
+        ctx: Click context.
+        param: The Click parameter.
+        value: The glob pattern string.
+
+    Returns:
+        List of Path objects matching the glob pattern, or an empty list if value is None.
+    """
+    if value is None:
+        return []
+    # Use glob.glob for shell-style wildcards; return as Path objects.
+    return [Path(p) for p in glob.glob(value, recursive=True)]

topmark/cli/commands/__init__.py

@@ -0,0 +1,11 @@
+# topmark:header:start
+#
+#   file         : __init__.py
+#   file_relpath : src/topmark/cli/commands/__init__.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark CLI commands."""

topmark/cli/commands/default.py

@@ -0,0 +1,295 @@
+# topmark:header:start
+#
+#   file         : default.py
+#   file_relpath : src/topmark/cli/commands/default.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""Default TopMark operation (check/apply).
+
+This module implements the unified default behavior of TopMark’s CLI. It is
+invoked when no explicit subcommand is provided and processes the file paths
+captured by Click (``ctx.args``), performing a dry‑run **check** by default or
+**applying** changes when ``--apply`` is given.
+
+Examples:
+  Check files and print a human summary::
+
+    topmark --summary src
+
+  Emit per‑file objects in NDJSON (one per line)::
+
+    topmark --format=ndjson src pkg
+
+  Write changes and show diffs (human output only)::
+
+    topmark --apply --diff .
+"""
+
+import click
+from yachalk import chalk
+
+from topmark.cli.cli_types import EnumParam
+from topmark.cli.config_resolver import resolve_config_from_click
+from topmark.cli.options import (
+    common_config_options,
+    common_file_and_filtering_options,
+    common_header_formatting_options,
+    typed_option,
+    underscored_trap_option,
+)
+from topmark.cli.utils import (
+    OutputFormat,
+    count_by_outcome,
+)
+from topmark.config.logging import get_logger
+from topmark.file_resolver import resolve_file_list
+from topmark.pipeline import runner
+from topmark.pipeline.context import ComparisonStatus, ProcessingContext
+from topmark.pipeline.pipelines import get_pipeline
+from topmark.rendering.formats import HeaderOutputFormat
+
+logger = get_logger(__name__)
+
+
+@common_config_options
+@common_file_and_filtering_options
+@common_header_formatting_options
+@typed_option(
+    "--apply", "apply_changes", is_flag=True, help="Write changes to files (off by default)."
+)
+@typed_option("--diff", is_flag=True, help="Show unified diffs (human output only).")
+@typed_option(
+    "--summary",
+    "summary_mode",
+    is_flag=True,
+    help="Show outcome counts instead of per-file details.",
+)
+@typed_option(
+    "--skip-compliant",
+    "skip_compliant",
+    is_flag=True,
+    help="Hide files that are already up-to-date.",
+)
+@underscored_trap_option("--skip_compliant")
+@typed_option(
+    "--format",
+    "output_format",
+    type=EnumParam(OutputFormat),
+    default=None,
+    help=f"Output format ({', '.join(v.value for v in OutputFormat)}).",
+)
+def default_command(
+    stdin: bool,
+    include_patterns: list[str],
+    include_from: list[str],
+    exclude_patterns: list[str],
+    exclude_from: list[str],
+    no_config: bool,
+    config_paths: list[str],
+    file_types: list[str],
+    relative_to: str | None,
+    align_fields: bool,
+    header_format: HeaderOutputFormat | None,
+    apply_changes: bool,
+    diff: bool,
+    summary_mode: bool,
+    skip_compliant: bool,
+    output_format: OutputFormat | None,
+) -> None:
+    """Run the unified default command (check/apply).
+
+    When invoked via the root group, this command receives options parsed at the
+    group level and reads positional paths from ``click.get_current_context().args``.
+
+    Args:
+      stdin: If True, read file paths from standard input (one per line).
+      include_patterns: Glob patterns specifying additional files or directories to include.
+      include_from: Paths to files that contain include glob patterns (one per line).
+      exclude_patterns: Glob patterns specifying files or directories to exclude.
+      exclude_from: Paths to files that contain exclude glob patterns (one per line).
+      no_config: If True, ignore user/project configuration files and use defaults only.
+      config_paths: Additional configuration file paths to load and merge.
+      file_types: Restrict processing to the given TopMark file type identifiers.
+      relative_to: Base directory used to compute relative paths in outputs.
+      align_fields: If True, align header fields by the colon for readability.
+      header_format: Optional override for the header output format used when rendering.
+      apply_changes: If True, write changes to files; otherwise perform a dry run.
+      diff: If True, show unified diffs of header changes (human output only).
+      summary_mode: If True, print outcome counts instead of per-file details.
+      skip_compliant: If True, suppress files whose comparison status is UNCHANGED.
+      output_format: Output format to use (default, json, or ndjson).
+
+    Raises:
+      click.UsageError: If no input is provided (Black‑style preflight).
+      SystemExit: With code 2 in check mode when changes would be required.
+
+    Returns:
+      None
+
+    Examples:
+      Dry‑run (default)::
+
+        topmark src
+
+      Apply changes::
+
+        topmark --apply src
+
+      NDJSON per‑file output::
+
+        topmark --format=ndjson src
+    """
+    ctx = click.get_current_context()
+    files = list(ctx.args)
+
+    # Before resolving config/files — block empty invocations (Black-style)
+    no_inputs = (
+        not files and not stdin and not include_patterns and not include_from and not config_paths
+    )
+    if no_inputs:
+        # Show a friendly usage error with guidance
+        raise click.UsageError(
+            "No input specified. Provide one or more paths, or use --stdin. "
+            "See --help for examples.",
+            ctx=ctx,
+        )
+
+    # === Primary TopMark operation (default: check, write with --apply) ===
+    config = resolve_config_from_click(
+        ctx=ctx,
+        files=list(files),
+        stdin=stdin,
+        include_patterns=list(include_patterns),
+        include_from=list(include_from),
+        exclude_patterns=list(exclude_patterns),
+        exclude_from=list(exclude_from),
+        file_types=list(file_types),
+        relative_to=relative_to,
+        no_config=no_config,
+        config_paths=list(config_paths),
+        align_fields=align_fields,
+        header_format=header_format,
+    )
+
+    logger.trace("Config after merging args: %s", config)
+
+    # file_list = resolve_file_list(config)
+    # Use Click's text stream for stdin so CliRunner/invoke input is read reliably
+    stdin_stream = click.get_text_stream("stdin") if stdin else None
+    file_list = resolve_file_list(config, stdin_stream=stdin_stream)
+    if not file_list:
+        click.echo(chalk.blue("\nNo files.\n"))
+        raise SystemExit(0)
+
+    click.echo(chalk.blue(f"\nProcessing {len(file_list)} file(s):\n"))
+    click.echo(chalk.bold.underline("TopMark Results:"))
+
+    # Use summary pipeline when --summary is set, else full (compare+update+patch)
+    pipeline_name = "summary" if summary_mode else "apply"
+    steps = get_pipeline(pipeline_name)
+
+    results: list[ProcessingContext] = []
+    for path in file_list:
+        try:
+            ctx_obj: ProcessingContext = ProcessingContext.bootstrap(path=path, config=config)
+            ctx_obj = runner.run(ctx_obj, steps)
+            results.append(ctx_obj)
+        except (FileNotFoundError, PermissionError, IsADirectoryError) as e:
+            logger.error("Filesystem error while processing %s: %s", path, e)
+            click.echo(chalk.red(f"Filesystem error processing {path}: {e}"))
+            continue
+        except UnicodeDecodeError as e:
+            logger.error("Encoding error while reading %s: %s", path, e)
+            click.echo(chalk.red(f"Encoding error in {path}: {e}"))
+            continue
+        except Exception as e:  # pragma: no cover - unexpected path
+            logger.exception("Unexpected error processing %s", path)
+            click.echo(
+                chalk.red(f"Unexpected error processing {path}: {e} (use -vv for traceback)")
+            )
+            continue
+
+    # Optional filtering
+    if skip_compliant:
+        view_results = [r for r in results if r.status.comparison is not ComparisonStatus.UNCHANGED]
+    else:
+        view_results = results
+
+    fmt: OutputFormat = output_format or OutputFormat.DEFAULT
+    # Machine formats first
+    if fmt is OutputFormat.NDJSON:
+        import json as _json
+
+        if summary_mode:
+            counts = count_by_outcome(view_results)
+            for key, (n, label, _color) in counts.items():
+                click.echo(_json.dumps({"key": key, "count": n, "label": label}))
+        else:
+            for r in view_results:
+                click.echo(_json.dumps(r.to_dict()))
+    elif fmt is OutputFormat.JSON:
+        import json as _json
+
+        if summary_mode:
+            counts = count_by_outcome(view_results)
+            data = {k: {"count": n, "label": label} for k, (n, label, _color) in counts.items()}
+            click.echo(_json.dumps(data, indent=2))
+        else:
+            payload = [r.to_dict() for r in view_results]
+            click.echo(_json.dumps(payload, indent=2))
+    else:
+        # Human output
+        if summary_mode:
+            click.echo()
+            click.echo(chalk.bold.underline("Summary by outcome:"))
+
+            counts = count_by_outcome(view_results)
+            label_width = max((len(v[1]) for v in counts.values()), default=0) + 1
+            num_width = len(str(len(file_list)))
+            for _key, (n, label, color) in counts.items():
+                click.echo(color(f"  {label:<{label_width}}: {n:>{num_width}}"))
+
+        else:
+            for r in view_results:
+                click.echo(r.summary)
+            if diff:
+                for r in view_results:
+                    if r.header_diff:
+                        click.echo(r.header_diff)
+
+    # Writes (only when --apply is set)
+    if apply_changes:
+        written = 0
+        failed = 0
+        from pathlib import Path
+
+        for r in results:
+            try:
+                if r.updated_file_lines is not None and r.file_lines != r.updated_file_lines:
+                    Path(str(r.path)).write_text("".join(r.updated_file_lines), encoding="utf-8")
+                    written += 1
+            except Exception as e:  # pragma: no cover
+                failed += 1
+                logger.error("Failed to write %s: %s", r.path, e)
+        if fmt is OutputFormat.DEFAULT:
+            click.echo(
+                f"\nApplied changes to {written} file(s)." if written else "\nNo changes to apply."
+            )
+        if failed:
+            raise SystemExit(1)
+
+    # Exit code policy: in check mode, non-zero if changes would be needed
+    if not apply_changes:
+        would_change = any(
+            (r.status.header.name == "MISSING") or (r.status.comparison.name == "CHANGED")
+            for r in results
+        )
+        if would_change:
+            raise SystemExit(2)
+
+    click.echo("All done!")
+    return