homebridge-plugin-utils 1.34.0 → 2.0.0

package/build/eslint-plugin/rules/enforce-node-protocol.mjs

@@ -0,0 +1,114 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * enforce-node-protocol.mjs: Require the `node:` protocol prefix on imports and re-exports of Node.js built-in modules.
+ */
+
+// The Node.js built-in modules that must be referenced via the `node:` protocol. Subpath imports (e.g., `timers/promises`) are matched by comparing the
+// top-level segment before the first `/`, so adding a new builtin here covers both bare and subpath references in one shot. This list is hand-maintained
+// rather than sourced from `node:module`'s `builtinModules` array so the rule's behavior stays fixed and version-independent across whatever Node runtime
+// ESLint happens to execute under, instead of silently drifting as builtins are added or removed between Node releases.
+const NODE_BUILTIN_MODULES = new Set([
+  "assert", "async_hooks", "buffer", "child_process", "cluster", "console", "crypto", "dgram", "diagnostics_channel", "dns", "domain", "events", "fs", "http", "http2",
+  "https", "inspector", "module", "net", "os", "path", "perf_hooks", "process", "punycode", "querystring", "readline", "repl", "stream", "string_decoder", "sys",
+  "timers", "tls", "trace_events", "tty", "url", "util", "v8", "vm", "wasi", "worker_threads", "zlib"
+]);
+
+// Find the source literal that should be rewritten with a `node:` prefix, or null when the reference is not a built-in or already correctly prefixed. We
+// look at the top-level module name (split on first `/`) so subpath references match too. For every supported visitor - Import / Export declarations
+// and `ImportExpression` (dynamic `import("x")`) - the typescript-eslint AST places the source literal at `node.source`. A null result means either the
+// value isn't a string (which also covers a declaration with no source clause at all, e.g. `export { foo };`, since `node.source` is then undefined) or
+// the module isn't a builtin.
+function findBuiltinSourceToPrefix(node, value) {
+
+  if(typeof value !== "string") {
+
+    return null;
+  }
+
+  const topLevel = value.split("/", 1)[0];
+
+  if(!NODE_BUILTIN_MODULES.has(topLevel)) {
+
+    return null;
+  }
+
+  return node.source ?? null;
+}
+
+// Require the `node:` protocol prefix on every reference to a Node.js built-in module.
+//
+// Cases covered:
+//  * `import x from "child_process"`            is flagged; autofix rewrites to `import x from "node:child_process"`.
+//  * `export { x } from "fs"`                   is flagged; autofix rewrites the source string.
+//  * `export * from "stream"`                   is flagged; same shape, same autofix.
+//  * `import("crypto")`                         dynamic-import call form, flagged when the argument is a string literal.
+//  * `import x from "node:child_process"`       canonical; ignored.
+//  * `import x from "lodash"`                   non-builtin; ignored.
+//  * `import x from "timers/promises"`          subpath of a builtin; flagged via the top-level-segment match.
+//
+// The reported location is the source string literal itself, so editor markers pinpoint the offending text. The autofix replaces the literal with a
+// double-quoted `node:`-prefixed form.
+const ruleEnforceNodeProtocol = {
+
+  create(context) {
+
+    function reportIfViolation(node, value) {
+
+      const source = findBuiltinSourceToPrefix(node, value);
+
+      if(source === null) {
+
+        return;
+      }
+
+      context.report({
+
+        fix(fixer) {
+
+          return fixer.replaceText(source, "\"node:" + value + "\"");
+        },
+        message: "Use the `node:` protocol prefix when importing Node.js built-in modules.",
+        node: source
+      });
+    }
+
+    return {
+
+      ExportAllDeclaration(node) {
+
+        reportIfViolation(node, node.source?.value);
+      },
+
+      ExportNamedDeclaration(node) {
+
+        reportIfViolation(node, node.source?.value);
+      },
+
+      ImportDeclaration(node) {
+
+        reportIfViolation(node, node.source.value);
+      },
+
+      ImportExpression(node) {
+
+        if(node.source.type === "Literal") {
+
+          reportIfViolation(node, node.source.value);
+        }
+      }
+    };
+  },
+  meta: {
+
+    docs: {
+
+      description: "require the `node:` protocol prefix on imports and re-exports of Node.js built-in modules",
+      recommended: false
+    },
+    fixable: "code",
+    schema: [],
+    type: "problem"
+  }
+};
+
+export default ruleEnforceNodeProtocol;

