behave-format 1.0.0__py3-none-any.whl

behave_format/__init__.py

@@ -0,0 +1,41 @@
+"""behave-format — The opinionated formatter for Behave .feature files.
+
+behave-format is the equivalent of Black for Gherkin .feature files.
+It consumes a behave-model Project and produces deterministic,
+beautifully formatted output.
+
+Public API:
+
+    from behave_format import format_project, render_project, Settings
+    from behave_model import load_project
+
+    project = load_project("features/")
+    format_project(project)
+    # or render to text:
+    text = render_project(project)
+
+CLI:
+
+    behave-format features/        # format in place
+    behave-format --check features/  # check mode (exit 1 if changes needed)
+    behave-format --diff features/   # show diff without writing
+"""
+
+from behave_format.config.settings import Settings
+from behave_format.pipeline.formatter import (
+    format_feature,
+    format_project,
+    render_feature,
+    render_project,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Settings",
+    "format_feature",
+    "format_project",
+    "render_feature",
+    "render_project",
+    "__version__",
+]

behave_format/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for behave-format."""

behave_format/cli/main.py

@@ -0,0 +1,175 @@
+"""CLI entry point for behave-format.
+
+Usage:
+    behave-format [OPTIONS] PATH...
+
+Options:
+    --check          Check mode: exit 1 if formatting is needed, don't write.
+    --diff           Show diffs without writing files.
+    --config PATH    Path to pyproject.toml (default: auto-discover).
+    --quiet          Suppress output except errors.
+    --help           Show help message.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import sys
+from pathlib import Path
+
+from behave_model import load_feature
+
+from behave_format.config.settings import Settings
+from behave_format.pipeline.formatter import format_feature
+from behave_format.printer.feature_printer import print_feature
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv).
+
+    Returns:
+        Exit code: 0 on success, 1 if formatting is needed (--check).
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    settings = _load_settings(args.config)
+
+    paths = [Path(p) for p in args.paths]
+    if not paths:
+        parser.print_help()
+        return 0
+
+    needs_formatting = False
+
+    for path in paths:
+        if path.is_dir():
+            changed = _process_directory(
+                path, settings, check=args.check, diff=args.diff, quiet=args.quiet
+            )
+            if changed:
+                needs_formatting = True
+        elif path.is_file() and path.suffix == ".feature":
+            changed = _process_file(
+                path, settings, check=args.check, diff=args.diff, quiet=args.quiet
+            )
+            if changed:
+                needs_formatting = True
+        else:
+            print(f"Warning: skipping {path} (not a .feature file or directory)", file=sys.stderr)
+
+    if args.check and needs_formatting:
+        if not args.quiet:
+            print("Files would be reformatted")
+        return 1
+
+    if not args.quiet and not args.check and not args.diff:
+        if needs_formatting:
+            print("Formatted files")
+        else:
+            print("No changes needed")
+
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="behave-format",
+        description="The opinionated formatter for Behave .feature files.",
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="Paths to .feature files or directories containing them.",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check mode: exit 1 if formatting is needed, don't write files.",
+    )
+    parser.add_argument(
+        "--diff",
+        action="store_true",
+        help="Show diffs without writing files.",
+    )
+    parser.add_argument(
+        "--config",
+        default=None,
+        help="Path to pyproject.toml for configuration.",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress output except errors.",
+    )
+    return parser
+
+
+def _load_settings(config_path: str | None) -> Settings:
+    if config_path:
+        return Settings.from_pyproject(config_path)
+    return Settings.from_pyproject("pyproject.toml")
+
+
+def _process_directory(
+    directory: Path,
+    settings: Settings,
+    *,
+    check: bool,
+    diff: bool,
+    quiet: bool,
+) -> bool:
+    feature_files = sorted(directory.rglob("*.feature"))
+    changed = False
+    for fpath in feature_files:
+        if _process_file(fpath, settings, check=check, diff=diff, quiet=quiet):
+            changed = True
+    return changed
+
+
+def _process_file(
+    fpath: Path,
+    settings: Settings,
+    *,
+    check: bool,
+    diff: bool,
+    quiet: bool,
+) -> bool:
+    original = fpath.read_text(encoding="utf-8")
+
+    feature = load_feature(fpath)
+    format_feature(feature, settings)
+    formatted = print_feature(feature, indent=settings.indent) + "\n"
+
+    if formatted == original:
+        return False
+
+    if diff:
+        _show_diff(fpath, original, formatted, quiet=quiet)
+
+    if not check and not diff:
+        fpath.write_text(formatted, encoding="utf-8")
+        if not quiet:
+            print(f"reformatted {fpath}")
+
+    return True
+
+
+def _show_diff(fpath: Path, original: str, formatted: str, *, quiet: bool) -> None:
+    diff_lines = difflib.unified_diff(
+        original.splitlines(keepends=True),
+        formatted.splitlines(keepends=True),
+        fromfile=str(fpath),
+        tofile=str(fpath),
+    )
+    diff_text = "".join(diff_lines)
+    if diff_text and not quiet:
+        sys.stdout.write(diff_text)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

