feat: sync with upstream phpdoc-parser v1.25-v1.33

rainx · rainx · commit 9243723a3470 · 2026-03-13T14:07:50.000+08:00
Adds features from PHPStan phpdoc-parser v1.25.0 through v1.33.0:

- Callable template types: `Closure&lt;T&gt;(T): T` syntax
- Template tag lower bounds: `@template T super int`
- Unsealed array shapes: `array{foo: int, ...}` and `array{...&lt;string, int&gt;}`
- Non-empty array/list shapes: `non-empty-array{...}`, `non-empty-list{...}`
- Array shape key constants: `array{Foo::BAR: int}`
- New PHPDoc tags: @param-closure-this, @param-immediately-invoked-callable,
  @param-later-invoked-callable, @pure-unless-callable-is-impure,
  @require-extends, @require-implements
- Unified SealedTagValueNode (replaces PhpstanSealedTagValueNode and
  PsalmInheritorsTagValueNode)
- Phan annotation aliases (@phan-param, @phan-var, @phan-return, etc.)
- Moved parseTemplateTagValue from PhpDocParser to TypeParser (upstream refactor)
diff --git a/src/index.ts b/src/index.ts
@@ -27,6 +27,9 @@ export { InvalidTagValueNode } from './phpdoc-parser/ast/php-doc/invalid-tag-val
 export { MethodTagValueNode } from './phpdoc-parser/ast/php-doc/method-tag-value-node';
 export { MethodTagValueParameterNode } from './phpdoc-parser/ast/php-doc/method-tag-value-parameter-node';
 export { MixinTagValueNode } from './phpdoc-parser/ast/php-doc/mixin-tag-value-node';
+export { ParamClosureThisTagValueNode } from './phpdoc-parser/ast/php-doc/param-closure-this-tag-value-node';
+export { ParamImmediatelyInvokedCallableTagValueNode } from './phpdoc-parser/ast/php-doc/param-immediately-invoked-callable-tag-value-node';
+export { ParamLaterInvokedCallableTagValueNode } from './phpdoc-parser/ast/php-doc/param-later-invoked-callable-tag-value-node';
 export { ParamOutTagValueNode } from './phpdoc-parser/ast/php-doc/param-out-tag-value-node';
 export { ParamTagValueNode } from './phpdoc-parser/ast/php-doc/param-tag-value-node';
 export { PhpDocChildNode } from './phpdoc-parser/ast/php-doc/php-doc-child-node';
@@ -35,7 +38,11 @@ export { PhpDocTagNode } from './phpdoc-parser/ast/php-doc/php-doc-tag-node';
 export { PhpDocTagValueNode } from './phpdoc-parser/ast/php-doc/php-doc-tag-value-node';
 export { PhpDocTextNode } from './phpdoc-parser/ast/php-doc/php-doc-text-node';
 export { PropertyTagValueNode } from './phpdoc-parser/ast/php-doc/property-tag-value-node';
+export { PureUnlessCallableIsImpureTagValueNode } from './phpdoc-parser/ast/php-doc/pure-unless-callable-is-impure-tag-value-node';
+export { RequireExtendsTagValueNode } from './phpdoc-parser/ast/php-doc/require-extends-tag-value-node';
+export { RequireImplementsTagValueNode } from './phpdoc-parser/ast/php-doc/require-implements-tag-value-node';
 export { ReturnTagValueNode } from './phpdoc-parser/ast/php-doc/return-tag-value-node';
+export { SealedTagValueNode } from './phpdoc-parser/ast/php-doc/sealed-tag-value-node';
 export { SelfOutTagValueNode } from './phpdoc-parser/ast/php-doc/self-out-tag-value-node';
 export { TemplateTagValueNode } from './phpdoc-parser/ast/php-doc/template-tag-value-node';
 export { ThrowsTagValueNode } from './phpdoc-parser/ast/php-doc/throws-tag-value-node';
@@ -46,6 +53,7 @@ export { UsesTagValueNode } from './phpdoc-parser/ast/php-doc/uses-tag-value-nod
 export { VarTagValueNode } from './phpdoc-parser/ast/php-doc/var-tag-value-node';
 export { ArrayShapeItemNode } from './phpdoc-parser/ast/type/array-shape-item-node';
 export { ArrayShapeNode } from './phpdoc-parser/ast/type/array-shape-node';
+export { ArrayShapeUnsealedTypeNode } from './phpdoc-parser/ast/type/array-shape-unsealed-type-node';
 export { ArrayTypeNode } from './phpdoc-parser/ast/type/array-type-node';
 export { CallableTypeNode } from './phpdoc-parser/ast/type/callable-type-node';
 export { CallableTypeParameterNode } from './phpdoc-parser/ast/type/callable-type-parameter-node';
