hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-24 06:24:06 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Complete implementation of the 3-pass matching algorithm for ambiguous path handling

Browse source 
- Finalized the transition from a duplicate-name blacklist system to a comprehensive 3-pass matching algorithm for both syncback and forward operations, enhancing the handling of ambiguous paths.
- Integrated a new `matching.lua` module to facilitate instance matching during hydration, utilizing unique name matching, class name narrowing, and structural fingerprinting.
- Updated various components, including `ChangeBatcher`, `Reconciler`, and `snapshot` modules, to leverage the new matching logic, ensuring robust file management and improved performance.
- Removed legacy duplicate handling code and streamlined the encoding process for instances with duplicate names.

These changes significantly enhance the clarity and efficiency of file operations, paving the way for improved project management and user experience.
This commit is contained in:
Joe 2026-02-17 02:43:25 -06:00
parent cc77a2cd8a
commit d6162ac210
21 changed files with 2507 additions and 846 deletions
Download patch file Download diff file Expand all files Collapse all files

381
src/snapshot/matching.rs Normal file
View file

@ -0,0 +1,381 @@
//! 3-pass instance matching algorithm for forward sync.
//!
//! Pairs snapshot children (from filesystem re-snapshot) to tree children
//! (existing RojoTree instances). Same algorithm pattern as
//! `syncback::matching` but operating on different data types:
//!
//! - **Snapshot side**: `InstanceSnapshot` with name, class_name, properties
//! - **Tree side**: `RojoTree` instances with name(), class_name(), properties()
use std::collections::HashMap;
use rbx_dom_weak::types::Ref;
use super::{InstanceSnapshot, InstanceWithMeta, RojoTree};
/// Result of the forward sync matching algorithm.
pub struct ForwardMatchResult {
/// Pairs of (snapshot_child, tree_ref) that were matched.
pub matched: Vec<(InstanceSnapshot, Ref)>,
/// Snapshot children with no match in the tree (to be added).
pub unmatched_snapshot: Vec<InstanceSnapshot>,
/// Tree children with no match in the snapshot (to be removed).
pub unmatched_tree: Vec<Ref>,
}
/// Run the 3-pass matching algorithm for forward sync.
///
/// Takes ownership of `snapshot_children` since matched snapshots are moved
/// into the result.
pub fn match_forward(
snapshot_children: Vec<InstanceSnapshot>,
tree_children: &[Ref],
tree: &RojoTree,
) -> ForwardMatchResult {
if snapshot_children.is_empty() && tree_children.is_empty() {
return ForwardMatchResult {
matched: Vec::new(),
unmatched_snapshot: Vec::new(),
unmatched_tree: Vec::new(),
};
}
// Index snapshot children for later consumption.
let mut snap_available: Vec<Option<InstanceSnapshot>> =
snapshot_children.into_iter().map(Some).collect();
// Track which indices are matched (separate from snap_available to avoid
// consuming snapshots before build_result).
let mut snap_matched: Vec<bool> = vec![false; snap_available.len()];
let mut tree_available: Vec<bool> = vec![true; tree_children.len()];
let mut matched: Vec<(usize, usize)> = Vec::new(); // (snap_idx, tree_idx)
// ---- Pass 1: unique name matching + ClassName narrowing ----
pass1_name_and_class(
&snap_available,
tree_children,
&tree_available,
tree,
&mut matched,
);
// Mark matched items as unavailable for subsequent passes.
for &(si, ti) in &matched {
snap_matched[si] = true;
tree_available[ti] = false;
}
// Fast path: if nothing remains on either side, skip Passes 2 and 3.
let snap_remaining = snap_matched.iter().filter(|&&m| !m).count();
let tree_remaining = tree_available.iter().filter(|&&a| a).count();
if snap_remaining == 0 || tree_remaining == 0 {
return build_result(snap_available, tree_children, &tree_available, matched);
}
// ---- Pass 2: Ref property discriminators (placeholder) ----
// TODO: Implement ref-based matching using Rojo_Ref_* attributes on
// snapshot side and resolved Refs on tree side.
// ---- Pass 3: similarity scoring ----
pass3_similarity(
&snap_available,
tree_children,
&mut tree_available,
tree,
&mut matched,
);
build_result(snap_available, tree_children, &tree_available, matched)
}
/// Build the final result, consuming the snapshot children.
fn build_result(
mut snap_available: Vec<Option<InstanceSnapshot>>,
tree_children: &[Ref],
tree_available: &[bool],
matched_indices: Vec<(usize, usize)>,
) -> ForwardMatchResult {
let mut matched = Vec::with_capacity(matched_indices.len());
for (si, ti) in matched_indices {
if let Some(snap) = snap_available[si].take() {
matched.push((snap, tree_children[ti]));
}
}
let unmatched_snapshot: Vec<InstanceSnapshot> =
snap_available.into_iter().flatten().collect();
let unmatched_tree: Vec<Ref> = tree_children
.iter()
.enumerate()
.filter(|(i, _)| tree_available[*i])
.map(|(_, r)| *r)
.collect();
ForwardMatchResult {
matched,
unmatched_snapshot,
unmatched_tree,
}
}
/// Pass 1: Match instances with unique names, then narrow by ClassName.
fn pass1_name_and_class(
snap_available: &[Option<InstanceSnapshot>],
tree_children: &[Ref],
tree_available: &[bool],
tree: &RojoTree,
matched: &mut Vec<(usize, usize)>,
) {
// Build name→indices maps for both sides.
let mut snap_by_name: HashMap<&str, Vec<usize>> = HashMap::new();
for (i, snap_opt) in snap_available.iter().enumerate() {
if let Some(snap) = snap_opt {
snap_by_name.entry(&snap.name).or_default().push(i);
}
}
let mut tree_by_name: HashMap<String, Vec<usize>> = HashMap::new();
for (i, &child_ref) in tree_children.iter().enumerate() {
if !tree_available[i] {
continue;
}
if let Some(inst) = tree.get_instance(child_ref) {
tree_by_name
.entry(inst.name().to_string())
.or_default()
.push(i);
}
}
for (name, snap_indices) in &snap_by_name {
let Some(tree_indices) = tree_by_name.get(*name) else {
continue;
};
// Case 1: exactly one on each side → instant match.
if snap_indices.len() == 1 && tree_indices.len() == 1 {
matched.push((snap_indices[0], tree_indices[0]));
continue;
}
// Case 2: try ClassName narrowing.
let mut snap_by_class: HashMap<&str, Vec<usize>> = HashMap::new();
for &si in snap_indices {
if let Some(snap) = &snap_available[si] {
snap_by_class.entry(&snap.class_name).or_default().push(si);
}
}
let mut tree_by_class: HashMap<String, Vec<usize>> = HashMap::new();
for &ti in tree_indices {
if let Some(inst) = tree.get_instance(tree_children[ti]) {
tree_by_class
.entry(inst.class_name().to_string())
.or_default()
.push(ti);
}
}
for (class, snap_class_indices) in &snap_by_class {
if let Some(tree_class_indices) = tree_by_class.get(*class) {
if snap_class_indices.len() == 1 && tree_class_indices.len() == 1 {
matched.push((snap_class_indices[0], tree_class_indices[0]));
}
}
}
}
}
/// Pass 3: Pairwise similarity scoring within same-name groups.
fn pass3_similarity(
snap_available: &[Option<InstanceSnapshot>],
tree_children: &[Ref],
tree_available: &mut [bool],
tree: &RojoTree,
matched: &mut Vec<(usize, usize)>,
) {
// Track which snap indices have been matched in this pass.
let mut snap_matched: Vec<bool> = vec![false; snap_available.len()];
// Group remaining by name.
let mut snap_by_name: HashMap<&str, Vec<usize>> = HashMap::new();
for (i, snap_opt) in snap_available.iter().enumerate() {
if let Some(snap) = snap_opt {
snap_by_name.entry(&snap.name).or_default().push(i);
}
}
let mut tree_by_name: HashMap<String, Vec<usize>> = HashMap::new();
for (i, &child_ref) in tree_children.iter().enumerate() {
if !tree_available[i] {
continue;
}
if let Some(inst) = tree.get_instance(child_ref) {
tree_by_name
.entry(inst.name().to_string())
.or_default()
.push(i);
}
}
for (name, snap_indices) in &snap_by_name {
let Some(tree_indices) = tree_by_name.get(*name) else {
continue;
};
// Build pairs with similarity scores.
let mut pairs: Vec<(usize, usize, u32)> = Vec::new();
for &si in snap_indices {
if snap_matched[si] {
continue;
}
let snap = match &snap_available[si] {
Some(s) => s,
None => continue,
};
for &ti in tree_indices {
if !tree_available[ti] {
continue;
}
let inst = match tree.get_instance(tree_children[ti]) {
Some(i) => i,
None => continue,
};
let score = compute_forward_similarity(snap, &inst);
pairs.push((si, ti, score));
}
}
// Sort descending by score, tiebreak by original order.
pairs.sort_by(|a, b| b.2.cmp(&a.2).then_with(|| a.0.cmp(&b.0).then(a.1.cmp(&b.1))));
// Greedy assignment.
for (si, ti, _score) in pairs {
if snap_matched[si] || !tree_available[ti] {
continue;
}
matched.push((si, ti));
snap_matched[si] = true;
tree_available[ti] = false;
}
}
}
/// Compute similarity between a snapshot child and a tree child.
fn compute_forward_similarity(snap: &InstanceSnapshot, inst: &InstanceWithMeta) -> u32 {
let mut score: u32 = 0;
if snap.class_name.as_str() == inst.class_name().as_str() {
score += 100;
}
// Children count similarity.
if snap.children.len() == inst.children().len() {
score += 20;
}
score
}
#[cfg(test)]
mod tests {
use super::*;
use crate::snapshot::{InstanceMetadata, InstanceSnapshot, RojoTree};
use rbx_dom_weak::ustr;
use std::borrow::Cow;
fn make_snapshot(name: &str, class: &str) -> InstanceSnapshot {
InstanceSnapshot {
snapshot_id: Ref::none(),
metadata: InstanceMetadata::default(),
name: Cow::Owned(name.to_string()),
class_name: ustr(class),
properties: Default::default(),
children: Vec::new(),
}
}
fn make_tree_with_children(children: &[(&str, &str)]) -> (RojoTree, Vec<Ref>) {
let child_snapshots: Vec<InstanceSnapshot> = children
.iter()
.map(|(name, class)| make_snapshot(name, class))
.collect();
let root_snap = InstanceSnapshot {
snapshot_id: Ref::none(),
metadata: InstanceMetadata::default(),
name: Cow::Borrowed("DataModel"),
class_name: ustr("DataModel"),
properties: Default::default(),
children: child_snapshots,
};
let tree = RojoTree::new(root_snap);
let root_id = tree.get_root_id();
let child_ids: Vec<Ref> = tree.get_instance(root_id).unwrap().children().to_vec();
(tree, child_ids)
}
#[test]
fn unique_names_match() {
let snaps = vec![make_snapshot("Alpha", "Folder"), make_snapshot("Beta", "Script")];
let (tree, children) = make_tree_with_children(&[("Alpha", "Folder"), ("Beta", "Script")]);
let result = match_forward(snaps, &children, &tree);
assert_eq!(result.matched.len(), 2);
assert!(result.unmatched_snapshot.is_empty());
assert!(result.unmatched_tree.is_empty());
}
#[test]
fn class_narrowing() {
let snaps = vec![
make_snapshot("Handler", "Script"),
make_snapshot("Handler", "ModuleScript"),
];
let (tree, children) =
make_tree_with_children(&[("Handler", "ModuleScript"), ("Handler", "Script")]);
let result = match_forward(snaps, &children, &tree);
assert_eq!(result.matched.len(), 2);
for (snap, tree_ref) in &result.matched {
let inst = tree.get_instance(*tree_ref).unwrap();
assert_eq!(snap.class_name.as_str(), inst.class_name().as_str());
}
}
#[test]
fn unmatched_both_sides() {
let snaps = vec![make_snapshot("A", "Folder"), make_snapshot("NewOnly", "Folder")];
let (tree, children) = make_tree_with_children(&[("A", "Folder"), ("OldOnly", "Folder")]);
let result = match_forward(snaps, &children, &tree);
assert_eq!(result.matched.len(), 1);
assert_eq!(result.unmatched_snapshot.len(), 1);
assert_eq!(result.unmatched_tree.len(), 1);
assert_eq!(result.unmatched_snapshot[0].name.as_ref(), "NewOnly");
}
#[test]
fn duplicate_names_greedy() {
let snaps = vec![
make_snapshot("Data", "Folder"),
make_snapshot("Data", "Folder"),
];
let (tree, children) = make_tree_with_children(&[("Data", "Folder"), ("Data", "Folder")]);
let result = match_forward(snaps, &children, &tree);
assert_eq!(result.matched.len(), 2);
assert!(result.unmatched_snapshot.is_empty());
assert!(result.unmatched_tree.is_empty());
}
#[test]
fn empty_both() {
let snaps: Vec<InstanceSnapshot> = vec![];
let (tree, children) = make_tree_with_children(&[]);
let result = match_forward(snaps, &children, &tree);
assert!(result.matched.is_empty());
}
}

1
src/snapshot/mod.rs
View file

@ -49,6 +49,7 @@
#![allow(dead_code)]
mod instance_snapshot;
pub mod matching;
mod metadata;
mod patch;
mod patch_apply;

67
src/snapshot/patch_compute.rs
View file

@ -217,63 +217,34 @@ fn compute_children_patches(
id: Ref,
patch_set: &mut PatchSet,
) {
use super::matching::match_forward;
let instance = tree
.get_instance(id)
.expect("Instance did not exist in tree");
let instance_children = instance.children();
let instance_children = instance.children().to_vec();
let snapshot_children = take(&mut snapshot.children);
let mut paired_instances = vec![false; instance_children.len()];
// Use the 3-pass matching algorithm instead of greedy name+class.
let match_result = match_forward(snapshot_children, &instance_children, tree);
for snapshot_child in take(&mut snapshot.children) {
let matching_instance =
instance_children
.iter()
.enumerate()
.find(|(instance_index, instance_child_id)| {
if paired_instances[*instance_index] {
return false;
}
let instance_child = tree
.get_instance(**instance_child_id)
.expect("Instance did not exist in tree");
if snapshot_child.name == instance_child.name()
&& snapshot_child.class_name == instance_child.class_name()
{
paired_instances[*instance_index] = true;
return true;
}
false
});
match matching_instance {
Some((_, instance_child_id)) => {
compute_patch_set_internal(
context,
snapshot_child,
tree,
*instance_child_id,
patch_set,
);
}
None => {
patch_set.added_instances.push(PatchAdd {
parent_id: id,
instance: snapshot_child,
});
}
}
// Matched pairs: recursively compute patches.
for (snapshot_child, tree_child_id) in match_result.matched {
compute_patch_set_internal(context, snapshot_child, tree, tree_child_id, patch_set);
}
for (instance_index, instance_child_id) in instance_children.iter().enumerate() {
if paired_instances[instance_index] {
continue;
}
// Unmatched snapshots: new instances to be added.
for snapshot_child in match_result.unmatched_snapshot {
patch_set.added_instances.push(PatchAdd {
parent_id: id,
instance: snapshot_child,
});
}
patch_set.removed_instances.push(*instance_child_id);
// Unmatched tree children: instances to be removed.
for tree_child_id in match_result.unmatched_tree {
patch_set.removed_instances.push(tree_child_id);
}
}

57
src/snapshot/tree.rs
View file

@ -231,36 +231,51 @@ impl RojoTree {
self.specified_id_to_refs.insert(specified, id);
}
/// Looks up an instance by its path in the tree (e.g., "SoundService/MySoundGroup").
/// The path is relative to the root of the tree, with segments separated by "/".
/// Returns the Ref if found, None otherwise.
/// Looks up an instance by its filesystem-name path in the tree.
///
/// Each segment is matched against the **filesystem name** of child
/// instances (derived from `instigating_source` path), falling back to
/// the instance name for instances without filesystem backing.
///
/// Path format: `"Workspace/Model.model.json5/Attachment~1.luau"`
/// Segments are separated by `/` (no escaping needed since filesystem
/// names can't contain `/`).
pub fn get_instance_by_path(&self, path: &str) -> Option<Ref> {
if path.is_empty() {
return Some(self.get_root_id());
}
// Use split_ref_path to handle escaped "/" in instance names.
// An instance named "A/B" is stored as "A\/B" in the path.
let segments = crate::split_ref_path(path);
let segments: Vec<&str> = path.split('/').collect();
let mut current_ref = self.get_root_id();
// The root of the tree doesn't appear in the path, so we start with
// the root's children.
for segment in segments.iter() {
for segment in &segments {
let current = self.inner.get_by_ref(current_ref)?;
let children = current.children();
let mut found = false;
for &child_ref in children {
let child = self.inner.get_by_ref(child_ref)?;
if child.name == segment.as_str() {
let fs_name = self.filesystem_name_for(child_ref);
if fs_name.eq_ignore_ascii_case(segment) {
current_ref = child_ref;
found = true;
break;
}
}
if !found {
// Fallback: try matching by instance name (for backward
// compatibility with legacy ref paths and instances without
// filesystem backing).
for &child_ref in children {
let child = self.inner.get_by_ref(child_ref)?;
if child.name == *segment {
current_ref = child_ref;
found = true;
break;
}
}
}
if !found {
return None;
}
@ -269,6 +284,24 @@ impl RojoTree {
Some(current_ref)
}
/// Returns the filesystem name for an instance (the filename or directory
/// name on disk). Derived from `instigating_source` if available, otherwise
/// falls back to the instance name.
pub fn filesystem_name_for(&self, id: Ref) -> String {
if let Some(meta) = self.metadata_map.get(&id) {
if let Some(source) = &meta.instigating_source {
if let Some(name) = source.path().file_name().and_then(|f| f.to_str()) {
return name.to_string();
}
}
}
// Fallback: use instance name
self.inner
.get_by_ref(id)
.map(|inst| inst.name.clone())
.unwrap_or_default()
}
fn insert_metadata(&mut self, id: Ref, metadata: InstanceMetadata) {
for path in &metadata.relevant_paths {
self.path_to_ids.insert(path.clone(), id);