@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 CHANGED
@@ -1,7 +1,189 @@
1
1
  # @tsrx/prettier-plugin
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/%40tsrx%2Fprettier-plugin?logo=npm)](https://www.npmjs.com/package/@tsrx/prettier-plugin)
4
- [![npm downloads](https://img.shields.io/npm/dm/%40tsrx%2Fprettier-plugin?logo=npm&label=downloads)](https://www.npmjs.com/package/@tsrx/prettier-plugin)
3
+ A Prettier plugin for formatting [TSRX](https://tsrx.dev) files.
5
4
 
6
- A Prettier plugin for formatting [TSRX](https://tsrx.dev) files, with `.tsrx` as
7
- the default extension.
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.4.11",
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": ">=2.0.0"
22
+ "prettier": ">=3.6.0"
24
23
  },
25
24
  "devDependencies": {
26
25
  "@types/node": "^24.3.0",
27
- "prettier": "^3.9.6"
26
+ "prettier": "^3.9.9",
27
+ "prettier-3-6": "npm:prettier@3.6.0"
28
28
  },
29
29
  "dependencies": {
30
- "@tsrx/core": "0.3.3"
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
  }