You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: correct where escape-run line maps are built - #55
The "Escape runs" paragraph in docs/architecture.md says a TemplateLineMap is only ever built next to createVirtualDocument in ensureDocument, and gives that as the reason the lazy escape-runs read is safe. There's one more place, though: when the validation cache hits and there's a diagnostic to map but no reusable session line map, DiagnosticsFeature.validate builds a fresh one with createTemplateLineMap(context) without a document. The "Caching" section actually already mentions this ("a fresh line map otherwise"), so the two sections disagree a little.
The code is fine, so this only adjusts the explanation:
The escape-runs read uses the .text of the context the map was built from. A reused map only serves contexts with the same raw text, and the substituted text is a pure function of the raw text, so the runs fit any of them.
The paragraph now mentions both places a line map gets built. On the cache-hit path, the read substitutes the requesting context's text once, and only when the raw text contains a backslash.
I updated the matching comment in src/virtual-document/template-line-map.ts too, since it made the same claim.
To double check, I ran a quick throwaway test: after replacing the session document, a new context with the same escaped raw text (\x63olr: red;) gets the same widened span on a cache hit as on a miss. I didn't include that test here to keep this a docs-only change, but can add it in a follow-up if it seems worth having.
Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.
This PR includes no changesets
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
The architecture documentation still contains conflicting guarantees about whether validation cache hits can read TemplateContext.text when escaped raw text has no reusable session map.
This documentation-only PR corrects the explanation of lazy escape-run computation in the plugin’s virtual-document layer. Runtime behavior is unchanged.
Changes:
Documents both line-map creation paths, including validation cache hits without a reusable session map.
Explains why escape runs remain valid when a map is reused for identical raw text.
Aligns the source comment with the corrected explanation.
File
Description
src/virtual-document/template-line-map.ts
Corrects the comment explaining safe reuse of escape runs.
docs/architecture.md
Clarifies line-map creation and lazy substitution on validation cache hits.
The reason will be displayed to describe this comment to others. Learn more.
Important
The spec still states the opposite of the behavior this PR documents, so the contradiction the PR sets out to fix survives in a different section.
Reviewed changes
This documentation-only PR corrects the "Escape runs" explanation in docs/architecture.md and the matching comment in src/virtual-document/template-line-map.ts.
Build sites — now names both situations that create a line map: alongside a virtual document, and on a validation-cache hit with no reusable session map.
Reuse rationale — replaces the "only built alongside createVirtualDocument" safety argument with the raw-text purity argument.
Source comment — aligns the escapeRuns getter comment with the corrected spec.
⚠️ The caching guarantee still forbids the read the new paragraph describes
Line 139 of docs/architecture.md still says a validation hit never reads TemplateContext.text, while the new paragraph describes exactly that read for escaped raw text without a reusable session map. The code agrees with the new paragraph: fromVirtualDocSpan reads the fresh map's escapeRuns, which calls getTemplateEscapeRuns(context) and therefore context.text, and a throwaway counter test confirmed one substitution on such a hit (the existing counter test uses only unescaped templates). Qualify the line 139 guarantee so the authoritative spec no longer contradicts itself.
Technical details
# Qualify the no-substitution guarantee for validation hits## Affected sites- docs/architecture.md:139 — "A request answered from a cache (a validation hit, a reused document or completion result) never reads `TemplateContext.text`" is stated absolutely. It is false when the cached raw text holds a backslash and the session has no reusable line map: `src/features/diagnostics.ts:158-160` builds a fresh line map, and `src/virtual-document/template-line-map.ts:64-67` reads `context.text` through `getTemplateEscapeRuns` before `fromVirtualDocSpan` can widen a diagnostic span.
- test/unit/template-language-service.test.ts:2417 — the cited guardrail ("substitute nothing for a diagnostics request whose templates are all validation cache hits") uses only templates without backslashes, so it proves the narrow case, not the absolute one. A throwaway probe with two alternating templates (`\x63olr: red;` and `color: blue;`) counted one substitution on the second request, confirming the exception.
## Required outcome- The spec must state both behaviors without conflict: a validation hit with no diagnostic, or with a reusable session line map, reads no substituted text; a hit that maps a diagnostic with escaped raw text and no reusable line map reads the requesting context's text once for escape runs, as the newly corrected Escape runs paragraph already says.
## Suggested approach (optional)- Add the narrow exception to the line 139 bullet, linking to the Escape runs paragraph and the fresh-line-map rule at docs/architecture.md:146.
The reason will be displayed to describe this comment to others. Learn more.
✅ No new issues found. The new commit resolves the finding from the prior review.
Reviewed changes
Since the prior Pullfrog review, this documentation-only PR:
Qualified the caching guarantee — docs/architecture.md:139 now names the validation-cache-hit exception the previous review asked for. It states that a hit with a diagnostic to map, escaped raw text, and no reusable session line map substitutes the requesting context's text once, links to the corrected "Escape runs" paragraph, and narrows the cited counter-test claim to templates without escapes.
Kept the spec consistent — the line 139 exception agrees with line 76 and the code: getLineMap() runs only when there are diagnostics, and the fresh map's escape-runs read is backslash-gated. No other section asserts a conflicting no-substitution guarantee.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The caching documentation still omits the stray-brace diagnostic scan that reads the requesting context’s text on a cache hit, contradicting the implementation.
No open issues 🎉
1 previously missed issue
In code that hasn't changed since last review
Document stray-brace diagnostics that read CSS despite cached line maps
docs/architecture.md:139
There is another cache-hit exception: DiagnosticsFeature.getShownDiagnostics calls getTemplateCssText(context) when a css-ruleorselectorexpected diagnostic maps to the template end (src/features/diagnostics.ts:128-132). That reads the requesting context's .text even without a backslash and with a reusable session line map, for example when validating color: red; } again. Please document the stray-brace scan too; otherwise this authoritative caching rule still contradicts the implementation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The "Escape runs" paragraph in
docs/architecture.mdsays aTemplateLineMapis only ever built next tocreateVirtualDocumentinensureDocument, and gives that as the reason the lazy escape-runs read is safe. There's one more place, though: when the validation cache hits and there's a diagnostic to map but no reusable session line map,DiagnosticsFeature.validatebuilds a fresh one withcreateTemplateLineMap(context)without a document. The "Caching" section actually already mentions this ("a fresh line map otherwise"), so the two sections disagree a little.The code is fine, so this only adjusts the explanation:
.textof the context the map was built from. A reused map only serves contexts with the same raw text, and the substituted text is a pure function of the raw text, so the runs fit any of them.I updated the matching comment in
src/virtual-document/template-line-map.tstoo, since it made the same claim.To double check, I ran a quick throwaway test: after replacing the session document, a new context with the same escaped raw text (
\x63olr: red;) gets the same widened span on a cache hit as on a miss. I didn't include that test here to keep this a docs-only change, but can add it in a follow-up if it seems worth having.No behavior change, so no changeset.