behave_format/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration package for behave-format."""

behave_format/config/settings.py

@@ -0,0 +1,81 @@
+"""Formatter settings with minimal configuration philosophy.
+
+Settings can be loaded from ``pyproject.toml`` under ``[tool.behave-format]``
+or constructed programmatically.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Immutable formatter settings.
+
+    Attributes:
+        indent: Number of spaces for indentation (default 2).
+        sort_tags: Sort tags alphabetically (default True).
+        sort_features: Sort features by name (default False).
+        sort_scenarios: Sort scenarios by name (default False).
+        line_length: Maximum line length for reference (default 120).
+    """
+
+    indent: int = 2
+    sort_tags: bool = True
+    sort_features: bool = False
+    sort_scenarios: bool = False
+    line_length: int = 120
+
+    @classmethod
+    def from_pyproject(cls, path: str = "pyproject.toml") -> Settings:
+        """Load settings from a ``pyproject.toml`` file.
+
+        Args:
+            path: Path to the ``pyproject.toml`` file.
+
+        Returns:
+            A Settings instance. If the file or section is missing,
+            defaults are returned.
+        """
+        from pathlib import Path
+
+        p = Path(path)
+        if not p.exists():
+            return cls()
+
+        with p.open("rb") as f:
+            data = tomllib.load(f)
+
+        section = data.get("tool", {}).get("behave-format", {})
+        return cls(
+            indent=section.get("indent", 2),
+            sort_tags=section.get("sort_tags", True),
+            sort_features=section.get("sort_features", False),
+            sort_scenarios=section.get("sort_scenarios", False),
+            line_length=section.get("line_length", 120),
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Settings:
+        """Create settings from a dictionary.
+
+        Args:
+            data: Dictionary with optional keys: indent, sort_tags,
+                sort_features, sort_scenarios, line_length.
+
+        Returns:
+            A Settings instance.
+        """
+        return cls(
+            indent=data.get("indent", 2),
+            sort_tags=data.get("sort_tags", True),
+            sort_features=data.get("sort_features", False),
+            sort_scenarios=data.get("sort_scenarios", False),
+            line_length=data.get("line_length", 120),
+        )

behave_format/pipeline/__init__.py

@@ -0,0 +1 @@
+"""Formatting pipeline package."""

behave_format/pipeline/align.py

@@ -0,0 +1,69 @@
+"""Align stage — table alignment and trailing whitespace removal.
+
+This stage ensures tables are properly aligned and no trailing
+whitespace remains in any text content. It operates on the model
+before printing.
+"""
+
+from __future__ import annotations
+
+from behave_model.model.feature import Feature
+from behave_model.model.project import Project
+from behave_model.model.scenario_outline import ScenarioOutline
+from behave_model.model.step import Step
+from behave_model.model.table import Table
+
+
+def align_project(project: Project) -> Project:
+    """Apply alignment rules to the project.
+
+    Args:
+        project: The project to align (mutated in place).
+
+    Returns:
+        The same project, aligned.
+    """
+    for feature in project.features:
+        _align_feature(feature)
+    return project
+
+
+def _align_feature(feature: Feature) -> None:
+    if feature.background:
+        for step in feature.background.steps:
+            _align_step(step)
+    for scenario in feature.scenarios:
+        for step in scenario.steps:
+            _align_step(step)
+        if isinstance(scenario, ScenarioOutline):
+            for ex in scenario.examples:
+                _align_table(examples_table=ex.table)
+    for rule in feature.rules:
+        if rule.background:
+            for step in rule.background.steps:
+                _align_step(step)
+        for scenario in rule.scenarios:
+            for step in scenario.steps:
+                _align_step(step)
+            if isinstance(scenario, ScenarioOutline):
+                for ex in scenario.examples:
+                    _align_table(examples_table=ex.table)
+
+
+def _align_step(step: Step) -> None:
+    if step.data_table:
+        _align_table(step.data_table)
+
+
+def _align_table(table: Table, *, examples_table: Table | None = None) -> None:
+    target = examples_table if examples_table is not None else table
+    _ensure_rectangular(target)
+
+
+def _ensure_rectangular(table: Table) -> None:
+    num_cols = len(table.headers)
+    for row in table.rows:
+        while len(row.cells) < num_cols:
+            row.cells.append("")
+        if len(row.cells) > num_cols:
+            row.cells = row.cells[:num_cols]

behave_format/pipeline/formatter.py

@@ -0,0 +1,96 @@
+"""Formatter — the main orchestrator for the formatting pipeline.
+
+The pipeline is:
+    1. Normalize  — clean whitespace, standardize structure
+    2. Sort       — order tags, features, scenarios
+    3. Align      — table alignment, trailing whitespace
+    4. Print      — convert model to .feature text
+"""
+
+from __future__ import annotations
+
+from behave_model.model.feature import Feature
+from behave_model.model.project import Project
+
+from behave_format.config.settings import Settings
+from behave_format.pipeline.align import align_project
+from behave_format.pipeline.normalize import normalize_project
+from behave_format.pipeline.sort import sort_project
+from behave_format.printer.feature_printer import print_feature
+
+
+def format_project(project: Project, settings: Settings | None = None) -> Project:
+    """Format a behave-model Project in place.
+
+    Applies the full pipeline: normalize → sort → align.
+    The project is mutated and returned.
+
+    Args:
+        project: The project to format.
+        settings: Optional formatter settings. Defaults to Settings().
+
+    Returns:
+        The same project, formatted.
+    """
+    if settings is None:
+        settings = Settings()
+
+    normalize_project(project)
+    sort_project(project, settings)
+    align_project(project)
+    return project
+
+
+def format_feature(feature: Feature, settings: Settings | None = None) -> Feature:
+    """Format a single Feature in place.
+
+    Args:
+        feature: The feature to format.
+        settings: Optional formatter settings. Defaults to Settings().
+
+    Returns:
+        The same feature, formatted.
+    """
+    if settings is None:
+        settings = Settings()
+
+    from behave_format.pipeline.normalize import _normalize_feature
+    from behave_format.pipeline.sort import _sort_feature_tags
+
+    _normalize_feature(feature)
+    if settings.sort_tags:
+        _sort_feature_tags(feature)
+    # align is handled at print time
+    return feature
+
+
+def render_feature(feature: Feature, settings: Settings | None = None) -> str:
+    """Format and render a Feature as .feature text.
+
+    Args:
+        feature: The feature to format and print.
+        settings: Optional formatter settings.
+
+    Returns:
+        The formatted .feature file content as a string.
+    """
+    format_feature(feature, settings)
+    return print_feature(feature, indent=settings.indent if settings else 2)
+
+
+def render_project(project: Project, settings: Settings | None = None) -> str:
+    """Format and render an entire Project as .feature text.
+
+    Features are separated by a single blank line.
+
+    Args:
+        project: The project to format and print.
+        settings: Optional formatter settings.
+
+    Returns:
+        The formatted content for all features, joined by blank lines.
+    """
+    format_project(project, settings)
+    indent = settings.indent if settings else 2
+    parts = [print_feature(f, indent=indent) for f in project.features]
+    return "\n\n".join(parts)

behave_format/pipeline/normalize.py

@@ -0,0 +1,124 @@
+"""Normalize stage — clean whitespace and standardize structure.
+
+This stage operates on a behave-model Project in place.
+It NEVER changes semantics: only whitespace, indentation, and
+structural consistency are normalized.
+"""
+
+from __future__ import annotations
+
+from behave_model.model.background import Background
+from behave_model.model.docstring import DocString
+from behave_model.model.examples import Examples
+from behave_model.model.feature import Feature
+from behave_model.model.project import Project
+from behave_model.model.rule import Rule
+from behave_model.model.scenario import Scenario
+from behave_model.model.scenario_outline import ScenarioOutline
+from behave_model.model.step import Step
+from behave_model.model.table import Table
+from behave_model.model.tag import Tag
+
+
+def normalize_project(project: Project) -> Project:
+    """Normalize whitespace and structure across the entire project.
+
+    Args:
+        project: The project to normalize (mutated in place).
+
+    Returns:
+        The same project, normalized.
+    """
+    for feature in project.features:
+        _normalize_feature(feature)
+    project.global_tags.sort(key=lambda t: t.name)
+    return project
+
+
+def _normalize_feature(feature: Feature) -> None:
+    feature.name = " ".join(feature.name.split())
+    feature.description = _normalize_description(feature.description)
+    _normalize_tags(feature.tags)
+    if feature.background:
+        _normalize_background(feature.background)
+    for scenario in feature.scenarios:
+        _normalize_scenario(scenario)
+    for rule in feature.rules:
+        _normalize_rule(rule)
+    for comment in feature.comments:
+        comment.text = comment.text.rstrip()
+
+
+def _normalize_rule(rule: Rule) -> None:
+    rule.name = " ".join(rule.name.split())
+    rule.description = _normalize_description(rule.description)
+    _normalize_tags(rule.tags)
+    if rule.background:
+        _normalize_background(rule.background)
+    for scenario in rule.scenarios:
+        _normalize_scenario(scenario)
+    for comment in rule.comments:
+        comment.text = comment.text.rstrip()
+
+
+def _normalize_background(background: Background) -> None:
+    background.name = " ".join(background.name.split())
+    for step in background.steps:
+        _normalize_step(step)
+
+
+def _normalize_scenario(scenario: Scenario | ScenarioOutline) -> None:
+    scenario.name = " ".join(scenario.name.split())
+    scenario.description = _normalize_description(scenario.description)
+    _normalize_tags(scenario.tags)
+    for step in scenario.steps:
+        _normalize_step(step)
+    if isinstance(scenario, ScenarioOutline):
+        for examples in scenario.examples:
+            _normalize_examples(examples)
+    for comment in scenario.comments:
+        comment.text = comment.text.rstrip()
+
+
+def _normalize_examples(examples: Examples) -> None:
+    examples.name = " ".join(examples.name.split())
+    _normalize_tags(examples.tags)
+    _normalize_table(examples.table)
+
+
+def _normalize_step(step: Step) -> None:
+    step.keyword = step.keyword.strip()
+    step.name = " ".join(step.name.split())
+    if step.doc_string:
+        _normalize_doc_string(step.doc_string)
+    if step.data_table:
+        _normalize_table(step.data_table)
+    for comment in step.comments:
+        comment.text = comment.text.rstrip()
+
+
+def _normalize_doc_string(doc_string: DocString) -> None:
+    doc_string.content_type = doc_string.content_type.strip()
+    delimiter = doc_string.delimiter or '"""'
+    doc_string.delimiter = delimiter
+
+
+def _normalize_table(table: Table) -> None:
+    table.headers = [h.strip() for h in table.headers]
+    for row in table.rows:
+        row.cells = [c.strip() for c in row.cells]
+
+
+def _normalize_tags(tags: list[Tag]) -> None:
+    for tag in tags:
+        tag.name = tag.name.strip()
+        if not tag.name.startswith("@"):
+            tag.name = "@" + tag.name
+
+
+def _normalize_description(description: str) -> str:
+    lines = description.splitlines()
+    normalized = []
+    for line in lines:
+        normalized.append(" ".join(line.split()))
+    return "\n".join(normalized)

