Expose rule authority URL manifest and add bulk docs prefetch command by Copilot · Pull Request #65 · bitflight-devops/skilllint

Copilot · 2026-05-12T23:57:59Z

Rule authority references were scattered across series modules with no single API to enumerate them, making bulk vendor-cache warming and authority auditing cumbersome. This change adds a registry-level authority URL manifest iterator and a docs command to fetch that manifest in one pass.

Rule registry: authority URL manifest API
- Added iter_authority_urls(*, unique: bool = True) to rule_registry.
- Iterates RuleEntry.authority.reference across registered rules.
- Defaults to deduped output (with stable first-seen order); supports unique=False to retain duplicates.
Docs CLI: bulk prefetch from registry authorities
- Added skilllint docs fetch-authorities.
- Pulls URLs from iter_authority_urls(unique=True) and fetches each through existing fetch_or_cached(...).
- Supports the same cache controls as docs fetch (--ttl, --force).
- Emits one cached path per successful fetch; exits non-zero if any authority URL cannot be fetched and has no usable cache fallback.
Tests and docs updates
- Added focused unit tests for:
  - deduped and non-deduped manifest iteration behavior
  - docs fetch-authorities success path, option forwarding, and partial-failure exit behavior
- Updated CLI docs/examples in README.md and CLAUDE.md to include fetch-authorities.

from skilllint.rule_registry import iter_authority_urls

# Default: deduped authority references for bulk cache warming
for url in iter_authority_urls():
    print(url)

# Optional: include duplicates for per-rule mapping workflows
all_refs = list(iter_authority_urls(unique=False))

Agent-Logs-Url: https://github.com/bitflight-devops/skilllint/sessions/fd38ea46-062c-499d-8243-f33cffb96666 Co-authored-by: Jamie-BitFlight <25075504+Jamie-BitFlight@users.noreply.github.com>

github-actions · 2026-05-13T00:17:48Z

📊 Test Coverage Report

Coverage: 82.89%

📥 Coverage XML available as artifact: coverage-xml

github-actions · 2026-05-13T00:19:18Z

Benchmark Results

✅ No regressions — threshold: 30%

scan-clean

Metric	Base	Compare	Change
`files_per_second`	67.8 files/s	67.8 files/s	✅ +0.0%
`scan_max_ms`	15203.9 ms	14887.3 ms	✅ -2.1%
`scan_mean_ms`	14772.1 ms	14769.1 ms	✅ -0.0%
`scan_min_ms`	14470.9 ms	14683.4 ms	➡️ +1.5%

scan-violations

Metric	Base	Compare	Change
`files_per_second`	83.3 files/s	84.3 files/s	✅ +1.3%
`scan_max_ms`	2534.7 ms	2411.4 ms	✅ -4.9%
`scan_mean_ms`	2414.4 ms	2383.3 ms	✅ -1.3%
`scan_min_ms`	2327.0 ms	2366.3 ms	➡️ +1.7%

fix-violations

Metric	Base	Compare	Change
`fix_files_per_second`	90.5 files/s	89.3 files/s	➡️ -1.3%
`fix_max_ms`	2232.6 ms	2260.1 ms	➡️ +1.2%
`fix_mean_ms`	2222.2 ms	2252.0 ms	➡️ +1.3%
`fix_min_ms`	2213.7 ms	2246.9 ms	➡️ +1.5%

cpu

Metric	Base	Compare	Change
`cpu_clean_mean_ms`	0.6 ms	0.6 ms	➡️ +0.3%
`cpu_fix_mean_ms`	2.0 ms	2.0 ms	➡️ +1.4%
`cpu_violations_mean_ms`	0.8 ms	0.8 ms	➡️ +0.1%

View benchmark history

_{Updated 2026-05-13 00:19 UTC}

Copilot

Pull request overview

This PR centralizes “rule authority” documentation references by adding a registry-level iterator for authority references and a new skilllint docs fetch-authorities CLI command to prefetch/cache those docs in bulk.

Changes:

Added iter_authority_urls(unique=...) to enumerate rule authority references from the registry (optionally deduped).
Added skilllint docs fetch-authorities to fetch/cache all registry authority references in one pass with --ttl/--force.
Added unit tests and updated README/CLAUDE docs to document the new subcommand.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Documents the new `docs fetch-authorities` subcommand and example usage.
packages/skilllint/rule_registry.py	Adds `iter_authority_urls()` iterator and exports it.
packages/skilllint/cli_docs.py	Implements `docs fetch-authorities` Typer command that calls the iterator and fetches via `fetch_or_cached()`.
packages/skilllint/tests/test_rule_registry.py	Adds tests for unique vs non-unique authority iteration behavior.
packages/skilllint/tests/test_cli_docs.py	Adds tests for `docs fetch-authorities` success path, option forwarding, and partial-failure exit code.
CLAUDE.md	Adds a short example of `docs fetch-authorities`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    authority_urls = list(iter_authority_urls(unique=True))
+    if not authority_urls:
+        err_console.print(":warning: [yellow]No authority URLs found in the rule registry[/yellow]")
+        return
+
+    had_failure = False
+    for url in authority_urls:
+        try:
+            result = fetch_or_cached(url, ttl_hours=ttl, force=force)


