Skip to content

Complete package specifications and reconcile API documentation - #76523

Merged
pelikhan merged 2 commits into
mainfrom
copilot/spec-librarian-audit-fixes
Nov 10, 2026
Merged

pelikhan merged 2 commits into
mainfrom
copilot/spec-librarian-audit-fixes

Conversation

Copilot AI commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

The package audit found missing specifications across workflow, CLI, and linter packages, along with undocumented exported APIs and an inaccurate envutil warning-output claim.

  • Package coverage: Add READMEs for workflow subpackages and CLI data; define centralized documentation for linter analyzers and internal helpers.
  • API accuracy: Document verified parser, workflow, and workqueue APIs.
  • Warning behavior: Clarify that envutil writes warnings to stderr without a logger and routes them through the provided logger otherwise.

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Copilot AI changed the title [WIP] Document workflow subpackages and fix API discrepancies Complete package specifications and reconcile API documentation Nov 10, 2026
Copilot AI requested a review from gh-aw-bot November 10, 2026 13:59
@pelikhan
pelikhan marked this pull request as ready for review November 10, 2026 14:33
Copilot AI adaptive review requested due to automatic review settings November 10, 2026 14:33
@pelikhan
pelikhan merged commit d6c9749 into main Nov 10, 2026
64 checks passed
@pelikhan
pelikhan deleted the copilot/spec-librarian-audit-fixes branch November 10, 2026 14:33
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

✅ PR Specification Reviewer completed successfully!

PR Specification Reviewer

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from PR Specification Reviewer · gpt56 · ~1 AIC · ⌖ ~1 AIC · ◇ ~1 AIC · ⊞ 1.6K · ◷

Generated by PR Specification Reviewer for #76523

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

Matt Pocock Skills Reviewer

Outcome: reported_action

The agent completed and reported one or more actions. The no-op output is a completion signal, not a claim that no action was taken.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Matt Pocock Skills Reviewer · routed: haiku55 xhigh · ~9 AIC · ⌖ ~2 AIC · ⊞ 6.6K · ◷

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

✅ Design Decision Gate 🏗️ completed the design decision gate check. See the comment below for the result and any generated ADR draft.

Design Decision Gate 🏗️

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Design Decision Gate 🏗️ · routed: haiku55 xhigh · ~1 AIC · ⌖ ~2 AIC · ◇ ~1 AIC · ⊞ 8.5K · ◷

🏗️ ADR gate enforced by Design Decision Gate 🏗️

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

✅ PR Code Quality Reviewer completed the code quality review.

PR Code Quality Reviewer

Outcome: reported_action

The agent completed and reported one or more actions. The no-op output is a completion signal, not a claim that no action was taken.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from PR Code Quality Reviewer · gpt56 · ~4 AIC · ⌖ ~1 AIC · ◇ ~1 AIC · ⊞ 1.6K · ◷

🔎 Code quality review by PR Code Quality Reviewer

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

✅ Test Quality Sentinel completed test quality analysis.

Test Quality Sentinel

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Test Quality Sentinel · routed: haiku55 xhigh · ~1 AIC · ⌖ ~2 AIC · ◇ ~1 AIC · ⊞ 7.2K · ◷

🧪 Test quality analysis by Test Quality Sentinel

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

✅ Ponytail Reviewer completed successfully!

Ponytail Reviewer

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Ponytail Reviewer · routed: gpt61 medium · ~4 AIC · ⌖ ~1 AIC · ◇ ~1 AIC · ⊞ 181 · ◷

Generated by Ponytail Reviewer for #76523

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.

🟡 Changes recommended

A critical documentation-sync issue remains because the README’s analyzer-name ordering causes the repository’s sync tests to fail, with additional documentation inaccuracies about identifier scope, parser error exposure, and shell-analysis result categories.

4 open issues
What changed in this PR

This pull request completes package-specification coverage across workflow, CLI, parser, workqueue, and linter packages, reconciles documented APIs with their implementations, and corrects envutil warning-output behavior.

