topmark 0.1.1__tar.gz → 0.2.0__tar.gz

{topmark-0.1.1/src/topmark.egg-info → topmark-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.1.1
+Version: 0.2.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
@@ -127,6 +127,15 @@ Logging verbosity is controlled globally:
 All other options, such as `--stdin`, `--file-type`, and path filters, are specific to individual
 subcommands like `check` or `apply`.
 
+### Skipping and filtering helpers
+
+These switches help keep CI output meaningful and fast:
+
+- `--skip-compliant` — hide files that are already compliant; only show items that need attention.
+- `--skip-unsupported` — hide unsupported file types and files matched by known types that
+  intentionally **do not** support headers (e.g., strict JSON). They remain **recognized** but are
+  not listed in results.
+
 ### Examples
 
 ```bash
@@ -159,6 +168,12 @@ topmark version
 
 # Apply changes to files in-place
 topmark --apply src/
+
+# CI-friendly summary: only show issues; ignore unsupported types
+topmark --skip-compliant --skip-unsupported src/
+
+# Apply fixes for only the changed files passed by pre-commit
+topmark --apply --apply --skip-unsupported --quiet
 ```
 
 ## 📐 Header placement rules
@@ -249,10 +264,79 @@ The following options can be used with most commands.
 
 ## 🧩 Supported file types
 
-| Processor            | File types (examples)                                                      |
-| -------------------- | -------------------------------------------------------------------------- |
-| PoundHeaderProcessor | python, shell, ruby, r, julia, perl, makefile, dockerfile, yaml, toml, env |
-| XmlHeaderProcessor   | xml, xhtml, html, svg, xsl/xslt, vue, svelte, markdown                     |
+| Processor            | File types (examples)                                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------------------------------- |
+| PoundHeaderProcessor | dockerfile, env, git-meta, ini, julia, makefile, perl, python, python-requirements, r, ruby, shell, toml, yaml |
+| SlashHeaderProcessor | c, cpp, cs, go, java, javascript, kotlin, rust, swift, typescript, vscode-jsonc                                |
+| XmlHeaderProcessor   | html, markdown, svelte, svg, vue, xhtml, xml, xsl, xslt, yaml                                                  |
+
+Some formats (e.g., strict JSON) are **recognized but intentionally skipped** because they lack a
+safe comment syntax. Use `--skip-unsupported` to hide them from the report while keeping safety.
+
+For a complete list, please run:
+
+```sh
+topmark filetypes
+```
+
+### How TopMark resolves file types (specificity & safety)
+
+TopMark may have multiple `FileType` definitions that **match** a given path. The resolver now:
+
+- evaluates **all** matching file types and scores them by **specificity**,
+- prefers **explicit filenames / tail subpaths** (e.g., `.vscode/settings.json`) over patterns, and
+  **patterns** over simple **extensions**,
+- breaks ties in favor of **headerable** types (those without `skip_processing=True`).
+
+**Tail subpath matching.** `FileType.filenames` entries that contain a path separator (e.g.,
+`".vscode/settings.json"`) are matched as **path suffixes** against `path.as_posix()`; plain names
+still match the **basename** only.
+
+**JSON vs JSONC.** Generic `json` is recognized but marked `skip_processing=True` (no comments in
+strict JSON), while `vscode-jsonc` is a safe, **narrow** opt‑in that uses `//` headers. If you need
+more JSON-with-comments files, add them via a dedicated `FileType` or an explicit allow‑list in
+config.
+
+**Shebang‑aware insertion.** The default insertion logic is policy‑driven and shebang‑aware (insert
+after `#!` and optional encoding line). For formats like XML that need character‑precise placement,
+processors provide a text‑offset path; `XmlHeaderProcessor` uses this and signals **no line
+anchor**.
+
+## 🪝 Pre-commit integration
+
+TopMark provides first-class pre-commit hooks. A minimal consumer configuration:
+
+```yaml
+# .pre-commit-config.yaml (in a consuming repository)
+repos:
+  - repo: https://github.com/shutterfreak/topmark
+    rev: v0.2.0   # pin to a released tag
+    hooks:
+      - id: topmark-check
+        # Optional: limit scope to supported text types
+        # files: '\\.(py|md|toml|ya?ml|sh|Makefile)$'
+```
+
+Hooks shipped by this repo:
+
+- **`topmark-check`** — non-destructive validation. Recommended on `pre-commit` / `pre-push`.
+- **`topmark-apply`** — destructive, requires `--apply`. Marked `manual` so it only runs when you
+  call it explicitly.
+
+**Run the manual hook locally:**
+
+```bash
+# On the whole repo
+pre-commit run topmark-apply --all-files --hook-stage manual
+
+# On specific files
+pre-commit run topmark-apply --files path/to/file1 path/to/file2 --hook-stage manual
+```
+
+**Why does the hook seem to run multiple times?** Pre-commit batches filenames to avoid OS
+argument-length limits. You may see repeated banners (e.g., “Processing N file(s)”) as the hook runs
+once per batch. To run **once** per repo, set `pass_filenames: false` in the hook manifest and let
+TopMark discover files itself.
 
 ## 🛠 Configuration
 

{topmark-0.1.1 → topmark-0.2.0}/README.md

@@ -78,6 +78,15 @@ Logging verbosity is controlled globally:
 All other options, such as `--stdin`, `--file-type`, and path filters, are specific to individual
 subcommands like `check` or `apply`.
 
+### Skipping and filtering helpers
+
+These switches help keep CI output meaningful and fast:
+
+- `--skip-compliant` — hide files that are already compliant; only show items that need attention.
+- `--skip-unsupported` — hide unsupported file types and files matched by known types that
+  intentionally **do not** support headers (e.g., strict JSON). They remain **recognized** but are
+  not listed in results.
+
 ### Examples
 
 ```bash
@@ -110,6 +119,12 @@ topmark version
 
 # Apply changes to files in-place
 topmark --apply src/
+
+# CI-friendly summary: only show issues; ignore unsupported types
+topmark --skip-compliant --skip-unsupported src/
+
+# Apply fixes for only the changed files passed by pre-commit
+topmark --apply --apply --skip-unsupported --quiet
 ```
 
 ## 📐 Header placement rules
@@ -200,10 +215,79 @@ The following options can be used with most commands.
 
 ## 🧩 Supported file types
 
-| Processor            | File types (examples)                                                      |
-| -------------------- | -------------------------------------------------------------------------- |
-| PoundHeaderProcessor | python, shell, ruby, r, julia, perl, makefile, dockerfile, yaml, toml, env |
-| XmlHeaderProcessor   | xml, xhtml, html, svg, xsl/xslt, vue, svelte, markdown                     |
+| Processor            | File types (examples)                                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------------------------------- |
+| PoundHeaderProcessor | dockerfile, env, git-meta, ini, julia, makefile, perl, python, python-requirements, r, ruby, shell, toml, yaml |
+| SlashHeaderProcessor | c, cpp, cs, go, java, javascript, kotlin, rust, swift, typescript, vscode-jsonc                                |
+| XmlHeaderProcessor   | html, markdown, svelte, svg, vue, xhtml, xml, xsl, xslt, yaml                                                  |
+
+Some formats (e.g., strict JSON) are **recognized but intentionally skipped** because they lack a
+safe comment syntax. Use `--skip-unsupported` to hide them from the report while keeping safety.
+
+For a complete list, please run:
+
+```sh
+topmark filetypes
+```
+
+### How TopMark resolves file types (specificity & safety)
+
+TopMark may have multiple `FileType` definitions that **match** a given path. The resolver now:
+
+- evaluates **all** matching file types and scores them by **specificity**,
+- prefers **explicit filenames / tail subpaths** (e.g., `.vscode/settings.json`) over patterns, and
+  **patterns** over simple **extensions**,
+- breaks ties in favor of **headerable** types (those without `skip_processing=True`).
+
+**Tail subpath matching.** `FileType.filenames` entries that contain a path separator (e.g.,
+`".vscode/settings.json"`) are matched as **path suffixes** against `path.as_posix()`; plain names
+still match the **basename** only.
+
+**JSON vs JSONC.** Generic `json` is recognized but marked `skip_processing=True` (no comments in
+strict JSON), while `vscode-jsonc` is a safe, **narrow** opt‑in that uses `//` headers. If you need
+more JSON-with-comments files, add them via a dedicated `FileType` or an explicit allow‑list in
+config.
+
+**Shebang‑aware insertion.** The default insertion logic is policy‑driven and shebang‑aware (insert
+after `#!` and optional encoding line). For formats like XML that need character‑precise placement,
+processors provide a text‑offset path; `XmlHeaderProcessor` uses this and signals **no line
+anchor**.
+
+## 🪝 Pre-commit integration
+
+TopMark provides first-class pre-commit hooks. A minimal consumer configuration:
+
+```yaml
+# .pre-commit-config.yaml (in a consuming repository)
+repos:
+  - repo: https://github.com/shutterfreak/topmark
+    rev: v0.2.0   # pin to a released tag
+    hooks:
+      - id: topmark-check
+        # Optional: limit scope to supported text types
+        # files: '\\.(py|md|toml|ya?ml|sh|Makefile)$'
+```
+
+Hooks shipped by this repo:
+
+- **`topmark-check`** — non-destructive validation. Recommended on `pre-commit` / `pre-push`.
+- **`topmark-apply`** — destructive, requires `--apply`. Marked `manual` so it only runs when you
+  call it explicitly.
+
+**Run the manual hook locally:**
+
+```bash
+# On the whole repo
+pre-commit run topmark-apply --all-files --hook-stage manual
+
+# On specific files
+pre-commit run topmark-apply --files path/to/file1 path/to/file2 --hook-stage manual
+```
+
+**Why does the hook seem to run multiple times?** Pre-commit batches filenames to avoid OS
+argument-length limits. You may see repeated banners (e.g., “Processing N file(s)”) as the hook runs
+once per batch. To run **once** per repo, set `pass_filenames: false` in the hook manifest and let
+TopMark discover files itself.
 
 ## 🛠 Configuration
 

{topmark-0.1.1 → topmark-0.2.0}/pyproject.toml

@@ -10,7 +10,7 @@
 
 [project]
 name = "topmark"
-version = "0.1.1"
+version = "0.2.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"
@@ -102,9 +102,11 @@ typing = [
 
 [tool.setuptools]
 package-dir = { "" = "src" }
+include-package-data = true
 
 [tool.setuptools.package-data]
 "topmark" = ["py.typed"]
+"topmark.config" = ["topmark-default.toml"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

{topmark-0.1.1 → topmark-0.2.0}/src/topmark/cli/commands/default.py

@@ -29,6 +29,8 @@ Examples:
     topmark --apply --diff .
 """
 
+import logging
+
 import click
 from yachalk import chalk
 
@@ -48,7 +50,7 @@ from topmark.cli.utils import (
 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.context import ComparisonStatus, FileStatus, HeaderStatus, ProcessingContext
 from topmark.pipeline.pipelines import get_pipeline
 from topmark.rendering.formats import HeaderOutputFormat
 
@@ -75,6 +77,13 @@ logger = get_logger(__name__)
     help="Hide files that are already up-to-date.",
 )
 @underscored_trap_option("--skip_compliant")
+@typed_option(
+    "--skip-unsupported",
+    "skip_unsupported",
+    is_flag=True,
+    help="Hide unsupported file types.",
+)
+@underscored_trap_option("--skip_unsupported")
 @typed_option(
     "--format",
     "output_format",
@@ -98,6 +107,7 @@ def default_command(
     diff: bool,
     summary_mode: bool,
     skip_compliant: bool,
+    skip_unsupported: bool,
     output_format: OutputFormat | None,
 ) -> None:
     """Run the unified default command (check/apply).
@@ -121,6 +131,7 @@ def default_command(
       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.
+      skip_unsupported: If True, suppress unsupported file types.
       output_format: Output format to use (default, json, or ndjson).
 
     Raises:
@@ -182,11 +193,12 @@ def default_command(
     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"))
+        click.echo(chalk.blue("\nℹ️  No files to process.\n"))
         raise SystemExit(0)
 
-    click.echo(chalk.blue(f"\nProcessing {len(file_list)} file(s):\n"))
-    click.echo(chalk.bold.underline("TopMark Results:"))
+    if logger.isEnabledFor(logging.INFO):
+        click.echo(chalk.blue(f"\n🔍 Processing {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"
@@ -200,16 +212,16 @@ def default_command(
             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}"))
+            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}"))
+            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)")
+                chalk.red(f"⚠️  Unexpected error processing {path}: {e} (use -vv for traceback)")
             )
             continue
 
@@ -219,6 +231,17 @@ def default_command(
     else:
         view_results = results
 
+    if skip_unsupported:
+        view_results = [
+            r
+            for r in view_results
+            if r.status.file
+            not in [
+                FileStatus.SKIPPED_UNSUPPORTED,
+                FileStatus.SKIPPED_KNOWN_NO_HEADERS,
+            ]
+        ]
+
     fmt: OutputFormat = output_format or OutputFormat.DEFAULT
     # Machine formats first
     if fmt is OutputFormat.NDJSON:
@@ -256,6 +279,18 @@ def default_command(
         else:
             for r in view_results:
                 click.echo(r.summary)
+                if r.status.comparison == ComparisonStatus.CHANGED:
+                    if apply_changes:
+                        if r.status.header == HeaderStatus.MISSING:
+                            click.echo(chalk.yellow(f"   ➕ Adding header for '{r.path}'"))
+                        else:
+                            click.echo(chalk.yellow(f"   ✏️  Updating header for '{r.path}'"))
+                    else:
+                        click.echo(
+                            chalk.yellow(
+                                f"   🛠️  Run `topmark --apply {r.path}` to update this file."
+                            )
+                        )
             if diff:
                 for r in view_results:
                     if r.header_diff:
@@ -277,7 +312,11 @@ def default_command(
                 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."
+                (
+                    f"\n✅ Applied changes to {written} file(s)."
+                    if written
+                    else "\n✅ No changes to apply."
+                )
             )
         if failed:
             raise SystemExit(1)
@@ -291,5 +330,7 @@ def default_command(
         if would_change:
             raise SystemExit(2)
 
-    click.echo("All done!")
+    if logger.isEnabledFor(logging.INFO):
+        click.echo("✅ All done!")
+
     return

{topmark-0.1.1 → topmark-0.2.0}/src/topmark/cli/main.py

@@ -184,6 +184,13 @@ CONTEXT_SETTINGS = dict(
     help="Hide files that are already up-to-date.",
 )
 @underscored_trap_option("--skip_compliant")
+@typed_option(
+    "--skip-unsupported",
+    "skip_unsupported",
+    is_flag=True,
+    help="Hide unsupported file types.",
+)
+@underscored_trap_option("--skip_unsupported")
 @typed_option(
     "--format",
     "output_format",
@@ -227,6 +234,7 @@ def cli(
     diff: bool,
     summary_mode: bool,
     skip_compliant: bool,
+    skip_unsupported: bool,
     output_format: OutputFormat | None,
 ) -> None:
     """
@@ -257,6 +265,7 @@ def cli(
         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.
+        skip_unsupported: If True, suppress unsupported file types.
         output_format: Output format to use (default, json, or ndjson).
 
     Notes:
@@ -331,6 +340,7 @@ def cli(
         diff=diff,
         summary_mode=summary_mode,
         skip_compliant=skip_compliant,
+        skip_unsupported=skip_unsupported,
         output_format=output_format,
     )
     return
@@ -395,6 +405,7 @@ def ensure_commands_registered() -> None:
             diff=p.get("diff", False),
             summary_mode=p.get("summary_mode", False),
             skip_compliant=p.get("skip_compliant", False),
+            skip_unsupported=p.get("skip_unsupported", False),
             output_format=p.get("output_format"),
         )
 

{topmark-0.1.1 → topmark-0.2.0}/src/topmark/config/__init__.py

@@ -21,17 +21,17 @@ from topmark.toml or pyproject.toml.
 import functools
 from dataclasses import dataclass, field
 from datetime import datetime
+from importlib.resources import files
 from pathlib import Path
 from typing import Any, TypeGuard
 
 import toml
 
 from topmark.cli.cli_types import ArgsNamespace
-from topmark.constants import DEFAULT_TOML_CONFIG_PATH, VALUE_NOT_SET
+from topmark.config.logging import get_logger
+from topmark.constants import DEFAULT_TOML_CONFIG_RESOURCE, VALUE_NOT_SET
 from topmark.rendering.formats import HeaderOutputFormat
 
-from .logging import get_logger
-
 logger = get_logger(__name__)
 
 
@@ -103,8 +103,9 @@ class Config:
         Returns:
             str: The contents of the default TOML configuration file.
         """
-        logger.debug("Loading defaults from %s", DEFAULT_TOML_CONFIG_PATH)
-        return DEFAULT_TOML_CONFIG_PATH.read_text(encoding="utf-8")
+        logger.debug("Loading defaults from package resource: %s", DEFAULT_TOML_CONFIG_RESOURCE)
+        resource = files("topmark.config") / DEFAULT_TOML_CONFIG_RESOURCE
+        return resource.read_text(encoding="utf-8")
 
     @classmethod
     def to_cleaned_toml(cls, toml_doc: str) -> str:
@@ -122,7 +123,7 @@ class Config:
         return toml.dumps(parsed)
 
     @classmethod
-    @functools.cache  # Cache to avoid re-parsing defaults multiple times
+    @functools.cache
     def from_defaults(cls) -> "Config":
         """
         Load the default configuration from the bundled topmark-default.toml file.
@@ -130,12 +131,16 @@ class Config:
         Returns:
             Config: A Config instance populated with default values.
         """
-        default_toml_data = toml.load(DEFAULT_TOML_CONFIG_PATH)
+        resource = files("topmark.config") / DEFAULT_TOML_CONFIG_RESOURCE
+        default_toml_text = resource.read_text(encoding="utf-8")
+        default_toml_data = toml.loads(default_toml_text)
         logger.debug("Default Config: %s", default_toml_data)
-        # When loading defaults, explicitly include defaults flag to allow special handling
+
+        # Note: `config_file` is set to None because this is a package resource,
+        # not a user-specified filesystem path.
         return cls.from_toml_dict(
             default_toml_data,
-            config_file=DEFAULT_TOML_CONFIG_PATH,
+            config_file=None,
             use_defaults=True,  # We ONLY include defaults when loading from defaults!
         )
 

topmark-0.2.0/src/topmark/config/topmark-default.toml

@@ -0,0 +1,75 @@
+# topmark:header:start
+#
+#   file         : topmark-default.toml
+#   file_relpath : src/topmark/config/topmark-default.toml
+#   project      : TopMark
+#   license      : MIT
+#   copyright    : (c) 2025 Olivier Biot
+#
+# topmark:header:end
+
+#########################
+# TopMark configuration #
+#########################
+# This file is used to define the default configuration for TopMark.
+
+
+# ==========================
+# Header field configuration
+# ==========================
+
+[header]
+# Configuration for header fields and metadata to include in generated headers
+
+# List of fields to include in the header.
+# Available fields include 'file', 'file_relpath', 'author', 'date', 'license', etc.
+# You can define your own fields as well.
+
+# TODO: review the fields: builtin field types and custom fields
+
+fields = ["file", "file_relpath"]
+
+
+# ========================
+# TopMark field definition
+# ========================
+
+[fields]
+
+# Project name to include in the header
+# project = "TopMark"
+
+# License to include in the header. Example values: 'MIT', 'GPL-3.0', 'Apache-2.0'
+# license = "MIT"
+
+# Copyright statement to include in the header.
+# copyright = "(c) 2025 Your Name" # Update according to your needs
+
+
+# ========================
+# Formatting configuration
+# ========================
+
+[formatting]
+# Formatting options for header rendering.
+
+# Align the fields (colons) in the header for better readability. Values: true or false.
+align_fields = true
+
+# File header format (default, native, plain, json)
+# header_format = "native"
+
+
+# ===================
+# Files configuration
+# ===================
+
+[files]
+
+# Specify (filter) file types:
+# file_types = "markdown"
+
+
+# ============================
+# END of TopMark Configuration
+# ============================

{topmark-0.1.1 → topmark-0.2.0}/src/topmark/constants.py

@@ -16,7 +16,10 @@ from pathlib import Path
 TOPMARK_VERSION = get_version("topmark")
 
 PYPROJECT_TOML_PATH = Path(__file__).parent.parent / "pyproject.toml"
-DEFAULT_TOML_CONFIG_PATH: Path = Path(__file__).parent / "config" / "topmark-default.toml"
+
+# Name of the bundled default config inside the package `topmark.config`.
+# This is used with importlib.resources in config/__init__.py
+DEFAULT_TOML_CONFIG_RESOURCE: str = "topmark-default.toml"
 
 TOPMARK_START_MARKER: str = "topmark:header:start"
 TOPMARK_END_MARKER: str = "topmark:header:end"

{topmark-0.1.1 → topmark-0.2.0}/src/topmark/pipeline/context.py

@@ -186,9 +186,9 @@ class ComparisonStatus(BaseStatus):
             Callable[[str], str],
             {
                 ComparisonStatus.PENDING: chalk.gray,
-                ComparisonStatus.CHANGED: chalk.yellow_bright,
+                ComparisonStatus.CHANGED: chalk.red,
                 ComparisonStatus.UNCHANGED: chalk.green,
-                ComparisonStatus.CANNOT_COMPARE: chalk.red,
+                ComparisonStatus.CANNOT_COMPARE: chalk.yellow_bright,
             }[self],
         )
 

{topmark-0.1.1 → topmark-0.2.0/src/topmark.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.1.1
+Version: 0.2.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
@@ -127,6 +127,15 @@ Logging verbosity is controlled globally:
 All other options, such as `--stdin`, `--file-type`, and path filters, are specific to individual
 subcommands like `check` or `apply`.
 
+### Skipping and filtering helpers
+
+These switches help keep CI output meaningful and fast:
+
+- `--skip-compliant` — hide files that are already compliant; only show items that need attention.
+- `--skip-unsupported` — hide unsupported file types and files matched by known types that
+  intentionally **do not** support headers (e.g., strict JSON). They remain **recognized** but are
+  not listed in results.
+
 ### Examples
 
 ```bash
@@ -159,6 +168,12 @@ topmark version
 
 # Apply changes to files in-place
 topmark --apply src/
+
+# CI-friendly summary: only show issues; ignore unsupported types
+topmark --skip-compliant --skip-unsupported src/
+
+# Apply fixes for only the changed files passed by pre-commit
+topmark --apply --apply --skip-unsupported --quiet
 ```
 
 ## 📐 Header placement rules
@@ -249,10 +264,79 @@ The following options can be used with most commands.
 
 ## 🧩 Supported file types
 
-| Processor            | File types (examples)                                                      |
-| -------------------- | -------------------------------------------------------------------------- |
-| PoundHeaderProcessor | python, shell, ruby, r, julia, perl, makefile, dockerfile, yaml, toml, env |
-| XmlHeaderProcessor   | xml, xhtml, html, svg, xsl/xslt, vue, svelte, markdown                     |
+| Processor            | File types (examples)                                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------------------------------- |
+| PoundHeaderProcessor | dockerfile, env, git-meta, ini, julia, makefile, perl, python, python-requirements, r, ruby, shell, toml, yaml |
+| SlashHeaderProcessor | c, cpp, cs, go, java, javascript, kotlin, rust, swift, typescript, vscode-jsonc                                |
+| XmlHeaderProcessor   | html, markdown, svelte, svg, vue, xhtml, xml, xsl, xslt, yaml                                                  |
+
+Some formats (e.g., strict JSON) are **recognized but intentionally skipped** because they lack a
+safe comment syntax. Use `--skip-unsupported` to hide them from the report while keeping safety.
+
+For a complete list, please run:
+
+```sh
+topmark filetypes
+```
+
+### How TopMark resolves file types (specificity & safety)
+
+TopMark may have multiple `FileType` definitions that **match** a given path. The resolver now:
+
+- evaluates **all** matching file types and scores them by **specificity**,
+- prefers **explicit filenames / tail subpaths** (e.g., `.vscode/settings.json`) over patterns, and
+  **patterns** over simple **extensions**,
+- breaks ties in favor of **headerable** types (those without `skip_processing=True`).
+
+**Tail subpath matching.** `FileType.filenames` entries that contain a path separator (e.g.,
+`".vscode/settings.json"`) are matched as **path suffixes** against `path.as_posix()`; plain names
+still match the **basename** only.
+
+**JSON vs JSONC.** Generic `json` is recognized but marked `skip_processing=True` (no comments in
+strict JSON), while `vscode-jsonc` is a safe, **narrow** opt‑in that uses `//` headers. If you need
+more JSON-with-comments files, add them via a dedicated `FileType` or an explicit allow‑list in
+config.
+
+**Shebang‑aware insertion.** The default insertion logic is policy‑driven and shebang‑aware (insert
+after `#!` and optional encoding line). For formats like XML that need character‑precise placement,
+processors provide a text‑offset path; `XmlHeaderProcessor` uses this and signals **no line
+anchor**.
+
+## 🪝 Pre-commit integration
+
+TopMark provides first-class pre-commit hooks. A minimal consumer configuration:
+
+```yaml
+# .pre-commit-config.yaml (in a consuming repository)
+repos:
+  - repo: https://github.com/shutterfreak/topmark
+    rev: v0.2.0   # pin to a released tag
+    hooks:
+      - id: topmark-check
+        # Optional: limit scope to supported text types
+        # files: '\\.(py|md|toml|ya?ml|sh|Makefile)$'
+```
+
+Hooks shipped by this repo:
+
+- **`topmark-check`** — non-destructive validation. Recommended on `pre-commit` / `pre-push`.
+- **`topmark-apply`** — destructive, requires `--apply`. Marked `manual` so it only runs when you
+  call it explicitly.
+
+**Run the manual hook locally:**
+
+```bash
+# On the whole repo
+pre-commit run topmark-apply --all-files --hook-stage manual
+
+# On specific files
+pre-commit run topmark-apply --files path/to/file1 path/to/file2 --hook-stage manual
+```
+
+**Why does the hook seem to run multiple times?** Pre-commit batches filenames to avoid OS
+argument-length limits. You may see repeated banners (e.g., “Processing N file(s)”) as the hook runs
+once per batch. To run **once** per repo, set `pass_filenames: false` in the hook manifest and let
+TopMark discover files itself.
 
 ## 🛠 Configuration
 

{topmark-0.1.1 → topmark-0.2.0}/src/topmark.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ src/topmark/cli/commands/show_defaults.py
 src/topmark/cli/commands/version.py
 src/topmark/config/__init__.py
 src/topmark/config/logging.py
+src/topmark/config/topmark-default.toml
 src/topmark/filetypes/__init__.py
 src/topmark/filetypes/base.py
 src/topmark/filetypes/instances.py