rubydex 0.1.0.beta12-aarch64-linux

data/rust/rubydex/src/model/id.rs

@@ -0,0 +1,110 @@
+use std::{marker::PhantomData, num::NonZeroU64, ops::Deref};
+use xxhash_rust::xxh3;
+
+/// Maps a u64 hash to a `NonZeroU64` by replacing 0 with `u64::MAX`.
+/// The probability of a 64-bit hash being exactly 0 is 2^-64 (~5.4e-20),
+/// and remapping 0 → MAX just means those two inputs collide — the same
+/// risk as any other hash collision, which the system already handles.
+const MAX_NONZERO: NonZeroU64 = NonZeroU64::new(u64::MAX).unwrap();
+
+#[inline]
+fn to_non_zero(value: u64) -> NonZeroU64 {
+    NonZeroU64::new(value).unwrap_or(MAX_NONZERO)
+}
+
+/// A deterministic type-safe ID representation.
+///
+/// Uses `NonZeroU64` internally so that `Option<Id<T>>` is 8 bytes (same as `Id<T>`)
+/// via niche optimization, instead of 16 bytes with a plain `u64`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Id<T> {
+    value: NonZeroU64,
+    _marker: PhantomData<T>,
+}
+
+impl<T> Id<T> {
+    #[must_use]
+    pub fn new(value: u64) -> Self {
+        Self {
+            value: to_non_zero(value),
+            _marker: PhantomData,
+        }
+    }
+
+    /// Returns the underlying `u64` value.
+    #[must_use]
+    pub fn get(&self) -> u64 {
+        self.value.get()
+    }
+}
+
+impl<T> Deref for Id<T> {
+    type Target = u64;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: NonZeroU64 is #[repr(transparent)] over u64.
+        // Deref requires returning &u64, but NonZeroU64::get() returns by value,
+        // so the pointer cast is unavoidable here. Prefer Id::get() when a u64
+        // value (not a reference) is sufficient.
+        unsafe { &*std::ptr::from_ref(&self.value).cast::<u64>() }
+    }
+}
+
+impl<T> std::fmt::Display for Id<T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.value)
+    }
+}
+
+impl<T> From<&str> for Id<T> {
+    fn from(value: &str) -> Self {
+        let hash = xxh3::xxh3_64(value.as_bytes());
+        Self::new(hash)
+    }
+}
+
+impl<T> From<&String> for Id<T> {
+    fn from(value: &String) -> Self {
+        let hash = xxh3::xxh3_64(value.as_bytes());
+        Self::new(hash)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+    pub struct Marker;
+    pub type TestId = Id<Marker>;
+
+    #[test]
+    fn test_create_hash() {
+        // Same input should produce same hash (deterministic)
+        let id1 = TestId::from("test_input");
+        let id2 = TestId::from("test_input");
+        assert_eq!(id1, id2);
+
+        // Different inputs should produce different hashes (unique)
+        let id3 = TestId::from("different_input");
+        assert_ne!(id1, id3);
+    }
+
+    #[test]
+    fn get_returns_value() {
+        let id = TestId::new(123);
+        assert_eq!(id.get(), 123);
+    }
+
+    #[test]
+    fn optional_id_is_still_8_bytes() {
+        assert_eq!(std::mem::size_of::<Option<TestId>>(), 8);
+        assert_eq!(std::mem::size_of::<TestId>(), 8);
+    }
+
+    #[test]
+    fn zero_hash_maps_to_nonzero() {
+        let id = TestId::new(0);
+        assert_eq!(id.get(), u64::MAX);
+    }
+}

data/rust/rubydex/src/model/identity_maps.rs

@@ -0,0 +1,58 @@
+//! This module contains identity maps that use externally hashed IDs as keys. They are used to avoid hashing the same
+//! value twice, simply using the given key directly
+
+use std::{
+    collections::{HashMap, HashSet},
+    hash::{BuildHasher, Hasher},
+};
+
+#[derive(Default)]
+pub struct IdentityHasher {
+    hash: u64,
+}
+
+impl Hasher for IdentityHasher {
+    fn write(&mut self, _bytes: &[u8]) {
+        unreachable!("IdentityHasher only supports write_u64");
+    }
+
+    fn write_u32(&mut self, i: u32) {
+        self.hash = u64::from(i);
+    }
+
+    fn write_u64(&mut self, i: u64) {
+        self.hash = i;
+    }
+
+    fn finish(&self) -> u64 {
+        self.hash
+    }
+}
+
+#[derive(Default)]
+pub struct IdentityHashBuilder;
+
+impl BuildHasher for IdentityHashBuilder {
+    type Hasher = IdentityHasher;
+
+    fn build_hasher(&self) -> Self::Hasher {
+        IdentityHasher::default()
+    }
+}
+
+pub type IdentityHashMap<K, V> = HashMap<K, V, IdentityHashBuilder>;
+pub type IdentityHashSet<T> = HashSet<T, IdentityHashBuilder>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn identity_hasher_uses_value_as_is() {
+        let builder = IdentityHashBuilder;
+        let mut hasher = builder.build_hasher();
+
+        hasher.write_u64(42);
+        assert_eq!(hasher.finish(), 42);
+    }
+}

data/rust/rubydex/src/model/ids.rs

@@ -0,0 +1,60 @@
+use crate::{assert_mem_size, model::id::Id};
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct DeclarationMarker;
+/// `DeclarationId` represents the ID of a fully qualified name. For example, `Foo::Bar` or `Foo#my_method`
+pub type DeclarationId = Id<DeclarationMarker>;
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct DefinitionMarker;
+
+// DefinitionId represents the ID of a definition found in a specific file
+pub type DefinitionId = Id<DefinitionMarker>;
+assert_mem_size!(DefinitionId, 8);
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct UriMarker;
+// UriId represents the ID of a URI, which is the unique identifier for a document
+pub type UriId = Id<UriMarker>;
+assert_mem_size!(UriId, 8);
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct StringMarker;
+/// `StringId` represents an ID for an interned string value
+pub type StringId = Id<StringMarker>;
+assert_mem_size!(StringId, 8);
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct NameMarker;
+/// `NameId` represents an ID for any constant name that we find as part of a reference or definition
+pub type NameId = Id<NameMarker>;
+assert_mem_size!(NameId, 8);
+
+// Reference IDs
+//
+// This section is for specialized IDs for each type of declaration reference
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct ConstantMarker;
+pub type ConstantReferenceId = Id<ConstantMarker>;
+assert_mem_size!(ConstantReferenceId, 8);
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct MethodMarker;
+pub type MethodReferenceId = Id<MethodMarker>;
+assert_mem_size!(MethodReferenceId, 8);
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct GlobalVariableMarker;
+pub type GlobalVariableReferenceId = Id<GlobalVariableMarker>;
+assert_mem_size!(GlobalVariableReferenceId, 8);
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct ClassVariableMarker;
+pub type ClassVariableReferenceId = Id<ClassVariableMarker>;
+assert_mem_size!(ClassVariableReferenceId, 8);
+
+#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
+pub struct InstanceVariableMarker;
+pub type InstanceVariableReferenceId = Id<InstanceVariableMarker>;
+assert_mem_size!(InstanceVariableReferenceId, 8);

data/rust/rubydex/src/model/keywords.rs

@@ -0,0 +1,256 @@
+/// A Ruby keyword with its documentation.
+#[derive(Debug)]
+pub struct Keyword {
+    /// The keyword text as it appears in source (e.g., "yield", "defined?", "__FILE__")
+    name: &'static str,
+    /// Documentation string for hover display
+    documentation: &'static str,
+}
+
+impl Keyword {
+    #[must_use]
+    pub const fn name(&self) -> &'static str {
+        self.name
+    }
+
+    #[must_use]
+    pub const fn documentation(&self) -> &'static str {
+        self.documentation
+    }
+}
+
+/// Looks up a keyword by its exact name. Returns `None` if the name is not a keyword.
+///
+/// Uses binary search on the sorted `KEYWORDS` array for O(log n) lookup.
+#[must_use]
+pub fn get(name: &str) -> Option<&'static Keyword> {
+    KEYWORDS
+        .binary_search_by_key(&name, |k| k.name)
+        .ok()
+        .map(|i| &KEYWORDS[i])
+}
+
+/// All Ruby keywords, sorted lexicographically by name for binary search.
+pub static KEYWORDS: &[Keyword] = &[
+    Keyword {
+        name: "BEGIN",
+        documentation: "Registers a block of code to be executed before the program starts. Syntax: `BEGIN { ... }`.",
+    },
+    Keyword {
+        name: "END",
+        documentation: "Registers a block of code to be executed after the program finishes. Syntax: `END { ... }`.",
+    },
+    Keyword {
+        name: "__ENCODING__",
+        documentation: "Returns the `Encoding` object representing the encoding of the current source file.",
+    },
+    Keyword {
+        name: "__FILE__",
+        documentation: "Returns the path of the current source file as a `String`.",
+    },
+    Keyword {
+        name: "__LINE__",
+        documentation: "Returns the current line number in the source file as an `Integer`.",
+    },
+    Keyword {
+        name: "alias",
+        documentation: "Creates an alias between two methods or global variables. Syntax: `alias new_name old_name`.",
+    },
+    Keyword {
+        name: "and",
+        documentation: "Low-precedence logical AND operator. Unlike `&&`, it has lower precedence than assignment.",
+    },
+    Keyword {
+        name: "begin",
+        documentation: "Opens an exception handling block. Can be followed by `rescue`, `else`, `ensure`, and closed with `end`.",
+    },
+    Keyword {
+        name: "break",
+        documentation: "Exits from a loop or block, optionally returning a value. Syntax: `break` or `break value`.",
+    },
+    Keyword {
+        name: "case",
+        documentation: "Starts a case expression for pattern matching. Used with `when` clauses and closed with `end`.",
+    },
+    Keyword {
+        name: "class",
+        documentation: "Defines a new class or opens an existing one. Syntax: `class Name < Superclass; end`.",
+    },
+    Keyword {
+        name: "def",
+        documentation: "Defines a method. Syntax: `def method_name(params); end`.",
+    },
+    Keyword {
+        name: "defined?",
+        documentation: "Returns a string describing the type of an expression, or `nil` if it is not defined. The argument is not evaluated.",
+    },
+    Keyword {
+        name: "do",
+        documentation: "Starts a block of code, typically following an iterator method call. Paired with `end`.",
+    },
+    Keyword {
+        name: "else",
+        documentation: "Provides an alternative branch in `if`, `unless`, `case`, or `begin/rescue` expressions.",
+    },
+    Keyword {
+        name: "elsif",
+        documentation: "Provides an additional conditional branch within an `if` expression.",
+    },
+    Keyword {
+        name: "end",
+        documentation: "Closes a `class`, `module`, `def`, `if`, `unless`, `case`, `while`, `until`, `for`, `begin`, or `do` block.",
+    },
+    Keyword {
+        name: "ensure",
+        documentation: "Defines a block of code within `begin`/`def` that always runs, whether an exception was raised or not.",
+    },
+    Keyword {
+        name: "false",
+        documentation: "The singleton instance of `FalseClass`. One of two falsy values in Ruby, along with `nil`.",
+    },
+    Keyword {
+        name: "for",
+        documentation: "Iterates over a collection. Syntax: `for variable in collection; end`. Prefer `.each` in idiomatic Ruby.",
+    },
+    Keyword {
+        name: "if",
+        documentation: "Conditional branch. Can be used as a statement (`if cond; end`) or a modifier (`expr if cond`).",
+    },
+    Keyword {
+        name: "in",
+        documentation: "Used with `for` loops (`for x in collection`) and pattern matching (`case value; in pattern`).",
+    },
+    Keyword {
+        name: "module",
+        documentation: "Defines a new module or opens an existing one. Modules provide namespacing and mixins via `include`/`extend`.",
+    },
+    Keyword {
+        name: "next",
+        documentation: "Skips to the next iteration of a loop or block, optionally returning a value. Syntax: `next` or `next value`.",
+    },
+    Keyword {
+        name: "nil",
+        documentation: "The singleton instance of `NilClass`. Represents the absence of a value. Falsy in boolean context.",
+    },
+    Keyword {
+        name: "not",
+        documentation: "Low-precedence logical NOT operator. Unlike `!`, it has lower precedence than most operators.",
+    },
+    Keyword {
+        name: "or",
+        documentation: "Low-precedence logical OR operator. Unlike `||`, it has lower precedence than assignment.",
+    },
+    Keyword {
+        name: "redo",
+        documentation: "Restarts the current iteration of a loop or block without re-evaluating the condition.",
+    },
+    Keyword {
+        name: "rescue",
+        documentation: "Catches exceptions in a `begin`/`def` block. Can also be used inline: `expr rescue default`.",
+    },
+    Keyword {
+        name: "retry",
+        documentation: "Re-executes the `begin` block from the start. Only valid inside a `rescue` clause.",
+    },
+    Keyword {
+        name: "return",
+        documentation: "Exits from the current method, optionally returning a value. Syntax: `return` or `return value`.",
+    },
+    Keyword {
+        name: "self",
+        documentation: "References the current object. Inside a method, it is the receiver. Inside a class/module body, it is the class/module itself.",
+    },
+    Keyword {
+        name: "super",
+        documentation: "Calls the next occurrence of the method in the ancestor chain. Forwards all arguments if called without parentheses.",
+    },
+    Keyword {
+        name: "then",
+        documentation: "Optional separator after the condition in `if`, `unless`, `when`, or `in` clauses.",
+    },
+    Keyword {
+        name: "true",
+        documentation: "The singleton instance of `TrueClass`. Truthy in boolean context.",
+    },
+    Keyword {
+        name: "undef",
+        documentation: "Removes a method definition from the current class. Syntax: `undef method_name`.",
+    },
+    Keyword {
+        name: "unless",
+        documentation: "Inverted conditional. Executes the body when the condition is falsy. Can be used as statement or modifier.",
+    },
+    Keyword {
+        name: "until",
+        documentation: "Loops while the condition is falsy. Can be used as a statement or modifier.",
+    },
+    Keyword {
+        name: "when",
+        documentation: "Defines a branch in a `case` expression. Syntax: `when value; ...`.",
+    },
+    Keyword {
+        name: "while",
+        documentation: "Loops while the condition is truthy. Can be used as a statement or modifier.",
+    },
+    Keyword {
+        name: "yield",
+        documentation: "Calls the block passed to the current method, passing optional arguments. Returns the block's return value.",
+    },
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn all_keywords_have_documentation() {
+        for keyword in KEYWORDS {
+            assert!(
+                !keyword.documentation().is_empty(),
+                "keyword '{}' has empty documentation",
+                keyword.name()
+            );
+        }
+    }
+
+    #[test]
+    fn get_returns_none_for_non_keywords() {
+        assert!(get("puts").is_none());
+        assert!(get("require").is_none());
+        assert!(get("").is_none());
+        assert!(get("Foo").is_none());
+    }
+
+    #[test]
+    fn get_returns_keyword_with_correct_data() {
+        let kw = get("yield").unwrap();
+        assert_eq!(kw.name(), "yield");
+        assert!(kw.documentation().contains("block"));
+
+        let kw = get("defined?").unwrap();
+        assert_eq!(kw.name(), "defined?");
+
+        let kw = get("__FILE__").unwrap();
+        assert_eq!(kw.name(), "__FILE__");
+    }
+
+    #[test]
+    fn keyword_names_are_unique() {
+        let mut seen = std::collections::HashSet::new();
+        for keyword in KEYWORDS {
+            assert!(seen.insert(keyword.name()), "duplicate keyword: '{}'", keyword.name());
+        }
+    }
+
+    #[test]
+    fn keywords_are_sorted() {
+        for window in KEYWORDS.windows(2) {
+            assert!(
+                window[0].name() < window[1].name(),
+                "KEYWORDS not sorted: '{}' should come before '{}'",
+                window[1].name(),
+                window[0].name()
+            );
+        }
+    }
+}