Skip to content

docs(lint): NOLINT cluster audit and refactor plan (ADR-0780) - #127

Closed
lusoris wants to merge 1 commit into
masterfrom
chore/nolint-cluster-audit-0780
Closed

lusoris wants to merge 1 commit into
masterfrom
chore/nolint-cluster-audit-0780

Conversation

@lusoris

@lusoris lusoris commented May 29, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Swept all 218 NOLINT annotations in core/src/ for clusters >5 identical suppressions per file; found 5 clusters (71 annotations total).
  • Identified 3 refactorable clusters (47 annotations): GPU slab performance-no-int-to-ptr (21, ADR-0278 non-compliant, no citations), SYCL stride bugprone-implicit-widening (12, can be fixed by explicit cast eliminating the suppression), SYCL/ADM consolidation candidates (14).
  • 1 load-bearing cluster left untouched: SYCL kernel entry-point readability-function-size (11 annotations, justified per ADR-0141).
  • Deliverables: research digest, ADR-0780 (Proposed), changelog fragment, rebase-notes entry.

This PR is docs/plan only. Follow-up refactor PRs (A–C) will execute the changes; they are independent and can be parallelised.

Deliverables checklist

  • Research digest: docs/research/nolint-cluster-audit-2026-05-29.md
  • Decision matrix: ADR-0780 ## Alternatives considered
  • AGENTS.md invariant note: no rebase-sensitive invariants — docs-only PR
  • Reproducer / smoke-test: grep -rn "NOLINT" core/src --include="*.c" --include="*.cpp" | awk -F: '{print $1}' | sort | uniq -c | sort -rn | head -10
  • changelog.d/changed/0780-nolint-cluster-refactor-plan.md
  • docs/rebase-notes.md: no rebase impact — docs-only addition

docs/state.md update

no state.md impact: no bug opened, closed, or ruled out-of-scope.

🤖 Generated with Claude Code

@lusoris
lusoris enabled auto-merge (squash) May 29, 2026 10:07
lusoris added a commit that referenced this pull request May 29, 2026
…it (ptrdiff_t) casts

Replace NOLINTNEXTLINE(bugprone-implicit-widening-of-multiplication-result)
comment blocks with explicit (ptrdiff_t) casts on the leading operand of
every stride and accumulator-size multiplication in integer_adm_sycl.cpp
(8 sites) and integer_vif_sycl.cpp (4 sites).

No behavioural change — the widening was always intended and operands are
bounded by frame dimensions. Removes all 12 NOLINTs identified in PR #127.

Smoke-tested: --feature adm_sycl --feature vif_sycl --backend sycl on
Netflix golden 576x324 (ADM-214 PASS, integer_adm=0.962083, 48 frames,
zero errors, 21.2 fps on Arc A380).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lusoris
lusoris disabled auto-merge May 29, 2026 11:50
@lusoris
lusoris marked this pull request as draft May 29, 2026 11:50
@lusoris
lusoris force-pushed the chore/nolint-cluster-audit-0780 branch from c0816d5 to f00e2e3 Compare May 29, 2026 12:08
lusoris added a commit that referenced this pull request May 29, 2026
…it (ptrdiff_t) casts

Replace NOLINTNEXTLINE(bugprone-implicit-widening-of-multiplication-result)
comment blocks with explicit (ptrdiff_t) casts on the leading operand of
every stride and accumulator-size multiplication in integer_adm_sycl.cpp
(8 sites) and integer_vif_sycl.cpp (4 sites).

No behavioural change — the widening was always intended and operands are
bounded by frame dimensions. Removes all 12 NOLINTs identified in PR #127.

Smoke-tested: --feature adm_sycl --feature vif_sycl --backend sycl on
Netflix golden 576x324 (ADM-214 PASS, integer_adm=0.962083, 48 frames,
zero errors, 21.2 fps on Arc A380).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Swept all 218 NOLINT annotations in core/src/ for clusters of five or more
identical suppressions per file. Identified five clusters (71 annotations):

- 21 bare performance-no-int-to-ptr in GPU slab allocators — ADR-0278
  non-compliant (no citations); scheduled for SLAB_FIELD macro (PR B).
- 12 bugprone-implicit-widening in SYCL stride arithmetic — scheduled for
  explicit (ptrdiff_t) casts that eliminate the suppression entirely (PR A).
- 14 misc-const-correctness in SYCL atomic_ref loops — fold into existing
  NOLINTBEGIN/NOLINTEND block (PR C).
