homebridge-plugin-utils 1.35.0 → 2.0.0

package/build/eslint-plugin/plugin.mjs

@@ -0,0 +1,46 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * plugin.mjs: The `@hjdhjd` ESLint plugin object - meta block plus the rule registry.
+ */
+import packageJson from "../../package.json" with { type: "json" };
+import ruleBlankAfterOpenBrace from "./rules/blank-line-after-open-brace.mjs";
+import ruleCommentStyle from "./rules/comment-style.mjs";
+import ruleEnforceNodeProtocol from "./rules/enforce-node-protocol.mjs";
+import ruleParenComparisonsInLogical from "./rules/paren-comparisons-in-logical.mjs";
+import ruleSplitTypeImports from "./rules/split-type-imports.mjs";
+
+/**
+ * The `@hjdhjd` ESLint plugin object. Follows the standard ESLint plugin shape - a `meta` block identifying the plugin (used by ESLint's cache
+ * invalidation and tooling) plus a `rules` map keyed by the rule name that consumers reference under the `@hjdhjd/` namespace.
+ *
+ * Register the plugin in a flat config under the `plugins` property, then reference its rules by their fully qualified name:
+ *
+ * ```js
+ * import { plugin } from "homebridge-plugin-utils/eslint";
+ * export default [{
+ *   plugins: { "@hjdhjd": plugin },
+ *   rules: { "@hjdhjd/split-type-imports": "warn" }
+ * }];
+ * ```
+ *
+ * For a fully composed configuration that wires this plugin together with the project's TypeScript, JavaScript, and webUI rule presets, prefer the
+ * `config()` helper exported from `./config.mjs`.
+ */
+const plugin = {
+
+  meta: {
+
+    name: "@hjdhjd/eslint-rules",
+    version: packageJson.version
+  },
+  rules: {
+
+    "blank-line-after-open-brace": ruleBlankAfterOpenBrace,
+    "comment-style": ruleCommentStyle,
+    "enforce-node-protocol": ruleEnforceNodeProtocol,
+    "paren-comparisons-in-logical": ruleParenComparisonsInLogical,
+    "split-type-imports": ruleSplitTypeImports
+  }
+};
+
+export default plugin;

package/build/eslint-plugin/rules/blank-line-after-open-brace.mjs

