docs: detail enum output and sample generation

Author: pyramation

AST_RESEARCH.md

@@ -125,6 +125,20 @@ Because PG16 introduced large changes, direct translation from PG13 to PG17 may
 | 16 | JsonAggConstructor, JsonArrayAgg, JsonArrayConstructor, JsonArrayQueryConstructor, JsonConstructorExpr, JsonFormat, JsonIsPredicate, JsonKeyValue, JsonObjectAgg, JsonObjectConstructor, JsonOutput, JsonReturning, JsonValueExpr, RTEPermissionInfo |
 | 17 | JsonArgument, JsonBehavior, JsonExpr, JsonFuncExpr, JsonParseExpr, JsonScalarExpr, JsonSerializeExpr, JsonTable, JsonTableColumn, JsonTablePath, JsonTablePathScan, JsonTablePathSpec, JsonTableSiblingJoin, MergeSupportFunc, SinglePartitionSpec, WindowFuncRunCondition |
 
+## Generating AST Samples
+
+To fully understand structural differences we will compile **libpg-query** for
+each supported PostgreSQL version and capture JSON output for a library of
+representative queries. This multi-runtime parser setup lets us record actual
+ASTs from PG13 through PG17. These samples are essential for training upgrade
+logic and verifying enum representations:
+
+- PG13 and PG14 output enum values as integers
+- PG15+ output enums as their string names
+
+The generated samples will live under a dedicated directory and can be compared
+programmatically to spot changes beyond what the protobuf types reveal.
+
 
 ## Conclusion
 

README.md

@@ -104,6 +104,14 @@ npm install @pgsql/enums
 - **Need fingerprint, normalize, or deparse?** → Use `@libpg-query/parser` (PG 17 only)
 
 
+### Enum Output Format
+
+Earlier releases of `libpg_query` (PostgreSQL 13 and 14) emit **numeric** codes
+for enum fields in the parsed AST JSON. Starting with PG15 the JSON instead uses
+the **string name** of each enum value. When translating ASTs from older
+versions you must convert these integers to their corresponding strings.
+
+
 ## API Documentation
 
 For detailed API documentation and usage examples, see the package-specific READMEs:

parser/README.md

@@ -103,6 +103,13 @@ Each version export provides:
 - `parse(query)`: Parse a query (async)
 - `parseSync(query)`: Parse a query (sync, requires loadModule first)
 
+### Enum Output Format
+
+Parsing with PostgreSQL 13 and 14 returns enum fields as **integers** in the
+resulting AST JSON. From PG15 onward those fields contain the **string names** of
+the enum values. When upgrading ASTs across versions you may need to convert
+numeric enums from older parsers into strings.
+
 ## Credits
 
 Built on the excellent work of several contributors: