fix: resolve compiler warnings for clean -Wall -Wextra -Wshadow build

[maxwbuckley]

Summary

• Add configurable compiler warning infrastructure (cmake/StrictCompilerWarnings.cmake) with 3 warning levels (basic, standard, strict) and optional -Werror support
• Fix all compiler warnings across 160+ source files including -Wshadow, -Wunused-parameter, -Wnon-virtual-dtor, -Wformat, -Wimplicit-fallthrough, and -Woverloaded-virtual
• Library and tests now compile cleanly at warning level 2 (-Wall -Wextra -Wpedantic -Wshadow -Wnon-virtual-dtor -Wunused -Woverloaded-virtual -Wformat=2 -Wimplicit-fallthrough) with -Werror

Motivation

Compiler warnings often indicate real bugs (shadowed variables, implicit fallthrough, format string issues) and make it harder to spot new problems when they're noisy. This PR brings the FAISS codebase to a warning-clean state and provides infrastructure to keep it that way.

Warning infrastructure

The new cmake/StrictCompilerWarnings.cmake module provides:

• FAISS_WARNING_LEVEL cache variable (0=off, 1=basic, 2=standard, 3=strict)
• FAISS_WARNINGS_AS_ERRORS option for CI enforcement
• faiss_add_warnings() function applied to all build targets
• Default is level 0 (off) so this is fully opt-in and does not break existing builds

Changes by category

Shadow variable fixes (-Wshadow): Renamed local variables, loop variables, and constructor parameters that shadowed outer-scope or member variables throughout the codebase.

Unused parameter fixes (-Wunused-parameter): Added (void)param casts or removed parameter names for intentionally unused parameters.

Format string fixes (-Wformat): Changed %ld/%d to portable format macros (PRId64, zu) where appropriate.

Implicit fallthrough fixes (-Wimplicit-fallthrough): Added [[fallthrough]] attributes or break/return statements.

Non-virtual destructor fixes (-Wnon-virtual-dtor): Added virtual destructors where classes have virtual methods.

Other: Fixed signed/unsigned comparisons, overloaded-virtual warnings, and various minor issues.

Test plan

• faiss library builds with -Werror at warning level 2 (GCC)
• Test binary builds cleanly
• All 170/171 tests pass (1 skipped - SIMD level test in static/generic build)
• No functional changes - all fixes are mechanical renames and annotations

🤖 Generated with Claude Code

[junjieqi]

@maxwbuckley thanks for the contribution. Would you like to update your change?

[maxwbuckley]

Thanks @junjieqi! I've rebased onto the latest main and resolved the merge conflicts with #4811 (the deserialization hardening PR). The branch is now up to date.

[junjieqi]

@maxwbuckley thanks for the update! There are couple of CI build failures, could you help to fix them?

[maxwbuckley]

@junjieqi Thanks for flagging the CI failures! I've pushed fixes for all three:

1. Format check — ran clang-format on all source files
2. Linux x86_64 warnings build — fixed %d format specifier for size_t variable in AdditiveQuantizer.cpp (should be %zd)
3. Windows conda build — MSVC requires signed integral types for OpenMP for loop variables; reverted 7 loop variables from size_t back to idx_t/int64_t

I also rebased onto the latest main and added the deserialization hardening changes from #4811 (overflow-safe arithmetic, HNSW/NSG validation on read, bounds checking).

[junjieqi]

@junjieqi Thanks for flagging the CI failures! I've pushed fixes for all three:

1. Format check — ran clang-format on all source files
2. Linux x86_64 warnings build — fixed %d format specifier for size_t variable in AdditiveQuantizer.cpp (should be %zd)
3. Windows conda build — MSVC requires signed integral types for OpenMP for loop variables; reverted 7 loop variables from size_t back to idx_t/int64_t

I also rebased onto the latest main and added the deserialization hardening changes from #4811 (overflow-safe arithmetic, HNSW/NSG validation on read, bounds checking).

@maxwbuckley looks like there are more conflicts, could you help update it? Thanks!

[maxwbuckley]

@junjieqi Rebased onto the latest main and resolved all merge conflicts. The branch is now up to date with a single squashed commit.

Changes since last push:

• Rebased onto latest main (includes PRs Deploy std::unique_ptr<> in index_read.cpp for exception safety #4809, Harden deserialization against integer overflow and buffer overflows #4811-Harden ZnSphere lattice codec against invalid parameters #4826, fbcode/faiss #4829, fbcode/faiss/IndexFlat.cpp #4831-fbcode/faiss/utils/simd_impl #4833)
• Resolved conflicts in 13+ files, preserving both upstream's improvements (unique_ptr safety, validation, refactoring) and our warning fixes
• Dropped the redundant copy of Harden deserialization against integer overflow and buffer overflows #4811 (already merged upstream)
• Fixed additional MSVC OpenMP issue in OnDiskInvertedLists.cpp
• Re-applied warning fixes to files modified by upstream
• All 181 C++ tests pass, clang-format clean

[maxwbuckley]

Updated to also fix warnings in AVX2-specific code paths (-DFAISS_OPT_LEVEL=avx2):

• faiss/utils/simdlib_avx2.h — shadow warnings (constructor params shadowing members)
• faiss/utils/hamming_distance/avx2-inl.h — unused parameters, shadow warnings
• faiss/utils/partitioning.cpp — sign-compare fixes
• faiss/utils/distances_fused/simdlib_based.cpp — sign-compare fix for OpenMP loop
• faiss/cppcontrib/sa_decode/Level2-avx2-inl.h — unused parameter warnings in stubs
• faiss/cppcontrib/sa_decode/PQ-avx2-inl.h — unused parameter warnings in stubs

Both generic and AVX2 builds compile clean with -Wall -Wextra -Wshadow -Werror. All tests pass (195/196 with AVX2, 1 pre-existing failure in TPO.IVFFlatPP unrelated to this PR).

[meta-codesync]

@limqiying has imported this pull request. If you are a Meta employee, you can view this in D94101552.

[mnorris11]

Sorry for the delay on this. I think this would be great to do, but 170 files may be too much to do all at once. There is a big refactor going on with dynamic dispatch of SIMD (see PRs by @algoriddle ). So the code churn will be high until it is complete. If you create smaller (maybe 10-20 files at a time?) PRs, that might be easier to merge in quickly. Or, we can take it up after the dynamic dispatch PRs are all merged.

[maxwbuckley]

@mnorris11 Thanks for the feedback! I've split this PR into 13 smaller PRs (10-20 files each), rebased onto the latest main:

#	PR	Files	Area
1	#4932	15	CMake warning infrastructure
2	#4933	12	Core base classes and headers
3	#4956	12	Graph-based indexes (HNSW, NSG, NNDescent)
4	#4957	14	Quantizer implementations
5	#4936	15	IO, result handlers, misc impl
6	#4937	11	Distance and hamming utilities
7	#4958	10	SIMD, sorting, misc utilities
8	#4939	12	Inverted lists and cppcontrib
9	#4940	12	Binary and misc Index files
10	#4941	8	PQ, PreTransform, Refine Index files
11	#4942	14	IVF Index implementations
12	#4943	13	Top-level FAISS source files
13	#4944	20	Test files

Each PR is independent and can be reviewed/merged separately. All changes are mechanical (variable renames, unused parameter annotations, casts, [[fallthrough]] attributes) with no functional changes.

I'll close this PR in favor of the smaller ones. Let me know if you'd like any of them adjusted!

[maxwbuckley]

Closing in favor of the 13 smaller PRs (see table above). Each can be reviewed and merged independently.