- 13 bare readability-function-size in integer_adm.c — ADR-0278 non-compliant;
  scheduled for NOLINTBEGIN block consolidation (PR C).
- 11 readability-function-size on SYCL kernel entry-points — load-bearing
  per ADR-0141; no change planned.

Deliverables: research digest, ADR-0780 (Proposed), changelog fragment.
Follow-up refactor PRs A–C are independent.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lusoris
lusoris force-pushed the chore/nolint-cluster-audit-0780 branch from f00e2e3 to c21a6e1 Compare May 29, 2026 14:12
@lusoris
lusoris marked this pull request as ready for review May 31, 2026 13:48
@lusoris

lusoris commented May 31, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by master merge marathon 2026-05-31.

@lusoris lusoris closed this May 31, 2026
@lusoris
lusoris deleted the chore/nolint-cluster-audit-0780 branch May 31, 2026 13:52
@lusoris
lusoris restored the chore/nolint-cluster-audit-0780 branch May 31, 2026 18:46
@lusoris lusoris reopened this May 31, 2026
@lusoris
lusoris marked this pull request as draft May 31, 2026 18:50
@lusoris

lusoris commented Jun 1, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #527 — bundled per 2026-06-01 triage.

@lusoris lusoris closed this Jun 1, 2026
lusoris added a commit that referenced this pull request Jun 3, 2026
Adds changelog.d/changed/bundle-docs-hygiene.md summarising the
four source PRs: #127 (NOLINT audit), #216 (doc compliance audit),
#291 (state.md drift sweep), #233 (changelog concat fix).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 3, 2026
…291 state.md drift sweep + #233 changelog concat fix) (#527)

* docs(lint): NOLINT cluster audit and refactor plan (ADR-0780)

Swept all 218 NOLINT annotations in core/src/ for clusters of five or more
identical suppressions per file. Identified five clusters (71 annotations):

- 21 bare performance-no-int-to-ptr in GPU slab allocators — ADR-0278
  non-compliant (no citations); scheduled for SLAB_FIELD macro (PR B).
- 12 bugprone-implicit-widening in SYCL stride arithmetic — scheduled for
  explicit (ptrdiff_t) casts that eliminate the suppression entirely (PR A).
- 14 misc-const-correctness in SYCL atomic_ref loops — fold into existing
  NOLINTBEGIN/NOLINTEND block (PR C).
- 13 bare readability-function-size in integer_adm.c — ADR-0278 non-compliant;
  scheduled for NOLINTBEGIN block consolidation (PR C).
- 11 readability-function-size on SYCL kernel entry-points — load-bearing
  per ADR-0141; no change planned.

Deliverables: research digest, ADR-0780 (Proposed), changelog fragment.
Follow-up refactor PRs A–C are independent.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(process): per-surface doc compliance audit — last 30 PRs (ADR-0848)

