efkt is a lightweight CLI that parses your React codebase, classifies every useEffect by dependency shape and cleanup pattern, and outputs clean JSON or Markdown, ready for code audits, LLM review, or sharing with your team.

• Scans .js, .jsx, .ts, .tsx files via fast AST parsing
• Classifies effects into 6 categories (untracked, reactive, once × plain/cleanup)
• Outputs structured JSON or human-readable Markdown
• Optional comment stripping from effect bodies
• Filter to a single category or cap total results with --limit
• Respects .gitignore files found anywhere in the scanned tree
• Always skips node_modules, dist, build, out, coverage, .next, .turbo, .git
• Caps scan at 10,000 files with a stderr warning (prevents runaway scans)

pnpm add -g @alwalxed/efkt
# or
npm install -g @alwalxed/efkt
# or
yarn global add @alwalxed/efkt

efkt [path] [options]

Omitting [path] defaults to ./. Running without --json or --md in a TTY launches an interactive prompt. In non-TTY contexts (pipes, CI) a format flag is required — omitting it exits with an error.

Effects are classified by two axes: dependency array shape and presence of a cleanup return.

When using --json, the top-level envelope always contains:

{
  "scannedAt": "2026-03-13T10:00:00.000Z",
  "root": "./src",
  "totalFiles": 42,
  "totalEffects": 17,
  "effects": {
    "untracked": { "plain": [...], "cleanup": [...] },
    "reactive":  { "plain": [...], "cleanup": [...] },
    "once":      { "plain": [...], "cleanup": [...] }
  }
}

Each effect object contains file, component, startLine, endLine, body, raw, deps, and hasCleanup.

# Inspect the most dangerous effects
efkt --json | jq '.effects.untracked.plain'

# Count effects per subcategory
efkt --json | jq '.effects | to_entries[] | "\(.key): plain=\(.value.plain | length) cleanup=\(.value.cleanup | length)"'

# Only reactive effects with cleanup, under src/
efkt src/ --json --case reactive.cleanup

# Generate a Markdown report (great for LLM review or PRs)
efkt src/ --md --strip-comments > effects-report.md

# Analyze a single file
efkt src/components/Auth.tsx --json

# Cap output in large repos
efkt ./src --json --limit 25

# Copy report to clipboard (macOS)
efkt ./src --md | pbcopy

1. Recursively finds .js/.jsx/.ts/.tsx files, skipping common build/output dirs (node_modules, dist, .next, etc.) and respecting any .gitignore files in the tree (capped at 10,000 files)
2. Parses each file with a fast AST parser
3. Locates every useEffect call and inspects its arguments:
   • No second arg → untracked
   • [] → once
   • […deps] → reactive
   • Return function present → cleanup variant
4. Extracts body, dependencies, file path, line number, and component context
5. Serializes to JSON or Markdown

efkt is intentionally small and focused. If you have ideas for meaningful improvements — better categorization, ignore patterns, richer context extraction — open an issue or send a clean PR.

Please keep PRs scoped and avoid adding heavy dependencies.

MIT