[WIP] Update language service documentation for new features

[Copilot]

Documentation and Sample Updates for Language Service Enhancements

This PR documents and demonstrates the language service enhancements from PR #3, including snippet support, path-based completions, text edit ranges, variable value previews, and the new HoverV2 type.

Changes Made:

✅ Updated docs/language-service.md

• Expanded features section with detailed descriptions of new capabilities
• Added "Advanced Features" section covering:
  • Nested variable completions with path-based navigation
  • Snippet support in function completions with tab stops
  • Text edit ranges for precise replacement
  • Variable value previews in hover with JSON truncation
  • HoverV2 type with guaranteed MarkupContent format
• Added comprehensive API Reference section:
  • createLanguageService(options?) - Create language service instances
  • ls.getCompletions(params) - Get completions with full parameter documentation
  • ls.getHover(params) - Get hover information with HoverV2 return type
  • ls.getHighlighting(textDocument) - Get syntax highlighting tokens
• Added TypeScript Types section documenting all exported types:
  • LanguageServiceApi, HoverV2, GetCompletionsParams, GetHoverParams
  • HighlightToken, LanguageServiceOptions
  • LSP types from vscode-languageserver-types
• Added Monaco Editor integration examples for all new features

✅ Updated samples/language-service-sample/app.js

• Added triggerCharacters: ['.'] to completion provider for dot-triggered completions
• Added snippet insertion support using insertTextRules with InsertAsSnippet when insertTextFormat === 2
• Implemented proper handling of textEdit.range from completion items for accurate text replacement
• Updated hover provider to handle HoverV2's guaranteed MarkupContent format
• Enhanced default context with deeper nested objects:
  • Added user.profile with email, score, level
  • Added user.preferences with theme, notifications
  • Added config object with timeout, retries, maxConnections
• Updated default expression to 'user.profile.score + config.timeout / 1000' to showcase nested path access

✅ Testing & Validation

• All 934 tests pass successfully
• Build completes without errors
• Linter passes (only expected dist warning)
• Code review completed with minor nitpick-level comments
• Security scan passed with 0 alerts
• Changes are minimal and focused on documentation and sample updates

Key Features Documented:

1. Path-based Variable Completions: Type user. to see user.name, user.profile, etc.
2. Snippet Support: Function completions include parameter placeholders (e.g., sum(${1:a}))
3. Text Edit Ranges: Proper replacement ranges for partial path completions
4. Variable Value Previews: Hover shows truncated JSON preview of variable values
5. HoverV2 Type: Guaranteed MarkupContent format for consistent hover handling
6. Exported Types: All language service types are properly exported and documented

Files Changed:

• docs/language-service.md - Comprehensive documentation update (+307 lines)
• samples/language-service-sample/app.js - Monaco Editor sample with all new features (+68 lines)

Security Summary:

✅ No security vulnerabilities detected by CodeQL scanner.

---

Note: The Monaco Editor sample requires CDN access to load Tailwind CSS and Monaco Editor. In restricted environments, these may be blocked, but the code changes are correct and will work when CDN access is available.

Original prompt

Summary

PR #3 "Better hovers and auto-completion" added significant enhancements to the language service that need to be documented and demonstrated in the sample application.

Changes Needed

1. Update docs/language-service.md

The documentation needs to be updated to cover the new features:

• Snippet support - Function completions now include tab stops with parameter placeholders (e.g., sum(${1:a}))
• Path-based variable completions - Completions for nested object properties (e.g., typing foo. shows foo.bar, foo.baz)
• Text edits with ranges - Proper replacement ranges for more accurate completions
• Variable value previews - Hovers on variables show a truncated JSON preview of the value
• Nested path support for hovers - Hovering over user.name resolves and shows the value at that path
• HoverV2 type - New type with guaranteed MarkupContent for contents
• Exported types - Document the newly exported types: LanguageServiceApi, HoverV2, GetCompletionsParams, GetHoverParams, HighlightToken, LanguageServiceOptions

Add:

• API reference section with detailed method documentation
• TypeScript types section
• Examples for nested variable completions
• Examples for variable hover with value preview

2. Update samples/language-service-sample/app.js

The Monaco Editor sample needs to be updated to use the new features:

1. Add triggerCharacters: ['.'] to the completion provider to enable completions after typing a dot
2. Add snippet insertion support using insertTextRules with InsertAsSnippet when insertTextFormat === 2
3. Handle textEdit.range from completion items for proper replacement of partial paths
4. Update the hover provider to properly handle the new MarkupContent format from HoverV2
5. Update the default context with deeper nested objects (e.g., user.profile, config) to demonstrate path completions
6. Update the default expression to showcase nested path access

Reference

See PR #3 diff for the implementation details: #3

Key files changed in PR #3:

• src/language-service/language-service.ts - Main language service with new completion and hover logic
• src/language-service/variable-utils.ts - New file with pathVariableCompletions and tryVariableHoverUsingSpans
• src/language-service/ls-utils.ts - New utilities including toTruncatedJsonString
• src/language-service/language-service.types.ts - New HoverV2 type
• index.ts - New exported types

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.