@hublo/sentinel 1.5.0-alpha.8 → 1.5.0

package/plugins/hublo.js

@@ -1,156 +1,31 @@
 /**
  * Local oxlint plugin: Hublo house rules that have no equivalent anywhere else.
  *
- * oxlint has no `no-restricted-syntax`, so the eight AST selectors that used to live in
- * `restricted-syntax.cjs` cannot be carried across as configuration. They are expressed
- * here as a real rule instead, which is what oxlint's JS plugin API is for.
+ * It ships INSIDE sentinel rather than being copied into each module. A house rule is code, not
+ * configuration: a per-module copy drifts, and drifting house rules are the problem sentinel
+ * exists to remove. The cost is that `@hublo/sentinel` carries a rule about Hublo's colour
+ * palette, which is honest for a package named after the company.
  *
- * It ships INSIDE sentinel rather than being copied into each module. A house rule is code,
- * not configuration: a per-module copy drifts, and drifting house rules are the problem
- * sentinel exists to remove. The cost is that `@hublo/sentinel` carries a rule about Hublo's
- * colour palette, which is honest for a package named after the company.
+ * ⛔ One file per rule, assembled here, and this file holds NO rule logic. It was one 220-line
+ * object with three rules inside it, which is the shape that invites a fourth: the rules share
+ * nothing, each carries its own constants and its own reasoning, and a reader looking for one of
+ * them had to scroll past the other two. Composition is the point here rather than speed: this
+ * plugin has no dependencies and loads in about 1 ms, so there is no sonarjs-style cost to cut.
  *
- * It now hosts a SECOND, unrelated rule. `no-regex-lookbehind` is not a carried-over selector
- * but a browser-support rule: regex lookbehind is Safari 16.4+, and unlike everything else a
- * preset controls it can be neither transpiled nor polyfilled, because no bundler rewrites the
- * contents of a regex literal. It is here for the same reason as the palette rule — a house
- * rule is code, not configuration — and because lint is the only layer left that can catch it.
- *
- * The original selectors, and where each is handled below:
- *   1-2  MemberExpression[object.property.name='palette'][property.name='common']       theme.palette.common
- *        …[computed=true][property.value='common']                                      theme.palette['common']
- *   3-4  MemberExpression[object.name='palette']…                                        palette.common
- *   5-6  Property[key.name|key.value=/<colour props>/] > Literal[value=/^common\./]      { color: 'common.white' }
- *   7-8  JSXAttribute[name.name=/<colour props>/] > Literal | JSXExpressionContainer     color="common.white"
- */
-
-const MESSAGE =
-  'Do not use palette.common or common.* color paths in product code. Use semantic palette tokens instead.'
-
-/** The MUI props that take a colour path, so `common.*` in them is the same mistake. */
-const COLOUR_PROPS =
-  /^(color|bgcolor|background|backgroundColor|borderColor|borderTopColor|borderRightColor|borderBottomColor|borderLeftColor|outlineColor|fill|stroke|textDecorationColor|caretColor|accentColor)$/
-
-/**
- * Lookbehind, positive or negative. NOT named groups `(?<name>)`, which Safari has had since
- * 11.3: the class is exactly `(?<` followed by `=` or `!`.
+ * ⚠️ The build copies a role's whole `plugins/` DIRECTORY, so `plugins/hublo/` ships beside
+ * `plugins/hublo.js` and the relative imports below resolve the same way in this repository and
+ * in the published package. The generated preset still names `../plugins/hublo.js`, so nothing an
+ * adopted module extends has moved.
  */
