topmark 0.2.1__tar.gz → 0.3.0__tar.gz

{topmark-0.2.1/src/topmark.egg-info → topmark-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topmark
-Version: 0.2.1
+Version: 0.3.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
@@ -24,7 +24,6 @@ Requires-Dist: click
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pylint; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pyright; extra == "dev"
 Requires-Dist: mdformat; extra == "dev"
 Requires-Dist: mdformat-tables; extra == "dev"
@@ -38,12 +37,14 @@ Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
+Requires-Dist: mkdocs-autorefs>=0.5; extra == "docs"
 Requires-Dist: pymdown-extensions>=10.8; extra == "docs"
+Requires-Dist: mkdocs-gen-files<0.6,>=0.5; extra == "docs"
+Requires-Dist: ruff; extra == "docs"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-xdist; extra == "test"
 Provides-Extra: typing
-Requires-Dist: mypy; extra == "typing"
 Requires-Dist: types-toml; extra == "typing"
 Dynamic: license-file
 
@@ -70,6 +71,13 @@ topmark:header:end
 codebases. It helps maintain consistent header metadata across projects by supporting per-file-type
 header formats, customizable fields, inclusion/exclusion rules, and dry-run safety.
 
+## 📚 Documentation
+
+Full documentation is available on Read the Docs: <https://topmark.readthedocs.io>
+
+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.).
+
 ## ✨ Features
 
 - File header detection, insertion, and replacement
@@ -113,7 +121,7 @@ pip install topmark
 ## ⚙️ Usage
 
 ```bash
-topmark [OPTIONS] [PATHS]...
+topmark [SUBCOMMAND] [OPTIONS] [PATHS]...
 ```
 
 TopMark uses Click 8.2 and supports shell completions. The base command performs a dry‑run *check*
@@ -126,35 +134,47 @@ Logging verbosity is controlled globally:
 - `-v`, `--verbose`: Increase verbosity (can be repeated)
 - `-q`, `--quiet`: Suppress most output (overrides verbosity)
 
-All other options, such as `--stdin`, `--file-type`, and path filters, are specific to individual
-subcommands like `check` or `apply`.
+All other options are specific to individual subcommands.
+
+______________________________________________________________________
 
-### Skipping and filtering helpers
+### Subcommands
 
-These switches help keep CI output meaningful and fast:
+| Command         | Description                                        |
+| --------------- | -------------------------------------------------- |
+| `dump-config`   | Show the resolved configuration in TOML format     |
+| `filetypes`     | List supported file types and their comment styles |
+| `processors`    | List registered header processors and file types   |
+| `strip`         | Remove TopMark headers from files (destructive)    |
+| `version`       | Print TopMark version                              |
+| `show-defaults` | Show default config (without merging)              |
+| `init-config`   | Output a starter configuration file                |
 
-- `--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
 # Check Python files in the src/ directory
-topmark --file-type python src/
+topmark check --file-type python src/
 
 # Use exclusion patterns, and compute relative paths from src
-topmark --file-type python --exclude .venv --relative-to src src/
+topmark check --file-type python --exclude .venv --relative-to src src/
 
 # Add one verbosity level to topmark, use exclusion patterns from .gitignore
-topmark -v --file-type python --exclude-from .gitignore src/
+topmark -v check --file-type python --exclude-from .gitignore src/
+
+# Read a list of files from STDIN, generate summary
+find . -name "*.py" | topmark check --file-type python --files-from -  --summary
 
-# Read files from stdin, generate summary
-find . -name "*.py" | topmark --file-type python --summary --stdin
+# Process all files that are either staged, or untracked but not ignored in a Git repo (needs dedulication with `sort -u`)
+git ls-files -c -o --exclude-standard | sort -u | topmark check --files-from - --apply
 
-# Process all files in a Git repo
-git ls-files -c -o --exclude-standard | sort -u | topmark --stdin --apply
+# Read a single file's *content* from STDIN and render the resultng unified diff
+cat README.md | topmark - --stdin-filename README.md --diff
+
+# Read a single file's *content* from STDIN and print the updated content to stdout
+cat README.md | topmark - --stdin-filename README.md --apply
 
 # Dump the merged configuration (after loading all applicable config layers)
 topmark dump-config --file-type python --exclude .venv --exclude-from .gitignore
@@ -165,11 +185,11 @@ topmark show-defaults
 # Output a starter configuration to stdout
 topmark init-config
 
-# Show TopMark version
-topmark version
+# Show TopMark version in JSON format
+topmark version --format json
 
 # Apply changes to files in-place
-topmark --apply src/
+topmark check --apply src/
 
 # Remove headers from files (dry-run)
 topmark strip src/
@@ -178,174 +198,173 @@ topmark strip src/
 topmark strip --apply src/
 
 # CI-friendly summary: only show issues; ignore unsupported types
-topmark --skip-compliant --skip-unsupported src/
+topmark check --skip-compliant --skip-unsupported src/
+
+# Apply fixes, don't report unsupported files, muted output (useful for pre-commit)
+topmark check --apply --skip-unsupported --quiet
 
-# Apply fixes for only the changed files passed by pre-commit
-topmark --apply --apply --skip-unsupported --quiet
+# Show supported file types in MarkDown format, providing detailed output:
+topmark filetypes --format markdown --long
+
+# Show registered header processors (brief)
+topmark processors
+
+# Detailed Markdown listing of processors and their file types
+topmark processors --format markdown --long
 ```
 
