topmark 0.3.2__tar.gz → 0.4.0__tar.gz

{topmark-0.3.2/src/topmark.egg-info → topmark-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.3.2
+Version: 0.4.0
 Summary: A Python CLI to inspect, validate, and manage license and copyright headers.
 Author-email: Olivier Biot <olivier.biot@gmail.com>
 License-Expression: MIT

{topmark-0.3.2 → topmark-0.4.0}/pyproject.toml

@@ -10,7 +10,7 @@
 
 [project]
 name = "topmark"
-version = "0.3.2"
+version = "0.4.0"
 description = "A Python CLI to inspect, validate, and manage license and copyright headers."
 authors = [{ name = "Olivier Biot", email = "olivier.biot@gmail.com" }]
 license = "MIT"
@@ -113,15 +113,6 @@ include-package-data = true
 [tool.setuptools.packages.find]
 where = ["src"]
 
-# Markdown formatting configuration (normative reference: .mdformat.toml)
-# Aligns with Prettier in VS Code and the mdformat pre-commit hook
-[tool.mdformat]
-wrap = 100
-extensions = ["tables"]
-# Exclude auto-generated API page from formatting (Python 3.13)
-# NOTE: Please use `make format-check` and `make format`
-exclude = ["docs/api/public.md"]
-
 
 # TOML formatting
 [tool.taplo.format]

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/api/__init__.py

@@ -34,6 +34,7 @@ Notes:
 - A FileType instance is **recognized** if it is in the FileTypeRegistry.
 - A FileType instance is **supported** if it is recognized and is registered to
   a HeaderProcessor instance in the HeaderProcessorRegistry.
+- The API returns per-file diagnostics and aggregate counts; levels are "info", "warning", "error".
 """
 
 from __future__ import annotations
@@ -52,10 +53,16 @@ from topmark.cli_shared.utils import write_updates
 from topmark.config import Config
 from topmark.config.logging import get_logger, setup_logging
 from topmark.constants import TOPMARK_VERSION
-from topmark.pipeline.context import ComparisonStatus, FileStatus, ProcessingContext, WriteStatus
+from topmark.pipeline.context import (
+    ComparisonStatus,
+    FileStatus,
+    ProcessingContext,
+    WriteStatus,
+)
 from topmark.registry import Registry
 
-from .types import FileResult, FileTypeInfo, Outcome, ProcessorInfo, RunResult
+from .public_types import PublicDiagnostic
+from .types import DiagnosticTotals, FileResult, FileTypeInfo, Outcome, ProcessorInfo, RunResult
 
 if "TOPMARK_DEBUG" in os.environ:
     setup_logging(level=logging.DEBUG)
@@ -75,6 +82,7 @@ __all__ = [
     "get_filetype_info",
     "get_processor_info",
     "Registry",
+    "PublicDiagnostic",
 ]
 
 
@@ -200,24 +208,45 @@ def _apply_view_filter(
     return view_results, skipped
 
 
-def _collect_diagnostics(results: list[ProcessingContext]) -> dict[str, list[str]]:
-    """Collect per-file diagnostics as a mapping `{path: [messages...]}`.
-
-    Only files that produced diagnostics are included in the result.
-
-    Args:
-        results: List of ProcessingContext results.
+def _collect_diagnostics(
+    results: list[ProcessingContext],
+) -> dict[str, list[PublicDiagnostic]]:
+    """Collect per-file diagnostics as a mapping `{path: [diagnostics...]}`.
 
-    Returns:
-        A mapping from file path (string) to a list of diagnostic messages.
+    Diagnostics are returned in the *public* JSON-friendly shape and do not
+    expose internal classes or enums.
     """
-    diags: dict[str, list[str]] = {}
+    diags: dict[str, list[PublicDiagnostic]] = {}
     for r in results:
         if r.diagnostics:
-            diags[str(r.path)] = r.diagnostics
+            diags[str(r.path)] = [
+                {"level": d.level.value, "message": d.message} for d in r.diagnostics
+            ]
     return diags
 
 
+def _collect_diagnostic_totals(results: list[ProcessingContext]) -> DiagnosticTotals:
+    """Return aggregate counts of diagnostics across the given results.
+
+    Counts reflect only the supplied `results` (typically the **view** after
+    filtering), matching what is returned to the caller.
+    """
+    total_info = total_warn = total_error = 0
+    for r in results:
+        if not r.diagnostics:
+            continue
+        for d in r.diagnostics:
+            lv = d.level.value
+            if lv == "info":
+                total_info += 1
+            elif lv == "warning":
+                total_warn += 1
+            elif lv == "error":
+                total_error += 1
+    total = total_info + total_warn + total_error
+    return {"info": total_info, "warning": total_warn, "error": total_error, "total": total}
+
+
 # ---------- public API ----------
 
 
@@ -354,6 +383,8 @@ def check(
         encountered_error_code is not None
     )
     diagnostics = _collect_diagnostics(view_results)
+    diagnostic_totals = _collect_diagnostic_totals(view_results)
+    diagnostic_totals_all = _collect_diagnostic_totals(results)
 
     written = failed = 0
     if apply:
@@ -380,6 +411,8 @@ def check(
         written=written,
         failed=failed,
         diagnostics=diagnostics,
+        diagnostic_totals=diagnostic_totals,
+        diagnostic_totals_all=diagnostic_totals_all,
     )
 
 
@@ -432,6 +465,8 @@ def strip(
         encountered_error_code is not None
     )
     diagnostics = _collect_diagnostics(view_results)
+    diagnostic_totals = _collect_diagnostic_totals(view_results)
+    diagnostic_totals_all = _collect_diagnostic_totals(results)
 
     written = failed = 0
     if apply:
@@ -452,6 +487,8 @@ def strip(
         written=written,
         failed=failed,
         diagnostics=diagnostics,
+        diagnostic_totals=diagnostic_totals,
+        diagnostic_totals_all=diagnostic_totals_all,
     )
 
 

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/api/public_types.py

@@ -21,11 +21,17 @@ Notes:
     * Attribute names and types here are part of the public API and follow
       semver. Adding optional attributes is allowed in minor versions; removing
       or changing types is a breaking change.
+
+Diagnostics
+-----------
+The public API uses JSON-friendly diagnostics with string literal severities.
+See :class:`PublicDiagnostic` for the shape and :data:`DiagnosticLevelLiteral`
+for the allowed values.
 """
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol, Sequence
+from typing import TYPE_CHECKING, Literal, Protocol, Sequence, TypedDict
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -96,3 +102,20 @@ class PublicHeaderProcessor(Protocol):
     block_suffix: str
     # registry binds at runtime
     file_type: PublicFileType
+
+
+"""Allowed diagnostic severity levels in the public API."""
+DiagnosticLevelLiteral = Literal["info", "warning", "error"]
+
+
+class PublicDiagnostic(TypedDict):
+    """Stable, JSON-friendly diagnostic for API consumers.
+
+    Notes:
+        * Uses string literal levels for semver stability and easy serialization.
+        * Mirrors internal pipeline diagnostics but does not expose internals.
+        * This shape is stable for semver and safe to serialize to JSON/NDJSON.
+    """
+
+    level: DiagnosticLevelLiteral
+    message: str

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/api/types.py

@@ -21,9 +21,28 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import TYPE_CHECKING, Mapping, Sequence, TypedDict
 
+
+class DiagnosticTotals(TypedDict):
+    """Aggregate diagnostic counts across the returned *view*.
+
+    Keys:
+        info: Number of info diagnostics.
+        warning: Number of warning diagnostics.
+        error: Number of error diagnostics.
+        total: Sum of all diagnostics.
+    """
+
+    info: int
+    warning: int
+    error: int
+    total: int
+
+
 if TYPE_CHECKING:
     from pathlib import Path
 
+    from .public_types import PublicDiagnostic
+
 
 class Outcome(str, Enum):
     """Per-file outcome bucket.
@@ -72,8 +91,11 @@ class RunResult:
         skipped: Number of items removed by view filters (e.g., `skip_compliant`).
         written: Number of files successfully written (only in apply mode; otherwise 0).
         failed: Number of files that failed to write (only in apply mode; otherwise 0).
-        diagnostics: Optional mapping from file path (string) to a list of pipeline
-            diagnostic messages; present only if any were produced.
+        diagnostics: Optional mapping from file path to a list of public diagnostics.
+        diagnostic_totals: Optional aggregate counts across the **returned view**
+            (not the entire run).
+        diagnostic_totals_all: Optional aggregate counts across the **entire run**
+            (pre view filtering).
     """
 
     files: Sequence[FileResult]
@@ -82,7 +104,9 @@ class RunResult:
     skipped: int = 0
     written: int = 0
     failed: int = 0
-    diagnostics: dict[str, list[str]] | None = None
+    diagnostics: dict[str, list[PublicDiagnostic]] | None = None
+    diagnostic_totals: DiagnosticTotals | None = None
+    diagnostic_totals_all: DiagnosticTotals | None = None
 
 
 # Tiny intent object used by check()/strip() to gate writes

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/cli/cli_types.py

@@ -64,6 +64,7 @@ class ArgsNamespace(TypedDict, total=False):
 
     Attributes:
         log_level: Verbosity level for logging.
+        verbosity_level: Program-output verbosity (0=terse, 1=verbose).
         no_config: Whether to ignore local config files.
         config_files: List of extra config file paths.
         files: List of file paths to process.
@@ -80,6 +81,7 @@ class ArgsNamespace(TypedDict, total=False):
 
     # Global options: retrieve from ctx.obj
     log_level: int
+    verbosity_level: int | None
 
     # TopMark Command
     # command: TopMarkCommand
@@ -109,6 +111,7 @@ class ArgsNamespace(TypedDict, total=False):
 def build_args_namespace(
     *,
     log_level: int = logging.WARNING,
+    verbosity_level: int | None = None,
     # command: TopMarkCommand = TopMarkCommand.NONE,
     no_config: bool | None = None,
     config_files: list[str] | None = None,
@@ -128,6 +131,7 @@ def build_args_namespace(
 
     Args:
         log_level: Verbosity level for logging.
+        verbosity_level: Program-output verbosity (0=terse, 1=verbose).
         no_config: Whether to ignore local config files.
         config_files: List of extra config file paths.
         files: List of file paths to process.
@@ -147,6 +151,7 @@ def build_args_namespace(
     """
     return {
         "log_level": log_level,
+        "verbosity_level": verbosity_level,
         # "command": command,
         "no_config": no_config,
         "config_files": config_files,

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/cli/cmd_common.py

@@ -175,6 +175,7 @@ def build_config_common(
         config_paths=config_paths,
         align_fields=align_fields,
         header_format=header_format,
+        verbosity_level=ctx.obj.get("verbosity_level"),
     )
 
 
@@ -206,6 +207,7 @@ def build_config_and_file_list(
             config_paths=config_paths,
             align_fields=align_fields,
             header_format=header_format,
+            verbosity_level=ctx.obj.get("verbosity_level"),
         )
         return config, [Path(plan.paths[0])]
     else:
@@ -224,5 +226,6 @@ def build_config_and_file_list(
             config_paths=config_paths,
             align_fields=align_fields,
             header_format=header_format,
+            verbosity_level=ctx.obj.get("verbosity_level"),
         )
         return config, resolve_file_list(config)

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/cli/commands/check.py

@@ -223,9 +223,6 @@ def check_command(
       UNEXPECTED_ERROR (255): An unhandled error occurred.
     """
     ctx = click.get_current_context()
-    level = ctx.obj["log_level"]
-    logger.debug(f"{ctx.command.name}: Log level is {level}")
-    logger.setLevel(level)
 
     fmt: OutputFormat = output_format or OutputFormat.DEFAULT
     if fmt in (OutputFormat.JSON, OutputFormat.NDJSON):

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/cli/commands/strip.py

@@ -207,9 +207,6 @@ def strip_command(
       UNEXPECTED_ERROR (255): An unhandled error occurred.
     """
     ctx = click.get_current_context()
-    level = ctx.obj["log_level"]
-    logger.debug(f"{ctx.command.name}: Log level is {level}")
-    logger.setLevel(level)
 
     fmt: OutputFormat = output_format or OutputFormat.DEFAULT
     if fmt in (OutputFormat.JSON, OutputFormat.NDJSON):

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/cli/config_resolver.py

@@ -43,6 +43,7 @@ def resolve_config_from_click(
     config_paths: list[str],
     align_fields: bool,
     header_format: HeaderOutputFormat | None,
+    verbosity_level: int | None,
 ) -> Config:
     """Build a :class:`Config` from Click parameters.
 
@@ -61,12 +62,15 @@ def resolve_config_from_click(
         config_paths: Extra config TOML file paths to merge.
         align_fields: Whether to align header fields with colons.
         header_format: Selected header output format.
+        verbosity_level: Program-output verbosity (0=terse, 1=verbose);
+            None = inherit from parent context.
 
     Returns:
         Config: The merged configuration.
     """
     args: ArgsNamespace = build_args_namespace(
         log_level=ctx.obj.get("log_level"),
+        verbosity_level=verbosity_level,
         files=list(files),
         files_from=list(files_from),
         stdin=stdin,

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/cli/main.py

@@ -36,6 +36,7 @@ from topmark.cli.options import (
     resolve_color_mode,
     resolve_verbosity,
 )
+from topmark.cli_shared.console import Console
 from topmark.config.logging import get_logger, setup_logging
 from topmark.pipeline.processors import register_all_processors
 
@@ -58,6 +59,10 @@ def init_common_state(
     """
     ctx.obj = ctx.obj or {}
 
+    # Program-output verbosity: map -v/-q to a non-negative level (0..2)
+    vlevel = max(0, min(2, verbose - quiet))
+    ctx.obj["verbosity_level"] = vlevel
+
     # Set the log level
     level = resolve_verbosity(verbose, quiet)
     ctx.obj["log_level"] = level
@@ -68,6 +73,9 @@ def init_common_state(
     ctx.obj["color_enabled"] = enable_color
     ctx.color = enable_color
 
+    console = Console(enable_color=not no_color)
+    ctx.obj["console"] = console
+
 
 @click.group(
     cls=click.Group,

topmark-0.4.0/src/topmark/cli_shared/console.py

@@ -0,0 +1,105 @@
+# topmark:header:start
+#
+#   file         : console.py
+#   file_relpath : src/topmark/cli_shared/console.py
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+"""Console abstraction for user-facing program output.
+
+This module provides a `Console` class that separates CLI output from
+internal logging. Use this for messages intended for end users, while
+reserving `logging` for diagnostics.
+"""
+
+import sys
+from typing import Any, TextIO, TypedDict
+
+import click
+
+
+# This TypedDict is for documentation and type-checking on the *caller* side.
+class StyleKwargs(TypedDict, total=False):
+    """Keyword arguments accepted by click.style()."""
+
+    fg: str
+    bg: str
+    bold: bool
+    dim: bool
+    underline: bool
+    blink: bool
+    reverse: bool
+    strikethrough: bool
+    # Ensure all valid arguments from click.style() are included here
+
+
+class Console:
+    """Program-output console, independent from the logger.
+
+    Attributes:
+        enable_color (bool): Whether to emit ANSI color codes.
+        out (TextIO): Stream for standard output (defaults to sys.stdout).
+        err (TextIO): Stream for error output (defaults to sys.stderr).
+    """
+
+    def __init__(
+        self, *, enable_color: bool = True, out: TextIO | None = None, err: TextIO | None = None
+    ) -> None:
+        """Initializes the Console.
+
+        Args:
+            enable_color: If True, enables ANSI color codes in the output.
+                Otherwise, all output is plain text.
+            out: The text stream to use for standard output.
+                Defaults to `sys.stdout`.
+            err: The text stream to use for error output.
+                Defaults to `sys.stderr`.
+        """
+        self.enable_color = enable_color
+        self.out = out or sys.stdout
+        self.err = err or sys.stderr
+
+    def print(self, text: str = "", *, nl: bool = True) -> None:
+        """Write a message to stdout.
+
+        Args:
+            text: Message text.
+            nl: If True, append a newline.
+        """
+        click.echo(text, nl=nl, file=self.out, color=self.enable_color)
+
+    def warn(self, text: str, *, nl: bool = True) -> None:
+        """Write a warning message to stderr.
+
+        Args:
+            text: Warning text.
+            nl: If True, append a newline.
+        """
+        click.echo(text, nl=nl, file=self.err, color=self.enable_color)
+
+    def error(self, text: str, *, nl: bool = True) -> None:
+        """Write an error message to stderr.
+
+        Args:
+            text: Error text.
+            nl: If True, append a newline.
+        """
+        click.echo(text, nl=nl, file=self.err, color=self.enable_color)
+
+    def styled(self, text: str, **style_kwargs: Any) -> str:
+        """Return a styled string using click.style.
+
+        Args:
+            text: Text to style.
+            **style_kwargs: Subset of keyword arguments supported by click.style.
+                            Expected keys are defined in the StyleKwargs TypedDict.
+
+        Returns:
+            str: The styled text (or plain text if color is disabled).
+        """
+        if not self.enable_color:
+            return text
+        return click.style(text, **style_kwargs)

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/cli_shared/utils.py

@@ -235,7 +235,7 @@ def classify_outcome(r: ProcessingContext) -> tuple[str, str, Callable[[str], st
     logger.debug("status: %s", r.status)
 
     if r.status.file is not FileStatus.RESOLVED:
-        return (f"file:{r.status.file.name}", f"file {r.status.file.value}", r.status.file.color)
+        return (f"file:{r.status.file.name}", f"{r.status.file.value}", r.status.file.color)
 
     # Highest precedence: if comparison says UNCHANGED, treat as compliant
     if r.status.comparison is ComparisonStatus.UNCHANGED:

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/config/__init__.py

@@ -67,6 +67,7 @@ class Config:
         files_from (list[str]): Paths to files that list newline-delimited candidate file paths
             to add before filtering.
         file_types (list[str]): File extensions or types to process.
+        verbosity_level (int | None): None = inherit, 0 = terse, 1 = verbose diagnostics.
     """
 
     # Initialization timestamp for the config instance
@@ -75,6 +76,10 @@ class Config:
     # Paths or identifiers of configuration files or sources used to build this Config
     config_files: list[Path | str] = field(default_factory=lambda: [])
 
+    # Verbosity level
+    # verbosity_level (int | None): None = inherit, 0 = terse, 1 = verbose diagnostics
+    verbosity_level: int | None = None
+
     # Header configuration fields and their values
     header_fields: list[str] = field(default_factory=lambda: [])  # From [header].fields
     field_values: dict[str, str] = field(default_factory=lambda: {})  # From [fields]
@@ -359,6 +364,19 @@ class Config:
         ):  # Only override if align_fields was passed via CLI
             self.align_fields = args["align_fields"]
 
+        if "verbosity_level" in args and args["verbosity_level"] is not None:
+            try:
+                self.verbosity_level = int(args["verbosity_level"])
+            except (TypeError, ValueError):
+                logger.warning(
+                    "Invalid verbosity_level=%r (expected int); keeping %r",
+                    args["verbosity_level"],
+                    self.verbosity_level,
+                )
+        elif "verbosity_level" in args and args["verbosity_level"] is None:
+            # Explicit None means inherit, do not override
+            pass
+
         logger.debug("Patched Config: %s", self)
         logger.info("Applied CLI overrides to Config")
         logger.debug("apply_cli_args(): finalized stdin=%s files=%s", self.stdin, self.files)
@@ -511,6 +529,9 @@ class Config:
             relative_to=(other.relative_to if other.relative_to is not None else self.relative_to),
             # Use other's file_types if set, else self's
             file_types=other.file_types or self.file_types,
+            verbosity_level=(
+                other.verbosity_level if other.verbosity_level is not None else self.verbosity_level
+            ),
         )
 
     def to_toml_dict(self) -> dict[str, Any]:

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/context.py

@@ -263,6 +263,47 @@ class WriteStatus(BaseStatus):
         )
 
 
+# --- Diagnostics support ------------------------------------------------------
+class DiagnosticLevel(Enum):
+    """Severity levels for diagnostics collected during processing.
+
+    Levels map to terminal colors and are ordered by importance: ERROR > WARNING > INFO.
+    This enum is **internal**; the public API exposes string literals.
+    """
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+    @property
+    def color(self) -> Callable[[str], str]:
+        """Return the `yachalk` color function associated with this severity level.
+
+        Intended for human-readable output only; machine formats should not use colors.
+        """
+        return cast(
+            "Callable[[str], str]",
+            {
+                DiagnosticLevel.INFO: chalk.blue,
+                DiagnosticLevel.WARNING: chalk.yellow,
+                DiagnosticLevel.ERROR: chalk.red_bright,
+            }[self],
+        )
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """Internal structured diagnostic with a severity level and message.
+
+    Note:
+        This type is **not** part of the public API surface. Conversions to
+        `PublicDiagnostic` happen at the API boundary.
+    """
+
+    level: DiagnosticLevel
+    message: str
+
+
 @dataclass
 class HeaderProcessingStatus:
     """Tracks the status of each processing phase for a single file.
@@ -349,7 +390,7 @@ class ProcessingContext:
     header_diff: str | None = None  # Unified diff (patch) for patching (updating) the header
 
     # Processing diagnostics: warnings/errors collected during processing
-    diagnostics: list[str] = field(default_factory=lambda: [])
+    diagnostics: list[Diagnostic] = field(default_factory=list[Diagnostic])
 
     def to_dict(self) -> dict[str, object]:
         """Return a machine-readable representation of this processing result.
@@ -369,7 +410,14 @@ class ProcessingContext:
             },
             "existing_header_range": self.existing_header_range,
             "has_diff": bool(self.header_diff),
-            "diagnostics": list(self.diagnostics),
+            "diagnostics": [
+                {"level": d.level.value, "message": d.message} for d in self.diagnostics
+            ],
+            "diagnostic_counts": {
+                "info": sum(1 for d in self.diagnostics if d.level is DiagnosticLevel.INFO),
+                "warning": sum(1 for d in self.diagnostics if d.level is DiagnosticLevel.WARNING),
+                "error": sum(1 for d in self.diagnostics if d.level is DiagnosticLevel.ERROR),
+            },
             # Heuristic: treat MISSING or CHANGED as a would-change indicator
             "would_change": (
                 self.status.header is HeaderStatus.MISSING
@@ -377,8 +425,8 @@ class ProcessingContext:
             ),
         }
 
-    def format_summary(self) -> str:
-        """Return the current human-readable per-file summary string.
+    def format_summary_v0_3_2(self) -> str:
+        """OLD - Return the current human-readable per-file summary string.
 
         TODO: refine the rendering.
         """
@@ -394,12 +442,119 @@ class ProcessingContext:
             f"{chalk.dim(self.file_type.name)} - "
             f"{self.status.file.color('file ' + self.status.file.value)}"
         )
-        result += f", {self.status.header.color('current header: ' + self.status.header.value)}"
+        result += f", {self.status.header.color('header: ' + self.status.header.value)}"
         result += f", {self.status.generation.color('new header: ' + self.status.generation.value)}"
         result += f", {self.status.comparison.color('result: ' + self.status.comparison.value)}"
         result += f", {self.status.strip.color('strip: ' + self.status.strip.value)}"
         return result
 
+    def format_summary_v0_3_3_dev0(self) -> str:
+        """Return the current human-readable per-file summary string.
+
+        TODO: refine the rendering.
+        """
+        result: str = f"{self.path}: "
+        if not self.file_type or self.status.file != FileStatus.RESOLVED:
+            result += (
+                f"{chalk.dim(self.file_type.name if self.file_type else '<unknown>')} - "
+                f"{self.status.file.color('file ' + self.status.file.value)}"
+            )
+            return result
+
+        result += f"{chalk.dim(self.file_type.name)}"
+        result += f" - {self.status.header.color('header ' + self.status.header.value)}"
+        result += f" - {self.status.comparison.color(self.status.comparison.value)}"
+        if self.status.write != WriteStatus.PENDING:
+            result += f" - {self.status.write.color(self.status.write.value)}"
+        elif self.status.generation != GenerationStatus.PENDING:
+            result += f" - {self.status.generation.color(self.status.generation.value)}"
+        else:
+            f"{self.status.file.color('file ' + self.status.file.value)}"
+
+        return result
+
+    def format_summary(self) -> str:
+        """Return a concise, human‑readable one‑liner for this file.
+
+        The summary is aligned with TopMark's pipeline phases and mirrors what
+        comparable tools (e.g., *ruff*, *black*, *prettier*) surface: a clear
+        primary outcome plus a few terse hints.
+
+        Rendering rules:
+          1) Primary bucket comes from :func:`topmark.cli_shared.utils.classify_outcome`.
+             This ensures stable wording across commands/pipelines.
+          2) If a write outcome is known (e.g., PREVIEWED/WRITTEN/INSERTED/REMOVED),
+             append it as a trailing hint.
+          3) If there is a diff but no write outcome (e.g., check/summary with
+             `--diff`), append a "diff" hint.
+          4) If diagnostics exist, append the diagnostic count as a hint.
+
+        Verbose per‑line diagnostics are emitted only when Config.verbosity_level >= 1
+        (treats None as 0).
+
+        Examples (colors omitted here):
+            path/to/file.py: python – would insert header - previewed
+            path/to/file.py: python – up-to-date
+            path/to/file.py: python – would strip header - diff - 2 issues
+        """
+        # Local import to avoid import cycles at module import time
+        from topmark.cli_shared.utils import classify_outcome
+
+        parts: list[str] = [f"{self.path}:"]
+
+        # File type (dim), or <unknown> if resolution failed
+        if self.file_type is not None:
+            parts.append(chalk.dim(self.file_type.name))
+        else:
+            parts.append(chalk.dim("<unknown>"))
+
+        # Primary bucket/label with color
+        key, label, color_fn = classify_outcome(self)
+        parts.append("\u2013")  # en dash separator
+        parts.append(color_fn(label))
+
+        if key != "ok":
+            # Secondary hints: write status > diff marker > diagnostics
+
+            if self.status.write is not WriteStatus.PENDING:
+                parts.append("-")
+                parts.append(self.status.write.color(self.status.write.value))
+            elif self.header_diff:
+                parts.append("-")
+                parts.append(chalk.yellow("diff"))
+
+        if self.diagnostics:
+            n_info = sum(1 for d in self.diagnostics if d.level is DiagnosticLevel.INFO)
+            n_warn = sum(1 for d in self.diagnostics if d.level is DiagnosticLevel.WARNING)
+            n_err = sum(1 for d in self.diagnostics if d.level is DiagnosticLevel.ERROR)
+            parts.append("-")
+            # Compose a compact triage summary like "1 error, 2 warnings"
+            triage: list[str] = []
+            if n_err:
+                triage.append(chalk.red_bright(f"{n_err} error" + ("s" if n_err != 1 else "")))
+            if n_warn:
+                triage.append(chalk.yellow(f"{n_warn} warning" + ("s" if n_warn != 1 else "")))
+            if n_info and not (n_err or n_warn):
+                # Only show infos when there are no higher severities
+                triage.append(chalk.blue(f"{n_info} info" + ("s" if n_info != 1 else "")))
+            parts.append(", ".join(triage) if triage else chalk.blue("info"))
+
+        result: str = " ".join(parts)
+
+        # Optional verbose listing (kept simple; could be gated by verbosity later)
+        if self.diagnostics and (self.config.verbosity_level or 0) >= 1:
+            details: list[str] = []
+            for d in self.diagnostics:
+                prefix = {
+                    DiagnosticLevel.ERROR: chalk.red_bright("error"),
+                    DiagnosticLevel.WARNING: chalk.yellow("warning"),
+                    DiagnosticLevel.INFO: chalk.blue("info"),
+                }[d.level]
+                details.append(f" - [{prefix}] {d.message}")
+            result += "\n" + "\n".join(details)
+
+        return result
+
     @property
     def summary(self) -> str:
         """Return a formatted summary string of the processing status for this file."""
@@ -409,3 +564,28 @@ class ProcessingContext:
     def bootstrap(cls, *, path: Path, config: Config) -> ProcessingContext:
         """Create a fresh context with no derived state."""
         return cls(path=path, config=config)
+
+    # --- Convenience helpers -------------------------------------------------
+    def add_info(self, message: str) -> None:
+        """Add an `info` diagnostic to the processing context.
+
+        Args:
+            message (str): The diagnostic message.
+        """
+        self.diagnostics.append(Diagnostic(DiagnosticLevel.INFO, message))
+
+    def add_warning(self, message: str) -> None:
+        """Add an `warning` diagnostic to the processing context.
+
+        Args:
+            message (str): The diagnostic message.
+        """
+        self.diagnostics.append(Diagnostic(DiagnosticLevel.WARNING, message))
+
+    def add_error(self, message: str) -> None:
+        """Add an `error` diagnostic to the processing context.
+
+        Args:
+            message (str): The diagnostic message.
+        """
+        self.diagnostics.append(Diagnostic(DiagnosticLevel.ERROR, message))

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/pipelines.py

@@ -19,8 +19,6 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Final, Mapping, Tuple
 
-from topmark.pipeline.steps import stripper
-
 from .steps import (
     builder,
     comparer,
@@ -29,6 +27,7 @@ from .steps import (
     renderer,
     resolver,
     scanner,
+    stripper,
     updater,
 )
 

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/processors/base.py

@@ -168,9 +168,7 @@ class HeaderProcessor:
         if start_rel is None or end_rel is None or end_rel <= start_rel:
             # Keep scanner as the single authority for header MALFORMED status.
             # Here we just surface a diagnostic to aid debugging.
-            context.diagnostics.append(
-                f"parse_fields(): could not locate a valid START/END marker pair in {context.path}"
-            )
+            context.add_error("parse_fields(): could not locate a valid START/END marker pair.")
             return {}
 
         # 2) Extract payload (strictly between markers).
@@ -193,13 +191,13 @@ class HeaderProcessor:
                 continue
 
             if ":" not in cleaned:
-                context.diagnostics.append(
-                    f"Unrecognized header line at {context.path}:{abs_line_no}: '{raw.rstrip()}'"
+                context.add_error(
+                    f"Unrecognized header field name at line {abs_line_no}: '{raw.rstrip()}'"
                 )
                 continue
 
             key, value = cleaned.split(":", 1)
-            k = key.strip().lstrip("#")  # tolerate accidental leading '#'
+            k = key.strip()
             v = value.strip()
             if not k:
                 logger.warning(
@@ -207,8 +205,8 @@ class HeaderProcessor:
                     abs_line_no,
                     raw,
                 )
-                context.diagnostics.append(
-                    f"Empty header key at {context.path}:{abs_line_no}: '{raw.rstrip()}'"
+                context.add_error(
+                    f"Empty header field name at line {abs_line_no}: '{raw.rstrip()}'"
                 )
                 continue
             result[k] = v

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/steps/builder.py

@@ -97,9 +97,7 @@ def build(ctx: ProcessingContext) -> ProcessingContext:
                 "Config.field_values contains keys that overlap with builtin fields: %s",
                 builtin_overlap_repr,
             )
-            ctx.diagnostics = (ctx.diagnostics or []) + [
-                f"Redefined built-in fields: {builtin_overlap_repr}"
-            ]
+            ctx.add_warning(f"Redefined built-in fields: {builtin_overlap_repr}")
 
     # Merge built-in and configuration-defined fields
     # Allow user-defined fields to override built-ins when both are in config.field_values
@@ -113,7 +111,7 @@ def build(ctx: ProcessingContext) -> ProcessingContext:
         value = all_fields.get(key)
         if value is None:
             logger.warning("Unknown header field: %s", key)
-            ctx.diagnostics.append(f"Unknown header field: {key}")
+            ctx.add_error(f"Unknown header field: {key}")
         else:
             result[key] = value
 

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/steps/reader.py

@@ -62,6 +62,7 @@ def read(ctx: ProcessingContext) -> ProcessingContext:
 
     if ctx.path.stat().st_size == 0:
         logger.warning("Found empty file: %s", ctx.path)
+        ctx.add_warning("File is empty.")
         ctx.status.file = FileStatus.EMPTY_FILE
         return ctx
 
@@ -122,7 +123,7 @@ def read(ctx: ProcessingContext) -> ProcessingContext:
     except Exception as e:  # Log and attach diagnostic; continue without raising
         ctx.status.file = FileStatus.UNREADABLE
         logger.error("Error reading file %s: %s", ctx.path, e)
-        ctx.diagnostics.append(f"Error reading file: {e}")
+        ctx.add_error(f"Error reading file: {e}")
 
     if nl:
         # Store the line end style
@@ -160,7 +161,7 @@ def read(ctx: ProcessingContext) -> ProcessingContext:
         # shebang, skip processing by default and surface a clear diagnostic.
         policy = getattr(ctx.header_processor.file_type, "header_policy", None)
         if ctx.leading_bom and ctx.has_shebang and policy and policy.supports_shebang:
-            ctx.diagnostics.append(
+            ctx.add_error(
                 "UTF-8 BOM appears before the shebang; POSIX requires '#!' at byte 0. "
                 "TopMark will not modify this file by default. Consider removing the BOM "
                 "or using a future '--fix-bom' option to resolve this conflict."
@@ -176,6 +177,7 @@ def read(ctx: ProcessingContext) -> ProcessingContext:
         # Record whether the file ends with a newline (used when generating patches)
         if len(lines) == 0:
             logger.warning("File has no lines (empty): %s", ctx.path)
+            ctx.add_warning("File is empty.")
             ctx.status.file = FileStatus.EMPTY_FILE
             return ctx
 
@@ -204,7 +206,7 @@ def read(ctx: ProcessingContext) -> ProcessingContext:
     except Exception as e:  # Log and attach diagnostic; continue without raising
         ctx.status.file = FileStatus.UNREADABLE
         logger.error("Error reading file %s: %s", ctx.path, e)
-        ctx.diagnostics.append(f"Error reading file: {e}")
+        ctx.add_error(f"Error reading file: {e}")
 
     logger.warning("%s: File cannot be processed: %s", ctx.status.file.value, ctx.path)
     return ctx

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/steps/resolver.py

@@ -250,7 +250,7 @@ def resolve(ctx: ProcessingContext) -> ProcessingContext:
 
         if file_type.skip_processing:
             ctx.status.file = FileStatus.SKIPPED_KNOWN_NO_HEADERS
-            ctx.diagnostics.append(
+            ctx.add_warning(
                 f"File type '{file_type.name}' recognized; "
                 "headers are not supported for this format. Skipping."
             )
@@ -267,9 +267,7 @@ def resolve(ctx: ProcessingContext) -> ProcessingContext:
             ctx.status.file = (
                 FileStatus.SKIPPED_NO_HEADER_PROCESSOR
             )  # or SKIPPED_NO_HEADER_MANAGER if that's your enum
-            ctx.diagnostics.append(
-                f"No header processor registered for file type '{file_type.name}'."
-            )
+            ctx.add_warning(f"No header processor registered for file type '{file_type.name}'.")
             logger.info(
                 "No header processor registered for file type '%s' (file '%s')",
                 file_type.name,
@@ -290,6 +288,6 @@ def resolve(ctx: ProcessingContext) -> ProcessingContext:
 
     # No FileType matched: mark as unsupported and record a diagnostic
     ctx.status.file = FileStatus.SKIPPED_UNSUPPORTED
-    ctx.diagnostics.append("No file type associated with this file.")
+    ctx.add_warning("No file type associated with this file.")
     logger.info("Unsupported file type for '%s' (no matcher)", ctx.path)
     return ctx

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/steps/stripper.py

@@ -44,9 +44,6 @@ def strip(ctx: ProcessingContext) -> ProcessingContext:
     if ctx.status.header not in [HeaderStatus.EMPTY, HeaderStatus.DETECTED]:
         # No header to be stripped
         ctx.status.strip = StripStatus.FAILED
-        ctx.diagnostics.append(
-            f"stripper: skipping {ctx.path}, header status is {ctx.status.header.value}"
-        )
         return ctx
 
     if ctx.header_processor is None:
@@ -70,7 +67,5 @@ def strip(ctx: ProcessingContext) -> ProcessingContext:
     ctx.updated_file_lines = new_lines
     # A header was present and removed
     ctx.status.strip = StripStatus.READY
-    ctx.diagnostics.append(
-        f"stripper: removed header lines at span {removed[0]}..{removed[1]} in {ctx.path}"
-    )
+    logger.debug(f"stripper: removed header lines at span {removed[0]}..{removed[1]}.")
     return ctx

{topmark-0.3.2 → topmark-0.4.0}/src/topmark/pipeline/steps/updater.py

@@ -64,7 +64,7 @@ def _prepend_bom_to_lines_if_needed(lines: list[str], ctx: ProcessingContext) ->
     if ctx.has_shebang:
         # Do not re-add the BOM which was stripped in reader.read(); a valid shebang
         # must start at byte 0 on POSIX systems.
-        ctx.diagnostics.append(
+        ctx.add_error(
             "UTF-8 BOM appears before the shebang; POSIX requires '#!' at byte 0. "
             "TopMark will not modify this file by default. Consider removing the BOM "
             "or using a future '--fix-bom' option to resolve this conflict."
@@ -118,12 +118,12 @@ def update(ctx: ProcessingContext) -> ProcessingContext:
 
     # Non-strip processing
     if ctx.expected_header_lines is None:
-        ctx.diagnostics.append("Cannot update header: no rendered header available")
+        ctx.add_error("Cannot update header: no rendered header available")
         ctx.status.write = WriteStatus.SKIPPED
         return ctx
 
     if ctx.header_processor is None:
-        ctx.diagnostics.append("Cannot update header: no header processor assigned")
+        ctx.add_error("Cannot update header: no header processor assigned")
         ctx.status.write = WriteStatus.SKIPPED
         return ctx
 
@@ -186,7 +186,7 @@ def update(ctx: ProcessingContext) -> ProcessingContext:
         insert_index = ctx.header_processor.get_header_insertion_index(original_lines)
         if insert_index == NO_LINE_ANCHOR:
             ctx.status.write = WriteStatus.FAILED
-            ctx.diagnostics.append(f"No line-based insertion anchor for file: {ctx.path}")
+            ctx.add_error(f"No line-based insertion anchor for file: {ctx.path}")
             return ctx
 
         # defensive clamp

{topmark-0.3.2 → topmark-0.4.0/src/topmark.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.3.2
+Version: 0.4.0
 Summary: A Python CLI to inspect, validate, and manage license and copyright headers.
 Author-email: Olivier Biot <olivier.biot@gmail.com>
 License-Expression: MIT

{topmark-0.3.2 → topmark-0.4.0}/src/topmark.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ src/topmark/cli/commands/show_defaults.py
 src/topmark/cli/commands/strip.py
 src/topmark/cli/commands/version.py
 src/topmark/cli_shared/__init__.py
+src/topmark/cli_shared/console.py
 src/topmark/cli_shared/exit_codes.py
 src/topmark/cli_shared/utils.py
 src/topmark/config/__init__.py