meta-ast 0.3.0

meta-ast is a fast, standalone static analysis engine that parses multi-language projects, builds symbol-level dependency graphs, detects cyclic imports, and generates MetaCall deployment manifests. Written in Rust, powered by tree-sitter, with no runtime execution of user code.

Built as part of Google Summer of Code 2026 for the MetaCall organization by Khaled Alam.

Supports 8 languages: Python, JavaScript, TypeScript, TSX, C, C++, Rust, Go.

Quick start

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

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 8 languages with one tool. Python, JavaScript, TypeScript, TSX, C, C++, Rust, and Go 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.
• Cyclic dependency guard. Run meta-ast graph in CI to fail builds that introduce accidental import cycles.
• Deployment planning for MetaCall / Function Mesh. 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.
• Documentation & visualization. Emit an interactive Cytoscape.js dashboard (--html, loaded from a CDN and cached by the browser) 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.

meta-ast inspect <path> [-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.

meta-ast graph <path> [-f json|yaml] [-o graph.json]
meta-ast graph <path> --html                    # interactive Cytoscape.js dashboard (CDN, browser-cached)

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.

cargo build --release --features metacall-deploy

meta-ast deploy <path> --out ./out      # generate manifests
meta-ast deploy <path> --check          # CI validation: verify every cut edge has an RPC stub

Generates two artifacts:

See docs/DEPLOY.md for scanner details, confidence scoring, pod partitioning, manifest schema, and the fairness check used in CI.

Documentation

Roadmap

• Phase 4 (In Progress): Watch mode, incremental analysis, C ABI.
• Phase 5 (Complete): metacall-deploy - call-site scanning, pod partitioning, dependency resolution, pod manifests, Function Mesh annotation, fairness checking.
• Phase 6 (Planned): Language expansion (C#, Java).

Full details in docs/ROADMAP.md.

Benchmarking

Performance is measured with criterion via two 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).

Run them locally:

cargo bench                                    # all suites
cargo bench --bench pipeline                   # extraction only
cargo bench --bench graph -- --plotting-backend=plotters

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