chore(sync): cascade conditional-files gate + sort-equality-disjunctions rule from socket-repo-template

jdalton · jdalton · commit fcffd44e264a · 2026-05-09T19:17:59.000-04:00
diff --git a/.config/oxlint-plugin/index.js b/.config/oxlint-plugin/index.js
@@ -31,6 +31,7 @@ import preferNodeBuiltinImports from './rules/prefer-node-builtin-imports.js'
 import preferSafeDelete from './rules/prefer-safe-delete.js'
 import preferUndefinedOverNull from './rules/prefer-undefined-over-null.js'
 import socketApiTokenEnv from './rules/socket-api-token-env.js'
+import sortEqualityDisjunctions from './rules/sort-equality-disjunctions.js'
 import sortNamedImports from './rules/sort-named-imports.js'
 import sortRegexAlternations from './rules/sort-regex-alternations.js'
 import sortSetArgs from './rules/sort-set-args.js'
@@ -61,6 +62,7 @@ const plugin = {
     'prefer-safe-delete': preferSafeDelete,
     'prefer-undefined-over-null': preferUndefinedOverNull,
     'socket-api-token-env': socketApiTokenEnv,
+    'sort-equality-disjunctions': sortEqualityDisjunctions,
     'sort-named-imports': sortNamedImports,
     'sort-regex-alternations': sortRegexAlternations,
     'sort-set-args': sortSetArgs,
diff --git a/.config/oxlint-plugin/rules/sort-equality-disjunctions.js b/.config/oxlint-plugin/rules/sort-equality-disjunctions.js
@@ -0,0 +1,250 @@
+/**
+ * @fileoverview Sort string-equality disjunctions alphanumerically.
+ *
+ * Per CLAUDE.md "Sorting" rule, `x === 'a' || x === 'b' || x === 'c'`
+ * is sorted by the comparand string (literal byte order, ASCII before
+ * letters). Order doesn't affect runtime semantics — JS's `||`
+ * short-circuits regardless of operand order — but keeps the diff
+ * churn low when adding a new comparand and makes "is X in this set?"
+ * checks visually consistent across the fleet.
+ *
+ * Detects:
+ *   - `(x === 'a' || x === 'b')`
+ *   - `(x !== 'a' && x !== 'b')` — De Morgan dual; ordering rule applies
+ *   - Chains of any length (≥2 operands).
+ *
+ * Each disjunction must:
+ *   - Use the SAME left operand (`x` in the example) for every clause.
+ *   - Use the SAME comparison operator (`===` for `||` chains, `!==`
+ *     for `&&` chains).
+ *   - Use string-literal right operands (number / boolean / template
+ *     literals are skipped — those rarely benefit from alpha order
+ *     and confuse the autofix).
+ *
+ * Autofix: rewrites the right-hand string literals in sorted order.
+ * Skipped (reports without fix) when:
+ *   - Any clause's left operand differs (mixed identifier).
+ *   - Any clause's right operand isn't a plain string literal.
+ *   - Any clause uses a different operator from the first.
+ *   - Comments live between clauses (reordering through a comment
+ *     would break attribution).
+ *
+ * Why a separate rule from sort-named-imports / sort-set-args:
+ *   - The shape is structurally different (BinaryExpression chain
+ *     under LogicalExpression, not an ArrayExpression / ImportSpecifier).
+ *   - Catches the most common "is this one of these constants?"
+ *     pattern in dispatch code (e.g. switch-prelude guards,
+ *     fix-action category checks). A single rule keeps this normalized.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Sort string-equality disjunctions alphanumerically (`x === "a" || x === "b"`).',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      unsorted:
+        'String-equality disjunction operands are out of alphabetical order. Saw `{{actual}}`, expected `{{expected}}`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    /**
+     * Flatten a left-associative LogicalExpression chain into a list
+     * of leaf nodes. `(a || b) || c` and `a || (b || c)` both flatten
+     * to [a, b, c]. We require the chain operator to be uniform
+     * (caller checks).
+     */
+    function flatten(node, op, out) {
+      if (node.type === 'LogicalExpression' && node.operator === op) {
+        flatten(node.left, op, out)
+        flatten(node.right, op, out)
+      } else {
+        out.push(node)
+      }
+    }
+
+    /**
+     * For a binary-equality leaf, return `{ left, right, operator }`
+     * if it's the shape we sort. Returns undefined otherwise.
+     */
+    function asEqualityClause(node) {
+      if (node.type !== 'BinaryExpression') {
+        return undefined
+      }
+      if (node.operator !== '===' && node.operator !== '!==') {
+        return undefined
+      }
+      // Right side must be a plain string-literal Identifier-comparand pattern.
+      if (
+        node.right.type !== 'Literal' ||
+        typeof node.right.value !== 'string'
+      ) {
+        return undefined
+      }
+      // Left side: prefer Identifier, but accept MemberExpression so
+      // `cat.x === 'a' || cat.x === 'b'` works too.
+      if (
+        node.left.type !== 'Identifier' &&
+        node.left.type !== 'MemberExpression'
+      ) {
+        return undefined
+      }
+      return {
+        leftText: sourceCode.getText(node.left),
+        operator: node.operator,
+        right: node.right,
+        rightValue: node.right.value,
+      }
+    }
+
+    /**
+     * Returns true if a comment lies anywhere between the first and
+     * last leaf of the chain. Comment-aware skipping prevents the
+     * autofix from silently relocating attribution.
+     */
+    function hasInteriorComment(leaves) {
+      if (!sourceCode.getCommentsInside) {
+        return false
+      }
+      const first = leaves[0]
+      const last = leaves[leaves.length - 1]
+      const all = sourceCode.getCommentsInside({
+        range: [first.range[0], last.range[1]],
+        loc: { start: first.loc.start, end: last.loc.end },
+        type: 'Program',
+      })
+      return all.length > 0
+    }
+
+    function checkChain(rootNode) {
+      // Top-level filter: only check the OUTERMOST `||` or `&&` of a
+      // chain, not its sub-expressions. We detect "outermost" by the
+      // parent being either non-LogicalExpression or a different
+      // operator.
+      const parent = rootNode.parent
+      if (
+        parent &&
+        parent.type === 'LogicalExpression' &&
+        parent.operator === rootNode.operator
+      ) {
+        return
+      }
+
+      const op = rootNode.operator
+      // We only process || and && chains.
+      if (op !== '||' && op !== '&&') {
+        return
+      }
+
+      const leaves = []
+      flatten(rootNode, op, leaves)
+      if (leaves.length < 2) {
+        return
+      }
+
+      const clauses = []
+      for (const leaf of leaves) {
+        const c = asEqualityClause(leaf)
+        if (!c) {
+          // Mixed shape — skip the whole chain. The rule only
+          // applies to homogeneous equality chains.
+          return
+        }
+        clauses.push(c)
+      }
+
+      // Operator/leftText must be uniform within the chain. For `||`
+      // chains the natural shape is `===`; for `&&` chains it's `!==`
+      // (De Morgan). Mixed → skip (rare and the rewrite would change
+      // semantics).
+      const firstLeft = clauses[0].leftText
+      const firstOp = clauses[0].operator
+      for (let i = 1; i < clauses.length; i++) {
+        if (
+          clauses[i].leftText !== firstLeft ||
+          clauses[i].operator !== firstOp
+        ) {
+          return
+        }
+      }
+
+      // For `||` chains, expect `===`. For `&&` chains, expect `!==`.
+      // Other combinations are valid logic but not the shape this rule
+      // sorts (they'd be tautologies or contradictions).
+      if (op === '||' && firstOp !== '===') {
+        return
+      }
+      if (op === '&&' && firstOp !== '!==') {
+        return
+      }
+
+      // Compute the sorted order.
+      const sortedClauses = [...clauses].sort((a, b) => {
+        if (a.rightValue < b.rightValue) {
+          return -1
+        }
+        if (a.rightValue > b.rightValue) {
+          return 1
+        }
+        return 0
+      })
+
+      const actualOrder = clauses.map(c => c.rightValue).join(', ')
+      const expectedOrder = sortedClauses.map(c => c.rightValue).join(', ')
+
+      if (actualOrder === expectedOrder) {
+        return
+      }
+
+      // Check for interior comments — skip autofix if any.
+      if (hasInteriorComment(leaves)) {
+        context.report({
+          node: rootNode,
+          messageId: 'unsorted',
+          data: { actual: actualOrder, expected: expectedOrder },
+        })
+        return
+      }
+
+      context.report({
+        node: rootNode,
+        messageId: 'unsorted',
+        data: { actual: actualOrder, expected: expectedOrder },
+        fix(fixer) {
+          // Replace each leaf's right-string-literal with the
+          // sorted-position counterpart. Because the chain is
+          // homogeneous (same left, same op), the rewrite is safe
+          // semantically — only the comparand strings reorder.
+          const fixes = []
+          for (let i = 0; i < leaves.length; i++) {
+            const leaf = leaves[i]
+            const targetRight = sortedClauses[i].right
+            // The leaf's right node is what we rewrite.
+            // BinaryExpression.right's range covers just the literal.
+            const rawTarget = sourceCode.getText(targetRight)
+            fixes.push(fixer.replaceText(asEqualityClause(leaf).right, rawTarget))
+          }
+          return fixes
+        },
+      })
+    }
+
+    return {
+      LogicalExpression: checkChain,
+    }
+  },
+}
+
+export default rule
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -209,7 +209,7 @@ Never silently let drift sit. Either reconcile in the same PR or open a follow-u
 - **Edits** — Edit tool, never `sed` / `awk`.
 - **Generated reports** — quality scans, security audits, perf snapshots, anything an automated tool emits — write to `.claude/reports/` (naturally gitignored as part of `.claude/*`, no separate rule needed). Never commit reports to a tracked `reports/`, `docs/reports/`, or similarly-named tracked directory: dated reports rot the moment they land and the directory becomes a graveyard. The current state of the repo is the report; tools regenerate findings on demand. If a finding is genuinely worth keeping past one run, fix it or open an issue — don't pickle it as a markdown file.
 - **Inclusive language** — see [`docs/claude.md/inclusive-language.md`](docs/claude.md/inclusive-language.md) for the substitution table.