@@ -0,0 +1,137 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * blank-line-after-open-brace.mjs: Require a blank line after an opening brace if it is immediately followed by a newline.
+ */
+
+// Find the open-brace token that needs a blank line inserted after it, or return null when the brace is canonical. The "canonical" form is one of:
+//  * the brace is closed on the same line (`{}` or `{ a }`), or
+//  * the brace is followed immediately by a blank line.
+// We do not flag braces that are followed by a blank line; we only flag braces followed by content on the very next line.
+function findBlankLineAfterOpenBrace(sourceCode, node) {
+
+  const openBrace = sourceCode.getFirstToken(node);
+  const nextToken = sourceCode.getTokenAfter(openBrace);
+
+  if(openBrace.loc.end.line >= nextToken.loc.start.line) {
+
+    return null;
+  }
+
+  const nextLine = sourceCode.lines[openBrace.loc.end.line];
+
+  if(nextLine.trim() === "") {
+
+    return null;
+  }
+
+  return openBrace;
+}
+
+// Require a blank line after an opening brace whenever the brace is followed by a newline and the next line carries non-whitespace content.
+//
+// Cases covered:
+//  * Block statements (`function`, `if`, `for`, etc.).
+//  * Class bodies.
+//  * Object expressions (including those nested as class-property initializers, which the `ObjectExpression` visitor reaches via ESLint's AST walk).
+//  * TypeScript interface bodies and embedded nested type literals.
+//  * TypeScript type alias declarations whose annotation is a type literal, and nested type literals therein.
+//
+// The autofix inserts a single `\n` immediately after the offending brace. Single-line braces (`{}` or `{ a }`) and braces already followed by a blank line
+// are both canonical and ignored. The rule reports against the brace token itself so editor markers pinpoint the brace rather than the wider statement.
+const ruleBlankAfterOpenBrace = {
+
+  create(context) {
+
+    const sourceCode = context.sourceCode;
+
+    function reportIfViolation(node) {
+
+      const openBrace = findBlankLineAfterOpenBrace(sourceCode, node);
+
+      if(openBrace === null) {
+
+        return;
+      }
+
+      context.report({
+
+        fix(fixer) {
+
+          return fixer.insertTextAfter(openBrace, "\n");
+        },
+        loc: openBrace.loc,
+        message: "Expected blank line after left brace and newline.",
+        node
+      });
+    }
+
+    return {
+
+      BlockStatement(node) {
+
+        reportIfViolation(node);
+      },
+
+      ClassBody(node) {
+
+        reportIfViolation(node);
+      },
+
+      // Nested object-expression property initializers inside class bodies are reached by the `ObjectExpression` visitor below, which ESLint dispatches
+      // automatically as it walks the AST. No manual recursion is needed here. (Compare with `TSInterfaceBody` and `TSTypeAliasDeclaration` below, which
+      // DO need manual recursion because `TSTypeLiteral` has no dedicated visitor in this rule.)
+      ObjectExpression(node) {
+
+        reportIfViolation(node);
+      },
+
+      TSInterfaceBody(node) {
+
+        reportIfViolation(node);
+
+        for(const property of node.body) {
+
+          if(!property.typeAnnotation || (property.type !== "TSPropertySignature") || (property.typeAnnotation.typeAnnotation.type !== "TSTypeLiteral")) {
+
+            continue;
+          }
+
+          reportIfViolation(property.typeAnnotation.typeAnnotation);
+        }
+      },
+
+      TSTypeAliasDeclaration(node) {
+
+        if(node.typeAnnotation.type !== "TSTypeLiteral") {
+
+          return;
+        }
+
+        reportIfViolation(node.typeAnnotation);
+
+        for(const member of node.typeAnnotation.members) {
+
+          if(!member.typeAnnotation || (member.type !== "TSPropertySignature") || (member.typeAnnotation.typeAnnotation.type !== "TSTypeLiteral")) {
+
+            continue;
+          }
+
+          reportIfViolation(member.typeAnnotation.typeAnnotation);
+        }
+      }
+    };
+  },
+  meta: {
+
+    docs: {
+
+      description: "require a blank line after an opening brace if it is immediately followed by a newline",
+      recommended: false
+    },
+    fixable: "whitespace",
+    schema: [],
+    type: "layout"
+  }
+};
+
+export default ruleBlankAfterOpenBrace;

package/build/eslint-plugin/rules/blank-line-after-open-brace.test.mjs

