@kreuzberg/tree-sitter-language-pack 1.8.0 → 1.9.0-rc.1

package/README.md

@@ -0,0 +1,189 @@
+# TypeScript / Node.js
+
+<div
+  align="center"
+  style="display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin: 20px 0"
+>
+  <a href="https://github.com/kreuzberg-dev/alef">
+    <img
+      src="https://img.shields.io/badge/Bindings-alef%20%D7%90-007ec6"
+      alt="Bindings"
+    />
+  </a>
+  <!-- Language Bindings -->
+  <a href="https://crates.io/crates/tree-sitter-language-pack">
+    <img
+      src="https://img.shields.io/crates/v/tree-sitter-language-pack?label=Rust&color=007ec6"
+      alt="Rust"
+    />
+  </a>
+  <a href="https://pypi.org/project/tree-sitter-language-pack/">
+    <img
+      src="https://img.shields.io/pypi/v/tree-sitter-language-pack?label=Python&color=007ec6"
+      alt="Python"
+    />
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/tree-sitter-language-pack">
+    <img
+      src="https://img.shields.io/npm/v/@kreuzberg/tree-sitter-language-pack?label=Node.js&color=007ec6"
+      alt="Node.js"
+    />
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/tree-sitter-language-pack-wasm">
+    <img
+      src="https://img.shields.io/npm/v/@kreuzberg/tree-sitter-language-pack-wasm?label=WASM&color=007ec6"
+      alt="WASM"
+    />
+  </a>
+  <a
+    href="https://central.sonatype.com/artifact/dev.kreuzberg.treesitterlanguagepack/tree-sitter-language-pack"
+  >
+    <img
+      src="https://img.shields.io/maven-central/v/dev.kreuzberg.treesitterlanguagepack/tree-sitter-language-pack?label=Java&color=007ec6"
+      alt="Java"
+    />
+  </a>
+  <a href="https://pkg.go.dev/github.com/kreuzberg-dev/tree-sitter-language-pack/packages/go">
+    <img
+      src="https://img.shields.io/github/v/tag/kreuzberg-dev/tree-sitter-language-pack?label=Go&color=007ec6"
+      alt="Go"
+    />
+  </a>
+  <a href="https://www.nuget.org/packages/TreeSitterLanguagePack/">
+    <img
+      src="https://img.shields.io/nuget/v/TreeSitterLanguagePack?label=C%23&color=007ec6"
+      alt="C#"
+    />
+  </a>
+  <a href="https://packagist.org/packages/kreuzberg/tree-sitter-language-pack">
+    <img
+      src="https://img.shields.io/packagist/v/kreuzberg/tree-sitter-language-pack?label=PHP&color=007ec6"
+      alt="PHP"
+    />
+  </a>
+  <a href="https://rubygems.org/gems/tree_sitter_language_pack">
+    <img
+      src="https://img.shields.io/gem/v/tree_sitter_language_pack?label=Ruby&color=007ec6"
+      alt="Ruby"
+    />
+  </a>
+  <a href="https://hex.pm/packages/tree_sitter_language_pack">
+    <img
+      src="https://img.shields.io/hexpm/v/tree_sitter_language_pack?label=Elixir&color=007ec6"
+      alt="Elixir"
+    />
+  </a>
+  <a href="https://pub.dev/packages/tree_sitter_language_pack">
+    <img
+      src="https://img.shields.io/pub/v/tree_sitter_language_pack?label=Dart&color=007ec6"
+      alt="Dart"
+    />
+  </a>
+  <a
+    href="https://central.sonatype.com/artifact/dev.kreuzberg.tslp.android/tree-sitter-language-pack-android"
+  >
+    <img
+      src="https://img.shields.io/maven-central/v/dev.kreuzberg.tslp.android/tree-sitter-language-pack-android?label=Kotlin&color=007ec6"
+      alt="Kotlin"
+    />
+  </a>
+  <a href="https://github.com/kreuzberg-dev/tree-sitter-language-pack/tree/main/packages/swift">
+    <img src="https://img.shields.io/badge/Swift-SPM-007ec6" alt="Swift" />
+  </a>
+  <a href="https://github.com/kreuzberg-dev/tree-sitter-language-pack/tree/main/packages/zig">
+    <img src="https://img.shields.io/badge/Zig-package-007ec6" alt="Zig" />
+  </a>
+  <a href="https://github.com/kreuzberg-dev/tree-sitter-language-pack/releases">
+    <img src="https://img.shields.io/badge/C-FFI-007ec6" alt="C FFI" />
+  </a>
+
+  <!-- Project Info -->
+  <a href="https://github.com/kreuzberg-dev/tree-sitter-language-pack/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-007ec6" alt="License" />
+  </a>
+  <a href="https://docs.tree-sitter-language-pack.kreuzberg.dev">
+    <img src="https://img.shields.io/badge/Docs-tree--sitter--language--pack-007ec6" alt="Documentation" />
+  </a>
+</div>
+
+<div align="center" style="margin: 24px 0 0">
+  <a href="https://kreuzberg.dev">
+    <img alt="tree-sitter-language-pack" src="https:&#x2f;&#x2f;github.com&#x2f;user-attachments&#x2f;assets&#x2f;478a83da-237b-446b-b3a8-e564c13e00a8" />
+  </a>
+</div>
+
+<div
+  align="center"
+  style="display: flex; flex-wrap: wrap; gap: 12px; justify-content: center; margin: 28px 0 24px"
+>
+  <a href="https://discord.gg/xt9WY3GnKR">
+    <img
+      height="22"
+      src="https://img.shields.io/badge/Discord-Chat-007ec6?logo=discord&logoColor=white"
+      alt="Join Discord"
+    />
+  </a>
+</div>
+
+Pre-compiled tree-sitter grammars for 305 programming languages with TypeScript types.
+
+## What This Package Provides
+
+- **Parser access** — load a tree-sitter language parser by name without wiring individual grammar crates or packages.
+- **Code intelligence primitives** — parse trees, functions, classes, imports, exports, symbols, docstrings, diagnostics, and syntax-aware chunks.
+- **Shared cache model** — parsers are fetched and cached once, then reused by every call in the process.
+- **Same catalog as every binding** — Rust, Python, Node.js, Go, Java, PHP, Ruby, .NET, Elixir, WASM, Dart, Kotlin Android, Swift, Zig, and C FFI use the same grammar set.
+- **Node-first TypeScript API** — native NAPI package with typed parser and query helpers.
+
+## Installation
+
+
+```bash
+npm install @kreuzberg/tree-sitter-language-pack
+```
+
+
+## Quick Start
+
+
+```typescript
+import { getParser } from "@kreuzberg/tree-sitter-language-pack";
+
+const parser = getParser("python");
+const tree = parser.parse("def hello(): pass");
+console.log(tree.rootNode.toString());
+```
+
+
+## Features
+
+- **300+ languages** — pre-compiled tree-sitter grammars covering every major programming language and many minor ones.
+- **On-demand download + cache** — parsers fetched at first use; subsequent runs hit the local cache.
+- **Code intelligence** — extract functions, classes, imports, exports, symbols, docstrings, and diagnostics with one API.
+- **Syntax-aware chunking** — semantic chunks for RAG/LLM pipelines.
+- **Polyglot bindings** — Rust core with native bindings for Python, TypeScript, Go, Java, C#, Ruby, PHP, Elixir, and WebAssembly via [alef](https://github.com/kreuzberg-dev/alef).
+
+## Documentation
+
+- **[Documentation](https://docs.tree-sitter-language-pack.kreuzberg.dev)** -- Full docs and API reference
+- **[GitHub Repository](https://github.com/kreuzberg-dev/tree-sitter-language-pack)** -- Source, issues, and discussions
+
+## Part of Kreuzberg.dev
+
+- [Kreuzberg](https://github.com/kreuzberg-dev/kreuzberg) — document intelligence: text, tables, metadata from 90+ formats with optional OCR.
+- [Kreuzberg Cloud](https://github.com/kreuzberg-dev/kreuzberg-cloud) — managed extraction API with SDKs, dashboards, and observability.
+- [kreuzcrawl](https://github.com/kreuzberg-dev/kreuzcrawl) — web crawling and scraping with HTML→Markdown and headless-Chrome fallback.
+- [html-to-markdown](https://github.com/kreuzberg-dev/html-to-markdown) — fast, lossless HTML→Markdown engine.
+- [liter-llm](https://github.com/kreuzberg-dev/liter-llm) — universal LLM API client with native bindings for 14 languages and 143 providers.
+- [alef](https://github.com/kreuzberg-dev/alef) — the polyglot binding generator that produces this README and all per-language bindings.
+- [Discord](https://discord.gg/xt9WY3GnKR) — community, roadmap, announcements.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](https://github.com/kreuzberg-dev/tree-sitter-language-pack/blob/main/CONTRIBUTING.md) for guidelines.
+
+Join our [Discord community](https://discord.gg/xt9WY3GnKR) for questions and discussion.
+
+## License
+
+MIT -- see [LICENSE](https://github.com/kreuzberg-dev/tree-sitter-language-pack/blob/main/LICENSE) for details.

package/index.d.ts

@@ -1,24 +1,24 @@
 // This file is auto-generated by alef — DO NOT EDIT.
-// alef:hash:7c65820ecd6e48e089b65d0938339ac51a03bd08db1e74ea026cec7d9171c313
+// alef:hash:eb942221e8ed2406fb12063e817b0beb5a7403bb320401b3280c538e2b34e217
 // To regenerate: alef generate
 // To verify freshness: alef verify --exit-code
 // Issues & docs: https://github.com/kreuzberg-dev/alef
 /* eslint-disable */
+import type { Language } from "tree-sitter";
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
 
 /**
  * List all available language names (sorted, deduplicated, includes aliases).
  *
  * Returns names of both statically compiled and dynamically loadable languages,
  * plus any configured aliases.
- * @example
- * ```typescript
- * use tree_sitter_language_pack::available_languages;
- *
- * let langs = available_languages();
- * for name in &langs {
- *     println!("{}", name);
- * }
- * ```typescript
  */
 export declare function availableLanguages(): Array<string>;
 
@@ -28,14 +28,6 @@ export declare function availableLanguages(): Array<string>;
  * This is either the custom path set via [`configure`] / [`init`] or the
  * default: `~/.cache/tree-sitter-language-pack/v{version}/libs/`.
  * @throws Returns an error if the system cache directory cannot be determined.
- *
- * @example
- * ```typescript
- * use tree_sitter_language_pack::cache_dir;
- *
- * let dir = cache_dir().unwrap();
- * println!("Cache directory: {dir}");
- * ```typescript
  */
 export declare function cacheDir(): string;
 
@@ -45,14 +37,6 @@ export declare function cacheDir(): string;
  * Resets the cache registration so the next call to [`get_language`] or
  * a download function will re-register the (now empty) cache directory.
  * @throws Returns an error if the cache directory cannot be removed.
- *
- * @example
- * ```typescript
- * use tree_sitter_language_pack::clean_cache;
- *
- * clean_cache().unwrap();
- * println!("Cache cleared");
- * ```typescript
  */
 export declare function cleanCache(): void;
 
@@ -64,28 +48,15 @@ export declare function cleanCache(): void;
  * after languages have been registered has no effect on already-loaded
  * languages.
  * @throws Returns an error if the lock cannot be acquired.
- *
- * @example
- * ```typescript
- * 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();
- * ```typescript
  */
-export declare function configure(config: JsPackConfig): void;
+export declare function configure(config: PackConfig): void;
 
 /**
  * Detect language name from a file path or extension.
  *
  * This compatibility alias matches the pre-Alef Python binding API.
  */
-export declare function detectLanguage(path: string): string | undefined | null;
+export declare function detectLanguage(path: string): string | null;
 
 /**
  * Detect language name from file content using the shebang line (`#!`).
@@ -111,7 +82,7 @@ export declare function detectLanguage(path: string): string | undefined | null;
  * assert_eq!(detect_language_from_content("no shebang here"), None);
  * ```
  */
-export declare function detectLanguageFromContent(content: string): string | undefined | null;
+export declare function detectLanguageFromContent(content: string): string | null;
 
 /**
  * Detect language name from a file extension (without leading dot).
@@ -125,7 +96,7 @@ export declare function detectLanguageFromContent(content: string): string | und
  * assert_eq!(detect_language_from_extension("xyz"), None);
  * ```
  */
-export declare function detectLanguageFromExtension(ext: string): string | undefined | null;
+export declare function detectLanguageFromExtension(ext: string): string | null;
 
 /**
  * Detect language name from a file path.
@@ -140,7 +111,7 @@ export declare function detectLanguageFromExtension(ext: string): string | undef
  * assert_eq!(detect_language_from_path("Makefile"), None);
  * ```
  */
-export declare function detectLanguageFromPath(path: string): string | undefined | null;
+export declare function detectLanguageFromPath(path: string): string | null;
 
 /**
  * Download specific languages to the local cache.
@@ -149,14 +120,6 @@ export declare function detectLanguageFromPath(path: string): string | undefined
  * compiled or cached languages are included in the count.
  * @throws Returns an error if any language is not available in the manifest or if
  * the download fails.
- *
- * @example
- * ```typescript
- * use tree_sitter_language_pack::download;
- *
- * let count = download(&["python", "rust", "typescript"]).unwrap();
- * println!("Ensured {} languages", count);
- * ```typescript
  */
 export declare function download(names: Array<string>): number;
 
@@ -171,14 +134,6 @@ export declare function download(names: Array<string>): number;
  * Returns the total number of languages now available (statically compiled
  * plus downloaded and cached).
  * @throws Returns an error if the manifest cannot be fetched or the bundle download fails.
- *
- * @example
- * ```typescript
- * use tree_sitter_language_pack::download_all;
- *
- * let count = download_all().unwrap();
- * println!("{} languages available", count);
- * ```typescript
  */
 export declare function downloadAll(): number;
 
@@ -187,50 +142,38 @@ export declare function downloadAll(): number;
  *
  * Does not perform any network requests. Returns an empty list if the
  * cache directory does not exist or cannot be read.
- * @example
- * ```typescript
- * use tree_sitter_language_pack::downloaded_languages;
- *
- * let langs = downloaded_languages();
- * println!("{} languages already cached", langs.len());
- * ```typescript
  */
 export declare function downloadedLanguages(): Array<string>;
 
+/**
+ * Download every language in a named group (e.g. `"web"`, `"data"`).
+ *
+ * Groups are defined in the remote manifest and let you ensure a curated
+ * set of related grammars in one call instead of listing each name to
+ * [`download`]. Already-cached languages are skipped.
+ *
+ * Returns the total number of languages now available (statically compiled
+ * plus downloaded and cached).
+ * @throws Returns an error if the manifest cannot be fetched, the group is unknown,
+ * or any constituent language fails to download.
+ */
+export declare function downloadGroup(name: string): number;
+
 /**
  * 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
- * ```typescript
- * 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());
- * ```typescript
  */
-export declare function getHighlightsQuery(language: string): string | undefined | null;
+export declare function getHighlightsQuery(language: string): string | 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
- * ```typescript
- * 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());
- * ```typescript
  */
-export declare function getInjectionsQuery(language: string): string | undefined | null;
+export declare function getInjectionsQuery(language: string): string | null;
 
 /**
  * Get a tree-sitter [`Language`] by name using the global registry.
@@ -240,70 +183,32 @@ export declare function getInjectionsQuery(language: string): string | undefined
  * the parser from GitHub releases if not found locally.
  * @throws Returns [`Error::LanguageNotFound`] if the language is not recognized,
  * or [`Error::Download`] if auto-download fails.
- *
- * @example
- * ```typescript
- * 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");
- * ```typescript
  */
-export declare function getLanguage(name: string): JsLanguage;
+export declare function getLanguage(name: string): Language;
 
 /**
  * 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
- * ```typescript
- * 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());
- * ```typescript
  */
-export declare function getLocalsQuery(language: string): string | undefined | null;
+export declare function getLocalsQuery(language: string): string | null;
 
 /**
- * Get a tree-sitter [`Parser`] pre-configured for the given language.
+ * Get a [`Parser`] pre-configured for the given language.
  *
  * This is a convenience function that calls [`get_language`] and configures
  * a new parser in one step.
  * @throws Returns [`Error::LanguageNotFound`] if the language is not recognized, or
  * [`Error::ParserSetup`] if the language cannot be applied to the parser.
- *
- * @example
- * ```typescript
- * 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());
- * ```typescript
  */
-export declare function getParser(name: string): JsParser;
+export declare function getParser(name: string): Parser;
 
 /**
  * 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
- * ```typescript
- * use tree_sitter_language_pack::has_language;
- *
- * assert!(has_language("python"));
- * assert!(has_language("shell")); // alias for "bash"
- * assert!(!has_language("nonexistent_language"));
- * ```typescript
  */
 export declare function hasLanguage(name: string): boolean;
 
@@ -314,50 +219,46 @@ export declare function hasLanguage(name: string): boolean;
  * specified in the config. This is the recommended entry point when you want
  * to pre-warm the cache before use.
  * @throws Returns an error if configuration cannot be applied or if downloads fail.
- *
- * @example
- * ```typescript
- * 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();
- * ```typescript
  */
-export declare function init(config: JsPackConfig): void;
+export declare function init(config: PackConfig): void;
+
+/** A byte range — start (inclusive) to end (exclusive). */
+export interface ByteRange {
+  /** Inclusive start byte offset. */
+  readonly start: number;
+  /** Exclusive end byte offset. */
+  readonly end: number;
+}
 
 /** 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;
+export interface ChunkContext {
+  readonly language?: string;
+  readonly chunkIndex?: number;
+  readonly totalChunks?: number;
+  readonly nodeTypes?: Array<string>;
+  readonly contextPath?: Array<string>;
+  readonly symbolsDefined?: Array<string>;
+  readonly comments?: Array<CommentInfo>;
+  readonly docstrings?: Array<DocstringInfo>;
+  readonly hasErrorNodes?: boolean;
 }
 
 /** A chunk of source code with rich metadata. */
-export interface JsCodeChunk {
-  content?: string;
-  startByte?: number;
-  endByte?: number;
-  startLine?: number;
-  endLine?: number;
-  metadata?: JsChunkContext;
+export interface CodeChunk {
+  readonly content?: string;
+  readonly startByte?: number;
+  readonly endByte?: number;
+  readonly startLine?: number;
+  readonly endLine?: number;
+  readonly metadata?: ChunkContext;
 }
 
 /** A comment extracted from source code. */
-export interface JsCommentInfo {
-  text?: string;
-  kind?: JsCommentKind;
-  span?: JsSpan;
-  associatedNode?: string;
+export interface CommentInfo {
+  readonly text?: string;
+  readonly kind?: CommentKind;
+  readonly span?: Span;
+  readonly associatedNode?: string;
 }
 
 /**
@@ -366,17 +267,17 @@ export interface JsCommentInfo {
  * Distinguishes between single-line comments, block (multi-line) comments,
  * and documentation comments.
  */
-export declare enum JsCommentKind {
+export declare enum CommentKind {
   Line = "Line",
   Block = "Block",
   Doc = "Doc",
 }
 
 /** A diagnostic (syntax error, missing node, etc.) from parsing. */
-export interface JsDiagnostic {
-  message?: string;
-  severity?: JsDiagnosticSeverity;
-  span?: JsSpan;
+export interface Diagnostic {
+  readonly message?: string;
+  readonly severity?: DiagnosticSeverity;
+  readonly span?: Span;
 }
 
 /**
@@ -385,17 +286,17 @@ export interface JsDiagnostic {
  * Used to classify parse errors, warnings, and informational messages
  * found in the syntax tree.
  */
-export declare enum JsDiagnosticSeverity {
+export declare enum DiagnosticSeverity {
   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;
+export interface DocSection {
+  readonly kind?: string;
+  readonly name?: string;
+  readonly description?: string;
 }
 
 /**
@@ -404,7 +305,7 @@ export interface JsDocSection {
  * Identifies the docstring convention used, which varies by language
  * (e.g., Python triple-quoted strings, JSDoc, Rustdoc `///` comments).
  */
-export declare enum JsDocstringFormat {
+export declare enum DocstringFormat {
   PythonTripleQuote = "PythonTripleQuote",
   JSDoc = "JSDoc",
   Rustdoc = "Rustdoc",
@@ -414,37 +315,22 @@ export declare enum JsDocstringFormat {
 }
 
 /** A docstring extracted from source code. */
-export interface JsDocstringInfo {
-  text?: string;
-  format?: JsDocstringFormat;
-  span?: JsSpan;
-  associatedItem?: string;
-  parsedSections?: Array<JsDocSection>;
+export interface DocstringInfo {
+  readonly text?: string;
+  readonly format?: DocstringFormat;
+  readonly span?: Span;
+  readonly associatedItem?: string;
+  readonly parsedSections?: Array<DocSection>;
 }
 
 /** Manages downloading and caching of pre-built parser shared libraries. */
-export declare class JsDownloadManager {
+export declare class DownloadManager {
   /** Create a new download manager for the given version. */
-  static new(version: string): JsDownloadManager;
+  static new(version: string): DownloadManager;
   /** 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;
+  static withCacheDir(version: string, cacheDir: string): DownloadManager;
   /** 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;
   /**
    * Download the platform bundle and extract every library file it contains.
    *
@@ -456,15 +342,24 @@ export declare class JsDownloadManager {
    * Returns the number of library files extracted (including those already cached).
    */
   downloadAllBestEffort(): number;
-  /** Remove all cached parser libraries. */
+  /**
+   * Remove all cached parser libraries.
+   *
+   * Acquires the cross-process lock so `clean_cache` cannot race a concurrent
+   * downloader (avoids Windows sharing-violation errors against an in-flight
+   * bundle write). The `.download.lock` file itself is **not** removed — it is
+   * permanent infrastructure; deleting it could allow a concurrent process that
+   * already opened the file to continue holding a stale lock handle while a new
+   * process opens a fresh inode, breaking the mutual-exclusion guarantee.
+   */
   cleanCache(): void;
 }
 
 /** An export statement extracted from source code. */
-export interface JsExportInfo {
-  name?: string;
-  kind?: JsExportKind;
-  span?: JsSpan;
+export interface ExportInfo {
+  readonly name?: string;
+  readonly kind?: ExportKind;
+  readonly span?: Span;
 }
 
 /**
@@ -472,38 +367,31 @@ export interface JsExportInfo {
  *
  * Covers named exports, default exports, and re-exports from other modules.
  */
-export declare enum JsExportKind {
+export declare enum ExportKind {
   Named = "Named",
   Default = "Default",
   ReExport = "ReExport",
 }
 
 /** 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;
+export interface FileMetrics {
+  readonly totalLines?: number;
+  readonly codeLines?: number;
+  readonly commentLines?: number;
+  readonly blankLines?: number;
+  readonly totalBytes?: number;
+  readonly nodeCount?: number;
+  readonly errorCount?: number;
+  readonly maxDepth?: number;
 }
 
 /** An import statement extracted from source code. */
-export interface JsImportInfo {
-  source?: string;
-  items?: Array<string>;
-  alias?: string;
-  isWildcard?: boolean;
-  span?: JsSpan;
-}
-
-export declare class JsLanguage {}
-
-export interface JsLanguageInfo {
-  group: string;
-  size: number;
+export interface ImportInfo {
+  readonly source?: string;
+  readonly items?: Array<string>;
+  readonly alias?: string;
+  readonly isWildcard?: boolean;
+  readonly span?: Span;
 }
 
 /**
@@ -513,39 +401,8 @@ export interface JsLanguageInfo {
  * Use [`LanguageRegistry::new()`] for the default registry, or access the
  * global instance via the module-level convenience functions
  * (`get_language`, `available_languages`, etc.).
- * @example
- * ```typescript
- * use tree_sitter_language_pack::{LanguageRegistry, ProcessConfig};
- *
- * 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);
- * ```typescript
  */
-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;
+export declare class LanguageRegistry {
   /**
    * Get a tree-sitter [`Language`] by name.
    *
@@ -555,7 +412,7 @@ export declare class JsLanguageRegistry {
    * @throws Returns [`Error::LanguageNotFound`] if the name (after alias resolution)
    * does not match any known grammar.
    */
-  getLanguage(name: string): JsLanguage;
+  getLanguage(name: string): Language;
   /**
    * List all available language names, sorted and deduplicated.
    *
@@ -573,8 +430,69 @@ export declare class JsLanguageRegistry {
   /** 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;
+  process(source: string, config: ProcessConfig): ProcessResult;
+  static default(): LanguageRegistry;
+}
+
+/**
+ * A single syntax node within a [`Tree`].
+ *
+ * Nodes hold a strong reference to their parent tree so they remain valid
+ * regardless of how the tree is moved or stored at the FFI boundary.
+ */
+export declare class Node {
+  clone(): Node;
+  /** Return the node's kind name (e.g. `"function_definition"`). */
+  kind(): string;
+  /**
+   * Return the node's numeric kind ID.
+   *
+   * Tree-sitter assigns a stable `u16` ID to every node kind in a grammar
+   * (e.g. `"function_definition" → 42`). Comparing `kind_id()` is cheaper
+   * than comparing the string [`kind()`](Self::kind) in tight AST loops.
+   */
+  kindId(): number;
+  /** Return the inclusive start byte offset of this node. */
+  startByte(): number;
+  /** Return the exclusive end byte offset of this node. */
+  endByte(): number;
+  /**
+   * Return the node's byte range as a [`ByteRange`].
+   *
+   * Callers should slice their own source bytes — this is a zero-copy
+   * text accessor.
+   */
+  byteRange(): ByteRange;
+  /** Return the start [`Point`] (row, column). */
+  startPosition(): Point;
+  /** Return the end [`Point`] (row, column). */
+  endPosition(): Point;
+  /** True when this node is named (not punctuation/whitespace). */
+  isNamed(): boolean;
+  /** True when this is an error node. */
+  isError(): boolean;
+  /** True when this is a missing-token node. */
+  isMissing(): boolean;
+  /** True when this is an "extra" node (e.g. a comment). */
+  isExtra(): boolean;
+  /** True when this node or any descendant is an error. */
+  hasError(): boolean;
+  /** Return this node's parent, if any. */
+  parent(): Node | null;
+  /** Return the i-th child of this node, if any. */
+  child(index: number): Node | null;
+  /** Total number of children (including unnamed). */
+  childCount(): number;
+  /** Return the i-th named child of this node, if any. */
+  namedChild(index: number): Node | null;
+  /** Number of named children of this node. */
+  namedChildCount(): number;
+  /** Look up a child by its grammar-defined field name. */
+  childByFieldName(name: string): Node | null;
+  /** Return the S-expression form of this node's subtree. */
+  toSexp(): string;
+  /** Return a [`TreeCursor`] positioned at this node. */
+  walk(): TreeCursor;
 }
 
 /**
@@ -583,87 +501,85 @@ export declare class JsLanguageRegistry {
  * 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.
- * @example
- * ```typescript
- * use tree_sitter_language_pack::PackConfig;
- *
- * let config = PackConfig {
- *     cache_dir: None,
- *     languages: Some(vec!["python".to_string(), "rust".to_string()]),
- *     groups: None,
- * };
- * ```typescript
- */
-export interface JsPackConfig {
+ */
+export interface PackConfig {
   /**
    * Override default cache directory.
    *
    * Default: `~/.cache/tree-sitter-language-pack/v{version}/libs/`
    */
-  cacheDir?: string;
+  readonly cacheDir?: string;
   /**
    * Languages to pre-download on init.
    *
    * Each entry is a language name (e.g. `"python"`, `"rust"`).
    */
-  languages?: Array<string>;
+  readonly languages?: Array<string>;
   /** Language groups to pre-download (e.g. `"web"`, `"systems"`, `"scripting"`). */
-  groups?: Array<string>;
+  readonly 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>>;
+/** A tree-sitter parser configured for one language at a time. */
+export declare class Parser {
+  /**
+   * Configure the parser to use the language identified by name (e.g. `"python"`).
+   *
+   * Resolves the language through the global registry — auto-downloading
+   * if necessary, when the `download` feature is enabled.
+   * @throws Returns [`Error::LanguageNotFound`] if the language is not recognized,
+   * or [`Error::ParserSetup`] if the language ABI is incompatible.
+   */
+  setLanguage(name: string): void;
+  /**
+   * Parse a UTF-8 source string. Returns `None` if parsing was cancelled
+   * or no language is set.
+   */
+  parse(source: string): Tree | null;
+  /**
+   * Parse a raw byte slice. Returns `None` if parsing was cancelled or
+   * no language is set.
+   */
+  parseBytes(source: Uint8Array): Tree | null;
+  /**
+   * Reset internal state. The next call to [`parse`](Self::parse) will
+   * not be incremental.
+   */
+  reset(): void;
+  static default(): Parser;
 }
 
-export interface JsPlatformBundle {
-  url: string;
-  sha256: string;
-  size: number;
+/** A source position — row + column, zero-indexed. */
+export interface Point {
+  /** Zero-indexed row number. */
+  readonly row: number;
+  /** Zero-indexed column number, in UTF-16 code units. */
+  readonly column: number;
 }
 
 /**
  * Configuration for the `process()` function.
  *
  * Controls which analysis features are enabled and whether chunking is performed.
- * @example
- * ```typescript
- * 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();
- * ```typescript
  */
-export interface JsProcessConfig {
+export interface ProcessConfig {
   /** Language name (required). */
-  language?: string;
+  readonly language?: string;
   /** Extract structural items (functions, classes, etc.). Default: true. */
-  structure?: boolean;
+  readonly structure?: boolean;
   /** Extract import statements. Default: true. */
-  imports?: boolean;
+  readonly imports?: boolean;
   /** Extract export statements. Default: true. */
-  exports?: boolean;
+  readonly exports?: boolean;
   /** Extract comments. Default: false. */
-  comments?: boolean;
+  readonly comments?: boolean;
   /** Extract docstrings. Default: false. */
-  docstrings?: boolean;
+  readonly docstrings?: boolean;
   /** Extract symbol definitions. Default: false. */
-  symbols?: boolean;
+  readonly symbols?: boolean;
   /** Include parse diagnostics. Default: false. */
-  diagnostics?: boolean;
+  readonly diagnostics?: boolean;
   /** Maximum chunk size in bytes. `None` disables chunking. */
-  chunkMaxSize?: number;
+  readonly chunkMaxSize?: number;
 }
 
 /**
@@ -686,17 +602,17 @@ export interface JsProcessConfig {
  * - `diagnostics` - Parse errors (when `config.diagnostics = true`)
  * - `chunks` - Chunked code segments (when `config.chunk_max_size` is set)
  */
-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>;
+export interface ProcessResult {
+  readonly language?: string;
+  readonly metrics?: FileMetrics;
+  readonly structure?: Array<StructureItem>;
+  readonly imports?: Array<ImportInfo>;
+  readonly exports?: Array<ExportInfo>;
+  readonly comments?: Array<CommentInfo>;
+  readonly docstrings?: Array<DocstringInfo>;
+  readonly symbols?: Array<SymbolInfo>;
+  readonly diagnostics?: Array<Diagnostic>;
+  readonly chunks?: Array<CodeChunk>;
 }
 
 /**
@@ -705,26 +621,26 @@ export interface JsProcessResult {
  * Represents both byte offsets (for slicing) and human-readable line/column
  * positions (for display and diagnostics).
  */
-export interface JsSpan {
-  startByte?: number;
-  endByte?: number;
-  startLine?: number;
-  startColumn?: number;
-  endLine?: number;
-  endColumn?: number;
+export interface Span {
+  readonly startByte?: number;
+  readonly endByte?: number;
+  readonly startLine?: number;
+  readonly startColumn?: number;
+  readonly endLine?: number;
+  readonly 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;
+export interface StructureItem {
+  readonly kind?: StructureKind;
+  readonly name?: string;
+  readonly visibility?: string;
+  readonly span?: Span;
+  readonly children?: Array<StructureItem>;
+  readonly decorators?: Array<string>;
+  readonly docComment?: string;
+  readonly signature?: string;
+  readonly bodySpan?: Span;
 }
 
 /**
@@ -734,7 +650,7 @@ export interface JsStructureItem {
  * structs, enums, traits, and more. Use [`Other`](StructureKind::Other) for
  * language-specific constructs that do not fit a standard category.
  */
-export declare enum JsStructureKind {
+export declare enum StructureKind {
   Function = "Function",
   Method = "Method",
   Class = "Class",
@@ -749,12 +665,12 @@ export declare enum JsStructureKind {
 }
 
 /** A symbol (variable, function, type, etc.) extracted from source code. */
-export interface JsSymbolInfo {
-  name?: string;
-  kind?: JsSymbolKind;
-  span?: JsSpan;
-  typeAnnotation?: string;
-  doc?: string;
+export interface SymbolInfo {
+  readonly name?: string;
+  readonly kind?: SymbolKind;
+  readonly span?: Span;
+  readonly typeAnnotation?: string;
+  readonly doc?: string;
 }
 
 /**
@@ -763,7 +679,7 @@ export interface JsSymbolInfo {
  * Categorizes symbol definitions such as variables, constants, functions,
  * classes, types, interfaces, enums, and modules.
  */
-export declare enum JsSymbolKind {
+export declare enum SymbolKind {
   Variable = "Variable",
   Constant = "Constant",
   Function = "Function",
@@ -775,20 +691,42 @@ export declare enum JsSymbolKind {
   Other = "Other",
 }
 
-export declare class JsTree {}
+/** A parsed syntax tree. Cheap to clone (refcount bump). */
+export declare class Tree {
+  /** Return the root [`Node`] of this tree. */
+  rootNode(): Node;
+  /** Return a [`TreeCursor`] positioned at the root. */
+  walk(): TreeCursor;
+}
+
+/** A cursor for traversing a [`Tree`]. */
+export declare class TreeCursor {
+  /** Return the [`Node`] at the cursor's current position. */
+  node(): Node;
+  /**
+   * Move the cursor to the first child of the current node.
+   * Returns `true` if a child existed.
+   */
+  gotoFirstChild(): boolean;
+  /**
+   * Move the cursor to the parent of the current node.
+   * Returns `true` if a parent existed.
+   */
+  gotoParent(): boolean;
+  /**
+   * Move the cursor to the next sibling of the current node.
+   * Returns `true` if a sibling existed.
+   */
+  gotoNextSibling(): boolean;
+  /** Return the field name for the current node, if any. */
+  fieldName(): string | null;
+}
 
 /**
  * Return the number of available languages.
  *
  * Includes statically compiled languages, dynamically loadable languages,
  * and aliases.
- * @example
- * ```typescript
- * use tree_sitter_language_pack::language_count;
- *
- * let count = language_count();
- * println!("{} languages available", count);
- * ```typescript
  */
 export declare function languageCount(): number;
 
@@ -799,14 +737,6 @@ export declare function languageCount(): number;
  * downloadable languages. Use [`downloaded_languages`] to list what is
  * already cached locally.
  * @throws Returns an error if the manifest cannot be fetched.
- *
- * @example
- * ```typescript
- * use tree_sitter_language_pack::manifest_languages;
- *
- * let langs = manifest_languages().unwrap();
- * println!("{} languages available for download", langs.len());
- * ```typescript
  */
 export declare function manifestLanguages(): Array<string>;
 
@@ -817,16 +747,5 @@ export declare function manifestLanguages(): Array<string>;
  * exports, comments, docstrings, symbols, diagnostics, and/or chunks based on
  * the flags set in [`ProcessConfig`].
  * @throws Returns an error if the language is not found or parsing fails.
- *
- * @example
- * ```typescript
- * use tree_sitter_language_pack::{ProcessConfig, process};
- *
- * 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());
- * ```typescript
  */
-export declare function process(source: string, config: JsProcessConfig): JsProcessResult;
+export declare function process(source: string, config: ProcessConfig): ProcessResult;

package/index.js

@@ -3,14 +3,18 @@
 const { platform, arch } = process;
 const isWindows = platform === "win32";
 const isMusl = () => {
+  // Prefer the report-header `glibcVersion` string when present — fastest and
+  // unambiguous on Node builds that populate it. On Node 22+, certain CI
+  // environments leave `glibcVersion` undefined even on glibc systems, so the
+  // `=== undefined` branch from older napi-rs templates produces a false
+  // "is musl" positive. Fall through to the filesystem heuristic instead: on
+  // glibc systems `/lib64/ld-musl-x86_64.so.1` does not exist; on musl systems
+  // it always does. statSync errors → not musl.
   if (typeof process.report === "object" && typeof process.report.getReport === "function") {
     const report = process.report.getReport();
     if (report && report.header && typeof report.header.glibcVersion === "string") {
       return false;
     }
-    if (report && report.header && report.header.glibcVersion === undefined) {
-      return true;
-    }
   }
   try {
     require("fs").statSync("/lib64/ld-musl-x86_64.so.1");

package/package.json

@@ -1,20 +1,8 @@
 {
   "name": "@kreuzberg/tree-sitter-language-pack",
-  "version": "1.8.0",
-  "description": "Tree-sitter language pack - pre-compiled parsers for 305 languages (Node.js NAPI bindings)",
-  "keywords": [
-    "kreuzberg",
-    "language-pack",
-    "napi",
-    "parser",
-    "syntax",
-    "tree-sitter"
-  ],
+  "version": "1.9.0-rc.1",
+  "description": "Pre-compiled tree-sitter grammars for 305 programming languages",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kreuzberg-dev/tree-sitter-language-pack"
-  },
   "files": [
     "index.js",
     "index.d.ts",
@@ -22,13 +10,9 @@
   ],
   "main": "index.js",
   "types": "index.d.ts",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
   "scripts": {
-    "artifacts": "napi artifacts",
     "build": "napi build --platform --release",
+    "artifacts": "napi artifacts",
     "prepublishOnly": "napi prepublish -t npm --skip-optional-publish"
   },
   "devDependencies": {
@@ -37,14 +21,15 @@
   "napi": {
     "binaryName": "ts-pack-core-node",
     "targets": [
-      "aarch64-apple-darwin",
       "x86_64-unknown-linux-gnu",
       "aarch64-unknown-linux-gnu",
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
       "x86_64-pc-windows-msvc",
       "aarch64-pc-windows-msvc"
     ]
   },
   "engines": {
-    "node": ">= 16"
+    "node": ">= 18"
   }
 }