@onrails/biome-plugin 0.1.3 → 0.2.0

package/README.md

@@ -18,7 +18,8 @@ Reference the rule files in `biome.json` 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-deprecated-synonyms.grit",
-    "./node_modules/@onrails/biome-plugin/rules/fluent-stays-local.grit"
+    "./node_modules/@onrails/biome-plugin/rules/fluent-stays-local.grit",
+    "./node_modules/@onrails/biome-plugin/rules/carrier-sinks-need-from.grit"
   ]
 }
 ```
@@ -29,8 +30,19 @@ 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) |
+| `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) |
+| `carrier-sinks-need-from` | `JSON.parse` / `structuredClone` / `.json()` output cast to `Result<…>` / `Maybe<…>` without `Result.from` / `Maybe.from`; cast form only, 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.3",
+  "version": "0.2.0",
   "type": "module",
   "description": "Biome GritQL plugin: boundary diagnostics for @onrails/result (Promise<Result<…>>, _unsafeUnwrap*).",
   "license": "MIT",
@@ -40,7 +40,8 @@
     "./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/fluent-stays-local.grit": "./rules/fluent-stays-local.grit"
+    "./rules/fluent-stays-local.grit": "./rules/fluent-stays-local.grit",
+    "./rules/carrier-sinks-need-from.grit": "./rules/carrier-sinks-need-from.grit"
   },
   "scripts": {
     "typecheck": "echo 'noop (grit files only)'",
@@ -48,9 +49,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/carrier-sinks-need-from.grit

@@ -0,0 +1,36 @@
+// @onrails/biome-plugin: carrier-sinks-need-from
+//
+// Flag `JSON.parse(…)`, `structuredClone(…)` and `….json()` output cast to
+// `Result<…>` / `Maybe<…>`. Plain data from those sinks has no methods once
+// carriers keep them on a prototype, so the cast lies. Lift with
+// `Result.from` / `Maybe.from` instead.
+//
+// Limitation: matches the direct `as` cast form only. The ESLint rule also
+// follows annotated declarators, carrier-typed returns and parameter defaults,
+// `const` bindings of a sink result, and `res.json<Result<…>>()`; GritQL cannot
+// relate a declarator, return type or binding to its use. Declared in ENGINE_DIVERGENCES
+// (`carrier-sinks-need-from` / `cast-form-only`).
+
+engine biome(1.0)
+language js
+
+or {
+  `$sink as Result<$a, $b>`,
+  `$sink as Maybe<$a>`
+} as $t where {
+  // the sink call itself (optionally awaited / parenthesized), not any call nested inside it:
+  // `Result.from(JSON.parse(raw)) as Result<T, E>` is lifted and must stay quiet
+  $sink <: or {
+    `JSON.parse($_)`,
+    `structuredClone($_)`,
+    `$_.json()`,
+    `await $_.json()`,
+    `($_.json())`,
+    `(await $_.json())`
+  },
+  register_diagnostic(
+    span = $t,
+    message = "Data from JSON.parse/structuredClone/.json() is typed as Result/Maybe but carries no methods — lift it with Result.from / Maybe.from.",
+    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
   )
 }