Configuration Reference

This page documents all configuration types and their defaults across all languages.

DataAttribute

An XML-style attribute attached to an Element node.

Populated only for DataNodeKind.Element; always empty for KeyValue and Sequence nodes.

Field	Type	Default	Description
`name`	`str`	—	Attribute name (e.g. `"class"`, `"href"`).
`value`	`str`	—	Attribute value as a raw string (quotes stripped).
`span`	`Span`	—	Source span covering the entire `name="value"` attribute token.

DataNode

A node in the hierarchical data tree produced by data-format extraction.

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:

`kind`	`key`	`value`	`attributes`	`children`
`KeyValue`	key / mapping key / index	leaf value	empty	nested map
`Element`	XML tag name	text content	XML attrs	child elements
`Sequence`	positional index (`"0"`)	leaf value	empty	sub-items

Field	Type	Default	Description
`kind`	`DataNodeKind`	`DataNodeKind.KEY_VALUE`	Whether this node is a key/value pair, XML element, or sequence item.
`key`	`str \| None`	`None`	Key, attribute name, tag name, or positional index (`"0"`, `"1"`, …). `None` at the document root.
`value`	`str \| None`	`None`	Leaf scalar value, if any. `None` for containers (objects, arrays, XML elements with child elements).
`attributes`	`list\[DataAttribute\]`	`[]`	Attributes on element-shape nodes (XML `STag` attributes). Empty for all other kinds.
`children`	`list\[DataNode\]`	`[]`	Children for nested containers and XML element bodies.
`span`	`Span`	—	Source span covering this node in the original source file.

Span

Byte and line/column range in source code.

Represents both byte offsets (for slicing) and human-readable line/column positions (for display and diagnostics).

Field	Type	Default	Description
`start_byte`	`int`	—	Inclusive start byte offset in the source.
`end_byte`	`int`	—	Exclusive end byte offset in the source.
`start_line`	`int`	—	Zero-indexed line number of the span’s start.
`start_column`	`int`	—	Zero-indexed column of the span’s start, counted in bytes from the start of the line — not characters, not UTF-16 code units.
`end_line`	`int`	—	Zero-indexed line number of the span’s end.
`end_column`	`int`	—	Zero-indexed column of the span’s end, counted in bytes from the start of the line — not characters, not UTF-16 code units.

ProcessResult

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 ProcessConfig flags.

