refactor: compat with language tools v3.1

[KazariEX]

Summary by CodeRabbit

• Refactor
  • Improved internal type inference mechanism for route handling in Vue components
  • Enhanced IDE autocomplete and type checking accuracy when using typed router utilities
  • Refined code transformation approach for more reliable type parameter handling

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/unplugin-vue-router@754

commit: d6faaf1

[codecov]

Codecov Report

❌ Patch coverage is 0% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.18%. Comparing base (81ca365) to head (d6faaf1).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
src/volar/entries/sfc-typed-router.ts	0.00%	19 Missing and 5 partials ⚠️
src/volar/utils/augment-vls-ctx.ts	0.00%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #754      +/-   ##
==========================================
- Coverage   70.53%   70.18%   -0.36%     
==========================================
  Files          32       32              
  Lines        2396     2408      +12     
  Branches      834      845      +11     
==========================================
  Hits         1690     1690              
- Misses        581      592      +11     
- Partials      125      126       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Walkthrough

The plugin entry point signature is refactored to use destructured parameters for compilerOptions and TypeScript module access. String-based useRoute mutations are replaced with AST traversal and precise source range replacements. The augment-vls-ctx utility is updated to accept a Code array instead of a function parameter.

Changes

Cohort / File(s)	Summary
Plugin entry point refactor src/volar/entries/sfc-typed-router.ts	Changed plugin signature from (ctx) to ({ compilerOptions, modules: { typescript: ts } }). Replaced regex-based useRoute mutations with AST-driven approach using replaceSourceRange. Updated to use compilerOptions.baseUrl directly and modified __VLS_ctx.$route augmentation to explicit object type assertion.
Utility signature update src/volar/utils/augment-vls-ctx.ts	Changed augmentVlsCtx parameter from getCodes: () => & ${string}`` to codes: Code[]. Updated insertion logic to spread and transform each Code item into the sequence with pattern `...${code},\n`. Adjusted end-detection from `";\n"` to `"}"`.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• AST traversal logic in plugin requires careful verification of node visiting and type parameter injection
• replaceSourceRange usage pattern consistency across mutations
• Verify augment-vls-ctx array spreading and Code item transformation logic handles edge cases

Possibly related PRs

• feat: volar plugins #609: Directly modifies the same Volar plugin files with related AST-based approach changes.

Suggested reviewers

• posva

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor: compat with language tools v3.1' directly addresses the main objective of updating compatibility with language tools v3.1, which is reflected in the substantial API changes to plugin signatures and mutation approaches.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 81ca365 and d6faaf1.

📒 Files selected for processing (2)

• src/volar/entries/sfc-typed-router.ts (4 hunks)
• src/volar/utils/augment-vls-ctx.ts (3 hunks)

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/codegen/generateParamParsers.ts:91-94
Timestamp: 2025-08-16T13:01:42.709Z
Learning: In the unplugin-vue-router codebase, path normalization for import specifiers is handled elsewhere in the system (not at individual call sites like generateParamParsers.ts). Individual functions should not normalize paths themselves as it violates separation of concerns.

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/core/context.ts:137-142
Timestamp: 2025-08-23T12:50:36.614Z
Learning: In src/core/context.ts, param parser relative paths must be computed relative to options.root (not relative to DTS file location) and the './' prefix is required for proper path resolution in the generated code.

📚 Learning: 2025-08-16T13:01:42.709Z

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/codegen/generateParamParsers.ts:91-94
Timestamp: 2025-08-16T13:01:42.709Z
Learning: In the unplugin-vue-router codebase, path normalization for import specifiers is handled elsewhere in the system (not at individual call sites like generateParamParsers.ts). Individual functions should not normalize paths themselves as it violates separation of concerns.

Applied to files:

• src/volar/entries/sfc-typed-router.ts

📚 Learning: 2025-08-23T12:50:36.614Z

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/core/context.ts:137-142
Timestamp: 2025-08-23T12:50:36.614Z
Learning: In src/core/context.ts, param parser relative paths must be computed relative to options.root (not relative to DTS file location) and the './' prefix is required for proper path resolution in the generated code.

