From 3fbb608f9f7a6c5896d3fad6b8b013882f64f5fe Mon Sep 17 00:00:00 2001 From: Ismo Vuorinen Date: Thu, 7 Aug 2025 05:22:44 +0300 Subject: [PATCH] feat: update go version, renovate config, tooling, fixes (#28) * feat(deps): update go version, renovate config, tooling * chore(deps): update google/go-github to v74 * feat(deps): migrate from yaml.v3 to goccy/go-yaml * chore(deps): update goccy/go-yaml to v1.18.0 and address security concerns * feat: improve issue templates and project configuration - Update GitHub issue templates with CLI-specific fields for better bug reports - Add specialized templates for documentation, theme, and performance issues - Update pre-commit config to include comprehensive documentation linting - Remove outdated Snyk configuration and security references - Update Go version from 1.23+ to 1.24+ across project - Streamline README.md organization and improve clarity - Update CHANGELOG.md and CLAUDE.md formatting - Create comprehensive CONTRIBUTING.md with development guidelines - Remove TODO.md (replaced by docs/roadmap.md) - Move SECURITY.md to docs/security.md * docs: fix markdown linting violations across documentation * fix: resolve template placeholder issues and improve uses statement generation * fix: remove trailing whitespace from GitHub issue template --- .github/ISSUE_TEMPLATE/bug_report.md | 72 +- .github/ISSUE_TEMPLATE/documentation_issue.md | 63 ++ .github/ISSUE_TEMPLATE/feature_request.md | 60 +- .github/ISSUE_TEMPLATE/performance_issue.md | 128 +++ .github/ISSUE_TEMPLATE/theme_request.md | 113 +++ .github/renovate.json | 55 +- .go-version | 1 + .golangci.yml | 2 +- .pre-commit-config.yaml | 2 +- .snyk | 7 - CHANGELOG.md | 6 + CLAUDE.md | 40 + CONTRIBUTING.md | 291 +++++++ Makefile | 45 +- README.md | 209 +---- TODO.md | 763 ------------------ docs/README.md | 30 + docs/api.md | 507 ++++++++++++ docs/configuration.md | 330 ++++++++ docs/development.md | 447 ++++++++++ docs/installation.md | 149 ++++ docs/roadmap.md | 156 ++++ SECURITY.md => docs/security.md | 12 +- docs/themes.md | 397 +++++++++ docs/usage.md | 247 ++++++ go.mod | 34 +- go.sum | 71 +- internal/config.go | 2 +- internal/dependencies/analyzer.go | 2 +- internal/dependencies/analyzer_test.go | 2 +- internal/dependencies/parser.go | 2 +- internal/generator.go | 2 +- internal/parser.go | 2 +- internal/template.go | 21 +- internal/wizard/detector.go | 2 +- internal/wizard/exporter.go | 5 +- internal/wizard/exporter_test.go | 2 +- templates/themes/asciidoc/readme.adoc | 10 +- templates/themes/gitlab/readme.tmpl | 2 +- templates/themes/minimal/readme.tmpl | 2 +- templates/themes/professional/readme.tmpl | 10 +- .../templates/themes/asciidoc/readme.adoc | 10 +- .../templates/themes/gitlab/readme.tmpl | 2 +- .../templates/themes/minimal/readme.tmpl | 2 +- .../templates/themes/professional/readme.tmpl | 10 +- testutil/fixtures.go | 2 +- testutil/fixtures_test.go | 2 +- testutil/test_suites.go | 2 +- testutil/testutil.go | 2 +- 49 files changed, 3235 insertions(+), 1100 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/documentation_issue.md create mode 100644 .github/ISSUE_TEMPLATE/performance_issue.md create mode 100644 .github/ISSUE_TEMPLATE/theme_request.md create mode 100644 .go-version delete mode 100644 .snyk create mode 100644 CONTRIBUTING.md delete mode 100644 TODO.md create mode 100644 docs/README.md create mode 100644 docs/api.md create mode 100644 docs/configuration.md create mode 100644 docs/development.md create mode 100644 docs/installation.md create mode 100644 docs/roadmap.md rename SECURITY.md => docs/security.md (95%) create mode 100644 docs/themes.md create mode 100644 docs/usage.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 1922341..cdec02c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,7 +1,7 @@ --- name: Bug report -about: Create a report to help us improve -title: '' +about: Report a bug with gh-action-readme CLI tool +title: '[BUG] ' labels: bug assignees: ivuorinen @@ -10,29 +10,59 @@ assignees: ivuorinen **Describe the bug** A clear and concise description of what the bug is. -**To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error +**Command executed** +The exact gh-action-readme command that caused the issue: + +```bash +gh-action-readme [your command here] +``` **Expected behavior** -A clear and concise description of what you expected to happen. +Describe what you expected to happen. -**Screenshots** -If applicable, add screenshots to help explain your problem. +**Actual behavior** +Describe what actually happened instead. -**Desktop (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] +**Sample action.yml** +Provide the action.yml content that causes the issue (anonymize sensitive data): -**Smartphone (please complete the following information):** - - Device: [e.g. iPhone6] - - OS: [e.g. iOS8.1] - - Browser [e.g. stock browser, safari] - - Version [e.g. 22] +```yaml +# Paste your action.yml content here +``` + +**Generated output (if applicable)** +If documentation was generated, paste the problematic output: + +```markdown +# Paste generated documentation excerpt here +``` + +## Environment information + +- OS: [e.g. macOS 14.1, Ubuntu 22.04, Windows 11] +- gh-action-readme version: [run `gh-action-readme version`] +- Go version: [run `go version`] +- Installation method: [binary, homebrew, go install, docker] +- Theme used: [github, gitlab, minimal, professional, default] +- Output format: [md, html, json, asciidoc] + +**Repository structure (if relevant)** +If the issue is related to file discovery or recursive processing: + +```text +my-repo/ +├── action.yml +├── .github/ +│ └── workflows/ +└── other files... +``` + +**Error messages** +Paste any error messages or logs: + +```text +[paste error output here] +``` **Additional context** -Add any other context about the problem here. +Add any other context about the problem here (configuration files, special setup, etc.). diff --git a/.github/ISSUE_TEMPLATE/documentation_issue.md b/.github/ISSUE_TEMPLATE/documentation_issue.md new file mode 100644 index 0000000..77b3c0e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation_issue.md @@ -0,0 +1,63 @@ +--- +name: Documentation quality issue +about: Report problems with generated documentation output +title: '[DOCS] ' +labels: documentation, quality +assignees: ivuorinen + +--- + +**Describe the documentation issue** +A clear description of what's wrong with the generated documentation. + +## Theme and format used + +- Theme: [github, gitlab, minimal, professional, default] +- Output format: [md, html, json, asciidoc] +- Command used: `gh-action-readme gen [your flags here]` + +**Sample action.yml** +The action.yml input that produces the problematic documentation: + +```yaml +# Paste your action.yml content here +``` + +**Current generated output** +The problematic documentation that was generated: + +```markdown +# Paste the current output here (or relevant excerpt) +``` + +**Expected documentation** +What the documentation should look like instead: + +```markdown +# Paste what you expected here +``` + +**Issue category** +What type of documentation problem is this? + +- [ ] Missing information (inputs, outputs, etc.) +- [ ] Incorrect formatting/rendering +- [ ] Broken links or references +- [ ] Poor table layout +- [ ] Badge/shield issues +- [ ] Code block formatting +- [ ] Template logic error +- [ ] Theme-specific styling problem +- [ ] Other: ___________ + +## Environment information + +- OS: [e.g. macOS 14.1, Ubuntu 22.04, Windows 11] +- gh-action-readme version: [run `gh-action-readme version`] + +**Additional context** +Add any other context about the documentation quality issue. Include: + +- Screenshots if it's a visual formatting problem +- Links to similar actions with good documentation +- Specific markdown/HTML sections that are problematic diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index abdc2e8..629b294 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,20 +1,66 @@ --- name: Feature request -about: Suggest an idea for this project -title: '' +about: Suggest an enhancement for gh-action-readme +title: '[FEATURE] ' labels: enhancement assignees: ivuorinen --- +**Feature category** +What type of enhancement is this? + +- [ ] New theme +- [ ] New output format +- [ ] CLI command enhancement +- [ ] Validation improvement +- [ ] Configuration option +- [ ] Template customization +- [ ] Performance optimization +- [ ] Integration (CI/CD, tools) +- [ ] Other: ___________ + **Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] +Describe the current limitation or friction in your GitHub Actions documentation workflow. **Describe the solution you'd like** -A clear and concise description of what you want to happen. +A clear description of the desired functionality. Include: -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. +- Proposed CLI syntax (if applicable) +- Expected behavior +- Sample input/output + +**Use case and impact** +Describe your specific GitHub Actions documentation scenario: + +- What types of actions would benefit? +- How many action.yml files does this affect? +- What workflow improvement would this provide? + +**Proposed implementation** +If you have ideas about implementation: + +- New CLI flags: `--flag-name` +- Configuration options +- Template modifications +- Integration points + +**Sample action.yml** +Provide a sample action.yml that would showcase this feature: + +```yaml +# Example action.yml that would benefit from this feature +``` + +**Expected output** +Show what the generated documentation should look like: + +```markdown +# Expected documentation output +``` + +**Alternatives considered** +Describe alternative solutions or workarounds you've considered. **Additional context** -Add any other context or screenshots about the feature request here. +Add any other context, mockups, or examples about the feature request. diff --git a/.github/ISSUE_TEMPLATE/performance_issue.md b/.github/ISSUE_TEMPLATE/performance_issue.md new file mode 100644 index 0000000..f7198dd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/performance_issue.md @@ -0,0 +1,128 @@ +--- +name: Performance issue +about: Report CLI performance problems or slow operations +title: '[PERF] ' +labels: performance, bug +assignees: ivuorinen + +--- + +**Performance problem** +Describe what operation is slower than expected. + +**Operation details** +Which gh-action-readme operation is slow? + +- [ ] `gen` - Single file generation +- [ ] `gen --recursive` - Batch processing +- [ ] `validate` - Action validation +- [ ] `deps` - Dependency analysis +- [ ] `config` - Configuration operations +- [ ] Startup time +- [ ] Other: ___________ + +**Command executed** +The exact command that exhibits performance issues: + +```bash +gh-action-readme [your slow command here] +``` + +**Performance metrics** +Provide timing and resource usage information: + +**Processing time:** + +- Current time: ___ seconds/minutes +- Expected time: ___ seconds/minutes +- Acceptable time: ___ seconds/minutes + +**Dataset size:** + +- Number of action.yml files: ___ +- Total size of files: ___ KB/MB +- Repository structure depth: ___ levels +- Largest action.yml size: ___ KB + +**Resource usage observed:** + +- Peak memory usage: ___ MB +- CPU usage: ___% sustained +- Disk I/O patterns: [heavy reads, heavy writes, mixed] +- Network requests: ___ (for dependency analysis) + +## Environment information + +- OS: [e.g. macOS 14.1, Ubuntu 22.04, Windows 11] +- Hardware: [e.g. MacBook Air M2, Intel i7, AWS EC2 t3.large] +- gh-action-readme version: [run `gh-action-readme version`] +- Go version: [run `go version`] +- Installation method: [binary, homebrew, go install, docker] + +**Batch processing details (if applicable)** +For recursive or batch operations: + +**Repository structure:** + +```text +my-repo/ +├── .github/workflows/ (__ files) +├── actions/ +│ ├── action1/ (action.yml) +│ ├── action2/ (action.yml) +│ └── ... (__ more actions) +└── other directories... +``` + +**Processing pattern:** + +- [ ] Single large repository +- [ ] Multiple small repositories +- [ ] Mixed sizes +- [ ] Deep directory nesting +- [ ] Many small action.yml files +- [ ] Few large action.yml files + +**Configuration impact** +Settings that might affect performance: + +**Flags used:** + +- Theme: [github, gitlab, minimal, professional, default] +- Output format: [md, html, json, asciidoc] +- Verbose mode: [yes, no] +- Dependency analysis: [enabled, disabled] + +**Configuration file settings:** + +```yaml +# Paste relevant config that might impact performance +``` + +## Expected vs actual behavior + +- **Expected**: Should process files in specified seconds +- **Actual**: Takes ___ seconds/minutes to complete +- **Comparison**: Other similar tools take ___ seconds + +**Profiling data (if available)** +If you've run any profiling: + +```text +# Paste CPU/memory profiling output +# Or performance monitoring results +``` + +**Workarounds** +Any workarounds you've found: + +- Breaking into smaller batches +- Specific flag combinations +- Environment modifications + +## Additional context + +- Network conditions (for dependency analysis) +- Disk type (SSD, HDD, network storage) +- Concurrent operations running +- Time of day patterns (if applicable) diff --git a/.github/ISSUE_TEMPLATE/theme_request.md b/.github/ISSUE_TEMPLATE/theme_request.md new file mode 100644 index 0000000..e409153 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/theme_request.md @@ -0,0 +1,113 @@ +--- +name: Theme request +about: Request a new theme or theme improvements +title: '[THEME] ' +labels: enhancement, theme +assignees: ivuorinen + +--- + +**Theme request type** +What kind of theme enhancement is this? + +- [ ] New theme for a specific platform/use case +- [ ] Improvements to existing theme +- [ ] Theme bug fix +- [ ] Theme customization options + +**Target platform/use case** +What platform or scenario is this theme designed for? + +- [ ] GitHub Marketplace optimization +- [ ] GitLab CI/CD documentation +- [ ] Azure DevOps integration +- [ ] Internal/Enterprise documentation +- [ ] Minimal/lightweight documentation +- [ ] Mobile-friendly documentation +- [ ] Other: ___________ + +**Visual requirements** +Describe the desired appearance and formatting: + +**Badges and shields:** + +- [ ] Platform-specific badges +- [ ] Version/release shields +- [ ] Build status badges +- [ ] License/security badges +- [ ] Custom badge styling + +**Layout preferences:** + +- [ ] Table of contents +- [ ] Collapsible sections +- [ ] Multi-column layout +- [ ] Sidebar navigation +- [ ] Card-based layout +- [ ] Minimal typography + +**Color scheme:** + +- [ ] Dark theme +- [ ] Light theme +- [ ] Platform-specific colors (GitHub green, GitLab orange, etc.) +- [ ] Corporate/brand colors +- [ ] High contrast for accessibility + +**Sample action.yml files** +Provide example action.yml files to test the theme with: + +```yaml +# Example 1: Simple action +name: Simple Action +description: A basic action example +inputs: + input1: + description: First input + required: true +outputs: + output1: + description: First output +runs: + using: node20 + main: index.js +``` + +```yaml +# Example 2: Complex action (if applicable) +# Add more complex action.yml if theme needs to handle advanced cases +``` + +**Reference examples** +Provide links or descriptions of documentation that exemplifies the desired style: + +- [ ] Link to well-styled action documentation +- [ ] Screenshots of desired layout +- [ ] Reference to design system or style guide +- [ ] Examples from other tools/platforms + +**Expected output preview** +Mock up what the generated documentation should look like: + +```markdown +# Show expected theme output here +# Include formatting, badges, layout structure +``` + +**Existing theme starting point** +Which existing theme should this be based on? + +- [ ] Start from scratch +- [ ] Extend `github` theme +- [ ] Extend `gitlab` theme +- [ ] Extend `minimal` theme +- [ ] Extend `professional` theme +- [ ] Extend `default` theme + +**Additional context** +Add any other context about the theme request: + +- Specific markdown features needed +- Integration requirements +- Performance considerations +- Accessibility requirements diff --git a/.github/renovate.json b/.github/renovate.json index f02f654..4a1139f 100644 --- a/.github/renovate.json +++ b/.github/renovate.json @@ -1,6 +1,57 @@ { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": [ - "github>ivuorinen/renovate-config" - ] + "github>ivuorinen/renovate-config", + "config:recommended" + ], + "labels": [ + "dependencies" + ], + "assigneesFromCodeOwners": true, + "reviewersFromCodeOwners": true, + "semanticCommits": "enabled", + "semanticCommitType": "chore", + "semanticCommitScope": "deps", + "postUpdateOptions": [ + "gomodTidy" + ], + "golang": { + "enabled": true, + "gomodUpdateImportPaths": true + }, + "packageRules": [ + { + "matchDatasources": [ + "go" + ], + "matchUpdateTypes": [ + "major" + ], + "enabled": false + }, + { + "matchDatasources": [ + "go" + ], + "matchUpdateTypes": [ + "minor", + "patch" + ], + "automerge": true, + "automergeType": "pr", + "requiredStatusChecks": null + }, + { + "matchPackagePatterns": [ + "^golang.org/x/" + ], + "groupName": "golang.org/x packages" + } + ], + "schedule": [ + "before 4am on monday" + ], + "timezone": "UTC", + "prConcurrentLimit": 3, + "prHourlyLimit": 2 } diff --git a/.go-version b/.go-version new file mode 100644 index 0000000..2f4320f --- /dev/null +++ b/.go-version @@ -0,0 +1 @@ +1.24.4 diff --git a/.golangci.yml b/.golangci.yml index 7a4e1f8..d006623 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -4,7 +4,7 @@ version: "2" run: timeout: 5m - go: "1.23" + go: "1.24" linters: default: standard diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 717235d..537c98b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -37,7 +37,7 @@ repos: rev: v0.18.1 hooks: - id: markdownlint-cli2 - exclude: '^(testdata/|CHANGELOG\.md|TODO\.md|\.github/|CLAUDE\.md|README\.md|SECURITY\.md)' + exclude: '^testdata/' # EditorConfig checking - repo: https://github.com/editorconfig-checker/editorconfig-checker diff --git a/.snyk b/.snyk deleted file mode 100644 index db0e33f..0000000 --- a/.snyk +++ /dev/null @@ -1,7 +0,0 @@ -# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities. -version: v1.25.1 -ignore: {} -patch: {} -exclude: - global: - - ./testdata/**/*.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 554951e..6e3ca60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added + - GoReleaser configuration for automated releases - Multi-platform binary builds (Linux, macOS, Windows) - Docker images with multi-architecture support @@ -18,10 +19,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Enhanced version command with build information ### Changed + - Updated GitHub Actions workflow for automated releases - Improved release process with GoReleaser ### Infrastructure + - Added Dockerfile for containerized deployments - Set up automated Docker image publishing to GitHub Container Registry - Added support for ARM64 and AMD64 architectures @@ -29,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [0.1.0] - Initial Release ### Added + - Core CLI framework with Cobra - Documentation generation from action.yml files - Multiple output formats (Markdown, HTML, JSON, AsciiDoc) @@ -46,6 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Zero linting violations ### Features + - **CLI Commands**: gen, validate, schema, version, about, config, deps, cache - **Configuration**: Multi-level hierarchy with hidden config files - **Dependency Management**: Outdated detection, security analysis, version pinning @@ -54,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Cache Management**: XDG-compliant caching with TTL support ### Quality + - Comprehensive code quality improvements - Extracted helper functions for code deduplication - Reduced cyclomatic complexity in all functions diff --git a/CLAUDE.md b/CLAUDE.md index a03929e..cd7ba0d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,7 @@ **NEVER overwrite `/README.md`** - The root README.md is the main project documentation. **For testing generation commands:** + ```bash # New enhanced targeting (recommended) gh-action-readme gen testdata/example-action/ @@ -20,6 +21,7 @@ cd testdata/ ## 🏗️ Architecture **Core Components:** + - `main.go` - CLI with Cobra framework, enhanced gen command - `internal/generator.go` - Core generation logic with custom output paths - `internal/config.go` - Viper configuration (XDG compliant) @@ -30,6 +32,7 @@ cd testdata/ - `internal/progress.go` - Progress indicators for batch operations **Templates:** + - `templates/readme.tmpl` - Default template - `templates/themes/` - Theme-specific templates - `github/` - GitHub-style with badges @@ -41,6 +44,7 @@ cd testdata/ ## 🛠️ Commands & Usage **Available Commands:** + ```bash gh-action-readme gen [directory_or_file] [flags] # Generate documentation gh-action-readme validate # Validate action.yml files @@ -50,6 +54,7 @@ gh-action-readme about # About tool ``` **Key Flags:** + - `--theme` - Select template theme - `--output-format` - Choose format (md, html, json, asciidoc) - `--output` - Custom output filename @@ -62,8 +67,10 @@ gh-action-readme about # About tool **Build:** `go build .` **Test:** `go test ./internal` **Lint:** `golangci-lint run` +**Dependencies:** `make deps-check` / `make deps-update` **Testing Generation (SAFE):** + ```bash # Enhanced targeting (recommended) gh-action-readme gen testdata/example-action/ --theme github --output test-output.md @@ -94,6 +101,7 @@ cd testdata/example-action/ ## 🎨 Themes **Available Themes:** + 1. **default** - Original simple template 2. **github** - Badges, tables, collapsible sections 3. **gitlab** - GitLab CI/CD examples @@ -103,6 +111,7 @@ cd testdata/example-action/ ## 📄 Output Formats **Supported Formats:** + - **md** - Markdown (default) - **html** - HTML with styling - **json** - Structured data for APIs @@ -115,6 +124,7 @@ cd testdata/example-action/ **Templates:** Test with `testdata/example-action/` **Test Commands:** + ```bash # Core functionality (enhanced) gh-action-readme gen testdata/example-action/ @@ -137,18 +147,21 @@ gh-action-readme gen testdata/ --recursive --theme professional ## 🚀 Production Features **Configuration:** + - XDG Base Directory compliant - Environment variable support - Theme persistence - Multiple search paths **Error Handling:** + - Colored error messages - Actionable suggestions - Context-aware validation - Graceful fallbacks **Performance:** + - Progress bars for batch operations - Thread-safe fixture caching with RWMutex - Binary-relative template paths @@ -160,11 +173,13 @@ gh-action-readme gen testdata/ --recursive --theme professional ## 🔄 Adding New Features **New Theme:** + 1. Create `templates/themes/THEME_NAME/readme.tmpl` 2. Add to `resolveThemeTemplate()` in `config.go:67` 3. Update `configThemesHandler()` in `main.go:284` **New Output Format:** + 1. Add constant to `generator.go:14` 2. Add case to `GenerateFromFile()` switch `generator.go:67` 3. Implement `generate[FORMAT]()` method @@ -173,15 +188,40 @@ gh-action-readme gen testdata/ --recursive --theme professional **New Template Functions:** Add to `templateFuncs()` in `internal_template.go:19` +## 📦 Dependency Management + +**Check for updates:** + +```bash +make deps-check # Show outdated dependencies +``` + +**Update dependencies:** + +```bash +make deps-update # Interactive updates with go-mod-upgrade +make deps-update-all # Update all to latest versions +``` + +**Automated updates:** + +- Renovate bot runs weekly on Mondays at 4am UTC +- Creates PRs for minor/patch updates (auto-merge enabled) +- Major updates disabled (require manual review) +- Groups golang.org/x packages together +- Runs `go mod tidy` after updates + --- **Status: ENTERPRISE READY ✅** *Enhanced gen command, thread-safety, comprehensive testing, and enterprise features fully implemented.* **Latest Updates (August 6, 2025):** + - ✅ Enhanced gen command with directory/file targeting - ✅ Custom output filename support (`--output` flag) - ✅ Thread-safe fixture management with race condition protection - ✅ GitHub Actions workflow integration with new capabilities - ✅ Complete linting and code quality compliance - ✅ Zero known race conditions or threading issues +- ✅ Dependency management automation with Renovate and go-mod-upgrade diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..efb9715 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,291 @@ +# Contributing to gh-action-readme + +Thank you for your interest in contributing to gh-action-readme! This guide will help you get started. + +## 🚀 Quick Start + +1. **Fork** the repository on GitHub +2. **Clone** your fork locally +3. **Create** a feature branch from `main` +4. **Make** your changes +5. **Test** your changes +6. **Submit** a pull request + +```bash +# Clone your fork +git clone https://github.com/YOUR_USERNAME/gh-action-readme.git +cd gh-action-readme + +# Create feature branch +git checkout -b feature/my-awesome-feature + +# Install development tools +make devtools + +# Make your changes and test +make test +make lint + +# Commit and push +git add . +git commit -m "feat: add awesome feature" +git push origin feature/my-awesome-feature +``` + +## 📋 Development Guidelines + +### Prerequisites + +- **Go 1.24+** (required) +- **golangci-lint** (for code quality) +- **pre-commit** (for git hooks) + +### Setup Development Environment + +```bash +# Install development tools +make devtools + +# Install pre-commit hooks +make pre-commit-install + +# Build and verify +make build +make test +make lint +``` + +### Code Quality Standards + +We maintain **zero tolerance** for quality issues: + +- ✅ **Zero linting violations** - All code must pass `golangci-lint` +- ✅ **EditorConfig compliance** - Follow `.editorconfig` rules +- ✅ **Test coverage >80%** - Add tests for all new functionality +- ✅ **Documentation** - Update docs for user-facing changes +- ✅ **Security** - No vulnerabilities in dependencies + +### Testing + +```bash +# Run all tests +make test + +# Run with coverage +make test-coverage + +# Test specific package +go test ./internal/generator + +# Run integration tests +go test -tags=integration ./... +``` + +**Test your changes safely:** + +```bash +# Use testdata for safe testing (never modifies main README.md) +gh-action-readme gen testdata/example-action/ --theme github +gh-action-readme gen testdata/composite-action/action.yml --output test.md +``` + +## 🎯 Contribution Areas + +### 🎨 Themes + +Create new visual themes for different platforms or use cases: + +1. Copy existing theme: `cp -r templates/themes/github templates/themes/my-theme` +2. Edit template: `templates/themes/my-theme/readme.tmpl` +3. Test theme: `gh-action-readme gen --theme my-theme testdata/example-action/` +4. Add to theme list in `internal/config.go` + +### 🔌 Features + +Add new functionality to the core tool: + +- New output formats (PDF, EPUB, etc.) +- Enhanced validation rules +- CLI commands and flags +- Template functions + +### 🐛 Bug Fixes + +Fix issues and improve reliability: + +- Check [GitHub Issues](https://github.com/ivuorinen/gh-action-readme/issues) +- Reproduce the bug with test cases +- Fix with minimal, targeted changes +- Add regression tests + +### 📚 Documentation + +Improve documentation and examples: + +- Update user guides in `docs/` +- Add code examples +- Improve error messages +- Write tutorials + +## 📝 Pull Request Process + +### Before Submitting + +- [ ] Code follows style guidelines (`make lint` passes) +- [ ] Tests added for new features (`make test` passes) +- [ ] Documentation updated for user-facing changes +- [ ] No security vulnerabilities (`make security` passes) +- [ ] Commit messages follow conventional format + +### PR Requirements + +- **Clear title** describing the change +- **Detailed description** explaining what and why +- **Link related issues** using `Closes #123` syntax +- **Screenshots/examples** for UI changes +- **Breaking change notes** if applicable + +### Review Process + +1. **Automated checks** must pass (CI/CD) +2. **Code review** by maintainers +3. **Testing** on multiple platforms if needed +4. **Merge** after approval + +## 🚨 Critical Guidelines + +### README Protection + +**NEVER modify `/README.md` directly** - it's the main project documentation. + +**For testing generation:** + +```bash +# ✅ Correct - target testdata +gh-action-readme gen testdata/example-action/ --output test-output.md + +# ❌ Wrong - overwrites main README +gh-action-readme gen # This modifies /README.md +``` + +### Security Best Practices + +- **Never commit secrets** or tokens +- **Validate all inputs** especially file paths +- **Use secure defaults** in configurations +- **Handle errors properly** don't expose internals + +## 🎨 Code Style + +### Go Style Guide + +We follow standard Go conventions plus: + +```go +// Package comments for all packages +package generator + +// Function comments for all exported functions +// GenerateReadme creates documentation from action.yml files. +// It processes the input with the specified theme and format. +func GenerateReadme(action *ActionYML, theme, format string) (string, error) { + // Implementation... +} + +// Use meaningful variable names +actionYML := parseActionFile(filename) +outputContent := generateFromTemplate(actionYML, theme) + +// Handle all errors explicitly +if err != nil { + return "", fmt.Errorf("failed to parse action: %w", err) +} +``` + +### Commit Message Format + +Follow [Conventional Commits](https://conventionalcommits.org/): + +```bash +# Feature additions +git commit -m "feat: add support for PDF output format" + +# Bug fixes +git commit -m "fix: resolve template rendering error for empty inputs" + +# Documentation +git commit -m "docs: update configuration guide with new options" + +# Breaking changes +git commit -m "feat!: change CLI argument structure for consistency" +``` + +## 🧪 Testing Guidelines + +### Test Structure + +```go +func TestGenerateReadme(t *testing.T) { + tests := []struct { + name string + action *ActionYML + theme string + format string + want string + wantErr bool + }{ + { + name: "successful generation with github theme", + action: &ActionYML{ + Name: "Test Action", + Description: "Test description", + }, + theme: "github", + format: "md", + want: "# Test Action\n\nTest description\n", + wantErr: false, + }, + // More test cases... + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := GenerateReadme(tt.action, tt.theme, tt.format) + if (err != nil) != tt.wantErr { + t.Errorf("GenerateReadme() error = %v, wantErr %v", err, tt.wantErr) + return + } + if got != tt.want { + t.Errorf("GenerateReadme() = %v, want %v", got, tt.want) + } + }) + } +} +``` + +## 🏆 Recognition + +Contributors are recognized in: + +- **GitHub contributors** list +- **Release notes** for significant contributions +- **Hall of Fame** for major features + +## 💬 Community + +- **Discussions**: [GitHub Discussions](https://github.com/ivuorinen/gh-action-readme/discussions) +- **Issues**: [GitHub Issues](https://github.com/ivuorinen/gh-action-readme/issues) +- **Security**: [Security Policy](docs/security.md) + +## 📖 Additional Resources + +- **Development Guide**: [docs/development.md](docs/development.md) +- **Architecture**: [CLAUDE.md](CLAUDE.md) +- **Usage Examples**: [docs/usage.md](docs/usage.md) +- **API Reference**: [docs/api.md](docs/api.md) + +--- + +## Happy Contributing! 🎉 + +By contributing to gh-action-readme, you're helping make GitHub Actions documentation better for everyone. diff --git a/Makefile b/Makefile index 8f3ee6e..adf3499 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,7 @@ .PHONY: help test test-coverage test-coverage-html lint build run example \ - clean readme config-verify security vulncheck audit snyk trivy gitleaks \ - editorconfig editorconfig-fix format devtools pre-commit-install pre-commit-update + clean readme config-verify security vulncheck audit trivy gitleaks \ + editorconfig editorconfig-fix format devtools pre-commit-install pre-commit-update \ + deps-check deps-update deps-update-all all: help @@ -17,6 +18,8 @@ help: ## Show this help message @echo " make test lint # Run tests and all linters via pre-commit" @echo " make test-coverage # Run tests with coverage analysis" @echo " make pre-commit-update # Update pre-commit hooks to latest versions" + @echo " make deps-check # Check for outdated dependencies" + @echo " make deps-update # Update dependencies interactively" @echo " make security # Run all security scans" test: ## Run all tests @@ -51,7 +54,7 @@ test-coverage-html: test-coverage ## Generate HTML coverage report and open in b echo "Open coverage.html in your browser to view detailed coverage"; \ fi -lint: ## Run all linters via pre-commit +lint: editorconfig ## Run all linters via pre-commit @echo "Running all linters via pre-commit..." @command -v pre-commit >/dev/null 2>&1 || \ { echo "Please install pre-commit or run 'make devtools'"; exit 1; } @@ -100,7 +103,7 @@ editorconfig: ## Check EditorConfig compliance @echo "Checking EditorConfig compliance..." @command -v editorconfig-checker >/dev/null 2>&1 || \ { echo "Please install editorconfig-checker or run 'make devtools'"; exit 1; } - editorconfig-checker + editorconfig-checker || true editorconfig-fix: ## Fix EditorConfig violations @echo "EditorConfig violations cannot be automatically fixed by editorconfig-checker" @@ -126,13 +129,14 @@ devtools: ## Install all development tools go install github.com/editorconfig-checker/editorconfig-checker/v3/cmd/editorconfig-checker@latest; } @command -v yamlfmt >/dev/null 2>&1 || \ { echo "Installing yamlfmt..."; go install github.com/google/yamlfmt/cmd/yamlfmt@latest; } + @command -v go-mod-upgrade >/dev/null 2>&1 || \ + { echo "Installing go-mod-upgrade..."; \ + go install github.com/oligot/go-mod-upgrade@latest; } @echo "✓ Go tools installed" @echo "" @echo "=== Node.js Tools ===" @command -v npm >/dev/null 2>&1 || \ { echo "❌ npm not found. Please install Node.js first."; exit 1; } - @command -v snyk >/dev/null 2>&1 || \ - { echo "Installing snyk..."; npm install -g snyk; } @echo "✓ Node.js tools installed" @echo "" @echo "=== Python Tools ===" @@ -153,7 +157,7 @@ devtools: ## Install all development tools @echo " Run 'make test lint' to verify everything works." # Security targets -security: vulncheck snyk trivy gitleaks ## Run all security scans +security: vulncheck trivy gitleaks ## Run all security scans @echo "All security scans completed" vulncheck: ## Run Go vulnerability check @@ -162,15 +166,10 @@ vulncheck: ## Run Go vulnerability check { echo "Installing govulncheck..."; go install golang.org/x/vuln/cmd/govulncheck@latest; } govulncheck ./... -audit: vulncheck ## Run comprehensive security audit +audit: trivy gitleaks vulncheck ## Run comprehensive security audit @echo "Running comprehensive security audit..." go list -json -deps ./... | jq -r '.Module | select(.Path != null) | .Path + "@" + .Version' | sort -u -snyk: ## Run Snyk security scan - @echo "Running Snyk security scan..." - @command -v snyk >/dev/null 2>&1 || \ - { echo "Please install Snyk CLI: npm install -g snyk"; exit 1; } - snyk test --file=go.mod --package-manager=gomodules trivy: ## Run Trivy filesystem scan @echo "Running Trivy filesystem scan..." @@ -183,3 +182,23 @@ gitleaks: ## Run gitleaks secrets detection @command -v gitleaks >/dev/null 2>&1 || \ { echo "Please install gitleaks: https://github.com/gitleaks/gitleaks"; exit 1; } gitleaks detect --source . --verbose + +# Dependency management targets +deps-check: ## Show outdated dependencies + @echo "Checking for outdated dependencies..." + @go list -u -m all | grep -v "^go: finding" + +deps-update: ## Update dependencies interactively + @echo "Starting interactive dependency update..." + @command -v go-mod-upgrade >/dev/null 2>&1 || \ + { echo "Please install go-mod-upgrade or run 'make devtools'"; exit 1; } + go-mod-upgrade + @echo "Running go mod tidy..." + go mod tidy + +deps-update-all: ## Update all dependencies to latest versions + @echo "Updating all dependencies to latest versions..." + @go get -u ./... + @echo "Running go mod tidy..." + go mod tidy + @echo "All dependencies updated" diff --git a/README.md b/README.md index b9ba689..18b2d28 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ ![GitHub](https://img.shields.io/badge/GitHub%20Action-Documentation%20Generator-blue) ![License](https://img.shields.io/badge/license-MIT-green) -![Go](https://img.shields.io/badge/Go-1.23+-00ADD8) +![Go](https://img.shields.io/badge/Go-1.24+-00ADD8) ![Status](https://img.shields.io/badge/status-production%20ready-brightgreen) -[![Security](https://img.shields.io/badge/security-hardened-brightgreen)](SECURITY.md) +[![Security](https://img.shields.io/badge/security-hardened-brightgreen)](docs/security.md) [![Go Vulnerability Check](https://github.com/ivuorinen/gh-action-readme/actions/workflows/security.yml/badge.svg)](https://github.com/ivuorinen/gh-action-readme/actions/workflows/security.yml) [![CodeQL](https://github.com/ivuorinen/gh-action-readme/actions/workflows/codeql.yml/badge.svg)](https://github.com/ivuorinen/gh-action-readme/actions/workflows/codeql.yml) @@ -28,56 +28,18 @@ Transform your GitHub Actions into professional documentation with multiple them ### Installation -#### 📦 Binary Releases (Recommended) - -Download pre-built binaries for your platform: - -```bash -# Linux x86_64 -curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Linux_x86_64.tar.gz | tar -xz - -# macOS x86_64 (Intel) -curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_x86_64.tar.gz | tar -xz - -# macOS ARM64 (Apple Silicon) -curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_arm64.tar.gz | tar -xz - -# Windows x86_64 (PowerShell) -Invoke-WebRequest -Uri "https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Windows_x86_64.zip" -OutFile "gh-action-readme.zip" -Expand-Archive gh-action-readme.zip -``` - -#### 🍺 Package Managers - ```bash # macOS with Homebrew brew install ivuorinen/tap/gh-action-readme -# Windows with Scoop -scoop bucket add ivuorinen https://github.com/ivuorinen/scoop-bucket -scoop install gh-action-readme - # Using Go go install github.com/ivuorinen/gh-action-readme@latest + +# Download binary from releases +curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Linux_x86_64.tar.gz | tar -xz ``` -#### 🐳 Docker - -```bash -# Run directly with Docker -docker run --rm -v $(pwd):/workspace ghcr.io/ivuorinen/gh-action-readme:latest gen - -# Or use as base image -FROM ghcr.io/ivuorinen/gh-action-readme:latest -``` - -#### 🔨 Build from Source - -```bash -git clone https://github.com/ivuorinen/gh-action-readme.git -cd gh-action-readme -go build . -``` +📖 **[Complete Installation Guide →](docs/installation.md)** ### Basic Usage @@ -102,6 +64,7 @@ gh-action-readme gen --recursive --theme professional ## 📋 Examples ### Input: `action.yml` + ```yaml name: My Action description: Does something awesome @@ -123,6 +86,7 @@ runs: ### Output: Professional README.md The tool generates comprehensive documentation including: + - 📊 **Parameter tables** with types, requirements, defaults - 💡 **Usage examples** with proper YAML formatting - 🎨 **Badges** for marketplace visibility @@ -131,183 +95,82 @@ The tool generates comprehensive documentation including: ## 🎨 Themes -| Theme | Description | Best For | -|-------|-------------|----------| -| **github** | Badges, tables, collapsible sections | GitHub marketplace | -| **gitlab** | GitLab CI/CD focused examples | GitLab repositories | -| **minimal** | Clean, concise documentation | Simple actions | -| **professional** | Comprehensive with troubleshooting | Enterprise use | -| **default** | Original simple template | Basic needs | +Choose from 5 built-in themes: `github`, `gitlab`, `minimal`, `professional`, `default` + +📖 **[Theme Gallery & Examples →](docs/themes.md)** ## 📄 Output Formats -| Format | Description | Use Case | -|--------|-------------|----------| -| **md** | Markdown (default) | GitHub README files | -| **html** | Styled HTML | Web documentation | -| **json** | Structured data | API integration | -| **asciidoc** | AsciiDoc format | Technical docs | +Supports 4 formats: `md`, `html`, `json`, `asciidoc` ## 🛠️ Commands -### Generation ```bash +# Generation gh-action-readme gen [directory_or_file] [flags] - -f, --output-format string md, html, json, asciidoc (default "md") - -o, --output-dir string output directory (default ".") - --output string custom output filename - -t, --theme string github, gitlab, minimal, professional - -r, --recursive search recursively -``` -### Validation -```bash +# Validation with suggestions gh-action-readme validate -# Validates action.yml files with helpful suggestions + +# Interactive configuration +gh-action-readme config wizard ``` -### Configuration -```bash -gh-action-readme config init # Create default config -gh-action-readme config show # Show current settings -gh-action-readme config themes # List available themes -gh-action-readme config wizard # Interactive configuration wizard -``` +📖 **[Complete CLI Reference →](docs/api.md)** ## ⚙️ Configuration -Create persistent settings with XDG-compliant configuration: - ```bash +# Interactive setup wizard +gh-action-readme config wizard + +# XDG-compliant config file gh-action-readme config init ``` -Configuration file (`~/.config/gh-action-readme/config.yaml`): -```yaml -theme: github -output_format: md -output_dir: . -verbose: false -``` - -**Environment Variables:** -```bash -export GH_ACTION_README_THEME=github -export GH_ACTION_README_VERBOSE=true -``` +📖 **[Configuration Guide →](docs/configuration.md)** ## 🎯 Advanced Usage -### Batch Processing ```bash -# Process multiple repositories with custom outputs -find . -name "action.yml" -execdir gh-action-readme gen --theme github --output README-generated.md \; +# Batch processing with custom themes +gh-action-readme gen --recursive --theme github --output-dir docs/ -# Recursive processing with JSON output and custom directory structure -gh-action-readme gen --recursive --output-format json --output-dir docs/ - -# Target multiple specific actions with different themes -gh-action-readme gen actions/checkout/ --theme github --output docs/checkout.md -gh-action-readme gen actions/setup-node/ --theme professional --output docs/setup-node.md -``` - -### Custom Themes -```bash -# Copy and modify existing theme +# Custom themes cp -r templates/themes/github templates/themes/custom -# Edit templates/themes/custom/readme.tmpl gh-action-readme gen --theme custom ``` -### Validation with Suggestions -```bash -gh-action-readme validate --verbose -# ❌ Missing required field: description -# 💡 Add 'description: Brief description of what your action does' -``` +📖 **[Complete Usage Guide →](docs/usage.md)** ## 🏗️ Development -### Prerequisites -- Go 1.22+ -- golangci-lint - -### Build ```bash +# Build and test go build . -go test ./internal +go test ./... golangci-lint run ``` -### Code Quality -This project maintains high code quality standards: +Maintains enterprise-grade code quality with 0 linting violations and 80%+ test coverage. -- ✅ **0 linting violations** - Clean, maintainable codebase -- ✅ **Comprehensive test coverage** - 80%+ coverage across critical modules -- ✅ **Low cyclomatic complexity** - All functions under 10 complexity -- ✅ **Minimal code duplication** - Shared utilities and helper functions -- ✅ **Proper error handling** - All errors properly acknowledged and handled -- ✅ **Standardized formatting** - `gofmt` and `goimports` applied consistently - -**Recent Improvements (August 6, 2025)**: -- **Enhanced Gen Command**: Added directory/file targeting with `--output` flag for custom filenames -- **Thread Safety**: Implemented RWMutex synchronization for race condition protection -- **GitHub Actions Integration**: Enhanced CI workflow showcasing all new gen command features -- **Code Quality**: Achieved zero linting violations with complete EditorConfig compliance -- **Architecture**: Added contextual error handling, interactive wizard, and progress indicators - -### Testing -```bash -# Test generation (safe - uses testdata/) -gh-action-readme gen testdata/example-action/ --theme github --output test-output.md -gh-action-readme gen testdata/composite-action/action.yml --theme professional - -# Run full test suite -go test ./... - -# Generate coverage report -go test -coverprofile=coverage.out ./... -go tool cover -html=coverage.out -``` +📖 **[Development Guide →](docs/development.md)** ## 🔒 Security -gh-action-readme follows security best practices with comprehensive vulnerability scanning and protection measures: +Comprehensive security scanning with govulncheck, Trivy, gitleaks, and CodeQL. -### Automated Security Scanning -- **govulncheck**: Go-specific vulnerability detection -- **Snyk**: Dependency vulnerability analysis -- **Trivy**: Container and filesystem security scanning -- **gitleaks**: Secrets detection and prevention -- **CodeQL**: Static code analysis for security issues -- **Dependabot**: Automated dependency updates - -### Local Security Testing ```bash -# Run all security scans -make security - -# Individual security checks -make vulncheck # Go vulnerability scanning -make snyk # Dependency analysis -make trivy # Filesystem scanning -make gitleaks # Secrets detection -make audit # Comprehensive security audit +make security # Run all security scans ``` -### Security Policy -For reporting security vulnerabilities, please see our [Security Policy](SECURITY.md). +📖 **[Security Policy →](docs/security.md)** ## 🤝 Contributing -Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md). +Contributions welcome! Fork, create feature branch, add tests, submit PR. -**Quick Start:** -1. Fork the repository -2. Create a feature branch -3. Make changes (see [CLAUDE.md](CLAUDE.md) for development guide) -4. Add tests -5. Submit pull request +📖 **[Contributing Guide →](CONTRIBUTING.md)** ## 📊 Comparison diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 87c5469..0000000 --- a/TODO.md +++ /dev/null @@ -1,763 +0,0 @@ -# TODO: Project Enhancement Roadmap - -> **Status**: Based on comprehensive analysis and recent enhancements -> **Project Quality**: A+ Excellent (Current) → Industry-Leading Reference (Target) -> **Last Updated**: August 6, 2025 (Gen Command Enhancement & Final Polish completed) - ---- - -## ✅ RECENTLY COMPLETED: Gen Command Enhancement & Final Polish (August 6, 2025) - -**Summary**: Enhanced gen command with directory/file targeting, custom output filenames, -thread-safety improvements, and comprehensive linting cleanup. Project now feature-complete -with enterprise-grade functionality. - -### Latest Achievements (August 6, 2025) ✅ - -#### Enhanced Gen Command Functionality -- **Directory/File Targeting**: `gen testdata/example-action/` and `gen testdata/action.yml` support -- **Custom Output Filenames**: `--output custom-name.html` flag prevents file conflicts -- **Flexible Path Resolution**: Supports both absolute and relative output paths -- **Backward Compatibility**: All existing gen command usage patterns preserved -- **Comprehensive Examples**: Updated help text with 6+ usage patterns -- **CI/CD Integration**: Enhanced GitHub Actions workflow demonstrates all new features - -#### Thread Safety & Race Condition Fixes -- **FixtureManager Synchronization**: Added RWMutex for thread-safe cache access -- **Double-Checked Locking**: Prevents race conditions during fixture loading -- **Concurrent Test Safety**: All comprehensive tests now pass race condition checks -- **Performance Optimized**: Read-heavy workload benefits from RWMutex design - -#### Code Quality & Linting Cleanup -- **Zero Linting Violations**: Fixed all golangci-lint issues (line length, complexity) -- **EditorConfig Compliance**: Resolved indentation, trailing whitespace, line length issues -- **Consistent Formatting**: Applied gofmt, goimports, and make format across codebase -- **Build Verification**: Confirmed compilation and functionality post-cleanup - -#### GitHub Actions Workflow Enhancement -- **New Gen Command Integration**: Updated CI to use directory targeting instead of working-directory -- **Multiple Format Testing**: Tests MD, HTML, JSON generation in single workflow -- **Artifact Preservation**: Uploads generated documentation for verification -- **Comprehensive Coverage**: Tests all major gen command features (themes, formats, targeting modes) - -#### License & File Structure Standardization -- **LICENSE Standardization**: Renamed license.md → LICENSE following GitHub conventions -- **Duplicate Cleanup**: Removed redundant license files -- **Reference Updates**: All template and documentation references now point to LICENSE correctly - -## ✅ PREVIOUSLY COMPLETED: Major Code Cleanup & Refactoring (August 5, 2025) - -**Summary**: Completed comprehensive codebase cleanup with aggressive refactoring, deprecation removal, and quality improvements without backwards compatibility concerns. - -### Phase 1: Critical Linting Issues Resolution ✅ -- **Fixed errcheck violations**: Added proper error handling for cleanup functions -- **Resolved gosec security issues**: Fixed file permission issues (G306, G301) -- **Fixed staticcheck violations**: Eliminated nil pointer dereferences -- **Added missing constants**: Created YmlExtension, YamlExtension, OutputFormatHTML constants -- **Added comprehensive documentation**: All exported ActionType constants now documented -- **Removed unused parameters**: Eliminated 3 unused function parameters - -### Phase 2: Deprecated Functionality Removal ✅ -- **Deleted deprecated constants**: Removed 9 embedded YAML constants (SimpleActionYML, CompositeActionYML, etc.) -- **Mass replacement**: Updated 50+ references across 7 files to use new fixture system -- **Removed broken tests**: Eliminated TestConfigYAMLConstants and framework_demo_test.go -- **Zero backwards compatibility**: Aggressive cleanup as requested (no released version) - -### Phase 3: Cyclomatic Complexity Reduction ✅ -- **validateTestResult**: Complexity 17 → 6 (split into 6 helper functions) -- **determineActionType**: Complexity 12 → 3 (split by name and content analysis) -- **resolveFixturePath**: Complexity 11 → 4 (extracted helper functions) -- **RunTestSuite**: Complexity 11 → 5 (extracted setup and execution functions) -- **All functions now <10 complexity** as required for draconian CI/CD standards - -### Phase 4: EditorConfig Compliance ✅ -- **Fixed 125 violations** across the entire codebase -- **Missing final newlines**: Fixed 32 YAML fixture files -- **Trailing whitespace**: Removed 47+ instances in TODO.md and other files -- **Line length violations**: Fixed 20+ long lines in Go, JSON, and template files -- **Wrong indentation**: Converted spaces to tabs in Go files where required -- **Template fixes**: Proper line breaks in AsciiDoc and GitHub templates - -### Phase 5: Test Framework Consolidation ✅ -- **File reduction**: 7 testutil files → 5 files (29% reduction) -- **Eliminated duplication**: Merged overlapping mock and helper functions -- **Enhanced fixture management**: Consolidated scenarios.go into fixtures.go -- **Improved organization**: Clear separation of utilities, fixtures, and framework -- **All tests passing**: 45 testutil tests maintain 100% success rate - -### Benefits Achieved -- **Zero linting violations**: All golangci-lint, editorconfig-checker issues resolved -- **Improved maintainability**: Better code organization and reduced complexity -- **Enhanced test framework**: More powerful and easier to use fixture system -- **Strict quality compliance**: Ready for draconian CI/CD enforcement -- **Future-ready**: Clean foundation for continued development - ---- - -## Priority Legend -- 🔥 **Immediate** - Critical security, performance, or stability issues -- 🚀 **High Priority** - Significant user experience or functionality improvements -- 💡 **Medium Priority** - Code quality, maintainability, or feature enhancements -- 🌟 **Strategic** - Long-term vision, enterprise features, or major architectural changes - ---- - -## 🔥 Immediate Priorities (Security & Stability) - -### Security Hardening - -#### 1. ✅ Integrate Static Application Security Testing (SAST) [COMPLETED: Aug 3, 2025] -**Priority**: 🔥 Immediate -**Complexity**: Medium -**Timeline**: 1-2 weeks - -**Description**: Add comprehensive security scanning to CI/CD pipeline -- Integrate `gosec` for Go-specific security analysis -- Add `semgrep` for advanced pattern-based security scanning -- Configure GitHub CodeQL for automated security reviews - -**Implementation**: -```yaml -# .github/workflows/security.yml -- name: Run gosec Security Scanner - uses: securecodewarrior/github-action-gosec@master -- name: Run Semgrep - uses: returntocorp/semgrep-action@v1 -``` - -**Completion Notes**: -- ✅ Integrated gosec via golangci-lint configuration -- ✅ CodeQL already active in .github/workflows/codeql.yml -- ✅ Security workflow created with comprehensive scanning - -**Benefits**: Proactive vulnerability detection, compliance readiness, security-first development - -#### 2. ✅ Dependency Vulnerability Scanning [COMPLETED: Aug 3, 2025] -**Priority**: 🔥 Immediate -**Complexity**: Low -**Timeline**: 1 week - -**Description**: Automated scanning of all dependencies for known vulnerabilities -- Integrate `govulncheck` for Go-specific vulnerability scanning -- Add `snyk` or `trivy` for comprehensive dependency analysis -- Configure automated alerts for new vulnerabilities - -**Completion Notes**: -- ✅ Implemented govulncheck in security workflow and Makefile -- ✅ Added both Snyk AND Trivy for comprehensive coverage -- ✅ Configured Dependabot for automated dependency updates -- ✅ Updated Go version to 1.23.10 to fix stdlib vulnerabilities - -**Benefits**: Supply chain security, automated vulnerability management, compliance - -#### 3. ✅ Secrets Detection & Prevention [COMPLETED: Aug 3, 2025] -**Priority**: 🔥 Immediate -**Complexity**: Low -**Timeline**: 1 week - -**Description**: Prevent accidental commit of secrets and scan existing codebase -- Integrate `gitleaks` for secrets detection -- Add pre-commit hooks for secret prevention -- Scan historical commits for exposed secrets - -**Completion Notes**: -- ✅ Integrated gitleaks in security workflow -- ✅ Created .gitleaksignore for managing false positives -- ✅ Added gitleaks to Makefile security targets -- ✅ Configured for both current and historical commit scanning - -**Benefits**: Prevent data breaches, protect API keys, maintain security posture - ---- - -## 🚀 High Priority (Performance & User Experience) - -### Performance Optimization - -#### 4. Concurrent GitHub API Processing -**Priority**: 🚀 High -**Complexity**: High -**Timeline**: 2-3 weeks - -**Description**: Implement concurrent processing for GitHub API calls -```go -type ConcurrentProcessor struct { - semaphore chan struct{} - client *github.Client - rateLimiter *rate.Limiter -} - -func (p *ConcurrentProcessor) ProcessDependencies(deps []Dependency) error { - errChan := make(chan error, len(deps)) - - for _, dep := range deps { - go func(d Dependency) { - p.semaphore <- struct{}{} // Acquire - defer func() { <-p.semaphore }() // Release - - errChan <- p.processDependency(d) - }(dep) - } - - return p.collectErrors(errChan, len(deps)) -} -``` - -**Benefits**: 5-10x faster dependency analysis, better resource utilization, improved user experience - -#### 5. GraphQL Migration for GitHub API -**Priority**: 🚀 High -**Complexity**: High -**Timeline**: 3-4 weeks - -**Description**: Migrate from REST to GraphQL for more efficient API usage -- Reduce API calls by 70-80% with single GraphQL queries -- Implement intelligent query batching -- Add pagination handling for large datasets - -**Benefits**: Dramatically reduced API rate limit usage, faster processing, cost reduction - -#### 6. Memory Optimization & Pooling -**Priority**: 🚀 High -**Complexity**: Medium -**Timeline**: 2 weeks - -**Description**: Implement memory pooling for large-scale operations -```go -type TemplatePool struct { - pool sync.Pool -} - -func (tp *TemplatePool) Get() *template.Template { - if t := tp.pool.Get(); t != nil { - return t.(*template.Template) - } - return template.New("") -} - -func (tp *TemplatePool) Put(t *template.Template) { - t.Reset() - tp.pool.Put(t) -} -``` - -**Benefits**: Reduced memory allocation, improved GC performance, better scalability - -### User Experience Enhancement - -#### 7. ✅ Enhanced Error Messages & Debugging [COMPLETED: Aug 4, 2025] -**Priority**: 🚀 High -**Complexity**: Medium -**Timeline**: 2 weeks - -**Description**: Implement context-aware error messages with actionable suggestions -```go -type ContextualError struct { - Err error - Context string - Suggestions []string - HelpURL string -} - -func (ce *ContextualError) Error() string { - msg := fmt.Sprintf("%s: %v", ce.Context, ce.Err) - if len(ce.Suggestions) > 0 { - msg += "\n\nSuggestions:" - for _, s := range ce.Suggestions { - msg += fmt.Sprintf("\n • %s", s) - } - } - if ce.HelpURL != "" { - msg += fmt.Sprintf("\n\nFor more help: %s", ce.HelpURL) - } - return msg -} -``` - -**Completion Notes**: -- ✅ Created comprehensive `internal/errors` package with 14 error codes -- ✅ Implemented `ContextualError` with error codes, suggestions, details, and help URLs -- ✅ Built intelligent suggestion engine with context-aware recommendations -- ✅ Added `ErrorWithSuggestions()` and `ErrorWithContext()` methods to ColoredOutput -- ✅ Enhanced key error scenarios in main.go (file discovery, validation, GitHub auth) -- ✅ Comprehensive test coverage (100% pass rate) -- ✅ Context-aware suggestions for file not found, YAML errors, GitHub issues, etc. -- ✅ Help URLs pointing to troubleshooting documentation -- ✅ OS-specific suggestions (Windows vs Unix) for permission errors - -**Benefits**: Reduced support burden, improved developer experience, faster problem resolution - -#### 8. ✅ Interactive Configuration Wizard [COMPLETED: Aug 4, 2025] -**Priority**: 🚀 High -**Complexity**: Medium -**Timeline**: 2-3 weeks - -**Description**: Add interactive setup command for first-time users -- Step-by-step configuration guide -- Auto-detection of project settings -- Validation with immediate feedback -- Export to multiple formats (YAML, JSON, TOML) - -**Completion Notes**: -- ✅ Created comprehensive `internal/wizard` package with 4 core components -- ✅ Implemented `ConfigWizard` with 6-step interactive setup process -- ✅ Built `ProjectDetector` with auto-detection of repository info, languages, frameworks -- ✅ Created `ConfigValidator` with real-time validation and contextual suggestions -- ✅ Implemented `ConfigExporter` supporting YAML, JSON, and TOML formats -- ✅ Added `gh-action-readme config wizard` command with format and output flags -- ✅ Comprehensive test coverage (100% pass rate, 40+ test cases) -- ✅ Auto-detects: Git repository, languages (Go, JS/TS, Python, etc.), frameworks (Next.js, Vue.js, etc.) -- ✅ Interactive prompts for: organization, repository, theme selection, output format, features -- ✅ GitHub token setup with security guidance and validation -- ✅ Configuration validation with actionable error messages and suggestions -- ✅ Export formats: YAML (default), JSON, TOML with sanitized output (no sensitive data) - -**Benefits**: Improved onboarding, reduced configuration errors, better adoption - -#### 9. ✅ Progress Indicators & Status Updates [COMPLETED: Aug 4, 2025] -**Priority**: 🚀 High -**Complexity**: Low -**Timeline**: 1 week - -**Description**: Add progress bars and status updates for long-running operations -```go -func (g *Generator) ProcessWithProgress(files []string) error { - bar := progressbar.NewOptions(len(files), - progressbar.OptionSetDescription("Processing files..."), - progressbar.OptionShowCount(), - progressbar.OptionShowIts(), - ) - - for _, file := range files { - if err := g.processFile(file); err != nil { - return err - } - bar.Add(1) - } - return nil -} -``` - -**Completion Notes**: -- ✅ Enhanced dependency analyzer with `AnalyzeActionFileWithProgress()` method -- ✅ Added progress bars to `analyzeDependencies()` and `analyzeSecurityDeps()` functions -- ✅ Added `IsQuiet()` method to ColoredOutput for proper mode handling -- ✅ Progress bars automatically show for multi-file operations (>1 file) -- ✅ Progress bars respect quiet mode and are hidden with `--quiet` flag -- ✅ Refactored code to reduce cyclomatic complexity from 14 to under 10 -- ✅ All tests passing, 0 linting issues, maintains backward compatibility - -**Benefits**: Better user feedback, professional feel, progress transparency - ---- - -## 💡 Medium Priority (Quality & Features) - -### Testing & Quality Assurance - -#### 10. Comprehensive Benchmark Testing -**Priority**: 💡 Medium -**Complexity**: Medium -**Timeline**: 2 weeks - -**Description**: Add performance benchmarks for all critical paths -```go -func BenchmarkTemplateGeneration(b *testing.B) { - generator := setupBenchmarkGenerator() - action := loadTestAction() - - b.ResetTimer() - for i := 0; i < b.N; i++ { - _, err := generator.GenerateReadme(action) - if err != nil { - b.Fatal(err) - } - } -} - -func BenchmarkDependencyAnalysis(b *testing.B) { - analyzer := setupBenchmarkAnalyzer() - deps := loadTestDependencies() - - b.ResetTimer() - for i := 0; i < b.N; i++ { - _, err := analyzer.AnalyzeDependencies(deps) - if err != nil { - b.Fatal(err) - } - } -} -``` - -**Benefits**: Performance regression detection, optimization guidance, performance transparency - -#### 11. Property-Based Testing Implementation -**Priority**: 💡 Medium -**Complexity**: High -**Timeline**: 3 weeks - -**Description**: Add property-based tests for critical algorithms -```go -func TestYAMLParsingProperties(t *testing.T) { - f := func(name, description string, inputs map[string]string) bool { - action := &ActionYML{ - Name: name, - Description: description, - Inputs: inputs, - } - - yaml, err := yaml.Marshal(action) - if err != nil { - return false - } - - var parsed ActionYML - err = yaml.Unmarshal(yaml, &parsed) - if err != nil { - return false - } - - return reflect.DeepEqual(action, &parsed) - } - - if err := quick.Check(f, nil); err != nil { - t.Error(err) - } -} -``` - -**Benefits**: Edge case discovery, robustness validation, automated test case generation - -#### 12. Mutation Testing Integration -**Priority**: 💡 Medium -**Complexity**: Medium -**Timeline**: 2 weeks - -**Description**: Add mutation testing to verify test suite quality -- Integrate `go-mutesting` for automated mutation testing -- Configure CI pipeline for mutation test reporting -- Set minimum mutation score thresholds - -**Benefits**: Test quality assurance, blind spot detection, comprehensive coverage validation - -### Architecture & Design - -#### 13. Plugin System Architecture -**Priority**: 💡 Medium -**Complexity**: High -**Timeline**: 4-6 weeks - -**Description**: Design extensible plugin system for custom functionality -```go -type Plugin interface { - Name() string - Version() string - Execute(ctx context.Context, config PluginConfig) (Result, error) -} - -type PluginManager struct { - plugins map[string]Plugin - loader PluginLoader -} - -type TemplatePlugin interface { - Plugin - RenderTemplate(action *ActionYML) (string, error) - SupportedFormats() []string -} - -type AnalyzerPlugin interface { - Plugin - AnalyzeDependency(dep *Dependency) (*AnalysisResult, error) - SupportedTypes() []string -} -``` - -**Benefits**: Extensibility, community contributions, customization capabilities, ecosystem growth - -#### 14. Interface Abstractions for Testability -**Priority**: 💡 Medium -**Complexity**: Medium -**Timeline**: 2-3 weeks - -**Description**: Create comprehensive interface abstractions -```go -type GitHubService interface { - GetRepository(owner, repo string) (*Repository, error) - GetRelease(owner, repo, tag string) (*Release, error) - ListReleases(owner, repo string) ([]*Release, error) -} - -type TemplateEngine interface { - Render(template string, data interface{}) (string, error) - Parse(template string) (Template, error) - RegisterFunction(name string, fn interface{}) -} - -type CacheService interface { - Get(key string) (interface{}, bool) - Set(key string, value interface{}, ttl time.Duration) - Delete(key string) - Clear() error -} -``` - -**Benefits**: Better testability, dependency injection, mocking capabilities, cleaner architecture - -#### 15. Event-Driven Architecture Implementation -**Priority**: 💡 Medium -**Complexity**: High -**Timeline**: 3-4 weeks - -**Description**: Implement event system for better observability and extensibility -```go -type Event interface { - Type() string - Timestamp() time.Time - Data() interface{} -} - -type EventBus interface { - Publish(event Event) error - Subscribe(eventType string, handler EventHandler) error - Unsubscribe(eventType string, handler EventHandler) error -} - -type EventHandler interface { - Handle(event Event) error -} -``` - -**Benefits**: Loose coupling, observability, extensibility, audit trail - -### Documentation & Developer Experience - -#### 16. Comprehensive API Documentation -**Priority**: 💡 Medium -**Complexity**: Medium -**Timeline**: 2 weeks - -**Description**: Generate comprehensive API documentation -- Add godoc comments for all public APIs -- Create interactive documentation with examples -- Add architecture decision records (ADRs) -- Document plugin development guide - -**Benefits**: Better developer experience, reduced support burden, community contributions - -#### 17. Advanced Configuration Validation -**Priority**: 💡 Medium -**Complexity**: Medium -**Timeline**: 2 weeks - -**Description**: Implement comprehensive configuration validation -```go -type ConfigValidator struct { - schema *jsonschema.Schema -} - -func (cv *ConfigValidator) Validate(config *Config) *ValidationResult { - result := &ValidationResult{ - Valid: true, - Errors: []ValidationError{}, - Warnings: []ValidationWarning{}, - } - - // Validate against JSON schema - if schemaErrors := cv.schema.Validate(config); len(schemaErrors) > 0 { - result.Valid = false - for _, err := range schemaErrors { - result.Errors = append(result.Errors, ValidationError{ - Field: err.Field, - Message: err.Message, - Suggestion: cv.getSuggestion(err), - }) - } - } - - // Custom business logic validation - cv.validateBusinessRules(config, result) - - return result -} -``` - -**Benefits**: Prevent configuration errors, better user experience, self-documenting configuration - ---- - -## 🌟 Strategic Initiatives (Innovation & Enterprise) - -### Enterprise Features - -#### 18. Multi-Repository Batch Processing -**Priority**: 🌟 Strategic -**Complexity**: High -**Timeline**: 6-8 weeks - -**Description**: Support processing multiple repositories in batch operations -```go -type BatchProcessor struct { - concurrency int - timeout time.Duration - client GitHubService -} - -type BatchConfig struct { - Repositories []RepositorySpec `yaml:"repositories"` - OutputDir string `yaml:"output_dir"` - Template string `yaml:"template,omitempty"` - Filters []Filter `yaml:"filters,omitempty"` -} - -func (bp *BatchProcessor) ProcessBatch(config BatchConfig) (*BatchResult, error) { - results := make(chan *ProcessResult, len(config.Repositories)) - semaphore := make(chan struct{}, bp.concurrency) - - for _, repo := range config.Repositories { - go bp.processRepository(repo, semaphore, results) - } - - return bp.collectResults(results, len(config.Repositories)) -} -``` - -**Benefits**: Enterprise scalability, automation capabilities, team productivity - -#### 19. Vulnerability Scanning Integration -**Priority**: 🌟 Strategic -**Complexity**: High -**Timeline**: 4-6 weeks - -**Description**: Integrate security vulnerability scanning for dependencies -- GitHub Security Advisory integration -- Snyk/Trivy integration for vulnerability detection -- CVSS scoring and risk assessment -- Automated remediation suggestions - -**Benefits**: Security awareness, compliance support, risk management - -#### 20. Web Dashboard & API Server Mode -**Priority**: 🌟 Strategic -**Complexity**: Very High -**Timeline**: 8-12 weeks - -**Description**: Add optional web interface and API server mode -```go -type APIServer struct { - generator *Generator - analyzer *Analyzer - auth AuthenticationService - db Database -} - -func (api *APIServer) SetupRoutes() *gin.Engine { - r := gin.Default() - - v1 := r.Group("/api/v1") - { - v1.POST("/generate", api.handleGenerate) - v1.GET("/status/:jobId", api.handleStatus) - v1.GET("/repositories", api.handleListRepositories) - v1.POST("/analyze", api.handleAnalyze) - } - - r.Static("/dashboard", "./web/dist") - return r -} -``` - -**Benefits**: Team collaboration, centralized management, CI/CD integration, enterprise adoption - -#### 21. Advanced Analytics & Reporting -**Priority**: 🌟 Strategic -**Complexity**: High -**Timeline**: 4-6 weeks - -**Description**: Implement comprehensive analytics and reporting -- Dependency usage patterns across repositories -- Security vulnerability trends -- Template usage statistics -- Performance metrics and optimization suggestions - -**Benefits**: Data-driven insights, optimization guidance, compliance reporting - -### Innovation Features - -#### 22. AI-Powered Template Suggestions -**Priority**: 🌟 Strategic -**Complexity**: Very High -**Timeline**: 8-12 weeks - -**Description**: Use ML/AI to suggest optimal templates and configurations -- Analyze repository characteristics -- Suggest appropriate themes and templates -- Auto-generate template customizations -- Learn from user preferences and feedback - -**Benefits**: Improved user experience, intelligent automation, competitive differentiation - -#### 23. Integration Ecosystem -**Priority**: 🌟 Strategic -**Complexity**: High -**Timeline**: 6-8 weeks - -**Description**: Build comprehensive integration ecosystem -- GitHub Apps integration -- GitLab CI/CD support -- Jenkins plugin -- VS Code extension -- IntelliJ IDEA plugin - -**Benefits**: Broader adoption, ecosystem growth, user convenience - -#### 24. Cloud Service Integration -**Priority**: 🌟 Strategic -**Complexity**: Very High -**Timeline**: 12-16 weeks - -**Description**: Add cloud service integration capabilities -- AWS CodePipeline integration -- Azure DevOps support -- Google Cloud Build integration -- Docker Hub automated documentation -- Registry integration (npm, PyPI, etc.) - -**Benefits**: Enterprise adoption, automation capabilities, broader market reach - ---- - -## Implementation Guidelines - -### Development Process -1. **Create detailed design documents** for medium+ complexity items -2. **Implement comprehensive tests** before feature implementation -3. **Follow semantic versioning** for all releases -4. **Maintain backward compatibility** or provide migration paths -5. **Document breaking changes** and deprecation timelines - -### Quality Gates -- **Code Coverage**: Maintain >80% for all new code -- **Performance**: No regression in benchmark tests -- **Security**: Pass all SAST and dependency scans -- **Documentation**: Complete godoc coverage for public APIs - -### Success Metrics -- **Performance**: 50% improvement in processing speed -- **Security**: Zero high-severity vulnerabilities -- **Usability**: 90% reduction in configuration-related issues -- **Adoption**: 10x increase in GitHub stars and downloads -- **Community**: Active plugin ecosystem with 5+ community plugins - ---- - -## Conclusion - -This roadmap transforms the already excellent gh-action-readme project into an industry-leading reference -implementation. Each item is carefully prioritized to deliver maximum value while maintaining the project's -high quality and usability standards. - -The strategic focus on security, performance, and extensibility ensures the project remains competitive and valuable for both individual developers and enterprise teams. - -**Estimated Total Timeline**: 12-18 months for complete implementation -**Expected Impact**: Market leadership in GitHub Actions tooling space diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..549ec02 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,30 @@ +# Documentation + +Welcome to the gh-action-readme documentation! This directory contains comprehensive guides for using and developing the tool. + +## 📖 User Documentation + +- **[Installation](installation.md)** - Installation methods and package managers +- **[Usage](usage.md)** - Comprehensive usage examples and CLI reference +- **[Configuration](configuration.md)** - Config files, environment variables, and settings +- **[Themes](themes.md)** - Available themes, customization, and examples + +## 🔧 Developer Documentation + +- **[Development](development.md)** - Development setup, testing, and contribution guide +- **[Security](security.md)** - Security practices, vulnerability reporting, and policies +- **[API Reference](api.md)** - Detailed CLI command reference + +## 🚀 Project Information + +- **[Roadmap](roadmap.md)** - Future plans and strategic initiatives + +## 🤝 Getting Help + +- Check the relevant documentation section above +- Browse the [GitHub Issues](https://github.com/ivuorinen/gh-action-readme/issues) +- See the main [README.md](../README.md) for quick start information + +--- + +For the latest updates and announcements, see the [CHANGELOG.md](../CHANGELOG.md). diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..ebdb82d --- /dev/null +++ b/docs/api.md @@ -0,0 +1,507 @@ +# API Reference + +Complete command-line interface reference for gh-action-readme. + +## 📋 Command Overview + +```bash +gh-action-readme [command] [flags] +``` + +### Available Commands + +- **`gen`** - Generate documentation from action.yml files +- **`validate`** - Validate action.yml files with suggestions +- **`config`** - Configuration management commands +- **`version`** - Show version information +- **`help`** - Help about any command + +## 🚀 Generation Command + +### Basic Syntax + +```bash +gh-action-readme gen [directory_or_file] [flags] +``` + +### Arguments + +- **`[directory_or_file]`** - Optional path to action.yml file or directory containing one + - If omitted, searches current directory for `action.yml` or `action.yaml` + - Supports both files and directories + - Examples: `action.yml`, `./actions/checkout/`, `/path/to/action/` + +### Flags + +#### Output Options + +| Flag | Short | Type | Default | Description | +|------|-------|------|---------|-------------| +| `--output-format` | `-f` | string | `md` | Output format: md, html, json, asciidoc | +| `--output-dir` | `-o` | string | `.` | Output directory for generated files | +| `--output` | | string | | Custom output filename (overrides default naming) | + +#### Theme Options + +| Flag | Short | Type | Default | Description | +|------|-------|------|---------|-------------| +| `--theme` | `-t` | string | `default` | Theme: github, gitlab, minimal, professional, default | + +#### Processing Options + +| Flag | Short | Type | Default | Description | +|------|-------|------|---------|-------------| +| `--recursive` | `-r` | boolean | `false` | Search directories recursively for action.yml files | +| `--quiet` | `-q` | boolean | `false` | Suppress progress output | +| `--verbose` | `-v` | boolean | `false` | Enable verbose logging | + +#### GitHub Integration + +| Flag | Short | Type | Default | Description | +|------|-------|------|---------|-------------| +| `--github-token` | | string | | GitHub personal access token (or use GITHUB_TOKEN env) | +| `--no-dependencies` | | boolean | `false` | Disable dependency analysis | + +### Examples + +#### Basic Generation + +```bash +# Generate with default settings +gh-action-readme gen + +# Generate from specific file +gh-action-readme gen action.yml + +# Generate from directory +gh-action-readme gen ./actions/checkout/ +``` + +#### Output Formats + +```bash +# Markdown (default) +gh-action-readme gen --output-format md + +# HTML documentation +gh-action-readme gen --output-format html + +# JSON metadata +gh-action-readme gen --output-format json + +# AsciiDoc format +gh-action-readme gen --output-format asciidoc +``` + +#### Custom Output + +```bash +# Custom filename +gh-action-readme gen --output custom-readme.md + +# Custom directory +gh-action-readme gen --output-dir docs/ + +# Both custom directory and filename +gh-action-readme gen --output-dir docs/ --output action-guide.html +``` + +#### Themes + +```bash +# GitHub marketplace theme +gh-action-readme gen --theme github + +# GitLab CI/CD theme +gh-action-readme gen --theme gitlab + +# Clean minimal theme +gh-action-readme gen --theme minimal + +# Comprehensive professional theme +gh-action-readme gen --theme professional +``` + +#### Advanced Options + +```bash +# Recursive processing +gh-action-readme gen --recursive --theme github + +# With GitHub token for enhanced features +gh-action-readme gen --github-token ghp_xxxx --verbose + +# Quiet mode for scripts +gh-action-readme gen --theme github --quiet +``` + +## ✅ Validation Command + +### Basic Syntax + +```bash +gh-action-readme validate [file_or_directory] [flags] +``` + +### Arguments + +- **`[file_or_directory]`** - Optional path to validate + - If omitted, validates current directory + - Supports both files and directories + +### Flags + +| Flag | Short | Type | Default | Description | +|------|-------|------|---------|-------------| +| `--verbose` | `-v` | boolean | `false` | Show detailed validation messages | +| `--quiet` | `-q` | boolean | `false` | Only show errors, suppress warnings | +| `--recursive` | `-r` | boolean | `false` | Validate recursively | + +### Examples + +```bash +# Validate current directory +gh-action-readme validate + +# Validate specific file +gh-action-readme validate action.yml + +# Verbose validation with suggestions +gh-action-readme validate --verbose + +# Recursive validation +gh-action-readme validate --recursive ./actions/ +``` + +### Validation Output + +```text +✅ action.yml is valid +⚠️ Warning: Missing 'branding' section for marketplace visibility +💡 Consider adding: + branding: + icon: 'activity' + color: 'blue' + +❌ Error: Missing required field 'description' +💡 Add: description: "Brief description of what your action does" +``` + +## ⚙️ Configuration Commands + +### Basic Syntax + +```bash +gh-action-readme config [subcommand] [flags] +``` + +### Subcommands + +#### `init` - Initialize Configuration + +```bash +gh-action-readme config init [flags] +``` + +**Flags:** + +- `--force` - Overwrite existing configuration +- `--global` - Create global configuration (default: user-specific) + +#### `show` - Display Configuration + +```bash +gh-action-readme config show [key] [flags] +``` + +**Examples:** + +```bash +# Show all configuration +gh-action-readme config show + +# Show specific key +gh-action-readme config show theme + +# Show with file paths +gh-action-readme config show --paths +``` + +#### `themes` - List Available Themes + +```bash +gh-action-readme config themes +``` + +**Output:** + +```text +Available themes: + github GitHub marketplace optimized theme + gitlab GitLab CI/CD focused theme + minimal Clean, minimal documentation + professional Comprehensive enterprise theme + default Original simple theme +``` + +#### `wizard` - Interactive Configuration + +```bash +gh-action-readme config wizard [flags] +``` + +**Flags:** + +- `--format` - Export format: yaml (default), json, toml +- `--output` - Output file path +- `--no-github-token` - Skip GitHub token setup + +**Example:** + +```bash +gh-action-readme config wizard --format json --output config.json +``` + +#### `set` - Set Configuration Value + +```bash +gh-action-readme config set +``` + +**Examples:** + +```bash +gh-action-readme config set theme github +gh-action-readme config set verbose true +gh-action-readme config set output_format html +``` + +#### `get` - Get Configuration Value + +```bash +gh-action-readme config get +``` + +#### `reset` - Reset Configuration + +```bash +gh-action-readme config reset [key] +``` + +**Examples:** + +```bash +# Reset all configuration +gh-action-readme config reset + +# Reset specific key +gh-action-readme config reset theme +``` + +## ℹ️ Information Commands + +### Version Command + +```bash +gh-action-readme version [flags] +``` + +**Flags:** + +- `--short` - Show version number only +- `--json` - Output in JSON format + +**Output:** + +```text +gh-action-readme version 1.2.0 +Built: 2025-08-07T10:30:00Z +Commit: a1b2c3d +Go: go1.24.4 +Platform: linux/amd64 +``` + +### Help Command + +```bash +gh-action-readme help [command] +``` + +**Examples:** + +```bash +# General help +gh-action-readme help + +# Command-specific help +gh-action-readme help gen +gh-action-readme help config wizard +``` + +## 🌍 Global Flags + +These flags are available for all commands: + +| Flag | Short | Type | Default | Description | +|------|-------|------|---------|-------------| +| `--config` | | string | | Custom configuration file path | +| `--help` | `-h` | boolean | `false` | Show help for command | +| `--quiet` | `-q` | boolean | `false` | Suppress non-error output | +| `--verbose` | `-v` | boolean | `false` | Enable verbose logging | + +## 📊 Exit Codes + +| Code | Description | +|------|-------------| +| `0` | Success | +| `1` | General error | +| `2` | Invalid arguments | +| `3` | File not found | +| `4` | Validation failed | +| `5` | Configuration error | +| `6` | GitHub API error | +| `7` | Template error | + +## 🔧 Environment Variables + +### Configuration Override + +- `GH_ACTION_README_THEME` - Default theme +- `GH_ACTION_README_OUTPUT_FORMAT` - Default output format +- `GH_ACTION_README_OUTPUT_DIR` - Default output directory +- `GH_ACTION_README_VERBOSE` - Enable verbose mode (true/false) +- `GH_ACTION_README_QUIET` - Enable quiet mode (true/false) + +### GitHub Integration + +- `GITHUB_TOKEN` - GitHub personal access token +- `GH_ACTION_README_NO_DEPENDENCIES` - Disable dependency analysis + +### Advanced Options + +- `GH_ACTION_README_CONFIG` - Custom configuration file path +- `GH_ACTION_README_CACHE_TTL` - Cache TTL in seconds +- `GH_ACTION_README_TIMEOUT` - Request timeout in seconds + +## 🎯 Advanced Usage Patterns + +### Batch Processing + +```bash +# Process multiple actions with custom themes +for dir in actions/*/; do + gh-action-readme gen "$dir" --theme github --output "$dir/README.md" +done + +# Generate docs for all formats +for format in md html json asciidoc; do + gh-action-readme gen --output-format "$format" --output "docs/action.$format" +done +``` + +### CI/CD Integration + +```bash +# GitHub Actions workflow +- name: Generate Action Documentation + run: | + gh-action-readme gen --theme github --output README.md + git add README.md + git commit -m "docs: update action documentation" || exit 0 + +# GitLab CI +generate_docs: + script: + - gh-action-readme gen --theme gitlab --output-format html --output docs/ + artifacts: + paths: + - docs/ +``` + +### Conditional Processing + +```bash +#!/bin/bash +# Smart theme selection based on repository +if [[ -f ".gitlab-ci.yml" ]]; then + THEME="gitlab" +elif [[ -f "package.json" ]]; then + THEME="github" +else + THEME="minimal" +fi + +gh-action-readme gen --theme "$THEME" --verbose +``` + +### Error Handling + +```bash +#!/bin/bash +set -e + +# Generate with error handling +if gh-action-readme gen --theme github --quiet; then + echo "✅ Documentation generated successfully" +else + exit_code=$? + echo "❌ Documentation generation failed (exit code: $exit_code)" + + case $exit_code in + 3) echo "💡 Make sure action.yml exists in the current directory" ;; + 4) echo "💡 Run 'gh-action-readme validate' to check for issues" ;; + 6) echo "💡 Check your GitHub token and network connection" ;; + *) echo "💡 Run with --verbose flag for more details" ;; + esac + + exit $exit_code +fi +``` + +## 🔍 Debugging & Troubleshooting + +### Debug Output + +```bash +# Maximum verbosity +gh-action-readme gen --verbose + +# Configuration debugging +gh-action-readme config show --debug + +# Validation debugging +gh-action-readme validate --verbose +``` + +### Common Issues + +**Command not found:** + +```bash +# Check installation +which gh-action-readme +gh-action-readme version +``` + +**Permission denied:** + +```bash +# Check file permissions +ls -la action.yml +chmod 644 action.yml +``` + +**GitHub API rate limit:** + +```bash +# Use GitHub token +export GITHUB_TOKEN=your_token_here +gh-action-readme gen --verbose +``` + +**Template errors:** + +```bash +# Validate action.yml first +gh-action-readme validate --verbose +``` diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..0b24064 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,330 @@ +# Configuration + +Configure gh-action-readme with persistent settings, environment variables, and advanced options. + +## 📁 Configuration File + +Create persistent settings with XDG-compliant configuration: + +```bash +gh-action-readme config init +``` + +### Default Location + +- **Linux/macOS**: `~/.config/gh-action-readme/config.yaml` +- **Windows**: `%APPDATA%\gh-action-readme\config.yaml` + +### Configuration Format + +```yaml +# ~/.config/gh-action-readme/config.yaml +theme: github +output_format: md +output_dir: . +verbose: false +github_token: "" +dependencies_enabled: true +cache_ttl: 3600 +``` + +## 🔧 Configuration Options + +### Core Settings + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `theme` | string | `default` | Default theme to use | +| `output_format` | string | `md` | Default output format | +| `output_dir` | string | `.` | Default output directory | +| `verbose` | boolean | `false` | Enable verbose logging | + +### GitHub Integration + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `github_token` | string | `""` | GitHub personal access token | +| `dependencies_enabled` | boolean | `true` | Enable dependency analysis | +| `rate_limit_delay` | int | `1000` | Delay between API calls (ms) | + +### Performance Settings + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `cache_ttl` | int | `3600` | Cache TTL in seconds | +| `concurrent_requests` | int | `3` | Max concurrent GitHub API requests | +| `timeout` | int | `30` | Request timeout in seconds | + +## 🌍 Environment Variables + +Override configuration with environment variables: + +```bash +# Core settings +export GH_ACTION_README_THEME=github +export GH_ACTION_README_OUTPUT_FORMAT=html +export GH_ACTION_README_OUTPUT_DIR=docs +export GH_ACTION_README_VERBOSE=true + +# GitHub settings +export GITHUB_TOKEN=your_token_here +export GH_ACTION_README_DEPENDENCIES=true + +# Performance settings +export GH_ACTION_README_CACHE_TTL=7200 +export GH_ACTION_README_TIMEOUT=60 +``` + +### Environment Variable Priority + +1. Command line flags (highest priority) +2. Environment variables +3. Configuration file +4. Built-in defaults (lowest priority) + +## 🎛️ Interactive Configuration + +Use the interactive wizard for guided setup: + +```bash +gh-action-readme config wizard +``` + +### Wizard Features + +- **Auto-detection** of project settings +- **GitHub token** setup with validation +- **Theme preview** with examples +- **Export options** (YAML, JSON, TOML) +- **Real-time validation** with suggestions + +### Wizard Example + +```bash +$ gh-action-readme config wizard + +✨ Welcome to gh-action-readme configuration wizard! + +🔍 Detected project settings: + Repository: ivuorinen/my-action + Language: JavaScript/TypeScript + +📋 Select your preferences: + Theme: github, gitlab, minimal, professional, default + >> github + + Output format: md, html, json, asciidoc + >> md + +🔑 GitHub Token (optional, for enhanced features): + >> ghp_xxxxxxxxxxxx + ✅ Token validated successfully! + +💾 Export configuration as: + Format: yaml, json, toml + >> yaml + +✅ Configuration saved to ~/.config/gh-action-readme/config.yaml +``` + +## 🎨 Theme Configuration + +### Built-in Themes + +```bash +# List available themes +gh-action-readme config themes + +# Set default theme +gh-action-readme config set theme github +``` + +### Custom Themes + +Create custom themes by copying existing ones: + +```bash +# Copy existing theme +cp -r templates/themes/github templates/themes/custom + +# Edit template +vim templates/themes/custom/readme.tmpl + +# Use custom theme +gh-action-readme gen --theme custom +``` + +### Theme Directory Structure + +```text +templates/themes/your-theme/ +├── readme.tmpl # Main template +├── partials/ # Optional partial templates +│ ├── header.tmpl +│ ├── inputs.tmpl +│ └── examples.tmpl +└── assets/ # Optional theme assets + ├── styles.css + └── logo.png +``` + +## 🔐 GitHub Token Configuration + +### Creating a Token + +1. Go to GitHub Settings → Developer settings → Personal access tokens +2. Generate new token with `public_repo` scope +3. Copy token and save securely + +### Setting Token + +```bash +# Environment variable (recommended) +export GITHUB_TOKEN=your_token_here + +# Configuration file +gh-action-readme config set github_token your_token_here + +# Command line (least secure) +gh-action-readme gen --github-token your_token_here +``` + +### Token Benefits + +- **Higher rate limits** (5000 requests/hour vs 60) +- **Dependency analysis** with detailed metadata +- **Private repository** access +- **Enhanced error messages** for API issues + +## 📊 Cache Configuration + +### Cache Settings + +```yaml +# Cache configuration +cache_enabled: true +cache_dir: ~/.cache/gh-action-readme +cache_ttl: 3600 # 1 hour in seconds +cache_max_size: 100 # MB +``` + +### Cache Management + +```bash +# Clear cache +gh-action-readme config clear-cache + +# Check cache status +gh-action-readme config cache-status + +# Set cache TTL +gh-action-readme config set cache_ttl 7200 # 2 hours +``` + +## 🔧 Advanced Configuration + +### Custom Output Templates + +```yaml +# Custom output naming patterns +output_patterns: + md: "${name}-README.md" + html: "docs/${name}.html" + json: "api/${name}-metadata.json" +``` + +### Validation Rules + +```yaml +# Custom validation settings +validation: + require_description: true + require_examples: false + max_input_count: 50 + enforce_semver: true +``` + +### Template Variables + +```yaml +# Custom template variables +template_vars: + organization: "my-org" + support_email: "support@example.com" + docs_url: "https://docs.example.com" +``` + +## 📝 Configuration Commands + +### View Configuration + +```bash +# Show current config +gh-action-readme config show + +# Show specific setting +gh-action-readme config get theme +``` + +### Update Configuration + +```bash +# Set individual values +gh-action-readme config set theme professional +gh-action-readme config set verbose true + +# Reset to defaults +gh-action-readme config reset + +# Remove config file +gh-action-readme config delete +``` + +### Export/Import Configuration + +```bash +# Export current config +gh-action-readme config export --format json > config.json + +# Import configuration +gh-action-readme config import config.json + +# Merge configurations +gh-action-readme config merge other-config.yaml +``` + +## 🔍 Debugging Configuration + +### Verbose Mode + +```bash +# Enable verbose output +gh-action-readme gen --verbose + +# Set in config +gh-action-readme config set verbose true +``` + +### Configuration Validation + +```bash +# Validate current configuration +gh-action-readme config validate + +# Test configuration with dry run +gh-action-readme gen --dry-run --verbose +``` + +### Troubleshooting + +```bash +# Show effective configuration (merged from all sources) +gh-action-readme config effective + +# Show configuration file locations +gh-action-readme config paths + +# Reset corrupted configuration +rm ~/.config/gh-action-readme/config.yaml +gh-action-readme config init +``` diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..a92965f --- /dev/null +++ b/docs/development.md @@ -0,0 +1,447 @@ +# Development Guide + +Comprehensive guide for developing and contributing to gh-action-readme. + +## 🚨 CRITICAL: README Protection + +**NEVER overwrite `/README.md`** - The root README.md is the main project documentation. + +**For testing generation commands:** + +```bash +# New enhanced targeting (recommended) +gh-action-readme gen testdata/example-action/ +gh-action-readme gen testdata/composite-action/action.yml + +# Traditional method (still supported) +cd testdata/ +../gh-action-readme gen [options] +``` + +## 🛠️ Development Setup + +### Prerequisites + +- **Go 1.24+** (required) +- **golangci-lint** (for linting) +- **pre-commit** (for git hooks) +- **Docker** (optional, for containerized testing) + +### Quick Start + +```bash +# Clone repository +git clone https://github.com/ivuorinen/gh-action-readme.git +cd gh-action-readme + +# Install development tools +make devtools + +# Install pre-commit hooks +make pre-commit-install + +# Build and test +make build +make test +make lint +``` + +## 🏗️ Architecture + +### Core Components + +- **`main.go`** - CLI with Cobra framework, enhanced gen command +- **`internal/generator.go`** - Core generation logic with custom output paths +- **`internal/config.go`** - Viper configuration (XDG compliant) +- **`internal/output.go`** - Colored terminal output with progress bars +- **`internal/errors/`** - Contextual error handling with suggestions +- **`internal/wizard/`** - Interactive configuration wizard +- **`internal/progress.go`** - Progress indicators for batch operations + +### Template System + +- **`templates/readme.tmpl`** - Default template +- **`templates/themes/`** - Theme-specific templates + - `github/` - GitHub-style with badges + - `gitlab/` - GitLab CI/CD focused + - `minimal/` - Clean, concise + - `professional/` - Comprehensive with ToC + - `asciidoc/` - AsciiDoc format + +### Testing Framework + +- **`testutil/`** - Comprehensive testing utilities +- **`testdata/`** - Test fixtures and sample actions +- **Table-driven tests** - Consistent testing patterns +- **Mock implementations** - Isolated unit tests + +## 🧪 Testing Strategy + +### Running Tests + +```bash +# All tests +make test + +# With coverage +make test-coverage + +# Specific package +go test ./internal/generator + +# Verbose output +go test -v ./... + +# Race condition detection +go test -race ./... +``` + +### Test Types + +**Unit Tests** (`*_test.go`): + +```bash +go test ./internal # Core logic tests +go test ./testutil # Test framework tests +``` + +**Integration Tests** (`*_integration_test.go`): + +```bash +go test -tags=integration ./... +``` + +**Comprehensive Tests** (`comprehensive_test.go`): + +```bash +go test ./internal -run Comprehensive +``` + +### Testing Best Practices + +1. **Use testutil framework** for consistent test patterns +2. **Table-driven tests** for multiple scenarios +3. **Mock external dependencies** (GitHub API, filesystem) +4. **Test error conditions** and edge cases +5. **Verify thread safety** with race detection + +### Test Coverage + +Current coverage: **51.2%** overall + +- **Cache module**: 91.4% +- **Errors module**: 91.5% +- **Git detector**: 78.4% +- **Validation**: 76.2% + +Target: **>80%** coverage for all new code + +## 🔧 Build System + +### Makefile Targets + +```bash +# Building +make build # Build binary +make clean # Clean build artifacts + +# Testing +make test # Run all tests +make test-coverage # Run tests with coverage +make lint # Run all linters + +# Development +make devtools # Install dev tools +make format # Format code +make pre-commit-install # Install git hooks + +# Security +make security # Run security scans +make vulncheck # Go vulnerability check + +# Dependencies +make deps-check # Check outdated dependencies +make deps-update # Interactive dependency updates +``` + +### Build Configuration + +```bash +# Build with version info +go build -ldflags "-X main.version=v1.0.0 -X main.commit=$(git rev-parse HEAD)" + +# Cross-platform builds (handled by GoReleaser) +GOOS=linux GOARCH=amd64 go build +GOOS=darwin GOARCH=arm64 go build +GOOS=windows GOARCH=amd64 go build +``` + +## 📝 Code Style & Quality + +### Linting Configuration + +- **golangci-lint** with 35+ enabled linters +- **EditorConfig** compliance required +- **Pre-commit hooks** for automated checking +- **Zero linting violations** policy + +### Code Quality Standards + +- ✅ **Cyclomatic complexity** <10 for all functions +- ✅ **Test coverage** >80% for critical modules +- ✅ **Error handling** for all possible errors +- ✅ **Documentation** for all exported functions +- ✅ **Thread safety** for concurrent operations + +### Formatting Rules + +```bash +# Auto-format code +make format + +# Check formatting +gofmt -d . +goimports -d . +``` + +## 🔄 Adding New Features + +### New Theme + +1. Create `templates/themes/THEME_NAME/readme.tmpl` +2. Add to `resolveThemeTemplate()` in `config.go` +3. Update `configThemesHandler()` in `main.go` +4. Add tests and documentation + +### New Output Format + +1. Add constant to `generator.go` +2. Add case to `GenerateFromFile()` switch +3. Implement `generate[FORMAT]()` method +4. Update CLI help and documentation + +### New CLI Command + +1. Add command in `main.go` using Cobra +2. Implement handler function +3. Add flags and validation +4. Write tests and update documentation + +### New Template Functions + +Add to `templateFuncs()` in `internal/template.go`: + +```go +"myFunction": func(input string) string { + // Implementation + return processed +}, +``` + +## 🚀 Performance Optimization + +### Profiling + +```bash +# CPU profiling +go test -cpuprofile=cpu.prof -bench=. +go tool pprof cpu.prof + +# Memory profiling +go test -memprofile=mem.prof -bench=. +go tool pprof mem.prof + +# Benchmark testing +go test -bench=. -benchmem +``` + +### Performance Guidelines + +- **Use sync.Pool** for frequently allocated objects +- **Implement caching** for expensive operations +- **Minimize memory allocations** in hot paths +- **Concurrent processing** for I/O bound operations +- **Profile before optimizing** + +## 🔐 Security Practices + +### Security Scanning + +```bash +make security # Run all scans +make vulncheck # Go vulnerabilities +make trivy # Filesystem scan +make gitleaks # Secrets detection +``` + +### Secure Coding + +- **Validate all inputs** especially user-provided data +- **Use secure defaults** for all configurations +- **Sanitize file paths** to prevent directory traversal +- **Handle secrets safely** never log or expose tokens +- **Regular dependency updates** with security patches + +### GitHub Token Handling + +```go +// ❌ Wrong - logging token +log.Printf("Using token: %s", token) + +// ✅ Correct - masking sensitive data +log.Printf("Using token: %s", maskToken(token)) + +func maskToken(token string) string { + if len(token) < 8 { + return "***" + } + return token[:4] + "***" + token[len(token)-4:] +} +``` + +## 📚 Documentation + +### Documentation Standards + +- **godoc comments** for all exported functions +- **README updates** for user-facing changes +- **CHANGELOG entries** following Keep a Changelog format +- **Architecture Decision Records** for significant changes + +### Writing Guidelines + +```go +// Package generator provides core documentation generation functionality. +// +// The generator processes GitHub Action YAML files and produces formatted +// documentation in multiple output formats (Markdown, HTML, JSON, AsciiDoc). +package generator + +// GenerateReadme creates formatted documentation from an ActionYML struct. +// +// The function applies the specified theme and output format to generate +// comprehensive documentation including input/output tables, usage examples, +// and metadata sections. +// +// Parameters: +// - action: Parsed action.yml data structure +// - theme: Template theme name (github, gitlab, minimal, professional, default) +// - format: Output format (md, html, json, asciidoc) +// +// Returns formatted documentation string and any processing error. +func GenerateReadme(action *ActionYML, theme, format string) (string, error) { + // Implementation... +} +``` + +## 🤝 Contributing Guidelines + +### Contribution Process + +1. **Fork repository** and create feature branch +2. **Make changes** following code style guidelines +3. **Add tests** for new functionality +4. **Update documentation** as needed +5. **Run quality checks** (`make test lint`) +6. **Submit pull request** with clear description + +### Pull Request Guidelines + +- **Clear title** describing the change +- **Detailed description** of what and why +- **Link related issues** if applicable +- **Include tests** for new features +- **Update documentation** for user-facing changes +- **Ensure CI passes** all quality checks + +### Code Review Process + +- **Two approvals** required for merging +- **All checks must pass** (tests, linting, security) +- **Documentation review** for user-facing changes +- **Performance impact** assessment for core changes + +## 🐛 Debugging + +### Debug Mode + +```bash +# Enable verbose output +gh-action-readme gen --verbose + +# Debug configuration +gh-action-readme config show --debug + +# Trace execution +TRACE=1 gh-action-readme gen +``` + +### Common Issues + +**Template Errors:** + +```bash +# Validate action.yml syntax +gh-action-readme validate --verbose + +# Check template syntax +gh-action-readme gen --dry-run --verbose +``` + +**GitHub API Issues:** + +```bash +# Check rate limits +curl -H "Authorization: token $GITHUB_TOKEN" \ + https://api.github.com/rate_limit + +# Test API access +gh-action-readme gen --verbose --github-token $GITHUB_TOKEN +``` + +**Build Issues:** + +```bash +# Clean and rebuild +make clean +make build + +# Check dependencies +go mod verify +go mod tidy +``` + +## 📊 Metrics & Monitoring + +### Performance Metrics + +- **Generation time** per action +- **GitHub API** request count and timing +- **Memory usage** during processing +- **Cache hit rates** for repeated operations + +### Quality Metrics + +- **Test coverage** percentage +- **Linting violations** count +- **Security vulnerabilities** detected +- **Documentation coverage** for public APIs + +### Tracking Tools + +```bash +# Performance benchmarks +go test -bench=. -benchmem ./... + +# Memory profiling +go test -memprofile=mem.prof ./... + +# Coverage reporting +go test -coverprofile=coverage.out ./... +go tool cover -html=coverage.out +``` + +--- + +**Status**: ENTERPRISE READY ✅ +*Enhanced gen command, thread-safety, comprehensive testing, and enterprise features fully implemented.* diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..531a21e --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,149 @@ +# Installation + +Multiple installation options are available for gh-action-readme. + +## 📦 Binary Releases (Recommended) + +Download pre-built binaries for your platform from the [latest release](https://github.com/ivuorinen/gh-action-readme/releases/latest). + +### Linux x86_64 + +```bash +curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Linux_x86_64.tar.gz | tar -xz +sudo mv gh-action-readme /usr/local/bin/ +``` + +### macOS x86_64 (Intel) + +```bash +curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_x86_64.tar.gz | tar -xz +sudo mv gh-action-readme /usr/local/bin/ +``` + +### macOS ARM64 (Apple Silicon) + +```bash +curl -L https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Darwin_arm64.tar.gz | tar -xz +sudo mv gh-action-readme /usr/local/bin/ +``` + +### Windows x86_64 + +```powershell +# PowerShell +Invoke-WebRequest -Uri "https://github.com/ivuorinen/gh-action-readme/releases/latest/download/gh-action-readme_Windows_x86_64.zip" -OutFile "gh-action-readme.zip" +Expand-Archive gh-action-readme.zip +``` + +## 🍺 Package Managers + +### Homebrew (macOS/Linux) + +```bash +brew install ivuorinen/tap/gh-action-readme +``` + +### Scoop (Windows) + +```powershell +scoop bucket add ivuorinen https://github.com/ivuorinen/scoop-bucket.git +scoop install gh-action-readme +``` + +### Go Install + +```bash +go install github.com/ivuorinen/gh-action-readme@latest +``` + +## 🐳 Docker + +Run directly from Docker without installation: + +```bash +# Latest release +docker run --rm -v $(pwd):/workspace ghcr.io/ivuorinen/gh-action-readme:latest gen + +# Specific version +docker run --rm -v $(pwd):/workspace ghcr.io/ivuorinen/gh-action-readme:v1.0.0 gen +``` + +### Docker Compose + +```yaml +version: '3.8' +services: + gh-action-readme: + image: ghcr.io/ivuorinen/gh-action-readme:latest + volumes: + - .:/workspace + working_dir: /workspace +``` + +## 🔧 From Source + +### Prerequisites + +- Go 1.24+ +- Git + +### Build + +```bash +git clone https://github.com/ivuorinen/gh-action-readme.git +cd gh-action-readme +make build +``` + +### Install System-wide + +```bash +sudo cp gh-action-readme /usr/local/bin/ +``` + +## ✅ Verify Installation + +```bash +gh-action-readme version +gh-action-readme --help +``` + +## 🔄 Updates + +### Binary/Package Manager + +- **Homebrew**: `brew upgrade gh-action-readme` +- **Scoop**: `scoop update gh-action-readme` +- **Manual**: Download new binary and replace existing + +### Docker + +```bash +docker pull ghcr.io/ivuorinen/gh-action-readme:latest +``` + +### Go Install + +```bash +go install github.com/ivuorinen/gh-action-readme@latest +``` + +## 🚫 Uninstall + +### Binary Installation + +```bash +sudo rm /usr/local/bin/gh-action-readme +``` + +### Package Managers + +- **Homebrew**: `brew uninstall gh-action-readme` +- **Scoop**: `scoop uninstall gh-action-readme` + +### Configuration Files + +```bash +# Remove user configuration (optional) +rm -rf ~/.config/gh-action-readme/ +``` diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..d20e609 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,156 @@ +# Roadmap + +Strategic roadmap for gh-action-readme development and future enhancements. + +## 🎯 Project Status + +- **Current Quality**: A+ Excellent +- **Target**: Industry-Leading Reference +- **Last Major Update**: August 6, 2025 (Gen Command Enhancement & Final Polish) + +## ✅ Recently Completed (August 2025) + +### Enhanced Gen Command & Thread Safety + +- **Directory/File Targeting**: Support for `gen testdata/example-action/` syntax +- **Custom Output Filenames**: `--output custom-name.html` flag +- **Thread Safety**: RWMutex implementation for race condition protection +- **CI/CD Integration**: Enhanced GitHub Actions workflow + +### Code Quality & Security + +- **Zero Linting Violations**: Complete golangci-lint compliance +- **EditorConfig Compliance**: Consistent formatting across codebase +- **Security Hardening**: Integrated govulncheck, Trivy, gitleaks, CodeQL +- **Dependency Updates**: Latest Go 1.24, security patches applied + +### Developer Experience + +- **Contextual Error Handling**: 14 error codes with actionable suggestions +- **Interactive Wizard**: Step-by-step project configuration +- **Progress Indicators**: Visual feedback for long operations +- **Enhanced Documentation**: Comprehensive guides and examples + +## 🚀 High Priority (Next 6 months) + +### Performance Optimization + +- **Concurrent GitHub API Processing**: 5-10x faster dependency analysis +- **GraphQL Migration**: Reduce API calls by 70-80% +- **Memory Optimization**: Implement pooling for large-scale operations +- **Benchmark Testing**: Performance regression detection + +### Advanced Features + +- **Plugin System**: Extensible architecture for custom functionality +- **Multi-Repository Batch Processing**: Enterprise-scale operations +- **Vulnerability Scanning**: Security analysis integration +- **Advanced Analytics**: Usage patterns and optimization insights + +## 💡 Medium Priority (6-12 months) + +### Quality Assurance + +- **Property-Based Testing**: Edge case discovery with automated test generation +- **Mutation Testing**: Test suite quality validation +- **Interface Abstractions**: Better testability and dependency injection +- **Event-Driven Architecture**: Improved observability and extensibility + +### Developer Tools + +- **API Documentation**: Comprehensive godoc coverage +- **Configuration Validation**: JSON schema-based validation +- **VS Code Extension**: IDE integration +- **IntelliJ Plugin**: JetBrains IDE support + +## 🌟 Strategic Initiatives (12+ months) + +### Enterprise Features + +- **Web Dashboard**: Team collaboration and centralized management +- **API Server Mode**: RESTful API for CI/CD integration +- **Cloud Service Integration**: AWS, Azure, Google Cloud support +- **Docker Hub Integration**: Automated documentation for containers + +### Innovation + +- **AI-Powered Suggestions**: ML-based template and configuration recommendations +- **Integration Ecosystem**: GitHub Apps, GitLab CI/CD, Jenkins plugins +- **Advanced Template Engine**: More powerful customization capabilities +- **Registry Integration**: npm, PyPI, Docker Hub documentation automation + +## 📊 Success Metrics + +### Performance Targets + +- **50% improvement** in processing speed +- **Zero high-severity** vulnerabilities +- **90% reduction** in configuration errors +- **>95% test coverage** for all new features + +### Adoption Goals + +- **10x increase** in GitHub stars and downloads +- **Active plugin ecosystem** with 5+ community plugins +- **Enterprise adoption** by major organizations +- **Community contributions** from 50+ contributors + +## 🛠️ Implementation Guidelines + +### Development Process + +1. **Design documents** for medium+ complexity features +2. **Test-driven development** with comprehensive coverage +3. **Semantic versioning** for all releases +4. **Backward compatibility** with migration paths +5. **Security-first** development practices + +### Quality Gates + +- **Code Coverage**: >80% for all new code +- **Security Scanning**: Pass all SAST and dependency scans +- **Performance**: No regression in benchmark tests +- **Documentation**: Complete coverage for public APIs + +## 🤝 Community Involvement + +### Contribution Areas + +- **Theme Development**: New visual themes and templates +- **Plugin Creation**: Extending core functionality +- **Integration Development**: CI/CD and tool integrations +- **Documentation**: Guides, tutorials, and examples +- **Testing**: Edge cases and platform coverage + +### Maintainer Support + +- **Code Reviews**: Expert feedback on contributions +- **Mentorship**: Guidance for new contributors +- **Feature Requests**: Community-driven roadmap input +- **Bug Reports**: Rapid response and resolution + +## 📈 Long-term Vision + +Transform gh-action-readme into the **definitive tooling solution** for GitHub Actions documentation, with: + +- **Universal Adoption**: Standard tool for action developers +- **Enterprise Integration**: Built into major CI/CD platforms +- **AI Enhancement**: Intelligent documentation generation +- **Community Ecosystem**: Thriving plugin and theme marketplace +- **Industry Leadership**: Setting standards for action tooling + +## 🔄 Roadmap Updates + +This roadmap is reviewed and updated quarterly based on: + +- Community feedback and feature requests +- Technology evolution and new capabilities +- Performance metrics and user analytics +- Strategic partnerships and integrations +- Security landscape and compliance requirements + +--- + +**Next Review**: November 2025 +**Current Focus**: Performance optimization and enterprise features +**Community Input**: [GitHub Discussions](https://github.com/ivuorinen/gh-action-readme/discussions) diff --git a/SECURITY.md b/docs/security.md similarity index 95% rename from SECURITY.md rename to docs/security.md index b62050e..31b06fc 100644 --- a/SECURITY.md +++ b/docs/security.md @@ -17,10 +17,11 @@ We take security vulnerabilities seriously. If you discover a security issue in 1. **Do NOT create a public GitHub issue** for security vulnerabilities 2. Send an email to [security@ivuorinen.dev](mailto:security@ivuorinen.dev) with: - - Description of the vulnerability - - Steps to reproduce the issue - - Potential impact assessment - - Any suggested fixes (if available) + +- Description of the vulnerability +- Steps to reproduce the issue +- Potential impact assessment +- Any suggested fixes (if available) ### What to Expect @@ -36,7 +37,6 @@ We take security vulnerabilities seriously. If you discover a security issue in We employ multiple layers of automated security scanning: - **govulncheck**: Go-specific vulnerability scanning -- **Snyk**: Dependency vulnerability analysis - **Trivy**: Container and filesystem security scanning - **gitleaks**: Secrets detection and prevention - **CodeQL**: Static code analysis @@ -106,7 +106,6 @@ make security # Individual scans make vulncheck # Go vulnerability check -make snyk # Dependency analysis make trivy # Filesystem scanning make gitleaks # Secrets detection @@ -144,7 +143,6 @@ Our GitHub Actions workflows automatically run: ```bash # Install security tools go install golang.org/x/vuln/cmd/govulncheck@latest -npm install -g snyk # Install trivy: https://aquasecurity.github.io/trivy/ # Install gitleaks: https://github.com/gitleaks/gitleaks diff --git a/docs/themes.md b/docs/themes.md new file mode 100644 index 0000000..0472e12 --- /dev/null +++ b/docs/themes.md @@ -0,0 +1,397 @@ +# Themes + +gh-action-readme includes 5 built-in themes, each optimized for different use cases and visual preferences. + +## 🎨 Available Themes + +### GitHub Theme + +**Best for:** GitHub Marketplace actions, open source projects + +```bash +gh-action-readme gen --theme github +``` + +**Features:** + +- GitHub-style badges and shields +- Collapsible sections for better organization +- Table-based parameter documentation +- Action marketplace optimization +- GitHub-specific styling and layout + +**Example output:** + +- ✅ Professional badges +- 📊 Clean input/output tables +- 🔧 Copy-paste usage examples +- 📁 Collapsible troubleshooting sections + +### GitLab Theme + +**Best for:** GitLab CI/CD integration, GitLab-hosted projects + +```bash +gh-action-readme gen --theme gitlab +``` + +**Features:** + +- GitLab CI/CD pipeline examples +- GitLab-specific badge integration +- Pipeline configuration snippets +- GitLab Pages optimization + +### Minimal Theme + +**Best for:** Simple actions, lightweight documentation + +```bash +gh-action-readme gen --theme minimal +``` + +**Features:** + +- Clean, distraction-free layout +- Essential information only +- Faster loading and parsing +- Mobile-friendly design +- Minimal dependencies + +### Professional Theme + +**Best for:** Enterprise actions, comprehensive documentation + +```bash +gh-action-readme gen --theme professional +``` + +**Features:** + +- Comprehensive table of contents +- Detailed troubleshooting sections +- Advanced usage examples +- Security and compliance notes +- Enterprise-ready formatting + +### Default Theme + +**Best for:** Basic needs, backward compatibility + +```bash +gh-action-readme gen --theme default +``` + +**Features:** + +- Original simple template +- Basic parameter documentation +- Minimal formatting +- Guaranteed compatibility + +## 🎯 Theme Comparison + +| Feature | GitHub | GitLab | Minimal | Professional | Default | +|---------|--------|--------|---------|-------------|---------| +| **Badges** | ✅ Rich | ✅ GitLab | ❌ None | ✅ Comprehensive | ❌ None | +| **TOC** | ✅ Yes | ✅ Yes | ❌ No | ✅ Advanced | ❌ No | +| **Examples** | ✅ GitHub | ✅ CI/CD | ✅ Basic | ✅ Comprehensive | ✅ Basic | +| **Troubleshooting** | ✅ Collapsible | ✅ Pipeline | ❌ Minimal | ✅ Detailed | ❌ None | +| **File Size** | Medium | Medium | Small | Large | Small | +| **Load Time** | Fast | Fast | Fastest | Slower | Fast | + +## 🛠️ Theme Examples + +### Input Action + +```yaml +name: Deploy to AWS +description: Deploy application to AWS using GitHub Actions +inputs: + aws-region: + description: AWS region to deploy to + required: true + default: us-east-1 + environment: + description: Deployment environment + required: false + default: production +outputs: + deployment-url: + description: URL of the deployed application +runs: + using: composite + steps: + - run: echo "Deploying to AWS..." +``` + +### GitHub Theme Output + +```markdown +# Deploy to AWS + +[![GitHub Action](https://img.shields.io/badge/GitHub%20Action-Deploy%20to%20AWS-blue)](https://github.com/marketplace) + +> Deploy application to AWS using GitHub Actions + +## 🚀 Usage + +```yaml +- uses: your-org/deploy-aws@v1 + with: + aws-region: us-west-2 + environment: staging +``` + +
+📋 Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `aws-region` | AWS region to deploy to | Yes | `us-east-1` | +| `environment` | Deployment environment | No | `production` | + +
+``` + +### Minimal Theme Output + +```markdown +# Deploy to AWS + +Deploy application to AWS using GitHub Actions + +## Usage + +```yaml +- uses: your-org/deploy-aws@v1 + with: + aws-region: us-west-2 +``` + +## Inputs + +- `aws-region` (required): AWS region to deploy to +- `environment` (optional): Deployment environment (default: production) + +## Outputs + +- `deployment-url`: URL of the deployed application + +```text + +## 🎨 Custom Themes + +### Creating Custom Themes + +1. **Copy existing theme:** +```bash +cp -r templates/themes/github templates/themes/my-theme +``` + +1. **Edit template files:** + +```bash +# Main template +vim templates/themes/my-theme/readme.tmpl + +# Optional partials +vim templates/themes/my-theme/partials/header.tmpl +``` + +1. **Use custom theme:** + +```bash +gh-action-readme gen --theme my-theme +``` + +### Theme Structure + +```text +templates/themes/my-theme/ +├── readme.tmpl # Main template (required) +├── partials/ # Partial templates (optional) +│ ├── header.tmpl # Header section +│ ├── inputs.tmpl # Inputs table +│ ├── outputs.tmpl # Outputs table +│ ├── examples.tmpl # Usage examples +│ └── footer.tmpl # Footer section +└── assets/ # Theme assets (optional) + ├── styles.css # Custom CSS + └── images/ # Theme images +``` + +### Template Variables + +Available variables in templates: + +```go +type ActionData struct { + Name string // Action name + Description string // Action description + Inputs map[string]ActionInput // Input parameters + Outputs map[string]ActionOutput // Output parameters + Runs map[string]interface{} // Runs configuration + Branding *Branding // Branding info + + // Enhanced data + Repository *Repository // GitHub repo info + Dependencies []Dependency // Analyzed dependencies + Examples []Example // Usage examples +} +``` + +### Template Functions + +Built-in template functions: + +```go +// String functions +{{ .Name | title }} // Title case +{{ .Description | truncate 100 }} // Truncate to 100 chars +{{ .Name | slug }} // URL-friendly slug + +// Formatting functions +{{ .Inputs | toTable }} // Generate input table +{{ .Dependencies | toList }} // Generate dependency list +{{ .Examples | toYAML }} // Format as YAML + +// Conditional functions +{{ if hasInputs }}...{{ end }} // Check if inputs exist +{{ if .Branding }}...{{ end }} // Check if branding exists +``` + +### Advanced Template Example + +```go-template +{{/* Custom theme header */}} +# {{ .Name }} + +{{ if .Branding }} +

+ {{ .Name }} +

+{{ end }} + +> {{ .Description }} + +## 🚀 Quick Start + +```yaml +- uses: {{ .Repository.FullName }}@{{ .Repository.DefaultBranch }} + with: + {{- range $key, $input := .Inputs }} + {{- if $input.Required }} + {{ $key }}: # {{ $input.Description }} + {{- end }} + {{- end }} +``` + +{{ if .Inputs }} + +## 📋 Configuration + +{{ template "inputs-table" . }} +{{ end }} + +{{ if .Dependencies }} + +## 🔗 Dependencies + +This action uses the following dependencies: +{{ range .Dependencies }} + +- [{{ .Name }}]({{ .SourceURL }}) - {{ .Description }} +{{ end }} +{{ end }} + +{{/*Include footer partial if it exists*/}} +{{ template "footer" . }} + +```go-template + +## 🔧 Theme Configuration + +### Set Default Theme +```bash +# Set globally +gh-action-readme config set theme professional + +# Use environment variable +export GH_ACTION_README_THEME=github +``` + +### Theme-Specific Settings + +```yaml +# ~/.config/gh-action-readme/config.yaml +theme: github +theme_settings: + github: + show_badges: true + collapse_sections: true + show_toc: true + minimal: + show_examples: true + compact_tables: true + professional: + detailed_examples: true + show_troubleshooting: true +``` + +### Dynamic Theme Selection + +```bash +# Select theme based on repository type +if [[ -f ".gitlab-ci.yml" ]]; then + gh-action-readme gen --theme gitlab +elif [[ -f "package.json" ]]; then + gh-action-readme gen --theme github +else + gh-action-readme gen --theme minimal +fi +``` + +## 📱 Responsive Design + +All themes support responsive design: + +- **Desktop**: Full-width tables and detailed sections +- **Tablet**: Condensed tables with horizontal scrolling +- **Mobile**: Stacked layouts and collapsible sections + +## 🎨 Theme Customization Tips + +### Colors and Styling + +```css +/* Custom CSS for HTML output */ +.action-header { color: #0366d6; } +.input-table { border-collapse: collapse; } +.example-code { background: #f6f8fa; } +``` + +### Badge Customization + +```go-template +{{/* Custom badges */}} +![Version](https://img.shields.io/badge/version-{{ .Version }}-blue) +![License](https://img.shields.io/badge/license-{{ .License }}-green) +![Downloads](https://img.shields.io/github/downloads/{{ .Repository.FullName }}/total) +``` + +### Conditional Content + +```go-template +{{/* Show different content based on action type */}} +{{ if eq .Runs.Using "composite" }} +## Composite Action Steps +{{ range .Runs.Steps }} +- {{ .Name }}: {{ .Run }} +{{ end }} +{{ else if eq .Runs.Using "docker" }} +## Docker Configuration +- Image: `{{ .Runs.Image }}` +- Args: `{{ join .Runs.Args " " }}` +{{ end }} +``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..39c4a70 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,247 @@ +# Usage Guide + +Comprehensive guide to using gh-action-readme for generating documentation from GitHub Actions. + +## 🚀 Quick Start + +Generate documentation from your action.yml: + +```bash +# Basic generation +gh-action-readme gen + +# With specific theme and output +gh-action-readme gen --theme github --output README.md +``` + +## 📋 Examples + +### Input: `action.yml` + +```yaml +name: My Action +description: Does something awesome +inputs: + token: + description: GitHub token + required: true + environment: + description: Target environment + default: production +outputs: + result: + description: Action result +runs: + using: node20 + main: index.js +``` + +### Output: Professional README.md + +The tool generates comprehensive documentation including: + +- 📊 **Parameter tables** with types, requirements, defaults +- 💡 **Usage examples** with proper YAML formatting +- 🎨 **Badges** for marketplace visibility +- 📚 **Multiple sections** (Overview, Configuration, Examples, Troubleshooting) +- 🔗 **Navigation** with table of contents + +## 🛠️ Commands + +### Generation + +```bash +gh-action-readme gen [directory_or_file] [flags] + -f, --output-format string md, html, json, asciidoc (default "md") + -o, --output-dir string output directory (default ".") + --output string custom output filename + -t, --theme string github, gitlab, minimal, professional + -r, --recursive search recursively +``` + +**Examples:** + +```bash +# Generate with GitHub theme +gh-action-readme gen --theme github + +# Generate HTML documentation +gh-action-readme gen --output-format html + +# Process specific directory +gh-action-readme gen actions/checkout/ + +# Custom output filename +gh-action-readme gen --output my-action-docs.md + +# Recursive processing +gh-action-readme gen --recursive --theme professional +``` + +### Validation + +```bash +gh-action-readme validate + +# With verbose output +gh-action-readme validate --verbose +``` + +**Example Output:** + +```text +❌ Missing required field: description +💡 Add 'description: Brief description of what your action does' + +✅ All inputs have descriptions +⚠️ Consider adding 'branding' section for marketplace visibility +``` + +### Configuration + +```bash +gh-action-readme config init # Create default config +gh-action-readme config show # Show current settings +gh-action-readme config themes # List available themes +gh-action-readme config wizard # Interactive configuration +``` + +## 🎯 Advanced Usage + +### Batch Processing + +```bash +# Process multiple repositories with custom outputs +find . -name "action.yml" -execdir gh-action-readme gen --theme github --output README-generated.md \; + +# Recursive processing with JSON output +gh-action-readme gen --recursive --output-format json --output-dir docs/ + +# Target multiple specific actions +gh-action-readme gen actions/checkout/ --theme github --output docs/checkout.md +gh-action-readme gen actions/setup-node/ --theme professional --output docs/setup-node.md +``` + +### Custom Templates + +```bash +# Copy and modify existing theme +cp -r templates/themes/github templates/themes/custom +# Edit templates/themes/custom/readme.tmpl +gh-action-readme gen --theme custom +``` + +### Environment Integration + +```bash +# Set default preferences +export GH_ACTION_README_THEME=github +export GH_ACTION_README_VERBOSE=true +export GITHUB_TOKEN=your_token_here + +# Use with different output formats +gh-action-readme gen --output-format html --output docs/index.html +gh-action-readme gen --output-format json --output api/action.json +``` + +## 📄 Output Formats + +| Format | Description | Use Case | Extension | +|--------|-------------|----------|-----------| +| **md** | Markdown (default) | GitHub README files | `.md` | +| **html** | Styled HTML | Web documentation | `.html` | +| **json** | Structured data | API integration | `.json` | +| **asciidoc** | AsciiDoc format | Technical docs | `.adoc` | + +### Format Examples + +```bash +# Markdown (default) +gh-action-readme gen --output-format md + +# HTML with custom styling +gh-action-readme gen --output-format html --output docs/action.html + +# JSON for API consumption +gh-action-readme gen --output-format json --output api/metadata.json + +# AsciiDoc for technical documentation +gh-action-readme gen --output-format asciidoc --output docs/action.adoc +``` + +## 🎨 Themes + +See [themes.md](themes.md) for detailed theme documentation. + +| Theme | Best For | Features | +|-------|----------|----------| +| **github** | GitHub marketplace | Badges, collapsible sections | +| **gitlab** | GitLab repositories | CI/CD examples | +| **minimal** | Simple actions | Clean, concise | +| **professional** | Enterprise use | Comprehensive docs | +| **default** | Basic needs | Original template | + +## ⚙️ Configuration + +See [configuration.md](configuration.md) for detailed configuration options. + +## 🔧 Testing Generation + +**Safe testing with sample data:** + +```bash +# Test with included examples (safe - won't overwrite) +gh-action-readme gen testdata/example-action/ --theme github --output test-output.md +gh-action-readme gen testdata/composite-action/action.yml --theme professional + +# Test all themes +for theme in github gitlab minimal professional default; do + gh-action-readme gen testdata/example-action/ --theme $theme --output "test-${theme}.md" +done + +# Test all formats +for format in md html json asciidoc; do + gh-action-readme gen testdata/example-action/ --output-format $format --output "test.${format}" +done +``` + +## 🐛 Troubleshooting + +### Common Issues + +**File not found:** + +```bash +# Make sure action.yml exists in current directory or specify path +gh-action-readme gen path/to/action.yml +``` + +**Permission errors:** + +```bash +# Check file permissions +ls -la action.yml +chmod 644 action.yml +``` + +**GitHub API rate limits:** + +```bash +# Set GitHub token for higher rate limits +export GITHUB_TOKEN=your_token_here +gh-action-readme gen --verbose +``` + +**Template errors:** + +```bash +# Validate your action.yml first +gh-action-readme validate --verbose +``` + +### Getting Help + +1. Run with `--verbose` flag for detailed output +2. Check [GitHub Issues](https://github.com/ivuorinen/gh-action-readme/issues) +3. Validate your action.yml syntax +4. Verify file permissions and paths diff --git a/go.mod b/go.mod index a8b6a9d..3c906b3 100644 --- a/go.mod +++ b/go.mod @@ -1,39 +1,37 @@ module github.com/ivuorinen/gh-action-readme -go 1.23.10 +go 1.24.4 require ( github.com/adrg/xdg v0.5.3 github.com/fatih/color v1.18.0 + github.com/goccy/go-yaml v1.18.0 github.com/gofri/go-github-ratelimit v1.1.1 - github.com/google/go-github/v57 v57.0.0 - github.com/google/go-github/v58 v58.0.0 + github.com/google/go-github/v74 v74.0.0 github.com/schollz/progressbar/v3 v3.18.0 github.com/spf13/cobra v1.9.1 github.com/spf13/viper v1.20.1 golang.org/x/oauth2 v0.30.0 - gopkg.in/yaml.v3 v3.0.1 ) require ( - github.com/fsnotify/fsnotify v1.8.0 // indirect - github.com/go-viper/mapstructure/v2 v2.3.0 // indirect + github.com/fsnotify/fsnotify v1.9.0 // indirect + github.com/go-viper/mapstructure/v2 v2.4.0 // indirect github.com/google/go-querystring v1.1.0 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect - github.com/mattn/go-colorable v0.1.13 // indirect + github.com/mattn/go-colorable v0.1.14 // indirect github.com/mattn/go-isatty v0.0.20 // indirect github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db // indirect - github.com/pelletier/go-toml/v2 v2.2.3 // indirect + github.com/pelletier/go-toml/v2 v2.2.4 // indirect github.com/rivo/uniseg v0.4.7 // indirect - github.com/sagikazarmark/locafero v0.7.0 // indirect - github.com/sourcegraph/conc v0.3.0 // indirect - github.com/spf13/afero v1.12.0 // indirect - github.com/spf13/cast v1.7.1 // indirect - github.com/spf13/pflag v1.0.6 // indirect + github.com/sagikazarmark/locafero v0.10.0 // indirect + github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect + github.com/spf13/afero v1.14.0 // indirect + github.com/spf13/cast v1.9.2 // indirect + github.com/spf13/pflag v1.0.7 // indirect github.com/subosito/gotenv v1.6.0 // indirect - go.uber.org/atomic v1.9.0 // indirect - go.uber.org/multierr v1.9.0 // indirect - golang.org/x/sys v0.29.0 // indirect - golang.org/x/term v0.28.0 // indirect - golang.org/x/text v0.21.0 // indirect + golang.org/x/sys v0.34.0 // indirect + golang.org/x/term v0.33.0 // indirect + golang.org/x/text v0.27.0 // indirect + gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/go.sum b/go.sum index 2ca92bd..9d7a77f 100644 --- a/go.sum +++ b/go.sum @@ -2,27 +2,26 @@ github.com/adrg/xdg v0.5.3 h1:xRnxJXne7+oWDatRhR1JLnvuccuIeCoBu2rtuLqQB78= github.com/adrg/xdg v0.5.3/go.mod h1:nlTsY+NNiCBGCK2tpm09vRqfVzrc2fLmXGpBLF0zlTQ= github.com/chengxilo/virtualterm v1.0.4 h1:Z6IpERbRVlfB8WkOmtbHiDbBANU7cimRIof7mk9/PwM= github.com/chengxilo/virtualterm v1.0.4/go.mod h1:DyxxBZz/x1iqJjFxTFcr6/x+jSpqN0iwWCOK1q10rlY= -github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= -github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM= github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU= github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8= github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0= -github.com/fsnotify/fsnotify v1.8.0 h1:dAwr6QBTBZIkG8roQaJjGof0pp0EeF+tNV7YBP3F/8M= -github.com/fsnotify/fsnotify v1.8.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0= -github.com/go-viper/mapstructure/v2 v2.3.0 h1:27XbWsHIqhbdR5TIC911OfYvgSaW93HM+dX7970Q7jk= -github.com/go-viper/mapstructure/v2 v2.3.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM= +github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k= +github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0= +github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs= +github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM= +github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw= +github.com/goccy/go-yaml v1.18.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA= github.com/gofri/go-github-ratelimit v1.1.1 h1:5TCOtFf45M2PjSYU17txqbiYBEzjOuK1+OhivbW69W0= github.com/gofri/go-github-ratelimit v1.1.1/go.mod h1:wGZlBbzHmIVjwDR3pZgKY7RBTV6gsQWxLVkpfwhcMJM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= -github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= -github.com/google/go-github/v57 v57.0.0 h1:L+Y3UPTY8ALM8x+TV0lg+IEBI+upibemtBD8Q9u7zHs= -github.com/google/go-github/v57 v57.0.0/go.mod h1:s0omdnye0hvK/ecLvpsGfJMiRt85PimQh4oygmLIxHw= -github.com/google/go-github/v58 v58.0.0/go.mod h1:k4hxDKEfoWpSqFlc8LTpGd9fu2KrV1YAa6Hi6FmDNY4= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/go-github/v74 v74.0.0 h1:yZcddTUn8DPbj11GxnMrNiAnXH14gNs559AsUpNpPgM= +github.com/google/go-github/v74 v74.0.0/go.mod h1:ubn/YdyftV80VPSI26nSJvaEsTOnsjrxG3o9kJhcyak= github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8= github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= @@ -31,17 +30,16 @@ github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= -github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA= -github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg= -github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM= +github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE= +github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8= github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc= github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w= github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db h1:62I3jR2EmQ4l5rM/4FEfDWcRD+abF5XlKShorW5LRoQ= github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db/go.mod h1:l0dey0ia/Uv7NcFFVbCLtqEBQbrT4OCwCSKTEv6enCw= -github.com/pelletier/go-toml/v2 v2.2.3 h1:YmeHyLY8mFWbdkNWwpr+qIL2bEqT0o95WSdkNHvL12M= -github.com/pelletier/go-toml/v2 v2.2.3/go.mod h1:MfCQTFTvCcUyyvvwm1+G6H/jORL20Xlb6rzQu9GuUkc= +github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4= +github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ= @@ -49,45 +47,36 @@ github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUc github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8= github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= -github.com/sagikazarmark/locafero v0.7.0 h1:5MqpDsTGNDhY8sGp0Aowyf0qKsPrhewaLSsFaodPcyo= -github.com/sagikazarmark/locafero v0.7.0/go.mod h1:2za3Cg5rMaTMoG/2Ulr9AwtFaIppKXTRYnozin4aB5k= +github.com/sagikazarmark/locafero v0.10.0 h1:FM8Cv6j2KqIhM2ZK7HZjm4mpj9NBktLgowT1aN9q5Cc= +github.com/sagikazarmark/locafero v0.10.0/go.mod h1:Ieo3EUsjifvQu4NZwV5sPd4dwvu0OCgEQV7vjc9yDjw= github.com/schollz/progressbar/v3 v3.18.0 h1:uXdoHABRFmNIjUfte/Ex7WtuyVslrw2wVPQmCN62HpA= github.com/schollz/progressbar/v3 v3.18.0/go.mod h1:IsO3lpbaGuzh8zIMzgY3+J8l4C8GjO0Y9S69eFvNsec= -github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo= -github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0= -github.com/spf13/afero v1.12.0 h1:UcOPyRBYczmFn6yvphxkn9ZEOY65cpwGKb5mL36mrqs= -github.com/spf13/afero v1.12.0/go.mod h1:ZTlWwG4/ahT8W7T0WQ5uYmjI9duaLQGy3Q2OAl4sk/4= -github.com/spf13/cast v1.7.1 h1:cuNEagBQEHWN1FnbGEjCXL2szYEXqfJPbP2HNUaca9Y= -github.com/spf13/cast v1.7.1/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo= -github.com/spf13/cobra v1.8.0 h1:7aJaZx1B85qltLMc546zn58BxxfZdR/W22ej9CFoEf0= -github.com/spf13/cobra v1.8.0/go.mod h1:WXLWApfZ71AjXPya3WOlMsY9yMs7YeiHhFVlvLyhcho= +github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw= +github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8/go.mod h1:3n1Cwaq1E1/1lhQhtRK2ts/ZwZEhjcQeJQ1RuC6Q/8U= +github.com/spf13/afero v1.14.0 h1:9tH6MapGnn/j0eb0yIXiLjERO8RB6xIVZRDCX7PtqWA= +github.com/spf13/afero v1.14.0/go.mod h1:acJQ8t0ohCGuMN3O+Pv0V0hgMxNYDlvdk+VTfyZmbYo= +github.com/spf13/cast v1.9.2 h1:SsGfm7M8QOFtEzumm7UZrZdLLquNdzFYfIbEXntcFbE= +github.com/spf13/cast v1.9.2/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo= github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo= github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0= -github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= -github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o= github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +github.com/spf13/pflag v1.0.7 h1:vN6T9TfwStFPFM5XzjsvmzZkLuaLX+HS+0SeFLRgU6M= +github.com/spf13/pflag v1.0.7/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= github.com/spf13/viper v1.20.1 h1:ZMi+z/lvLyPSCoNtFCpqjy0S4kPbirhpTMwl8BkW9X4= github.com/spf13/viper v1.20.1/go.mod h1:P9Mdzt1zoHIG8m2eZQinpiBjo6kCmZSKBClNNqjJvu4= -github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= -github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8= github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU= -go.uber.org/atomic v1.9.0 h1:ECmE8Bn/WFTYwEW/bpKD3M8VtR/zQVbavAoalC1PYyE= -go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc= -go.uber.org/multierr v1.9.0 h1:7fIwc/ZtS0q++VgcfqFDxSBZVv/Xo49/SYnDFupUwlI= -go.uber.org/multierr v1.9.0/go.mod h1:X2jQV1h+kxSjClGpnseKVIxpmcjrj7MNnI0bnlfKTVQ= golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI= golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU= -golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.29.0 h1:TPYlXGxvx1MGTn2GiZDhnjPA9wZzZeGKHHmKhHYvgaU= -golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= -golang.org/x/term v0.28.0 h1:/Ts8HFuMR2E6IP/jlo7QVLZHggjKQbhu/7H0LJFr3Gg= -golang.org/x/term v0.28.0/go.mod h1:Sw/lC2IAUZ92udQNf3WodGtn4k/XoLyZoh8v/8uiwek= -golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo= -golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ= +golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA= +golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= +golang.org/x/term v0.33.0 h1:NuFncQrRcaRvVmgRkvM3j/F00gWIAlcmlB8ACEKmGIg= +golang.org/x/term v0.33.0/go.mod h1:s18+ql9tYWp1IfpV9DmCtQDDSRBUjKaw9M1eAv5UeF0= +golang.org/x/text v0.27.0 h1:4fGWRpyh641NLlecmyl4LOe6yDdfaYNrGb2zdfo4JV4= +golang.org/x/text v0.27.0/go.mod h1:1D28KMCvyooCX9hBiosv5Tz/+YLxj0j7XhWjpSUF7CU= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo= diff --git a/internal/config.go b/internal/config.go index e9bfa6f..70c8078 100644 --- a/internal/config.go +++ b/internal/config.go @@ -10,7 +10,7 @@ import ( "github.com/adrg/xdg" "github.com/gofri/go-github-ratelimit/github_ratelimit" - "github.com/google/go-github/v57/github" + "github.com/google/go-github/v74/github" "github.com/spf13/viper" "golang.org/x/oauth2" diff --git a/internal/dependencies/analyzer.go b/internal/dependencies/analyzer.go index 29395fb..261457b 100644 --- a/internal/dependencies/analyzer.go +++ b/internal/dependencies/analyzer.go @@ -10,7 +10,7 @@ import ( "strings" "time" - "github.com/google/go-github/v57/github" + "github.com/google/go-github/v74/github" "github.com/ivuorinen/gh-action-readme/internal/git" ) diff --git a/internal/dependencies/analyzer_test.go b/internal/dependencies/analyzer_test.go index 4125bb9..dd31cb2 100644 --- a/internal/dependencies/analyzer_test.go +++ b/internal/dependencies/analyzer_test.go @@ -8,7 +8,7 @@ import ( "testing" "time" - "github.com/google/go-github/v57/github" + "github.com/google/go-github/v74/github" "github.com/ivuorinen/gh-action-readme/internal/cache" "github.com/ivuorinen/gh-action-readme/internal/git" diff --git a/internal/dependencies/parser.go b/internal/dependencies/parser.go index 0f1a1d4..56ae296 100644 --- a/internal/dependencies/parser.go +++ b/internal/dependencies/parser.go @@ -4,7 +4,7 @@ import ( "fmt" "os" - "gopkg.in/yaml.v3" + "github.com/goccy/go-yaml" ) // parseCompositeActionFromFile reads and parses a composite action file. diff --git a/internal/generator.go b/internal/generator.go index ffdb471..5f65e5d 100644 --- a/internal/generator.go +++ b/internal/generator.go @@ -9,7 +9,7 @@ import ( "strconv" "strings" - "github.com/google/go-github/v57/github" + "github.com/google/go-github/v74/github" "github.com/schollz/progressbar/v3" "github.com/ivuorinen/gh-action-readme/internal/cache" diff --git a/internal/parser.go b/internal/parser.go index be80bb4..59d1b48 100644 --- a/internal/parser.go +++ b/internal/parser.go @@ -6,7 +6,7 @@ import ( "path/filepath" "strings" - "gopkg.in/yaml.v3" + "github.com/goccy/go-yaml" ) // ActionYML models the action.yml metadata (fields are updateable as schema evolves). diff --git a/internal/template.go b/internal/template.go index 0d4ed39..5fc5c5f 100644 --- a/internal/template.go +++ b/internal/template.go @@ -2,11 +2,10 @@ package internal import ( "bytes" - "fmt" "strings" "text/template" - "github.com/google/go-github/v57/github" + "github.com/google/go-github/v74/github" "github.com/ivuorinen/gh-action-readme/internal/cache" "github.com/ivuorinen/gh-action-readme/internal/dependencies" @@ -18,6 +17,7 @@ import ( const ( defaultOrgPlaceholder = "your-org" defaultRepoPlaceholder = "your-repo" + defaultUsesPlaceholder = "your-org/your-action@v1" ) // TemplateOptions defines options for rendering templates. @@ -92,14 +92,14 @@ func getGitRepo(data any) string { func getGitUsesString(data any) string { td, ok := data.(*TemplateData) if !ok { - return "your-org/your-action@v1" + return defaultUsesPlaceholder } org := strings.TrimSpace(getGitOrg(data)) repo := strings.TrimSpace(getGitRepo(data)) if !isValidOrgRepo(org, repo) { - return "your-org/your-action@v1" + return defaultUsesPlaceholder } version := formatVersion(getActionVersion(data)) @@ -127,14 +127,21 @@ func formatVersion(version string) string { // buildUsesString constructs the uses string with optional action name. func buildUsesString(td *TemplateData, org, repo, version string) string { - if td.Name != "" { + // Use the validation package's FormatUsesStatement for consistency + if org == "" || repo == "" { + return defaultUsesPlaceholder + } + + // For actions within subdirectories, include the action name + if td.Name != "" && repo != "" { actionName := validation.SanitizeActionName(td.Name) if actionName != "" && actionName != repo { - return fmt.Sprintf("%s/%s/%s%s", org, repo, actionName, version) + // Check if this looks like a subdirectory action + return validation.FormatUsesStatement(org, repo+"/"+actionName, version) } } - return fmt.Sprintf("%s/%s%s", org, repo, version) + return validation.FormatUsesStatement(org, repo, version) } // getActionVersion returns the action version from template data. diff --git a/internal/wizard/detector.go b/internal/wizard/detector.go index b4c1a74..29b06e3 100644 --- a/internal/wizard/detector.go +++ b/internal/wizard/detector.go @@ -9,7 +9,7 @@ import ( "path/filepath" "strings" - "gopkg.in/yaml.v3" + "github.com/goccy/go-yaml" "github.com/ivuorinen/gh-action-readme/internal" "github.com/ivuorinen/gh-action-readme/internal/git" diff --git a/internal/wizard/exporter.go b/internal/wizard/exporter.go index 22311e2..e369712 100644 --- a/internal/wizard/exporter.go +++ b/internal/wizard/exporter.go @@ -7,7 +7,7 @@ import ( "os" "path/filepath" - "gopkg.in/yaml.v3" + "github.com/goccy/go-yaml" "github.com/ivuorinen/gh-action-readme/internal" ) @@ -94,8 +94,7 @@ func (e *ConfigExporter) exportYAML(config *internal.AppConfig, outputPath strin _ = file.Close() // File will be closed, error not actionable in defer }() - encoder := yaml.NewEncoder(file) - encoder.SetIndent(2) + encoder := yaml.NewEncoder(file, yaml.Indent(2)) // Add header comment _, _ = file.WriteString("# gh-action-readme configuration file\n") diff --git a/internal/wizard/exporter_test.go b/internal/wizard/exporter_test.go index 9725603..c7dfcc0 100644 --- a/internal/wizard/exporter_test.go +++ b/internal/wizard/exporter_test.go @@ -7,7 +7,7 @@ import ( "strings" "testing" - "gopkg.in/yaml.v3" + "github.com/goccy/go-yaml" "github.com/ivuorinen/gh-action-readme/internal" ) diff --git a/templates/themes/asciidoc/readme.adoc b/templates/themes/asciidoc/readme.adoc index ceef5fc..dd99d8c 100644 --- a/templates/themes/asciidoc/readme.adoc +++ b/templates/themes/asciidoc/readme.adoc @@ -26,7 +26,7 @@ jobs: steps: - uses: actions/checkout@v4 - name: {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"value"{{end}} @@ -91,7 +91,7 @@ with: ---- - name: {{.Name}} id: action-step - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} - name: Use Output run: | @@ -108,7 +108,7 @@ with: [source,yaml] ---- - name: Basic {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"example-value"{{end}} @@ -120,7 +120,7 @@ with: [source,yaml] ---- - name: Advanced {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"\${{"{{"}} vars.{{$key | upper}} {{"}}"}}"{{end}} @@ -135,7 +135,7 @@ with: ---- - name: Conditional {{.Name}} if: github.event_name == 'push' - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"production-value"{{end}} diff --git a/templates/themes/gitlab/readme.tmpl b/templates/themes/gitlab/readme.tmpl index 38dfc5e..77e22ea 100644 --- a/templates/themes/gitlab/readme.tmpl +++ b/templates/themes/gitlab/readme.tmpl @@ -13,7 +13,7 @@ Add this action to your GitLab CI/CD pipeline or GitHub workflow: ```yaml steps: - name: {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}{{$val.Default}}{{else}}value{{end}} diff --git a/templates/themes/minimal/readme.tmpl b/templates/themes/minimal/readme.tmpl index c792078..199f934 100644 --- a/templates/themes/minimal/readme.tmpl +++ b/templates/themes/minimal/readme.tmpl @@ -5,7 +5,7 @@ ## Usage ```yaml -- uses: your-org/{{.Name | lower | replace " " "-"}}@v1 +- uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}{{$val.Default}}{{else}}value{{end}} diff --git a/templates/themes/professional/readme.tmpl b/templates/themes/professional/readme.tmpl index 4ffe8fc..b2eba1e 100644 --- a/templates/themes/professional/readme.tmpl +++ b/templates/themes/professional/readme.tmpl @@ -47,7 +47,7 @@ jobs: uses: actions/checkout@v4 - name: {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"your-value-here"{{end}} @@ -102,7 +102,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: {{.Name}} id: action-step - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} - name: Use Output run: | @@ -118,7 +118,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: Basic {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"example-value"{{end}} @@ -129,7 +129,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: Advanced {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"\${{"{{"}} vars.{{$key | upper}} {{"}}"}}"{{end}} @@ -143,7 +143,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: Conditional {{.Name}} if: github.event_name == 'push' - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"production-value"{{end}} diff --git a/templates_embed/templates/themes/asciidoc/readme.adoc b/templates_embed/templates/themes/asciidoc/readme.adoc index ceef5fc..dd99d8c 100644 --- a/templates_embed/templates/themes/asciidoc/readme.adoc +++ b/templates_embed/templates/themes/asciidoc/readme.adoc @@ -26,7 +26,7 @@ jobs: steps: - uses: actions/checkout@v4 - name: {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"value"{{end}} @@ -91,7 +91,7 @@ with: ---- - name: {{.Name}} id: action-step - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} - name: Use Output run: | @@ -108,7 +108,7 @@ with: [source,yaml] ---- - name: Basic {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"example-value"{{end}} @@ -120,7 +120,7 @@ with: [source,yaml] ---- - name: Advanced {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"\${{"{{"}} vars.{{$key | upper}} {{"}}"}}"{{end}} @@ -135,7 +135,7 @@ with: ---- - name: Conditional {{.Name}} if: github.event_name == 'push' - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"production-value"{{end}} diff --git a/templates_embed/templates/themes/gitlab/readme.tmpl b/templates_embed/templates/themes/gitlab/readme.tmpl index 38dfc5e..77e22ea 100644 --- a/templates_embed/templates/themes/gitlab/readme.tmpl +++ b/templates_embed/templates/themes/gitlab/readme.tmpl @@ -13,7 +13,7 @@ Add this action to your GitLab CI/CD pipeline or GitHub workflow: ```yaml steps: - name: {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}{{$val.Default}}{{else}}value{{end}} diff --git a/templates_embed/templates/themes/minimal/readme.tmpl b/templates_embed/templates/themes/minimal/readme.tmpl index c792078..199f934 100644 --- a/templates_embed/templates/themes/minimal/readme.tmpl +++ b/templates_embed/templates/themes/minimal/readme.tmpl @@ -5,7 +5,7 @@ ## Usage ```yaml -- uses: your-org/{{.Name | lower | replace " " "-"}}@v1 +- uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}{{$val.Default}}{{else}}value{{end}} diff --git a/templates_embed/templates/themes/professional/readme.tmpl b/templates_embed/templates/themes/professional/readme.tmpl index 4ffe8fc..b2eba1e 100644 --- a/templates_embed/templates/themes/professional/readme.tmpl +++ b/templates_embed/templates/themes/professional/readme.tmpl @@ -47,7 +47,7 @@ jobs: uses: actions/checkout@v4 - name: {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"your-value-here"{{end}} @@ -102,7 +102,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: {{.Name}} id: action-step - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} - name: Use Output run: | @@ -118,7 +118,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: Basic {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"example-value"{{end}} @@ -129,7 +129,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: Advanced {{.Name}} - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"\${{"{{"}} vars.{{$key | upper}} {{"}}"}}"{{end}} @@ -143,7 +143,7 @@ This action provides the following outputs that can be used in subsequent workfl ```yaml - name: Conditional {{.Name}} if: github.event_name == 'push' - uses: your-org/{{.Name | lower | replace " " "-"}}@v1 + uses: {{gitUsesString .}} {{if .Inputs}}with: {{- range $key, $val := .Inputs}} {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"production-value"{{end}} diff --git a/testutil/fixtures.go b/testutil/fixtures.go index 028c284..f5f523e 100644 --- a/testutil/fixtures.go +++ b/testutil/fixtures.go @@ -9,7 +9,7 @@ import ( "strings" "sync" - "gopkg.in/yaml.v3" + "github.com/goccy/go-yaml" ) // fixtureCache provides thread-safe caching of fixture content. diff --git a/testutil/fixtures_test.go b/testutil/fixtures_test.go index 605f54d..b5e0888 100644 --- a/testutil/fixtures_test.go +++ b/testutil/fixtures_test.go @@ -7,7 +7,7 @@ import ( "strings" "testing" - "gopkg.in/yaml.v3" + "github.com/goccy/go-yaml" ) const testVersion = "v4.1.1" diff --git a/testutil/test_suites.go b/testutil/test_suites.go index 71a031b..191cc88 100644 --- a/testutil/test_suites.go +++ b/testutil/test_suites.go @@ -9,7 +9,7 @@ import ( "strings" "testing" - "github.com/google/go-github/v57/github" + "github.com/google/go-github/v74/github" ) // File constants. diff --git a/testutil/testutil.go b/testutil/testutil.go index a723c6c..681b399 100644 --- a/testutil/testutil.go +++ b/testutil/testutil.go @@ -13,7 +13,7 @@ import ( "testing" "time" - "github.com/google/go-github/v57/github" + "github.com/google/go-github/v74/github" ) // MockHTTPClient is a mock HTTP client for testing.