computer-playbook/docs/contributing/actions/testing/suppression.md

Suppression Markers 🚫

The unified # noqa / # nocheck syntax that suppresses individual checks across the infinito-nexus test suite.

You MUST use these markers only when the check genuinely does not apply. You MUST NOT use them to silence legitimate issues.

Grammar 📐

A suppression marker is a comment carrying one or more rule keys:

<comment-prefix> (noqa|nocheck): <rule>(, <rule>)*

Rules:

• noqa and nocheck are synonyms. By convention, use noqa for code-level lints (analogous to flake8 / ruff) and nocheck for repository-content checks (URLs, image versions, file size, run-once schema). Either keyword works for any rule; the test does not enforce which one is used.
• The keyword is matched case-insensitively.
• <rule> is a kebab-case identifier from the catalog below.
• Multiple rules MAY be combined on one comment, comma-separated: # noqa: shared, email.

Accepted comment prefixes (so the marker fits any file format that the test scans):

Prefix	Use in
#	Python, YAML, shell, conf, INI, …
//	JS, JSONC, …
{# … #}	Jinja2 templates
<!-- … -->	HTML, Markdown

Implementation: utils/annotations/suppress.py.

Position semantics 📍

The placement rule is per check. The catalog column "Position" uses these labels:

• same line: the marker MUST be on the same line as the construct it suppresses.
• same line / span: the marker MUST be on the construct's own line or, for multi-line call expressions, any physical line spanned by that call.
• line above: the marker MUST be on the immediately preceding non-empty line. Blank lines between the marker and the construct break the association.
• same or above: either of the above is accepted.
• comment block above: the marker may sit on any line in a contiguous comment block above the construct (no blank line between marker and construct).
• head (first 30 lines): the marker MAY appear anywhere in the first 30 lines of the file. Used for file-level opt-outs that should stay visible at the top of the file.
• anywhere: the marker may appear on any line of the file. Used for whole-file opt-outs whose semantics legitimately apply to the entire file.

Catalog 📚

Rule	Position	Affected test	Effect
url	same or above	test_urls_reachable.py	Skips probing the literal HTTP(S) URL. Use for CDN roots and API base URLs that return 4xx without a path.
docker-version	line above	test_image_versions.py	Skips the live version-update warning for that image's version: key.
direct-yaml	same line / span	test_no_direct_yaml_calls.py	Allows the marked yaml.safe_load / safe_dump call to bypass utils.cache.yaml.
redundant-bool-ternary	same line	test_no_redundant_bool_patterns.py	Allows the redundant | bool | ternary('true','false') pattern on the marked line — only when a consumer really requires the lowercase true/false tokens.
redundant-bool-comparison	same line	test_no_redundant_bool_patterns.py	Allows ... | bool == True/False/true/false on the marked line — only when a real tri-state guard is intended (e.g. distinguishing None from False).
shared	comment block above	test_service_shared_consistency.py	Marks a service whose enabled: true legitimately does not require shared: true.
email	line above	test_web_app_email_integration.py	Suppresses the missing-email-integration warning when paired with enabled: false and shared: false.
file-size	head (first 30 lines)	test_python_file_size.py	Opts the entire .py file out of the 500-line cap.
project-walk	same line / span	test_no_raw_project_walk.py	Allows a raw Path.rglob, os.walk, or glob.glob call when the walk is intentionally outside the cached project-tree helper contract.
cache-read	same line / span	test_no_uncached_file_reads.py	Allows a raw Path.read_text / Path.read_bytes call in a tests/lint/ test when the read is intentionally outside the LRU-cached utils.cache.files.read_text contract.
run-once	anywhere	test_run_once_tags.py, test_schema.py	Marks a role's tasks/main.yml as intentionally re-runnable; skips both the run-once tag check and the suffix check.
run-once-suffix	same line	test_schema.py	Allows a single when: item to reference a run_once_<other> flag whose suffix differs from the current role.
raw-docker	same or above; head (first 30 lines)	test_no_raw_docker.py	Marks a single line or a whole file under roles/ as legitimately calling docker / docker compose / docker-compose directly. The check is scoped to roles/; bootstrap scripts and CI workflows outside roles/ are not scanned and need no marker.

Examples 💡

url, on the line carrying the literal URL or on the line above it:

ensure_proxy_repo raw raw-packagist "$(... https://repo.packagist.org/ ...)"  # nocheck: url

# nocheck: url
api_base_url: "https://example.org/v1"

docker-version, directly above a version: key:

service_x:
  # nocheck: docker-version
  version: "4.5"

direct-yaml, anywhere on the call's physical line or on any line spanned by the multi-line call:

data = yaml.safe_load(text)  # noqa: direct-yaml

shared, somewhere in the comment block immediately above a service key:

# This service is inherently role-local.
# noqa: shared
my_local_service:
  enabled: true

email, directly above the email: block, paired with both flags false:

# noqa: email
email:
  enabled: false
  shared: false

file-size, at the top of a long Python file:

"""Module docstring."""
# nocheck: file-size  (single-host orchestration script ships as one file)

project-walk, on the raw walk call or on any line spanned by the call:

for path in temp_dir.rglob("*"):  # noqa: project-walk
    ...

Use project-walk only for scans that genuinely do not fit utils.cache.files.iter_project_files, such as temporary directories, .git metadata, or a deliberately tiny fixed path probe. Broad scans of the repository tree SHOULD use the cached helpers instead.

cache-read, on the raw read call or on any line spanned by the call:

text = tmp_path.read_text()  # noqa: cache-read  (synthetic fixture written above)

Use cache-read only when the file legitimately does not belong to the project-tree LRU cache — e.g. a tempdir written and read inside the same test, a file outside the repository root, or an in-memory io.StringIO- backed Path. Reads of project files (under roles/, tasks/, docs/, tests/, etc.) MUST go through utils.cache.files.read_text so the LRU cache is shared across the pytest session.

run-once, at the top of a role's tasks/main.yml:

# nocheck: run-once

- name: ...

run-once-suffix, on the exact when: list-item line:

when:
  - run_once_svc_db_openldap is not defined   # noqa: run-once-suffix

raw-docker, per-line on a single role-task line that legitimately calls docker directly (e.g. a bootstrap step that runs before the container wrapper is on the path):

- name: "Bootstrap engine before the wrapper exists"
  ansible.builtin.command: docker info  # noqa: raw-docker

raw-docker, file-level at the top of a role's bundled shell script that legitimately drives the engine directly:

#!/usr/bin/env bash
# nocheck: raw-docker. Runs from sys-svc-container's installer before the wrapper symlink lands.
docker buildx build ...

Tool-Native noqa Codes 🧹

Some Python files also use Ruff-compatible uppercase # noqa codes. These codes are handled by Ruff and related Python linters, not by utils/annotations/suppress.py. They MAY appear in Python files when the local exception is intentional and clear from context.

Code	Tool meaning	Typical allowed use in this repository
BLE001	Blind exception caught	Narrow command-wrapper boundaries that must convert any underlying failure into a domain-specific error.
E402	Module import not at top	Tests that MUST adjust sys.path or load fixtures before importing the module under test.
E731	Lambda assigned to variable	Small test-local callbacks or path formatters where a named function would add noise.
F401	Imported but unused	Re-export modules or import-probe tests where import success is the assertion.
SLF001	Private member access	Test-only introspection of parser or object internals when the public surface does not expose the needed state.

Adding a new rule 🆕

1. Pick a kebab-case <rule> identifier.
2. Decide which position semantic from the list above fits the check.
3. Use the is_suppressed_at / is_suppressed_in_head / is_suppressed_anywhere helpers from utils/annotations/suppress.py in your test. Do NOT roll a new regex.
4. Add the rule to the catalog table on this page.