Add must_use lint

CHANGELOG.md

@@ -5,6 +5,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Added
 - `table.insert(x)` no longer counts as a read to `x`, which allows selene to alert you that you are only assigning to it.
   - This is done through a new standard library field for arguments called `observes`. This takes 3 values: "read-write" (the default), signifying a potential read and write, "read", signifying only a read, and "write", signifying only a write. Only "write" has meaning at this time.
+- Added new `must_use` lint, which will warn you when you are not using the return value of a function that performs no other behavior.
+  - This is done through a new standard library field for functions called `must_use`. Set it to `true` to gain this functionality.
 
 ### Fixed
 - Fixed a bunch of performance failures, lowering some benchmarks from 3 seconds to 200ms.

docs/src/SUMMARY.md

@@ -22,6 +22,7 @@
   - [if_same_then_else](./lints/if_same_then_else.md)
   - [ifs_same_cond](./lints/ifs_same_cond.md)
   - [multiple_statements](./lints/multiple_statements.md)
+  - [must_use](./lint/must_use.md)
   - [mismatched_arg_count](./lints/mismatched_arg_count.md)
   - [parenthese_conditions](./lints/parenthese_conditions.md)
   - [roblox_incorrect_color3_new_bounds](./lints/roblox_incorrect_color3_new_bounds.md)

docs/src/lints/must_use.md

@@ -0,0 +1,23 @@
+# must_use
+## What it does
+Checks that the return values of functions [marked `must_use`](../usage/std.md#must_use) are used.
+
+## Why this is bad
+This lint will only catch uses where the function has no reason to be called other than to use its output.
+
+
+## Example
+```lua
+bit32.bor(entity.flags, Flags.Invincible)
+```
+
+...should be written as...
+
+```lua
+entity.flags = bit32.bor(entity.flags, Flags.Invincible)
+```
+
+...as `bit32.bor` only produces a new value, it does not mutate anything.
+
+## Remarks
+The output is deemed "unused" if the function call is its own statement.