@kreuzberg/tree-sitter-language-pack 1.6.2 → 1.8.0-rc.19

package/index.d.ts

@@ -1,330 +1,1152 @@
-/* auto-generated by NAPI-RS */
+// This file is auto-generated by alef — DO NOT EDIT.
+// alef:hash:f6e4811199d464c199f48100178d92c2e39459da567fbbc1253fa08fa895a07c
+// To regenerate: alef generate
+// To verify freshness: alef verify --exit-code
+// Issues & docs: https://github.com/kreuzberg-dev/alef
 /* eslint-disable */
 
-export declare class ExternalObject<T> {
-	readonly "": {
-		readonly "": unique symbol;
-		[K: symbol]: T;
-	};
-}
-
-/** Byte and line/column span within source code. */
-export interface Span {
-	startByte: number;
-	endByte: number;
-	startRow: number;
-	startCol: number;
-	endRow: number;
-	endCol: number;
-}
-
-/** Information about a single syntax tree node. */
-export interface NodeInfo {
-	kind: string;
-	isNamed: boolean;
-	startByte: number;
-	endByte: number;
-	startRow: number;
-	startCol: number;
-	endRow: number;
-	endCol: number;
-	namedChildCount: number;
-	isError: boolean;
-	isMissing: boolean;
-}
+/**
+ * List all available language names (sorted, deduplicated, includes aliases).
+ *
+ * Returns names of both statically compiled and dynamically loadable languages,
+ * plus any configured aliases.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::available_languages;
+ *
+ * let langs = available_languages();
+ * for name in &langs {
+ * println!("{}", name);
+ * }
+ * ```
+ */
+export declare function availableLanguages(): Array<string>;
 
