fix docstring with @ sign breaking Scenario Outline parsing #2775

Two issues fixed:

1. Lexer: shouldTransitionToGherkin() didn't recognize """ as a
   transition trigger, so docstrings after Scenario Outline were
   consumed as description text. Added """ to the keyword list.

2. Parser: bare docstrings (before any step) in scenarios and outlines
   are now consumed as documentation rather than causing parse failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ptrthomas

karate-core/src/main/java/io/karatelabs/gherkin/GherkinLexer.java

@@ -120,6 +120,7 @@ private TokenType scanGherkinWhitespaceWithNewline() {
             }
         }
         // After newline, return to appropriate state
+        // GS_DOC_STRING must NOT be reset - content continues until closing """
         if (gState == GherkinState.GS_COMMENT || gState == GherkinState.GS_DESC
                 || gState == GherkinState.GS_TAGS || gState == GherkinState.GS_TABLE_ROW
                 || gState == GherkinState.GS_STEP || gState == GherkinState.GS_STEP_MATCH
@@ -283,7 +284,7 @@ private boolean shouldTransitionToGherkin() {
                 || rest.startsWith("And") || rest.startsWith("But") || rest.startsWith("*")
                 || rest.startsWith("Scenario:") || rest.startsWith("Scenario Outline:")
                 || rest.startsWith("Background:") || rest.startsWith("Examples:")
-                || rest.startsWith("@") || rest.startsWith("|");
+                || rest.startsWith("@") || rest.startsWith("|") || rest.startsWith("\"\"\"");
     }
 
     // ========== GS_COMMENT State ==========

karate-core/src/main/java/io/karatelabs/gherkin/GherkinParser.java

@@ -146,6 +146,7 @@ private boolean scenario() {
             return false;
         }
         nameDesc();
+        docString(); // Skip bare docstring used as documentation (before any step)
         while (step()) {
             // Collect steps
         }
@@ -157,6 +158,7 @@ private boolean scenarioOutline() {
             return false;
         }
         nameDesc();
+        docString(); // Skip bare docstring used as documentation (before any step)
         while (step()) {
             // Collect steps
         }

karate-core/src/test/java/io/karatelabs/gherkin/GherkinParserTest.java

@@ -822,4 +822,47 @@ void testScenarioOutlineWithDocstringBeforeSteps() {
         assertEquals(3, outline.getExamplesTables().get(0).getTable().getRows().size());
     }
 
+    @Test
+    void testDocstringWithAtSignTokenization() {
+        // Debug: verify @ inside docstring is NOT tokenized as G_TAG
+        String text = "Feature: test\nScenario Outline: x\n  \"\"\"\n  @foo\n  \"\"\"\n  * print '<a>'\nExamples:\n  | a |\n  | 1 |\n";
+        Resource resource = Resource.text(text);
+        GherkinLexer lexer = new GherkinLexer(resource);
+        Token token;
+        boolean foundTagInDocstring = false;
+        do {
+            token = lexer.nextToken();
+            if (token.type == TokenType.G_TAG && token.getText().contains("foo")) {
+                foundTagInDocstring = true;
+            }
+        } while (token.type != TokenType.EOF);
+        assertFalse(foundTagInDocstring, "@foo inside docstring should NOT be tokenized as G_TAG");
+    }
+
+    @Test
+    void testDocstringWithAtSignDoesNotBreakParsing() {
+        // https://github.com/karatelabs/karate/issues/2775
+        // An @ inside a docstring should NOT be tokenized as a tag
+        parseWithAst("""
+                Feature: Docstring with @
+                @test
+                Scenario Outline: My outline
+                    \"\"\"
+                    @This is a doc comment describing the outline.
+                    \"\"\"
+                    * print "row: <label>"
+                Examples:
+                    | label |
+                    | A     |
+                    | B     |
+                """);
+        assertNotNull(outline, "Outline should be parsed");
+        assertEquals("My outline", outline.getName());
+        assertEquals(1, outline.getSteps().size());
+        assertEquals(1, outline.getExamplesTables().size());
+        assertEquals(3, outline.getExamplesTables().get(0).getTable().getRows().size());
+        // The bare docstring is consumed as documentation, not attached to any step
+        assertNull(outline.getSteps().get(0).getDocString());
+    }
+
 }