# Contributing to KimaAI

Thanks for contributing! This guide covers how to set up a development environment and run every check locally. See `CLAUDE.md` for an architecture overview.

## Requirements

- PHP >= 8.0 (CI tests 8.0–8.4)
- Composer 2
- Node.js >= 20 (see `.nvmrc`; run `nvm use` if you use nvm)

> Older Node versions fail with misleading errors (e.g. `Object.hasOwn is not a function` in Jest, or stylelint crashing on `stripVTControlCharacters`). Check `node -v` first.

## Setup

```bash
composer install
npm install
npm run build
```

Premium development additionally needs `composer install --working-dir=premium` (requires access to the private `kimaai/kimaai-vector-db-sdk` package).

## Running checks

| Check | Command | Notes |
| --- | --- | --- |
| PHP coding standards | `npm run lint:php-check` (fix: `npm run lint:php-fix`) | WordPress standards, see `phpcs.ruleset.xml` |
| PHP static analysis | `composer analyse` | PHPStan level 1 |
| PHP unit tests | `npm run test:unit` | No WordPress/database needed |
| PHP integration tests | `npm run test:integration` | Needs `.env.test` with real provider credentials (copy `.env.example`) |
| JS lint | `npm run lint:js` | |
| CSS lint | `npm run lint:css` | |
| JS unit tests | `npm run test:js` | Jest via `@wordpress/scripts` |
| E2E tests | `npm run test:e2e` | Playwright; needs provider API keys in the environment |
| Everything lintable | `npm run lint` | Runs every `lint:*` script (JS, CSS, markdown, package.json, PHP) |

CI (`.github/workflows/ci.yml`) runs PHPCS, PHPStan, and PHP unit tests on PHP 8.0–8.4, plus the JS build, ESLint, stylelint, and Jest. Integration and e2e tests are not run in CI because they require real provider API keys — run them locally before submitting changes that touch provider integrations or user-facing flows.

## Local WordPress

`npm run server` starts a disposable WordPress via WP Playground with the plugin active. `npm run watch` rebuilds JS/CSS on change.

## i18n

After adding or changing translatable strings (`__('…', 'kimaai')` in PHP or JS), regenerate the translation files:

```bash
npm run i18n
```

If `wp i18n make-pot` runs out of memory, raise the limit: `php -d memory_limit=4G $(which wp) i18n make-pot . languages/kimaai.pot --domain=kimaai --exclude=node_modules,build`.

## Pull requests

- Branch off `master`; never push to `master` directly.
- Keep commits scoped to one logical change each.
- Run the checks above before opening a PR — CI enforces the PHP and JS suites.
- Update `readme.txt` changelog entries as part of release PRs, not feature PRs.

## Secrets

Never commit API keys. Local credentials belong in `.env` / `.env.test` (both git-ignored); `.env.example` documents the expected variables.