Development
===========

Code structure
--------------

The tool is implemented as a set of reviewers, each with its own
focus. The reviewers keep track of their comments as the LaTeX file is
processed line by line.
Once the entire file has passed, all diagnostics are printed to the
console, referencing line numbers.
A summary is also outputted at the end.
As the reviewers are independent of one another, adding new ones
does not break existing features.

Reviewer implementations are located in ``source/reviewers/``. All inherit
from the base class in ``source/reviewers/reviewer.py``, and a central
rule registry is in ``source/reviewers/rules.py``.

Rule identity
-------------

Every diagnostic refers to one immutable ``Rule`` in the central registry.
The registry contains the error code, name, message template, severity,
and documentation path. A ``Diagnostic`` adds the context for one
occurrence: source filename, line, and the rendered message.

Reviewer prefixes:

* ``Reviewer_Inthis`` uses ``INT``.
* ``Reviewer_Casing`` uses ``CAS``.
* ``Reviewer_Unsure`` uses ``UNS``.
* ``Reviewer_RefLabel`` uses ``REF``.
* ``Reviewer_Figure`` uses ``FIG``.
* ``Reviewer_ChkTeX`` uses ``CHK``.

Each reviewer owns the numeric suffixes in its prefix. For example,
``CAS001`` is the casing rule and ``FIG003`` is the missing-figure-label
rule. Native ChkTeX diagnostics use ``CHK001`` through ``CHK899`` with the
Native ChkTeX diagnostics use ``CHK001`` through ``CHK899`` with the
native ChkTeX number preserved. Native numbers at or above 900 are shifted
into a disjoint range. TeXact's ChkTeX lifecycle rules use ``CHK901`` through
``CHK904`` so the two sources cannot collide.

Rule documentation is indexed at ``docs/rules/index.md``. Each TeXact rule
has its own Markdown page under ``docs/rules/`` with sections for what it
detects, why the issue matters, and a LaTeX example. When adding a rule, add
its registry entry, use the returned named rule handle when creating
diagnostics, add its dedicated page to the hidden rule toctree, and add tests.
Never reuse a published code.

Adding features
---------------

All reviewers inherit from the same base class, *Reviewer*, and
implement a set of methods: ``process_line``, ``get_comments``,
``get_summary``, ``get_status``, and ``get_name``. ``get_comments``
returns ``Diagnostic`` objects linked to registry ``Rule`` objects.

Use a named ``Rule`` handle from ``source/reviewers/rules.py`` and
call its ``render_message`` method for dynamic values. Add a test that checks
the registry metadata, the diagnostic location, and the rendered code in CLI
output.
Adding a feature involves either modifying an existing reviewer
or adding a new one.
The easiest way to get started is by studying one of the existing
classes, e.g. ``Reviewer_Unsure``. The main file, ``texact``, must be
updated to include any new reviewer.
Options to the command-line interface and the parsing of the configuration
file can be added as well.