# Ruling

> Ruling is an Agent Skill for testing & quality published in the SonarSource/SonarJS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Run ruling integration tests and update expected results for SonarJS rules. Use when running ruling tests or syncing expected ruling output.

- Skill name: `ruling`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/SonarSource/SonarJS/blob/HEAD/.claude/skills/ruling/SKILL.md
- Repository: SonarSource/SonarJS (1,250 GitHub stars when collected)

## SKILL.md

## Overview

Ruling tests analyze large third-party codebases (JS/TS and CSS) and compare issues against expected output. Run them when adding or modifying rules to verify real-world behavior.

> **Warning:** Running ruling tests removes `node_modules` from the project root. Run `npm ci` afterward.

## Running Ruling

```bash
# Prerequisites: init submodules, install dependencies, build JS/TS, then rebuild the jar
git submodule update --init --recursive
npm install
npm run bbf
mvn install -DskipTests

# Run ruling (JS/TS and CSS)
npm run ruling

# Sync actual → expected (after reviewing output)
npm run ruling-sync

# Debug differences
sh tools/ruling-debug-script.sh
```

Results:

- Actual: `packages/ruling/actual/`
- Expected: `its/ruling/src/test/expected/`

## Java Ruling (Old Way)

```bash
cd its/ruling
mvn verify -Dtest=RulingTest -Dmaven.test.redirectTestOutputToFile=false
```

Copy actual to expected:

```bash
cp -R target/actual/ src/test/expected/
```

Review diff:

```bash
diff -rq src/test/expected target/actual
```

## Custom Source Files for New Rules

If a new rule raises no issues on existing sources, add test code:

- `its/sources/custom/jsts/S1234.js` — regular code
- `its/sources/custom/jsts/tests/S1234.js` — test code

Copy from RSPEC HTML description (compliant/non-compliant examples).

## Debugging with Node Process

To debug the Node.js bridge during ruling:

1. Start your Node.js process manually
2. Set `SONARJS_EXISTING_NODE_PROCESS_PORT=<port>`
3. Remove `@Execution(ExecutionMode.CONCURRENT)` from the ruling test class (for serial execution)

## Submodule Setup

If submodules aren't checked out:

```bash
git submodule init
git submodule update
```

---

Source: https://www.openparable.com/skill/testing-quality/ruling (OpenParable). Cite the canonical URL above.
