nickna / nickna/SharpTS

Standalone editors: validate and document TypeScript formatter interoperability

Open
#1,398 0 comments 0 reactions 0 assignees View on GitHub
deferred documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.