Skip to content

docs(api): warning-clean doxygen build for libvmaf public C API - #457

Closed
lusoris wants to merge 0 commit into
masterfrom
chore/doxygen-build-clean
Closed

docs(api): warning-clean doxygen build for libvmaf public C API#457
lusoris wants to merge 0 commit into
masterfrom
chore/doxygen-build-clean

Conversation

@lusoris

@lusoris lusoris commented May 31, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add core/doc/Doxyfile.public-api — a standalone Doxyfile that targets only the installable public headers under core/include/libvmaf/.
  • Add .github/workflows/doxygen-public-api.yml — on-demand CI job that builds the doxygen tree and publishes the rendered HTML + warning log as build artifacts.
  • Drive baseline warning count 95 → 0 on doxygen 1.15 by removing the unsupported @field antipattern, adding missing @param / @return blocks, documenting previously-undocumented compounds, and converting cross-symbol @ref to backtick literals.

The workflow is informational only; promotion to a required gate is tracked in ADR-0953.

Warnings before / after

Phase Total libvmaf_mcp.h dnn.h libvmaf_metal.h picture.h libvmaf_hip.h libvmaf.h model.h libvmaf_sycl.h libvmaf_cuda.h
Before 95 24 22 12 9 7 7 6 4 4
After 0 0 0 0 0 0 0 0 0 0

Warning classes in the baseline: 44 undocumented struct members, 21 missing @param, 11 missing @return, 8 undocumented compounds, 11 misc (unknown @field command, unresolved cross-symbol @ref).

ADR-0108 deliverables

  • Research digest — docs/research/doxygen-public-api-clean-2026-05-31.md
  • Decision matrix — docs/adr/0953-doxygen-public-api-clean.md (Alternatives considered section)
  • AGENTS.md invariant note — core/include/libvmaf/AGENTS.md (new "Doxygen-clean public API" rebase-sensitive invariant)
  • Reproducer command — included in the PR body (below) and in the research digest
  • Changelog fragment — changelog.d/added/doxygen-build-clean.md
  • Rebase-notes entry — docs/rebase-notes.md ("Doxygen public-API clean (ADR-0953, 2026-05-31)")

Test plan

  • doxygen --version — verified against 1.15.0 in vmaf-dev-mcp.
  • Local reproducer: 
    doxygen core/doc/Doxyfile.public-api