+def iter_authority_urls(*, unique: bool = True) -> Iterator[str]:
+    """Iterate authority reference URLs declared by registered rules.
+
+    Args:
+        unique: When True, yield each reference URL at most once while preserving
+            first-seen order (by sorted rule ID). When False, include duplicates.
+
+    Yields:
+        Authority reference URL strings from RuleEntry.authority.reference.
+    """
+    seen: set[str] = set()
+    for rule in list_rules():
+        reference = rule.authority.reference if rule.authority is not None else None
+        if not reference:


+Fetches every unique authority reference URL declared by the rule registry. Prints one
+cached file path per successful fetch. Exits 1 if any URL cannot be fetched and no stale
+cache is available.


+    def test_fetches_all_authority_urls(self, cli_runner: CliRunner, mocker: MockerFixture) -> None:
+        """Fetches each authority URL and prints one path per success."""
+        mock_iter = mocker.patch("skilllint.cli_docs.iter_authority_urls")
+        mock_iter.return_value = iter([_TEST_URL, _TEST_URL_2])
+
+        mock_fetch = mocker.patch("skilllint.cli_docs.fetch_or_cached")
+        mock_fetch.side_effect = [
+            _cache_result(CacheStatus.FRESH, path=_TEST_PATH),
+            _cache_result(CacheStatus.NEW, path=_TEST_PATH_2),
+        ]
+
+        result = cli_runner.invoke(plugin_validator.app, ["docs", "fetch-authorities"])
+
+        assert result.exit_code == 0
+        mock_iter.assert_called_once_with(unique=True)
+        assert mock_fetch.call_count == 2
+        assert str(_TEST_PATH) in result.output
+        assert str(_TEST_PATH_2) in result.output


Initial plan

99aa41e

Copilot AI assigned Copilot and Jamie-BitFlight May 12, 2026

Copilot started work on behalf of Jamie-BitFlight May 12, 2026 23:58 View session

Copilot AI linked an issue May 12, 2026 that may be closed by this pull request

feat: Expose authority URL manifest for bulk vendor cache pre-fetch #43

Open

2 tasks

Copilot AI and others added 2 commits May 13, 2026 00:01

feat: expose authority URL manifest and docs bulk fetch command

4e1012e

Agent-Logs-Url: https://github.com/bitflight-devops/skilllint/sessions/fd38ea46-062c-499d-8243-f33cffb96666 Co-authored-by: Jamie-BitFlight <25075504+Jamie-BitFlight@users.noreply.github.com>

chore: address review feedback on rule registry typing import

6a68584

Agent-Logs-Url: https://github.com/bitflight-devops/skilllint/sessions/fd38ea46-062c-499d-8243-f33cffb96666 Co-authored-by: Jamie-BitFlight <25075504+Jamie-BitFlight@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add authority URL manifest for bulk vendor cache pre-fetch~~ Expose rule authority URL manifest and add bulk docs prefetch command May 13, 2026

Copilot AI requested a review from Jamie-BitFlight May 13, 2026 00:04

Copilot finished work on behalf of Jamie-BitFlight May 13, 2026 00:04

Copilot started work on behalf of Jamie-BitFlight May 13, 2026 00:10 View session

Copilot finished work on behalf of Jamie-BitFlight May 13, 2026 00:11

Jamie-BitFlight marked this pull request as ready for review May 13, 2026 00:16

Copilot AI review requested due to automatic review settings May 13, 2026 00:16

Copilot started reviewing on behalf of Jamie-BitFlight May 13, 2026 00:16 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Copilot started work on behalf of Jamie-BitFlight May 13, 2026 00:36 View session

Copilot finished work on behalf of Jamie-BitFlight May 13, 2026 00:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expose rule authority URL manifest and add bulk docs prefetch command#65

Expose rule authority URL manifest and add bulk docs prefetch command#65
Copilot wants to merge 3 commits into
mainfrom
copilot/expose-authority-url-manifest

Copilot AI commented May 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 13, 2026

📊 Test Coverage Report

Uh oh!

github-actions Bot commented May 13, 2026

Benchmark Results

scan-clean

scan-violations

fix-violations

cpu

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented May 12, 2026 •

edited

Loading