fix(ml-cellar): add MLBin struct (#20)

Signed-off-by: scepter914 <scepter914@gmail.com>

Author: scepter914

src/bin/ml-cellar/check.rs

@@ -1,11 +1,14 @@
-use ml_cellar::rack::{RackConfig, load_config};
-
 use std::path::{Path, PathBuf};
 use walkdir::WalkDir;
 
-pub fn check_required_files(config: &RackConfig, target_directory_path: &Path) {
+use ml_cellar::cellar::load_cellar_config;
+use ml_cellar::ml_bin::MLBin;
+use ml_cellar::rack::{RackConfig, load_rack_config};
+
+/// Checks that all required files defined in the rack configuration exist in the ML-bin.
+fn check_required_files(config: &RackConfig, ml_bin: &MLBin) {
     for required_filename in &config.artifact.required_files {
-        let required_file_path = target_directory_path.join(required_filename);
+        let required_file_path = ml_bin.get_full_path().join(required_filename);
         if !required_file_path.exists() {
             log::error!("Required file of {:?} is missing", required_file_path);
             std::process::exit(1);
@@ -14,14 +17,16 @@ pub fn check_required_files(config: &RackConfig, target_directory_path: &Path) {
     log::info!("All required files are confirmed");
 }
 
-pub fn check_optional_files(config: &RackConfig, target_directory_path: &PathBuf) {
-    let files_in_target_directory: Vec<PathBuf> = WalkDir::new(target_directory_path)
+/// Checks that all files in the ML-bin are either required or optional files
+/// as defined in the rack configuration.
+fn check_optional_files(config: &RackConfig, ml_bin: &MLBin) {
+    let files_in_target_directory: Vec<PathBuf> = WalkDir::new(ml_bin.get_full_path())
         .into_iter()
         .filter_map(|e| e.ok())
         .filter(|p| p.file_type().is_file())
         .filter_map(|e| {
             e.path()
-                .strip_prefix(target_directory_path)
+                .strip_prefix(ml_bin.get_full_path())
                 .ok()
                 .map(Path::to_path_buf)
         })
@@ -39,39 +44,54 @@ pub fn check_optional_files(config: &RackConfig, target_directory_path: &PathBuf
     log::info!("All files are required files or optional files");
 }
 
-pub fn check_version(config: &RackConfig, config_dir: &PathBuf, target_directory_path: &Path) {
-    let target_directory_path_from_config_dir = target_directory_path
-        .strip_prefix(config_dir)
-        .unwrap_or(target_directory_path)
-        .to_path_buf();
+/// Checks that the ML-bin version follows the valid version format
+/// defined in the project configuration.
+fn check_version(config: &RackConfig, ml_bin: &MLBin) {
     if config
         .project
-        .is_valid_version(&target_directory_path_from_config_dir)
+        .is_valid_version(ml_bin.project_name.to_str().unwrap(), &ml_bin.version)
     {
         log::info!("Version format is valid");
     } else {
         log::error!(
             "Version format is invalid at {:?}.\n
              Please check ProjectConfig of {:?} ",
-            target_directory_path_from_config_dir,
+            ml_bin.get_full_path(),
             config.project
         );
         std::process::exit(1);
     }
 }
 
-pub fn check(target_directory_path: PathBuf) {
-    if !target_directory_path.exists() {
-        log::error!("{:?} does not exist", target_directory_path);
+/// Performs comprehensive validation checks on an ML-bin directory.
+///
+/// This function validates that:
+/// - All required files exist in the ML-bin
+/// - All files in the ML-bin are either required or optional
+/// - The version format follows the project's versioning rules
+///
+/// # Arguments
+///
+/// - `path` - Path to the ML-bin directory to check
+///
+/// # Panics
+///
+/// Exits the process with code 1 if:
+/// - The path does not exist
+/// - Any validation check fails
+///
+pub fn check(path: PathBuf) {
+    if !path.exists() {
+        log::error!("{:?} does not exist", path);
         std::process::exit(1);
-    } else {
-        log::info!(
-            "Checking artifacts in rack at {:?}",
-            target_directory_path.display()
-        );
-        let (config, config_dir) = load_config(&target_directory_path);
-        check_required_files(&config, &target_directory_path);
-        check_optional_files(&config, &target_directory_path);
-        check_version(&config, &config_dir, &target_directory_path);
     }
+    log::info!("Checking artifacts in rack at {:?}", path);
+
+    let (rack_config, rack_directory) = load_rack_config(&path);
+    let (_cellar_config, cellar_directory) = load_cellar_config(&path);
+    let ml_bin = MLBin::from_ml_bin_path(path, cellar_directory, rack_directory);
+
+    check_required_files(&rack_config, &ml_bin);
+    check_optional_files(&rack_config, &ml_bin);
+    check_version(&rack_config, &ml_bin);
 }

src/bin/ml-cellar/clone.rs

@@ -1,5 +1,22 @@
 use std::process::{Command, Stdio};
 
+/// Clones a Git repository without downloading Git LFS file contents.
+///
+/// This function clones a Git repository with `GIT_LFS_SKIP_SMUDGE=1` environment variable set,
+/// which means Git LFS pointers are cloned instead of the actual large files.
+/// This is useful for creating a lightweight clone of a model registry where you can
+/// selectively materialize only the files you need later.
+///
+/// # Arguments
+///
+/// - `repository` - The Git repository URL to clone
+///
+/// # Panics
+///
+/// Exits the process with code 1 if:
+/// - The git clone command fails
+/// - Git is not installed or cannot be executed
+///
 pub fn clone(repository: String) {
     let status = Command::new("git")
         .env("GIT_LFS_SKIP_SMUDGE", "1")

src/bin/ml-cellar/docs.rs

@@ -2,8 +2,11 @@ use regex::Regex;
 use serde_json::Value;
 use std::path::{Path, PathBuf};
 
-use ml_cellar::rack::{RackConfig, load_config};
+use ml_cellar::rack::{RackConfig, load_rack_config};
 
+/// Looks up a value in a JSON object using a dot-separated path.
+/// This function traverses a JSON structure using a path string like "a.b.c"
+/// to access nested fields. It supports both object fields and array indices.
 fn lookup_json_path<'a>(root: &'a Value, path: &str) -> Option<&'a Value> {
     let mut cur = root;
 
@@ -24,6 +27,7 @@ fn lookup_json_path<'a>(root: &'a Value, path: &str) -> Option<&'a Value> {
     Some(cur)
 }
 
+/// Converts a JSON value to a text string representation.
 fn value_to_text(v: &Value) -> String {
     match v {
         // Delete " "
@@ -38,7 +42,11 @@ fn value_to_text(v: &Value) -> String {
     }
 }
 
-/// Replace {a.b.c} in template file to JSON value
+/// Replaces placeholders in a markdown template with values from JSON data.
+/// This function finds all placeholders in the format `{a.b.c}` in the template
+/// and replaces them with corresponding values from the JSON data.
+/// If a placeholder is not found in the JSON, a warning is logged and the
+/// placeholder is kept as-is in the output.
 fn render_markdown_template(template: &str, data: &Value) -> String {
     let re = Regex::new(r"\{([^{}]+)\}").expect("invalid regex");
 
@@ -57,6 +65,7 @@ fn render_markdown_template(template: &str, data: &Value) -> String {
     .to_string()
 }
 
+/// Loads the template markdown file specified in the rack configuration.
 fn load_template_file(config: &RackConfig, config_dir: &Path) -> String {
     let template_file_path = config_dir.join(config.document.template_file.as_ref().unwrap());
     match std::fs::read_to_string(&template_file_path) {
@@ -68,7 +77,10 @@ fn load_template_file(config: &RackConfig, config_dir: &Path) -> String {
     }
 }
 
-fn load_result_json(model_version_path: &Path, config: &RackConfig, config_dir: &Path) -> Value {
+/// Loads and parses the result JSON file from the ML-bin directory.
+/// This function loads the JSON file containing evaluation results and metrics
+/// for the ML model, as specified in the rack configuration.
+fn load_result_json(ml_bin_path: &Path, config: &RackConfig, config_dir: &Path) -> Value {
     if config.document.result_file.is_none() {
         log::error!(
             "Documentation configuration is not set up in {:?}.\n
@@ -78,7 +90,7 @@ fn load_result_json(model_version_path: &Path, config: &RackConfig, config_dir:
         std::process::exit(1);
     }
 
-    let result_file_path = model_version_path.join(config.document.result_file.as_ref().unwrap());
+    let result_file_path = ml_bin_path.join(config.document.result_file.as_ref().unwrap());
 
     let json_text = match std::fs::read_to_string(&result_file_path) {
         Ok(s) => s,
@@ -96,20 +108,40 @@ fn load_result_json(model_version_path: &Path, config: &RackConfig, config_dir:
     }
 }
 
-pub fn docs(model_version_path: PathBuf) {
-    if !model_version_path.exists() {
-        log::error!("{:?} does not exist", model_version_path);
+/// Generates documentation for an ML-bin by rendering a template with result data.
+///
+/// This function:
+/// 1. Loads the rack configuration
+/// 2. Loads the result JSON file from the ML-bin
+/// 3. Loads the template markdown file
+/// 4. Replaces `{{version}}` with the full model version path
+/// 5. Replaces `{field.name}` placeholders with values from the result JSON
+/// 6. Prints the rendered documentation
+///
+/// # Arguments
+///
+/// - `ml_bin_path` - Path to the ML-bin directory to generate documentation for
+///
+/// # Panics
+///
+/// Exits the process with code 1 if:
+/// - The ML-bin path does not exist
+/// - The configuration or result files cannot be loaded
+/// - Template rendering fails
+pub fn docs(ml_bin_path: PathBuf) {
+    if !ml_bin_path.exists() {
+        log::error!("{:?} does not exist", ml_bin_path);
         std::process::exit(1);
     }
 
-    let (config, config_dir) = load_config(&model_version_path);
-    let json_value = load_result_json(&model_version_path, &config, &config_dir);
+    let (config, config_dir) = load_rack_config(&ml_bin_path);
+    let json_value = load_result_json(&ml_bin_path, &config, &config_dir);
     let template_text = load_template_file(&config, &config_dir);
 
     // Replace {{version}} with model version
-    let path_from_config_dir = model_version_path
+    let path_from_config_dir = ml_bin_path
         .strip_prefix(config_dir)
-        .unwrap_or(&model_version_path)
+        .unwrap_or(&ml_bin_path)
         .to_path_buf();
     let project_name = match path_from_config_dir.parent().and_then(|p| p.to_str()) {
         Some(s) => s.to_string(),
@@ -127,7 +159,7 @@ pub fn docs(model_version_path: PathBuf) {
     let rendered = render_markdown_template(&rendered_version, &json_value);
     log::info!(
         "Generate documentation for model version at path: {:?}",
-        model_version_path
+        ml_bin_path
     );
     print!("\n\n {rendered} \n\n");
 }

src/bin/ml-cellar/init.rs

@@ -1,9 +1,27 @@
 use std::process::{Command, Stdio};
 use toml::to_string_pretty;
 
+use ml_cellar::cellar::CellarConfig;
 use ml_cellar::file::GITATTRIBUTES;
-use ml_cellar::repository::RepositoryConfig;
 
+/// Initializes a new ml-cellar model registry repository.
+///
+/// This function sets up a new Git repository configured for use with ml-cellar by:
+/// 1. Initializing a new Git repository (`git init`)
+/// 2. Renaming the default branch to "main" (`git branch -M main`)
+/// 3. Creating a `.gitattributes` file with Git LFS configuration for common ML file types
+/// 4. Creating a `.mlcellar.toml` configuration file with default settings
+///
+/// The `.gitattributes` file configures Git LFS to track large files commonly used in ML projects,
+/// such as model checkpoints, weights, and data files.
+///
+/// # Panics
+///
+/// Exits the process with code 1 if:
+/// - Git is not installed or cannot be executed
+/// - `git init` or `git branch -M main` commands fail
+/// - `.gitattributes` or `.mlcellar.toml` files cannot be written
+///
 pub fn init() {
     // Git init
     let status = Command::new("git")
@@ -59,8 +77,7 @@ pub fn init() {
     std::fs::write(".gitattributes", GITATTRIBUTES).expect("failed to write .gitattributes");
 
     // Make .mlcellar.toml
-    let config = RepositoryConfig::default();
-    let toml_str =
-        to_string_pretty(&config).expect("failed to serialize repository config to TOML");
+    let config = CellarConfig::default();
+    let toml_str = to_string_pretty(&config).expect("failed to serialize cellar config to TOML");
     std::fs::write(".mlcellar.toml", toml_str).expect("failed to write .mlcellar.toml");
 }