Skip to content
View as Markdown

Write a custom check

This guide shows how to add your own rule to LaNorme as a plugin: a small Python module that registers a check, which LaNorme then discovers and runs alongside the built-ins. Use it to encode a house rule the bundled normes do not cover, your domain vocabulary, a project-specific structural invariant, or any mechanical standard your team agrees on.

You do not fork LaNorme. A check is an ordinary object; you ship it in your own package and point LaNorme at it.

The Check protocol

A check is any object with four members:

  • name (str): a unique identifier, used by --check <name> and in output.
  • description (str): one line describing what the check enforces.
  • rules (list of str): one entry per rule code, each "CODE-001: one line".
  • check(self, scan: Scan) -> CheckResult: scans the tree and returns the findings.

check receives the lanorme.scan.Scan for the pass: scan.root is the directory being checked (a Path), and the scan also carries the subtree scope, the exclude globs in force, the project's source_root and the run's parse cache. LaNorme activates the scan around the call, so the readers in lanorme.sources and lanorme.discovery prune what it prunes; a check reads scan.root and calls them. check returns a CheckResult carrying two lists of Violation: violations (hard findings that fail the build) and warnings (advisories that report but keep the exit code at 0).

from lanorme import CheckResult, Violation
from lanorme.scan import Scan


class MyCheck:
    name = "my_check"
    description = "What it enforces, in one line"
    rules = ["MYCODE-001: the rule, in one line"]

    def check(self, scan: Scan) -> CheckResult:
        violations: list[Violation] = []
        # inspect files under scan.root
        return CheckResult.from_findings(check=self.name, violations=violations)

CheckResult.from_findings(check=, violations=, warnings=) builds the result from the two lists, both empty by default. Its status is derived from them, never stored: any violation is FAIL, otherwise any warning is WARN, otherwise PASS, so the header LaNorme prints always agrees with the findings. CheckResult(check=, violations=, warnings=) builds the same result; its status= argument is deprecated and ignored, with a DeprecationWarning.

The previous entry point, run(self, *, src_root: str), is deprecated. A check that defines run and no check still runs: LaNorme calls run with the scan active and src_root set to str(scan.root), and emits a DeprecationWarning once per check class. Implement check(scan) before the old entry point is removed.

A Violation records where and what:

Violation(
    file="src/utils.py",  # path, relative to scan.root
    line=12,  # 1-based line, or 0 for a whole-file or path finding
    rule="MYCODE-001",  # the bare code; the runner adds the description
    message="What is wrong here",
    fix="What to do about it",
)

rule may be the bare code ("MYCODE-001") or the full declared string ("MYCODE-001: the rule, in one line"). The runner expands a bare code to the string the check declares in rules, so every output carries the description and you spell it once per check.

Three optional fields give the finding's extent: column and end_column (0-based, as ast counts them) and end_line (1-based, inclusive). Fill all three from the node you report with **locate(node):

from lanorme.sources import locate

Violation(
    file=module.relative,
    line=node.lineno,
    rule="MYCODE-001",
    message="What is wrong here",
    fix="What to do about it",
    **locate(node),
)

A node without positions gives None for each. The JSON and ndjson records carry these fields, derive the finding's scope (span, line or file) from them, and the github format turns them into annotation columns. See finding records.

Register the check

Call register() with an instance at import time. That is what makes LaNorme find and run it.

from lanorme import register

register(MyCheck())

Each check needs a name of its own: registering a second, different check under a name already taken raises lanorme.errors.UsageError (exit 2 at the CLI) rather than letting the later one silently replace the earlier. Registering the same instance twice is harmless.

The registered instance is a template. The run never configures or runs it in place: every pass (the whole-tree pass and one per config region) works on a deep copy configured from that pass's config, so settings cannot leak from one region, or one run, into the next. A check must therefore survive copy.deepcopy, which rules out holding an open file or a lock on the instance.

A check that reads configuration may also implement configure(self, *, settings), which receives its [tool.lanorme.<name>] table before the run. See Configuring a check below.

Read sources through lanorme.sources

