0
# AST Analysis Utilities
1

2
Comprehensive collection of utilities for React component and TypeScript/Flow analysis, providing low-level AST manipulation functions.
3

4
## Capabilities
5

6
### Utility Namespaces
7

8
Core utility namespaces for different types of AST analysis.
9

10
```typescript { .api }
11
namespace utils {
12
  /** JSDoc parsing and manipulation utilities */
13
  namespace docblock;
14
  /** Expression conversion utilities */
15
  namespace expressionTo;
16
  /** Flow type utility functions */
17
  namespace flowUtilityTypes;
18
  /** AST traversal utilities */
19
  namespace traverse;
20
}
21
```
22

23
### Docblock Utilities
24

25
JSDoc comment parsing and manipulation functions.
26

27
```typescript { .api }
28
namespace docblock {
29
  /** Parse JSDoc comment blocks into structured data */
30
  function parse(docblock: string): JSDocInfo;
31
  
32
  /** Extract docblock comment from AST node */
33
  function getDocblock(path: NodePath): string | null;
34
  
35
  /** Format docblock text with proper indentation */
36
  function format(docblock: string): string;
37
}
38

39
interface JSDocInfo {
40
  description?: string;
41
  tags: JSDocTag[];
42
}
43

44
interface JSDocTag {
45
  tag: string;
46
  name?: string;
47
  type?: string;
48
  description?: string;
49
}
50
```
51

52
### Expression Conversion Utilities
53

54
Functions for converting AST expressions to different formats.
55

56
```typescript { .api }
57
namespace expressionTo {
58
  /** Convert AST expression to string representation */
59
  function toString(path: NodePath): string;
60
  
61
  /** Convert AST expression to JavaScript value */
62
  function toValue(path: NodePath): unknown;
63
  
64
  /** Convert AST expression to type descriptor */
65
  function toType(path: NodePath): TypeDescriptor;
66
}
67
```
68

69
### Flow Type Utilities
70

71
Utilities specific to Flow type analysis.
72

73
```typescript { .api }
74
namespace flowUtilityTypes {
75
  /** Check if type annotation is a Flow utility type */
76
  function isUtilityType(path: NodePath): boolean;
77
  
78
  /** Extract utility type information */
79
  function getUtilityTypeInfo(path: NodePath): UtilityTypeInfo;
80
}
81

82
interface UtilityTypeInfo {
83
  name: string;
84
  parameters: TypeDescriptor[];
85
}
86
```
87

88
### Traversal Utilities
89

90
AST traversal and navigation functions.
91

92
```typescript { .api }
93
namespace traverse {
94
  /** Shallow visitor that ignores nested scopes */
95
  const shallowIgnoreVisitors: VisitorMap;
96
  
97
  /** Find all nodes matching a predicate */
98
  function findAll(
99
    path: NodePath, 
100
    predicate: (path: NodePath) => boolean
101
  ): NodePath[];
102
  
103
  /** Find first node matching a predicate */
104
  function findFirst(
105
    path: NodePath, 
106
    predicate: (path: NodePath) => boolean
107
  ): NodePath | null;
108
}
109
```
110

111
### Type Analysis Functions
112

113
Functions for extracting and analyzing type information.
114

115
```typescript { .api }
116
/** Extract Flow type information from AST nodes */
117
function getFlowType(path: NodePath): TypeDescriptor<FunctionSignatureType> | null;
118

119
/** Extract TypeScript type information from AST nodes */
120
function getTSType(path: NodePath): TypeDescriptor<TSFunctionSignatureType> | null;
121

122
/** Get type annotation from various AST node types */
123
function getTypeAnnotation(path: NodePath): NodePath | null;
124

125
/** Extract type identifier from type annotations */
126
function getTypeIdentifier(path: NodePath): string | null;
127

128
/** Get generic type parameters from functions or classes */
129
function getTypeParameters(path: NodePath): TypeParameters | null;
130
```
131

132
### Component Analysis Functions
133

134
Functions for analyzing React component patterns.
135

