Quickstart

This example requires each text file in config/ to start with /internal/. It uses a regular expression and makes no AI calls.

Install

Use Node.js ^24.15.0 || >=26.0.0. The CLI command is coderuler. The npm package name is @alex-dbs/coderuler.

For a project-local installation, run these commands from your project root:

npm install --save-dev @alex-dbs/coderuler
npx coderuler --help
npx coderuler --version

This guide uses npx coderuler. If you prefer a global installation, run npm install -g @alex-dbs/coderuler and use coderuler instead. A global CLI can load rules without a project-local SDK dependency.

Use coderuler update for a global npm installation. See the update commands for project-local installations.

To use an unreleased source checkout instead of the npm package:

git clone https://github.com/alex-dbs/coderuler.git
cd coderuler
npm ci
npm run build
npm start -- --help

From another project’s root, invoke the built CLI with node /absolute/path/to/coderuler/dist/cli.js instead of npx coderuler.

Save a rule and its tests

Create .coderuler/internal-url.rule.ts in your project. Copy this complete module:

import { Rule, regex, test } from '@alex-dbs/coderuler';

export default class InternalUrl extends Rule {
  files = ['config/*.txt'];
  check = regex({ pattern: /^\/internal\//, violationMessage: 'Use an /internal/ URL' });
}
export const tests = [
  test('internal URL passes').withFiles({ 'config/url.txt': '/internal/jobs' }).passes(),
  test('public URL violates').withFiles({ 'config/url.txt': '/public/jobs' }).violates(),
];

The filename gives this rule the name internal-url. The files property selects root-relative paths. Without a scope selector, the check receives each whole file separately.

regex() treats a match as a pass. A nonmatch is a violation. The tests create temporary files, so they do not write config/url.txt into your project.

Validate and test

Run these commands from your project root:

npx coderuler validate .coderuler/internal-url.rule.ts
npx coderuler test .coderuler/internal-url.rule.ts

If the module meets the rule contract, validation prints Valid rule: internal-url and exits with status 0. It does not evaluate the policy or type-check TypeScript.

The test command runs both cases. Both tests pass: the second case expects a violation. Successful tests exit with status 0.

See what the rule selected

Inspection runs the rule on real project files and shows its pipeline:

npx coderuler inspect .coderuler/internal-url.rule.ts .

If no files match, the rule does not evaluate a subject. A skip does not prove that the policy works. Keep both passing and violating tests, and inspect representative files.

Next, read how it works or writing rules. This example also appears in the rule author reference.