wc -l build/doxygen-public-api/warnings.log    # 0
  • Pre-commit suite (pre-commit run --files <all touched>) — green.
  • CI doxygen-public-api workflow — runs on this PR via the pull_request path-filter on core/include/libvmaf/**, publishes doxygen-public-api-warnings + doxygen-public-api-html artifacts.

🤖 Generated with Claude Code

@lusoris
lusoris marked this pull request as ready for review May 31, 2026 05:31
@lusoris
lusoris enabled auto-merge (squash) May 31, 2026 05:31
@lusoris
lusoris marked this pull request as draft May 31, 2026 09:01
auto-merge was automatically disabled May 31, 2026 09:01

Pull request was converted to draft

@lusoris
lusoris marked this pull request as ready for review May 31, 2026 12:20
@lusoris lusoris closed this May 31, 2026
@lusoris
lusoris force-pushed the chore/doxygen-build-clean branch from ca12a6d to eb9d679 Compare May 31, 2026 12:23
@lusoris lusoris mentioned this pull request May 31, 2026
Merged
2 of 6 tasks
lusoris added a commit that referenced this pull request May 31, 2026
@lusoris
fix(ci): semgrep-local pre-commit hook — io_uring memlock exhaustion (#…
26452fe 
…487)

Add `require_serial: true` + `--jobs 1` to the `semgrep-local`
pre-commit hook so it stops silently exiting 2 on commits.

Root cause: semgrep-core (the OCaml engine behind `semgrep scan`)
uses Eio, which spawns one io_uring submission queue per worker.
On `pre-commit run --all-files`, pre-commit batches the matched
targets into chunks and runs the chunks in parallel (one process
per CPU by default). Each chunk's OCaml runtime starts its own
pool of io_uring queues, and the combined per-process memlock
charge exceeds `ulimit -l` (8 MB default on Arch / CachyOS).
semgrep-core dies with `Unix_error: Cannot allocate memory
io_uring_queue_init`. The Python wrapper surfaces this as exit 2,
silently, because the hook's `--quiet` flag swallows the stderr
trace.

The bug blocked PR #481 (ISO header guards) and contributed to
the accidental nuking of PR #457 (doxygen) when a blocked commit
let a push through.

`require_serial: true` collapses pre-commit's parallel batches
into a single sequential invocation; `--jobs 1` collapses
semgrep-core's intra-process parallelism. Cost on the staged-files
commit path is negligible (≈2 s → ≈4 s); the all-files path goes
from "always fails" to "works".

Verified locally:
  pre-commit run semgrep-local --all-files  # → Passed

Co-authored-by: Lusoris <lusoris@pm.me>
lusoris added a commit that referenced this pull request May 31, 2026
@lusoris @claude
docs(api): warning-clean doxygen build for libvmaf public C API (reco…
bbadf53 
…very of #457)

Add core/doc/Doxyfile.public-api + on-demand doxygen-public-api CI workflow;
fix 95 baseline warnings across core/include/libvmaf/*.h (drop @field antipattern,
add missing @param/@return, convert cross-symbol @ref to backtick literals,
split multi-name declarations); warning count 95 -> 0 on doxygen 1.15. ADR-0953.

Also fix the pre-existing semgrep-local hook exit-2 crash (io_uring memlock
exhaustion on CachyOS: add --jobs 1 + require_serial: true to the semgrep-local
hook; add scripts/githooks/pre-commit.sh to .semgrepignore for the false-positive
vmaf-no-skip-hooks-in-scripts match on a doc comment).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request May 31, 2026
@lusoris @claude
docs(api): warning-clean doxygen build for libvmaf public C API (reco…
cfd7dac 
…very of #457)

Add core/doc/Doxyfile.public-api + on-demand doxygen-public-api CI workflow;
fix 95 baseline warnings across core/include/libvmaf/*.h (drop @field antipattern,
add missing @param/@return, convert cross-symbol @ref to backtick literals,
split multi-name declarations); warning count 95 -> 0 on doxygen 1.15. ADR-0953.

Also fix the pre-existing semgrep-local hook exit-2 crash (io_uring memlock
exhaustion on CachyOS: add --jobs 1 + require_serial: true to the semgrep-local
hook; add scripts/githooks/pre-commit.sh to .semgrepignore for the false-positive
vmaf-no-skip-hooks-in-scripts match on a doc comment).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request May 31, 2026
@lusoris @claude
docs(api): warning-clean doxygen build for libvmaf public C API (reco…
26043e1 
…very of #457)

Add core/doc/Doxyfile.public-api + on-demand doxygen-public-api CI workflow;
fix 95 baseline warnings across core/include/libvmaf/*.h (drop @field antipattern,
add missing @param/@return, convert cross-symbol @ref to backtick literals,
split multi-name declarations); warning count 95 -> 0 on doxygen 1.15. ADR-0953.

Also fix the pre-existing semgrep-local hook exit-2 crash (io_uring memlock
exhaustion on CachyOS: add --jobs 1 + require_serial: true to the semgrep-local
hook; add scripts/githooks/pre-commit.sh to .semgrepignore for the false-positive
vmaf-no-skip-hooks-in-scripts match on a doc comment).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request May 31, 2026
@lusoris @claude
docs(api): warning-clean doxygen build for libvmaf public C API (reco…
e411bc6 
…very of #457)

Add core/doc/Doxyfile.public-api + on-demand doxygen-public-api CI workflow;
fix 95 baseline warnings across core/include/libvmaf/*.h (drop @field antipattern,
add missing @param/@return, convert cross-symbol @ref to backtick literals,
split multi-name declarations); warning count 95 -> 0 on doxygen 1.15. ADR-0953.

Also fix the pre-existing semgrep-local hook exit-2 crash (io_uring memlock
exhaustion on CachyOS: add --jobs 1 + require_serial: true to the semgrep-local
hook; add scripts/githooks/pre-commit.sh to .semgrepignore for the false-positive
vmaf-no-skip-hooks-in-scripts match on a doc comment).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request May 31, 2026
@lusoris @claude
docs(api): warning-clean doxygen build for libvmaf public C API (reco…
f349bd4 
…very of #457) (#484)

Add core/doc/Doxyfile.public-api + on-demand doxygen-public-api CI workflow;
fix 95 baseline warnings across core/include/libvmaf/*.h (drop @field antipattern,
add missing @param/@return, convert cross-symbol @ref to backtick literals,
split multi-name declarations); warning count 95 -> 0 on doxygen 1.15. ADR-0953.

Also fix the pre-existing semgrep-local hook exit-2 crash (io_uring memlock
exhaustion on CachyOS: add --jobs 1 + require_serial: true to the semgrep-local
hook; add scripts/githooks/pre-commit.sh to .semgrepignore for the false-positive
vmaf-no-skip-hooks-in-scripts match on a doc comment).

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This was referenced Jun 1, 2026
Closed
Merged
Merged
Merged
Merged
Closed
lusoris added a commit that referenced this pull request Jun 3, 2026
@lusoris @claude
test(compat-python-vmaf): 175 pytest cases for Result, FeatureAssembl…
fbc76ba 
…er, QualityRunner, FeatureExtractor

Add compat/python-vmaf/tests/ with four focused test modules covering the
pure-Python wrapper layer without invoking the vmaf binary:

- test_result.py: BasicResult aggregation, wildcard key matching, Result
  equality, to_dict/to_json/to_xml round-trips, combine_result, dataframe
  helpers, RawResult.
- test_feature_assembler.py: construction, option-dict routing in
  _get_fextractor_instance, _create_feature_result_dicts, run() with
  mocked extractors.
- test_quality_runner.py: clip_score, transform_score (polynomial, knots,
  rectification), _do_transform_score, _assert_extension_format,
  _get_aggr_feature_opts_dict, predict_with_model.
- test_feature_extractor.py: TYPE/VERSION metadata, ATOM_FEATURES membership,
  DERIVED_ATOM_FEATURES, ATOM_FEATURES_TO_VMAFEXEC_KEY_DICT, find_subclass,
  _discover_feature_exact / _wildcard for all concrete extractor classes.

Wire the new directory into pyproject.toml testpaths and add python/ to
pythonpath so import vmaf resolves to compat/vmaf (the symlink target).

SKIP=semgrep-local: pre-commit semgrep binary crashes with io_uring OOM
on this machine (documented failure, same as PRs #481/#457/#484). Standalone
semgrep scan --jobs 1 passes with zero findings on all four new test files.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 3, 2026
@lusoris @claude
test(compat-python-vmaf): 175 pytest cases for Result, FeatureAssembl…
0317b64 
…er, QualityRunner, FeatureExtractor (#582)

Add compat/python-vmaf/tests/ with four focused test modules covering the
pure-Python wrapper layer without invoking the vmaf binary:

- test_result.py: BasicResult aggregation, wildcard key matching, Result
  equality, to_dict/to_json/to_xml round-trips, combine_result, dataframe
  helpers, RawResult.
- test_feature_assembler.py: construction, option-dict routing in
  _get_fextractor_instance, _create_feature_result_dicts, run() with
  mocked extractors.
- test_quality_runner.py: clip_score, transform_score (polynomial, knots,
  rectification), _do_transform_score, _assert_extension_format,
  _get_aggr_feature_opts_dict, predict_with_model.
- test_feature_extractor.py: TYPE/VERSION metadata, ATOM_FEATURES membership,
  DERIVED_ATOM_FEATURES, ATOM_FEATURES_TO_VMAFEXEC_KEY_DICT, find_subclass,
  _discover_feature_exact / _wildcard for all concrete extractor classes.

Wire the new directory into pyproject.toml testpaths and add python/ to
pythonpath so import vmaf resolves to compat/vmaf (the symlink target).

SKIP=semgrep-local: pre-commit semgrep binary crashes with io_uring OOM
on this machine (documented failure, same as PRs #481/#457/#484). Standalone
semgrep scan --jobs 1 passes with zero findings on all four new test files.

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 3, 2026
@lusoris
test(ai): coverage push — 2 new test files lifting online_trainer + f…
c36a3a0 
…eature_extractor

Add 56 new tests across two previously untested modules:

- ai/sidecar/tests/test_online_trainer.py (30 tests):
  covers OnlineTrainer construction, ingest/batch/checkpoint lifecycle,
  _write_sha256_sidecar atomicity, _build_fallback_model / _load_base_model
  happy + error paths, _handle_connection JSON wire protocol (happy/bad-key/
  malformed/empty-line/multi-message), and run_server start+stop.
  Module coverage: online_trainer.py 0% → 85%.

- ai/tests/test_feature_extractor_unit.py (26 tests):
  covers _ensure_binary raise + pass, _lookup direct/integer_-fallback/absent,
  _run_vmaf_json argv composition/feature-flags/pix_fmt/cleanup-on-error,
  extract_features happy/NaN/integer_-fallback/empty-frames/missing-binary/
  env-binary paths, FeatureExtractionResult round-trip, and aggregate_clip_stats
  shape/mean/p10-p90/NaN-ignore/all-NaN/empty-frames/bad-ndim/float32/single-frame.
  Module coverage: feature_extractor.py partial → 94%.

semgrep skipped locally: pre-commit venv semgrep-core hits io_uring ENOMEM
(ulimit -l 8 MiB on CachyOS); system semgrep passes cleanly; CI container
runs with unlimited memlock. Same pre-existing failure as PR #481 / #457 / #484.
All other pre-commit hooks pass. Tests: 56/56 green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

# Conflicts:
#	CONTRIBUTING.md
#	README.md
#	ai/scripts/train_konvid.py
#	core/src/dnn/AGENTS.md
#	core/src/dnn/ort_backend.c
#	core/src/dnn/ort_backend_internal.h
#	core/src/feature/feature_extractor.cpp
#	docs/adr/0761-cpp23-wave8-opt-read-json-model.md
#	docs/adr/0763-cuda-adm-decouple-ldg.md
#	docs/adr/0771-simd-twin-inventory.md
#	docs/adr/0772-feature-extractor-cpp-rename.md
#	docs/adr/0777-thread-safety-audit-gpu-backends.md
#	docs/adr/0779-ebpf-fuse-bypass.md
#	docs/adr/0780-nolint-cluster-refactor.md
#	docs/adr/0793-nightly-workflow-audit.md
#	docs/adr/0802-ci-runner-image-standardization.md
#	docs/adr/0809-cli-cpp23-conversion.md
#	docs/adr/0812-renovate-go-rust-scheduling.md
#	docs/adr/0815-operator-node-distroless-dockerfiles.md
#	docs/adr/0844-float-adm-avx2-512-f2-f3.md
#	docs/adr/0852-hip-speed-extractor-wiring.md
#	docs/adr/0858-cpp23-gpu-dispatch-env.md
#	docs/adr/0865-ansnr-sunset-pre-vmaf-metric-drop.md
#	docs/adr/0879-python-dep-freshness-2026-05-30.md
#	docs/adr/0881-coverage-overrides-audit-2026-05-30.md
#	docs/adr/0888-pyright-strict-audit.md
#	docs/adr/0946-sycl-kernel-coverage-round3.md
#	docs/adr/0957-sycl-kernel-coverage-round4.md
#	docs/adr/README.md
#	docs/ai/models/learned_filter_v1.md
#	docs/backends/operator.md
#	docs/development/ebpf-fuse-bypass.md
#	docs/k8s/integration-tests.md
#	docs/rebase-notes.md
#	docs/research/0763-cuda-adm-decouple-ldg-f3-fix.md
#	docs/research/0881-coverage-overrides-audit-2026-05-30.md
#	docs/research/0946-sycl-kernel-coverage-round3-2026-05-31.md
#	docs/research/0957-sycl-kernel-coverage-round4-2026-05-31.md
#	docs/research/dependency-audit-2026-05-30.md
#	docs/research/nolint-cluster-audit-2026-05-29.md
#	docs/research/pyright-strict-audit-2026-05-30.md
#	docs/research/python-dep-freshness-2026-05-30.md
#	docs/research/python-type-annotations-audit-20260530.md
#	docs/research/research-0787-libvmaf-api-error-path-audit.md
#	docs/research/simd-twin-inventory-2026-05-29.md
#	docs/research/thread-safety-audit-backends-2026-05-29.md
#	docs/state.md
#	mkdocs.yml
#	pyproject.toml
lusoris added a commit that referenced this pull request Jun 3, 2026
@lusoris
test(ai): coverage push — 2 new test files lifting online_trainer + f…
4f42702 
…eature_extractor (#578)

Add 56 new tests across two previously untested modules:

- ai/sidecar/tests/test_online_trainer.py (30 tests):
  covers OnlineTrainer construction, ingest/batch/checkpoint lifecycle,
  _write_sha256_sidecar atomicity, _build_fallback_model / _load_base_model
  happy + error paths, _handle_connection JSON wire protocol (happy/bad-key/
  malformed/empty-line/multi-message), and run_server start+stop.
  Module coverage: online_trainer.py 0% → 85%.

- ai/tests/test_feature_extractor_unit.py (26 tests):
  covers _ensure_binary raise + pass, _lookup direct/integer_-fallback/absent,
  _run_vmaf_json argv composition/feature-flags/pix_fmt/cleanup-on-error,
  extract_features happy/NaN/integer_-fallback/empty-frames/missing-binary/
  env-binary paths, FeatureExtractionResult round-trip, and aggregate_clip_stats
  shape/mean/p10-p90/NaN-ignore/all-NaN/empty-frames/bad-ndim/float32/single-frame.
  Module coverage: feature_extractor.py partial → 94%.

semgrep skipped locally: pre-commit venv semgrep-core hits io_uring ENOMEM
(ulimit -l 8 MiB on CachyOS); system semgrep passes cleanly; CI container
runs with unlimited memlock. Same pre-existing failure as PR #481 / #457 / #484.
All other pre-commit hooks pass. Tests: 56/56 green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

# Conflicts:
#	CONTRIBUTING.md
#	README.md
#	ai/scripts/train_konvid.py
#	core/src/dnn/AGENTS.md
#	core/src/dnn/ort_backend.c
#	core/src/dnn/ort_backend_internal.h
#	core/src/feature/feature_extractor.cpp
#	docs/adr/0761-cpp23-wave8-opt-read-json-model.md
#	docs/adr/0763-cuda-adm-decouple-ldg.md
#	docs/adr/0771-simd-twin-inventory.md
#	docs/adr/0772-feature-extractor-cpp-rename.md
#	docs/adr/0777-thread-safety-audit-gpu-backends.md
#	docs/adr/0779-ebpf-fuse-bypass.md
#	docs/adr/0780-nolint-cluster-refactor.md
#	docs/adr/0793-nightly-workflow-audit.md
#	docs/adr/0802-ci-runner-image-standardization.md
#	docs/adr/0809-cli-cpp23-conversion.md
#	docs/adr/0812-renovate-go-rust-scheduling.md
#	docs/adr/0815-operator-node-distroless-dockerfiles.md
#	docs/adr/0844-float-adm-avx2-512-f2-f3.md
#	docs/adr/0852-hip-speed-extractor-wiring.md
#	docs/adr/0858-cpp23-gpu-dispatch-env.md
#	docs/adr/0865-ansnr-sunset-pre-vmaf-metric-drop.md
#	docs/adr/0879-python-dep-freshness-2026-05-30.md
#	docs/adr/0881-coverage-overrides-audit-2026-05-30.md
#	docs/adr/0888-pyright-strict-audit.md
#	docs/adr/0946-sycl-kernel-coverage-round3.md
#	docs/adr/0957-sycl-kernel-coverage-round4.md
#	docs/adr/README.md
#	docs/ai/models/learned_filter_v1.md
#	docs/backends/operator.md
#	docs/development/ebpf-fuse-bypass.md
#	docs/k8s/integration-tests.md
#	docs/rebase-notes.md
#	docs/research/0763-cuda-adm-decouple-ldg-f3-fix.md
#	docs/research/0881-coverage-overrides-audit-2026-05-30.md
#	docs/research/0946-sycl-kernel-coverage-round3-2026-05-31.md
#	docs/research/0957-sycl-kernel-coverage-round4-2026-05-31.md
#	docs/research/dependency-audit-2026-05-30.md
#	docs/research/nolint-cluster-audit-2026-05-29.md
#	docs/research/pyright-strict-audit-2026-05-30.md
#	docs/research/python-dep-freshness-2026-05-30.md
#	docs/research/python-type-annotations-audit-20260530.md
#	docs/research/research-0787-libvmaf-api-error-path-audit.md
#	docs/research/simd-twin-inventory-2026-05-29.md
#	docs/research/thread-safety-audit-backends-2026-05-29.md
#	docs/state.md
#	mkdocs.yml
#	pyproject.toml

Co-authored-by: Lusoris <lusoris@pm.me>
This was referenced Jun 3, 2026
Merged
Merged
Merged
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
test(scripts/dev): coverage push for project_modernization_audit + tr…
772b318 
…aining_discovery + cross_backend_parity_gate

Add 95 new pure-Python tests (no GPU, no corpus, no model downloads) across
three previously-untested or under-tested utility scripts:

- scripts/dev/test_training_discovery_report.py (31 tests, new file):
  Covers _extract_metric_table_value, _extract_bold_field, _float_or_none,
  _fmt, _markdown_table, PredictorCard.family, load_predictor_cards
  (including synthetic-stub rejection), _predictor_rows sort order,
  _qsv_nvenc_delta_rows, render_report sections and data, and main() CLI
  (stdout + file output + parent-dir creation).

- scripts/ci/test_cross_backend_parity_gate.py (46 tests, new file):
  Covers build_matrix combinatorics, feature_extractor_name (CPU/CUDA/SYCL/
  Vulkan suffixes, ADR-0586 adm alias, ADR-0662 motion alias, LCS pseudo-
  feature), build_command device-flag injection, diff_frames (zero-diff,
  tolerance detection, accumulation, mismatched-length raises),
  resolve_cell_tolerance (fp16 override, calibrated/placeholder/no-match),
  emit_json (schema, fields, status, newline), emit_md (header, table rows,
  failure section, tolerance_source), and registry consistency checks.

- scripts/dev/test_project_modernization_audit.py (18 new tests, extending
  existing 28): adds dedupe_findings (duplicate removal, sort order),
  summarize_findings (counter aggregation, empty case), _area_for (all
  major AREA_RULES prefixes + exact-match + unknown fallback),
  render_markdown (clusters section, blocked section, by-area table),
  _skip_path include_archives=True branch, and main() stdout path.

Note: semgrep-local skipped via SKIP= due to io_uring resource exhaustion
in the worktree sandbox (same crash documented in .pre-commit-config.yaml
at the semgrep-local hook comment, PR #481 / #457 / #484); semgrep finds
no violations on these files when invoked correctly in CI.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
chore(cppcheck): audit + cite ALL cppcheck-suppress comments (§12 r12…
7e78938 
… sweep)

Audit result: one file with suppressions found — core/src/feature/vif.c.
Ten bare `cppcheck-suppress invalidPointerCast` annotations on char*→float*
slab-partition casts had no inline citation, violating CLAUDE.md §12 r12.

All 10 suppressions now carry:
  [MISRA-C:2012-11.3/EXP36-C: see block comment above]

The block comment above the cast block has been expanded to explain why
aligned_malloc(MAX_ALIGN=32) + ALIGN_CEIL(buf_sz_one) together guarantee
that every sub-region base address satisfies float's alignment requirement,
and why cppcheck cannot verify this statically.

No logic changed. All other hooks pass; semgrep skipped due to pre-existing
io_uring memlock sandbox limit (RLIMIT_MEMLOCK hard limit = 8 MB, cannot be
raised; see .pre-commit-config.yaml semgrep-local comment and PR #481/#457).

ADR-0108 deliverables:
- Research digest: no digest needed: trivial comment-only audit
- Decision matrix: no alternatives: only-one-way fix (add citation)
- AGENTS.md note: no rebase-sensitive invariants
- Reproducer: grep -rn "cppcheck-suppress" core/ --include="*.{c,h}" -> 10 cited hits
- Changelog: changelog.d/chore/cppcheck-suppress-cite-audit.md
- Rebase notes: docs/rebase-notes.md (no rebase impact)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
test(scripts/dev): coverage push for project_modernization_audit + tr…
ee926c1 
…aining_discovery + cross_backend_parity_gate (#598)

Add 95 new pure-Python tests (no GPU, no corpus, no model downloads) across
three previously-untested or under-tested utility scripts:

- scripts/dev/test_training_discovery_report.py (31 tests, new file):
  Covers _extract_metric_table_value, _extract_bold_field, _float_or_none,
  _fmt, _markdown_table, PredictorCard.family, load_predictor_cards
  (including synthetic-stub rejection), _predictor_rows sort order,
  _qsv_nvenc_delta_rows, render_report sections and data, and main() CLI
  (stdout + file output + parent-dir creation).

- scripts/ci/test_cross_backend_parity_gate.py (46 tests, new file):
  Covers build_matrix combinatorics, feature_extractor_name (CPU/CUDA/SYCL/
  Vulkan suffixes, ADR-0586 adm alias, ADR-0662 motion alias, LCS pseudo-
  feature), build_command device-flag injection, diff_frames (zero-diff,
  tolerance detection, accumulation, mismatched-length raises),
  resolve_cell_tolerance (fp16 override, calibrated/placeholder/no-match),
  emit_json (schema, fields, status, newline), emit_md (header, table rows,
  failure section, tolerance_source), and registry consistency checks.

- scripts/dev/test_project_modernization_audit.py (18 new tests, extending
  existing 28): adds dedupe_findings (duplicate removal, sort order),
  summarize_findings (counter aggregation, empty case), _area_for (all
  major AREA_RULES prefixes + exact-match + unknown fallback),
  render_markdown (clusters section, blocked section, by-area table),
  _skip_path include_archives=True branch, and main() stdout path.

Note: semgrep-local skipped via SKIP= due to io_uring resource exhaustion
in the worktree sandbox (same crash documented in .pre-commit-config.yaml
at the semgrep-local hook comment, PR #481 / #457 / #484); semgrep finds
no violations on these files when invoked correctly in CI.

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
test(sycl): parity coverage round 5 — CAMBI CPU vs. SYCL parity gate …
af1c532 
…(ADR-1001)

Adds test_sycl_cambi_parity.c: the first genuine numerical-correctness
parity gate for cambi_sycl. The pre-existing test_integer_cambi_sycl.c
was a smoke test only (its own header says so); ADR-0957 incorrectly
counted it as a parity gate, leaving cambi_sycl as the sole registered
SYCL extractor without a CPU-vs-SYCL delta assertion.

Fixture: 256x256 quantised-gradient (8-step/32-px bands), above the
CAMBI_MIN_WIDTH_HEIGHT=216 threshold, non-trivial banding score.
Tolerance: 1e-4 (ADR-0214 places=4 default for integer kernels).
Skip: [skip: no SYCL device] when no oneAPI runtime present.

Active SYCL parity coverage corrects to 17/18 registered extractors
(2 dormant SpEED twins activate automatically once their build wiring
lands per ADR-0957). semgrep skipped: pre-existing io_uring/RLIMIT_MEMLOCK
environment failure documented in .pre-commit-config.yaml (PR #481/#457).

ADR-0108 deliverables:
- research digest: no digest needed: trivial parity gap-fill
- decision matrix: ADR-1001 Alternatives considered
- AGENTS.md invariant: core/test/AGENTS.md (smoke vs. parity distinction)
- reproducer: meson test -C build test_sycl_cambi_parity (suite fast/gpu)
- changelog: changelog.d/added/sycl-cambi-parity.md
- rebase-notes: docs/rebase-notes.md (no rebase impact)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
chore(cppcheck): audit + cite ALL cppcheck-suppress comments (§12 r12…
b37d21e 
… sweep)

Audit result: one file with suppressions found — core/src/feature/vif.c.
Ten bare `cppcheck-suppress invalidPointerCast` annotations on char*→float*
slab-partition casts had no inline citation, violating CLAUDE.md §12 r12.

All 10 suppressions now carry:
  [MISRA-C:2012-11.3/EXP36-C: see block comment above]

The block comment above the cast block has been expanded to explain why
aligned_malloc(MAX_ALIGN=32) + ALIGN_CEIL(buf_sz_one) together guarantee
that every sub-region base address satisfies float's alignment requirement,
and why cppcheck cannot verify this statically.

No logic changed. All other hooks pass; semgrep skipped due to pre-existing
io_uring memlock sandbox limit (RLIMIT_MEMLOCK hard limit = 8 MB, cannot be
raised; see .pre-commit-config.yaml semgrep-local comment and PR #481/#457).

ADR-0108 deliverables:
- Research digest: no digest needed: trivial comment-only audit
- Decision matrix: no alternatives: only-one-way fix (add citation)
- AGENTS.md note: no rebase-sensitive invariants
- Reproducer: grep -rn "cppcheck-suppress" core/ --include="*.{c,h}" -> 10 cited hits
- Changelog: changelog.d/chore/cppcheck-suppress-cite-audit.md
- Rebase notes: docs/rebase-notes.md (no rebase impact)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
chore(cppcheck): audit + cite ALL cppcheck-suppress comments (§12 r12…
150c7d5 
… sweep) (#602)

Audit result: one file with suppressions found — core/src/feature/vif.c.
Ten bare `cppcheck-suppress invalidPointerCast` annotations on char*→float*
slab-partition casts had no inline citation, violating CLAUDE.md §12 r12.

All 10 suppressions now carry:
  [MISRA-C:2012-11.3/EXP36-C: see block comment above]

The block comment above the cast block has been expanded to explain why
aligned_malloc(MAX_ALIGN=32) + ALIGN_CEIL(buf_sz_one) together guarantee
that every sub-region base address satisfies float's alignment requirement,
and why cppcheck cannot verify this statically.

No logic changed. All other hooks pass; semgrep skipped due to pre-existing
io_uring memlock sandbox limit (RLIMIT_MEMLOCK hard limit = 8 MB, cannot be
raised; see .pre-commit-config.yaml semgrep-local comment and PR #481/#457).

ADR-0108 deliverables:
- Research digest: no digest needed: trivial comment-only audit
- Decision matrix: no alternatives: only-one-way fix (add citation)
- AGENTS.md note: no rebase-sensitive invariants
- Reproducer: grep -rn "cppcheck-suppress" core/ --include="*.{c,h}" -> 10 cited hits
- Changelog: changelog.d/chore/cppcheck-suppress-cite-audit.md
- Rebase notes: docs/rebase-notes.md (no rebase impact)

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
test(sycl): parity coverage round 5 — CAMBI CPU vs. SYCL parity gate …
fd6fab2 
…(ADR-1001)

Adds test_sycl_cambi_parity.c: the first genuine numerical-correctness
parity gate for cambi_sycl. The pre-existing test_integer_cambi_sycl.c
was a smoke test only (its own header says so); ADR-0957 incorrectly
counted it as a parity gate, leaving cambi_sycl as the sole registered
SYCL extractor without a CPU-vs-SYCL delta assertion.

Fixture: 256x256 quantised-gradient (8-step/32-px bands), above the
CAMBI_MIN_WIDTH_HEIGHT=216 threshold, non-trivial banding score.
Tolerance: 1e-4 (ADR-0214 places=4 default for integer kernels).
Skip: [skip: no SYCL device] when no oneAPI runtime present.

Active SYCL parity coverage corrects to 17/18 registered extractors
(2 dormant SpEED twins activate automatically once their build wiring
lands per ADR-0957). semgrep skipped: pre-existing io_uring/RLIMIT_MEMLOCK
environment failure documented in .pre-commit-config.yaml (PR #481/#457).

ADR-0108 deliverables:
- research digest: no digest needed: trivial parity gap-fill
- decision matrix: ADR-1001 Alternatives considered
- AGENTS.md invariant: core/test/AGENTS.md (smoke vs. parity distinction)
- reproducer: meson test -C build test_sycl_cambi_parity (suite fast/gpu)
- changelog: changelog.d/added/sycl-cambi-parity.md
- rebase-notes: docs/rebase-notes.md (no rebase impact)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 4, 2026
@lusoris @claude
test(sycl): parity coverage round 5 — CAMBI CPU vs. SYCL parity gate …
63c71c8 
…(ADR-1001) (#604)

Adds test_sycl_cambi_parity.c: the first genuine numerical-correctness
parity gate for cambi_sycl. The pre-existing test_integer_cambi_sycl.c
was a smoke test only (its own header says so); ADR-0957 incorrectly
counted it as a parity gate, leaving cambi_sycl as the sole registered
SYCL extractor without a CPU-vs-SYCL delta assertion.

Fixture: 256x256 quantised-gradient (8-step/32-px bands), above the
CAMBI_MIN_WIDTH_HEIGHT=216 threshold, non-trivial banding score.
Tolerance: 1e-4 (ADR-0214 places=4 default for integer kernels).
Skip: [skip: no SYCL device] when no oneAPI runtime present.

Active SYCL parity coverage corrects to 17/18 registered extractors
(2 dormant SpEED twins activate automatically once their build wiring
lands per ADR-0957). semgrep skipped: pre-existing io_uring/RLIMIT_MEMLOCK
environment failure documented in .pre-commit-config.yaml (PR #481/#457).

ADR-0108 deliverables:
- research digest: no digest needed: trivial parity gap-fill
- decision matrix: ADR-1001 Alternatives considered
- AGENTS.md invariant: core/test/AGENTS.md (smoke vs. parity distinction)
- reproducer: meson test -C build test_sycl_cambi_parity (suite fast/gpu)
- changelog: changelog.d/added/sycl-cambi-parity.md
- rebase-notes: docs/rebase-notes.md (no rebase impact)

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@lusoris
lusoris deleted the chore/doxygen-build-clean branch June 4, 2026 08:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@lusoris