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

Programmatic API

import { run } from "mejora";

const result = await run();
// with options (config is loaded from disk by default)
const resultWithOptions = await run({ force: true });

Configuration

Create one of:

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

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

export default defineConfig({
  checks: [
    eslint({
      name: "no-nested-ternary",
      files: ["src/**/*.{ts,tsx,js,jsx}"],
      rules: {
        "no-nested-ternary": "error",
      },
    }),
    typescript({
      name: "no-implicit-any",
      compilerOptions: {
        noImplicitAny: true,
      },
    }),
    regex({
      name: "no-todos",
      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 check’s name is used as its ID in the baseline and output.

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

Define custom checks using defineCheck():

import { defineConfig, defineCheck } from "mejora";
import { glob, readFile } from "node:fs/promises";

const noHardcodedUrls = defineCheck<{ files: string[] }>({
  type: "no-hardcoded-urls",
  async run(config) {
    const violations = [];

    for await (const file of glob(config.files, { cwd: process.cwd() })) {
      const content = await readFile(file, "utf-8");
      const lines = content.split("\n");

      for (let i = 0; i < lines.length; i++) {
        const line = lines[i];
        const matches = line.matchAll(/https?:\/\/[^\s'"]+/g);

        for (const match of matches) {
          violations.push({
            file,
            line: i + 1,
            column: match.index + 1,
            rule: "no-hardcoded-urls",
            message: `Hardcoded URL found: ${match[0]}`,
          });
        }
      }
    }

    return violations;
  },
});

export default defineConfig({
  checks: [
    noHardcodedUrls({
      name: "urls-in-src",
      files: ["src/**/*.ts"],
    }),
    noHardcodedUrls({
      name: "urls-in-lib",
      files: ["lib/**/*.ts"],
    }),
  ],
});

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.