Standalone editors: validate and document TypeScript formatter interoperability
- Dominant language
- C#
- Stars
- 154
- Forks
- 4
- Avg merge
- 2h 46m
- Merged PRs (30d)
- 189
Description
Parent epic: #1390. Addresses the formatting item deferred from #1306 without presupposing a native SharpTS formatter.
## Goal
Make formatting a deliberate, verified standalone-editor experience. Prefer interoperating with established TypeScript formatters; advertise an LSP formatting provider only if evidence and an approved design show that external formatter configuration cannot meet SharpTS users' needs.
## Decision gate
Before implementation, record:
- which supported editors lack practical TypeScript formatter integration while `sharpts-lsp` is active;
- whether SharpTS syntax accepted by the compiler is rejected or damaged by current Prettier/Biome/TypeScript formatters;
- whether invocation belongs in the editor, a separate adapter, or `sharpts-lsp`;
- security, executable discovery, configuration, timeout, and version-reproducibility implications of invoking an external tool from the server;
- the cost of a native formatter, including comment/trivia preservation and parser recovery.
The expected outcome is documented external-formatter interoperability. A native formatter requires a separately approved design and should not be smuggled into this issue.
## Work: preferred external path
- [ ] Test current Prettier and Biome releases against representative SharpTS `.ts`/`.tsx` sources, including decorators, `dotnet:` imports, namespaces, generics, JSX, comments, and configuration files.
- [ ] Document formatter setup alongside `sharpts-lsp` for VS Code, Neovim, and Helix, including format-on-save and formatter-selection conflict avoidance.
- [ ] Confirm `interop-only` and `full` do not advertise document/range formatting when the editor owns formatting.
- [ ] Add a small repository fixture or smoke script that checks representative files format successfully and remain parseable/type-checkable.
- [ ] Document any formatter/version limitations and a supported workaround.
## Work: only if the gate approves LSP formatting
- [ ] Publish and review a design selecting native formatting or a bounded external-process adapter.
- [ ] Define document/range/on-type capability and mode behavior, configuration discovery, cancellation/timeouts, error reporting, and conflict handling.
- [ ] Preserve comments/trivia, TS/TSX syntax, line endings, final newline, and user configuration; output minimal deterministic edits.
- [ ] Add security controls for executable/config discovery and never execute workspace-controlled commands implicitly.
## Verification
### External-path acceptance
- [ ] Representative TS/TSX fixtures format with documented commands in CI or a pinned reproducible smoke environment.
- [ ] Formatted files parse and type-check in SharpTS; a second formatting pass is byte-identical (idempotent).
- [ ] VS Code, Neovim, and Helix manual/configuration checks show format-on-save works while SharpTS LSP features remain active and no duplicate provider prompt appears.
- [ ] Documentation clearly states which component owns formatting and how to troubleshoot conflicts.
### Additional acceptance if LSP formatting is approved
- [ ] Exact edit tests cover whole document, ranges, malformed source, comments, TSX, CRLF/LF, Unicode, and user configuration.
- [ ] Applying returned edits yields the formatter's expected output, remains parseable, and is idempotent.
- [ ] Cancellation, timeout, missing executable, invalid config, stale document, and hostile workspace-path tests fail safely.
- [ ] Capability handshakes and coexistence behavior match the approved design.
- [ ] Full unit, extension compile, language-server pack, Test262, and TypeScript conformance validation is green.
## Success criteria
This issue may close when standalone users have a documented, reproducibly verified formatting path with no LSP-provider conflict. Native/LSP formatting is not required if external editor-owned formatting satisfies that contract.
## Non-goals
- Reimplementing Prettier/Biome by default.
- Adding a formatter to `interop-only` merely for feature-count parity.
- Executing arbitrary workspace commands.
Contributor guide
Research direction
Start by testing current Prettier and Biome releases against representative SharpTS TS/TSX sources, then inspect sharpts-lsp behavior in interop-only and full modes. Verify the documented setup for VS Code, Neovim, and Helix, including format-on-save and provider conflicts. Done means a reproducible external-formatting path, parseable and type-checkable output, idempotence, and clear limitations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, neovim, typescript, vscode
- Domain
- developer-experience, devtools, documentation, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100