From 260f6855b567c8b1bb289b3d9c25cdcfeac22c8e Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Sat, 9 Mar 2024 17:25:31 +0000
Subject: [PATCH] chore: add docs

---
 README.md                           |  5 +++++
 docs/rules/avoid-micro-utilities.md | 28 +++++++++++++++++++++++++
 docs/rules/redundant-polyfills.md   | 32 +++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 docs/rules/avoid-micro-utilities.md
 create mode 100644 docs/rules/redundant-polyfills.md

diff --git a/README.md b/README.md
index ca3bbc0..a689f7e 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,11 @@ export default [
 ];
 ```
 
+## Rules
+
+- [`optimize/redundant-polyfills`](./docs/rules/redundant-polyfills.md)
+- [`optimize/avoid-micro-utilities`](./docs/rules/avoid-micro-utilities.md)
+
 ## License
 
 MIT
diff --git a/docs/rules/avoid-micro-utilities.md b/docs/rules/avoid-micro-utilities.md
new file mode 100644
index 0000000..b76a06a
--- /dev/null
+++ b/docs/rules/avoid-micro-utilities.md
@@ -0,0 +1,28 @@
+# Detects possibly redundant micro-utilities, preferring local/inline functionality instead
+
+This rule detects imports of "micro utilities" - very small packages which
+provide utilities you could replace with native functionality or your own
+code.
+
+## Rule Details
+
+This rule detects possibly redundant micro-utilities.
+
+The following patterns are considered warnings:
+
+```ts
+const isNaN = require('is-nan');
+isNaN(v);
+```
+
+The following patterns are not warnings:
+
+```ts
+Number.isNaN(v);
+```
+
+## When Not To Use It
+
+If you prefer the cost of pulling in many utility dependencies over
+the cost of writing the equivalent snippet yourself, it may be worth disabling
+this rule.
diff --git a/docs/rules/redundant-polyfills.md b/docs/rules/redundant-polyfills.md
new file mode 100644
index 0000000..8f7f721
--- /dev/null
+++ b/docs/rules/redundant-polyfills.md
@@ -0,0 +1,32 @@
+# Detects possibly redundant polyfills of natively available functionality
+
+This rule detects imports of dependencies which provide functionality now
+available natively.
+
+If your package has an `engines` constraint for `node`, it will be taken
+into account (i.e. polyfills of functionality your version doesn't yet have
+will be allowed).
+
+## Rule Details
+
+This rule detects possibly redundant polyfills.
+
+The following patterns are considered warnings:
+
+```ts
+// With no `engines` or `engines.node` is `>=7.0.0`
+const entries = require('object.entries');
+entries({foo: 'bar'});
+```
+
+The following patterns are not warnings:
+
+```ts
+// With no `engines` or `engines.node` is `>=7.0.0`
+Object.entries({foo: 'bar'});
+```
+
+## When Not To Use It
+
+If you need to support much older JS runtimes (node, browsers, etc), this
+rule may not be of much use as the polyfills are probably still useful there.