-## 📐 Header placement rules
+______________________________________________________________________
 
-TopMark is comment-aware and places the header block according to the file type and its policy.
+## 🔌 Public API (stable)
+
+TopMark exposes a small, stable Python API for integrations. Import from `topmark.api` for core
+operations, and use the registry facade for read-only discovery.
+
+### Quickstart
+
+```python
+from pathlib import Path
+from topmark import api
+
+# Check (dry-run by default)
+result = api.check([Path("src")])
+print(result.summary)           # {"unchanged": N, "error": M, ...}
+print(result.had_errors)        # True/False
 
-### Pound-style files (e.g., Python, Shell, Ruby, Makefile, YAML, TOML, Dockerfile)
+# Apply changes explicitly
+applied = api.check([Path("src")], apply=True)
 
-Rules:
+# Remove headers
+stripped = api.strip([Path("src")], apply=False)
+```
+
+### Registry facade (read-only)
 
-- If a **shebang** is present (e.g., `#!/usr/bin/env python3`), place the header **after** the
-  shebang and ensure **exactly one** blank line in-between.
-- If a **coding/encoding line** follows the shebang (PEP 263 style), place the header **after**
-  shebang **and** encoding line.
-- Otherwise, place the header **at the top of the file**.
-- Ensure **one trailing blank line** after the header block when the next line is not already blank.
+```python
+from topmark.registry import Registry
 
-Example (Python):
+fts = Registry.filetypes()      # Mapping[str, FileType]
+procs = Registry.processors()   # Mapping[str, HeaderProcessor]
+for b in Registry.bindings():   # (filetype, optional processor)
+    print(b.filetype.name, bool(b.processor))
+```
 
-```py
-#!/usr/bin/env python3
+> **Note:** `Registry` is **not** re-exported from `topmark.api`; import it from `topmark.registry`.
 
-# topmark:header:start
-#
-#   file         :
-#   file_relpath :
-#
-# topmark:header:end
+### Version helper
 
-print("hello")
+```python
+from topmark import api
+print(api.version())  # e.g. "0.3.0"
 ```
 
-### XML-style files (XML, HTML/XHTML, SVG, Vue/Svelte/Markdown via HTML comments)
+### Stability
 
-Rules:
+- `topmark.api` and the `Registry` facade are covered by semantic versioning.
+- Low-level registries (`FileTypeRegistry`, `HeaderProcessorRegistry`) remain available for
+  plugins/tests but are **advanced** and may change between minor versions.
 
-- If present, place the header **after the XML declaration** and **DOCTYPE**, with **one blank
-  line** before the header block.
-- Otherwise, place the header **at the top of the file**.
-- The header uses the file’s native comment syntax; for XML/HTML it’s a comment block wrapper:
+### Adding & updating headers
 
-```html
-<!--
-topmark:header:start
+Use the `topmark check` command to insert or update headers. It’s **dry‑run by default**; add
+`--apply` to write changes. Placement follows file‑type policy (shebang/encoding for Python, XML
+declaration for XML/HTML, etc.). Newline style and BOM are preserved; runs are idempotent.
 
-  file         :
-  file_relpath :
+#### Quick examples
 
-topmark:header:end
--->
+```bash
+# Preview (exit code 2 when changes are pending)
+topmark src/
 
-<html>...</html>
+# Apply in place
+topmark check --apply src/
 ```
 
-### General guarantees
+> For full details, options, examples, and exit codes, see the dedicated guide:
+> **[Adding & updating headers with `topmark`](docs/usage/commands/topmark.md)**
 
-- **Newline preservation:** The inserted header uses the same newline style as the file
-  (LF/CRLF/CR).
-- **BOM preservation:** If a UTF‑8 BOM is present, it is preserved.
-- **Idempotency:** Re-running TopMark on a file with a correct header makes **no changes**.
+### Removing headers with `strip`
 
-### Common Options
+Use `topmark strip` to remove the entire TopMark header block. The command is **dry-run by
+default**; add `--apply` to write changes. It preserves newline style and BOM, and keeps XML
+declarations and Markdown code fences intact.
 
-The following options can be used with most commands.
+#### Quick examples
 
