feat!: sync with upstream phpdoc-parser v2.0-v2.1

BREAKING CHANGES:
- Merge QuoteAwareConstExprStringNode into ConstExprStringNode: quoteType
  is now a required constructor parameter (SINGLE_QUOTED/DOUBLE_QUOTED)
- Remove QuoteAwareConstExprStringNode class
- Remove quoteAwareConstExprString parameter from ConstExprParser and
  TypeParser constructors (always quote-aware now)

New features:
- Add ParserConfig class for centralized parser configuration
- Add Comment class for inline comments in type expressions
- Add TOKEN_COMMENT to Lexer for // comment tokenization
- Add skipNewLineTokensAndConsumeComments() to TokenIterator
- Add flushComments() to TokenIterator
- Add COMMENTS attribute constant
- Speculative union/intersection parsing across newlines with comments
  (enrichTypeOnUnionOrIntersection pattern from upstream)

Internal changes:
- TokenIterator savepoints now preserve comment state
- All tryConsumeTokenType(TOKEN_PHPDOC_EOL) calls in TypeParser replaced
  with skipNewLineTokensAndConsumeComments()
- Transpiler uses ConstExprStringNode.value for property names instead of
  toString() to avoid quoted output

Author: rainx

src/index.ts

@@ -1,5 +1,6 @@
 export { AbstractNodeVisitor } from './phpdoc-parser/ast/abstract-node-visitor';
 export { BaseNode } from './phpdoc-parser/ast/base-node';
+export { Comment } from './phpdoc-parser/ast/comment';
 export { ConstExprArrayItemNode } from './phpdoc-parser/ast/const-expr/const-expr-array-item-node';
 export { ConstExprArrayNode } from './phpdoc-parser/ast/const-expr/const-expr-array-node';
 export { ConstExprFalseNode } from './phpdoc-parser/ast/const-expr/const-expr-false-node';
@@ -10,7 +11,6 @@ export { ConstExprNullNode } from './phpdoc-parser/ast/const-expr/const-expr-nul
 export { ConstExprStringNode } from './phpdoc-parser/ast/const-expr/const-expr-string-node';
 export { ConstExprTrueNode } from './phpdoc-parser/ast/const-expr/const-expr-true-node';
 export { ConstFetchNode } from './phpdoc-parser/ast/const-expr/const-fetch-node';
-export { QuoteAwareConstExprStringNode } from './phpdoc-parser/ast/const-expr/quote-aware-const-expr-string-node';
 export type { Node } from './phpdoc-parser/ast/node';
 export { NodeTraverser } from './phpdoc-parser/ast/node-traverser';
 export type { NodeVisitor } from './phpdoc-parser/ast/node-visitor';
@@ -79,6 +79,7 @@ export { PhpDocParser } from './phpdoc-parser/parser/php-doc-parser';
 export { StringUnescaper } from './phpdoc-parser/parser/string-unescaper';
 export { TokenIterator } from './phpdoc-parser/parser/token-iterator';
 export { TypeParser } from './phpdoc-parser/parser/type-parser';
+export { ParserConfig } from './phpdoc-parser/parser-config';
 export { Printer } from './phpdoc-parser/printer/printer';
 export * from './phpdoc-parser/transpiler/helpers';
 export * from './phpdoc-parser/transpiler/php-doc-to-typescript-type-transpiler';

src/phpdoc-parser/ast/comment.ts

@@ -0,0 +1,17 @@
+export class Comment {
+  public text: string;
+
+  public startLine: number;
+
+  public startIndex: number;
+
+  constructor(text: string, startLine: number = -1, startIndex: number = -1) {
+    this.text = text;
+    this.startLine = startLine;
+    this.startIndex = startIndex;
+  }
+
+  getReformattedText(): string {
+    return this.text.trim();
+  }
+}

src/phpdoc-parser/ast/const-expr/const-expr-node.ts

@@ -8,7 +8,6 @@ import type { ConstExprNullNode } from './const-expr-null-node';
 import type { ConstExprStringNode } from './const-expr-string-node';
 import type { ConstExprTrueNode } from './const-expr-true-node';
 import type { ConstFetchNode } from './const-fetch-node';
