feat(vx): add --json output flag to inspect and tree commands

Adds structured JSON output option to the inspect and tree commands,
enabling programmatic access to file metadata for tooling integration.

Signed-off-by: Baris Palaska <[email protected]>

Author: palaska

vortex-tui/src/inspect.rs

@@ -6,11 +6,13 @@ use std::fs::File;
 use std::io::Read;
 use std::io::Seek;
 use std::io::SeekFrom;
+use std::path::Path;
 use std::path::PathBuf;
 use std::sync::Arc;
 
 use flatbuffers::root;
 use itertools::Itertools;
+use serde::Serialize;
 use vortex::buffer::Alignment;
 use vortex::buffer::ByteBuffer;
 use vortex::error::VortexExpect;
@@ -36,6 +38,10 @@ pub struct InspectArgs {
 
     /// Path to the Vortex file to inspect
     pub file: PathBuf,
+
+    /// Output as JSON
+    #[arg(long, global = true)]
+    pub json: bool,
 }
 
 #[derive(Debug, clap::Subcommand)]
@@ -50,15 +56,189 @@ pub enum InspectMode {
     Footer,
 }
 
+#[derive(Serialize)]
+pub struct InspectOutput {
+    pub file_path: String,
+    pub file_size: u64,
+    pub eof: EofInfoJson,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub postscript: Option<PostscriptInfoJson>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub footer: Option<FooterInfoJson>,
+}
+
+#[derive(Serialize)]
+pub struct EofInfoJson {
+    pub version: u16,
+    pub current_version: u16,
+    pub postscript_size: u16,
+    pub magic_bytes: String,
+    pub valid_magic: bool,
+}
+
+#[derive(Serialize)]
+pub struct SegmentInfoJson {
+    pub offset: u64,
+    pub length: u32,
+    pub alignment: usize,
+}
+
+#[derive(Serialize)]
+pub struct PostscriptInfoJson {
+    pub dtype: Option<SegmentInfoJson>,
+    pub layout: SegmentInfoJson,
+    pub statistics: Option<SegmentInfoJson>,
+    pub footer: SegmentInfoJson,
+}
+
+#[derive(Serialize)]
+pub struct FooterInfoJson {
+    pub total_segments: usize,
+    pub total_data_size: u64,
+    pub segments: Vec<FooterSegmentJson>,
+}
+
+#[derive(Serialize)]
+pub struct FooterSegmentJson {
+    pub index: usize,
+    pub offset: u64,
+    pub end_offset: u64,
+    pub length: u32,
+    pub alignment: usize,
+    pub path: Option<String>,
+}
+
 pub async fn exec_inspect(args: InspectArgs) -> anyhow::Result<()> {
     let mut inspector = VortexInspector::new(args.file.clone())?;
 
-    println!("File: {}", args.file.display());
+    let mode = args.mode.unwrap_or(InspectMode::Footer);
+
+    if args.json {
+        exec_inspect_json(&mut inspector, &args.file, mode).await
+    } else {
+        exec_inspect_text(&mut inspector, &args.file, mode).await
+    }
+}
+
+async fn exec_inspect_json(
+    inspector: &mut VortexInspector,
+    file_path: &Path,
+    mode: InspectMode,
+) -> anyhow::Result<()> {
+    let eof = inspector.read_eof()?;
+    let eof_json = EofInfoJson {
+        version: eof.version,
+        current_version: VERSION,
+        postscript_size: eof.postscript_size,
+        magic_bytes: std::str::from_utf8(&eof.magic_bytes)
+            .unwrap_or("<invalid utf8>")
+            .to_string(),
+        valid_magic: eof.valid_magic,
+    };
+
+    let postscript_json =
+        if matches!(mode, InspectMode::Postscript | InspectMode::Footer) && eof.valid_magic {
+            inspector
+                .read_postscript(eof.postscript_size)
+                .ok()
+                .map(|ps| PostscriptInfoJson {
+                    dtype: ps.dtype.map(|s| SegmentInfoJson {
+                        offset: s.offset,
+                        length: s.length,
+                        alignment: *s.alignment,
+                    }),
+                    layout: SegmentInfoJson {
+                        offset: ps.layout.offset,
+                        length: ps.layout.length,
+                        alignment: *ps.layout.alignment,
+                    },
+                    statistics: ps.statistics.map(|s| SegmentInfoJson {
+                        offset: s.offset,
+                        length: s.length,
+                        alignment: *s.alignment,
+                    }),
+                    footer: SegmentInfoJson {
+                        offset: ps.footer.offset,
+                        length: ps.footer.length,
+                        alignment: *ps.footer.alignment,
+                    },
+                })
+        } else {
+            None
+        };
+
+    let footer_json =
+        if matches!(mode, InspectMode::Footer) && eof.valid_magic && postscript_json.is_some() {
+            inspector.read_footer().await.ok().map(|footer| {
+                let segment_map = footer.segment_map().clone();
+                let root_layout = footer.layout().clone();
+
+                let mut segment_paths: Vec<Option<Vec<Arc<str>>>> = vec![None; segment_map.len()];
+                let mut queue =
+                    VecDeque::<(Vec<Arc<str>>, LayoutRef)>::from_iter([(Vec::new(), root_layout)]);
+                while !queue.is_empty() {
+                    let (path, layout) = queue.pop_front().vortex_expect("queue is not empty");
+                    for segment in layout.segment_ids() {
+                        segment_paths[*segment as usize] = Some(path.clone());
+                    }
+                    if let Ok(children) = layout.children() {
+                        for (child_layout, child_name) in
+                            children.into_iter().zip(layout.child_names())
+                        {
+                            let child_path = path.iter().cloned().chain([child_name]).collect();
+                            queue.push_back((child_path, child_layout));
+                        }
+                    }
+                }
+
+                let segments: Vec<FooterSegmentJson> = segment_map
+                    .iter()
+                    .enumerate()
+                    .map(|(i, segment)| FooterSegmentJson {
+                        index: i,
+                        offset: segment.offset,
+                        end_offset: segment.offset + segment.length as u64,
+                        length: segment.length,
+                        alignment: *segment.alignment,
+                        path: segment_paths[i]
+                            .as_ref()
+                            .map(|p| p.iter().map(|s| s.as_ref()).collect::<Vec<_>>().join(".")),
+                    })
+                    .collect();
+
+                FooterInfoJson {
+                    total_segments: segment_map.len(),
+                    total_data_size: segment_map.iter().map(|s| s.length as u64).sum(),
+                    segments,
+                }
+            })
+        } else {
+            None
+        };
+
+    let output = InspectOutput {
+        file_path: file_path.display().to_string(),
+        file_size: inspector.file_size,
+        eof: eof_json,
+        postscript: postscript_json,
+        footer: footer_json,
+    };
+
+    let json_output = serde_json::to_string_pretty(&output)?;
+    println!("{json_output}");
+
+    Ok(())
+}
+
+async fn exec_inspect_text(
+    inspector: &mut VortexInspector,
+    file_path: &Path,
+    mode: InspectMode,
+) -> anyhow::Result<()> {
+    println!("File: {}", file_path.display());
     println!("Size: {} bytes", inspector.file_size);
     println!();
 
-    let mode = args.mode.unwrap_or(InspectMode::Footer);
-
     match mode {
         InspectMode::Eof => {
             let eof = inspector.read_eof()?;

vortex-tui/src/tree.rs

@@ -4,9 +4,11 @@
 use std::path::Path;
 use std::path::PathBuf;
 
+use serde::Serialize;
 use vortex::array::stream::ArrayStreamExt;
 use vortex::error::VortexResult;
 use vortex::file::OpenOptionsSessionExt;
+use vortex::layout::LayoutRef;
 
 use crate::SESSION;
 
@@ -23,6 +25,9 @@ pub enum TreeMode {
     Array {
         /// Path to the Vortex file
         file: PathBuf,
+        /// Output as JSON
+        #[arg(long)]
+        json: bool,
     },
     /// Display the layout tree structure (metadata only, no array loading)
     Layout {
@@ -31,19 +36,43 @@ pub enum TreeMode {
         /// Show additional metadata information
         #[arg(short, long)]
         verbose: bool,
+        /// Output as JSON
+        #[arg(long)]
+        json: bool,
     },
 }
 
+#[derive(Serialize)]
+pub struct LayoutTreeNode {
+    pub encoding: String,
+    pub dtype: String,
+    pub row_count: u64,
+    pub metadata_bytes: usize,
+    pub segment_ids: Vec<u32>,
+    pub children: Vec<LayoutTreeNodeWithName>,
+}
+
+#[derive(Serialize)]
+pub struct LayoutTreeNodeWithName {
+    pub name: String,
+    #[serde(flatten)]
+    pub node: LayoutTreeNode,
+}
+
 pub async fn exec_tree(args: TreeArgs) -> VortexResult<()> {
     match args.mode {
-        TreeMode::Array { file } => exec_array_tree(&file).await?,
-        TreeMode::Layout { file, verbose } => exec_layout_tree(&file, verbose).await?,
+        TreeMode::Array { file, json } => exec_array_tree(&file, json).await?,
+        TreeMode::Layout {
+            file,
+            verbose,
+            json,
+        } => exec_layout_tree(&file, verbose, json).await?,
     }
 
     Ok(())
 }
 
-async fn exec_array_tree(file: &Path) -> VortexResult<()> {
+async fn exec_array_tree(file: &Path, _json: bool) -> VortexResult<()> {
     let full = SESSION
         .open_options()
         .open(file)
@@ -53,16 +82,50 @@ async fn exec_array_tree(file: &Path) -> VortexResult<()> {
         .read_all()
         .await?;
 
+    // TODO: Add JSON output support for array tree
     println!("{}", full.display_tree());
 
     Ok(())
 }
 
-async fn exec_layout_tree(file: &Path, verbose: bool) -> VortexResult<()> {
+async fn exec_layout_tree(file: &Path, verbose: bool, json: bool) -> VortexResult<()> {
     let vxf = SESSION.open_options().open(file).await?;
     let footer = vxf.footer();
 
-    println!("{}", footer.layout().display_tree_verbose(verbose));
+    if json {
+        let tree = layout_to_json(footer.layout().clone())?;
+        let json_output = serde_json::to_string_pretty(&tree)
+            .map_err(|e| vortex::error::vortex_err!("Failed to serialize JSON: {e}"))?;
+        println!("{json_output}");
+    } else {
+        println!("{}", footer.layout().display_tree_verbose(verbose));
+    }
 
     Ok(())
 }
+
+fn layout_to_json(layout: LayoutRef) -> VortexResult<LayoutTreeNode> {
+    let children = layout.children()?;
+    let child_names: Vec<_> = layout.child_names().collect();
+
+    let children_json: Vec<LayoutTreeNodeWithName> = children
+        .into_iter()
+        .zip(child_names.into_iter())
+        .map(|(child, name)| {
+            let node = layout_to_json(child)?;
+            Ok(LayoutTreeNodeWithName {
+                name: name.to_string(),
+                node,
+            })
+        })
+        .collect::<VortexResult<Vec<_>>>()?;
+
+    Ok(LayoutTreeNode {
+        encoding: layout.encoding().to_string(),
+        dtype: layout.dtype().to_string(),
+        row_count: layout.row_count(),
+        metadata_bytes: layout.metadata().len(),
+        segment_ids: layout.segment_ids().iter().map(|s| **s).collect(),
+        children: children_json,
+    })
+}