New Rule: no-unsafe-array-access

[pertrai1]

Research Evidence

From empirical LLM bug studies: Missing edge cases account for ~15% of LLM bugs. The "Understanding Code Generation Errors" study (557 bugs) lists "missing condition" as a top semantic error. LLMs frequently access array elements without checking if the array is empty.

Description

Prevent accessing arr[0], arr[arr.length - 1], or destructuring const [first] = arr without first checking that the array is non-empty.

Examples

Bad

const items = getItems();
const first = items[0]; // No length check

const [head, ...tail] = results; // No emptiness check

function getFirst(arr: string[]) {
  return arr[0]; // Could be undefined
}

Good

const items = getItems();
if (items.length > 0) {
  const first = items[0];
}

const [head, ...tail] = results.length > 0 ? results : [defaultValue];

function getFirst(arr: string[]): string | undefined {
  return arr.length > 0 ? arr[0] : undefined;
}

Detection Approach

• Flag arr[0] and arr[arr.length - 1] when not preceded by a length/emptiness check in the same scope
• Flag array destructuring const [x] = arr without a guard
• Consider only flagging when the array type doesn't include undefined in its element type (to avoid flagging when noUncheckedIndexedAccess is enabled)

Scope Considerations

• TypeScript's noUncheckedIndexedAccess handles the type-level concern, but many projects don't enable it
• This rule focuses on the runtime safety pattern, not the type system
• Should respect existing guard patterns: if (arr.length), arr?.length > 0, arr.length !== 0, etc.

Priority

High — one of the most specific, detectable edge-case patterns from the research. Directly derived from splitting the overly broad require-edge-case-handling proposal.

[pertrai1]

Gap Analysis: Overlap with Existing Rules

Before moving to implementation, I ran an overlap analysis against existing ESLint rules and TypeScript compiler options to evaluate acceptance criterion #5 ("Not already covered well enough").

Existing Coverage

Tool	What it catches	What it misses for this rule
noUncheckedIndexedAccess (TS compiler option)	Makes arr[i] return T | undefined instead of T	Does not require a preceding length check. Does not affect destructuring — const [first] = arr still types first as T. Not in the strict suite, explicitly called out in the PR notes as having "behavioral limitations."
@typescript-eslint/no-unnecessary-condition	Warns on always-truthy/falsy conditions	The opposite problem — it warns when you do check, not when you don't. Has documented false positives with arrays.
prefer-destructuring (ESLint core)	Encourages const [first] = arr over const first = arr[0]	Actively encourages the pattern this rule would guard. No length check required.
@typescript-eslint/safe-array-destructuring (proposed)	Would restrict destructuring to tuple types	PR #1645 was closed without merging. The team called it "ergonomically terrible for a lint rule" and noted it would require control-flow analysis of variable usage.
eslint-plugin-unicorn/explicit-length-check	Enforces === 0 / > 0 style	Does not check that a length comparison precedes array access.
eslint-plugin-sonarjs	Various array checks (size mischeck, unused collection, element overwrite)	None check for bounds/emptiness guards before access. Repo archived Oct 2024.

Conclusion: The gap is genuine. No existing rule requires verifying that an array is non-empty before arr[0], arr[arr.length - 1], or destructuring. The typescript-eslint team's rejection of safe-array-destructuring confirms this is a real problem worth solving, but also that the control-flow analysis is the hard part.

---

Implementation Ambiguities to Resolve

The proposal has strong research backing and clear motivating examples, but several concrete decisions are unresolved. The hardest — control-flow guard detection — is the entire complexity of the rule and is currently specified in one sentence.

Hard Blockers (must resolve before implementation)

1. Config placement not stated
Project acceptance criterion #6 requires stating whether the rule belongs in recommended, all, or which category config. Not specified in the issue.

2. Control-flow guard scope undefined
"Not preceded by a length/emptiness check in the same scope" — what does "same scope" mean here?

• Same block ({ ... })?
• Same function body?
• Any control-flow ancestor (i.e., if (arr.length > 0) { ... arr[0] ... } is guarded)?
• What about early returns: if (!arr.length) return; followed by arr[0] in the same function?

3. Valid guard patterns not enumerated
The issue mentions if (arr.length), arr?.length > 0, arr.length !== 0 but is silent on:

• arr.length > 0
• arr.length >= 1
• !!arr.length
• Truthiness: if (arr.length) { ... }
• Optional chaining on access: arr?.[0] — is this self-guarding?
• for...of loops (body inherently implies non-empty?)
• Type predicates / user-defined type guards like function hasAtLeast<T, N extends number>(n: N, arr: T[]): arr is [...]
• NonEmptyArray<T> branded types

Important but resolvable during implementation

4. Destructuring with defaults — Is const [x = defaultValue] = arr considered safe (default provided) or still flagged?

5. Rule options — No options proposed. Should there be any (e.g., checkDestructuring, checkElementAccess)?

6. Error message — Not drafted. Must follow the project's structured teaching format (what's wrong, why, how to fix with concrete examples).

7. noUncheckedIndexedAccess interaction — Should the rule behave differently (or be a no-op) when this compiler option is enabled?

8. Suggestion vs auto-fix — Not specified, but project convention is clear: suggestions for semantic changes, which this is.

---

Verdict

The rule fills a genuine ecosystem gap and the research justification is solid. But the control-flow analysis question (#2 above) is the entire rule complexity — the typescript-eslint team cited exactly this as the reason they rejected their own proposal. We should resolve blockers #1–3 in this issue before moving to implementation.