From c1c7c1a5bc258f0b9cc26cdf4891dff49b0dc087 Mon Sep 17 00:00:00 2001 From: Jeroen Engels Date: Fri, 28 Jul 2023 17:53:25 +0200 Subject: [PATCH] Update docs --- docs.json | 2 +- src/NoUnused/Exports.elm | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs.json b/docs.json index 7dae9637..0d51b1c1 100644 --- a/docs.json +++ b/docs.json @@ -1 +1 @@ -[{"name":"NoUnused.CustomTypeConstructorArgs","comment":"\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Reports arguments of custom type constructors that are never used.\n\n config =\n [ NoUnused.CustomTypeConstructorArgs.rule\n ]\n\nCustom type constructors can contain data that is never extracted out of the constructor.\nThis rule will warn arguments that are always pattern matched using a wildcard (`_`).\n\nFor package projects, custom types whose constructors are exposed as part of the package API are not reported.\n\nNote that this rule **may report false positives** if you compare custom types with the `==` or `/=` operators\n(and never destructure the custom type), like when you do `value == Just 0`, or store them in lists for instance with\n[`assoc-list`](https://package.elm-lang.org/packages/pzp1997/assoc-list/latest).\nThis rule attempts to detect when the custom type is used in comparisons, but it may still result in false positives.\n\n\n## Fail\n\n type CustomType\n = CustomType Used Unused\n\n case customType of\n CustomType value _ -> value\n\n\n## Success\n\n type CustomType\n = CustomType Used Unused\n\n case customType of\n CustomType value maybeUsed -> value\n\n\n## When not to enable this rule?\n\nIf you like giving names to all arguments when pattern matching, then this rule will not find many problems.\nThis rule will work well when enabled along with [`NoUnused.Patterns`](./NoUnused-Patterns).\n\nAlso, if you like comparing custom types in the way described above, you might pass on this rule, or want to be very careful when enabling it.\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.CustomTypeConstructorArgs\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.CustomTypeConstructors","comment":" Forbid having unused custom type constructors inside the project.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Forbid having unused custom type constructors.\n\n🔧 Running with `--fix` will automatically remove most of the reported errors.\n\n config =\n [ NoUnused.CustomTypeConstructors.rule []\n ]\n\nNote that this rule reports any custom type constructor that isn't used\nanywhere _in the project_.\n\nIf the project is a package and the module that declared the type is exposed and\nthe type's constructors are exposed, then the constructors will not be reported.\n\nThis does not prevent you from using phantom types.\nI highly suggest chaning your phantom types to the following shape: `type TypeName = ConstructorName Never`.\nThis shape makes it obvious to tooling and readers that the type can't be created, so if it is used, it must be as a phantom type.\n\n**Deprecated configuration for phantom types**\n\n_I recommend changing your types like mentioned right above, and to configure the rule like `NoUnused.CustomTypeConstructors.rule []`.\nI'll keep this section and configuration option around until the next major version comes out._\n\n**Note**: At the time of writing, there may be cases where phantom types are not well detected.\nWhen an opaque type is defined in a dependency, we don't know whether a type variable should be considered as a phantom type.\n\nTherefore, sometimes this rule will need some help, by having you tell it what type variables of which type is a phantom type variable.\nThat's what the argument to the rule is for.\n\nTo explain that the `a` in `type Id a = Id String` from the `IdModule` module\ncorresponds to a phantom type variable, you would configure the rule like this:\n\n config =\n [ NoUnused.CustomTypeConstructors.rule\n [ { moduleName = \"IdModule\"\n , typeName = \"Id\"\n , index = 0 -- Position of the phantom variable in the type's arguments\n }\n ]\n ]\n\nThis rule could do a much better job than it currently does at figuring this out,\nby following the definitions of custom types and type aliases, until it finds out that the type\nvariable is not used, or that it hits the limit related to dependencies described above.\nIn the meantime, you can configure the rule with all the phantom type exceptions.\n\n**End of deprecated section**\n\n\n## Fail\n\n module A exposing (a)\n\n type MyType\n = UsedType\n | UnusedType -- Will get reported\n\n a =\n UsedType\n\n\n## Success\n\n module A exposing (ExposedType(..))\n\n type MyType\n = UsedType\n\n a =\n UsedType\n\n type ExposedType\n = A\n | B\n | C\n\n -----------------------\n module A exposing (..)\n\n type ExposedType\n = A\n | B\n | C\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.CustomTypeConstructors\n```\n\n","type":"List.List { moduleName : String.String, typeName : String.String, index : Basics.Int } -> Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Dependencies","comment":" Forbid the use of dependencies that are never used in your project.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Forbid the use of dependencies that are never used in your project.\n\n🔧 Running with `--fix` will automatically remove all the reported errors.\n\nA dependency is considered unused if none of its modules are imported in the project.\n\n config =\n [ NoUnused.Dependencies.rule\n ]\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Dependencies\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Exports","comment":" Forbid the use of exposed elements (functions, values or types) that are never used in your project.\n\n🔧 Running with `--fix` will automatically remove all the reported errors,\nexcept for the ones reported when using [`reportUnusedProductionExports`](#reportUnusedProductionExports).\nIt won't automatically remove unused modules though.\n\nIf the project is a package and the module that declared the element is exposed,\nthen nothing will be reported.\n\n@docs rule\n\n\n## Going one step further\n\nThis rule can be configured to report more unused elements than the default configuration.\n\n@docs Configuration, defaults, toRule\n\nBy default, this rule only reports exposed elements that are never imported in other modules.\nIt is however pretty common to have elements imported and used in non-production parts of the codebase,\nsuch as in tests or in a styleguide.\n\nFor instance, let's say there is a module `A` that exposes a function `someFunction`:\n\n module A exposing (someFunction)\n\n someFunction input =\n doSomethingComplexWith input\n\nAnd there is this test module to test `A.someFunction`:\n\n module ATest exposing (tests)\n\n import A\n import Test exposing (Test, describe, test)\n\n tests : Test\n tests =\n describe \"A.someFunction\"\n [ test \"does something complex\" <|\n \\() ->\n A.someFunction someInput\n |> Expect.equal someExpectedOutput\n ]\n\nLet's say this is the only use of `A.someFunction` in the entire project.\nBecause `A.someFunction` is technically used in the project, this rule won't report it.\n\nBut since the function is not used in production code, it is a good practice to remove it, as that will remove the\namount of code that needs to be maintained unnecessarily. We can detect that using [`reportUnusedProductionExports`](#reportUnusedProductionExports).\n\n@docs reportUnusedProductionExports\n\n@docs Exception, annotatedBy, suffixedBy, prefixedBy, definedInModule\n\n\n## Try it out\n\nYou can try this rule out by running the following commands:\n\nUsing the default configuration:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Exports\n```\n\nUsing `reportUnusedProductionExports` with the following configuration:\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = \\{ moduleName, filePath, isInSourceDirectories } -> isInSourceDirectories\n , exceptionsAre = [ annotatedBy \"@test-helper\", suffixedBy \"_FOR_TESTS\" ]\n }\n |> NoUnused.Exports.toRule\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example-ignore-tests --rules NoUnused.Exports\n```\n\n","unions":[{"name":"Configuration","comment":" Configuration for the rule. Use [`defaults`](#defaults) to get a default configuration and use [`toRule`](#toRule) to turn it into a rule.\nYou can change the configuration using [`reportUnusedProductionExports`](#reportUnusedProductionExports).\n","args":[],"cases":[]},{"name":"Exception","comment":" Predicate to identify exceptions (that shouldn't be reported) for elements defined in production code that are only used in non-production code.\n\nA problem with reporting these elements is that it's going to produce false positives, as there are legitimate use-cases\nfor exporting these elements, hence the need for the rule to be able to identify them.\n\nFor instance, while it's generally discouraged, you might want to test the internals of an API (to make sure some properties hold\ngiven very specific situations). In this case, your module then needs to expose a way to gain insight to the internals.\n\nAnother example is giving the means for tests to create opaque types that are impossible or very hard to create in a test\nenvironment. This can be the case for types that can only be created through the decoding of an HTTP request.\n\nNote that another common way to handle these use-cases is to move the internals to another module that exposes everything\nwhile making sure only specific production modules import it.\n\n","args":[],"cases":[]}],"aliases":[],"values":[{"name":"annotatedBy","comment":" Prevents reporting usages of elements that contain a specific tag in their documentation.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre = [ annotatedBy \"@test-helper\" ]\n }\n |> NoUnused.Exports.toRule\n\nany element that has `@test-helper` in its documentation will not be reported as unused (as long as its used at least once in the project):\n\n {-| @test-helper\n -}\n someFunction input =\n doSomethingComplexWith input\n\nA recommended practice is to have annotations start with `@`.\n\nYou can use this function several times to define multiple annotations.\n\n","type":"String.String -> NoUnused.Exports.Exception"},{"name":"defaults","comment":" Default configuration. This will only report exported elements that are never used in other modules.\n","type":"NoUnused.Exports.Configuration"},{"name":"definedInModule","comment":" Prevents reporting usages of elements in some modules.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre =\n [ definedInModule\n (\\{ moduleName, filePath } ->\n List.member \"Util\" moduleName\n || String.startsWith \"src/test-helpers/\" filePath\n )\n ]\n }\n |> NoUnused.Exports.toRule\n\nno elements from modules named `*.Util.*` or modules inside `src/test-helpers/` will be reported.\n\nThe provided `filePath` is relative to the project's `elm.json` and is in a UNIX style (`/`, no `\\`).\n\n","type":"({ moduleName : Elm.Syntax.ModuleName.ModuleName, filePath : String.String } -> Basics.Bool) -> NoUnused.Exports.Exception"},{"name":"prefixedBy","comment":" Prevents reporting usages of elements whose name start with a specific string.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre = [ prefixedBy \"test_\" ]\n }\n |> NoUnused.Exports.toRule\n\nany element that starts with `\"test_\"` will not be reported as unused (as long as its used at least once in the project):\n\n test_someFunction input =\n doSomethingComplexWith input\n\nYou can use this function several times to define multiple prefixes.\n\n","type":"String.String -> NoUnused.Exports.Exception"},{"name":"reportUnusedProductionExports","comment":" Configures the rule to report elements defined in production code but only used in non-production files.\n\n import NoUnused.Exports exposing (annotatedBy, prefixedBy, suffixedBy)\n\n config =\n [ NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile =\n \\{ moduleName, filePath, isInSourceDirectories } ->\n isInSourceDirectories\n && not (String.endsWith \"/Example.elm\" filePath)\n , exceptionsAre = [ annotatedBy \"@test-helper\" ]\n }\n |> NoUnused.Exports.toRule\n ]\n\nElements reported using this configuration won't be automatically fixed as they require removing the code\nthat uses the element.\n\nThis function needs to know two things:\n\n1. Which files are considered to be production files, which is determined by a function that you provide.\n Generally, production files are the ones that in the `\"source-directories\"`, which is indicated by\n `isInSourceDirectories` (that is given as an argument to the function) being `True`. If you want to exclude\n more files, you can use the `filePath` or `moduleName` of the Elm module, whichever is more practical for you to use.\n `filePath` is relative to the folder containing the `elm.json` file and is written in a UNIX format (`/`, no `\\`).\n\n2. How to identify exceptions. See [`Exception`](#Exception) for more information.\n\n","type":"{ isProductionFile : { moduleName : Elm.Syntax.ModuleName.ModuleName, filePath : String.String, isInSourceDirectories : Basics.Bool } -> Basics.Bool, exceptionsAre : List.List NoUnused.Exports.Exception } -> NoUnused.Exports.Configuration -> NoUnused.Exports.Configuration"},{"name":"rule","comment":" Report functions and types that are exposed from a module but that are never\nused in other modules. Also reports when a module is entirely unused.\n\n config =\n [ NoUnused.Exports.rule\n ]\n\nThis is equivalent to `NoUnused.Exports.toRule NoUnused.Exports.defaults`.\n\n","type":"Review.Rule.Rule"},{"name":"suffixedBy","comment":" Prevents reporting usages of elements whose name end with a specific string.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre = [ suffixedBy \"_FOR_TESTS\" ]\n }\n |> NoUnused.Exports.toRule\n\nany element that ends with `\"_FOR_TESTS\"` will not be reported as unused (as long as its used at least once in the project):\n\n someFunction_FOR_TESTS input =\n doSomethingComplexWith input\n\nYou can use this function several times to define multiple suffixes.\n\n","type":"String.String -> NoUnused.Exports.Exception"},{"name":"toRule","comment":" Creates a rule that reports unused exports using a [`Configuration`](#Configuration).\n","type":"NoUnused.Exports.Configuration -> Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Modules","comment":" Forbid the use of modules that are never used in your project.\n\n**@deprecated** This rule has been deprecated, as it has now been integrated into [`NoUnused.Exports`](NoUnused-Exports).\nYou should use that rule instead.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Forbid the use of modules that are never used in your project.\n\nA module is considered used if\n\n - it contains a `main` function (be it exposed or not)\n - it imports the `Test` module\n - it is imported in any other modules, even if it is not used.\n - the project is a package and the module is part of the `elm.json`'s `exposed-modules`\n - it is named `ReviewConfig`\n\n```elm\nconfig =\n [ NoUnused.Modules.rule\n ]\n```\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Modules\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Parameters","comment":" Report parameters that are not used.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Report parameters that are not used.\n\n🔧 Running with `--fix` will automatically remove some of the reported errors.\n\n config =\n [ NoUnused.Parameters.rule\n ]\n\nThis rule looks within function arguments, let functions and lambdas to find any values that are unused. It will report any parameters that are not used.\n\n\n## Fixes for lambdas\n\nWe're only offering fixes for lambdas here because we believe unused parameters in functions are a code smell that should be refactored.\n\n\n## Fail\n\nValue `number` is not used:\n\n add1 number =\n 1\n\nThe rule will also report parameters that are only used to be passed again to the containing recursive function:\n\n last list unused =\n case list of\n [] ->\n Nothing\n\n [ a ] ->\n Just a\n\n _ :: rest ->\n last rest unused\n\n\n## Success\n\n add1 number =\n number + 1\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Parameters\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Patterns","comment":" Report useless patterns and pattern values that are not used.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Report useless patterns and pattern values that are not used.\n\n🔧 Running with `--fix` will automatically remove all the reported errors.\n\n config =\n [ NoUnused.Patterns.rule\n ]\n\nThis rule looks within let..in blocks and case branches to find any patterns that are unused. It will report any useless patterns as well as any pattern values that are not used.\n\n\n## Fail\n\nValue `something` is not used:\n\n case maybe of\n Just something ->\n True\n\n Nothing ->\n False\n\n\n## Success\n\n case maybe of\n Just _ ->\n True\n\n Nothing ->\n False\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Patterns\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Variables","comment":" Report variables or types that are declared or imported but never used inside of a module.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Report variables or types that are declared or imported but never used.\n\n🔧 Running with `--fix` will automatically remove all the reported errors.\n\n config =\n [ NoUnused.Variables.rule\n ]\n\n\n## Fail\n\n module A exposing (a, b)\n\n import UnusedImport\n\n a n =\n n + 1\n\n b =\n let\n unused =\n some thing\n\n _ =\n someOther thing\n in\n 2\n\n c =\n a 2\n\n\n## Success\n\n module A exposing (a, b)\n\n a n =\n n + 1\n\n b =\n 2\n\n\n## Exception\n\nTo avoid resorting to weird workarounds that are sometimes used in internal interactive examples, the rule won't report\nvalues assigned to `_` if a direct call to `Debug.log` is assigned to it.\n\n a value =\n let\n _ =\n Debug.log \"value\" value\n in\n value + 1\n\nIf you enable the [`NoDebug.Log`](https://package.elm-lang.org/packages/jfmengels/elm-review-debug/latest/NoDebug-Log) rule\nfrom the [`jfmengels/elm-review-debug`](https://package.elm-lang.org/packages/jfmengels/elm-review-debug/latest/) package,\nand configure it to ignore the locations where it's acceptable, then the combination of both rules will make sure to\nclean up code like the above in all the other locations.\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Variables\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]}] \ No newline at end of file +[{"name":"NoUnused.CustomTypeConstructorArgs","comment":"\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Reports arguments of custom type constructors that are never used.\n\n config =\n [ NoUnused.CustomTypeConstructorArgs.rule\n ]\n\nCustom type constructors can contain data that is never extracted out of the constructor.\nThis rule will warn arguments that are always pattern matched using a wildcard (`_`).\n\nFor package projects, custom types whose constructors are exposed as part of the package API are not reported.\n\nNote that this rule **may report false positives** if you compare custom types with the `==` or `/=` operators\n(and never destructure the custom type), like when you do `value == Just 0`, or store them in lists for instance with\n[`assoc-list`](https://package.elm-lang.org/packages/pzp1997/assoc-list/latest).\nThis rule attempts to detect when the custom type is used in comparisons, but it may still result in false positives.\n\n\n## Fail\n\n type CustomType\n = CustomType Used Unused\n\n case customType of\n CustomType value _ -> value\n\n\n## Success\n\n type CustomType\n = CustomType Used Unused\n\n case customType of\n CustomType value maybeUsed -> value\n\n\n## When not to enable this rule?\n\nIf you like giving names to all arguments when pattern matching, then this rule will not find many problems.\nThis rule will work well when enabled along with [`NoUnused.Patterns`](./NoUnused-Patterns).\n\nAlso, if you like comparing custom types in the way described above, you might pass on this rule, or want to be very careful when enabling it.\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.CustomTypeConstructorArgs\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.CustomTypeConstructors","comment":" Forbid having unused custom type constructors inside the project.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Forbid having unused custom type constructors.\n\n🔧 Running with `--fix` will automatically remove most of the reported errors.\n\n config =\n [ NoUnused.CustomTypeConstructors.rule []\n ]\n\nNote that this rule reports any custom type constructor that isn't used\nanywhere _in the project_.\n\nIf the project is a package and the module that declared the type is exposed and\nthe type's constructors are exposed, then the constructors will not be reported.\n\nThis does not prevent you from using phantom types.\nI highly suggest chaning your phantom types to the following shape: `type TypeName = ConstructorName Never`.\nThis shape makes it obvious to tooling and readers that the type can't be created, so if it is used, it must be as a phantom type.\n\n**Deprecated configuration for phantom types**\n\n_I recommend changing your types like mentioned right above, and to configure the rule like `NoUnused.CustomTypeConstructors.rule []`.\nI'll keep this section and configuration option around until the next major version comes out._\n\n**Note**: At the time of writing, there may be cases where phantom types are not well detected.\nWhen an opaque type is defined in a dependency, we don't know whether a type variable should be considered as a phantom type.\n\nTherefore, sometimes this rule will need some help, by having you tell it what type variables of which type is a phantom type variable.\nThat's what the argument to the rule is for.\n\nTo explain that the `a` in `type Id a = Id String` from the `IdModule` module\ncorresponds to a phantom type variable, you would configure the rule like this:\n\n config =\n [ NoUnused.CustomTypeConstructors.rule\n [ { moduleName = \"IdModule\"\n , typeName = \"Id\"\n , index = 0 -- Position of the phantom variable in the type's arguments\n }\n ]\n ]\n\nThis rule could do a much better job than it currently does at figuring this out,\nby following the definitions of custom types and type aliases, until it finds out that the type\nvariable is not used, or that it hits the limit related to dependencies described above.\nIn the meantime, you can configure the rule with all the phantom type exceptions.\n\n**End of deprecated section**\n\n\n## Fail\n\n module A exposing (a)\n\n type MyType\n = UsedType\n | UnusedType -- Will get reported\n\n a =\n UsedType\n\n\n## Success\n\n module A exposing (ExposedType(..))\n\n type MyType\n = UsedType\n\n a =\n UsedType\n\n type ExposedType\n = A\n | B\n | C\n\n -----------------------\n module A exposing (..)\n\n type ExposedType\n = A\n | B\n | C\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.CustomTypeConstructors\n```\n\n","type":"List.List { moduleName : String.String, typeName : String.String, index : Basics.Int } -> Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Dependencies","comment":" Forbid the use of dependencies that are never used in your project.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Forbid the use of dependencies that are never used in your project.\n\n🔧 Running with `--fix` will automatically remove all the reported errors.\n\nA dependency is considered unused if none of its modules are imported in the project.\n\n config =\n [ NoUnused.Dependencies.rule\n ]\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Dependencies\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Exports","comment":" Forbid the use of exposed elements (functions, values or types) that are never used in your project.\n\n🔧 Running with `--fix` will automatically remove all the reported errors,\nexcept for the ones reported when using [`reportUnusedProductionExports`](#reportUnusedProductionExports).\nIt won't automatically remove unused modules though.\n\nIf the project is a package and the module that declared the element is exposed,\nthen nothing will be reported.\n\n@docs rule\n\n\n## Going one step further\n\nThis rule can be configured to report more unused elements than the default configuration.\n\n@docs Configuration, defaults, toRule\n\nBy default, this rule only reports exposed elements that are never imported in other modules.\nIt is however pretty common to have elements imported and used in non-production parts of the codebase,\nsuch as in tests or in a styleguide.\n\nFor instance, let's say there is a module `A` that exposes a function `someFunction`:\n\n module A exposing (someFunction)\n\n someFunction input =\n doSomethingComplexWith input\n\nAnd there is this test module to test `A.someFunction`:\n\n module ATest exposing (tests)\n\n import A\n import Test exposing (Test, describe, test)\n\n tests : Test\n tests =\n describe \"A.someFunction\"\n [ test \"does something complex\" <|\n \\() ->\n A.someFunction someInput\n |> Expect.equal someExpectedOutput\n ]\n\nLet's say this is the only use of `A.someFunction` in the entire project.\nBecause `A.someFunction` is technically used in the project, this rule won't report it.\n\nBut since the function is not used in production code, it is a good practice to remove it, as that will remove the\namount of code that needs to be maintained unnecessarily. We can detect that using [`reportUnusedProductionExports`](#reportUnusedProductionExports).\n\n@docs reportUnusedProductionExports\n\n@docs Exception, annotatedBy, suffixedBy, prefixedBy, definedInModule\n\n\n## Try it out\n\nYou can try this rule out by running the following commands:\n\nUsing the default configuration:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Exports\n```\n\nUsing `reportUnusedProductionExports` with the following configuration:\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = \\{ moduleName, filePath, isInSourceDirectories } -> isInSourceDirectories\n , exceptionsAre = [ annotatedBy \"@test-helper\", suffixedBy \"_FOR_TESTS\" ]\n }\n |> NoUnused.Exports.toRule\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example-ignore-tests --rules NoUnused.Exports\n```\n\n","unions":[{"name":"Configuration","comment":" Configuration for the rule. Use [`defaults`](#defaults) to get a default configuration and use [`toRule`](#toRule) to turn it into a rule.\nYou can change the configuration using [`reportUnusedProductionExports`](#reportUnusedProductionExports).\n","args":[],"cases":[]},{"name":"Exception","comment":" Predicate to identify exceptions (that shouldn't be reported) for elements defined in production code that are only used in non-production code.\n\nA problem with reporting these elements is that it's going to produce false positives, as there are legitimate use-cases\nfor exporting these elements, hence the need for the rule to be able to identify them.\n\nFor instance, while it's generally discouraged, you might want to test the internals of an API (to make sure some properties hold\ngiven very specific situations). In this case, your module then needs to expose a way to gain insight to the internals.\n\nAnother example is giving the means for tests to create opaque types that are impossible or very hard to create in a test\nenvironment. This can be the case for types that can only be created through the decoding of an HTTP request.\n\nNote that another common way to handle these use-cases is to move the internals to another module that exposes everything\nwhile making sure only specific production modules import it.\n\n","args":[],"cases":[]}],"aliases":[],"values":[{"name":"annotatedBy","comment":" Prevents reporting usages of elements that contain a specific tag in their documentation.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre = [ annotatedBy \"@test-helper\" ]\n }\n |> NoUnused.Exports.toRule\n\nany element that has `@test-helper` in its documentation will not be reported as unused (as long as its used at least once in the project):\n\n {-| @test-helper\n -}\n someFunction input =\n doSomethingComplexWith input\n\nA recommended practice is to have annotations start with `@`.\n\nYou can use this function several times to define multiple annotations.\n\n","type":"String.String -> NoUnused.Exports.Exception"},{"name":"defaults","comment":" Default configuration. This will only report exported elements that are never used in other modules.\n","type":"NoUnused.Exports.Configuration"},{"name":"definedInModule","comment":" Prevents reporting usages of elements in some modules.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre =\n [ definedInModule\n (\\{ moduleName, filePath } ->\n List.member \"Util\" moduleName\n || String.startsWith \"src/test-helpers/\" filePath\n )\n ]\n }\n |> NoUnused.Exports.toRule\n\nno elements from modules named `*.Util.*` or modules inside `src/test-helpers/` will be reported.\n\nThe provided `filePath` is relative to the project's `elm.json` and is in a UNIX style (`/`, no `\\`).\n\n","type":"({ moduleName : Elm.Syntax.ModuleName.ModuleName, filePath : String.String } -> Basics.Bool) -> NoUnused.Exports.Exception"},{"name":"prefixedBy","comment":" Prevents reporting usages of elements whose name start with a specific string.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre = [ prefixedBy \"test_\" ]\n }\n |> NoUnused.Exports.toRule\n\nany element that starts with `\"test_\"` will not be reported as unused (as long as its used at least once in the project):\n\n test_someFunction input =\n doSomethingComplexWith input\n\nYou can use this function several times to define multiple prefixes.\n\n","type":"String.String -> NoUnused.Exports.Exception"},{"name":"reportUnusedProductionExports","comment":" Configures the rule to report elements defined in production code but only used in non-production files.\n\n import NoUnused.Exports exposing (annotatedBy)\n\n config =\n [ NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile =\n \\{ moduleName, filePath, isInSourceDirectories } ->\n isInSourceDirectories\n && not (String.endsWith \"/Example.elm\" filePath)\n , exceptionsAre = [ annotatedBy \"@test-helper\" ]\n }\n |> NoUnused.Exports.toRule\n ]\n\nElements reported using this configuration won't be automatically fixed as they require removing the code\nthat uses the element.\n\nThis function needs to know two things:\n\n1. Which files are considered to be production files, which is determined by a function that you provide.\n Generally, production files are in the `\"source-directories\"`, which is indicated by\n `isInSourceDirectories` (given as an argument to the function) being `True`. If you want to exclude\n more files, you can use the `filePath` or `moduleName` of the Elm module, whichever is more practical for you to use.\n `filePath` is relative to the folder containing the `elm.json` file and is written in a UNIX format (`/`, no `\\`).\n\n2. How to identify exceptions. See [`Exception`](#Exception) for more information.\n\n","type":"{ isProductionFile : { moduleName : Elm.Syntax.ModuleName.ModuleName, filePath : String.String, isInSourceDirectories : Basics.Bool } -> Basics.Bool, exceptionsAre : List.List NoUnused.Exports.Exception } -> NoUnused.Exports.Configuration -> NoUnused.Exports.Configuration"},{"name":"rule","comment":" Report functions and types that are exposed from a module but that are never\nused in other modules. Also reports when a module is entirely unused.\n\n config =\n [ NoUnused.Exports.rule\n ]\n\nThis is equivalent to `NoUnused.Exports.toRule NoUnused.Exports.defaults`.\n\n","type":"Review.Rule.Rule"},{"name":"suffixedBy","comment":" Prevents reporting usages of elements whose name end with a specific string.\n\nGiven the following configuration\n\n NoUnused.Exports.defaults\n |> NoUnused.Exports.reportUnusedProductionExports\n { isProductionFile = isProductionFile\n , exceptionsAre = [ suffixedBy \"_FOR_TESTS\" ]\n }\n |> NoUnused.Exports.toRule\n\nany element that ends with `\"_FOR_TESTS\"` will not be reported as unused (as long as its used at least once in the project):\n\n someFunction_FOR_TESTS input =\n doSomethingComplexWith input\n\nYou can use this function several times to define multiple suffixes.\n\n","type":"String.String -> NoUnused.Exports.Exception"},{"name":"toRule","comment":" Creates a rule that reports unused exports using a [`Configuration`](#Configuration).\n","type":"NoUnused.Exports.Configuration -> Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Modules","comment":" Forbid the use of modules that are never used in your project.\n\n**@deprecated** This rule has been deprecated, as it has now been integrated into [`NoUnused.Exports`](NoUnused-Exports).\nYou should use that rule instead.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Forbid the use of modules that are never used in your project.\n\nA module is considered used if\n\n - it contains a `main` function (be it exposed or not)\n - it imports the `Test` module\n - it is imported in any other modules, even if it is not used.\n - the project is a package and the module is part of the `elm.json`'s `exposed-modules`\n - it is named `ReviewConfig`\n\n```elm\nconfig =\n [ NoUnused.Modules.rule\n ]\n```\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Modules\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Parameters","comment":" Report parameters that are not used.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Report parameters that are not used.\n\n🔧 Running with `--fix` will automatically remove some of the reported errors.\n\n config =\n [ NoUnused.Parameters.rule\n ]\n\nThis rule looks within function arguments, let functions and lambdas to find any values that are unused. It will report any parameters that are not used.\n\n\n## Fixes for lambdas\n\nWe're only offering fixes for lambdas here because we believe unused parameters in functions are a code smell that should be refactored.\n\n\n## Fail\n\nValue `number` is not used:\n\n add1 number =\n 1\n\nThe rule will also report parameters that are only used to be passed again to the containing recursive function:\n\n last list unused =\n case list of\n [] ->\n Nothing\n\n [ a ] ->\n Just a\n\n _ :: rest ->\n last rest unused\n\n\n## Success\n\n add1 number =\n number + 1\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Parameters\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Patterns","comment":" Report useless patterns and pattern values that are not used.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Report useless patterns and pattern values that are not used.\n\n🔧 Running with `--fix` will automatically remove all the reported errors.\n\n config =\n [ NoUnused.Patterns.rule\n ]\n\nThis rule looks within let..in blocks and case branches to find any patterns that are unused. It will report any useless patterns as well as any pattern values that are not used.\n\n\n## Fail\n\nValue `something` is not used:\n\n case maybe of\n Just something ->\n True\n\n Nothing ->\n False\n\n\n## Success\n\n case maybe of\n Just _ ->\n True\n\n Nothing ->\n False\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Patterns\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]},{"name":"NoUnused.Variables","comment":" Report variables or types that are declared or imported but never used inside of a module.\n\n@docs rule\n\n","unions":[],"aliases":[],"values":[{"name":"rule","comment":" Report variables or types that are declared or imported but never used.\n\n🔧 Running with `--fix` will automatically remove all the reported errors.\n\n config =\n [ NoUnused.Variables.rule\n ]\n\n\n## Fail\n\n module A exposing (a, b)\n\n import UnusedImport\n\n a n =\n n + 1\n\n b =\n let\n unused =\n some thing\n\n _ =\n someOther thing\n in\n 2\n\n c =\n a 2\n\n\n## Success\n\n module A exposing (a, b)\n\n a n =\n n + 1\n\n b =\n 2\n\n\n## Exception\n\nTo avoid resorting to weird workarounds that are sometimes used in internal interactive examples, the rule won't report\nvalues assigned to `_` if a direct call to `Debug.log` is assigned to it.\n\n a value =\n let\n _ =\n Debug.log \"value\" value\n in\n value + 1\n\nIf you enable the [`NoDebug.Log`](https://package.elm-lang.org/packages/jfmengels/elm-review-debug/latest/NoDebug-Log) rule\nfrom the [`jfmengels/elm-review-debug`](https://package.elm-lang.org/packages/jfmengels/elm-review-debug/latest/) package,\nand configure it to ignore the locations where it's acceptable, then the combination of both rules will make sure to\nclean up code like the above in all the other locations.\n\n\n## Try it out\n\nYou can try this rule out by running the following command:\n\n```bash\nelm-review --template jfmengels/elm-review-unused/example --rules NoUnused.Variables\n```\n\n","type":"Review.Rule.Rule"}],"binops":[]}] \ No newline at end of file diff --git a/src/NoUnused/Exports.elm b/src/NoUnused/Exports.elm index 96c14a45..9e5758bc 100644 --- a/src/NoUnused/Exports.elm +++ b/src/NoUnused/Exports.elm @@ -156,7 +156,7 @@ defaults = {-| Configures the rule to report elements defined in production code but only used in non-production files. - import NoUnused.Exports exposing (annotatedBy, prefixedBy, suffixedBy) + import NoUnused.Exports exposing (annotatedBy) config = [ NoUnused.Exports.defaults @@ -176,8 +176,8 @@ that uses the element. This function needs to know two things: 1. Which files are considered to be production files, which is determined by a function that you provide. - Generally, production files are the ones that in the `"source-directories"`, which is indicated by - `isInSourceDirectories` (that is given as an argument to the function) being `True`. If you want to exclude + Generally, production files are in the `"source-directories"`, which is indicated by + `isInSourceDirectories` (given as an argument to the function) being `True`. If you want to exclude more files, you can use the `filePath` or `moduleName` of the Elm module, whichever is more practical for you to use. `filePath` is relative to the folder containing the `elm.json` file and is written in a UNIX format (`/`, no `\`).