Add a TypelevelMTLSubmarine rule

.github/workflows/ci.yml

@@ -34,7 +34,7 @@ jobs:
     timeout-minutes: 60
     steps:
       - name: Checkout current branch (full)
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -74,11 +74,11 @@ jobs:
 
       - name: Make target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: mkdir -p modules/fs2/rules/target target/rules-aggregate/target modules/cats-effect/rules/target modules/http4s/rules/target modules/cats/rules/target project/target
+        run: mkdir -p modules/fs2/rules/target target/rules-aggregate/target modules/cats-effect/rules/target modules/http4s/rules/target modules/mtl/rules/target modules/cats/rules/target project/target
 
       - name: Compress target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: tar cf targets.tar modules/fs2/rules/target target/rules-aggregate/target modules/cats-effect/rules/target modules/http4s/rules/target modules/cats/rules/target project/target
+        run: tar cf targets.tar modules/fs2/rules/target target/rules-aggregate/target modules/cats-effect/rules/target modules/http4s/rules/target modules/mtl/rules/target modules/cats/rules/target project/target
 
       - name: Upload target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
@@ -98,7 +98,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout current branch (full)
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -172,7 +172,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout current branch (full)
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -195,27 +195,27 @@ jobs:
       - name: Submit Dependencies
         uses: scalacenter/sbt-dependency-submission@v2
         with:
-          modules-ignore: cats-output_2.13 cats-output_2.12 http4s_2.13 http4s_2.12 fs2_2.13 fs2_2.12 cats-effect_2.13 cats-effect_2.12 cats-tests_2.13 cats-tests_2.12 fs2-tests_2.13 fs2-tests_2.12 cats-effect-tests_2.13 cats-effect-tests_2.12 typelevel-scalafix_2.13 typelevel-scalafix_2.12 fs2-output_2.13 fs2-output_2.12 fs2-input_2.13 fs2-input_2.12 cats-effect-input_2.13 cats-effect-input_2.12 http4s-tests_2.13 http4s-tests_2.12 http4s-input_2.13 http4s-input_2.12 cats-effect-output_2.13 cats-effect-output_2.12 http4s-output_2.13 http4s-output_2.12 cats_2.13 cats_2.12 cats-input_2.13 cats-input_2.12
+          modules-ignore: mtl-output_2.13 mtl-output_2.12 cats-output_2.13 cats-output_2.12 http4s_2.13 http4s_2.12 fs2_2.13 fs2_2.12 mtl-tests_2.13 mtl-tests_2.12 cats-effect_2.13 cats-effect_2.12 cats-tests_2.13 cats-tests_2.12 fs2-tests_2.13 fs2-tests_2.12 cats-effect-tests_2.13 cats-effect-tests_2.12 typelevel-scalafix_2.13 typelevel-scalafix_2.12 fs2-output_2.13 fs2-output_2.12 fs2-input_2.13 fs2-input_2.12 cats-effect-input_2.13 cats-effect-input_2.12 http4s-tests_2.13 http4s-tests_2.12 mtl-input_2.13 mtl-input_3 http4s-input_2.13 http4s-input_2.12 mtl_2.13 mtl_2.12 cats-effect-output_2.13 cats-effect-output_2.12 http4s-output_2.13 http4s-output_2.12 cats_2.13 cats_2.12 cats-input_2.13 cats-input_2.12
           configs-ignore: test scala-tool scala-doc-tool test-internal
 
   validate-steward:
     name: Validate Steward Config
     strategy:
       matrix:
         os: [ubuntu-22.04]
-        java: [temurin@11]
+        java: [temurin@17]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout current branch (fast)
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
-      - name: Setup Java (temurin@11)
-        id: setup-java-temurin-11
-        if: matrix.java == 'temurin@11'
+      - name: Setup Java (temurin@17)
+        id: setup-java-temurin-17
+        if: matrix.java == 'temurin@17'
         uses: actions/setup-java@v5
         with:
           distribution: temurin
-          java-version: 11
+          java-version: 17
 
       - uses: coursier/setup-action@v1
         with:

.scalafmt.conf

@@ -11,3 +11,9 @@ indent {
   defnSite = 2
   extendSite = 2
 }
+
+fileOverride {
+  "glob:**/scala-3/**" {
+    runner.dialect = scala3
+  }
+}

README.md

@@ -15,16 +15,18 @@ Then you can add the *typelevel-scalafix* rules to your sbt project using the `s
 
 ```scala
 // To add all Scalafix rules
-ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix" % "0.2.0"
+ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix" % "0.6.0"
 
 // To add only cats Scalafix rules
-ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-cats" % "0.2.0"
+ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-cats" % "0.6.0"
 // To add only cats-effect Scalafix rules
-ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-cats-effect" % "0.2.0"
+ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-cats-effect" % "0.6.0"
+// To add only cats-mtl Scalafix rules
+ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-mtl" % "0.6.0"
 // To add only fs2 Scalafix rules
-ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-fs2" % "0.2.0"
+ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-fs2" % "0.6.0"
 // To add only http4s Scalafix rules
-ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-http4s" % "0.2.0"
+ThisBuild / scalafixDependencies += "org.typelevel" %% "typelevel-scalafix-http4s" % "0.6.0"
 ```
 
 ## Usage
@@ -41,6 +43,7 @@ rules = [
   TypelevelFs2SyncCompiler
   TypelevelHttp4sLiteralsSyntax
   TypelevelIORandomUUID
+  TypelevelMTLSubmarine
 ]
 ```
 
@@ -62,6 +65,7 @@ Not all rules function with Scala 3 yet.
 | TypelevelUnusedShowInterpolator | :white_check_mark: | :x:                |
 | TypelevelFs2SyncCompiler        | :white_check_mark: | :x:                |
 | TypelevelHttp4sLiteralsSyntax   | :white_check_mark: | :white_check_mark: |
+| TypelevelMTLSubmarine           | :white_check_mark: | :white_check_mark: |
 
 ## Rules for cats
 
@@ -170,6 +174,47 @@ val test = IO.randomUUID
 
 This rule works on variable declarations, usaged within methods as well as for comprehensions.
 
+## Rules for cats-mtl
+
+### TypelevelMTLSubmarine
+
+This rule reports Cats and `IO` error handlers used on expressions that require
+`cats.mtl.Raise[F, E]`. When `Raise` comes from `Handle.allow`, raised values travel as
+traceless `Handle.Submarine` exceptions. A general error handler can catch one before
+`Handle` sees it.
+
+The rule covers Cats typeclass methods and syntax, plus concrete `IO` methods. It does
+not follow user-defined wrappers or constructors such as `Stream.eval`, and it does not
+match concrete `SyncIO` or `fs2.Stream` handlers. `Raise` and `Handle` aliases are
+supported; user-defined subtypes are not.
+
+Partial and narrow handlers are reported when they can match `Handle.Submarine`, a
+`RuntimeException`. This includes wildcards and the standard exception supertypes, but
+not disjoint types such as `IOException`. Unknown patterns are reported.
+
+Scala 2.13 and Scala 3 are supported. Scala 3 also supports context-function values such
+as `Raise[F, E] ?=> F[A]`.
+
+Example:
+
+```scala
+import cats.effect.IO
+import cats.mtl.{Raise, Handle}
+
+def raiseError: Raise[IO, String] ?=> IO[Unit] = r ?=>
+  r.raise("boom")
+
+def standardError: IO[Unit] =
+  IO.raiseError(new RuntimeException("boom"))
+
+Handle.allow[String] {
+  for {
+    _ <- raiseError.onError(e => IO.println("Error: " + e)) // reported
+    _ <- standardError.onError(e => IO.println("Error: " + e)) // not reported
+  } yield ()
+}
+```
+
 ## Rules for fs2
 
 ### TypelevelFs2SyncCompiler

build.sbt

@@ -7,6 +7,7 @@
 lazy val CatsEffectVersion = "3.6.3"
 lazy val Fs2Version        = "3.12.2"
 lazy val Http4sVersion     = "0.23.32"
+lazy val MtlVersion        = "1.7.0"
 
 ThisBuild / startYear := Some(2022)
 ThisBuild / developers ++= List(
@@ -15,16 +16,16 @@
 
 ThisBuild / semanticdbEnabled          := true
 ThisBuild / semanticdbVersion          := scalafixSemanticdb.revision
 ThisBuild / scalafixScalaBinaryVersion := CrossVersion.binaryScalaVersion(scalaVersion.value)
 
 lazy val `typelevel-scalafix` = project
   .in(file("."))
-  .aggregate(`typelevel-scalafix-rules`, cats.all, catsEffect.all, fs2.all, http4s.all)
+  .aggregate(`typelevel-scalafix-rules`, cats.all, catsEffect.all, fs2.all, http4s.all, mtl.all)
   .enablePlugins(NoPublishPlugin)
 
 lazy val `typelevel-scalafix-rules` = project
   .in(file("target/rules-aggregate"))
-  .dependsOn(cats.rules, catsEffect.rules, fs2.rules, http4s.rules)
+  .dependsOn(cats.rules, catsEffect.rules, fs2.rules, http4s.rules, mtl.rules)
   .settings(
     moduleName := "typelevel-scalafix",
     tlVersionIntroduced ++= List("2.12", "2.13").map(_ -> "0.1.2").toMap,
@@ -83,3 +84,17 @@
       "org.http4s" %% "http4s-core" % Http4sVersion
     )
   )
