xfingine 0.0.1__tar.gz

xfingine-0.0.1/.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --package xtask --"

xfingine-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,155 @@
+name: Multi-Ecosystem Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      publish_crates:
+        description: 'Publish to crates.io'
+        type: boolean
+        default: true
+      publish_npm:
+        description: 'Publish to NPM'
+        type: boolean
+        default: true
+      publish_pypi:
+        description: 'Publish to PyPI'
+        type: boolean
+        default: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  check_branch:
+    name: Verify Tag is on Main
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check if tag is on main
+        run: |
+          git fetch origin main
+          if ! git branch -r --contains ${{ github.sha }} | grep -E -q '(^|\s)origin/main$'; then
+            echo "Error: Tag ${{ github.ref_name }} is not on the main branch."
+            exit 1
+          fi
+
+  test:
+    name: Test Before Publish
+    needs: check_branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - name: Run tests
+        run: cargo test --workspace --all-features
+
+  crates_io:
+    name: Publish to crates.io
+    if: github.event_name == 'push' || inputs.publish_crates != false
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
+      - name: Authenticate with crates.io
+        uses: rust-lang/crates-io-auth-action@v1
+        id: auth
+      - name: Publish xfingine crate
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+        run: cargo publish --package xfingine
+
+  npm:
+    name: Publish to NPM
+    if: github.event_name == 'push' || inputs.publish_npm != false
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: 'https://registry.npmjs.org'
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - name: Cache Cargo dependencies
+        uses: Swatinem/rust-cache@v2
+      - name: Install wasm-pack
+        run: |
+          if ! command -v wasm-pack &> /dev/null; then
+            curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+          fi
+      - name: Build WASM (Web Target)
+        working-directory: wasm
+        run: wasm-pack build --target web
+      - name: Publish to NPM
+        working-directory: wasm/pkg
+        run: |
+          npm install -g npm@latest
+          unset NODE_AUTH_TOKEN
+          npm publish --access public --provenance
+
+  pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'push' || inputs.publish_pypi != false
+    needs: test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install Maturin
+        run: pip install maturin
+      - name: Build Wheels
+        working-directory: python
+        run: maturin build --release --out dist
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: python/dist/
+
+  pypi_publish:
+    name: Upload to PyPI
+    if: github.event_name == 'push' || inputs.publish_pypi != false
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Download wheels
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true

xfingine-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,72 @@
+name: PR Checks
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    name: Approve PR
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check Changes and Changelog
+        id: check_changes
+        run: |
+          git fetch origin ${{ github.base_ref }}
+
+          # Core paths that require a changelog entry (markdown excluded)
+          CORE_CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- src/ python/ wasm/ tests/ Cargo.toml | grep -v -i '\.md$' || true)
+
+          if [ -n "$CORE_CHANGED" ]; then
+            echo "The following core files were modified:"
+            echo "$CORE_CHANGED"
+            echo "----------------------------------------"
+
+            if ! git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -q "^CHANGELOG.md$"; then
+              echo "::error::Core files were modified but CHANGELOG.md was not updated. Please document your changes."
+              exit 1
+            fi
+            echo "Success: CHANGELOG.md was updated!"
+            echo "run_tests=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "No core files modified. Changelog update not strictly required."
+            echo "run_tests=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install Rust
+        if: steps.check_changes.outputs.run_tests == 'true'
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+          targets: wasm32-unknown-unknown
+
+      - name: Cache cargo registry and build
+        if: steps.check_changes.outputs.run_tests == 'true'
+        uses: Swatinem/rust-cache@v2
+
+      - name: Check formatting
+        if: steps.check_changes.outputs.run_tests == 'true'
+        run: cargo fmt --check
+
+      - name: Check for warnings
+        if: steps.check_changes.outputs.run_tests == 'true'
+        run: cargo clippy --workspace --all-targets --all-features -- -D warnings
+
+      - name: Run tests
+        if: steps.check_changes.outputs.run_tests == 'true'
+        run: cargo test --workspace --all-features
+
+      - name: Build WASM
+        if: steps.check_changes.outputs.run_tests == 'true'
+        run: cargo build --target wasm32-unknown-unknown -p xfingine-wasm
+
+      - name: Build Python bindings
+        if: steps.check_changes.outputs.run_tests == 'true'
+        run: cargo check -p xfingine-py

