repomatic 6.26.0__tar.gz → 6.28.0__tar.gz

{repomatic-6.26.0 → repomatic-6.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repomatic
-Version: 6.26.0
+Version: 6.28.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,renovate,repository-automation,repository-management,reusable-workflows,software-factory,sphinx-doc,typo,uv,workflow-reusable
 Author: Kevin Deldycke
@@ -58,7 +58,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/v6.26.0
+Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v6.28.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

{repomatic-6.26.0 → repomatic-6.28.0}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "uv-build>=0.9" ]
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "repomatic"
-version = "6.26.0"
+version = "6.28.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -116,18 +116,14 @@ dependencies = [
   # globbing uses iglob() with FOLLOW for symlink-aware file discovery.
   "wcmatch>=10",
 ]
-
-[project.scripts]
-repomatic = "repomatic.__main__:main"
-
-[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/v6.26.0"
-"Funding" = "https://github.com/sponsors/kdeldycke"
-"Homepage" = "https://github.com/kdeldycke/repomatic"
-"Issues" = "https://github.com/kdeldycke/repomatic/issues"
-"Repository" = "https://github.com/kdeldycke/repomatic"
+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/v6.28.0"
+urls.Funding = "https://github.com/sponsors/kdeldycke"
+urls.Homepage = "https://github.com/kdeldycke/repomatic"
+urls.Issues = "https://github.com/kdeldycke/repomatic/issues"
+urls.Repository = "https://github.com/kdeldycke/repomatic"
+scripts.repomatic = "repomatic.__main__:main"
 
 # Non-runtime development dependency groups.
 [dependency-groups]
@@ -186,12 +182,15 @@ dependency-groups.docs = { requires-python = ">= 3.14" }
 # 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.
 exclude-newer = "1 week"
-# repomatic is pinned to git main. click-extra 7.19.0 is bypassed so the release
-# engine's manpages job picks up the new `--output-dir` CLI flag without waiting
-# out the cooldown window; drop the override on the next routine bump. tomlrt
-# 1.7.5 ships the silent-empty-dump fix the project depends on; bypass the
-# cooldown until the release ages past `exclude-newer`.
-exclude-newer-package = { click-extra = "0 day", repomatic = "0 day", tomlrt = "0 day" }
+# 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
+# version instead of tracking newer releases. `sync-uv-lock` freezes new
+# bypasses at that date and prunes each entry once its held version ages past
+# `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. click-extra is held at 7.19.0 (manpages `--output-dir` flag);
+# tomlrt is held at 1.8.2.
+exclude-newer-package = { repomatic = "0 day", tomlrt = "2026-06-16T00:00:00Z" }
 # Package is at root level, not in "./src/".
 build-backend.module-root = ""
 
@@ -204,7 +203,7 @@ 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 = "6.26.0"
+file-version = "6.28.0"
 include-data-dir = [
   "repomatic/data/awesome_template=repomatic/data/awesome_template",
 ]
@@ -222,7 +221,7 @@ include-package-data = [ "click_extra" ]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "6.26.0"
+product-version = "6.28.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -284,11 +283,26 @@ default.extend-ignore-identifiers-re = [
   "WARNIN",
 ]
 
