y2038: eliminate false positives with automatic build system detection

The Y2038 addon currently generates false positive warnings when scanning
  codebases that are properly configured for Y2038 safety through build
  system flags, making it impractical for comprehensive codebase analysis.

  This prevents teams from running Y2038 checks across entire projects in
  CI/CD pipelines due to noise from correctly configured code.

  Add automatic build system detection to discover Y2038-related compiler
  flags (_TIME_BITS=64, _FILE_OFFSET_BITS=64, _USE_TIME_BITS64) from:

  - Makefile variants (Makefile, makefile, GNUmakefile, *.mk)
  - CMake files (CMakeLists.txt, *.cmake)
  - Meson build files (meson.build)
  - Autotools scripts (configure, configure.ac, configure.in)
  - Compiler flags passed via cppcheck -D options

  When proper Y2038 configuration is detected (both _TIME_BITS=64 AND
  _FILE_OFFSET_BITS=64), suppress Y2038 warnings and display an
  informational message indicating the configuration source.

  Implement hierarchical directory search up to 5 levels from source files
  to locate relevant build files, with flag precedence: build system >
  compiler flags > source code #define directives.

  Add performance optimizations:
  - Intelligent file caching with TTL-based invalidation
  - UTF-8 BOM handling for cross-platform compatibility
  - Robust import fallback system

  Extend test suite with comprehensive coverage:
  - Compiler flag parsing edge cases (18 test scenarios)
  - Build system detection for all supported formats
  - Caching behavior and performance validation
  - Cross-platform file encoding handling

  This enables organizations to run comprehensive Y2038 analysis on entire
  codebases without false positives from properly configured projects,
  while maintaining detection of actual Y2038 safety issues.

Author: Hiesx

AUTHORS

@@ -238,6 +238,7 @@ Ludvig Gunne Lindström
 Luis Díaz Más
 Luís Pereira
 Lukas Grützmacher
+Lukas Hiesmayr
 Lukasz Czajczyk
 Łukasz Jankowski
 Luxon Jean-Pierre

addons/doc/y2038.md

