Function-level lint: flag functions with weak or missing contracts

[smochan]

The idea

A function-level lint pass that flags functions which are technically defined but practically landmines: no docstring, no clear contract, or a signature that lies about what it returns.

Why it matters

"Defined" and "actually defined" are different things. A function named validate_user with no docstring and a bare -> bool that always returns True is a trap for both humans and agents. Surfacing these makes the graph a quality signal, not just a map.

Sketch of an approach

• Node already carries signature and docstring in codegraph/graph/schema.py, so this is largely a query-and-report pass over existing graph data — no new extraction required to start.
• Start with cheap, high-signal rules: missing docstring on a public function; return annotation present but no return in the body; parameter documented that no longer exists.
• Emit findings in the same shape as existing analysis outputs (see codegraph/analysis/).

Acceptance criteria

• A lint command/report lists functions failing the initial rule set
• Rules are individually toggleable
• Test coverage for each rule with a small fixture
• Zero false positives on the repo's own well-documented public API

---

Part of the build-in-public roadmap. Good first issue — mostly reads existing graph data. Discussed on LinkedIn (link to follow).