feat(rules): add prefer-nullish-coalescing rule 0️⃣

- Add new lint rule for preferring nullish coalescing over logical OR
- Add test suite with 30+ test cases
- Add with examples and usage guidelines
- Add type definitions for LiteralNode and LogicalExpressionNode
- Add utility functions for AST node type checking
- Update plugin exports to include new rule
- Update README with rule documentation link

Author: NeaByteLab

README.md

@@ -7,6 +7,7 @@ Deno lint plugin collection for identifying and reporting on patterns found in c
 - [`async-function-naming`](./examples/async-function-naming.md) - Enforces async functions to have 'Async' suffix
 - [`explicit-parameter-types`](./examples/explicit-parameter-types.md) - Requires explicit type annotations on parameters
 - [`explicit-return-types`](./examples/explicit-return-types.md) - Requires explicit return type annotations
+- [`prefer-nullish-coalescing`](./examples/prefer-nullish-coalescing.md) - Prefers nullish coalescing (??) over logical OR (||) for null/undefined checks
 - [`require-error-handling`](./examples/require-error-handling.md) - Ensures Deno file operations are properly awaited
 
 ## Installation

examples/prefer-nullish-coalescing.md

@@ -0,0 +1,144 @@
+# Expected Behavior: `prefer-nullish-coalescing` Rule
+
+This rule enforces the use of nullish coalescing operator (`??`) over logical OR (`||`) when dealing with null or undefined values, particularly when the right-hand side is a falsy but not nullish value.
+
+## ❌ Invalid Examples
+
+```typescript
+// Logical OR with empty string (falsy but not nullish)
+const displayName = user.name || ''
+const message = input || ''
+const title = config.title || ''
+
+// Logical OR with zero (falsy but not nullish)
+const count = items.length || 0
+const index = searchIndex || 0
+const timeout = settings.timeout || 0
+
+// Logical OR with false (falsy but not nullish)
+const enabled = feature.flag || false
+const visible = config.show || false
+const required = field.required || false
+
+// Complex expressions with falsy values
+const result = user?.name || '' || 'Anonymous'
+const config = {
+  apiUrl: process.env.API_URL || '',
+  timeout: settings.timeout || 0,
+  debug: process.env.DEBUG || false
+}
+
+// Function parameters with falsy defaults
+function createUser(name = user.name || '', age = user.age || 0) {
+  return { name, age }
+}
+
+// Object properties with falsy values
+const user = {
+  name: input.name || '',
+  count: data.count || 0,
+  active: status.active || false
+}
+
+// Template literals with falsy values
+const greeting = `Hello ${user.name || ''}!`
+const status = `Count: ${items.length || 0}`
+const message = `Debug: ${config.debug || false}`
+```
+
+## ✅ Valid Examples
+
+```typescript
+// Nullish coalescing with empty string (correct)
+const displayName = user.name ?? ''
+const message = input ?? ''
+const title = config.title ?? ''
+
+// Nullish coalescing with zero (correct)
+const count = items.length ?? 0
+const index = searchIndex ?? 0
+const timeout = settings.timeout ?? 0
+
+// Nullish coalescing with false (correct)
+const enabled = feature.flag ?? false
+const visible = config.show ?? false
+const required = field.required ?? false
+
+// Complex expressions with nullish coalescing
+const result = (user?.name ?? '') || 'Anonymous'
+const config = {
+  apiUrl: process.env.API_URL ?? '',
+  timeout: settings.timeout ?? 0,
+  debug: process.env.DEBUG ?? false
+}
+
+// Function parameters with nullish coalescing defaults
+function createUser(name = user.name ?? '', age = user.age ?? 0) {
+  return { name, age }
+}
+
+// Object properties with nullish coalescing
+const user = {
+  name: input.name ?? '',
+  count: data.count ?? 0,
+  active: status.active ?? false
+}
+
+// Template literals with nullish coalescing
+const greeting = `Hello ${user.name ?? ''}!`
+const status = `Count: ${items.length ?? 0}`
+const message = `Debug: ${config.debug ?? false}`
+
+// Logical OR with non-falsy values (not affected by this rule)
+const name = user.name || 'Anonymous'
+const count = items.length || 10
+const enabled = feature.flag || true
+
+// Logical AND (not affected by this rule)
+const result = user && user.name
+const isValid = input && input.length > 0
+
+// Already using nullish coalescing (not affected by this rule)
+const displayName = user.name ?? 'Anonymous'
+const count = items.length ?? 10
+const enabled = feature.flag ?? true
+```
+
+## Rule Scope
+
+This rule **only applies to**:
+
+- ✅ Logical OR (`||`) operators where the right-hand side is a falsy but not nullish value:
+  - Empty string (`""`)
+  - Zero (`0`)
+  - Boolean `false`
+
+This rule **does NOT apply to**:
+
+- ❌ Logical OR (`||`) with non-falsy values (`"hello"`, `1`, `true`)
+- ❌ Logical AND (`&&`) operators
+- ❌ Nullish coalescing (`??`) operators
+- ❌ Other logical operators (`!`, `&&`, `??`)
+
+## Why This Rule Matters
+
+The logical OR (`||`) operator treats **all** falsy values as "missing":
+
+- `""` (empty string) → treated as missing
+- `0` (zero) → treated as missing
+- `false` (boolean) → treated as missing
+
+The nullish coalescing (`??`) operator only treats `null` and `undefined` as missing:
+
+- `""` (empty string) → preserved
+- `0` (zero) → preserved
+- `false` (boolean) → preserved
+
+## Auto-fix Behavior
+
+The rule provides auto-fix suggestions that replace `||` with `??`:
+
+- `value || ""` → `value ?? ""`
+- `count || 0` → `count ?? 0`
+- `flag || false` → `flag ?? false`
+- `(user?.name || "") || false` → `(user?.name ?? "") || false` (first occurrence)

