.. 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)