Merge pull request #6 from harvard-lil/renames

Terminology updates

Author: jcushman

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-Binoc generates changelogs for datasets that don't ship with them. Given two snapshots of a dataset, it detects structural and content changes, records them as a migration tree (the IR), and renders changes as JSON or Markdown. The primary audience is archivists, data scientists, and stewards tracking undocumented changes to published datasets.
+Binoc generates changelogs for datasets that don't ship with them. Given two snapshots of a dataset, it detects structural and content changes, records them as a changeset tree (the IR), and renders changes as JSON or Markdown. The primary audience is archivists, data scientists, and stewards tracking undocumented changes to published datasets.
 
 Rust workspace with five crates:
 
@@ -22,9 +22,9 @@ Shared test fixtures live in `test-vectors/`. Authoritative architecture spec is
 
 2. **The standard library (`binoc-stdlib`) is a plugin pack**, architecturally identical to third-party packs. The core engine has zero domain knowledge—not even about directories or text files.
 
-3. **Comparators are the parser** (raw data → IR). **Transformers are optimization passes** (IR → IR, no raw data access). **Significance classification is an outputter concern**, mapped from semantic tags via config—not baked into the IR.
+3. **Comparators are the parser** (raw data → IR). **Transformers are optimization passes** (IR → IR, no raw data access). **Significance classification is a renderer concern**, mapped from semantic tags via config—not baked into the IR.
 
-4. **The IR is tree-structured, openly typed, and tag-annotated.** `kind`, `item_type`, and `tags` are open enums/strings. No built-in types or significance levels. Conventions, not enforcement.
+4. **The IR is tree-structured, openly typed, and tag-annotated.** `action`, `item_type`, and `tags` are open enums/strings. No built-in types or significance levels. Conventions, not enforcement.
 
 5. **Dispatch is declarative-first** (type/extension filters) **with an imperative escape hatch** (`can_handle`). First comparator to claim an item wins. Ordering is a config concern, not a plugin concern.
 

README.md

@@ -1,6 +1,6 @@
 # Binoc: The Missing Changelog for Datasets
 
-Binoc generates changelogs for datasets that don't have them. Given a series of snapshots of a dataset downloaded at different times, Binoc detects what changed, expresses those changes as a minimal structured diff, and produces human-readable summaries that distinguish substantive policy changes from ministerial housekeeping.
+Binoc generates changelogs for datasets that don't have them. Given a series of snapshots of a dataset downloaded at different times, Binoc detects what changed, expresses those changes as a minimal structured diff, and produces human-readable summaries that distinguish substantive policy changes from clerical housekeeping.
 
 The core workflow: an archivist, data scientist, or steward has five copies of a government dataset containing CSVs, downloaded over two years. Some are identical. Some have reordered columns. One has a new category relevant to their research. Binoc tells them exactly what changed, when, and whether (by their definition) it matters.
 
@@ -15,7 +15,7 @@ binoc diff release-q3/ release-q4/
 ```
 # Changelog: release-q3/ → release-q4/
 
-## Ministerial Changes
+## Clerical Changes
 
 - **data.zip/agencies.csv**: Columns reordered (content unchanged)
 
@@ -24,7 +24,7 @@ binoc diff release-q3/ release-q4/
 - **summary.sqlite**: Content changed (12.0 KB → 12.0 KB)
 ```
 
-Binoc looked inside the zip and compared the CSV column-by-column — the reorder is flagged as ministerial housekeeping, not a real data change. But `.sqlite` is opaque to the standard library, so you only learn that the bytes differ.
+Binoc looked inside the zip and compared the CSV column-by-column — the reorder is flagged as clerical housekeeping, not a real data change. But `.sqlite` is opaque to the standard library, so you only learn that the bytes differ.
 
 ```bash
 pip install binoc-sqlite
@@ -34,7 +34,7 @@ binoc diff release-q3/ release-q4/
 ```
 # Changelog: release-q3/ → release-q4/
 
-## Ministerial Changes
+## Clerical Changes
 
 - **data.zip/agencies.csv**: Columns reordered (content unchanged)
 
@@ -50,7 +50,7 @@ Same command, richer output. The plugin parsed the database and found the actual
 Datasets published by governments, research institutions, and public bodies are living artifacts, and can change without warning or documentation (or without consistent documentation). The archival and data science communities need tooling to:
 
 - Detect whether a new snapshot of a dataset actually differs from the previous one.
-- Describe changes precisely — not just "the file changed," but "three columns were reordered (ministerial) and one column was split into two (substantive)."
+- Describe changes precisely — not just "the file changed," but "three columns were reordered (clerical) and one column was split into two (substantive)."
 - Produce changelogs that are machine-readable for automated pipelines and human-readable for policy analysis.
 - Handle real-world messiness: datasets inside zip archives, nested containers, mixed formats, renamed files.
 
@@ -65,8 +65,8 @@ Generic diff tools don't understand data formats, while version control systems
 - Compare text files at line level
 - Compare binary files by content hash
 - Detect moves and copies from content hashes
