Skip to content

fix: keep one plugin layer per project entry across project reloads - #54

Open
usercao wants to merge 5 commits into
mainfrom
fix/reload-duplicate-decoration
Open

usercao wants to merge 5 commits into
mainfrom
fix/reload-duplicate-decoration

Conversation

@usercao

@usercao usercao commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

CSS diagnostics show up twice after a project reload, and three times after a second one. For example, with boarder: 0; in a styled.div template, semanticDiagnosticsSync gives me one "Unknown property" warning on the first load, two after a reloadProjects, and three after another. Same on TypeScript 5.0.4 and 6.0.3. Quick fixes and folding ranges repeat the same way. From reading tsserver's code, saving a change to tsconfig.json seems to go through the same reload path, so users likely hit this without ever running a reload command.

The cause: on a reload, tsserver runs enablePluginsWithOptions again and calls our create() with the project's current language service, which already has our earlier decoration around it. The template decorator adds its own results on top of whatever the wrapped service returns for diagnostics, code fixes, and outlining spans, so each extra layer contributes another copy (and validates every template again).

This keeps a single active layer per project and plugin entry, where an entry is its name plus its position among same-named entries in plugins[]:

  • A layer is retired when a newer layer for the same project and entry is created, or when a reload no longer enables its entry (for example, one of two same-named entries was removed from tsconfig). The entries a load enables are the project's plugins[] entries plus each name in ProjectService.globalPlugins that no project entry has, which is the rule tsserver's enableGlobalPlugins uses.
  • A retired layer forwards every call straight to the service it wraps and drops its decorator, so it doesn't walk the file on each request, and the decorator and its caches can be collected.
  • Retired layers leave the chain. create() skips retired layers on top of the service it gets, and when our layer sits directly above a retired one, the retired one splices itself out by handing its inner service to that layer, which decorates it instead. So repeated reloads of an aliased entry plus the global plugin keep the chain the same length. A retired layer only stays, as a pass-through, when another plugin's layer sits between two of ours, or when another plugin patched it.
  • The layer create() returns is a proxy with its own empty target. Its methods are stable functions that look up the active service at call time, since the decorator (and plugins like it) bind methods once when they wrap. If another plugin assigns or Object.definePropertys a method on our layer and returns the same object (ts-graphql-plugin does this), the patch stays on the layer instead of landing on the service underneath; otherwise a retired layer forwarding to that service would call the patch again and recurse. A property defined by value alone gets the attributes a plain service method has (configurable, enumerable, writable), so the decorator's own proxy above can still wrap it. A method's property descriptor reports the same forwarder as a property read, so a plugin that copies methods with Object.getOwnPropertyDescriptors goes through our layer too.

The key includes the name and position because tsserver enables every plugins[] entry, and only skips a global plugin when a project entry has exactly the same name. So an npm alias in tsconfig plus the editor's global plugin, or the same name listed twice with different tags, both give two layers in one load, and both should keep working. One limit: if the editor sends configurePlugin before the project loads, tsserver gives every same-named entry the same override object, so they can't be told apart and only one stays active. That case already lost the second entry's settings on main, so it's no worse; it's noted in the spec. Another limit, unchanged from main: tsserver never unloads a plugin. If a tsconfig edit removes every entry for this plugin and there's no global plugin, tsserver doesn't call create() at all and keeps the project's current language service, so the old layer stays active until the TS server restarts. The spec and docs/tsserver-host.md now say so.

Worth flagging: this changes how the shared configuration store behaves. It used to keep every manager ever created for a project and broadcast to all of them; now it keeps one per project and entry. Two existing tests in plugin-configuration.test.ts relied on two live managers for the same project, so I moved them onto separate projects and added a test for the retiring behavior. Open to a different approach if you see a cleaner one.

I also updated docs/architecture.md (Request flow and Configuration) and the reload notes in docs/tsserver-host.md, and added a patch changeset.

Testing:

  • A new e2e test reloads twice and checks that diagnostics, code fixes, and outlining spans match the first load exactly.
  • Three more e2e tests: an aliased tsconfig entry plus the global plugin, reloaded twice; the same name listed twice with different tags, reloaded twice; and two same-named entries where a tsconfig edit removes the first before the reload, after which the remaining entry reports once.
  • Unit tests cover a reload that passes our own decoration back in, one where another plugin wraps it (binding methods eagerly, like the decorator does), one where another plugin copies it by property descriptor, the alias plus global case, two same-named entries, an entry the reload no longer enables, and the retired manager. One counts how often the decorator walks the file: a retired layer under another plugin adds no walks. One measures the stack depth from a request to the project's language service across five reloads of an alias plus a global entry, and checks it doesn't grow. Two cover a plugin that patches a method onto our layer during a reload, by assignment and by Object.defineProperty with a value only.
  • Each new test fails without the change. pnpm verify passes, and the e2e suite passes on typescript-minimum, typescript-5.9, and typescript-current.

Performance:

This only touches src/tsserver/, which pnpm benchmark and pnpm test:scaling don't exercise (they drive the template language service directly), so I compared main against this branch two other ways, with throwaway scripts I haven't committed. Each run alternated a main build and a branch build in fresh processes, five rounds, reporting the median. The file has three styled templates of about 100 lines each plus some plain TypeScript.

Real tsserver (TypeScript 6.0.3), one project entry, median round-trip of 500 protocol requests:

Request main branch
completionInfo in a template 363 µs 361 µs
semanticDiagnosticsSync 58 µs 58 µs
quickinfo in a template 50 µs 50 µs
semanticDiagnosticsSync after 5 reloadProjects 197 µs, CSS diagnostics reported 6 times 59 µs, once
completionInfo after 5 reloadProjects 367 µs 367 µs

In process, calling the plugin's language service directly to isolate the layer itself, median per call:

Call main branch
Completions in a template 30.5 µs 31.0 µs
Hover in a template 8.2 µs 8.1 µs
Semantic diagnostics 24.4 µs 24.6 µs
Hover outside any template 8.2 µs 8.4 µs
getNavigationTree (not intercepted, pure forwarding) 4.60 µs 4.67 µs
Semantic diagnostics, alias entry plus global plugin, after 5 reloads 172.6 µs 30.7 µs
create() 6.3 µs 7.4 µs
StyledTemplateLanguageService instances alive after 5 two-entry reloads 13 3

The layer adds one proxy lookup and one forwarding call per request: up to about 0.5 µs in process, which doesn't show up through tsserver, where the protocol round trip dominates. I tried caching the forwarder lookup to skip it and got no measurable difference, so I left it out. create() costs about 1 µs more and runs once per entry per project load. In exchange, a reload no longer adds a layer that walks every template on each diagnostics, code-fix, and outlining request, and retired layers no longer keep their template language service and caches alive.

@changeset-bot

changeset-bot Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 6683a5f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@styled/typescript-styled-plugin Patch

Not sure what this means? Click here to learn what changesets are.

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

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

@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

Repeated reloads still accumulate inert decorator layers when a second plugin entry or a foreign wrapper is in the chain, so per-request template scanning keeps growing in those setups.

Approach: sound for the common single-entry reload, but incomplete: unwrapping only a direct hit mutes old managers without removing their decorators from tsserver's chain.

Reviewed changes

  • Reload guard: a module-level WeakMap records each decorated service, the service it wrapped, and the tsserver plugin entry name; a direct hit on the same entry is unwrapped before redecoration.
  • Shared configuration store: one listener per project and entry name remains live; an older manager is retired with empty tags and notified so its caches are released.
  • Coverage: an e2e test compares exact diagnostics, code fixes, and outlining spans across two reloads, with unit tests for unwrap, wrapped service, alias plus global entry, and manager supersession; docs and a patch changeset are updated.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using big-pickle (free) | 𝕏

Comment thread src/tsserver/tsserver-plugin.ts Resolved

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

Retirement can leave stale session data, unwrapping can discard other plugins' methods, and same-named plugin entries can lose CSS features.

3 open issues
What changed in this PR

This PR aims to keep one active styled-language plugin layer per project and entry name, preventing CSS diagnostics, quick fixes, and folding ranges from multiplying after project reloads.

Changes:

  • Unwraps earlier decorations when possible and retires older configuration managers while keeping differently named entries separate.
  • Adds reload, alias/global-entry, and manager-retirement coverage.
  • Updates lifecycle documentation and adds a patch changeset.
File Description
test/​unit/​tsserver-plugin.test.ts Covers reload decoration handling and alias/global coexistence.
test/​unit/​plugin-configuration.test.ts Tests manager retirement and adjusts project lifecycle coverage.
test/​e2e/​scenarios/​plugin-lifecycle.test.ts Checks diagnostics, fixes, and folding across two reloads.
src/​tsserver/​tsserver-plugin.ts Tracks returned decorations and unwraps matching earlier layers.
src/​tsserver/​editor-configuration.ts Retires older managers for the same project and entry name.
docs/​tsserver-host.md Documents tsserver reload behavior and plugin-entry naming.
docs/​architecture.md Defines decoration replacement and manager-retirement behavior.
.changeset/​single-decoration-after-reload.md Adds a patch release note for duplicate reload results.

Review effort: Balanced

Comment thread src/tsserver/editor-configuration.ts Resolved
Comment thread src/tsserver/editor-configuration.ts Outdated
Comment on lines +225 to +226
this.effectiveConfiguration = { ...this.effectiveConfiguration, tags: [] }
this.notifyUpdated()
Comment thread src/tsserver/tsserver-plugin.ts 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.

✅ No new issues found. The earlier concern about accumulating inert layers is addressed, and the new tests cover the previously untested chains.

Approach: sound — superseded layers now forward past the decorator, so a retained layer costs no template walk no matter what wraps it.

