0
# Definition System
1

2
The definition tracking system categorizes how variables are defined and provides detailed context about their declarations across different language constructs.
3

4
## Capabilities
5

6
### Definition Union Type
7

8
The main Definition type that represents all possible definition types in the system.
9

10
```typescript { .api }
11
type Definition = 
12
  | CatchClauseDefinition
13
  | ClassNameDefinition
14
  | FunctionNameDefinition
15
  | ImplicitGlobalVariableDefinition
16
  | ImportBindingDefinition
17
  | ParameterDefinition
18
  | TSEnumMemberDefinition
19
  | TSEnumNameDefinition
20
  | TSModuleNameDefinition
21
  | TypeDefinition
22
  | VariableDefinition;
23
```
24

25
### Definition Type Enumeration
26

27
Enumeration of all definition type identifiers used throughout the system.
28

29
```typescript { .api }
30
enum DefinitionType {
31
  CatchClause = "CatchClause",
32
  ClassName = "ClassName",
33
  FunctionName = "FunctionName", 
34
  ImplicitGlobalVariable = "ImplicitGlobalVariable",
35
  ImportBinding = "ImportBinding",
36
  Parameter = "Parameter",
37
  TSEnumMember = "TSEnumMemberName",
38
  TSEnumName = "TSEnumName",
39
  TSModuleName = "TSModuleName",
40
  Type = "Type",
41
  Variable = "Variable"
42
}
43
```
44

45
### Base Definition Interface
46

47
All definitions extend from a common base that provides essential definition information.
48

49
```typescript { .api }
50
interface DefinitionBase {
51
  /** Unique identifier for this definition instance */
52
  readonly $id: number;
53
  
54
  /** The type of this definition */
55
  readonly type: DefinitionType;
56
  
57
  /** The identifier node being defined */
58
  readonly name: TSESTree.BindingName;
59
  
60
  /** The AST node that creates this definition */
61
  readonly node: TSESTree.Node;
62
  
63
  /** The parent AST node containing the definition */
64
  readonly parent: TSESTree.Node | null;
65
  
66
  /** True if this definition creates a type binding */
67
  readonly isTypeDefinition: boolean;
68
  
69
  /** True if this definition creates a variable binding */
70
  readonly isVariableDefinition: boolean;
71
}
72
```
73

74
## JavaScript Definition Types
75

76
### Variable Definition
77

78
Definitions created by variable declarations (var, let, const).
79

80
```typescript { .api }
81
class VariableDefinition extends DefinitionBase {
82
  readonly type: DefinitionType.Variable;
83
  readonly node: TSESTree.VariableDeclarator;
84
  readonly parent: TSESTree.VariableDeclaration;
85
  readonly isTypeDefinition: false;
86
  readonly isVariableDefinition: true;
87
}
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
// VariableDefinition examples:
94
var x = 1;        // VariableDefinition for 'x'
95
let y = 2;        // VariableDefinition for 'y'  
96
const z = 3;      // VariableDefinition for 'z'
97

98
const [a, b] = arr;     // VariableDefinition for 'a' and 'b'
99
const {name, age} = obj; // VariableDefinition for 'name' and 'age'
100
```
101

102
### Function Name Definition
103

104
Definitions created by function declarations and named function expressions.
105

106
```typescript { .api }
107
class FunctionNameDefinition extends DefinitionBase {
108
  readonly type: DefinitionType.FunctionName;
109
  readonly node: TSESTree.FunctionDeclaration | TSESTree.FunctionExpression;
110
  readonly parent: TSESTree.Node | null;
111
  readonly isTypeDefinition: false;
112
  readonly isVariableDefinition: true;
113
}
114
```
115

116
### Parameter Definition
117

118
Definitions created by function parameters.
119

