codeql: add maybe-missing.ql to detect MAYBE-wrap gaps

Flags calls to rebrgen's fallible accessor APIs (`ctx.get`, `ctx.get_field`,
`ctx.visit`, `ctx.identifier`) whose result has `operator!` semantics
(pointer or `expected<>`) but is neither MAYBE-wrapped nor explicitly
checked via `if (...)` / `!` / `.has_value()` / `.has_error()`.

Heuristic also accepts the "save then check" idiom:

    auto x = ctx.get(ref);
    if (x) { ... use *x ... }

is treated as checked.

Test-scaffolding functions (`test_*`) are excluded; the rebrgen codebase has
one such smoke-test that intentionally discards a `visit()` return.

Baseline on the ebm2zig DB after filters:
  total findings: 1 (`includes.hpp:22`, likely an intentional bypass where
  the callee handles null input gracefully)
versus 222 before filters (most being saved-then-checked locals in the
generated main.cpp).

Each finding is a review candidate, not a definite bug — some bypasses are
deliberate. README updated accordingly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: on-keyday

rebrgen/codeql-queries/README.md

@@ -91,14 +91,20 @@ for run in d['runs']:
 
 ## Empirical baseline (taken from ebm2zig on 2026-05-26)
 
-| Query                              | Hits | What it means                                          |
-| ---------------------------------- | ---- | ------------------------------------------------------ |
-| `escaped-ref-capture.ql`           | 0    | No truly dangerous escapes in current code.            |
-| `escaped-ref-capture-review.ql`    | 13   | All `[&]ctx` patterns — safe today via dispatch_entry. |
+| Query                              | Hits | What it means                                                              |
+| ---------------------------------- | ---- | -------------------------------------------------------------------------- |
+| `escaped-ref-capture.ql`           | 0    | No truly dangerous escapes in current code.                                |
+| `escaped-ref-capture-review.ql`    | 13   | All `[&]ctx` patterns — safe today via dispatch_entry.                     |
+| `maybe-missing.ql`                 | 1    | Review candidate at `includes.hpp:22`; likely an intentional bypass.       |
 
-If the strict query starts firing in the future, that's a real bug. If the
-review-aid count changes, audit what changed — new patterns may break the
-dispatch_entry lifetime invariant.
+If the strict capture query starts firing in the future, that's a real bug.
+If the review-aid count changes, audit what changed — new patterns may break
+the dispatch_entry lifetime invariant.
+
+`maybe-missing.ql` will produce some false positives by design (the codebase
+has intentional bypasses where the callee handles null input gracefully).
+Treat its output as a review queue: each hit is either a real propagation
+gap or an intentional bypass to document/annotate.
 
 ## Iterating on a query
 
@@ -133,6 +139,7 @@ results.
 | `codeql-pack.lock.yml`            | Pinned dependency versions (generated by `codeql pack install`)      |
 | `escaped-ref-capture.ql`          | Strict: definitely-escaped auto-storage locals (0 hits on ebm2zig)   |
 | `escaped-ref-capture-review.ql`   | Loose: includes reference captures, for human lifetime audit         |
+| `maybe-missing.ql`                | Fallible accessor calls (get / get_field / visit / identifier) that are neither MAYBE-wrapped nor explicitly checked |
 
 ## Adding a new query
 

rebrgen/codeql-queries/maybe-missing.ql

@@ -0,0 +1,92 @@
+/**
+ * @name Fallible accessor used outside MAYBE / explicit check
+ * @description Detects calls to rebrgen accessor APIs (`ctx.get`,
+ *              `ctx.get_field<>`, `ctx.visit`, `ctx.identifier`) whose result
+ *              has `operator!` semantics (pointer or `expected<T>`) but is
+ *              not consumed through the `MAYBE(name, expr)` macro nor through
+ *              an explicit `if (!x)` / `if (x)` / `x.has_value()` style check.
+ *
+ *              In rebrgen the convention is that every fallible accessor goes
+ *              through MAYBE so nullptr / unexpected propagates as an error
+ *              return instead of crashing. AI-generated code often skips this.
+ *
+ * @kind problem
+ * @problem.severity warning
+ * @id rebrgen/maybe-missing
+ * @tags correctness
+ *       rebrgen-custom
+ */
+
+import cpp
+
+/** A call to one of the rebrgen accessor APIs whose result is nullable
+ *  (raw pointer) or expected-of-something. */
+class FallibleAccessorCall extends FunctionCall {
+  FallibleAccessorCall() {
+    this.getTarget().getName() in ["get", "get_field", "visit", "identifier"] and
+    (
+      this.getType().getUnspecifiedType() instanceof PointerType
+      or this.getType().getUnspecifiedType().toString().matches("expected<%>")
+    )
+  }
+}
+
+/** An invocation of the MAYBE / MAYBE_VOID macro. */
+class MaybeMacroInvocation extends MacroInvocation {
+  MaybeMacroInvocation() { this.getMacroName() = ["MAYBE", "MAYBE_VOID"] }
+}
+
+/** True if `e` lives inside the expansion of a MAYBE / MAYBE_VOID macro. */
+predicate insideMaybe(Expr e) {
+  exists(MaybeMacroInvocation m | m.getAnExpandedElement() = e)
+}
+
+/** True if `e` (or its surrounding sub-expression chain) is consumed by a
+ *  truthiness check: `!e`, `if (e)`, `while (e)`, `e ? a : b`,
+ *  or `e.has_value()` / `e.has_error()` / `e.value()` / `e.error()`. */
+predicate isCheckedExpr(Expr e) {
+  exists(NotExpr n | n.getOperand() = e.getParent*())
+  or
+  exists(IfStmt s | s.getCondition() = e.getParent*())
+  or
+  exists(WhileStmt s | s.getCondition() = e.getParent*())
+  or
+  exists(ConditionalExpr s | s.getCondition() = e.getParent*())
+  or
+  exists(FunctionCall chk |
+    chk.getQualifier() = e.getParent*() and
+    chk.getTarget().getName() in ["has_value", "has_error", "error", "value"]
+  )
+}
+
+/** True if the call result reaches an explicit check, either directly or
+ *  via a local variable that captures it (`auto x = call(); if (x) ...`). */
+predicate explicitlyChecked(Expr call) {
+  isCheckedExpr(call)
+  or
+  // Local variable initialized from the call, later checked.
+  exists(LocalVariable v |
+    v.getInitializer().getExpr().getFullyConverted() = call.getFullyConverted() and
+    isCheckedExpr(v.getAnAccess())
+  )
+}
+
+/** True if the call is the direct return value (`return call;`) — no
+ *  unwrap needed when propagating verbatim. */
+predicate directlyReturned(Expr call) {
+  exists(ReturnStmt r | r.getExpr() = call.getParent*())
+}
+
+from FallibleAccessorCall call
+where
+  not insideMaybe(call) and
+  not explicitlyChecked(call) and
+  not directlyReturned(call) and
+  // skip obvious test scaffolding
+  not call.getEnclosingFunction().getName().matches("test_%")
+select call,
+  "[REVIEW] Fallible call `" + call.getTarget().getName() +
+    "(...)` -> `" + call.getType().getUnspecifiedType().toString() +
+    "`: not MAYBE-wrapped and not explicitly checked. Some bypasses are " +
+    "intentional (e.g. when the callee handles null input gracefully); " +
+    "treat as a review candidate, not a definite bug."