Struct ResolvedJS 

pub struct ResolvedJS { /* private fields */ }

A successful resolution: the arena, the resolved AST, and the SemContext holding the results, owned together.

Produced by resolve, resolve_for_parser or resolve_for_compile, each of which consumes the ParsedJS it resolves. Read the tree with its semantic information through with_program, or dump both with to_sema_dump.

Not Send, for the same reason ParsedJS is not: the arena uses Cell/UnsafeCell and the GCLock guarding it is thread-local by design. (The name keeps the port’s ParsedJS casing rather than Rust’s ResolvedJs; that is deliberate, for consistency inside the port.)

Implementations

impl ResolvedJS

pub fn with_program<R, F>(&mut self, f: F) -> R

where F: for<'gc> FnOnce(&'gc GCLock<'static, '_>, &'gc Node<'gc>, &SemContext) -> R,

Run f with the arena locked, the resolved root node, and the SemContext in hand.

This is the read path. The SemContext comes along because that is the point of resolution: given an hermes_ast::node::Identifier in the tree, SemContext::get_expression_decl / SemContext::get_declaration_decl give the crate::ids::DeclId it binds to, and SemContext::decl gives that declaration.

References into the arena cannot escape the closure — their lifetime ends with the lock — so return owned data instead. The one thing that can escape is a NodeRc, which is refcounted rather than borrowed; dropping this ResolvedJS while such a handle is still alive panics inside Context::drop.

The bound is higher-ranked because Node is invariant in its lifetime: a walker (hermes_ast::visitor::Visitor) needs the node reference and the node’s own lifetime to be the same 'gc, which only a for<'gc> closure can promise. A visitor that keeps the &GCLock in a field must give the lock its own lifetime parameters rather than reusing 'gc — GCLock<'ast, 'ctx> is invariant in 'ast, so the two cannot be equated; crates/sema/examples/print_bindings.rs shows the pattern and the error it avoids.

Why &mut self for a read

This locks the arena, and Context::lock takes &mut self: the GCLock holds a &mut Context, which is what stops Context::gc — the mark-and-sweep that would invalidate every outstanding &Node — from running while the tree is being read. &mut therefore means “exclusive view of the arena”, not “the AST or the SemContext is modified”; the SemContext is in fact handed to f as &. To share results, collect owned data inside the closure. (sem_context needs no lock and does take &self.)

Panics

Panics if another GCLock is active on this thread — in particular if with_program is called from inside another with_program.

Examples found in repository

examples/resolve_and_dump.rs (lines 121-129)

fn print_summary(resolved: &mut ResolvedJS) {
    use hermes_parser::ast::node::Node;
    use hermes_parser::ast::visitor::Visitor;

    /// Counts identifier *expressions* by whether they resolved.
    struct Counter<'a> {
        sem: &'a hermes_sema::sem_context::SemContext,
        resolved: usize,
        unresolved: usize,
    }
    impl<'gc> Visitor<'gc> for Counter<'_> {
        fn visit_node(&mut self, node: &'gc Node<'gc>) {
            if let Node::Identifier(id) = node {
                match self.sem.get_expression_decl(id) {
                    Some(_) => self.resolved += 1,
                    None => self.unresolved += 1,
                }
            }
            node.visit_children(self);
        }
    }

    let (resolved_ids, unresolved_ids) =
        resolved.with_program(|_gc, root, sem| {
            let mut c = Counter {
                sem,
                resolved: 0,
                unresolved: 0,
            };
            c.visit_node(root);
            (c.resolved, c.unresolved)
        });

    let sem = resolved.sem_context();
    println!("functions:            {}", sem.functions_len());
    println!("resolved references:  {resolved_ids}");
    println!("other identifiers:    {unresolved_ids}");
}

examples/print_bindings.rs (lines 166-174)

fn main() {
    let (name, source) = match std::env::args().nth(1) {
        Some(path) => match std::fs::read_to_string(&path) {
            Ok(s) => (path, s),
            Err(e) => {
                eprintln!("print_bindings: cannot read '{path}': {e}");
                std::process::exit(1);
            }
        },
        None => ("<builtin>".to_string(), SOURCE.to_string()),
    };

    // Step 1: parse. `ParseFlags::default()` is plain ECMAScript.
    let parsed = match parse_named(&source, &name, ParseFlags::default()) {
        Ok(parsed) => parsed,
        Err(e) => {
            // `messages()` strings are already newline-terminated.
            for m in e.messages() {
                eprint!("{m}");
            }
            std::process::exit(2);
        }
    };

    // Step 2: resolve. The compile path, so the standard globals exist and an
    // undeclared `console` comes back as `UndeclaredGlobalProperty` rather
    // than as nothing at all; `hermes_sema::resolve` is the parser path.
    let mut resolved =
        match resolve_for_compile(parsed, &CompileOptions::default()) {
            Ok(resolved) => resolved,
            Err(e) => {
                for m in e.messages() {
                    eprint!("{m}");
                }
                std::process::exit(2);
            }
        };

    // Step 3: walk. References into the arena die with the lock, so the
    // visitor collects owned `String`s and hands them back out.
    let rows = resolved.with_program(|gc, root, sem| {
        let mut printer = BindingPrinter {
            gc,
            sem,
            rows: Vec::new(),
        };
        printer.visit_node(root);
        printer.rows
    });

    println!("{}: {} identifiers", name, rows.len());
    for (name, role, binding) in rows {
        println!("  {name:<12} {role:<5} {binding}");
    }
}

pub fn sem_context(&self) -> &SemContext

The resolution results, for the queries that do not need the AST — walking the scope tree, or reading a FunctionInfo reached from a crate::ids::FunctionInfoId obtained inside with_program.

Examples found in repository

examples/resolve_and_dump.rs (line 131)

fn print_summary(resolved: &mut ResolvedJS) {
    use hermes_parser::ast::node::Node;
    use hermes_parser::ast::visitor::Visitor;

    /// Counts identifier *expressions* by whether they resolved.
    struct Counter<'a> {
        sem: &'a hermes_sema::sem_context::SemContext,
        resolved: usize,
        unresolved: usize,
    }
    impl<'gc> Visitor<'gc> for Counter<'_> {
        fn visit_node(&mut self, node: &'gc Node<'gc>) {
            if let Node::Identifier(id) = node {
                match self.sem.get_expression_decl(id) {
                    Some(_) => self.resolved += 1,
                    None => self.unresolved += 1,
                }
            }
            node.visit_children(self);
        }
    }

    let (resolved_ids, unresolved_ids) =
        resolved.with_program(|_gc, root, sem| {
            let mut c = Counter {
                sem,
                resolved: 0,
                unresolved: 0,
            };
            c.visit_node(root);
            (c.resolved, c.unresolved)
        });

    let sem = resolved.sem_context();
    println!("functions:            {}", sem.functions_len());
    println!("resolved references:  {resolved_ids}");
    println!("other identifiers:    {unresolved_ids}");
}

pub fn to_sema_dump(&mut self) -> Vec<u8>

Dump the SemContext and the annotated AST as text, through crate::dump::sem_dump — the -dump-sema format, byte-for-byte. (After resolve_for_compile this is exactly what hermesc -dump-sema prints for the same input; that differential is this crate’s correctness gate. After the parser path it is the same format over the differently-resolved tree, which is what the C++ sema-parser-dump tool prints.)

Bytes rather than a String because an identifier in the source may be an unpaired surrogate, which the dumper writes out as WTF-8 — not valid UTF-8. For ordinary sources String::from_utf8 succeeds.

Takes &mut self although it only reads, for the reason with_program documents: dumping locks the arena, and taking the lock needs exclusive access to the Context.

Panics

Takes the arena lock, so it panics if another GCLock is live on this thread — in particular when called from inside with_program.

Examples found in repository

examples/resolve_and_dump.rs (line 90)

fn main() -> ExitCode {
    let mut args = std::env::args().skip(1);
    let mut summary = false;
    let mut path = None;
    for arg in args.by_ref() {
        match arg.as_str() {
            "--summary" => summary = true,
            _ => path = Some(arg),
        }
    }
    let Some(path) = path else {
        eprintln!("usage: resolve_and_dump [--summary] <file.js>");
        return ExitCode::from(1);
    };

    let source = match std::fs::read_to_string(&path) {
        Ok(s) => s,
        Err(e) => {
            eprintln!("resolve_and_dump: cannot read '{path}': {e}");
            return ExitCode::from(1);
        }
    };

    // Step 1: parse. `ParseFlags::default()` is plain ECMAScript; set
    // `parse_flow`, `parse_ts` or `parse_jsx` for the other dialects.
    let parsed = match parse_named(&source, &path, ParseFlags::default()) {
        Ok(parsed) => parsed,
        Err(e) => {
            for m in e.messages() {
                eprint!("{m}");
            }
            return ExitCode::from(2);
        }
    };

    // Step 2: resolve. The compile path, with the standard globals declared —
    // what `hermesc -dump-sema` does. `hermes_sema::resolve` is the parser
    // path instead: no ambient declarations and no AST rewrites.
    let options = CompileOptions::default();
    let mut resolved = match resolve_for_compile(parsed, &options) {
        Ok(resolved) => resolved,
        Err(e) => {
            for m in e.messages() {
                eprint!("{m}");
            }
            return ExitCode::from(2);
        }
    };

    // Warnings, if any: resolution succeeded, so none of these is an error.
    for d in resolved.diagnostics() {
        eprintln!("{}:{}:{}: {}", d.file_name, d.line, d.col, d.message);
    }

    // Step 3: read the result.
    if summary {
        print_summary(&mut resolved);
    } else {
        // Bytes, not a `String`: an identifier can be an unpaired surrogate,
        // which the dumper writes as WTF-8.
        let dump = resolved.to_sema_dump();
        std::io::stdout().write_all(&dump).expect("write failed");
    }
    ExitCode::SUCCESS
}

