@xberg-io/tree-sitter-language-pack 1.14.2 → 1.15.6

package/README.md

@@ -1,3 +1,8 @@
+<!-- This file is auto-generated by alef — DO NOT EDIT. -->
+<!-- alef:hash:5f53c35a3c177554fec1d69a57b489f951570b04e3ea933ee9e68f7c59452458 -->
+<!-- To regenerate: alef readme -->
+<!-- To verify freshness: alef verify -->
+
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/xberg-io/assets@v1/banner/readme-banner-dark.svg">
@@ -113,12 +118,14 @@ npm install @xberg-io/tree-sitter-language-pack
 
 ## Quick Start
 
-```typescript
-import { getParser } from "@xberg-io/tree-sitter-language-pack";
+```typescript title="TypeScript"
+import { process } from "@xberg-io/tree-sitter-language-pack";
+function main() {
+  const result = process("# A comment\ndef greet(name):\n    \"\"\"Say hello.\"\"\"\n    return f'Hi {name}'\n\nimport os\n", { language: "python" });
+  console.log(result);
+}
 
-const parser = getParser("python");
-const tree = parser.parse("def hello(): pass");
-console.log(tree.rootNode.toString());
+void main();
 ```
 
 ## Features

package/index.d.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by alef — DO NOT EDIT.
-// alef:hash:976e3b6b83d187cee6bb9dd6b0b8644f15198c5e45d5a66a3b2d2f7573374a9d
+// alef:hash:dfcbc4453ca8c45a492f2bb6653993898741a1008761931894bf829abd29e46a
 // To regenerate: alef generate
-// To verify freshness: alef verify --exit-code
+// To verify freshness: alef verify
 /* eslint-disable */
 import type { Language } from "tree-sitter";
 
@@ -18,16 +18,23 @@ export declare function availableLanguages(): Array<string>;
 /**
  * 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/`.
- * @throws Returns an error if the system cache directory cannot be determined.
+ * This is `{base}/tree-sitter-language-pack/v{version}/libs/`, where `{base}` is
+ * either the custom BASE directory set via `configure` / `init`
+ * (`PackConfig.cache_dir`) or the platform default cache directory — both are
+ * suffixed identically, so a custom `cache_dir` is never used as the final libs
+ * path. The default resolves to `~/.cache/tree-sitter-language-pack/v{version}/libs/`
+ * on a typical Unix system.
+ * @throws Returns an error if no cache directory can be resolved: `version` is somehow
+ * invalid, or (with no custom `cache_dir` configured) the platform reports none
+ * and `TREE_SITTER_LANGUAGE_PACK_CACHE_DIR` is unset. This crate no longer falls
+ * back to the temporary directory for the latter case — see #101 H2.
  */
 export declare function cacheDir(): string;
 
 /**
  * Delete all cached parser shared libraries.
  *
- * Resets the cache registration so the next call to [`get_language`] or
+ * 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.
  */
@@ -37,9 +44,16 @@ 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
+ * `get_language` or any download function. Changing the cache dir
  * after languages have been registered has no effect on already-loaded
  * languages.
+ *
+ * `PackConfig.cache_dir` is a BASE directory, not the final libs path: this
+ * crate appends `tree-sitter-language-pack/v{version}/libs` to it, the same
+ * suffix applied to the platform default cache directory. In the example below,
+ * files actually land under `/tmp/my-parsers/tree-sitter-language-pack/v{version}/libs/`,
+ * never directly in `/tmp/my-parsers/`. Call `cache_dir` to read back the
+ * resolved, fully-suffixed path.
  * @throws Returns an error if the lock cannot be acquired.
  */
 export declare function configure(config?: PackConfig | undefined | null): void;
@@ -65,15 +79,11 @@ export declare function detectLanguage(path: string): string | null;
  * 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.
+ * A leading UTF-8 BOM (`U+FEFF`) is skipped before the `#!` check, so a
+ * BOM-prefixed script is still detected by its shebang.
  *
- * ```
- * 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);
- * ```
+ * Returns `None` when content does not start with `#!` (after stripping a
+ * leading BOM), the shebang is malformed, or the interpreter is not recognised.
  */
 export declare function detectLanguageFromContent(content: string): string | null;
 
@@ -81,13 +91,6 @@ export declare function detectLanguageFromContent(content: string): string | nul
  * 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 | null;
 
@@ -96,21 +99,17 @@ export declare function detectLanguageFromExtension(ext: string): string | null;
  *
  * 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 | null;
 
 /**
  * Download specific languages to the local cache.
  *
- * Returns the number of requested languages available after the call. Already
+ * Returns the number of distinct languages available after the call. Already
  * compiled or cached languages are included in the count.
+ *
+ * Aliases are resolved before counting, so `["shell", "bash"]` names one
+ * language and returns 1.
  * @throws Returns an error if any language is not available in the manifest or if
  * the download fails.
  */