xfingine-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug
+target
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# Generated by cargo mutants
+**/mutants.out*/
+
+# WASM / npm build output
+wasm/pkg/
+node_modules/
+
+# Python build output
+python/dist/
+python/target/
+*.egg-info/
+__pycache__/
+.venv/
+
+# Scratch and debug files
+scratch/
+*.rs.scratch

xfingine-0.0.1/AGENTS.md

@@ -0,0 +1,116 @@
+# Xfingine — Agent Context & Guidelines
+
+A cheat sheet for AI agents working on Xfingine, so you can get oriented without
+re-deriving the architecture.
+
+## What this project is (and is not)
+
+Xfingine is a **pure computation library**. Input data → computation → output
+data. There is **no UI, no CLI, no file I/O, no network, and no clock** in the
+core crate, and none should be added. If a change requires reaching outside the
+process, it belongs in the caller, not here.
+
+This is the sibling project to [Xfina](https://github.com/sakthipriyan/xfina),
+which parses financial statements. Xfina has a web app; Xfingine deliberately
+does not. Consumers bring their own UI — today that is the tools page on
+sakthipriyan.com, which loads the WASM bundle.
+
+## Architecture Overview
+
+- **Core (`src/`):** Plain Rust. One module per engine (`src/emi/`), each split
+  into `model.rs` (the serde types on the wire) and `engine.rs` (the maths).
+  Shared helpers live in `src/num.rs`; all errors are `XfingineError`.
+- **WASM (`wasm/`):** `wasm-bindgen` wrappers published to npm as
+  `xfingine-wasm`. Every engine is exposed twice — object in/out, and a `_json`
+  twin taking and returning strings.
+- **Python (`python/`):** `pyo3` + `pythonize` wrappers published to PyPI as
+  `xfingine`. Same dual shape: dict in/out, plus a `_json` twin.
+- **`xtask/`:** Release automation only. Not published.
+
+The bindings must stay **thin**. They deserialize, call one core function, and
+serialize. No maths, no validation, no defaulting in a binding — if you find
+yourself writing logic there, it belongs in the core so all three targets get
+it.
+
+## Build & Test
+
+```bash
+cargo test --workspace --all-features
+cargo fmt --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo build --target wasm32-unknown-unknown -p xfingine-wasm
+
+cd wasm   && wasm-pack build --target web    # npm package → wasm/pkg
+cd python && maturin develop                 # importable module (needs a venv)
+```
+
+`maturin develop` needs `VIRTUAL_ENV` set or a `.venv` in the tree.
+
+## Testing Workflow
+
+- **Snapshots:** `tests/data/emi_cases.json` holds inputs, `emi_expected.json`
+  holds full recorded results. Unlike Xfina — whose fixtures contain PII and so
+  live outside the repo in `../xfina-test-data/` — these are pure numbers, so
+  they are **committed** and CI checks them directly.
+- **Re-recording:** `UPDATE_EXPECTED=1 cargo test`. Never re-record to make a
+  failing test pass without first understanding *why* the numbers moved, and
+  say so in the changelog when they legitimately did.
+- **Invariants:** `schedules_are_internally_consistent` asserts properties that
+  hold regardless of the numbers (rows sum exactly, balance reaches zero, the
+  per-year breakdown covers every payment once). Add to it when adding an
+  engine — it catches classes of bug snapshots cannot.
+
+## Technical Rules & Conventions
+
+1. **Money out is `i64` whole rupees.** Engines compute in `f64` and round at
+   the boundary, because that is what a lender debits. Never emit fractional
+   currency; paise drift accumulates badly across 360 rows.
+2. **Use `num::js_round`, not `f64::round`.** The engines are ported from
+   JavaScript and must match it bit for bit. `Math.round` rounds half *up*;
+   Rust's `f64::round` rounds half *away from zero*. They differ on negatives.
+3. **Rates are percentages, not fractions.** `9.0` means 9%. Convert to a
+   monthly fraction inside the engine, never at the API boundary.
+4. **JSON is `camelCase`** on every type, via
+   `#[serde(rename_all = "camelCase")]`, so Rust, WASM and Python share one wire
+   format.
+5. **No ambient clock.** Never call `SystemTime::now()` or equivalent. Dates are
+   opt-in through an explicit `start` field; without it the engine emits no
+   dates and an empty per-year breakdown. Determinism is the point.
+6. **Errors, never panics.** Every fallible path returns `XfingineError`.
+   Validate inputs up front and name the offending field in the message, using
+   the `camelCase` name the caller actually passed (`loanAmount`, not
+   `loan_amount`).
+7. **Every engine sits behind its own Cargo feature,** included in `all`, so a
+   WASM bundle only carries the maths it uses.
+8. **`#![warn(missing_docs)]` is on.** Public items need doc comments. Say what
+   a number *means*, not just its type — `real_interest` needs the sentence
+   about discounting far more than it needs "the real interest".
+
+## Porting an engine from the JavaScript tools
+
+The engines originate as `.js` files in
+`../sakthipriyan.github.io/static/js/`. When porting one:
+
+1. Extract *only* the maths — the JS files interleave it with Vue templates and
+   ECharts wiring.
+2. Build a differential harness: run the extracted JS and the Rust side over the
+   same inputs and compare **every field of every row**, not just the totals.
+   Fuzz it with a few hundred random cases too; the interesting bugs live in
+   final-row and zero-rate edges.
+3. Where the Rust deliberately diverges from the JS — a rounding bug in the
+   original, say — record it in `CHANGELOG.md` and explain why, so nobody
+   "fixes" it back later.
+
+## Release Process
+
+```bash
+cargo xtask prepare-release <major|minor|patch>   # bumps version, rolls changelog, branches
+# push, open a PR, merge to main
+cargo xtask tag-release                          # tags main and pushes
+```
+
+The tag fires `.github/workflows/publish.yml` → crates.io, npm, PyPI in
+parallel. PRs touching `src/`, `wasm/`, `python/`, `tests/` or `Cargo.toml`
+**must** update `CHANGELOG.md`; CI fails the PR otherwise.
+
+Open the PR and stop — merging is the maintainer's call, per PR.

xfingine-0.0.1/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be 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]
+
+## [0.1.0] - 2026-08-27
+
+Initial release.
+
+### Added
+
+- **Core:** The `xfingine` crate — a pure computation layer for personal finance
+  planning. Data in, arithmetic, data out: no UI, no I/O, no network, no clock.
+- **RealValue EMI Engine (`emi` feature):** Loan amortization reported in both
+  nominal rupees and rupees discounted for inflation. Solves for any one of
+  monthly payment, tenure, or loan amount given the other two, and returns
+  headline totals, the full month-by-month schedule, and an optional
+  per-calendar-year breakdown. Ported from `realvalue-emi-engine.js` on
+  sakthipriyan.com.
+- **WASM bindings (`xfingine-wasm` on npm):** Each engine exposed as both an
+  object-in/object-out function and a `_json` string variant.
+- **Python bindings (`xfingine` on PyPI):** Each engine exposed as both a
+  dict-in/dict-out function and a `_json` string variant, via `pyo3`.
+- **Cargo features:** One feature per engine, all enabled by `default`, so a
+  WASM bundle carries only the maths it uses.
+- **Tests:** Committed snapshots over 16 scenarios, structural invariant checks,
+  and unit coverage of the formulas, degenerate zero-rate cases, and every error
+  path.
+- **CI/CD:** PR checks gating on formatting, clippy, tests and a changelog
+  entry; tag-triggered publishing to crates.io, npm and PyPI.
+- **`xtask`:** `prepare-release` and `tag-release` for cutting versions.
+
+### Notes on the port
+
+The EMI engine was verified differentially against the original JavaScript, not
+merely tested in isolation: both implementations were run over the same inputs
+and compared field by field across every schedule row — 16 hand-picked scenarios
+(2,691 rows) and 600 randomized cases (133,686 rows). Output is bit-identical
+apart from one deliberate difference:
+
+- **Fixed:** the JavaScript rounds every payment to whole rupees *except the
+  final one*, where it assigns the raw floating-point balance as the closing
+  principal. On loans whose principal is not itself a round number this made the
+  last row — and therefore the nominal total — carry fractional paise, and could
+  report a *real* final payment marginally larger than the nominal one, which is
+  incoherent. Xfingine rounds the closing principal like every other row, so
+  `emi == principal + interest` holds in whole rupees on all rows and the
+  schedule sums exactly to the totals. The difference only surfaces on the final
+  row of a loan with a non-round principal.