-const LOOKBEHIND = /\(\?<[=!]/
-
-const LOOKBEHIND_MESSAGE =
-  'Regex lookbehind ((?<=) / (?<!)) is Safari 16.4+ and can be neither transpiled nor polyfilled: on older iOS the literal is a parse-time SyntaxError that takes the whole chunk with it. Rewrite the pattern. Named groups (?<name>) are fine.'
-
-/** `common.something` as a string value, e.g. `{ color: 'common.white' }`. */
-const isCommonPath = (node) =>
-  node?.type === 'Literal' && typeof node.value === 'string' && /^common\./.test(node.value)
+import { rule as noPaletteCommon } from './hublo/no-palette-common.js'
+import { rule as noRegexLookbehind } from './hublo/no-regex-lookbehind.js'
+import { rule as requireReloadDocument } from './hublo/require-reload-document.js'
 
-const plugin = {
+export default {
   meta: { name: 'hublo' },
   rules: {
-    'no-palette-common': {
-      meta: {
-        docs: {
-          description: 'Ban palette.common and common.* colour paths in product code.',
-        },
-      },
-      create(context) {
-        const report = (node) => context.report({ node, message: MESSAGE })
-
-        return {
-          // 1-4: reaching `common` off a palette, by property or by computed key.
-          MemberExpression(node) {
-            const onPalette =
-              node.object?.property?.name === 'palette' || node.object?.name === 'palette'
-            if (!onPalette) {
-              return
-            }
-            const reachesCommon =
-              node.property?.name === 'common' ||
-              (node.computed && node.property?.value === 'common')
-            if (reachesCommon) {
-              report(node)
-            }
-          },
-
-          // 5-6: `{ color: 'common.white' }` in an object literal, key written either way.
-          Property(node) {
-            const key = node.key?.name ?? node.key?.value
-            if (typeof key === 'string' && COLOUR_PROPS.test(key) && isCommonPath(node.value)) {
-              report(node.value)
-            }
-          },
-
-          // 7-8: `color="common.white"` and `color={'common.white'}` on a JSX element.
-          JSXAttribute(node) {
-            const name = node.name?.name
-            if (typeof name !== 'string' || !COLOUR_PROPS.test(name)) {
-              return
-            }
-            const value = node.value
-            if (isCommonPath(value)) {
-              return report(value)
-            }
-            if (value?.type === 'JSXExpressionContainer' && isCommonPath(value.expression)) {
-              report(value.expression)
-            }
-          },
-        }
-      },
-    },
-
-    'no-regex-lookbehind': {
-      meta: {
-        docs: {
-          description: 'Ban regex lookbehind, unsupported by Safari below 16.4.',
-        },
-      },
-      create(context) {
-        const report = (node) => context.report({ node, message: LOOKBEHIND_MESSAGE })
-
-        /**
-         * `new RegExp(...)` and `RegExp(...)`, when the pattern is readable statically: a
-         * string, or a template whose fixed parts carry the lookbehind.
-         *
-         * Each template chunk is tested on its own rather than joined. Joining invents a
-         * `(?<=` that the runtime string never has, across an interpolation boundary:
-         * `` `(?<${op}=x)` `` would read as one.
-         */
-        const isStaticLookbehind = (pattern) => {
-          if (pattern?.type === 'Literal') {
-            return typeof pattern.value === 'string' && LOOKBEHIND.test(pattern.value)
-          }
-          if (pattern?.type === 'TemplateLiteral') {
-            return (pattern.quasis ?? []).some((quasi) =>
-              LOOKBEHIND.test(quasi.value?.cooked ?? quasi.value?.raw ?? ''),
-            )
-          }
-          return false
-        }
-
-        const checkRegExpCall = (node) => {
-          if (node.callee?.name !== 'RegExp') {
-            return
-          }
-          const pattern = node.arguments?.[0]
-          if (isStaticLookbehind(pattern)) {
-            report(pattern)
-          }
-        }
-
-        return {
-          // The case that actually breaks a page: a literal is an EARLY error, so the whole
-          // chunk fails to parse rather than the one call site failing.
-          Literal(node) {
-            if (node.regex && LOOKBEHIND.test(node.regex.pattern)) {
-              report(node)
-            }
-          },
-          NewExpression: checkRegExpCall,
-          CallExpression: checkRegExpCall,
-        }
-      },
-    },
+    'no-palette-common': noPaletteCommon,
+    'no-regex-lookbehind': noRegexLookbehind,
+    'require-reload-document': requireReloadDocument,
   },
 }
-
-export default plugin

package/plugins/sonar-cognitive.js

@@ -0,0 +1,108 @@
+/**
+ * Cognitive complexity, measured by Sonar's own rule, loaded into oxlint.
+ *
+ * ⚠️ Source file. It is COPIED to `plugins/` at build time by `scripts/build-presets.ts`, which
+ * wipes that directory first: `plugins/` is git-ignored, so a file written straight into it lasts
+ * until the next build. Edit this one.
+ *
+ * ## Why a bridge and not an implementation
+ *
+ * Cognitive complexity is Campbell 2018, and its author works at SonarSource, so their
+ * implementation is not one reading of the specification among several: it is the specification's
+ * own house, with the language-specific decisions that come with it. The clearest of those is that
+ * `||` and `??` sequences do NOT increment in JavaScript and TypeScript, which looks like a defect
+ * against the generic paper and is deliberate: in this language those two operators are
+ * overwhelmingly default-value shorthand rather than control flow. SonarSource say so themselves,
+ * "we tried to adjust the cognitive complexity rule to accommodate common idioms", and made the
+ * exclusion universal in SonarQube 10.8 after it had been inconsistent between contexts.
+ *
+ * Measured here before it was believed, same file and same parser on both:
+ *
+ *   |                            | sonarjs 0.25.1 | sonarjs 4.2.2 |
+ *   | `if (a \|\| b \|\| c)`     |              2 |             1 |
+ *   | `if (a && b && c)`         |              2 |             2 |
+ *   | `const x = a \|\| b \|\| c`|              1 |             0 |
+ *
+ * ⛔ **The rule is USED, never copied.** `eslint-plugin-sonarjs` ships under the Sonar
+ * Source-Available License, whose grant is limited to a "Non-competitive Purpose", and sentinel is
+ * published under MIT. Depending on a package is not preparing a derivative work of it; copying its
+ * code into this repository would be, and would also mean granting rights we never received. So
+ * this file re-exposes their rule and contains none of their code.
+ *
+ * ## Why it works at all, which is not obvious
+ *
+ * This is an ESLint rule running inside oxlint. Measured before it was adopted:
+ *
+ *   |                                              | |
+ *   | the same values as ESLint, on `.js` and `.ts`| identical on every fixture, including the 7 of Campbell's own published example |
+ *   | on a real module, `contract`, 516 files      | 765 ms, exit 0, no error |
+ *   | `eslint` itself                              | NOT installed: pnpm leaves the peer unmet and oxlint provides the context |
+ *   | advisories the dependency adds               | 0 at every level, 94 packages |
+ *
+ * ⚠️ It does pull `typescript` as a hard dependency of the plugin, which nothing of ours imports.
+ */
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * ⛔ The deep path, and not the package name.
+ *
+ * `eslint-plugin-sonarjs` declares `main: ./cjs/plugin.js` and no `exports` map, so a bare ESM
+ * `import` of the package name fails to resolve under Node's ESM rules. Measured: it throws
+ * `ERR_MODULE_NOT_FOUND` before oxlint has read a single file, and oxlint reports it as
+ * "Failed to parse oxlint configuration file", which points at the wrong thing entirely.
+ */
+/*
+ * ## ⛔ The ONE rule, not the 295 the package ships
+ *
+ * `cjs/plugin.js` is the public door and it loads every rule to hand back one. Measured on this
+ * machine, cold, three runs each:
+ *
+ *     cjs/plugin.js          399 ms   295 rules   we use 1
+ *     cjs/S3776/index.js     159 ms     1 rule    the same object
+ *
+ * That difference is paid ONCE PER MODULE, because oxlint runs as a process per invocation. Over
+ * the whole repository, 441 modules, it is the difference between a sweep that is mostly loading
+ * rules nobody asked for and one that is not. The rule's own work is untouched: same `create`,
+ * same `meta.schema`, same figures.
+ *
+ * ⚠️ S3776 is Sonar's own identifier for cognitive complexity, and the package lays out ONE
+ * directory per rule, 295 of them. It also declares no `exports` field, so this path is reachable
+ * by the package's own layout rather than by accident.
+ *
+ * ⛔ It falls BACK rather than failing, and says so on stderr. A future version that moves the
+ * file must not cost the figure, and must not cost it silently either: a fallback nobody can see
+ * is how a 240 ms regression per module comes back unnoticed.
+ */
+function cognitiveRule() {
+  try {
+    const only = require('eslint-plugin-sonarjs/cjs/S3776/index.js')
+    const rule = only.rule ?? only.default?.rule
+    if (typeof rule?.create === 'function') return rule
+  } catch {
+    // falls through to the public door below
+  }
+
+  const sonarjs = require('eslint-plugin-sonarjs/cjs/plugin.js')
+  /** CJS interop: the plugin is reached either directly or behind `default`. */
+  const rule = (sonarjs.rules ?? sonarjs.default?.rules)?.['cognitive-complexity']
+  if (typeof rule?.create !== 'function') {
+    throw new Error(
+      'sentinel: eslint-plugin-sonarjs exposes `cognitive-complexity` from neither ' +
+        'cjs/S3776/index.js nor cjs/plugin.js. The cognitive complexity figure cannot be ' +
+        'produced; see this file.',
+    )
+  }
+  process.stderr.write(
+    'sentinel static-analysis: eslint-plugin-sonarjs no longer exposes cjs/S3776/index.js, so the ' +
+      'whole package was loaded for one rule. The figures are unchanged and the size pass is about ' +
+      '240 ms slower per module; see plugins/sonar-cognitive.js.\n',
+  )
+  return rule
+}
+
+export default {
+  meta: { name: 'sonar' },
+  rules: { 'cognitive-complexity': cognitiveRule() },
+}