Applied to files:

• src/volar/entries/sfc-typed-router.ts

📚 Learning: 2025-08-15T16:11:02.627Z

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/codegen/generateRouteResolver.ts:0-0
Timestamp: 2025-08-15T16:11:02.627Z
Learning: In src/codegen/generateRouteResolver.ts, the user wants comment alignment preserved in the generated resolver code, even when fixing potential runtime errors with String.repeat().

Applied to files:

• src/volar/entries/sfc-typed-router.ts

🧬 Code graph analysis (1)

src/volar/entries/sfc-typed-router.ts (1)

src/volar/utils/augment-vls-ctx.ts (1)

• augmentVlsCtx (9-34)

🔇 Additional comments (8)

src/volar/utils/augment-vls-ctx.ts (3)

7-9: LGTM! Cleaner API.

The parameter change from a function to a direct array simplifies the interface and aligns with how it's called in sfc-typed-router.ts.

---

33-33: No changes needed.

The spreading syntax is correct. vlsCtxAugmentations contains object type expressions (e.g., `{} as { $route: ... }`), and wrapping them as `...${code},\n` produces valid string content for object literal spreading. When inserted into the VLS context, these create proper spread properties.

---

22-22: Verify the end marker change from ';\n' to '}'.

The codebase search found no test cases, examples, or __VLS_ctx structure definition to confirm whether the new marker correctly identifies the object's closing brace rather than a nested closing brace. Manual verification needed: ensure the generated __VLS_ctx object has no nested braces and that } reliably marks the object's end across expected use cases.

src/volar/entries/sfc-typed-router.ts (5)

33-33: LGTM! Consistent with destructured parameters.

The parameter rename and baseUrl access align with the refactored plugin signature.

Also applies to: 41-42

---

107-109: LGTM! Simplified conditional logic.

The condition now simply checks if augmentations exist, making the code more maintainable.

---

97-99: Augmentation format is valid.

The pattern ...{} as { $route: ReturnType<typeof ${typedCall}> }, produces syntactically valid TypeScript. The spread operator spreads an empty object while the type assertion informs TypeScript of the property shape, a standard pattern for type-only augmentation.

---

3-5: Plugin signature is correct for @vue/language-core v3.1.

The destructured parameters at lines 17-20 correctly match the VueLanguagePlugin API. The function properly receives the ctx object and extracts compilerOptions and modules.typescript, which aligns with the expected v3.1 signature.

---

49-89: Verify property names and types against actual @vue/language-core v3.1.4.

Code accesses sfc.scriptSetup.ast (line 50), sfc.scriptSetup!.name (lines 64, 73, 80), and sfc.scriptSetup!.lang (line 61). Web documentation lists SFCScriptBlock properties as: type, content, attrs, loc, map, lang (optional), src, setup, bindings, imports, scriptAst, scriptSetupAst, warnings, deps. The .ast and .name properties don't appear in this list. Additionally, .lang is optional but accessed without a null check in line 61. Confirm these properties exist on the actual SFCScriptBlock type or update to use documented properties like .scriptAst/.scriptSetupAst.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[posva]

I couldn't push to the branch so I'm merging locally because this allows using $route without breaking all types so It's better than nothing but I don't understand why I couldn't fix it

[posva]

This seems to work only if useRoute is imported (which is most of the time not the case as you only use one of them)

[posva]

I'm confused, I tried

          `{} as { $route: ReturnType<typeof import('vue-router').useRoute${useRouteNameTypeParam}> }`

and it doesn't work in the plugin but it works on regular TS...

I also tried this

        const RouteMap = `import('vue-router/auto-routes').RouteNamedMap`
        const RouteLocationNormalizedLoaded = `import('vue-router').RouteLocationNormalizedLoaded`
        vlsCtxAugmentations.push(
          `{} as { $route: ${RouteLocationNormalizedLoaded}<${useRouteNameType} | ${RouteMap}[${useRouteNameType}]["childrenNames"]> }`
        )

It's as if something else is blocking in the way? I inspected with Volar Labs and the output is correct, just the types are not...

[posva]

Thanks, I merged locally and opened #761