rubydex 0.2.4-aarch64-linux → 0.2.5-aarch64-linux

data/rust/rubydex/src/operation/mod.rs

@@ -0,0 +1,284 @@
+//! Operations represent the ordered actions extracted from Ruby/RBS source code.
+//!
+//! Unlike definitions (which are unordered and declarative), operations are ordered and imperative.
+//! They model what Ruby actually does at execution time: define a class, define a method, change
+//! visibility, include a module, etc.
+//!
+//! Each operation is self-contained: it carries enough context (`name_id`, etc.) to know what it
+//! defines, while scope context is provided by surrounding Enter/Exit scope operations.
+//!
+//! The builder produces a `Vec<Operation>` for each file. These operations are then applied in order
+//! by the applier to produce definitions and declarations in the graph.
+//!
+//! # Example
+//!
+//! ```ruby
+//! class Foo
+//!   def bar; end
+//!   private :bar
+//! end
+//! ```
+//!
+//! Produces the operations:
+//! 1. `EnterClass` (name: Foo)
+//! 2.   `EnterMethod` (name: bar)
+//! 3.   `ExitScope` # exit method bar
+//! 4.   `SetMethodVisibility` (name: bar, visibility: private)
+//! 5. `ExitScope` # exit class Foo
+
+pub mod applier;
+pub mod printer;
+pub mod ruby_builder;
+
+use crate::model::{
+    comment::Comment,
+    definitions::{DefinitionFlags, Signatures},
+    ids::{NameId, StringId, UriId},
+    visibility::Visibility,
+};
+use crate::offset::Offset;
+
+/// An ordered instruction extracted from Ruby/RBS source code.
+///
+/// Operations are produced by the builder in the order they appear in the source file.
+/// Scope context is established by Enter/Exit operations rather than carried on each variant.
+#[derive(Debug)]
+pub enum Operation {
+    /// Enter a class scope (`class Foo` or `Class.new`).
+    EnterClass(EnterClass),
+    /// Enter a module scope (`module Foo` or `Module.new`).
+    EnterModule(EnterModule),
+    /// Enter a singleton class scope (`class << self` or `class << Foo`).
+    EnterSingletonClass(EnterSingletonClass),
+    /// Enter a method scope (`def foo` or `def self.foo`).
+    EnterMethod(EnterMethod),
+    /// Exit the current scope (class, module, singleton class, or method).
+    ExitScope,
+    /// Alias a method (`alias new_name old_name` or `alias_method :new, :old`).
+    AliasMethod(AliasMethod),
+    /// Change visibility of a specific method (`private :foo`).
+    SetMethodVisibility(SetMethodVisibility),
+    /// Change the default visibility for subsequent method definitions (`private` with no args).
+    SetDefaultVisibility(SetDefaultVisibility),
+    /// Define a constant (`FOO = 1`).
+    DefineConstant(DefineConstant),
+    /// Define a constant alias (`ALIAS = OtherConstant`).
+    AliasConstant(AliasConstant),
+    /// Change visibility of constants (`private_constant :FOO` or `public_constant :BAR`).
+    SetConstantVisibility(SetConstantVisibility),
+    /// Include, prepend, or extend a module.
+    Mixin(Mixin),
+    /// Define an attribute (`attr_accessor :foo`, `attr_reader :bar`, `attr_writer :baz`).
+    DefineAttribute(DefineAttribute),
+    /// Define a global variable (`$foo = 1`).
+    DefineGlobalVariable(DefineGlobalVariable),
+    /// Define an instance variable (`@foo = 1`).
+    DefineInstanceVariable(DefineInstanceVariable),
+    /// Define a class variable (`@@foo = 1`).
+    DefineClassVariable(DefineClassVariable),
+    /// Alias a global variable (`alias $new $old`).
+    AliasGlobalVariable(AliasGlobalVariable),
+    /// Record a reference to a constant (for tracking usages).
+    ReferenceConstant(ReferenceConstant),
+    /// Record a reference to a method (for tracking usages).
+    ReferenceMethod(ReferenceMethod),
+}
+
+/// A resolved target as it appears in source code.
+///
+/// Used for method receivers (`def self.foo`), mixin targets (`include Foo`),
+/// constant visibility (`Foo.private_constant`), and method references (`Foo.bar`).
+#[derive(Debug, Clone, Copy)]
+pub enum Target {
+    /// Explicit `self` (e.g. `def self.foo`, `extend self`).
+    ExplicitSelf,
+    /// A constant name (e.g. `def Foo.foo`, `include Foo`).
+    Constant(NameId),
+    /// An expression we don't resolve (e.g. `def expr.foo`).
+    Other,
+}
+
+/// The kind of attribute definition.
+#[derive(Debug, Clone, Copy)]
+pub enum AttrKind {
+    Accessor,
+    Reader,
+    Writer,
+}
+
+/// The kind of mixin operation.
+#[derive(Debug, Clone, Copy)]
+pub enum MixinKind {
+    Include,
+    Prepend,
+    Extend,
+}
+
+#[derive(Debug)]
+pub struct EnterClass {
+    pub name_id: NameId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub name_offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+    pub superclass_name: Option<NameId>,
+    pub is_lexical_scope: bool,
+}
+
+#[derive(Debug)]
+pub struct EnterModule {
+    pub name_id: NameId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub name_offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+    pub is_lexical_scope: bool,
+}
+
+#[derive(Debug)]
+pub struct EnterSingletonClass {
+    pub name_id: NameId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub name_offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct EnterMethod {
+    pub str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+    pub signatures: Signatures,
+    pub receiver: Option<Target>,
+}
+
+#[derive(Debug)]
+pub struct AliasMethod {
+    pub new_name_str_id: StringId,
+    pub old_name_str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+    pub receiver: Option<Target>,
+}
+
+#[derive(Debug)]
+pub struct SetMethodVisibility {
+    pub str_id: StringId,
+    pub visibility: Visibility,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct SetDefaultVisibility {
+    pub visibility: Visibility,
+    pub uri_id: UriId,
+    pub offset: Offset,
+}
+
+#[derive(Debug)]
+pub struct DefineConstant {
+    pub name_id: NameId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct AliasConstant {
+    pub name_id: NameId,
+    pub target_name_id: NameId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct SetConstantVisibility {
+    pub receiver: Option<Target>,
+    pub target: StringId,
+    pub visibility: Visibility,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct Mixin {
+    pub kind: MixinKind,
+    pub target: Target,
+}
+
+#[derive(Debug)]
+pub struct DefineAttribute {
+    pub kind: AttrKind,
+    pub str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct DefineGlobalVariable {
+    pub str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct DefineInstanceVariable {
+    pub str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct DefineClassVariable {
+    pub str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct AliasGlobalVariable {
+    pub new_name_str_id: StringId,
+    pub old_name_str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub comments: Box<[Comment]>,
+    pub flags: DefinitionFlags,
+}
+
+#[derive(Debug)]
+pub struct ReferenceConstant {
+    pub name_id: NameId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+}
+
+#[derive(Debug)]
+pub struct ReferenceMethod {
+    pub str_id: StringId,
+    pub uri_id: UriId,
+    pub offset: Offset,
+    pub receiver: Option<Target>,
+}

data/rust/rubydex/src/operation/printer.rs

@@ -0,0 +1,260 @@
+use std::fmt::Write;
+
+use crate::model::{
+    identity_maps::IdentityHashMap,
+    ids::{NameId, StringId},
+    name::NameRef,
+    string_ref::StringRef,
+    visibility::Visibility,
+};
+use crate::operation::{
+    AliasConstant, AliasGlobalVariable, AliasMethod, AttrKind, DefineAttribute, DefineClassVariable, DefineConstant,
+    DefineGlobalVariable, DefineInstanceVariable, EnterClass, EnterMethod, EnterModule, EnterSingletonClass, Mixin,
+    MixinKind, Operation, ReferenceConstant, ReferenceMethod, SetConstantVisibility, SetDefaultVisibility,
+    SetMethodVisibility, Target,
+};
+
+struct OperationPrinter<'a> {
+    strings: &'a IdentityHashMap<StringId, StringRef>,
+    names: &'a IdentityHashMap<NameId, NameRef>,
+    out: String,
+    depth: usize,
+    include_references: bool,
+}
+
+impl OperationPrinter<'_> {
+    fn name_str(&self, name_id: NameId) -> String {
+        let mut parts = Vec::new();
+        let mut current = Some(name_id);
+        while let Some(id) = current {
+            let name = self.names.get(&id).expect("NameId should exist");
+            let s = self.strings.get(name.str()).expect("StringId should exist");
+            parts.push(s.as_str().to_string());
+            current = name.parent_scope().as_ref().copied();
+        }
+        parts.reverse();
+        parts.join("::")
+    }
+
+    fn string_value(&self, str_id: StringId) -> String {
+        self.strings
+            .get(&str_id)
+            .expect("StringId should exist")
+            .as_str()
+            .to_string()
+    }
+
+    fn receiver_prefix(&self, receiver: Option<&Target>) -> String {
+        match receiver {
+            Some(Target::ExplicitSelf) => "self.".to_string(),
+            Some(Target::Constant(name_id)) => format!("{}.", self.name_str(*name_id)),
+            Some(Target::Other) => "<expr>.".to_string(),
+            None => String::new(),
+        }
+    }
+
+    fn vis(visibility: Visibility) -> &'static str {
+        match visibility {
+            Visibility::Public => "public",
+            Visibility::Protected => "protected",
+            Visibility::Private => "private",
+            Visibility::ModuleFunction => "module_function",
+        }
+    }
+
+    fn indent(&self) -> String {
+        "  ".repeat(self.depth)
+    }
+
+    fn print_operation(&mut self, op: &Operation) {
+        match op {
+            Operation::EnterClass(op) => self.print_enter_class(op),
+            Operation::EnterModule(op) => self.print_enter_module(op),
+            Operation::EnterSingletonClass(op) => self.print_enter_singleton_class(op),
+            Operation::EnterMethod(op) => self.print_enter_method(op),
+            Operation::ExitScope => {
+                self.depth = self.depth.saturating_sub(1);
+                let indent = self.indent();
+                writeln!(self.out, "{indent}ExitScope").unwrap();
+            }
+            Operation::AliasMethod(op) => self.print_alias_method(op),
+            Operation::SetMethodVisibility(op) => self.print_set_method_visibility(op),
+            Operation::SetDefaultVisibility(op) => self.print_set_default_visibility(op),
+            Operation::DefineConstant(op) => self.print_define_constant(op),
+            Operation::AliasConstant(op) => self.print_alias_constant(op),
+            Operation::SetConstantVisibility(op) => self.print_set_constant_visibility(op),
+            Operation::Mixin(op) => self.print_mixin(op),
+            Operation::DefineAttribute(op) => self.print_define_attribute(op),
+            Operation::DefineGlobalVariable(op) => self.print_define_global_variable(op),
+            Operation::DefineInstanceVariable(op) => self.print_define_instance_variable(op),
+            Operation::DefineClassVariable(op) => self.print_define_class_variable(op),
+            Operation::AliasGlobalVariable(op) => self.print_alias_global_variable(op),
+            Operation::ReferenceConstant(op) => self.print_reference_constant(op),
+            Operation::ReferenceMethod(op) => self.print_reference_method(op),
+        }
+    }
+
+    fn print_enter_class(&mut self, op: &EnterClass) {
+        let indent = self.indent();
+        let name = self.name_str(op.name_id);
+        write!(self.out, "{indent}EnterClass({name}").unwrap();
+        if let Some(sc_name_id) = op.superclass_name {
+            let sc = self.name_str(sc_name_id);
+            write!(self.out, ", superclass: {sc}").unwrap();
+        }
+        writeln!(self.out, ")").unwrap();
+        self.depth += 1;
+    }
+
+    fn print_enter_module(&mut self, op: &EnterModule) {
+        let indent = self.indent();
+        let name = self.name_str(op.name_id);
+        writeln!(self.out, "{indent}EnterModule({name})").unwrap();
+        self.depth += 1;
+    }
+
+    fn print_enter_singleton_class(&mut self, op: &EnterSingletonClass) {
+        let indent = self.indent();
+        let name = self.name_str(op.name_id);
+        writeln!(self.out, "{indent}EnterSingletonClass({name})").unwrap();
+        self.depth += 1;
+    }
+
+    fn print_enter_method(&mut self, op: &EnterMethod) {
+        let indent = self.indent();
+        let prefix = self.receiver_prefix(op.receiver.as_ref());
+        let name = self.string_value(op.str_id);
+        writeln!(self.out, "{indent}EnterMethod({prefix}{name})").unwrap();
+        self.depth += 1;
+    }
+
+    fn print_alias_method(&mut self, op: &AliasMethod) {
+        let indent = self.indent();
+        let new_name = self.string_value(op.new_name_str_id);
+        let old_name = self.string_value(op.old_name_str_id);
+        writeln!(self.out, "{indent}AliasMethod({new_name} -> {old_name})").unwrap();
+    }
+
+    fn print_set_method_visibility(&mut self, op: &SetMethodVisibility) {
+        let indent = self.indent();
+        let name = self.string_value(op.str_id);
+        let v = Self::vis(op.visibility);
+        writeln!(self.out, "{indent}SetMethodVisibility({name}, vis: {v})").unwrap();
+    }
+
+    fn print_set_default_visibility(&mut self, op: &SetDefaultVisibility) {
+        let indent = self.indent();
+        let v = Self::vis(op.visibility);
+        writeln!(self.out, "{indent}SetDefaultVisibility({v})").unwrap();
+    }
+
+    fn print_define_constant(&mut self, op: &DefineConstant) {
+        let indent = self.indent();
+        let name = self.name_str(op.name_id);
+        writeln!(self.out, "{indent}DefineConstant({name})").unwrap();
+    }
+
+    fn print_alias_constant(&mut self, op: &AliasConstant) {
+        let indent = self.indent();
+        let name = self.name_str(op.name_id);
+        let target = self.name_str(op.target_name_id);
+        writeln!(self.out, "{indent}AliasConstant({name} -> {target})").unwrap();
+    }
+
+    fn print_set_constant_visibility(&mut self, op: &SetConstantVisibility) {
+        let indent = self.indent();
+        let name = self.string_value(op.target);
+        let v = Self::vis(op.visibility);
+        writeln!(self.out, "{indent}SetConstantVisibility({name}, vis: {v})").unwrap();
+    }
+
+    fn print_mixin(&mut self, op: &Mixin) {
+        let indent = self.indent();
+        let kind_str = match op.kind {
+            MixinKind::Include => "include",
+            MixinKind::Prepend => "prepend",
+            MixinKind::Extend => "extend",
+        };
+        let target_name = match op.target {
+            Target::Constant(name_id) => self.name_str(name_id),
+            Target::ExplicitSelf => "self".to_string(),
+            Target::Other => "<expr>".to_string(),
+        };
+        writeln!(self.out, "{indent}Mixin({kind_str}, {target_name})").unwrap();
+    }
+
+    fn print_define_attribute(&mut self, op: &DefineAttribute) {
+        let indent = self.indent();
+        let kind_str = match op.kind {
+            AttrKind::Accessor => "accessor",
+            AttrKind::Reader => "reader",
+            AttrKind::Writer => "writer",
+        };
+        let name = self.string_value(op.str_id);
+        writeln!(self.out, "{indent}DefineAttribute({kind_str} {name})").unwrap();
+    }
+
+    fn print_define_global_variable(&mut self, op: &DefineGlobalVariable) {
+        let indent = self.indent();
+        let name = self.string_value(op.str_id);
+        writeln!(self.out, "{indent}DefineGlobalVariable({name})").unwrap();
+    }
+
+    fn print_define_instance_variable(&mut self, op: &DefineInstanceVariable) {
+        let indent = self.indent();
+        let name = self.string_value(op.str_id);
+        writeln!(self.out, "{indent}DefineInstanceVariable({name})").unwrap();
+    }
+
+    fn print_define_class_variable(&mut self, op: &DefineClassVariable) {
+        let indent = self.indent();
+        let name = self.string_value(op.str_id);
+        writeln!(self.out, "{indent}DefineClassVariable({name})").unwrap();
+    }
+
+    fn print_alias_global_variable(&mut self, op: &AliasGlobalVariable) {
+        let indent = self.indent();
+        let new_name = self.string_value(op.new_name_str_id);
+        let old_name = self.string_value(op.old_name_str_id);
+        writeln!(self.out, "{indent}AliasGlobalVariable({new_name} -> {old_name})").unwrap();
+    }
+
+    fn print_reference_constant(&mut self, op: &ReferenceConstant) {
+        if self.include_references {
+            let indent = self.indent();
+            let name = self.name_str(op.name_id);
+            writeln!(self.out, "{indent}ReferenceConstant({name})").unwrap();
+        }
+    }
+
+    fn print_reference_method(&mut self, op: &ReferenceMethod) {
+        if self.include_references {
+            let indent = self.indent();
+            let name = self.string_value(op.str_id);
+            writeln!(self.out, "{indent}ReferenceMethod({name})").unwrap();
+        }
+    }
+}
+
+#[must_use]
+#[allow(clippy::implicit_hasher)]
+pub fn print_operations(
+    operations: &[Operation],
+    strings: &IdentityHashMap<StringId, StringRef>,
+    names: &IdentityHashMap<NameId, NameRef>,
+    include_references: bool,
+) -> String {
+    let mut printer = OperationPrinter {
+        strings,
+        names,
+        out: String::new(),
+        depth: 0,
+        include_references,
+    };
+
+    for op in operations {
+        printer.print_operation(op);
+    }
+
+    printer.out.trim_end().to_string()
+}