Changes:

  • Added READMEs for workflow subpackages, CLI data, and centralized linter helpers.
  • Documented previously omitted parser, workflow, and workqueue APIs.
  • Updated linter documentation policy and specification-audit workflow metadata.
  • Recorded documentation accuracy and linter synchronization findings for follow-up.
File Description
pkg/​workqueue/​README.md Documents the ObsoleteWorkIDs API.
pkg/​workflow/​taint/​README.md Adds the taint-analysis package specification.
pkg/​workflow/​shellpattern/​README.md Documents shell-expansion detection behavior.
pkg/​workflow/​README.md Adds workflow API documentation and links to subpackage specifications.
pkg/​workflow/​lint/​README.md Documents the workflow linter package and diagnostics.
pkg/​workflow/​gradershell/​README.md Documents Bash grader loading and static checks.
pkg/​workflow/​compilerenv/​README.md Documents environment override resolution APIs.
pkg/​workflow/​codemod/​README.md Documents source-preserving frontmatter codemods.
pkg/​workflow/​checkoutpolicy/​README.md Documents checkout trust predicates.
pkg/​workflow/​cachepolicy/​README.md Documents cache trigger policy helpers.
pkg/​workflow/​aw/​README.md Documents the authored workflow AST.
pkg/​workflow/​actionslanguageservice/​README.md Documents Actions expression and workflow parsing APIs.
pkg/​workflow/​actions/​README.md Documents the native Actions workflow AST and transformations.
pkg/​parser/​README.md Documents parser metadata APIs and read-only import-cache behavior.
pkg/​linters/​README.md Centralizes analyzer documentation and registry descriptions.
pkg/​linters/​internal/​README.md Documents shared internal linter helper packages.
pkg/​envutil/​README.md Clarifies stderr versus logger warning routing.
pkg/​cli/​data/​README.md Documents the embedded model catalogue.
.github/​workflows/​spec-librarian.md Defines centralized documentation rules for linter analyzers and internal helpers.
.github/​workflows/​spec-librarian.lock.yml Updates generated workflow metadata and integrity hashes.

Review effort: Lite (auto)

Comment thread pkg/linters/README.md
| `ctxbackground` | Custom `go/analysis` analyzer that flags `context.Background()` calls inside functions that already receive a context parameter |
| `deferinloop` | Custom `go/analysis` analyzer that flags `defer` statements inside `for`/`range` loop bodies that execute when the enclosing function returns rather than each iteration |
| `deferrerrorunchecked` | Custom `go/analysis` analyzer that flags deferred calls discarding errors, except zero-argument `Close()` methods |
| `deferred-error-unchecked` (`deferrerrorunchecked`) | Custom `go/analysis` analyzer that flags deferred calls discarding errors, except zero-argument `Close()` methods |
| `EditSource` | Merges semantic changes into authored YAML while retaining unaffected syntax. |
| `ValidateJob` | Validates one job's native Actions structure. |

Workflow and step IDs are job-scoped. A step can read only outputs from earlier steps in its job, and workflow-level environment values cannot reference job or step outputs.

This package implements the Actions expression grammar used by the compiler and linter. It parses syntax and tracks source ranges; it does not evaluate expressions, execute workflow code, or replace schema validation.

Expression length and nesting are bounded by `MaxExpressionLength` and `MaxExpressionDepth`. Parsing errors are value-safe and do not include the full source expression in debug logging.
|--------|-------------|
| `ValidRunPath` | Accepts literal relative `.sh` paths without traversal or shell expressions. |
| `Load` | Reads a regular UTF-8 Bash source file from within the repository, without executing it. |
| `Check` | Returns findings for supported direct file-write patterns in a Bash source string. |
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This pull request is included in a new release.

Release: v1.2.3

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[spec-librarian] Specification Audit — 2026-11-10 — 121 issues found

4 participants