120
```typescript { .api }
121
class ParameterDefinition extends DefinitionBase {
122
  readonly type: DefinitionType.Parameter;
123
  readonly node: TSESTree.FunctionDeclaration | TSESTree.FunctionExpression 
124
               | TSESTree.ArrowFunctionExpression;
125
  readonly parent: TSESTree.Node | null;
126
  readonly isTypeDefinition: false;
127
  readonly isVariableDefinition: true;
128
}
129
```
130

131
### Class Name Definition
132

133
Definitions created by class declarations and expressions.
134

135
```typescript { .api }
136
class ClassNameDefinition extends DefinitionBase {
137
  readonly type: DefinitionType.ClassName;
138
  readonly node: TSESTree.ClassDeclaration | TSESTree.ClassExpression;
139
  readonly parent: TSESTree.Node | null;
140
  readonly isTypeDefinition: true;
141
  readonly isVariableDefinition: true;
142
}
143
```
144

145
### Catch Clause Definition
146

147
Definitions created by catch clause parameters.
148

149
```typescript { .api }
150
class CatchClauseDefinition extends DefinitionBase {
151
  readonly type: DefinitionType.CatchClause;
152
  readonly node: TSESTree.CatchClause;
153
  readonly parent: TSESTree.TryStatement;
154
  readonly isTypeDefinition: false;
155
  readonly isVariableDefinition: true;
156
}
157
```
158

159
### Import Binding Definition
160

161
Definitions created by import statements.
162

163
```typescript { .api }
164
class ImportBindingDefinition extends DefinitionBase {
165
  readonly type: DefinitionType.ImportBinding;
166
  readonly node: TSESTree.ImportDefaultSpecifier | TSESTree.ImportNamespaceSpecifier 
167
               | TSESTree.ImportSpecifier;
168
  readonly parent: TSESTree.ImportDeclaration;
169
  readonly isTypeDefinition: boolean; // Depends on import type
170
  readonly isVariableDefinition: boolean; // Depends on import type
171
}
172
```
173

174
### Implicit Global Variable Definition
175

176
Definitions for implicit global variables.
177

178
```typescript { .api }
179
class ImplicitGlobalVariableDefinition extends DefinitionBase {
180
  readonly type: DefinitionType.ImplicitGlobalVariable;
181
  readonly node: TSESTree.Program;
182
  readonly parent: null;
183
  readonly isTypeDefinition: false;
184
  readonly isVariableDefinition: true;
185
}
186
```
187

188
## TypeScript Definition Types
189

190
### Type Definition
191

192
Definitions created by TypeScript type declarations.
193

194
```typescript { .api }
195
class TypeDefinition extends DefinitionBase {
196
  readonly type: DefinitionType.Type;
197
  readonly node: TSESTree.TSTypeAliasDeclaration | TSESTree.TSInterfaceDeclaration;
198
  readonly parent: TSESTree.Node | null;
199
  readonly isTypeDefinition: true;
200
  readonly isVariableDefinition: false;
201
}
202
```
203

204
### TypeScript Enum Definitions
205

206
Definitions for TypeScript enums and their members.
207

208
```typescript { .api }
209
class TSEnumNameDefinition extends DefinitionBase {
210
  readonly type: DefinitionType.TSEnumName;
211
  readonly node: TSESTree.TSEnumDeclaration;
212
  readonly parent: TSESTree.Node | null;
213
  readonly isTypeDefinition: true;
214
  readonly isVariableDefinition: true;
215
}
216

217
class TSEnumMemberDefinition extends DefinitionBase {
218
  readonly type: DefinitionType.TSEnumMember;
219
  readonly node: TSESTree.TSEnumMember;
220
  readonly parent: TSESTree.TSEnumDeclaration;
221
  readonly isTypeDefinition: false;
222
  readonly isVariableDefinition: true;
223
}
224
```
225

226
### TypeScript Module Definition
227

228
Definitions created by TypeScript module (namespace) declarations.
229

