hermes_ast/
lib.rs

1#![warn(missing_docs)]
2//! Hermes ESTree AST — GC arena (juno-derived) + node model.
3//!
4//! The node set in [`node`] is generated from
5//! `include/hermes/AST/ESTree.def` with every parse family enabled — Flow,
6//! TypeScript, JSX, and the parser's "cover" grammar nodes — so a single
7//! [`node::Node`] enum spans all of them.
8//!
9//! The pieces a consumer touches:
10//! - [`context::Context`] and [`context::GCLock`] — the arena that owns the
11//!   nodes and the lock through which they are allocated and read.
12//! - [`node::Node`] — one enum arm per node kind, over `#[repr(C)]` structs
13//!   whose fields mirror the `.def` entry: structural children are `&'gc`
14//!   references or [`node_child::NodeList`]s, everything else is a `Cell`.
15//! - [`visitor::VisitorMut`] plus `Node::visit_children_mut` — transforms
16//!   that rebuild only the spine whose children changed.
17//! - [`dump::ESTreeJSONDumper`] — ESTree JSON matching
18//!   `hermesc -dump-ast -dump-source-location=both` byte for byte.
19//!
20//! See `rust/ARCHITECTURE.md` for the design rationale and
21//! doc/superpowers/specs/2026-06-03-ast-design.md for the port spec.
22
23pub mod context;
24pub mod dump;
25pub mod node;
26pub mod node_child;
27pub mod visitor;
28
29pub use hermes_support::HeapSize;
30
31/// Opaque handle to a resolved Sema entity (scope / decl / function info).
32/// The AST only stores the raw index in a `Cell`; the `sema` crate wraps it
33/// in the typed newtypes of its `ids` module and owns the interpretation.
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub struct SemaId(pub u32);
36
37/// Unique, never-reused identity of an AST node within its `Context`.
38/// Assigned by `Context::alloc` from a monotonic counter (starting at 1);
39/// `UNASSIGNED` (0) only exists on metadata not yet stored in the arena.
40/// Consumers outside sema key side tables by NodeId (see the Sema design
41/// spec §3.1): unlike raw addresses, ids never alias after arena slot
42/// reuse; unlike NodeRc keys, they don't pin garbage. Insert entries only
43/// with the node in hand under GCLock — a stored id may already be dead.
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
45pub struct NodeId(pub u32);
46
47impl NodeId {
48    /// The id of a node that is not (yet) stored in the arena. Never returned
49    /// by `Context::alloc`, whose counter starts at 1.
50    pub const UNASSIGNED: NodeId = NodeId(0);
51}
hermes_ast/lib.rs

hermes_ast/
lib.rs
