@herb-tools/linter 0.6.1 → 0.7.0

package/README.md

@@ -122,10 +122,15 @@ npx @herb-tools/linter template.html.erb --json
 # or
 npx @herb-tools/linter template.html.erb --format json
 
-# Use GitHub Actions output format
+# Use GitHub Actions output format with detailed preview (default)
+# (This is enabled automatically when the GITHUB_ACTIONS environment variable is set)
 npx @herb-tools/linter template.html.erb --github
-# or
-npx @herb-tools/linter template.html.erb --format github
+
+# Combine GitHub Actions output with simple format
+npx @herb-tools/linter template.html.erb --format=simple --github
+
+# Combine GitHub Actions output with detailed format (explicit)
+npx @herb-tools/linter template.html.erb --format=detailed --github
 ```
 
 **Display Options:**
@@ -144,6 +149,12 @@ npx @herb-tools/linter template.html.erb --no-wrap-lines
 
 # Enable line truncation (mutually exclusive with line wrapping)
 npx @herb-tools/linter template.html.erb --truncate-lines --no-wrap-lines
+
+# Combine GitHub Actions annotations with different formats
+npx @herb-tools/linter template.html.erb --format=simple --github
+
+# Disable GitHub Actions annotations (even in GitHub Actions environment)
+npx @herb-tools/linter template.html.erb --no-github
 ```
 
 **Help and Version:**
@@ -157,21 +168,53 @@ npx @herb-tools/linter --version
 
 #### GitHub Actions Output Format
 
-The linter supports GitHub Actions annotation format with the `--github` flag, which outputs errors and warnings in a format that GitHub Actions can parse to create inline annotations in pull requests:
+The linter supports GitHub Actions annotation format with the `--github` flag, which can be combined with `--format=simple` or `--format=detailed`. The `--github` flag adds GitHub Actions annotations that GitHub can parse to create inline annotations in pull requests, while also showing the regular format output for local debugging.
+
+::: tip Tip: Running in GitHub Actions
+When the `GITHUB_ACTIONS` environment variable is set (as in GitHub Actions), GitHub Actions annotations are enabled by default. You can disable them with `--no-github` if needed.
+:::
 
 ```bash
-npx @herb-tools/linter "**/*.html.erb" --github
+# GitHub Actions annotations + detailed format (default)
+npx @herb-tools/linter --github
+
+# GitHub Actions annotations + simple format (minimal local output)
+npx @herb-tools/linter --format=simple --github
+```
+
+**Example: `--github` (GitHub annotations + detailed format)**
 ```
+::error file=template.html.erb,line=3,col=3,title=html-img-require-alt • @herb-tools/linter@0.7.0::Missing required `alt` attribute on `<img>` tag [html-img-require-alt]%0A%0A%0Atemplate.html.erb:3:3%0A%0A      1 │ <div>%0A      2 │   <span>Test content</span>%0A  →   3 │   <img src="test.jpg">%0A        │    ~~~%0A      4 │ </div>%0A
+
+[error] Missing required `alt` attribute on `<img>` tag [html-img-require-alt]
+
+template.html.erb:3:3
 
-Example output:
+      1 │ <div>
+      2 │   <span>Test content</span>
+  →   3 │   <img src="test.jpg">
+        │    ~~~
+      4 │ </div>
 ```
-::error file=template.html.erb,line=5,col=5::File must end with trailing newline [erb-requires-trailing-newline]
-::warning file=template.html.erb,line=3,col=10::Consider using semantic HTML tags [html-semantic-tags]
+
+**Example: `--format=simple --github` (GitHub annotations + simple format)**
 ```
+::error file=template.html.erb,line=3,col=3,title=html-img-require-alt • @herb-tools/linter@0.7.0::Missing required `alt` attribute on `<img>` tag [html-img-require-alt]%0A%0A%0Atemplate.html.erb:3:3%0A%0A      1 │ <div>%0A      2 │   <span>Test content</span>%0A  →   3 │   <img src="test.jpg">%0A        │    ~~~%0A      4 │ </div>%0A
 
-This format is ideal for CI/CD workflows in GitHub Actions:
+template.html.erb:
+  3:3 ✗ Missing required `alt` attribute on `<img>` tag [html-img-require-alt]
+```
 
-```yaml [.github/workflows/herb-lint.yml]
+The GitHub Actions annotations include:
+- **Embedded plain-text code previews** (with `%0A` for newlines) that GitHub renders in PR comments
+- **`title` property** showing the rule code and linter version for better traceability
+- **Full error context** for debugging directly in GitHub's UI
+
+The regular format output provides colorful syntax highlighting for local terminal debugging.
+
+This approach is ideal for CI/CD workflows as it provides both GitHub integration and local debugging:
+
+```yaml [.github/workflows/herb.yml]
 name: Herb Lint
 on: [push, pull_request]
 
@@ -180,8 +223,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-      - run: npx @herb-tools/linter "**/*.html.erb" --github
+
+      - name: Run Herb Linter
+        run: npx @herb-tools/linter
 ```
 
 #### JSON Output Format
@@ -232,11 +276,11 @@ npx @herb-tools/linter template.html.erb --json
 
 JSON output fields:
 - `offenses`: Array of linting offenses with location and severity
-- `summary`: Statistics about the linting run (null on errors)
-- `timing`: Timing information with ISO timestamp (null with `--no-timing`)
+- `summary`: Statistics about the linting run (`null` on errors)
+- `timing`: Timing information with ISO timestamp (`null` with `--no-timing`)
 - `completed`: Whether the linter ran successfully on files
-- `clean`: Whether there were no offenses (null when `completed=false`)
-- `message`: Error or informational message (null on success)
+- `clean`: Whether there were no offenses (`null` when `completed=false`)
+- `message`: Error or informational message (`null` on success)
 
 ### Language Server Integration