behave_format/pipeline/rules.py

@@ -0,0 +1,31 @@
+"""Formatting rules registry.
+
+Each rule is a callable that transforms the project at a specific
+stage of the pipeline. Rules are applied in order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from behave_model.model.project import Project
+
+from behave_format.config.settings import Settings
+
+Rule = Callable[[Project, Settings], Project]
+
+
+def apply_rules(project: Project, settings: Settings, rules: list[Rule]) -> Project:
+    """Apply a list of formatting rules to the project.
+
+    Args:
+        project: The project to format.
+        settings: Formatter settings.
+        rules: Ordered list of rule callables.
+
+    Returns:
+        The formatted project.
+    """
+    for rule in rules:
+        project = rule(project, settings)
+    return project

behave_format/pipeline/sort.py

@@ -0,0 +1,65 @@
+"""Sort stage — order tags, features, and scenarios.
+
+Sorting is configurable via Settings. By default only tags are sorted
+alphabetically. Feature and scenario sorting are opt-in.
+"""
+
+from __future__ import annotations
+
+from behave_model.model.feature import Feature
+from behave_model.model.project import Project
+from behave_model.model.rule import Rule
+from behave_model.model.scenario_outline import ScenarioOutline
+
+from behave_format.config.settings import Settings
+
+
+def sort_project(project: Project, settings: Settings) -> Project:
+    """Apply sorting rules to the project.
+
+    Args:
+        project: The project to sort (mutated in place).
+        settings: Formatter settings controlling sort behavior.
+
+    Returns:
+        The same project, sorted.
+    """
+    if settings.sort_tags:
+        _sort_all_tags(project)
+
+    if settings.sort_features:
+        project.features.sort(key=lambda f: f.name)
+
+    if settings.sort_scenarios:
+        for feature in project.features:
+            feature.scenarios.sort(key=lambda s: s.name)
+            for rule in feature.rules:
+                rule.scenarios.sort(key=lambda s: s.name)
+
+    return project
+
+
+def _sort_all_tags(project: Project) -> None:
+    project.global_tags.sort(key=lambda t: t.name)
+    for feature in project.features:
+        _sort_feature_tags(feature)
+
+
+def _sort_feature_tags(feature: Feature) -> None:
+    feature.tags.sort(key=lambda t: t.name)
+    for scenario in feature.scenarios:
+        scenario.tags.sort(key=lambda t: t.name)
+        if isinstance(scenario, ScenarioOutline):
+            for ex in scenario.examples:
+                ex.tags.sort(key=lambda t: t.name)
+    for rule in feature.rules:
+        _sort_rule_tags(rule)
+
+
+def _sort_rule_tags(rule: Rule) -> None:
+    rule.tags.sort(key=lambda t: t.name)
+    for scenario in rule.scenarios:
+        scenario.tags.sort(key=lambda t: t.name)
+        if isinstance(scenario, ScenarioOutline):
+            for ex in scenario.examples:
+                ex.tags.sort(key=lambda t: t.name)

behave_format/printer/__init__.py

@@ -0,0 +1 @@
+"""Printer package — converts behave-model objects to .feature text."""

behave_format/printer/feature_printer.py

@@ -0,0 +1,93 @@
+"""Feature printer — formats a complete Feature as .feature text."""
+
+from __future__ import annotations
+
+from behave_model.model.feature import Feature
+from behave_model.model.rule import Rule
+from behave_model.model.scenario_outline import ScenarioOutline
+
+from behave_format.printer.scenario_printer import (
+    print_background,
+    print_scenario,
+    print_scenario_outline,
+)
+from behave_format.printer.tag_printer import print_tags
+
+
+def print_feature(feature: Feature, indent: int = 2) -> str:
+    """Format a Feature as valid, deterministic Gherkin text.
+
+    Args:
+        feature: The Feature to print.
+        indent: Base indentation for scenarios and rules.
+
+    Returns:
+        Multi-line string representing the complete feature file content.
+    """
+    lines: list[str] = []
+
+    if feature.tags:
+        lines.append(print_tags(feature.tags, indent=0))
+
+    header = f"Feature: {feature.name}" if feature.name else "Feature:"
+    lines.append(header)
+
+    if feature.description:
+        for desc_line in feature.description.splitlines():
+            if desc_line:
+                lines.append(f"{' ' * indent}{desc_line}")
+            else:
+                lines.append("")
+
+    if feature.background:
+        lines.append("")
+        lines.append(print_background(feature.background, indent=indent))
+
+    for scenario in feature.scenarios:
+        lines.append("")
+        if isinstance(scenario, ScenarioOutline):
+            lines.append(print_scenario_outline(scenario, indent=indent))
+        else:
+            lines.append(print_scenario(scenario, indent=indent))
+
+    for rule in feature.rules:
+        lines.append("")
+        lines.append(_print_rule(rule, indent=indent))
+
+    return "\n".join(lines)
+
+
+def _print_rule(rule: Rule, indent: int = 2) -> str:
+    prefix = " " * indent
+    lines: list[str] = []
+
+    if rule.tags:
+        lines.append(print_tags(rule.tags, indent=indent))
+
+    header = f"Rule: {rule.name}" if rule.name else "Rule:"
+    lines.append(f"{prefix}{header}")
+
+    if rule.description:
+        for desc_line in rule.description.splitlines():
+            if desc_line:
+                lines.append(f"{prefix}  {desc_line}")
+            else:
+                lines.append("")
+
+    first_child = True
+    if rule.background:
+        if not first_child:
+            lines.append("")
+        lines.append(print_background(rule.background, indent=indent + 2))
+        first_child = False
+
+    for scenario in rule.scenarios:
+        if not first_child:
+            lines.append("")
+        if isinstance(scenario, ScenarioOutline):
+            lines.append(print_scenario_outline(scenario, indent=indent + 2))
+        else:
+            lines.append(print_scenario(scenario, indent=indent + 2))
+        first_child = False
+
+    return "\n".join(lines)

behave_format/printer/scenario_printer.py

@@ -0,0 +1,117 @@
+"""Scenario printer — formats scenarios and scenario outlines."""
+
+from __future__ import annotations
+
+from behave_model.model.background import Background
+from behave_model.model.examples import Examples
+from behave_model.model.scenario import Scenario
+from behave_model.model.scenario_outline import ScenarioOutline
+
+from behave_format.printer.step_printer import print_step
+from behave_format.printer.table_printer import print_table
+from behave_format.printer.tag_printer import print_tags
+
+
+def print_background(background: Background, indent: int = 2) -> str:
+    """Format a Background block.
+
+    Args:
+        background: The Background to print.
+        indent: Base indentation level.
+
+    Returns:
+        Multi-line string with the background and its steps.
+    """
+    prefix = " " * indent
+    header = "Background:"
+    if background.name:
+        header = f"Background: {background.name}"
+    lines: list[str] = [f"{prefix}{header}"]
+    for step in background.steps:
+        lines.append(print_step(step, indent=indent + 2))
+    return "\n".join(lines)
+
+
+def print_scenario(scenario: Scenario, indent: int = 2) -> str:
+    """Format a Scenario as Gherkin text.
+
+    Args:
+        scenario: The Scenario to print.
+        indent: Base indentation level.
+
+    Returns:
+        Multi-line string with tags, scenario header, and steps.
+    """
+    prefix = " " * indent
+    lines: list[str] = []
+
+    if scenario.tags:
+        lines.append(print_tags(scenario.tags, indent=indent))
+
+    header = f"Scenario: {scenario.name}" if scenario.name else "Scenario:"
+    lines.append(f"{prefix}{header}")
+
+    if scenario.description:
+        for desc_line in scenario.description.splitlines():
+            if desc_line:
+                lines.append(f"{prefix}  {desc_line}")
+            else:
+                lines.append("")
+
+    for step in scenario.steps:
+        lines.append(print_step(step, indent=indent + 2))
+
+    return "\n".join(lines)
+
+
+def print_scenario_outline(outline: ScenarioOutline, indent: int = 2) -> str:
+    """Format a ScenarioOutline as Gherkin text.
+
+    Args:
+        outline: The ScenarioOutline to print.
+        indent: Base indentation level.
+
+    Returns:
+        Multi-line string with tags, outline header, steps, and examples.
+    """
+    prefix = " " * indent
+    lines: list[str] = []
+
+    if outline.tags:
+        lines.append(print_tags(outline.tags, indent=indent))
+
+    header = f"Scenario Outline: {outline.name}" if outline.name else "Scenario Outline:"
+    lines.append(f"{prefix}{header}")
+
+    if outline.description:
+        for desc_line in outline.description.splitlines():
+            if desc_line:
+                lines.append(f"{prefix}  {desc_line}")
+            else:
+                lines.append("")
+
+    for step in outline.steps:
+        lines.append(print_step(step, indent=indent + 2))
+
+    for examples in outline.examples:
+        lines.append("")
+        lines.append(_print_examples(examples, indent=indent + 2))
+
+    return "\n".join(lines)
+
+
+def _print_examples(examples: Examples, indent: int = 4) -> str:
+    prefix = " " * indent
+    lines: list[str] = []
+
+    if examples.tags:
+        lines.append(print_tags(examples.tags, indent=indent))
+
+    header = "Examples:"
+    if examples.name:
+        header = f"Examples: {examples.name}"
+    lines.append(f"{prefix}{header}")
+
+    lines.append(print_table(examples.table, indent=indent + 2))
+
+    return "\n".join(lines)

behave_format/printer/step_printer.py

@@ -0,0 +1,46 @@
+"""Step printer — formats steps with proper indentation."""
+
+from __future__ import annotations
+
+from behave_model.model.docstring import DocString
+from behave_model.model.step import Step
+
+from behave_format.printer.table_printer import print_table
+
+
+def print_step(step: Step, indent: int = 4) -> str:
+    """Format a single step as Gherkin text.
+
+    Args:
+        step: The Step to print.
+        indent: Number of spaces for indentation.
+
+    Returns:
+        Multi-line string with the step and any attached docstring or table.
+    """
+    prefix = " " * indent
+    lines: list[str] = [f"{prefix}{step.keyword} {step.name}".rstrip()]
+
+    if step.doc_string:
+        lines.append(_print_doc_string(step.doc_string, indent))
+
+    if step.data_table:
+        lines.append(print_table(step.data_table, indent=indent + 2))
+
+    return "\n".join(lines)
+
+
+def _print_doc_string(doc_string: DocString, indent: int) -> str:
+    prefix = " " * (indent + 2)
+    delimiter = doc_string.delimiter or '"""'
+    content_type = doc_string.content_type
+
+    lines: list[str] = []
+    header = f"{prefix}{delimiter}"
+    if content_type:
+        header += content_type
+    lines.append(header)
+    for content_line in doc_string.lines:
+        lines.append(f"{prefix}{content_line}")
+    lines.append(f"{prefix}{delimiter}")
+    return "\n".join(lines)

behave_format/printer/table_printer.py

@@ -0,0 +1,47 @@
+"""Table printer — formats data tables with aligned columns."""
+
+from __future__ import annotations
+
+from behave_model.model.table import Table
+
+
+def print_table(table: Table, indent: int = 4) -> str:
+    """Format a Table as aligned Gherkin table text.
+
+    Args:
+        table: The Table to print.
+        indent: Number of spaces for indentation.
+
+    Returns:
+        Multi-line string with aligned table rows.
+    """
+    if not table.headers and not table.rows:
+        return ""
+
+    widths = _compute_widths(table)
+    prefix = " " * indent
+    lines: list[str] = []
+
+    header_cells = [
+        h.ljust(widths[i]) if i < len(widths) else h for i, h in enumerate(table.headers)
+    ]
+    lines.append(f"{prefix}| {' | '.join(header_cells)} |")
+
+    for row in table.rows:
+        row_cells = [
+            cell.ljust(widths[i]) if i < len(widths) else cell for i, cell in enumerate(row.cells)
+        ]
+        lines.append(f"{prefix}| {' | '.join(row_cells)} |")
+
+    return "\n".join(lines)
+
+
+def _compute_widths(table: Table) -> list[int]:
+    widths = [len(h) for h in table.headers]
+    for row in table.rows:
+        for i, cell in enumerate(row.cells):
+            if i < len(widths):
+                widths[i] = max(widths[i], len(cell))
+            else:
+                widths.append(len(cell))
+    return widths

