cm45t3r / candlestick / 29127823745

100%

push

github

feat(kicker): configurable, pluggable volatility-based gap significance threshold (#98)

* feat(kicker): add configurable, pluggable volatility-based gap threshold

Kicker detection previously treated any nonzero gap between candle bodies
as significant, producing matches on economically meaningless gaps (e.g.
$0.30 on a $210 stock, reported with the same static 0.9 confidence as a
multi-dollar news gap).

Adds an opt-in `minGapVol` threshold to `bullishKicker`/`bearishKicker`/
`isBullishKicker`/`isBearishKicker`, measured against a configurable
volatility unit:

- `volMethod: "atr" | "stddev" | "percentile"` — built-in measures
  (src/volatility.js), all expressed as a fraction of price so they're
  comparable across price levels.
- `volMethod: "fixed-pct"` — flat percentage of previous close, no
  lookback/history required.
- `externalVolatility` / `volatilityFn` — escape hatches for callers who
  already have a more advanced volatility model (e.g. GARCH fit
  externally); this package does not implement GARCH itself.

Also extracts `src/seriesResolver.js`, a small internal helper that
resolves a per-candle series from (callback > precomputed array > named
built-in method), shared plumbing intended for reuse by the trend-context
proposal in #95.

Fully backward compatible: `minGapVol` defaults to `0`, preserving the
exact pre-existing behavior when omitted.

Closes #96. Implements the shared helper proposed in #97.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XRBitjqZyuWGbSXjYKivE2

* test(kicker): cover the atr/percentile array-level paths and bearishKicker's minGapVol branch

CI coverage on the previous commit showed kicker.js at 93.14% stmts /
88.88% funcs (below this repo's 99%+/100% targets), missing:
- the percentile builtin wrapper inside resolveVolatilitySeries
- bearishKicker's entire minGapVol > 0 branch (only bullishKicker's was
  exercised)
- any real volMethod: "atr"/"percenti... (continued)

800 of 809 branches covered (98.89%)

Branch coverage included in aggregate %.

2918 of 2924 relevant lines covered (99.79%)

17364.53 hits per line