Repository Tree Map - October 11, 2025

[github-actions[bot]]

📊 Repository Tree Map Visualization

A comprehensive analysis of the gh-aw repository structure, file distribution, and organization.

---

📈 Repository Statistics

Metric	Value
Total Files	674 files
Total Directories	50 directories
Go Source Files	121 files
Go Test Files	225 files
Test Coverage	65% (225 tests vs 121 source files)
Markdown Files	184 files
JavaScript Files	53 files (.js, .cjs, .mjs)
YAML Files	38 files (.yml, .yaml)
JSON Files	21 files

---

🌳 ASCII Tree Map

gh-aw/ [674 files, 50 dirs]
│
├─ 📦 pkg/ [499 files] ██████████████████████████████████████████░░ (74.0%)
│  │
│  ├─ 🔧 workflow/ [314 files] ███████████████████████████░░ (46.6%)
│  │  ├─ js/ [62 files] ██████░░ (9.2%)
│  │  │  ├─ parse_copilot_log.cjs
│  │  │  ├─ validate_errors.cjs
│  │  │  ├─ create_safe_outputs_helper.cjs
│  │  │  └─ ... (JavaScript action handlers)
│  │  │
│  │  ├─ templates/ (YAML workflow templates)
│  │  ├─ config/ (Engine configurations)
│  │  ├─ data/ (Test data and fixtures)
│  │  ├─ schemas/ (JSON schema definitions)
│  │  └─ *.go [252 files] - Workflow compilation engine
│  │     ├─ Engine implementations (Claude, Copilot, Codex, Custom)
│  │     ├─ MCP server configuration
│  │     ├─ Safe outputs processing
│  │     ├─ Expression parsing & safety
│  │     ├─ Network controls & security
│  │     └─ Git operations & patches
│  │
│  ├─ 🎯 cli/ [155 files] ████████████████░░ (23.0%)
│  │  ├─ commands.go - Main CLI command structure
│  │  ├─ compile_command.go - Workflow compilation
│  │  ├─ logs.go - Log analysis and metrics
│  │  ├─ mcp*.go - MCP server management [12 files]
│  │  ├─ audit.go - Workflow run auditing
│  │  ├─ workflows/ - Built-in agentic workflows
│  │  └─ *_test.go [~70 files] - CLI tests
│  │
│  ├─ 📝 parser/ [24 files] ███░░ (3.6%)
│  │  ├─ frontmatter.go - YAML frontmatter parsing
│  │  ├─ validation.go - Schema validation
│  │  └─ schemas/ - JSON schema files
│  │
│  └─ 🎨 console/ [5 files] █░░ (0.7%)
│     └─ formatting.go - CLI output styling
│
├─ 🔀 .github/ [92 files] ████████████░░ (13.7%)
│  ├─ workflows/ [82 files] ███████████░░ (12.2%)
│  │  ├─ *.md - Agentic workflow definitions [~41 files]
│  │  └─ *.lock.yml - Compiled GitHub Actions [~41 files]
│  │
│  ├─ instructions/ - Development guidelines
│  │  ├─ github-agentic-workflows.instructions.md
│  │  ├─ github-script.instructions.md
│  │  ├─ documentation.instructions.md
│  │  ├─ copilot-cli.instructions.md
│  │  └─ error-pattern-safety.instructions.md
│  │
│  └─ prompts/ - AI prompt templates
│
├─ 📚 docs/ [~40 files] ████░░ (5.9%)
│  ├─ src/content/ [33 files] - Astro Starlight docs
│  │  ├─ docs/ - Main documentation (Diátaxis framework)
│  │  │  ├─ tutorials/
│  │  │  ├─ how-to/
│  │  │  ├─ reference/
│  │  │  └─ explanation/
│  │  └─ i18n/ - Internationalization
│  │
│  ├─ astro.config.mjs - Astro configuration
│  ├─ package.json - npm dependencies
│  └─ DIATAXIS_AUDIT.md - Documentation audit
│
├─ 🚀 cmd/ [~3 files] █░░ (0.4%)
│  └─ gh-aw/ - Main CLI entry point
│     └─ main.go
│
├─ 📋 schemas/ [~3 files] █░░ (0.4%)
│  └─ JSON schema definitions
│
├─ 🛠️  scripts/ [~3 files] █░░ (0.4%)
│  └─ Build and release scripts
│
└─ 📄 Root Files [~14 files] ██░░ (2.1%)
   ├─ 📖 Documentation
   │  ├─ README.md
   │  ├─ AGENTS.md - AI agent instructions
   │  ├─ DEVGUIDE.md
   │  ├─ CONTRIBUTING.md
   │  ├─ TESTING.md
   │  ├─ CHANGELOG.md
   │  ├─ CODE_OF_CONDUCT.md
   │  ├─ SECURITY.md
   │  └─ SUPPORT.md
   │
   ├─ ⚙️ Configuration
   │  ├─ go.mod, go.sum - Go dependencies
   │  ├─ Makefile - Build automation
   │  ├─ .golangci.yml - Go linter config
   │  ├─ .prettierrc.json - Code formatting
   │  └─ .nvmrc - Node version
   │
   └─ 🔐 Meta
      ├─ LICENSE
      ├─ CODEOWNERS
      └─ install-gh-aw.sh