pub fn diagnostics(&self) -> &[ResolvedDiagnostic]

The diagnostics recorded so far, in emission order: the parse’s (which were warnings and notes, since the parse succeeded) followed by resolution’s.

For a ResolvedJS that came out of resolve or resolve_for_compile these are again warnings and notes only; resolve_for_parser can return one carrying errors — see its doc. Render one with hermes_support::render::render_diagnostic.

Examples found in repository

examples/resolve_and_dump.rs (line 80)

fn main() -> ExitCode {
    let mut args = std::env::args().skip(1);
    let mut summary = false;
    let mut path = None;
    for arg in args.by_ref() {
        match arg.as_str() {
            "--summary" => summary = true,
            _ => path = Some(arg),
        }
    }
    let Some(path) = path else {
        eprintln!("usage: resolve_and_dump [--summary] <file.js>");
        return ExitCode::from(1);
    };

    let source = match std::fs::read_to_string(&path) {
        Ok(s) => s,
        Err(e) => {
            eprintln!("resolve_and_dump: cannot read '{path}': {e}");
            return ExitCode::from(1);
        }
    };

    // Step 1: parse. `ParseFlags::default()` is plain ECMAScript; set
    // `parse_flow`, `parse_ts` or `parse_jsx` for the other dialects.
    let parsed = match parse_named(&source, &path, ParseFlags::default()) {
        Ok(parsed) => parsed,
        Err(e) => {
            for m in e.messages() {
                eprint!("{m}");
            }
            return ExitCode::from(2);
        }
    };

    // Step 2: resolve. The compile path, with the standard globals declared —
    // what `hermesc -dump-sema` does. `hermes_sema::resolve` is the parser
    // path instead: no ambient declarations and no AST rewrites.
    let options = CompileOptions::default();
    let mut resolved = match resolve_for_compile(parsed, &options) {
        Ok(resolved) => resolved,
        Err(e) => {
            for m in e.messages() {
                eprint!("{m}");
            }
            return ExitCode::from(2);
        }
    };

    // Warnings, if any: resolution succeeded, so none of these is an error.
    for d in resolved.diagnostics() {
        eprintln!("{}:{}:{}: {}", d.file_name, d.line, d.col, d.message);
    }

    // Step 3: read the result.
    if summary {
        print_summary(&mut resolved);
    } else {
        // Bytes, not a `String`: an identifier can be an unpaired surrogate,
        // which the dumper writes as WTF-8.
        let dump = resolved.to_sema_dump();
        std::io::stdout().write_all(&dump).expect("write failed");
    }
    ExitCode::SUCCESS
}

pub fn error_count(&self) -> u32

How many of the recorded diagnostics are errors.

Zero for a ResolvedJS from resolve or resolve_for_compile. This is the check the C++ resolveASTForParser callers make instead of looking at a return value, so it is what resolve_for_parser’s result must be tested with.

pub fn source_manager(&self) -> &SourceErrorManager

The source manager owning the parsed buffer (and the libhermes buffer, if CompileOptions::std_globals was on), for coordinate lookups and for driving the AST dumper by hand.

pub fn into_parsed(self) -> ParsedJS

Give back the ParsedJS, now holding the resolved AST, and drop the SemContext.

This is how the rest of the parser façade’s surface — ESTree JSON dumping in particular, which is what a resolve-then-serialize consumer like hermes-parser-wasm does — stays reachable after resolution without this type mirroring it method for method. The AST keeps every rewrite the resolver made; only the Decl/scope tables go away.

Trait Implementations

impl Debug for ResolvedJS

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Summarizes rather than printing the AST or the tables, which can be huge. (Hand-written because neither ParsedJS nor SemContext derives Debug.)