package/build/eslint-plugin/rules/enforce-node-protocol.test.mjs

@@ -0,0 +1,116 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * enforce-node-protocol.test.mjs: Unit tests for the enforce-node-protocol rule covering each visitor (ImportDeclaration, ExportNamedDeclaration,
+ * ExportAllDeclaration, ImportExpression), the subpath-import case where the rule matches by the top-level segment, and the negative cases that prove
+ * already-prefixed and non-builtin references pass without flagging.
+ */
+import { RuleTester } from "../test-setup.mjs";
+import rule from "./enforce-node-protocol.mjs";
+
+const ruleTester = new RuleTester();
+
+ruleTester.run("enforce-node-protocol", rule, {
+
+  invalid: [
+
+    // ImportDeclaration - bare builtin name, autofix prepends `node:`.
+    {
+
+      code: "import x from \"child_process\";",
+      errors: [{ message: /Use the `node:` protocol prefix/ }],
+      output: "import x from \"node:child_process\";"
+    },
+
+    // Named-import form of ImportDeclaration.
+    {
+
+      code: "import { spawn } from \"child_process\";",
+      errors: 1,
+      output: "import { spawn } from \"node:child_process\";"
+    },
+
+    // Namespace-import form of ImportDeclaration. The rule's `ImportDeclaration` visitor dispatches on `node.source.value` regardless of specifier
+    // shape, so namespace imports flag the same way as default and named imports do.
+    {
+
+      code: "import * as cp from \"child_process\";",
+      errors: 1,
+      output: "import * as cp from \"node:child_process\";"
+    },
+
+    // ExportNamedDeclaration with a source clause - the source string gets prefixed.
+    {
+
+      code: "export { foo } from \"fs\";",
+      errors: 1,
+      output: "export { foo } from \"node:fs\";"
+    },
+
+    // ExportAllDeclaration - same shape, same autofix.
+    {
+
+      code: "export * from \"stream\";",
+      errors: 1,
+      output: "export * from \"node:stream\";"
+    },
+
+    // Re-export with an alias clause - the autofix targets only the source literal, not the named clause.
+    {
+
+      code: "export * as nodeStream from \"stream\";",
+      errors: 1,
+      output: "export * as nodeStream from \"node:stream\";"
+    },
+
+    // ImportExpression (dynamic import) with a string-literal argument. The rule's ImportExpression visitor guards on `node.source.type === "Literal"`
+    // before reporting, so this case fires; the dynamic-with-variable case in the valid list does not.
+    {
+
+      code: "const m = import(\"crypto\");",
+      errors: 1,
+      output: "const m = import(\"node:crypto\");"
+    },
+
+    // Subpath import of a builtin (`timers/promises`). The top-level segment matches the `NODE_BUILTIN_MODULES` Set, so the rule fires and the autofix
+    // prefixes the whole specifier including the subpath.
+    {
+
+      code: "import { setTimeout } from \"timers/promises\";",
+      errors: 1,
+      output: "import { setTimeout } from \"node:timers/promises\";"
+    },
+
+    // Subpath via a re-export.
+    {
+
+      code: "export { setImmediate } from \"timers/promises\";",
+      errors: 1,
+      output: "export { setImmediate } from \"node:timers/promises\";"
+    }
+  ],
+
+  valid: [
+
+    // Already-prefixed builtins - canonical, no rewrite.
+    "import x from \"node:child_process\";",
+    "import { spawn } from \"node:child_process\";",
+    "export { foo } from \"node:fs\";",
+    "export * from \"node:stream\";",
+    "const m = import(\"node:crypto\");",
+    "import { setTimeout } from \"node:timers/promises\";",
+
+    // Non-builtin packages - the rule's `NODE_BUILTIN_MODULES` Set does not contain them, so they pass through.
+    "import x from \"lodash\";",
+    "import { foo } from \"./local-module.mjs\";",
+    "import { bar } from \"@scope/package\";",
+    "export { baz } from \"my-package\";",
+
+    // Local re-export with no source clause - `ExportNamedDeclaration.source` is null, the rule's `findBuiltinSourceToPrefix` short-circuits via the
+    // `typeof value !== \"string\"` guard.
+    "const foo = 1; export { foo };",
+
+    // Dynamic import with a non-literal argument - the ImportExpression visitor's `node.source.type === \"Literal\"` guard skips this case so the rule
+    // does not fire on runtime-computed module specifiers.
+    "const name = \"crypto\"; const m = import(name);"
+  ]
+});

