topmark 0.6.2__tar.gz → 0.8.0__tar.gz

{topmark-0.6.2/src/topmark.egg-info → topmark-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.6.2
+Version: 0.8.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
@@ -79,6 +79,73 @@ Full documentation is available on Read the Docs: <https://topmark.readthedocs.i
 This README is the canonical, complete introduction for GitHub/PyPI. The docs site provides a
 concise landing page and deep links into topics (install, usage, CI, API, etc.).
 
+## 📝 Example headers
+
+TopMark inserts headers that are tailored to the comment style and conventions of each file type
+(line comments like `#`/`//`, and block comments like `/* … */`). Here are examples of how TopMark
+headers appear in different file formats:
+
+```bash
+#!/bin/bash
+
+# topmark:header:start
+#
+#   project   : TopMark
+#   file      : script.sh
+#   license   : MIT
+#   copyright : (c) 2025 Olivier Biot
+
+# topmark:header:end
+
+echo "Hello, World!"
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+topmark:header:start
+
+  project   : TopMark
+  file      : config.xml
+  license   : MIT
+  copyright : (c) 2025 Olivier Biot
+
+topmark:header:end
+-->
+
+<configuration>
+    <!-- XML content here -->
+</configuration>
+```
+
+```javascript
+// topmark:header:start
+//
+//   project   : TopMark
+//   file      : app.js
+//   license   : MIT
+//   copyright : (c) 2025 Olivier Biot
+//
+// topmark:header:end
+
+console.log("Hello, World!");
+```
+
+```css
+/*
+ * topmark:header:start
+ *
+ *   project   : TopMark
+ *   file      : styles.css
+ *   license   : MIT
+ *   copyright : (c) 2025 Olivier Biot
+ *
+ * topmark:header:end
+ */
+
+body { margin: 0; }
+```
+
 ## ✨ Features
 
 - File header detection, insertion, and replacement
@@ -193,9 +260,12 @@ topmark show-defaults
 # Output a starter configuration to stdout
 topmark init-config
 
-# Show TopMark version in JSON format
+# Output TopMark version (PEP 440) in JSON format
 topmark version --format json
 
+# Output TopMark version (SemVer) to stdout
+topmark version --semver
+
 # Apply changes to files in-place
 topmark check --apply src/
 

{topmark-0.6.2 → topmark-0.8.0}/README.md

@@ -28,6 +28,73 @@ Full documentation is available on Read the Docs: <https://topmark.readthedocs.i
 This README is the canonical, complete introduction for GitHub/PyPI. The docs site provides a
 concise landing page and deep links into topics (install, usage, CI, API, etc.).
 
+## 📝 Example headers
+
+TopMark inserts headers that are tailored to the comment style and conventions of each file type
+(line comments like `#`/`//`, and block comments like `/* … */`). Here are examples of how TopMark
+headers appear in different file formats:
+
+```bash
+#!/bin/bash
+
+# topmark:header:start
+#
+#   project   : TopMark
+#   file      : script.sh
+#   license   : MIT
+#   copyright : (c) 2025 Olivier Biot
+
+# topmark:header:end
+
+echo "Hello, World!"
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+topmark:header:start
+
+  project   : TopMark
+  file      : config.xml
+  license   : MIT
+  copyright : (c) 2025 Olivier Biot
+
+topmark:header:end
+-->
+
+<configuration>
+    <!-- XML content here -->
+</configuration>
+```
+
+```javascript
+// topmark:header:start
+//
+//   project   : TopMark
+//   file      : app.js
+//   license   : MIT
+//   copyright : (c) 2025 Olivier Biot
+//
+// topmark:header:end
+
+console.log("Hello, World!");
+```
+
+```css
+/*
+ * topmark:header:start
+ *
+ *   project   : TopMark
+ *   file      : styles.css
+ *   license   : MIT
+ *   copyright : (c) 2025 Olivier Biot
+ *
+ * topmark:header:end
+ */
+
+body { margin: 0; }
+```
+
 ## ✨ Features
 
 - File header detection, insertion, and replacement
@@ -142,9 +209,12 @@ topmark show-defaults
 # Output a starter configuration to stdout
 topmark init-config
 
-# Show TopMark version in JSON format
+# Output TopMark version (PEP 440) in JSON format
 topmark version --format json
 
+# Output TopMark version (SemVer) to stdout
+topmark version --semver
+
 # Apply changes to files in-place
 topmark check --apply src/
 

{topmark-0.6.2 → topmark-0.8.0}/pyproject.toml

@@ -10,7 +10,7 @@
 
 [project]
 name = "topmark"
-version = "0.6.2"
+version = "0.8.0" # PEP 440: "X.Y.Z.devN", "X.Y.ZrcN", or "X.Y.Z"
 description = "A Python CLI to inspect, validate, and manage license and copyright headers."
 authors = [{ name = "Olivier Biot", email = "olivier.biot@gmail.com" }]
 license = "MIT"

{topmark-0.6.2 → topmark-0.8.0}/src/topmark/__init__.py

@@ -12,3 +12,5 @@
 
 Provides tools and utilities for evaluating and benchmarking models and algorithms.
 """
+
+from __future__ import annotations

{topmark-0.6.2 → topmark-0.8.0}/src/topmark/api/__init__.py

@@ -65,7 +65,7 @@ from __future__ import annotations
 
 from dataclasses import replace
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Iterable, Sequence, cast
+from typing import TYPE_CHECKING, Any, Iterable, Mapping, Sequence, cast
 
 from topmark.cli.cmd_common import (
     filter_view_results,
@@ -74,7 +74,7 @@ from topmark.cli.cmd_common import (
 from topmark.cli.io import InputPlan
 from topmark.cli_shared.utils import write_updates
 from topmark.config import Config, MutableConfig
-from topmark.config.logging import get_logger
+from topmark.config.logging import TopmarkLogger, get_logger
 from topmark.constants import TOPMARK_VERSION
 from topmark.pipeline.context import (
     ComparisonStatus,
@@ -90,10 +90,12 @@ from .types import DiagnosticTotals, FileResult, FileTypeInfo, Outcome, Processo
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
 
-logger = get_logger(__name__)
+    from topmark.cli_shared.exit_codes import ExitCode
 
+logger: TopmarkLogger = get_logger(__name__)
 
-__all__ = [
+
+__all__: list[str] = [
     "Outcome",
     "FileResult",
     "RunResult",
@@ -174,7 +176,7 @@ def _map_outcome(r: ProcessingContext, *, apply: bool) -> Outcome:
     """
     if r.status.file is not FileStatus.RESOLVED:
         # Treat unsupported/matched-but-unhandled types as non-errors for API consumers.
-        unsupported = {
+        unsupported: set[FileStatus] = {
             FileStatus.SKIPPED_UNSUPPORTED,
             FileStatus.SKIPPED_KNOWN_NO_HEADERS,
         }
@@ -194,8 +196,8 @@ def _map_outcome(r: ProcessingContext, *, apply: bool) -> Outcome:
 def _to_file_result(r: ProcessingContext, *, apply: bool) -> FileResult:
     """Convert a ProcessingContext into a FileResult."""
     # Prefer a unified diff when available; otherwise None (human views may omit diffs).
-    diff = r.header_diff or None
-    message = getattr(r, "summary", None)
+    diff: str | None = r.header_diff or None
+    message: str | None = r.summary or None
     return FileResult(
         path=Path(str(r.path)), outcome=_map_outcome(r, apply=apply), diff=diff, message=message
     )
@@ -216,7 +218,7 @@ def _run_pipeline(
     base_config: Mapping[str, Any] | Config | None,
     file_types: Sequence[str] | None,
     apply_changes: bool,
-) -> tuple[Config, list[Path], list[ProcessingContext], object | None]:
+) -> tuple[Config, list[Path], list[ProcessingContext], ExitCode | None]:
     """Resolve config + files, register processors, and run the pipeline.
 
     - Uses the same planner/resolver as the CLI (via `build_config_and_file_list`)
@@ -232,14 +234,16 @@ def _run_pipeline(
         apply_changes (bool): True if changes should be applied, False if dry-run.
 
     Returns:
-        tuple[Config, list[Path], list[ProcessingContext], object | None]: Tuple containing:
+        tuple[Config, list[Path], list[ProcessingContext], ExitCode | None]: Tuple containing:
             - the resulting Config object;
             - the resolved (optionally filtered if `file_types` was specified) list of paths
               to process;
             - the results of running the pipeline as list of `ProcessingContext` instances;
-            - the encountered error code
+            - the encountered `ExitCode` error code
     """
     logger.info("Building config and file list for paths: %s", paths)
+    cfg: Config
+    file_list: list[Path]
     cfg, file_list = _build_cfg_and_files_via_cli_helpers(
         paths, base_config=base_config, file_types=file_types
     )
@@ -253,8 +257,10 @@ def _run_pipeline(
     Registry.ensure_processors_registered()
 
     # Use a snapshot that carries the apply intent
-    cfg_for_run = replace(cfg, apply_changes=apply_changes)
+    cfg_for_run: Config = replace(cfg, apply_changes=apply_changes)
 
+    results: list[ProcessingContext] = []
+    encountered_error_code: ExitCode | None
     results, encountered_error_code = run_steps_for_files(
         file_list, pipeline_name=pipeline_name, config=cfg_for_run
     )
@@ -275,10 +281,10 @@ def _apply_view_filter(
     `skipped_count` equals `len(results) - len(filtered_results)` and reflects only
     view-level filtering (not internal SKIPPED statuses).
     """
-    view_results = filter_view_results(
+    view_results: list[ProcessingContext] = filter_view_results(
         results, skip_compliant=skip_compliant, skip_unsupported=skip_unsupported
     )
-    skipped = len(results) - len(view_results)
+    skipped: int = len(results) - len(view_results)
     return view_results, skipped
 
 
@@ -305,19 +311,21 @@ def _collect_diagnostic_totals(results: list[ProcessingContext]) -> DiagnosticTo
     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
+    total_info: int = 0
+    total_warn: int = 0
+    total_error: int = 0
     for r in results:
         if not r.diagnostics:
             continue
         for d in r.diagnostics:
-            lv = d.level.value
+            lv: str = 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
+    total: int = total_info + total_warn + total_error
     return {"info": total_info, "warning": total_warn, "error": total_error, "total": total}
 
 
@@ -362,7 +370,7 @@ def _build_cfg_and_files_via_cli_helpers(
     # normalization of paths.
     if base_config is not None:
         # Start from defaults so that header fields/values are present unless overridden
-        draft_defaults = MutableConfig.from_defaults()
+        draft_defaults: MutableConfig = MutableConfig.from_defaults()
         draft = draft_defaults.merge_with(
             draft
         )  # 'draft' came from _ensure_mutable_config(base_config)
@@ -372,8 +380,8 @@ def _build_cfg_and_files_via_cli_helpers(
         logger.debug("Found %d input paths", len(draft.files))
         if file_types:
             draft.file_types = set(file_types)
-        cfg = draft.freeze()
-        file_list = resolve_file_list(cfg)
+        cfg: Config = draft.freeze()
+        file_list: list[Path] = resolve_file_list(cfg)
         logger.debug("Files found: %s", len(file_list))
         return cfg, file_list
 
@@ -405,7 +413,7 @@ def _build_cfg_and_files_via_cli_helpers(
             local_toml = Path(local_toml_file)
             if local_toml.exists():
                 logger.info("Loading local config from: %s", local_toml)
-                local_config = MutableConfig.from_toml_file(local_toml)
+                local_config: MutableConfig | None = MutableConfig.from_toml_file(local_toml)
                 if local_config is not None:
                     draft = draft.merge_with(local_config)
                 break  # only first one
@@ -415,11 +423,11 @@ def _build_cfg_and_files_via_cli_helpers(
         "Sequence[str | Path]", args_mapping.get("config_files", ())
     )
     for entry in config_files_seq:
-        p = entry if isinstance(entry, Path) else Path(entry)
+        p: Path = entry if isinstance(entry, Path) else Path(entry)
         logger.debug("Adding config file '%s' (type=%s)", entry, type(entry).__name__)
         if p.exists():
             logger.info("Loading config override from: %s", p)
-            extra = MutableConfig.from_toml_file(p)
+            extra: MutableConfig | None = MutableConfig.from_toml_file(p)
             if extra is not None:
                 draft = draft.merge_with(extra)
         else:
@@ -475,6 +483,9 @@ def check(
         raise ValueError("Options add_only and update_only are mutually exclusive.")
 
     # Always use 'apply' pipeline to compute updated content even in dry-run
+    file_list: list[Path] = []
+    results: list[ProcessingContext] = []
+    encountered_error_code: ExitCode | None = None
     _, file_list, results, encountered_error_code = _run_pipeline(
         pipeline_name="apply",
         paths=paths,
@@ -485,20 +496,23 @@ def check(
     if not file_list:
         return RunResult(files=(), summary={}, had_errors=False)
 
+    view_results: list[ProcessingContext]
+    skipped: int
     view_results, skipped = _apply_view_filter(
         results, skip_compliant=skip_compliant, skip_unsupported=skip_unsupported
     )
 
-    files = tuple(_to_file_result(r, apply=apply) for r in view_results)
-    summary = _summarize(files)
-    had_errors = any(_map_outcome(r, apply=apply) is Outcome.ERROR for r in results) or (
+    files: tuple[FileResult, ...] = tuple(_to_file_result(r, apply=apply) for r in view_results)
+    summary: Mapping[str, int] = _summarize(files)
+    had_errors: bool = any(_map_outcome(r, apply=apply) is Outcome.ERROR for r in results) or (
         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)
+    diagnostics: dict[str, list[PublicDiagnostic]] = _collect_diagnostics(view_results)
+    diagnostic_totals: DiagnosticTotals = _collect_diagnostic_totals(view_results)
+    diagnostic_totals_all: DiagnosticTotals = _collect_diagnostic_totals(results)
 
-    written = failed = 0
+    written: int = 0
+    failed: int = 0
     if apply:
 
         def _should_write_check(r: ProcessingContext) -> bool:
@@ -559,6 +573,9 @@ def strip(
         pipeline write decisions.
     """
     # The 'strip' pipeline computes removal-ready updates even in dry-run
+    file_list: list[Path] = []
+    results: list[ProcessingContext] = []
+    encountered_error_code: ExitCode | None = None
     _, file_list, results, encountered_error_code = _run_pipeline(
         pipeline_name="strip",
         paths=paths,
@@ -569,20 +586,23 @@ def strip(
     if not file_list:
         return RunResult(files=(), summary={}, had_errors=False)
 
+    view_results: list[ProcessingContext]
+    skipped: int = 0
     view_results, skipped = _apply_view_filter(
         results, skip_compliant=skip_compliant, skip_unsupported=skip_unsupported
     )
 
-    files = tuple(_to_file_result(r, apply=apply) for r in view_results)
-    summary = _summarize(files)
-    had_errors = any(_map_outcome(r, apply=apply) is Outcome.ERROR for r in results) or (
+    files: tuple[FileResult, ...] = tuple(_to_file_result(r, apply=apply) for r in view_results)
+    summary: Mapping[str, int] = _summarize(files)
+    had_errors: bool = any(_map_outcome(r, apply=apply) is Outcome.ERROR for r in results) or (
         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)
+    diagnostics: dict[str, list[PublicDiagnostic]] = _collect_diagnostics(view_results)
+    diagnostic_totals: DiagnosticTotals = _collect_diagnostic_totals(view_results)
+    diagnostic_totals_all: DiagnosticTotals = _collect_diagnostic_totals(results)
 
-    written = failed = 0
+    written: int = 0
+    failed: int = 0
     if apply:
 
         def _should_write_strip(r: ProcessingContext) -> bool:
@@ -625,7 +645,7 @@ def get_filetype_info(long: bool = False) -> list[FileTypeInfo]:
     for name, ft in Registry.filetypes().items():
         processor = proc_reg.get(name, None) if proc_reg else None
         supported = bool(processor)
-        processor_name = processor.__class__.__name__ if processor else None
+        processor_name: str | None = processor.__class__.__name__ if processor else None
         info: FileTypeInfo = {
             "name": name,
             "description": getattr(ft, "description", ""),

{topmark-0.6.2 → topmark-0.8.0}/src/topmark/cli/__init__.py

@@ -26,4 +26,4 @@ from __future__ import annotations
 
 from .main import cli
 
-__all__ = ["cli"]
+__all__: list[str] = ["cli"]

{topmark-0.6.2 → topmark-0.8.0}/src/topmark/cli/cli_types.py

@@ -213,7 +213,7 @@ class EnumChoiceParam(ParamTypeBase, Generic[E]):
             for choice in cast("Iterable[E]", self.enum_cls)
         }
 
-        key = value.lower()
+        key: str = value.lower()
         if key in lookup:
             return lookup[key]
 
@@ -240,7 +240,7 @@ class EnumChoiceParam(ParamTypeBase, Generic[E]):
             CompletionItem as RuntimeCompletionItem,
         )  # Click 8.x
 
-        prefix = (incomplete or "").lower()
+        prefix: str = (incomplete or "").lower()
         items: list["ClickCompletionItem"] = []
         for e in cast("Iterable[E]", self.enum_cls):
             val = str(getattr(e, "value", e))

{topmark-0.6.2 → topmark-0.8.0}/src/topmark/cli/cmd_common.py

@@ -24,20 +24,23 @@ import click
 from topmark.cli.config_resolver import resolve_config_from_click
 from topmark.cli.console_helpers import get_console_safely
 from topmark.cli_shared.exit_codes import ExitCode
-from topmark.config.logging import get_logger
+from topmark.config.logging import TopmarkLogger, get_logger
 from topmark.file_resolver import resolve_file_list
 from topmark.pipeline import runner
 from topmark.pipeline.context import ComparisonStatus, FileStatus, ProcessingContext
 from topmark.pipeline.pipelines import get_pipeline
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
     from pathlib import Path
 
     from topmark.cli.io import InputPlan
+    from topmark.cli_shared.console_api import ConsoleLike
     from topmark.config import Config, MutableConfig
+    from topmark.pipeline.contracts import Step
     from topmark.rendering.formats import HeaderOutputFormat
 
-logger = get_logger(__name__)
+logger: TopmarkLogger = get_logger(__name__)
 
 
 def get_effective_verbosity(ctx: click.Context, config: "Config | None" = None) -> int:
@@ -48,7 +51,7 @@ def get_effective_verbosity(ctx: click.Context, config: "Config | None" = None)
         2. ctx.obj["verbosity_level"] if present
         3. 0 (terse)
     """
-    cfg_level = getattr(config, "verbosity_level", None) if config else None
+    cfg_level: int | None = config.verbosity_level if config else None
     if cfg_level is not None:
         return int(cfg_level)
     return int(ctx.obj.get("verbosity_level", 0))
@@ -83,8 +86,8 @@ def run_steps_for_files(
         ENCODING_ERROR → UnicodeDecodeError
         PIPELINE_ERROR → any other unexpected exception
     """
-    console = get_console_safely()
-    steps = get_pipeline(pipeline_name)
+    console: ConsoleLike = get_console_safely()
+    steps: Sequence[Step] = get_pipeline(pipeline_name)
     results: list[ProcessingContext] = []
     encountered_error_code: ExitCode | None = None
 

{topmark-0.6.2 → topmark-0.8.0}/src/topmark/cli/commands/check.py

@@ -58,7 +58,7 @@ from topmark.cli.cmd_common import (
     run_steps_for_files,
 )
 from topmark.cli.errors import TopmarkIOError, TopmarkUsageError
-from topmark.cli.io import plan_cli_inputs
+from topmark.cli.io import InputPlan, plan_cli_inputs
 from topmark.cli.options import (
     CONTEXT_SETTINGS,
     common_config_options,
@@ -80,7 +80,7 @@ from topmark.cli_shared.utils import (
     safe_unlink,
     write_updates,
 )
-from topmark.config.logging import get_logger
+from topmark.config.logging import TopmarkLogger, get_logger
 from topmark.pipeline.context import (
     ComparisonStatus,
     FileStatus,
@@ -90,10 +90,13 @@ from topmark.pipeline.context import (
 )
 
 if TYPE_CHECKING:
+    from pathlib import Path
+
     from topmark.cli_shared.console_api import ConsoleLike
+    from topmark.config import Config, MutableConfig
     from topmark.rendering.formats import HeaderOutputFormat
 
-logger = get_logger(__name__)
+logger: TopmarkLogger = get_logger(__name__)
 
 
 @click.command(
@@ -236,7 +239,7 @@ def check_command(
         PIPELINE_ERROR (70): An internal processing step failed.
         UNEXPECTED_ERROR (255): An unhandled error occurred.
     """
-    ctx = click.get_current_context()
+    ctx: click.Context = click.get_current_context()
     ctx.ensure_object(dict)
     console: ConsoleLike = ctx.obj["console"]
 
@@ -253,7 +256,7 @@ def check_command(
         )
 
     # === Build Config and file list ===
-    plan = plan_cli_inputs(
+    plan: InputPlan = plan_cli_inputs(
         ctx=ctx,
         files_from=files_from,
         include_from=include_from,
@@ -262,7 +265,7 @@ def check_command(
         exclude_patterns=exclude_patterns,
         stdin_filename=stdin_filename,
     )
-    draft_config = build_config_common(
+    draft_config: MutableConfig = build_config_common(
         ctx=ctx,
         plan=plan,
         no_config=no_config,
@@ -276,18 +279,18 @@ def check_command(
     # Propagate runtime intent for updater (terminal vs preview write status)
     draft_config.apply_changes = bool(apply_changes)
 
-    config = draft_config.freeze()
+    config: Config = draft_config.freeze()
 
-    temp_path = plan.temp_path  # for cleanup/STDIN-apply branch
-    stdin_mode = plan.stdin_mode
-    file_list = build_file_list(
+    temp_path: Path | None = plan.temp_path  # for cleanup/STDIN-apply branch
+    stdin_mode: bool = plan.stdin_mode
+    file_list: list[Path] = build_file_list(
         config,
         stdin_mode=stdin_mode,
         temp_path=temp_path,
     )
 
     # Determine effective program-output verbosity for gating extra details
-    vlevel = get_effective_verbosity(ctx, config)
+    vlevel: int = get_effective_verbosity(ctx, config)
 
     logger.trace("Config after merging args and resolving file list: %s", config)
 
@@ -304,7 +307,7 @@ def check_command(
 
     # Always run the 'apply' pipeline when --apply is set so updated_file_lines are computed.
     # The --summary flag only affects how we render output, not which steps run.
-    pipeline_name = "apply" if apply_changes else ("summary" if summary_mode else "apply")
+    pipeline_name: str = "apply" if apply_changes else ("summary" if summary_mode else "apply")
     results: list[ProcessingContext] = []
     encountered_error_code: ExitCode | None = None
 
@@ -313,7 +316,7 @@ def check_command(
     )
 
     # Optional filtering
-    view_results = filter_view_results(
+    view_results: list[ProcessingContext] = filter_view_results(
         results, skip_compliant=skip_compliant, skip_unsupported=skip_unsupported
     )
 
@@ -358,8 +361,8 @@ def check_command(
         return
 
     if apply_changes:
-        written = 0
-        failed = 0
+        written: int = 0
+        failed: int = 0
 
         def _should_write_check(r: ProcessingContext) -> bool:
             """Determine whether to write this file in check mode."""
@@ -376,7 +379,7 @@ def check_command(
         written, failed = write_updates(results, should_write=_should_write_check)
 
         if fmt == OutputFormat.DEFAULT:
-            msg = (
+            msg: str = (
                 f"\n✅ Applied changes to {written} file(s)."
                 if written
                 else "\n✅ No changes to apply."