Reviewed changes

  • Replaced the returned decorator with a stable-method proxy that forwards to the wrapped service once its manager is superseded, so a retained layer runs no template walk and holds no decorator cache.
  • Changed ProjectConfigurationManager.supersede() to fire onSuperseded listeners instead of emptying tags and notifying, and updated docs/architecture.md to match.
  • Added a walk-count unit test for a foreign wrapper that binds methods eagerly, plus an e2e case that checks exact diagnostics across two reloads with an aliased tsconfig entry alongside the global plugin.

Pullfrog  | 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.

Important

Removing one of two same-named plugin entries leaves a stale decorator active after a reload, so the surviving tag's diagnostics appear twice. That is the duplication this PR is meant to eliminate, reached by an ordinary tsconfig edit.

Approach: sound for patched layers and two stable same-named entries, but the position-based entry key breaks when the entry set changes.

Reviewed changes

  • Entry identity: keyed decorations and configuration listeners by plugin name plus index among same-named entries, so two entries stay active in one load.
  • Patched layers: stored another plugin's property assignments on the layer and skipped unwrapping a patched layer, so those assignments survive supersession.
  • Coverage: added e2e and unit cases for two same-named entries and for a plugin patching methods across a reload.
  • Docs: updated the architecture and tsserver-host specs for per-entry keys and patched layers.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using big-pickle (free) | 𝕏

Comment thread src/tsserver/tsserver-plugin.ts Resolved

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

Repeated reloads retain proxy layers, causing quadratic request costs and growing stack depth; removed entries and descriptor-based patches are also mishandled.

4 open issues
2 resolved since last review

Review effort: Balanced

Comment thread src/tsserver/tsserver-plugin.ts Resolved
Comment thread src/tsserver/editor-configuration.ts Resolved
Comment thread src/tsserver/tsserver-plugin.ts Resolved
- Supersede a project's listener whose entry a reload no longer enables, using the project's plugins[] entries plus ProjectService.globalPlugins.
- Splice an unpatched retired layer out from under this plugin's layer above it, and skip retired layers on top of the service passed to create(), so repeated reloads of two entries keep the chain the same length.
- Keep properties another plugin defines on a layer, including through Object.defineProperty, on the layer's own proxy target, with a plain service method's attributes.

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

Removing the last plugin entry leaves its layer and manager active, while descriptor-based copies retain retired decorators, causing stale diagnostics and duplicate CSS results after reload.

2 open issues
1 previously missed issue

In code that hasn't changed since last review

High severity Removing the final styled plugin leaves its layer active

src/​tsserver/​editor-configuration.ts:64

Removing the last styled-plugin entry with no global instance leaves its old layer and manager active, so CSS diagnostics continue after reload. No new create() call runs this cleanup; handle that lifecycle path and add a final-entry-removal e2e test. The retirement guarantees in docs/architecture.md:9,167 are affected too.

3 resolved since last review

Review effort: Balanced

Comment thread src/tsserver/tsserver-plugin.ts 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.

✅ No new issues found. The prior finding about a removed same-named entry is fixed, and the new layer-splicing logic holds up under adversarial traces.

Approach: sound, because each load now reconciles the entries it enables and retires superseded layers directly, so a removed entry no longer leaves a second decorator in the chain.

Reviewed changes

  • Removed-entry retirement: each load carries the set of enabled entry keys (project entries plus unshadowed global plugins), and supersedes stored listeners whose entry is gone instead of matching only on equal keys.
  • Chain compaction: a retired, unpatched layer drops its decorator and splices itself out when this plugin's layer sits directly above, so repeated multi-entry reloads no longer accumulate proxy hops.
  • Patch capture: the returned layer uses a null-prototype target with definition and descriptor traps, so foreign Object.defineProperty calls stay on the layer and never reach the wrapped service.
  • Coverage: added a unit and real tsserver case for entry removal, a descriptor-based patch case, and a repeated two-entry reload case that checks stack depth stays flat.

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

A plugin that copies methods with Object.getOwnPropertyDescriptors got the undecorated method of the service under the decorator, so it lost every CSS result, and after a reload it kept calling past retirement. The descriptor now carries the same forwarder a property read returns.

Also document that tsserver never unloads a plugin: a reload that enables no entry of this plugin leaves its last layers active until the server restarts.

@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 descriptor-forwarder change is sound, and the prior Copilot finding it targets is addressed cleanly.

Reviewed changes — this run reviewed the delta since the prior Pullfrog review at fd7cb99:

  • Descriptor forwarders: extracted forwarderFor(property) and made getOwnPropertyDescriptor report the stable forwarder as a function method's descriptor value, so a plugin that copies methods by descriptor observes retirement instead of capturing a raw, undecorated method that would repeat CSS results.
  • Coverage: added a copyByDescriptor reload case with a positive control proving the copied layer still carries CSS behavior.
  • Docs: recorded tsserver's no-unload behavior and the last-entry-removal limitation in the architecture and host specs.

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

Lifecycle behavior across separate plugin installations has subtle reload and cleanup implications that require human assessment.

1 open issue
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