---
description: Use when the user wants a tree-sitter syntax tree for a source file — an s-expression dump or JSON tree. Covers `ts-pack parse`, language auto-detection vs `--language`, stdin input, and reading `has_errors`.
name: tree-sitter-language-pack-parsing-source
---

<!--
AI-RULEZ :: GENERATED FILE — DO NOT EDIT
Content-Hash: blake3:211a994b629d9e5e530945c00db243d6f0e4a8f78e054dc7c52db4527c90c35f
Source-Hash: blake3:3943dbd87fc16cef858ef879723581d4e6c392ea827fbdf825d1cbd7a304abc7
Schema-Version: v1
-->

# Parsing source into a syntax tree

`ts-pack parse <file>` parses one source file with the matching
tree-sitter grammar and prints the resulting concrete syntax tree. Use it
when the user wants the tree itself — to inspect node structure, debug a
grammar, or feed an s-expression to another tool.

## Quick recipe

```bash
# S-expression (default) — auto-detects language from the file extension
ts-pack parse src/main.rs

# JSON form: { "language", "sexp", "has_errors" }
ts-pack parse src/main.rs --format json
```

## Flag surface

| Flag | Short | Default | Purpose |
| ---- | ----- | ------- | ------- |
| `--language <name>` | `-l` | auto | Override the language (skip extension detection). |
| `--format <fmt>` | `-f` | `sexp` | `sexp` or `json`. |

The parser library for the language downloads on first use and is cached.

## Language detection

The language is auto-detected from the file extension. Override it when the
extension is missing, misleading, or you are reading from stdin:

```bash
# Misleading extension or no extension:
ts-pack parse script --language bash

# stdin (use "-" as the file):
cat snippet.py | ts-pack parse - --language python
```

stdin cannot be auto-detected by path; always pass `--language` with `-`.
For content-based detection without a path, use the SDK
(`detect_language_from_content`) — see the `tree-sitter-language-pack-detecting-languages` skill.

## Output shapes

### S-expression

A nested `(node_type child ...)` tree. Compact, good for eyeballing
structure or piping to a grammar tool.

### JSON

```json
{
  "language": "rust",
  "sexp": "(source_file (function_item ...))",
  "has_errors": false
}
```

Read `has_errors` to know whether the parse produced any error nodes — a
fast syntax check. For positioned, per-error detail use
`ts-pack process <file> --diagnostics` (see `tree-sitter-language-pack-extracting-code-structure`).

## Examples

```bash
# Inspect a TypeScript file's tree
ts-pack parse src/app.ts

# Machine-readable, then check for syntax errors with jq
ts-pack parse src/app.ts --format json | jq '.has_errors'

# Parse a heredoc as Python
printf 'def f():\n    return 1\n' | ts-pack parse - -l python
```

## When to reach for process instead

`parse` gives you the raw tree. If the user wants structured metadata
(functions, imports, exports, symbols, docstrings) rather than the tree,
use `ts-pack process` — see the `tree-sitter-language-pack-extracting-code-structure` skill.