Report directory and metadata.json format specification

docs/README.md

@@ -411,9 +411,12 @@ you should be greeted with a web application showing you the analysis results.
 
 ## Developer documentations
 * [Architecture](architecture.md)
+* [Report Directory Specification](report_directory.md)
+* [Plist Report Format Specification](tools/plist.md)
 * [Package layout](package_layout.md)
 * [Dependencies](deps.md)
 * [Thrift interface](web/api/README.md)
+* [Sample CodeChecker Command Line Client](/scripts/thrift/README.md)
 * [Package and integration tests](tests.md)
 * [Server-side background tasks](web/background_tasks.md)
 

docs/report_directory.md

@@ -0,0 +1,220 @@
+# CodeChecker Report Directory Structure
+
+## Overview
+
+This directory contains static analysis reports generated by `CodeChecker analyze` for C/C++ projects. The report directory format is standardized within CodeChecker and it is assumed by various sub-commands such as `CodeChecker parse/store`.
+
+Other tools, such as CodeChecker [bazel rules](https://github.com/Ericsson/rules_codechecker) should follow this specification to be compatible with the CodeChecker ecosystem.
+
+## Directory Layout
+
+```
+report_directory/
+├── metadata.json                       # Analysis metadata and configuration. (used opionally by store)
+├── compiler_info.json                  # Compiler details and flags. (for debugging)
+├── compile_cmd.json                    # Compilation commands. (for debugging)
+├── unique_compile_commands.json        # Deduplicated compilation commands (for debugging)
+├── <file>_<analyzer>_<hash>.plist      # Successful analysis results (used by parse and store)
+├── <file>_<analyzer>_<hash>.plist.err  # Analysis error logs (used by parse --status)
+├── cppcheck/                           # Cppcheck backup files
+│   └── <hash>/
+│       └── *.plist.bak
+├── gcc/                                # GCC analyzer backup files (for debugging)
+│   └── *.sarif.bak
+├── fixit/                              # Clang-tidy fix suggestions (used optionall by store))
+│   └── *_clang-tidy_*.yaml
+├── failed/                             # Failed analysis artifacts (for debugging)
+│   └── *_compile_error.zip
+└── ctu_connections/                    # Cross-translation unit data (for debugging)
+```
+### Usage
+
+* `CodeChecker store` stores the reports found in the `plist` files and optionally parses the information in the `metadata.json`.
+
+* `CodeChecker parse` displays the reports in the `plist` files and displays analysis status based on the existence of the `plist` or `plist.err` files.
+
+* `CodeChecker parse --file` relies on the `result_source_files` section of the `metadata.json`.
+
+* `CodeChecker fixit` relies on the `fixit` subdirectory.
+## File Types
+
+### Information files
+
+- **metadata.json** - Contains:
+  - CodeChecker version
+  - Analysis command
+  - Enabled analyzers and checkers
+  - Source file mappings
+  - Analysis statistics
+
+- **compiler_info.json** - Compiler configuration:
+  - Compiler path and version
+  - Include directories
+  - Language standard
+  - Target architecture
+
+- **compile_cmd.json** - Compilation database with build commands for each source file
+
+### Report Files
+
+Format: `<source_file>_<analyzer>_<hash>.plist`
+
+**Analyzers:**
+- `clang-tidy` - C++ linter with 600+ checks
+- `clangsa` - Clang Static Analyzer
+- `cppcheck` - C/C++ static analyzer
+- `gcc` - GCC static analyzer
+
+**Report Format:** Apple Property List (plist) XML containing:
+- Diagnostics with severity, category, and description
+- File locations (line, column)
+- Execution paths showing issue flow
+- Check names for filtering
+
+**Error Files** (`.plist.err`):
+- Generated when analysis fails
+- Contains analyzer command, return code, stderr, and stdout
+- Includes compiler errors and warnings that prevented analysis
+
+### Auxiliary Directories
+
+- **fixit/** - YAML files with automated fix suggestions from clang-tidy
+- **cppcheck/**, **gcc/** - Backup copies of original reports
+- **failed/** - ZIP archives of failed analysis attempts with compile errors
+- **ctu_connections/** - Cross-translation unit analysis metadata
+
+## Metadata Structure
+
+The `metadata.json` file contains comprehensive information about the analysis run, including configuration, enabled checkers, and statistics.
+
+### Field Descriptions
+
+`Metadata format version : 2`
+
+**Top-level fields:**
+- `version` - Metadata format version
+- `tools` - Array of tool configurations (typically one CodeChecker entry)
+
+**Tool object fields:**
+- `name` - Tool name ("codechecker")
+- `action_num` - Number of compilation actions analyzed
+- `command` - Full command line used to invoke the analysis
+- `version` - CodeChecker version with git commit hash
+- `working_directory` - Project root directory where analysis was executed
+- `output_path` - Absolute path to report directory
+- `result_source_files` - Map of report files to their source files
+- `analyzers` - Configuration for each analyzer (clangsa, clang-tidy, cppcheck, gcc)
+- `skipped` - Number of skipped source files
+- `timestamps` - Analysis start (`begin`) and end (`end`) times in Unix epoch
+
+**Analyzer object fields:**
+- `checkers` - Map of checker names to enabled status (true/false)
+- `analyzer_statistics` - Analysis results summary
+  - `failed` - Count of failed analyses
+  - `failed_sources` - List of source files that failed analysis
+  - `successful` - Count of successful analyses
+  - `successful_sources` - List of successfully analyzed source files
+  - `version` - Analyzer version
+
+### Example
+
+```json
+{
+  "version": 2,
+  "tools": [{
+    "name": "codechecker",
+    "action_num": 3,
+    "command": [
+      "analyze",
+      "-d", "default",
+      "-e", "optin.taint",
+      "--timeout", "300",
+      "./src/file.c",
+      "-o", "./reports"
+    ],
+    "version": "6.28 (2281ca3ce898b1061063ded46b7754f5da6281f5)",
+    "working_directory": "/workspace/project",
+    "output_path": "/workspace/project/reports",
+    "result_source_files": {
+      "/workspace/project/reports/file.c_clangsa_abc123.plist": "/workspace/project/src/file.c"
+    },
+    "analyzers": {
+      "clangsa": {
+        "checkers": {
+          "optin.taint.GenericTaint": true,
+          "optin.taint.TaintedAlloc": true,
+          "core.NullDereference": false,
+          "core.DivideZero": false
+        },
+        "analyzer_statistics": {
+          "failed": 0,
+          "failed_sources": [],
+          "successful": 3,
+          "successful_sources": [
+            "/workspace/project/src/file.c"
+          ],
+          "version": "20.0.0"
+        }
+      }
+    },
+    "skipped": 0,
+    "timestamps": {
+      "begin": 1770915554.200186,
+      "end": 1770915561.956268
+    }
+  }]
+}
+```
+
+## Report File Structure
+
+For detailed plist format specification, see [plist.md](tools/plist.md).
+
+### Success Report (.plist)
+
+```xml
+<plist>
+  <dict>
+    <key>diagnostics</key>
+    <array>
+      <dict>
+        <key>check_name</key>
+        <string>cert-err33-c</string>
+        <key>description</key>
+        <string>Issue description</string>
+        <key>category</key>
+        <string>cert</string>
+        <key>location</key>
+        <dict>
+          <key>line</key><integer>564</integer>
+          <key>col</key><integer>5</integer>
+          <key>file</key><integer>0</integer>
+        </dict>
+        <key>path</key>
+        <array><!-- Execution path --></array>
+      </dict>
+    </array>
+    <key>files</key>
+    <array><!-- Source file paths --></array>
+  </dict>
+</plist>
+```
+
+### Error Report (.plist.err)
+
+```xml
+<plist>
+  <dict>
+    <key>analyzer_cmd</key>
+    <array><!-- Full analyzer command --></array>
+    <key>analyzer_name</key>
+    <string>clang-tidy</string>
+    <key>return_code</key>
+    <integer>1</integer>
+    <key>stderr</key>
+    <string>Error messages</string>
+    <key>stdout</key>
+    <string>Warnings and errors</string>
+  </dict>
+</plist>
+```