volar-docs/docs/response-formatting.md

Response Formatting & Content Best Practices

Docs Index • Repo README • UX Best Practices • Telemetry & Observability

Great tooling depends not only on fast responses but also on clear, consistent payloads. This guide outlines best practices for shaping diagnostics, hover content, completion items, and code actions so users get precise information without noise.

Diagnostics

Content

• Source: Set diagnostic.source = 'rule-name' (e.g., json-schema, custom-lint). Helps users filter.
• Code: Provide a stable identifier (diagnostic.code = 'missing-prop'), enabling ignore lists or quick fixes.
• Message: Include cause + remediation (“Prop foo missing. Declare it in <script setup> defineProps.”).
• Severity: Follow LSP conventions (1 = Error, 2 = Warning, 3 = Information, 4 = Hint). Allow configuration to downgrade.

Performance

• Batch diagnostics per document. Avoid sending duplicates for nested ranges.
• When possible, include relatedInformation for cross-file context but cap the number to avoid huge payloads.

Hover Content

• Prefer Markdown; wrap code snippets in fenced blocks (ts … ).
• Trim trailing whitespace and collapse excessive blank lines.
• Provide primary info first (type/value) and link to docs for detail.
• Strip sensitive data (absolute paths, user tokens).

Context Tips

• For schema-derived hovers, include the schema title and a short description; keep JSON schema dumps behind a collapsible section (use <details> if the client supports it).

Completion Items

• Label: concise name (“v-if”, “<MyComponent>”).
• Detail: extra context (prop types, component path).
• Documentation: Markdown doc snippet.
• SortText: use prefixes (e.g., a_, b_) to prioritize built-ins vs user symbols.
• InsertText: prefer snippets for props/attributes; escape $/}.
• Additional Text Edits: use sparingly; ensure they do not conflict with user edits.

Code Actions & Quick Fixes

• Provide descriptive titles (“Add $schema reference”).
• Group actions by kind (quickfix, source.organizeImports).
• Include diagnostics references so editors can tie actions to specific issues.
• Bundle workspace edits that can be applied atomically; avoid overlapping edits from multiple actions.

Formatting Edits

• Respect editor options (tabSize, insertSpaces).
• Ensure edits are deterministic; format the entire document only when necessary.
• For large files, prefer range formatting to reduce payload size.

Response Size & Throttling

• Cap the number of completions/diagnostics per request (e.g., 500) and log when truncation occurs.
• Debounce responses triggered by rapid changes (especially diagnostics and code lenses).
• Use ResultProgressReporter (where supported) for long-running operations to stream partial results.

Consistency Across Contexts

• Reuse formatting helpers in LSP, CLI, and Monaco contexts so users see identical messages.
• When building a CLI, mirror VS Code’s diagnostic format (file:line:char severity message) for familiarity.

Testing & Validation

• Snapshot hover/completion payloads to detect accidental format regressions.
• Use integration tests to ensure markdown renders properly in target editors (VS Code’s MarkdownString preview, etc.).
• Validate JSON output (CLI) against a schema so downstream tooling can rely on field names/types.

By focusing on content quality, context, and payload size, you deliver responses that are not only fast but also clear and actionable, regardless of editor or CLI. EOF