feat: add subscript access expression support for dataset static analysis

Support $v[0] string/array index access in data provider evaluation,
enabling conditional yield patterns like `if ($v[0] === 'a')` in
foreach loops.

Author: recca0120

packages/phpunit/src/Interpreter/AstParser/AstNode.ts

@@ -257,6 +257,13 @@ export interface ConstDeclarationNode {
     loc?: AstNodeLoc;
 }
 
+export interface SubscriptAccessNode {
+    kind: 'subscript_access_expression';
+    object: AstNode;
+    index: AstNode;
+    loc?: AstNodeLoc;
+}
+
 export interface ArrayCreationNode {
     kind: 'array_creation_expression';
     entries: ArrayEntryNode[];
@@ -317,4 +324,5 @@ export type AstNode =
     | VariableNode
     | NumberNode
     | ClassConstantAccessNode
-    | ConstDeclarationNode;
+    | ConstDeclarationNode
+    | SubscriptAccessNode;

packages/phpunit/src/Interpreter/AstParser/PhpParser/PhpParserAdapter.ts

@@ -135,6 +135,13 @@ function adaptNode(raw: RawNode): AstNode | undefined {
                 alternate: adaptNode(raw.falseExpr) ?? EMPTY_STRING_NODE,
                 loc: convertLoc(raw.loc),
             };
+        case 'offsetlookup':
+            return {
+                kind: 'subscript_access_expression',
+                object: adaptNode(raw.what) ?? EMPTY_STRING_NODE,
+                index: adaptNode(raw.offset) ?? EMPTY_STRING_NODE,
+                loc: convertLoc(raw.loc),
+            };
         case 'parenthesis':
             return raw.inner ? adaptNode(raw.inner) : undefined;
         default:

packages/phpunit/src/Interpreter/AstParser/TreeSitter/TreeSitterAdapter.ts

@@ -789,6 +789,16 @@ const expressionAdapters: Record<string, (node: SyntaxNode) => AstNode> = {
         name: node.namedChildren[1]?.text ?? '',
         loc: locOf(node),
     }),
+    subscript_expression: (node) => {
+        const object = node.namedChildren[0];
+        const index = node.namedChildren[1];
+        return {
+            kind: 'subscript_access_expression',
+            object: object ? adaptExpression(object) : EMPTY_STRING_NODE,
+            index: index ? adaptExpression(index) : EMPTY_STRING_NODE,
+            loc: locOf(node),
+        };
+    },
     anonymous_function_creation_expression: adaptClosure,
     anonymous_function: adaptClosure,
     arrow_function: adaptArrowFunction,

packages/phpunit/src/Interpreter/Expressions/Literals/SubscriptAccessExpression.ts

@@ -0,0 +1,22 @@
+import type { AstNode, SubscriptAccessNode } from '../../AstParser/AstNode';
+import type { Context, Expression } from '../Expression';
+
+class SubscriptAccessExpression implements Expression<unknown> {
+    supports(node: AstNode): boolean {
+        return node.kind === 'subscript_access_expression';
+    }
+
+    resolve(node: AstNode, context: Context): unknown {
+        const { object, index } = node as SubscriptAccessNode;
+        const obj = context.resolve(object);
+        const idx = context.resolve(index);
+
+        if ((typeof obj === 'string' || Array.isArray(obj)) && typeof idx === 'number') {
+            return obj[idx];
+        }
+
+        return undefined;
+    }
+}
+
+export const subscriptAccessExpression = new SubscriptAccessExpression();

packages/phpunit/src/Interpreter/Expressions/PhpExpression.ts

@@ -21,6 +21,7 @@ import { classConstantAccessExpression } from './Iterables/ClassConstantAccessEx
 import { encapsedStringExpression } from './Literals/EncapsedStringExpression';
 import { numberLiteralExpression } from './Literals/NumberLiteralExpression';
 import { stringLiteralExpression } from './Literals/StringLiteralExpression';
+import { subscriptAccessExpression } from './Literals/SubscriptAccessExpression';
 import { variableExpression } from './Literals/VariableExpression';
 import { binaryExpr } from './Operators/BinaryExpression';
 import { conditionalExpression } from './Operators/ConditionalExpression';
@@ -41,6 +42,7 @@ const allExpressions: Expression<unknown>[] = [
     variableExpression,
     stringLiteralExpression,
     numberLiteralExpression,
+    subscriptAccessExpression,
     encapsedStringExpression,
     binaryExpr,
     conditionalExpression,

packages/phpunit/src/Interpreter/evaluate.test.ts

@@ -515,6 +515,22 @@ describe.each(parsers)('DataProviderParser (%s)', (_name, createParser) => {
             ]);
         });
 
+        it('foreach loop with conditional yield using subscript access', () => {
+            const method = givenMethod(
+                `<?php class FooTest extends \\PHPUnit\\Framework\\TestCase {
+                    public static function provider() {
+                        foreach (['apple', 'banana', 'avocado', 'cherry'] as $v) {
+                            if ($v[0] === 'a') {
+                                yield $v => [$v];
+                            }
+                        }
+                    }
+                }`,
+                'provider',
+            );
+            expect(parseDataProvider(method)).toEqual(['data set "apple"', 'data set "avocado"']);
+        });
+
         it('yield key with strtoupper', () => {
             const method = givenMethod(
                 `<?php class FooTest extends \\PHPUnit\\Framework\\TestCase {