@ast-grep/napi 0.31.1 → 0.32.0

package/index.d.ts

@@ -1,287 +1,19 @@
-/* tslint:disable */
-/* eslint-disable */
+//-----Type Only Export!-----//
+export type { Pos, Edit, Range } from './types/sgnode'
+export type { NapiConfig, FindConfig, FileOption } from './types/config'
+// Only Rule here. User can use Rule['pattern'], e.g., to get the type of subfield.
+export type { Rule } from './types/rule'
 
-/* auto-generated by NAPI-RS */
-
-/**
- * Rule configuration similar to YAML
- * See https://ast-grep.github.io/reference/yaml.html
- */
-export interface NapiConfig {
-  /** The rule object, see https://ast-grep.github.io/reference/rule.html */
-  rule: import('./manual').Rule
-  /** See https://ast-grep.github.io/guide/rule-config.html#constraints */
-  constraints?: Record<string, import('./manual').Rule>
-  /** Available languages: html, css, js, jsx, ts, tsx */
-  language?: Lang
-  /**
-   * transform is NOT useful in JavaScript. You can use JS code to directly transform the result.
-   * https://ast-grep.github.io/reference/yaml.html#transform
-   */
-  transform?: any
-  /** https://ast-grep.github.io/guide/rule-config/utility-rule.html */
-  utils?: any
-}
-export interface FileOption {
-  paths: Array<string>
-  languageGlobs: Record<string, Array<string>>
-}
-export declare function parseFiles(paths: Array<string> | FileOption, callback: (err: null | Error, result: SgRoot) => void): Promise<number>
-export interface FindConfig {
-  /** specify the file paths to recursively find files */
-  paths: Array<string>
-  /** a Rule object to find what nodes will match */
-  matcher: NapiConfig
-  /**
-   * An list of pattern globs to treat of certain files in the specified language.
-   * eg. ['*.vue', '*.svelte'] for html.findFiles, or ['*.ts'] for tsx.findFiles.
-   * It is slightly different from https://ast-grep.github.io/reference/sgconfig.html#languageglobs
-   */
-  languageGlobs?: Array<string>
-}
-export enum Lang {
-  Html = 'Html',
-  JavaScript = 'JavaScript',
-  Tsx = 'Tsx',
-  Css = 'Css',
-  TypeScript = 'TypeScript',
-  Bash = 'Bash',
-  C = 'C',
-  Cpp = 'Cpp',
-  CSharp = 'CSharp',
-  Go = 'Go',
-  Elixir = 'Elixir',
-  Haskell = 'Haskell',
-  Java = 'Java',
-  Json = 'Json',
-  Kotlin = 'Kotlin',
-  Lua = 'Lua',
-  Php = 'Php',
-  Python = 'Python',
-  Ruby = 'Ruby',
-  Rust = 'Rust',
-  Scala = 'Scala',
-  Sql = 'Sql',
-  Swift = 'Swift',
-  Yaml = 'Yaml'
-}
-export interface Edit {
-  /** The start position of the edit */
-  startPos: number
-  /** The end position of the edit */
-  endPos: number
-  /** The text to be inserted */
-  insertedText: string
-}
-export interface Pos {
-  /** line number starting from 0 */
-  line: number
-  /** column number starting from 0 */
-  column: number
-  /** byte offset of the position */
-  index: number
-}
-export interface Range {
-  /** starting position of the range */
-  start: Pos
-  /** ending position of the range */
-  end: Pos
-}
-/** Parse a string to an ast-grep instance */
-export declare function parse(lang: Lang, src: string): SgRoot
-/**
- * Parse a string to an ast-grep instance asynchronously in threads.
- * It utilize multiple CPU cores when **concurrent processing sources**.
- * However, spawning excessive many threads may backfire.
- * Please refer to libuv doc, nodejs' underlying runtime
- * for its default behavior and performance tuning tricks.
- */
-export declare function parseAsync(lang: Lang, src: string): Promise<SgRoot>
-/** Get the `kind` number from its string name. */
-export declare function kind(lang: Lang, kindName: string): number
-/** Compile a string to ast-grep Pattern. */
-export declare function pattern(lang: Lang, pattern: string): NapiConfig
-/**
- * Discover and parse multiple files in Rust.
- * `lang` specifies the language.
- * `config` specifies the file path and matcher.
- * `callback` will receive matching nodes found in a file.
- */
-export declare function findInFiles(lang: Lang, config: FindConfig, callback: (err: null | Error, result: SgNode[]) => void): Promise<number>
-export declare class SgNode {
-  range(): Range
-  isLeaf(): boolean
-  isNamed(): boolean
-  isNamedLeaf(): boolean
-  /** Returns the string name of the node kind */
-  kind(): string
-  text(): string
-  matches(m: string): boolean
-  inside(m: string): boolean
-  has(m: string): boolean
-  precedes(m: string): boolean
-  follows(m: string): boolean
-  getMatch(m: string): SgNode | null
-  getMultipleMatches(m: string): Array<SgNode>
-  getTransformed(m: string): string | null
-  /** Returns the node's SgRoot */
-  getRoot(): SgRoot
-  children(): Array<SgNode>
-  /** Returns the node's id */
-  id(): number
-  find(matcher: string | number | NapiConfig): SgNode | null
-  findAll(matcher: string | number | NapiConfig): Array<SgNode>
-  /** Finds the child node in the `field` */
-  field(name: string): SgNode | null
-  parent(): SgNode | null
-  child(nth: number): SgNode | null
-  ancestors(): Array<SgNode>
-  next(): SgNode | null
-  nextAll(): Array<SgNode>
-  prev(): SgNode | null
-  prevAll(): Array<SgNode>
-  replace(text: string): Edit
-  commitEdits(edits: Array<Edit>): string
-}
-/** Represents the parsed tree of code. */
-export declare class SgRoot {
-  /** Returns the root SgNode of the ast-grep instance. */
-  root(): SgNode
-  /**
-   * Returns the path of the file if it is discovered by ast-grep's `findInFiles`.
-   * Returns `"anonymous"` if the instance is created by `lang.parse(source)`.
-   */
-  filename(): string
-}
-export declare namespace html {
-  /** Parse a string to an ast-grep instance */
-  export function parse(src: string): SgRoot
-  /**
-   * Parse a string to an ast-grep instance asynchronously in threads.
-   * It utilize multiple CPU cores when **concurrent processing sources**.
-   * However, spawning excessive many threads may backfire.
-   * Please refer to libuv doc, nodejs' underlying runtime
-   * for its default behavior and performance tuning tricks.
-   */
-  export function parseAsync(src: string): Promise<SgRoot>
-  /** Get the `kind` number from its string name. */
-  export function kind(kindName: string): number
-  /** Compile a string to ast-grep Pattern. */
-  export function pattern(pattern: string): NapiConfig
-  /**
-   * Discover and parse multiple files in Rust.
-   * `config` specifies the file path and matcher.
-   * `callback` will receive matching nodes found in a file.
-   */
-  export function findInFiles(config: FindConfig, callback: (err: null | Error, result: SgNode[]) => void): Promise<number>
-}
-export declare namespace js {
-  /** Parse a string to an ast-grep instance */
-  export function parse(src: string): SgRoot
-  /**
-   * Parse a string to an ast-grep instance asynchronously in threads.
-   * It utilize multiple CPU cores when **concurrent processing sources**.
-   * However, spawning excessive many threads may backfire.
-   * Please refer to libuv doc, nodejs' underlying runtime
-   * for its default behavior and performance tuning tricks.
-   */
-  export function parseAsync(src: string): Promise<SgRoot>
-  /** Get the `kind` number from its string name. */
-  export function kind(kindName: string): number
-  /** Compile a string to ast-grep Pattern. */
-  export function pattern(pattern: string): NapiConfig
-  /**
-   * Discover and parse multiple files in Rust.
-   * `config` specifies the file path and matcher.
-   * `callback` will receive matching nodes found in a file.
-   */
-  export function findInFiles(config: FindConfig, callback: (err: null | Error, result: SgNode[]) => void): Promise<number>
-}
-export declare namespace jsx {
-  /** Parse a string to an ast-grep instance */
-  export function parse(src: string): SgRoot
-  /**
-   * Parse a string to an ast-grep instance asynchronously in threads.
-   * It utilize multiple CPU cores when **concurrent processing sources**.
-   * However, spawning excessive many threads may backfire.
-   * Please refer to libuv doc, nodejs' underlying runtime
-   * for its default behavior and performance tuning tricks.
-   */
-  export function parseAsync(src: string): Promise<SgRoot>
-  /** Get the `kind` number from its string name. */
-  export function kind(kindName: string): number
-  /** Compile a string to ast-grep Pattern. */
-  export function pattern(pattern: string): NapiConfig
-  /**
-   * Discover and parse multiple files in Rust.
-   * `config` specifies the file path and matcher.
-   * `callback` will receive matching nodes found in a file.
-   */
-  export function findInFiles(config: FindConfig, callback: (err: null | Error, result: SgNode[]) => void): Promise<number>
-}
-export declare namespace ts {
-  /** Parse a string to an ast-grep instance */
-  export function parse(src: string): SgRoot
-  /**
-   * Parse a string to an ast-grep instance asynchronously in threads.
-   * It utilize multiple CPU cores when **concurrent processing sources**.
-   * However, spawning excessive many threads may backfire.
-   * Please refer to libuv doc, nodejs' underlying runtime
-   * for its default behavior and performance tuning tricks.
-   */
-  export function parseAsync(src: string): Promise<SgRoot>
-  /** Get the `kind` number from its string name. */
-  export function kind(kindName: string): number
-  /** Compile a string to ast-grep Pattern. */
-  export function pattern(pattern: string): NapiConfig
-  /**
-   * Discover and parse multiple files in Rust.
-   * `config` specifies the file path and matcher.
-   * `callback` will receive matching nodes found in a file.
-   */
-  export function findInFiles(config: FindConfig, callback: (err: null | Error, result: SgNode[]) => void): Promise<number>
-}
-export declare namespace tsx {
-  /** Parse a string to an ast-grep instance */
-  export function parse(src: string): SgRoot
-  /**
-   * Parse a string to an ast-grep instance asynchronously in threads.
-   * It utilize multiple CPU cores when **concurrent processing sources**.
-   * However, spawning excessive many threads may backfire.
-   * Please refer to libuv doc, nodejs' underlying runtime
-   * for its default behavior and performance tuning tricks.
-   */
-  export function parseAsync(src: string): Promise<SgRoot>
-  /** Get the `kind` number from its string name. */
-  export function kind(kindName: string): number
-  /** Compile a string to ast-grep Pattern. */
-  export function pattern(pattern: string): NapiConfig
-  /**
-   * Discover and parse multiple files in Rust.
-   * `config` specifies the file path and matcher.
-   * `callback` will receive matching nodes found in a file.
-   */
-  export function findInFiles(config: FindConfig, callback: (err: null | Error, result: SgNode[]) => void): Promise<number>
-}
-export declare namespace css {
-  /** Parse a string to an ast-grep instance */
-  export function parse(src: string): SgRoot
-  /**
-   * Parse a string to an ast-grep instance asynchronously in threads.
-   * It utilize multiple CPU cores when **concurrent processing sources**.
-   * However, spawning excessive many threads may backfire.
-   * Please refer to libuv doc, nodejs' underlying runtime
-   * for its default behavior and performance tuning tricks.
-   */
-  export function parseAsync(src: string): Promise<SgRoot>
-  /** Get the `kind` number from its string name. */
-  export function kind(kindName: string): number
-  /** Compile a string to ast-grep Pattern. */
-  export function pattern(pattern: string): NapiConfig
-  /**
-   * Discover and parse multiple files in Rust.
-   * `config` specifies the file path and matcher.
-   * `callback` will receive matching nodes found in a file.
-   */
-  export function findInFiles(config: FindConfig, callback: (err: null | Error, result: SgNode[]) => void): Promise<number>
-}
+//-----Runtime Value Export!-----//
+export { SgRoot, SgNode } from './types/sgnode'
+export { Lang } from './types/lang'
+export {
+  parseFiles,
+  parse,
+  parseAsync,
+  kind,
+  pattern,
+  findInFiles,
+} from './types/api'
+// deprecated
+export * from './types/deprecated'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ast-grep/napi",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "Search and Rewrite code at large scale using precise AST pattern",
   "homepage": "https://ast-grep.github.io",
   "main": "index.js",
