codemod 2.0.0-alpha.1 → 2.0.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/README.md +56 -2
  2. package/codemod +17 -30
  3. package/package.json +80 -10
  4. package/register.d.mts +2 -0
  5. package/register.mjs +67 -0
  6. package/runtime/addon.d.mts +114 -0
  7. package/runtime/addon.mjs +55 -0
  8. package/runtime/ast-grep.d.mts +20 -0
  9. package/runtime/ast-grep.mjs +82 -0
  10. package/runtime/context.d.mts +49 -0
  11. package/runtime/context.mjs +59 -0
  12. package/runtime/hooks.d.mts +2 -0
  13. package/runtime/hooks.mjs +7 -0
  14. package/runtime/host.d.mts +121 -0
  15. package/runtime/host.mjs +450 -0
  16. package/runtime/llm.d.mts +2 -0
  17. package/runtime/llm.mjs +5 -0
  18. package/runtime/metrics.d.mts +9 -0
  19. package/runtime/metrics.mjs +42 -0
  20. package/runtime/modules.d.mts +3 -0
  21. package/runtime/modules.mjs +17 -0
  22. package/runtime/orchestrator-version.d.mts +2 -0
  23. package/runtime/orchestrator-version.mjs +3 -0
  24. package/runtime/orchestrator.d.mts +261 -0
  25. package/runtime/orchestrator.mjs +879 -0
  26. package/runtime/runtime.d.mts +15 -0
  27. package/runtime/runtime.mjs +40 -0
  28. package/runtime/workflow.d.mts +19 -0
  29. package/runtime/workflow.mjs +126 -0
  30. package/testing/index.d.mts +157 -0
  31. package/testing/index.mjs +648 -0
  32. package/types/index.d.ts +8 -0
  33. package/types/langs/angular.d.ts +5 -0
  34. package/types/langs/c.d.ts +5 -0
  35. package/types/langs/c_sharp.d.ts +5 -0
  36. package/types/langs/cpp.d.ts +5 -0
  37. package/types/langs/css.d.ts +5 -0
  38. package/types/langs/elixir.d.ts +5 -0
  39. package/types/langs/go.d.ts +5 -0
  40. package/types/langs/html.d.ts +5 -0
  41. package/types/langs/java.d.ts +5 -0
  42. package/types/langs/javascript.d.ts +5 -0
  43. package/types/langs/json.d.ts +5 -0
  44. package/types/langs/kotlin.d.ts +5 -0
  45. package/types/langs/package.json +3 -0
  46. package/types/langs/php.d.ts +5 -0
  47. package/types/langs/python.d.ts +5 -0
  48. package/types/langs/ruby.d.ts +5 -0
  49. package/types/langs/rust.d.ts +5 -0
  50. package/types/langs/scala.d.ts +5 -0
  51. package/types/langs/toml.d.ts +5 -0
  52. package/types/langs/tsx.d.ts +5 -0
  53. package/types/langs/typescript.d.ts +5 -0
  54. package/types/langs/xml.d.ts +5 -0
  55. package/types/langs/yaml.d.ts +5 -0
  56. package/types/llm.d.ts +6 -0
  57. package/types/llrt/abort.d.ts +69 -0
  58. package/types/llrt/assert.d.ts +39 -0
  59. package/types/llrt/async_hooks.d.ts +210 -0
  60. package/types/llrt/buffer.d.ts +1186 -0
  61. package/types/llrt/child_process.d.ts +447 -0
  62. package/types/llrt/console.d.ts +210 -0
  63. package/types/llrt/crypto.d.ts +854 -0
  64. package/types/llrt/dgram.d.ts +381 -0
  65. package/types/llrt/dns.d.ts +124 -0
  66. package/types/llrt/dom-events.d.ts +51 -0
  67. package/types/llrt/events.d.ts +245 -0
  68. package/types/llrt/exceptions.d.ts +26 -0
  69. package/types/llrt/fetch.d.ts +332 -0
  70. package/types/llrt/fs/promises.d.ts +554 -0
  71. package/types/llrt/fs.d.ts +360 -0
  72. package/types/llrt/globals.d.ts +23 -0
  73. package/types/llrt/https.d.ts +27 -0
  74. package/types/llrt/index.d.ts +33 -0
  75. package/types/llrt/module.d.ts +285 -0
  76. package/types/llrt/navigator.d.ts +9 -0
  77. package/types/llrt/net.d.ts +488 -0
  78. package/types/llrt/os.d.ts +293 -0
  79. package/types/llrt/path.d.ts +150 -0
  80. package/types/llrt/perf_hooks.d.ts +23 -0
  81. package/types/llrt/process.d.ts +502 -0
  82. package/types/llrt/stream/web.d.ts +526 -0
  83. package/types/llrt/stream.d.ts +366 -0
  84. package/types/llrt/string_decoder.d.ts +63 -0
  85. package/types/llrt/timers.d.ts +72 -0
  86. package/types/llrt/timezone.d.ts +101 -0
  87. package/types/llrt/tty.d.ts +11 -0
  88. package/types/llrt/url.d.ts +774 -0
  89. package/types/llrt/util.d.ts +240 -0
  90. package/types/llrt/zlib.d.ts +177 -0
  91. package/types/main.d.ts +5 -0
  92. package/types/metrics.d.ts +5 -0
  93. package/types/modules/ast-grep.d.ts +634 -0
  94. package/types/modules/langs.d.ts +87 -0
  95. package/types/modules/llm.d.ts +23 -0
  96. package/types/modules/metrics.d.ts +107 -0
  97. package/types/modules/runtime.d.ts +66 -0
  98. package/types/modules/workflow.d.ts +915 -0
  99. package/types/runtime.d.ts +6 -0
  100. package/types/workflow.d.ts +5 -0
  101. package/vite.d.mts +7 -0
  102. package/vite.mjs +32 -0
@@ -0,0 +1,634 @@
1
+ declare module "codemod:ast-grep" {
2
+ export class SgNode<M extends TypesMap = TypesMap, out T extends Kinds<M> = Kinds<M>> {
3
+ /** Returns the node's id */
4
+ id(): number;
5
+ range(): Range;
6
+ isLeaf(): boolean;
7
+ isNamed(): boolean;
8
+ isNamedLeaf(): boolean;
9
+ text(): string;
10
+ matches(m: string | number | RuleConfig<M>): boolean;
11
+ inside(m: string | number | RuleConfig<M>): boolean;
12
+ has(m: string | number | RuleConfig<M>): boolean;
13
+ precedes(m: string | number | RuleConfig<M>): boolean;
14
+ follows(m: string | number | RuleConfig<M>): boolean;
15
+ /** Returns the string name of the node kind */
16
+ kind(): T;
17
+ readonly kindToRefine: T;
18
+ /** Check if the node is the same kind as the given `kind` string */
19
+ is<K extends T>(kind: K): this is SgNode<M, K>;
20
+ // we need this override to allow string literal union
21
+ is(kind: string): boolean;
22
+
23
+ getMatch: NodeMethod<M, [mv: string]>;
24
+ getMultipleMatches(m: string): Array<SgNode<M>>;
25
+ getTransformed(m: string): string | null;
26
+ /** Returns the node's SgRoot */
27
+ getRoot(): SgRoot<M>;
28
+ children(): Array<SgNode<M>>;
29
+ find: NodeMethod<M, [matcher: string | number | RuleConfig<M>]>;
30
+ findAll<K extends Kinds<M>>(matcher: string | number | RuleConfig<M>): Array<RefineNode<M, K>>;
31
+ /** Finds the first child node in the `field` */
32
+ field<F extends FieldNames<M[T]>>(name: F): FieldNode<M, T, F>;
33
+ /** Finds all the children nodes in the `field` */
34
+ fieldChildren<F extends FieldNames<M[T]>>(name: F): Exclude<FieldNode<M, T, F>, null>[];
35
+ parent: NodeMethod<M>;
36
+ child(nth: number): SgNode<M, ChildKinds<M, T>> | null;
37
+ child<K extends NamedChildKinds<M, T>>(nth: number): RefineNode<M, K> | null;
38
+ ancestors(): Array<SgNode<M>>;
39
+ next: NodeMethod<M>;
40
+ nextAll(): Array<SgNode<M>>;
41
+ prev: NodeMethod<M>;
42
+ prevAll(): Array<SgNode<M>>;
43
+ replace(text: string): Edit;
44
+ commitEdits(edits: Array<Edit>): string;
45
+
46
+ // Semantic analysis methods (requires semantic provider)
47
+
48
+ /**
49
+ * Get the definition for the symbol at this node's position.
50
+ *
51
+ * Returns an object containing:
52
+ * - `node`: The SgNode at the definition location
53
+ * - `root`: The SgRoot for the file containing the definition
54
+ * - `kind`: The kind of definition ('local', 'import', or 'external')
55
+ *
56
+ * Returns null if:
57
+ * - No semantic provider is configured
58
+ * - No symbol is found at this position
59
+ *
60
+ * When a symbol comes from an import that can't be resolved (e.g., external module),
61
+ * the definition will point to the import statement with `kind: 'import'`.
62
+ *
63
+ * @param options - Optional settings for definition lookup
64
+ * @param options.resolveExternal - If false, stop at import statements without
65
+ * attempting to resolve the source module. Default: true
66
+ * @returns An object with the definition node, its root, and kind, or null
67
+ */
68
+ definition(options?: DefinitionOptions): DefinitionResult<M> | null;
69
+
70
+ /**
71
+ * Find all references to the symbol at this node's position.
72
+ *
73
+ * Returns an array of objects, one per file, each containing:
74
+ * - `root`: The SgRoot for the file
75
+ * - `nodes`: Array of SgNode objects for each reference in that file
76
+ *
77
+ * Returns an empty array if:
78
+ * - No semantic provider is configured
79
+ * - No symbol is found at this position
80
+ *
81
+ * In file scope mode, it only searches files that have been processed.
82
+ * In workspace scope mode, it searches the entire workspace.
83
+ *
84
+ * @returns An array of file references, each with a root and nodes
85
+ */
86
+ references(): Array<FileReferences<M>>;
87
+ }
88
+ /** Represents the parsed tree of code. */
89
+ export class SgRoot<M extends TypesMap = TypesMap> {
90
+ /** Returns the root SgNode of the ast-grep instance. */
91
+ root(): SgNode<M, RootKind<M>>;
92
+ /**
93
+ * Returns the path of the file if it is discovered by ast-grep's `findInFiles`.
94
+ * Returns `"anonymous"` if the instance is created by `lang.parse(source)`.
95
+ */
96
+ filename(): string;
97
+ /**
98
+ * Returns the file path relative to the current target directory.
99
+ */
100
+ relativeFilename(): string;
101
+ /**
102
+ * Returns the source code of the file.
103
+ */
104
+ source(): string;
105
+ /**
106
+ * Write content to this file.
107
+ *
108
+ * This method is only valid for files obtained via `definition()` or `references()`.
109
+ * It cannot be called on the current file being processed - for that, return the
110
+ * modified content from the `transform()` function instead.
111
+ *
112
+ * After writing, the semantic provider's cache is automatically updated with the new content.
113
+ *
114
+ * @param content - The new content to write to the file
115
+ * @throws Error if called on the current file being processed
116
+ * @throws Error if the file has no path
117
+ * @throws Error if the write operation fails
118
+ *
119
+ * @example
120
+ * ```ts
121
+ * export default function transform(root) {
122
+ * const node = root.root().find({ rule: { pattern: "myVar" } });
123
+ * const def = node.definition();
124
+ *
125
+ * if (def && def.root.filename() !== root.filename()) {
126
+ * // Edit the other file
127
+ * const edits = [def.node.replace("newVar")];
128
+ * const newContent = def.root.root().commitEdits(edits);
129
+ * def.root.write(newContent);
130
+ * }
131
+ *
132
+ * // Return changes for the current file
133
+ * return root.root().commitEdits([...]);
134
+ * }
135
+ * ```
136
+ */
137
+ write(content: string): void;
138
+ /**
139
+ * Rename the current file to a new path.
140
+ *
141
+ * If the path is relative, it is resolved against the current file's parent directory.
142
+ * If absolute, it is used as-is.
143
+ *
144
+ * The rename is applied after the transform function returns:
145
+ * - If the transform returns a string, the file is renamed and its content is updated.
146
+ * - If the transform returns null, the file is renamed with its original content.
147
+ *
148
+ * @param newPath - The new file path (relative or absolute)
149
+ * @throws Error if the path is empty
150
+ *
151
+ * @example
152
+ * ```ts
153
+ * // Rename .less to .css
154
+ * export default function transform(root) {
155
+ * root.rename(root.filename().replace('.less', '.css'));
156
+ * return transformedContent;
157
+ * }
158
+ * ```
159
+ */
160
+ rename(newPath: string): void;
161
+ }
162
+
163
+ interface NodeMethod<M extends TypesMap, Args extends unknown[] = []> {
164
+ (...args: Args): SgNode<M> | null;
165
+ <K extends NamedKinds<M>>(...args: Args): RefineNode<M, K> | null;
166
+ }
167
+
168
+ /**
169
+ * if K contains string, return general SgNode. Otherwise,
170
+ * if K is a literal union, return a union of SgNode of each kind.
171
+ */
172
+ type RefineNode<M extends TypesMap, K> = string extends K
173
+ ? SgNode<M>
174
+ : K extends Kinds<M>
175
+ ? SgNode<M, K>
176
+ : never;
177
+
178
+ /**
179
+ * return the SgNode of the field in the node.
180
+ */
181
+ // F extends string is used to prevent noisy TS hover info
182
+ type FieldNode<
183
+ M extends TypesMap,
184
+ K extends Kinds<M>,
185
+ F extends FieldNames<M[K]>,
186
+ > = F extends string ? FieldNodeImpl<M, ExtractField<M[K], F>> : never;
187
+
188
+ type FieldNodeImpl<M extends TypesMap, I extends NodeFieldInfo> = I extends {
189
+ required: true;
190
+ }
191
+ ? RefineNode<M, TypesInField<M, I>>
192
+ : RefineNode<M, TypesInField<M, I>> | null;
193
+
194
+ /**
195
+ * Rule configuration similar to YAML
196
+ * See https://ast-grep.github.io/reference/yaml.html
197
+ */
198
+ export interface RuleConfig<M extends TypesMap = TypesMap> {
199
+ /** The rule object, see https://ast-grep.github.io/reference/rule.html */
200
+ rule: Rule<M>;
201
+ /** See https://ast-grep.github.io/guide/rule-config.html#constraints */
202
+ constraints?: Record<string, Rule<M>>;
203
+ /** Builtin Language or custom language */
204
+ language?: string;
205
+ /**
206
+ * transform is NOT useful in JavaScript. You can use JS code to directly transform the result.
207
+ * https://ast-grep.github.io/reference/yaml.html#transform
208
+ */
209
+ transform?: unknown;
210
+ /** https://ast-grep.github.io/guide/rule-config/utility-rule.html */
211
+ utils?: Record<string, Rule<M>>;
212
+ }
213
+
214
+ export interface FileOption {
215
+ paths: Array<string>;
216
+ languageGlobs: Record<string, Array<string>>;
217
+ }
218
+
219
+ export interface FindConfig<M extends TypesMap = TypesMap> {
220
+ /** specify the file paths to recursively find files */
221
+ paths: Array<string>;
222
+ /** a Rule object to find what nodes will match */
223
+ matcher: RuleConfig<M>;
224
+ /**
225
+ * An list of pattern globs to treat of certain files in the specified language.
226
+ * eg. ['*.vue', '*.svelte'] for html.findFiles, or ['*.ts'] for tsx.findFiles.
227
+ * It is slightly different from https://ast-grep.github.io/reference/sgconfig.html#languageglobs
228
+ */
229
+ languageGlobs?: Array<string>;
230
+ }
231
+
232
+ export type Strictness = "cst" | "smart" | "ast" | "relaxed" | "signature";
233
+
234
+ export interface PatternObject<M extends TypesMap = TypesMap> {
235
+ context: string;
236
+ selector?: NamedKinds<M>; // only named node types
237
+ strictness?: Strictness;
238
+ }
239
+
240
+ export type PatternStyle<M extends TypesMap = TypesMap> = string | PatternObject<M>;
241
+
242
+ export interface Relation<M extends TypesMap = TypesMap> extends Rule<M> {
243
+ /**
244
+ * Specify how relational rule will stop relative to the target node.
245
+ */
246
+ stopBy?: "neighbor" | "end" | Rule<M>;
247
+ /** Specify the tree-sitter field in parent node. Only available in has/inside rule. */
248
+ field?: string;
249
+ }
250
+
251
+ export interface NthChildObject<M extends TypesMap = TypesMap> {
252
+ /** The position in nodes' sibling list. It can be a number of An+B string */
253
+ position: string | number;
254
+ ofRule?: Rule<M>;
255
+ reverse?: boolean;
256
+ }
257
+
258
+ /**
259
+ * NthChild can have these types:
260
+ * * number: the position of the node in the sibling list.
261
+ * * string: An + B style string like CSS nth-child selector.
262
+ * * object: An object with `position` and `ofRule` fields.
263
+ */
264
+ export type NthChild<M extends TypesMap = TypesMap> = number | string | NthChildObject<M>;
265
+
266
+ export interface Rule<M extends TypesMap = TypesMap> {
267
+ /** A pattern string or a pattern object. */
268
+ pattern?: PatternStyle<M>;
269
+ /** The kind name of the node to match. You can look up code's kind names in playground. */
270
+ kind?: NamedKinds<M>;
271
+ /** The exact range of the node in the source code. */
272
+ range?: Range;
273
+ /** A Rust regular expression to match the node's text. https://docs.rs/regex/latest/regex/#syntax */
274
+ regex?: string;
275
+ /**
276
+ * `nthChild` accepts number, string or object.
277
+ * It specifies the position in nodes' sibling list. */
278
+ nthChild?: NthChild<M>;
279
+
280
+ // relational
281
+ /**
282
+ * `inside` accepts a relational rule object.
283
+ * the target node must appear inside of another node matching the `inside` sub-rule. */
284
+ inside?: Relation<M>;
285
+ /**
286
+ * `has` accepts a relational rule object.
287
+ * the target node must has a descendant node matching the `has` sub-rule. */
288
+ has?: Relation<M>;
289
+ /**
290
+ * `precedes` accepts a relational rule object.
291
+ * the target node must appear before another node matching the `precedes` sub-rule. */
292
+ precedes?: Relation<M>;
293
+ /**
294
+ * `follows` accepts a relational rule object.
295
+ * the target node must appear after another node matching the `follows` sub-rule. */
296
+ follows?: Relation<M>;
297
+ // composite
298
+ /**
299
+ * A list of sub rules and matches a node if all of sub rules match.
300
+ * The meta variables of the matched node contain all variables from the sub-rules. */
301
+ all?: Array<Rule<M>>;
302
+ /**
303
+ * A list of sub rules and matches a node if any of sub rules match.
304
+ * The meta variables of the matched node only contain those of the matched sub-rule. */
305
+ any?: Array<Rule<M>>;
306
+ /** A single sub-rule and matches a node if the sub rule does not match. */
307
+ not?: Rule<M>;
308
+ /** A utility rule id and matches a node if the utility rule matches. */
309
+ matches?: string;
310
+ }
311
+
312
+ type Separator = "caseChange" | "dash" | "dot" | "slash" | "space" | "underscore";
313
+
314
+ type StringCase =
315
+ | "lowerCase"
316
+ | "upperCase"
317
+ | "capitalize"
318
+ | "camelCase"
319
+ | "snakeCase"
320
+ | "kebabCase"
321
+ | "pascalCase";
322
+
323
+ interface Substring {
324
+ endChar?: number | null;
325
+ source: string;
326
+ startChar?: number | null;
327
+ }
328
+
329
+ interface Replace {
330
+ by: string;
331
+ replace: string;
332
+ source: string;
333
+ }
334
+
335
+ type Transformation =
336
+ | { substring: Substring }
337
+ | { replace: Replace }
338
+ | { convert: Convert }
339
+ | { rewrite: Rewrite };
340
+
341
+ interface Rewrite {
342
+ joinBy?: string | null;
343
+ rewriters: string[];
344
+ source: string;
345
+ }
346
+
347
+ interface SerializableFixConfig {
348
+ expandEnd?: Relation;
349
+ expandStart?: Relation;
350
+ template: string;
351
+ }
352
+
353
+ type SerializableFixer = string | SerializableFixConfig;
354
+
355
+ export type Severity = "hint" | "info" | "warning" | "error" | "off";
356
+
357
+ export interface CompleteRuleConfig<M extends TypesMap = TypesMap> extends RuleConfig<M> {
358
+ id: string;
359
+ fix?: SerializableFixer;
360
+ transform?: Record<string, Transformation>;
361
+ severity?: Severity;
362
+ note?: string;
363
+ message?: string;
364
+ ignores?: string[];
365
+ url?: string;
366
+ }
367
+
368
+ // Definitions
369
+ interface Convert {
370
+ separatedBy?: Separator[] | null;
371
+ source: string;
372
+ toCase: StringCase;
373
+ }
374
+
375
+ export interface Edit {
376
+ /** The start position of the edit */
377
+ startPos: number;
378
+ /** The end position of the edit */
379
+ endPos: number;
380
+ /** The text to be inserted */
381
+ insertedText: string;
382
+ }
383
+ export interface Position {
384
+ /** line number starting from 0 */
385
+ line: number;
386
+ /** column number starting from 0 */
387
+ column: number;
388
+ /** byte offset of the position */
389
+ index: number;
390
+ }
391
+ export interface Range {
392
+ /** starting position of the range */
393
+ start: Position;
394
+ /** ending position of the range */
395
+ end: Position;
396
+ }
397
+
398
+ /**
399
+ * Result of getDefinition() - contains the definition node and its root.
400
+ */
401
+ /**
402
+ * The kind of definition that was found.
403
+ * - 'local': Definition is in the same file (local variable, function, class, etc.)
404
+ * - 'import': Definition traced to an import statement but module couldn't be resolved
405
+ * - 'external': Definition resolved to a different file in the workspace
406
+ */
407
+ export type DefinitionKind = "local" | "import" | "external";
408
+
409
+ /**
410
+ * Options for definition lookup.
411
+ */
412
+ export interface DefinitionOptions {
413
+ /**
414
+ * If true, attempt to resolve imports to their source modules.
415
+ * If false, stop at the import statement.
416
+ * @default true
417
+ */
418
+ resolveExternal?: boolean;
419
+ }
420
+
421
+ export interface DefinitionResult<M extends TypesMap = TypesMap> {
422
+ /** The SgNode at the definition location */
423
+ node: SgNode<M>;
424
+ /** The SgRoot for the file containing the definition */
425
+ root: SgRoot<M>;
426
+ /** The kind of definition (local, import, or external) */
427
+ kind: DefinitionKind;
428
+ }
429
+
430
+ /**
431
+ * References in a single file - contains the root and all reference nodes.
432
+ */
433
+ export interface FileReferences<M extends TypesMap = TypesMap> {
434
+ /** The SgRoot for the file */
435
+ root: SgRoot<M>;
436
+ /** Array of SgNode objects for each reference in this file */
437
+ nodes: Array<SgNode<M>>;
438
+ }
439
+
440
+ /**
441
+ * Reference
442
+ * https://tree-sitter.github.io/tree-sitter/using-parsers#static-node-types
443
+ * Rust CLI Impl
444
+ * https://github.com/tree-sitter/tree-sitter/blob/f279d10aa2aca37c0004d84b2261685739f3cab8/cli/generate/src/node_types.rs#L35-L47
445
+ */
446
+
447
+ export interface NodeBasicInfo {
448
+ type: string;
449
+ named: boolean;
450
+ }
451
+
452
+ export interface NodeFieldInfo {
453
+ multiple: boolean;
454
+ required: boolean;
455
+ types: NodeBasicInfo[];
456
+ }
457
+
458
+ export interface NodeType extends NodeBasicInfo {
459
+ root?: boolean;
460
+ fields?: {
461
+ [fieldName: string]: NodeFieldInfo;
462
+ };
463
+ children?: NodeFieldInfo;
464
+ subtypes?: NodeBasicInfo[];
465
+ }
466
+
467
+ /**
468
+ * A map of key to NodeType.
469
+ * Note, the key is not necessary node's kind.
470
+ * it can be a rule representing a category of syntax nodes
471
+ * (e.g. “expression”, “type”, “declaration”).
472
+ * See reference above for more details.
473
+ */
474
+ export interface TypesMap {
475
+ [key: string]: NodeType;
476
+ }
477
+
478
+ export type FieldNames<N extends NodeType> = N extends { fields: infer F } ? keyof F : string;
479
+
480
+ export type ExtractField<N extends NodeType, F extends FieldNames<N>> =
481
+ N["fields"] extends Record<F, NodeFieldInfo> ? N["fields"][F] : NodeFieldInfo;
482
+
483
+ // in case of empty types array, return string as fallback
484
+ type NoNever<T, Fallback> = [T] extends [never] ? Fallback : T;
485
+
486
+ export type TypesInField<M extends TypesMap, I extends NodeFieldInfo> = NoNever<
487
+ ResolveType<M, I["types"][number]["type"]>,
488
+ Kinds<M>
489
+ >;
490
+
491
+ export type NamedChildKinds<M extends TypesMap, T extends Kinds<M>> = M[T] extends {
492
+ children: infer C extends NodeFieldInfo;
493
+ }
494
+ ? TypesInField<M, C>
495
+ : NamedKinds<M>;
496
+ export type ChildKinds<M extends TypesMap, T extends Kinds<M>> =
497
+ | NamedChildKinds<M, T>
498
+ | LowPriorityKey;
499
+
500
+ /**
501
+ * resolve subtypes alias. see tree-sitter's reference
502
+ * e.g. like `expression` => `binary_expression` | `unary_expression` | ...
503
+ */
504
+ type ResolveType<M extends TypesMap, K> = K extends keyof M
505
+ ? M[K] extends { subtypes: infer S extends NodeBasicInfo[] }
506
+ ? ResolveType<M, S[number]["type"]>
507
+ : K
508
+ : K;
509
+
510
+ /**
511
+ * All named nodes' kinds that are usable in ast-grep rule
512
+ * NOTE: SgNode can return kind not in this list
513
+ */
514
+ export type NamedKinds<M extends TypesMap> = ResolveType<M, keyof M>;
515
+
516
+ /**
517
+ * See open-ended unions / string literal completion in TypeScript
518
+ * https://github.com/microsoft/TypeScript/issues/26277
519
+ * https://github.com/microsoft/TypeScript/issues/33471
520
+ */
521
+ type LowPriorityKey = string & {};
522
+
523
+ /**
524
+ * A union of all named node kinds and a low priority key
525
+ * tree-sitter Kinds also include unnamed nodes which is not usable in rule
526
+ * NOTE: SgNode can return a string type if it is not a named node
527
+ */
528
+ export type Kinds<M extends TypesMap = TypesMap> = NamedKinds<M> | LowPriorityKey;
529
+
530
+ /**
531
+ * The root node kind of the tree.
532
+ */
533
+ export type RootKind<M extends TypesMap> = NoNever<
534
+ Extract<M[keyof M], { root: true }>["type"],
535
+ Kinds<M>
536
+ >;
537
+
538
+ /** Something to parse along with its path, such as a workflow `forEachFile` file. */
539
+ export interface ParseSource {
540
+ readonly text: string;
541
+ /** Becomes the root's `filename()`; relative paths are against the target. */
542
+ readonly path?: string;
543
+ readonly language?: string;
544
+ }
545
+
546
+ export interface ParseOptions {
547
+ language?: string;
548
+ }
549
+
550
+ /** Parse `src` as `lang`. */
551
+ export function parse<M extends TypesMap = TypesMap>(lang: string, src: string): SgRoot<M>;
552
+ /**
553
+ * Parse a file, such as the one a workflow `forEachFile` callback receives.
554
+ * The language comes from `options`, then the file, then the step's
555
+ * selector, then the file extension.
556
+ */
557
+ export function parse<M extends TypesMap = TypesMap>(
558
+ file: ParseSource,
559
+ options?: ParseOptions,
560
+ ): SgRoot<M>;
561
+ /**
562
+ * Parse text. Without `options.language`, uses the language of the
563
+ * `forEachFile` step it runs in, when the step's selector names one.
564
+ */
565
+ export function parse<M extends TypesMap = TypesMap>(
566
+ text: string,
567
+ options?: ParseOptions,
568
+ ): SgRoot<M>;
569
+ export function parseAsync<M extends TypesMap = TypesMap>(
570
+ lang: string,
571
+ src: string,
572
+ ): Promise<SgRoot<M>>;
573
+ export function parseAsync<M extends TypesMap = TypesMap>(
574
+ source: ParseSource | string,
575
+ options?: ParseOptions,
576
+ ): Promise<SgRoot<M>>;
577
+
578
+ export type TransformOptions<T extends TypesMap> = {
579
+ params: Record<string, string>;
580
+ matches?: SgNode<T>[];
581
+ language: string;
582
+ matrixValues?: Record<string, any>;
583
+ dryRun?: boolean;
584
+ targetDir: string;
585
+ };
586
+
587
+ /**
588
+ * @deprecated Use `Codemod` type instead. The name `Transform` is misleading as it implies the function must return a transformed string, but in fact it can also return null for detection purposes.
589
+ */
590
+ export type Transform<T extends TypesMap> = Codemod<T>;
591
+
592
+ export type Codemod<T extends TypesMap> = (
593
+ root: SgRoot<T>,
594
+ options: TransformOptions<T>,
595
+ ) => Promise<string | null>;
596
+
597
+ export type GetSelectorOptions<_T extends TypesMap> = {
598
+ params: Record<string, string>;
599
+ };
600
+
601
+ export type GetSelector<T extends TypesMap> = ({
602
+ params,
603
+ }: GetSelectorOptions<T>) => RuleConfig<T>;
604
+
605
+ /**
606
+ * Execute a transform function on a file, collecting the result.
607
+ *
608
+ * Reads the file at `pathToFile`, parses it with the given `language`,
609
+ * calls the `transformFn` with the parsed root, and returns the
610
+ * transformed content string if the file was modified, or `null` if
611
+ * the file was unchanged.
612
+ *
613
+ * @param transformFn - The transform function to apply
614
+ * @param pathToFile - Path to the file to transform
615
+ * @param language - The language to parse the file as (e.g., "typescript", "javascript")
616
+ * @returns A promise that resolves with the transformed content, or null if unchanged
617
+ *
618
+ * @example
619
+ * ```ts
620
+ * import { jssgTransform } from "codemod/ast-grep";
621
+ *
622
+ * // Apply a transform to a specific file and get the result
623
+ * const result = await jssgTransform(myTransform, "./src/config.ts", "typescript");
624
+ * if (result !== null) {
625
+ * console.log("Transformed content:", result);
626
+ * }
627
+ * ```
628
+ */
629
+ export function jssgTransform<T extends TypesMap = TypesMap>(
630
+ transformFn: Transform<T>,
631
+ pathToFile: string,
632
+ language: string,
633
+ ): Promise<string | null>;
634
+ }