diff --git a/src/phpdoc-parser/ast/php-doc/param-closure-this-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/param-closure-this-tag-value-node.ts
@@ -0,0 +1,20 @@
+import type { TypeNode } from '../type/type-node';
+import { PhpDocTagValueNode } from './php-doc-tag-value-node';
+
+export class ParamClosureThisTagValueNode extends PhpDocTagValueNode {
+  constructor(
+    public type: TypeNode,
+    public parameterName: string,
+    public description: string,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    return `${this.type.toString()} ${this.parameterName} ${this.description}`.trim();
+  }
+
+  public getNodeType(): string {
+    return 'ParamClosureThisTagValueNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/php-doc/param-immediately-invoked-callable-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/param-immediately-invoked-callable-tag-value-node.ts
@@ -0,0 +1,18 @@
+import { PhpDocTagValueNode } from './php-doc-tag-value-node';
+
+export class ParamImmediatelyInvokedCallableTagValueNode extends PhpDocTagValueNode {
+  constructor(
+    public parameterName: string,
+    public description: string,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    return `${this.parameterName} ${this.description}`.trim();
+  }
+
+  public getNodeType(): string {
+    return 'ParamImmediatelyInvokedCallableTagValueNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/php-doc/param-later-invoked-callable-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/param-later-invoked-callable-tag-value-node.ts
@@ -0,0 +1,18 @@
+import { PhpDocTagValueNode } from './php-doc-tag-value-node';
+
+export class ParamLaterInvokedCallableTagValueNode extends PhpDocTagValueNode {
+  constructor(
+    public parameterName: string,
+    public description: string,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    return `${this.parameterName} ${this.description}`.trim();
+  }
+
+  public getNodeType(): string {
+    return 'ParamLaterInvokedCallableTagValueNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/php-doc/pure-unless-callable-is-impure-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/pure-unless-callable-is-impure-tag-value-node.ts
@@ -0,0 +1,18 @@
+import { PhpDocTagValueNode } from './php-doc-tag-value-node';
+
+export class PureUnlessCallableIsImpureTagValueNode extends PhpDocTagValueNode {
+  constructor(
+    public parameterName: string,
+    public description: string,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    return `${this.parameterName} ${this.description}`.trim();
+  }
+
+  public getNodeType(): string {
+    return 'PureUnlessCallableIsImpureTagValueNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/php-doc/require-extends-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/require-extends-tag-value-node.ts
@@ -0,0 +1,19 @@
+import type { TypeNode } from '../type/type-node';
+import { PhpDocTagValueNode } from './php-doc-tag-value-node';
+
+export class RequireExtendsTagValueNode extends PhpDocTagValueNode {
+  constructor(
+    public type: TypeNode,
+    public description: string,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    return `${this.type.toString()} ${this.description}`.trim();
+  }
+
+  public getNodeType(): string {
+    return 'RequireExtendsTagValueNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/php-doc/require-implements-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/require-implements-tag-value-node.ts
@@ -0,0 +1,19 @@
+import type { TypeNode } from '../type/type-node';
+import { PhpDocTagValueNode } from './php-doc-tag-value-node';
+
+export class RequireImplementsTagValueNode extends PhpDocTagValueNode {
+  constructor(
+    public type: TypeNode,
+    public description: string,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    return `${this.type.toString()} ${this.description}`.trim();
+  }
+
+  public getNodeType(): string {
+    return 'RequireImplementsTagValueNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/php-doc/sealed-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/sealed-tag-value-node.ts
@@ -0,0 +1,19 @@
+import type { TypeNode } from '../type/type-node';
+import { PhpDocTagValueNode } from './php-doc-tag-value-node';
+
+export class SealedTagValueNode extends PhpDocTagValueNode {
+  constructor(
+    public type: TypeNode,
+    public description: string,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    return `${this.type.toString()} ${this.description}`.trim();
+  }
+
+  public getNodeType(): string {
+    return 'SealedTagValueNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/php-doc/template-tag-value-node.ts b/src/phpdoc-parser/ast/php-doc/template-tag-value-node.ts
@@ -7,17 +7,20 @@ export class TemplateTagValueNode extends PhpDocTagValueNode {
     public bound: TypeNode | null,
     public description: string,
     public defaultTypeNode: TypeNode | null = null,
+    public lowerBound: TypeNode | null = null,
   ) {
     super();
   }
 
   public toString(): string {
     const bound = this.bound !== null ? ` of ${this.bound.toString()}` : '';
+    const lowerBoundStr =
+      this.lowerBound !== null ? ` super ${this.lowerBound.toString()}` : '';
     const defaultString =
       this.defaultTypeNode !== null
         ? ` = ${this.defaultTypeNode.toString()}`
         : '';
-    return `${this.name}${bound}${defaultString} ${this.description}`.trim();
+    return `${this.name}${bound}${lowerBoundStr}${defaultString} ${this.description}`.trim();
   }
 
   public getNodeType(): string {
diff --git a/src/phpdoc-parser/ast/type/array-shape-item-node.ts b/src/phpdoc-parser/ast/type/array-shape-item-node.ts
@@ -1,5 +1,6 @@
 import type { ConstExprIntegerNode } from '../const-expr/const-expr-integer-node';
 import type { ConstExprStringNode } from '../const-expr/const-expr-string-node';
+import type { ConstFetchNode } from '../const-expr/const-fetch-node';
 import type { IdentifierTypeNode } from './identifier-type-node';
 import { TypeNode } from './type-node';
 
@@ -8,6 +9,7 @@ export class ArrayShapeItemNode extends TypeNode {
     public keyName:
       | ConstExprIntegerNode
       | ConstExprStringNode
+      | ConstFetchNode
       | IdentifierTypeNode
       | null,
     public optional: boolean,
diff --git a/src/phpdoc-parser/ast/type/array-shape-node.ts b/src/phpdoc-parser/ast/type/array-shape-node.ts
@@ -1,28 +1,48 @@
 import type { ArrayShapeItemNode } from './array-shape-item-node';
+import type { ArrayShapeUnsealedTypeNode } from './array-shape-unsealed-type-node';
 import { TypeNode } from './type-node';
 
 export enum ArrayShapeNodeKind {
   ARRAY = 'array',
   LIST = 'list',
+  NON_EMPTY_ARRAY = 'non-empty-array',
+  NON_EMPTY_LIST = 'non-empty-list',
 }
 
 export class ArrayShapeNode extends TypeNode {
   constructor(
     public items: (ArrayShapeItemNode | string)[],
     public sealed: boolean = true,
     public kind: ArrayShapeNodeKind = ArrayShapeNodeKind.ARRAY,
+    public unsealedType: ArrayShapeUnsealedTypeNode | null = null,
   ) {
     super();
     this.items = items;
     this.sealed = sealed;
     this.kind = kind;
+    this.unsealedType = unsealedType;
+  }
+
+  public static createSealed(
+    items: (ArrayShapeItemNode | string)[],
+    kind: ArrayShapeNodeKind = ArrayShapeNodeKind.ARRAY,
+  ): ArrayShapeNode {
+    return new ArrayShapeNode(items, true, kind, null);
+  }
+
+  public static createUnsealed(
+    items: (ArrayShapeItemNode | string)[],
+    unsealedType: ArrayShapeUnsealedTypeNode | null,
+    kind: ArrayShapeNodeKind = ArrayShapeNodeKind.ARRAY,
+  ): ArrayShapeNode {
+    return new ArrayShapeNode(items, false, kind, unsealedType);
   }
 
   public toString(): string {
-    const { items } = this;
+    const items: (ArrayShapeItemNode | string)[] = [...this.items];
 
     if (!this.sealed) {
-      items.push('...');
+      items.push(`...${  this.unsealedType !== null ? this.unsealedType.toString() : ''}`);
     }
 
     return `${this.kind}{${items.join(', ')}}`;
diff --git a/src/phpdoc-parser/ast/type/array-shape-unsealed-type-node.ts b/src/phpdoc-parser/ast/type/array-shape-unsealed-type-node.ts
@@ -0,0 +1,21 @@
+import { TypeNode } from './type-node';
+
+export class ArrayShapeUnsealedTypeNode extends TypeNode {
+  constructor(
+    public valueType: TypeNode,
+    public keyType: TypeNode | null,
+  ) {
+    super();
+  }
+
+  public toString(): string {
+    if (this.keyType !== null) {
+      return `<${this.keyType.toString()}, ${this.valueType.toString()}>`;
+    }
+    return `<${this.valueType.toString()}>`;
+  }
+
+  public getNodeType(): string {
+    return 'ArrayShapeUnsealedTypeNode';
+  }
+}
diff --git a/src/phpdoc-parser/ast/type/callable-type-node.ts b/src/phpdoc-parser/ast/type/callable-type-node.ts
@@ -1,3 +1,4 @@
+import type { TemplateTagValueNode } from '../php-doc/template-tag-value-node';
 import type { CallableTypeParameterNode } from './callable-type-parameter-node';
 import type { IdentifierTypeNode } from './identifier-type-node';
 import { TypeNode } from './type-node';
@@ -7,6 +8,7 @@ export class CallableTypeNode extends TypeNode {
     public identifier: IdentifierTypeNode,
     public parameters: CallableTypeParameterNode[],
     public returnType: TypeNode,
+    public templateTypes: TemplateTagValueNode[] = [],
   ) {
     super();
   }
@@ -16,8 +18,9 @@ export class CallableTypeNode extends TypeNode {
     if (returnType instanceof CallableTypeNode) {
       returnType = `(${returnType.toString()})`;
     }
+    const template = this.templateTypes.length > 0 ? `<${this.templateTypes.join(', ')}>` : '';
     const parameters = this.parameters.join(', ');
-    return `${this.identifier.toString()}(${parameters}): ${returnType.toString()}`;
+    return `${this.identifier.toString()}${template}(${parameters}): ${returnType.toString()}`;
   }
 
   public getNodeType(): string {
diff --git a/src/phpdoc-parser/parser/php-doc-parser.ts b/src/phpdoc-parser/parser/php-doc-parser.ts
diff --git a/src/phpdoc-parser/parser/type-parser.ts b/src/phpdoc-parser/parser/type-parser.ts
diff --git a/tests/parser/upstream-2024-features.test.ts b/tests/parser/upstream-2024-features.test.ts
