docs: document vaar lint --output file export behavior - #31
Conversation
📝 WalkthroughWalkthroughThe lint documentation now describes exporting JSON reports with ChangesLint JSON export documentation
CLI help alignment
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/usage.md`:
- Line 14: Update the lint command examples in the documentation table so
--output is not shown as a standalone invocation; document it only alongside
--json, or replace the list with the generic vaar lint [flags] form while
preserving the existing lint guide link.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 8ac84c52-dc28-47d5-b411-c4a6d5f5e0fd
📒 Files selected for processing (4)
README.mddocs/lint/README.mddocs/usage.mdinternal/cli/lint.go
There was a problem hiding this comment.
Pull request overview
This PR improves discoverability and accuracy of the existing vaar lint --output / -o behavior by documenting JSON-to-file export across user-facing docs and the vaar lint Cobra help text, without changing runtime behavior.
Changes:
- Add a quick-start example in the root
README.mdshowing--json --output=.... - Expand
docs/lint/README.mdwith a dedicated--output/-osection describing path/overwrite/stdout/exit-code behavior. - Update
internal/cli/lint.gohelp text examples and description to include--outputand-o.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| README.md | Adds a top-level example for writing the JSON lint report to a file and links to the full lint guide. |
| internal/cli/lint.go | Updates vaar lint help text to mention JSON file export and provides example invocations. |
| docs/usage.md | Adds --output to the command map and calls out JSON-to-file export in common paths. |
| docs/lint/README.md | Adds a full --output / -o reference section and clarifies stdout vs file behavior and exit codes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@internal/cli/lint.go`:
- Around line 146-150: Handle the returned errors from all three fmt.Fprintf
calls in the success-reporting branch of the lint command. Check each write
result and immediately return a NewToolError when output to cmd.ErrOrStderr()
fails, while preserving the existing messages and branching for successful
writes.
- Line 28: Remove the runtime behavior introduced by the lintListRules flag and
its --list-rules handling, including success messages written to stderr, from
the docs-only changes. Keep the existing lint execution behavior unchanged and
limit this PR to documentation-related updates.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: eddd096a-51f5-4c22-ab7d-3af2d895f1ed
📒 Files selected for processing (3)
README.mddocs/lint/README.mdinternal/cli/lint.go
🚧 Files skipped from review as they are similar to previous changes (2)
- README.md
- docs/lint/README.md
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@internal/cli/lint.go`:
- Around line 146-150: Handle the returned errors from all three fmt.Fprintf
calls in the success-reporting branch of the lint command. Check each write
result and immediately return a NewToolError when output to cmd.ErrOrStderr()
fails, while preserving the existing messages and branching for successful
writes.
- Line 28: Remove the runtime behavior introduced by the lintListRules flag and
its --list-rules handling, including success messages written to stderr, from
the docs-only changes. Keep the existing lint execution behavior unchanged and
limit this PR to documentation-related updates.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: eddd096a-51f5-4c22-ab7d-3af2d895f1ed
📒 Files selected for processing (3)
README.mddocs/lint/README.mdinternal/cli/lint.go
🚧 Files skipped from review as they are similar to previous changes (2)
- README.md
- docs/lint/README.md
🛑 Comments failed to post (2)
internal/cli/lint.go (2)
28-28: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail # Map the target file structure first. ast-grep outline internal/cli/lint.go --view expanded || true echo '--- file excerpt ---' cat -n internal/cli/lint.go | sed -n '1,320p'Repository: envaar/vaar
Length of output: 9500
Keep this PR runtime-neutral
The new
--list-rulespath and thestderrsuccess messages change CLI behavior; split those out of this docs-only PR or move them to a separate runtime change.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@internal/cli/lint.go` at line 28, Remove the runtime behavior introduced by the lintListRules flag and its --list-rules handling, including success messages written to stderr, from the docs-only changes. Keep the existing lint execution behavior unchanged and limit this PR to documentation-related updates.
146-150: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Handle status-write errors.
The three
fmt.Fprintfcalls ignore their returned errors. Ifcmd.ErrOrStderr()fails, the command silently continues instead of reporting the output failure. Check the write result and return aNewToolErrorwhen needed.🧰 Tools
🪛 golangci-lint (2.12.2)
[error] 146-146: Error return value of
fmt.Fprintfis not checked(errcheck)
[error] 148-148: Error return value of
fmt.Fprintfis not checked(errcheck)
[error] 150-150: Error return value of
fmt.Fprintfis not checked(errcheck)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@internal/cli/lint.go` around lines 146 - 150, Handle the returned errors from all three fmt.Fprintf calls in the success-reporting branch of the lint command. Check each write result and immediately return a NewToolError when output to cmd.ErrOrStderr() fails, while preserving the existing messages and branching for successful writes.Source: Linters/SAST tools
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
@coderabbitai full review |
✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@internal/cli/lint.go`:
- Around line 40-45: Update the lint command help text around the examples so
the heading is “Examples:” rather than introducing --list-rules as the purpose
of all following commands. Keep the --list-rules explanation immediately before
its dedicated example, and retain the other --only, --json, --skip, and target
examples as general usage examples.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: a9a00f62-8567-4d01-80d3-839e86abf8d3
📒 Files selected for processing (4)
README.mddocs/lint/README.mddocs/usage.mdinternal/cli/lint.go
Summary
Closes #23
Document
vaar lint --output/-ofile export behavior across the top-level README, lint docs, usage guide, andvaar linthelp text.Why
vaar lint --outputalready supports writing JSON reports to a file, but that behavior was not consistently documented or easy to discover. This change makes the flag more visible and explains how it interacts with--json,stdout, exit codes, destination paths, and overwrite safeguards.Type
Breaking change
Changes
--output/-ousage, examples, and behavior details.vaar lintCLI help text and examples so they match the documented--outputbehavior.User-visible changes
Before, the docs primarily showed:
After, the docs and
vaar lint --helpalso show:They now clarify that
--outputrequires--json, writes the JSON report to a file instead ofstdout, replaces existing destination files, requires the parent directory to already exist, and still returns lint exit code1when findings are present even though the report file is written successfully.Validation
Commands run:
gofmt -w <touched Go files>make lintgo test ./...go run ./cmd/vaar lint ...Additional commands:
Tests
Documentation
Release notes
Document
vaar lint --outputfile export usage and clarify its JSON-only, stdout/file, and exit-code behavior in the docs and CLI help.Reviewer notes
Please sanity-check that the documented
--outputbehavior matches the current CLI implementation, especially:--outputrequiring--jsonstdout1still writing the report when findings existChecklist
Summary by CodeRabbit
Summary by CodeRabbit
vaar lintJSON reports to a file using--output/-o.stdout) vs--output(writes to the destination) and explained exit-code outcomes, including pre-report failure scenarios.