Plugin Development¶

Plugins extend behave-lint with custom rules, reporters, or configuration providers.

Plugin types¶

Type	Entry point group	Description
Rules	`behave_lint.rules`	Custom lint rules
Reporters	`behave_lint.reporters`	Custom output formats
Config	`behave_lint.config_sources`	Configuration providers

Quick start with the cookiecutter template¶

The fastest way to create a plugin is using the cookiecutter template included in this repository:

# Install cookiecutter
pip install cookiecutter

# Generate a plugin from the template
cookiecutter https://github.com/MathiasPaulenko/behave-lint --directory templates/cookiecutter-plugin

You'll be prompted for:

Field	Description	Example
`project_name`	PyPI package name	`behave-lint-acme-rules`
`plugin_name`	Python module name	`acme_rules`
`class_name`	PascalCase rule class name	`AcmeRules`
`rule_id`	Unique rule ID	`XA001`
`rule_name`	Kebab-case rule name	`acme-check`
`rule_title`	Human-readable title	`Acme compliance check`
`category`	Rule category	`style`, `correctness`, etc.
`severity`	Default severity	`warning`, `error`, `info`
`include_auto_fix`	Include auto-fix skeleton	`yes` or `no`

The generated project includes:

pyproject.toml with entry points configured
Rule skeleton with RuleMetadata, check(), and optional get_fixes()
Test suite with fixtures
README with usage examples
MIT LICENSE
.gitignore

Creating a plugin manually¶

1. Set up your package¶

[project]
name = "behave-lint-my-plugin"
version = "0.1.0"
requires-python = ">=3.11"

[project.entry-points."behave_lint.rules"]
my-rule = "my_plugin.rules:MyCustomRule"

2. Implement your rule¶

See the Custom Rules guide for the full rule implementation example.

3. Implement a custom reporter¶

from behave_lint.models.lint_result import LintResult
from behave_lint.reporters.base import Reporter
from typing import ClassVar


class MyReporter(Reporter):
    """Custom reporter that outputs diagnostics as CSV."""

    name: ClassVar[str] = "csv"
    supports_file_output: ClassVar[bool] = True
    supports_stdout: ClassVar[bool] = True

    def render(self, result: LintResult, output_file: str | None = None) -> None:
        lines = ["rule_id,severity,file,line,message"]
        for d in result.diagnostics:
            lines.append(
                f"{d.rule_id},{d.severity},"
                f"{d.file_path},{d.line},{d.message}"
            )
        content = "\n".join(lines)
        self._write_output(content, output_file)

Register it:

[project.entry-points."behave_lint.reporters"]
csv = "my_plugin.reporters:MyReporter"

4. Install and test¶

pip install -e .
behave-lint features/ --output csv

Plugin isolation¶

Plugins are loaded in isolated mode — a failure in one plugin does not crash the linter. Errors are reported as warnings.

Discovery¶

behave-lint discovers plugins via Python entry points. Ensure your plugin package is installed in the same environment as behave-lint.