mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-08 11:46:35 +00:00
kevinveenbirkenbachandClaude Opus 4.7
587a3a1796
Replace per-key `compose_container_name` lookup with a generic
`compose_only(key, value)` SPOT that emits `key: "<value>"` only in
compose mode and nothing in swarm. Same gating logic now serves
container_name (157 call sites) and pull_policy (17 call sites)
without duplicate plugin code.
Why this consolidation:
- The earlier `build-key` lint rule was misdirected. Swarm tolerates
`build:` with a harmless warning when `image:` is pre-pushed (via
the existing handlers/swarm_registry_push.py flow in
roles/sys-svc-compose). The actual swarm-rejected key is
`pull_policy:` ("Additional property pull_policy is not allowed"),
and 10 templates were silently broken because they declared inline
`pull_policy: never` outside the existing `{% if DEPLOYMENT_MODE
\!= 'swarm' %}` gate in roles/sys-svc-container/templates/build.yml.j2.
- A single generic lookup is cleaner than N per-key wrappers when
the gating logic is identical (emit-key-or-nothing).
Lint changes in tests/lint/ansible/jinja/test_mode_incompatible_keys.py:
- New `pull-policy-key` rule, regex `^\s*pull_policy\s*:`, remediation
points at compose_only.
- Existing `container-name` rule keeps its raw-key regex; remediation
now also points at compose_only.
- Broken-split / broken-embed regexes rekeyed on the `compose_only`
lookup name (was `compose_container_name`).
- `build-key` rule and its 12 nocheck annotations across templates
removed.
Coordinated changes:
- 86 templates rewritten (157 container_name calls migrated;
17 inline pull_policy lines replaced).
- 1 redundant `{% if DEPLOYMENT_MODE \!= 'swarm' %}` guard dropped in
build.yml.j2 (the lookup self-gates).
- 12 unit tests pin the compose_only contract.
- Catalog (suppression.md) updated: `pull-policy-key` row added,
`container-name` row remediation updated.
- Old `plugins/lookup/compose_container_name.py` and its test module
deleted.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
102 lines
25 KiB
Markdown
102 lines
25 KiB
Markdown
# 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](../../../../tests/lint/filesystem/python/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](../../../../utils/annotations/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](../../../../tests/external/repository/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](../../../../tests/external/update/docker/test_image_versions.py), [test_semver_pinning.py](../../../../tests/lint/ansible/services/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](../../../../tests/external/update/repository/test_repository_versions.py), [test_semver_pinning.py](../../../../tests/lint/ansible/services/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](../../../../tests/lint/repository/yaml/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](../../../../tests/lint/filesystem/python/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](../../../../tests/lint/filesystem/python/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](../../../../tests/lint/ansible/services/test_service_shared_consistency.py) | Marks a service whose `enabled: true` does not require `shared: true`. |
|
|
| `email` | line above | [test_email.py](../../../../tests/lint/ansible/roles/web-app/integration/test_email.py) | Suppresses the missing-email-integration warning. Pair with `enabled: false` and `shared: false`. |
|
|
| `logout` | line above | [test_logout_dashboard.py](../../../../tests/lint/ansible/roles/web-app/integration/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](../../../../tests/lint/ansible/roles/web-app/integration/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](../../../../tests/lint/ansible/roles/web-app/integration/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](../../../../tests/lint/repository/structure/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](../../../../tests/lint/filesystem/python/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](../../../../tests/lint/filesystem/python/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](../../../../tests/lint/ansible/modules/test_run_once_tags.py), [test_schema.py](../../../../tests/integration/roles/run_once/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](../../../../tests/integration/roles/run_once/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](../../../../tests/integration/infrastructure/docker/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](../../../../tests/lint/repository/network/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](../../../../tests/integration/roles/meta/services/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](../../../../tests/integration/roles/meta/services/prometheus/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](../../../../tests/integration/roles/meta/services/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](../../../../tests/integration/roles/meta/variants/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](../../../../tests/integration/roles/meta/variants/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/](../../../../tests/integration/ansible/lookups/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](../../../../tests/lint/ansible/variables/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](../../../../tests/lint/filesystem/python/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](../../../../tests/lint/repository/network/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](../../../../tests/lint/repository/yaml/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](../../../../tests/lint/filesystem/python/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](../../../../tests/lint/ansible/roles/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](../../../../tests/integration/roles/playwright/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](../../../../tests/integration/roles/playwright/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](../../../../tests/lint/repository/dependencies/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](../../../../tests/lint/repository/network/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`). |
|
|
| `container-name` | same or above | [test_mode_incompatible_keys.py](../../../../tests/lint/ansible/jinja/test_mode_incompatible_keys.py) | Allows a raw `container_name:` key in a `roles/*/templates/**/*.j2` template. Default path: route through the generic `compose_only` lookup (`{{ lookup('compose_only', 'container_name', NAME) }}`) so swarm-mode replicas do not collide on the static name. |
|
|
| `pull-policy-key` | same or above | [test_mode_incompatible_keys.py](../../../../tests/lint/ansible/jinja/test_mode_incompatible_keys.py) | Allows a raw `pull_policy:` key in a `roles/*/templates/**/*.j2` template. Default path: route through the generic `compose_only` lookup (`{{ lookup('compose_only', 'pull_policy', 'never') }}`) so swarm does not reject the compose-only extension with "Additional property pull_policy is not allowed". |
|
|
| `restart-key` | same or above | [test_mode_incompatible_keys.py](../../../../tests/lint/ansible/jinja/test_mode_incompatible_keys.py) | Allows a raw `restart:` key in a `roles/*/templates/**/*.j2` template. Default path: route through the `compose_restart` lookup so swarm-mode does not silently drop the operator's `docker_restart_policy`. |
|
|
|
|
## Tool-Native `noqa` Codes 🧹
|
|
|
|
Some Python files use Ruff-compatible uppercase `# noqa` codes. Ruff and related Python linters handle these, not [suppress.py](../../../../utils/annotations/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](../../../../utils/annotations/suppress.py) in your test. Do NOT roll a new regex.
|
|
4. Add the rule to the catalog table on this page.
|