@allxsmith/eslint-plugin-bestax 0.0.0-development → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,8 +1,16 @@
1
1
  import { TEXT_ALIAS_COLOR_ELEMENTS } from '../generated/metadata.js';
2
- import { attributesOf, elementOf, hasSpread, literalValue, withImports, } from '../lib/elements.js';
2
+ import { validColorShades, validColors, } from '@allxsmith/bestax-bulma/constants';
3
+ import { attributesOf, doubledNames, elementOf, hasSpread, isKnownNonNullish, isUnreadableValue, literalValue, namedAttr, withImports, } from '../lib/elements.js';
3
4
  const TEXT_ALIAS = new Set(TEXT_ALIAS_COLOR_ELEMENTS);
4
5
  /** Setting either of these shows the author knows where the surface comes from. */
5
6
  const BACKGROUND_PROPS = ['bgColor', 'backgroundColor'];
7
+ /**
8
+ * Values for which the message's claim is true. `useColorClasses` emits
9
+ * nothing outside this set, so on anything else the rule would assert a class
10
+ * that never renders — and its fix would move a dead value to a different dead
11
+ * prop. A wrong value is `valid-helper-value`'s to report, not this rule's.
12
+ */
13
+ const RENDERABLE = new Set([...validColors, 'inherit', 'current']);
6
14
  const rule = {
7
15
  meta: {
8
16
  type: 'suggestion',
@@ -13,7 +21,7 @@ const rule = {
13
21
  },
14
22
  schema: [],
15
23
  messages: {
16
- ambiguous: '`color` on `{{element}}` is a text-colour alias — it renders `has-text-{{value}}`, and no `is-<color>` CSS exists for it. Write `textColor="{{value}}"` to say so, or `bgColor="{{value}}"` if you wanted a coloured surface.',
24
+ ambiguous: '`color` on `{{element}}` is a text-colour alias — it renders `{{rendered}}`, and no `is-<color>` CSS exists for it. Write `textColor="{{value}}"` to say so, or `bgColor="{{value}}"` if you wanted a coloured surface.',
17
25
  redundant: '`color` on `{{element}}` is ignored here: `textColor` is already set and takes precedence. Remove `color`.',
18
26
  },
19
27
  },
@@ -32,11 +40,25 @@ const rule = {
32
40
  if (hasSpread(opening))
33
41
  return;
34
42
  const attrs = attributesOf(opening);
35
- const named = (n) => attrs.find((a) => a.name.name === n);
43
+ const named = (n) => namedAttr(attrs, n);
36
44
  const color = named('color');
37
45
  if (!color)
38
46
  return;
39
- if (named('textColor')) {
47
+ const textColor = named('textColor');
48
+ if (textColor) {
49
+ // `color: textColor ?? color` ignores `color` only when `textColor`
50
+ // is non-nullish, which is stronger than readable: a readable `null`
51
+ // leaves the `??` resolving to `color`, so the element really does
52
+ // render it and "remove `color`" would delete what renders. A
53
+ // readable `true` or number does win, so those still report.
54
+ //
55
+ // This rule RETURNS in that case rather than reporting `ambiguous`.
56
+ // The ambiguous message would be true — `color` is the value being
57
+ // used as a text alias — but its fix rewrites `color` to `textColor`,
58
+ // which on an element already carrying one emits a duplicate
59
+ // attribute. Silence on an opt-in rule beats that.
60
+ if (!isKnownNonNullish(textColor))
61
+ return;
40
62
  context.report({
41
63
  node: color,
42
64
  messageId: 'redundant',
@@ -52,13 +74,43 @@ const rule = {
52
74
  // computed value could be anything, and the message would have to say
53
75
  // so in place of the value, which is not advice anyone can act on.
54
76
  const value = literalValue(color);
55
- if (value === null)
77
+ if (value === null || !RENDERABLE.has(value))
56
78
  return;
79
+ // `colorShade` decides which class the library emits, and it applies
80
+ // the same membership test as every other value: `addColorClass`
81
+ // shades only `if (shade && validColorShades.includes(shade))`, and
82
+ // falls back to the unshaded class otherwise. So a shade outside the
83
+ // tuple means the unshaded class, and a shade this rule cannot read
84
+ // means it cannot state the class at all.
85
+ let shadeSuffix = '';
86
+ const shadeAttr = named('colorShade');
87
+ if (shadeAttr) {
88
+ if (isUnreadableValue(shadeAttr))
89
+ return;
90
+ // A readable shade that is not in the tuple leaves the class
91
+ // unshaded, which `addColorClass` does for `true` and a number too.
92
+ const shade = literalValue(shadeAttr);
93
+ if (shade !== null && validColorShades.includes(shade)) {
94
+ shadeSuffix = `-${shade}`;
95
+ }
96
+ }
57
97
  context.report({
58
98
  node: color.name,
59
99
  messageId: 'ambiguous',
60
- data: { element, value },
61
- fix: fixer => fixer.replaceText(color.name, 'textColor'),
100
+ data: {
101
+ element,
102
+ value,
103
+ rendered: `has-text-${value}${shadeSuffix}`,
104
+ },
105
+ // A doubled `color` is read last-wins, so the value above is the one
106
+ // that renders and the report is right. The FIX is not: renaming the
107
+ // winner leaves the loser behind as a dead `color`, which still
108
+ // resolves correctly through `textColor ?? color` and still wants
109
+ // deleting by hand. Same withholding `no-deprecated-props` does, for
110
+ // the same reason.
111
+ fix: doubledNames(opening).has('color')
112
+ ? null
113
+ : fixer => fixer.replaceText(color.name, 'textColor'),
62
114
  });
63
115
  },
64
116
  };
@@ -1 +1 @@
1
- {"version":3,"file":"no-deprecated-props.d.ts","sourceRoot":"","sources":["../../src/rules/no-deprecated-props.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAqBnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAoEhB,CAAC;AAEF,eAAe,IAAI,CAAC"}
1
+ {"version":3,"file":"no-deprecated-props.d.ts","sourceRoot":"","sources":["../../src/rules/no-deprecated-props.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAsCnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAoFhB,CAAC;AAEF,eAAe,IAAI,CAAC"}
@@ -1,5 +1,20 @@
1
1
  import { DEPRECATED_PROPS } from '../generated/metadata.js';
2
- import { attributesOf, elementOf, hasSpread, withImports, } from '../lib/elements.js';
2
+ import { doubledNames, winningAttributes, elementOf, hasSpread, withImports, } from '../lib/elements.js';
3
+ /**
4
+ * Renames whose fix is withheld because the two props do not share a value
5
+ * grammar, so swapping the name silently changes what renders.
6
+ *
7
+ * `icon` is the case: the library space-splits it and keeps only the LAST
8
+ * segment as the glyph ("Only its last segment is read", its own TSDoc says),
9
+ * while `name` is never split. So `icon="material-symbols-outlined home"`
10
+ * renders the `home` ligature and `name="material-symbols-outlined home"`
11
+ * renders that string as literal text. The deprecation is still reported; only
12
+ * the edit is left to a human.
13
+ *
14
+ * Declared rather than inferred: nothing in the generated note says whether
15
+ * two props read their value the same way.
16
+ */
17
+ const VALUE_GRAMMAR_DIFFERS = new Set(['icon']);
3
18
  /**
4
19
  * Own-property reads only. The keys come from the user's source, so a plain
5
20
  * `table[name]` resolves `Object.prototype` members: `<Icon valueOf="x" />`
@@ -39,17 +54,34 @@ const rule = {
39
54
  const deprecations = own(DEPRECATED_PROPS, element);
40
55
  if (!deprecations)
41
56
  return;
42
- const attrs = attributesOf(opening);
57
+ const attrs = winningAttributes(opening);
43
58
  const written = new Set(attrs.map((a) => a.name.name));
59
+ // Two deprecated props on one element can rename to the same target,
60
+ // and the library picks between them in a fixed order: Tabs resolves
61
+ // `isFullwidth ?? isFullWidth ?? fullwidth`. Renaming the one that
62
+ // happens to come first in the source promotes it past the one that
63
+ // was winning, so `<Tabs fullwidth isFullWidth={false} />` (not
64
+ // fullwidth) became `<Tabs isFullwidth isFullWidth={false} />`
65
+ // (fullwidth). Whichever way it is resolved, the author has to decide,
66
+ // so no fix is offered to any of them.
67
+ const contested = new Set();
68
+ const seen = new Set();
69
+ for (const a of attrs) {
70
+ const target = own(deprecations, a.name.name)?.replacement;
71
+ if (!target)
72
+ continue;
73
+ if (seen.has(target))
74
+ contested.add(target);
75
+ seen.add(target);
76
+ }
44
77
  // A spread can hold the replacement, and renaming onto it would let
45
78
  // the explicit attribute shadow a value the author meant to keep.
46
79
  // Report, but leave the edit to a human.
47
80
  const spread = hasSpread(opening);
48
- // Two deprecated props on one element can rename to the SAME target:
49
- // Tabs deprecates both `isFullWidth` and `fullwidth` in favour of
50
- // `isFullwidth`. Fixing both produced `<Tabs isFullwidth isFullwidth>`,
51
- // which is a duplicate JSX attribute and does not compile.
52
- const claimed = new Set();
81
+ // A name written twice is pathological, and fixing one occurrence
82
+ // leaves the other behind. `doubledNames` owns that; see its comment
83
+ // for the edit that made it necessary.
84
+ const doubled = doubledNames(opening);
53
85
  for (const attr of attrs) {
54
86
  const prop = attr.name.name;
55
87
  const info = own(deprecations, prop);
@@ -59,9 +91,9 @@ const rule = {
59
91
  const fixable = replacement !== null &&
60
92
  !spread &&
61
93
  !written.has(replacement) &&
62
- !claimed.has(replacement);
63
- if (fixable)
64
- claimed.add(replacement);
94
+ !contested.has(replacement) &&
95
+ !doubled.has(prop) &&
96
+ !VALUE_GRAMMAR_DIFFERS.has(prop);
65
97
  context.report({
66
98
  node: attr.name,
67
99
  messageId: 'deprecated',
@@ -1 +1 @@
1
- {"version":3,"file":"no-inert-flex-props.d.ts","sourceRoot":"","sources":["../../src/rules/no-inert-flex-props.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAiBnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAsDhB,CAAC;AAEF,eAAe,IAAI,CAAC"}
1
+ {"version":3,"file":"no-inert-flex-props.d.ts","sourceRoot":"","sources":["../../src/rules/no-inert-flex-props.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAkBnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAuDhB,CAAC;AAEF,eAAe,IAAI,CAAC"}
@@ -1,5 +1,5 @@
1
1
  import { DISPLAY_PROPS, FLEX_CONTAINER_PROPS, FLEX_DISPLAYS, } from '../lib/values.js';
2
- import { attributesOf, hasSpread, literalValue, elementOf, withImports, } from '../lib/elements.js';
2
+ import { isUnreadableValue, winningAttributes, hasSpread, literalValue, elementOf, withImports, } from '../lib/elements.js';
3
3
  const CONTAINER = new Set(FLEX_CONTAINER_PROPS);
4
4
  const DISPLAY = new Set(DISPLAY_PROPS);
5
5
  const rule = {
@@ -24,15 +24,17 @@ const rule = {
24
24
  return;
25
25
  if (hasSpread(opening))
26
26
  return;
27
- const attrs = attributesOf(opening);
27
+ const attrs = winningAttributes(opening);
28
28
  const containerProps = attrs.filter((a) => CONTAINER.has(a.name.name));
29
29
  if (!containerProps.length)
30
30
  return;
31
31
  const displays = attrs.filter((a) => DISPLAY.has(a.name.name));
32
- // An unreadable display value could be a flex one; say nothing.
33
- if (displays.some((a) => literalValue(a) === null)) {
32
+ // A display the rule cannot read could be a flex one; say nothing.
33
+ // Anything it CAN read and that is not a flex string — `true`, a
34
+ // number, `{false}` — is knowably not flex, so it must not buy the
35
+ // element silence. `isUnreadableValue` is the line between those.
36
+ if (displays.some(isUnreadableValue))
34
37
  return;
35
- }
36
38
  if (displays.some((a) => FLEX_DISPLAYS.includes(literalValue(a)))) {
37
39
  return;
38
40
  }
@@ -12,12 +12,23 @@
12
12
  * This rule earns its place where that check is not running:
13
13
  *
14
14
  * - JavaScript and JSX projects, which have no such check at all
15
- * - code in markdown and MDX, which no `tsc` program includes; every real
16
- * bug this rule has found so far was in a docs fence
17
15
  * - editors and CI stages that lint before, or instead of, typechecking
16
+ * - values `tsc` cannot see as literals, and numbers: `m={2}` typechecks
17
+ * against a string union in neither direction anyone expects, and the
18
+ * library's `includes` check never matches it
19
+ *
20
+ * Code in markdown is where this rule has found its real bugs in this repo,
21
+ * but reaching it needs an ESLint markdown processor and a per-fence way to
22
+ * resolve elements, since most fences carry no import. The preset does not
23
+ * match `.md`/`.mdx` and this rule claims nothing about them.
18
24
  *
19
25
  * It is deliberately not a substitute for typechecking, and the overlap on
20
26
  * `.tsx` is expected rather than a defect.
27
+ *
28
+ * The table is keyed by prop rather than by element, with one exception the
29
+ * rule has to know about: a name in it can mean something else entirely on a
30
+ * particular element, and then judging it reports working code.
31
+ * `NOT_A_HELPER_PROP` is that list, and `Theme`'s `radius` is why it exists.
21
32
  */
22
33
  import type { Rule } from 'eslint';
23
34
  declare const rule: Rule.RuleModule;
@@ -1 +1 @@
1
- {"version":3,"file":"valid-helper-value.d.ts","sourceRoot":"","sources":["../../src/rules/valid-helper-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AA2CnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UA+ChB,CAAC;AAEF,eAAe,IAAI,CAAC"}
1
+ {"version":3,"file":"valid-helper-value.d.ts","sourceRoot":"","sources":["../../src/rules/valid-helper-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAiDnC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAoGhB,CAAC;AAEF,eAAe,IAAI,CAAC"}
@@ -1,5 +1,5 @@
1
- import { HELPER_VALUES } from '../lib/values.js';
2
- import { attributesOf, literalValue, elementOf, withImports, } from '../lib/elements.js';
1
+ import { HELPER_VALUES, NOT_A_HELPER_PROP, REMOVES_ONLY, } from '../lib/values.js';
2
+ import { isTrueValue, literalValue, numericValue, elementOf, valuesThatRender, withImports, } from '../lib/elements.js';
3
3
  /**
4
4
  * Closest valid values by a cheap edit-distance, for the message.
5
5
  *
@@ -41,6 +41,10 @@ const rule = {
41
41
  messages: {
42
42
  invalid: '`{{prop}}="{{value}}"` is not a value {{prop}} accepts, so the class is never emitted and nothing renders. Valid values: {{valid}}.',
43
43
  invalidWithSuggestion: '`{{prop}}="{{value}}"` is not a value {{prop}} accepts, so the class is never emitted and nothing renders. Did you mean {{suggestions}}?',
44
+ numeric: '`{{prop}}={{{value}}}` is a number, and {{prop}} is matched against strings, so the class is never emitted and nothing renders. Write `{{prop}}="{{value}}"`.',
45
+ numericInvalid: '`{{prop}}={{{value}}}` is a number, and {{prop}} is matched against strings. `"{{value}}"` is not a value it accepts either. Valid values: {{valid}}.',
46
+ shorthand: '`{{prop}}` is `true` here, and {{prop}} is matched against strings, so the class is never emitted and nothing renders. Give it a value: {{valid}}.',
47
+ shorthandRemoves: '`{{prop}}` is `true` here, and {{prop}} is matched against strings, so nothing renders. It is also not a switch: its only value {{valid}} REMOVES the {{thing}}. Omit `{{prop}}` to keep the {{thing}}, or write `{{prop}}="{{only}}"` to remove it.',
44
48
  },
45
49
  },
46
50
  create(context) {
@@ -49,13 +53,59 @@ const rule = {
49
53
  ...visitor,
50
54
  JSXOpeningElement(node) {
51
55
  const opening = node;
52
- if (elementOf(context, opening, imports) === null)
56
+ const element = elementOf(context, opening, imports);
57
+ if (element === null)
53
58
  return;
54
- for (const attr of attributesOf(opening)) {
59
+ // A name in the table can mean something else on a particular
60
+ // element, in which case the table says nothing about it. `Theme`'s
61
+ // `radius` is the case; see NOT_A_HELPER_PROP.
62
+ const shadowed = NOT_A_HELPER_PROP.get(element);
63
+ for (const attr of valuesThatRender(opening)) {
55
64
  const prop = attr.name.name;
65
+ if (shadowed?.has(prop))
66
+ continue;
56
67
  const valid = HELPER_VALUES.get(prop);
57
68
  if (!valid)
58
69
  continue;
70
+ // `true`, bare or explicit, matches no tuple of strings. Same
71
+ // argument as the numeric case, one type further out.
72
+ if (isTrueValue(attr)) {
73
+ // `radius` and `shadow` are the props a shorthand is most natural
74
+ // on and most wrong on, because their one value removes rather
75
+ // than adds. The length check is what keeps "its only value" true
76
+ // rather than trusting the table to stay a single value.
77
+ const thing = REMOVES_ONLY.get(prop);
78
+ const removes = thing !== undefined && valid.length === 1;
79
+ context.report({
80
+ node: attr,
81
+ messageId: removes ? 'shorthandRemoves' : 'shorthand',
82
+ data: {
83
+ prop,
84
+ thing: thing ?? '',
85
+ only: valid[0] ?? '',
86
+ valid: valid.map(v => `\`${v}\``).join(', '),
87
+ },
88
+ });
89
+ continue;
90
+ }
91
+ // A number never matches a tuple of strings, so it renders nothing
92
+ // however plausible it looks. Worth its own message: the fix is the
93
+ // quotes, not the value.
94
+ const numeric = numericValue(attr);
95
+ if (numeric !== null) {
96
+ context.report({
97
+ node: attr,
98
+ messageId: valid.includes(String(numeric))
99
+ ? 'numeric'
100
+ : 'numericInvalid',
101
+ data: {
102
+ prop,
103
+ value: String(numeric),
104
+ valid: valid.map(v => `\`${v}\``).join(', '),
105
+ },
106
+ });
107
+ continue;
108
+ }
59
109
  const value = literalValue(attr);
60
110
  if (value === null || valid.includes(value))
61
111
  continue;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@allxsmith/eslint-plugin-bestax",
3
- "version": "0.0.0-development",
3
+ "version": "1.0.1",
4
4
  "description": "ESLint rules for @allxsmith/bestax-bulma — catches helper-prop values the library silently drops, deprecated props, and the color-as-surface mistake",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -41,7 +41,7 @@
41
41
  "url": "https://github.com/allxsmith/bestax/issues"
42
42
  },
43
43
  "dependencies": {
44
- "@allxsmith/bestax-bulma": "^5.15.2"
44
+ "@allxsmith/bestax-bulma": "^5.16.4"
45
45
  },
46
46
  "peerDependencies": {
47
47
  "eslint": "^10.0.0"
@@ -51,7 +51,6 @@
51
51
  "@types/jest": "^30.0.0",
52
52
  "@types/node": "^26.3.0",
53
53
  "@typescript-eslint/parser": "^8.68.0",
54
- "@typescript-eslint/types": "^8.68.0",
55
54
  "eslint": "^10.9.1",
56
55
  "jest": "^30.2.0",
57
56
  "ts-jest": "^29.4.12",
@@ -73,5 +72,5 @@
73
72
  "clean": "rimraf dist",
74
73
  "release": "npx semantic-release"
75
74
  },
76
- "readme": "# @allxsmith/eslint-plugin-bestax\n\n[![npm version](https://img.shields.io/npm/v/@allxsmith%2Feslint-plugin-bestax.svg)](https://www.npmjs.com/package/@allxsmith/eslint-plugin-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/@allxsmith%2Feslint-plugin-bestax.svg)](https://www.npmjs.com/package/@allxsmith/eslint-plugin-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://socket.dev/api/badge/npm/package/@allxsmith/eslint-plugin-bestax)](https://socket.dev/npm/package/@allxsmith/eslint-plugin-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/@allxsmith/eslint-plugin-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nESLint rules for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma).\n\nEvery rule here reports code that does not do what it looks like it does. The\nlibrary's helper props validate by membership and emit nothing for a value they\ndo not recognise, with no throw and no warning, so `textColor=\"blue\"` renders\nnothing and says nothing.\n\n**Scope, up front:** the helper props are typed as literal unions, so if you\nwrite bestax in `.tsx` and run `tsc`, it already catches a wrong literal. This\nplugin is for the places that check does not reach: JavaScript and JSX\nprojects, code in markdown and MDX, and lint stages that run before or instead\nof typechecking. The deprecation and flex rules are additive everywhere, since\nno type error marks a deprecated prop or a flex prop that emits nothing.\n\n## Requirements\n\nESLint 10, using [flat config](https://eslint.org/docs/latest/use/configure/configuration-files).\nThe plugin is ESM-only, so it cannot be `require()`d from a legacy\n`.eslintrc.js`.\n\n## Setup\n\n```bash\nnpm install --save-dev @allxsmith/eslint-plugin-bestax\n```\n\n```js\n// eslint.config.js\nimport bestax from '@allxsmith/eslint-plugin-bestax';\n\nexport default [bestax.configs.recommended];\n```\n\nThe preset matches `.js`, `.mjs`, `.cjs`, `.jsx` and `.tsx`, and enables JSX\nparsing. It sets no `parser`, so whatever you configure for TypeScript\nsurvives; put your TypeScript config first and this after:\n\n```js\nimport bestax from '@allxsmith/eslint-plugin-bestax';\nimport tseslint from 'typescript-eslint';\n\nexport default [...tseslint.configs.recommended, bestax.configs.recommended];\n```\n\nOr register it yourself and pick rules. `files` is load-bearing: a flat config\nobject without it inherits ESLint's default `**/*.{js,mjs,cjs}` set, so leaving\nit out silently lints none of your JSX.\n\n```js\nimport bestax from '@allxsmith/eslint-plugin-bestax';\n\nexport default [\n {\n files: ['**/*.{jsx,tsx}'],\n plugins: { '@allxsmith/bestax': bestax },\n languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },\n rules: {\n '@allxsmith/bestax/valid-helper-value': 'error',\n '@allxsmith/bestax/no-deprecated-props': 'warn',\n },\n },\n];\n```\n\n## Rules\n\nIn `recommended` — each reports code that does not do what it says:\n\n| Rule | Fixable | What it catches |\n| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `valid-helper-value` | — | Helper values the library silently drops: `textAlign=\"center\"` (it is `centered`), `textSize=\"8\"`, `mt=\"1rem\"` |\n| `no-deprecated-props` | yes | Props the library deprecated: `isFullWidth`, `gapSize*`, `icon`. Also the retired ones that emit a class no CSS matches |\n| `no-inert-flex-props` | — | `justifyContent` and friends without a flex `display`, which emit nothing |\n\nOpt-in — this one reports code that works, and buys explicitness instead:\n\n| Rule | Fixable | What it asks for |\n| --------------------- | ------- | ----------------------------------------------------------------------------- |\n| `no-color-as-surface` | yes | `textColor` instead of the `color` alias, where `color` cannot mean a surface |\n\nEach rule resolves elements through the import and through scope, so neither\nyour own `<Box>` nor a local shadowing the imported one is linted against\nBulma's rules, and each skips a value it cannot read as a literal.\n\nA spread is handled by what it can change: `no-color-as-surface` and\n`no-inert-flex-props` go silent, since a spread may carry the prop that makes\nthe code correct; `no-deprecated-props` reports but offers no fix; and\n`valid-helper-value` still reports, because an explicit attribute wins over a\nspread so a wrong literal is wrong regardless. No autofix changes what the code\nrenders.\n\n### valid-helper-value\n\n```jsx\n<Box textAlign=\"center\" /> // ✗ not a value textAlign accepts. Did you mean `centered`?\n<Box textAlign=\"centered\" /> // ✓\n```\n\nThe valid values come from the library's own exported tuples at lint time, by\nway of its `/constants` subpath, rather than from a list copied into this\npackage. The version those tuples come from is the copy of\n`@allxsmith/bestax-bulma` this plugin resolves, which in an ordinary deduped\ninstall is the same one your app uses; across a major bump it may not be, so\nkeep the two in step. Component-specific `color` props are deliberately not\nchecked, since `<Button color=\"ghost\">` is correct and reporting it would be\nworse than reporting nothing.\n\n### no-deprecated-props\n\n```jsx\n<Button isFullWidth /> // ✗ deprecated → fixes to isFullwidth\n<Tabs color=\"info\" /> // ✗ no .tabs.is-<color> CSS exists; no fix offered\n```\n\nThe table is generated from the library's own TSDoc, so a rename lands here\nwith the library rather than after someone notices.\n\n### no-color-as-surface\n\nOff by default. `color` on the content elements is a documented alias for\n`textColor`, so this rule is about saying which you meant, not about broken\ncode.\n\n```jsx\n<Box color=\"primary\" /> // ✗ ambiguous → fixes to textColor\n<Box bgColor=\"primary\" /> // ✓ a coloured surface\n<Button color=\"primary\" /> // ✓ Button really has an is-primary variant\n\n// ✓ silent: the background is explicit, so `color` is plainly the text half\n<Box backgroundColor=\"light\" color=\"dark\" />\n```\n\n### no-inert-flex-props\n\n```jsx\n<Box justifyContent=\"center\" /> // ✗ emits nothing\n<Box display=\"flex\" justifyContent=\"center\" /> // ✓\n<Box flexGrow=\"1\" /> // ✓ child props always apply\n```\n\n## Links\n\n- [Documentation](https://bestax.io/docs/guides/getting-started/eslint-plugin)\n- [Component library](https://www.npmjs.com/package/@allxsmith/bestax-bulma)\n- [Repository](https://github.com/allxsmith/bestax)\n\n## License\n\nMIT\n"
75
+ "readme": "# @allxsmith/eslint-plugin-bestax\n\n[![npm version](https://img.shields.io/npm/v/@allxsmith/eslint-plugin-bestax.svg)](https://www.npmjs.com/package/@allxsmith/eslint-plugin-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/@allxsmith/eslint-plugin-bestax.svg)](https://www.npmjs.com/package/@allxsmith/eslint-plugin-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://socket.dev/api/badge/npm/package/@allxsmith/eslint-plugin-bestax)](https://socket.dev/npm/package/@allxsmith/eslint-plugin-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nESLint rules for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma).\n\nEvery rule here reports code that does not do what it looks like it does. The\nlibrary's helper props validate by membership and emit nothing for a value they\ndo not recognise, with no throw and no warning, so `textColor=\"blue\"` renders\nnothing and says nothing.\n\n**Scope, up front:** the helper props are typed as literal unions, so if you\nwrite bestax in `.tsx` and run `tsc`, it already catches a wrong literal. This\nplugin is for the places that check does not reach: JavaScript and JSX\nprojects, and lint stages that run before or instead of typechecking. The deprecation and flex rules are additive everywhere, since\nno type error marks a deprecated prop or a flex prop that emits nothing.\n\n## Requirements\n\nESLint 10, using [flat config](https://eslint.org/docs/latest/use/configure/configuration-files).\nThe plugin is ESM-only, which does not rule out a CommonJS config. An\n`eslint.config.cjs` can `require()` it on a Node that supports `require(esm)`,\nand `configs.recommended` reads straight off the result with no interop hop,\nbecause `rules` and `configs` are named exports alongside the default. On a\nNode without that support it throws `ERR_REQUIRE_ESM`, and an `import` from\n`eslint.config.mjs` works either way.\n\n## Setup\n\n```bash\nnpm install --save-dev @allxsmith/eslint-plugin-bestax\n```\n\n### TypeScript\n\nThe preset sets no `parser`, so a TypeScript parser has to come from a config\nobject of your own. Put it first; the preset after:\n\n```js\n// eslint.config.js\nimport bestax from '@allxsmith/eslint-plugin-bestax';\nimport parser from '@typescript-eslint/parser';\n\nexport default [\n { files: ['**/*.{ts,tsx}'], languageOptions: { parser } },\n bestax.configs.recommended,\n];\n```\n\nAny TypeScript setup that sets a parser works the same way, `typescript-eslint`\nincluded, precisely because the preset does not set one of its own.\n\nThe parser is a requirement, not a nicety. The preset matches `.tsx` because\nthat is where a TypeScript project's JSX lives, and with no parser supplied it\nhands that file to the default one, which stops at the first type annotation:\n`Parsing error: The keyword 'interface' is reserved`.\n\n### JavaScript and JSX\n\nIf the project contains no `.tsx` at all, the preset alone is enough:\n\n```js\n// eslint.config.js\nimport bestax from '@allxsmith/eslint-plugin-bestax';\n\nexport default [bestax.configs.recommended];\n```\n\nAdd one `.tsx` file later and you need the parser block above. The failure is\nloud rather than silent, which is the intended trade: leaving `.tsx` out of the\npreset's own `files` would mean a TypeScript project got no rules on any `.tsx`\nfile and no indication why.\n\n### Picking rules yourself\n\n`files` is load-bearing: a flat config object without it inherits ESLint's\ndefault `**/*.{js,mjs,cjs}` set, so leaving it out silently lints none of your\nJSX.\n\n```js\nimport bestax from '@allxsmith/eslint-plugin-bestax';\n\nexport default [\n {\n files: ['**/*.{jsx,tsx}'],\n plugins: { '@allxsmith/bestax': bestax },\n languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },\n rules: {\n '@allxsmith/bestax/valid-helper-value': 'error',\n '@allxsmith/bestax/no-deprecated-props': 'warn',\n },\n },\n];\n```\n\n## Rules\n\nIn `recommended` — each reports code that does not do what it says:\n\n| Rule | Fixable | What it catches |\n| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `valid-helper-value` | — | Helper values the library silently drops: `textAlign=\"center\"` (it is `centered`), `textSize=\"8\"`, `mt=\"1rem\"` |\n| `no-deprecated-props` | partly | Props the library deprecated: `isFullWidth`, `gapSize*`, `icon`. Fixes only the renames that cannot change what renders |\n| `no-inert-flex-props` | — | `justifyContent` and friends without a flex `display`, which emit nothing |\n\nOpt-in — this one reports code that works, and buys explicitness instead:\n\n| Rule | Fixable | What it asks for |\n| --------------------- | ------- | ----------------------------------------------------------------------------- |\n| `no-color-as-surface` | yes | `textColor` instead of the `color` alias, where `color` cannot mean a surface |\n\nEach rule resolves elements through the import and through scope, so neither\nyour own `<Box>` nor a local shadowing the imported one is linted against\nBulma's rules, and each skips a value it cannot read as a literal.\n\nA spread is handled by what it can change: `no-color-as-surface` and\n`no-inert-flex-props` go silent, since a spread may carry the prop that makes\nthe code correct; `no-deprecated-props` reports but offers no fix; and\n`valid-helper-value` judges only the values that actually render, so a spread\nBEFORE the attribute leaves it reporting and a spread after it does not: JSX is\nlast-wins throughout, spreads included. No autofix changes what the code\nrenders.\n\n### valid-helper-value\n\n```jsx\n<Box textAlign=\"center\" /> // ✗ not a value textAlign accepts. Did you mean `centered`?\n<Box textAlign=\"centered\" /> // ✓\n```\n\nThe valid values come from the library's own exported tuples at lint time, by\nway of its `/constants` subpath, rather than from a list copied into this\npackage. The version those tuples come from is the copy of\n`@allxsmith/bestax-bulma` this plugin resolves, which in an ordinary deduped\ninstall is the same one your app uses; across a major bump it may not be, so\nkeep the two in step.\n\nOne family is outside its reach, knowingly: component-specific `color` props\nhave their own unions, so `<Button color=\"ghost\">` is correct and reporting it\nwould be worse than reporting nothing. And one element shadows a helper name:\n`Theme` takes a prop per Bulma CSS variable, so its `radius` sets\n`--bulma-radius` rather than emitting a class, while its type still says\notherwise. The rule skips that one pair until the library picks a meaning.\n\n### no-deprecated-props\n\n```jsx\n<Button isFullWidth /> // ✗ deprecated → fixes to isFullwidth\n<Tabs color=\"info\" /> // ✗ no .tabs.is-<color> CSS exists; no fix offered\n```\n\nThe table is generated from the library's own TSDoc, so a rename lands here\nwith the library rather than after someone notices.\n\n### no-color-as-surface\n\nOff by default. `color` on the content elements is a documented alias for\n`textColor`, so this rule is about saying which you meant, not about broken\ncode.\n\n```jsx\n<Box color=\"primary\" /> // ✗ ambiguous → fixes to textColor\n<Box bgColor=\"primary\" /> // ✓ a coloured surface\n<Button color=\"primary\" /> // ✓ Button really has an is-primary variant\n\n// ✓ silent: the background is explicit, so `color` is plainly the text half\n<Box bgColor=\"info\" color=\"primary\" />\n```\n\n### no-inert-flex-props\n\n```jsx\n<Box justifyContent=\"center\" /> // ✗ emits nothing\n<Box display=\"flex\" justifyContent=\"center\" /> // ✓\n<Box flexGrow=\"1\" /> // ✓ child props always apply\n```\n\n## Links\n\n- [Documentation](https://bestax.io/docs/guides/getting-started/eslint-plugin)\n- [Component library](https://www.npmjs.com/package/@allxsmith/bestax-bulma)\n- [Repository](https://github.com/allxsmith/bestax)\n\n## License\n\nMIT\n"
77
76
  }