Output Reporters

Sheath provides reporters for terminal output, machine-readable output, CI annotations, and coding agents. Select one with the --format option.

#Available Reporters

Select a reporter based on where you want to use the results.

Sheath writes reports to standard output and operational messages to standard error. Machine-readable formats therefore remain parseable during fixing, statistics collection, and parallel fallback. Write a report directly to a file when another job or tool will consume it:

php artisan sheath:lint --format=json --output=sheath-report.json

#Compatibility

The json reporter is the versioned machine contract: read schemaVersion and ignore unknown fields. The agent envelope and the Checkstyle element and attribute meanings are supported but unversioned, so they may gain fields, and no format guarantees object-key, file, or violation ordering. The stylish, compact, unix, and github layouts are presentation and may change in any release, though their path, severity, position, message, and rule-ID meanings do not.

Every format uses forward slashes and shows project files relative to the project root. Files outside the project are shown with absolute paths. In the line-oriented stylish, compact, and unix formats, tab, line-feed, and carriage-return characters in a file path are rendered as \\t, \\n, and \\r; other ASCII controls use \\xNN. This keeps one finding from creating extra records or terminal control sequences. Structured formats preserve representable path characters through their native escaping.

#Using Reporters

# Default (stylish)
php artisan sheath:lint

# Select a reporter
php artisan sheath:lint --format=json

# Save to file
php artisan sheath:lint --format=checkstyle --output=report.xml

#Stylish (Default)

Human-readable format with severity symbols, file grouping, and a summary, ideal for terminal output.

php artisan sheath:lint --format=stylish

#Output Example

resources/views/dashboard.blade.php
  ✗ 12:5  Images must have an alt attribute for accessibility. Use alt="" for decorative images.                           a11y-alt-text
  ⚠ 24:9  Buttons should have an explicit type attribute (button, submit, or reset) to prevent accidental form submission  best-practices-button-type
  ✗ 45:1  Form is missing @csrf directive. Add @csrf for CSRF protection.                                                  security-csrf-field

  2 errors, 1 warning

resources/views/profile.blade.php
  ⚠ 8:3  Void element <br> should not use a trailing slash.  best-practices-self-closing-void-elements

  0 errors, 1 warning

============================================================
Total: 2 errors, 2 warnings in 2 files
2 problems can be automatically fixed

#Features

• Grouped by file, with a count under each
• Severity symbols: ✗ error (red), ⚠ warning (yellow), ℹ info (cyan) -- coloured on a capable terminal, plain under --no-ansi or when piped
• Line:column positioning
• Rule ID for reference, dimmed so the message stays the focus
• Full messages with columns sized to the file, so nothing is truncated
• Summary with fixable count; info counts join the per-file and total lines whenever a run has info findings, and an info-only run still prints the totals block and the fix hint

#JSON

Machine-readable JSON format for programmatic processing.

php artisan sheath:lint --format=json

#Output Example

{
  "schemaVersion": 1,
  "results": [
    {
      "filePath": "resources/views/dashboard.blade.php",
      "violations": [
        {
          "ruleId": "a11y-alt-text",
          "message": "Images must have an alt attribute for accessibility. Use alt=\"\" for decorative images.",
          "severity": "error",
          "filePath": "resources/views/dashboard.blade.php",
          "offset": 120,
          "line": 12,
          "column": 5,
          "endOffset": 154,
          "endLine": 12,
          "endColumn": 35,
          "fix": null,
          "fixAvailable": false,
          "dangerousFix": false
        }
      ],
      "hasParseErrors": false,
      "errorCount": 1,
      "warningCount": 0,
      "infoCount": 0,
      "fixableCount": 0
    }
  ],
  "summary": {
    "errors": 1,
    "warnings": 0,
    "infos": 0,
    "files": 1,
    "fixable": 0
  }
}

This example is representative, not exhaustive. The JSON structure mirrors LintResult::toArray() and Violation::toArray(). A filePath inside the project is project-relative. An explicitly linted file outside the project uses a normalized absolute path because it has no project-relative representation. summary.files counts files with violations, not files linted.

Fix objects may include an integer priority when several zero-width fixes share an offset. Lower-priority replacement text is emitted first; omitted priority is equivalent to 0.

fix.replacement is normally the literal UTF-8 replacement text. If a fix must preserve malformed source bytes that JSON cannot represent, the value is base64 encoded and the fix also contains "replacementEncoding": "base64". Consumers must decode that value before applying the byte-offset fix.

schemaVersion versions the top-level CLI JSON contract. Version 1 is the v1 contract; consumers should ignore unknown fields so compatible additions do not break them. Sheath will increment the version before making an incompatible structural change.

Offsets are zero-based byte offsets into the source. Ranges are half-open: offset is included and endOffset is the first byte after the finding. Lines and columns are one-based. For valid UTF-8, columns count Unicode code points; if a source line contains invalid UTF-8 before a finding, Sheath accepts the file and falls back to a byte column for that position. endLine/endColumn identify that same exclusive endpoint.

Both single-file and multi-file output from the json format use this versioned envelope; the former contains exactly one entry in results, including for a clean file.

#Compact

Minimal single-line format for quick scanning.

