Repository navigation
Complete package specifications and reconcile API documentation - #76523
Conversation
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
|
✅ PR Specification Reviewer completed successfully! PR Specification ReviewerOutcome: 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.
|
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ Matt Pocock Skills ReviewerOutcome: 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.
|
|
✅ 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: 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.
|
|
✅ PR Code Quality Reviewer completed the code quality review. PR Code Quality ReviewerOutcome: 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.
|
|
✅ Test Quality Sentinel completed test quality analysis. Test Quality SentinelOutcome: 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.
|
|
✅ Ponytail Reviewer completed successfully! Ponytail ReviewerOutcome: 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.
|
There was a problem hiding this comment.
🟡 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)
| | `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. | |
|
🎉 This pull request is included in a new release. Release: |


The package audit found missing specifications across workflow, CLI, and linter packages, along with undocumented exported APIs and an inaccurate
envutilwarning-output claim.envutilwrites warnings to stderr without a logger and routes them through the provided logger otherwise.