Merge pull request #7 from harvard-lil/artifacts

Use artifacts for data flow between plugins

Author: jcushman

.gitignore

@@ -1,6 +1,7 @@
-/target
-*.swp
-*.swo
+/target
+*.snap.new
+*.swp
+*.swo
 *.pyc
 *.so
 /binoc-python/python/binoc/lib_binoc.dylib.dSYM

AGENTS.md

@@ -14,7 +14,7 @@ Rust workspace with five crates:
 | `binoc-python` | PyO3 bindings and Python plugin support |
 | `binoc-sqlite` | Demo plugin: SQLite schema and row count diffing (also a reference for plugin authors) |
 
-Shared test fixtures live in `test-vectors/`. Authoritative architecture spec is `docs/design.md`.
+Shared test fixtures live in `test-vectors/`. ADRs live in `docs/adr/`.
 
 ## Key Architectural Rules
 

Cargo.lock

@@ -74,8 +74,8 @@ Generic diff tools don't understand data formats, while version control systems
 ## Documentation
 
 - [tutorial.md](docs/tutorial.md): end-to-end contributor walkthrough.
-- Start with [docs/design.md](docs/design.md) for the current architectural contract.
 - [test-vectors/](test-vectors/): fixtures demonstrating major capabilities.
+- [docs/adr/](docs/adr/): records of architectural decisions.
 
 ## Quick Start
 
