Merge PR fsprojects#841 from webwarrior-ws/simple-async-complementary-helpers-2-squashed

Added SimpleAsyncComplementaryHelpers rule.

Contributes to fsprojects#517

Author: knocte

docs/content/how-tos/rules/FL0097.md

@@ -0,0 +1,49 @@
+---
+title: FL0097
+category: how-to
+hide_menu: true
+---
+
+# SimpleAsyncComplementaryHelpers (FL0097)
+
+*Introduced in `0.26.12`*
+
+## Cause
+
+There is a function that returns `Async<'T>` but no corresponding function that returns `Task<'T>` or vice versa.
+
+## Rationale
+
+Having both variants of asynchronous function (`Async` and `Task`) gives better interoperability, because C# uses `Task` and F# mainly uses `Async`.
+
+By convention, `Async` prefix or suffix in function name means that the function is asynchronous.
+
+Prefix is used for functions that return `Async` type, e.g.:
+```
+let AsyncFoo(): Async<int> =
+    async { return 1 }
+```
+
+Suffix is used for functions that return `System.Threading.Task` type, e.g.:
+```
+open System.Threading
+
+let FooAsync(): Task<int> =
+    task { return 1 }
+```
+
+## How To Fix
+
+For each function `AsyncFoo(): Async<'T>` create corresponding function `FooAsync(): Task<'T>` that just calls `Async.StartAsTask(AsyncFoo())`.
+For each function `FooAsync(): Task<'T>` create corresponding function `AsyncFoo(): Async<'T>` that just calls `async { return Async.AwaitTask (FooAsync()) }`.
+
+## Rule Settings
+
+    {
+        "simpleAsyncComplementaryHelpers": { 
+            "enabled": false,
+            "config": {
+                "mode": "OnlyPublicAPIsInLibraries"
+            }
+        }
+    }

src/FSharpLint.Core/Application/Configuration.fs

@@ -566,7 +566,8 @@ type Configuration =
       DiscourageStringInterpolationWithStringFormat:EnabledConfig option
       FavourNamedMembers:EnabledConfig option
       SynchronousFunctionNames:EnabledConfig option
-      AsynchronousFunctionNames:EnabledConfig option }
+      AsynchronousFunctionNames:EnabledConfig option
+      SimpleAsyncComplementaryHelpers:RuleConfig<SimpleAsyncComplementaryHelpers.Config> option }
 with
 // Method Zero is too big but can't be split into parts because it returns a record
 // and it requires all fields to be set.
@@ -678,6 +679,7 @@ with
         FavourNamedMembers = None
         SynchronousFunctionNames = None
         AsynchronousFunctionNames = None
+        SimpleAsyncComplementaryHelpers = None
     }
 
 // fsharplint:enable MaxLinesInMember
@@ -902,6 +904,7 @@ let flattenConfig (config:Configuration) =
                 config.FavourNamedMembers |> Option.bind (constructRuleIfEnabled FavourNamedMembers.rule)
                 config.SynchronousFunctionNames |> Option.bind (constructRuleIfEnabled SynchronousFunctionNames.rule)
                 config.AsynchronousFunctionNames |> Option.bind (constructRuleIfEnabled AsynchronousFunctionNames.rule)
+                config.SimpleAsyncComplementaryHelpers |> Option.bind (constructRuleWithConfig SimpleAsyncComplementaryHelpers.rule)
             |]
 
     let allEnabledRules = Array.choose id allPossibleRules

src/FSharpLint.Core/Application/Lint.fs

@@ -484,6 +484,9 @@ module Lint =
             return FailedToLoadFile projectFilePath |> LintResult.Failure
     }
 
+    let lintProjectAsync (optionalParams:OptionalLintParameters) (projectFilePath:string) (toolsPath:Ionide.ProjInfo.Types.ToolsPath) =
+        Async.StartAsTask(asyncLintProject optionalParams projectFilePath toolsPath)
+
     [<Obsolete "Use asyncLintProject instead, otherwise this synchronous version might cause thread blocking issues; this API will be removed in the future.">]
     let lintProject optionalParams projectFilePath toolsPath =
         asyncLintProject optionalParams projectFilePath toolsPath |> Async.RunSynchronously
