From 93e1507f86eb0327fc994d8924547ae4abfa0853 Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:15:53 +0000 Subject: [PATCH 1/5] docs(#1427): add CLAUDE.md with project conventions and review preferences Add a CLAUDE.md file documenting project conventions to improve the signal-to-noise ratio of automated review agent findings. Covers: - Project overview (Flask web + Celery worker architecture) - Code style (black, flake8, mypy, yamllint, hadolint settings) - Docstring format (reStructuredText) and license headers - Security patterns (credential redaction via _sanitize_cmd_log and _get_safe_args) - Test conventions (pytest, unittest.mock, fixture patterns) - Review preferences (useful vs. noise findings) - Build/CI configuration (tox environments, pip-tools, migrations) This gives the review agent project-specific context so it can distinguish style findings that matter from those that do not, reducing unaddressed noise findings per review. Closes #1427 Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..e1cdec6df --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,188 @@ +# CLAUDE.md — IIB (IIB Image Builder) + +## Project overview + +IIB is a REST API service for managing operator index container images and bundle images +in the Red Hat container ecosystem. It is a Python 3.12+ application with two layers: + +- **`iib/web/`** — Flask REST API. Handles HTTP requests, authentication (Kerberos via + `flask-login`), input validation, SQLAlchemy models, and database migrations (Alembic). + Entry point: `iib/web/app.py`. +- **`iib/workers/`** — Celery worker layer. Executes long-running build tasks + asynchronously. Orchestrates container tools (`podman`, `buildah`, `opm`, `skopeo`), + interacts with container registries, and manages Git-based FBC (file-based catalog) + workflows. Task entry points are in `iib/workers/tasks/`. +- **`iib/common/`** — Shared utilities (tracing, binary version helpers). + +The web layer validates and enqueues requests; the worker layer executes them. They +communicate through Celery (RabbitMQ) and share the database via the REST API +(`iib/workers/api_utils.py` calls back to the web API to update request state). + +## Code style + +### Formatting and linting + +- **`black`** enforces formatting with `line-length = 100` and + `skip-string-normalization = true` (single quotes preferred over double quotes). +- **`flake8`** enforces PEP 8 with `max-line-length = 100`. The `flake8-docstrings` + plugin is enabled with exemptions for D100, D104, D105. +- **`mypy`** runs with `--ignore-missing-imports` on the `iib/` package. +- **`yamllint`** checks all YAML files (max line length 100, warning level). +- **`hadolint`** lints Dockerfiles with `--failure-threshold warning`. +- **`bandit`** runs static application security testing. + +Run all static checks: `tox -m static` (runs `black`, `flake8`, `yamllint`, `mypy`, +`hadolint`). + +### Docstrings + +Use reStructuredText format: + +```python +""" +Get the IIB build request from the REST API. + +:param int request_id: the ID of the IIB request +:return: the request +:rtype: dict +:raises IIBError: if the HTTP request fails +""" +``` + +### License headers + +Every Python source file starts with `# SPDX-License-Identifier: GPL-3.0-or-later`. + +### Naming conventions + +- Functions that sanitize sensitive data from values use prefixes like `_sanitize_` + (e.g., `_sanitize_cmd_log`) or `_get_safe_` (e.g., `_get_safe_args`). These naming + patterns indicate credential-redaction logic — treat them as security-sensitive. +- Validation helpers use `_is_safe_` prefix (e.g., `_is_safe_operator_package_name`). + +### Import organization + +Standard library imports first, then third-party, then `iib.*` internal imports. +Each group is separated by a blank line. `black` handles ordering within groups. + +## Security patterns + +### Credential redaction + +All subprocess commands that may contain credentials (Git URLs with tokens, registry +auth) must be logged through `_sanitize_cmd_log` (in `iib/workers/tasks/utils.py`), +which strips embedded credentials from URLs before logging. + +API request arguments containing tokens (`cnr_token`, `overwrite_from_index_token`, +`overwrite_target_index_token`, `registry_auths`) are redacted via `_get_safe_args` +(in `iib/web/api_v1.py`) before logging. + +When reviewing or writing code that logs commands or request parameters: +- Never log raw token values or registry auth credentials. +- Always use the existing sanitization helpers rather than ad-hoc redaction. +- Test that log output does not contain credential material. + +### Authentication + +The web API uses Kerberos authentication via `flask-login`. Worker identity is +validated separately. See `iib/web/auth.py` for the authentication setup. + +## Test conventions + +### Structure + +- **`tests/test_web/`** — tests for the Flask web layer. +- **`tests/test_workers/`** — tests for the Celery worker layer. + - **`tests/test_workers/test_tasks/`** — tests for individual build task modules. + +Test files mirror the source structure: `iib/web/api_v1.py` is tested in +`tests/test_web/test_api_v1.py`, `iib/workers/tasks/utils.py` is tested in +`tests/test_workers/test_tasks/test_utils.py`. + +### Patterns + +- Tests use `pytest` with `unittest.mock` for mocking (`@mock.patch` decorators). +- Fixtures are defined in `tests/conftest.py` (app, db, client, auth environments). +- `@pytest.mark.parametrize` is used extensively for testing multiple input + combinations. +- The `app` fixture creates a Flask application context; `db` provides a clean + database per test using SQLite and Alembic migrations. +- D103 (missing docstring) is exempted for all test files. +- Coverage threshold is 90% (`fail_under = 90` in `.coveragerc`). + +### Running tests + +```bash +# Run all tests and static checks +tox + +# Run only unit tests +tox -m test + +# Run only static linters +tox -m static + +# Run a specific test +tox -e py312 tests/test_web/test_api_v1.py::test_add_bundle_invalid_param + +# Run security checks (bandit, safety) +tox -m security +``` + +## Review preferences + +### Findings that are useful + +- Correctness bugs (wrong logic, missing error handling, race conditions). +- Security issues (credential leakage in logs, missing input validation, + authentication bypasses). +- Missing or incorrect test coverage for changed behavior. +- API contract violations (changed response shapes, missing required fields). + +### Findings that are noise for this project + +- **String quoting style**: `black` with `skip-string-normalization = true` means + single quotes are the project convention. Do not flag single-vs-double quote + choices — `black` enforces this automatically. +- **Docstring format preferences**: The project uses reStructuredText style. Do not + suggest switching to Google or NumPy style. +- **Import ordering**: `black` handles this. Do not flag import order. +- **Linked issues in PRs**: Not every PR requires a linked issue. Do not flag + missing issue references as a review finding. +- **Scope bundling**: Cross-cutting changes (e.g., security hardening across + multiple files) are acceptable in a single PR. Do not flag these as scope + bundling unless the changes are genuinely unrelated. +- **Generic naming suggestions** (e.g., rename `x` to `y` for clarity) unless + the name is actively misleading. +- **Pattern inconsistency** across files that predate the change under review. + Only flag inconsistency introduced by the current PR. + +## Build and CI + +### Tox environments + +| Label | Environments | Purpose | +|-------------|-------------------------------------------------|-------------------------| +| `static` | `black`, `flake8`, `yamllint`, `mypy`, `hadolint` | Code style and types | +| `test` | `unit_tests` | Unit tests with coverage | +| `security` | `bandit` | SAST | +| `docs` | `docs` | Sphinx documentation | + +CI runs on every pull request and push to `master` via `.github/workflows/run_tox.yml`. +It tests on Python 3.12 and 3.13. + +### Dependency management + +Dependencies are pinned with hashes via `pip-tools`. Runtime deps are in `setup.py`, +pinned to `requirements.txt`. Test deps are in `requirements-test.in`, pinned to +`requirements-test.txt`. Update with `tox -e pip-compile`. + +### Database migrations + +Use Alembic via Flask-Migrate. Migrations live in `iib/web/migrations/versions/`. +Generate with `tox -e migrate-db `. + +### Docker + +Dockerfiles are in `docker/` — `Dockerfile-api` (web), `Dockerfile-workers` (workers). +Linted by `hadolint` in CI. From 6f810b8f4bf3c6734c0ffaecd18fd57187310065 Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:43:13 +0000 Subject: [PATCH 2/5] fix: address review feedback on CLAUDE.md (#1428) - Clarify "two layers" to "two main layers and a shared utility package" to resolve ambiguity with the three-bullet structure (line 6) - Correct false claim that black handles import ordering; state it is a manual convention with no automated sorter configured (lines 66, 149) - Fix security checks comment from "(bandit, safety)" to "(bandit)" to match the tox security label which only includes bandit (line 128) Disagreements: - design-smell (line 150): noise-list entries for linked issues and scope bundling are legitimate project review preferences, not misplaced process controls - design-smell (AGENTS.md divergence): future coordination concern, not a code fix for this PR Addresses #1428 Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e1cdec6df..338923d85 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,7 +3,8 @@ ## Project overview IIB is a REST API service for managing operator index container images and bundle images -in the Red Hat container ecosystem. It is a Python 3.12+ application with two layers: +in the Red Hat container ecosystem. It is a Python 3.12+ application with two main layers +and a shared utility package: - **`iib/web/`** — Flask REST API. Handles HTTP requests, authentication (Kerberos via `flask-login`), input validation, SQLAlchemy models, and database migrations (Alembic). @@ -63,7 +64,8 @@ Every Python source file starts with `# SPDX-License-Identifier: GPL-3.0-or-late ### Import organization Standard library imports first, then third-party, then `iib.*` internal imports. -Each group is separated by a blank line. `black` handles ordering within groups. +Each group is separated by a blank line. Import ordering is a manual convention +(no automated import sorter is configured). ## Security patterns @@ -125,7 +127,7 @@ tox -m static # Run a specific test tox -e py312 tests/test_web/test_api_v1.py::test_add_bundle_invalid_param -# Run security checks (bandit, safety) +# Run security checks (bandit) tox -m security ``` @@ -146,7 +148,8 @@ tox -m security choices — `black` enforces this automatically. - **Docstring format preferences**: The project uses reStructuredText style. Do not suggest switching to Google or NumPy style. -- **Import ordering**: `black` handles this. Do not flag import order. +- **Import ordering**: Import order follows a manual convention (stdlib → third-party + → `iib.*`). No automated sorter is configured. Do not flag import order. - **Linked issues in PRs**: Not every PR requires a linked issue. Do not flag missing issue references as a review finding. - **Scope bundling**: Cross-cutting changes (e.g., security hardening across From 0ba23cda453c62008da462d9dc7296cad116698d Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:10:28 +0000 Subject: [PATCH 3/5] fix: use title case for CLAUDE.md headings (#1428) Capitalize significant words in all section headings to match the title case convention used in README.md (e.g., Project Overview, Code Style, Running Tests). Disagreements: - protected-path (CLAUDE.md): merge-gate finding only, human approval required, no content change prescribed Addresses #1428 Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 338923d85..8489baea9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md — IIB (IIB Image Builder) -## Project overview +## Project Overview IIB is a REST API service for managing operator index container images and bundle images in the Red Hat container ecosystem. It is a Python 3.12+ application with two main layers @@ -19,9 +19,9 @@ The web layer validates and enqueues requests; the worker layer executes them. T communicate through Celery (RabbitMQ) and share the database via the REST API (`iib/workers/api_utils.py` calls back to the web API to update request state). -## Code style +## Code Style -### Formatting and linting +### Formatting and Linting - **`black`** enforces formatting with `line-length = 100` and `skip-string-normalization = true` (single quotes preferred over double quotes). @@ -50,26 +50,26 @@ Get the IIB build request from the REST API. """ ``` -### License headers +### License Headers Every Python source file starts with `# SPDX-License-Identifier: GPL-3.0-or-later`. -### Naming conventions +### Naming Conventions - Functions that sanitize sensitive data from values use prefixes like `_sanitize_` (e.g., `_sanitize_cmd_log`) or `_get_safe_` (e.g., `_get_safe_args`). These naming patterns indicate credential-redaction logic — treat them as security-sensitive. - Validation helpers use `_is_safe_` prefix (e.g., `_is_safe_operator_package_name`). -### Import organization +### Import Organization Standard library imports first, then third-party, then `iib.*` internal imports. Each group is separated by a blank line. Import ordering is a manual convention (no automated import sorter is configured). -## Security patterns +## Security Patterns -### Credential redaction +### Credential Redaction All subprocess commands that may contain credentials (Git URLs with tokens, registry auth) must be logged through `_sanitize_cmd_log` (in `iib/workers/tasks/utils.py`), @@ -89,7 +89,7 @@ When reviewing or writing code that logs commands or request parameters: The web API uses Kerberos authentication via `flask-login`. Worker identity is validated separately. See `iib/web/auth.py` for the authentication setup. -## Test conventions +## Test Conventions ### Structure @@ -112,7 +112,7 @@ Test files mirror the source structure: `iib/web/api_v1.py` is tested in - D103 (missing docstring) is exempted for all test files. - Coverage threshold is 90% (`fail_under = 90` in `.coveragerc`). -### Running tests +### Running Tests ```bash # Run all tests and static checks @@ -131,9 +131,9 @@ tox -e py312 tests/test_web/test_api_v1.py::test_add_bundle_invalid_param tox -m security ``` -## Review preferences +## Review Preferences -### Findings that are useful +### Findings That Are Useful - Correctness bugs (wrong logic, missing error handling, race conditions). - Security issues (credential leakage in logs, missing input validation, @@ -141,7 +141,7 @@ tox -m security - Missing or incorrect test coverage for changed behavior. - API contract violations (changed response shapes, missing required fields). -### Findings that are noise for this project +### Findings That Are Noise for This Project - **String quoting style**: `black` with `skip-string-normalization = true` means single quotes are the project convention. Do not flag single-vs-double quote @@ -162,7 +162,7 @@ tox -m security ## Build and CI -### Tox environments +### Tox Environments | Label | Environments | Purpose | |-------------|-------------------------------------------------|-------------------------| @@ -174,13 +174,13 @@ tox -m security CI runs on every pull request and push to `master` via `.github/workflows/run_tox.yml`. It tests on Python 3.12 and 3.13. -### Dependency management +### Dependency Management Dependencies are pinned with hashes via `pip-tools`. Runtime deps are in `setup.py`, pinned to `requirements.txt`. Test deps are in `requirements-test.in`, pinned to `requirements-test.txt`. Update with `tox -e pip-compile`. -### Database migrations +### Database Migrations Use Alembic via Flask-Migrate. Migrations live in `iib/web/migrations/versions/`. Generate with `tox -e migrate-db `. From 538f0fff4c8ade8a989241c8df6e26a696b2ee84 Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:35:24 +0000 Subject: [PATCH 4/5] fix: move bandit to Security section, reframe noise entries (#1428) Move bandit from Formatting and Linting to a new Security Scanning subsection under Security Patterns, since bandit is a SAST tool under the security tox label, not a static linter. Reframe linked-issue and scope-bundling noise entries with narrower conditions instead of blanket suppressions. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8489baea9..b3ffdd057 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,6 @@ communicate through Celery (RabbitMQ) and share the database via the REST API - **`mypy`** runs with `--ignore-missing-imports` on the `iib/` package. - **`yamllint`** checks all YAML files (max line length 100, warning level). - **`hadolint`** lints Dockerfiles with `--failure-threshold warning`. -- **`bandit`** runs static application security testing. Run all static checks: `tox -m static` (runs `black`, `flake8`, `yamllint`, `mypy`, `hadolint`). @@ -84,6 +83,10 @@ When reviewing or writing code that logs commands or request parameters: - Always use the existing sanitization helpers rather than ad-hoc redaction. - Test that log output does not contain credential material. +### Security Scanning + +- **`bandit`** runs static application security testing via `tox -m security`. + ### Authentication The web API uses Kerberos authentication via `flask-login`. Worker identity is @@ -150,11 +153,12 @@ tox -m security suggest switching to Google or NumPy style. - **Import ordering**: Import order follows a manual convention (stdlib → third-party → `iib.*`). No automated sorter is configured. Do not flag import order. -- **Linked issues in PRs**: Not every PR requires a linked issue. Do not flag - missing issue references as a review finding. +- **Linked issues in PRs**: This project does not require every PR to link an + issue. Flag a missing issue reference only when a PR introduces a behavioral + change with no rationale provided in the PR description. - **Scope bundling**: Cross-cutting changes (e.g., security hardening across - multiple files) are acceptable in a single PR. Do not flag these as scope - bundling unless the changes are genuinely unrelated. + multiple files) are acceptable in a single PR. Flag scope bundling only when + the changes are genuinely unrelated to each other. - **Generic naming suggestions** (e.g., rename `x` to `y` for clarity) unless the name is actively misleading. - **Pattern inconsistency** across files that predate the change under review. From 9979ea767380785b42d78270a3b7bd84ba9c2387 Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 18:02:20 +0000 Subject: [PATCH 5/5] fix: correct quote enforcement claim, add missing Dockerfile, add AGENTS.md migration note (#1428) - Fix logic-error: clarify that skip-string-normalization means black leaves quotes as-is; single quotes are a manual convention, not auto-enforced - Fix edge-case: add docker/message_broker/Dockerfile to the Docker section listing (it is linted by hadolint in CI) - Fix misplaced-abstraction: add HTML comment noting review preferences section may migrate to .claude/AGENTS.md once #1366 merges Addresses #1428 Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b3ffdd057..ea1399e3f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -136,6 +136,8 @@ tox -m security ## Review Preferences + + ### Findings That Are Useful - Correctness bugs (wrong logic, missing error handling, race conditions). @@ -146,9 +148,9 @@ tox -m security ### Findings That Are Noise for This Project -- **String quoting style**: `black` with `skip-string-normalization = true` means - single quotes are the project convention. Do not flag single-vs-double quote - choices — `black` enforces this automatically. +- **String quoting style**: `black` with `skip-string-normalization = true` leaves + quotes as-is — it does not normalize them. Single quotes are a manual convention, + not auto-enforced. Do not flag single-vs-double quote choices. - **Docstring format preferences**: The project uses reStructuredText style. Do not suggest switching to Google or NumPy style. - **Import ordering**: Import order follows a manual convention (stdlib → third-party @@ -191,5 +193,5 @@ Generate with `tox -e migrate-db `. ### Docker -Dockerfiles are in `docker/` — `Dockerfile-api` (web), `Dockerfile-workers` (workers). -Linted by `hadolint` in CI. +Dockerfiles are in `docker/` — `Dockerfile-api` (web), `Dockerfile-workers` (workers), +`message_broker/Dockerfile` (message broker). Linted by `hadolint` in CI.