gherkin-lint-plus

A Gherkin linter for .feature files, implemented in TypeScript and built on @cucumber/gherkin. It aims to be a modern, maintainable take on the same idea as the original gherkin-lint CLI.

Requirements: Node.js >=20.

Install

npm install gherkin-lint-plus

From a git checkout (development):

cd gherkin-lint-plus
npm install
npm run build

npm run build runs the unit tests first, then compiles to dist/.

Usage

You need a config file in the current working directory unless you pass -c (see below).

npx gherkin-lint-plus [options] [files...]

No arguments: lints all **/*.feature under ., respecting ignore rules.
Paths: files, directories, or globs; directories are expanded to **/*.feature under them.

CLI options

Option	Description
`-c, --config [path]`	Config file (default: `.gherkin-lintrc` in cwd)
`-f, --format [format]`	Output format; only `stylish` is supported today
`-i, --ignore <items>`	Comma-separated ignore globs (overrides `.gherkin-lintignore` if present)
`-r, --rulesdir <dir>`	Extra directory of custom rules (repeatable); see Custom rules

Exit code 1 if any file has lint errors.

Configuration file

The default name is .gherkin-lintrc in your working directory. Contents are JSON with optional comments (JSONC). Use -c / --config if the file lives elsewhere.

Each key is a rule name. Allowed values:

Form	Meaning
`"on"`	Rule enabled with default options (or no extra options).
`"off"`	Rule disabled (not allowed for mandatory rules).
`["on", <options>]`	Rule enabled; `<options>` is an object for most rules, or a string where documented (e.g. `new-line-at-eof`, `no-dupe-scenario-names`).
`["off", <options>]`	Rule disabled (same restriction for mandatory rules).

Optional rules are off if omitted from the config.

Mandatory rules always run. You may omit them or set "on" / ["on", …]; you must not set them to "off" or ["off", …] (the CLI reports a configuration error).

Example `.gherkin-lintrc`

{
  "indentation": "on",
  "no-trailing-spaces": "on",
  "file-name": ["on", { "style": "kebab-case" }],
  "new-line-at-eof": ["on", "yes"]
}

Ignoring feature files

Add .gherkin-lintignore in the working directory: one glob pattern per line.
Or use -i / --ignore with comma-separated globs (this overrides the ignore file when provided).