@@ -544,6 +547,9 @@ module Lint =
             return FailedToLoadFile solutionFilePath |> LintResult.Failure
     }
 
+    let lintSolutionAsync (optionalParams:OptionalLintParameters) (solutionFilePath:string) (toolsPath:Ionide.ProjInfo.Types.ToolsPath) =
+        Async.StartAsTask(asyncLintSolution optionalParams solutionFilePath toolsPath)
+
     [<Obsolete "Use asyncLintSolution instead, otherwise this synchronous version might cause thread blocking issues; this API will be removed in the future.">]
     let lintSolution optionalParams solutionFilePath toolsPath =
         asyncLintSolution optionalParams solutionFilePath toolsPath |> Async.RunSynchronously
@@ -594,6 +600,9 @@ module Lint =
             | ParseFile.Failed failure -> return LintResult.Failure(FailedToParseFile failure)
         }
 
+    let lintSourceAsync optionalParams source =
+        Async.StartAsTask(asyncLintSource optionalParams source)
+
     [<Obsolete "Use asyncLintSource instead, otherwise this synchronous version might cause thread blocking issues; this API will be removed in the future.">]
     let lintSource optionalParams source =
         asyncLintSource optionalParams source |> Async.RunSynchronously
@@ -646,6 +655,9 @@ module Lint =
             return FailedToLoadFile filePath |> LintResult.Failure
     }
 
+    let lintFileAsync optionalParams filePath =
+        Async.StartAsTask(asyncLintFile optionalParams filePath)
+
     [<Obsolete "Use asyncLintFile instead, otherwise this synchronous version might cause thread blocking issues; this API will be removed in the future.">]
     let lintFile optionalParams filePath =
         asyncLintFile optionalParams filePath |> Async.RunSynchronously
@@ -692,6 +704,9 @@ module Lint =
             return LintResult.Failure (RunTimeConfigError err)
     }
 
+    let lintFilesAsync optionalParams filePaths =
+        Async.StartAsTask(asyncLintFiles optionalParams filePaths)
+
     [<Obsolete "Use asyncLintFiles instead, otherwise this synchronous version might cause thread blocking issues; this API will be removed in the future.">]
     let lintFiles optionalParams filePaths =
         asyncLintFiles optionalParams filePaths |> Async.RunSynchronously

src/FSharpLint.Core/Application/Lint.fsi

@@ -15,6 +15,7 @@ module ConfigurationManagement =
 module Lint =
 
     open System.Threading
+    open System.Threading.Tasks
     open FSharpLint.Framework
     open FSharpLint.Framework.Configuration
     open FSharpLint.Framework.Rules
@@ -156,19 +157,28 @@ module Lint =
     /// Lints an entire F# solution by linting all projects specified in the `.sln`, `slnx` or `.slnf` file.
     val asyncLintSolution : optionalParams:OptionalLintParameters -> solutionFilePath:string -> toolsPath:Ionide.ProjInfo.Types.ToolsPath -> Async<LintResult>
 
+    /// Lints an entire F# solution by linting all projects specified in the `.sln`, `slnx` or `.slnf` file.
+    val lintSolutionAsync : optionalParams:OptionalLintParameters -> solutionFilePath:string -> toolsPath:Ionide.ProjInfo.Types.ToolsPath ->  Task<LintResult>
+
     /// [Obsolete] Lints an entire F# solution by linting all projects specified in the `.sln`, `slnx` or `.slnf` file.
     val lintSolution : optionalParams:OptionalLintParameters -> solutionFilePath:string -> toolsPath:Ionide.ProjInfo.Types.ToolsPath -> LintResult
 
     /// Lints an entire F# project by retrieving the files from a given
     /// path to the `.fsproj` file.
     val asyncLintProject : optionalParams:OptionalLintParameters -> projectFilePath:string -> toolsPath:Ionide.ProjInfo.Types.ToolsPath -> Async<LintResult>
 