@@ -139,16 +138,23 @@ export declare function downloadAll(): number;
 export declare function downloadedLanguages(): Array<string>;
 
 /**
- * Download every language in a named group (e.g. `"web"`, `"data"`).
+ * Download every language in a named group.
+ *
+ * Groups are defined by the remote manifest, not by this crate, 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.
  *
- * 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.
+ * Call `manifest_groups` to discover the group names the manifest actually
+ * defines. The published manifest currently defines a single group, `"all"`;
+ * earlier revisions of this documentation advertised `"web"`, `"data"`, and
+ * `"systems"`, which the manifest has never contained, so every call following
+ * that example failed. Do not hardcode a group name without checking.
  *
  * 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.
+ * @throws Returns `Error.Download` if the manifest cannot be fetched, if the group
+ * is unknown — the message lists the groups the manifest defines — or if any
+ * constituent language fails to download.
  */
 export declare function downloadGroup(name: string): number;
 
@@ -185,13 +191,13 @@ export declare function getIndentsQuery(language: string): string | null;
 export declare function getInjectionsQuery(language: string): string | null;
 
 /**
- * Get a tree-sitter [`Language`] by name using the global registry.
+ * 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.
- * @throws Returns [`Error::LanguageNotFound`] if the language is not recognized,
- * or [`Error::Download`] if auto-download fails.
+ * @throws Returns `Error.LanguageNotFound` if the language is not recognized,
+ * or `Error.Download` if auto-download fails.
  */
 export declare function getLanguage(name: string): Language;
 
@@ -204,12 +210,12 @@ export declare function getLanguage(name: string): Language;
 export declare function getLocalsQuery(language: string): string | null;
 
 /**
- * Get a [`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
+ * 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.
+ * @throws Returns `Error.LanguageNotFound` if the language is not recognized, or
+ * `Error.ParserSetup` if the language cannot be applied to the parser.
  */
 export declare function getParser(name: string): Parser;
 
