big-code-analysis-ast 2.6.0

Parse and classification layer behind big-code-analysis (internal, version-locked)
Documentation
//! Mozjs's role rows. The Halstead keyword roles (#1693), the
//! paying-construct roles — `Comparison`, `ShortCircuit`, `EagerLogical`,
//! `Ternary`, `CaseArm`, `Guard`, `NullSafe` (#1694, #1695) — the space
//! tree (#1696) and the control flow — `Branch`, `Switch`, `Loop`,
//! `Catch`, `ElseIf`, `Exit` (#1697) — and
//! the documentation rows (#1699) are declared.

use crate::Mozjs;
use crate::role_table;
use crate::roles::control_flow::else_if_parent_clause_gate;
use crate::roles::js_family::{
    js_doc_gates, js_family_binding_gates, js_family_closures, js_family_comparison_payers,
    js_family_containers, js_family_decl_keywords, js_family_doc_gates, js_family_doc_targets,
    js_family_exits, js_family_func_openers, js_family_loops, js_family_modifiers,
    js_family_short_circuit_payers, js_family_strings,
};

// The chained `if` sits directly inside an `else_clause`; a nested one
// under `else { … }` sits inside the statement block (#1697).
else_if_parent_clause_gate!(Mozjs, ElseClause);
js_family_binding_gates!(Mozjs, MozjsCode, FieldDefinition);

// The documentation gates, per dialect (#1699): JSDoc ignores `/***`; Mozilla's JavaScript follows it.
js_family_doc_gates!(Mozjs, javadoc_block);
js_doc_gates!(Mozjs);

role_table! {
    lang: Mozjs;
    // As JavaScript's: the second `call_expression` id is the never
    // emitted decorator alias, listed defensively.
    Call { owns [CallExpression, CallExpression2] }
    // `String2` is MozJS's anonymous string-*literal* alias (the same
    // production as JS's, e.g. `import "m"` module strings), a string
    // alongside `String` (#283).
    StringLit { owns [..js_family_strings!(), String2] wraps [TemplateSubstitution] }
    // The one `binary_expression` kind carries every binary operator;
    // its `operator` field says which, so each row's owner holds its
    // payer (`roles/js_family.rs` has the lists). `??` is `NullSafe`'s
    // and `&&=` / `||=` are assignments.
    Comparison {
        owns [BinaryExpression(holds_payer)]
        pays [..js_family_comparison_payers!()]
        project "operator"
    }
    ShortCircuit {
        owns [BinaryExpression(holds_payer)]
        pays [..js_family_short_circuit_payers!()]
        project "operator"
    }
    EagerLogical { absent "JavaScript's `&` / `|` / `^` are bitwise" }
    // The `ternary_expression` owns it and its `?` pays, ungated: the
    // JavaScript grammars spell the bare token nowhere else, and a `?`
    // error recovery strands under an `ERROR` (`let c = a ?` at end of
    // input) has always paid (the TypeScript grammars gate theirs, for
    // the ten type productions `roles/js_family.rs` names).
    Ternary {
        owns [TernaryExpression]
        pays [QMARK]
        project "operator"
    }
    // Two structural forms, each one decision per token (#281, #248):
    // the null coalescing `a ?? b`, a `binary_expression` owned through
    // its `operator` field, and the optional chain `a?.b` / `a?.[0]` /
    // `a?.()`, whose `?.` the JavaScript grammars emit as the bare
    // `optional_chain` token (no wrapper) — the TypeScript grammars wrap
    // it, and their rows say so. The compound `??=` is an
    // `augmented_assignment_expression`, not a `binary_expression`: it
    // stays the consumers' own, recorded here as considered.
    NullSafe {
        owns [BinaryExpression(holds_payer)]
        pays [QMARKQMARK, OptionalChain]
        project "operator"
        excludes [QMARKQMARKEQ "the compound `??=`, an assignment ABC pays as one and a decision cyclomatic pays as its own (#236, #248)"]
    }
    // A `switch_case` owns a decision and its `case` keyword pays; the
    // `switch_default` and its `default` keyword are the fallback and
    // pay nothing (lesson 11, #469).
    CaseArm {
        owns [SwitchCase(holds_payer)]
        pays [Case]
        excludes [
            SwitchDefault "the fallback arm, no decision (lesson 11, #469)",
            Default "the fallback label's keyword",
        ]
    }
    Guard { absent "JavaScript has no guard clause" }
    // The JS family's control flow (#1697): the one-kind rows are spelled
    // inline, the loop and exit lists are fragments of
    // `roles/js_family.rs`, and no dialect has an extra — the four
    // grammars share the shape and differ only in kind ids. The `ElseIf`
    // gate is emitted beside this table.
    Branch { owns [IfStatement] pays [If] }
    Switch { owns [SwitchStatement] }
    Loop { owns [..js_family_loops!()] pays [For, While] }
    Catch { owns [CatchClause] pays [Catch] }
    ElseIf { owns [IfStatement(gated_by continues_else_clause)] pays [] }
    Exit { owns [..js_family_exits!()] }
    // The shared JS-family `static` (`roles/js_family.rs`) plus
    // `Staticget`, one token spelling `static get` followed by a
    // newline — the static getter whose name starts the next line —
    // which these two grammars alone have. It is billed beside `static`
    // (#1563) so that form bills a modifier rather than nothing; being
    // one node it is one operator.
    Modifier { owns [..js_family_modifiers!(), Staticget] }
    DeclKeyword { owns [..js_family_decl_keywords!()] }
    Primitive { absent "JavaScript has no type names" }
    // The shared JS-family openers, closures and containers
    // (`roles/js_family.rs`); the binding gates are emitted above, with
    // this grammar's class-field kind.
    FuncOpener { owns [..js_family_func_openers!()] }
    Closure { owns [..js_family_closures!()] }
    Container { owns [..js_family_containers!()] }
    // A class field (`x = v;`); one whose initialiser is a function is
    // a method written as a field, which the consumers tell apart
    // themselves — the row recognises the declaration, the consumer
    // reads its value.
    Member { owns [FieldDefinition] }
    // The two comment kinds — a `/* */` or `//` `comment` and the Annex-B
    // `<!-- -->` `html_comment` (#697); only the first can open with the
    // tool's block marker (#1699).
    Comment { owns [Comment, HtmlComment] }
    DocComment { owns [Comment(text_gated_by opens_with_doc_block_marker no_chain)] }
    Docstring { absent "JavaScript documents with JSDoc comments, not string literals" }
    // What JSDoc's `astnode.getInfo` names: the family fragment, plus an
    // export other than a bare `export { … }` list and an expression
    // statement assigning to a name or a member. Every target but the
    // class, method and field is outside the space-tree rows — the
    // parity exceptions `roles/doc_tests/parity.rs` records.
    DocTarget {
        owns [
            ..js_family_doc_targets!(),
            UsingDeclaration(gated_by first_declarator_binds_a_name no_chain),
            FieldDefinition,
            ExportStatement(gated_by export_declares no_chain),
            ExpressionStatement(gated_by assigns_to_a_name_or_member no_chain),
        ]
    }
    DocRunOpener { absent "JSDoc attaches every doc comment to a declaration or a named symbol; none documents by its own content" }
    DocRunDirective { absent "JSDoc reads no directive comment" }
    // Nothing beyond the callables and the closures: JSDoc documents
    // inner symbols (`outer~inner`), so a doc comment in a body stays
    // documentation (`DOC_COMMENTS_IN_FUNCTION_BODIES`, #1597), and which
    // child is the body — a statement block, an arrow's expression — is
    // the Checker's body-child test, not a kind.
    DocBodyResidual { absent "only the callables and closures hold a doc comment in a body; the body-child test is the Checker's" }
}