Field	Type	Default	Description
`language`	`str`	—	The language name used to parse the source file.
`metrics`	`FileMetrics`	—	File-level metrics (line counts, byte size, error count).
`structure`	`list\[StructureItem\]`	`[]`	Top-level structural items (functions, classes, etc.).
`imports`	`list\[ImportInfo\]`	`[]`	Import statements extracted from the source.
`exports`	`list\[ExportInfo\]`	`[]`	Export statements extracted from the source.
`comments`	`list\[CommentInfo\]`	`[]`	Comments extracted from the source.
`docstrings`	`list\[DocstringInfo\]`	`[]`	Docstrings extracted from the source.
`symbols`	`list\[SymbolInfo\]`	`[]`	Symbol definitions (variables, types, functions) extracted from the source.
`diagnostics`	`list\[Diagnostic\]`	`[]`	Parse diagnostics (syntax errors, missing nodes) from tree-sitter.
`chunks`	`list\[CodeChunk\]`	`[]`	Syntax-aware code chunks produced when chunking is enabled.
`data`	`DataNode \| None`	`None`	Hierarchical data tree extracted when `config.data_extraction` is `True`. Populated for supported data-format languages (JSON, YAML, TOML, properties, 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.

FileMetrics

Aggregate metrics for a source file.

Field	Type	Default	Description
`total_lines`	`int`	—	Total number of lines (including blank and comment lines).
`code_lines`	`int`	—	Number of lines containing non-blank, non-comment source code.
`comment_lines`	`int`	—	Number of lines that are entirely comments.
`blank_lines`	`int`	—	Number of blank (whitespace-only) lines.
`total_bytes`	`int`	—	Total byte length of the source file.
`node_count`	`int`	—	Total number of nodes in the syntax tree.
`error_count`	`int`	—	Number of error nodes in the syntax tree (parse errors).
`max_depth`	`int`	—	Maximum nesting depth reached in the syntax tree.

StructureItem

A structural item (function, class, struct, etc.) in source code.

Field	Type	Default	Description
`kind`	`StructureKind`	`StructureKind.FUNCTION`	The kind of structural item.
`name`	`str \| None`	`None`	The declared name of the item, if present.
`visibility`	`str \| None`	`None`	Visibility modifier (e.g., `"pub"`, `"public"`, `"private"`).
`span`	`Span`	—	Source span covering the entire item declaration.
`children`	`list\[StructureItem\]`	`[]`	Nested structural items (e.g., methods within a class).
`decorators`	`list\[str\]`	`[]`	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.
`doc_comment`	`str \| None`	`None`	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.
`signature`	`str \| None`	`None`	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 library extracts structure for, since it is derived from `body_span`’s boundary rather than per-language syntax.
`body_span`	`Span \| None`	`None`	Source span covering only the body of the item, if distinct from the declaration.

CommentInfo

A comment extracted from source code.

Field	Type	Default	Description
`text`	`str`	—	The raw text content of the comment.
`kind`	`CommentKind`	`CommentKind.LINE`	The kind of comment (line, block, or doc).
`span`	`Span`	—	Source span covering the comment.
`associated_node`	`str \| None`	`None`	Name of the syntax node this comment is directly associated with.

DocstringInfo

A docstring extracted from source code.

Field	Type	Default	Description
`text`	`str`	—	The raw text of the docstring.
`format`	`DocstringFormat`	`DocstringFormat.PYTHON_TRIPLE_QUOTE`	The docstring format (Python, JSDoc, Rustdoc, etc.).
`span`	`Span`	—	Source span covering the docstring.
`associated_item`	`str \| None`	`None`	Name of the item this docstring documents.
`parsed_sections`	`list\[DocSection\]`	`[]`	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.

DocSection

A section within a docstring (e.g., Args, Returns, Raises).

Field	Type	Default	Description
`kind`	`str`	—	Section kind (e.g., `"args"`, `"returns"`, `"raises"`).
`name`	`str \| None`	`None`	Parameter or return value name, if applicable.
`description`	`str`	—	Description text for this section.

ImportInfo

An import statement extracted from source code.

Field	Type	Default	Description
`source`	`str`	—	The module or path being imported from.
`items`	`list\[str\]`	`[]`	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 library 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.
`alias`	`str \| None`	`None`	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.
`is_wildcard`	`bool`	—	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.
`span`	`Span`	—	Source span covering the import statement.

ExportInfo

An export statement extracted from source code.

Field	Type	Default	Description
`name`	`str`	—	The exported name.
`kind`	`ExportKind`	`ExportKind.NAMED`	The kind of export (named, default, or re-export).
`span`	`Span`	—	Source span covering the export statement.

SymbolInfo

A symbol (variable, function, type, etc.) extracted from source code.

Field	Type	Default	Description
`name`	`str`	—	The name of the symbol.
`kind`	`SymbolKind`	`SymbolKind.VARIABLE`	The kind of symbol (variable, function, class, etc.).
`span`	`Span`	—	Source span covering the symbol definition.
`type_annotation`	`str \| None`	`None`	Explicit type annotation, if present in the source.
`doc`	`str \| None`	`None`	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.

Diagnostic

A diagnostic (syntax error, missing node, etc.) from parsing.

Field	Type	Default	Description
`message`	`str`	—	Human-readable description of the diagnostic.
`severity`	`DiagnosticSeverity`	`DiagnosticSeverity.ERROR`	Severity of the diagnostic.
`span`	`Span`	—	Source span where the diagnostic was detected.

CodeChunk

A chunk of source code with rich metadata.

Field	Type	Default	Description
`content`	`str`	—	The raw source text of this chunk.
`start_byte`	`int`	—	Inclusive start byte offset of this chunk in the original source.
`end_byte`	`int`	—	Exclusive end byte offset of this chunk in the original source.
`start_line`	`int`	—	Zero-indexed start line of this chunk.
`end_line`	`int`	—	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.
`metadata`	`ChunkContext`	—	Contextual metadata about this chunk.

ChunkContext

Metadata for a single chunk of source code.

Field	Type	Default	Description
`language`	`str`	—	Language name used to parse this chunk.
`chunk_index`	`int`	—	Zero-indexed position of this chunk within the file’s chunk list.
`total_chunks`	`int`	—	Total number of chunks the file was split into.
`node_types`	`list\[str\]`	`[]`	Tree-sitter node kinds that appear at the top level of this chunk.
`context_path`	`list\[str\]`	`[]`	Hierarchical path of enclosing structural items (e.g., `["MyClass", "my_method"]`).
`symbols_defined`	`list\[str\]`	`[]`	Names of symbols defined within this chunk.
`comments`	`list\[CommentInfo\]`	`[]`	Comments contained within this chunk.
`docstrings`	`list\[DocstringInfo\]`	`[]`	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.
`has_error_nodes`	`bool`	—	Whether this chunk contains any tree-sitter error nodes.

PackConfig

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.

Field	Type	Default	Description
`cache_dir`	`str \| None`	`None`	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 library 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 base: the platform cache dir, e.g. `~/.cache` on Linux.
`languages`	`list\[str\] \| None`	`[]`	Languages to pre-download on init. Each entry is a language name (e.g. `"python"`, `"rust"`).
`groups`	`list\[str\] \| None`	`[]`	Language groups to pre-download. Group names come from the remote manifest, so the valid set is not fixed by this library; the published manifest currently defines only `"all"`. Call `manifest_groups` to enumerate them. An unknown name makes `init` fail.

ProcessConfig

Configuration for the process() function.

Controls which analysis features are enabled and whether chunking is performed.

Field	Type	Default	Description
`language`	`str`	`""`	Language name (required).
`structure`	`bool`	`True`	Extract structural items (functions, classes, etc.). Default: true.
`imports`	`bool`	`True`	Extract import statements. Default: true.
`exports`	`bool`	`True`	Extract export statements. Default: true.
`comments`	`bool`	`False`	Extract comments. Default: false.
`docstrings`	`bool`	`False`	Extract docstrings. Default: false.
`symbols`	`bool`	`False`	Extract symbol definitions. Default: false.
`diagnostics`	`bool`	`False`	Include parse diagnostics. Default: false.
`chunk_max_size`	`int \| None`	`None`	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”.
`data_extraction`	`bool`	`False`	Extract hierarchical key/value data tree from data-format files. Default: false. 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`.
`max_source_bytes`	`int \| None`	`None`	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.
`parse_timeout_ms`	`int \| None`	`None`	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`.

Enums

CommentKind

The kind of a comment found in source code.

Distinguishes between single-line comments, block (multi-line) comments, and documentation comments.

Variant	Description
`Line`	A single-line comment (e.g., `// ...` or `# ...`).
`Block`	A block or multi-line comment using slash-star delimiters.
`Doc`	A documentation comment such as `/// ...` or slash-double-star block.

DataNodeKind

The kind of a data node extracted from a data-format file.

Classifies each node in the hierarchical DataNode tree returned when data_extraction is enabled on ProcessConfig.

Wire format (public JSON contract)

Unit variants serialize as a bare string ("KeyValue"). DO NOT add #[serde(tag = "...")] or rename variants — every language binding has a hand-written deserializer matching this exact shape, and any change breaks all bindings’ process() tests simultaneously. Covered by tests/wire_format.rs.

Variant	Description
`KeyValue`	A key/value pair or mapping (json/toml/properties/yaml/hcl/cue/kdl pair, or a wrapper “object”/“mapping” container).
`Element`	An XML element with a tag name in `key` and attributes in `attributes`.
`Sequence`	A positional sequence item (JSON array element, YAML block sequence item, CSV/PSV row or cell).

DiagnosticSeverity

Severity level of a diagnostic produced during parsing.

Used to classify parse errors, warnings, and informational messages found in the syntax tree.

Variant	Description
`Error`	A parse error (e.g., an `ERROR` or `MISSING` node in the tree).
`Warning`	A warning-level diagnostic.
`Info`	An informational diagnostic.

DocstringFormat

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).