php artisan sheath:lint --format=compact

#Output Example

resources/views/dashboard.blade.php: line 12, col 5, ERROR - Images must have an alt attribute for accessibility. Use alt="" for decorative images. (a11y-alt-text)
resources/views/dashboard.blade.php: line 24, col 9, WARNING - Buttons should have an explicit type attribute (button, submit, or reset) to prevent accidental form submission (best-practices-button-type)
resources/views/profile.blade.php: line 8, col 3, WARNING - Void element <br> should not use a trailing slash. (best-practices-self-closing-void-elements)

#Format

file: line N, col N, SEVERITY - message (ruleId)

#Unix

Unix grep-style format for piping to other tools.

php artisan sheath:lint --format=unix

#Output Example

resources/views/dashboard.blade.php:12:5: Images must have an alt attribute for accessibility. Use alt="" for decorative images. [a11y-alt-text]
resources/views/dashboard.blade.php:24:9: Buttons should have an explicit type attribute (button, submit, or reset) to prevent accidental form submission [best-practices-button-type]
resources/views/profile.blade.php:8:3: Void element <br> should not use a trailing slash. [best-practices-self-closing-void-elements]

#Format

file:line:column: message [ruleId]

#Checkstyle

Sheath emits the conventional Checkstyle XML document shape. Use this reporter only when the receiving tool explicitly accepts Checkstyle XML; it is not a SonarQube generic issue report, GitLab code quality report, or another vendor-specific schema. Characters that XML 1.0 cannot represent are replaced with U+FFFD in file paths, rule IDs, and messages so malformed template input cannot corrupt the report document. XML whitespace controls are emitted as character references, so an XML parser recovers the original tab, line-feed, or carriage return instead of normalizing it to a space.

php artisan sheath:lint --format=checkstyle --output=sheath-report.xml

#Output Example

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
  <file name="resources/views/dashboard.blade.php">
    <error line="12" column="5" severity="error"
           message="Images must have an alt attribute for accessibility. Use alt=&quot;&quot; for decorative images."
           source="a11y-alt-text"/>
    <error line="24" column="9" severity="warning"
           message="Buttons should have an explicit type attribute (button, submit, or reset) to prevent accidental form submission"
           source="best-practices-button-type"/>
  </file>
  <file name="resources/views/profile.blade.php">
    <error line="8" column="3" severity="warning"
           message="Void element &lt;br&gt; should not use a trailing slash."
           source="best-practices-self-closing-void-elements"/>
  </file>
</checkstyle>

#GitHub

GitHub Actions workflow commands for inline annotations.

php artisan sheath:lint --format=github

#Output Example

::error file=resources/views/dashboard.blade.php,line=12,col=5::Images must have an alt attribute for accessibility. Use alt="" for decorative images. [a11y-alt-text]
::warning file=resources/views/dashboard.blade.php,line=24,col=9::Buttons should have an explicit type attribute (button, submit, or reset) to prevent accidental form submission [best-practices-button-type]
::warning file=resources/views/profile.blade.php,line=8,col=3::Void element <br> should not use a trailing slash. [best-practices-self-closing-void-elements]

#Features

• Emits GitHub error, warning, and notice workflow commands
• Associates each annotation with a file, line, and column
• Includes the rule ID in the annotation message

#GitHub Actions Example

- name: Lint Blade templates
  run: php artisan sheath:lint --format=github

#Agent

Everything on one line of JSON, for a coding agent reading output as tokens rather than looking at a terminal.

php artisan sheath:lint --format=agent

#Output Example

A clean run says so and nothing more:

{"tool":"sheath","result":"passed"}

Otherwise, wrapped here for reading but emitted on a single line:

{
  "tool": "sheath",
  "result": "fail",
  "errors": 2,
  "warnings": 1,
  "infos": 0,
  "fixable": 2,
  "files": [
    {
      "path": "resources/views/dashboard.blade.php",
      "violations": [
        {"line": 12, "col": 5, "severity": "error", "rule": "a11y-alt-text", "message": "Images must have an alt attribute for accessibility. Use alt=\"\" for decorative images."},
        {"line": 24, "col": 9, "severity": "warning", "rule": "best-practices-button-type", "message": "Buttons should have an explicit type attribute (button, submit, or reset) to prevent accidental form submission", "fixable": true}
      ]
    }
  ]
}

#Format

The envelope uses tool, result, and files fields so a coding agent can consume a concise result without parsing terminal presentation.

• result reflects the findings: errors fail, while warnings fail only when they exceed --max-warnings. A clean run reports passed; non-failing findings keep their counts and files list.
• I/O failures exit with status 1 regardless of result. Use the process exit code to determine whether the command succeeded.
• path on each file entry follows the same convention as every other format: project-relative inside the project and normalized absolute outside it.
• errors, warnings, infos and fixable are the totals the run already computed, so they need not be summed back out of files.
• fixable on a violation is true when a safe fix is available, and the string "dangerous" when applying it also needs --dangerous. The key is absent when there is no fix. Overlapping or conflicting fixes can still be skipped during a fix run.

#See Also

• CLI Usage: command options
• CI/CD Integration: pipeline setup