@onrails/biome-plugin 0.1.2 → 0.1.4

package/README.md

@@ -16,7 +16,9 @@ Reference the rule files in `biome.json` plugins:
 {
   "plugins": [
     "./node_modules/@onrails/biome-plugin/rules/no-promise-result.grit",
-    "./node_modules/@onrails/biome-plugin/rules/no-unsafe-unwrap.grit"
+    "./node_modules/@onrails/biome-plugin/rules/no-unsafe-unwrap.grit",
+    "./node_modules/@onrails/biome-plugin/rules/no-deprecated-synonyms.grit",
+    "./node_modules/@onrails/biome-plugin/rules/fluent-stays-local.grit"
   ]
 }
 ```
@@ -27,6 +29,18 @@ Reference the rule files in `biome.json` plugins:
 |------|------------------|
 | `no-promise-result` | `Promise<Result<T, E>>` in any type position — return `ResultAsync<T, E>` and use `fromAsync` / `tryAsync` at the boundary (error) |
 | `no-unsafe-unwrap`  | `._unsafeUnwrap()` / `._unsafeUnwrapErr()` calls — use `match` / `resolve` / `yieldResult` instead (error) |
+| `no-deprecated-synonyms` | Deprecated synonyms (`chain`, `fold`, `getOrElse`, `of`, …) — use the canonical names (error, partly fixable) |
+| `fluent-stays-local` | Bare `FluentResult<…>` / `FluentMaybe<…>` type references — broader net than the ESLint rule, see `ENGINE_DIVERGENCES` (error) |
+
+## Fixes
+
+`no-deprecated-synonyms` rewrites. `.chain()` → `.flatMap()` is a **safe** fix, applied by `biome check --write`. The free-function renames (`matchResult`/`matchMaybe` → `match`, `getOrElse` → `unwrapOr`, `collect` → `combine`, `sequenceTupleAsync` → `ResultAsync.combineTuple`) are **unsafe** — the canonical name still has to be imported, which GritQL cannot do — so they need `biome check --write --unsafe` plus an import fix, or `@onrails/codemod`, which rewrites the imports too. `fold`, `of`, and `ResultAsync.isOk()` / `.isErr()` have no mechanical rewrite and stay diagnostic-only.
+
+## Scoping
+
+`no-deprecated-synonyms` only fires in files that mention an `@onrails/*` module source, so RxJS `of` or fp-ts `fold` in unrelated files are left alone. Files that reach onrails through a local alias or re-export are not matched — use the ESLint plugin, which matches by name everywhere. Declared as `no-deprecated-synonyms` / `import-scoped` in `ENGINE_DIVERGENCES`.
+
+Requires Biome >= 2.5.12 for plugin rewrites and `fix_kind`.
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/biome-plugin",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Biome GritQL plugin: boundary diagnostics for @onrails/result (Promise<Result<…>>, _unsafeUnwrap*).",
   "license": "MIT",
@@ -39,7 +39,8 @@
   "exports": {
     "./rules/no-promise-result.grit": "./rules/no-promise-result.grit",
     "./rules/no-unsafe-unwrap.grit": "./rules/no-unsafe-unwrap.grit",
-    "./rules/no-deprecated-synonyms.grit": "./rules/no-deprecated-synonyms.grit"
+    "./rules/no-deprecated-synonyms.grit": "./rules/no-deprecated-synonyms.grit",
+    "./rules/fluent-stays-local.grit": "./rules/fluent-stays-local.grit"
   },
   "scripts": {
     "typecheck": "echo 'noop (grit files only)'",
@@ -47,9 +48,9 @@
     "check": "bun test"
   },
   "peerDependencies": {
-    "@biomejs/biome": ">=2.0.0"
+    "@biomejs/biome": ">=2.5.12"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16"
+    "@biomejs/biome": "^2.5.12"
   }
 }

package/rules/fluent-stays-local.grit

@@ -0,0 +1,27 @@
+// @onrails/biome-plugin: fluent-stays-local
+//
+// Flag `FluentResult<T, E>` / `FluentMaybe<T>` named as a type — the fluent
+// wrapper (`@onrails/result/fluent`, `@onrails/maybe/fluent`) must open and
+// close within a function body, never escape as a return type, an exported
+// binding, or a stored field.
+//
+// Limitation: GritQL matches the bare type reference wherever it appears —
+// a broader net than the ESLint rule, which only flags the four scoped
+// positions (return type, exported binding, stored field, serialize-sink
+// argument) and inspects call-argument shape for the sink check. This rule
+// cannot express that argument heuristic at all; declared in
+// ENGINE_DIVERGENCES (`fluent-stays-local` / `no-position-scoping`).
+
+engine biome(1.0)
+language js
+
+or {
+  `FluentResult<$ok, $err>` as $t,
+  `FluentMaybe<$value>` as $t
+} where {
+  register_diagnostic(
+    span = $t,
+    message = "FluentResult/FluentMaybe must stay local — it was flagged as a return type, an exported binding, a stored field, or an argument to a serialize/postMessage/cache call. Call toResult()/toMaybe()/toString() before it leaves the function.",
+    severity = "error"
+  )
+}

package/rules/no-deprecated-synonyms.grit

@@ -9,32 +9,45 @@
 // - collect() -> combine()
 // - ResultAsync.isOk() / isErr() -> await and narrow with isOk() / isErr()
 //
-// Limitation: matching is name-based — GritQL cannot scope by import, so
-// same-named calls from other libraries (RxJS `of`, fp-ts `fold`,
-// neverthrow `.isOk()`) are flagged too. Suppress with an inline
-// biome-ignore comment in mixed codebases.
+// Scoping: only files that mention an `@onrails/*` module source are matched,
+// so same-named calls from other libraries (RxJS `of`, fp-ts `fold`) are left
+// alone. The ESLint rule is name-based everywhere; declared in
+// ENGINE_DIVERGENCES (`no-deprecated-synonyms` / `import-scoped`).
+//
+// Fixes: `.chain()` -> `.flatMap()` is a safe rewrite (method rename, no
+// import churn). The free-function renames are unsafe fixes — they need the
+// canonical name imported, which GritQL cannot add; run `--write --unsafe`
+// and fix the import, or use `@onrails/codemod`, which rewrites both.
 
 engine biome(1.0)
-language js
+language js(typescript)
 
 or {
-  `$_.chain($_)` as $call,
-  `$_?.chain($_)` as $call,
-  `$_.isOk()` as $call,
-  `$_?.isOk()` as $call,
-  `$_.isErr()` as $call,
-  `$_?.isErr()` as $call,
-  `fold($_)` as $call,
-  `matchResult($_)` as $call,
-  `matchMaybe($_)` as $call,
-  `getOrElse($_)` as $call,
-  `sequenceTupleAsync($_)` as $call,
-  `collect($_)` as $call,
-  `of($_)` as $call
-} where {
+  `$x.chain($args)` => `$x.flatMap($args)`,
+  `$x?.chain($args)` => `$x?.flatMap($args)`,
+  `matchResult($args)` => `match($args)`,
+  `matchMaybe($args)` => `match($args)`,
+  `getOrElse($args)` => `unwrapOr($args)`,
+  `collect($args)` => `combine($args)`,
+  `sequenceTupleAsync($args)` => `ResultAsync.combineTuple($args)`,
+  `fold($args)`,
+  `of($args)`,
+  `$x.isOk()`,
+  `$x?.isOk()`,
+  `$x.isErr()`,
+  `$x?.isErr()`
+} as $call where {
+  $call <: within JsModule(items = $items),
+  $items <: contains JsModuleSource() as $source,
+  $source <: r".*@onrails/.*",
+  or {
+    { $call <: or { `$_.chain($_)`, `$_?.chain($_)` }, $kind = "safe" },
+    { $kind = "unsafe" }
+  },
   register_diagnostic(
     span = $call,
     message = "Avoid deprecated onrails synonyms/methods. Use the canonical equivalents instead.",
-    severity = "error"
+    severity = "error",
+    fix_kind = $kind
   )
 }