package/build/eslint-plugin/rules/paren-comparisons-in-logical.mjs

@@ -0,0 +1,94 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * paren-comparisons-in-logical.mjs: Require parentheses around comparison operands when used inside compound logical expressions.
+ */
+
+// The set of comparison operators whose operands must be parenthesized when nested inside a compound logical expression.
+const COMPARISON_OPERATORS = new Set([ "!=", "!==", "<", "<=", "==", "===", ">", ">=", "in", "instanceof" ]);
+
+// The set of compound logical operators that trigger the parenthesization requirement on their direct comparison operands.
+const LOGICAL_OPERATORS = new Set([ "&&", "||" ]);
+
+// Test whether a node is a comparison binary expression with one of the recognized operators.
+function isComparison(node) {
+
+  return !!node && (node.type === "BinaryExpression") && COMPARISON_OPERATORS.has(node.operator);
+}
+
+// Test whether a node is already parenthesized in source. Duck-types a sourceCode.isParenthesized method for environments that may expose one,
+// falling back to inspecting the tokens immediately surrounding the node when it is absent.
+function isParenthesized(sourceCode, node) {
+
+  if(typeof sourceCode.isParenthesized === "function") {
+
+    return sourceCode.isParenthesized(node);
+  }
+
+  const before = sourceCode.getTokenBefore(node);
+  const after = sourceCode.getTokenAfter(node);
+
+  return !!before && !!after && (before.value === "(") && (after.value === ")");
+}
+
+// Require parentheses around any comparison operand that is a direct child of a compound logical expression.
+//
+// Cases covered:
+//  * `a === b && c === d`               both operands are flagged independently; autofix produces `(a === b) && (c === d)`.
+//  * `(a === b) && (c === d)`           is canonical; ignored.
+//  * `a && b && c`                       has no comparison operands and is ignored.
+//  * `(a && b) === (c && d)`             is a comparison containing logicals (not a logical containing comparisons); ignored at this level.
+//
+// The rule only inspects direct operands of `&&` and `||`. Deeper nested comparisons are reached because ESLint dispatches the `LogicalExpression` visitor on each
+// nested logical node as it traverses the already-built AST.
+const ruleParenComparisonsInLogical = {
+
+  create(context) {
+
+    const sourceCode = context.sourceCode;
+
+    function reportIfViolation(node) {
+
+      if(!isComparison(node) || isParenthesized(sourceCode, node)) {
+
+        return;
+      }
+
+      context.report({
+
+        fix(fixer) {
+
+          return fixer.replaceText(node, "(" + sourceCode.getText(node) + ")");
+        },
+        message: "Wrap comparison operands in parentheses inside compound logical expressions (&&, ||).",
+        node
+      });
+    }
+
+    return {
+
+      LogicalExpression(node) {
+
+        if(!LOGICAL_OPERATORS.has(node.operator)) {
+
+          return;
+        }
+
+        reportIfViolation(node.left);
+        reportIfViolation(node.right);
+      }
+    };
+  },
+  meta: {
+
+    docs: {
+
+      description: "require parentheses around comparison operands when used inside compound logical expressions (&&, ||)",
+      recommended: false
+    },
+    fixable: "code",
+    schema: [],
+    type: "layout"
+  }
+};
+
+export default ruleParenComparisonsInLogical;

