feat: Add helpful hints for contract not found errors in LSP

[emmanuelist]

Problem

When developers encounter contract-related errors in the Clarity LSP (Language Server Protocol), error messages are often cryptic and don't provide actionable guidance. Developers waste time debugging simple configuration issues like missing imports or incorrect Clarinet.toml entries.

Solution

This PR enhances error messages in both clarity-lsp and clarinet-cli LSP modules by adding contextual hints that help developers quickly identify and resolve common issues.

Implementation

Added an enhance_error_message() helper function that detects common error patterns and appends helpful hints:

1. "use of unresolved contract"

Hint: Make sure the contract is:
  • Listed in your Clarinet.toml
  • Located in the contracts/ directory
  • Deployed before this contract (check deployment order)

2. "use of unresolved trait"

Hint: Make sure the trait is:
  • Defined in an accessible contract
  • Properly imported with 'use-trait'
  • The contract defining it is deployed first

3. "contract not found" / "NoSuchContract"

Hint: Verify that:
  • The contract is registered in Clarinet.toml
  • The contract file exists in contracts/
  • The contract name matches exactly (case-sensitive)

4. "use of unresolved function"

Hint: Check if:
  • The function is defined in this contract
  • You're using the correct function name (Clarity is case-sensitive)
  • The function is public (use define-public) if calling from another contract

Files Modified

• components/clarity-lsp/src/utils/mod.rs - Added enhance_error_message() helper and updated clarity_diagnostic_to_lsp_type()
• components/clarinet-cli/src/lsp/mod.rs - Added enhance_error_message() helper and updated clarity_diagnostic_to_tower_lsp_type()

Testing

• Both clarity-lsp and clarinet-cli compile successfully
• Verified error messages contain expected patterns ("use of unresolved contract", "use of unresolved function")
• Enhanced messages flow through LSP diagnostic pipeline to VS Code
• Existing LSP functionality remains unchanged

Resolves

• TODO comment in components/clarity-lsp/src/utils/mod.rs:40 - "add hint for contracts not found errors"
• TODO comment in components/clarinet-cli/src/lsp/mod.rs:76 - "add hint for contracts not found errors"

Example Output

Before:

error: use of unresolved contract 'ST000000000000000000002AMW42H.missing-contract'

After:

error: use of unresolved contract 'ST000000000000000000002AMW42H.missing-contract'

Hint: Make sure the contract is:
  • Listed in your Clarinet.toml
  • Located in the contracts/ directory
  • Deployed before this contract (check deployment order)

Impact

This enhancement improves developer experience by reducing debugging time and making error messages more actionable, especially beneficial for developers new to Clarity and Clarinet.

---

Type: Enhancement
Component: LSP, Developer Experience
Breaking Changes: None

[hugo-stacks]

Hey @emmanuelist
Thanks for your contribution.

This is a step in the right direction. But maybe still not ideal.

Regarding the messages:
"use of unresolved contract" is often related to requirements issues, I believe, such as a missing requirement, or a requirement that is deployed at a higher epoch. In which case, we would say " exists but is deployed at an epoch higher than ". "Check deployment order" is also good advice, but might be too cryptic on big projects.
Additionally, contracts don't need to be Located in the contracts/ directory.

Regarding the implementation itself, I like the idea of having enhance_error_message(), but also, I'm thinking that we may want to have proper error management instead of relying on strings everywhere 😬

What do you think?