Conversation
5 tasks
Agent-Logs-Url: https://github.com/github/gh-aw/sessions/0eb250f6-a1e9-4e26-a498-f96203f95352 Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
…7 packages - Renamed ## Functions/## Types/## Core Components to ## Public API in 17 packages - Added ## Usage Examples (or renamed ## Usage) in 17 packages - Added ## Dependencies to 10 packages with internal deps - Updated ## Dependencies in cli (9 missing pkgs), parser (wrong/missing external), workflow (missing external) Closes #1308 Agent-Logs-Url: https://github.com/github/gh-aw/sessions/0eb250f6-a1e9-4e26-a498-f96203f95352 Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Fix naming and structure violations in package specifications
docs: fix spec audit — add Public API, Usage Examples, and Dependencies to 17 packages
May 4, 2026
pelikhan
approved these changes
May 4, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Updates package specifications to satisfy an automated spec audit by standardizing section structure and improving completeness of exported API, usage, and dependency documentation across multiple packages.
Changes:
- Renamed/standardized exported API sections to
## Public APIacross affected package specs. - Added
## Usage Examplessections to 17 package READMEs. - Added/corrected
## Dependenciessections (including internalpkg/dependencies and corrected external module paths/versions) and updated a locked workflow allowlist.
Show a summary per file
| File | Description |
|---|---|
| pkg/workflow/README.md | Corrects/extends external dependency list (go-yaml module path, adds go-gh and jsonschema v6). |
| pkg/typeutil/README.md | Renames API section to Public API; adds usage examples and internal dependency docs. |
| pkg/types/README.md | Renames API section to Public API; adds usage examples. |
| pkg/tty/README.md | Renames API section to Public API; adds usage examples. |
| pkg/timeutil/README.md | Renames API section to Public API; adds usage examples. |
| pkg/testutil/README.md | Renames API section to Public API; adds usage examples. |
| pkg/styles/README.md | Adds Public API summary table; renames Usage to Usage Examples. |
| pkg/stringutil/README.md | Reframes top-level section to Public API; adds usage examples and dependency docs. |
| pkg/sliceutil/README.md | Renames API section to Public API; adds usage examples. |
| pkg/semverutil/README.md | Consolidates types/functions under Public API; adds usage examples and dependency docs. |
| pkg/repoutil/README.md | Renames API section to Public API; adds usage examples and dependency docs. |
| pkg/parser/README.md | Corrects external dependencies (jsonschema v6, go-yaml module path) and documents additional external deps. |
| pkg/logger/README.md | Adds Public API section/table; renames Usage to Usage Examples; adds dependency docs. |
| pkg/gitutil/README.md | Renames API section to Public API; adds usage examples and dependency docs. |
| pkg/fileutil/README.md | Renames API section to Public API; adds usage examples and dependency docs. |
| pkg/envutil/README.md | Splits API docs into Public API + Usage Examples; adds dependency docs. |
| pkg/constants/README.md | Moves semantic types under Public API; adds usage examples. |
| pkg/console/README.md | Adds Public API summary table; adds usage examples and dependency docs. |
| pkg/cli/README.md | Expands internal dependency list to include missing pkg/ packages. |
| pkg/agentdrain/README.md | Consolidates under Public API; adds usage examples and dependency docs. |
| .github/workflows/daily-model-inventory.lock.yml | Adds shell(playwright-cli:*) to the allow-tool list for the Copilot execution step. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (1)
pkg/styles/README.md:95
- The
## Usage Examplessnippet usesfmt.Printlnandlipgloss.NewStyle()but only importspkg/styles. Consider adding the required imports (e.g.,fmtandcharm.land/lipgloss/v2) or simplifying the example so it doesn’t reference undeclared identifiers/packages.
## Usage Examples
```go
import "github.com/github/gh-aw/pkg/styles"
// Use pre-configured styles
fmt.Println(styles.Error.Render("Something went wrong"))
fmt.Println(styles.Success.Render("Operation completed"))
fmt.Println(styles.Command.Render("gh aw compile"))
// Use adaptive colors for custom styles
customStyle := lipgloss.NewStyle().
Foreground(styles.ColorInfo).
Bold(true)
fmt.Println(customStyle.Render("Custom styled text"))
</details>
- **Files reviewed:** 21/21 changed files
- **Comments generated:** 5
Comment on lines
+118
to
+126
| // HTTP MCP server with OIDC auth | ||
| cfg := types.BaseMCPServerConfig{ | ||
| Type: "http", | ||
| URL: "https://my-mcp-server.example.com", | ||
| Auth: &types.MCPAuthConfig{ | ||
| Type: "github-oidc", | ||
| Audience: "https://my-mcp-server.example.com", | ||
| }, | ||
| } |
Comment on lines
+85
to
+88
| // Map a slice | ||
| names := []string{"alice", "bob"} | ||
| upper := sliceutil.Map(names, strings.ToUpper) | ||
| // upper = ["ALICE", "BOB"] |
Comment on lines
+60
to
+66
| ```go | ||
| import "github.com/github/gh-aw/pkg/timeutil" | ||
|
|
||
| // Format a time.Duration | ||
| timeutil.FormatDuration(500 * time.Millisecond) // "500ms" | ||
| timeutil.FormatDuration(2500 * time.Millisecond) // "2.5s" | ||
| timeutil.FormatDuration(90 * time.Second) // "1.5m" |
Comment on lines
+61
to
+73
| import "github.com/github/gh-aw/pkg/testutil" | ||
|
|
||
| func TestMyFunction(t *testing.T) { | ||
| // Create an isolated temp directory for test artifacts | ||
| dir := testutil.TempDir(t, "my-test-*") | ||
| // dir is cleaned up automatically when the test ends | ||
|
|
||
| // Capture output written to os.Stderr | ||
| output := testutil.CaptureStderr(t, func() { | ||
| myFunction() // function that writes to os.Stderr | ||
| }) | ||
| assert.Contains(t, output, "expected message") | ||
| } |
Comment on lines
+448
to
+459
| ```go | ||
| import "github.com/github/gh-aw/pkg/constants" | ||
|
|
||
| // Engine constants | ||
| engine := constants.CopilotEngine // EngineName("copilot") | ||
| fmt.Println(engine.String()) // "copilot" | ||
| fmt.Println(engine.IsValid()) // true | ||
|
|
||
| // Resolve an engine option for display and secret info | ||
| opt := constants.GetEngineOption("copilot") | ||
| fmt.Println(opt.Label) // "GitHub Copilot" | ||
| fmt.Println(opt.SecretName) // "COPILOT_GITHUB_TOKEN" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automated spec audit flagged 47 issues across 22 packages: missing
## Public APIsections, missing## Usage Examples, and incomplete/absent## Dependenciesdocumentation.Section renames (17 packages)
## Functions→## Public API:fileutil,gitutil,repoutil,sliceutil,testutil,timeutil,tty,typeutil## Types→## Public API(with### Typessubsection):types,semverutil,agentdrain## Core Components→### Core Componentsunder new## Public API:agentdrain## Semantic Types→## Public API+### Semantic Types:constants## Usage(containing API docs) →## Public API+ separate## Usage Examples:envutil## Public APIsummary tables:console,logger,stringutil,stylesUsage Examples added (17 packages)
Idiomatic code snippets added to all 17 packages.
envutil,logger, andstyleshad## Usagerenamed; the rest received new sections.Dependencies added (10 packages)
All packages with internal
pkg/imports were missing dependency docs:agentdrain,console,envutil,fileutil,gitutil,logger,repoutil,semverutil,stringutil,typeutil.Dependencies corrected (3 packages)
cli: 9 missing internal packages added (agentdrain,envutil,semverutil,sliceutil,stats,styles,timeutil,tty,types)parser: jsonschema version correctedv5 → v6; addedgithub.com/cli/go-gh/v2andgithub.com/modelcontextprotocol/go-sdk/mcp; removedgo.yaml.in/yaml/v3(not imported)workflow: fixedgoccy/go-yaml→github.com/goccy/go-yaml; addedgithub.com/cli/go-gh/v2andgithub.com/santhosh-tekuri/jsonschema/v6