136
```typescript { .api }
137
/** Check if AST node represents a React component class */
138
function isReactComponentClass(path: NodePath): boolean;
139

140
/** Check if AST node represents a stateless component */
141
function isStatelessComponent(path: NodePath): boolean;
142

143
/** Check if method belongs to a React component */  
144
function isReactComponentMethod(path: NodePath): boolean;
145

146
/** Check if call expression is React.createElement */
147
function isReactCreateElementCall(path: NodePath): boolean;
148

149
/** Check if call expression is React.createClass */
150
function isReactCreateClassCall(path: NodePath): boolean;
151

152
/** Check if call expression is React.forwardRef */
153
function isReactForwardRefCall(path: NodePath): boolean;
154

155
/** Check if call expression is React.cloneElement */
156
function isReactCloneElementCall(path: NodePath): boolean;
157

158
/** Check if reference points to React builtin */
159
function isReactBuiltinReference(path: NodePath): boolean;
160
```
161

162
### Member Access Functions
163

164
Functions for analyzing object and class members.
165

166
```typescript { .api }
167
/** Get all members of a class or object */
168
function getMembers(path: NodePath): NodePath[];
169

170
/** Get class member value by name */
171
function getClassMemberValuePath(path: NodePath, name: string): NodePath | null;
172

173
/** Get member expression root identifier */
174
function getMemberExpressionRoot(path: NodePath): NodePath | null;
175

176
/** Get member expression value path */
177
function getMemberExpressionValuePath(path: NodePath, name: string): NodePath | null;
178

179
/** Get general member value path with type support */
180
function getMemberValuePath(path: NodePath, name: string): NodePath | null;
181

182
/** Check if definition type is supported for member extraction */
183
function isSupportedDefinitionType(path: NodePath): boolean;
184
```
185

186
### Property Analysis Functions
187

188
Functions for analyzing object properties and their values.
189

190
```typescript { .api }
191
/** Get property name, handling computed properties */
192
function getPropertyName(path: NodePath): string | null;
193

194
/** Get property value path from object expressions */
195
function getPropertyValuePath(path: NodePath, name: string): NodePath | null;
196

197
/** Get name or value from various AST node types */
198
function getNameOrValue(path: NodePath): string | null;
199

200
/** Get parameter name from function parameters */
201
function getParameterName(path: NodePath): string | null;
202

203
/** Prefix used for computed property names */
204
const COMPUTED_PREFIX: string;
205
```
206

207
### Resolution Functions
208

209
Functions for resolving references and values in the AST.
210

211
```typescript { .api }
212
/** Resolve AST path to its actual value */
213
function resolveToValue(path: NodePath): NodePath;
214

215
/** Resolve to module reference */
216
function resolveToModule(path: NodePath): string | null;
217

218
/** Resolve export declarations to their definitions */
219
function resolveExportDeclaration(path: NodePath): NodePath[];
220

221
/** Resolve function definition to its return value */
222
function resolveFunctionDefinitionToReturnValue(path: NodePath): NodePath | null;
223

224
/** Resolve generic type annotations */
225
function resolveGenericTypeAnnotation(path: NodePath): NodePath | null;
226

227
/** Resolve Higher-Order Component patterns */
228
function resolveHOC(path: NodePath): NodePath | null;
229

230
/** Resolve object pattern properties to values */
231
function resolveObjectPatternPropertyToValue(path: NodePath, key: string): NodePath | null;
232

233
/** Resolve object keys to array of strings */
234
function resolveObjectKeysToArray(path: NodePath): string[] | null;
235

236
/** Resolve object to array of property names */
237
function resolveObjectToNameArray(path: NodePath): string[] | null;
238

239
/** Resolve object values to array */
240
function resolveObjectValuesToArray(path: NodePath): NodePath[] | null;
241
```
242

243
### Validation Functions
244

245
Functions for validating and checking AST node properties.
246

