Validation is part of the product

A PR Lens graph is meant to become a picture that someone can use to reason about a change. This chapter asks what must be true before that handoff: when is a graph merely well-shaped data, and when is it coherent enough to draw without inventing relationships? It also examines how a repository can correct a recurring naming or boundary problem without editing a generated document that will be replaced on the next run.

Parsing is not integrity

The first failure mode is easy to underestimate. A model can return valid JSON with the right broad fields and still produce a diagram that points at nothing. It might place a node in a lane that was never declared, connect an edge to a misspelled node id, or make a flow message use a participant who appears elsewhere in the graph but not in that flow. From a programming-language perspective, the object may have the right shape. From a reviewer’s perspective, the picture would be false or incomplete.

PR Lens separates these questions. Structural parsing checks the shape of the document. Its objects are strict, so an invented field is an error rather than a suggestion. It checks types, lengths, enums, supported contract versions, identifiers, and file references. A file reference must be repository-relative and use POSIX separators; a line range cannot end before it starts, and an ending line cannot appear without a starting line. A message marked as a self-message must have the same sender and receiver, while other message kinds cannot quietly pretend to be self-messages.

Those checks protect the boundaries at which data leaves the graph. An identifier may later become part of an SVG id, a URL, a comment anchor, or a lookup key. A file reference may later become a link into the base or head revision. A field that is “almost right” at the JSON layer can therefore break the visual or navigational layer downstream. The strictness is not an attempt to make authors memorize every rule. It keeps later components from having to guess what an ambiguous input meant.

The second failure mode is referential integrity. Once the structure has been parsed, PR Lens checks the relationships among declared elements. Every node must name a lane that exists. Every edge must connect two declared nodes. Every flow participant must name a graph node, and every message must run between participants of that particular flow. A flow also requires the data-flow lens to be declared, because a document cannot carry sequence information while claiming it has no sequence view.

The same logic applies to presentation. A view’s selection must point to known lanes, nodes, edges, or flows. A walkthrough stage must name a real view or flow, and a focus on messages must refer to messages in the flow that stage actually shows. Layout hints must refer to existing lanes and nodes. These rules matter because a reader experiences a view or walkthrough as an instruction: look here, then here. If the named target does not exist, the surface would either fail visibly or, worse, substitute a different target.

The validator reports all problems it finds, with paths into the document and machine-readable error codes.