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>)*

noqa and nocheck are case-insensitive synonyms in the parser. Every project rule MUST use nocheck: because # noqa: <code> is also parsed by ruff as a flake8 directive and warns on non-flake8 keys. Reserve noqa: for real flake8 / ruff codes (E402, F401, …). test_noqa_only_ruff_codes.py hard-rejects # noqa: <code> whose codes do not match [A-Z]+\d+.

<rule> is a kebab-case identifier from the catalog below. Multiple rules MAY be combined comma-separated.

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

Implementation: suppress.py.

Position semantics 📍

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

Label	Meaning
same line	Marker MUST be on the construct's line.
same line / span	Marker MUST be on the construct's line or any physical line spanned by a multi-line call.
line above	Marker MUST be on the immediately preceding non-empty line. Blank lines break the association.
same or above	Either of the above is accepted.
comment block above	Marker MAY sit on any line of a contiguous comment block above the construct. No blank line between marker and construct.
head (first 30 lines)	Marker MAY appear anywhere in the first 30 lines of the file. For file-level opt-outs that stay visible at the top.
anywhere	Marker MAY appear on any line of the file. For whole-file opt-outs.

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 4xx without a path.
docker-version	same or above	test_image_versions.py, test_semver_pinning.py	Skips both the live version-update warning and the non-semver-pin lint for that image's version: key.
repository-version	same or above	test_repository_versions.py, test_semver_pinning.py	Skips both the live ref-update warning and the non-semver-pin lint for that entity's ref: key.
direct-yaml	same line / span	test_no_direct_calls.py	Allows the marked yaml.safe_load / safe_dump call to bypass utils.cache.yaml. MUST use nocheck:, not noqa:.
redundant-bool-ternary	same line	test_no_redundant_bool_patterns.py	Allows the redundant | bool | ternary('true','false') pattern when a consumer requires the lowercase tokens.
redundant-bool-comparison	same line	test_no_redundant_bool_patterns.py	Allows ... | bool == True/False/true/false when a real tri-state guard is intended (distinguishing None from False).
shared	comment block above	test_service_shared_consistency.py	Marks a service whose enabled: true does not require shared: true.
email	line above	test_email.py	Suppresses the missing-email-integration warning. Pair with enabled: false and shared: false.
logout	line above	test_logout_dashboard.py	Opts a web-app-* role out of the universal-logout integration. Marker MUST be directly above logout:. Pair with enabled: false and shared: false.
dashboard	line above	test_logout_dashboard.py	Opts a web-app-* role out of the dashboard tile integration. Same shape as logout.
sso	line above	test_sso.py	Opts the role's unified services.sso block out. Declares "no login flow"; paired with enabled: false + 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 outside the utils.cache.files.iter_project_files contract.
cache-read	same line / span	test_no_uncached_file_reads.py	Allows a raw Path.read_text / Path.read_bytes call in tests/lint/ 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.
hardcoded-dns-resolver	same or above	test_no_hardcoded_dns_resolvers.py	Marks a line that needs a literal IP from NETWORK_PUBLIC_DNS_RESOLVERS where the substitution point cannot consume the variable (CoreDNS non-Jinja templates, host-bootstrap shell, doc examples).
dynamic-flag	same line OR comment block above key	test_dynamic_flags.py	Marks a roles/*/meta/services.yml flag whose value stays literal. Per-flag (same line) for databases. Block-level (comment block above) when both flags stay literal.
native-metrics	comment block above	test_native_metrics_contract.py	Marks a role whose services.prometheus.native_metrics.enabled and templates/prometheus.yml.j2 presence are intentionally inconsistent. Reserved for prepared-but-default-off scrape fragments (operator opt-in).
variants-static-override	same line	test_variants_no_static_override.py	Allows a roles/*/meta/variants.yml leaf override of an attribute whose base value in meta/services.yml is a static literal. Place on the override line in variants.yml. Use only when the consumer chain is provably immune to the variant-merge propagation gap; the default is to make the base value dynamic via "{{ '<role>' in group_names }}".
variants-services-match	same or above	test_services_match.py	Allows a roles/*/meta/variants.yml services.<key> entry to reference a service key that is NOT declared as a top-level entry in meta/services.yml. Reserved for resolver-only matrix hooks (typically on invokable infrastructure roles) whose variant entries pin the round's companion topology via service-key flags the resolver maps to provider roles, with no real consumer contract in the base meta.
variants-auth-isolation	same or above	test_auth_isolation.py	Exempts an auth-isolated variant entry in roles/*/meta/variants.yml (one that enables exactly one of LDAP / OIDC / OAuth2) from the rule that every non-auth service-key in the role's variant union must be pinned to literal false. Place on the leading - services: line of the variant or on the line above. Use only when the broader closure is intentional.
lookup-config-path	same or above	config/	Skips a single lookup('config', …) call from path-validation passes. Use when the call resolves against runtime-only state, typically self-referential roles.
unused-var	same or above	test_role_and_group_vars_used.py	Exempts a top-level key in roles/<role>/{vars,defaults}/main.yml or group_vars/**/*.yml from the "must be referenced" check. Use when the consumer is non-YAML/Jinja (Python plugins, external tools).
project-root-import	same or above	test_project_root_import.py	Permits a local PROJECT_ROOT / parents[N] / os.pardir chain. Reserved for __main__.py sys.path bootstrap and standalone scripts under roles/<role>/files/. The marker MUST carry an inline explanation.
domain-spot	same or above	test_domain_primary_spot.py	Marks a line using a <word>.{{ DOMAIN_PRIMARY }} host literal outside the meta SPOT. Reserved for legacy domain cleanups that the canonical SPOT cannot represent.
literal-protocol-lookup	same or above	test_literal_protocol_with_lookup.py	Allows a hardcoded http:// / https:// literal next to a lookup(...) call. Reserved for genuinely fixed protocols (Docker-network upstreams, loopback URLs in CI fixtures).
self-path-reference	same line	test_no_self_path_reference.py	Allows a file to contain its own relative path from the repo root as a string literal. Reserved for load-bearing self-references. Repo-root files are exempt without a marker.
role-file-spot	same or above	test_file_spot.py	Allows a .py file to carry a literal role-file path instead of the matching ROLE_FILE_* constant from utils.roles.mapping. Reserved for tests asserting the constant's value, migration scripts, or doc strings.
playwright-service-flag	comment block above	test_env_services_match.py	Exempts a top-level service in roles/<role>/meta/services.yml from the "must be registered as <NAME>_SERVICE_ENABLED= in templates/playwright.env.j2" check.
playwright-service-gate	same or above	test_spec_env_gates.py	Exempts a <NAME>_SERVICE_ENABLED= line in roles/<role>/templates/playwright.env.j2 from the "must be gated in files/playwright/playwright.spec.js" check.
pkgmgr-deprecated	same or above	test_pkgmgr_deprecated.py	Suppresses the warn-only deprecation notice for include_role / import_role of pkgmgr / pkgmgr-install. The check emits a DeprecationWarning locally and a GitHub Actions ::warning annotation in CI. Prefer pip install <name> or pip install git+<repo>.
deprecated-http-header	same or above	test_no_deprecated_http_security_headers.py	Exempts a deprecated add_header / Header set/add line for X-Frame-Options / X-XSS-Protection / X-Download-Options / X-Permitted-Cross-Domain-Policies. Prefer Content-Security-Policy via the role's meta/server.yml (csp.flags / csp.whitelist).
seaweedfs-required	head (first 30 lines)	test_database_requires_seaweedfs.py	Exempts a database-backed web-app-* role from the requirement to declare a seaweedfs object-store service. Place in the head of roles/<role>/meta/services.yml. Use only when the application genuinely needs no object storage.

Tool-Native noqa Codes 🧹

Some Python files use Ruff-compatible uppercase # noqa codes. Ruff and related Python linters handle these, not suppress.py. They MAY appear when the local exception is intentional and clear from context.

Code	Tool meaning	Typical allowed use
BLE001	Blind exception caught	Narrow command-wrapper boundaries that 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 is_suppressed_at / is_suppressed_in_head / is_suppressed_anywhere from suppress.py in your test. Do NOT roll a new regex.
4. Add the rule to the catalog table on this page.