@@ -139,7 +139,7 @@ Or with `uvx`, no install needed:
 uvx binoc --with binoc-sqlite diff snapshots/v1 snapshots/v2
 ```
 
-Plugins can be Rust crates (compiled as native shared libraries via the `export_plugin!` macro) or pure Python. See [docs/design.md](docs/design.md) for architecture and [model-plugins/](model-plugins/) for reference implementations.
+Plugins can be Rust crates (compiled as native shared libraries via the `export_plugin!` macro) or pure Python. See [docs/adr/](docs/adr/) for architecture and [model-plugins/](model-plugins/) for reference implementations.
 
 ### Rust-only CLI
 

README.md

@@ -177,7 +177,8 @@ comparators:
   - binoc.csv
   - binoc.text
   - binoc.binary
-transformers: []
+transformers:
+  - binoc.tabular_analyzer
 "#,
     )
     .unwrap();

binoc-cli/tests/cli.rs

@@ -66,6 +66,7 @@ impl DatasetConfig {
             transformers: vec![
                 "binoc.move_detector".into(),
                 "binoc.copy_detector".into(),
+                "binoc.tabular_analyzer".into(),
                 "binoc.column_reorder_detector".into(),
             ],
             renderers: default_renderers(),

binoc-core/src/config.rs

@@ -61,8 +61,8 @@ impl Controller {
     ///
     /// Implements the reopen walk: traverses the ancestor chain calling
     /// `reopen()` on each container comparator to reconstruct the
-    /// scratchpad, then `compare()` at the target leaf to populate cache,
-    /// and finally `extract()` on the last toucher.
+    /// scratchpad, then `compare()` at the target leaf to regenerate
+    /// artifacts, and finally `extract()` on the last toucher.
     pub fn extract(
         &self,
         changeset: &Changeset,
@@ -109,11 +109,18 @@ impl Controller {
         let comparator = self.find_comparator_by_name(comp_name).ok_or_else(|| {
             BinocError::Extract(format!("comparator '{comp_name}' not found in registry"))
         })?;
-        let _ = comparator.compare(&current_pair, data.as_ref())?;
+        let compare_result = comparator.compare(&current_pair, data.as_ref())?;
 
         let mut target_node = target.clone();
         target_node.source_items = Some(current_pair);
 
+        match compare_result {
+            CompareResult::Leaf(n) | CompareResult::Expand(n, _) => {
+                target_node.artifacts = n.artifacts;
+            }
+            _ => {}
+        }
+
         if let Some(last_transformer_name) = target_node.transformed_by.last().cloned() {
             let transformer = self
                 .find_transformer_by_name(&last_transformer_name)
@@ -446,17 +453,43 @@ impl Controller {
         }
     }
 
+    /// All fields are AND (every non-empty field must pass).
+    /// Within each field, values are OR (any value satisfies that field).
+    /// Empty/default fields are unconstrained (always pass).
+    /// A descriptor with all fields empty/default matches nothing.
     fn transformer_matches(desc: &TransformerDescriptor, node: &DiffNode) -> bool {
-        if !desc.match_types.is_empty() && desc.match_types.iter().any(|t| t == &node.item_type) {
-            return true;
-        }
-        if !desc.match_tags.is_empty() && desc.match_tags.iter().any(|t| node.tags.contains(t)) {
-            return true;
+        let dominated = match desc.node_shape {
+            NodeShapeFilter::Container => !node.children.is_empty(),
+            NodeShapeFilter::Leaf => node.children.is_empty(),
+            NodeShapeFilter::Any => true,
+        };
+        if !dominated {
+            return false;
         }
-        if !desc.match_actions.is_empty() && desc.match_actions.iter().any(|k| k == &node.action) {
-            return true;
+
+        let types_ok =
+            desc.match_types.is_empty() || desc.match_types.iter().any(|t| t == &node.item_type);
+        let tags_ok =
+            desc.match_tags.is_empty() || desc.match_tags.iter().any(|t| node.tags.contains(t));
+        let actions_ok =
+            desc.match_actions.is_empty() || desc.match_actions.iter().any(|k| k == &node.action);
+        let artifacts_ok = desc.match_artifacts.is_empty()
+            || desc
+                .match_artifacts
+                .iter()
+                .any(|req| node.artifacts.iter().any(|a| a.format == *req));
+
+        if !types_ok || !tags_ok || !actions_ok || !artifacts_ok {
+            return false;
         }
-        false
+
+        // At least one non-default field must be set, otherwise the
+        // descriptor is unconstrained and matches nothing.
+        !matches!(desc.node_shape, NodeShapeFilter::Any)
+            || !desc.match_types.is_empty()
+            || !desc.match_tags.is_empty()
+            || !desc.match_actions.is_empty()
+            || !desc.match_artifacts.is_empty()
     }
 }
 

binoc-core/src/controller.rs

@@ -108,6 +108,9 @@ def transform(self, node):
     match_types: list[str] = []
     match_tags: list[str] = []
     match_actions: list[str] = []
+    node_shape: str = "any"
+    """Dispatch filter on node shape: ``"any"`` (default), ``"container"``
+    (only nodes with children), or ``"leaf"`` (only childless nodes)."""
 
     def can_handle(self, node: DiffNode) -> bool:
         """Return True if this transformer should process the given node.

binoc-python/python/binoc/__init__.py

@@ -18,6 +18,26 @@ use binoc_sdk::*;
 
 use binoc_stdlib::renderers::markdown as md_renderer;
 
+fn restore_transform_transient_fields(
+    result: &mut TransformResult,
+    source_items: &Option<ItemPair>,
+    artifacts: &[ArtifactDescriptor],
+) {
+    match result {
+        TransformResult::Replace(ref mut node) => {
+            node.source_items = source_items.clone();
+            node.artifacts = artifacts.to_vec();
+        }
+        TransformResult::ReplaceMany(ref mut nodes) => {
+            for node in nodes.iter_mut() {
+                node.source_items = source_items.clone();
+                node.artifacts = artifacts.to_vec();
+            }
+        }
+        _ => {}
+    }
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Native plugin loader — loads Rust plugins via C ABI (libloading)
 // ═══════════════════════════════════════════════════════════════════════════
@@ -160,7 +180,18 @@ impl Comparator for NativeComparator {
         let response: CompareResponse = serde_json::from_str(&json)
             .map_err(|e| BinocError::Other(format!("deserialize CompareResponse: {e}")))?;
         match response {
-            CompareResponse::Ok { result } => Ok(*result),
+            CompareResponse::Ok {
+                mut result,
+                artifacts,
+            } => {
+                match result.as_mut() {
+                    CompareResult::Leaf(n) | CompareResult::Expand(n, _) => {
+                        n.artifacts = artifacts;
+                    }
+                    _ => {}
+                }
+                Ok(*result)
+            }
             CompareResponse::Error { message } => Err(BinocError::Comparator {
                 comparator: self.desc.name.clone(),
                 message,
@@ -212,6 +243,7 @@ impl Comparator for NativeComparator {
             aspect: aspect.to_string(),
             data_root: data_root.to_string_lossy().to_string(),
             source_items: node.source_items.clone(),
+            artifacts: node.artifacts.clone(),
         };
         let request_json = serde_json::to_string(&request).ok()?;
         let json = self
@@ -249,10 +281,12 @@ impl Transformer for NativeTransformer {
             Err(_) => return TransformResult::Unchanged,
         };
         let source_items = node.source_items.clone();
+        let artifacts = node.artifacts.clone();
         let request = TransformRequest {
             node,
             data_root: data_root.to_string_lossy().to_string(),
-            source_items,
+            source_items: source_items.clone(),
+            artifacts: artifacts.clone(),
         };
         let request_json = match serde_json::to_string(&request) {
             Ok(j) => j,
@@ -269,10 +303,12 @@ impl Transformer for NativeTransformer {
             Ok(r) => r,
             Err(_) => return TransformResult::Unchanged,
         };
-        match response.into_result() {
+        let mut result = match response.into_result() {
             Ok(r) => r,
             Err(_) => TransformResult::Unchanged,
-        }
+        };
+        restore_transform_transient_fields(&mut result, &source_items, &artifacts);
+        result
     }
 
     fn extract(
@@ -288,6 +324,7 @@ impl Transformer for NativeTransformer {
             aspect: aspect.to_string(),
             data_root: data_root.to_string_lossy().to_string(),
             source_items: node.source_items.clone(),
+            artifacts: node.artifacts.clone(),
         };
         let request_json = serde_json::to_string(&request).ok()?;
         let json = self
@@ -1236,10 +1273,21 @@ fn create_transformer_bridge(
         .getattr("match_actions")
         .and_then(|v| v.extract())
         .unwrap_or_default();
+    let node_shape: NodeShapeFilter = obj
+        .getattr("node_shape")
+        .and_then(|v| v.extract::<String>())
+        .ok()
+        .and_then(|s| match s.as_str() {
+            "container" => Some(NodeShapeFilter::Container),
+            "leaf" => Some(NodeShapeFilter::Leaf),
+            _ => None,
+        })
+        .unwrap_or_default();
     let desc = TransformerDescriptor::new(name)
         .with_match_types(match_types)
         .with_match_tags(match_tags)
-        .with_match_actions(match_actions);
+        .with_match_actions(match_actions)
+        .with_node_shape(node_shape);
     Ok(PyTransformerBridge {
         py_obj: obj.clone().unbind(),
         desc,