From 47ba636e2e805757a828b4f1acfa0292b86f77fb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 18 Apr 2026 09:10:22 +0000 Subject: [PATCH] docs: update architecture diagram - 2026-04-18 Full rebuild from scratch - analyzed all 24 packages across cmd/ and pkg/, mapping real internal import relationships. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scratchpad/architecture.md | 147 +++++++++++++++++++------------------ 1 file changed, 76 insertions(+), 71 deletions(-) diff --git a/scratchpad/architecture.md b/scratchpad/architecture.md index 772453f8c28..6e960217801 100644 --- a/scratchpad/architecture.md +++ b/scratchpad/architecture.md @@ -1,88 +1,93 @@ # Architecture Diagram -> Last updated: 2026-04-17 · Source: [Issue #26033](https://github.com/github/gh-aw/issues/26033) +> Last updated: 2026-04-18 · Source: [Run §24601274706](https://github.com/github/gh-aw/actions/runs/24601274706) ## Overview This diagram shows the package structure and dependencies of the `gh-aw` codebase. ``` -┌──────────────────────────────────────────────────────────────────────────────────────────────┐ -│ ENTRY POINTS │ -│ ┌───────────────────────────────────────────┐ ┌──────────────────────────────────────┐ │ -│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ -│ │ Main CLI binary │ │ WebAssembly target │ │ -│ └──────────────────────┬────────────────────┘ └──────────────┬───────┬──────────────┘ │ -│ │ │ │ │ -│ ┌───────────────────────┘ internal/tools ──▶ pkg/cli │ │ │ -│ │ (actions-build, generate-action-metadata) │ │ │ -├──┼────────────────────────────────────────────────────────────────┼───────┼───────────────────┤ -│ CORE ▼ │ │ │ -│ ┌────────────────────────────────────────────────────────────┐ │ │ │ -│ │ pkg/cli │ │ │ │ -│ │ Commands: compile, run, audit, mcp, logs, fix, add... │ │ │ │ -│ └────────────────────────────────────────┬────────────────────┘ │ │ │ -│ │ │ │ │ -│ ▼ ▼ │ │ -│ ┌──────────────────────┐ ┌──────────────────────────────────────────┐ │ │ -│ │ pkg/agentdrain │ │ pkg/workflow │ │ │ -│ │ Log drain, cluster │ │ Workflow compilation engine & │ │ │ -│ │ & anomaly detection │ │ GitHub Actions YAML generation │ │ │ -│ └──────────────────────┘ └────────────────────┬──────────┬─────────┘ │ │ -│ │ │ │ │ -│ ▼ │ ▼ │ -│ ┌───────────────────────────────────────────┐ │ ┌───────────────────────────────────────┐ │ -│ │ pkg/parser │◀──┘ │ pkg/actionpins │ │ -│ │ Markdown frontmatter parsing & │ │ GitHub Actions pin resolution │ │ -│ │ YAML schema validation │ │ (SHA pinning from version refs) │ │ -│ └───────────────────────────────────────────┘ └───────────────────────────────────────┘ │ -│ ┌────────────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ pkg/console │ │ -│ │ Terminal UI: rendering, progress bars, spinner, prompts & output formatting │ │ -│ │ ← consumed by: cli · workflow · parser · actionpins │ │ -│ └───────────────────────────────────────────────────────────────────────────┬────────────┘ │ -│ │ │ -├────────────────────────────────────────────────────────────────────────────────┼───────────────┤ -│ UTILITIES ▼ │ -│ ┌────────┐ ┌──────┐ ┌─────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ │ -│ │ logger │ │styles│ │ tty │ │ types │ │constants │ │ stringutil │ │ sliceutil│ │ -│ └────────┘ └──────┘ └─────┘ └──────────┘ └──────────┘ └────────────┘ └──────────┘ │ -│ ┌─────────┐ ┌──────────┐ ┌────────┐ ┌─────────┐ ┌──────────┐ ┌──────┐ ┌────────┐ │ -│ │typeutil │ │ fileutil │ │gitutil │ │repoutil │ │semverutil│ │stats │ │envutil │ │ -│ └─────────┘ └──────────┘ └────────┘ └─────────┘ └──────────┘ └──────┘ └────────┘ │ -│ ┌──────────┐ ┌─────────┐ │ -│ │ timeutil │ │testutil │ │ -│ └──────────┘ └─────────┘ │ -└──────────────────────────────────────────────────────────────────────────────────────────────┘ +┌────────────────────────────────────────────────────────────────────────────────────────────┐ +│ ENTRY POINTS │ +│ │ +│ ┌──────────────────────────────────────────┐ ┌────────────────────────────────────┐ │ +│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ +│ │ Main CLI binary │ │ WebAssembly target │ │ +│ │ imports: cli,console,constants, │ │ imports: parser, workflow │ │ +│ │ parser, workflow │ │ │ │ +│ └────────────┬─────────────────────────────┘ └──────────────┬─────────────────────┘ │ +│ │ │ │ +├─────────────────┼─────────────────────────────────────────────────┼─────────────────────────┤ +│ │ CORE PACKAGES │ │ +│ ▼ ▼ │ +│ ┌──────────────────────────────────┐ ┌────────────────────────────────────────────┐ │ +│ │ pkg/cli │ │ pkg/workflow │ │ +│ │ Command dispatch, flag handling,│────▶│ Workflow compilation and GitHub Actions │ │ +│ │ and CLI command execution │ │ YAML generation │ │ +│ └───┬───────────────────────────┬──┘ └───────────────────┬────────────────┬───────┘ │ +│ │ │ │ │ │ +│ │ │ ▼ ▼ │ +│ │ │ ┌─────────────────┐ ┌──────────────────┐ │ +│ │ │ │ pkg/parser │ │ pkg/actionpins │ │ +│ │ │ │ Markdown/YAML │ │ GitHub Actions │ │ +│ │ │ │ frontmatter & │ │ pin version │ │ +│ │ │ │ schema parsing │ │ resolution │ │ +│ │ │ └────────┬────────┘ └──────────┬───────┘ │ +│ │ ┌──────────────────────┼──────────────────────┘ │ │ +│ │ │ │ │ │ +│ │ ▼ ▼ ▼ │ +│ │ ┌──────────────────────────────────────────────────────────────────────────┐ │ +│ ├─▶│ pkg/console │ │ +│ │ │ Terminal UI: spinners, message formatting, styled output rendering │ │ +│ │ └──────────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ ┌──────────────────────────────────────────┐ │ +│ ├─▶│ pkg/agentdrain │ │ +│ │ │ Agent log streaming and drain for CI │ │ +│ │ └──────────────────────────────────────────┘ │ +│ │ ┌──────────────────────────────────────────┐ │ +│ └─▶│ pkg/stats │ │ +│ │ Numerical statistics and metrics │ │ +│ └──────────────────────────────────────────┘ │ +├────────────────────────────────────────────────────────────────────────────────────────────┤ +│ UTILITY PACKAGES │ +│ ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌──────┐ │ +│ │constants │ │ types │ │ logger │ │ fileutil │ │ gitutil │ │ repoutil │ │envutil│ │ +│ └──────────┘ └────────┘ └────────┘ └──────────┘ └─────────┘ └──────────┘ └──────┘ │ +│ ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌───────┐ ┌────────┐ │ +│ │ stringutil │ │ sliceutil│ │ typeutil │ │ semverutil │ │ tty │ │ styles │ │ +│ └────────────┘ └──────────┘ └──────────┘ └────────────┘ └───────┘ └────────┘ │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ timeutil │ │ testutil │ (consumed by all core packages above) │ +│ └──────────┘ └──────────┘ │ +└────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ## Package Reference | Package | Layer | Description | |---------|-------|-------------| -| cmd/gh-aw | Entry | Main CLI binary (GitHub CLI extension entry point) | -| cmd/gh-aw-wasm | Entry | WebAssembly compilation target | -| internal/tools/actions-build | Internal | Build and validate custom GitHub Actions | -| internal/tools/generate-action-metadata | Internal | Generate action.yml and README.md for JS modules | -| pkg/cli | Core | Command implementations: compile, run, audit, mcp, logs, fix, add, update | -| pkg/workflow | Core | Workflow compilation engine (Markdown → GitHub Actions YAML) | -| pkg/parser | Core | Markdown frontmatter parsing & YAML schema validation | -| pkg/console | Core | Terminal UI: rendering, progress bars, spinner, prompts & output formatting | -| pkg/agentdrain | Core | Log drain, clustering & anomaly detection (DRAIN3 algorithm) | -| pkg/actionpins | Core | GitHub Actions pin resolution — maps version refs to pinned SHAs | +| cmd/gh-aw | Entry | Main CLI binary — imports cli, console, constants, parser, workflow | +| cmd/gh-aw-wasm | Entry | WebAssembly compilation target — imports parser, workflow | +| pkg/cli | Core | Command dispatch, flag handling, and CLI command execution | +| pkg/workflow | Core | Workflow compilation and GitHub Actions YAML generation | +| pkg/parser | Core | Markdown/YAML/frontmatter parsing and schema validation | +| pkg/console | Core | Terminal UI: spinners, message formatting, styled output rendering | +| pkg/agentdrain | Core | Agent log streaming and drain for CI workflows | +| pkg/actionpins | Core | GitHub Actions pin version resolution | +| pkg/stats | Core | Numerical statistics and metrics collection | +| pkg/constants | Utility | Shared constants and semantic type aliases | +| pkg/types | Utility | Shared type definitions used across packages | | pkg/logger | Utility | Namespace-based debug logging with zero overhead when disabled | -| pkg/styles | Utility | Centralized terminal color and style definitions | -| pkg/tty | Utility | TTY (terminal) detection utilities | -| pkg/types | Utility | Shared type definitions across packages | -| pkg/constants | Utility | Shared constants: engine names, job names, feature flags, URLs | -| pkg/stringutil | Utility | String manipulation utilities | -| pkg/sliceutil | Utility | Generic slice utility functions | -| pkg/typeutil | Utility | Safe type conversion utilities for any/JSON/YAML values | | pkg/fileutil | Utility | File path and file operation utilities | -| pkg/gitutil | Utility | Git repository utilities | +| pkg/gitutil | Utility | Git repository utility functions | | pkg/repoutil | Utility | GitHub repository slug and URL utilities | -| pkg/semverutil | Utility | Semantic versioning primitives | -| pkg/stats | Utility | Numerical statistics utilities for metric collection | -| pkg/envutil | Utility | Environment variable reading and validation | -| pkg/timeutil | Utility | Time formatting utilities | -| pkg/testutil | Utility | Test support utilities (test-only) | +| pkg/envutil | Utility | Environment variable reading and validation utilities | +| pkg/stringutil | Utility | String manipulation utilities including ANSI stripping | +| pkg/sliceutil | Utility | Generic slice operation utilities | +| pkg/typeutil | Utility | General-purpose type conversion utilities | +| pkg/semverutil | Utility | Shared semantic versioning primitives | +| pkg/tty | Utility | TTY (terminal) detection utilities | +| pkg/styles | Utility | Terminal style definitions (no-op for WASM builds) | +| pkg/timeutil | Utility | Time formatting and duration utilities | +| pkg/testutil | Utility | Shared test helper utilities |