-- **Sorting** — sort alphanumerically (literal byte order, ASCII before letters). Applies to: object property keys (config + return shapes + internal state — `__proto__: null` first); named imports inside a single statement (`import { a, b, c }`); `Set` / `SafeSet` constructor arguments; allowlists / denylists / config arrays / interface members. Position-bearing arrays (where index matters) keep their meaningful order. Full details in [`docs/claude.md/sorting.md`](docs/claude.md/sorting.md). When in doubt, sort.
+- **Sorting** — sort alphanumerically (literal byte order, ASCII before letters). Applies to: object property keys (config + return shapes + internal state — `__proto__: null` first); named imports inside a single statement (`import { a, b, c }`); `Set` / `SafeSet` constructor arguments; allowlists / denylists / config arrays / interface members; **string-equality disjunctions** (`x === 'a' || x === 'b'` and the De Morgan dual `x !== 'a' && x !== 'b'`). Position-bearing arrays (where index matters) keep their meaningful order. Full details in [`docs/claude.md/sorting.md`](docs/claude.md/sorting.md). When in doubt, sort.
 - **`Promise.race` / `Promise.any` in loops** — never re-race a pool that survives across iterations (the handlers stack). See `.claude/skills/plug-leaking-promise-race/SKILL.md`.
 - **`Safe` suffix** — non-throwing wrappers end in `Safe` (`safeDelete`, `safeDeleteSync`, `applySafe`, `weakRefSafe`). Read it as "X, but safe from throwing." The wrapper traps the thrown value internally and returns `undefined` (or the documented fallback). Don't invent alternative suffixes (`Try`, `OrUndefined`, `Maybe`) — pick `Safe`.
 - **`node:smol-*` modules** — feature-detect, then require. From outside socket-btm (socket-lib, socket-cli, anywhere else): `import { isBuiltin } from 'node:module'; if (isBuiltin('node:smol-X')) { const mod = require('node:smol-X') }`. The `node:smol-*` namespace is provided by socket-btm's smol Node binary; on stock Node `isBuiltin` returns false and the require would throw. Wrap the loader in a `/*@__NO_SIDE_EFFECTS__*/` lazy-load that caches the result — see `socket-lib/src/smol/util.ts` and `socket-lib/src/smol/primordial.ts` for canonical shape. **Inside** socket-btm's `additions/source-patched/` JS (the smol binary's own bootstrap code), use `internalBinding('smol_X')` directly — that's the C++-binding access path and it's guaranteed available there.
diff --git a/docs/claude.md/sorting.md b/docs/claude.md/sorting.md
@@ -11,6 +11,7 @@ Sort lists alphanumerically (literal byte order, ASCII before letters).
 - **Array literals** — when the array is a config list, allowlist, or set-like collection. Position-bearing arrays (e.g. `argv`, anything where index matters semantically) keep their meaningful order.
 - **`Set` constructor arguments** — `new Set([...])` and `new SafeSet([...])` literals. The runtime is order-insensitive, so source order is alphanumeric. Same rationale as Array literals: predictable diffs, no merge conflicts on insertions.
 - **Regex alternation groups** — `(foo|bar|baz)` reads as `(bar|baz|foo)`. Capturing, non-capturing, and named-capture groups all follow the rule. Auto-fixable when every alternative is a simple literal. The exception is order-bearing alternations where the regex engine MUST try one alternative before another (rare; the canonical example is markup parsers where `<!--|-->` would silently mismatch if reordered) — append `// socket-hook: allow regex-alternation-order` on those lines.
+- **String-equality disjunctions** — `x === 'a' || x === 'b' || x === 'c'` reads with the comparand strings in alpha order. The De Morgan dual `x !== 'a' && x !== 'b'` (negative-membership check) follows the same rule. The `||` chain short-circuits regardless of operand order; sorting reduces diff churn when adding new comparands and makes "is X in this set?" checks visually consistent. Auto-fixable when every clause has the same left operand and uses string-literal comparands. Mixed shape (different left, different operator, non-string right) is skipped — those are usually genuine ordering-sensitive predicates and the autofix would change semantics.
 
 ## Default
 