230
```typescript { .api }
231
class TSModuleNameDefinition extends DefinitionBase {
232
  readonly type: DefinitionType.TSModuleName;
233
  readonly node: TSESTree.TSModuleDeclaration;
234
  readonly parent: TSESTree.Node | null;
235
  readonly isTypeDefinition: true;
236
  readonly isVariableDefinition: true;
237
}
238
```
239

240
**Usage Examples:**
241

242
```typescript
243
import { analyze } from "@typescript-eslint/scope-manager";
244
import { parse } from "@typescript-eslint/parser";
245

246
const code = `
247
// Variable definitions
248
const message = "Hello";
249
let count = 0;
250

251
// Function definition
252
function greet(name: string) {  // Parameter definition for 'name'
253
  return message + ", " + name;
254
}
255

256
// Class definition
257
class User {
258
  constructor(public name: string) {}  // Parameter definition for 'name'
259
}
260

261
// Type definitions
262
interface Point {
263
  x: number;
264
  y: number;
265
}
266

267
type StringOrNumber = string | number;
268

269
// Enum definitions
270
enum Color {
271
  Red,    // TSEnumMemberDefinition
272
  Green,  // TSEnumMemberDefinition
273
  Blue    // TSEnumMemberDefinition
274
}
275

276
// Module definition
277
namespace Utils {
278
  export function helper() {}
279
}
280

281
// Import definitions
282
import { parse } from "@typescript-eslint/parser";
283

284
// Catch clause definition
285
try {
286
  // code
287
} catch (error) {  // CatchClauseDefinition for 'error'
288
  console.log(error);
289
}
290
`;
291

292
const ast = parse(code);
293
const scopeManager = analyze(ast, { sourceType: 'module' });
294

295
// Analyze all definitions
296
console.log('=== Definition Analysis ===');
297
scopeManager.variables.forEach(variable => {
298
  console.log(`\nVariable: ${variable.name}`);
299
  console.log(`Definitions: ${variable.defs.length}`);
300
  
301
  variable.defs.forEach((def, index) => {
302
    console.log(`  Definition ${index}:`);
303
    console.log(`    Type: ${def.type}`);
304
    console.log(`    Node: ${def.node.type}`);
305
    console.log(`    Is type definition: ${def.isTypeDefinition}`);
306
    console.log(`    Is variable definition: ${def.isVariableDefinition}`);
307
    
308
    if (def.parent) {
309
      console.log(`    Parent: ${def.parent.type}`);
310
    }
311
  });
312
});
313
```
314

315
### Definition Categories
316

317
Analyze definitions by their characteristics:
318

319
```typescript
320
// Categorize definitions
321
const allDefinitions: Definition[] = [];
322
scopeManager.variables.forEach(variable => {
323
  allDefinitions.push(...variable.defs);
324
});
325

326
// Group by definition type
327
const defsByType = new Map<DefinitionType, Definition[]>();
328
allDefinitions.forEach(def => {
329
  if (!defsByType.has(def.type)) {
330
    defsByType.set(def.type, []);
331
  }
332
  defsByType.get(def.type)!.push(def);
333
});
334

335
console.log('Definitions by type:');
336
defsByType.forEach((defs, type) => {
337
  console.log(`  ${type}: ${defs.length}`);
338
});
339

340
// Categorize by context
341
const typeDefs = allDefinitions.filter(def => def.isTypeDefinition);
342
const valueDefs = allDefinitions.filter(def => def.isVariableDefinition);
343
const dualDefs = allDefinitions.filter(def => 
344
  def.isTypeDefinition && def.isVariableDefinition
345
);
346

347
console.log('\nDefinitions by context:');
348
console.log(`  Type-only: ${typeDefs.length - dualDefs.length}`);
349
console.log(`  Value-only: ${valueDefs.length - dualDefs.length}`);
350
console.log(`  Dual context: ${dualDefs.length}`);
351
```
352

353
### Definition Location Analysis
354

355
Analyze where definitions occur in the code:
356