+
+// typelevel/mtl Scalafix rules
+lazy val mtl = scalafixProject("mtl")
+  .rulesSettings(
+    tlVersionIntroduced ++= List("2.12", "2.13").map(_ -> "0.6.0").toMap
+  )
+  .inputSettings(
+    scalaVersion       := "3.7.2",
+    crossScalaVersions := Seq(V.scala213, "3.7.2"),
+    libraryDependencies ++= Seq(
+      "org.typelevel" %% "cats-effect" % CatsEffectVersion,
+      "org.typelevel" %% "cats-mtl"    % MtlVersion
+    )
+  )

modules/cats-effect/rules/src/main/scala/org/typelevel/fix/UnusedIO.scala

@@ -51,17 +51,15 @@ class UnusedIO extends SemanticRule("TypelevelUnusedIO") {
           checkSignature(outer, ref)
         case Term.ApplyInfix.Initial(_, op, _, _) =>
           checkSignature(outer, op)
-        case Term.Apply.Initial(fn @ Term.Name(_), _) if IOCompanionSym.matches(fn) =>
+        case Term.Apply.After_4_6_0(fn @ Term.Name(_), _) if IOCompanionSym.matches(fn) =>
           Patch.lint(UnusedIODiagnostic(outer))
-        case Term.Apply.Initial(fn @ Term.Name(_), _) =>
+        case Term.Apply.After_4_6_0(fn @ Term.Name(_), _) =>
           checkSignature(outer, fn)
         case Term.ApplyUnary(fn @ Term.Name(_), _) =>
           checkSignature(outer, fn)
-        case Term.ApplyUsing.Initial(fn @ Term.Name(_), _) =>
-          checkSignature(outer, fn)
         case Term.Select(_, prop @ Term.Name(_)) =>
           checkSignature(outer, prop)
-        case Term.Apply.Initial(Term.Select(_, method), _) =>
+        case Term.Apply.After_4_6_0(Term.Select(_, method), _) =>
           checkSignature(outer, method)
         case Term.Annotate(expr, _) =>
           checkInner(expr)

modules/mtl/input/src/main/scala-2/fix/MTLSubmarineDirectProtectedArgumentTest.scala

@@ -0,0 +1,20 @@
+/*
+rule = TypelevelMTLSubmarine
+ */
+package fix
+
+import cats.mtl._
+import cats.effect._
+
+// scalafmt: { maxColumn = 160 }
+object DirectProtectedArgument {
+
+  def raiseDependentRecovery[F[_]](error: Throwable)(implicit r: Raise[F, String]): F[Unit] =
+    r.raise(error.getMessage)
+
+  def normalSource[F[_]: Async](implicit r: Raise[F, String]): F[Unit] = {
+    Async[F].handleErrorWith(Async[F].unit)(raiseDependentRecovery[F])
+    Async[F].redeemWith(Async[F].unit)(raiseDependentRecovery[F], _ => Async[F].unit)
+  }
+
+}

modules/mtl/input/src/main/scala-2/fix/MTLSubmarineEffectPropagationTest.scala

@@ -0,0 +1,120 @@
+/*
+rule = TypelevelMTLSubmarine
+ */
+package fix
+
+import cats.mtl._
+import cats.effect._
+import cats.effect.implicits._
+import cats.syntax.all._
+
+// scalafmt: { maxColumn = 160 }
+object EffectPropagation {
+
+  def methodRaise[F[_]](implicit r: Raise[F, String]): F[Unit] =
+    r.raise("something went wrong")
+
+  def syntax[F[_]: Async](implicit r: Raise[F, String]): F[Unit] = {
+    methodRaise[F].map(identity).attempt                     // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].void.recover(_ => ())                     // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].as(()).attempt                            // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (Async[F].unit *> methodRaise[F]).attempt                // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (methodRaise[F] <* Async[F].unit).attempt                // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (Async[F].unit >> methodRaise[F]).attempt                // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].product(Async[F].unit).attempt            // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].unit.product(methodRaise[F]).attempt            // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].productL(Async[F].unit).attempt           // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].unit.productR(methodRaise[F]).attempt           // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].unit.map2(methodRaise[F])((_, _) => ()).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].fproduct(identity).attempt                // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].fproductLeft(identity).attempt            // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].tupleLeft(()).attempt                     // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].tupleRight(()).attempt                    // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F]
+      .as((_: Unit) => ())
+      .<&>(Async[F].unit)
+      .attempt                                          // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    methodRaise[F].flatMap(_ => Async[F].unit).attempt  // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].unit.flatMap(_ => methodRaise[F]).attempt  // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].unit.flatTap(_ => methodRaise[F]).attempt  // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (Async[F].unit >>= (_ => methodRaise[F])).attempt   // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].unit.mproduct(_ => methodRaise[F]).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].unit.map(identity).attempt
+    (for {
+      _ <- Async[F].unit
+      _ <- methodRaise[F]
+    } yield ()).attempt.void // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+  }
+
+  def direct[F[_]: Async](implicit r: Raise[F, String]): F[Unit] = {
+    Async[F].attempt(Async[F].map(methodRaise[F])(identity)).void               // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].attempt(Async[F].flatMap(Async[F].unit)(_ => methodRaise[F])).void // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    Async[F].attempt(Async[F].map(Async[F].unit)(identity)).void
+    Async[F].attempt(Async[F].flatMap(Async[F].unit)(_ => Async[F].unit)).void
+  }
+
+  def safeSyntax[F[_]: Async]: F[Unit] = {
+    Async[F].unit.map(identity).attempt
+    Async[F].unit.void.recover(_ => ())
+    Async[F].unit.as(()).attempt
+    (Async[F].unit *> Async[F].unit).attempt
+    (Async[F].unit <* Async[F].unit).attempt
+    (Async[F].unit >> Async[F].unit).attempt
+    Async[F].unit.product(Async[F].unit).attempt
+    Async[F].unit.productL(Async[F].unit).attempt
+    Async[F].unit.productR(Async[F].unit).attempt
+    Async[F].unit.map2(Async[F].unit)((_, _) => ()).attempt
+    Async[F].unit.fproduct(identity).attempt
+    Async[F].unit.fproductLeft(identity).attempt
+    Async[F].unit.tupleLeft(()).attempt
+    Async[F].unit.tupleRight(()).attempt
+    Async[F].pure((_: Unit) => ()).<&>(Async[F].unit).attempt
+    Async[F].unit.flatMap(_ => Async[F].unit).attempt
+    Async[F].unit.flatTap(_ => Async[F].unit).attempt
+    (Async[F].unit >>= (_ => Async[F].unit)).attempt
+    Async[F].unit.mproduct(_ => Async[F].unit).attempt
+    (for {
+      _ <- Async[F].unit
+      _ <- Async[F].unit
+    } yield ()).attempt.void
+  }
+
+  def expressionWrappers[F[_]: Async](implicit r: Raise[F, String]): F[Unit] = {
+    (methodRaise[F]: F[Unit]).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (((methodRaise[F]))).attempt      // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (Async[F].unit: F[Unit]).attempt.void
+  }
+
+  def conditional[F[_]: Async](condition: Boolean)(implicit r: Raise[F, String]): F[Unit] = {
+    (if (condition) Async[F].unit else methodRaise[F]).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (if (condition) methodRaise[F] else Async[F].unit).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (if (condition) Async[F].unit else Async[F].unit).attempt.void
+  }
+
+  def matched[F[_]: Async](condition: Boolean)(implicit r: Raise[F, String]): F[Unit] = {
+    (condition match {
+      case true  => Async[F].unit
+      case false => methodRaise[F]
+    }).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (condition match {
+      case true  => methodRaise[F]
+      case false => Async[F].unit
+    }).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    (condition match {
+      case true  => Async[F].unit
+      case false => Async[F].unit
+    }).attempt.void
+  }
+
+  def blocks[F[_]: Async](implicit r: Raise[F, String]): F[Unit] = {
+    ({
+      Async[F].unit
+      methodRaise[F]
+    }).attempt // assert: TypelevelMTLSubmarine.mtlSubmarineErrorHandling
+    ({
+      methodRaise[F]
+      Async[F].unit
+    }).attempt.void
+  }
+
+}