247
```typescript { .api }
248
/** Check if assignment is destructuring pattern */
249
function isDestructuringAssignment(path: NodePath): boolean;
250

251
/** Check if assignment is exports or module.exports */
252
function isExportsOrModuleAssignment(path: NodePath): boolean;
253

254
/** Check if node is import specifier */
255
function isImportSpecifier(path: NodePath): boolean;
256

257
/** Check if PropType is required */
258
function isRequiredPropType(path: NodePath): boolean;
259

260
/** Check if Flow type is unreachable */
261
function isUnreachableFlowType(path: NodePath): boolean;
262

263
/** Check if module name refers to React */
264
function isReactModuleName(name: string): boolean;
265
```
266

267
### Processing Functions
268

269
Functions for processing and transforming documentation data.
270

271
```typescript { .api }
272
/** Normalize class definitions for consistent analysis */
273
function normalizeClassDefinition(path: NodePath): NodePath;
274

275
/** Parse JSDoc comments into structured data */
276
function parseJsDoc(docblock: string): JSDocInfo;
277

278
/** Post-process documentation for cleanup and validation */
279
function postProcessDocumentation(documentation: Documentation): Documentation;
280

281
/** Print AST values in readable format */
282
function printValue(path: NodePath): string;
283

284
/** Set property description from JSDoc */
285
function setPropDescription(prop: PropDescriptor, docblock: string): void;
286
```
287

288
### Method Analysis Functions
289

290
Functions for analyzing component methods and their signatures.
291

292
```typescript { .api }
293
/** Extract method documentation including parameters and return types */
294
function getMethodDocumentation(path: MethodNodePath): MethodDescriptor;
295

296
/** Find function return statement paths */
297
function findFunctionReturn(path: NodePath): NodePath[];
298

299
type MethodNodePath = NodePath<
300
  | ArrowFunctionExpression
301
  | FunctionExpression
302
  | FunctionDeclaration
303
  | ObjectMethod
304
  | ClassMethod
305
>;
306
```
307

308
### PropType Analysis Functions
309

310
Functions for analyzing PropTypes and prop-related patterns.
311

312
```typescript { .api }
313
/** Extract PropType information from AST nodes */
314
function getPropType(path: NodePath): PropTypeDescriptor | null;
315

316
/** Extract types from React component prop interfaces */
317
function getTypeFromReactComponent(path: NodePath): TypeDescriptor | null;
318

319
/** Apply function to all type properties */
320
function applyToTypeProperties(
321
  type: TypeDescriptor,
322
  callback: (property: TypeProperty) => void
323
): void;
324
```
325

326
### Type Parameters Interface
327

328
Interface for generic type parameter information.
329

330
```typescript { .api }
331
interface TypeParameters {
332
  /** Names of type parameters */
333
  names: string[];
334
  /** Constraints for each type parameter */
335
  constraints: (TypeDescriptor | null)[];
336
  /** Default types for each type parameter */
337
  defaults: (TypeDescriptor | null)[];
338
}
339
```
340

341
### Usage Examples
342

343
**Type Analysis:**
344

345
```typescript
346
import { utils } from "react-docgen";
347

348
// Extract TypeScript type information
349
const tsType = utils.getTSType(propPath);
350

351
// Get type annotation from various sources
352
const annotation = utils.getTypeAnnotation(componentPath);
353

354
// Check if component is React class
355
if (utils.isReactComponentClass(classPath)) {
356
  // Analyze class component
357
}
358
```
359

360
**Member Analysis:**
361

362
```typescript
363
// Get all class members
364
const members = utils.getMembers(classPath);
365

366
// Get specific property value
367
const propTypes = utils.getClassMemberValuePath(classPath, 'propTypes');
368

369
// Get property name (handles computed properties)
370
const propName = utils.getPropertyName(propertyPath);
371
```
372

373
**Resolution:**
374

375
```typescript
376
// Resolve reference to actual value
377
const resolved = utils.resolveToValue(referencePath);
378

379
// Resolve export to definition
380
const definitions = utils.resolveExportDeclaration(exportPath);
381

382
// Resolve HOC patterns
383
const innerComponent = utils.resolveHOC(hocPath);
384
```