@@ -14,9 +14,10 @@
     "rewrite"
   ],
   "files": [
-    "manual.d.ts",
     "index.d.ts",
-    "index.js"
+    "index.js",
+    "types/*.ts",
+    "lang/*.ts"
   ],
   "napi": {
     "name": "ast-grep-napi",
@@ -41,16 +42,23 @@
   },
   "scripts": {
     "artifacts": "napi artifacts",
-    "build": "napi build --no-const-enum --platform --release",
-    "build:debug": "napi build --no-const-enum --platform",
+    "build": "napi build --no-const-enum --dts ignore.d.ts --platform --release",
+    "build:debug": "napi build --no-const-enum --dts ignore.d.ts --platform",
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
-    "test": "ava",
-    "version": "napi version"
+    "pretest": "ts-node scripts/generateTypes.ts --test-only",
+    "test": "tsc --noEmit && ava",
+    "version": "napi version",
+    "lint": "biome lint --fix && biome format --write",
+    "typegen": "ts-node scripts/generateTypes.ts"
   },
   "devDependencies": {
+    "@ast-grep/napi": "0.31.1",
+    "@biomejs/biome": "1.9.4",
     "@napi-rs/cli": "2.18.4",
+    "@types/node": "^22.10.2",
     "ava": "6.2.0",
     "chalk": "5.3.0",
+    "smol-toml": "^1.3.1",
     "ts-node": "10.9.2",
     "typescript": "5.7.2"
   },
@@ -68,14 +76,14 @@
     }
   },
   "optionalDependencies": {
-    "@ast-grep/napi-win32-x64-msvc": "0.31.1",
-    "@ast-grep/napi-darwin-x64": "0.31.1",
-    "@ast-grep/napi-linux-x64-gnu": "0.31.1",
-    "@ast-grep/napi-win32-ia32-msvc": "0.31.1",
-    "@ast-grep/napi-darwin-arm64": "0.31.1",
-    "@ast-grep/napi-win32-arm64-msvc": "0.31.1",
-    "@ast-grep/napi-linux-arm64-gnu": "0.31.1",
-    "@ast-grep/napi-linux-arm64-musl": "0.31.1",
-    "@ast-grep/napi-linux-x64-musl": "0.31.1"
+    "@ast-grep/napi-win32-x64-msvc": "0.32.0",
+    "@ast-grep/napi-darwin-x64": "0.32.0",
+    "@ast-grep/napi-linux-x64-gnu": "0.32.0",
+    "@ast-grep/napi-win32-ia32-msvc": "0.32.0",
+    "@ast-grep/napi-darwin-arm64": "0.32.0",
+    "@ast-grep/napi-win32-arm64-msvc": "0.32.0",
+    "@ast-grep/napi-linux-arm64-gnu": "0.32.0",
+    "@ast-grep/napi-linux-arm64-musl": "0.32.0",
+    "@ast-grep/napi-linux-x64-musl": "0.32.0"
   }
 }

