diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..b0f4e6ee --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,6 @@ +# Code owners for Wickra. +# +# The owner listed here is requested for review automatically on every pull +# request. See https://docs.github.com/articles/about-code-owners. + +* @kingchenc diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..6d7d1f17 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,39 @@ +--- +name: Bug report +about: Report incorrect behaviour in Wickra +title: "[bug] " +labels: bug +assignees: "" +--- + +## Description + + + +## Reproduction + + + +```rust +// or python / javascript +``` + +## Expected behaviour + + + +## Actual behaviour + + + +## Environment + +- Wickra version: +- Language / binding: +- OS and architecture: +- Rust / Python / Node version (if relevant): + +## Additional context + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..332ee64d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/kingchenc/wickra/security/advisories/new + about: Report security issues privately — do not open a public issue. + - name: Question or discussion + url: https://github.com/kingchenc/wickra/discussions + about: Ask usage questions and discuss ideas here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..9281181a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,31 @@ +--- +name: Feature request +about: Suggest a new indicator or capability for Wickra +title: "[feature] " +labels: enhancement +assignees: "" +--- + +## Problem + + + +## Proposed solution + + + +## Alternatives considered + + + +## Scope + +- [ ] Affects the Rust core +- [ ] Should be exposed in the Python binding +- [ ] Should be exposed in the Node binding +- [ ] Should be exposed in the WASM binding + +## Additional context + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..0f72007e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,33 @@ + + +## Summary + + + +## Related issue + + + +## Type of change + +- [ ] Bug fix +- [ ] New feature +- [ ] Indicator addition / change +- [ ] Documentation +- [ ] CI / build / tooling + +## Checklist + +- [ ] `cargo fmt --all --check` is clean. +- [ ] `cargo clippy --workspace --all-targets -- -D warnings` is clean. +- [ ] `cargo test --workspace` passes. +- [ ] New behaviour has tests; bug fixes have a regression test. +- [ ] Public API changes are mirrored in the Python / Node / WASM bindings + and their type stubs (if applicable). +- [ ] Documentation under `docs/wiki/` and the `README.md` is updated + (if applicable). +- [ ] An entry was added under `## [Unreleased]` in `CHANGELOG.md`. + +## Notes for reviewers + + diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..313685a3 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,38 @@ +version: 2 +updates: + # Rust workspace (root Cargo.toml + all member crates). + - package-ecosystem: cargo + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 10 + commit-message: + prefix: "deps(cargo)" + + # Node binding npm dependencies. + - package-ecosystem: npm + directory: "/bindings/node" + schedule: + interval: weekly + open-pull-requests-limit: 10 + commit-message: + prefix: "deps(npm)" + + # Python binding pip dependencies. + - package-ecosystem: pip + directory: "/bindings/python" + schedule: + interval: weekly + open-pull-requests-limit: 10 + commit-message: + prefix: "deps(pip)" + + # GitHub Actions — keeps the SHA-pinned actions current (Dependabot reads + # the version comment after each pinned SHA and bumps both together). + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 10 + commit-message: + prefix: "deps(actions)" diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..6a78951a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,86 @@ +# Changelog + +All notable changes to Wickra are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- `TickAggregator::with_gap_fill` — opt-in mode that emits a flat placeholder + candle for every empty bucket between two ticks, keeping the candle series + evenly spaced for downstream indicators. +- CSV reader: a leading UTF-8 byte-order mark is stripped, fields are trimmed, + and the header is validated against the required OHLCV columns. +- CI: an `msrv` job that builds and tests the workspace on Rust 1.75 and the + node binding on Rust 1.77. +- Community health files: `CONTRIBUTING.md`, `SECURITY.md`, + `CODE_OF_CONDUCT.md`, issue / pull-request templates, `CODEOWNERS`, and a + Dependabot configuration. + +### Changed +- `TickAggregator::push` returns `Result>` (was + `Result>`) so a single tick can yield a closed bar plus gap + fillers. +- `Resampler::push` returns `Result>`: a candle in a bucket + earlier than the open bar is now rejected as out of order. +- Aggregated candles are finalised through the validating `Candle::new`, so a + volume that overflows to a non-finite value is surfaced as an error instead + of producing a poisoned candle. +- All GitHub Actions are pinned to commit SHAs; the four publish jobs run in a + protected `release` environment. + +### Fixed +- `Timeframe::floor` no longer overflows for timestamps near `i64::MIN`. +- The aggregator rejects same-bucket ticks that arrive out of order instead of + silently overwriting the bar's close with a stale price. +- The Binance live stream reconnects with exponential backoff, skips non-kline + frames, applies a read timeout and message-size limits, and tracks a closed + flag. +- Example scripts: `live_trading.py` skips non-kline frames and validates the + symbol/interval; `backtest.py` and `multi_timeframe.py` report clear errors + for malformed CSV input. + +## [0.1.4] - 2026-05-21 + +### Added +- GitHub Release runs now attach every built artefact (wheels, sdist, native + Node binaries, npm-pack tarballs, cargo `.crate` files) to the tag's + release page. + +## [0.1.3] - 2026-05-21 + +### Fixed +- npm package ships the napi-generated loader and is built with `--platform` + so the per-platform binary is resolved correctly. + +## [0.1.2] - 2026-05-21 + +### Fixed +- Release pipeline: per-platform idempotent npm publishing with a spam-filter + retry, and committed `npm//` package templates. + +## [0.1.1] - 2026-05-21 + +### Fixed +- Node publish step and coordinated version bump across all bindings. + +## [0.1.0] - 2026-05-21 + +### Added +- Initial release: a streaming-first technical-analysis library with 25 + indicators (SMA, EMA, WMA, DEMA, TEMA, HMA, KAMA, RSI, MACD, ROC, Stochastic, + CCI, Williams %R, ADX, MFI, TRIX, Aroon, Awesome Oscillator, Bollinger Bands, + ATR, Keltner Channels, Donchian Channels, Parabolic SAR, OBV, VWAP). +- Rust core (`wickra-core`), umbrella crate (`wickra`), and a data layer + (`wickra-data`) with a CSV reader, tick aggregator, resampler, and an + optional Binance live feed. +- Bindings for Python, Node.js, and WebAssembly. + +[Unreleased]: https://github.com/kingchenc/wickra/compare/v0.1.4...HEAD +[0.1.4]: https://github.com/kingchenc/wickra/compare/v0.1.3...v0.1.4 +[0.1.3]: https://github.com/kingchenc/wickra/compare/v0.1.2...v0.1.3 +[0.1.2]: https://github.com/kingchenc/wickra/compare/v0.1.1...v0.1.2 +[0.1.1]: https://github.com/kingchenc/wickra/compare/v0.1.0...v0.1.1 +[0.1.0]: https://github.com/kingchenc/wickra/releases/tag/v0.1.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..8dd14afb --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,47 @@ +# Code of Conduct + +## Our pledge + +We as members, contributors, and maintainers pledge to make participation in +the Wickra project a respectful and welcoming experience for everyone, +regardless of background or identity. + +## Our standards + +Behaviour that helps build a positive community includes: + +- Showing empathy and kindness toward others. +- Respecting differing opinions, viewpoints, and experiences. +- Giving and gracefully accepting constructive feedback. +- Taking responsibility for mistakes and learning from them. +- Focusing on what is best for the project and the community. + +Behaviour that is not acceptable includes: + +- Personal attacks, insults, or derogatory comments. +- Harassment of any kind, public or private. +- Publishing others' private information without explicit permission. +- Other conduct that would reasonably be considered inappropriate in a + professional setting. + +## Scope + +This Code of Conduct applies in all project spaces — the repository, issues, +pull requests, and discussions — and when an individual is representing the +project in public spaces. + +## Enforcement + +Instances of unacceptable behaviour may be reported to the project maintainer +at **kingchencp@gmail.com**. All reports will be reviewed and investigated +promptly and fairly, and the maintainer will respect the privacy and security +of the reporter. + +Maintainers may take any action they deem appropriate, including warnings, +temporary bans, or permanent removal from the project, for behaviour that +violates this Code of Conduct. + +## Attribution + +This Code of Conduct is adapted from the +[Contributor Covenant](https://www.contributor-covenant.org), version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..390d1113 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,94 @@ +# Contributing to Wickra + +Thanks for your interest in improving Wickra. This document explains how to +build the project, the standards a change must meet, and how to get it merged. + +## License of contributions + +Wickra is licensed under the **PolyForm Noncommercial License 1.0.0** (see +[`LICENSE`](LICENSE)). By submitting a contribution you agree that it is +licensed to the project under those same terms. The Noncommercial license +permits use for any purpose **other than** a commercial one; keep that in mind +when proposing features or depending on Wickra elsewhere. + +## Project layout + +| Path | Contents | +| --- | --- | +| `crates/wickra-core` | The indicator engine — every indicator lives here. | +| `crates/wickra` | Thin umbrella crate re-exporting `wickra-core`. | +| `crates/wickra-data` | CSV reader, tick aggregator, resampler, Binance feed. | +| `bindings/python` | PyO3 bindings (`wickra` on PyPI). | +| `bindings/node` | napi-rs bindings (`wickra` on npm). | +| `bindings/wasm` | wasm-bindgen bindings (`wickra-wasm` on npm). | +| `examples/` | Runnable examples. | +| `docs/wiki/` | Documentation sources. | + +## Building and testing + +### Rust + +```bash +cargo fmt --all --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace +cargo test -p wickra-data --features live-binance +``` + +The minimum supported Rust version is **1.75** for the workspace crates and +**1.77** for `bindings/node`; the `msrv` CI job enforces both. + +### Python + +```bash +cd bindings/python +python -m maturin build --release --out dist +python -m pip install --force-reinstall --no-deps dist/wickra-*.whl +python -m pytest -q +``` + +### Node + +```bash +cd bindings/node +npm install +npx napi build --platform --release +node --test __tests__/ +``` + +### WASM + +```bash +wasm-pack build bindings/wasm --target web --release --features panic-hook +wasm-pack test --node bindings/wasm +``` + +## Standards for a change + +- **Formatting & lints.** `cargo fmt` must leave the tree unchanged and + `cargo clippy ... -D warnings` must be clean. CI gates both. +- **Tests.** New behaviour needs tests; bug fixes need a regression test. +- **Indicator correctness.** A new or changed indicator must have a + reference-value test against a known-good source (TA-Lib, pandas-ta, or a + hand-computed value) and a `reset` test. +- **Streaming parity.** An indicator's `batch` output must equal the sequence + of `update` calls. +- **Bindings.** A change to a public indicator API must be mirrored across the + Python, Node, and WASM bindings, including their type stubs / `.d.ts`. +- **Docs.** Update the relevant page under `docs/wiki/` and the `README.md` + when behaviour or the public API changes. +- **Changelog.** Add an entry under `## [Unreleased]` in `CHANGELOG.md`. + +## Commit and pull-request workflow + +1. Branch off `main`. +2. Keep commits focused — one logical change per commit, with an imperative + subject line and a body explaining *why*. +3. Open a pull request against `main` and fill in the template. +4. CI must be green before review. + +## Reporting bugs and proposing features + +Use the issue templates under +[`.github/ISSUE_TEMPLATE`](.github/ISSUE_TEMPLATE). For security-sensitive +reports, follow [`SECURITY.md`](SECURITY.md) instead of opening a public issue. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..85527dd6 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,43 @@ +# Security Policy + +## Supported versions + +Wickra is pre-1.0. Security fixes are applied to the latest released `0.1.x` +version only; please upgrade to the newest release before reporting an issue. + +| Version | Supported | +| --- | --- | +| 0.1.x (latest) | :white_check_mark: | +| older 0.1.x | :x: | + +## Reporting a vulnerability + +**Do not open a public issue for a security vulnerability.** + +Report it privately through one of: + +- GitHub's [private vulnerability reporting](https://github.com/kingchenc/wickra/security/advisories/new) + ("Report a vulnerability" under the repository's *Security* tab), or +- email to **kingchencp@gmail.com** with a subject line starting with + `[wickra security]`. + +Please include: + +- the affected version(s) and platform / language binding, +- a description of the issue and its impact, +- steps to reproduce, ideally a minimal proof of concept. + +## What to expect + +- An acknowledgement within **5 working days**. +- An assessment and, if confirmed, a planned fix with a target release. +- Coordinated disclosure: we will agree on a disclosure date with you and + credit you in the release notes unless you prefer to stay anonymous. + +## Scope + +In scope: the published crates (`wickra-core`, `wickra-data`, `wickra`), the +PyPI/npm packages, and the build/release workflows in `.github/workflows/`. + +Out of scope: vulnerabilities in third-party dependencies (report those +upstream; we track them via Dependabot and `cargo-deny`).