-[tool.pytest]
-# https://docs.pytest.org/en/latest/customize.html#pyproject-toml
-markers = [
-  "once: Tests that only need to run once, not across the full CI matrix.",
+[tool.mypy]
+mypy_path = "docs"
+check_untyped_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+warn_unreachable = true
+pretty = true
+warn_unused_configs = true
+overrides = [
+  { module = [
+    "bumpversion.*",
+    "gitdb.*",
+    "py_walk.*",
+    "pydriller.*",
+    "vt",
+  ], ignore_missing_imports = true },
 ]
+
+[tool.pytest]
 addopts = [
   "--durations=10",
   "--cov",
@@ -296,6 +310,10 @@ addopts = [
   "--numprocesses=auto",
   "--dist=loadgroup",
 ]
+# https://docs.pytest.org/en/latest/customize.html#pyproject-toml
+markers = [
+  "once: Tests that only need to run once, not across the full CI matrix.",
+]
 # Make sure tests that are expected to fail do not resurrect and start working all of a sudden.
 xfail_strict = true
 
@@ -306,20 +324,20 @@ run.source = [ "repomatic" ]
 report.precision = 2
 
 [tool.bumpversion]
-current_version = "6.26.0"
-allow_dirty = true
-ignore_missing_files = true
+current_version = "6.28.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 = [
   "{major}.{minor}.{patch}.dev{dev}",
   "{major}.{minor}.{patch}",
 ]
+ignore_missing_files = true
+allow_dirty = true
+parts.dev.optional_value = "release"
 # When dev is "release" (its optional value), the .devN suffix is omitted.
 # Bumping patch/minor/major resets dev to "0", producing X.Y.Z.dev0.
 # Bumping dev goes from "0" to "release", stripping the suffix for release.
 parts.dev.values = [ "0", "release" ]
-parts.dev.optional_value = "release"
 
 [[tool.bumpversion.files]]
 # Update Python package version in any __init__.py file.
@@ -373,25 +391,6 @@ regex = true
 search = "date-released: \\d{{4}}-\\d{{2}}-\\d{{2}}"
 replace = "date-released: {utcnow:%Y-%m-%d}"
 
-[tool.mypy]
-check_untyped_defs = true
-mypy_path = "docs"
-warn_unused_configs = true
-warn_redundant_casts = true
-warn_unused_ignores = true
-warn_return_any = true
-warn_unreachable = true
-pretty = true
-overrides = [
-  { ignore_missing_imports = true, module = [
-    "bumpversion.*",
-    "gitdb.*",
-    "py_walk.*",
-    "pydriller.*",
-    "vt",
-  ] },
-]
-
 [tool.lychee]
 # https://lychee.cli.rs/guides/config/
 exclude = [

{repomatic-6.26.0 → repomatic-6.28.0}/repomatic/__init__.py

@@ -17,5 +17,5 @@
 
 from __future__ import annotations
 
-__version__ = "6.26.0"
-__git_tag_sha__ = "9b9fa8a1d838c1f28bb9d0bb82fa67084b8a2ca7"
+__version__ = "6.28.0"
+__git_tag_sha__ = "a6458162963b57814a69421fed1f969cbbe1d2b6"

{repomatic-6.26.0 → repomatic-6.28.0}/repomatic/cli.py

@@ -26,6 +26,7 @@ import sys
 import tempfile
 import time
 from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 from urllib.request import Request, urlopen
 
@@ -39,14 +40,17 @@ from click_extra import (
     EnumChoice,
     FloatRange,
     IntRange,
+    ParameterSource,
     ParamType,
     Section,
     UsageError,
     argument,
+    context,
     dir_path,
     echo,
     file_path,
     group,
+    jobs_option,
     option,
     option_group,
     pass_context,
@@ -167,7 +171,12 @@ from .sponsor import (
     is_pull_request,
     is_sponsor,
 )
-from .test_plan import DEFAULT_TEST_PLAN, SkippedTest, parse_test_plan
+from .test_plan import (
+    DEFAULT_TEST_PLAN,
+    CLITestCase,
+    SkippedTest,
+    parse_test_plan,
+)
 from .tool_runner import (
     TOOL_REGISTRY,
     binary_tool_context,
@@ -179,10 +188,12 @@ from .uv import (
     AdvisorySource,
     _format_upload_date,
     build_comparison_urls,
+    collect_vulnerable_packages,
     fetch_release_notes,
     fix_vulnerable_deps as _fix_vulnerable_deps,
     format_diff_table,
     format_release_notes,
+    format_vulnerability_table,
     sync_uv_lock as _sync_uv_lock,
 )
 from .virustotal import (
@@ -227,9 +238,21 @@ def prep_path(filepath: Path) -> IO:
 
     For non-stdout paths, parent directories are created automatically if they don't
     exist. This absorbs the `mkdir -p` step that workflows previously had to do.
+
+    ```{note}
+    When stdout is a captured in-memory stream with no backing file descriptor
+    (Click's test runner, the Sphinx `{click:run}` directive that live-renders CLI
+    output in the docs), `fileno()` raises and we write to the stream directly. Such
+    streams are already Python text objects, so the Windows `cp1252` concern does not
+    apply: that only bites a real terminal, which always has a descriptor.
+    ```
     """
     if is_stdout(filepath):
-        return open(sys.stdout.fileno(), "w", encoding="UTF-8", closefd=False)
+        try:
+            fd = sys.stdout.fileno()
+        except (OSError, ValueError):
+            return sys.stdout
+        return open(fd, "w", encoding="UTF-8", closefd=False)
     filepath.parent.mkdir(parents=True, exist_ok=True)
     return filepath.open("w", encoding="UTF-8")
 
@@ -749,7 +772,12 @@ def metadata(ctx, format, overwrite, output, list_keys, keys):
             )
 
     if is_stdout(output):
-        if overwrite:
+        # The overwrite flag is moot for stdout. Warn only when the user set it
+        # explicitly: firing on the default value warns on every bare stdout run.
+        if (
+            overwrite
+            and ctx.get_parameter_source("overwrite") is not ParameterSource.DEFAULT
+        ):
             logging.warning("Ignore the --overwrite/--force/--replace option.")
         logging.info(f"Print metadata to {sys.stdout.name}")
     else:
@@ -766,7 +794,9 @@ def metadata(ctx, format, overwrite, output, list_keys, keys):
     meta = Metadata()
 
     # Output a warning in GitHub runners if metadata are not saved to $GITHUB_OUTPUT.
-    if is_github_ci():
+    # Skip the warning for stdout: writing to stdout is a legitimate use case
+    # (human inspection, --format json piping, Sphinx docs rendering) even in CI.
+    if is_github_ci() and not is_stdout(output):
         env_file = os.getenv("GITHUB_OUTPUT")
         if env_file and Path(env_file) != output:
             logging.warning(
@@ -1449,6 +1479,7 @@ def sync_mailmap(ctx, source, create_if_missing, destination_mailmap):
     default=False,
     help="Exit instantly on first failed test.",
 )
+@jobs_option
 @option(
     "-T",
     "--timeout",
@@ -1490,7 +1521,15 @@ def test_plan(
     (--plan-envvar), [tool.repomatic] config, or a built-in default.
     Each test invokes the command with the specified arguments and validates
     the output against expected patterns.
+
+    Cases run in parallel by default (see --jobs): each is an independent
+    process invocation, so they overlap well. Pass --jobs 1 for sequential
+    execution, which lets --exit-on-error stop on the first failure.
     """
+    # click-extra's --jobs option stores its clamped worker count on the
+    # context; it does not drive concurrency itself, so we read and act on it.
+    worker_count = context.get(ctx, context.JOBS, 1)
+
     # Load [tool.repomatic] config for fallback values.
     config = get_tool_config(ctx)
 
@@ -1540,16 +1579,21 @@ def test_plan(
 
     counter = Counter(total=len(test_list), skipped=0, failed=0)
 
+    # Select the cases to run (respecting --select-test), keeping their 1-based
+    # numbers for stable reporting.
+    pending: list[tuple[int, CLITestCase]] = []
     for index, test_case in enumerate(test_list):
         test_number = index + 1
-        test_name = f"#{test_number}"
-        logging.info(f"Run test {test_name}...")
-
         if select_test and test_number not in select_test:
-            logging.warning(f"Test {test_name} skipped by user request.")
+            logging.warning(f"Test #{test_number} skipped by user request.")
             counter["skipped"] += 1
             continue
+        pending.append((test_number, test_case))
 
+    def run_case(item: tuple[int, CLITestCase]) -> tuple[int, str, CLITestCase]:
+        """Run one case, returning its number, outcome, and the case itself."""
+        test_number, test_case = item
+        logging.info(f"Run test #{test_number}...")
         try:
             logging.debug(f"Test case parameters: {test_case}")
             test_case.run_cli_test(
@@ -1558,16 +1602,44 @@ def test_plan(
                 default_timeout=timeout,
             )
         except SkippedTest as ex:
-            counter["skipped"] += 1
-            logging.warning(f"Test {test_name} skipped: {ex}")
+            logging.warning(f"Test #{test_number} skipped: {ex}")
+            return test_number, "skipped", test_case
         except Exception as ex:  # noqa: BLE001
+            logging.error(f"Test #{test_number} failed: {ex}")
+            return test_number, "failed", test_case
+        return test_number, "passed", test_case
+
+    def tally(outcome: tuple[int, str, CLITestCase]) -> bool:
+        """Record an outcome in the counters and echo a failure's trace.
+
+        :return: `True` if the case failed.
+        """
+        _, status, test_case = outcome
+        if status == "skipped":
+            counter["skipped"] += 1
+        elif status == "failed":
             counter["failed"] += 1
-            logging.error(f"Test {test_name} failed: {ex}")
             if show_trace_on_error and test_case.execution_trace:
                 echo(test_case.execution_trace)
-            if exit_on_error:
+        return status == "failed"
+
+    if worker_count == 1 or len(pending) <= 1:
+        # Sequential: --exit-on-error can short-circuit on the first failure.
+        for item in pending:
+            if tally(run_case(item)) and exit_on_error:
                 logging.debug("Don't continue testing, a failed test was found.")
                 ctx.exit(1)
+    else:
+        # Parallel: subprocess.run releases the GIL while the child runs, so
+        # worker threads overlap each case's process spawn and execution. All
+        # selected cases run (--exit-on-error has no effect); executor.map
+        # yields in submission order, keeping traces and counters ordered.
+        logging.info(
+            f"Run {len(pending)} test cases across {worker_count} parallel workers."
+        )
+        with ThreadPoolExecutor(max_workers=worker_count) as executor:
+            for outcome in executor.map(run_case, pending):
+                tally(outcome)
 
     if stats:
         echo(
@@ -2622,9 +2694,22 @@ def verify_binary(target: str, binary_path: Path) -> None:
     echo(f"Binary architecture verified for {target}: {binary_path}")
 
 
+AUDIT_HEADER_DEFS: tuple[tuple[str, str], ...] = (
+    ("Package", "package"),
+    ("Version", "version"),
+    ("Advisory", "advisory"),
+    ("Fixed", "fixed"),
+    ("Sources", "sources"),
+)
+"""Column definitions for the `repomatic audit` table."""
+
+_audit_sort = SortByOption(*AUDIT_HEADER_DEFS, default="package")
+
+
 @repomatic.command(
-    short_help="Upgrade packages with known vulnerabilities",
-    section=_section_sync,
+    short_help="Report (and optionally fix) vulnerable dependencies",
+    section=_section_lint,
+    params=[_audit_sort],
 )
 @option(
     "--lockfile",
@@ -2638,58 +2723,81 @@ def verify_binary(target: str, binary_path: Path) -> None:
     type=str,
     default=lambda: os.environ.get("GITHUB_REPOSITORY", ""),
     help=(
-        "Repository in OWNER/NAME format. Required to query the GitHub"
-        " Advisory Database. Defaults to GITHUB_REPOSITORY when set."
+        "Repository in OWNER/NAME format. Enables the GitHub Advisory"
+        " Database source. Defaults to GITHUB_REPOSITORY when set."
+    ),
+)
+@option(
+    "--fix/--no-fix",
+    default=False,
+    help=(
+        "Upgrade fixable packages and persist cooldown exemptions"
+        " (mutates uv.lock and pyproject.toml). Default: report only."
     ),
 )
+@option(
+    "--exit-zero/--no-exit-zero",
+    default=False,
+    help="In report mode, exit 0 even when vulnerabilities are found.",
+)
 @option(
     "--output",
     type=file_path(writable=True, resolve_path=True, allow_dash=True),
     default=None,
-    help="Write a markdown report (vulnerabilities + updates) to this file.",
+    help="Write a markdown report to this file.",
 )
 @output_format_option
 @pass_context
-def fix_vulnerable_deps_cmd(
+def audit(
     ctx: Context,
     lockfile: Path,
     repo: str,
+    fix: bool,
+    exit_zero: bool,
     output: Path | None,
     output_format: str,
 ) -> None:
-    """Detect and upgrade packages with known security vulnerabilities.
+    """Scan locked dependencies for known security vulnerabilities.
 
     \b
-    Queries every advisory database enabled in
+    Read-only by default: queries every advisory database enabled in
     [tool.repomatic] vulnerable-deps.sources (default: uv-audit and
-    github-advisories), unions and deduplicates the results, then upgrades
-    each fixable package with uv lock --upgrade-package and:
+    github-advisories), unions and deduplicates the results, and prints
+    them. The table respects the global --table-format option (github,
+    json, csv, etc.), so --table-format json yields a machine-readable
+    report. Report mode exits 1 when any vulnerability is found (use
+    --exit-zero to override), so it can gate CI.
+
+    \b
+    With --fix, upgrades each fixable package with uv lock --upgrade-package
+    and:
       - bypasses the exclude-newer cooldown for security fixes
       - persists exclude-newer-package entries in pyproject.toml
       - prints a markdown report of vulnerabilities and version changes
 
     \b
     Examples:
-        # Scan and fix vulnerabilities (uses GITHUB_REPOSITORY when set)
-        repomatic fix-vulnerable-deps
+        # Report known vulnerabilities (read-only)
+        repomatic audit
 
     \b
-        # Force a specific repository for the GHSA query
-        repomatic fix-vulnerable-deps --repo owner/name
+        # Machine-readable output
+        repomatic --table-format json audit
 
     \b
-        # CI: write markdown report as a GitHub Actions step output
-        repomatic fix-vulnerable-deps \\
+        # Upgrade fixable packages (mutates uv.lock and pyproject.toml)
+        repomatic audit --fix
+
+    \b
+        # CI autofix job: write the markdown report as a step output
+        repomatic audit --fix --repo owner/name \\
             --output "$GITHUB_OUTPUT" --output-format github-actions
     """
     config = get_tool_config(ctx)
-    if not config.vulnerable_deps.sync:
-        logging.info(
-            "[tool.repomatic] vulnerable-deps.sync is disabled."
-            " Skipping vulnerability scan."
-        )
-        ctx.exit(0)
 
+    # Parse the configured advisory sources, dropping the GitHub Advisory
+    # Database when neither --repo nor GITHUB_REPOSITORY is available to
+    # query it.
     sources: list[AdvisorySource] = []
     for raw in config.vulnerable_deps.sources:
         try:
@@ -2706,28 +2814,67 @@ def fix_vulnerable_deps_cmd(
         )
         sources = [s for s in sources if s is not AdvisorySource.GITHUB_ADVISORIES]
 
-    has_fixes, diff_table = _fix_vulnerable_deps(
+    if fix:
+        # vulnerable-deps.sync gates the autofix (mutation), not reporting.
+        if not config.vulnerable_deps.sync:
+            logging.info(
+                "[tool.repomatic] vulnerable-deps.sync is disabled. Skipping --fix."
+            )
+            ctx.exit(0)
+
+        has_fixes, diff_table = _fix_vulnerable_deps(
+            lockfile, repo=repo or None, sources=sources or None
+        )
+        if not has_fixes:
+            echo("No fixable vulnerabilities found.")
+            ctx.exit(0)
+
+        echo("Upgraded vulnerable packages.")
+        if diff_table:
+            echo(diff_table)
+        if output and diff_table:
+            # Keep the github-actions key as `diff_table`: the autofix
+            # workflow's pr-metadata step reads steps.fix.outputs.diff_table.
+            if output_format == "github-actions":
+                content = format_multiline_output("diff_table", diff_table)
+            else:
+                content = diff_table
+            echo(content, file=prep_path(output))
+        ctx.exit(0)
+
+    # Report mode (default, read-only).
+    vulns = collect_vulnerable_packages(
         lockfile, repo=repo or None, sources=sources or None
     )
-
-    if not has_fixes:
-        echo("No fixable vulnerabilities found.")
+    if not vulns:
+        echo("No known vulnerabilities found.")
         ctx.exit(0)
 
-    echo("Upgraded vulnerable packages.")
-    if diff_table:
-        echo(diff_table)
+    rows = [
+        (
+            v.name,
+            v.current_version,
+            v.advisory_id,
+            v.fixed_version or "unknown",
+            ", ".join(sorted(s.value for s in v.sources)) or "—",
+        )
+        for v in vulns
+    ]
+    ctx.print_table(AUDIT_HEADER_DEFS, rows)  # type: ignore[attr-defined]
 
-    if output and diff_table:
+    if output:
+        markdown = format_vulnerability_table(vulns)
         if output_format == "github-actions":
-            content = format_multiline_output("diff_table", diff_table)
+            content = format_multiline_output("vuln_table", markdown)
         else:
-            content = diff_table
+            content = markdown
         echo(content, file=prep_path(output))
 
+    ctx.exit(0 if exit_zero else 1)
+
 
 @repomatic.command(
-    short_help="Re-lock dependencies and prune stale cooldown overrides",
+    short_help="Re-lock dependencies and roll cooldown overrides forward",
     section=_section_sync,
 )
 @option(
@@ -2766,8 +2913,10 @@ def sync_uv_lock_cmd(
 
     \b
     Wraps uv lock --upgrade and:
-      - prunes stale exclude-newer-package entries from pyproject.toml
-        whose locked version has aged past the exclude-newer cutoff
+      - prunes exclude-newer-package entries from pyproject.toml whose held
+        version has aged past the exclude-newer cutoff, then freezes the
+        survivors at their locked version (a fixed date) so the upgrade
+        holds them instead of tracking newer releases
       - prints a table of updated packages with upload dates
       - optionally fetches release notes from GitHub (markdown)
 

{repomatic-6.26.0 → repomatic-6.28.0}/repomatic/config.py

@@ -284,6 +284,30 @@ class TestMatrixConfig:
     Additive to the upstream default excludes.
     """
 
+    full_include: list[dict[str, str]] = field(
+        default_factory=list,
+        metadata={"click_extra.config_path": "full-include"},
+    )
+    """Full-matrix-only job rows, added as standalone matrix combinations.
+
+    Each entry is a dict of GitHub Actions matrix keys fully describing one job
+    (like `{"os": "ubuntu-24.04-arm", "python-version": "3.10",
+    "click-version": "8.3.1"}`). Unlike `include`, these are appended as
+    independent rows of the full matrix, never merged into the base
+    cross-product, so a cell can't overwrite a shipped-config job that shares
+    its `os` and `python-version`. Keys left out inherit the matrix defaults
+    (the single-key `include` entries, plus `state: stable`), so a cell lists
+    only what differs from the shipped configuration.
+
+    Use this for heterogeneous coverage, like pinning each release of a
+    dependency to its own runner and Python, where carving the same shape from
+    the base cross-product with `exclude` would take many rules. Like
+    `variations` and `unstable`, it touches the full matrix only; the PR matrix
+    stays a curated reduced set. Adding any entry makes the full matrix emit as
+    a flat job list (`{"include": [...]}`), which GitHub runs verbatim with no
+    cross-product expansion.
+    """
+
     include: list[dict[str, str]] = field(default_factory=list)
     """Extra include directives applied to both full and PR test matrices.