If there is no ignore file and you did not pass -i, node_modules/** is ignored by default.

Built-in rules summary

Rule name	Category	In `.gherkin-lintrc`?	Enable example
`no-tags-on-backgrounds`	Parse	No — fix the `.feature` file	—
`one-feature-per-file`	Parse	No	—
`up-to-one-background-per-file`	Parse	No	—
`no-multiline-steps`	Parse	No	—
`unexpected-error`	Parse	No (other parse failures)	—
`no-empty-file`	Mandatory	Yes (cannot turn off)	Omit, or `"no-empty-file": "on"`
`no-files-without-scenarios`	Mandatory	Yes (cannot turn off)	Omit, or `"on"`
`no-unnamed-features`	Mandatory	Yes (cannot turn off)	Omit, or `"on"`
`no-unnamed-scenarios`	Mandatory	Yes (cannot turn off)	Omit, or `"on"`
`allowed-tags`	Optional	Yes	`"allowed-tags": "on"` + options (see below)
`file-name`	Optional	Yes	`"file-name": ["on", { "style": "PascalCase" }]`
`indentation`	Optional	Yes	`"indentation": "on"` or `["on", { … }]`
`keywords-in-logical-order`	Optional	Yes	`"keywords-in-logical-order": "on"`
`max-scenarios-per-file`	Optional	Yes	`"max-scenarios-per-file": ["on", { … }]`
`name-length`	Optional	Yes	`"name-length": ["on", { … }]`
`new-line-at-eof`	Optional	Yes	`"new-line-at-eof": ["on", "yes"]`
`no-background-only-scenario`	Optional	Yes	`"no-background-only-scenario": "on"`
`no-dupe-feature-names`	Optional	Yes	`"no-dupe-feature-names": "on"`
`no-dupe-scenario-names`	Optional	Yes	`"on"` or `["on", "in-feature"]`
`no-duplicate-tags`	Optional	Yes	`"no-duplicate-tags": "on"`
`no-empty-background`	Optional	Yes	`"no-empty-background": "on"`
`no-examples-in-scenarios`	Optional	Yes	`"no-examples-in-scenarios": "on"`
`no-homogenous-tags`	Optional	Yes	`"no-homogenous-tags": "on"`
`no-multiple-empty-lines`	Optional	Yes	`"no-multiple-empty-lines": "on"`
`no-partially-commented-tag-lines`	Optional	Yes	`"no-partially-commented-tag-lines": "on"`
`no-restricted-patterns`	Optional	Yes	`["on", { … }]`
`no-restricted-tags`	Optional	Yes	`["on", { "tags": [], "patterns": [] }]`
`no-scenario-outlines-without-examples`	Optional	Yes	`"no-scenario-outlines-without-examples": "on"`
`no-superfluous-tags`	Optional	Yes	`"no-superfluous-tags": "on"`
`no-trailing-spaces`	Optional	Yes	`"no-trailing-spaces": "on"`
`no-unused-variables`	Optional	Yes	`"no-unused-variables": "on"`
`one-space-between-tags`	Optional	Yes	`"one-space-between-tags": "on"`
`only-one-when`	Optional	Yes	`"only-one-when": "on"`
`required-tags`	Optional	Yes	`["on", { … }]`
`scenario-size`	Optional	Yes	`["on", { "steps-length": { … } }]`
`use-and`	Optional	Yes	`"use-and": "on"`

Parse rules are emitted when the Gherkin parser rejects the file. They are not toggled in config; correct the source. Mandatory rules always run and cannot be disabled.

Backgrounds: you may have one optional Background under Feature, and one optional Background inside each Rule:. up-to-one-background-per-file fires when a second Background appears in the same scope (duplicate at feature level or duplicate inside one rule).

Rule reference

Parse-time rules (not configurable)

These appear as rule IDs on parse failures. Fix the .feature text; do not add them to .gherkin-lintrc.

Rule	What it checks
`no-tags-on-backgrounds`	Tags are not allowed on `Background`.
`one-feature-per-file`	Only one `Feature:` per file.
`up-to-one-background-per-file`	At most one `Background` in each feature or rule block.
`no-multiline-steps`	Step text must not continue as a random continuation line (use `And`, Doc Strings, or tables).
`unexpected-error`	Other parser errors, surfaced with the raw message.

Mandatory rules

Always evaluated. Use "on" or omit the key; never "off".

`no-empty-file`

What: Whitespace-only or missing feature content is not allowed.

Example:

{
  "no-empty-file": "on"
}

`no-files-without-scenarios`

What: The file must contain at least one scenario (including under Rule:).

Example:

{
  "no-files-without-scenarios": "on"
}

`no-unnamed-features`

What: Feature: must have a name.

Example:

{
  "no-unnamed-features": "on"
}

`no-unnamed-scenarios`

What: Scenario: / Scenario Outline: must have a name.

Example:

{
  "no-unnamed-scenarios": "on"
}

Optional rules

Turn on with "rule-name": "on" or "off" to disable. Use ["on", …] when the rule needs options (below).

`allowed-tags`

What: Only listed tags and patterns are allowed on tag-bearing nodes.

Enable / off:

{
  "allowed-tags": [
    "on",
    { "tags": ["@watch", "@wip"], "patterns": ["^@todo$"] }
  ]
}

{ "allowed-tags": "off" }

`file-name`

What: Basename of *.feature must match a naming style (default PascalCase).

Styles: PascalCase, Title Case, camelCase, kebab-case, snake_case

{
  "file-name": ["on", { "style": "kebab-case" }]
}

`indentation`

What: Checks column positions for keywords, tags, steps, and example tables. Defaults: feature-level keywords at 0; steps and table rows at 2 spaces. Override per keyword type; localized Gherkin keywords are supported.

{
  "indentation": [
    "on",
    {
      "Feature": 0,
      "Background": 0,
      "Rule": 0,
      "Scenario": 0,
      "Step": 2,
      "Examples": 0,
      "example": 2,
      "given": 2,
      "when": 2,
      "then": 2,
      "and": 2,
      "but": 2,
      "feature tag": 0,
      "scenario tag": 0
    }
  ]
}

`keywords-in-logical-order`

What: Given / When / Then order should follow a sensible flow.

{ "keywords-in-logical-order": "on" }

`max-scenarios-per-file`

What: Caps how many “scenarios” count per file (plain scenarios count as 1; outlines can count each example row).

Options: maxScenarios (default 10), countOutlineExamples (default true)

{
  "max-scenarios-per-file": [
    "on",
    { "maxScenarios": 10, "countOutlineExamples": true }
  ]
}

`name-length`

What: Max length for Feature, Rule, Scenario, and step text (default 70 each).

{
  "name-length": [
    "on",
    { "Feature": 70, "Rule": 70, "Scenario": 70, "Step": 70 }
  ]
}

`new-line-at-eof`

What: Require or forbid a newline at end of file. Must use a string option: "yes" or "no".

{ "new-line-at-eof": ["on", "yes"] }

{ "new-line-at-eof": ["on", "no"] }

`no-background-only-scenario`

What: If there is only one scenario, a Background is not allowed (feature level or inside a Rule).

{ "no-background-only-scenario": "on" }

`no-dupe-feature-names`

What: The same feature name must not appear in more than one linted file (cross-file state).

{ "no-dupe-feature-names": "on" }

`no-dupe-scenario-names`

What: Duplicate scenario names. String option: "anywhere" (default, cross-file) or "in-feature" (per feature only).

{ "no-dupe-scenario-names": "on" }

{ "no-dupe-scenario-names": ["on", "in-feature"] }

`no-duplicate-tags`

What: No duplicate tags on the same feature, rule, or scenario.

{ "no-duplicate-tags": "on" }

`no-empty-background`

What: Background must contain at least one step.

{ "no-empty-background": "on" }

`no-examples-in-scenarios`

What: Examples belongs on scenario outlines, not plain scenarios.

{ "no-examples-in-scenarios": "on" }

`no-homogenous-tags`

What: If every scenario shares the same tag(s), prefer moving those tags to the feature (or avoid redundant tagging).

{ "no-homogenous-tags": "on" }

`no-multiple-empty-lines`

What: No runs of multiple blank lines.

{ "no-multiple-empty-lines": "on" }

`no-partially-commented-tag-lines`

What: Tag lines must not be partially commented in a misleading way.

{ "no-partially-commented-tag-lines": "on" }

`no-restricted-patterns`

What: Ban regex patterns (case-insensitive) in names, descriptions, and step text. Keys: Global, Feature, Rule, Background, Scenario, ScenarioOutline. Match step text only (not the Given/When keyword).

{
  "no-restricted-patterns": [
    "on",
    {
      "Global": ["^globally restricted"],
      "Feature": ["poor description"],
      "Background": [],
      "Scenario": [],
      "Rule": [],
      "ScenarioOutline": []
    }
  ]
}

`no-restricted-tags`

What: Disallow specific @tags and patterns.

{
  "no-restricted-tags": [
    "on",
    { "tags": ["@watch"], "patterns": ["^@todo$"] }
  ]
}

`no-scenario-outlines-without-examples`

What: Every scenario outline must have Examples.

{ "no-scenario-outlines-without-examples": "on" }

`no-superfluous-tags`

What: Tags repeated on both feature and scenarios inside that feature are flagged.

{ "no-superfluous-tags": "on" }

`no-trailing-spaces`

What: No trailing spaces on lines.

{ "no-trailing-spaces": "on" }

`no-unused-variables`

What: Scenario outline placeholders must match Examples headers (no unused columns, no missing columns).

{ "no-unused-variables": "on" }

`one-space-between-tags`

What: Multiple tags on one line must be separated by a single space.

{ "one-space-between-tags": "on" }

`only-one-when`

What: At most one When step per scenario.

{ "only-one-when": "on" }

`required-tags`

What: Scenarios must match tag regexes. Options: tags (regex strings), ignoreUntagged (default true — untagged scenarios skipped).

{
  "required-tags": [
    "on",
    { "tags": ["^@issue:[1-9]\\d*$"], "ignoreUntagged": false }
  ]
}

`scenario-size`

What: Max steps per Background (feature level), Scenario (feature-level scenarios/outlines), and everything under a Rule (uses the Rule limit).

{
  "scenario-size": [
    "on",
    {
      "steps-length": {
        "Rule": 15,
        "Background": 15,
        "Scenario": 15
      }
    }
  ]
}

`use-and`

What: Repeated same step keyword (Given, When, …) should use And / But instead.

{ "use-and": "on" }

Custom rules

Use -r / --rulesdir one or more times. Each path must be a directory (absolute or relative to cwd). The linter loads every *.ts file in that directory (not subfolders). Files are compiled at runtime with jiti; JavaScript rule files are not supported.

Each module must default-export a rule object:

import type { Feature } from '@cucumber/messages';

const name = 'my-rule';

export default {
  name,
  run(
    feature: Feature | undefined,
    file: { relativePath: string; lines: string[] },
    config: unknown
  ) {
    return [{ message: '…', rule: name, line: 1 }];
  },
  availableConfigs: [] as const,
};

name — must match the key in .gherkin-lintrc.
run — returns { message, rule, line }[], or undefined / [] if OK. config is the second part of ["on", …] when present, else {}.
availableConfigs — [] if only "on"/"off"; otherwise a string array (allowed string options) or an object whose keys are allowed option names.

If two files define the same name, the one loaded last wins.

Add @cucumber/messages (and optionally typescript) to your project for typing. See built-in rules under src/rules/ and the rulesdir fixture.

Development

Script	Purpose
`npm test`	Run Vitest once
`npm run test:watch`	Vitest watch mode
`npm run test:coverage`	Tests + coverage (HTML & LCOV under `coverage/`)
`npm run build`	Tests, then `tsc`
`npm start`	Run `node dist/main.js` (after build)

Limitations (current)

Output: only the stylish formatter; json / xunit are not implemented.

License

ISC

Name		Name	Last commit message	Last commit date
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

gherkin-lint-plus

Install

Usage

CLI options

Configuration file

Example .gherkin-lintrc

Ignoring feature files

Built-in rules summary

Rule reference

Parse-time rules (not configurable)

Mandatory rules

no-empty-file

no-files-without-scenarios

no-unnamed-features

no-unnamed-scenarios

Optional rules

allowed-tags

file-name

indentation

keywords-in-logical-order

max-scenarios-per-file

name-length

new-line-at-eof

no-background-only-scenario

no-dupe-feature-names

no-dupe-scenario-names

no-duplicate-tags

no-empty-background

no-examples-in-scenarios

no-homogenous-tags

no-multiple-empty-lines

no-partially-commented-tag-lines

no-restricted-patterns

no-restricted-tags

no-scenario-outlines-without-examples

no-superfluous-tags

no-trailing-spaces

no-unused-variables

one-space-between-tags

only-one-when

required-tags

scenario-size

use-and

Custom rules

Development

Limitations (current)

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Example `.gherkin-lintrc`

`no-empty-file`

`no-files-without-scenarios`

`no-unnamed-features`

`no-unnamed-scenarios`

`allowed-tags`

`file-name`

`indentation`

`keywords-in-logical-order`

`max-scenarios-per-file`

`name-length`

`new-line-at-eof`

`no-background-only-scenario`

`no-dupe-feature-names`

`no-dupe-scenario-names`

`no-duplicate-tags`

`no-empty-background`

`no-examples-in-scenarios`

`no-homogenous-tags`

`no-multiple-empty-lines`

`no-partially-commented-tag-lines`

`no-restricted-patterns`

`no-restricted-tags`

`no-scenario-outlines-without-examples`

`no-superfluous-tags`

`no-trailing-spaces`

`no-unused-variables`

`one-space-between-tags`

`only-one-when`

`required-tags`

`scenario-size`

`use-and`