eslint-plugin-hex-under 1.7.5 → 1.7.7

package/README.md

@@ -1,29 +1,47 @@
 # eslint-plugin-hex-under
 
-Improve readability by enforcing limits on non-decimal numeric literals (hex, binary, octal).
+Enforce readability by limiting non-decimal numeric literals (hex, binary, octal) in JavaScript.
 
-This plugin helps prevent hard-to-read numeric literals by automatically converting large values into their decimal representation or raising an error.
+Automatically converts large non-decimal literals into readable decimal values or reports them as errors.
 
 ## Why?
 
-Numeric literals like `0xfff` or `0b101010101` are compact, but often hard to read and reason about.
+Numeric literals like `0xfff` or `0b101010101` are compact, but often hard to read and reason about—especially for developers unfamiliar with bitwise operations.
+
+This can lead to:
+
+- Reduced code readability
+- Slower code reviews
+- Hidden "magic numbers"
+
+This plugin enforces limits to keep numeric literals understandable at a glance.
 
 ## hex-under
 
-This ESLint plugin ensures that numeric literals written in non-decimal formats (hexadecimal, binary, or octal) do not exceed a specified maximum value. By default, the limit corresponds to the largest commonly used value for each format (`255` for hexadecimal, `15` for binary, and `511` for octal). Values exceeding the limit are automatically converted to their decimal representation.
+This ESLint plugin ensures that numeric literals written in non-decimal formats (hexadecimal, binary, or octal) do not exceed a specified maximum value.
+By default, the limits are:
+
+- Hexadecimal: `0xff` (255)
+- Binary: `0b1111` (15)
+- Octal: `0o777` (511)
+
+Values exceeding these limits are automatically converted to decimal.
 
 ## When should I use this?
 
 Use this plugin if:
-- You care about code readability
-- Your team avoids "magic numbers"
-- You review low-level or bitwise-heavy code
 
-### Example
+- You want to improve code readability in your codebase
+- Your team avoids hard-to-read numeric literals ("magic numbers")
+- You work with bitwise operations but want to keep them understandable
+- You review code where non-decimal formats are frequently used
+
+### Examples
+
+#### valid with default limits
 
 ```js
-// valid with { limit: 255 }
-const signal = 0xef;
+const signal = 0xef; // OK: below default hex limit (255)
 
 let func = () => 0xab;
 
@@ -34,18 +52,11 @@ function add(a, b) {
 const binary = 0b1111_1111;
 
 const octal = 0o377;
+```
 
-/* You can also turn off the rule with a comment, see next examples */
-// ignore-hex-under
-const hexTooBig = 0xfffff;
-const binTooBig = 0b1000_0000_0000; // ignore-binary-under
-// ignore-octal-under
-const octalTooBig = 0o777777;
-
-// valid with { limit: 255, skipBigInt: true }
-const mask = 0xdead_beefn;
+#### Invalid with default limits
 
-// invalid with { limit: 255 }
+```js
 const signal = 0x21b;
 
 let func = () => 0xabc;
@@ -59,7 +70,11 @@ let d = 0xaa_ffn;
 const binary = 0b1_0000_0000;
 
 const octal = 0o400;
+```
+
+#### Auto-fixable
 
+```js
 // This can be transformed to:
 const signal = 539;
 
@@ -76,31 +91,52 @@ const binary = 256;
 const octal = 256;
 ```
 
-If you want to disable all rules, you can paste a special block comment at the very first line of the file.
+#### Ignore with line comments
+
+```js
+// ignore-hex-under
+const hexTooBig = 0xfffff;
+
+const binTooBig = 0b1000_0000_0000; // ignore-binary-under
+
+// ignore-octal-under
+const octalTooBig = 0o777777;
+```
+
+#### Ignore Bigint values
+
+```js
+// valid with { limit: 255, skipBigInt: true }
+const mask = 0xdead_beefn;
+```
+
+#### Disable rules globally
 
 ```js
 /* ignore-all-hex-under */
 
-// this all will be ignored
+// ignore-all-hex-under must be the very first line and a block comment.
+// This will ignore all of the whole file.
 const foo = 0xffff;
-
 const bar = 0b10100010101;
 ```
 
-Or you disable every rule separately with a block comment before the code, e.g.:
+#### Disable specific formats
 
 ```js
-// This should be ignore all hex numbers but not octal or binary numbers.
+// This should ignore all hex numbers but not octal or binary numbers.
 
 /* ignore-hex-under */
 
-const hex = 0x100; // This should stay 0x100
-const octal = 0o1000; // This should be fixed to 512
-const binary = 0b10000; // This should be fixed to 16
+const hex = 0x100; // stays 0x100
+const octal = 0o1000; // fixed to 512
+const binary = 0b10000; // fixed to 16
 ```
 
 ## Integration
 
+Requires ESLint v9+ (flat config)
+
 ```sh
 npm install --save-dev eslint-plugin-hex-under
 ```
@@ -125,12 +161,28 @@ export default [
 ];
 ```
 
+## Rules
+
+| Rule                     | Description                 |
+| ------------------------ | --------------------------- |
+| `hex-under/hex-under`    | Limits hexadecimal literals |
+| `hex-under/binary-under` | Limits binary literals      |
+| `hex-under/octal-under`  | Limits octal literals       |
+
 ## Configuration
 
-Option       | Type    | Default           | Description
--------------|---------|-------------------|--------------------------------
-`limit`      | number  | format-specific   | Maximum allowed value
-`skipBigInt` | boolean | false             | Ignore BigInt values
+| Option       | Type    | Default         | Description           |
+| ------------ | ------- | --------------- | --------------------- |
+| `limit`      | number  | format-specific | Maximum allowed value |
+| `skipBigInt` | boolean | false           | Ignore BigInt values  |
+
+### Ignoring rules
+
+You can disable rules using inline comments:
+
+- `ignore-hex-under`
+- `ignore-binary-under`
+- `ignore-octal-under`
 
 ## Testing & Code Coverage
 

package/package.json

@@ -43,5 +43,5 @@
     "test:watch": "vitest"
   },
   "type": "module",
-  "version": "1.7.5"
+  "version": "1.7.7"
 }