luplo.core.checks
=================

.. py:module:: luplo.core.checks

.. autoapi-nested-parse::

   Rule pack — deterministic checks over the item graph.

   A **check** is a read-only query that produces :class:`Finding` rows.
   Rules are intentionally narrow and SQL-only: no LLM, no external
   network calls. Hallucination plus compliance context is a liability,
   not a feature — see the roadmap page for the explicit rejection.

   Each rule lives in its own file under :mod:`luplo.core.checks.rules`
   and is registered via :data:`RULES`. Surface layers (CLI, MCP, HTTP)
   call :func:`run_checks` to run the enabled set and aggregate.

   Disabling a rule per-project is opt-in: add the rule's :attr:`Rule.name`
   to the ``[checks] disabled_rules`` list in ``.luplo``. The rule's code
   is unchanged; the runner just skips it.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /api/luplo/core/checks/registry/index
   /api/luplo/core/checks/rules/index
   /api/luplo/core/checks/runner/index
   /api/luplo/core/checks/types/index


Attributes
----------

.. autoapisummary::

   luplo.core.checks.RULES
   luplo.core.checks.Severity


Classes
-------

.. autoapisummary::

   luplo.core.checks.Finding
   luplo.core.checks.Rule


Functions
---------

.. autoapisummary::

   luplo.core.checks.run_checks


Package Contents
----------------

.. py:data:: RULES
   :type:  dict[str, luplo.core.checks.types.Rule]

.. py:function:: run_checks(conn: psycopg.AsyncConnection[Any], project_id: str, *, rule_names: collections.abc.Iterable[str] | None = None, disabled: collections.abc.Iterable[str] = ()) -> list[luplo.core.checks.types.Finding]
   :async:


   Run the selected rules and return their aggregated findings.

   :param conn: Async psycopg connection.
   :param project_id: Project scope — every rule is project-local.
   :param rule_names: If given, run only these rules (by ``Rule.name``).
                      Unknown names raise :class:`ValidationError` before any SQL
                      runs. When ``None``, run every registered rule.
   :param disabled: Names to skip (typically from
                    ``.luplo [checks] disabled_rules``). Silently no-ops when a
                    disabled name also appears in *rule_names* — the caller's
                    explicit ``--rule X`` does not override the project-level
                    disable.

   :returns: Flat list of :class:`Finding` ordered first by the rule order in
             :data:`luplo.core.checks.registry.RULES`, then by whatever order
             the rule's own SQL returned.


.. py:class:: Finding

   One hit from a rule run.


   .. py:attribute:: rule_name
      :type:  str


   .. py:attribute:: severity
      :type:  Severity


   .. py:attribute:: message
      :type:  str


   .. py:attribute:: item_id
      :type:  str | None
      :value: None



   .. py:attribute:: details
      :type:  dict[str, Any]


.. py:class:: Rule

   A registered check.


   .. py:attribute:: name
      :type:  str

      Stable identifier used by ``--rule`` and ``disabled_rules``.


   .. py:attribute:: default_severity
      :type:  Severity

      Severity applied to every finding this rule produces.


   .. py:attribute:: description
      :type:  str

      One-line human explanation. Shown by ``lp check --list``.


   .. py:attribute:: check
      :type:  collections.abc.Callable[[psycopg.AsyncConnection[Any], str], collections.abc.Awaitable[list[Finding]]]

      Async callable that takes (connection, project_id) and returns findings.


.. py:data:: Severity

   Severity levels, ordered by decreasing blocking weight.

   - ``error`` — blocks ``lp check`` exit code (non-zero on any).
   - ``warn`` — surfaced but does not block.
   - ``info`` — advisory, hidden from default CLI output.