Read Python files through lanorme.sources, never Path.rglob. The module walks the tree with the same pruning as discovery (the built-in never-source directories such as .venv, node_modules, __pycache__, dist and build, plus the user's exclude globs, so an excluded subtree is never read), decodes each file the way the interpreter does (a UTF-8 BOM and a coding: cookie are honoured) and parses it once per run. Every check then receives the same Module, so a run costs one parse per file rather than one per check.

from lanorme.sources import iter_parsed_modules

for module in iter_parsed_modules(scan.root):
    module.path  # Path to the *.py file
    module.relative  # its path relative to scan.root, posix style
    module.source  # the decoded text
    module.lines  # the text split into lines
    module.tree  # the parsed ast.Module
    module.comments  # every # comment, read by tokenize
    module.docstrings  # every module, class and function docstring
    module.imports  # every module an import statement names

lines, comments, docstrings and imports are views computed on first use and shared with every other check that reads the same file in the run, so reach for them rather than tokenising or walking the file again:

  • module.comments holds one Comment per # comment (line, column, token as written, text without the #, and standalone when it has the line to itself). A # inside a string is never a comment. On the rare source the tokeniser gives up on part-way, the tuple holds the comments before that point and module.has_complete_comments is false.
  • module.docstrings holds one Docstring per documented module, class and function, in ast.walk order: owner (the node), node (the string constant), text as written, line, and clean(), which equals ast.get_docstring(owner). module.find_docstring(node) looks one up by its owner.
  • module.imports holds one ImportedModule per module named: import a, b gives two, from x import y, z gives one for x holding both aliases. Each has node, module ("" for from . import y), aliases, level and is_from.

iter_parsed_modules(root) yields only the files that parse. iter_modules(root) yields those same Module objects and, for a file the parser rejects, overflows on, or cannot read, an UnparseableFile (path, relative, reason) so the check can decide what to do. A check that reports such files emits the advisory <PREFIX>-000 notice through build_unparseable_notice:

from lanorme.sources import Module, iter_modules, build_unparseable_notice

for item in iter_modules(scan.root):
    if isinstance(item, Module):
        ...  # analyse item.tree
    else:
        warnings.append(build_unparseable_notice(prefix="MYCODE", failure=item))

The notice's rule is MYCODE-000: <reason>, with the reason one of parse error, too deeply nested or unreadable. A -000 code is a notice, not a finding: promotion never escalates it and the baseline never records it. build_skip_notice(prefix=, file=, name=, reason=) builds the same notice for a file the check skips on its own.

Trees are shared with every other check in the run, so a check must never mutate one, or read and ast.parse a file itself. Copy the tree first, or collect what you need without changing nodes.

For files that are not Python, lanorme.discovery.iter_files(root, suffix=".md") walks the tree with the same pruning and returns the paths, sorted.

Walk the tree through module.index

module.index is the file's NodeIndex: every node grouped by type, from one walk of the tree that all checks share. Ask it for the nodes you need instead of calling ast.walk(module.tree):

import ast

for module in iter_parsed_modules(scan.root):
    for call in module.index.collect(ast.Call):
        ...  # every call in the file
    for function in module.index.functions:
        ...  # every def and async def, nested ones included

collect(*types) returns the nodes whose exact type is one of types. functions is collect(ast.FunctionDef, ast.AsyncFunctionDef). Both keep ast.walk order, so a check that switches from a walk reports the same findings in the same order.

Read names off nodes through lanorme.astnames

lanorme.astnames answers the small questions many checks ask of a node:

  • find_decorator_leaf(decorator) gives the name a decorator resolves to (@app.route("/") gives route, @abc.abstractmethod gives abstractmethod), or None. Calls are looked through unless calls=False; subscripts too with subscripts=True. list_decorator_leaves(node) gives one per decorator of a function or class.
  • build_attr_chain(node) gives the dotted path an attribute spells (hashlib.md5 gives ("hashlib", "md5")), or ().
  • read_str_constant(node) gives the value of a string literal, or None.

The run context: lanorme.scan.Scan

iter_files, iter_dirs, iter_modules and parse_module honour the run's exclude globs and subtree scope and share one parse cache, but a check never passes these around: they belong to the current Scan, the one check receives, which LaNorme activates around the call. A check reads scan.root and calls the functions. To run a check by hand under the same confinement, hand lanorme.run_check the scan; it activates the scan around the call and isolates an exception as a RUN-000 notice, as a full run does:

from lanorme import run_check
from lanorme.scan import Scan

result = run_check(MyCheck(), scan=Scan(root=project_root, excludes=("vendor/*",)))

run_check(check, src_root=str(path)) runs it over that path under whatever scan is active, and lanorme.run_all takes the same two arguments for every registered check. A direct MyCheck().check(scan) runs under the scan in force, not the one passed, so activate it first: with scan.activate():. Scan.restrict(scope=..., excludes=...) gives a scan confined to a subtree with more globs, sharing the parse cache. With no scan active, the whole tree is walked with no excludes. lanorme.scan.get_current_scan() returns the scan in force.

The current scan lives in a contextvars.ContextVar, so it follows the context. Whether a new thread starts in its creator's context depends on the Python version and build (Python 3.14 adds the thread_inherit_context flag), and a worker outside it walks the whole tree with no excludes and another parse cache. A check that hands work to threads should run each task in a copy of its own context:

import contextvars
from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor() as pool:
    futures = [pool.submit(contextvars.copy_context().run, scan_part, part) for part in parts]

Take one copy_context() per task: a context can be entered by only one thread at a time.

Conventions

These conventions keep a custom check consistent with the built-ins. The same rules apply whether the check ships inside LaNorme or as your plugin.

  • One category prefix per check. A check owns a single rule-code family (MYCODE-001, MYCODE-002, ...). Codes are the public surface: people put them in select, ignore, and per-file-ignores, so treat them as stable.
  • Hard findings in violations, advisories in warnings. A violations entry fails the run (exit code 1); a warnings entry reports but leaves the exit code at 0. Opinionated or stylistic rules belong in warnings, so a user can promote them to errors when they choose (see promote).
  • Fill the finding lists; never set a status. The status is derived from violations and warnings, so the header LaNorme prints ([FAIL], [WARN], [PASS]) always agrees with the findings.
  • Cross-file checks declare scope = "tree". If a finding depends on comparing or aggregating across files, set the class attribute scope = "tree". The default "file" scope lets a check run once per config region under per-directory configuration; a tree-scoped check runs once at the project root so a finding split across two regions is not missed. A region pass still starts at the project root and sees only that region's files, so module.relative keeps the full path (tests/helpers.py, not helpers.py) and a path-based exemption such as tests/ holds inside a nested region.
  • Default off when opinionated or broad. A rule that fires often on ordinary code should ship default-off behind an enabled flag, so users opt in (see Configuring a check).
  • Raise UsageError for a user's mistake. A setting that makes no sense is not a crash. Raise lanorme.errors.ConfigError (a UsageError that also carries the offending key and the source table) from configure, or UsageError for any other mistake of the user's, with the message the user needs; the CLI prints it as ERROR: ... and exits 2. A UsageError raised from check is not hidden in a RUN-000 notice either. Never print to stderr or call sys.exit from a check.

A check must never let an exception escape check. LaNorme isolates a check that raises and reports it as a RUN-000 warning whose message carries the exception type and text, so one bug cannot sink the whole run. A clean check should not rely on that safety net.

A worked example

This check fails when a module is named exactly utils.py, on the house rule that every module should be named after what it does. LaNorme ships the same rule built in as NAMING-010 in the opt-in naming_clean_code check; it stays here as the example because it is the smallest complete check.

# house_rules.py
from __future__ import annotations

from lanorme import CheckResult, Violation, register
from lanorme.scan import Scan
from lanorme.sources import iter_parsed_modules


class NoUtilsModule:
    name = "no_utils_module"
    description = "Modules must have a meaningful name, not 'utils'"
    rules = ["HOUSE-001: Module must not be named 'utils.py'"]

    def check(self, scan: Scan) -> CheckResult:
        violations: list[Violation] = []
        for module in iter_parsed_modules(scan.root):
            if module.path.name == "utils.py":
                violations.append(
                    Violation(
                        file=module.relative,
                        line=0,
                        rule="HOUSE-001",
                        message="Module named 'utils.py' has no clear responsibility",
                        fix="Rename it after what it actually does",
                    )
                )
        return CheckResult.from_findings(check=self.name, violations=violations)


register(NoUtilsModule())

With house_rules.py importable (on sys.path or installed), load it with --plugin and run it:

$ lanorme check src/ --plugin house_rules --check no_utils_module
[FAIL] no_utils_module
  VIOLATION: utils.py:0 — Module named 'utils.py' has no clear responsibility
    Rule: HOUSE-001: Module must not be named 'utils.py'
    Fix: Rename it after what it actually does
--- no_utils_module: 1 violations, 0 warnings ---

Summary: 1 checks — 0 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.

The check emitted the bare code HOUSE-001; the report shows the full rule string from rules.

The exit code is 1. Rename or remove the file and the run is clean:

$ lanorme check src/ --plugin house_rules --check no_utils_module
All 1 checks passed.

The exit code is 0.

Note

--plugin is repeatable (--plugin a --plugin b), not comma-separated. Pass the dotted module path, for example --plugin myproject.checks.house_rules.

Make it an advisory

To report without failing the build, collect the findings in a warnings list instead and pass it as warnings:

return CheckResult.from_findings(check=self.name, warnings=warnings)

The run then exits 0, the check shows as [WARN] and each finding is labelled WARNING: rather than VIOLATION:. A user who wants it to fail the build can escalate the code with promote:

$ lanorme check src/ --plugin house_rules --promote HOUSE-001

That turns the advisory into a build-failing error (exit code 1). promote = ["ALL"] escalates every advisory at once. A code in promote must be one a loaded check declares, so load the plugin in the same run; otherwise the run exits 2 with 'promote' names no known rule code or category.

A rule that asks a question about a design choice rather than reporting a defect can stay advisory under ALL (and so under the strict profile). Declare its code in an advisory_codes class attribute; only a promote entry naming the code or its category escalates it then:

from typing import ClassVar


class HouseRulesCheck:
    advisory_codes: ClassVar[frozenset[str]] = frozenset({"HOUSE-001"})

Loading the plugin

LaNorme has three ways to load a plugin module so its register() call runs. Choose one.

Name it in config

List the module under plugins in [tool.lanorme]. LaNorme imports each named module before the run, so the check self-registers:

[tool.lanorme]
plugins = ["myproject.checks.house_rules"]

This is the usual choice for a check that lives in your own repository. The plugins reference documents the key.

Ship it under the entry-point group

A distributable package can advertise its check module under the lanorme.checks entry-point group. Any environment that installs the package then has the check available with no per-project config:

# in the plugin package's pyproject.toml
[project.entry-points."lanorme.checks"]
house-rules = "myproject.checks.house_rules"

The entry-point value is the dotted module path; LaNorme imports it on every run.

Pass it on the command line

Use --plugin for a one-off run, a quick experiment, or CI wiring that prefers explicit flags over config:

$ lanorme check src/ --plugin myproject.checks.house_rules

CLI flags override config, so --plugin adds to whatever plugins already lists.

Configuring a check

To accept settings from a [tool.lanorme.<name>] table, implement an optional configure method. LaNorme hands it the table (a dict) before the run.

Read each value through the typed readers in lanorme.checkconfig: is_flag_set for a boolean, read_int, read_str and read_str_list. Each returns the value or rejects the wrong type (a quoted number, a float or true for an integer, a bare string for a list). Declare the keys configure reads in settings_keys. LaNorme then refuses a key outside that set, and --show-config lists the set on the check's keys: line. Both mistakes exit 2 and name the table and the key.

A reader rejects a value by raising lanorme.checkconfig.SettingError (a TypeError), and a configure that validates a value itself raises TypeError or ValueError; LaNorme reports any of these as a ConfigError naming the table and, where it can isolate it, the key. Any other exception out of configure (an AttributeError, a KeyError) is a bug in the check and surfaces as one, not as the user's mistake.

# stray_extensions.py
from dataclasses import dataclass, field
from typing import ClassVar

from lanorme import CheckResult, Violation, register
from lanorme.checkconfig import is_flag_set, read_str_list
from lanorme.discovery import iter_files
from lanorme.scan import Scan


@dataclass
class StrayExtensions:
    name: str = "stray_extensions"
    description: str = "Flag unwanted file extensions in the tree"
    enabled: bool = False
    extensions: tuple[str, ...] = ()
    rules: list[str] = field(default_factory=lambda: ["HOUSE-002: Unwanted file extension"])
    settings_keys: ClassVar[frozenset[str]] = frozenset({"enabled", "extensions"})

    def configure(self, *, settings: dict[str, object]) -> None:
        self.enabled = is_flag_set(settings=settings, key="enabled", default=self.enabled)
        self.extensions = read_str_list(
            settings=settings, key="extensions", default=self.extensions
        )

    def check(self, scan: Scan) -> CheckResult:
        if not self.enabled:
            return CheckResult.from_findings(check=self.name)
        root = scan.root
        warnings = [
            Violation(
                file=path.relative_to(root).as_posix(),
                line=0,
                rule="HOUSE-002",
                message=f"File with unwanted extension {suffix}",
                fix="Delete it, or keep it out of the repository",
            )
            for suffix in self.extensions
            for path in iter_files(root, suffix=suffix)
        ]
        return CheckResult.from_findings(check=self.name, warnings=warnings)


register(StrayExtensions())

A user then configures it under the check's own table, named after self.name:

[tool.lanorme.stray_extensions]
enabled = true
extensions = [".zip", ".tmp"]

With stray_extensions.py importable and src/old.zip and src/notes.tmp in the tree:

$ lanorme check . --plugin stray_extensions --check stray_extensions
[WARN] stray_extensions
  WARNING: src/old.zip:0 — File with unwanted extension .zip
    Rule: HOUSE-002: Unwanted file extension
    Fix: Delete it, or keep it out of the repository
  WARNING: src/notes.tmp:0 — File with unwanted extension .tmp
    Rule: HOUSE-002: Unwanted file extension
    Fix: Delete it, or keep it out of the repository
--- stray_extensions: 0 violations, 2 warnings ---

Summary: 1 checks — 0 passed, 1 warned, 0 failed.
Findings: 0 errors to fix, 2 advisory warnings.

A mistyped value or key stops the run before any check starts:

$ cat pyproject.toml
[tool.lanorme.stray_extensions]
enabled = true
extension = [".zip"]
$ lanorme check . --plugin stray_extensions
ERROR: unknown key in [tool.lanorme.stray_extensions]: 'extension'.
  Keys this check reads: enabled, extensions.
$ echo $?
2

An opt-in check defaults enabled to false and returns an empty result (CheckResult.from_findings(check=self.name)) until the table sets enabled = true. That keeps a broad or opinionated rule inert on a project that has not asked for it. The concise summary counts such checks on its Opt-in checks not enabled: line, and --check on one prints a note saying it is off.

When only some of a check's rules wait on a setting, declare them in a class attribute opt_in_rules: frozenset[str] and, to name the setting, an opt_in_settings: dict[str, str] from code to key. lanorme rule CODE then reports the rule as opt-in via <key> = true in [tool.lanorme.<check>] instead of on by default, as comments does for PROSE-001 (em_dash).

For a mistake configure cannot express as a type, such as two settings that contradict each other, raise lanorme.errors.ConfigError with the key and source it concerns. The CLI reports it the same way, with exit 2.

Verify it is loaded

Run the check and confirm it executed. --output-format full shows passing checks too, so a loaded check appears even when it found nothing:

$ lanorme check . --plugin myproject.checks.house_rules --output-format full

For a check loaded via config or the entry-point group, drop the --plugin flag: plain lanorme check . --output-format full lists it once it is registered. Seeing your check in that output (a [PASS] line when it is clean) is the reliable signal that the plugin loaded. For machine-readable output while developing, use --output-format ndjson (one finding per line) or --output-format json (one object per check).

lanorme rules is a narrower check. It lists only rules registered through the lanorme.checks entry-point group, so it surfaces a plugin shipped that way but not one loaded via [tool.lanorme] plugins or --plugin. The rules command also takes no --plugin flag.

  • Configuration reference: every [tool.lanorme] key, including plugins, select, ignore, and promote.
  • Rule reference: what each built-in rule catches and how to configure it; a model for documenting your own.