package/build/eslint-plugin/rules/paren-comparisons-in-logical.test.mjs

@@ -0,0 +1,107 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * paren-comparisons-in-logical.test.mjs: Unit tests for the paren-comparisons-in-logical rule covering each comparison operator on either side of a
+ * compound logical expression, the partial-wrap case where only one operand is a comparison, and the negative passthrough cases that prove already-
+ * parenthesized comparisons and non-comparison operands are correctly ignored.
+ */
+import { RuleTester } from "../test-setup.mjs";
+import rule from "./paren-comparisons-in-logical.mjs";
+
+const ruleTester = new RuleTester();
+
+ruleTester.run("paren-comparisons-in-logical", rule, {
+
+  invalid: [
+
+    // Equality comparisons on both operands of `&&` - both sides wrap.
+    {
+
+      code: "const r = a === b && c === d;",
+      errors: [ { message: /Wrap comparison operands in parentheses/ }, { message: /Wrap comparison operands in parentheses/ } ],
+      output: "const r = (a === b) && (c === d);"
+    },
+
+    // Inequality comparisons on both operands of `||`.
+    {
+
+      code: "const r = a !== b || c !== d;",
+      errors: 2,
+      output: "const r = (a !== b) || (c !== d);"
+    },
+
+    // Relational comparisons (`<`, `<=`, `>`, `>=`) and loose equality (`==`, `!=`) all wrap when used as direct operands of a logical expression.
+    {
+
+      code: "const r = x < 10 || y > 20;",
+      errors: 2,
+      output: "const r = (x < 10) || (y > 20);"
+    },
+    {
+
+      code: "const r = x <= 10 && y >= 20;",
+      errors: 2,
+      output: "const r = (x <= 10) && (y >= 20);"
+    },
+    {
+
+      code: "const r = x == null || y != 0;",
+      errors: 2,
+      output: "const r = (x == null) || (y != 0);"
+    },
+
+    // `in` and `instanceof` are recognized as comparison operators by the rule and wrap when used as logical operands.
+    {
+
+      code: "const r = key in obj && key !== \"reserved\";",
+      errors: 2,
+      output: "const r = (key in obj) && (key !== \"reserved\");"
+    },
+    {
+
+      code: "const r = x instanceof Foo || y instanceof Bar;",
+      errors: 2,
+      output: "const r = (x instanceof Foo) || (y instanceof Bar);"
+    },
+
+    // Asymmetric case - only the left operand is a comparison. Only that side wraps; the non-comparison right operand stays as-is.
+    {
+
+      code: "const r = a === b && ready;",
+      errors: 1,
+      output: "const r = (a === b) && ready;"
+    },
+
+    // Asymmetric case - only the right operand is a comparison.
+    {
+
+      code: "const r = ready && a === b;",
+      errors: 1,
+      output: "const r = ready && (a === b);"
+    }
+  ],
+
+  valid: [
+
+    // Already-parenthesized comparisons - canonical, no rewrite.
+    "const r = (a === b) && (c === d);",
+    "const r = (x < 10) || (y > 20);",
+
+    // Logical expressions whose operands are not comparisons - the rule has nothing to wrap.
+    "const r = a && b;",
+    "const r = a && b && c;",
+    "const r = a || b;",
+    "const r = ready && configured;",
+
+    // Comparison without a surrounding logical - the rule only flags direct operands of `&&` / `||`, so a bare comparison is ignored.
+    "const r = a === b;",
+    "const r = x < 10;",
+
+    // Comparison containing logicals (not a logical containing comparisons). The top-level binary expression is `===` - the rule only inspects operands
+    // when the parent is `&&` / `||`, so this configuration is ignored at the top level.
+    "const r = (a && b) === (c && d);",
+
+    // Non-comparison binary expressions (arithmetic) as logical operands - not in the comparison-operator set, no wrap.
+    "const r = (a + b) && (c - d);",
+    "const r = a + b && c - d;"
+  ]
+});