behave_format/printer/tag_printer.py

@@ -0,0 +1,21 @@
+"""Tag printer — formats tags as space-separated strings."""
+
+from __future__ import annotations
+
+from behave_model.model.tag import Tag
+
+
+def print_tags(tags: list[Tag], indent: int = 0) -> str:
+    """Format a list of tags as a single line.
+
+    Args:
+        tags: List of Tag objects.
+        indent: Number of spaces to prefix.
+
+    Returns:
+        A space-separated tag string, or empty string if no tags.
+    """
+    if not tags:
+        return ""
+    prefix = " " * indent
+    return prefix + " ".join(t.name for t in tags)

behave_format-1.0.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: behave-format
+Version: 1.0.0
+Summary: The opinionated formatter for Behave .feature files
+Project-URL: Homepage, https://github.com/MathiasPaulenko/behave-format
+Project-URL: Repository, https://github.com/MathiasPaulenko/behave-format
+Project-URL: Issues, https://github.com/MathiasPaulenko/behave-format/issues
+Project-URL: Changelog, https://github.com/MathiasPaulenko/behave-format/blob/main/CHANGELOG.md
+Author: Mathias Paulenko
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bdd,behave,cucumber,format,formatter,gherkin,testing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: behave-model>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# behave-format
+
+> The opinionated formatter for Behave `.feature` files.
+
+[Black](https://github.com/psf/black) is for Python. [gofmt](https://go.dev/blog/gofmt) is for Go. **behave-format** is for Gherkin.
+
+---
+
+## Overview
+
+`behave-format` is a deterministic, opinionated formatter for Behave `.feature` files. It consumes the canonical domain model from [behave-model](https://github.com/MathiasPaulenko/behave-model) and produces clean, consistent, beautifully formatted output.
+
+**Key principle:** behave-format does NOT parse Gherkin. It does NOT lint. It does NOT validate. It ONLY transforms a `behave-model.Project` into formatted `.feature` files.
+
+```text
+.feature files → behave-model (domain model) → behave-format → formatted .feature files
+```
+
+## Features
+
+- **Opinionated** — minimal configuration, sensible defaults
+- **Deterministic** — same input always produces same output
+- **Idempotent** — `format(format(x)) == format(x)`
+- **Fast** — handles thousands of feature files efficiently
+- **CI-friendly** — `--check` mode with exit code 1 when formatting is needed
+- **Safe** — never changes semantics (names, step text, table values, docstrings)
+
+## Installation
+
+```bash
+pip install behave-format
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Format files in place (default)
+behave-format features/
+
+# Check mode (CI) — exit 1 if formatting is needed
+behave-format --check features/
+
+# Diff mode — show differences without writing
+behave-format --diff features/
+```
+
+### Python API
+
+```python
+from behave_model import load_project
+from behave_format import format_project, render_project, Settings
+
+project = load_project("features/")
+
+# Format the project model in place
+format_project(project)
+
+# Or render to text
+text = render_project(project, Settings())
+```
+
+## Formatting Rules
+
+### Tags
+
+Tags are sorted alphabetically by default:
+
+```gherkin
+@api @smoke
+```
+
+### Features
+
+- One blank line before each Feature
+- Clean title formatting
+
+### Scenarios
+
+- One blank line before each Scenario
+- Two-space indentation for steps
+
+```gherkin
+  Given user exists
+  When user logs in
+  Then dashboard is shown
+```
+
+### Tables
+
+Tables are always aligned:
+
+Before:
+
+```gherkin
+|user|password|
+|john|123|
+```
+
+After:
+
+```gherkin
+| user | password |
+| john | 123      |
+```
+
+### Blank Lines
+
+- No trailing blank lines
+- No multiple consecutive empty lines
+- Consistent spacing between blocks
+
+### Indentation
+
+- Spaces only (no tabs)
+- Default: 2 spaces
+
+## Configuration
+
+Minimal configuration via `pyproject.toml`:
+
+```toml
+[tool.behave-format]
+indent = 2
+sort_tags = true
+sort_features = false
+sort_scenarios = false
+line_length = 120
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `indent` | `2` | Number of spaces for indentation |
+| `sort_tags` | `true` | Sort tags alphabetically |
+| `sort_features` | `false` | Sort features by name |
+| `sort_scenarios` | `false` | Sort scenarios by name |
+| `line_length` | `120` | Maximum line length (reference) |
+
+## Before / After
+
+### Before
+
+```gherkin
+@smoke @auth
+Feature: Login
+  As a user
+  I want to log in
+
+  Background:
+    Given a database connection
+
+  @happy
+  Scenario: Successful login
+    Given the user is on the login page
+    When the user enters "admin" and "password"
+    Then the user should be logged in
+```
+
+### After
+
+```gherkin
+@auth @smoke
+Feature: Login
+  As a user
+  I want to log in
+
+  Background:
+    Given a database connection
+
+  @happy
+  Scenario: Successful login
+    Given the user is on the login page
+    When the user enters "admin" and "password"
+    Then the user should be logged in
+```
+
+## Architecture
+
+```text
+behave_format/
+├── config/
+│   └── settings.py        # Settings dataclass + pyproject.toml loader
+├── pipeline/
+│   ├── normalize.py       # Whitespace, indentation, tag normalization
+│   ├── sort.py            # Sort tags, features, scenarios
+│   ├── align.py           # Table alignment, trailing whitespace
+│   ├── rules.py           # Formatting rules registry
+│   └── formatter.py       # Main orchestrator (format_project)
+├── printer/
+│   ├── feature_printer.py
+│   ├── scenario_printer.py
+│   ├── step_printer.py
+│   ├── table_printer.py
+│   └── tag_printer.py
+└── cli/
+    └── main.py            # CLI entry point
+```
+
+## Pipeline
+
+1. **Normalize** — clean whitespace, standardize indentation, normalize tags
+2. **Sort** — order tags (alphabetically by default), optionally features and scenarios
+3. **Align** — align table columns, remove trailing spaces
+4. **Print** — convert `behave-model` → `.feature` text (deterministic)
+
+## Safety
+
+The formatter NEVER changes semantics:
+
+- Feature names: preserved
+- Scenario names: preserved
+- Step text: preserved (only whitespace normalized)
+- DocString content: preserved
+- Table values: preserved (only alignment changes)
+- Comments content: preserved
+
+## Integration
+
+`behave-format` integrates naturally with the Behave ecosystem:
+
+- [behave-model](https://github.com/MathiasPaulenko/behave-model) — single source of truth
+- [behave-lint](https://github.com/MathiasPaulenko/behave-lint) — linting
+- [behave-modern-json-report](https://github.com/MathiasPaulenko/behave-modern-json-report)
+- [behave-modern-report](https://github.com/MathiasPaulenko/behave-modern-report)
+- [behave-markdown-report](https://github.com/MathiasPaulenko/behave-markdown-report)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+ruff check .
+ruff format --check .
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Run `ruff check .` and `pytest tests/` before submitting
+4. Open a Pull Request
+
+## License
+
+MIT

behave_format-1.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+behave_format/__init__.py,sha256=qa2JDyFPm5NkhhqOK4bpa1V7oq3o1mjwQGYWFszj2Bc,1041
+behave_format/cli/__init__.py,sha256=9ogAdUoeTrMYLl2IZz6MygctP1elHvpfFM777i1cEcs,37
+behave_format/cli/main.py,sha256=DSH0l8L8EayHR3QT_zotK1HNOtJFhnbT05B6BAghELA,4645
+behave_format/config/__init__.py,sha256=uGsMkjI0Hyg0_utGKM3lOsp-cko-hevIQNX7L1VpPI8,47
+behave_format/config/settings.py,sha256=oTxX3BGf-Fyi8jedFRDmvuzX8XE5B2BxZCzNynsXAnA,2439
+behave_format/pipeline/__init__.py,sha256=Gh5e_EKrI36jOEpvfIC0mf_LjZs08_iSzFxlF30ebG8,35
+behave_format/pipeline/align.py,sha256=omZpO9LNGGTTxnWynymNWeIeMwDgV19H-GR31gbEQ0o,2169
+behave_format/pipeline/formatter.py,sha256=FXFYnyrU5sh20wptNtVFg03WHqrtP8BkE2LBE_3y14U,2986
+behave_format/pipeline/normalize.py,sha256=Lf090fIGz9r5R2mJePryGkoEVj5VSAq-moiSUSjfHvg,4095
+behave_format/pipeline/rules.py,sha256=pcdXtvhB7vR5Qh8I6nf43nCajJfaejNYOUE3AiVGYDI,789
+behave_format/pipeline/sort.py,sha256=tHU7tEwv1Mlm1OKG9YzYZhZcxwsHwKxH4vBrREWxs0s,2036
+behave_format/printer/__init__.py,sha256=rMnxwqPHv68zwrq2UicaUE6Dt1Sik6-Ni7GeBjTFfLM,74
+behave_format/printer/feature_printer.py,sha256=1ksgWapnkyhhZFzZ0wFWrwKCmAMfqc6NuppG44_kYd0,2805
+behave_format/printer/scenario_printer.py,sha256=fxnakBkH4O_VPhm33XTqx0vlM0gjHu8GOb8WFmziERY,3445
+behave_format/printer/step_printer.py,sha256=W7gSvn3yuSgcs1hFMLBEcAkGs9-o7ZVTuGUbj62Az9A,1344
+behave_format/printer/table_printer.py,sha256=CFJwkYG-_iambqFCnOEBmXNGbUYQzHMYfu7UqANPvvI,1334
+behave_format/printer/tag_printer.py,sha256=cZQE2tvfkVZ8HDw0U0-BflLEF17eA48kgFCc-YOQ-Sc,535
+behave_format-1.0.0.dist-info/METADATA,sha256=D96PgzdE7WdgI9cfkGpCRptp0a52TBQwbuADgKCSX7M,7222
+behave_format-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+behave_format-1.0.0.dist-info/entry_points.txt,sha256=n9Q-LKVSfdDO-5vez6RQ96hwl3pFFMmR_uDiKjSN52A,62
+behave_format-1.0.0.dist-info/licenses/LICENSE,sha256=LLr8AP65kT83seFEcknE3-76LL7oikrP87U33tZKYro,1073
+behave_format-1.0.0.dist-info/RECORD,,

behave_format-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

behave_format-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+behave-format = behave_format.cli.main:main

behave_format-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mathias Paulenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.