@tsrx/prettier-plugin 0.4.11 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +186 -4
- package/package.json +9 -5
- package/src/index.js +29 -7549
- package/src/jsx.js +533 -0
- package/src/parse.js +800 -0
- package/src/printer.js +1262 -0
- package/src/range.js +236 -0
- package/src/index.test.js +0 -8312
package/README.md
CHANGED
|
@@ -1,7 +1,189 @@
|
|
|
1
1
|
# @tsrx/prettier-plugin
|
|
2
2
|
|
|
3
|
-
[
|
|
4
|
-
[](https://www.npmjs.com/package/@tsrx/prettier-plugin)
|
|
3
|
+
A Prettier plugin for formatting [TSRX](https://tsrx.dev) files.
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
The goal is Prettier's output wherever TSRX is TSX, so TSRX only differs where its
|
|
6
|
+
syntax does: `@{ … }` blocks, `@if`/`@for`/`@switch`/`@try`, `{value}` shorthand
|
|
7
|
+
props, `<style>`/`<script>` bodies, and comments between JSX children.
|
|
8
|
+
|
|
9
|
+
## How it works
|
|
10
|
+
|
|
11
|
+
- **Parser** (`src/parse.js`) parses with `@tsrx/core` in `collect` mode, so
|
|
12
|
+
mistakes TypeScript only reports as diagnostics (a redeclared variable) still
|
|
13
|
+
format. An unclosed or mismatched tag is still an error: the parser would guess
|
|
14
|
+
the markup's structure. So is a dynamic tag whose expression isn't an
|
|
15
|
+
identifier, a member access or a string literal (`<{getTag()} />`). Then it
|
|
16
|
+
reshapes the acorn-typescript AST into the typescript-estree shape that
|
|
17
|
+
Prettier's printer expects:
|
|
18
|
+
- renames, such as `superTypeParameters` → `superTypeArguments`, `accessor`
|
|
19
|
+
fields → `AccessorProperty`, `namespace A.B` → `TSQualifiedName`, and
|
|
20
|
+
`export import` → `ExportNamedDeclaration`;
|
|
21
|
+
- the parts of Prettier's parser postprocess that its printer relies on:
|
|
22
|
+
`__contentEnd`, `locEnd` for statements, rebalanced logical expressions,
|
|
23
|
+
merged touching JSDoc comments, dropped single-type unions;
|
|
24
|
+
- a comment between JSX children, which renders like `{/* … */}` in TSX, is the
|
|
25
|
+
`{…}` child that `{/* … */}` is in the parser's tree (a
|
|
26
|
+
`JSXExpressionContainer` with a `JSXEmptyExpression`, and no braces in the
|
|
27
|
+
source), so Prettier lays it out; it becomes the plugin's comment child, which
|
|
28
|
+
prints without the braces, and a `prettier-ignore` one keeps the next child as
|
|
29
|
+
written;
|
|
30
|
+
- comments go to Prettier as a flat list with their source text, and Prettier
|
|
31
|
+
attaches them itself.
|
|
32
|
+
- **Printer** (`src/printer.js`) is Prettier's `estree` printer from
|
|
33
|
+
`prettier/plugins/estree`. It sees the options as its own `typescript` parser's,
|
|
34
|
+
because it checks the parser's name for TypeScript-only rules. The plugin prints
|
|
35
|
+
the TSRX syntax:
|
|
36
|
+
- `@{ … }` is a block statement with an `@`, and `@case` bodies are blocks, so
|
|
37
|
+
blank lines and comments follow Prettier's statement rules.
|
|
38
|
+
- Directives are presented to Prettier as `do { … }` expressions. A directive's
|
|
39
|
+
head is printed while the node presents itself as its statement
|
|
40
|
+
(`IfStatement`, `ForOfStatement`), so `@if (…)` breaks like `if (…)`.
|
|
41
|
+
- A directive, or a `@{ … }` block used as a value, lays out like a JSX element:
|
|
42
|
+
wrapped in `(` … `)` where it's assigned, returned, thrown, or an arrow's
|
|
43
|
+
body, with its comments inside the parentheses. While its parent prints, it
|
|
44
|
+
presents itself as a `JSXElement` (`withTsrxValuesAsJsx`), so Prettier's
|
|
45
|
+
JSX-specific layout applies to it. A `@{ … }` function or arrow body stays on
|
|
46
|
+
its line.
|
|
47
|
+
- An element that starts a statement keeps its parentheses where TSRX would read
|
|
48
|
+
it as output without them, as Prettier keeps them before a statement that
|
|
49
|
+
would start with `{`, `function` or `class`: in a template body wherever it
|
|
50
|
+
starts the statement (`(<hr />) + 1;`), and in any other block when it is the
|
|
51
|
+
whole statement (`(<div />);`).
|
|
52
|
+
- A `@{ … }` block that is an element's or fragment's only child hugs its tags
|
|
53
|
+
(`<div>@{`, the statements, `}</div>`), as a function's `@{ … }` body hugs its
|
|
54
|
+
`)`, and one in an expression container hugs the braces (`{@{`, `}}`), as
|
|
55
|
+
Prettier hugs a function there.
|
|
56
|
+
- A comment before a tag name: after a line comment, Prettier would print
|
|
57
|
+
`<// note` with the name below it, which TSX can't parse, so the comment and
|
|
58
|
+
the name go on their own indented lines after `<`, as in Prettier's closing
|
|
59
|
+
tags. A block comment prints straight after `<` (`</* note */ div />`).
|
|
60
|
+
- `<style>` bodies are formatted as CSS. A `<script>` body is formatted as
|
|
61
|
+
Prettier's HTML formatter formats it: its `type` or `lang` picks the parser
|
|
62
|
+
(JavaScript without either; JSON for JSON, import maps, and speculation rules;
|
|
63
|
+
Markdown; HTML), JavaScript and TypeScript bodies are formatted with this
|
|
64
|
+
plugin's own parser, and a body without a parser (`src`, an unknown type), or
|
|
65
|
+
that its parser can't read, is kept as written on its own lines, as Prettier
|
|
66
|
+
keeps it. With `embeddedLanguageFormatting: "off"`, `<style>` bodies are kept
|
|
67
|
+
as written and `<script>` bodies are kept on their own lines.
|
|
68
|
+
- Comments between a directive's branches are placed by Prettier's own comment
|
|
69
|
+
handling for `if` and `try`, while `@if` and `@try` present themselves as
|
|
70
|
+
those statements. A comment before `@empty` is handled like one before `else`.
|
|
71
|
+
- **JSX children** (`src/jsx.js`): a comment between children prints without the
|
|
72
|
+
braces, as written. An element with such comments is laid out by a copy of
|
|
73
|
+
Prettier's `printJsxElementInternal` and `printJsxChildren` with the two rules a
|
|
74
|
+
bare comment needs: a line comment ends its line, and it keeps whitespace before
|
|
75
|
+
it after text or a comment (touching them, `//` is text); text that starts with
|
|
76
|
+
`//` right after a block comment stays on its line. Every other element is
|
|
77
|
+
printed by Prettier itself. Keep the copy in step with Prettier when upgrading.
|
|
78
|
+
|
|
79
|
+
The plugin needs no other Prettier plugin, including in `prettier/standalone`,
|
|
80
|
+
except to format JSON, HTML, or Markdown `<script>` bodies there.
|
|
81
|
+
|
|
82
|
+
## Selection formatting
|
|
83
|
+
|
|
84
|
+
The plugin supports selection formatting (also called range formatting). Use your
|
|
85
|
+
editor's **Format Selection** command to format part of a `.tsrx` file, or pass
|
|
86
|
+
Prettier's `rangeStart` and `rangeEnd` options when formatting through its API.
|
|
87
|
+
|
|
88
|
+
## In the browser
|
|
89
|
+
|
|
90
|
+
`prettier/standalone` loads no parser by itself, and this plugin brings only its
|
|
91
|
+
own and the CSS one for `<style>`. JavaScript and TypeScript `<script>` bodies are
|
|
92
|
+
formatted with the plugin's parser, but a JSON, HTML, or Markdown body is kept as
|
|
93
|
+
written unless you pass the Prettier plugins that parse and print it: Prettier
|
|
94
|
+
finds a body's parser and printer among all the plugins in `plugins`.
|
|
95
|
+
|
|
96
|
+
```js
|
|
97
|
+
import * as prettier from 'prettier/standalone';
|
|
98
|
+
import tsrx from '@tsrx/prettier-plugin';
|
|
99
|
+
// JSON, import maps, and speculation rules: babel parses JSON, estree prints it
|
|
100
|
+
import * as babel from 'prettier/plugins/babel';
|
|
101
|
+
import * as estree from 'prettier/plugins/estree';
|
|
102
|
+
// <script type="text/html">
|
|
103
|
+
import * as html from 'prettier/plugins/html';
|
|
104
|
+
// <script type="text/markdown">
|
|
105
|
+
import * as markdown from 'prettier/plugins/markdown';
|
|
106
|
+
|
|
107
|
+
const formatted = await prettier.format(code, {
|
|
108
|
+
parser: 'tsrx',
|
|
109
|
+
plugins: [tsrx, babel, estree, html, markdown],
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
In Node, `prettier` loads its own plugins, so these bodies are formatted without
|
|
114
|
+
passing them.
|
|
115
|
+
|
|
116
|
+
## Prettier versions
|
|
117
|
+
|
|
118
|
+
The Prettier peer dependency is `>=3.6.0`, with no upper limit. **We recommend
|
|
119
|
+
Prettier 3.9.9 or newer for more correct formatting.** Older versions have
|
|
120
|
+
formatting differences and known compatibility gaps, including `prettier-ignore`
|
|
121
|
+
on template outputs.
|
|
122
|
+
|
|
123
|
+
The full formatting suite uses 3.9.9; focused import-type compatibility tests also
|
|
124
|
+
run with 3.6.0.
|
|
125
|
+
|
|
126
|
+
## Tests
|
|
127
|
+
|
|
128
|
+
- `tests/import-types.test.js` checks import types, comments, standalone output,
|
|
129
|
+
cursors, and selections with both the workspace Prettier and 3.6.0. Run the
|
|
130
|
+
older-version checks with `pnpm test --project prettier-plugin-3.6`.
|
|
131
|
+
- `tests/tsrx.test.js` covers TSRX syntax, which Prettier's own tests don't. Each
|
|
132
|
+
formatting test also checks that a second format changes nothing.
|
|
133
|
+
- `tests/tsrx-migrated.test.js` holds every test of the previous implementation
|
|
134
|
+
that exercises TSRX syntax (#852, Phase 2), under one `describe` with their old
|
|
135
|
+
names. Each expects this plugin's output and that formatting it again changes
|
|
136
|
+
nothing, and, where Prettier's `typescript` parser gives the same output, checks
|
|
137
|
+
that too. The old tests of plain JavaScript and TypeScript aren't migrated:
|
|
138
|
+
Prettier prints those, the imported Prettier tests run them through the TSRX
|
|
139
|
+
parser, and core's parser tests cover the parser.
|
|
140
|
+
- `tests/prettier/` holds Prettier's own format tests for JavaScript, JSX, and
|
|
141
|
+
TypeScript, imported by `scripts/import-prettier-tests.js`. A case is imported
|
|
142
|
+
when Prettier's `typescript` parser prints the snapshot's output and the input
|
|
143
|
+
is TSRX: valid TSX, in a strict-mode module. `tests/prettier.test.js` runs every
|
|
144
|
+
case through this plugin the way Prettier's harness does (with its cursor, range
|
|
145
|
+
and line endings) and expects exactly Prettier's output.
|
|
146
|
+
- `tests/prettier/manifest.json` records the Prettier version, the cases that were
|
|
147
|
+
left out and why, and the imported cases that the TSRX parser rejects.
|
|
148
|
+
- `tests/prettier-known-failures.json` lists the cases that don't pass yet. They
|
|
149
|
+
run as expected failures, and a listed case that starts passing fails the run,
|
|
150
|
+
so the list only shrinks. Refresh it after a change with
|
|
151
|
+
`UPDATE_KNOWN_FAILURES=1 pnpm test --project prettier-plugin`.
|
|
152
|
+
- `tests/prettier-overrides.js` holds the cases where TSRX deliberately differs
|
|
153
|
+
from Prettier, each with its reason. An override skips the case (for example,
|
|
154
|
+
syntax that is only a proposal), expects Prettier's output for the input as a
|
|
155
|
+
`.tsx` file, or replaces the input or the expected output.
|
|
156
|
+
|
|
157
|
+
The files in `tests/prettier/` come from Prettier and are under
|
|
158
|
+
[Prettier's MIT license](tests/prettier/LICENSE).
|
|
159
|
+
|
|
160
|
+
## Ongoing: keeping up with Prettier
|
|
161
|
+
|
|
162
|
+
The maintenance checklist from [#852](https://github.com/tsrx-org/tsrx/issues/852)
|
|
163
|
+
applies to every Prettier upgrade:
|
|
164
|
+
|
|
165
|
+
1. Re-import the installed release's format tests, then review and refresh the
|
|
166
|
+
known failures:
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
pnpm --filter @tsrx/prettier-plugin import-prettier-tests
|
|
170
|
+
UPDATE_KNOWN_FAILURES=1 pnpm test --project prettier-plugin
|
|
171
|
+
pnpm test --project prettier-plugin --project prettier-plugin-3.6
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The importer clones the installed release's tests, or accepts
|
|
175
|
+
`--source <prettier checkout>`. Review changes to the imported cases,
|
|
176
|
+
overrides, and known failures: a new failure can mean a regression or a change
|
|
177
|
+
in Prettier's output.
|
|
178
|
+
|
|
179
|
+
2. Keep `src/jsx.js` in step with Prettier's `printJsxElementInternal` and
|
|
180
|
+
`printJsxChildren`, which it copies to handle comments between TSRX children.
|
|
181
|
+
3. Check `src/parse.js` against Prettier's `src/language-js/parse/postprocess`.
|
|
182
|
+
The node shapes and metadata the printer expects can change between releases.
|
|
183
|
+
4. Check range formatting in `src/range.js` against Prettier's `formatRange` in
|
|
184
|
+
`src/main/core.js` and `calculateRange` in `src/main/range.js`. It relies on
|
|
185
|
+
Prettier passing the options object from the file's parse to the range's
|
|
186
|
+
format, and on how Prettier grows a selection to AST nodes. For example,
|
|
187
|
+
[prettier/prettier#19880](https://github.com/prettier/prettier/pull/19880)
|
|
188
|
+
changes how a range grows after 3.9. Verify the range and cursor tests on each
|
|
189
|
+
upgrade, even when the release is already allowed by the peer dependency.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tsrx/prettier-plugin",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "TSRX plugin for Prettier",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"module": "src/index.js",
|
|
@@ -12,7 +12,6 @@
|
|
|
12
12
|
"formatter"
|
|
13
13
|
],
|
|
14
14
|
"homepage": "https://tsrx.dev/",
|
|
15
|
-
"author": "Dominic Gannaway",
|
|
16
15
|
"license": "MIT",
|
|
17
16
|
"repository": {
|
|
18
17
|
"type": "git",
|
|
@@ -20,19 +19,24 @@
|
|
|
20
19
|
"directory": "packages/prettier-plugin"
|
|
21
20
|
},
|
|
22
21
|
"peerDependencies": {
|
|
23
|
-
"prettier": ">=
|
|
22
|
+
"prettier": ">=3.6.0"
|
|
24
23
|
},
|
|
25
24
|
"devDependencies": {
|
|
26
25
|
"@types/node": "^24.3.0",
|
|
27
|
-
"prettier": "^3.9.
|
|
26
|
+
"prettier": "^3.9.9",
|
|
27
|
+
"prettier-3-6": "npm:prettier@3.6.0"
|
|
28
28
|
},
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@tsrx/core": "0.
|
|
30
|
+
"@tsrx/core": "0.5.0"
|
|
31
31
|
},
|
|
32
32
|
"files": [
|
|
33
33
|
"src/"
|
|
34
34
|
],
|
|
35
|
+
"author": "Dominic Gannaway",
|
|
35
36
|
"publishConfig": {
|
|
36
37
|
"access": "public"
|
|
38
|
+
},
|
|
39
|
+
"scripts": {
|
|
40
|
+
"import-prettier-tests": "node scripts/import-prettier-tests.js"
|
|
37
41
|
}
|
|
38
42
|
}
|