+    /// Lints an entire F# project by retrieving the files from a given path to the `.fsproj` file.
+    val lintProjectAsync : optionalParams:OptionalLintParameters -> projectFilePath:string -> toolsPath:Ionide.ProjInfo.Types.ToolsPath -> Task<LintResult>
+
     /// [Obsolete] Lints an entire F# project by retrieving the files from a given path to the `.fsproj` file.
     val lintProject : optionalParams:OptionalLintParameters -> projectFilePath:string -> toolsPath:Ionide.ProjInfo.Types.ToolsPath -> LintResult
 
     /// Lints F# source code async.
     val asyncLintSource : optionalParams:OptionalLintParameters -> source:string -> Async<LintResult>
 
+    /// Lints F# source code async.
+    val lintSourceAsync : optionalParams:OptionalLintParameters -> source:string -> Task<LintResult>
+
     /// [Obsolete] Lints F# source code.
     val lintSource : optionalParams:OptionalLintParameters -> source:string -> LintResult
 
@@ -179,12 +189,18 @@ module Lint =
     /// Lints an F# file from a given path to the `.fs` file.
     val asyncLintFile : optionalParams:OptionalLintParameters -> filePath:string -> Async<LintResult>
 
+    /// Lints an F# file from a given path to the `.fs` file.
+    val lintFileAsync : optionalParams:OptionalLintParameters -> filePath:string -> Task<LintResult>
+
     /// [Obsolete] Lints an F# file from a given path to the `.fs` file.
     val lintFile : optionalParams:OptionalLintParameters -> filePath:string -> LintResult
 
     /// Lints multiple F# files from given file paths.
     val asyncLintFiles : optionalParams:OptionalLintParameters -> filePaths:string seq -> Async<LintResult>
 
+    /// Lints multiple F# files from given file paths.
+    val lintFilesAsync : optionalParams:OptionalLintParameters -> filePaths:string seq -> Task<LintResult>
+
     /// [Obsolete] Lints multiple F# files from given file paths.
     val lintFiles : optionalParams:OptionalLintParameters -> filePaths:string seq -> LintResult
 

src/FSharpLint.Core/FSharpLint.Core.fsproj

@@ -31,6 +31,8 @@
     <Compile Include="Framework\Suppression.fs" />
     <!-- Rules -->
     <Compile Include="Rules\Identifiers.fs" />
+    <Compile Include="Rules\NamingHelper.fs" />
+    <Compile Include="Rules\Utilities.fs" />
     <Compile Include="Rules\Formatting\TupleFormatting\TupleFormattingHelper.fs" />
     <Compile Include="Rules\Formatting\TupleFormatting\TupleCommaSpacing.fs" />
     <Compile Include="Rules\Formatting\TupleFormatting\TupleIndentation.fs" />
@@ -80,9 +82,9 @@
     <Compile Include="Rules\Conventions\FunctionReimplementation\FunctionReimplementationHelper.fs" />
     <Compile Include="Rules\Conventions\FunctionReimplementation\ReimplementsFunction.fs" />
     <Compile Include="Rules\Conventions\FunctionReimplementation\CanBeReplacedWithComposition.fs" />
-    <Compile Include="Rules\Conventions\Naming\NamingHelper.fs" />
     <Compile Include="Rules\Conventions\Naming\SynchronousFunctionNames.fs" />
     <Compile Include="Rules\Conventions\Naming\AsynchronousFunctionNames.fs" />
+    <Compile Include="Rules\Conventions\Naming\SimpleAsyncComplementaryHelpers.fs" />
     <Compile Include="Rules\Conventions\Naming\InterfaceNames.fs" />
     <Compile Include="Rules\Conventions\Naming\ExceptionNames.fs" />
     <Compile Include="Rules\Conventions\Naming\TypeNames.fs" />