@@ -0,0 +1,112 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * blank-line-after-open-brace.test.mjs: Unit tests for the blank-line-after-open-brace rule covering each visitor (BlockStatement, ClassBody,
+ * ObjectExpression, TSInterfaceBody, TSTypeAliasDeclaration), the canonical single-line and already-padded forms that pass without flagging, and the
+ * nested TS type-literal recursion that drives the rule into the deeper levels of an interface or type-alias body.
+ */
+import { RuleTester } from "../test-setup.mjs";
+import rule from "./blank-line-after-open-brace.mjs";
+import ts from "typescript-eslint";
+
+// RuleTester wired to the typescript-eslint parser so the test suite can exercise TSInterfaceBody and TSTypeAliasDeclaration cases. The non-TS visitors
+// (BlockStatement, ClassBody, ObjectExpression) parse identically under either parser, so a single tester covers every case.
+const ruleTester = new RuleTester({
+
+  languageOptions: {
+
+    parser: ts.parser
+  }
+});
+
+ruleTester.run("blank-line-after-open-brace", rule, {
+
+  invalid: [
+
+    // BlockStatement followed immediately by content on the next line - autofix inserts a single newline after the opening brace.
+    {
+
+      code: "function foo() {\n  return 1;\n}",
+      errors: [{ message: /Expected blank line after left brace/ }],
+      output: "function foo() {\n\n  return 1;\n}"
+    },
+
+    // ClassBody case - same pattern. The class body's opening brace gets a blank line after it.
+    {
+
+      code: "class Foo {\n  bar() { return 1; }\n}",
+      errors: 1,
+      output: "class Foo {\n\n  bar() { return 1; }\n}"
+    },
+
+    // ObjectExpression case. Multi-line object literal whose first property is on the very next line.
+    {
+
+      code: "const x = {\n  a: 1,\n  b: 2\n};",
+      errors: 1,
+      output: "const x = {\n\n  a: 1,\n  b: 2\n};"
+    },
+
+    // ObjectExpression nested as a class-property initializer. The rule's header calls this case out specifically as covered via the `ObjectExpression`
+    // visitor's automatic AST walk. The outer class body is already padded so this test isolates the inner object's blank-line gap; only the inner brace
+    // fires.
+    {
+
+      code: "class Foo {\n\n  config = {\n    a: 1\n  };\n}",
+      errors: 1,
+      output: "class Foo {\n\n  config = {\n\n    a: 1\n  };\n}"
+    },
+
+    // TSInterfaceBody case. The opening `{` of the interface body needs the blank line.
+    {
+
+      code: "interface Foo {\n  bar: number;\n}",
+      errors: 1,
+      output: "interface Foo {\n\n  bar: number;\n}"
+    },
+
+    // TSTypeAliasDeclaration with a type literal annotation - the literal's opening `{` gets the blank line.
+    {
+
+      code: "type Foo = {\n  bar: number;\n};",
+      errors: 1,
+      output: "type Foo = {\n\n  bar: number;\n};"
+    },
+
+    // Nested type literal inside an interface property. The rule manually descends from TSInterfaceBody into TSTypeLiteral members (which have no
+    // dedicated visitor in this rule), so the inner brace is flagged independently of the outer interface brace.
+    {
+
+      code: "interface Foo {\n\n  bar: {\n    baz: number;\n  };\n}",
+      errors: 1,
+      output: "interface Foo {\n\n  bar: {\n\n    baz: number;\n  };\n}"
+    }
+  ],
+
+  valid: [
+
+    // Empty braces - canonical, no content to pad.
+    "function foo() {}",
+    "class Foo {}",
+    "const x = {};",
+    "interface Foo {}",
+    "type Foo = {};",
+
+    // Single-line braces with content - canonical, no newline after `{` so the rule doesn't engage.
+    "function foo() { return 1; }",
+    "const x = { a: 1 };",
+
+    // Multi-line braces with the canonical blank line already in place.
+    "function foo() {\n\n  return 1;\n}",
+    "class Foo {\n\n  bar() { return 1; }\n}",
+    "const x = {\n\n  a: 1\n};",
+    "interface Foo {\n\n  bar: number;\n}",
+    "type Foo = {\n\n  bar: number;\n};",
+
+    // Nested type literal already padded.
+    "interface Foo {\n\n  bar: {\n\n    baz: number;\n  };\n}",
+
+    // Type alias whose annotation is not a type literal - the rule's TSTypeAliasDeclaration visitor returns early.
+    "type Foo = number;",
+    "type Bar = string | number;"
+  ]
+});

package/build/eslint-plugin/rules/comment-style.mjs

