Skip to content
View as Markdown

Configure which checks run

This how-to gives recipes for narrowing what LaNorme runs and silencing the noise you have decided to accept, from selecting a subset of rules down to silencing a single line. Each recipe gives the goal, the [tool.lanorme] config, the equivalent command-line flag where one exists, and a verified example.

A finding has to survive every stage below to be reported, applied in this order:

flowchart LR
    A[select] --> B[ignore]
    B --> C[exclude]
    C --> D[per-file-ignores]
    D --> E[inline ignore]
    E --> F[reported]

Config is read from [tool.lanorme] in pyproject.toml, or from a lanorme.toml / .lanorme.toml file. LaNorme walks up from the scan path to the outermost config, and a nested config cascades over the ones above it; see config discovery. Command-line flags override config for a single run. For the full key list and types, see the configuration reference. Rule codes and categories are listed by lanorme rules; per-check settings live in the rule reference.

Note

The recipes below use the pyproject.toml layout. In a standalone lanorme.toml / .lanorme.toml the tool.lanorme prefix is dropped: top-level scalar keys go bare (select = [...]) and sub-tables lose the prefix too, so [tool.lanorme.per-file-ignores] becomes [per-file-ignores]. A prefixed header in a lanorme.toml is a configuration error (exit 2), as is any top-level key that is neither a run key nor the name of a check. See the config discovery note in the CLI reference.

Targets are rule codes (EVAL-001), categories (the part before the dash: CMT, SECRETPY), or ALL. lanorme rules lists every code. A target that names no known code or category, in a flag, in [tool.lanorme] or in per-file-ignores, is a usage error: the run exits 2 and points you at lanorme rules.

$ lanorme check src --select EVAL-01
ERROR: 'select' names no known rule code or category: 'EVAL-01'.
  Run 'lanorme rules' to list every code and category.
$ echo $?
2

Run only some checks

Goal: run a chosen subset and skip everything else.

[tool.lanorme]
select = ["SECRETPY", "EVAL-001"]

Equivalent flag: --select takes a comma-separated list.

$ lanorme check src --select EVAL-001
[FAIL] security_calls
  VIOLATION: pkg/main.py:1 — eval() on a non-literal argument is an RCE primitive
    Rule: EVAL-001: No eval/exec/compile on a non-literal argument
    Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 1 violations, 0 warnings ---

Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).

A category selects every code under it: --select CMT runs every comment rule; --select ALL runs everything enabled. --select takes codes and categories, not check names. To run one check by name, use --check (--check file_limits).

Note

Opt-in checks stay off even when named in select. Enable them first with [tool.lanorme.<check>] enabled = true (for example [tool.lanorme.prose]). See the rule reference.

Skip a rule everywhere

Goal: keep the full run but drop one rule (or one category) you do not want.

[tool.lanorme]
ignore = ["PARAM-001"]

Equivalent flag: --ignore takes a comma-separated list. Here the file_limits check finds a nine-parameter function:

$ lanorme check src --check file_limits
[FAIL] file_limits
  VIOLATION: pkg/wide.py:1 — Function 'build' has parameter count 9 (limit: 8)
    Rule: PARAM-001: Function exceeds the parameter limit
    Fix: Group related parameters into a dataclass or TypedDict
--- file_limits: 1 violations, 0 warnings ---

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

Ignoring PARAM-001 drops it and keeps the rest of the check:

$ lanorme check src --check file_limits --ignore PARAM-001
All 1 checks passed.

--select SIZE,COMPLEXITY narrows a full run to the size and complexity codes the same way, leaving PARAM out.

ignore applies after select, so a rule that is both selected and ignored is skipped.

Exclude paths from the scan

Goal: never walk certain files, such as generated code or migrations.

[tool.lanorme]
exclude = ["**/migrations/*", "generated/*"]

Equivalent flag: --exclude takes a comma-separated list of globs.

