topmark 0.1.0__py3-none-any.whl

topmark/cli/commands/dump_config.py

@@ -0,0 +1,108 @@
+# topmark:header:start
+#
+#   file         : dump_config.py
+#   file_relpath : src/topmark/cli/commands/dump_config.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark `dump-config` command.
+
+Emits the effective TopMark configuration as TOML after applying defaults,
+project/user config files, and any CLI overrides. The output is wrapped
+between `# === BEGIN ===` and `# === END ===` markers for easy parsing in
+tests or tooling.
+"""
+
+import click
+from yachalk import chalk
+
+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_argument,
+)
+from topmark.rendering.formats import HeaderOutputFormat
+
+
+@typed_argument("files", nargs=-1)
+@common_config_options
+@common_file_and_filtering_options
+@common_header_formatting_options
+def dump_config_command(
+    # Command arguments
+    files: list[str],
+    # Command options: common_file_filtering_options
+    stdin: bool,
+    include_patterns: list[str],
+    include_from: list[str],
+    exclude_patterns: list[str],
+    exclude_from: list[str],
+    file_types: list[str],
+    relative_to: str | None,
+    # Command options: config
+    no_config: bool,
+    config_paths: list[str],
+    # Command options: formatting
+    align_fields: bool,
+    header_format: HeaderOutputFormat | None,
+) -> None:
+    """Dump the final merged configuration as TOML.
+
+    Builds the effective configuration from defaults, discovered/explicit
+    config files, and CLI overrides, then prints it as TOML surrounded by
+    BEGIN/END markers. This is useful for debugging or for external tools
+    that need to consume the resolved configuration.
+
+    Args:
+        files: Positional file or directory paths used to influence config
+            discovery or resolution (may be empty).
+        stdin: If True, read newline‑separated paths from standard input
+            when resolving files (may affect config discovery).
+        include_patterns: Additional include glob patterns to consider.
+        include_from: Paths to files containing include patterns (one per line).
+        exclude_patterns: Glob patterns to exclude from consideration.
+        exclude_from: Paths to files containing exclude patterns (one per line).
+        file_types: Explicit file‑type filters to restrict processing.
+        relative_to: Optional base directory for resolving relative paths.
+        no_config: If True, skip loading project/user configuration files.
+        config_paths: Additional TOML config files to merge into the effective config.
+        align_fields: Whether to align header fields when rendering (captured in config).
+        header_format: Optional output format override for header rendering (captured in config).
+
+    Returns:
+        None. Prints the merged configuration as TOML to stdout.
+    """
+    ctx = click.get_current_context()
+    ctx.ensure_object(dict)
+
+    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,
+    )
+
+    import toml
+
+    merged_config = toml.dumps(config.to_toml_dict())
+    click.echo(chalk.bold.underline("TopMark Config Dump:"))
+    click.echo(
+        chalk.dim(
+            f"# Merged TopMark config (TOML):\n\n# === BEGIN ===\n{merged_config}# === END ==="
+        )
+    )
+    return

topmark/cli/commands/filetypes.py

@@ -0,0 +1,39 @@
+# topmark:header:start
+#
+#   file         : filetypes.py
+#   file_relpath : src/topmark/cli/commands/filetypes.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark `filetypes` command.
+
+Lists all file types supported by TopMark along with their identifiers and
+descriptions. Useful for discovering available file type filters when
+configuring headers.
+"""
+
+import click
+from yachalk import chalk
+
+from topmark.filetypes.instances import get_file_type_registry
+
+
+def filetypes_command() -> None:
+    """List supported file types.
+
+    Prints all file types supported by TopMark, including their identifiers and descriptions.
+    Useful for reference when configuring file type filters.
+
+    Returns:
+        None. Prints output to stdout.
+    """
+    click.echo(chalk.bold.underline("Supported file types:"))
+
+    file_types = get_file_type_registry()
+    for key, value in sorted(file_types.items()):
+        # key is file type identifier (name)
+        # value contains the file type fields (e.g., description)
+        click.echo(f"  - {key:<12} {chalk.dim(value.description)}")

topmark/cli/commands/init_config.py

