Skip to content

Add floating / unawaited promise detector #258

Description

@cursor

Summary

Add a detector for floating/unawaited promises — async calls whose returned promise is neither awaited, returned, nor .catch-handled — including fire-and-forget async work started inside React effects.

Motivation

Unawaited promises cause silent failures, race conditions, and unhandled rejections. They are easy to introduce when editing quickly and are not covered by any current rule. This pairs naturally with effect-complexity for the React case.

Proposed behavior

  • floating-promise: a call to a function known/inferred to return a promise (async function, .then-able, or common APIs like fetch) used as an expression statement without await, return, void, or .catch(...).
  • React-aware variant: async work kicked off inside useEffect without cleanup/handling.
  • Conservative defaults to keep false positives low (only flag clearly promise-returning calls; allow void expr as an explicit opt-out, matching common lint conventions).

Implementation surface

  • New src/detectors/floatingPromise.ts using ts-morph type/heuristic inference and the shared AST helpers in src/utils/ast.ts.
  • Register in src/detectors/index.ts; include in core (and surface the effect case via the react pack) in src/config/packs.ts.
  • Docs in docs/rules.md; fixtures covering awaited, returned, voided, and floating cases.

Acceptance criteria

  • Flags clear floating promises; does not flag awaited/returned/voided/.catch-handled calls.
  • Effect-scoped fire-and-forget is detected.
  • Documented confidence + false-positive notes.
  • npm run test:all passes.

Difficulty: medium.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions