<div align="center">
<img src="docs/src/assets/metast.png" alt="meta-ast Logo" width="400">
<p align="center"><strong>Standalone static analysis and dependency graph generator for polyglot source trees</strong></p>
</div>
---
[](https://summerofcode.withgoogle.com/)
[](https://crates.io/crates/meta-ast)
[](https://metacall.github.io/meta-ast/)
[](https://github.com/metacall/meta-ast/actions/workflows/ci.yml)
`meta-ast` is a fast, standalone, general-purpose static analysis engine that parses multi-language projects, builds symbol-level dependency graphs, detects cyclic imports, and serves as the semantic foundation for polyglot developer tooling (LSP servers, security analyzers, and deployment orchestration). Written in Rust, powered by tree-sitter, with zero runtime execution of user code.
Built as part of **Google Summer of Code 2026** for the **MetaCall** organization by **[Khaled Alam](https://github.com/k5602)**. Project status: complete. See the [Final Report](docs/src/FINAL_REPORT.md).
Supports **9 languages**: Python, JavaScript, TypeScript, TSX, C, C++, Rust, Go, Ruby.
---
## Quick start
```bash
# Requires Rust toolchain - https://rustup.rs
git clone https://github.com/metacall/meta-ast.git
cd meta-ast
cargo build --release
```
The binary is at `./target/release/meta-ast`.
---
## Installation
### From crates.io (recommended)
`meta-ast` is published to [crates.io](https://crates.io/crates/meta-ast). With a
Rust toolchain installed, install the latest release in one command:
```bash
cargo install meta-ast
```
This installs the core analyzer (`inspect` and `graph` subcommands). To also
enable the MetaCall deployment manifest generator (`deploy` subcommand), install
with the `metacall-deploy` feature:
```bash
cargo install meta-ast --features metacall-deploy
```
The binary lands at `~/.cargo/bin/meta-ast` (on your `PATH` if cargo's bin dir is
configured). No external services, network calls, or runtime execution of your
code are involved.
### From source
```bash
git clone https://github.com/metacall/meta-ast.git
cd meta-ast
cargo build --release # core only
# or, with the deploy module:
cargo build --release --features metacall-deploy
```
The binary is at `./target/release/meta-ast`.
---
## Goals
`meta-ast` exists to give polyglot codebases a single, fast, language-agnostic
view of their structure without executing any user code. Its objectives:
- **Parse 9 languages with one tool.** Python, JavaScript, TypeScript, TSX, C,
C++, Rust, Go, and Ruby flow through a uniform tree-sitter pipeline. A mixed
Python/JS/Rust project is one graph, not three glued together.
- **Normalize to a stable IR.** Every declaration becomes a `Symbol` with a
consistent shape and a stable JSON/YAML output contract. Downstream tooling
consumes results without caring about the source language.
- **Surface deployment structure.** Cross-file dependency graphs plus Tarjan
SCC reveal cyclic import clusters and independent units. These feed the
MetaCall Function Mesh deployment model via pod-based manifests.
- **Recover, never abort.** Partial or malformed trees are parsed as far as
possible and any parse/extraction gaps are accumulated as diagnostics. A
broken file never takes down the whole analysis.
- **Stay standalone and safe.** No runtime execution of target code, no network,
no external services. Pure static analysis driven by CLI or library API.
---
## Scope
**In scope:**
- Syntactic symbol extraction (functions, classes, objects, methods, structs,
enums, interfaces, namespaces) and their visibility/doc metadata.
- Cross-file import resolution, reference resolution, and dependency graph
assembly with confidence-weighted edges.
- Cyclic-import detection (Tarjan SCC) and deployment-unit classification.
- MetaCall pod-based deployment manifest generation (`metacall.pods.json`) and
Function Mesh annotation (`metacall.mesh.json`) behind the `metacall-deploy`
feature.
- External dependency resolution: per-language lockfile/manifest parsing to
pin dependencies with exact versions.
- Single-snapshot analysis of a directory tree via CLI or `analyze_graph`.
---
## Use cases
- **Architecture review & onboarding.** Get a normalized map of every symbol and
its dependencies across a polyglot repo to understand structure quickly.
Run `meta-ast inspect` on a checkout and read the JSON/YAML, or open the
interactive dashboard from `meta-ast graph --html`.
- **CI gate.** `meta-ast graph` exits 1 when the run reports an error
diagnostic, 2 for a usage or configuration problem, and 0 otherwise. Pass
`--fail-on warning` to fail on warnings as well, or `--fail-on never` to
always exit 0. Import cycles surface as cyclic clusters in the output and in
the deployability hints, and they are not errors by themselves.
- **Dependency-graph diffing & refactors.** Before splitting a module or
deleting a package, generate the graph and confirm what actually depends on
it across languages - catch hidden cross-language coupling a grep would miss.
- **Pre-commit / code-review signal.** Emit the graph or inspect output as a
PR artifact so reviewers see structural impact (new symbols, new edges) rather
than reading diffs blind.
- **Deployment planning for MetaCall / Function Mesh.** With the `metacall-deploy`
feature, the `deploy` subcommand turns detected cross-language
`metacall_load_from_*` call sites and SCC units into manifests that drive
co-deployment vs. independent-function decisions. Requires the feature-enabled
install (`cargo install meta-ast --features metacall-deploy`).
- **Documentation & visualization.** Emit an interactive Cytoscape.js dashboard
(`--html`, self-contained: the vendored bundle travels inside the document, so
it renders offline) to explore ownership, references, and deployment units
visually.
- **Library integration.** Consume `meta-ast` as a crate: `analyze_graph`
returns a `GraphAnalysis` (`CodeGraph` + `SccAnalysis`) for custom tooling,
linters, or report generators.
---
## Subcommands
### `inspect`
Extracts all function, class, and object declarations from a codebase.
```bash
meta-ast inspect <path> [-l language] [-f json|yaml] [-o output.json]
```
### `graph`
Builds the cross-file dependency graph, resolves imports, and runs Tarjan SCC to identify cyclic clusters and independent deployment units.
```bash
meta-ast graph <path> [-l language] [-f json|yaml] [-o graph.json]
meta-ast graph <path> --html # interactive Cytoscape.js dashboard (self-contained, <path>.html)
meta-ast graph <path> --html --open # write the dashboard and open it in the browser
meta-ast graph <path> --datagraph # export detailed datagraph.json (requires --features dataflow)
meta-ast graph <path> --datagraph --datagraph-output dg.json # choose the datagraph path
meta-ast graph <path> --watch # watch mode: continuous re-analysis on file changes (requires --features watch)
`--datagraph`, `--datagraph-output`, `--watch`, `--watch-debounce` and the `deploy`
subcommand are compiled in only when their feature is enabled. A build without the
feature rejects the flag at argument parsing with exit status 2, so the CLI surface
depends on the feature set of the installed binary.
meta-ast graph <path> --watch --watch-debounce 100 --html -o graph.html
```
`--watch` enters a debounced watch loop: on each file change, only changed files
are re-extracted using BLAKE3 cryptographic content fingerprinting (unchanged files reuse cached `Arc` extractions), then the graph + SCC
are rebuilt. Snapshot IDs increment with each re-analysis tick. Requires
`cargo install meta-ast --features watch` (or `cargo build --features watch`).
### `deploy` *(requires `--features metacall-deploy`)*
Scans for cross-language `metacall_load_from_*` call sites, resolves external dependencies from lockfiles and package manifests, partitions files into same-language pods, and generates deployment artifacts.
```bash
cargo build --release --features metacall-deploy
meta-ast deploy <path> [-f json|yaml] [-o ./out] # generate manifests
meta-ast deploy <path> --check # CI validation: verify every cut edge has an RPC stub
```
Generates two artifacts:
| `metacall.pods.json` | Pod manifest: language-based deployment units, inter-pod edges with confidence scores, per-pod dependency lists with pinned versions, and AST node metrics |
| `metacall.mesh.json` | SCC-derived Function Mesh topology annotation with cross-language call-site attribution |
See [docs/src/DEPLOY.md](docs/src/DEPLOY.md) for scanner details, confidence scoring, pod partitioning, manifest schema, and the fairness check used in CI.
---
## Documentation
| [docs/src/DEMO.md](docs/src/DEMO.md) | Recorded walkthroughs of every subcommand (GIFs) |
| [docs/src/BENCHMARKS.md](docs/src/BENCHMARKS.md) | Criterion benchmark results |
| [docs/src/FINAL_REPORT.md](docs/src/FINAL_REPORT.md) | GSoC 2026 completion report |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to build, test, and submit changes |
| [docs/src/ARCHITECTURE.md](docs/src/ARCHITECTURE.md) | High-level pipeline and component boundaries |
| [docs/src/STRUCTURE.md](docs/src/STRUCTURE.md) | Module layout, data structures, design patterns |
| [docs/src/DEPLOY.md](docs/src/DEPLOY.md) | Deploy module: scanner, manifests, mesh annotation |
| [docs/src/ROADMAP.md](docs/src/ROADMAP.md) | Phase-by-phase delivery plan |
| [docs/src/adr/](docs/src/adr/) | Architecture Decision Records |
| [docs/src/rfcs/](docs/src/rfcs/) | Design RFCs |
| [docs/src/specs/](docs/src/specs/) | Requirements and traceability |
All docs are also published as an [mdbook site](https://metacall.github.io/meta-ast/).
---
## Roadmap
The core GSoC 2026 milestones (Phases 1-7) are complete with release `v0.7.0`. Full details and post-v1 initiatives are tracked in [docs/src/ROADMAP.md](docs/src/ROADMAP.md).
### Post-v1 Active Roadmap
- **Phase 8 (In Progress)**: Polyglot LSP Server & Shard Indexing (`metacall/lsp`) - RFC 0012 seams, in-memory buffers, and `.metast` v2 persistence.
- **Phase 9 (Planned)**: Engine Refactoring & Graph Reuse - zero-allocation resolver dispatch, language pack macros, and modular `DeployOrchestrator`.
- **Phase 10 (Planned)**: Polyglot Security & Taint Flow Analysis (SAST) - cross-language vulnerability detection, CWE mapping, and SARIF output.
- **Phase 11 (In Progress)**: Developer Ecosystem & Community Tooling - cross-platform installers, property-based test suites (`proptest`), and curated contributor issues.
- **Phase 12 (Strategic)**: Deep Expression AST & Control-Flow Representation - statement nodes, operator trees, and intra-procedural CFGs.
- **Phase 13 (Strategic)**: Polyglot Code Transformation & Refactoring Engine - lossless CST rewriting, cross-language atomic symbol renaming, and automated codegen.
---
## Benchmarking
Performance is measured with [criterion](https://github.com/japaric/criterion.rs)
via three benchmark suites (`harness = false`):
- `benches/pipeline.rs` - end-to-end extraction across the per-language fixtures
(python, javascript, typescript, tsx, rust, go, c, cpp, mixed).
- `benches/graph.rs` - graph construction, Tarjan SCC on varied topologies
(acyclic chains, single/multiple cycles, dense graphs), edge deduplication,
and node lookup at scale (up to 10k nodes / 10k duplicates).
- `benches/incremental.rs` - cold vs warm incremental re-analysis after file modifications
(requires `--features watch`).
Run them locally:
```bash
cargo bench # all suites
cargo bench --bench pipeline # extraction only
cargo bench --bench graph -- --plotting-backend=plotters
cargo bench --bench incremental --features watch # incremental watch benchmark
```
Benchmarks run on the fixture corpus under `tests/fixtures/`, so results scale
with that corpus. Typical wall-clock figures (your hardware will vary):
- Per-language extraction of the fixture set completes in low milliseconds.
- SCC and node lookup stay sub-millisecond into the thousands-of-nodes range;
edge deduplication is linear in the duplicate count.
For reproducible CI numbers, pin the toolchain (MSRV 1.94.0) and run on a
quiet machine; criterion reports mean/stddev and supports `--save-baseline` for
regression tracking.
---
## License
Apache License, Version 2.0. See `LICENSE` for details.