xfingine-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to Xfingine
+
+Thanks for your interest in Xfingine. The most valuable contribution is a new
+**engine** — a self-contained computation that takes data in and gives data
+back.
+
+## Getting Started
+
+1. **Fork the repository.**
+2. **Install Rust** via [rustup](https://rustup.rs/).
+3. **Build and test:**
+   ```bash
+   cargo build
+   cargo test --workspace --all-features
+   ```
+
+For the bindings you will also want
+[`wasm-pack`](https://rustwasm.github.io/wasm-pack/) and
+[`maturin`](https://www.maturin.rs/).
+
+## Scope
+
+Xfingine is a **pure library**: no UI, no CLI, no file I/O, no network, and no
+clock. Anything that reaches outside the process belongs in the caller. Pull
+requests that add such dependencies to the core crate will be asked to move
+them out.
+
+## Adding a New Engine
+
+Engines live in `src/<engine>/`, split into `model.rs` (the serde types) and
+`engine.rs` (the maths).
+
+1. **Create the module.** Add `src/<engine>/mod.rs`, `model.rs` and `engine.rs`,
+   and declare it in `src/lib.rs` behind `#[cfg(feature = "<engine>")]`.
+2. **Model the data.** Put every type on the wire in `model.rs` with
+   `#[serde(rename_all = "camelCase")]`. Provide builder-style constructors for
+   the common cases, the way `EmiRequest::emi(..)` does.
+3. **Return errors, never panic.** Everything fallible returns
+   `Result<T, XfingineError>`. Validate inputs up front, and name the offending
+   field using the `camelCase` name the caller passed.
+4. **Add the feature flag** in `Cargo.toml` and include it in `all`.
+5. **Wire up the targets** — both are one line each, thanks to the macros:
+   - `wasm/src/lib.rs`: `bind_engine!(compute_x_json, compute_x, XRequest, xfingine::x::compute)`
+   - `python/src/lib.rs`: `bind_engine!(compute_x, compute_x_json, XRequest, ::xfingine::x::compute)`
+     and register both in the `#[pymodule]` block.
+   - Mirror the feature flag in `wasm/Cargo.toml` and `python/Cargo.toml`.
+6. **Document it** in `README.md`, `wasm/README.md` and `python/README.md`.
+
+Keep the bindings thin. They deserialize, call one core function, and serialize.
+Any logic there is logic the other two targets silently miss.
+
+## Testing Requirements
+
+Tests are mandatory. Because the engines are pure maths with no PII, all
+fixtures are committed to this repository — there is no external test-data repo.
+
+1. **Snapshot test.** Add inputs to `tests/data/<engine>_cases.json` and record
+   the output:
+   ```bash
+   UPDATE_EXPECTED=1 cargo test
+   ```
+   Commit both files. Follow the pattern in `tests/emi_integration.rs`:
+   ```rust
+   if std::env::var("UPDATE_EXPECTED").as_deref() == Ok("1") {
+       fs::write(EXPECTED, serde_json::to_string(&actual).unwrap()).unwrap();
+       return;
+   }
+   let expected: Vec<XResult> = serde_json::from_str(&fs::read_to_string(EXPECTED)?)?;
+   assert_eq!(expected, actual);
+   ```
+2. **Invariant tests.** Assert what must hold whatever the numbers are — totals
+   reconcile with rows, balances land exactly on zero, monotonic relationships
+   stay monotonic. These catch what snapshots cannot.
+3. **Unit tests** in `engine.rs` for the formulas themselves, the zero-rate
+   degenerate cases, and every error path.
+
+### Porting from the JavaScript tools
+
+If you are porting an engine from `sakthipriyan.com`'s existing `.js` tools,
+verify it **differentially**: run the original JavaScript and your Rust over the
+same inputs and compare every field of every row, plus a few hundred randomized
+cases. Totals agreeing is not enough — rounding bugs hide in the final row.
+
+Where you deliberately diverge from the original, record it in `CHANGELOG.md`
+with the reasoning, so it is not "fixed" back later.
+
+## Pull Request Process
+
+1. `cargo test --workspace --all-features` passes.
+2. `cargo fmt --check` is clean.
+3. `cargo clippy --workspace --all-targets --all-features -- -D warnings` is clean.
+4. **Update `CHANGELOG.md`** under `## [Unreleased]`. CI fails any PR touching
+   `src/`, `wasm/`, `python/`, `tests/` or `Cargo.toml` without one.
+5. Open the PR against `main`.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+Apache 2.0 License.