Skip to content

docs: correct where escape-run line maps are built - #55

Open
usercao wants to merge 2 commits into
mainfrom
docs/escape-runs-line-map
Open

usercao wants to merge 2 commits into
mainfrom
docs/escape-runs-line-map

Conversation

@usercao

@usercao usercao commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

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.

No behavior change, so no changeset.

@changeset-bot

changeset-bot Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 6800f24

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

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copilot AI balanced review requested due to automatic review settings November 21, 2026 13:41

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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.

1 open issue
What changed in this PR

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.

Review effort: Balanced

Comment thread docs/architecture.md Resolved

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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.

Pullfrog  | Fix it ➔ | View workflow run | Using big-pickle (free) | 𝕏

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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.

Pullfrog  | View workflow run | Using big-pickle (free) | 𝕏

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Low severity 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.

1 resolved since last review

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants