Definition-audit pass: verify a function does what its name/signature claims

[smochan]

The idea

An audit pass that checks each function against what its name and signature claim it does, and flags mismatches.

Why it matters

Names and signatures are promises. When the body breaks the promise — validate_* that never returns False, a function annotated to return a list where every path returns None — that's a bug the graph can catch structurally, before anyone runs the code. This is the "check functions against their definition" idea taken to its useful end.

Sketch of an approach

• Build on the control-flow nodes from fix(resolver): R3 — conditional self.X assignment + class-level union types #1 (so the audit can reason about branches/returns) plus the signature/docstring data already on Node.
• Heuristic checks first: return-annotation vs actual return paths; boolean-predicate naming (is_/has_/validate_) vs constant returns; documented raises vs actual raises.
• Report in the existing analysis-output shape (codegraph/analysis/).

Acceptance criteria

• Audit flags at least the return-annotation-vs-paths and predicate-naming mismatches
• Each finding cites file + line + the specific mismatch
• Fixture tests for true positives and for clean functions (no false positives)

Blocked by #1 (needs control-flow nodes).

---

Part of the build-in-public roadmap. Discussed on LinkedIn (link to follow).