Rules and categories

A rule checks the module graph and reports violations. Each built-in rule is in one category. A category switches all its rules on or off together.

Categories

Use the categories key to change the level of a category:

export default defineConfig({
  categories: { correctness: "error", suspicious: "error", restriction: "warn" },
});

Levels

A level is off, warn or error.

• off disables the rule.
• warn reports a violation as a warning. A warning does not change the exit code, unless you use --deny-warnings or --max-warnings.
• error reports a violation as an error. An error gives exit code 1.

Configure one rule

A rule in the rules key wins over its category. A rule that its category switches off can still be on here. Give a level, or give an object with a level and the options of the rule. An object without level means error.

export default defineConfig({
  rules: {
    "orphan-modules": "error",
    "circular-dependencies": { level: "error", ignore: ["src/index.ts"] },
    "peer-dependencies": "warn",
  },
});

In overrides, an object without level keeps the level that the rule has for those modules and replaces the options. Oxcruise reserves the name level. No rule has an option with this name.

Oxcruise checks the options of every rule. It stops with the name of the rule and the option when an option is not valid.

List the rules

Run npx oxcruise --rules to list the built-in rules by category. Add -f json for JSON. The rules reference has one page for each rule.

Other kinds of rules

• Forbid rules are your own rules for dependencies that the project does not allow.
• Layers and visibility are two built-in rules for architecture.
• Folder structure is a built-in rule for the shape of the file tree.
• A JS plugin can add rules that you write in TypeScript.

Cycles and suppression

Oxcruise reports a cycle once, and not once for each dependency in it. A cycle counts as suppressed when one of its dependencies has an ignore comment.