# Build Tooling

Convert Plus uses **Grunt** as the primary build runner and **npm** for package management. The `@wordpress/scripts` package provides linting tooling.

## Prerequisites

- Node.js (check `.nvmrc` or `package.json` engines if present)
- npm

```bash
npm install
```

## Package Manager

Use **npm** for this project (not pnpm or yarn).

## npm Scripts

Defined in the root `package.json`:

| Script | Command | Description |
|--------|---------|-------------|
| `lint:js` | `wp-scripts lint-js --fix` | Lint and auto-fix JavaScript files |
| `lint:js:fix` | `wp-scripts lint-js --fix` | Same as above |
| `lint:css` | `wp-scripts lint-style --fix` | Lint and auto-fix CSS/SCSS files |
| `lint:css:fix` | `wp-scripts lint-style --fix` | Same as above |
| `lint:pkg-json` | `wp-scripts lint-pkg-json` | Validate package.json |
| `check-engines` | `wp-scripts check-engines` | Verify Node/npm engine compatibility |
| `i18n` | `grunt i18n && wp i18n make-pot ...` | Extract translatable strings |
| `i18n:po` | `wp i18n update-po lang/smile.pot` | Update `.po` files from `.pot` |
| `i18n:mo` | `wp i18n make-mo lang` | Compile `.po` to `.mo` binary files |
| `i18n:json` | `wp i18n make-json lang --no-purge` | Generate JS translation JSON files |

## Grunt Tasks (Root `Gruntfile.js`)

The root Gruntfile handles plugin-level tasks. Grunt plugins used:

| Plugin | Purpose |
|--------|---------|
| `grunt-contrib-uglify` | Minify JavaScript |
| `grunt-contrib-cssmin` | Minify CSS |
| `grunt-contrib-clean` | Clean build artifacts |
| `grunt-contrib-copy` | Copy files to artifact/release directory |
| `grunt-contrib-compress` | Create ZIP archives for releases |
| `grunt-bumpup` | Bump version numbers across files |
| `grunt-text-replace` | Find/replace version strings |
| `grunt-rtlcss` | Generate RTL CSS variants |
| `grunt-postcss` + `autoprefixer` | Add CSS vendor prefixes |
| `grunt-wp-i18n` | WordPress i18n string extraction |
| `grunt-json2php` | Convert JSON to PHP arrays |

## Per-Module Grunt Files

Each module has its own `Gruntfile.js` and `package.json` for module-specific asset compilation:

- `modules/modal/Gruntfile.js`
- `modules/slide_in/Gruntfile.js`
- `modules/info_bar/Gruntfile.js`

These compile module-specific JS and CSS independently.

## Linting Configuration

### JavaScript

Uses `@wordpress/scripts` ESLint configuration. Run:

```bash
npm run lint:js
```

### CSS / SCSS

Uses `@wordpress/stylelint-config`. Run:

```bash
npm run lint:css
```

### PHP (PHPCS/WPCS)

Configuration is in `phpcs.xml.dist`. Ruleset applies:

- `PHPCompatibility` (targeting PHP 5.3+)
- `WordPress-Core`
- `WordPress-Docs`
- `WordPress-Extra`

Run:

```bash
composer run lint
# or for auto-fix:
composer run format
```

**Excluded from PHPCS:**
- `node_modules/`, `vendor/`, `lib/`, `framework/`
- `admin/bsf-core/`, `admin/bsf-analytics/`
- Some specific theme files

### PHPStan

Configuration in `phpstan.neon`. Level 9 (strictest). Run:

```bash
composer run phpstan
```

Paths analysed: `framework/classes`, `framework/functions`, `convertplug.php`, `modules/`, `classes/`, `admin/`, `lang/`

Excluded: `admin/bsf-core/class-bsf-wp-cli-command.php`

## Internationalisation (i18n)

Text domain: `smile`

Translation files in `lang/`:

| File | Description |
|------|-------------|
| `lang/smile.pot` | Master translation template |
| `lang/smile-{locale}.po` | Human-editable translations |
| `lang/smile-{locale}.mo` | Compiled binary translations (loaded by WordPress) |
| `lang/smile-{locale}-{hash}.json` | JS translations for `@wordpress/i18n` |

### Updating Translations

```bash
# 1. Extract strings into .pot
npm run i18n

# 2. Update .po files with new strings
npm run i18n:po

# 3. Compile .mo files
npm run i18n:mo

# 4. Generate JS JSON files
npm run i18n:json
```

## Generating PHPStan Stubs

When you need to regenerate the plugin's own stubs (for PHPStan analysis):

```bash
composer run gen-stubs
```

This runs `generate-stubs` on a built artifact directory and outputs to `tests/php/stubs/convertplug-stubs.php`.

## Related Pages

- [Contributing Guide](Contributing-Guide)
- [Testing Guide](Testing-Guide)
- [Environment Configuration](Environment-Configuration)