@whiteeclipse/toolchain 0.1.0-alpha.2 → 0.1.0-alpha.3
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 +16 -42
- package/dist/prettier.js +6 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,13 +5,11 @@ standard_revision: 1
|
|
|
5
5
|
|
|
6
6
|
# @whiteeclipse/toolchain
|
|
7
7
|
|
|
8
|
-
Shared ESLint and Prettier configurations for White Eclipse's JavaScript and TypeScript workspaces. This README covers
|
|
9
|
-
`0.1.0-alpha.1`, an exploratory alpha package.
|
|
8
|
+
Shared ESLint and Prettier configurations for White Eclipse's JavaScript and TypeScript workspaces. This README covers `0.1.0-alpha.3`, an exploratory alpha package for [RFC 0003](https://github.com/whiteeclipse-studio/hypatia/blob/feature/website/docs/internal/rfcs/0003-engineering-conventions.md).
|
|
10
9
|
|
|
11
10
|
## Setup
|
|
12
11
|
|
|
13
|
-
Install the exploratory release with `bun add --dev @whiteeclipse/toolchain@0.1.0-alpha.
|
|
14
|
-
The workspace instructions below apply when developing this repository.
|
|
12
|
+
Install the exploratory release with `bun add --dev @whiteeclipse/toolchain@0.1.0-alpha.3`. The registry tag is `alpha`. The workspace instructions below apply when developing this repository.
|
|
15
13
|
|
|
16
14
|
Add the package to a consuming workspace's development dependencies, then run `bun install`:
|
|
17
15
|
|
|
@@ -31,10 +29,7 @@ Install compatible peers according to [package.json](./package.json):
|
|
|
31
29
|
| Prettier | `3.9.10` |
|
|
32
30
|
| TypeScript | `6.0.3` |
|
|
33
31
|
|
|
34
|
-
Run `bun run --cwd packages/libraries/toolchain build` from the repository root before consuming the package.
|
|
35
|
-
Entrypoints select built `dist/*.js` files by default, adjacent `.d.ts` files for types, and built JavaScript when the
|
|
36
|
-
consumer enables the `development` condition. The examples run tools with Bun; the built configuration entrypoints also
|
|
37
|
-
load through Node ESM.
|
|
32
|
+
Run `bun run --cwd packages/libraries/toolchain build` from the repository root before consuming the package. Entrypoints select built `dist/*.js` files by default, adjacent `.d.ts` files for types, and built JavaScript when the consumer enables the `development` condition. The examples run tools with Bun; the built configuration entrypoints also load through Node ESM.
|
|
38
33
|
|
|
39
34
|
Create `eslint.config.ts` at the workspace root:
|
|
40
35
|
|
|
@@ -57,10 +52,7 @@ export { default } from "@whiteeclipse/toolchain/prettier";
|
|
|
57
52
|
|
|
58
53
|
## Running checks
|
|
59
54
|
|
|
60
|
-
With dependencies installed, run `bun run lint` from the repository root to check all packages and applications, or from
|
|
61
|
-
an individual workspace to check only that workspace. The toolchain workspace imports its own source configuration
|
|
62
|
-
directly. Consuming workspaces may load the built entrypoint, so rebuild the toolchain after changing shared rules.
|
|
63
|
-
Passing `--conditions=development` to `bun run` does not propagate that condition to the ESLint subprocess.
|
|
55
|
+
With dependencies installed, run `bun run lint` from the repository root to check all packages and applications, or from an individual workspace to check only that workspace. The toolchain workspace imports its own source configuration directly. Consuming workspaces may load the built entrypoint, so rebuild the toolchain after changing shared rules. Passing `--conditions=development` to `bun run` does not propagate that condition to the ESLint subprocess.
|
|
64
56
|
|
|
65
57
|
To load shared rules from source, invoke ESLint directly from the repository root:
|
|
66
58
|
|
|
@@ -82,31 +74,17 @@ Use ESLint's `--fix` or Prettier's `--write` to apply available fixes, then revi
|
|
|
82
74
|
The package exposes two default exports; it has no package-root export:
|
|
83
75
|
|
|
84
76
|
- **`@whiteeclipse/toolchain/eslint`:** a flat configuration array combining JavaScript correctness, type-aware TypeScript, import boundaries, promise handling, JSDoc, readability, and JSX checks.
|
|
85
|
-
- **`@whiteeclipse/toolchain/prettier`:** a configuration object using 120-column lines, four-space indentation, double
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
resolution supports Bun and checks `tsconfig.json` in the current directory as well as projects at
|
|
91
|
-
`apps/*/tsconfig.json` and `packages/*/*/tsconfig.json`. Repository workspace configurations set `tsconfigRootDir` to
|
|
92
|
-
their own directory, and their TypeScript projects include the ESLint configuration and relevant scripts.
|
|
93
|
-
|
|
94
|
-
JSDoc is required on interfaces, standalone functions, and class methods. PascalCase function declarations and assigned
|
|
95
|
-
functions with an explicit `ReactElement` or `React.ReactElement` return annotation may omit JSDoc; a union with `null`
|
|
96
|
-
is also supported. Inferred returns, type aliases, hooks, and other return types do not receive this exception. These
|
|
97
|
-
components may also use summary-only JSDoc without `@param` or `@returns`. Other checks, including supplied tag names
|
|
98
|
-
and parameter names, still apply. Object-literal methods and function-valued
|
|
99
|
-
properties do not require duplicate comments; document their contracts on the corresponding types. Any JSDoc supplied on
|
|
100
|
-
an implementation is still checked.
|
|
77
|
+
- **`@whiteeclipse/toolchain/prettier`:** a configuration object using 120-column lines, four-space indentation, double quotes, semicolons, trailing commas, and LF endings. It includes `prettier-plugin-packagejson` for package-file formatting and `prettier-plugin-tailwindcss` for automatic utility-class ordering. The Tailwind plugin loads last. Markdown paragraphs stay on one source line so the renderer can wrap them to fit the page.
|
|
78
|
+
|
|
79
|
+
Typed linting uses TypeScript's project service, so checked TypeScript files need an appropriate `tsconfig.json`. Import resolution supports Bun and checks `tsconfig.json` in the current directory as well as projects at `apps/*/tsconfig.json` and `packages/*/*/tsconfig.json`. Repository workspace configurations set `tsconfigRootDir` to their own directory, and their TypeScript projects include the ESLint configuration and relevant scripts.
|
|
80
|
+
|
|
81
|
+
JSDoc is required on interfaces, standalone functions, and class methods. PascalCase function declarations and assigned functions with an explicit `ReactElement` or `React.ReactElement` return annotation may omit JSDoc; a union with `null` is also supported. Inferred returns, type aliases, hooks, and other return types do not receive this exception. These components may also use summary-only JSDoc without `@param` or `@returns`. Other checks, including supplied tag names and parameter names, still apply. Object-literal methods and function-valued properties do not require duplicate comments; document their contracts on the corresponding types. Any JSDoc supplied on an implementation is still checked.
|
|
101
82
|
|
|
102
83
|
JavaScript files, configuration files, and scripts receive Node globals. Source files under `src` and Storybook files receive browser globals; overlapping patterns can receive both. Test files relax selected function-name, numeric-literal, and named-capture rules while retaining other checks.
|
|
103
84
|
|
|
104
85
|
ESLint ignores dependency directories, `dist`, `storybook-static`, `coverage`, `.idea`, and `.obsidian`. Prettier's file selection is controlled separately by the consumer's command targets and ignore file.
|
|
105
86
|
|
|
106
|
-
See
|
|
107
|
-
the [ESLint entrypoint](https://github.com/whiteeclipse-studio/hypatia/blob/feature/website/packages/libraries/toolchain/src/eslint/index.ts), [rule groups](https://github.com/whiteeclipse-studio/hypatia/tree/feature/website/packages/libraries/toolchain/src/eslint/plugins),
|
|
108
|
-
and [Prettier configuration](https://github.com/whiteeclipse-studio/hypatia/blob/feature/website/packages/libraries/toolchain/src/prettier.ts)
|
|
109
|
-
for complete settings.
|
|
87
|
+
See the [ESLint entrypoint](https://github.com/whiteeclipse-studio/hypatia/blob/feature/website/packages/libraries/toolchain/src/eslint/index.ts), [rule groups](https://github.com/whiteeclipse-studio/hypatia/tree/feature/website/packages/libraries/toolchain/src/eslint/plugins), and [Prettier configuration](https://github.com/whiteeclipse-studio/hypatia/blob/feature/website/packages/libraries/toolchain/src/prettier.ts) for complete settings.
|
|
110
88
|
|
|
111
89
|
## Extending configurations
|
|
112
90
|
|
|
@@ -132,13 +110,9 @@ export default { ...config, printWidth: 100 };
|
|
|
132
110
|
|
|
133
111
|
### Tailwind class formatting
|
|
134
112
|
|
|
135
|
-
Use the shared Prettier configuration to sort utility classes consistently. Tailwind recommends its official plugin
|
|
136
|
-
in [Automatic Class Sorting with Prettier](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier). Sorting
|
|
137
|
-
groups related utilities and state variants; it does not shorten long class lists or automatically split them into
|
|
138
|
-
logical groups.
|
|
113
|
+
Use the shared Prettier configuration to sort utility classes consistently. Tailwind recommends its official plugin in [Automatic Class Sorting with Prettier](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier). Sorting groups related utilities and state variants; it does not shorten long class lists or automatically split them into logical groups.
|
|
139
114
|
|
|
140
|
-
For Tailwind CSS v4, consuming workspaces must configure `tailwindStylesheet` with the CSS entrypoint, relative to their
|
|
141
|
-
Prettier configuration file:
|
|
115
|
+
For Tailwind CSS v4, consuming workspaces must configure `tailwindStylesheet` with the CSS entrypoint, relative to their Prettier configuration file:
|
|
142
116
|
|
|
143
117
|
```js
|
|
144
118
|
import config from "@whiteeclipse/toolchain/prettier";
|
|
@@ -149,10 +123,9 @@ export default {
|
|
|
149
123
|
};
|
|
150
124
|
```
|
|
151
125
|
|
|
152
|
-
Hypatia's root configuration supplies separate stylesheet overrides for Website and Storybook. See the
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
when extending this setup.
|
|
126
|
+
Hypatia's root configuration supplies separate stylesheet overrides for Website and Storybook. See the plugin's [stylesheet configuration](https://github.com/tailwindlabs/prettier-plugin-tailwindcss#specifying-your-tailwind-stylesheet-path-tailwind-css-v4) and [plugin-order requirement](https://github.com/tailwindlabs/prettier-plugin-tailwindcss#compatibility-with-other-prettier-plugins) when extending this setup.
|
|
127
|
+
|
|
128
|
+
When adding file-specific overrides, include `...(config.overrides ?? [])` at the start of the `overrides` array to retain the shared Markdown setting.
|
|
156
129
|
|
|
157
130
|
## Troubleshooting
|
|
158
131
|
|
|
@@ -182,3 +155,4 @@ Released under the [MIT License](https://whiteeclipse.dev/LICENCE).
|
|
|
182
155
|
| 5 | 2026-10-30 | Akane SHIMOKA | Clarify object-literal JSDoc exemptions and shared rule loading |
|
|
183
156
|
| 6 | 2026-11-04 | Akane SHIMOKA | Add Tailwind class sorting and the React component JSDoc exception |
|
|
184
157
|
| 7 | 2026-11-04 | Akane SHIMOKA | Document alpha registry installation and release packaging |
|
|
158
|
+
| 8 | 2026-11-19 | Akane SHIMOKA | Document single-line Markdown paragraphs in alpha.3 |
|
package/dist/prettier.js
CHANGED
|
@@ -18,6 +18,12 @@ const config = {
|
|
|
18
18
|
bracketSameLine: false,
|
|
19
19
|
arrowParens: "avoid",
|
|
20
20
|
endOfLine: "lf",
|
|
21
|
+
overrides: [
|
|
22
|
+
{
|
|
23
|
+
files: "*.md",
|
|
24
|
+
options: { proseWrap: "never" },
|
|
25
|
+
},
|
|
26
|
+
],
|
|
21
27
|
plugins: [
|
|
22
28
|
require.resolve("prettier-plugin-packagejson"),
|
|
23
29
|
// Tailwind's plugin must be last to preserve compatibility with other plugins.
|