Skip to content

Refresh stale package specs and add linters doc drift guard#46257

Merged
pelikhan merged 4 commits into
mainfrom
copilot/spec-librarian-audit-2026-07-17
Jul 18, 2026
Merged

Refresh stale package specs and add linters doc drift guard#46257
pelikhan merged 4 commits into
mainfrom
copilot/spec-librarian-audit-2026-07-17

Conversation

Copilot AI commented Jul 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

The spec-librarian audit reported documentation drift across package specs, including missing PinContext.SkipHardcodedFallback and a missing mapclearloop analyzer entry. This PR updates stale package READMEs and adds a guard to keep pkg/linters/README.md and pkg/linters/doc.go aligned.

  • Spec parity updates (pkg/actionpins, pkg/linters)

    • Added a dedicated PinContext fields table in pkg/actionpins/README.md, including SkipHardcodedFallback.
    • Added mapclearloop to pkg/linters/README.md across overview, subpackage API table, and dependency listing.

  • Stale spec refreshes (source-synced READMEs)

    • Refreshed stale specs for:
      • pkg/cli/README.md
      • pkg/constants/README.md
      • pkg/modelsdev/README.md
      • pkg/parser/README.md
      • pkg/semverutil/README.md
      • pkg/workflow/README.md
    • Added source-synchronization notes to capture current alignment with recent source changes.

  • Drift prevention for linters docs

    • Extended pkg/linters/doc_sync_test.go with a new check that compares analyzer names in:
      • doc.go bullet list
      • README.md subpackages table
    • Fails on mismatch to enforce simultaneous updates.
func TestDocGo_AnalyzersMatchREADME(t *testing.T) {
    // parses analyzer names from doc.go and README.md
    // asserts the sorted sets are identical
}

Copilot AI linked an issue Jul 17, 2026 that may be closed by this pull request
[spec-librarian] Specification Audit — 2026-07-17 — 9 issues found #46256
Closed
6 tasks
Copilot AI and others added 3 commits July 17, 2026 14:00
@pelikhan
chore: outline plan for spec audit fixes
f18d367 
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
@pelikhan
docs: refresh package specs and enforce linters doc sync
f98483e 
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
@pelikhan
chore: revert unrelated auto-upgrade cron change
5ab25bd 
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot AI changed the title [WIP] Audit specification for 8 packages with outdated updates Refresh stale package specs and add linters doc drift guard Jul 17, 2026
Copilot AI requested a review from pelikhan July 17, 2026 14:31
@pelikhan
pelikhan marked this pull request as ready for review July 18, 2026 05:31
Copilot AI review requested due to automatic review settings July 18, 2026 05:31
Copilot AI reviewed Jul 18, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Refreshes package specifications and adds a test guard against linter documentation drift.

Changes:

  • Documents PinContext fields and mapclearloop.
  • Marks six package specifications as source-reviewed.
  • Compares analyzer listings across linter documentation.
Show a summary per file
File Description
pkg/actionpins/README.md Documents PinContext fields.
pkg/cli/README.md Adds source synchronization note.
pkg/constants/README.md Adds source synchronization note.
pkg/linters/README.md Documents mapclearloop.
pkg/linters/doc_sync_test.go Adds analyzer-list parity guard.
pkg/modelsdev/README.md Adds source synchronization note.
pkg/parser/README.md Adds source synchronization note.
pkg/semverutil/README.md Adds source synchronization note.
pkg/workflow/README.md Adds source synchronization note.

Review details

Tip

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

  • Files reviewed: 9/9 changed files
  • Comments generated: 2
  • Review effort level: Medium

Comment thread pkg/actionpins/README.md
| `AllowActionRefs` | `bool` | Downgrades unresolved pinning failures to warnings |
| `Warnings` | `map[string]bool` | Shared warning dedupe map keyed by `repo@version` |
| `RecordResolutionFailure` | `func(ResolutionFailure)` | Optional callback for unresolved pinning events |
| `SkipHardcodedFallback` | `bool` | Skips version→SHA hardcoded fallback after dynamic resolver failure while preserving SHA→version labeling |
Comment thread pkg/linters/doc_sync_test.go
Comment on lines +71 to +84
readmeTableRe := regexp.MustCompile(`^\|\s+` + "`" + `([a-z0-9-]+)` + "`" + `\s+\|`)
for line := range strings.SplitSeq(string(readmeBytes), "\n") {
if !strings.HasPrefix(line, "| `") {
continue
}
m := readmeTableRe.FindStringSubmatch(line)
if m == nil {
continue
}
if m[1] == "internal" {
continue
}
readmeSet[m[1]] = struct{}{}
}
@pelikhan
pelikhan merged commit bfe3aa0 into main Jul 18, 2026
31 checks passed
@pelikhan
pelikhan deleted the copilot/spec-librarian-audit-2026-07-17 branch July 18, 2026 05:46
@github-actions github-actions Bot mentioned this pull request Jul 18, 2026
Closed
@github-actions

github-actions Bot commented Jul 18, 2026

Copy link
Copy Markdown
Contributor

🎉 This pull request is included in a new release.

Release: v0.82.13

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@pelikhan pelikhan Awaiting requested review from pelikhan

Assignees

@pelikhan pelikhan

Copilot code review Copilot

Labels

pr-action:batch_review pr-agent:copilot pr-batch:docs-updates pr-priority:low pr-risk:low pr-type:docs

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[spec-librarian] Specification Audit — 2026-07-17 — 9 issues found

3 participants

@pelikhan