-- Extract actual changed data from migration nodes (added rows, text diffs, etc.)
-- Render migrations as JSON or Markdown changelogs
+- Extract actual changed data from changeset nodes (added rows, text diffs, etc.)
+- Render changesets as JSON or Markdown changelogs
 - Extend comparison and transformation pipelines via Rust native plugins (C ABI), Python plugins, or in-workspace stdlib plugins
 
 ## Documentation
@@ -97,7 +97,7 @@ Diff two snapshots (prints a Markdown changelog to stdout by default):
 binoc diff path/to/snapshot-a path/to/snapshot-b
 ```
 
-Get raw migration JSON instead:
+Get raw changeset JSON instead:
 
 ```bash
 binoc diff path/to/snapshot-a path/to/snapshot-b --format json
@@ -107,19 +107,19 @@ Save outputs to files (format inferred from extension, or use `format:path` synt
 
 ```bash
 binoc diff path/to/snapshot-a path/to/snapshot-b \
-  -o migration.json -o CHANGELOG.md -q
+  -o changeset.json -o CHANGELOG.md -q
 ```
 
-Combine saved migrations into a changelog:
+Combine saved changesets into a changelog:
 
 ```bash
-binoc changelog migrations/*.json
+binoc changelog changesets/*.json
 ```
 
-Extract the actual changed data from a migration node (requires original snapshots):
+Extract the actual changed data from a changeset node (requires original snapshots):
 
 ```bash
-binoc extract migration.json data.csv rows_added
+binoc extract changeset.json data.csv rows_added
 ```
 
 ### Plugins
@@ -176,7 +176,7 @@ This builds both packages from source and wires up entry-point discovery automat
 | `binoc-stdlib/` | Standard comparators and transformers (architecturally identical to third-party plugins) |
 | `binoc-cli/` | CLI library + standalone Rust binary |
 | `binoc-python/` | PyO3 bindings, native plugin loader (`libloading`), Python plugin bridges, `binoc` CLI entry point |
-| `model-plugins/` | Reference plugin implementations: `binoc-sqlite` (Rust comparator), `binoc-row-reorder` (Rust transformer), `binoc-html` (Python outputter) |
+| `model-plugins/` | Reference plugin implementations: `binoc-sqlite` (Rust comparator), `binoc-row-reorder` (Rust transformer), `binoc-html` (Python renderer) |
 | `test-vectors/` | Shared test fixtures for standard library plugins |
 | `docs/` | Documentation, design notes, and ADRs |
 

binoc-cli/src/lib.rs

@@ -6,7 +6,7 @@ use clap::{Parser, Subcommand};
 use binoc_core::config::{DatasetConfig, PluginRegistry, ResolvedPlugins};
 use binoc_core::controller::Controller;
 use binoc_core::output;
-use binoc_sdk::{BinocError, ExtractResult, Migration, Outputter};
+use binoc_sdk::{BinocError, Changeset, ExtractResult, Renderer};
 
 #[derive(Parser)]
 #[command(name = "binoc", about = "The missing changelog for datasets")]
@@ -30,9 +30,9 @@ enum Commands {
         #[arg(long, short)]
         quiet: bool,
     },
-    /// Generate a human-readable changelog from one or more migrations.
+    /// Generate a human-readable changelog from one or more changesets.
     Changelog {
-        migrations: Vec<PathBuf>,
+        changesets: Vec<PathBuf>,
         #[arg(long)]
         config: Option<PathBuf>,
         #[arg(long, short)]
@@ -42,9 +42,9 @@ enum Commands {
         #[arg(long, short)]
         quiet: bool,
     },
-    /// Extract actual changed data from a migration node.
+    /// Extract actual changed data from a changeset node.
     Extract {
-        migration: PathBuf,
+        changeset: PathBuf,
         node: String,
         #[arg(default_value = "content")]
         aspect: String,
@@ -85,7 +85,7 @@ impl OutputSpec {
 
 enum ResolvedFormat {
     Json,
-    Outputter(Arc<dyn Outputter>),
+    Renderer(Arc<dyn Renderer>),
 }
 
 fn resolve_format(
@@ -99,8 +99,8 @@ fn resolve_format(
             if ext == "json" {
                 return Ok(ResolvedFormat::Json);
             }
-            match resolved.outputter_for_extension(ext)? {
-                Some(o) => Ok(ResolvedFormat::Outputter(o)),
+            match resolved.renderer_for_extension(ext)? {
+                Some(o) => Ok(ResolvedFormat::Renderer(o)),
                 None => Err(BinocError::Config(format!(
                     "cannot infer format for .{ext}; use format:path syntax (e.g. markdown:{path})",
                     path = spec.path.display(),
@@ -118,28 +118,28 @@ fn resolve_format_name(
         return Ok(ResolvedFormat::Json);
     }
     resolved
-        .outputter_by_name(name)
-        .map(ResolvedFormat::Outputter)
+        .renderer_by_name(name)
+        .map(ResolvedFormat::Renderer)
         .ok_or_else(|| BinocError::Config(format!("unknown output format: {name}")))
 }
 
 fn render(
     format: &ResolvedFormat,
-    migrations: &[Migration],
+    changesets: &[Changeset],
     config: &DatasetConfig,
 ) -> Result<String, BinocError> {
     match format {
         ResolvedFormat::Json => {
-            if migrations.len() == 1 {
-                output::to_json(&migrations[0]).map_err(|e| BinocError::Other(e.to_string()))
+            if changesets.len() == 1 {
+                output::to_json(&changesets[0]).map_err(|e| BinocError::Other(e.to_string()))
             } else {
-                serde_json::to_string_pretty(&migrations)
+                serde_json::to_string_pretty(&changesets)
                     .map_err(|e| BinocError::Other(e.to_string()))
             }
         }
-        ResolvedFormat::Outputter(o) => {
-            let outputter_config = config.output.get_for_outputter(&o.descriptor().name);
-            o.render(migrations, &outputter_config)
+        ResolvedFormat::Renderer(o) => {
+            let renderer_config = config.output.get_for_renderer(&o.descriptor().name);
+            o.render(changesets, &renderer_config)
         }
     }
 }
@@ -148,20 +148,20 @@ fn write_outputs(
     output_specs: &[String],
     stdout_format: &str,
     quiet: bool,
-    migrations: &[Migration],
+    changesets: &[Changeset],
     config: &DatasetConfig,
     resolved: &ResolvedPlugins,
 ) -> Result<(), Box<dyn std::error::Error>> {
     if !quiet {
         let fmt = resolve_format_name(stdout_format, resolved)?;
-        let text = render(&fmt, migrations, config)?;
+        let text = render(&fmt, changesets, config)?;
         print!("{text}");
     }
 
     for raw in output_specs {
         let spec = OutputSpec::parse(raw);
         let fmt = resolve_format(&spec, resolved)?;
-        let text = render(&fmt, migrations, config)?;
+        let text = render(&fmt, changesets, config)?;
         if let Some(parent) = spec.path.parent() {
             if !parent.as_os_str().is_empty() {
                 std::fs::create_dir_all(parent)?;
@@ -210,20 +210,20 @@ pub fn run(
             let snap_a = snapshot_a.to_string_lossy().to_string();
             let snap_b = snapshot_b.to_string_lossy().to_string();
 
-            let migration = controller.diff(&snap_a, &snap_b)?;
-            let migrations = [migration];
+            let changeset = controller.diff(&snap_a, &snap_b)?;
+            let changesets = [changeset];
 
             write_outputs(
                 &output,
                 &format,
                 quiet,
-                &migrations,
+                &changesets,
                 &dataset_config,
                 &resolved,
             )?;
         }
         Commands::Changelog {
-            migrations: migration_paths,
+            changesets: changeset_paths,
             config,
             output,
             format,
@@ -236,39 +236,39 @@ pub fn run(
 
             let resolved = registry.resolve(&dataset_config)?;
 
-            let mut migrations: Vec<Migration> = Vec::new();
-            for path in &migration_paths {
+            let mut changesets: Vec<Changeset> = Vec::new();
+            for path in &changeset_paths {
                 let data = std::fs::read_to_string(path)?;
-                let m: Migration = serde_json::from_str(&data)?;
-                migrations.push(m);
+                let m: Changeset = serde_json::from_str(&data)?;
+                changesets.push(m);
             }
 
             write_outputs(
                 &output,
                 &format,
                 quiet,
-                &migrations,
+                &changesets,
                 &dataset_config,
                 &resolved,
             )?;
         }
         Commands::Extract {
-            migration: migration_path,
+            changeset: changeset_path,
             node,
             aspect,
             snapshot_a,
             snapshot_b,
             config,
         } => {
-            let data = std::fs::read_to_string(&migration_path)?;
-            let migration: Migration = serde_json::from_str(&data)?;
+            let data = std::fs::read_to_string(&changeset_path)?;
+            let changeset: Changeset = serde_json::from_str(&data)?;
 
             let snap_a = snapshot_a
                 .map(|p| p.to_string_lossy().to_string())
-                .unwrap_or_else(|| migration.from_snapshot.clone());
+                .unwrap_or_else(|| changeset.from_snapshot.clone());
             let snap_b = snapshot_b
                 .map(|p| p.to_string_lossy().to_string())
-                .unwrap_or_else(|| migration.to_snapshot.clone());
+                .unwrap_or_else(|| changeset.to_snapshot.clone());
 
             if !std::path::Path::new(&snap_a).exists() {
                 eprintln!("Snapshot A not found: {snap_a}");
@@ -289,7 +289,7 @@ pub fn run(
             let resolved = registry.resolve(&dataset_config)?;
             let controller = Controller::new(resolved.comparators, resolved.transformers);
 
-            match controller.extract(&migration, &node, &aspect, &snap_a, &snap_b) {
+            match controller.extract(&changeset, &node, &aspect, &snap_a, &snap_b) {
                 Ok(result) => match result {
                     ExtractResult::Text(text) => {
                         print!("{text}");