@@ -0,0 +1,60 @@
+# topmark:header:start
+#
+#   file         : init_config.py
+#   file_relpath : src/topmark/cli/commands/init_config.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark `init-config` command.
+
+Prints an initial TopMark configuration file to stdout. The output includes a
+generated header block and the default TOML configuration. Intended as a
+starting point for customizing a project's configuration.
+"""
+
+import click
+from yachalk import chalk
+
+from topmark.cli.utils import default_header_overrides
+from topmark.config import Config
+from topmark.constants import PYPROJECT_TOML_PATH
+from topmark.rendering.api import render_header_for_path
+
+
+def init_config_command() -> None:
+    """Print a starter config file to stdout.
+
+    Outputs an initial TopMark configuration file with default values and a header.
+    Intended as a starting point for customization in your own project.
+
+    Returns:
+        None. Prints output to stdout.
+    """
+    # TODO: use topmark to generate this header
+    click.echo(chalk.bold.underline("Initial TopMark Configuration:"))
+
+    header_overrides = default_header_overrides(
+        info="Initial TopMark configuration -- adjust according to your needs",
+        file_label="topmark.toml",
+    )
+
+    topmark_header = render_header_for_path(
+        config=Config.from_defaults(),
+        path=PYPROJECT_TOML_PATH,
+        header_fields_overrides=["file", "version", "info", "license", "copyright"],
+        header_overrides=header_overrides,
+    )
+
+    click.echo(
+        chalk.gray(
+            f"""\
+{topmark_header}
+
+{Config.get_default_config_toml()}
+## === END of TopMark Configuration ===
+"""
+        )
+    )

topmark/cli/commands/show_defaults.py

@@ -0,0 +1,54 @@
+# topmark:header:start
+#
+#   file         : show_defaults.py
+#   file_relpath : src/topmark/cli/commands/show_defaults.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark `show-defaults` command.
+
+Displays the built-in default TopMark configuration. This includes the default
+header template and the default TOML configuration bundled with the package.
+Intended as a reference for users customizing their own configuration files.
+"""
+
+import click
+from yachalk import chalk
+
+from topmark.cli.utils import default_header_overrides
+from topmark.config import Config
+from topmark.constants import PYPROJECT_TOML_PATH
+from topmark.rendering.api import render_header_for_path
+
+
+def show_defaults_command() -> None:
+    """Display the built-in default configuration.
+
+    Prints the TopMark default configuration as bundled with the package, including a header.
+    Useful as a reference for configuration structure and default values.
+
+    Returns:
+        None. Prints output to stdout.
+    """
+    header_overrides = default_header_overrides(
+        info="Default TopMark Configuration", file_label="topmark.toml"
+    )
+    topmark_header = render_header_for_path(
+        config=Config.from_defaults(),
+        path=PYPROJECT_TOML_PATH,
+        header_fields_overrides=["file", "version", "info", "license", "copyright"],
+        header_overrides=header_overrides,
+    )
+
+    click.echo(chalk.bold.underline("Default TopMark Configuration:"))
+    click.echo(
+        chalk.gray(
+            f"""\
+{topmark_header}
+{Config.to_cleaned_toml(Config.get_default_config_toml())}
+## === END of TopMark Configuration ==="""
+        )
+    )

topmark/cli/commands/version.py

@@ -0,0 +1,32 @@
+# topmark:header:start
+#
+#   file         : version.py
+#   file_relpath : src/topmark/cli/commands/version.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""TopMark `version` command.
+
+Prints the current TopMark version as installed in the active Python environment.
+"""
+
+from __future__ import annotations
+
+import click
+
+from topmark.constants import TOPMARK_VERSION
+
+
+def version_command() -> None:
+    """Show the current version of TopMark.
+
+    Prints the TopMark version as installed in the current Python environment.
+
+    Returns:
+        None. Prints output to stdout.
+    """
+    topmark_version = TOPMARK_VERSION
+    click.echo(f"TopMark version: {topmark_version}")

topmark/cli/config_resolver.py

@@ -0,0 +1,82 @@
+# topmark:header:start
+#
+#   file         : config_resolver.py
+#   file_relpath : src/topmark/cli/config_resolver.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""Utilities for resolving TopMark configuration from Click parameters.
+
+This module provides helpers to convert Click command-line parameters into an
+:class:`~topmark.config.Config` object. It bridges CLI parsing and the core
+configuration system by building an ArgsNamespace and merging user, project,
+and default config sources.
+"""
+
+import click
+
+from topmark.cli.cli_types import ArgsNamespace, build_args_namespace
+from topmark.config import Config
+from topmark.config.logging import get_logger
+from topmark.rendering.formats import HeaderOutputFormat
+
+logger = get_logger(__name__)
+
+
+# Helper: Build Config from Click params using ArgsNamespace and merged config logic
+def resolve_config_from_click(
+    *,
+    ctx: click.Context,
+    files: list[str],
+    stdin: bool,
+    include_patterns: list[str],
+    include_from: list[str],
+    exclude_patterns: list[str],
+    exclude_from: list[str],
+    file_types: list[str],
+    relative_to: str | None,
+    no_config: bool,
+    config_paths: list[str],
+    align_fields: bool,
+    header_format: HeaderOutputFormat | None,
+) -> Config:
+    """Build a :class:`Config` from Click parameters.
+
+    Args:
+        ctx: Click context that provides the resolved log level.
+        files: File paths passed on the command line.
+        stdin: Whether to read file paths from standard input.
+        include_patterns: Glob patterns of files to include.
+        include_from: Paths to files that contain include patterns.
+        exclude_patterns: Glob patterns of files to exclude.
+        exclude_from: Paths to files that contain exclude patterns.
+        file_types: File type identifiers to restrict processing to.
+        relative_to: Root directory used to compute relative paths.
+        no_config: If True, ignore local project config files.
+        config_paths: Extra config TOML file paths to merge.
+        align_fields: Whether to align header fields with colons.
+        header_format: Selected header output format.
+
+    Returns:
+        Config: The merged configuration.
+    """
+    args: ArgsNamespace = build_args_namespace(
+        log_level=ctx.obj.get("log_level"),
+        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),
+        no_config=no_config,
+        config_files=list(config_paths),
+        file_types=list(file_types),
+        relative_to=relative_to,
+        align_fields=align_fields,
+        header_format=header_format,
+    )
+    logger.trace("ArgsNamespace: %s", args)
+    return Config.load_merged(args)