Description:

Currently, XdocsExamplesAstConsistencyTest only validates that examples have the same AST structure (token types and tree hierarchy), but does not validate that literal values within the code match between examples.

Problem:

The StructuralAstNode class only stores and compares token types, not the actual text/values of literals. This means examples can have different literal values but still pass the consistency check.

Example from PR #18505 :
In checks/whitespace/emptyforinitializerpad, the examples had different loop conditions:

• Example1: for ( ; i < 1; i++ )
• Example2: for ( ; i < 2; i++ )

These have identical AST structure (same token types: LITERAL_FOR, EXPR, LT, NUM_INT, etc.) but different semantics due to the literal values 1 vs 2.
As Discussed here : #18505 (review)

Current Behavior:

private static final class StructuralAstNode {
    private final int type;  // Only stores token TYPE
    private final List<StructuralAstNode> children = new ArrayList<>();
    
    // equals() only compares type and children structure
    // Does NOT compare literal values like "1" vs "2"
}

Impact:

Examples can diverge in their literal values without detection:

• Numeric literals: int x = 5 vs int x = 10
• String literals: String s = "hello" vs String s = "world"
• Character literals: char c = 'a' vs char c = 'b'
• Boolean literals: if (true) vs if (false)

This defeats the purpose of consistency testing, as examples that should be identical can have different behavior.

Related:

• Discovered in PR checkstyle/checkstyle Issue #18435: Remove emptyforinitializerpad Example2 from XdocsExampl… #18505
• Issue Fix xdocs Examples AST Consistency Test (Reduce suppressions list) #18435 tracks reducing the SUPPRESSED_EXAMPLES list