-/** Aggregate metrics for a source file. */
-export interface FileMetrics {
-	totalLines: number;
-	totalBytes: number;
-	blankLines: number;
-	commentLines: number;
-	codeLines: number;
-	errorCount: number;
+/**
+ * Return the effective cache directory path.
+ *
+ * This is either the custom path set via [`configure`] / [`init`] or the
+ * default: `~/.cache/tree-sitter-language-pack/v{version}/libs/`.
+ *
+ * # Errors
+ *
+ * Returns an error if the system cache directory cannot be determined.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::cache_dir;
+ *
+ * let dir = cache_dir().unwrap();
+ * println!("Cache directory: {}", dir.display());
+ * ```
+ */
+export declare function cacheDir(): string;
+
+/**
+ * Delete all cached parser shared libraries.
+ *
+ * Resets the cache registration so the next call to [`get_language`] or
+ * a download function will re-register the (now empty) cache directory.
+ *
+ * # Errors
+ *
+ * Returns an error if the cache directory cannot be removed.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::clean_cache;
+ *
+ * clean_cache().unwrap();
+ * println!("Cache cleared");
+ * ```
+ */
+export declare function cleanCache(): void;
+
+/**
+ * Apply download configuration without downloading anything.
+ *
+ * Use this to set a custom cache directory before the first call to
+ * [`get_language`] or any download function. Changing the cache dir
+ * after languages have been registered has no effect on already-loaded
+ * languages.
+ *
+ * # Errors
+ *
+ * Returns an error if the lock cannot be acquired.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use std::path::PathBuf;
+ * use tree_sitter_language_pack::{PackConfig, configure};
+ *
+ * let config = PackConfig {
+ * cache_dir: Some(PathBuf::from("/tmp/my-parsers")),
+ * languages: None,
+ * groups: None,
+ * };
+ * configure(&config).unwrap();
+ * ```
+ */
+export declare function configure(config: JsPackConfig): void;
+
+/**
+ * Detect language name from file content using the shebang line (`#!`).
+ *
+ * Inspects only the first line of `content`. If it begins with `#!`, the
+ * interpreter name is extracted and mapped to a language name.
+ *
+ * Handles common patterns:
+ * - `#!/usr/bin/env python3` → `"python"`
+ * - `#!/bin/bash` → `"bash"`
+ * - `#!/usr/bin/env node` → `"javascript"`
+ *
+ * The `-S` flag accepted by some `env` implementations is skipped automatically.
+ * Version suffixes (e.g. `python3.11`, `ruby3.2`) are stripped before matching.
+ *
+ * Returns `None` when content does not start with `#!`, the shebang is
+ * malformed, or the interpreter is not recognised.
+ *
+ * ```
+ * use tree_sitter_language_pack::detect_language_from_content;
+ * assert_eq!(detect_language_from_content("#!/usr/bin/env python3\npass"), Some("python"));
+ * assert_eq!(detect_language_from_content("#!/bin/bash\necho hi"), Some("bash"));
+ * assert_eq!(detect_language_from_content("no shebang here"), None);
+ * ```
+ */
+export declare function detectLanguageFromContent(content: string): string | undefined | null;
+
+/**
+ * Detect language name from a file extension (without leading dot).
+ *
+ * Returns `None` for unrecognized extensions. The match is case-insensitive.
+ *
+ * ```
+ * use tree_sitter_language_pack::detect_language_from_extension;
+ * assert_eq!(detect_language_from_extension("py"), Some("python"));
+ * assert_eq!(detect_language_from_extension("RS"), Some("rust"));
+ * assert_eq!(detect_language_from_extension("xyz"), None);
+ * ```
+ */
+export declare function detectLanguageFromExtension(ext: string): string | undefined | null;
+
+/**
+ * Detect language name from a file path.
+ *
+ * Extracts the file extension and looks it up. Returns `None` if the
+ * path has no extension or the extension is not recognized.
+ *
+ * ```
+ * use tree_sitter_language_pack::detect_language_from_path;
+ * assert_eq!(detect_language_from_path("src/main.rs"), Some("rust"));
+ * assert_eq!(detect_language_from_path("README.md"), Some("markdown"));
+ * assert_eq!(detect_language_from_path("Makefile"), None);
+ * ```
+ */
+export declare function detectLanguageFromPath(path: string): string | undefined | null;
+
+/**
+ * Download specific languages to the local cache.
+ *
+ * Returns the number of newly downloaded languages (languages that were
+ * already cached are not counted).
+ *
+ * # Errors
+ *
+ * Returns an error if any language is not available in the manifest or if
+ * the download fails.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::download;
+ *
+ * let count = download(&["python", "rust", "typescript"]).unwrap();
+ * println!("Downloaded {} new languages", count);
+ * ```
+ */
+export declare function download(names: Array<string>): number;
+
+/**
+ * Download all available languages from the remote manifest.
+ *
+ * Returns the number of newly downloaded languages.
+ *
+ * # Errors
+ *
+ * Returns an error if the manifest cannot be fetched or a download fails.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::download_all;
+ *
+ * let count = download_all().unwrap();
+ * println!("Downloaded {} languages", count);
+ * ```
+ */
+export declare function downloadAll(): number;
+
+/**
+ * Return languages that are already downloaded and cached locally.
+ *
+ * Does not perform any network requests. Returns an empty list if the
+ * cache directory does not exist or cannot be read.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::downloaded_languages;
+ *
+ * let langs = downloaded_languages();
+ * println!("{} languages already cached", langs.len());
+ * ```
+ */
+export declare function downloadedLanguages(): Array<string>;
+
+/**
+ * Run extraction patterns against source code.
+ *
+ * Convenience wrapper around [`extract::extract`].
+ *
+ * # Errors
+ *
+ * Returns an error if the language is not found, parsing fails, or a query
+ * pattern is invalid.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use ahash::AHashMap;
+ * use tree_sitter_language_pack::{ExtractionConfig, ExtractionPattern, CaptureOutput, extract_patterns};
+ *
+ * let mut patterns = AHashMap::new();
+ * patterns.insert("fns".to_string(), ExtractionPattern {
+ * query: "(function_definition name: (identifier) @fn_name)".to_string(),
+ * capture_output: CaptureOutput::default(),
+ * child_fields: Vec::new(),
+ * max_results: None,
+ * byte_range: None,
+ * });
+ * let config = ExtractionConfig { language: "python".to_string(), patterns };
+ * let result = extract_patterns("def hello(): pass", &config).unwrap();
+ * ```
+ */
+export declare function extractPatterns(source: string, config: JsExtractionConfig): JsExtractionResult;
+
+/**
+ * Find all nodes matching the given type name, returning their `NodeInfo`.
+ *
+ * Performs a depth-first traversal. Returns an empty vec if no matches.
+ */
+export declare function findNodesByType(tree: JsTree, nodeType: string): Array<JsNodeInfo>;
+
+/**
+ * Get the highlights query for a language, if bundled.
+ *
+ * Returns the contents of `highlights.scm` as a static string, or `None`
+ * if no highlights query is bundled for this language.
+ *
+ * # Example
+ *
+ * ```
+ * use tree_sitter_language_pack::get_highlights_query;
+ *
+ * // Returns Some(...) for languages with bundled queries
+ * let query = get_highlights_query("python");
+ * // Returns None for languages without bundled highlights queries
+ * let missing = get_highlights_query("nonexistent_lang");
+ * assert!(missing.is_none());
+ * ```
+ */
+export declare function getHighlightsQuery(language: string): string | undefined | null;
+
+/**
+ * Get the injections query for a language, if bundled.
+ *
+ * Returns the contents of `injections.scm` as a static string, or `None`
+ * if no injections query is bundled for this language.
+ *
+ * # Example
+ *
+ * ```
+ * use tree_sitter_language_pack::get_injections_query;
+ *
+ * let query = get_injections_query("markdown");
+ * // Returns None for languages without bundled injections queries
+ * let missing = get_injections_query("nonexistent_lang");
+ * assert!(missing.is_none());
+ * ```
+ */
+export declare function getInjectionsQuery(language: string): string | undefined | null;
+
+/**
+ * Get a tree-sitter [`Language`] by name using the global registry.
+ *
+ * Resolves language aliases (e.g., `"shell"` maps to `"bash"`).
+ * When the `download` feature is enabled (default), automatically downloads
+ * the parser from GitHub releases if not found locally.
+ *
+ * # Errors
+ *
+ * Returns [`Error::LanguageNotFound`] if the language is not recognized,
+ * or [`Error::Download`] if auto-download fails.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::get_language;
+ *
+ * let lang = get_language("python").unwrap();
+ * // Use the Language with a tree-sitter Parser
+ * let mut parser = tree_sitter::Parser::new();
+ * parser.set_language(&lang).unwrap();
+ * let tree = parser.parse("x = 1", None).unwrap();
+ * assert_eq!(tree.root_node().kind(), "module");
+ * ```
+ */
+export declare function getLanguage(name: string): JsLanguage;
+
+/**
+ * Get the locals query for a language, if bundled.
+ *
+ * Returns the contents of `locals.scm` as a static string, or `None`
+ * if no locals query is bundled for this language.
+ *
+ * # Example
+ *
+ * ```
+ * use tree_sitter_language_pack::get_locals_query;
+ *
+ * let query = get_locals_query("python");
+ * // Returns None for languages without bundled locals queries
+ * let missing = get_locals_query("nonexistent_lang");
+ * assert!(missing.is_none());
+ * ```
+ */
+export declare function getLocalsQuery(language: string): string | undefined | null;
+
+/**
+ * Get a tree-sitter [`Parser`] pre-configured for the given language.
+ *
+ * This is a convenience function that calls [`get_language`] and configures
+ * a new parser in one step.
+ *
+ * # Errors
+ *
+ * Returns [`Error::LanguageNotFound`] if the language is not recognized, or
+ * [`Error::ParserSetup`] if the language cannot be applied to the parser.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::get_parser;
+ *
+ * let mut parser = get_parser("rust").unwrap();
+ * let tree = parser.parse("fn main() {}", None).unwrap();
+ * assert!(!tree.root_node().has_error());
+ * ```
+ */
+export declare function getParser(name: string): JsParser;
+
+/**
+ * Check if a language is available by name or alias.
+ *
+ * Returns `true` if the language can be loaded (statically compiled,
+ * dynamically available, or a known alias for one of these).
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::has_language;
+ *
+ * assert!(has_language("python"));
+ * assert!(has_language("shell")); // alias for "bash"
+ * assert!(!has_language("nonexistent_language"));
+ * ```
+ */
+export declare function hasLanguage(name: string): boolean;
+
+/**
+ * Initialize the language pack with the given configuration.
+ *
+ * Applies any custom cache directory, then downloads all languages and groups
+ * specified in the config. This is the recommended entry point when you want
+ * to pre-warm the cache before use.
+ *
+ * # Errors
+ *
+ * Returns an error if configuration cannot be applied or if downloads fail.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::{PackConfig, init};
+ *
+ * let config = PackConfig {
+ * cache_dir: None,
+ * languages: Some(vec!["python".to_string(), "rust".to_string()]),
+ * groups: None,
+ * };
+ * init(&config).unwrap();
+ * ```
+ */
+export declare function init(config: JsPackConfig): void;
+
+/** Controls what data is captured for each query match. */
+export declare enum JsCaptureOutput {
+  /** Capture only the matched text. */
+  Text = "Text",
+  /** Capture only the `NodeInfo`. */
+  Node = "Node",
+  /** Capture both text and `NodeInfo` (default). */
+  Full = "Full",
 }
 
-/** A structural item (function, class, method, etc.) in source code. */
-export interface StructureItem {
-	kind: string;
-	name: string;
-	span: Span;
-	parent: string | null;
+/** A single captured node within a match. */
+export interface JsCaptureResult {
+  /** The capture name from the query (e.g., `"fn_name"`). */
+  name: string
+  /** The `NodeInfo` snapshot, present when `CaptureOutput` is `Node` or `Full`. */
+  node: JsNodeInfo
+  /** The matched source text, present when `CaptureOutput` is `Text` or `Full`. */
+  text: string
+  /** Values of requested child fields, keyed by field name. */
+  childFields: string
+  /** Byte offset where this capture starts in the source. */
+  startByte: number
 }
 
-/** An import statement extracted from source code. */
-export interface ImportInfo {
-	module: string;
-	names: string[];
-	span: Span;
+/** Metadata for a single chunk of source code. */
+export interface JsChunkContext {
+  language: string
+  chunkIndex: number
+  totalChunks: number
+  nodeTypes: Array<string>
+  contextPath: Array<string>
+  symbolsDefined: Array<string>
+  comments: Array<JsCommentInfo>
+  docstrings: Array<JsDocstringInfo>
+  hasErrorNodes: boolean
 }
 
-/** An export statement extracted from source code. */
-export interface ExportInfo {
-	name: string;
-	kind: string;
-	span: Span;
+/** A chunk of source code with rich metadata. */
+export interface JsCodeChunk {
+  content: string
+  startByte: number
+  endByte: number
+  startLine: number
+  endLine: number
+  metadata: JsChunkContext
 }
 
 /** A comment extracted from source code. */
-export interface CommentInfo {
-	text: string;
-	kind: string;
-	span: Span;
-	associatedNode: string | null;
+export interface JsCommentInfo {
+  text: string
+  kind: JsCommentKind
+  span: JsSpan
+  associatedNode: string
+}
+
+/**
+ * The kind of a comment found in source code.
+ *
+ * Distinguishes between single-line comments, block (multi-line) comments,
+ * and documentation comments.
+ */
+export declare enum JsCommentKind {
+  Line = "Line",
+  Block = "Block",
+  Doc = "Doc",
+}
+
+/** A diagnostic (syntax error, missing node, etc.) from parsing. */
+export interface JsDiagnostic {
+  message: string
+  severity: JsDiagnosticSeverity
+  span: JsSpan
+}
+
+/**
+ * Severity level of a diagnostic produced during parsing.
+ *
+ * Used to classify parse errors, warnings, and informational messages
+ * found in the syntax tree.
+ */
+export declare enum JsDiagnosticSeverity {
+  Error = "Error",
+  Warning = "Warning",
+  Info = "Info",
+}
+
+/** A section within a docstring (e.g., Args, Returns, Raises). */
+export interface JsDocSection {
+  kind: string
+  name: string
+  description: string
+}
+
+/**
+ * The format of a docstring extracted from source code.
+ *
+ * Identifies the docstring convention used, which varies by language
+ * (e.g., Python triple-quoted strings, JSDoc, Rustdoc `///` comments).
+ */
+export declare enum JsDocstringFormat {
+  PythonTripleQuote = "PythonTripleQuote",
+  JSDoc = "JSDoc",
+  Rustdoc = "Rustdoc",
+  GoDoc = "GoDoc",
+  JavaDoc = "JavaDoc",
+  Other = "Other",
 }
 
 /** A docstring extracted from source code. */
-export interface DocstringInfo {
-	text: string;
-	format: string;
-	span: Span;
-	associatedItem: string | null;
-	sections: Array<Record<string, string>>;
+export interface JsDocstringInfo {
+  text: string
+  format: JsDocstringFormat
+  span: JsSpan
+  associatedItem: string
+  parsedSections: Array<JsDocSection>
 }
 
-/** A symbol (variable, function, type, etc.) extracted from source code. */
-export interface SymbolInfo {
-	name: string;
-	kind: string;
-	span: Span;
-	typeAnnotation: string | null;
+/** Manages downloading and caching of pre-built parser shared libraries. */
+export declare class JsDownloadManager {
+  /** Create a new download manager for the given version. */
+  static new(version: string): JsDownloadManager
+  /** Create a download manager with a custom cache directory. */
+  static withCacheDir(version: string, cacheDir: string): JsDownloadManager
+  /** Default cache directory: `~/.cache/tree-sitter-language-pack/v{version}/libs/` */
+  static defaultCacheDir(version: string): string
+  /** Return the path to the libs cache directory. */
+  cacheDir(): string
+  /** List languages that are already downloaded and cached. */
+  installedLanguages(): Array<string>
+  /**
+   * Ensure the specified languages are available in the cache.
+   * Downloads the platform bundle if any requested languages are missing.
+   */
+  ensureLanguages(names: Array<string>): void
+  /** Ensure all languages in a named group are available. */
+  ensureGroup(group: string): void
+  /** Get the expected path for a language's shared library in the cache. */
+  libPath(name: string): string
+  /** Fetch the parser manifest from GitHub Releases. */
+  fetchManifest(): JsParserManifest
+  /** Remove all cached parser libraries. */
+  cleanCache(): void
 }
 
-/** A diagnostic (syntax error, missing node, etc.) from parsing. */
-export interface Diagnostic {
-	message: string;
-	severity: string;
-	span: Span;
+/** An export statement extracted from source code. */
+export interface JsExportInfo {
+  name: string
+  kind: JsExportKind
+  span: JsSpan
 }
 
-/** Metadata for a single chunk of source code. */
-export interface ChunkContext {
-	language: string;
-	chunkIndex: number;
-	totalChunks: number;
-	startLine: number;
-	endLine: number;
-	nodeTypes: string[];
-	symbolsDefined: string[];
-	comments: string[];
-	docstrings: string[];
-	hasErrorNodes: boolean;
-	contextPath: string[];
+/**
+ * The kind of an export statement found in source code.
+ *
+ * Covers named exports, default exports, and re-exports from other modules.
+ */
+export declare enum JsExportKind {
+  Named = "Named",
+  Default = "Default",
+  ReExport = "ReExport",
 }
 
-/** A chunk of source code with rich metadata. */
-export interface CodeChunk {
-	content: string;
-	startByte: number;
-	endByte: number;
-	metadata: ChunkContext;
+/** Configuration for an extraction run against a single language. */
+export interface JsExtractionConfig {
+  /** The language name (e.g., `"python"`). */
+  language: string
+  /** Named patterns to run. Keys become the keys in `ExtractionResult::results`. */
+  patterns: string
 }
 
-/** Complete analysis result from processing a source file. */
-export interface ProcessResult {
-	language: string;
-	metrics: FileMetrics;
-	structure: StructureItem[];
-	imports: ImportInfo[];
-	exports: ExportInfo[];
-	comments: CommentInfo[];
-	docstrings: DocstringInfo[];
-	symbols: SymbolInfo[];
-	diagnostics: Diagnostic[];
-	chunks: CodeChunk[];
+/** Defines a single extraction pattern and its configuration. */
+export interface JsExtractionPattern {
+  /** The tree-sitter query string (S-expression). */
+  query: string
+  /** What to include in each capture result. */
+  captureOutput: JsCaptureOutput
+  /**
+   * Field names to extract from child nodes of each capture.
+   * Maps a label to a tree-sitter field name used with `child_by_field_name`.
+   */
+  childFields: Array<string>
+  /** Maximum number of matches to return. `None` means unlimited. */
+  maxResults: number
+  /** Restrict matches to a byte range `(start, end)`. */
+  byteRange: Array<number>
 }
 
-/** A single query capture pairing a capture name with a node. */
-export interface QueryCapture {
-	captureName: string;
-	node: NodeInfo;
+/** Complete extraction results for all patterns. */
+export interface JsExtractionResult {
+  /** The language that was used. */
+  language: string
+  /** Results keyed by pattern name. */
+  results: string
 }
 
-/** A single pattern match from a tree-sitter query. */
-export interface QueryMatch {
-	patternIndex: number;
-	captures: QueryCapture[];
+/** Aggregate metrics for a source file. */
+export interface JsFileMetrics {
+  totalLines: number
+  codeLines: number
+  commentLines: number
+  blankLines: number
+  totalBytes: number
+  nodeCount: number
+  errorCount: number
+  maxDepth: number
 }
 
-/** Result of resolving a file-extension ambiguity. */
-export interface AmbiguityResult {
-	assigned: string;
-	alternatives: string[];
+/** An import statement extracted from source code. */
+export interface JsImportInfo {
+  source: string
+  items: Array<string>
+  alias: string
+  isWildcard: boolean
+  span: JsSpan
 }
 
-/** Returns an array of all available language names. */
-export declare function availableLanguages(): Array<string>;
+export declare class JsLanguage {
+}
+
+export interface JsLanguageInfo {
+  group: string
+  size: number
+}
 
 /**
- * Get the effective cache directory being used.
+ * Thread-safe registry of tree-sitter language parsers.
+ *
+ * Manages both statically compiled and dynamically loaded language grammars.
+ * Use [`LanguageRegistry::new()`] for the default registry, or access the
+ * global instance via the module-level convenience functions
+ * ([`crate::get_language`], [`crate::available_languages`], etc.).
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::{LanguageRegistry, ProcessConfig};
  *
- * Returns the path as a string. Throws an error if cache directory cannot be determined.
+ * let registry = LanguageRegistry::new();
+ * let langs = registry.available_languages();
+ * println!("Available: {:?}", langs);
+ *
+ * let config = ProcessConfig::new("python").all();
+ * let result = registry.process("def hello(): pass", &config).unwrap();
+ * println!("Structure: {:?}", result.structure);
+ * ```
  */
-export declare function cacheDir(): string;
+export declare class JsLanguageRegistry {
+  /**
+   * Create a registry with a custom directory for dynamic libraries.
+   *
+   * Overrides the default build-time library directory. Useful when
+   * dynamic grammar shared libraries are stored in a non-standard location.
+   */
+  static withLibsDir(libsDir: string): JsLanguageRegistry
+  /**
+   * Add an additional directory to search for dynamic libraries.
+   *
+   * When [`get_language`](Self::get_language) cannot find a grammar in the
+   * primary library directory, it searches these extra directories in order.
+   * Typically used by the download system to register its cache directory.
+   *
+   * Takes `&self` (not `&mut self`) because `extra_lib_dirs` uses interior
+   * mutability via an `Arc<RwLock<...>>`, so the outer registry can remain
+   * immutable while the directory list is updated.
+   */
+  addExtraLibsDir(dir: string): void
+  /**
+   * Get a tree-sitter [`Language`] by name.
+   *
+   * Resolves aliases (e.g., `"shell"` -> `"bash"`, `"makefile"` -> `"make"`),
+   * then looks up the language in the static table. When the `dynamic-loading`
+   * feature is enabled, falls back to loading a shared library on demand.
+   *
+   * # Errors
+   *
+   * Returns [`Error::LanguageNotFound`] if the name (after alias resolution)
+   * does not match any known grammar.
+   */
+  getLanguage(name: string): JsLanguage
+  /**
+   * List all available language names, sorted and deduplicated.
+   *
+   * Includes statically compiled languages, dynamically loadable languages
+   * (if the `dynamic-loading` feature is enabled), and all configured aliases.
+   */
+  availableLanguages(): Array<string>
+  /**
+   * Check whether a language is available by name or alias.
+   *
+   * Returns `true` if the language can be loaded, either from the static
+   * table or from a dynamic library on disk.
+   */
+  hasLanguage(name: string): boolean
+  /** Return the total number of available languages (including aliases). */
+  languageCount(): number
+  /** Parse source code and extract file intelligence based on config in a single pass. */
+  process(source: string, config: JsProcessConfig): JsProcessResult
+  static default(): JsLanguageRegistry
+}
+
+/** A single query match containing one or more captures. */
+export interface JsMatchResult {
+  /** The pattern index within the query that produced this match. */
+  patternIndex: number
+  /** The captures for this match. */
+  captures: Array<JsCaptureResult>
+}
 
 /**
- * Delete all cached parser files.
+ * Lightweight snapshot of a tree-sitter node's properties.
  *
- * Throws an error if cache deletion fails.
+ * Contains only primitive types for easy cross-language serialization.
+ * This is an owned type that can be passed across FFI boundaries, unlike
+ * `tree_sitter::Node` which borrows from the tree.
  */
-export declare function cleanCache(): void;
+export interface JsNodeInfo {
+  /** The grammar type name (e.g., "function_definition", "identifier"). */
+  kind: string
+  /** Whether this is a named node (vs anonymous like punctuation). */
+  isNamed: boolean
+  /** Start byte offset in source. */
+  startByte: number
+  /** End byte offset in source. */
+  endByte: number
+  /** Start row (zero-indexed). */
+  startRow: number
+  /** Start column (zero-indexed). */
+  startCol: number
+  /** End row (zero-indexed). */
+  endRow: number
+  /** End column (zero-indexed). */
+  endCol: number
+  /** Number of named children. */
+  namedChildCount: number
+  /** Whether this node is an ERROR node. */
+  isError: boolean
+  /** Whether this node is a MISSING node. */
+  isMissing: boolean
+}
 
 /**
- * Configure the cache directory without downloading.
+ * Configuration for the tree-sitter language pack.
+ *
+ * Controls cache directory and which languages to pre-download.
+ * Can be loaded from a TOML file, constructed programmatically,
+ * or passed as a dict/object from language bindings.
  *
- * Throws an error if configuration fails.
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::PackConfig;
+ *
+ * let config = PackConfig {
+ * cache_dir: None,
+ * languages: Some(vec!["python".to_string(), "rust".to_string()]),
+ * groups: None,
+ * };
+ * ```
  */
-export declare function configure(config: JsPackConfig): void;
+export interface JsPackConfig {
+  /**
+   * Override default cache directory.
+   *
+   * Default: `~/.cache/tree-sitter-language-pack/v{version}/libs/`
+   */
+  cacheDir: string
+  /**
+   * Languages to pre-download on init.
+   *
+   * Each entry is a language name (e.g. `"python"`, `"rust"`).
+   */
+  languages: Array<string>
+  /** Language groups to pre-download (e.g. `"web"`, `"systems"`, `"scripting"`). */
+  groups: Array<string>
+}
+
+export declare class JsParser {
+}
+
+/** Manifest describing available parser downloads for a specific version. */
+export interface JsParserManifest {
+  version: string
+  platforms: Record<string, JsPlatformBundle>
+  languages: Record<string, JsLanguageInfo>
+  groups: Record<string, Array<string>>
+}
+
+/** Results for a single named pattern. */
+export interface JsPatternResult {
+  /** The individual matches. */
+  matches: Array<JsMatchResult>
+  /** Total number of matches before `max_results` truncation. */
+  totalCount: number
+}
+
+/** Validation information for a single pattern. */
+export interface JsPatternValidation {
+  /** Whether the pattern compiled successfully. */
+  valid: boolean
+  /** Names of captures defined in the query. */
+  captureNames: Array<string>
+  /** Number of patterns in the query. */
+  patternCount: number
+  /** Non-fatal warnings (e.g., unused captures). */
+  warnings: Array<string>
+  /** Fatal errors (e.g., query syntax errors). */
+  errors: Array<string>
+}
+
+export interface JsPlatformBundle {
+  url: string
+  sha256: string
+  size: number
+}
 
 /**
- * Download specific languages by name.
+ * Configuration for the `process()` function.
+ *
+ * Controls which analysis features are enabled and whether chunking is performed.
+ *
+ * # Examples
  *
- * Returns the number of languages successfully downloaded.
- * Throws an error if download fails.
+ * ```
+ * use tree_sitter_language_pack::ProcessConfig;
+ *
+ * // Defaults: structure + imports + exports enabled
+ * let config = ProcessConfig::new("python");
+ *
+ * // With chunking
+ * let config = ProcessConfig::new("python").with_chunking(1000);
+ *
+ * // Everything enabled
+ * let config = ProcessConfig::new("python").all();
+ * ```
  */
-export declare function download(names: Array<string>): number;
+export interface JsProcessConfig {
+  /** Language name (required). */
+  language: string
+  /** Extract structural items (functions, classes, etc.). Default: true. */
+  structure: boolean
+  /** Extract import statements. Default: true. */
+  imports: boolean
+  /** Extract export statements. Default: true. */
+  exports: boolean
+  /** Extract comments. Default: false. */
+  comments: boolean
+  /** Extract docstrings. Default: false. */
+  docstrings: boolean
+  /** Extract symbol definitions. Default: false. */
+  symbols: boolean
+  /** Include parse diagnostics. Default: false. */
+  diagnostics: boolean
+  /** Maximum chunk size in bytes. `None` disables chunking. */
+  chunkMaxSize: number
+  /**
+   * Custom extraction patterns to run against the parsed tree.
+   * Keys become the keys in `ProcessResult::extractions`.
+   */
+  extractions: string
+}
 
 /**
- * Download all 170+ available languages from the remote manifest.
+ * Complete analysis result from processing a source file.
+ *
+ * Contains metrics, structural analysis, imports/exports, comments,
+ * docstrings, symbols, diagnostics, and optionally chunked code segments.
+ * Fields are populated based on the [`crate::ProcessConfig`] flags.
  *
- * Returns the number of languages successfully downloaded.
- * Throws an error if download fails.
+ * # Fields
+ *
+ * - `language` - The language used for parsing
+ * - `metrics` - Always computed: line counts, byte sizes, error counts
+ * - `structure` - Functions, classes, structs (when `config.structure = true`)
+ * - `imports` - Import statements (when `config.imports = true`)
+ * - `exports` - Export statements (when `config.exports = true`)
+ * - `comments` - Comments (when `config.comments = true`)
+ * - `docstrings` - Docstrings (when `config.docstrings = true`)
+ * - `symbols` - Symbol definitions (when `config.symbols = true`)
+ * - `diagnostics` - Parse errors (when `config.diagnostics = true`)
+ * - `chunks` - Chunked code segments (when `config.chunk_max_size` is set)
  */
-export declare function downloadAll(): number;
+export interface JsProcessResult {
+  language: string
+  metrics: JsFileMetrics
+  structure: Array<JsStructureItem>
+  imports: Array<JsImportInfo>
+  exports: Array<JsExportInfo>
+  comments: Array<JsCommentInfo>
+  docstrings: Array<JsDocstringInfo>
+  symbols: Array<JsSymbolInfo>
+  diagnostics: Array<JsDiagnostic>
+  chunks: Array<JsCodeChunk>
+  /** Results of custom extraction patterns (when `config.extractions` is set). */
+  extractions: string
+}
+
+/** A single match from a tree-sitter query, with captured nodes. */
+export interface JsQueryMatch {
+  /** The pattern index that matched (position in the query string). */
+  patternIndex: number
+  /** Captures: list of (capture_name, node_info) pairs. */
+  captures: Array<string>
+}
 
 /**
- * Get all languages that have been downloaded and cached locally.
+ * Byte and line/column range in source code.
  *
- * Returns an array of language names currently in the cache.
+ * Represents both byte offsets (for slicing) and human-readable line/column
+ * positions (for display and diagnostics).
  */
-export declare function downloadedLanguages(): Array<string>;
+export interface JsSpan {
+  startByte: number
+  endByte: number
+  startLine: number
+  startColumn: number
+  endLine: number
+  endColumn: number
+}
+
+/** A structural item (function, class, struct, etc.) in source code. */
+export interface JsStructureItem {
+  kind: JsStructureKind
+  name: string
+  visibility: string
+  span: JsSpan
+  children: Array<JsStructureItem>
+  decorators: Array<string>
+  docComment: string
+  signature: string
+  bodySpan: JsSpan
+}
 
 /**
- * Returns the raw TSLanguage pointer for interop with node-tree-sitter.
+ * The kind of structural item found in source code.
  *
- * Throws an error if the language is not found.
+ * Categorizes top-level and nested declarations such as functions, classes,
+ * structs, enums, traits, and more. Use [`Other`](StructureKind::Other) for
+ * language-specific constructs that do not fit a standard category.
  */
-export declare function getLanguagePtr(name: string): number;
+export declare enum JsStructureKind {
+  Function = "Function",
+  Method = "Method",
+  Class = "Class",
+  Struct = "Struct",
+  Interface = "Interface",
+  Enum = "Enum",
+  Module = "Module",
+  Trait = "Trait",
+  Impl = "Impl",
+  Namespace = "Namespace",
+  Other = "Other",
+}
 
-/** Checks whether a language with the given name is available. */
-export declare function hasLanguage(name: string): boolean;
+/** A symbol (variable, function, type, etc.) extracted from source code. */
+export interface JsSymbolInfo {
+  name: string
+  kind: JsSymbolKind
+  span: JsSpan
+  typeAnnotation: string
+  doc: string
+}
 
 /**
- * Initialize download system with configuration and pre-download all specified languages.
+ * The kind of a symbol definition found in source code.
  *
- * Throws an error if configuration or download fails.
+ * Categorizes symbol definitions such as variables, constants, functions,
+ * classes, types, interfaces, enums, and modules.
  */
-export declare function init(config?: JsPackConfig | undefined | null): void;
+export declare enum JsSymbolKind {
+  Variable = "Variable",
+  Constant = "Constant",
+  Function = "Function",
+  Class = "Class",
+  Type = "Type",
+  Interface = "Interface",
+  Enum = "Enum",
+  Module = "Module",
+  Other = "Other",
+}
 
-/** Configuration for download and cache management. */
-export interface JsPackConfig {
-	cacheDir?: string;
-	languages?: Array<string>;
-	groups?: Array<string>;
+export declare class JsTree {
 }
 
-/** Configuration for the `process` function. */
-export interface JsProcessConfig {
-	language: string;
-	structure?: boolean;
-	imports?: boolean;
-	exports?: boolean;
-	comments?: boolean;
-	docstrings?: boolean;
-	symbols?: boolean;
-	diagnostics?: boolean;
-	chunkMaxSize?: number;
-}
-
-/** Returns the number of available languages. */
-export declare function languageCount(): number;
+/** Validation results for an entire extraction config. */
+export interface JsValidationResult {
+  /** Whether all patterns are valid. */
+  valid: boolean
+  /** Per-pattern validation details. */
+  patterns: string
+}
 
 /**
- * Get all available languages from the remote manifest.
+ * Return the number of available languages.
+ *
+ * Includes statically compiled languages, dynamically loadable languages,
+ * and aliases.
  *
- * Returns an array of language names. Throws an error if manifest fetch fails.
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::language_count;
+ *
+ * let count = language_count();
+ * println!("{} languages available", count);
+ * ```
  */
-export declare function manifestLanguages(): Array<string>;
+export declare function languageCount(): number;
 
 /**
- * Parse a source string using the named language and return an opaque tree handle.
+ * Return all language names available in the remote manifest (305).
  *
- * Throws an error if the language is not found or parsing fails.
+ * Fetches (and caches) the remote manifest to discover the full list of
+ * downloadable languages. Use [`downloaded_languages`] to list what is
+ * already cached locally.
+ *
+ * # Errors
+ *
+ * Returns an error if the manifest cannot be fetched.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::manifest_languages;
+ *
+ * let langs = manifest_languages().unwrap();
+ * println!("{} languages available for download", langs.len());
+ * ```
  */
-export declare function parseString(language: string, source: string): ExternalObject<Tree>;
+export declare function manifestLanguages(): Array<string>;
 
 /**
- * Process source code using a config and return a result object with metadata and chunks.
+ * Get `NodeInfo` for all named children of the root node.
  *
- * Accepts both camelCase and snake_case config keys (auto-normalized to snake_case).
- * Returns camelCase keys in the result for JavaScript convention.
+ * Useful for understanding the top-level structure of a file
+ * (e.g., list of function definitions, class declarations, imports).
  */
-export declare function process(source: string, config: JsProcessConfig): ProcessResult;
-
-/** Check whether any node in the tree has the given type name. */
-export declare function treeContainsNodeType(tree: ExternalObject<Tree>, nodeType: string): boolean;
-
-/** Check whether the tree contains any ERROR or MISSING nodes. */
-export declare function treeHasErrorNodes(tree: ExternalObject<Tree>): boolean;
-
-/** Get the number of named children of the root node. */
-export declare function treeRootChildCount(tree: ExternalObject<Tree>): number;
-
-/** Get the type name of the root node. */
-export declare function treeRootNodeType(tree: ExternalObject<Tree>): string;
+export declare function namedChildrenInfo(tree: JsTree): Array<JsNodeInfo>;
 
 /**
- * Detect language from source content using heuristics.
+ * Parse source code with the named language, returning the syntax tree.
+ *
+ * Uses the global registry to look up the language by name.
+ * Caches parsers per-thread so repeated calls for the same language avoid
+ * re-creating the parser.
  *
- * Returns the detected language name, or null if detection fails.
+ * # Examples
+ *
+ * ```no_run
+ * let tree = tree_sitter_language_pack::parse_string("python", b"def hello(): pass").unwrap();
+ * assert_eq!(tree.root_node().kind(), "module");
+ * ```
  */
-export declare function detectLanguageFromContent(content: string): string | null;
+export declare function parseString(language: string, source: Uint8Array): JsTree;
 
 /**
- * Detect language from a file path or extension.
+ * Process source code and extract file intelligence using the global registry.
+ *
+ * Parses the source with tree-sitter and extracts metrics, structure, imports,
+ * exports, comments, docstrings, symbols, diagnostics, and/or chunks based on
+ * the flags set in [`ProcessConfig`].
+ *
+ * # Errors
+ *
+ * Returns an error if the language is not found or parsing fails.
+ *
+ * # Example
+ *
+ * ```no_run
+ * use tree_sitter_language_pack::{ProcessConfig, process};
  *
- * Returns the detected language name, or null if detection fails.
+ * let config = ProcessConfig::new("python").all();
+ * let result = process("def hello(): pass", &config).unwrap();
+ * println!("Language: {}", result.language);
+ * println!("Lines: {}", result.metrics.total_lines);
+ * println!("Structures: {}", result.structure.len());
+ * ```
  */
-export declare function detectLanguage(path: string): string | null;
+export declare function process(source: string, config: JsProcessConfig): JsProcessResult;
+
+/** Get a `NodeInfo` snapshot of the root node. */
+export declare function rootNodeInfo(tree: JsTree): JsNodeInfo;
 
 /**
- * Detect language from a bare file extension (without leading dot).
+ * Execute a tree-sitter query pattern against a parsed tree.
+ *
+ * The `query_source` is an S-expression pattern like:
+ * ```text
+ * (function_definition name: (identifier) @name)
+ * ```
+ *
+ * Returns all matches with their captured nodes.
+ *
+ * # Arguments
  *
- * Returns the detected language name, or null if detection fails.
+ * * `tree` - The parsed syntax tree to query.
+ * * `language` - Language name (used to compile the query pattern).
+ * * `query_source` - The tree-sitter query pattern string.
+ * * `source` - The original source code bytes (needed for capture resolution).
+ *
+ * # Examples
+ *
+ * ```no_run
+ * let tree = tree_sitter_language_pack::parse_string("python", b"def hello(): pass").unwrap();
+ * let matches = tree_sitter_language_pack::run_query(
+ * &tree,
+ * "python",
+ * "(function_definition name: (identifier) @fn_name)",
+ * b"def hello(): pass",
+ * ).unwrap();
+ * assert!(!matches.is_empty());
+ * ```
  */
-export declare function detectLanguageFromExtension(ext: string): string | null;
+export declare function runQuery(tree: JsTree, language: string, querySource: string, source: Uint8Array): Array<JsQueryMatch>;
 
 /**
- * Detect language from a file path based on its extension.
+ * Check whether any node in the tree matches the given type name.
  *
- * Returns the detected language name, or null if detection fails.
+ * Performs a depth-first traversal using `TreeCursor`.
  */
-export declare function detectLanguageFromPath(path: string): string | null;
+export declare function treeContainsNodeType(tree: JsTree, nodeType: string): boolean;
 
 /**
- * Resolve ambiguity for a file extension that maps to multiple languages.
+ * Count the number of ERROR and MISSING nodes in the tree.
  *
- * Returns the assigned language and alternatives, or null if no ambiguity exists.
+ * Returns 0 for a clean parse.
  */
-export declare function extensionAmbiguity(ext: string): AmbiguityResult | null;
+export declare function treeErrorCount(tree: JsTree): number;
 
 /**
- * Get the highlights query string for a language.
+ * Check whether the tree contains any ERROR or MISSING nodes.
  *
- * Returns the query source, or null if no highlights query is available.
+ * Useful for determining if the parse was clean or had syntax errors.
  */
-export declare function getHighlightsQuery(language: string): string | null;
+export declare function treeHasErrorNodes(tree: JsTree): boolean;
 
 /**
- * Get the injections query string for a language.
+ * Return the S-expression representation of the entire tree.
  *
- * Returns the query source, or null if no injections query is available.
+ * This is the standard tree-sitter debug format, useful for logging,
+ * snapshot testing, and debugging grammars.
  */
-export declare function getInjectionsQuery(language: string): string | null;
+export declare function treeToSexp(tree: JsTree): string;
 
 /**
- * Get the locals query string for a language.
+ * Validate extraction patterns without running them.
+ *
+ * Convenience wrapper around [`extract::validate_extraction`].
+ *
+ * # Errors
  *
- * Returns the query source, or null if no locals query is available.
+ * Returns an error if the language cannot be loaded.
  */
-export declare function getLocalsQuery(language: string): string | null;
+export declare function validateExtraction(config: JsExtractionConfig): JsValidationResult;