-| Option           | Description                              |
-| ---------------- | ---------------------------------------- |
-| `--file-type`    | Specify file type (python, markdown, …)  |
-| `--relative-to`  | Set base path for relative header fields |
-| `--include`      | Include paths or glob patterns           |
-| `--include-from` | Read inclusion patterns from file        |
-| `--exclude`      | Exclude paths or glob patterns           |
-| `--exclude-from` | Read exclusion patterns from file        |
-| `--stdin`        | Read file paths from stdin               |
-| `--apply`        | Actually modify files instead of dry-run |
-| `-v, --verbose`  | Increase verbosity (can be repeated)     |
-| `-q, --quiet`    | Suppress most output                     |
+```bash
+# Preview (exit code 2 when removals are pending)
+topmark strip src/
 
-### Subcommands
+# Apply in place
+topmark strip --apply src/
+```
 
-| Command         | Description                                        |
-| --------------- | -------------------------------------------------- |
-| `dump-config`   | Show the resolved configuration in TOML format     |
-| `filetypes`     | List supported file types and their comment styles |
-| `strip`         | Remove TopMark headers from files (destructive)    |
-| `version`       | Print TopMark version                              |
-| `show-defaults` | Show default config (without merging)              |
-| `init-config`   | Output a starter configuration file                |
+> For full details, options, examples, and exit codes, see the dedicated guide:
+> **[Removing headers with `topmark strip`](docs/usage/commands/strip.md)**
 
-## 🧩 Supported file types
+### Dumping the merged configuration
 
-| 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                                                  |
+Use `topmark dump-config` to print the **effective** configuration (defaults → discovered config →
+`--config` files → CLI flags) as TOML. This command is **file‑agnostic**: positional paths and
+`--files-from` are ignored; filter flags (`--include/--exclude`, `--include-from/--exclude-from`)
+are honored.
 
-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.
+```bash
+# Dump merged configuration
+topmark dump-config
 
-For a complete list, please run:
+# Include/exclude filters still apply
+topmark dump-config --exclude .venv --exclude-from .gitignore
 
-```sh
-topmark filetypes
+# Read patterns from STDIN
+printf "*.py\n" | topmark dump-config --include-from -
 ```
 
-### How TopMark resolves file types (specificity & safety)
+> For details and notes, see:
+> **[Dumping the merged configuration with `dump-config`](docs/usage/commands/dump_config.md)**
 
-TopMark may have multiple `FileType` definitions that **match** a given path. The resolver now:
+### Listing supported file types
 
-- 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`).
+Use `topmark filetypes` to see the identifiers you can pass to `--file-type` and the associated
+comment styles TopMark will use when rendering headers.
 
-**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.
+```bash
+# Show available file type identifiers
+topmark filetypes
 
-**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.
+# Then restrict processing to one or more types
+topmark check --file-type python src/
+topmark check --file-type markdown --file-type env docs/ 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**.
+> For details, see:
+> **[Listing supported file types with `filetypes`](docs/usage/commands/filetypes.md)**
 
-## 🪝 Pre-commit integration
+## 📐 Header placement rules
 
-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)$'
-```
+TopMark is comment-aware and places the header block according to the file type and its policy.
 
-Hooks shipped by this repo:
+The complete header placement rules are documented in the usage guide:
 
-- **`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.
+- [Header placement rules](docs/usage/header-placement.md)
 
-**Run the manual hook locally:**
+## 🧩 Supported file types
 
-```bash
-# On the whole repo
-pre-commit run topmark-apply --all-files --hook-stage manual
+See the full list and resolver behavior in the dedicated guide:
 
-# On specific files
-pre-commit run topmark-apply --files path/to/file1 path/to/file2 --hook-stage manual
-```
+- [Supported file types](docs/usage/filetypes.md)
+
+## 🪝 Pre-commit integration
+
+TopMark ships with pre-commit hooks to validate or update file headers.
+
+- **`topmark-check`** — runs automatically at `pre-commit` / `pre-push`, fails if headers need
+  changes.
+- **`topmark-apply`** — manual only; applies fixes and may modify files.
+
+For configuration examples, hook policies, and troubleshooting, see the dedicated guide:
 
-**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.
+- [Using TopMark with pre-commit](docs/usage/pre-commit.md)
 
 ## 🛠 Configuration
 
@@ -357,9 +376,9 @@ You can specify one or more `--config` files, or rely on local fallback resoluti
 TopMark reads configuration from one or more TOML files. Configuration is merged from:
 
 1. Built-in defaults
-2. Local project config (if not disabled via `--no-config`)
-3. Additional files via `--config`
-4. CLI overrides
+1. Local project config (if not disabled via `--no-config`)
+1. Additional files via `--config`
+1. CLI overrides
 
 Example configuration snippet (`topmark.toml`):
 
@@ -405,5 +424,4 @@ type checks in each environment.
 
 MIT License © 2025 Olivier Biot
 
-Markdown formatting is handled by `mdformat` with the `mdformat-tables` plugin, and configuration is
-read from `pyproject.toml`.
+> **[LICENSE (MIT)](LICENSE)**