src/mod.ts

@@ -2,6 +2,7 @@ import type { LintPlugin } from '@app/types.ts'
 import { asyncFunctionNamingRule } from '@rules/async-function-naming.ts'
 import { explicitParameterTypesRule } from '@rules/explicit-parameter-types.ts'
 import { explicitReturnTypesRule } from '@rules/explicit-return-types.ts'
+import { preferNullishCoalescingRule } from '@rules/prefer-nullish-coalescing.ts'
 import { requireErrorHandlingRule } from '@rules/require-error-handling.ts'
 
 /**
@@ -13,6 +14,7 @@ const plugin: LintPlugin = {
     'async-function-naming': asyncFunctionNamingRule,
     'explicit-parameter-types': explicitParameterTypesRule,
     'explicit-return-types': explicitReturnTypesRule,
+    'prefer-nullish-coalescing': preferNullishCoalescingRule,
     'require-error-handling': requireErrorHandlingRule
   }
 }

src/rules/prefer-nullish-coalescing.ts

@@ -0,0 +1,57 @@
+import type { ASTNode, LintContext, LintFixer, LogicalExpressionNode } from '@app/types.ts'
+import { isLiteral, isLogicalExpression } from '@shared/expression.ts'
+
+/**
+ * Checks if a logical expression should use nullish coalescing instead of logical OR.
+ * @param node - The logical expression node to check
+ * @returns True if the expression should use nullish coalescing, false otherwise
+ */
+function shouldUseNullishCoalescing(node: LogicalExpressionNode): boolean {
+  if (node.operator !== '||') {
+    return false
+  }
+  const rightSide = node.right
+  if (isLiteral(rightSide)) {
+    const value = rightSide.value
+    if (value === '' || value === 0 || value === false) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Lint rule for preferring nullish coalescing over logical OR.
+ */
+export const preferNullishCoalescingRule = {
+  /**
+   * Creates the lint rule implementation.
+   * @param context - The Deno lint context for reporting issues and fixes
+   * @returns Object containing visitor functions for AST node types
+   */
+  create(context: LintContext): Record<string, (node: ASTNode) => void> {
+    return {
+      /**
+       * Visitor function for logical expressions.
+       * @param node - The AST node representing a logical expression
+       */
+      LogicalExpression(node: ASTNode): void {
+        if (!isLogicalExpression(node)) {
+          return
+        }
+        if (shouldUseNullishCoalescing(node)) {
+          context.report({
+            node,
+            message:
+              'Prefer nullish coalescing (??) over logical OR (||) for null/undefined checks',
+            fix(fixer: LintFixer): unknown {
+              const original = context.sourceCode.getText(node)
+              const newText = original.replace('||', '??')
+              return fixer.replaceText(node, newText)
+            }
+          })
+        }
+      }
+    }
+  }
+}

src/shared/expression.ts

@@ -4,6 +4,8 @@ import type {
   CallExpressionNode,
   FunctionDeclarationNode,
   FunctionExpressionNode,
+  LiteralNode,
+  LogicalExpressionNode,
   MethodDefinitionNode
 } from '@app/types.ts'
 
@@ -51,3 +53,21 @@ export function isFunctionExpression(node: ASTNode): node is FunctionExpressionN
 export function isMethodDefinition(node: ASTNode): node is MethodDefinitionNode {
   return node.type === 'MethodDefinition'
 }
+
+/**
+ * Type guard to check if a node is a logical expression.
+ * @param node - The AST node to check
+ * @returns True if the node is a logical expression, false otherwise
+ */
+export function isLogicalExpression(node: ASTNode): node is LogicalExpressionNode {
+  return node.type === 'LogicalExpression'
+}
+
+/**
+ * Type guard to check if a node is a literal.
+ * @param node - The AST node to check
+ * @returns True if the node is a literal, false otherwise
+ */
+export function isLiteral(node: ASTNode): node is LiteralNode {
+  return node.type === 'Literal'
+}

src/types.ts

@@ -205,6 +205,30 @@ export interface TSTypeAliasDeclarationNode {
   id?: { name: string }
 }
 
+/**
+ * AST node representing a literal value (string, number, boolean, etc.).
+ */
+export interface LiteralNode {
+  /** Type identifier for literal nodes */
+  type: 'Literal'
+  /** The literal value */
+  value: string | number | boolean | null
+}
+
+/**
+ * AST node representing a logical expression (&&, ||, ??).
+ */
+export interface LogicalExpressionNode {
+  /** Type identifier for logical expressions */
+  type: 'LogicalExpression'
+  /** The logical operator */
+  operator: '&&' | '||' | '??'
+  /** Left side of the expression */
+  left: ASTNode
+  /** Right side of the expression */
+  right: ASTNode
+}
+
 /**
  * AST node representing a variable declarator.
  */
@@ -229,6 +253,8 @@ export type ASTNode =
   | FunctionDeclarationNode
   | FunctionExpressionNode
   | InterfaceDeclarationNode
+  | LiteralNode
+  | LogicalExpressionNode
   | MethodDefinitionNode
   | TSEnumDeclarationNode
   | TSEnumMemberNode

tests/index.ts

@@ -22,12 +22,17 @@ export function verifyAutoFix(
   rulesId: string,
   code: string,
   expectedFixedCode: string,
-  description: string
+  description: string,
+  expectedCount = 1
 ): void {
   const diagnostics = Deno.lint.runPlugin(plugin, 'test.ts', code)
   const ruleDiagnostics = diagnostics.filter((d) => d.id === rulesId)
   console.log(`${description} diagnostics:`, JSON.stringify(ruleDiagnostics, null, 2))
-  assertEquals(ruleDiagnostics.length, 1, `Expected 1 diagnostic for ${description}`)
+  assertEquals(
+    ruleDiagnostics.length,
+    expectedCount,
+    `Expected ${expectedCount} diagnostic for ${description}`
+  )
   const diagnostic = ruleDiagnostics[0]
   assertEquals(diagnostic.fix?.length, 1, `Should have auto-fix available for ${description}`)
   const fix = diagnostic.fix?.[0]