@@ -263,7 +269,13 @@ export interface ChunkContext {
   readonly symbolsDefined?: Array<string>
   /** Comments contained within this chunk. */
   readonly comments?: Array<CommentInfo>
-  /** Docstrings contained within this chunk. */
+  /**
+   * Docstrings contained within this chunk.
+   *
+   * Populated only for Python — the same language for which
+   * `ProcessResult.docstrings` is populated, and by the same
+   * classifier. Always empty for every other language.
+   */
   readonly docstrings?: Array<DocstringInfo>
   /** Whether this chunk contains any tree-sitter error nodes. */
   readonly hasErrorNodes?: boolean
@@ -279,7 +291,13 @@ export interface CodeChunk {
   readonly endByte?: number
   /** Zero-indexed start line of this chunk. */
   readonly startLine?: number
-  /** Zero-indexed end line of this chunk. */
+  /**
+   * Zero-indexed row of the last byte actually included in this chunk
+   * (inclusive — the same row a `Span.end_line` would report for a node
+   * ending on that byte). Computed the same way regardless of whether the
+   * source has a trailing newline: it is always the row of `end_byte - 1`,
+   * never a phantom row past the file's real content.
+   */
   readonly endLine?: number
   /** Contextual metadata about this chunk. */
   readonly metadata?: ChunkContext
@@ -313,9 +331,9 @@ export declare enum CommentKind {
 }
 
 /**
- * An XML-style attribute attached to an [`Element`](DataNodeKind::Element) node.
+ * An XML-style attribute attached to an `Element` node.
  *
- * Populated only for `DataNodeKind::Element`; always empty for `KeyValue` and
+ * Populated only for `DataNodeKind.Element`; always empty for `KeyValue` and
  * `Sequence` nodes.
  */
 export interface DataAttribute {
@@ -330,9 +348,9 @@ export interface DataAttribute {
 /**
  * A node in the hierarchical data tree produced by data-format extraction.
  *
- * When [`ProcessConfig::data_extraction`](crate::ProcessConfig::data_extraction) is
- * `true`, [`ProcessResult::data`] is populated with a root `DataNode` whose
- * [`children`](DataNode::children) mirror the structure of the parsed file.
+ * When `ProcessConfig.data_extraction` is
+ * `true`, `ProcessResult.data` is populated with a root `DataNode` whose
+ * `children` mirror the structure of the parsed file.
  *
  * The `kind` field determines which other fields are meaningful:
  *
@@ -366,7 +384,7 @@ export interface DataNode {
 /**
  * The kind of a data node extracted from a data-format file.
  *
- * Classifies each node in the hierarchical [`DataNode`] tree returned when
+ * Classifies each node in the hierarchical `DataNode` tree returned when
  * `data_extraction` is enabled on `ProcessConfig`.
  *
  * # Wire format (public JSON contract)
@@ -470,20 +488,51 @@ export interface DocstringInfo {
   readonly span?: Span
   /** Name of the item this docstring documents. */
   readonly associatedItem?: string
-  /** Parsed sections of the docstring (Args, Returns, Raises, etc.). */
+  /**
+   * Parsed sections of the docstring (Args, Returns, Raises, etc.).
+   *
+   * **Reserved: not yet populated.** Always empty, for every
+   * `DocstringFormat`. Parsing a docstring body into sections requires
+   * implementing each convention's own layout (Google/NumPy/reST style
+   * for Python, `@param`/`@returns` for JSDoc/Javadoc, and so on), which
+   * no extractor here does yet. The field is kept rather than removed so
+   * a consumer's deserializer does not need updating once it is.
+   */
   readonly parsedSections?: Array<DocSection>
 }
 
 /** Manages downloading and caching of pre-built parser shared libraries. */
 export declare class DownloadManager {
-  /** Create a new download manager for the given version. */
+  /**
+   * Create a new download manager for the given version.
+   * @throws Returns `Error.Download` if `version` is empty, contains a path
+   * separator or `..`, or contains a character outside `[A-Za-z0-9.+-]` — see
+   * `validate_version` — or if no cache directory can be resolved (see
+   * `Self.default_cache_dir`).
+   */
   static new(version: string): DownloadManager
-  /** List languages that are already downloaded and cached. */
+  /**
+   * List languages that are already downloaded and cached.
+   *
+   * Derived from the on-disk cache filenames, one canonical name per file, plus
+   * every alias that resolves to it (via `aliases_for`) — so
+   * this list agrees with the user-facing
+   * `LanguageRegistry.available_languages`
+   * about which names are "available"; both report `"shell"` once `bash` is
+   * cached, for example. A previous version reported canonical names only,
+   * which could never agree with `available_languages()`. See #107.
+   *
+   * Returns an empty list if the cache directory does not exist. If it exists
+   * but cannot be read (e.g. a permission error), also returns an empty list —
+   * changing this to a `Result` would be a breaking change across every
+   * language binding — but logs a `tracing.warn!` so the failure is not
+   * silently indistinguishable from "nothing installed".
+   */
   installedLanguages(): Array<string>
   /**
    * Download the platform bundle and extract every library file it contains.
    *
-   * Unlike [`Self::ensure_languages`], this does not check the manifest language list
+   * Unlike `Self.ensure_languages`, this does not check the manifest language list
    * against archive contents — it simply extracts all `.so`/`.dylib`/`.dll` files
    * from the bundle. Languages in the manifest that are missing from the archive
    * are silently ignored rather than returning an error.
@@ -552,11 +601,43 @@ export interface FileMetrics {
 export interface ImportInfo {
   /** The module or path being imported from. */
   readonly source?: string
-  /** Specific names imported from the source module. */
+  /**
+   * Specific names imported from the source module.
+   *
+   * For `import a, b` / `from m import a, b`, every entry's base name
+   * (never the alias). For a JavaScript/TypeScript named-imports clause
+   * (`import { a, b as c } from 'm'`), every specifier's original name.
+   *
+   * Populated for Python and JavaScript/TypeScript only. Always empty for
+   * every other language this crate recognises import statements for —
+   * Rust, Go, Java, Kotlin, and Elixir (`import`/`alias`/`require`/`use`)
+   * — and for a JS/TS namespace import (`import * as ns`) or default
+   * import (`import x from 'm'`), neither of which names individual items.
+   */
   readonly items?: Array<string>
-  /** Alias assigned to the import (e.g., `import numpy as np`). */
+  /**
+   * Alias assigned to the import (e.g., `import numpy as np`).
+   *
+   * Populated for Python's single-name form (`import numpy as np`,
+   * `from m import a as b`) and JavaScript/TypeScript's namespace form
+   * (`import * as ns from 'm'`) or a named-imports clause naming exactly
+   * one specifier (`import { a as b } from 'm'`). `None` for Rust, Go,
+   * Java, Kotlin, and Elixir (which has its own `as:` alias option on
+   * `alias` directives, not yet extracted here) — and for a Python
+   * statement that aliases several names at once (`import os, sys as s`),
+   * where there is no single alias to report for the statement as a
+   * whole, so only `items` is populated for it.
+   */
   readonly alias?: string
-  /** Whether this is a wildcard import (e.g., `import *` or `use foo::*`). */
+  /**
+   * Whether this is a wildcard import (e.g., `import *` or `use foo.*`).
+   *
+   * Detected from the syntax tree — a dedicated wildcard node
+   * (`wildcard_import` in Python, `use_wildcard` in Rust) or a bare `*`
+   * token outside of string-literal content — not by searching the
+   * import's source text for a `*` character, so a glob in an import path
+   * string (`import a from './glob*.js'`) is not mistaken for one.
+   */
   readonly isWildcard?: boolean
   /** Source span covering the import statement. */
   readonly span?: Span
@@ -566,7 +647,7 @@ export interface ImportInfo {
  * 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
+ * Use `LanguageRegistry.new()` for the default registry, or access the
  * global instance via the module-level convenience functions
  * (`get_language`, `available_languages`, etc.).
  */
@@ -578,16 +659,6 @@ export declare class LanguageRegistry {
    * about dynamically loadable grammars and will load them on demand.
    */
   static new(): LanguageRegistry
-  /**
-   * 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.
-   * @throws Returns [`Error::LanguageNotFound`] if the name (after alias resolution)
-   * does not match any known grammar.
-   */
-  getLanguage(name: string): Language
   /**
    * List all available language names, sorted and deduplicated.
    *
@@ -596,26 +667,28 @@ export declare class LanguageRegistry {
    */
   availableLanguages(): Array<string>
   /**
-   * Check whether a parser is statically compiled into this build.
+   * Check whether this language can be parsed right now, without downloading.
    *
-   * Returns `true` only when the grammar was compiled in at build time
-   * (i.e. it appears in the `STATIC_LANGUAGES` table). This is independent
-   * of the extension-to-language mapping: `detect_language_from_extension`
-   * consults the static ext table for all 371 grammars regardless of which
-   * parsers are compiled in.
+   * Resolves aliases, then answers from exactly the lookup
+   * `get_language` performs: the statically compiled
+   * table, the already-loaded dynamic grammars, and the parser shared
+   * libraries present in the primary and extra (download-cache) library
+   * directories. It never performs network I/O.
    *
-   * Use this when you need to distinguish "we know the language name" from
-   * "we can actually parse files in that language right now".
+   * A previous implementation consulted only the statically compiled table.
+   * That table is empty in every build that does not set `TSLP_LANGUAGES`,
+   * so the function answered `false` for languages this registry parses
+   * perfectly well.
    *
-   * ```no_run
-   * use tree_sitter_language_pack::{detect_language_from_extension, LanguageRegistry};
+   * Contrast `has_language`, which is also `true` for a
+   * grammar that is merely *known to the manifest* and would have to be
+   * downloaded first. The pair distinguishes "we can parse it offline, now"
+   * from "we recognise the name".
    *
-   * let registry = LanguageRegistry::new();
-   * // Extension detection uses the static table — independent of compiled parsers.
-   * let lang = detect_language_from_extension("feature"); // always returns Some("gherkin")
-   * // Parser availability depends on which grammars were compiled in.
-   * let can_parse = lang.map(|name| registry.has_parser(name)).unwrap_or(false);
-   * ```
+   * The first `true` answer for a dynamic grammar loads its shared library:
+   * loading is the only way to know the grammar is usable, since a truncated
+   * or wrong-architecture library exists on disk but cannot parse. Loads are
+   * cached process-wide, so repeat calls are cheap.
    */
   hasParser(name: string): boolean
   /**
@@ -623,23 +696,41 @@ export declare class LanguageRegistry {
    *
    * Returns `true` if the language can be loaded, either from the static
    * table or from a dynamic library on disk.
+   *
+   * Every branch is one more way to answer `true`, so they are ordered
+   * cheapest-first and the filesystem is only consulted once every in-memory
+   * source has said no. Probing the loaded-grammar map and the manifest ahead
+   * of the `stat` calls is what keeps this off the syscall path for the
+   * languages a process actually uses.
    */
   hasLanguage(name: string): boolean
-  /** Return the total number of available languages (including aliases). */
+  /**
+   * Return the total number of available languages (including aliases).
+   *
+   * Counts the same set `available_languages`
+   * lists, without materialising or sorting it.
+   */
   languageCount(): number
-  /** Parse source code and extract file intelligence based on config in a single pass. */
+  /**
+   * Parse source code and extract file intelligence based on config in a single pass.
+   * @throws Returns `Error.InvalidRange` if the config is invalid (see
+   * `ProcessConfig.validate`) or if the source
+   * exceeds the configured
+   * `max_source_bytes`;
+   * `Error.LanguageNotFound` if the language is unknown; or
+   * `Error.ParseFailed` if parsing produces no tree.
+   */
   process(source: string, config?: ProcessConfig | undefined | null): ProcessResult
   static default(): LanguageRegistry
 }
 
 /**
- * A single syntax node within a [`Tree`].
+ * 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
   /**
@@ -647,7 +738,7 @@ export declare class Node {
    *
    * 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.
+   * than comparing the string `kind()` in tight AST loops.
    */
   kindId(): number
   /** Return the inclusive start byte offset of this node. */
@@ -655,15 +746,15 @@ export declare class Node {
   /** Return the exclusive end byte offset of this node. */
   endByte(): number
   /**
-   * Return the node's byte range as a [`ByteRange`].
+   * 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). */
+  /** Return the start `Point` (row, column). */
   startPosition(): Point
-  /** Return the end [`Point`] (row, column). */
+  /** Return the end `Point` (row, column). */
   endPosition(): Point
   /** True when this node is named (not punctuation/whitespace). */
   isNamed(): boolean
@@ -689,7 +780,7 @@ export declare class Node {
   childByFieldName(name: string): Node | null
   /** Return the S-expression form of this node's subtree. */
   toSexp(): string
-  /** Return a [`TreeCursor`] positioned at this node. */
+  /** Return a `TreeCursor` positioned at this node. */
   walk(): TreeCursor
 }
 
@@ -702,9 +793,20 @@ export declare class Node {
  */
 export interface PackConfig {
   /**
-   * Override default cache directory.
+   * Override the BASE directory the parser cache lives under.
+   *
+   * This is a base, not the final library path: the crate appends
+   * `tree-sitter-language-pack/v{version}/libs` to it, exactly as it does to the
+   * platform default. So `cache_dir = "/tmp/my-parsers"` resolves to
+   * `/tmp/my-parsers/tree-sitter-language-pack/v{version}/libs/`.
+   *
+   * The suffix is not cosmetic. It keeps the whole cache tree — manifest, bundles
+   * and lock file included — inside a directory this crate owns and versions.
+   * Earlier releases used this path verbatim, which put those files in the
+   * configured directory's PARENT and let a cache built by one crate version be
+   * reused by another.
    *
-   * Default: `~/.cache/tree-sitter-language-pack/v{version}/libs/`
+   * Default base: the platform cache dir, e.g. `~/.cache` on Linux.
    */
   readonly cacheDir?: string
   /**
@@ -713,39 +815,84 @@ export interface PackConfig {
    * Each entry is a language name (e.g. `"python"`, `"rust"`).
    */
   readonly languages?: Array<string>
-  /** Language groups to pre-download (e.g. `"web"`, `"systems"`, `"scripting"`). */
+  /**
+   * Language groups to pre-download.
+   *
+   * Group names come from the remote manifest, so the valid set is not fixed
+   * by this crate; the published manifest currently defines only `"all"`.
+   * Call `manifest_groups` to enumerate them.
+   * An unknown name makes `init` fail.
+   */
   readonly groups?: Array<string>
 }
 
 /** A tree-sitter parser configured for one language at a time. */
 export declare class Parser {
   /**
-   * Construct a new parser with no language set.
+   * Construct a new parser with no language set and no parse limits.
    *
-   * Call [`Parser::set_language`] before parsing.
+   * Call `Parser.set_language` before parsing. Limits are opt-in via
+   * `set_max_source_bytes` and
+   * `set_parse_timeout_ms`; both default to
+   * unbounded so that existing callers are unaffected.
    */
   static new(): Parser
+  /**
+   * Refuse to parse sources longer than `max_bytes`.
+   *
+   * `None` (the default) means no limit. Over-limit input makes
+   * `parse` and `parse_bytes` return
+   * `None` after emitting a `WARN`; input is never silently truncated.
+   *
+   * See `RECOMMENDED_MAX_SOURCE_BYTES`.
+   */
+  setMaxSourceBytes(maxBytes?: number | undefined | null): void
+  /**
+   * Cancel a parse that exceeds `timeout_ms` milliseconds of wall clock.
+   *
+   * `None` (the default) means no budget. Cancellation runs through
+   * tree-sitter's parse progress callback, so it is granular to that
+   * callback's interval rather than exact.
+   *
+   * See `RECOMMENDED_PARSE_TIMEOUT_MS`.
+   */
+  setParseTimeoutMs(timeoutMs?: number | undefined | null): void
   /**
    * 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.
+   * @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 a UTF-8 source string.
+   *
+   * Returns `None` if no language is set, if the parse was cancelled by the
+   * configured [timeout](Self.set_parse_timeout_ms), or if the source
+   * exceeds the configured [size limit](Self.set_max_source_bytes). Each
+   * non-parse outcome is logged, so an empty result is never silent.
+   *
+   * # Concurrency
+   *
+   * Parsing runs fully in parallel across threads for almost every language — no lock is
+   * taken. The exception is the small set of grammars whose external scanner keeps mutable
+   * process-global state (currently just `properties`): parses of that language are
+   * serialized against each other through an internal per-language lock, so that concurrent
+   * threads can't corrupt shared scanner state. Every other language is unaffected by that
+   * lock and never waits on it.
    */
   parse(source: string): Tree | null
   /**
-   * Parse a raw byte slice. Returns `None` if parsing was cancelled or
-   * no language is set.
+   * Parse a raw byte slice.
+   *
+   * Same outcomes as `parse`, including the concurrency behaviour documented
+   * there.
    */
   parseBytes(source: Uint8Array): Tree | null
   /**
-   * Reset internal state. The next call to [`parse`](Self::parse) will
+   * Reset internal state. The next call to `parse` will
    * not be incremental.
    */
   reset(): void
@@ -756,7 +903,22 @@ export declare class Parser {
 export interface Point {
   /** Zero-indexed row number. */
   readonly row: number
-  /** Zero-indexed column number, in UTF-16 code units. */
+  /**
+   * Zero-indexed column, counted in **bytes** from the start of the row.
+   *
+   * This is `tree_sitter.Point.column` verbatim, and tree-sitter defines it
+   * as a byte offset — not characters, and not UTF-16 code units. Measured on
+   * a row of the form `x = '<c>'` where `<c>` is a single 4-byte character
+   * (an emoji), the string node reports columns `4..10`, identical to its
+   * byte range; the character columns would be `4..7` and the UTF-16 columns
+   * `4..8`.
+   *
+   * Anything that builds LSP positions (UTF-16) or editor caret columns
+   * (characters) from this field is silently wrong on every row containing a
+   * non-ASCII byte, and must re-measure the row against the source text
+   * instead. Earlier releases documented this field as UTF-16 code units;
+   * that was never what the value contained.
+   */
   readonly column: number
 }
 
@@ -782,19 +944,51 @@ export interface ProcessConfig {
   readonly symbols?: boolean
   /** Include parse diagnostics. Default: false. */
   readonly diagnostics?: boolean
-  /** Maximum chunk size in bytes. `None` disables chunking. */
+  /**
+   * Maximum chunk size in bytes. `None` disables chunking.
+   *
+   * `Some(0)` is rejected by `ProcessConfig.validate` with
+   * `Error.InvalidRange`. A zero-sized chunk
+   * limit previously produced an empty chunk list and silently discarded the
+   * whole source; use `None` to mean "do not chunk".
+   */
   readonly chunkMaxSize?: number
   /**
    * Extract hierarchical key/value data tree from data-format files. Default: false.
    *
-   * When `true`, [`ProcessResult::data`](crate::ProcessResult::data) is populated
-   * with a [`DataNode`](crate::DataNode) tree for supported languages: JSON, YAML,
+   * When `true`, `ProcessResult.data` is populated
+   * with a `DataNode` tree for supported languages: JSON, YAML,
    * TOML, `.properties`, HCL/HOCON, INI, editorconfig, KDL, CUE, CSV, PSV, PO,
    * nginx config, Caddy config, XML, and DTD.
    *
    * For languages outside this set the field is left as `None`.
    */
   readonly dataExtraction?: boolean
+  /**
+   * Reject source longer than this many bytes instead of parsing it.
+   * Default: `None` (unbounded).
+   *
+   * Tree-sitter allocates and walks proportionally to input size, so an
+   * unbounded parse of attacker-supplied input is a denial-of-service vector.
+   * The default stays unbounded for backward compatibility; services handling
+   * untrusted input should opt in, e.g. with
+   * `RECOMMENDED_MAX_SOURCE_BYTES`.
+   *
+   * Exceeding the limit fails the call with
+   * `Error.InvalidRange` — the source is never
+   * silently truncated.
+   */
+  readonly maxSourceBytes?: number
+  /**
+   * Wall-clock budget for the parse step, in milliseconds.
+   * Default: `None` (no timeout).
+   *
+   * Enforced through tree-sitter's parse progress callback, which the parser
+   * invokes periodically; cancellation is therefore granular to that callback
+   * interval rather than exact. A parse that exceeds the budget fails with
+   * `Error.ParseTimeout`.
+   */
+  readonly parseTimeoutMs?: number
 }
 
 /**
@@ -845,7 +1039,7 @@ export interface ProcessResult {
    * HCL, INI, XML, CSV, and more). `None` when `data_extraction` is `false` (the
    * default) or when the language is not a recognised data format.
    *
-   * See [`DataNode`] for the shape of the returned tree.
+   * See `DataNode` for the shape of the returned tree.
    */
   readonly data?: DataNode
 }
@@ -863,11 +1057,17 @@ export interface Span {
   readonly endByte?: number
   /** Zero-indexed line number of the span's start. */
   readonly startLine?: number
-  /** Zero-indexed column number of the span's start. */
+  /**
+   * Zero-indexed column of the span's start, counted in **bytes** from the
+   * start of the line — not characters, not UTF-16 code units.
+   */
   readonly startColumn?: number
   /** Zero-indexed line number of the span's end. */
   readonly endLine?: number
-  /** Zero-indexed column number of the span's end. */
+  /**
+   * Zero-indexed column of the span's end, counted in **bytes** from the
+   * start of the line — not characters, not UTF-16 code units.
+   */
   readonly endColumn?: number
 }
 
@@ -883,11 +1083,44 @@ export interface StructureItem {
   readonly span?: Span
   /** Nested structural items (e.g., methods within a class). */
   readonly children?: Array<StructureItem>
-  /** Decorator or attribute names applied to the item. */
+  /**
+   * Decorator or attribute names applied to the item.
+   *
+   * **Reserved: not yet populated.** Always empty, for every language.
+   * Recognising a decorator requires per-language grammar knowledge (a
+   * Python `decorated_definition` wrapper, Java/C# annotations, Rust
+   * attributes each have a different shape), which no extractor here
+   * implements yet. The field is kept rather than removed so a consumer's
+   * deserializer does not need updating once it is.
+   */
   readonly decorators?: Array<string>
-  /** Documentation comment attached to the item, if any. */
+  /**
+   * Documentation comment attached to the item, if any.
+   *
+   * The text of the comment (or run of comments) immediately preceding
+   * the item, with no blank line in between, when that comment is
+   * classified as a doc comment. Multiple adjacent single-line doc
+   * comments (Rust `///`) are joined with `\n` in source order.
+   *
+   * Populated for Rust (`///`/`//!`), Java (`/** * /`), and JavaScript/
+   * TypeScript (`/** * /`). `None` for every other language, and for a
+   * preceding comment that is not in doc-comment form (a plain `#`
+   * comment in Python, Ruby, or Elixir) — Python's docstring convention is
+   * captured separately, as `DocstringInfo`, not through this field.
+   */
   readonly docComment?: string
-  /** Full signature text of the item (e.g., function parameters and return type). */
+  /**
+   * Full signature text of the item (e.g., function parameters and return type).
+   *
+   * The item's own source text from its start up to the start of its body
+   * (see `StructureItem.body_span`), trimmed of trailing whitespace —
+   * for example `fn add(a: i32, b: i32) -> i32` for a Rust function whose
+   * body is `{ a + b }`. `None` only when that text is empty, which does
+   * not happen for any item `StructureKind` currently reports. Populated
+   * for every language and kind this crate extracts structure for, since
+   * it is derived from `body_span`'s boundary rather than per-language
+   * syntax.
+   */
   readonly signature?: string
   /** Source span covering only the body of the item, if distinct from the declaration. */
   readonly bodySpan?: Span
@@ -897,7 +1130,7 @@ export interface StructureItem {
  * The kind of structural item found in source code.
  *
  * Categorizes top-level and nested declarations such as functions, classes,
- * structs, enums, traits, and more. Use [`Other`](StructureKind::Other) for
+ * structs, enums, traits, and more. Use `Other` for
  * language-specific constructs that do not fit a standard category.
  *
  * # Wire format (public JSON contract)
@@ -944,7 +1177,18 @@ export interface SymbolInfo {
   readonly span?: Span
   /** Explicit type annotation, if present in the source. */
   readonly typeAnnotation?: string
-  /** Documentation comment associated with this symbol. */
+  /**
+   * Documentation comment immediately preceding this symbol, resolved by
+   * the same walk `StructureItem.doc_comment` uses (see
+   * `doc_comment_at`) — never hard-coded `None`.
+   *
+   * Populated for Rust (`///`/`//!`), Java (`/** * /`), and JavaScript/
+   * TypeScript (`/** * /`) — the languages whose comment classification
+   * recognizes a doc-kind comment. `None` for every other language (e.g.
+   * Python, Go, Ruby, which have no doc-kind comment classification), and
+   * also `None` when a symbol in a supported language simply has no doc
+   * comment immediately above it.
+   */
   readonly doc?: string
 }
 
@@ -983,15 +1227,15 @@ export declare enum SymbolKind {
 
 /** A parsed syntax tree. Cheap to clone (refcount bump). */
 export declare class Tree {
-  /** Return the root [`Node`] of this tree. */
+  /** Return the root `Node` of this tree. */
   rootNode(): Node
-  /** Return a [`TreeCursor`] positioned at the root. */
+  /** Return a `TreeCursor` positioned at the root. */
   walk(): TreeCursor
 }
 
-/** A cursor for traversing a [`Tree`]. */
+/** A cursor for traversing a `Tree`. */
 export declare class TreeCursor {
-  /** Return the [`Node`] at the cursor's current position. */
+  /** Return the `Node` at the cursor's current position. */
   node(): Node
   /**
    * Move the cursor to the first child of the current node.
@@ -1020,11 +1264,22 @@ export declare class TreeCursor {
  */
 export declare function languageCount(): number;
 
+/**
+ * Return the names of every language group the remote manifest defines, sorted.
+ *
+ * Group names are manifest data, not a compile-time constant of this crate, so
+ * this is the only reliable way to learn what `download_group` and
+ * `PackConfig.groups` accept. The published manifest currently defines just
+ * `"all"`.
+ * @throws Returns `Error.Download` if the manifest cannot be fetched.
+ */
+export declare function manifestGroups(): Array<string>;
+
 /**
  * Return all language names available in the remote manifest (371).
  *
  * Fetches (and caches) the remote manifest to discover the full list of
- * downloadable languages. Use [`downloaded_languages`] to list what is
+ * downloadable languages. Use `downloaded_languages` to list what is
  * already cached locally.
  * @throws Returns an error if the manifest cannot be fetched.
  */
@@ -1034,12 +1289,12 @@ export declare function manifestLanguages(): Array<string>;
  * Prefetch grammars: download any not already loadable from disk, then load every
  * requested language into the process registry so a subsequent hot loop only parses.
  *
- * Unlike [`download()`], this does not trust in-memory availability — it downloads
+ * Unlike `download()`, this does not trust in-memory availability — it downloads
  * whenever a grammar is not actually loadable from disk (fixing the case where a
  * known-but-not-downloaded grammar is reported present), then resolves and caches
  * every requested language. Call it once, up front, before a parallel workload.
- * @throws Returns [`Error::Download`] if a required grammar cannot be fetched, or
- * [`Error::LanguageNotFound`] if a requested name is unknown.
+ * @throws Returns `Error.Download` if a required grammar cannot be fetched, or
+ * `Error.LanguageNotFound` if a requested name is unknown.
  */
 export declare function prefetch(languages: Array<string>): void;
 
@@ -1048,7 +1303,11 @@ export declare function prefetch(languages: Array<string>): void;
  *
  * 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`].
- * @throws Returns an error if the language is not found or parsing fails.
+ * the flags set in `ProcessConfig`.
+ * @throws Returns `Error.InvalidRange` if the config carries a zero-valued limit or
+ * the source exceeds `ProcessConfig.max_source_bytes`,
+ * `Error.ParseTimeout` if the parse exceeds
+ * `ProcessConfig.parse_timeout_ms`, `Error.LanguageNotFound` if the
+ * language is unknown, or `Error.ParseFailed` if parsing yields no tree.
  */
 export declare function process(source: string, config?: ProcessConfig | undefined | null): ProcessResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xberg-io/tree-sitter-language-pack",
-  "version": "1.14.2",
+  "version": "1.15.6",
   "description": "Pre-compiled tree-sitter grammars for 371 programming languages",
   "license": "MIT",
   "repository": {
@@ -18,14 +18,14 @@
   },
   "files": ["index.js", "index.d.ts", "*.node"],
   "optionalDependencies": {
-    "@xberg-io/tree-sitter-language-pack-linux-x64-gnu": "1.14.2",
-    "@xberg-io/tree-sitter-language-pack-linux-arm64-gnu": "1.14.2",
-    "@xberg-io/tree-sitter-language-pack-linux-x64-musl": "1.14.2",
-    "@xberg-io/tree-sitter-language-pack-linux-arm64-musl": "1.14.2",
-    "@xberg-io/tree-sitter-language-pack-darwin-x64": "1.14.2",
-    "@xberg-io/tree-sitter-language-pack-darwin-arm64": "1.14.2",
-    "@xberg-io/tree-sitter-language-pack-win32-x64-msvc": "1.14.2",
-    "@xberg-io/tree-sitter-language-pack-win32-arm64-msvc": "1.14.2"
+    "@xberg-io/tree-sitter-language-pack-linux-x64-gnu": "1.15.6",
+    "@xberg-io/tree-sitter-language-pack-linux-arm64-gnu": "1.15.6",
+    "@xberg-io/tree-sitter-language-pack-linux-x64-musl": "1.15.6",
+    "@xberg-io/tree-sitter-language-pack-linux-arm64-musl": "1.15.6",
+    "@xberg-io/tree-sitter-language-pack-darwin-x64": "1.15.6",
+    "@xberg-io/tree-sitter-language-pack-darwin-arm64": "1.15.6",
+    "@xberg-io/tree-sitter-language-pack-win32-x64-msvc": "1.15.6",
+    "@xberg-io/tree-sitter-language-pack-win32-arm64-msvc": "1.15.6"
   },
   "napi": {
     "packageName": "@xberg-io/tree-sitter-language-pack",