initial commit

README.md

@@ -0,0 +1,118 @@
+`errorck` is a Clang libTooling–based static analysis tool for measuring how
+often error-returning functions are ignored, partially handled, or handled
+with future-proof catch-all logic in real-world C and C++ codebases.
+
+It is intended for large-scale, empirical analysis across many projects,
+not as an interactive linter.
+
+## Overview
+
+`errorck` analyzes calls to a fixed set of error-returning functions
+(hardcoded in the source for now) and classifies how each call’s return
+value is handled. It also detects simple one-layer wrapper functions that
+forward error codes (e.g. project-specific allocation wrappers) and treats
+calls through those wrappers equivalently.
+
+The tool emits machine-readable output suitable for ingestion into a
+database and later statistical analysis.
+
+## What `errorck` detects
+
+For each call to a watched function (or trivial wrapper), `errorck` classifies
+the handling into one of the following categories:
+
+    ignored
+    	The return value is discarded and not read.
+
+    assigned_not_read
+    	The return value is assigned to a local variable but never read,
+    	branched on, or returned.
+
+    branched_no_catchall
+    	The return value is used in an if or switch, but there is no
+    	else/default branch to handle future error cases.
+
+    branched_with_catchall
+    	The return value is branched on and includes an else or default.
+
+    propagated
+    	The return value is returned directly to the caller.
+
+    used_other
+    	The return value is used in some other way (logging, passed to
+    	another function, etc.).
+
+For reporting purposes, the following are considered “ignored” error
+conditions:
+
+- ignored
+- assigned_not_read
+- branched_no_catchall
+
+## Trivial wrapper detection
+
+`errorck` detects one layer of trivial wrappers around watched functions.
+A function is considered a trivial wrapper if it:
+
+- returns a watched function call directly, or
+- assigns the result of a watched function call to a local variable,
+  optionally branches or logs based on that value, and then returns the
+  value unchanged.
+
+Wrappers are reported explicitly, and calls through wrappers are attributed
+to the underlying base function.
+
+## Limitations
+
+`errorck` deliberately trades completeness for scalability and clarity.
+
+Current limitations include:
+
+- One-layer wrapper detection only
+- No interprocedural dataflow
+- No function pointer resolution
+- Simplified wrapper body patterns (single return, single result variable)
+- Catch-all detection limited to else/default
+- Analysis is per-translation-unit
+
+These limitations are documented and must be considered when interpreting
+results.
+
+## Building
+
+`errorck` requires LLVM/Clang with libTooling.
+
+A minimal build using llvm-config:
+
+    $ c++ -std=c++17 `errorck`.cpp -o `errorck` \
+        `llvm-config --cxxflags --ldflags --system-libs \
+         --libs core clangTooling clangFrontend clangAST clangBasic`
+
+Alternatively, a CMake build can be used.
+
+## Running
+
+`errorck` requires a compilation database.
+
+    $ `errorck` -p /path/to/build file1.c file2.cpp ...
+
+Output is written to stdout as JSON Lines (one record per line).
+
+Example:
+
+    $ `errorck` -p . src/*.c > results.jsonl
+
+## Intended use
+
+`errorck` is designed for:
+
+- empirical studies of error handling
+- large-scale analysis across many repositories
+- research and auditing, not enforcement
+
+It is not intended to replace compiler warnings or linters.
+
+## License
+
+Public domain, Unlicense, 0BSD, or CC0. Whichever you prefer. The 0BSD license
+is included in the source distribution.