Add README with build/usage instructions and benchmark numbers

Benchmark: one real run against spdlog (v1.17.0, commit 989d28d),
~27.5k LOC across include/+src/, 7 TUs. Average of 3 runs on this
machine: 1.76s wall clock, ~15,650 LOC/s, ~189 MiB peak RSS. Also
turned up a real pre-existing redundant-move-return case in spdlog's
own pattern_formatter-inl.h.

Author: czhao-dev

README.md

@@ -0,0 +1,153 @@
+# cpp-sentinel
+
+A command-line static analyzer for C++17/20, built on Clang LibTooling, AST
+Matchers, and a hand-rolled lock-order graph analysis. Loads a
+`compile_commands.json`, analyzes real translation units, and reports
+defects with precise source locations.
+
+This is the MVP scoped in [`docs/spec.md`](docs/spec.md): three rules,
+text/JSON output, YAML config with suppression, and one flagship
+cross-file rule with real graph-algorithm teeth. See
+[`docs/architecture.md`](docs/architecture.md) for how it's built
+internally.
+
+## Rules
+
+| Rule | Kind | What it catches |
+|---|---|---|
+| `missing-override` | AST | A virtual method that overrides a base method without the `override` keyword. |
+| `redundant-move-return` | AST | `return std::move(local);`, which suppresses NRVO for no benefit. |
+| `lock-order-inversion` | CFG + cross-file graph | A cycle in lock acquisition order across the whole project (a potential deadlock), found via Tarjan's SCC over a project-wide lock graph. |
+
+`lock-order-inversion` is the flagship: it tracks which locks are held
+through each function (explicit `lock()`/`unlock()` and
+`lock_guard`/`unique_lock` RAII scopes), accumulates that as facts across
+every translation unit in the run, and only after all of them are
+processed builds the merged graph and looks for cycles. Two files can each
+be individually lock-order-safe and still form a cycle once merged --
+that's the case the flagship is built to catch (see
+`tests/projects/lock-cycle/`).
+
+## Building
+
+Requires CMake 3.20+, a C++20 compiler, and LLVM/Clang dev packages
+(headers + the CMake config files, i.e.
+`LLVMConfig.cmake`/`ClangConfig.cmake`). Developed and CI-tested against
+LLVM/Clang 22; other reasonably recent versions likely work but aren't
+verified.
+
+```bash
+# macOS (Homebrew)
+brew install llvm cmake
+
+# Ubuntu/Debian
+wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 22 all
+```
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j"$(nproc)"
+ctest --test-dir build --output-on-failure
+```
+
+GoogleTest and yaml-cpp are pulled in automatically via `FetchContent` --
+no need to install them separately. On macOS, CMake is pointed at
+`/opt/homebrew/opt/llvm` by default; override with
+`-DCMAKE_PREFIX_PATH=<your LLVM prefix>` if yours lives elsewhere.
+
+## Usage
+
+```bash
+cpp-sentinel analyze --compile-commands build/compile_commands.json
+
+cpp-sentinel analyze --compile-commands build/compile_commands.json \
+    --format json --output report.json
+
+cpp-sentinel list-rules
+cpp-sentinel explain lock-order-inversion
+```
+
+Key `analyze` options: `--format text|json`, `--output <file>`,
+`--enable`/`--disable <rule-id>` (repeatable), `--config <file.yaml>`,
+`--include`/`--exclude <glob>` (repeatable), `--fail-on warning|error`.
+
+Exit codes: `0` clean, `1` findings at/above `--fail-on`, `2` usage/config
+error, `4` a translation unit failed to compile.
+
+### Config file
+
+```yaml
+rules:
+  enable: [missing-override, redundant-move-return]
+  disable: [lock-order-inversion]
+```
+
+### Suppression
+
+```cpp
+int x = risky();  // cpp-sentinel-ignore some-rule
+
+// cpp-sentinel-disable some-rule
+... code some-rule won't be applied to ...
+// cpp-sentinel-enable some-rule
+```
+
+Either form works with no rule id too (`// cpp-sentinel-ignore` suppresses
+every rule on that line).
+
+## Demonstration
+
+1. Build a small multithreaded sample with an intentional lock-order bug
+   spanning two files (`tests/projects/lock-cycle/` is exactly this).
+2. `cpp-sentinel analyze --compile-commands build/compile_commands.json`
+   -- shows the missing-`override` and redundant-move-return catches.
+3. The same run reports the cross-file lock cycle, with both acquisition
+   sites' source locations.
+4. Re-run with `--format json` to show the structured output.
+
+## Benchmark
+
+One real run against [spdlog](https://github.com/gabime/spdlog) at commit
+[`989d28d`](https://github.com/gabime/spdlog/commit/989d28dd768adef702538634857942db24e1058a)
+(v1.17.0) -- a real-world, mutex-heavy C++ logging library, ~27.5k LOC
+across `include/` + `src/`, 7 translation units in its compiled-library
+configuration (`-DSPDLOG_BUILD_EXAMPLE=OFF -DSPDLOG_BUILD_TESTS=OFF`).
+Measured on an Apple M-series machine, Release build, single-threaded
+(no parallel scheduler in the MVP), average of 3 runs:
+
+| Metric | Value |
+|---|---|
+| Wall clock | 1.76 s |
+| Throughput | ~15,650 LOC/s |
+| Peak RSS | ~189 MiB (198 MB) |
+
+It also found a real, pre-existing `redundant-move-return` case in
+spdlog's own `pattern_formatter-inl.h`.
+
+This is one honest number, not a benchmark suite -- see
+[`docs/spec.md`](docs/spec.md) §10/§14 for what's deliberately out of
+scope for the MVP (parallel/incremental analysis, a benchmark corpus,
+scaling studies).
+
+## Known limitations
+
+- Single-threaded, no incremental caching (analyzes every TU from scratch
+  every run).
+- `lock-order-inversion`: no alias analysis (two pointers to the same
+  mutex are different lock ids unless they resolve to the same
+  `VarDecl`/`FieldDecl`), loop bodies walked once rather than to a
+  dataflow fixed point, only `lock_guard`/`unique_lock` RAII wrappers
+  recognized (not `scoped_lock`), `unique_lock`'s `defer_lock` form is
+  treated as an immediate acquisition.
+- `redundant-move-return` doesn't verify all of a function's return paths
+  agree on the same NRVO candidate.
+- Text/JSON output only (no SARIF yet -- the JSON schema is deliberately
+  close enough that adding one later is a serialization change, not a
+  redesign).
+
+Full roadmap for what comes after the MVP is in
+[`docs/spec.md`](docs/spec.md) §14.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).