# Contributing

## Prerequisites

- Node.js 18 or later
- pnpm 10 or later
- [Emscripten](https://emscripten.org/docs/getting_started/downloads.html) (only for recompiling the WASM module)

On macOS, Emscripten is available via Homebrew:

```sh
brew install emscripten
```

## Building from source

Clone the repository, install dependencies, and build the TypeScript:

```sh
git clone https://github.com/acamarata/solar-spa.git
cd solar-spa
pnpm install
pnpm run build:ts
```

To recompile the WASM module (requires Emscripten):

```sh
pnpm run build:wasm
```

Or build everything at once:

```sh
pnpm run build
```

## Running tests

```sh
pnpm test
```

This runs both the ESM test suite (`test.mjs`, 66 assertions) and the CJS smoke test (`test-cjs.cjs`). Tests cover multiple geographic locations, seasons, input validation, error handling, concurrent initialization, polar regions, boundary coordinates, and all SPA function codes.

## Type checking

```sh
pnpm run typecheck
```

## Project structure

```
src/
  index.ts           # Main implementation (TypeScript source)
  types.ts           # Type definitions and constants
  spa.c              # NREL SPA algorithm (do not modify)
  spa.h              # NREL SPA header (do not modify)
  spa_wrapper.c      # Flat wrapper for WASM boundary
wasm/
  spa-module.js      # Compiled WASM output (~60KB, inlined as base64)
dist/                # Generated by tsup (CJS + ESM + declarations)
  index.cjs
  index.mjs
  index.d.ts         # CJS declarations
  index.d.mts        # ESM declarations
test.mjs             # ESM test suite
test-cjs.cjs         # CJS smoke test
tsup.config.ts       # Build configuration
tsconfig.json        # TypeScript configuration
```

## Guidelines

- Do not modify `spa.c` or `spa.h`. These are the original NREL source files and should remain identical to the NREL distribution.
- Changes to `spa_wrapper.c` that add new output fields require corresponding changes in `src/index.ts` (the OFFSET map and `readResult` function) and `src/types.ts` (the result interfaces).
- Run `pnpm test` and `pnpm run typecheck` before submitting. All tests and type checks should pass.
- The test suite uses approximate comparisons (`approx` with a tolerance) because floating-point results vary slightly across platforms and Emscripten versions.

## Reporting bugs

Open an issue at [github.com/acamarata/solar-spa/issues](https://github.com/acamarata/solar-spa/issues). Include:

- Node.js version (`node --version`)
- The input parameters that produced the unexpected result
- Expected vs actual output

---

[Home](Home) · [Architecture](Architecture) · [API Reference](API-Reference)