{"slug": "why-a-pr-walkthrough-can-pass-validation-and-still-be-hard-to-read", "title": "Why a PR walkthrough can pass validation and still be hard to read", "summary": "A developer built PR Tour, a tool that generates a single HTML file for reading pull requests, using a coding agent to author reading order, explanations, and definition mappings into a manifest that a Python builder validates against the repository. The builder verifies that excerpts and line numbers refer to the same source revision, checks line numbering and text on both sides of the diff, requires every changed file to appear in a reading step, and converts Python code-point string positions to JavaScript UTF-16 offsets for definition links. The developer notes that these checks establish reproducible source references but do not prove that explanations correctly describe a change or improve reader comprehension.", "body_md": "I made an HTML guide for reading pull requests. When I shared it with coworkers, the visual feedback was encouraging, but I still felt that parts were hard to follow. One person wanted to see the explanation before the code pane, which led to a layout switch.\n\nThat feedback points to a limit of validation: source references can all be valid while the reader still lacks the context needed to understand a change.\n\nThe implementation discussed here is my project, PR Tour. A coding agent writes the reading order, explanations, and definition mappings into a manifest. A Python builder reads the repository and produces the HTML. The builder can check the source material much more directly than it can check the explanation.\n\nThe manifest records the PR URL and base and head commits. The builder resolves the commits, computes their merge base, and collects the changed files between that merge base and the head. The left and right sides of the guide come from those snapshots.\n\nThis makes a reference reproducible. It also imposes a limit: if the PR changes afterward, the saved HTML still describes the old snapshot. A working link to a PR does not make the embedded code current.\n\nThe useful invariant is that an excerpt and its line numbers refer to the same source revision. Whether the explanation correctly describes that revision remains a separate review question.\n\nA normal diff omits unchanged regions. For supported text files, the builder adds that context back as expandable rows, then checks the result against the source from Git.\n\nIt checks two properties on each side:\n\nChecking the numbering alone would leave room for incorrect text at a valid position. Checking text alone would miss errors in the line labels that notes rely on. Both are needed for a trustworthy source view.\n\nThe builder also requires every changed file to appear in a reading step, including files it cannot render as a text diff. Binary and non-UTF-8 files get a notice directing the reader to GitHub.\n\nThat is file coverage, not explanation coverage. A step can mention a file and still omit an important failure path. The same file can also appear in multiple steps, because following a behavior may require returning to it later.\n\nDefinition previews use authored mappings. The builder verifies that the target exists, its source range is valid, and the clickable text matches the source. An explicit text link must be unambiguous or include its column. Overlapping links are rejected.\n\nThere is a small cross-language detail here: Python string positions count Unicode code points, while JavaScript string slicing counts UTF-16 code units. The builder converts positions before rendering them in the browser:\n\n```\nstart = len(line[:column].encode(\"utf-16-le\")) // 2\nend = start + len(link_text.encode(\"utf-16-le\")) // 2\n```\n\nFor example, in `\"😀send\"`, Python places the `s` at index 1. JavaScript places it at index 2. Sending the Python index directly to JavaScript would put the link at the wrong position. The conversion concerns string indexing, not visual character width.\n\nEven with correct offsets, the chosen definition can be conceptually wrong. Two objects can have the same name. A working preview proves that a source range exists; it does not prove that the author mapped the reference to the relevant object.\n\nThe reader can open selected definitions and inspect the diff beside the explanation. Notes point to the lines being discussed. The layout switch lets readers choose which pane comes first.\n\nThese are navigation choices, not evidence that the guide improves comprehension. The public Starlette example has five changed files, eight reading steps, and thirteen definition previews. Those counts describe its structure; they do not measure how well it teaches the change.\n\nThe output is one HTML file containing the source excerpts, explanations, styles, and scripts. Sharing it therefore shares the included source code too. The public example uses public Starlette code and includes its attribution.\n\nA next evaluation could ask a reviewer to explain a transition between two steps, identify the definition that justifies a claim, or point out a missing failure case. That would test something a line-range validator cannot.\n\nNo review-time benchmark or controlled comprehension study has been performed for this release. The upstream Starlette test suite was not run as part of generating the example, either. Building the guide should not be confused with testing the underlying change.\n\nThe unresolved question for me is how to find the missing connection in an otherwise complete-looking guide. Valid source references give the reader evidence to inspect. The explanation still has to earn their trust.\n\n`build`, source reconstruction in `changed_files`, and link checks in `collect_links` and `append_link`.\n*Writing disclosure: Codex drafted this article from my project, feedback I shared, and its source code. Codex checked the implementation descriptions against the pinned version linked above.*", "url": "https://wpnews.pro/news/why-a-pr-walkthrough-can-pass-validation-and-still-be-hard-to-read", "canonical_source": "https://dev.to/devyuuun/why-a-pr-walkthrough-can-pass-validation-and-still-be-hard-to-read-3gmb", "published_at": "2026-09-14 05:06:39+00:00", "updated_at": "2026-09-14 05:26:33.021611+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["PR Tour", "Starlette", "GitHub", "Python", "JavaScript"], "alternates": {"html": "https://wpnews.pro/news/why-a-pr-walkthrough-can-pass-validation-and-still-be-hard-to-read", "markdown": "https://wpnews.pro/news/why-a-pr-walkthrough-can-pass-validation-and-still-be-hard-to-read.md", "text": "https://wpnews.pro/news/why-a-pr-walkthrough-can-pass-validation-and-still-be-hard-to-read.txt", "jsonld": "https://wpnews.pro/news/why-a-pr-walkthrough-can-pass-validation-and-still-be-hard-to-read.jsonld"}}