357
```typescript
358
// Analyze definition locations
359
console.log('=== Definition Location Analysis ===');
360

361
const defsByScope = new Map<string, Definition[]>();
362
scopeManager.scopes.forEach(scope => {
363
  scope.variables.forEach(variable => {
364
    variable.defs.forEach(def => {
365
      const scopeType = scope.type;
366
      if (!defsByScope.has(scopeType)) {
367
        defsByScope.set(scopeType, []);
368
      }
369
      defsByScope.get(scopeType)!.push(def);
370
    });
371
  });
372
});
373

374
defsByScope.forEach((defs, scopeType) => {
375
  console.log(`\n${scopeType} scope:`);
376
  console.log(`  Definitions: ${defs.length}`);
377
  
378
  const typeCount = new Map<DefinitionType, number>();
379
  defs.forEach(def => {
380
    typeCount.set(def.type, (typeCount.get(def.type) || 0) + 1);
381
  });
382
  
383
  typeCount.forEach((count, type) => {
384
    console.log(`    ${type}: ${count}`);
385
  });
386
});
387
```
388

389
### Import Definition Analysis
390

391
Special analysis for import definitions:
392

393
```typescript
394
// Analyze import definitions
395
const importDefs = allDefinitions.filter(def => 
396
  def.type === DefinitionType.ImportBinding
397
) as ImportBindingDefinition[];
398

399
console.log('=== Import Definition Analysis ===');
400
console.log(`Total imports: ${importDefs.length}`);
401

402
const importTypes = new Map<string, number>();
403
importDefs.forEach(def => {
404
  const nodeType = def.node.type;
405
  importTypes.set(nodeType, (importTypes.get(nodeType) || 0) + 1);
406
});
407

408
console.log('Import types:');
409
importTypes.forEach((count, type) => {
410
  console.log(`  ${type}: ${count}`);
411
});
412

413
// Examples:
414
// ImportDefaultSpecifier: import React from 'react'
415
// ImportNamespaceSpecifier: import * as React from 'react'  
416
// ImportSpecifier: import { useState } from 'react'
417
```
418

419
### Parameter Definition Analysis
420

421
Analyze function parameters:
422

423
```typescript
424
// Analyze parameter definitions
425
const paramDefs = allDefinitions.filter(def => 
426
  def.type === DefinitionType.Parameter
427
) as ParameterDefinition[];
428

429
console.log('=== Parameter Definition Analysis ===');
430
console.log(`Total parameters: ${paramDefs.length}`);
431

432
paramDefs.forEach(def => {
433
  const functionNode = def.node;
434
  console.log(`Parameter in ${functionNode.type}:`);
435
  console.log(`  Name: ${(def.name as TSESTree.Identifier).name}`);
436
  
437
  // Analyze parameter patterns
438
  if (def.name.type === 'ObjectPattern') {
439
    console.log(`  Destructured object parameter`);
440
  } else if (def.name.type === 'ArrayPattern') {
441
    console.log(`  Destructured array parameter`);
442
  } else if (def.name.type === 'RestElement') {
443
    console.log(`  Rest parameter`);
444
  }
445
});
446
```
447

448
### Type Definition Analysis
449

450
Analyze TypeScript type definitions:
451

452
```typescript
453
// Analyze type definitions
454
const typeDefs = allDefinitions.filter(def => 
455
  def.type === DefinitionType.Type
456
) as TypeDefinition[];
457

458
console.log('=== Type Definition Analysis ===');
459
console.log(`Total type definitions: ${typeDefs.length}`);
460

461
typeDefs.forEach(def => {
462
  console.log(`Type definition: ${(def.name as TSESTree.Identifier).name}`);
463
  console.log(`  Node type: ${def.node.type}`);
464
  
465
  if (def.node.type === 'TSInterfaceDeclaration') {
466
    console.log(`  Interface definition`);
467
  } else if (def.node.type === 'TSTypeAliasDeclaration') {
468
    console.log(`  Type alias definition`);
469
  }
470
});
471
```