Add --output-format flag for GitHub Actions workflow integration

[Copilot]

Refactoring Complete ✅

Summary

Refactored the output logic following the separation of concerns pattern used throughout the codebase. All output formatting has been moved from /cmd/check.go to a new /pkg/output package with an interface-based design.

Changes Made

Architecture

• Created /pkg/output package with clean interface-based design
• Formatter interface - Common interface for all output formatters
• Three implementations:
  • DefaultFormatter - Shows only broken links (default)
  • VerboseFormatter - Shows all links with status codes
  • GitHubFormatter - GitHub Actions format with annotations

CLI Changes

• Changed flag from --github-output to --output-format (or -o)
  • Values: default, verbose, github
  • Better alignment with industry standards (like ruff's --output-format=github)
• Backward compatibility: Kept -v/--verbose flag (marked as deprecated)
• Cleaner /cmd/check.go: Now contains only CLI logic, no output formatting

Code Organization

pkg/output/
├── output.go      # Interface definition and factory
├── default.go     # DefaultFormatter implementation
├── verbose.go     # VerboseFormatter implementation  
├── github.go      # GitHubFormatter implementation
├── utils.go       # Shared utilities (status icons, colors, counting)
└── output_test.go # Comprehensive tests

Code Quality

• ✅ String constants defined for format names to satisfy goconst linter
• ✅ GITHUB_OUTPUT file created with 0600 permissions (owner read/write only)

Documentation

• ✅ Updated copilot-instructions.md with comprehensive output package documentation
• ✅ Documented all three formatters and their behavior
• ✅ Added guidance for adding new output formats

Testing

• ✅ All existing tests pass
• ✅ New comprehensive tests for output package
• ✅ Race detection clean
• ✅ Code formatted
• ✅ Linting passes

Usage Examples

# Default format (broken links only)
brokli check url https://example.com

# Verbose format
brokli check url https://example.com --output-format=verbose
brokli check url https://example.com -o verbose
brokli check url https://example.com -v  # backward compatible

# GitHub Actions format  
brokli check url https://example.com --output-format=github
brokli check url https://example.com -o github

Benefits

1. Separation of Concerns: CLI logic separate from output formatting
2. Extensible: Easy to add new formatters (JSON, XML, etc.)
3. Testable: Output logic fully unit tested
4. Interface-Based: Follows existing patterns in the codebase
5. Industry Standard: Flag naming inspired by ruff and other tools
6. Backward Compatible: Old -v flag still works
7. Secure: Proper file permissions for sensitive output files
8. Clean Code: Passes all linting checks including goconst
9. Well Documented: Comprehensive developer guide updated

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature Request: Add --github-output flag for GitHub Actions CI compatibility</issue_title>
<issue_description>## Summary
Add a new flag --github-output to brokli so that its output is formatted for use as part of a GitHub Actions workflow in CI pipelines.

Motivation

• When brokli is used in GitHub Actions, its current output is not always easy to parse or use with downstream steps that expect specific output formats (such as GitHub workflow commands).
• A dedicated --github-output flag would allow developers to more easily capture, parse, and act on brokli output in CI jobs, improving integration and automation efficiency.

Proposed Solution

• Implement a --github-output flag that reformats key output (e.g., status, errors, results) in a way that GitHub Actions can natively understand (such as workflow annotations).
• Document the output format and provide usage instructions for common CI scenarios.

Example Usage

brokli check url https://127.0.0.1 --github-output

Additional Notes

• Consider using GitHub Actions syntax for output files and step outputs where applicable.
• May need to support both stdout formatting and explicit output files (e.g., for GITHUB_OUTPUT).</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Feature Request: Add --github-output flag for GitHub Actions CI compatibility #17

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[EndlessTrax]

@copilot let's refactor this and remove all output logic and code into /pkg. the /cmd/check.go should contain only cli logic. Use the same design pattern used through the code base to use a separation of duties and implement a common interface for output. Also, if you are able, look a the code base for https://github.com/astral-sh/ruff. They have very nicely formatted output that works well for GitHub actions with their --output-format=github flag. Use that as inspiration.

[Copilot]

@copilot let's refactor this and remove all output logic and code into /pkg. the /cmd/check.go should contain only cli logic. Use the same design pattern used through the code base to use a separation...

Refactored! All output logic moved to /pkg/output with interface-based design. Changes in commit a68a594:

Architecture:

• Created /pkg/output package with Formatter interface
• Implemented DefaultFormatter, VerboseFormatter, and GitHubFormatter
• /cmd/check.go now contains only CLI logic

Flag Changes:

• Changed --github-output to --output-format (or -o)
• Values: default, verbose, github
• Kept -v/--verbose for backward compatibility (deprecated)
• Inspired by ruff's --output-format=github pattern

Examples:

# Default (broken links only)
brokli check url https://example.com

# Verbose (all links)
brokli check url https://example.com -o verbose

# GitHub Actions format
brokli check url https://example.com -o github

Testing:

• ✅ All tests pass with race detection
• ✅ New comprehensive tests for output package
• ✅ Backward compatible with -v flag

See full demo output below showing all three formats in action.

---

Demo Output:

1. DEFAULT FORMAT (--output-format=default or no flag)
-------------------------------------------------------
Found 3 links
Checking links... 3/3

Broken Links:
✗ 1. [404] 404 Link -> http://localhost:8771/404
✗ 2. [500] 500 Link -> http://localhost:8771/500

Summary: 2 broken links found out of 3 total

2. VERBOSE FORMAT (--output-format=verbose or -o verbose or -v)
----------------------------------------------------------------
Found 3 links
Checking links... 3/3

All Links:
✓ 1. [200] Working Link -> http://localhost:8771/ok
✗ 2. [404] 404 Link -> http://localhost:8771/404
✗ 3. [500] 500 Link -> http://localhost:8771/500

Summary: 2 broken links found out of 3 total

3. GITHUB ACTIONS FORMAT (--output-format=github or -o github)
---------------------------------------------------------------
Found 3 links
Checking links... 3/3
::error title="Broken Link (Status 404)"::Link '404 Link' to http://localhost:8771/404 returned status 404
::error title="Broken Link (Status 500)"::Link '500 Link' to http://localhost:8771/500 returned status 500
Found 2 broken links out of 3 total

GITHUB_OUTPUT file:
broken_links_count=2
total_links_count=3
has_broken_links=true

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• invalid-domain-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build841966837/b205/checker.test /tmp/go-build841966837/b205/checker.test -test.testlogfile=/tmp/go-build841966837/b205/testlog.txt -test.paniconexit0 -test.timeout=10m0s (dns block)
  • Triggering command: /tmp/go-build3788884285/b207/checker.test /tmp/go-build3788884285/b207/checker.test -test.testlogfile=/tmp/go-build3788884285/b207/testlog.txt -test.paniconexit0 -test.timeout=10m0s (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[EndlessTrax]

@copilot Linting is failing with:

Error: cmd/check.go:108:16: string `verbose` has 4 occurrences, make it a constant (goconst)
  			formatStr = "verbose"

Please fix.

[Copilot]

@copilot Linting is failing with:

...

Fixed in commit dbaa110. Added string constants FormatNameDefault, FormatNameVerbose, and FormatNameGitHub to pkg/output/output.go and updated cmd/check.go to use these constants instead of string literals. The goconst linter error is now resolved.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• invalid-domain-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build2778697106/b205/checker.test /tmp/go-build2778697106/b205/checker.test -test.testlogfile=/tmp/go-build2778697106/b205/testlog.txt -test.paniconexit0 -test.timeout=10m0s (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[EndlessTrax]

@copilot Almost there. Please update copilot-instructions.md with relevant documentation from changes in this PR.

[Copilot]

@copilot Almost there. Please update copilot-instructions.md with relevant documentation from changes in this PR.

Updated in commit 511808e. The copilot-instructions.md now includes:

• Architecture section updated with pkg/output/ package
• Completed features updated to reflect new output formats and GitHub Actions integration
• Comprehensive documentation of the Formatter interface and three implementations
• CLI flags documentation (--output-format and backward compatibility)
• Details on all three output formats (Default, Verbose, GitHub)
• Helper functions documentation from pkg/output/utils.go
• New "Adding a new output format" common task section with step-by-step guide
• Updated guidance for working with output formatters

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• invalid-domain-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build2659076264/b205/checker.test /tmp/go-build2659076264/b205/checker.test -test.testlogfile=/tmp/go-build2659076264/b205/testlog.txt -test.paniconexit0 -test.timeout=10m0s (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)