redocly-cli

# Contributing to Redocly CLI with AI assistants

AI-assisted contributions are welcome, but the bar is the same as for any other code: a change must be simple, readable, tested, and explainable by the person who opens the pull request.
This file tells an AI assistant — and its human — how to produce a change that fits Redocly CLI and survives review.

It is the single source of truth for AI tools, read from the repository root — directly or through a tool-specific pointer file.
The detailed operating rules live in [`.claude/rules/`](./.claude/rules), and the sections below link to them for the full depth.
For full development setup, the complete test command reference, and the release flow, see [`CONTRIBUTING.md`](./CONTRIBUTING.md).

## How we work

- Write the simplest code that solves the problem and matches the surrounding file.
  Don't add wrappers, layers, or abstractions for something used in one place.
- Every PR is reviewed in details: code that can't be explained gets rejected.
  If you can't say why a line is there, remove it.
- Push back when something looks wrong.
  A good contribution argues for the better solution instead of agreeing with every instruction.
- Base changes on what the code and configuration actually do, not on assumptions.
  Read the relevant file before you change it.
- Use plain English in comments, commit messages, and PR descriptions — no filler and no marketing tone.
- For experimental features, follow the [experimental features checklist](./CONTRIBUTING.md#experimental-features) in the contributing guide.

The principles behind this, ordered by value, are in [`.claude/rules/core-principles.md`](./.claude/rules/core-principles.md).

## Commands

```bash
# Install dependencies
npm install

# Compile TypeScript (required before running tests)
npm run compile

# Type checking only (no emit)
npm run typecheck

# Run all unit tests
npm run unit

# Run a single test file
npm run unit -- packages/core/src/__tests__/some.test.ts

# Run tests matching a name pattern
npm run unit -- -t 'test name pattern'

# Update snapshots
npm run unit -- -u

# Run e2e tests (everything under tests/e2e except generate-client)
npm run e2e

# Run the generate-client e2e tests (they compile real Python/Go/PHP/TypeScript output)
npm run client-generators

# Run the full test suite (compile + typecheck + unit + e2e)
npm test

# Lint
npm run lint

# Format
npm run format

# Run the CLI directly from source
npm run cli -- lint openapi.yaml
```

## Architecture

Where each package sits, and the key directories inside it, are in
[`.claude/rules/architecture.md`](./.claude/rules/architecture.md) — read it before a change lands
in the wrong package.

## Build System

`packages/core`, `packages/respect-core`, `packages/reunite-integration`, and `packages/client-generator` are compiled by TypeScript (`tsc -b tsconfig.build.json`).
`packages/cli` is bundled by esbuild (`packages/cli/scripts/build.mjs`) — it produces `lib/index.js` (entry chunk, ~450 kB) and lazy chunks under `lib/chunks/` (redoc + react, loaded only when `build-docs` runs).
The root `npm run compile` runs both steps: tsc for the compiled packages, then the esbuild bundle for the CLI.

The published CLI package ships from a staged `.publish/` directory (created by `packages/cli/scripts/prepare-publish-dir.mjs`) with a hand-crafted `package.json` that has zero runtime dependencies — everything is bundled.

## Respect the architecture: Walker, Visitors, Nodes

Every traversal of an API description in this repository — linting, bundling, decorating, and the CLI commands that read a description — rests on one pattern: the **Walker** traverses the parsed API description, resolves `$ref`s, and calls **Visitors** — objects keyed by **Node** type — through their `enter` / `leave` / `skip` hooks at every node.
Every rule, decorator, and preprocessor is a visitor.
Write new ones as visitors: a visitor already hands you the typed node, so reach for it before a regular expression or manual drilling into the document object.
A regex belongs only where a visitor cannot get you the value, such as the text inside one string.
What each `enter` / `leave` / `skip` hook receives and when it runs, the fields of the `ctx` object, and a worked rule are in [`.claude/rules/walker-visitors-nodes.md`](./.claude/rules/walker-visitors-nodes.md).

## Add or change a built-in rule

A rule is not finished when its logic works.
To avoid a half-wired rule, a new rule must also be:

- Registered in the spec index (for example `packages/core/src/rules/oas3/index.ts`).
- Added to the `minimal`, `recommended`, `recommended-strict`, `spec`, and `all` rulesets with sensible severities — the defaults are `off` or `warn` for `minimal` and `recommended`, and `error` for `all`.
- Added to the built-in rules list in `packages/core/src/types/redocly-yaml.ts`.
- Documented: a new page under `docs/@v2/`, a link from the built-in rules list and the sidebar, plus updates to the rulesets and ruleset-templates pages.

Naming and reuse:

- If the rule enforces a specification requirement, prefix its name with `spec-` and add it to the spec ruleset in `packages/core/src/config/spec.ts`.
- If the same concept already exists for another spec flavor, reuse that rule name so it stays discoverable across specs.
- Boolean options default to `false`.
  Name each of them according to what makes `true`, so that adding them never alters the existing behavior.
- Prefer real rule code over assertion-based (`redocly.yaml`) rules when contributing to the core rule set.

## Testing

- **Compile before testing.** Unit tests import from `lib/` (compiled output), not `src/` — run `npm run compile` after every change.
  Do not work around the compile step with aliases, `tsconfig` changes, or a separate test suite for one package.
  The slow `client-generators` e2e suite is the one exception.
- Cover the feature or fix with one focused test, not a pile of redundant ones.
  A single clear test that exercises the behavior is enough.
- Rule unit tests parse a YAML document, run `lintDocument`, and assert with `toMatchInlineSnapshot` so the whole output stays visible.
  Generate or update snapshots as part of the change.
  When the rule must report no problems, assert `toEqual([])`.
- Base the API description in a new test on the Redocly Cafe API (`resources/cafe.yaml` or `resources/cafe-split/`) when you can.
  Copy only the part the test needs.
- Don't add `console.log` or write to `stdout` / `stderr` directly — it breaks the e2e snapshots.
  Use the `logger` from `@redocly/openapi-core` (see [`CONTRIBUTING.md`](./CONTRIBUTING.md#logging)).
- A `redocly.yaml` in the repository root affects unit tests in the CLI package.
  Remove it before running them.
- Run the full suite (`npm test`) before you open a pull request.
- Run `npm run client-generators` when you touch client generation.

The full testing and QA rules — including the rule test pattern to copy — are in
[`.claude/rules/testing.md`](./.claude/rules/testing.md).

## Code quality — no AI slop

Before opening a PR, strip the things an assistant tends to add that a human reviewer would not:

- Comments that restate the code or don't match the file's existing comment density.
- Defensive `try/catch` or null checks in trusted, already-validated code paths.
- Casts to `any` to silence the type checker — fix the type instead.
- Helpers or wrappers used in only one place.
- Imports of another package's source files by path (`'core/src/typings/openapi.js'`).
  Import from the package name, such as `@redocly/openapi-core`, instead.
- Single-letter or abbreviated names (`m`, `p`, `e`).
  Use descriptive names like `pkgRootMatch`, `inputPath`, `error`.
  This applies across every package and script.

The full list of practices this repo enforces is in [`.claude/rules/code-quality-standards.md`](./.claude/rules/code-quality-standards.md).

## Documentation and user-facing output

- Update the docs for every new or changed rule, decorator, option, or command — a feature without docs is incomplete.
- Update the agent skills under `.claude/skills/` that describe what you changed, for example `redocly-cli` when a command or option changes.
- Keep user-facing output (CLI messages, warnings, errors) clear, non-technical, and actionable.
- Don't create explanation, summary, or design files unless asked.
  Put the explanation in the PR description.

The full documentation and output rules are in [`.claude/rules/documentation.md`](./.claude/rules/documentation.md).

## Changesets and commits

The full release and commit workflow is in [`.claude/rules/workflow.md`](./.claude/rules/workflow.md).

- Every feature or fix needs a changeset: run `npx changeset` and describe the change in sentence case.
  If the change lives in `packages/core`, `packages/respect-core`, or `packages/reunite-integration` but affects CLI behavior, include `@redocly/cli` as well.
  All four packages share one version and release together.
- Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.
- Don't add AI co-author or "Generated by" lines to commits.
- Don't modify the pull request template.
- Let the contributor review and make the commit — don't commit automatically.

## Security basics

The full security guidelines are in [`.claude/rules/security-guidelines.md`](./.claude/rules/security-guidelines.md).

- Never hardcode credentials, tokens, or secrets.
- Validate and type-check external input (configuration, CLI arguments, fetched documents) before using it.
- Don't use `eval` or build shell commands from unsanitised input.

More agent context in Redocly/redocly-cli

6 other files this repository gives its agents.