-import type { QuoteAwareConstExprStringNode } from './quote-aware-const-expr-string-node';
 
 export class ConstExprNode extends BaseNode {
   public getNodeType(): string {
@@ -31,10 +30,6 @@ export class ConstExprNode extends BaseNode {
     return this.getNodeType() === 'ConstExprFalseNode';
   }
 
-  public isQuoteAwareConstExprStringNode(): this is QuoteAwareConstExprStringNode {
-    return this.getNodeType() === 'QuoteAwareConstExprStringNode';
-  }
-
   public isConstExprNullNode(): this is ConstExprNullNode {
     return this.getNodeType() === 'ConstExprNullNode';
   }

src/phpdoc-parser/ast/const-expr/const-expr-string-node.ts

@@ -1,12 +1,55 @@
 import { ConstExprNode } from './const-expr-node';
 
 export class ConstExprStringNode extends ConstExprNode {
-  constructor(public value: string) {
+  public static readonly SINGLE_QUOTED = 1;
+
+  public static readonly DOUBLE_QUOTED = 2;
+
+  constructor(
+    public value: string,
+    public quoteType: number,
+  ) {
     super();
   }
 
   public toString(): string {
-    return this.value;
+    if (this.quoteType === ConstExprStringNode.SINGLE_QUOTED) {
+      return `'${this.value.replace(/[\\']/g, '\\$&')}'`;
+    }
+
+    return `"${this.escapeDoubleQuotedString()}"`;
+  }
+
+  private escapeDoubleQuotedString(): string {
+    // eslint-disable-next-line no-control-regex
+    let escaped = this.value.replace(/["\n\r\t\x0B\f\v\\$]/g, '\\$&');
+
+    const regexes = [
+      // eslint-disable-next-line no-control-regex
+      /[\x00-\x08\x0E-\x1F]/g,
+      /[\xC0-\xC1]/g,
+      /[\xF5-\xFF]/g,
+      /\xE0[\x80-\x9F]/g,
+      /\xF0[\x80-\x8F]/g,
+      /[\xC2-\xDF](?![\x80-\xBF])/g,
+      /[\xE0-\xEF](?![\x80-\xBF]{2})/g,
+      /[\xF0-\xF4](?![\x80-\xBF]{3})/g,
+      // eslint-disable-next-line no-control-regex
+      /(?<=[\x00-\x7F\xF5-\xFF])[\x80-\xBF]/g,
+      /(?<![\xC2-\xDF]|[\xE0-\xEF]|[\xE0-\xEF][\x80-\xBF]|[\xF0-\xF4]|[\xF0-\xF4][\x80-\xBF]|[\xF0-\xF4][\x80-\xBF]{2})[\x80-\xBF]/g,
+      /(?<=[\xE0-\xEF])[\x80-\xBF](?![\x80-\xBF])/g,
+      /(?<=[\xF0-\xF4])[\x80-\xBF](?![\x80-\xBF]{2})/g,
+      /(?<=[\xF0-\xF4][\x80-\xBF])[\x80-\xBF](?![\x80-\xBF])/g,
+    ];
+
+    for (const regex of regexes) {
+      escaped = escaped.replace(regex, (match) => {
+        const hex = match.charCodeAt(0).toString(16);
+        return `\\x${'0'.repeat(2 - hex.length) + hex}`;
+      });
+    }
+
+    return escaped;
   }
 
   public getNodeType(): string {

src/phpdoc-parser/ast/const-expr/quote-aware-const-expr-string-node.ts

@@ -45,4 +45,6 @@ export enum Attribute {
   END_INDEX = 'endIndex',
 
   ORIGINAL_NODE = 'originalNode',
+
+  COMMENTS = 'comments',
 }

src/phpdoc-parser/ast/types.ts

@@ -69,6 +69,8 @@ export class Lexer {
 
   public static TOKEN_ARROW = 'TOKEN_ARROW';
 
+  public static TOKEN_COMMENT = 'TOKEN_COMMENT';
+
   public static TOKEN_LABELS = {
     [Lexer.TOKEN_REFERENCE]: '&',
     [Lexer.TOKEN_UNION]: '|',
@@ -84,6 +86,7 @@ export class Lexer {
     [Lexer.TOKEN_OPEN_CURLY_BRACKET]: '{',
     [Lexer.TOKEN_CLOSE_CURLY_BRACKET]: '}',
     [Lexer.TOKEN_COMMA]: ',',
+    [Lexer.TOKEN_COMMENT]: '//',
     [Lexer.TOKEN_COLON]: ':',
     [Lexer.TOKEN_VARIADIC]: '...',
     [Lexer.TOKEN_DOUBLE_COLON]: '::',
@@ -160,6 +163,7 @@ export class Lexer {
       [Lexer.TOKEN_OPEN_CURLY_BRACKET]: '\\{',
       [Lexer.TOKEN_CLOSE_CURLY_BRACKET]: '\\}',
       [Lexer.TOKEN_COMMA]: ',',
+      [Lexer.TOKEN_COMMENT]: '\\/\\/[^\\r\\n]*(?=\\n|\\r|\\*\\/)',
       [Lexer.TOKEN_VARIADIC]: '\\.\\.\\.',
       [Lexer.TOKEN_DOUBLE_COLON]: '::',
       [Lexer.TOKEN_DOUBLE_ARROW]: '=>',

src/phpdoc-parser/lexer/lexer.ts

@@ -0,0 +1,19 @@
+export class ParserConfig {
+  public useLinesAttributes: boolean;
+
+  public useIndexAttributes: boolean;
+
+  public useCommentsAttributes: boolean;
+
+  constructor(
+    usedAttributes: {
+      lines?: boolean;
+      indexes?: boolean;
+      comments?: boolean;
+    } = {},
+  ) {
+    this.useLinesAttributes = usedAttributes.lines ?? false;
+    this.useIndexAttributes = usedAttributes.indexes ?? false;
+    this.useCommentsAttributes = usedAttributes.comments ?? false;
+  }
+}

src/phpdoc-parser/parser-config.ts

@@ -8,7 +8,6 @@ import { ConstExprNullNode } from '../ast/const-expr/const-expr-null-node';
 import { ConstExprStringNode } from '../ast/const-expr/const-expr-string-node';
 import { ConstExprTrueNode } from '../ast/const-expr/const-expr-true-node';
 import { ConstFetchNode } from '../ast/const-expr/const-fetch-node';
-import { QuoteAwareConstExprStringNode } from '../ast/const-expr/quote-aware-const-expr-string-node';
 import { Attribute } from '../ast/types';
 import { Lexer } from '../lexer/lexer';
 import { ParserException } from './parser-exception';
@@ -25,7 +24,6 @@ export class ConstExprParser {
    */
   constructor(
     private unescapeStrings: boolean = false,
-    private quoteAwareConstExprString: boolean = false,
     usedAttributes: { lines?: boolean; indexes?: boolean } = {},
   ) {
     this.useLinesAttributes = usedAttributes.lines ?? false;
@@ -76,23 +74,14 @@ export class ConstExprParser {
       }
       tokens.next();
 
-      if (this.quoteAwareConstExprString) {
-        return this.enrichWithAttributes(
-          tokens,
-          new QuoteAwareConstExprStringNode(
-            value,
-            type === Lexer.TOKEN_SINGLE_QUOTED_STRING
-              ? QuoteAwareConstExprStringNode.SINGLE_QUOTED
-              : QuoteAwareConstExprStringNode.DOUBLE_QUOTED,
-          ),
-          startLine,
-          startIndex,
-        );
-      }
-
       return this.enrichWithAttributes(
         tokens,
-        new ConstExprStringNode(value),
+        new ConstExprStringNode(
+          value,
+          type === Lexer.TOKEN_SINGLE_QUOTED_STRING
+            ? ConstExprStringNode.SINGLE_QUOTED
+            : ConstExprStringNode.DOUBLE_QUOTED,
+        ),
         startLine,
         startIndex,
       );

src/phpdoc-parser/parser/const-expr-parser.ts

@@ -1,3 +1,4 @@
+import { Comment } from '../ast/comment';
 import { Lexer } from '../lexer/lexer';
 import { ParserException } from './parser-exception';
 
@@ -6,7 +7,9 @@ export class TokenIterator {
 
   private index: number;
 
-  private savePoints: number[] = [];
+  private comments: Comment[] = [];
+
+  private savePoints: Array<[number, Comment[]]> = [];
 
   private skippedTokenTypes: string[] = [Lexer.TOKEN_HORIZONTAL_WS];
 
@@ -158,6 +161,47 @@ export class TokenIterator {
     return true;
   }
 
+  public flushComments(): Comment[] {
+    const res = this.comments;
+    this.comments = [];
+    return res;
+  }
+
+  public skipNewLineTokensAndConsumeComments(): void {
+    if (this.currentTokenType() === Lexer.TOKEN_COMMENT) {
+      this.comments.push(
+        new Comment(
+          this.currentTokenValue(),
+          this.currentTokenLine(),
+          this.currentTokenIndex(),
+        ),
+      );
+      this.next();
+    }
+
+    if (!this.isCurrentTokenType(Lexer.TOKEN_PHPDOC_EOL)) {
+      return;
+    }
+
+    let foundNewLine: boolean;
+    do {
+      foundNewLine = this.tryConsumeTokenType(Lexer.TOKEN_PHPDOC_EOL);
+      if (this.currentTokenType() !== Lexer.TOKEN_COMMENT) {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      this.comments.push(
+        new Comment(
+          this.currentTokenValue(),
+          this.currentTokenLine(),
+          this.currentTokenIndex(),
+        ),
+      );
+      this.next();
+    } while (foundNewLine);
+  }
+
   private detectNewline(): void {
     const value = this.currentTokenValue();
     if (value.substring(0, 2) === '\r\n') {
@@ -228,17 +272,19 @@ export class TokenIterator {
   }
 
   public pushSavePoint(): void {
-    this.savePoints.push(this.index);
+    this.savePoints.push([this.index, [...this.comments]]);
   }
 
   public dropSavePoint(): void {
     this.savePoints.pop();
   }
 
   public rollback(): void {
-    const index = this.savePoints.pop();
-    // assert(index !== null);
-    this.index = index;
+    const savepoint = this.savePoints.pop();
+    if (savepoint === undefined) {
+      throw new Error('No save point to rollback to');
+    }
+    [this.index, this.comments] = savepoint;
   }
 
   throwError(