File Formats
============

.. _config-toml:

``config.toml``
---------------

General and output configuration. Located at ``.sawmill/config.toml``
(project-level) or ``~/.config/sawmill/config.toml`` (user-level).

.. code-block:: toml

   [general]
   default_plugin = "vivado"    # Plugin name to use by default

   [output]
   color = true                 # Enable coloured output (bool)
   format = "text"              # Default output format (string: text/json/count)

Local config overrides user config with a shallow per-section merge.

.. _suppress-toml:

``suppress.toml``
-----------------

Display suppression rules. Located at ``.sawmill/suppress.toml``.

.. code-block:: toml

   [suppress]
   patterns = [
       "INFO:.*Synthesizing",
       "Phase \\d+ .*Complete",
   ]
   message_ids = [
       "Common 17-55",
       "Vivado 12-1023",
   ]

``patterns``
   List of regex patterns. Messages with ``raw_text`` matching any
   pattern are hidden from display.

``message_ids``
   List of exact message IDs to hide.

Suppressions are display-only --- they do not affect CI pass/fail.

.. _waivers-toml:

``waivers.toml``
----------------

Waiver entries for CI acceptance. Located at ``.sawmill/waivers.toml``.

.. code-block:: toml

   [metadata]
   tool = "vivado"

   [[waiver]]
   message_id = "Vivado 12-3523"
   reason = "Expected warning, reviewed by team"
   author = "engineer@company.com"
   date = "2026-01-15"

   [[waiver]]
   message_id = "Synth 8-6157"
   content_match = "raw"
   content_pattern = "synthesizing module 'top'"
   reason = "Top-level synthesis message"
   author = "engineer@company.com"
   date = "2026-01-15"

   [[waiver]]
   message_id = "DRC RTSTAT-10"
   content_match = "regex"
   content_pattern = "Net .* has no driver"
   reason = "Test stub nets"
   author = "engineer@company.com"
   date = "2026-01-15"

Fields per ``[[waiver]]`` entry:

.. list-table::
   :header-rows: 1
   :widths: 20 10 70

   * - Field
     - Required
     - Description
   * - ``message_id``
     - yes
     - Exact message ID to match.
   * - ``reason``
     - yes
     - Why this message is acceptable.
   * - ``author``
     - yes
     - Who created this waiver.
   * - ``date``
     - yes
     - Creation date (ISO format, e.g. ``2026-01-15``).
   * - ``content_match``
     - no
     - How to interpret ``content_pattern``: ``"raw"`` (substring) or ``"regex"``.
   * - ``content_pattern``
     - no
     - Narrows match beyond ``message_id``. If omitted, matches all instances.

See :doc:`/user-guide/waivers` for matching semantics.

.. _json-report:

JSON report
-----------

Generated by ``--report report.json``. Top-level structure:

``metadata``
   ``log_file`` (string), ``plugin`` (string), ``timestamp`` (ISO-8601),
   ``fail_on_level`` (int).

``exit_code``
   ``0`` = pass, ``1`` = failure.

``summary``
   ``total`` (int), ``suppressed`` (int), ``waived`` (int),
   ``by_severity`` (object mapping severity ID to count),
   ``waived_by_severity`` (same shape).

``issues``
   Array of unwaived messages. Each has ``message_id``, ``severity``,
   ``content``, ``line``, ``raw_text``.

``waived``
   Array of waived messages. Each has ``message_id``, ``severity``,
   ``content``, ``line``, ``waiver_message_id``, ``waiver_reason``.

``suppressed``
   Array of display-suppressed messages. Each has ``message_id``,
   ``severity``, ``content``, ``line``, ``raw_text``.

``unused_waivers``
   Array of waivers that matched no messages. Each has ``message_id``,
   ``reason``.