@@ -0,0 +1,183 @@
+# README of the Y2038 cppcheck addon
+
+## Contents
+
+- [README of the Y2038 cppcheck addon](#readme-of-the-y2038-cppcheck-addon)
+  - [Contents](#contents)
+  - [What is Y2038?](#what-is-y2038)
+  - [What is the Y2038 cppcheck addon?](#what-is-the-y2038-cppcheck-addon)
+  - [How does the Y2038 cppcheck addon work?](#how-does-the-y2038-cppcheck-addon-work)
+    - [Primary Usage: Cppcheck Addon Integration (`y2038.py`)](#primary-usage-cppcheck-addon-integration-y2038py)
+      - [Implementation Details](#implementation-details)
+  - [Requirements](#requirements)
+  - [How to use the Y2038 cppcheck addon](#how-to-use-the-y2038-cppcheck-addon)
+    - [**Auditing Your Project for Y2038 Compliance**](#auditing-your-project-for-y2038-compliance)
+    - [**CI/CD Integration**](#cicd-integration)
+  - [Testing](#testing)
+    - [Running Y2038 Addon Tests](#running-y2038-addon-tests)
+    - [Test Coverage](#test-coverage)
+    - [Test Structure](#test-structure)
+
+---
+
+## What is Y2038?
+
+In a few words:
+
+In Linux, the current date and time is kept as the number of seconds elapsed
+since the Unix epoch, that is, since January 1st, 1970 at 00:00:00 GMT.
+
+Most of the time, this representation is stored as a 32-bit signed quantity.
+
+On January 19th, 2038 at 03:14:07 GMT, such 32-bit representations will reach
+their maximum positive value.
+
+What happens then is unpredictable: system time might roll back to December
+13th, 1901 at 19:55:13, or it might keep running on until February 7th, 2106
+at 06:28:15 GMT, or the computer may freeze, or just about anything you can
+think of, plus a few ones you can't.
+
+The workaround for this is to switch to a 64-bit signed representation of time
+as seconds from the Unix epoch. This representation will work for more than 250
+billion years.
+
+Working around Y2038 requires fixing the Linux kernel, the C libraries, and
+any user code around which uses 32-bit epoch representations.
+
+There is Y2038-proofing work in progress on the Linux and GNU glibc front.
+
+## What is the Y2038 cppcheck addon?
+
+The Y2038 cppcheck addon is a tool to help detect code which might need fixing
+because it is Y2038-unsafe. This may be because it uses types or functions from
+GNU libc or from the Linux kernel which are known not to be Y2038-proof.
+
+## How does the Y2038 cppcheck addon work?
+
+The Y2038 addon is a comprehensive tool designed to audit your project for Y2038 compliance. It provides a streamlined, intelligent approach to Y2038 analysis.
+
+### Primary Usage: Cppcheck Addon Integration (`y2038.py`)
+
+The main addon `addons/y2038.py` is designed to be used directly with cppcheck using the command:
+
+```bash
+cppcheck --addon=addons/y2038.py source_file.c
+```
+
+The addon implements intelligent flag detection with a simplified 2-tier priority system:
+
+1. **Build system flags** (highest priority) - Extracted from `compile_commands.json` when available
+2. **Source code directives** (fallback) - `#define` statements in the source code
+
+#### Implementation Details
+
+The addon uses an intelligent, automated approach:
+
+- **Automatic Build System Integration**: When analyzing a source file, the addon automatically detects if the project uses a build system (Make, CMake, Meson, Autotools) and generates `compile_commands.json` if needed using the helper library `y2038_buildsystem.py`
+- **Flag Extraction**: Parses compilation commands to extract Y2038-relevant flags (`_TIME_BITS`, `_FILE_OFFSET_BITS`, `_USE_TIME_BITS64`)
+- **Priority Logic**: If build system flags are found, they take complete precedence over any source code directives
+- **Source Fallback**: Only when no build system configuration is available, the addon analyzes source code `#define` statements
+
+This architecture ensures seamless integration with any build system while maintaining the simplicity of direct cppcheck addon usage. The build system detection and `compile_commands.json` generation happens automatically behind the scenes when needed.
+
+The output is the standard Cppcheck analysis report, focused on Y2038-related issues.
+
+## Requirements
+
+For Make-based and Autotools-based projects, the `y2038_buildsystem.py` script requires the `bear` utility to be installed and available in the system's `PATH`.
+
+`bear` is used to intercept compiler calls during the build process and generate the `compile_commands.json` file, which is essential for Cppcheck to analyze your project correctly.
+
+You can typically install `bear` using your system's package manager:
+
+```
+# On Debian/Ubuntu
+sudo apt-get install bear
+
+# On Fedora
+sudo dnf install bear
+
+# On macOS (using Homebrew)
+brew install bear
+```
+
+## How to use the Y2038 cppcheck addon
+
+### **Auditing Your Project for Y2038 Compliance**
+
+The Y2038 addon seamlessly integrates with your existing cppcheck workflow. Simply use the addon flag with cppcheck:
+
+```bash
+cppcheck --addon=addons/y2038.py source_file.c
+```
+
+**For project-wide analysis:**
+
+```bash
+cppcheck --addon=addons/y2038.py src/
+```
+
+The addon automatically:
+
+1.  **Detects your build system** (e.g., Make, CMake, Meson, Autotools) if present
+2.  **Generates `compile_commands.json`** when needed for accurate analysis
+3.  **Extracts Y2038-relevant compilation flags** from your build configuration
+4.  **Analyzes source code** with proper Y2038 context
+
+### **CI/CD Integration**
+
+For CI/CD integration, you can use the Y2038 addon directly with cppcheck:
+
+```sh
+# Example CI script
+#!/bin/bash
+cppcheck --addon=addons/y2038.py --error-exitcode=1 src/
+
+# The addon will return a non-zero exit code if Y2038 issues are found.
+# The output is the standard Cppcheck report.
+```
+
+**Alternative CI approach using the build system helper:**
+
+```sh
+# Example CI script for build system integration
+#!/bin/bash
+python3 addons/y2038_buildsystem.py /path/to/your/project
+```
+
+## Testing
+
+The Y2038 addon includes comprehensive test suites to ensure reliability and correctness:
+
+### Running Y2038 Addon Tests
+
+To run the Y2038 addon tests, execute:
+
+```bash
+# Run the main Y2038 addon tests
+python3 -m pytest addons/test/y2038_test.py -v
+
+# Run the build system integration tests
+python3 -m pytest addons/test/test_y2038_buildsystem.py -v
+
+# Run all Y2038-related tests
+python3 -m pytest addons/test/ -k y2038 -v
+```
+
+### Test Coverage
+
+The test suite covers:
+
+- **Core Y2038 detection logic**: Testing identification of Y2038-unsafe functions and types
+- **Compiler flag parsing**: Validation of `_TIME_BITS`, `_FILE_OFFSET_BITS`, and `_USE_TIME_BITS64` detection
+- **Build system integration**: Testing automatic build system detection and `compile_commands.json` generation
+- **Priority-based flag resolution**: Ensuring build system flags take precedence over source directives
+- **Warning suppression**: Verifying proper Y2038-safe configuration detection and warning suppression
+- **Error reporting**: Testing accurate error messages and source attribution
+
+### Test Structure
+
+- `addons/test/y2038_test.py` - Core addon functionality tests
+- `addons/test/test_y2038_buildsystem.py` - Build system integration tests
+
+The tests use mock objects and temporary directories to simulate various project configurations and build systems without requiring actual build tools to be installed.