.. index:: single: linter_reporter
.. _linter_reporter/0:

.. rst-class:: right

**object**

``linter_reporter``
===================

Intercepts compiler linter warnings and caches them as machine-readable diagnostics.

| **Availability:** 
|    ``logtalk_load(linter_reporter(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:2
| **Date:** 2026-07-19

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Imports:**
|    ``public`` :ref:`tool_diagnostics_common <tool_diagnostics_common/0>`
|    ``public`` :ref:`tutor_explanations <tutor_explanations/0>`
|    ``public`` :ref:`options <options/0>`
| **Provides:**
|    :ref:`logtalk::message_hook/4 <logtalk/0::message_hook/4>`
| **Uses:**
|    :ref:`list <list/0>`
|    :ref:`logtalk <logtalk/0>`
|    :ref:`os <os/0>`
|    :ref:`term_io <term_io/0>`
|    :ref:`type <type/0>`
|    :ref:`user <user/0>`

| **Remarks:**

   - Usage: Load this tool before compiling code to be checked by the built-in linter. Call ``enable/0-1`` before compiling code, ``disable/0`` when finished collecting warnings, and then query the cached warnings using either the legacy warning predicates or the diagnostics protocol predicates. The standalone ``sarif`` tool can generate SARIF reports by querying these diagnostics.
   - Diagnostics targets: The diagnostics predicates accept the targets ``all``, ``entity(Entity)``, ``file(File)``, ``directory(Directory)``, ``rdirectory(Directory)``, ``library(Library)``, and ``rlibrary(Library)``. These targets simply filter the cached diagnostics collected in the current warning collection session.

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`tool_diagnostics_protocol/0::diagnostic/2`  :ref:`tool_diagnostics_protocol/0::diagnostic/3`  :ref:`tool_diagnostics_protocol/0::diagnostic_rule/5`  :ref:`tool_diagnostics_protocol/0::diagnostic_rules/1`  :ref:`tool_diagnostics_protocol/0::diagnostic_target/1`  :ref:`tool_diagnostics_protocol/0::diagnostics/2`  :ref:`tool_diagnostics_protocol/0::diagnostics/3`  :ref:`tool_diagnostics_protocol/0::diagnostics_preflight/2`  :ref:`tool_diagnostics_protocol/0::diagnostics_preflight/3`  :ref:`tool_diagnostics_protocol/0::diagnostics_summary/2`  :ref:`tool_diagnostics_protocol/0::diagnostics_summary/3`  :ref:`tool_diagnostics_protocol/0::diagnostics_tool/5`  :ref:`tutor_explanations/0::explain//1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: enable/0
.. _linter_reporter/0::enable/0:

``enable/0``
^^^^^^^^^^^^

Enables warning collection and starts a fresh warning collection session using the default options.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``enable`` - ``one``


------------

.. index:: enable/1
.. _linter_reporter/0::enable/1:

``enable/1``
^^^^^^^^^^^^

Enables warning collection and starts a fresh warning collection session using the given options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``enable(Options)``
| **Mode and number of proofs:**
|    ``enable(+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is not a valid option:
|        ``domain_error(option,Option)``


------------

.. index:: disable/0
.. _linter_reporter/0::disable/0:

``disable/0``
^^^^^^^^^^^^^

Disables warning collection while preserving the cached warnings for later querying.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``disable`` - ``one``


------------

.. index:: reset/0
.. _linter_reporter/0::reset/0:

``reset/0``
^^^^^^^^^^^

Clears all cached warnings collected in the current session.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``reset`` - ``one``


------------

.. index:: warning/1
.. _linter_reporter/0::warning/1:

``warning/1``
^^^^^^^^^^^^^

Enumerates normalized linter warnings collected in the current session.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``warning(Warning)``
| **Mode and number of proofs:**
|    ``warning(-compound)`` - ``zero_or_more``


------------

.. index:: warnings/1
.. _linter_reporter/0::warnings/1:

``warnings/1``
^^^^^^^^^^^^^^

Returns the collected normalized linter warnings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``warnings(Warnings)``
| **Mode and number of proofs:**
|    ``warnings(-list(compound))`` - ``one``


------------

.. index:: summary/1
.. _linter_reporter/0::summary/1:

``summary/1``
^^^^^^^^^^^^^

Returns a machine-readable summary for the collected linter warnings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``summary(Summary)``
| **Mode and number of proofs:**
|    ``summary(-compound)`` - ``one``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

.. index:: enabled_/0
.. _linter_reporter/0::enabled_/0:

``enabled_/0``
^^^^^^^^^^^^^^

True when warning collection is enabled.

| **Compilation flags:**
|    ``dynamic``

| **Mode and number of proofs:**
|    ``enabled_`` - ``zero_or_one``


------------

.. index:: warning_sequence_/1
.. _linter_reporter/0::warning_sequence_/1:

``warning_sequence_/1``
^^^^^^^^^^^^^^^^^^^^^^^

Stores the last assigned warning sequence number.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``warning_sequence_(Sequence)``
| **Mode and number of proofs:**
|    ``warning_sequence_(-integer)`` - ``zero_or_one``


------------

.. index:: recorded_warning_/4
.. _linter_reporter/0::recorded_warning_/4:

``recorded_warning_/4``
^^^^^^^^^^^^^^^^^^^^^^^

Caches collected warnings together with their sequence number, flag, normalized message term, and printed message tokens.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``recorded_warning_(Sequence,Flag,Message,Tokens)``
| **Mode and number of proofs:**
|    ``recorded_warning_(?integer,?atom,?compound,?list(compound))`` - ``zero_or_more``


------------

.. index:: collection_options_/1
.. _linter_reporter/0::collection_options_/1:

``collection_options_/1``
^^^^^^^^^^^^^^^^^^^^^^^^^

Stores the merged options for the current warning collection session.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``collection_options_(Options)``
| **Mode and number of proofs:**
|    ``collection_options_(-list(compound))`` - ``zero_or_one``


------------

Operators
---------

(none)

