scrabble-solver 2.18.9 → 2.18.10-alpha.1

package/.oxlintrc.json

@@ -2,7 +2,7 @@
   "$schema": "./node_modules/oxlint/configuration_schema.json",
   "plugins": ["eslint", "typescript", "react", "import", "unicorn", "oxc", "jest"],
   "jsPlugins": [
-    { "name": "import-js", "specifier": "eslint-plugin-import" },
+    { "name": "perfectionist", "specifier": "eslint-plugin-perfectionist" },
     { "name": "playwright", "specifier": "eslint-plugin-playwright" },
     { "name": "react-js", "specifier": "eslint-plugin-react" }
   ],
@@ -30,18 +30,6 @@
   "settings": {
     "react": {
       "version": "19"
-    },
-    "import-js/extensions": [".js", ".jsx", ".ts", ".tsx"],
-    "import-js/external-module-folders": ["node_modules"],
-    "import-js/parsers": {
-      "@typescript-eslint/parser": [".ts", ".tsx"]
-    },
-    "import-js/resolver": {
-      "typescript": {
-        "alwaysTryTypes": true,
-        "project": ["tsconfig.json", "packages/*/tsconfig.json", "e2e/tsconfig.json"]
-      },
-      "node": true
     }
   },
   "ignorePatterns": [
@@ -60,23 +48,33 @@
   ],
   "rules": {
     "import/default": "error",
+    "import/newline-after-import": "error",
     "import/no-absolute-path": "error",
     "import/no-cycle": "error",
     "import/no-dynamic-require": "error",
 
-    "import-js/newline-after-import": "error",
-    "import-js/order": [
+    "jest/no-focused-tests": "error",
+
+    "perfectionist/sort-import-attributes": "error",
+    "perfectionist/sort-imports": [
       "error",
       {
-        "alphabetize": { "order": "asc", "caseInsensitive": true },
         "groups": [["builtin", "external"], "internal", "parent", "sibling", "index"],
-        "newlines-between": "always",
-        "pathGroups": [{ "pattern": "@/**", "group": "internal" }],
-        "pathGroupsExcludedImportTypes": ["builtin"]
+        "internalPattern": ["^@/"]
       }
     ],
-
-    "jest/no-focused-tests": "error",
+    "perfectionist/sort-jsx-props": [
+      "error",
+      {
+        "groups": ["unknown", "callbacks"],
+        "customGroups": [{ "groupName": "callbacks", "elementNamePattern": "^on[A-Z]" }]
+      }
+    ],
+    "perfectionist/sort-named-imports": ["error", { "groups": ["type-import", "value-import"] }],
+    "perfectionist/sort-union-types": [
+      "error",
+      { "groups": ["named", "keyword", "literal", "unknown", "nullish"] }
+    ],
 
     "react-js/no-deprecated": "error",
     "react-js/no-unused-prop-types": "error",

package/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository layout
 
-This is a Bun-workspaces monorepo (managed with Lerna for versioning/publishing and Nx purely for build caching/ordering). `engines` requires **Bun >=1.4** and **Node.js >=24**. The lockfile is `bun.lock` (text JSON, lockfileVersion 1) — `package-lock.json` was removed when the project migrated off npm/Jest in `#421` (Apr 2026). Workspace scripts use `bun run --filter <pattern> <script>` — the `'./packages/*'` glob runs in dependency order (built-in Nx cache), and `'*'` skips workspaces without that script (relevant for `test`). The root `workspaces` field is an explicit nine-entry list in dependency order, not a glob.
+This is a Bun-workspaces monorepo (Nx for build caching/ordering and `nx release` versioning; publishing is a plain `npm publish`). `engines` requires **Bun >=1.4** and **Node.js >=24**. The lockfile is `bun.lock` (text JSON, lockfileVersion 1) — `package-lock.json` was removed when the project migrated off npm/Jest in `#421` (Apr 2026). Workspace scripts use `bun run --filter <pattern> <script>` — the `'./packages/*'` glob runs in dependency order (built-in Nx cache), and `'*'` skips workspaces without that script (relevant for `test`). The root `workspaces` field is an explicit nine-entry list in dependency order, not a glob.
 
 The nine packages live under `packages/` and have a strict dependency order. When something breaks "downstream" of where you edited, rebuild the upstream package first:
 
@@ -19,7 +19,7 @@ logger (independent, used by app + dictionaries)
 The GADDAG itself lives outside this repo, in [`@kamilmielnik/gaddag`](https://github.com/kamilmielnik/gaddag) — a flat typed-array automaton with `has`/`hasPrefix`/`getArc`, binary `serialize`/`deserialize`, and `Gaddag.fromArray(words)`. It replaced `@kamilmielnik/trie` (#164) and is consumed by `dictionaries`, `solver`, and the app as a regular npm dependency (`3.0.0`). A local `packages/gaddag/` directory may exist — it holds git-ignored compiled output left over from before the package was extracted and is **not** a workspace.
 
 - `solver` — pure word-finding engine. Given a `Gaddag`, `Config`, `Board`, and `Tile[]`, returns scored `ResultJson`s. Has no I/O. `solve.ts` delegates to `MoveGenerator` (a single file holding all the logic) — anchor-based GADDAG move generation with per-cell cross-check masks, run once per direction; results are scored inline and sorted deterministically so UI ties resolve identically. `MoveGenerator` throws on alphabets over 64 tiles or boards over 32×32 because move sort keys pack direction/line/start/end into one integer. `benchmarks/` measures median `solve()` times on fixed mid-game boards (en-US, en-GB, pl-PL; 0–2 blanks): `bun run benchmark` from the root reruns them and rewrites the chart SVG + results table in the package `README.md`; it needs real (downloaded) dictionaries.
-- `dictionaries` — downloads/caches per-locale word lists to `$HOME/.scrabble-solver/dictionaries` and exposes them as `Gaddag`s (binary `<locale>.gaddag` files on disk; building the Polish GADDAG from its 3.2M-word list takes ~25 s, so it happens in `postbuild`/background updates, not per request; the `update-dictionaries` / `remove-dictionaries` bin scripts wrap this, and `update()` refreshes only stale locales unless forced, returning the locales it could not build — `update-dictionaries` exits 1 when there are any, so `bun run build` fails instead of shipping without a dictionary). The `Dictionaries` class layers a `MemoryCache` over a `DiskCache` (`LayeredCache`) and uses a per-locale `createAsyncProxy` to coalesce concurrent downloads. Cache entries older than `CACHE_STALE_THRESHOLD` (1 day) are considered stale, but only `update()` (run from `postbuild` and the packaging workflows) refreshes them — `get()` serves stale entries as-is. `DiskCache.get` treats files it cannot deserialize (corrupted, or written by an app version with an incompatible format — the binary magic doubles as the format version) as cache misses: it deletes them and the dictionary is re-downloaded and re-serialized automatically; `set` also removes the pre-#164 `<locale>.txt` trie cache. The solver worker does the same client-side (`src/solver-worker/getGaddag.ts`): it returns undefined for undeserializable cached dictionaries, falling back to the server and revalidating. Only this package and `logger` perform filesystem I/O — keep other packages pure so they can run in Edge / browser contexts.
+- `dictionaries` — downloads/caches per-locale word lists to `$HOME/.scrabble-solver/dictionaries` and exposes them as `Gaddag`s (binary `<locale>.gaddag` files on disk; building the Polish GADDAG from its 3.2M-word list takes ~25 s, so it happens in `postbuild`/background updates, not per request; the `update-dictionaries` / `remove-dictionaries` bin scripts wrap this, and `update()` refreshes only stale locales unless forced, returning the locales it could not build — `update-dictionaries` exits 1 when there are any, so `bun run build` fails instead of shipping without a dictionary). The `Dictionaries` class layers a `MemoryCache` over a `DiskCache` (`LayeredCache`) and uses a per-locale `createAsyncProxy` to coalesce concurrent downloads. Cache entries older than `CACHE_STALE_THRESHOLD` (1 day) are considered stale, but only `update()` (run from `postbuild` and the packaging workflows) refreshes them — `get()` serves stale entries as-is. `DiskCache.get` treats files it cannot deserialize (corrupted, or written by an app version with an incompatible format — the binary magic doubles as the format version) as cache misses: it deletes them and the dictionary is re-downloaded and re-serialized automatically. The solver worker does the same client-side (`src/solver-worker/getGaddag.ts`): it returns undefined for undeserializable cached dictionaries, falling back to the server and revalidating. Only this package and `logger` perform filesystem I/O — keep other packages pure so they can run in Edge / browser contexts.
 - `word-lists` — pulls raw word lists from upstream sources (one fetcher per locale in `src/languages/`). Used by `dictionaries` during downloads.
 - `word-definitions` — per-locale `crawl(word) → string` and a parser for each source (Wiktionary, CNRTL, DWDS, SJP, dexonline, vajehyab, etc.). English uses the Wiktionary REST API (#431): `parse` JSON-parses the payload and uses cheerio only to strip HTML from definition strings, so the English fixtures are `.json`. Add a new locale by adding a `crawl` and a `parse` function in `src/languages/` and wiring them into `crawl.ts` / `parse.ts`. `parse.test.ts` is where you add fixture-based parser tests.
 - `types` — domain model classes (`Board`, `Cell`, `Tile`, `Result`, `Config`, `Locale`, …) plus `*Json` shapes. Most of these have a `fromJson` / `toJson` round-trip — use them at the wire boundary instead of hand-rolled serialization. Free functions live one-per-file under `src/lib/` (`getBoardWords`, `getCells`, `getCollidingWords`, `getCollisions`, `isSameBoardWord`, …) and type guards under `src/type-guards/` (`isBoardJson`, `isCellJson`, `isGame`, `isLocale`, …); the class methods are thin wrappers over them, so put new board/word logic in `lib/` and expose it as a method rather than growing `Board.ts`. `Board.getWords()` returns `BoardWord[]` (`{ direction, word, x, y }`), not strings — the same word can appear twice on a board, so a word's identity is its start cell plus direction (`isSameBoardWord`), and `Board.getCollidingWords(word)` returns the perpendicular words crossing it.
@@ -51,6 +51,7 @@ All commands run from the repo root unless noted.
 | --- | --- |
 | Install + build everything | `bun install && bun run build` |
 | Build all packages | `bun run build` (Nx-cached, respects dep order) |
+| Release | `bun run release` (prompts for the version; run from `master`) |
 | Build one package | `bun run --filter @scrabble-solver/<name> build` |
 | Dev server (port 3000) | `bun run dev` |
 | Production server (port 3333) | `bun start` (also waits for :3333 and opens the browser; `bun run start:app` is server-only) |
@@ -83,8 +84,8 @@ Hot reload only works for the `scrabble-solver` package. Edits to any other pack
 - **Install layout**: `bunfig.toml` pins `[install] linker = "hoisted"`. With Bun's isolated layout, `next build` fails — webpack bundles `unzipper` from `word-lists` and errors on its uninstalled optional `@aws-sdk/client-s3` dependency. Don't remove it.
 - **TypeScript**: stable TypeScript 7 (`typescript@^7.0.2`), whose `tsc` is the native Go compiler. It runs every package `build`, the app's `type-check`, and `next build` — the latter because Next.js runs the project-local `tsc` CLI (TS7 has no JS compiler API). Next 16.3.0 turned that on by default, so the `experimental.useTypeScriptCli` flag that pinned the app to the 16.3 preview line is gone from `next.config.js`; set it to `false` only to opt back into the JS compiler API, which TS7 cannot serve. The interim `@typescript/native-preview` (`tsgo`) setup from PR #422 was removed (Aug 2026). Root `tsconfig.json` sets `types: ["bun"]` for global test-runner types and excludes `e2e` and `playwright.config.ts` (covered by `e2e/tsconfig.json` instead); library packages extend it and additionally exclude `**/*.test.ts` from emitted output. A package's `tsconfig.json` covers `src/` only, so TypeScript living outside it needs its own `noEmit` config and its own `tsc` invocation or nothing type-checks it — `packages/logger/scripts/tsconfig.json` is the pattern (`module: preserve` because the scripts are ESM run by bun, while the package itself emits CJS), invoked from the package `build` so CI catches it. `packages/solver/benchmarks/` is still uncovered.
 - **Next.js**: built with `--webpack` flag explicitly (the default Turbopack is intentionally not used). `next.config.js` registers `@svgr/webpack` for SVG-as-component imports and the Workbox `InjectManifest` plugin for the service worker, and stubs out Next's unconditionally-bundled ES2019-2022 polyfills (`polyfill-module`) with `empty-module.js` via `NormalModuleReplacementPlugin` — every browserslist target (`package.json` `browserslist`: Chrome/Edge/Firefox ≥ 100, Safari ≥ 15.4, …) supports those natively, and browserslist alone does not control that chunk. SCSS load paths are extended to `./src` and `node_modules/include-media/dist`.
-- **Dependency upgrades**: `bun update --latest -r` rewrites every internal `@scrabble-solver/*` specifier to `"latest"` in both `package.json`s and `bun.lock` — restore them to `<version>` afterwards. Every dependency in every workspace is pinned to an exact version: `bunfig.toml` sets `exact = true` so `bun add` saves exact versions, `version:bump-lerna` passes `--exact`, and `bump-version.js` writes exact internal specifiers. `next` is pinned exactly because the published package ships a prebuilt `.next` and global installs (`bunx`/`npx`) ignore the lockfile, so a newer Next.js resolved at install time crashes on the older build output (next 16.4.0 broke 2.18.5 this way).
-- **Nx**: `nx.json` only defines a `build` target with `dependsOn: ["^build"]` and `cache: true`. It is used purely for dependency-aware build ordering and caching — there are no Nx generators or executors.
+- **Dependency upgrades**: `bun update --latest -r` rewrites every internal `@scrabble-solver/*` specifier to `"latest"` in both `package.json`s and `bun.lock` — restore them to `<version>` afterwards. Every dependency in every workspace is pinned to an exact version: `bunfig.toml` sets `exact = true` so `bun add` saves exact versions, and `nx release` writes exact internal specifiers. `next` is pinned exactly because the published package ships a prebuilt `.next` and global installs (`bunx`/`npx`) ignore the lockfile, so a newer Next.js resolved at install time crashes on the older build output (next 16.4.0 broke 2.18.5 this way).
+- **Nx**: `nx.json` defines the `build` target (`dependsOn: ["^build"]`, `cache: true`) and the `release` config used by `nx release` (fixed lockstep group over the root and `@scrabble-solver/*`, one commit named with the bare version, bare-version tag, no push). `pluginsConfig["@nx/js"].analyzeSourceFiles` is `false` because Nx's JS plugin calls the TypeScript JS API, which TypeScript 7 removed; the graph still comes from `package.json` dependencies. The root has a `project.json` so `nx release` can version it, which also makes its `package.json` scripts Nx targets (`nx run-many -t build` would run the root build too). There are no Nx generators or executors.
 
 ## CI workflows
 
@@ -101,7 +102,7 @@ When adding a workflow, match the existing pattern: trigger on `push`/`pull_requ
 
 ## Versioning & publishing
 
-`bun run release` chains `reinstall → version:bump → np → lerna publish from-package`. `version:bump` runs `lerna version --force-publish` (bumps every package in lockstep) followed by `bump-version.js` to sync any other version references, then commits. Don't hand-edit `version` fields across packages — use the script.
+`bun run release` chains `release:prepare` (reinstall) → `bun run test` → `nx release --skip-publish` → `release:publish`. `nx release` prompts for the version, bumps the root and every package in lockstep, updates internal `@scrabble-solver/*` ranges and `bun.lock`, then makes one commit named with the version and tags it. `release:publish` pushes the commit and tag, then runs `npm publish --workspaces --include-workspace-root --access public` with `--tag next` when the version is a prerelease (contains `-`, e.g. `2.18.10-rc.0`) and `--tag latest` otherwise, then opens a draft GitHub release for the tag with `gh release create --draft --generate-notes` (marked prerelease the same way). Publish the draft on GitHub after reviewing it. Run it from `master`. Don't pass arguments to `release:publish`: they go to the last command, `gh`, not to `npm publish`. npm has no skip for already-published versions, so after a partial publish, publish the remaining packages individually (`npm publish -w <name>`, or `npm publish` in the root) and don't re-run `bun run release`, which would bump again. Don't hand-edit `version` fields across packages — use `nx release`.
 
 ## Deploys
 

package/README.md

@@ -204,7 +204,6 @@ bun run --filter @scrabble-solver/word-lists build
 - [SCSS](https://sass-lang.com/)
 - [CSS Modules](https://github.com/css-modules/css-modules)
 - [include-media](https://eduardoboucas.github.io/include-media/)
-- [Lerna](https://lerna.js.org/)
 - [Nx](https://nx.dev/)
 - [Playwright](https://playwright.dev/)
 - [Oxlint](https://oxc.rs/docs/guide/usage/linter)