eslint-plugin-file-companion

ESLint plugin that forces files matching a glob pattern to have one or more "companion" files next to them (e.g. a Storybook story or a spec/test file).

Install

pnpm add -D eslint-plugin-file-companion

Requires ESLint ^9.0.0 || ^10.0.0 with flat config.

Usage

// eslint.config.js
import fileCompanion from 'eslint-plugin-file-companion';

export default [
  {
    plugins: { 'file-companion': fileCompanion },
    rules: {
      'file-companion/required-companion': [
        'error',
        [
          { files: 'src/**/*.tsx', companion: ['stories.tsx', 'spec.tsx'] },
        ],
      ],
    },
  },
];

Given the config above, src/components/Button.tsx must have both src/components/Button.stories.tsx and src/components/Button.spec.tsx next to it, otherwise the rule reports an error.

Options

required-companion takes a single option: an array of entries.

type RequiredCompanionEntry = {
  files: string | string[];   // glob pattern(s) matched against the file path
  companion: string | string[]; // suffix(es) appended to the file's base name
  contains?: string | string[]; // only apply if the file's content matches one of these
  exceptContains?: string | string[]; // skip the file if its content matches one of these
};

• files — a minimatch glob (or array of globs) matched against the file path relative to the ESLint working directory.
• companion — one or more suffixes. For a file Button.tsx and companion stories.tsx, the plugin checks for Button.stories.tsx in the same directory. All listed companions are required.
• contains — one or more plain strings or regex patterns (written as /pattern/flags, e.g. /export default/). If provided, the entry only applies to files whose content matches at least one of them.
• exceptContains — same syntax as contains, but the entry is skipped for files whose content matches at least one of them.

Multiple entries can be provided to apply different companion requirements to different sets of files.

Development

pnpm install
pnpm build
pnpm test
pnpm lint