Globs match the path relative to the project root. A leading **/ matches a directory at any depth, so **/migrations/* excludes src/pkg/migrations/:

$ lanorme check . --select EVAL-001
[FAIL] security_calls
  VIOLATION: src/pkg/main.py:1 — eval() on a non-literal argument is an RCE primitive
    Rule: EVAL-001: No eval/exec/compile on a non-literal argument
    Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
  VIOLATION: src/pkg/migrations/m.py:1 — eval() on a non-literal argument is an RCE primitive
    Rule: EVAL-001: No eval/exec/compile on a non-literal argument
    Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 2 violations, 0 warnings ---

Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 2 errors to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).

$ lanorme check . --select EVAL-001 --exclude '**/migrations/*'
[FAIL] security_calls
  VIOLATION: src/pkg/main.py:1 — eval() on a non-literal argument is an RCE primitive
    Rule: EVAL-001: No eval/exec/compile on a non-literal argument
    Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 1 violations, 0 warnings ---

Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).

Match the depth you have. To exclude a migrations/ directory sitting at the project root, use migrations/*; the leading **/ form needs a parent segment and will not match a top-level directory.

Naming an excluded path on the command line does not override the glob. With exclude = ["**/migrations/*"] in config, asking for the excluded file checks nothing: the run reports a clean tree and a note on stderr says so.

$ lanorme check src/pkg/migrations/m.py --select EVAL-001
Note: every requested path matches an exclude glob, so nothing was checked. Pass --exclude with another glob to override the configured excludes for one run.
All 31 checks passed.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).

Silence a rule for a path glob

Goal: keep a rule on, but accept it for files matching a glob (for example, allow wide-signature test factories under tests/ to keep PARAM-001).

This is config only; there is no command-line equivalent.

Without any suppression, a nine-parameter factory in tests/factories.py reports PARAM-001:

$ lanorme check . --select PARAM-001
[FAIL] file_limits
  VIOLATION: tests/factories.py:1 — Function 'build' has parameter count 9 (limit: 8)
    Rule: PARAM-001: Function exceeds the parameter limit
    Fix: Group related parameters into a dataclass or TypedDict
--- file_limits: 1 violations, 0 warnings ---

Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).

The key is a glob; the value is a list of codes or categories suppressed for matching files. In pyproject.toml the table carries the tool.lanorme prefix:

[tool.lanorme.per-file-ignores]
"tests/*" = ["PARAM-001"]

In a standalone lanorme.toml / .lanorme.toml the prefix is dropped and the header is bare. The prefixed form is silently ignored there:

[per-file-ignores]
"tests/*" = ["PARAM-001"]

With either form in place, the matching file is no longer reported, and the summary counts what the glob suppressed:

$ lanorme check . --select PARAM-001
All 31 checks passed.
Suppressed: 0 by inline ignores, 1 by per-file-ignores, 0 by the baseline.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).

Globs match paths relative to the project root, and so does a nested region: a tests/lanorme.toml does not change what "tests/*" matches.

Confirm the discovered config and effective per-check settings with lanorme check --show-config.

Silence one line

Goal: accept a single finding in place, at the source line.

This is a source pragma; there is no command-line equivalent. Two directives are read, both on the finding's own line:

  • # noqa suppresses every finding on that line.
  • # noqa: CODE suppresses only that rule code on that line; other findings on the line still report, and a different code does not suppress.
  • # lanorme: ignore and # lanorme: ignore[CODE, CODE] behave the same way, bare or with a bracketed code list.

# noqa is shared with ruff and other linters, so a bare # noqa you add for ruff also silences LaNorme on that line. Reach for # lanorme: ignore[...] when you run both tools and want to silence a LaNorme finding alone: ruff cannot parse the hyphen in a code like TYPE-001, so a shared # noqa: TYPE-001 makes ruff report an invalid directive, while # lanorme: ignore carries no noqa token for ruff to read.