package/types/api.d.ts

@@ -0,0 +1,46 @@
+import type { SgNode, SgRoot } from './sgnode'
+import type { NapiConfig, FindConfig, FileOption } from './config'
+import type { Lang } from './lang'
+import type { NamedKinds, TypesMap } from './staticTypes'
+
+export declare function parseFiles<M extends TypesMap>(
+  paths: Array<string> | FileOption,
+  callback: (err: null | Error, result: SgRoot<M>) => void,
+): Promise<number>
+/** Parse a string to an ast-grep instance */
+export declare function parse<M extends TypesMap>(
+  lang: Lang,
+  src: string,
+): SgRoot<M>
+/**
+ * Parse a string to an ast-grep instance asynchronously in threads.
+ * It utilize multiple CPU cores when **concurrent processing sources**.
+ * However, spawning excessive many threads may backfire.
+ * Please refer to libuv doc, nodejs' underlying runtime
+ * for its default behavior and performance tuning tricks.
+ */
+export declare function parseAsync<M extends TypesMap>(
+  lang: Lang,
+  src: string,
+): Promise<SgRoot<M>>
+/** Get the `kind` number from its string name. */
+export declare function kind<M extends TypesMap>(
+  lang: Lang,
+  kindName: NamedKinds<M>,
+): number
+/** Compile a string to ast-grep Pattern. */
+export declare function pattern<M extends TypesMap>(
+  lang: Lang,
+  pattern: string,
+): NapiConfig<M>
+/**
+ * Discover and parse multiple files in Rust.
+ * `lang` specifies the language.
+ * `config` specifies the file path and matcher.
+ * `callback` will receive matching nodes found in a file.
+ */
+export declare function findInFiles<M extends TypesMap>(
+  lang: Lang,
+  config: FindConfig<M>,
+  callback: (err: null | Error, result: SgNode<M>[]) => void,
+): Promise<number>

package/types/config.d.ts

@@ -0,0 +1,39 @@
+import type { Rule } from './rule'
+import type { Lang } from './lang'
+import type { TypesMap } from './staticTypes'
+
+/**
+ * Rule configuration similar to YAML
+ * See https://ast-grep.github.io/reference/yaml.html
+ */
+export interface NapiConfig<M extends TypesMap = TypesMap> {
+  /** The rule object, see https://ast-grep.github.io/reference/rule.html */
+  rule: Rule<M>
+  /** See https://ast-grep.github.io/guide/rule-config.html#constraints */
+  constraints?: Record<string, Rule<M>>
+  /** Available languages: html, css, js, jsx, ts, tsx */
+  language?: Lang
+  /**
+   * transform is NOT useful in JavaScript. You can use JS code to directly transform the result.
+   * https://ast-grep.github.io/reference/yaml.html#transform
+   */
+  transform?: unknown
+  /** https://ast-grep.github.io/guide/rule-config/utility-rule.html */
+  utils?: Record<string, Rule<M>>
+}
+export interface FileOption {
+  paths: Array<string>
+  languageGlobs: Record<string, Array<string>>
+}
+export interface FindConfig<M extends TypesMap = TypesMap> {
+  /** specify the file paths to recursively find files */
+  paths: Array<string>
+  /** a Rule object to find what nodes will match */
+  matcher: NapiConfig<M>
+  /**
+   * An list of pattern globs to treat of certain files in the specified language.
+   * eg. ['*.vue', '*.svelte'] for html.findFiles, or ['*.ts'] for tsx.findFiles.
+   * It is slightly different from https://ast-grep.github.io/reference/sgconfig.html#languageglobs
+   */
+  languageGlobs?: Array<string>
+}

package/types/deprecated.d.ts

@@ -0,0 +1,117 @@
+import type { SgRoot, SgNode } from './sgnode'
+import type { NapiConfig, FindConfig } from './config'
+
+/**
+ * @deprecated language specific objects are deprecated
+ * use the equivalent functions like `parse` in @ast-grep/napi
+ */
+export declare namespace html {
+  /** @deprecated use `parse(Lang.Html, src)` instead */
+  export function parse(src: string): SgRoot
+  /** @deprecated use `parseAsync(Lang.Html, src)` instead */
+  export function parseAsync(src: string): Promise<SgRoot>
+  /** @deprecated use `kind(Lang.Html, kindName)` instead */
+  export function kind(kindName: string): number
+  /** @deprecated use `pattern(Lang.Html, p)` instead */
+  export function pattern(pattern: string): NapiConfig
+  /** @deprecated use `findInFiles(Lang.Html, config, callback)` instead */
+  export function findInFiles(
+    config: FindConfig,
+    callback: (err: null | Error, result: SgNode[]) => void,
+  ): Promise<number>
+}
+/**
+ * @deprecated language specific objects are deprecated
+ * use the equivalent functions like `parse` in @ast-grep/napi
+ */
+export declare namespace js {
+  /** @deprecated use `parse(Lang.JavaScript, src)` instead */
+  export function parse(src: string): SgRoot
+  /** @deprecated use `parseAsync(Lang.JavaScript, src)` instead */
+  export function parseAsync(src: string): Promise<SgRoot>
+  /** @deprecated use `kind(Lang.JavaScript, kindName)` instead */
+  export function kind(kindName: string): number
+  /** @deprecated use `pattern(Lang.JavaScript, p)` instead */
+  export function pattern(pattern: string): NapiConfig
+  /** @deprecated use `findInFiles(Lang.JavaScript, config, callback)` instead */
+  export function findInFiles(
+    config: FindConfig,
+    callback: (err: null | Error, result: SgNode[]) => void,
+  ): Promise<number>
+}
+/**
+ * @deprecated language specific objects are deprecated
+ * use the equivalent functions like `parse` in @ast-grep/napi
+ */
+export declare namespace jsx {
+  /** @deprecated use `parse(Lang.JavaScript, src)` instead */
+  export function parse(src: string): SgRoot
+  /** @deprecated use `parseAsync(Lang.JavaScript, src)` instead */
+  export function parseAsync(src: string): Promise<SgRoot>
+  /** @deprecated use `kind(Lang.JavaScript, kindName)` instead */
+  export function kind(kindName: string): number
+  /** @deprecated use `pattern(Lang.JavaScript, p)` instead */
+  export function pattern(pattern: string): NapiConfig
+  /** @deprecated use `findInFiles(Lang.JavaScript, config, callback)` instead */
+  export function findInFiles(
+    config: FindConfig,
+    callback: (err: null | Error, result: SgNode[]) => void,
+  ): Promise<number>
+}
+/**
+ * @deprecated language specific objects are deprecated
+ * use the equivalent functions like `parse` in @ast-grep/napi
+ */
+export declare namespace ts {
+  /** @deprecated use `parse(Lang.TypeScript, src)` instead */
+  export function parse(src: string): SgRoot
+  /** @deprecated use `parseAsync(Lang.TypeScript, src)` instead */
+  export function parseAsync(src: string): Promise<SgRoot>
+  /** @deprecated use `kind(Lang.TypeScript, kindName)` instead */
+  export function kind(kindName: string): number
+  /** @deprecated use `pattern(Lang.TypeScript, p)` instead */
+  export function pattern(pattern: string): NapiConfig
+  /** @deprecated use `findInFiles(Lang.TypeScript, config, callback)` instead */
+  export function findInFiles(
+    config: FindConfig,
+    callback: (err: null | Error, result: SgNode[]) => void,
+  ): Promise<number>
+}
+/**
+ * @deprecated language specific objects are deprecated
+ * use the equivalent functions like `parse` in @ast-grep/napi
+ */
+export declare namespace tsx {
+  /** @deprecated use `parse(Lang.Tsx, src)` instead */
+  export function parse(src: string): SgRoot
+  /** @deprecated use `parseAsync(Lang.Tsx, src)` instead */
+  export function parseAsync(src: string): Promise<SgRoot>
+  /** @deprecated use `kind(Lang.Tsx, kindName)` instead */
+  export function kind(kindName: string): number
+  /** @deprecated use `pattern(Lang.Tsx, p)` instead */
+  export function pattern(pattern: string): NapiConfig
+  /** @deprecated use `findInFiles(Lang.Tsx, config, callback)` instead */
+  export function findInFiles(
+    config: FindConfig,
+    callback: (err: null | Error, result: SgNode[]) => void,
+  ): Promise<number>
+}
+/**
+ * @deprecated language specific objects are deprecated
+ * use the equivalent functions like `parse` in @ast-grep/napi
+ */
+export declare namespace css {
+  /** @deprecated use `parse(Lang.Css, src)` instead */
+  export function parse(src: string): SgRoot
+  /** @deprecated use `parseAsync(Lang.Css, src)` instead */
+  export function parseAsync(src: string): Promise<SgRoot>
+  /** @deprecated use `kind(Lang.Css, kindName)` instead */
+  export function kind(kindName: string): number
+  /** @deprecated use `pattern(Lang.Css, p)` instead */
+  export function pattern(pattern: string): NapiConfig
+  /** @deprecated use `findInFiles(Lang.Css, config, callback)` instead */
+  export function findInFiles(
+    config: FindConfig,
+    callback: (err: null | Error, result: SgNode[]) => void,
+  ): Promise<number>
+}

package/types/lang.d.ts

@@ -0,0 +1,26 @@
+export enum Lang {
+  Html = 'Html',
+  JavaScript = 'JavaScript',
+  Tsx = 'Tsx',
+  Css = 'Css',
+  TypeScript = 'TypeScript',
+  Bash = 'Bash',
+  C = 'C',
+  Cpp = 'Cpp',
+  CSharp = 'CSharp',
+  Go = 'Go',
+  Elixir = 'Elixir',
+  Haskell = 'Haskell',
+  Java = 'Java',
+  Json = 'Json',
+  Kotlin = 'Kotlin',
+  Lua = 'Lua',
+  Php = 'Php',
+  Python = 'Python',
+  Ruby = 'Ruby',
+  Rust = 'Rust',
+  Scala = 'Scala',
+  Sql = 'Sql',
+  Swift = 'Swift',
+  Yaml = 'Yaml',
+}

package/{manual.d.ts → types/rule.d.ts}

@@ -1,27 +1,30 @@
-export type Strictness =
-  | 'cst' | 'smart' | 'ast' | 'relaxed' | 'signature'
+import type { TypesMap, NamedKinds } from './staticTypes'
 
-export interface PatternObject {
+export type Strictness = 'cst' | 'smart' | 'ast' | 'relaxed' | 'signature'
+
+export interface PatternObject<M extends TypesMap = TypesMap> {
   context: string
-  selector?: string
+  selector?: NamedKinds<M> // only named node types
   strictness?: Strictness
 }
 
-export type PatternStyle = string | PatternObject
+export type PatternStyle<M extends TypesMap = TypesMap> =
+  | string
+  | PatternObject<M>
 
-export interface Relation extends Rule {
+export interface Relation<M extends TypesMap = TypesMap> extends Rule<M> {
   /**
    * Specify how relational rule will stop relative to the target node.
    */
-  stopBy?: 'neighbor' | 'end' | Rule
+  stopBy?: 'neighbor' | 'end' | Rule<M>
   /** Specify the tree-sitter field in parent node. Only available in has/inside rule. */
   field?: string
 }
 
-export interface NthChildObject {
+export interface NthChildObject<M extends TypesMap = TypesMap> {
   /** The position in nodes' sibling list. It can be a number of An+B string */
   position: string | number
-  ofRule?: Rule
+  ofRule?: Rule<M>
   reverse?: boolean
 }
 
@@ -31,11 +34,14 @@ export interface NthChildObject {
  * * string: An + B style string like CSS nth-child selector.
  * * object: An object with `position` and `ofRule` fields.
  */
-export type NthChild = number | string | NthChildObject
+export type NthChild<M extends TypesMap = TypesMap> =
+  | number
+  | string
+  | NthChildObject<M>
 
 export interface Position {
-  /** 0-indexed row number. */
-  row: number
+  /** 0-indexed line number. */
+  line: number
   /** 0-indexed column number. */
   column: number
 }
@@ -45,11 +51,11 @@ export interface Range {
   end: Position
 }
 
-export interface Rule {
+export interface Rule<M extends TypesMap = TypesMap> {
   /** A pattern string or a pattern object. */
-  pattern?: PatternStyle
+  pattern?: PatternStyle<M>
   /** The kind name of the node to match. You can look up code's kind names in playground. */
-  kind?: string
+  kind?: NamedKinds<M>
   /** The exact range of the node in the source code. */
   range?: Range
   /** A Rust regular expression to match the node's text. https://docs.rs/regex/latest/regex/#syntax */
@@ -57,36 +63,36 @@ export interface Rule {
   /**
    * `nthChild` accepts number, string or object.
    * It specifies the position in nodes' sibling list. */
-  nthChild?: NthChild
+  nthChild?: NthChild<M>
 
   // relational
   /**
    * `inside` accepts a relational rule object.
    * the target node must appear inside of another node matching the `inside` sub-rule. */
-  inside?: Relation
+  inside?: Relation<M>
   /**
    * `has` accepts a relational rule object.
    * the target node must has a descendant node matching the `has` sub-rule. */
-  has?: Relation
+  has?: Relation<M>
   /**
    * `precedes` accepts a relational rule object.
    * the target node must appear before another node matching the `precedes` sub-rule. */
-  precedes?: Relation
+  precedes?: Relation<M>
   /**
    * `follows` accepts a relational rule object.
    * the target node must appear after another node matching the `follows` sub-rule. */
-  follows?: Relation
+  follows?: Relation<M>
   // composite
   /**
    * A list of sub rules and matches a node if all of sub rules match.
    * The meta variables of the matched node contain all variables from the sub-rules. */
-  all?: Array<Rule>
+  all?: Array<Rule<M>>
   /**
    * A list of sub rules and matches a node if any of sub rules match.
    * The meta variables of the matched node only contain those of the matched sub-rule. */
-  any?: Array<Rule>
+  any?: Array<Rule<M>>
   /** A single sub-rule and matches a node if the sub rule does not match. */
-  not?: Rule
+  not?: Rule<M>
   /** A utility rule id and matches a node if the utility rule matches. */
   matches?: string
-}
+}

package/types/sgnode.d.ts

@@ -0,0 +1,119 @@
+import type {
+  FieldNames,
+  TypesInField,
+  TypesMap,
+  ExtractField,
+  Kinds,
+  NodeFieldInfo,
+  RootKind,
+} from './staticTypes'
+import type { NapiConfig } from './config'
+
+export interface Edit {
+  /** The start position of the edit */
+  startPos: number
+  /** The end position of the edit */
+  endPos: number
+  /** The text to be inserted */
+  insertedText: string
+}
+export interface Pos {
+  /** line number starting from 0 */
+  line: number
+  /** column number starting from 0 */
+  column: number
+  /** byte offset of the position */
+  index: number
+}
+export interface Range {
+  /** starting position of the range */
+  start: Pos
+  /** ending position of the range */
+  end: Pos
+}
+
+export declare class SgNode<
+  M extends TypesMap = TypesMap,
+  out T extends Kinds<M> = Kinds<M>,
+> {
+  range(): Range
+  isLeaf(): boolean
+  isNamed(): boolean
+  isNamedLeaf(): boolean
+  /** Returns the string name of the node kind */
+  kind(): T
+  readonly kindToRefine: T
+  /** Check if the node is the same kind as the given `kind` string */
+  is<K extends Kinds<M>>(kind: K): this is SgNode<M, K>
+  text(): string
+  matches(m: string): boolean
+  inside(m: string): boolean
+  has(m: string): boolean
+  precedes(m: string): boolean
+  follows(m: string): boolean
+  getMatch<K extends Kinds<M>>(m: string): RefineNode<M, K> | null
+  getMultipleMatches(m: string): Array<SgNode<M>>
+  getTransformed(m: string): string | null
+  /** Returns the node's SgRoot */
+  getRoot(): SgRoot<M>
+  children(): Array<SgNode<M>>
+  /** Returns the node's id */
+  id(): number
+  find<K extends Kinds<M>>(
+    matcher: string | number | NapiConfig<M>,
+  ): RefineNode<M, K> | null
+  findAll<K extends Kinds<M>>(
+    matcher: string | number | NapiConfig<M>,
+  ): Array<RefineNode<M, K>>
+  /** Finds the first child node in the `field` */
+  field<F extends FieldNames<M[T]>>(name: F): FieldNode<M, T, F>
+  /** Finds all the children nodes in the `field` */
+  fieldChildren<F extends FieldNames<M[T]>>(
+    name: F,
+  ): Exclude<FieldNode<M, T, F>, null>[]
+  parent<K extends Kinds<M>>(): RefineNode<M, K> | null
+  child<K extends Kinds<M>>(nth: number): RefineNode<M, K> | null
+  ancestors(): Array<SgNode<M>>
+  next<K extends Kinds<M>>(): RefineNode<M, K> | null
+  nextAll(): Array<SgNode<M>>
+  prev<K extends Kinds<M>>(): RefineNode<M, K> | null
+  prevAll(): Array<SgNode<M>>
+  replace(text: string): Edit
+  commitEdits(edits: Array<Edit>): string
+}
+/** Represents the parsed tree of code. */
+export declare class SgRoot<M extends TypesMap = TypesMap> {
+  /** Returns the root SgNode of the ast-grep instance. */
+  root(): SgNode<M, RootKind<M>>
+  /**
+   * Returns the path of the file if it is discovered by ast-grep's `findInFiles`.
+   * Returns `"anonymous"` if the instance is created by `lang.parse(source)`.
+   */
+  filename(): string
+}
+
+/**
+ * if K contains string, return general SgNode. Otherwise,
+ * if K is a literal union, return a union of SgNode of each kind.
+ */
+type RefineNode<M extends TypesMap, K> = string extends K
+  ? SgNode<M>
+  : K extends Kinds<M>
+    ? SgNode<M, K>
+    : never
+
+/**
+ * return the SgNode of the field in the node.
+ */
+// F extends string is used to prevent noisy TS hover info
+type FieldNode<
+  M extends TypesMap,
+  K extends Kinds<M>,
+  F extends FieldNames<M[K]>,
+> = F extends string ? FieldNodeImpl<M, ExtractField<M[K], F>> : never
+
+type FieldNodeImpl<M extends TypesMap, I extends NodeFieldInfo> = I extends {
+  required: true
+}
+  ? RefineNode<M, TypesInField<M, I>>
+  : RefineNode<M, TypesInField<M, I>> | null

package/types/staticTypes.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Reference
+ * https://tree-sitter.github.io/tree-sitter/using-parsers#static-node-types
+ * Rust CLI Impl
+ * https://github.com/tree-sitter/tree-sitter/blob/f279d10aa2aca37c0004d84b2261685739f3cab8/cli/generate/src/node_types.rs#L35-L47
+ */
+
+export interface NodeBasicInfo {
+  type: string
+  named: boolean
+}
+
+export interface NodeFieldInfo {
+  multiple: boolean
+  required: boolean
+  types: NodeBasicInfo[]
+}
+
+export interface NodeType extends NodeBasicInfo {
+  root?: boolean
+  fields?: {
+    [fieldName: string]: NodeFieldInfo
+  }
+  children?: NodeFieldInfo
+  subtypes?: NodeBasicInfo[]
+}
+
+/**
+ * A map of key to NodeType.
+ * Note, the key is not necessary node's kind.
+ * it can be a rule representing a category of syntax nodes
+ * (e.g. “expression”, “type”, “declaration”).
+ * See reference above for more details.
+ */
+export interface TypesMap {
+  [key: string]: NodeType
+}
+
+export type FieldNames<N extends NodeType> = N extends { fields: infer F }
+  ? keyof F
+  : string
+
+export type ExtractField<
+  N extends NodeType,
+  F extends FieldNames<N>,
+> = N['fields'] extends Record<F, NodeFieldInfo>
+  ? N['fields'][F]
+  : NodeFieldInfo
+
+// in case of empty types array, return string as fallback
+type NoNever<T, Fallback = string> = [T] extends [never] ? Fallback : T
+
+export type TypesInField<M extends TypesMap, I extends NodeFieldInfo> = NoNever<
+  ResolveType<M, I['types'][number]['type']>
+>
+
+/**
+ * resolve subtypes alias. see tree-sitter's reference
+ * e.g. like `expression` => `binary_expression` | `unary_expression` | ...
+ */
+type ResolveType<M extends TypesMap, K> = K extends keyof M
+  ? M[K] extends { subtypes: infer S extends NodeBasicInfo[] }
+    ? ResolveType<M, S[number]['type']>
+    : K
+  : K
+
+/**
+ * All named nodes' kinds that are usable in ast-grep rule
+ * NOTE: SgNode can return kind not in this list
+ */
+export type NamedKinds<M extends TypesMap> = ResolveType<M, keyof M>
+
+/**
+ * See open-ended unions / string literal completion in TypeScript
+ * https://github.com/microsoft/TypeScript/issues/26277
+ * https://github.com/microsoft/TypeScript/issues/33471
+ */
+type LowPriorityKey = string & {}
+
+/**
+ * A union of all named node kinds and a low priority key
+ * tree-sitter Kinds also include unnamed nodes which is not usable in rule
+ * NOTE: SgNode can return a string type if it is not a named node
+ */
+export type Kinds<M extends TypesMap = TypesMap> =
+  | NamedKinds<M>
+  | LowPriorityKey
+
+/**
+ * The root node kind of the tree.
+ */
+export type RootKind<M extends TypesMap> = NoNever<
+  Extract<M[keyof M], { root: true }>['type'],
+  Kinds<M>
+>