lsp(feat): signature help

[adam2am]

Overview

This pull request introduces two enhancements to the Civet LSP: a fully-featured Signature Help Provider and a foundation for managing developer-facing debug logs in one place

High-Level Summary

1. New Feature: Signature Help: Implements the textDocument/signatureHelp LSP request, providing users with real-time parameter information for function calls, method calls, constructors, and generic type parameters.
2. Architectural Refactor: Centralized Debugging: Establishes a clean, scalable pattern for developer debugging. All feature-specific debug flags are now managed in a single, dedicated file, removing scattered hardcoded values

---

Detailed Changes

1. Signature Help Provider (lsp(feat): Signature Help Provider)

• handleSignatureHelp function: A new handler in lsp/source/features/signatureHelp.mts processes signature help requests with sourcemap awareness
• Trigger Characters: The server now advertises support for (, ,, and < as trigger characters, enabling signature help for:
  • Standard function/method calls: myFunc(|)
  • Argument lists: myFunc(arg1, |)
  • Generic type parameters: genericFunc<|>()
• Comprehensive Tests: New tests have been added in lsp/test/tsFeatures/signature-help.civet to validate functionality across various scenarios.

2. Centralized Debug Settings (lsp(debug): Centralize debug settings)

This is a key architectural improvement that sets a standard for all future development.

• The Problem: Previously, debug flags were hardcoded as loose constants within feature or server files. This approach is not scalable and makes it difficult to manage logging across the LSP.
• The Solution:
  • A new single source of truth for developer debugging has been created at lsp/source/lib/debug.mts.
  • This file exports a debugSettings object where all feature-specific flags can be toggled in one place.
  • This keeps configuration logic completely separate from feature logic.
• How to Use: To enable or disable logging for a feature (e.g., signatureHelp), a developer simply edits the boolean value in lsp/source/lib/debug.mts:

  export const debugSettings = {
    signatureHelp: true, // Set to false to disable
    completions: false,
    // Add new debug flags here
  };

3. Type Safety and Code Hygiene (lsp(chore): Improve type definitions)

• Robust FeatureDeps: The type definitions in lsp/types/types.d.ts have been improved:
  • Explicit imports for vscode-languageserver types have been added, removing reliance on global resolution and making the types more robust.
  • The new debugSettings object is now part of the FeatureDeps type, ensuring all feature handlers receive it in a structured and type-safe way.
• Clean Integration: The server.mts file now imports the centralized debugSettings and cleanly passes it down to feature handlers, acting as the central integration point.

---

Known Limitations

Generic Type Parameter Signature Help

Current Behavior: Signature help for incomplete generic type parameters (e.g., mapValue<) is not available. Potentially because of the Civet parser limitations, but I'm not skilled enough to dive in

Technical Details:

• When users type mapValue<, the Civet parser fails to produce a valid transpiled buffer
• The LSP correctly detects this scenario and gracefully aborts the signature help request
• This is documented in the test suite: lsp/test/tsFeatures/signature-help.civet includes a test case that verifies this behavior

Workaround: Users can complete the generic syntax (e.g., mapValue<>()) to receive signature help for the function parameters. But its not really nice DX

Future Consideration: This limitation may be addressed in future Civet parser improvements that provide better error recovery for incomplete generic syntax.

---

Happy to hear any thoughts, thanks