@@ -0,0 +1,190 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * comment-style.mjs: Enforce ASCII-first comment style and disallow decorative banner separators.
+ */
+
+// The substitution table mapping Unicode glyphs to their canonical ASCII equivalents inside comments. Extend by adding a new entry; the substitution pass
+// reads this table once per character and emits the ASCII form in place.
+const COMMENT_ASCII_SUBSTITUTIONS = {
+
+  "±": "+/-",
+  "—": "-",
+  "←": "<-",
+  "→": "->",
+  "↔": "<->",
+  "≤": "<=",
+  "≥": ">="
+};
+
+// A line comment whose body is exclusively a four-or-more run of `=`, `-`, or `#` characters with optional surrounding whitespace. The leading `^\s*` and
+// trailing `\s*$` allow space padding (e.g., `// ====  `); the `\1{3,}` backreference forces the run to be a single repeated character.
+const COMMENT_DECORATIVE_BANNER_RE = /^\s*([=\-#])\1{3,}\s*$/;
+
+// Test whether a code point falls in the Unicode Box Drawing block (U+2500..U+257F, covering single-line, heavy, doubled, and rounded-corner forms in one
+// contiguous range so a single bounds check covers every variant).
+function isBoxDrawing(codePoint) {
+
+  return (codePoint >= 0x2500) && (codePoint <= 0x257F);
+}
+
+// Format a character's code point as a `U+XXXX` string for use in human-readable rule messages.
+function formatCodePoint(ch) {
+
+  return "U+" + ch.codePointAt(0).toString(16).toUpperCase().padStart(4, "0");
+}
+
+// Find the source range to remove for a decorative-banner-line violation, or null when the comment is not a removable banner. A removable banner is a
+// line comment (block comments use `=`/`-` runs as part of structured JSDoc syntax) whose body matches the banner regex and which is the only content on
+// its source line - banners that share a line with code are left to the contents pass so removing the line does not also delete the code.
+function findCommentBannerRange(sourceCode, comment) {
+
+  if(comment.type !== "Line") {
+
+    return null;
+  }
+
+  if(!COMMENT_DECORATIVE_BANNER_RE.test(comment.value)) {
+
+    return null;
+  }
+
+  const line = sourceCode.lines[comment.loc.start.line - 1];
+  const before = line.slice(0, comment.loc.start.column);
+
+  if(before.trim() !== "") {
+
+    return null;
+  }
+
+  const lineStart = sourceCode.getIndexFromLoc({ column: 0, line: comment.loc.start.line });
+  const nextLine = comment.loc.start.line + 1;
+  const lineEnd = (nextLine <= sourceCode.lines.length) ?
+    sourceCode.getIndexFromLoc({ column: 0, line: nextLine }) :
+    sourceCode.text.length;
+
+  return [ lineStart, lineEnd ];
+}
+
+// Analyze a comment's contents for substitutable Unicode glyphs and box-drawing characters. Returns null when the comment is clean; otherwise returns the
+// full replacement source text plus the rule message describing the first issue found. The pass walks by code point so any future supplementary-plane
+// character (e.g., emoji) is processed atomically rather than as two surrogates.
+function findCommentContentsViolation(comment) {
+
+  let transformed = "";
+  const issues = [];
+
+  for(const ch of comment.value) {
+
+    if(ch in COMMENT_ASCII_SUBSTITUTIONS) {
+
+      transformed += COMMENT_ASCII_SUBSTITUTIONS[ch];
+      issues.push({ char: ch, kind: "substitution" });
+
+      continue;
+    }
+
+    if(isBoxDrawing(ch.codePointAt(0))) {
+
+      issues.push({ char: ch, kind: "boxdrawing" });
+
+      continue;
+    }
+
+    transformed += ch;
+  }
+
+  if(issues.length === 0) {
+
+    return null;
+  }
+
+  const newSource = (comment.type === "Line") ? ("//" + transformed) : ("/*" + transformed + "*/");
+  const first = issues[0];
+  const message = (first.kind === "substitution") ?
+    ("Replace Unicode glyph `" + first.char + "` (" + formatCodePoint(first.char) + ") with ASCII `" + COMMENT_ASCII_SUBSTITUTIONS[first.char] +
+      "` in comments.") :
+    ("Remove box-drawing character `" + first.char + "` (" + formatCodePoint(first.char) + ") from comments.");
+
+  return { message, newSource };
+}
+
+// Enforce ASCII-first comment style. The rule visits every comment in a single `Program` walk and reports the following classes of drift.
+//
+// Cases covered:
+//  * Substitutable Unicode glyphs with direct ASCII equivalents - arrows (U+2192, U+2190, U+2194), comparison operators (U+2264, U+2265), plus-minus
+//    (U+00B1), and the em-dash (U+2014). Each is replaced in place via the substitution table.
+//  * Decorative banner separators - line comments whose body is exclusively a run of four or more `=`, `-`, or `#` characters. The entire offending
+//    source line is removed (including the trailing newline) so the section header collapses to the line above it.
+//  * Characters in the Unicode Box Drawing block (U+2500..U+257F, covering single-line, heavy, doubled, and rounded-corner forms). Stripped in place.
+//
+// Design decisions:
+//  * The walk is comment-scoped by construction (via `getAllComments`), so Unicode in string literals - e.g., a webUI label that legitimately renders
+//    an arrow - is never touched. The rule physically cannot reach a non-comment AST node.
+//  * Banner removal short-circuits the contents pass: within a single walk each comment is tested for a banner first, and a match removes the line and
+//    `continue`s, so banner-removal and substitution never both apply to the same comment in one pass. Across ESLint's multi-pass fixing an em-dash run can
+//    substitute to a hyphen run that a later pass then treats as a banner and removes; that convergence to a clean section break is benign.
+//  * Banners that share a line with code are left alone, since removing the line would delete the code too; such cases fall through to the contents pass,
+//    which doesn't match because banner runs aren't substitutable.
+const ruleCommentStyle = {
+
+  create(context) {
+
+    const sourceCode = context.sourceCode;
+
+    return {
+
+      Program() {
+
+        for(const comment of sourceCode.getAllComments()) {
+
+          const bannerRange = findCommentBannerRange(sourceCode, comment);
+
+          if(bannerRange !== null) {
+
+            context.report({
+
+              fix(fixer) {
+
+                return fixer.removeRange(bannerRange);
+              },
+              loc: comment.loc,
+              message: "Decorative banner separators are not allowed in comments. Use a plain section comment such as `// Section name.` instead."
+            });
+
+            continue;
+          }
+
+          const violation = findCommentContentsViolation(comment);
+
+          if(violation === null) {
+
+            continue;
+          }
+
+          context.report({
+
+            fix(fixer) {
+
+              return fixer.replaceTextRange(comment.range, violation.newSource);
+            },
+            loc: comment.loc,
+            message: violation.message
+          });
+        }
+      }
+    };
+  },
+  meta: {
+
+    docs: {
+
+      description: "enforce ASCII-first comment style and disallow decorative banner separators",
+      recommended: false
+    },
+    fixable: "code",
+    schema: [],
+    type: "suggestion"
+  }
+};
+
+export default ruleCommentStyle;

package/build/eslint-plugin/rules/comment-style.test.mjs

@@ -0,0 +1,190 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * comment-style.test.mjs: Unit tests for the comment-style rule covering its enforcement groups (Unicode-glyph substitution, em-dash substitution,
+ * decorative-banner-line removal, and box-drawing-character stripping) along with the negative cases that prove comment scoping works (string literals
+ * are never touched).
+ */
+import { RuleTester } from "../test-setup.mjs";
+import rule from "./comment-style.mjs";
+
+const ruleTester = new RuleTester();
+
+ruleTester.run("comment-style", rule, {
+
+  invalid: [
+
+    // Group A: each Unicode glyph is independently replaced with its ASCII equivalent in a line comment.
+    {
+
+      code: "// 0 → 1 transition",
+      errors: [{ message: /Replace Unicode glyph/ }],
+      output: "// 0 -> 1 transition"
+    },
+    {
+
+      code: "// arrow ← backwards",
+      errors: 1,
+      output: "// arrow <- backwards"
+    },
+    {
+
+      code: "// bidirectional ↔ link",
+      errors: 1,
+      output: "// bidirectional <-> link"
+    },
+    {
+
+      code: "// x ≤ 10",
+      errors: 1,
+      output: "// x <= 10"
+    },
+    {
+
+      code: "// x ≥ 10",
+      errors: 1,
+      output: "// x >= 10"
+    },
+    {
+
+      code: "// tolerance ± 5",
+      errors: 1,
+      output: "// tolerance +/- 5"
+    },
+
+    // Group B: em-dash replacement.
+    {
+
+      code: "// before — after",
+      errors: [{ message: /U\+2014/ }],
+      output: "// before - after"
+    },
+
+    // Group A inside block comments works the same way - the rule walks all comment types, not just line comments.
+    {
+
+      code: "/* foo → bar */",
+      errors: 1,
+      output: "/* foo -> bar */"
+    },
+    {
+
+      code: "/* range ≤ to ≥ */",
+      errors: 1,
+      output: "/* range <= to >= */"
+    },
+
+    // Multiple violations in a single comment collapse into one report with one fix...autofix produces the fully cleaned text in a single pass.
+    {
+
+      code: "// arrow → and check ≤ ok",
+      errors: 1,
+      output: "// arrow -> and check <= ok"
+    },
+
+    // Group C: decorative banner separators (=, -, # runs of four or more) on a line by themselves are removed entirely along with their trailing newline.
+    {
+
+      code: "// Section\n// ==========\nconst x = 1;\n",
+      errors: [{ message: /Decorative banner separator/ }],
+      output: "// Section\nconst x = 1;\n"
+    },
+    {
+
+      code: "// Section\n// ----------\nconst x = 1;\n",
+      errors: 1,
+      output: "// Section\nconst x = 1;\n"
+    },
+    {
+
+      code: "// Section\n// ##########\nconst x = 1;\n",
+      errors: 1,
+      output: "// Section\nconst x = 1;\n"
+    },
+
+    // Banner with leading whitespace is also removed - the indentation is part of the line we strip.
+    {
+
+      code: "function foo() {\n  // ============\n  return 1;\n}\n",
+      errors: 1,
+      output: "function foo() {\n  return 1;\n}\n"
+    },
+
+    // Banner on the final line of source (no trailing newline) is removed cleanly through end-of-file.
+    {
+
+      code: "const x = 1;\n// ==========",
+      errors: 1,
+      output: "const x = 1;\n"
+    },
+
+    // Group D: characters in the Box Drawing block (U+2500..U+257F) are stripped from comments.
+    {
+
+      code: "// border ─── done",
+      errors: [{ message: /box-drawing character/ }],
+      output: "// border  done"
+    },
+    {
+
+      code: "// pipe │ vertical",
+      errors: 1,
+      output: "// pipe  vertical"
+    },
+    {
+
+      code: "// double ═║ corner ╔",
+      errors: 1,
+      output: "// double  corner "
+    },
+
+    // Mixed substitution and box-drawing in the same comment...one report, one fix that handles both transformations.
+    {
+
+      code: "// arrow → box ─ done",
+      errors: 1,
+      output: "// arrow -> box  done"
+    },
+
+    // String literal is unaffected by the autofix; only the comment is cleaned. This is the proof that the rule is comment-scoped.
+    {
+
+      code: "const s = \"→\"; // arrow → string",
+      errors: 1,
+      output: "const s = \"→\"; // arrow -> string"
+    }
+  ],
+
+  valid: [
+
+    // Plain ASCII comments are unaffected.
+    "// This is a normal comment.",
+    "/* Block comment */",
+    "/* Multi\n * line\n * block */",
+
+    // Comments containing only ASCII punctuation including the same characters used in banners (but not as a full-line banner) are valid.
+    "// foo - bar",
+    "// 0 -> 1 transition",
+    "// x <= 10 and y >= 20",
+
+    // The banner regex requires the whole comment body to be a contiguous run, so a body with mixed content does not match.
+    "// === short label",
+
+    // Comments with banner-shaped text are allowed when they share a line with code...full-line removal would also delete the code, so we leave them be.
+    "const x = 1; // ====",
+
+    // Banner inside a block comment is not subject to the line-comment banner check.
+    "/* === */",
+
+    // Block comment using the structured `/* * */` continuation marker convention is fine - the asterisks are inside the body but not banner-shaped runs.
+    "/* Header.\n *\n * Body line.\n */",
+
+    // Unicode in string literals is never touched. The following cases are the load-bearing proof of the comment-only scope.
+    "const s = \"→\";",
+    "const s = \"—\";",
+    "const s = \"─\";",
+    "const arr = [ \"→\", \"≤\", \"≥\" ];",
+
+    // Em-dash inside a regular-expression literal is not a comment and is not flagged.
+    "const re = /—/;"
+  ]
+});