Wire format (public JSON contract)

Unit variants serialize as a bare string ("JSDoc"); the Other variant serializes as a single-keyed object ({"Other": "rst"}). DO NOT add #[serde(tag = "...")]. Covered by tests/wire_format.rs.

Variant	Description
`PythonTripleQuote`	Python triple-quoted string docstring (`"""..."""`).
`JSDoc`	JavaScript/TypeScript JSDoc block comment (opens with two stars, closes with star-slash).
`Rustdoc`	Rust `///` or `//!` doc comment.
`GoDoc`	Go doc comment (a comment block immediately preceding a declaration).
`JavaDoc`	Java Javadoc block comment (opens with two stars, closes with star-slash).
`Other`	A language-specific docstring format not covered by the standard variants. — Fields: `_0`: `String`

ExportKind

The kind of an export statement found in source code.

Covers named exports, default exports, and re-exports from other modules.

Variant	Description
`Named`	A named export (e.g., `export { foo }`).
`Default`	A default export (e.g., `export default foo`).
`ReExport`	A re-export from another module (e.g., `export { foo } from 'bar'`).

StructureKind

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 for language-specific constructs that do not fit a standard category.

Wire format (public JSON contract)

Unit variants serialize as a bare string ("Function"); the Other variant serializes as a single-keyed object ({"Other": "macro"}). DO NOT add #[serde(tag = "...")] or rename variants — every language binding has a hand-written deserializer matching this exact shape, and any change breaks all bindings’ process() tests simultaneously. Covered by tests/wire_format.rs.

Variant	Description
`Function`	A free-standing or associated function.
`Method`	A method defined inside a class, struct, trait, or impl block.
`Class`	A class definition.
`Struct`	A struct definition.
`Interface`	An interface or protocol definition.
`Enum`	An enum definition.
`Module`	A module or package declaration.
`Trait`	A trait definition.
`Impl`	An impl block (Rust) or similar implementation block.
`Namespace`	A namespace declaration.
`Other`	A language-specific construct that does not fit any standard category. — Fields: `_0`: `String`

SymbolKind

The kind of a symbol definition found in source code.

Categorizes symbol definitions such as variables, constants, functions, classes, types, interfaces, enums, and modules.

Wire format (public JSON contract)

Unit variants serialize as a bare string ("Function"); the Other variant serializes as a single-keyed object ({"Other": "macro"}). DO NOT add #[serde(tag = "...")]. Covered by tests/wire_format.rs.

Variant	Description
`Variable`	A variable binding.
`Constant`	A constant (immutable binding).
`Function`	A function definition.
`Class`	A class definition.
`Type`	A type alias or typedef.
`Interface`	An interface definition.
`Enum`	An enum definition.
`Module`	A module declaration.
`Other`	A symbol kind not covered by the standard variants. — Fields: `_0`: `String`