Skip to content

docs: update README and AGENTS.md #228

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zharinov merged 1 commit into from
Jan 3, 2026
Merged

docs: update README and AGENTS.md #228

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 36 additions & 10 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,19 +145,20 @@ Tree-sitter: `((a) (b))` — Plotnik: `{(a) (b)}`. The #1 syntax error.
```
crates/
plotnik-cli/ # CLI tool
src/commands/ # Subcommands (check, dump, infer, tree, langs)
src/commands/ # Subcommands (check, dump, exec, infer, trace, tree, langs)
plotnik-core/ # Common code (Interner, Symbol)
plotnik-lib/ # Plotnik as library
src/
analyze/ # Semantic analysis (symbol_table, dependencies, type_check, validation)
bytecode/ # Binary format definitions
typegen/ # Type declaration extraction (bytecode → .d.ts)
compile/ # Thompson NFA construction (AST → IR)
diagnostics/ # User-friendly error reporting
emit/ # Bytecode emission (IR → binary)
engine/ # Runtime VM (execution, backtracking, effects)
parser/ # Syntactic parsing (lexer, grammar, AST)
query/ # Query facade (Query, QueryBuilder, SourceMap)
type_system/ # Shared type primitives
typegen/ # Type declaration extraction (bytecode → .d.ts)
plotnik-langs/ # Tree-sitter language bindings
plotnik-macros/ # Proc macros
docs/
Expand All @@ -169,14 +170,15 @@ docs/

Run: `cargo run -p plotnik-cli -- <command>`

| Command | Purpose | Status |
| ------- | -------------------------- | ------- |
| `tree` | Explore tree-sitter AST | Working |
| `check` | Validate query | Working |
| `dump` | Show compiled bytecode | Working |
| `infer` | Generate TypeScript types | Working |
| `langs` | List supported languages | Working |
| `exec` | Execute query, output JSON | Not yet |
| Command | Purpose |
| ------- | ----------------------------- |
| `tree` | Explore tree-sitter AST |
| `check` | Validate query |
| `dump` | Show compiled bytecode |
| `infer` | Generate TypeScript types |
| `exec` | Execute query, output JSON |
| `trace` | Trace execution for debugging |
| `langs` | List supported languages |

## tree

Expand Down Expand Up @@ -220,6 +222,30 @@ cargo run -p plotnik-cli -- infer -q '(identifier) @id' -l typescript

Options: `--verbose-nodes`, `--no-node-type`, `--no-export`, `-o <FILE>`

## exec

Execute a query against source code and output JSON.

```sh
cargo run -p plotnik-cli -- exec query.ptk app.ts
cargo run -p plotnik-cli -- exec -q '(identifier) @id' app.ts # -q shifts positional to source
cargo run -p plotnik-cli -- exec -q '(identifier) @id' -s 'let x' -l javascript
```

Options: `--compact`, `--verbose-nodes`, `--check`, `--entry <NAME>`

## trace

Trace query execution for debugging.

```sh
cargo run -p plotnik-cli -- trace query.ptk app.ts
cargo run -p plotnik-cli -- trace -q '(identifier) @id' app.ts # -q shifts positional to source
cargo run -p plotnik-cli -- trace query.ptk app.ts --no-result -vv
```

Options: `-v` (verbose), `-vv` (very verbose), `--no-result`, `--fuel <N>`

## langs

List supported tree-sitter languages.
Expand Down
81 changes: 32 additions & 49 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,8 @@
<br/>

<p align="center">
Plotnik is a query language for source code.<br/>
Queries extract relevant structured data.<br/>
Transactions allow granular, atomic edits.
A type-safe query language for source code.<br/>
Query in, typed data out.
</p>

<br/>
Expand All @@ -28,7 +27,7 @@
<br/>

<p align="center">
⚠️ <a href="#roadmap">ALPHA STAGE</a>: not for production use ⚠️<br/>
⚠️ <a href="#status">ALPHA STAGE</a>: not for production use ⚠️<br/>
</p>

<br/>
Expand All @@ -38,7 +37,7 @@

Tree-sitter solved parsing. It powers syntax highlighting and code navigation at GitHub, drives the editing experience in Zed, Helix, and Neovim. It gives you a fast, accurate, incremental syntax tree for virtually any language.

The hard problem now is what comes _after_ parsing: extraction of meaning from the tree, and safe transformation back to source:
The hard problem now is what comes _after_ parsing: extracting structured data from the tree:

```typescript
function extractFunction(node: SyntaxNode): FunctionInfo | null {
Expand All @@ -57,7 +56,7 @@ function extractFunction(node: SyntaxNode): FunctionInfo | null {
}
```

Every extraction requires a new function, each one a potential source of bugs that won't surface until production. And once you've extracted what you need, applying changes back to the source requires careful span tracking, validation, and error handling—another layer of brittle code.
Every extraction requires a new function, each one a potential source of bugs that won't surface until production.

## The solution

Expand All @@ -81,8 +80,6 @@ interface FunctionInfo {

This structure is guaranteed by the query engine. No defensive programming needed.

Once extraction is complete, Plotnik will support **transactions** to apply validated changes back to the source. The same typed nodes used for extraction become targets for transformation—completing the loop from source to structured data and back to source.

## But what about Tree-sitter queries?

Tree-sitter already has queries:
Expand Down Expand Up @@ -138,7 +135,22 @@ Plotnik extends Tree-sitter's query syntax with:

## Language design

Plotnik builds on Tree-sitter's query syntax, extending it with the features needed for typed extraction:
Start simple—extract all function names from a file:

```clojure
Functions = (program
{(function_declaration name: (identifier) @name :: string)}* @functions)
```

Plotnik infers the output type:

```typescript
type Functions = {
functions: { name: string }[];
};
```

Scale up to tagged unions for richer structure:

```clojure
Statement = [
Expand Down Expand Up @@ -193,53 +205,24 @@ for (const stmt of result.statements) {

For the detailed specification, see the [Language Reference](docs/lang-reference.md).

## Supported Languages

Plotnik uses [arborium](https://github.com/bearcove/arborium), a batteries-included tree-sitter grammar collection with 60+ permissively-licensed languages out of the box.

## Roadmap

### Ignition: the parser ✓
## Documentation

The foundation is complete: a resilient parser that recovers from errors and keeps going.
- [CLI Guide](docs/cli.md) — Command-line tool usage
- [Language Reference](docs/lang-reference.md) — Complete syntax and semantics
- [Type System](docs/type-system.md) — How output types are inferred from queries
- [Runtime Engine](docs/runtime-engine.md) — VM execution model (for contributors)

- [x] Resilient parser
- [x] Rich diagnostics
- [x] Name resolution
- [x] Recursion validation
- [x] Structural validation

### Liftoff: type inference

The schema infrastructure is built. Type inference is next.

- [x] `node-types.json` parsing and schema representation
- [x] Proc macro for compile-time schema embedding
- [x] Statically bundled languages with node type info
- [x] Query validation against language schemas (unstable)
- [x] Type inference
## Supported Languages

### Acceleration: query engine
Plotnik bundles 15 languages out of the box: Bash, C, C++, CSS, Go, HTML, Java, JavaScript, JSON, Python, Rust, TOML, TSX, TypeScript, and YAML. The underlying [arborium](https://github.com/bearcove/arborium) collection includes 60+ permissively-licensed grammars—additional languages can be enabled as needed.

- [x] Runtime execution with backtracking cursor walker
- [x] Query IR
- [ ] Advanced validation powered by `grammar.json` (production rules, precedence)
- [ ] Match result API with typed accessors
## Status

### Orbit: developer experience
**Working now:** Parser with error recovery, type inference, query execution, CLI tools (`check`, `dump`, `infer`, `exec`, `trace`, `tree`, `langs`).

The CLI foundation exists. The full developer experience is ahead.
**Next up:** CLI distribution (Homebrew, npm), language bindings (TypeScript/WASM, Python), LSP server, editor extensions.

- [x] CLI framework with `debug`, `docs`, `langs`, `exec`, `types` commands
- [x] Query inspection: AST dump, symbol table, node arities, spans, transition graph, inferred types
- [x] Source inspection: Tree-sitter parse tree visualization
- [x] Execute queries against source code and output JSON (`exec`)
- [x] Generate TypeScript types from queries (`types`)
- [ ] CLI distribution: Homebrew, cargo-binstall, npm wrapper
- [ ] Compiled queries via Rust proc macros (zero-cost: query → native code)
- [ ] Language bindings: TypeScript (WASM), Python, Ruby
- [ ] LSP server: diagnostics, completions, hover, go-to-definition
- [ ] Editor extensions: VS Code, Zed, Neovim
⚠️ Alpha stage—API may change. Not for production use.

## Acknowledgments

Expand Down