CucumberND table headers might be missing

[uuf6429]

The following line:

Gherkin/src/Behat/Gherkin/Loader/CucumberNDJsonAstLoader.php

Line 160 in e016902

$table[$tableJson['tableHeader']['location']['line']] = array_column($tableJson['tableHeader']['cells'], 'value');

assumes that tableHeader is always set, but according to the spec schema, tableHeader is not required, and therefore optional.

I discovered this while implementing PHPStan fixes, using hand-written schema in PHPStan types DSL:

/**
 * @phpstan-type TExamples THasTags&array{
 *     location: TLocation,
 *     keyword: string,
 *     name: string,
 *     description: string,
 *     tableHeader?: TTableRow,              <-----
 *     tableBody: list<TTableRow>,
 *     id: string,
 * }
 */

What shall we do about this?

1. Make the PHPStan type mandatory (by removing the ?) and generally ignore the code.
2. Make PHPStan ignore that line (@phpstan-ignore-next-line)
3. Skip that line when the header is not set:

   if (isset($tableJson['tableHeader'])) {
       $table[$tableJson['tableHeader']['location']['line']] = array_column($tableJson['tableHeader']['cells'], 'value');
   }

4. Create an empty table row (representing the header) when not set. I tried to hack up some code, but it's not as easy as it sounds:
   • if we take the line (row index) as the first-body-row-line - 1, it might conflict with an existing line
   • what would the columns be? empty strings?
5. Something else...?

I think option 3 sounds reasonable, but we need to be sure it doesn't change behaviour.

[stof]

Well, is this property actually optional in the Cucumber format that we want to load here ? That's the first question. If it is not actually optional, we should fix the type (option 1). If it is indeed optional, we should fix the code (option 2 is bad in any case: if phpstan tells us that our code is broken, ignoring it still makes our code broken)

[uuf6429]

Well, is this property actually optional in the Cucumber format that we want to load here ?

I cannot fully answer that because this was the first time I'm looking at the code and I haven't in fact even used it before (as far as I know).

The link I posted seemed authoritative - or at least, that seemed to be the point of the https://github.com/cucumber/messages repo.

The generated typescript also seems to make example table headers optional: https://github.com/cucumber/messages/blob/e1537b07e511feb6405ed9aa00261ff79d8a9710/javascript/src/messages.ts#L174 as well as the spec here: https://github.com/cucumber/messages/blob/main/messages.md#examples

(honestly I don't fully understand the reasoning, it seems to me that examples must have a header - otherwise how would it map the values to placeholders? and additionally, how can it determine when a row is a header and when it isn't? afaik the top row was always considered as the header)

[uuf6429]

Making the PHPStan part required would technically break spec parity (option 1).

On the other hand, putting the header parsing in a condition (option 3) might put us in a bind, seeing as we do not distinguish between a header row and a table without a header (we just keep rows).

[ciaranmcnulty]

The cucumber parsers no longer populate TableHeader - I believe it's still in the JSON schema for BC reasons

If this class is only being used for parsing the testData (I can't recall) it's fine to assume it'll never be set.