mejora

Prevent regressions. Allow improvement. mejora (Spanish for "improvement")

mejora runs checks, compares them to a stored baseline, and fails only when things get worse.

Behavior

Each check produces a snapshot.

Snapshots are compared against a baseline.

• New items are regressions and fail the run
• Removed items are improvements and pass the run

Snapshots use the items format to represent issues:

{
  "checks": {
    "eslint": {
      "type": "items",
      "items": [
        {
          "id": "a1b2c3d4...",
          "file": "src/example.ts",
          "line": 12,
          "column": 5,
          "rule": "no-unused-vars",
          "message": "'foo' is declared but never used"
        }
      ]
    }
  }
}

[!NOTE] Issue identifiers (id) are stable across runs and generally insensitive to code movement, while remaining unique for repeated issues.

The baseline represents the last accepted state and should be committed to the repository.

Default location:

.mejora/baseline.json

When a run produces fewer items than the baseline, the run passes and the baseline is updated automatically.

Regressions fail the run.

mejora --force updates the baseline even when regressions are present.

Output

Output is non-interactive and deterministic.

• Plain text by default
• Markdown output for human-friendly review and navigation
• --json produces structured output for CI and automation

Exit Codes

• 0 pass or improvement
• 1 regression detected or baseline out of sync
• 2 configuration or runtime error

Installation

pnpm add -D mejora

[!NOTE] mejora requires Node.js 22.18.0 or later.

Usage

Run checks:

pnpm mejora

Force the baseline to accept regressions:

pnpm mejora --force

JSON output for CI and automation:

pnpm mejora --json

Run only a subset of checks:

pnpm mejora --only "eslint > *"

Skip checks:

pnpm mejora --skip typescript

Configuration

Create one of:

• mejora.config.ts
• mejora.config.js
• mejora.config.mjs
• mejora.config.mts

Example:

import { defineConfig, eslint, regex, regexRunner, typescript } from "mejora";

export default defineConfig({
  runners: [regexRunner()],
  checks: {
    "eslint > no-nested-ternary": eslint({
      files: ["src/**/*.{ts,tsx,js,jsx}"],
      overrides: {
        rules: {
          "no-nested-ternary": "error",
        },
      },
    }),
    "typescript > noImplicitAny": typescript({
      overrides: {
        compilerOptions: {
          noImplicitAny: true,
        },
      },
    }),
    "no-todos": regex({
      files: ["src/**/*"],
      patterns: [
        {
          pattern: /\/\/\s*TODO(?:\((?<owner>[^)]+)\))?:\s*(?<task>.*)/gi,
          message: (match) => {
            const task = match.groups?.task?.trim() || "no description";
            const owner = match.groups?.owner;
            const truncated =
              task.length > 80 ? `${task.slice(0, 80)}...` : task;

            return owner ? `[${owner}] ${truncated}` : truncated;
          },
          rule: "todo",
        },
      ],
    }),
  },
});

Each entry in checks is an explicit check.

The object key is the check identifier and is used in the baseline.

Supported Checks

ESLint

• Snapshot type: "items"
• Each lint message is treated as an issue
• Regressions are new issues

[!NOTE] eslint (^9.34.0) is required as a peer dependency when using the ESLint check

TypeScript

• Snapshot type: "items"
• Each compiler diagnostic is treated as an issue
• Regressions are new issues
• Uses the nearest tsconfig.json by default, or an explicit one if provided

[!NOTE] typescript (^5.0.0) is required as a peer dependency when using the TypeScript check

Regex

• Snapshot type: "items"
• Each pattern match is treated as an issue
• Regressions are new matches
• Works on any file type (not just code)

Custom Checks

You can add your own checks by implementing CheckRunner and returning an "items" snapshot.

A custom check is made of two pieces:

• A runner (registered in runners) that knows how to execute your check type
• A check config (declared in checks) that includes a matching type and any options your runner needs

import type { CheckRunner, IssueInput } from "mejora";

interface CustomCheckConfig {
  files: string[];
  // your custom options
}

class CustomCheckRunner implements CheckRunner {
  readonly type = "custom";

  async run(config: CustomCheckConfig) {
    const items: IssueInput[] = [];
    // ...produce IssueInput entries (file/line/column/rule/message)
    return { type: "items", items };
  }
}

Register the runner and declare a check that uses it:

import { defineConfig } from "mejora";

export default defineConfig({
  runners: [new CustomCheckRunner()],
  checks: {
    "my-custom-check": {
      type: "custom",
      files: ["src/**/*.ts"],
      // your custom options
    },
  },
});

CI

When running in CI, mejora does not write the baseline.

Instead, it compares the committed baseline to the expected results from the current codebase.

If there is any difference between the committed baseline and the expected results, the run fails.

Merge Conflicts

mejora can automatically resolve merge conflicts in both baseline.json and baseline.md.

After merging branches, you may see conflicts like:

$ git status
both modified:   .mejora/baseline.json
both modified:   .mejora/baseline.md

Instead of resolving these by hand, simply run mejora:

$ mejora
Merge conflict detected in baseline, auto-resolving...
✔ Baseline conflict resolved

mejora reconciles both sides of the conflict and regenerates a consistent baseline.

Credits

• mejora is inspired by betterer.