Audits 30 most recent merged commits (PRs #96–#174) for CLAUDE §12 r10
compliance: user-discoverable surface change must ship human-readable docs
in the same PR.

Score: 22/30 N/A (no surface change), 5/8 with surface changes compliant
(62.5 %). Three confirmed gaps:

- Gap A (HIGH): PR #47 (ADR-0726, Vulkan drop) — docs/backends/vulkan/overview.md,
  docs/metrics/features.md, and docs/development/build-flags.md still describe
  Vulkan as an operative backend. Tracked as T-DOC-VULKAN-STALE-POST-ADR0726.
- Gap B (MEDIUM): PR #87 (ADR-0749, VmafLegacyQualityRunner sunset) — no
  docs/development/deprecations.md entry and no migration note in
  docs/usage/python.md. Tracked as T-DOC-LEGACY-RUNNER-MISSING-DEPRECATION.
- Gap C (LOW): PR #135 (log format standardization) — removes "Error: " prefix
  from CUDA error messages with no doc note.

Three follow-up issues proposed (Issue A, B, C in Research-0848). No code
changes in this PR; audit-only per task brief.

Six deliverables (ADR-0108):
(1) Research-0848: docs/research/research-0848-per-surface-doc-compliance-audit-20260529.md
(2) Decision matrix in ADR-0848 §Alternatives considered
(3) no rebase-sensitive invariants
(4) Reproducer: git log --oneline origin/master | head -30 (auditable from commit list)
(5) changelog.d/changed/per-surface-doc-compliance-audit.md
(6) docs/rebase-notes.md entry added

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(state): close T-LEGACY-RUNNER-ANSNR-BROKEN + T-LEGACY-RUNNER-STUB-MISSING

Both rows referenced classes / imports that no longer exist on master:

1. T-LEGACY-RUNNER-ANSNR-BROKEN — AnsnrFeatureExtractor was deleted
   by PR #283 (merged at faede7a). The class is absent from
   compat/python-vmaf/core/feature_extractor.py on master tip
   d45d503. The Netflix golden assertions still cover the
   integer-path VMAF score (Rule #1 preserved).

2. T-LEGACY-RUNNER-STUB-MISSING-2026-05-29 — VmafLegacyQualityRunner
   import-time failure: the class was removed in ADR-0749 / PR #87
   and python/test/quality_runner_test.py was updated by the
   ADR-0749 sunset PR to drop the import (only a removed-comment
   placeholder at line 49 remains).

Moved both rows from Open to Recently closed with verified-on-master
reproducer commands.

No code changes — documentation cleanup only.

Deliverables (ADR-0108):
- [x] **Research digest**: no digest needed: state.md hygiene
- [x] **Decision matrix**: no alternatives: only-one-way fix
- [x] **AGENTS.md invariant**: no rebase-sensitive invariants
- [x] **Reproducer**: `git show origin/master:compat/python-vmaf/core/feature_extractor.py | grep -c 'class AnsnrFeatureExtractor'` returns 0; `git show origin/master:python/test/quality_runner_test.py | grep -c '^from.*VmafLegacy'` returns 0.
- [x] **Changelog**: changelog.d/changed/state-md-drift-sweep-20260530.md
- [x] **Rebase notes**: no rebase impact: docs only

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

* docs(state): migrate 3 Vulkan rows to Recently closed (ADR-0726 supersession)

ADR-0726 (Vulkan backend dropped 2026-05-28, PR #47) structurally closes
three long-standing Vulkan Open rows by removing the affected code path
entirely:

- T-VK-1.4-BUMP — NVIDIA driver 595.71+ FP-contraction regression
- T-VK-CIEDE-F32-F64 — NVIDIA Vulkan f32/f64 ciede precision gap
- T-VK-VIF-1.4-RESIDUAL-ARC — Intel Arc A380 vif residual on Mesa-ANV

The entire `core/src/vulkan/`, `core/src/feature/vulkan/`, and
`core/include/libvmaf/libvmaf_vulkan.h` surface no longer exists on
master, so each row now has a verified empty-path reproducer. Native
CUDA / HIP / SYCL backends cover every vendor formerly served by Vulkan
(see ADR-0726 §Context).

Combined with the legacy-runner closures already in this PR
(T-LEGACY-RUNNER-ANSNR-BROKEN + T-LEGACY-RUNNER-STUB-MISSING-2026-05-29),
this brings the Open section from 14 → 11 rows.

Row counts (verified): Open 11 + Deferred 4 + Recently closed 137 +
Confirmed not-affected 1 = 153 total T- rows in tree.

* chore(changelog): fix concat awk boundary + consolidate perf/ fragments (ADR-0221)

Fix `concat-changelog-fragments.sh` --check/--write awk block-boundary: the
previous `/^## [^[]/` pattern terminated the Unreleased block on any `## Heading`
embedded inside a fragment (e.g. `## Added`, `## [perf] …`). Switch to
`/^## \[(Unreleased|[0-9])/` which matches only versioned-release headers and
the `[Unreleased]` sentinel, making `--check` deterministic. Tightened the
`--write` awk pass with the same fix.

Consolidate 32 fragments from non-standard `changelog.d/perf/` (27) and
`changelog.d/performance/` (5) into the recognised `changed/` section with
`perf-` filename prefix per ADR-0221 KaC convention.

Remove 3 duplicate stubs: `ort-run-stack-arrays-f3b.md`, `adm-pnorm-deferred-comment.md`,
`fixed/vmaf-tune-predictor-directory-corpus.md` (richer versions retained).
Rename `changed/fr-regressor-v3-namespace.md` → `…-adr-appendix.md` to
resolve filename collision with `added/fr-regressor-v3-namespace.md`.

Regenerate CHANGELOG.md Unreleased block via `--write`; `--check` exits 0.

no rebase impact: changelog.d/ + scripts/release/ only, no upstream C touched.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore(bundle): add changelog fragment for docs/hygiene bundle PR

Adds changelog.d/changed/bundle-docs-hygiene.md summarising the
four source PRs: #127 (NOLINT audit), #216 (doc compliance audit),
#291 (state.md drift sweep), #233 (changelog concat fix).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant