ARM API Reviewer agent: reason about the API as a graph (resource / operation / data-flow / version-delta) rather than a flat list of rules

[ravimeda]

Background

Linear, file-by-file rule scanning catches named-rule violations well but misses systemic problems that emerge only when the API is viewed as a graph:

• Orphan resources (schemas defined but never referenced by an operation).
• Asymmetric CRUD (PUT without DELETE, GET without LIST-by-subscription, list-only resources).
• $ref cycles and silent breaking changes via reference removal.
• Secrets that enter via PUT and leak via LIST.
• Identity-scope mismatches and synchronous POST mutations on tracked resources.

No single rule in the instruction files would catch these in isolation.

Proposal

Introduce Step 3.5, API Graph & Data-Flow Analysis (PR #43494) as a mandatory step on the full-review track. The Reviewer renders four Mermaid views inside the Step 6 report (collapsible <details> blocks):

1. Resource graph: resources touched by the PR; edges = parent/child, extension, $ref.
2. Operation graph: operations per resource; flags CRUD asymmetries.
3. Sensitive-data-flow graph: secret-bearing properties traced from accepting operations to returning operations.
4. Version-delta graph: previous-version overlay (only when a previous version exists).

The Critic independently re-derives each graph and graph-diffs. Graph integrity = FAIL: fabrication is non-overridable. The Reviewer must drop or correct any finding whose evidence depends on a fabricated node or edge.

Size guardrails (post-partition thresholds: > 75 resource nodes, > 200 operations, > 50 secret-bearing nodes) downgrade rendering to summary text, but the sensitive-data-flow view is always re-derived (rendering cost is irrelevant to secret-leak analysis). Failure recovery distinguishes graphs-produced: false (fast path, silent, by design) from graphs-produced: degraded (full-review attempt failed even after retry, requires a [!CAUTION] banner so the review cannot be mistaken for structurally complete).

References

• .github/skills/azure-api-review/references/think-in-graphs.md: canonical specification (node/edge definitions, partition thresholds, graph-only findings catalogue).
• arm-api-reviewer.agent.md, Step 3.5

Acceptance criteria

• Every full-review PR with .tsp or resource-manager .json changes produces the four graph views (or the documented downgrade/degraded fallback).
• The Critic's graph-diff catches at least one missed structural finding on a representative real PR (validation case: PR #40595).
• Evals cover the size-guardrail downgrade and the degraded failure-recovery banner.

[ravimeda]

Addressed by PR #43494 (merged). The relevant changes are now in main. Closing as completed.