fix: Reinstate support for legacy tag filters without @ prefix (#407)

As reported by @carlos-granados in #406, the 4.16.0 release broke tag
filtering where the tag expression does not contain `@` symbols [e.g. in
Behat](https://github.com/Behat/Behat/actions/runs/20028377501/job/57431075976).

Behat's filter expression in the failing feature is arguably incorrect:

* It uses `new TagFilter('tag2')` (note no leading `@`) - the PHP config
object is obviously new but the value has been the same since [the
feature was first added in
2014](https://github.com/Behat/Behat/pull/434/files#diff-ca77b0b1e7860ced7eb08cc40f9d6648acc0760a0be45c5fd76a8a19992adbebR92)
* All the Behat documentation shows expressing tag filters with the
leading `@` e.g.
https://docs.behat.org/en/latest/user_guide/configuration/suites.html#suite-filters
* The actual implementation of tag filtering is done in Behat/Gherkin.
Gherkin's [TagFilterTest only tests tag expressions where the leading
`@` is
included](https://github.com/Behat/Gherkin/blame/297297343c125d058e18b3f03a24ebb32f70b69d/tests/Filter/TagFilterTest.php)
and that appears to have been the case from the beginning.

As far as I can see, `TagFilter` has therefore never been meant to
accept that expression, and it's been working by accident.

However, we obviously don't validate the expression, and we have
decided we should reintroduce support for it if even Behat
has been relying on it until now.

Note that this syntax is officially deprecated and will be removed in the
next major - see #408

Author: acoulton

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 This project follows the [Behat release and version support policies]
 (https://docs.behat.org/en/latest/releases.html).
 
+# [4.16.1] - 2025-12-08
+
+### Fixed
+
+* Reinstate support for tag filter expressions without a leading `@` (e.g. `wip&&~slow` instead of `@wip&&~@slow`).
+  This syntax was never officially supported, but previously worked and was broken by 4.16.0. We have temporarily
+  fixed this, but it is deprecated and will be removed in the next major version.
+
 # [4.16.0] - 2025-12-05
 
 ### Changed
@@ -588,6 +596,7 @@ This project follows the [Behat release and version support policies]
 - 47 brand new translations (see i18n)
 - Full test suite for everything from AST nodes to translations
 
+[4.16.1]: https://github.com/Behat/Gherkin/compare/v4.16.0...v4.16.1
 [4.16.0]: https://github.com/Behat/Gherkin/compare/v4.15.0...v4.16.0
 [4.15.0]: https://github.com/Behat/Gherkin/compare/v4.14.0...v4.15.0
 [4.14.0]: https://github.com/Behat/Gherkin/compare/v4.13.0...v4.14.0

src/Filter/TagFilter.php

@@ -28,7 +28,10 @@ class TagFilter extends ComplexFilter
 
     public function __construct(string $filterString)
     {
-        $this->filterString = trim($filterString);
+        $filterString = trim($filterString);
+        $fixedFilterString = $this->fixLegacyFilterStringWithoutPrefixes($filterString);
+        // @todo trigger a deprecation here $filterString !== $fixedFilterString
+        $this->filterString = $fixedFilterString;
 
         if (preg_match('/\s/u', $this->filterString)) {
             trigger_error(
@@ -38,6 +41,40 @@ public function __construct(string $filterString)
         }
     }
 
+    /**
+     * Fix tag expressions where the filter string does not include the `@` prefixes.
+     *
+     * e.g. `new TagFilter('wip&&~slow')` rather than `new TagFilter('@wip&&~@slow')`. These were historically
+     * supported, although not officially, and have been reinstated to solve a BC issue. This syntax will be deprecated
+     * and removed in future.
+     */
+    private function fixLegacyFilterStringWithoutPrefixes(string $filterString): string
+    {
+        if ($filterString === '') {
+            return '';
+        }
+
+        $allParts = [];
+        foreach (explode('&&', $filterString) as $andTags) {
+            $allParts[] = implode(
+                ',',
+                array_map(
+                    fn (string $tag): string => match (true) {
+                        // Valid - tag filter contains the `@` prefix
+                        str_starts_with($tag, '@'),
+                        str_starts_with($tag, '~@') => $tag,
+                        // Invalid / legacy cases - insert the missing `@` prefix in the right place
+                        str_starts_with($tag, '~') => '~@' . substr($tag, 1),
+                        default => '@' . $tag,
+                    },
+                    explode(',', $andTags),
+                ),
+            );
+        }
+
+        return implode('&&', $allParts);
+    }
+
     /**
      * Filters feature according to the filter.
      *

tests/Filter/TagFilterTest.php

@@ -279,6 +279,54 @@ public function testFilterFeatureWithTaggedExamples(): void
         $this->assertEquals([$exampleTableNode3], $scenarioInterfaces[1]->getExampleTables());
     }
 
+    /**
+     * @phpstan-return list<array{string, list<string>, bool}>
+     */
+    public static function providerMatchWithNoPrefixInFilter(): array
+    {
+        // This is officially unsupported (but potentially widespread) use of a filter expression that does not
+        // contain the `@` prefix. Behat's documentation shows that the `@` prefix should be provided - however Behat's
+        // own tests include an example where this is not the case, which has been passing. Gherkin has not historically
+        // validated the tag expression, so we will continue to support these for now.
+        // These cases rely on the bulk of the coverage being provided by the other tests, and the knowledge that the
+        // implementation ultimately uses the same logic to compare tags from all types of nodes.
+        // They are only intended to be temporary until we enforce that filter expressions are valid.
+        return [
+            ['wip', [], false],
+            ['wip', ['slow'], false],
+            ['wip', ['wip'], true],
+            ['wip', ['slow', 'wip'], true],
+            ['tag1&&~tag2&&tag3', [], false],
+            ['tag1&&~tag2&&tag3', ['tag1'], false],
+            ['tag1&&~tag2&&tag3', ['tag1', 'tag3'], true],
+            ['tag1&&~tag2&&tag3', ['tag1', 'tag2'], false],
+            ['tag1&&~tag2&&tag3', ['tag1', 'tag4'], false],
+            ['tag1&&~tag2&&tag3', ['tag1', 'tag2', 'tag3'], false],
+            // Also cover when the file was parsed in compatibility mode including the prefix
+            ['wip', [], false],
+            ['wip', ['@slow'], false],
+            ['wip', ['@wip'], true],
+            ['wip', ['@slow', '@wip'], true],
+            ['tag1&&~tag2&&tag3', [], false],
+            ['tag1&&~tag2&&tag3', ['@tag1'], false],
+            ['tag1&&~tag2&&tag3', ['@tag1', '@tag3'], true],
+            ['tag1&&~tag2&&tag3', ['@tag1', '@tag2'], false],
+            ['tag1&&~tag2&&tag3', ['@tag1', '@tag4'], false],
+            ['tag1&&~tag2&&tag3', ['@tag1', '@tag2', '@tag3'], false],
+        ];
+    }
+
+    /**
+     * @phpstan-param list<string> $tags
+     */
+    #[DataProvider('providerMatchWithNoPrefixInFilter')]
+    public function testItMatchesWhenFilterDoesNotContainPrefix(string $filter, array $tags, bool $expect): void
+    {
+        $feature = new FeatureNode(null, null, $tags, null, [], '', '', null, 1);
+        $tagFilter = new TagFilter($filter);
+        $this->assertSame($expect, $tagFilter->isFeatureMatch($feature));
+    }
+
     public function testFilterWithWhitespaceIsDeprecated(): void
     {
         $this->expectDeprecationError();