# `linter_reporter`

This tool intercepts compiler linter warnings and caches them as machine-readable diagnostics. These diagnostics can be queried directly or serialized as SARIF using the standalone `sarif` tool.

## API documentation

This tool API documentation is available at:

../../apis/library_index.html#linter_reporter

## Loading

Load the tool before loading the code to be checked:

    | ?- logtalk_load(linter_reporter(loader)).
    ...

Enable collecting linter warnings data using default options:

    | ?- linter_reporter::enable.
    true.

Or using explicit options:

    | ?- linter_reporter::enable([explanations(true)]).
    true.

Load the code for which you want diagnostics collected:

    | ?- logtalk_load(my_application(loader)).
    ...

Disable further collecting of linter warnings:

    | ?- linter_reporter::disable.
    true.

Query the cached diagnostics directly:

    | ?- linter_reporter::diagnostics(all, Diagnostics).
    ...

Warnings originating in an included file are not always file-scoped. When the `include/1` directive appears inside an entity, the diagnostic context can be that entity; otherwise the context is typically the included file.

Or generate a SARIF report using the standalone `sarif` tool:

    | ?- logtalk_load(sarif(loader)).
    ...

    | ?- sarif::generate(linter_reporter, all, file('./linter_warnings.sarif'), []).
    true.

## Testing

To test this tool, load the `tester.lgt` file:

    | ?- logtalk_load(linter_reporter(tester)).

The test suite reuses `errors` example files to exercise representative built-in linter warnings and validates both the diagnostics API and standalone SARIF generation in explanation-disabled and explanation-enabled configurations.

## Usage

Load the tool, call `enable/0-1` before compiling the code to be checked, call `disable/0` when warning collection is finished, and then query the cached warnings using either the legacy warning predicates or the diagnostics protocol predicates. To generate SARIF from the cached diagnostics, load the standalone `sarif` tool and call `sarif::generate(linter_reporter, all, file('./linter_warnings.sarif'), []).`

## Options

- `explanations(Boolean)` Boolean option accepted by `enable/1`. When set to `true` (default is `false`), the tool enriches warnings with explanations from the `tutor_explanations` category provided by the `tutor` tool.