.. index:: single: tool_diagnostics_protocol
.. _tool_diagnostics_protocol/0:

.. rst-class:: right

**protocol**

``tool_diagnostics_protocol``
=============================

Common machine-readable diagnostics protocol for developer tools.

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

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-03-31

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


| **Dependencies:**
|   (none)


| **Remarks:**

   - Targets and options: Implementing objects should enumerate supported targets using ``diagnostic_target/1`` and predicates taking an ``Options`` argument must accept ``explanations(Boolean)``.
   - Tool metadata predicate: Tool metadata is exposed using ``diagnostics_tool/5``.
   - Rule descriptor predicate: Rule descriptors are exposed using ``diagnostic_rule/5`` and collected in stable order using ``diagnostic_rules/1``.
   - Diagnostic and preflight terms: Findings and analysis prerequisites are represented using ``diagnostic/8`` and ``preflight_issue/7`` terms.
   - Summary term: Summaries are represented using ``diagnostics_summary/5`` terms with supporting breakdown and count terms.

| **Inherited public predicates:**
|    (none)

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

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

.. index:: diagnostics_tool/5
.. _tool_diagnostics_protocol/0::diagnostics_tool/5:

``diagnostics_tool/5``
^^^^^^^^^^^^^^^^^^^^^^

Returns tool metadata.

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

| **Template:**
|    ``diagnostics_tool(Id,Name,Version,InformationURI,Properties)``
| **Mode and number of proofs:**
|    ``diagnostics_tool(?atom,?atom,?atom,?atom,?list(compound))`` - ``zero_or_one``


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

.. index:: diagnostic_target/1
.. _tool_diagnostics_protocol/0::diagnostic_target/1:

``diagnostic_target/1``
^^^^^^^^^^^^^^^^^^^^^^^

Enumerates supported diagnostics target patterns.

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

| **Template:**
|    ``diagnostic_target(Target)``
| **Mode and number of proofs:**
|    ``diagnostic_target(?nonvar)`` - ``zero_or_more``


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

.. index:: diagnostic_rule/5
.. _tool_diagnostics_protocol/0::diagnostic_rule/5:

``diagnostic_rule/5``
^^^^^^^^^^^^^^^^^^^^^

Enumerates diagnostic rule descriptors.

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

| **Template:**
|    ``diagnostic_rule(RuleId,ShortDescription,FullDescription,DefaultSeverity,Properties)``
| **Mode and number of proofs:**
|    ``diagnostic_rule(?atom,?atom,?atom,?atom,?list(compound))`` - ``zero_or_more``


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

.. index:: diagnostic_rules/1
.. _tool_diagnostics_protocol/0::diagnostic_rules/1:

``diagnostic_rules/1``
^^^^^^^^^^^^^^^^^^^^^^

Returns all supported diagnostic rule descriptors in a stable order.

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

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


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

.. index:: diagnostic/3
.. _tool_diagnostics_protocol/0::diagnostic/3:

``diagnostic/3``
^^^^^^^^^^^^^^^^

Enumerates, by backtracking, diagnostics for a target using the given options. Diagnostics are returned using terms of the form ``diagnostic(RuleId, Severity, Confidence, Message, Context, File, Lines, Properties)``. All implementations must accept the common option ``explanations(Boolean)``.

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

| **Template:**
|    ``diagnostic(Target,Diagnostic,Options)``
| **Mode and number of proofs:**
|    ``diagnostic(+nonvar,-compound,+list(compound))`` - ``zero_or_more``


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

.. index:: diagnostic/2
.. _tool_diagnostics_protocol/0::diagnostic/2:

``diagnostic/2``
^^^^^^^^^^^^^^^^

Enumerates, by backtracking, diagnostics for a target using default options. Diagnostics are returned using terms of the form ``diagnostic(RuleId, Severity, Confidence, Message, Context, File, Lines, Properties)``.

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

| **Template:**
|    ``diagnostic(Target,Diagnostic)``
| **Mode and number of proofs:**
|    ``diagnostic(+nonvar,-compound)`` - ``zero_or_more``


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

.. index:: diagnostics/3
.. _tool_diagnostics_protocol/0::diagnostics/3:

``diagnostics/3``
^^^^^^^^^^^^^^^^^

Returns an ordered set of diagnostics for a target using the given options. Diagnostics are returned using terms of the form ``diagnostic(RuleId, Severity, Confidence, Message, Context, File, Lines, Properties)``. All implementations must accept the common option ``explanations(Boolean)``.

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

| **Template:**
|    ``diagnostics(Target,Diagnostics,Options)``
| **Mode and number of proofs:**
|    ``diagnostics(+nonvar,-list(compound),+list(compound))`` - ``one``


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

.. index:: diagnostics/2
.. _tool_diagnostics_protocol/0::diagnostics/2:

``diagnostics/2``
^^^^^^^^^^^^^^^^^

Returns an ordered set of diagnostics for a target using default options. Diagnostics are returned using terms of the form ``diagnostic(RuleId, Severity, Confidence, Message, Context, File, Lines, Properties)``.

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

| **Template:**
|    ``diagnostics(Target,Diagnostics)``
| **Mode and number of proofs:**
|    ``diagnostics(+nonvar,-list(compound))`` - ``one``


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

.. index:: diagnostics_summary/3
.. _tool_diagnostics_protocol/0::diagnostics_summary/3:

``diagnostics_summary/3``
^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a machine-readable summary for a target using the given options. The summary counts diagnostics only and does not include preflight issues. All implementations must accept the common option ``explanations(Boolean)``.

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

| **Template:**
|    ``diagnostics_summary(Target,Summary,Options)``
| **Mode and number of proofs:**
|    ``diagnostics_summary(+nonvar,-compound,+list(compound))`` - ``one``


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

.. index:: diagnostics_summary/2
.. _tool_diagnostics_protocol/0::diagnostics_summary/2:

``diagnostics_summary/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a machine-readable summary for a target using default options. The summary counts diagnostics only and does not include preflight issues.

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

| **Template:**
|    ``diagnostics_summary(Target,Summary)``
| **Mode and number of proofs:**
|    ``diagnostics_summary(+nonvar,-compound)`` - ``one``


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

.. index:: diagnostics_preflight/3
.. _tool_diagnostics_protocol/0::diagnostics_preflight/3:

``diagnostics_preflight/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns an ordered set of machine-readable preflight issues for a target using the given options. Preflight issues are returned using terms of the form ``preflight_issue(Id, Severity, Message, Context, File, Lines, Properties)``. All implementations must accept the common option ``explanations(Boolean)``.

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

| **Template:**
|    ``diagnostics_preflight(Target,Issues,Options)``
| **Mode and number of proofs:**
|    ``diagnostics_preflight(+nonvar,-list(compound),+list(compound))`` - ``one``


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

.. index:: diagnostics_preflight/2
.. _tool_diagnostics_protocol/0::diagnostics_preflight/2:

``diagnostics_preflight/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns an ordered set of machine-readable preflight issues for a target using default options. Preflight issues are returned using terms of the form ``preflight_issue(Id, Severity, Message, Context, File, Lines, Properties)``.

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

| **Template:**
|    ``diagnostics_preflight(Target,Issues)``
| **Mode and number of proofs:**
|    ``diagnostics_preflight(+nonvar,-list(compound))`` - ``one``


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

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

(none)

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

(none)

Operators
---------

(none)