---

📊 File Distribution by Type

Go Source Code       ██████████████████░░░░░░░░░░░░░░░░░░░░ 346 files (51.3%)
├─ Test Files        ████████████████████░░░░░░░░░░░░░░░░ 225 files (33.4%)
└─ Source Files      ███████████░░░░░░░░░░░░░░░░░░░░░░░░░ 121 files (17.9%)

Documentation        █████████████░░░░░░░░░░░░░░░░░░░░░░░ 184 files (27.3%)
├─ .md files         (includes docs/, .github/, root/)

JavaScript           ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  53 files (7.9%)
├─ GitHub Actions    (pkg/workflow/js/*.cjs)

YAML                 ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  38 files (5.6%)
├─ Workflows         (.github/workflows/*.yml)

JSON                 ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  21 files (3.1%)
├─ Configs & Schemas

---

🔍 Key Directories Deep Dive

pkg/workflow/ - The Workflow Engine Core

The largest and most critical component with 314 files containing:

• Engine Implementations: Claude, Copilot, Codex, Custom engines
• MCP Server Management: Configuration, validation, integration
• Safe Outputs: Secure GitHub API interactions (issues, PRs, comments)
• Security Features: Expression safety, XPIA detection, network controls
• Compilation: Markdown → GitHub Actions YAML transformation
• Git Operations: Patch generation, branch management, PR creation
• Testing: ~180 test files covering all workflow scenarios

Subdirectory Breakdown:

• js/ [62 files] - GitHub Actions JavaScript runtime
• Core Go files [252 files] - Engine logic and compilation

pkg/cli/ - Command-Line Interface

Second largest with 155 files providing:

• Commands: compile, logs, audit, mcp, init, add, remove
• MCP Operations: inspect, list, list-tools, add, registry
• Log Analysis: Download, parse, analyze workflow execution
• Workflow Management: File tracking, compilation, validation
• Built-in Workflows: Pre-configured agentic workflows

.github/workflows/ - Agentic Workflow Examples

Contains 82 files (41 pairs of .md + .lock.yml):

• Workflow definitions in Markdown format with YAML frontmatter
• Compiled GitHub Actions in .lock.yml files
• Examples covering various triggers and use cases
• Production workflows for the project itself

docs/ - Documentation Site

Astro Starlight-based documentation following Diátaxis framework:

• Tutorials: Learning-oriented guides
• How-to Guides: Task-oriented instructions
• Reference: Technical specifications
• Explanation: Conceptual understanding

---

🎯 Architecture Highlights

Layered Architecture:

┌─────────────────────────────────────────┐
│  CLI Layer (pkg/cli)                    │
│  ├─ User commands                       │
│  └─ Workflow management                 │
├─────────────────────────────────────────┤
│  Compilation Layer (pkg/workflow)       │
│  ├─ Markdown → YAML transformation      │
│  ├─ Expression parsing & validation     │
│  └─ Template rendering                  │
├─────────────────────────────────────────┤
│  Engine Layer (pkg/workflow)            │
│  ├─ AI engine integrations              │
│  ├─ MCP server orchestration            │
│  └─ Safe output processing              │
├─────────────────────────────────────────┤
│  Parser Layer (pkg/parser)              │
│  ├─ YAML frontmatter parsing            │
│  └─ JSON schema validation              │
├─────────────────────────────────────────┤
│  Runtime Layer (pkg/workflow/js)        │
│  ├─ GitHub Actions JavaScript           │
│  ├─ Log parsing & analysis              │
│  └─ Safe output execution               │
└─────────────────────────────────────────┘

---

🧪 Test Coverage Analysis

Test Distribution:

• Total test files: 225 (65% ratio to source files)
• Test types:
  • Unit tests (*_test.go)
  • Integration tests (*_integration_test.go)
  • Simple tests (*_simple_test.go)
  • Compilation tests (*compilation_test.go)

High Test Density Areas:

• pkg/workflow/: ~180 test files (comprehensive engine testing)
• pkg/cli/: ~70 test files (CLI command validation)
• Engine-specific: Each engine has dedicated test suites

---

🔒 Security & Safety Features

The codebase demonstrates strong security consciousness:

Expression Safety (expression_safety.go, expression_safety_test.go)

• Validates GitHub Actions expressions
• Prevents unauthorized context access
• Only allows approved expression patterns

XPIA Protection (xpia.go, xpia_test.go)

• Cross-Prompt Injection Attack detection
• Content sanitization for user inputs
• Threat detection and isolation

Network Controls (network.go, network_proxy.go, engine_network_hooks.go)

• Domain allowlists/denylists
• Ecosystem-based permissions
• Proxy-based enforcement

Safe Outputs (safe_outputs*.go [13 files])

• Secure GitHub API interactions
• Permission separation
• Output validation and sanitization

---

🏆 Notable Patterns

Comprehensive Testing Strategy:

• 1.86:1 test-to-source ratio
• Multiple test types for different scenarios
• Integration tests for real-world validation

Modular JavaScript Runtime:

• 62 JavaScript files in pkg/workflow/js/
• GitHub Actions integration
• Separated concerns (parsing, validation, execution)

Rich Documentation:

• 184 markdown files
• Structured documentation in docs/
• Agent instructions in .github/instructions/
• Inline guides (AGENTS.md, DEVGUIDE.md, etc.)

Security-First Design:

• Multiple layers of validation
• Expression safety checks
• Network isolation options
• Threat detection systems

---

📦 Technology Stack

Technology	Purpose	Files
Go	Core engine, CLI, compilation	346
JavaScript	GitHub Actions runtime	53
Markdown	Documentation, workflows	184
YAML	Configuration, workflows	38
JSON	Schemas, configs	21
Astro	Documentation site	~15
TypeScript	Documentation types	~5

---

🎨 Visual Summary

Repository Composition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

pkg/workflow    ████████████████████████████████ 314 files (46.6%)
pkg/cli         ████████████████                 155 files (23.0%)
.github         ████████████                      92 files (13.7%)
docs            ████                              40 files (5.9%)
pkg/parser      ███                               24 files (3.6%)
Other           ███████                           49 files (7.3%)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: 674 files across 50 directories

---

💡 Key Insights

1. Test-Driven Development: With 225 test files vs 121 source files, the project demonstrates strong testing discipline

2. Workflow Engine Dominance: 46.6% of all files are in the workflow package, showing this is the heart of the system

3. Well-Documented: 27.3% of files are documentation, indicating commitment to developer experience

4. Security-Conscious: Multiple dedicated modules for security (XPIA, expression safety, network controls, safe outputs)

5. Modular Architecture: Clear separation between CLI, compilation, parsing, and runtime layers

6. Living Documentation: Both traditional docs and agentic workflow examples serve as documentation

---

Generated on October 11, 2025
Repository: githubnext/gh-aw
Total Files Analyzed: 674

AI generated by Repository Tree Map Generator

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 month ago.