repomatic 7.4.1__tar.gz → 7.6.0__tar.gz

{repomatic-7.4.1 → repomatic-7.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repomatic
-Version: 7.4.1
+Version: 7.6.0
 Summary: 🏭 Automate repository maintenance, releases, and CI/CD workflows
 Keywords: changelog-formatter,dependabot-alternative,github-actions,github-labels,github-workflow,gitignore,mailmap,mypy,nuitka,python-automation,release-automation,repository-automation,repository-management,reusable-workflows,software-factory,sphinx-doc,typo,uv,workflow-reusable
 Author: Kevin Deldycke
@@ -59,7 +59,7 @@ Requires-Dist: wcmatch>=10
 Requires-Python: >=3.10
 Project-URL: Changelog, https://github.com/kdeldycke/repomatic/blob/main/changelog.md
 Project-URL: Documentation, https://kdeldycke.github.io/repomatic
-Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.4.1
+Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.6.0
 Project-URL: Funding, https://github.com/sponsors/kdeldycke
 Project-URL: Homepage, https://github.com/kdeldycke/repomatic
 Project-URL: Issues, https://github.com/kdeldycke/repomatic/issues
@@ -77,7 +77,7 @@ Description-Content-Type: text/markdown
 [![Coverage status](https://codecov.io/gh/kdeldycke/repomatic/branch/main/graph/badge.svg)](https://app.codecov.io/gh/kdeldycke/repomatic)
 [![Documentation status](https://img.shields.io/github/actions/workflow/status/kdeldycke/repomatic/docs.yaml?branch=main&label=%F0%9F%93%9A%20Docs)](https://github.com/kdeldycke/repomatic/actions/workflows/docs.yaml?query=branch%3Amain)
 
-A Python CLI and `pyproject.toml` configuration that let you **release Python packages multiple times a day with only 2-clicks**. Designed for `uv`-based Python projects, but usable for other projects too. The CLI operates through reusable GitHub Actions workflows as its CI delivery mechanism.
+A Python CLI and `pyproject.toml` configuration that let you **release Python packages multiple times a day with only 2-clicks**. Designed for `uv`-based Python projects, but usable for other projects too. Every step is a CLI command: reusable GitHub Actions workflows are only the trigger, so the same automation runs on your machine.
 
 **Maintainer-in-the-loop**: nothing is done behind your back. A PR or issue is created every time a change is proposed or action is needed.
 
@@ -99,8 +99,10 @@ A Python CLI and `pyproject.toml` configuration that let you **release Python pa
 
 ## Why repomatic
 
+repomatic does for the release process what ruff did for linting and uv did for packaging: replace a stack of single-purpose tools with one.
+
 - [18 third-party GitHub Actions replaced](https://kdeldycke.github.io/repomatic/security.html#third-party-action-minimization) by internal CLI commands and SHA-256-verified binary downloads, keeping the supply chain attack surface minimal
-- [8 Python linters and formatters](https://kdeldycke.github.io/repomatic/security.html#ruff-consolidation) (pylint, black, isort, pyupgrade, pydocstyle, pycln, docformatter, blacken-docs) consolidated into ruff
+- [10 Python linters and formatters](https://kdeldycke.github.io/repomatic/security.html#ruff-consolidation) (pylint, pydocstyle, pycln, pyupgrade, isort, black, docformatter, mdformat-black, blacken-docs, mdformat-ruff) consolidated into ruff
 - [5 packaging and install tools](https://kdeldycke.github.io/repomatic/security.html#uv-consolidation) (poetry, build, twine, check-wheel-contents, pip-audit) consolidated into uv
 - All `uses:` references [pinned to full commit SHAs](https://kdeldycke.github.io/repomatic/security.html#supply-chain-security) with stabilization windows before adopting new versions, managed entirely by self-hosted sync jobs
 - [SLSA provenance attestations](https://kdeldycke.github.io/repomatic/security.html#supply-chain-security) on every release artifact (wheels and compiled binaries)
@@ -110,7 +112,8 @@ A Python CLI and `pyproject.toml` configuration that let you **release Python pa
 - Workflow security linting with [`zizmor`](https://kdeldycke.github.io/repomatic/workflows.html#github-workflows-lint-yaml-jobs) on every push to catch dangerous triggers and excessive permissions
 - Credential scanning with [`gitleaks`](https://kdeldycke.github.io/repomatic/workflows.html#github-workflows-lint-yaml-jobs) to prevent secret leakage
 - Single [`pyproject.toml` configuration](https://kdeldycke.github.io/repomatic/configuration.html): no extra dotfiles, no JSON configs, no YAML presets to maintain
-- [15+ code quality tools](https://kdeldycke.github.io/repomatic/tool-runner.html) (ruff, mypy, biome, typos, mdformat, shfmt, yamllint, actionlint, lychee, oxipng, jpegoptim, pyproject-fmt, labelmaker, gitleaks, zizmor) managed through one `repomatic run <tool>` interface with automatic installation and platform-specific binary caching
+- The CLI itself [ships as standalone binaries](https://kdeldycke.github.io/repomatic/install.html#executables) (Linux / macOS / Windows, x86_64 / arm64): no Python environment needed to run it
+- [15+ code quality tools](https://kdeldycke.github.io/repomatic/tool-runner.html) (ruff, mypy, biome, typos, mdformat, shfmt, yamllint, actionlint, lychee, oxipng, pyproject-fmt, labelmaker, gitleaks, zizmor) managed through one `repomatic run <tool>` interface with automatic installation and platform-specific binary caching
 
 ## Quick start
 
@@ -124,6 +127,13 @@ $ git push
 
 Works for new and existing repositories. Managed files are always regenerated to the latest version; `changelog.md` is never overwritten. Push, and the workflows guide you through remaining setup via issues and PRs.
 
+The workflows only call CLI commands, so every automated step can also be run and previewed locally:
+
+```shell-session
+$ uvx -- repomatic sync-deps --dry-run
+$ uvx -- repomatic run ruff -- check
+```
+
 See `repomatic init --help` for available components and options.
 
 ## Documentation
@@ -133,10 +143,11 @@ See the **[full documentation](https://kdeldycke.github.io/repomatic/)** for:
 - [Installation methods and executables](https://kdeldycke.github.io/repomatic/install.html)
 - [`[tool.repomatic]` configuration reference](https://kdeldycke.github.io/repomatic/configuration.html)
 - [CLI parameters](https://kdeldycke.github.io/repomatic/cli.html)
-- [Reusable workflow reference](https://kdeldycke.github.io/repomatic/workflows.html) (all 13 workflows with job descriptions)
+- [Reusable workflow reference](https://kdeldycke.github.io/repomatic/workflows.html) (all 14 workflows with job descriptions)
 - [Security practices and token setup](https://kdeldycke.github.io/repomatic/security.html)
-- [Claude Code skills](https://kdeldycke.github.io/repomatic/skills.html)
+- [Claude Code skills](https://kdeldycke.github.io/repomatic/skills.html) and [agents](https://kdeldycke.github.io/repomatic/agents.html), also installable as a [Claude Code plugin](https://kdeldycke.github.io/repomatic/plugin.html)
 - [API reference](https://kdeldycke.github.io/repomatic/repomatic.html)
+- [Project history](https://kdeldycke.github.io/repomatic/history.html)
 
 ## Used in
 

{repomatic-7.4.1 → repomatic-7.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["uv-build>=0.8"]
 
 [project]
 name = "repomatic"
-version = "7.4.1"
+version = "7.6.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -92,7 +92,7 @@ email = "kevin@deldycke.com"
 [project.urls]
 Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 Documentation = "https://kdeldycke.github.io/repomatic"
-Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.4.1"
+Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.6.0"
 Funding = "https://github.com/sponsors/kdeldycke"
 Homepage = "https://github.com/kdeldycke/repomatic"
 Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -138,8 +138,6 @@ exclude-newer = "1 week"
 requires-python = ">= 3.14"
 
 [tool.uv.exclude-newer-package]
-click-extra = "2026-08-02T00:00:00Z"
-extra-platforms = "2026-07-28T00:00:00Z"
 repomatic = "0 day"
 
 [tool.uv.build-backend]
@@ -148,14 +146,17 @@ module-root = ""
 [tool.nuitka]
 copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed under GPL-2.0-or-later license."
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
-file-version = "7.4.1"
-include-data-dir = ["repomatic/data/awesome_template=repomatic/data/awesome_template"]
+file-version = "7.6.0"
+include-data-dir = [
+    "repomatic/data/awesome_template=repomatic/data/awesome_template",
+    "repomatic/data/skills=repomatic/data/skills",
+]
 include-data-files = ["repomatic/templates/*.md=repomatic/templates/"]
 include-package-data = ["click_extra"]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.4.1"
+product-version = "7.6.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -163,6 +164,7 @@ preview = true
 fix = true
 unsafe-fixes = false
 show-fixes = true
+output-prefer-rule-codes = true
 
 [tool.ruff.format]
 docstring-code-format = true
@@ -203,6 +205,7 @@ Typescript = "TypeScript"
 
 [tool.typos.default.extend-words]
 astroid = "astroid"
+Contribuer = "Contribuer"
 oject = "oject"
 PNGs = "PNGs"
 sur = "sur"
@@ -245,7 +248,7 @@ source = ["repomatic"]
 precision = 2
 
 [tool.bumpversion]
-current_version = "7.4.1"
+current_version = "7.6.0"
 parse = '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.dev(?P<dev>\d+))?'
 serialize = [
     "{major}.{minor}.{patch}.dev{dev}",
@@ -330,6 +333,7 @@ pypi-package-history = [
     "gha-utils",
     "repokit",
 ]
+release-assets = ["repomatic-plugin.zip"]
 
 [tool.repomatic.changelog]
 archive-location = "./docs/changelog-archive.md"

{repomatic-7.4.1 → repomatic-7.6.0}/pyproject.toml.orig

@@ -12,7 +12,7 @@ requires = [ "uv-build>=0.8" ]
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "repomatic"
-version = "7.4.1"
+version = "7.6.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -93,8 +93,8 @@ dependencies = [
   "boltons>=25",
   # click-extra 8.8.0 is the floor: repomatic delegates to the utilities absorbed
   # there — `format_size` (byte sizes in the image and cache reports), the
-  # `parse_duration`/`parse_friendly_duration`/`parse_iso8601_duration` family
-  # (uv cooldown spans in `uv.py`/`version_sync.py`), `prep_path`/`is_stdout`
+  # `parse_friendly_duration`/`parse_iso8601_duration` pair (uv cooldown spans
+  # in `uv.py`/`version_sync.py`), `prep_path`/`is_stdout`/`STDOUT_SENTINEL`
   # (CLI `--output` handling), and `config_table_to_flags` (tool flag
   # translation). Earlier floors remain in play: `binaries_page` imports
   # `click_extra.blocks` (`replace_region`, 8.7.1) to splice the binaries page
@@ -145,7 +145,7 @@ dependencies = [
 ]
 urls.Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 urls.Documentation = "https://kdeldycke.github.io/repomatic"
-urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.4.1"
+urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.6.0"
 urls.Funding = "https://github.com/sponsors/kdeldycke"
 urls.Homepage = "https://github.com/kdeldycke/repomatic"
 urls.Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -223,9 +223,12 @@ typing = [
 required-version = ">=0.11.15"
 # Docs group requires Python >= 3.14 for recent MyST-Parser and click-extra features.
 dependency-groups.docs = { requires-python = ">= 3.14" }
-# Cooldown period: 7-day buffer before using newly released packages.
-# Relative dates are fine here: uv 0.11.8+ writes a sentinel timestamp to
-# uv.lock for relative spans, so re-resolving never produces churn.
+# Cooldown period before using newly released packages. Kept equal to
+# `[tool.repomatic] minimum-release-age`: that value gates the `uvx` installs
+# every workflow runs, and a wider window here would lock a version those
+# installs refuse to resolve. Relative dates are fine: uv 0.11.8+ writes a
+# sentinel timestamp to uv.lock for relative spans, so re-resolving never
+# produces churn.
 exclude-newer = "1 week"
 # Per-package cooldown control. A fixed date holds a package at the version
 # available then (the day after it shipped), so `uv lock --upgrade` keeps that
@@ -234,7 +237,7 @@ exclude-newer = "1 week"
 # `exclude-newer`, returning the package to the normal cooldown. repomatic is
 # pinned to git main (no PyPI release to freeze), so it keeps a permanent
 # "0 day" span.
-exclude-newer-package = { click-extra = "2026-08-02T00:00:00Z", extra-platforms = "2026-07-28T00:00:00Z", repomatic = "0 day" }
+exclude-newer-package = { repomatic = "0 day" }
 # Package is at root level, not in "./src/".
 build-backend.module-root = ""
 
@@ -247,9 +250,10 @@ copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed u
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 # Numeric only: Nuitka rejects PEP 440 .devN suffixes. Kept in sync with the
 # package version by the dedicated [tool.bumpversion] rule that strips the suffix.
-file-version = "7.4.1"
+file-version = "7.6.0"
 include-data-dir = [
   "repomatic/data/awesome_template=repomatic/data/awesome_template",
+  "repomatic/data/skills=repomatic/data/skills",
 ]
 include-data-files = [
   "repomatic/templates/*.md=repomatic/templates/",
@@ -265,7 +269,7 @@ include-package-data = [ "click_extra" ]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.4.1"
+product-version = "7.6.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -299,11 +303,15 @@ lint.isort.combine-as-imports = true
 # this would simplify a fix or enable a new diagnostic.
 # https://docs.astral.sh/ruff/settings/#lint_future-annotations
 lint.future-annotations = true
+# Report rule codes, not the human-readable names preview mode defaults to.
+# See the bundled repomatic/data/ruff.toml for the rationale.
+output-prefer-rule-codes = true
 
 [tool.typos]
 default.extend-identifiers = { Github = "GitHub", IOS = "iOS", Javascript = "JavaScript", MacOS = "macOS", PNGs = "PNGs", PyPi = "PyPI", Typescript = "TypeScript" }
-# False positives.
-default.extend-words = { astroid = "astroid", oject = "oject", PNGs = "PNGs", sur = "sur" }
+# False positives. "Contribuer" is the French for "Contributing", part of the
+# translated-readme fixture in tests/test_awesome_toc.py.
+default.extend-words = { astroid = "astroid", Contribuer = "Contribuer", oject = "oject", PNGs = "PNGs", sur = "sur" }
 # Skip content between <!-- typos:off --> and <!-- typos:on --> markers.
 default.extend-ignore-re = [
   "(?s)<!-- typos:off -->.*?<!-- typos:on -->",
@@ -387,7 +395,7 @@ run.source = [ "repomatic" ]
 report.precision = 2
 
 [tool.bumpversion]
-current_version = "7.4.1"
+current_version = "7.6.0"
 # Parse versions with an optional .devN suffix (PEP 440).
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.dev(?P<dev>\\d+))?"
 serialize = [
@@ -510,3 +518,8 @@ exclude = [ "workflows" ]
 # the HTML docs site stay in lockstep.
 manpages.script = "repomatic.cli:repomatic"
 pypi-package-history = [ "gha-utils", "repokit" ]
+# Claude Code plugin archive packed by release.yaml's pack-plugin job and
+# attached to every GitHub release by the engine's extra-assets job. The
+# marketplace at .claude-plugin/marketplace.json installs the plugin straight
+# from this asset, so a release missing it breaks `/plugin install`.
+release-assets = [ "repomatic-plugin.zip" ]

{repomatic-7.4.1 → repomatic-7.6.0}/readme.md

@@ -9,7 +9,7 @@
 [![Coverage status](https://codecov.io/gh/kdeldycke/repomatic/branch/main/graph/badge.svg)](https://app.codecov.io/gh/kdeldycke/repomatic)
 [![Documentation status](https://img.shields.io/github/actions/workflow/status/kdeldycke/repomatic/docs.yaml?branch=main&label=%F0%9F%93%9A%20Docs)](https://github.com/kdeldycke/repomatic/actions/workflows/docs.yaml?query=branch%3Amain)
 
-A Python CLI and `pyproject.toml` configuration that let you **release Python packages multiple times a day with only 2-clicks**. Designed for `uv`-based Python projects, but usable for other projects too. The CLI operates through reusable GitHub Actions workflows as its CI delivery mechanism.
+A Python CLI and `pyproject.toml` configuration that let you **release Python packages multiple times a day with only 2-clicks**. Designed for `uv`-based Python projects, but usable for other projects too. Every step is a CLI command: reusable GitHub Actions workflows are only the trigger, so the same automation runs on your machine.
 
 **Maintainer-in-the-loop**: nothing is done behind your back. A PR or issue is created every time a change is proposed or action is needed.
 
@@ -31,8 +31,10 @@ A Python CLI and `pyproject.toml` configuration that let you **release Python pa
 
 ## Why repomatic
 
+repomatic does for the release process what ruff did for linting and uv did for packaging: replace a stack of single-purpose tools with one.
+
 - [18 third-party GitHub Actions replaced](https://kdeldycke.github.io/repomatic/security.html#third-party-action-minimization) by internal CLI commands and SHA-256-verified binary downloads, keeping the supply chain attack surface minimal
-- [8 Python linters and formatters](https://kdeldycke.github.io/repomatic/security.html#ruff-consolidation) (pylint, black, isort, pyupgrade, pydocstyle, pycln, docformatter, blacken-docs) consolidated into ruff
+- [10 Python linters and formatters](https://kdeldycke.github.io/repomatic/security.html#ruff-consolidation) (pylint, pydocstyle, pycln, pyupgrade, isort, black, docformatter, mdformat-black, blacken-docs, mdformat-ruff) consolidated into ruff
 - [5 packaging and install tools](https://kdeldycke.github.io/repomatic/security.html#uv-consolidation) (poetry, build, twine, check-wheel-contents, pip-audit) consolidated into uv
 - All `uses:` references [pinned to full commit SHAs](https://kdeldycke.github.io/repomatic/security.html#supply-chain-security) with stabilization windows before adopting new versions, managed entirely by self-hosted sync jobs
 - [SLSA provenance attestations](https://kdeldycke.github.io/repomatic/security.html#supply-chain-security) on every release artifact (wheels and compiled binaries)
@@ -42,7 +44,8 @@ A Python CLI and `pyproject.toml` configuration that let you **release Python pa
 - Workflow security linting with [`zizmor`](https://kdeldycke.github.io/repomatic/workflows.html#github-workflows-lint-yaml-jobs) on every push to catch dangerous triggers and excessive permissions
 - Credential scanning with [`gitleaks`](https://kdeldycke.github.io/repomatic/workflows.html#github-workflows-lint-yaml-jobs) to prevent secret leakage
 - Single [`pyproject.toml` configuration](https://kdeldycke.github.io/repomatic/configuration.html): no extra dotfiles, no JSON configs, no YAML presets to maintain
-- [15+ code quality tools](https://kdeldycke.github.io/repomatic/tool-runner.html) (ruff, mypy, biome, typos, mdformat, shfmt, yamllint, actionlint, lychee, oxipng, jpegoptim, pyproject-fmt, labelmaker, gitleaks, zizmor) managed through one `repomatic run <tool>` interface with automatic installation and platform-specific binary caching
+- The CLI itself [ships as standalone binaries](https://kdeldycke.github.io/repomatic/install.html#executables) (Linux / macOS / Windows, x86_64 / arm64): no Python environment needed to run it
+- [15+ code quality tools](https://kdeldycke.github.io/repomatic/tool-runner.html) (ruff, mypy, biome, typos, mdformat, shfmt, yamllint, actionlint, lychee, oxipng, pyproject-fmt, labelmaker, gitleaks, zizmor) managed through one `repomatic run <tool>` interface with automatic installation and platform-specific binary caching
 
 ## Quick start
 
@@ -56,6 +59,13 @@ $ git push
 
 Works for new and existing repositories. Managed files are always regenerated to the latest version; `changelog.md` is never overwritten. Push, and the workflows guide you through remaining setup via issues and PRs.
 
+The workflows only call CLI commands, so every automated step can also be run and previewed locally:
+
+```shell-session
+$ uvx -- repomatic sync-deps --dry-run
+$ uvx -- repomatic run ruff -- check
+```
+
 See `repomatic init --help` for available components and options.
 
 ## Documentation
@@ -65,10 +75,11 @@ See the **[full documentation](https://kdeldycke.github.io/repomatic/)** for:
 - [Installation methods and executables](https://kdeldycke.github.io/repomatic/install.html)
 - [`[tool.repomatic]` configuration reference](https://kdeldycke.github.io/repomatic/configuration.html)
 - [CLI parameters](https://kdeldycke.github.io/repomatic/cli.html)
-- [Reusable workflow reference](https://kdeldycke.github.io/repomatic/workflows.html) (all 13 workflows with job descriptions)
+- [Reusable workflow reference](https://kdeldycke.github.io/repomatic/workflows.html) (all 14 workflows with job descriptions)
 - [Security practices and token setup](https://kdeldycke.github.io/repomatic/security.html)
-- [Claude Code skills](https://kdeldycke.github.io/repomatic/skills.html)
+- [Claude Code skills](https://kdeldycke.github.io/repomatic/skills.html) and [agents](https://kdeldycke.github.io/repomatic/agents.html), also installable as a [Claude Code plugin](https://kdeldycke.github.io/repomatic/plugin.html)
 - [API reference](https://kdeldycke.github.io/repomatic/repomatic.html)
+- [Project history](https://kdeldycke.github.io/repomatic/history.html)
 
 ## Used in
 

{repomatic-7.4.1 → repomatic-7.6.0}/repomatic/__init__.py

@@ -17,5 +17,5 @@
 
 from __future__ import annotations
 
-__version__ = "7.4.1"
-__git_tag_sha__ = "f3fd0341a6ffbe9f948e78e3270ca30faf2b2459"
+__version__ = "7.6.0"
+__git_tag_sha__ = "07e3ef8ae5685c7dfc4af43001b6fc67501396b1"

repomatic-7.6.0/repomatic/awesome_toc.py

@@ -0,0 +1,277 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+"""Remove the table-of-contents entries awesome-lint forbids.
+
+Backs the `fix-awesome-toc` command, which runs on `awesome-*` repositories
+right after `repomatic run mdformat` regenerates the ToC of every readme.
+
+```{note}
+This is the one operation that has no job, PR branch or template of its own,
+against the rule in `claude.md` § Naming conventions for automated operations.
+It corrects what `format-markdown` just wrote, so it has to share that job's
+working tree: given its own job, the two would land in separate PRs and undo
+each other on every push, `format-markdown` re-adding the entries this command
+had removed.
+```
+
+`mdformat-toc` lists every heading in range and offers no exclusion mechanism
+of its own, so the entries have to be deleted afterwards. Upstream tracks the
+feature in [hukkin/mdformat-toc#17](https://github.com/hukkin/mdformat-toc/issues/17)
+and [hukkin/mdformat-toc#20](https://github.com/hukkin/mdformat-toc/pull/20);
+this module can go once either lands and grows a way to express the exclusion
+in the ToC marker.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator, Sequence
+
+FORBIDDEN_HEADINGS: tuple[str, ...] = (
+    "Contents",
+    "Contributing",
+    "Footnotes",
+    "Related Lists",
+)
+"""Headings awesome-lint refuses to see listed in the table of contents.
+
+Mirrors the roster in
+[awesome-lint's `toc.js`](https://github.com/sindresorhus/awesome-lint/blob/v2.2.2/rules/toc.js#L14-L18),
+plus the heading owning the ToC itself (`Contents`), whose entry trips
+`remark-lint:awesome-toc`:
+
+```
+✖  26:1  ToC item "Contents" does not match corresponding heading "Meta"
+```
+
+These are the English names, the only ones awesome-lint knows. A translated
+readme names the same sections in its own language, which is why matching on
+this roster alone is not enough: see {func}`forbidden_headings_for`.
+"""
+
+README_RE = re.compile(r"^readme(\.[^.]+)?\.md$")
+"""Match `readme.md` and every `readme.{lang}.md` translation beside it.
+
+Only the repository root is scanned. The `find ./` this replaced walked the
+whole tree, which on a checkout carrying a `node_modules/` directory would
+have reached a few hundred vendored readmes.
+"""
+
+REFERENCE_README = "readme.md"
+"""The English readme, whose heading positions every translation is mapped onto."""
+
+HEADING_RE = re.compile(r"^\#{1,6}[ \t]+(?P<text>.+?)[ \t]*\#*[ \t]*$", re.MULTILINE)
+"""Match an ATX heading and capture its text, closing sequence excluded."""
+
+TOC_ENTRY_RE = re.compile(r"^[ \t]*- \[(?P<text>.+)\]\(#[^)]*\)$")
+"""Match one `mdformat-toc` list entry and capture its link text."""
+
+TOC_START_RE = re.compile(r"^<!--\s*mdformat-toc\s+start\b.*-->$", re.IGNORECASE)
+"""Match the opening marker of an `mdformat-toc` block."""
+
+TOC_END_RE = re.compile(r"^<!--\s*mdformat-toc\s+end\s*-->$", re.IGNORECASE)
+"""Match the closing marker of an `mdformat-toc` block."""
+
+FENCE_RE = re.compile(r"^[ \t]*(?P<fence>`{3,}|~{3,})")
+"""Match the delimiter of a fenced code block."""
+
+
+def _strip_fenced_blocks(content: str) -> str:
+    """Blank out fenced code blocks so their `#` lines are not read as headings.
+
+    Replaces the content of every fence with empty lines, keeping the line
+    count intact so positions elsewhere are unaffected.
+
+    :param content: The full Markdown document.
+    :return: The document with fenced blocks blanked out.
+    """
+    lines = content.splitlines()
+    kept: list[str] = []
+    fence: str | None = None
+    for line in lines:
+        match = FENCE_RE.match(line)
+        if fence is None:
+            if match:
+                fence = match.group("fence")[0]
+                kept.append("")
+                continue
+        elif match and match.group("fence")[0] == fence:
+            fence = None
+            kept.append("")
+            continue
+        kept.append("" if fence else line)
+    return "\n".join(kept)
+
+
+def headings(content: str) -> list[str]:
+    """List the ATX heading texts of a Markdown document, in document order.
+
+    :param content: The full Markdown document.
+    :return: Every heading text, code fences excluded.
+    """
+    return [m.group("text") for m in HEADING_RE.finditer(_strip_fenced_blocks(content))]
+
+
+def forbidden_headings_for(
+    content: str,
+    reference_headings: Sequence[str] | None = None,
+) -> set[str]:
+    """Resolve which heading texts must not appear in *content*'s ToC.
+
+    Always includes the English {data}`FORBIDDEN_HEADINGS` that awesome-lint
+    knows, since a translation routinely leaves some of them untranslated.
+
+    On top of that, when *reference_headings* is given and the document has the
+    same number of headings, the heading occupying each forbidden position in
+    the reference is forbidden here too. That positional mapping is what carries
+    the rule across languages: repomatic cannot know that `贡献` translates
+    `Contributing`, but it can see that both sit at the same index of a readme
+    and its translation. Headings survive formatting untouched, so the mapping
+    holds even against an already-stripped reference.
+
+    :param content: The Markdown document to resolve the roster for.
+    :param reference_headings: Headings of {data}`REFERENCE_README`, if any.
+    :return: The heading texts whose ToC entry must be deleted.
+    """
+    forbidden = set(FORBIDDEN_HEADINGS)
+    if not reference_headings:
+        return forbidden
+
+    own_headings = headings(content)
+    if len(own_headings) != len(reference_headings):
+        logging.warning(
+            f"Heading count differs from {REFERENCE_README} "
+            f"({len(own_headings)} vs {len(reference_headings)}): "
+            "falling back to English heading names only."
+        )
+        return forbidden
+
+    forbidden.update(
+        own_headings[index]
+        for index, heading in enumerate(reference_headings)
+        if heading in FORBIDDEN_HEADINGS
+    )
+    return forbidden
+
+
+def _toc_bounds(lines: Sequence[str]) -> tuple[int, int] | None:
+    """Locate the `mdformat-toc` block in *lines*.
+
+    :param lines: The document split into lines.
+    :return: The start and end marker indices, or `None` when either is absent.
+    """
+    start = end = None
+    for index, line in enumerate(lines):
+        if start is None:
+            if TOC_START_RE.match(line):
+                start = index
+        elif TOC_END_RE.match(line):
+            end = index
+            break
+    if start is None or end is None:
+        return None
+    return start, end
+
+
+def strip_toc_entries(content: str, forbidden: set[str]) -> tuple[str, list[str]]:
+    """Delete the ToC entries of *content* whose link text is *forbidden*.
+
+    Only the `mdformat-toc` block is touched: a list item elsewhere in the
+    document that happens to link the same heading is left alone.
+
+    :param content: The full Markdown document.
+    :param forbidden: Heading texts whose entry must go.
+    :return: The updated document and the link texts that were deleted.
+    """
+    lines = content.splitlines(keepends=True)
+    bounds = _toc_bounds([line.rstrip("\r\n") for line in lines])
+    if bounds is None:
+        return content, []
+    start, end = bounds
+
+    kept: list[str] = []
+    removed: list[str] = []
+    for index, line in enumerate(lines):
+        if start < index < end:
+            match = TOC_ENTRY_RE.match(line.rstrip("\r\n"))
+            if match and match.group("text") in forbidden:
+                removed.append(match.group("text"))
+                continue
+        kept.append(line)
+    return "".join(kept), removed
+
+
+def fix_awesome_toc(root: Path | None = None) -> dict[Path, list[str]]:
+    """Strip the forbidden ToC entries from every readme under *root*.
+
+    Reads {data}`REFERENCE_README` first so its heading positions can be mapped
+    onto each translation, then rewrites every readme that changed. Idempotent:
+    a second run finds nothing left to delete.
+
+    :param root: Directory holding the readmes. Defaults to the current one.
+    :return: The deleted entries, keyed by the readme they came from.
+    """
+    root = Path.cwd() if root is None else root
+
+    reference = root / REFERENCE_README
+    reference_headings: list[str] | None = None
+    if reference.is_file():
+        reference_headings = headings(reference.read_text(encoding="utf-8"))
+    else:
+        logging.warning(
+            f"No {REFERENCE_README} in {root}: translations can only be matched "
+            "on English heading names."
+        )
+
+    report: dict[Path, list[str]] = {}
+    for readme in _readmes(root):
+        content = readme.read_text(encoding="utf-8")
+        forbidden = forbidden_headings_for(content, reference_headings)
+        updated, removed = strip_toc_entries(content, forbidden)
+        if not removed:
+            logging.debug(f"No forbidden ToC entry in {readme}.")
+            continue
+        readme.write_text(updated, encoding="utf-8")
+        logging.info(f"Removed {len(removed)} ToC entries from {readme}.")
+        report[readme] = removed
+    return report
+
+
+def _readmes(root: Path) -> Iterator[Path]:
+    """Yield the readmes of *root*, the reference first.
+
+    The reference goes first so its own entries are gone before a translation
+    is compared against it, which keeps a partial failure from leaving the
+    English readme dirtier than its translations.
+
+    :param root: Directory to scan.
+    :return: Each matching readme path, sorted after the reference.
+    """
+    matches: Iterable[Path] = sorted(
+        path for path in root.iterdir() if path.is_file() and README_RE.match(path.name)
+    )
+    for path in matches:
+        if path.name == REFERENCE_README:
+            yield path
+    for path in matches:
+        if path.name != REFERENCE_README:
+            yield path

{repomatic-7.4.1 → repomatic-7.6.0}/repomatic/binaries_page.py

@@ -160,7 +160,7 @@ The table is searchable and sortable on the documentation site; the raw data liv
 """
 """Initial page content, used when the page does not exist yet.
 
-The `{repo_url}` placeholder is substituted with `str.replace` (not
+The ``{repo_url}`` placeholder is substituted with `str.replace` (not
 `str.format`, which would choke on the csv-table directive's braces).
 Everything outside the marker pair is written once and never touched again:
 repositories can reword the prose without fighting the generator.
@@ -418,8 +418,10 @@ def render_binaries_csv(
             # they stay clickable with their label.
             writer.writerow((
                 f"[`{version}` {{octicon}}`link-external`]({release_url})",
-                f"[{{octicon}}`download` `{_platform_target(asset.name)}`]"
-                f"({asset.download_url})",
+                (
+                    f"[{{octicon}}`download` `{_platform_target(asset.name)}`]"
+                    f"({asset.download_url})"
+                ),
                 release.date,
                 vt_cell,
             ))