A code in either directive may be an exact code (EVAL-001), a category (CMT), or ALL, matching the other config targets. A finding reported at line 0 is about the whole file (a junk-drawer module, say) and has no line to carry a directive; silence it with per-file-ignores instead.

Given this file checked with --select EVAL-001:

def f():
    x = eval(input())


def g():
    y = eval(input())  # noqa


def h():
    z = eval(input())  # noqa: EVAL-001


def k():
    w = eval(input())  # lanorme: ignore[EVAL-001]


def m():
    v = eval(input())  # noqa: SQL-001

Only lines 2 and 18 are reported. The bare # noqa, the matching # noqa: EVAL-001 and # lanorme: ignore[EVAL-001] suppress their lines. # noqa: SQL-001 names the wrong code and does not silence the eval.

$ lanorme check a.py --select EVAL-001
[FAIL] security_calls
  VIOLATION: a.py:2 — eval() on a non-literal argument is an RCE primitive
    Rule: EVAL-001: No eval/exec/compile on a non-literal argument
    Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
  VIOLATION: a.py:18 — eval() on a non-literal argument is an RCE primitive
    Rule: EVAL-001: No eval/exec/compile on a non-literal argument
    Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 2 violations, 0 warnings ---

Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 2 errors to fix, 0 advisory warnings.
Suppressed: 3 by inline ignores, 0 by per-file-ignores, 0 by the baseline.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).

Tune a check's settings

Goal: change a check's threshold or option, such as the parameter limit.

Each check reads its own table, named after the check. The keys it accepts are in its rule reference section.

[tool.lanorme.file_limits]
param_error = 10

With the limit raised to 10, the nine-parameter factory drops from an error to an advisory warning (it is still past the warning threshold of 5), and the run exits 0.

Every table is validated before the run. A value of the wrong type exits 2 and names the table and the key. That covers a quoted number, a bare string where a list is expected, and a float or true where an integer is expected:

$ cat pyproject.toml
[tool.lanorme.file_limits]
param_error = "10"
$ lanorme check . --select PARAM-001
ERROR: invalid value for [tool.lanorme.file_limits] param_error: 'param_error' must be an integer, got str
  Run 'lanorme check . --show-config' to see the effective settings for every check.

A key the check does not read also exits 2, and the message lists the keys it does read:

$ cat pyproject.toml
[tool.lanorme.file_limits]
param_limit = 10
$ lanorme check . --select PARAM-001
ERROR: unknown key in [tool.lanorme.file_limits]: 'param_limit'.
  Keys this check reads: class_method_warn, complexity_error, complexity_warn, file_error_lines, file_warn_lines, func_error_lines, func_warn_lines, param_error, param_warn.

The top level is strict in the same way: a key that is neither a run key (select, promote, source_root, ...) nor the name of a check exits 2 and lists both, and a [tool.lanorme] table inside a lanorme.toml is refused with a message saying the keys go top level there. See config discovery.

lanorme check --show-config prints each check's effective settings and, on a keys: line under it, the keys its table accepts:

$ lanorme check . --show-config
...
  file_limits        file_warn_lines=300 file_error_lines=500 func_warn_lines=50 func_error_lines=80 class_method_warn=10 complexity_warn=10 complexity_error=15 param_warn=5 param_error=10
                     keys: class_method_warn, complexity_error, complexity_warn, file_error_lines, file_warn_lines, func_error_lines, func_warn_lines, param_error, param_warn
...

Exit codes

lanorme check exits 0 when clean or when only warnings were found, 1 when there are violations, and 2 on a usage or config error. This drives CI: a silenced finding leaves the run clean.

$ lanorme check src --select EVAL-001   # no eval in src
All 31 checks passed.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
$ echo $?
0

See also

  • Configuration reference for every [tool.lanorme] key, including promote, extends, baseline, source_root, and plugins.
  • Rule reference for what each code catches and its per-check settings.