updating README with usage examples

perryqh · perryqh · commit 0c00aabe0329 · 2025-08-21T21:06:45.000-05:00
diff --git a/README.md b/README.md
@@ -190,3 +190,44 @@ codeowners for-team Payroll
   ```
 
 - Please update `CHANGELOG.md` and this `README.md` when making changes.
+
+### Module layout (for library users)
+
+- `src/runner.rs`: public façade re-exporting the API and types.
+- `src/runner/api.rs`: externally available functions used by the CLI and other crates.
+- `src/runner/types.rs`: `RunConfig`, `RunResult`, and runner `Error`.
+- `src/ownership/`: all ownership logic (parsing, mapping, validation, generation).
+- `src/ownership/codeowners_query.rs`: CODEOWNERS-only queries consumed by the façade.
+
+Import public APIs from `codeowners::runner::*`.
+
+### Library usage example
+
+```rust
+use codeowners::runner::{RunConfig, for_file, teams_for_files_from_codeowners};
+
+fn main() {
+    let run_config = RunConfig {
+        project_root: std::path::PathBuf::from("."),
+        codeowners_file_path: std::path::PathBuf::from(".github/CODEOWNERS"),
+        config_path: std::path::PathBuf::from("config/code_ownership.yml"),
+        no_cache: true, // set false to enable on-disk caching
+    };
+
+    // Find owner for a single file using the optimized path (not just CODEOWNERS)
+    let result = for_file(&run_config, "app/models/user.rb", false);
+    for msg in result.info_messages { println!("{}", msg); }
+    for err in result.io_errors { eprintln!("io: {}", err); }
+    for err in result.validation_errors { eprintln!("validation: {}", err); }
+
+    // Map multiple files to teams using CODEOWNERS rules only
+    let files = vec![
+        "app/models/user.rb".to_string(),
+        "config/teams/payroll.yml".to_string(),
+    ];
+    match teams_for_files_from_codeowners(&run_config, &files) {
+        Ok(map) => println!("{:?}", map),
+        Err(e) => eprintln!("error: {}", e),
+    }
+}
+```
diff --git a/src/runner.rs b/src/runner.rs
@@ -242,119 +242,10 @@ impl Runner {
 
 #[cfg(test)]
 mod tests {
-    use std::path::Path;
-    use tempfile::tempdir;
-
     use super::*;
-    use crate::{common_test, ownership::mapper::Source};
 
     #[test]
     fn test_version() {
         assert_eq!(version(), env!("CARGO_PKG_VERSION").to_string());
     }
-    fn write_file(temp_dir: &Path, file_path: &str, content: &str) {
-        let file_path = temp_dir.join(file_path);
-        let _ = std::fs::create_dir_all(file_path.parent().unwrap());
-        std::fs::write(file_path, content).unwrap();
-    }
-
-    #[test]
-    fn test_file_owners_for_file() {
-        let temp_dir = tempdir().unwrap();
-        write_file(
-            temp_dir.path(),
-            "config/code_ownership.yml",
-            common_test::tests::DEFAULT_CODE_OWNERSHIP_YML,
-        );
-        ["a", "b", "c"].iter().for_each(|name| {
-            let team_yml = format!("name: {}\ngithub:\n  team: \"@{}\"\n  members:\n    - {}member\n", name, name, name);
-            write_file(temp_dir.path(), &format!("config/teams/{}.yml", name), &team_yml);
-        });
-        write_file(
-            temp_dir.path(),
-            "app/consumers/deep/nesting/nestdir/deep_file.rb",
-            "# @team b\nclass DeepFile end;",
-        );
-
-        let run_config = RunConfig {
-            project_root: temp_dir.path().to_path_buf(),
-            codeowners_file_path: temp_dir.path().join(".github/CODEOWNERS").to_path_buf(),
-            config_path: temp_dir.path().join("config/code_ownership.yml").to_path_buf(),
-            no_cache: false,
-        };
-
-        let file_owner = file_owner_for_file(&run_config, "app/consumers/deep/nesting/nestdir/deep_file.rb")
-            .unwrap()
-            .unwrap();
-        assert_eq!(file_owner.team.name, "b");
-        assert_eq!(file_owner.team.github_team, "@b");
-        assert!(file_owner.team.path.to_string_lossy().ends_with("config/teams/b.yml"));
-        assert_eq!(file_owner.sources.len(), 1);
-        assert_eq!(file_owner.sources, vec![Source::AnnotatedFile]);
-
-        let team = team_for_file(&run_config, "app/consumers/deep/nesting/nestdir/deep_file.rb")
-            .unwrap()
-            .unwrap();
-        assert_eq!(team.name, "b");
-        assert_eq!(team.github_team, "@b");
-        assert!(team.path.to_string_lossy().ends_with("config/teams/b.yml"));
-    }
-
-    #[test]
-    fn test_teams_for_files_from_codeowners() {
-        let project_root = Path::new("tests/fixtures/valid_project");
-        let file_paths = [
-            "javascript/packages/items/item.ts",
-            "config/teams/payroll.yml",
-            "ruby/app/models/bank_account.rb",
-            "made/up/file.rb",
-            "ruby/ignored_files/git_ignored.rb",
-        ];
-        let run_config = RunConfig {
-            project_root: project_root.to_path_buf(),
-            codeowners_file_path: project_root.join(".github/CODEOWNERS").to_path_buf(),
-            config_path: project_root.join("config/code_ownership.yml").to_path_buf(),
-            no_cache: false,
-        };
-        let teams =
-            teams_for_files_from_codeowners(&run_config, &file_paths.iter().map(|s| s.to_string()).collect::<Vec<String>>()).unwrap();
-        assert_eq!(teams.len(), 5);
-        assert_eq!(
-            teams
-                .get("javascript/packages/items/item.ts")
-                .unwrap()
-                .as_ref()
-                .map(|t| t.name.as_str()),
-            Some("Payroll")
-        );
-        assert_eq!(
-            teams.get("config/teams/payroll.yml").unwrap().as_ref().map(|t| t.name.as_str()),
-            Some("Payroll")
-        );
-        assert_eq!(
-            teams
-                .get("ruby/app/models/bank_account.rb")
-                .unwrap()
-                .as_ref()
-                .map(|t| t.name.as_str()),
-            Some("Payments")
-        );
-        assert_eq!(teams.get("made/up/file.rb").unwrap().as_ref().map(|t| t.name.as_str()), None);
-        assert_eq!(
-            teams
-                .get("ruby/ignored_files/git_ignored.rb")
-                .unwrap()
-                .as_ref()
-                .map(|t| t.name.as_str()),
-            None
-        );
-        assert_eq!(
-            teams
-                .get("ruby/ignored_files/git_ignored.rb")
-                .unwrap()
-                .as_ref()
-                .map(|t| t.name.as_str()),
-            None
-        );
-    }
 }
diff --git a/tests/runner_api.rs b/tests/runner_api.rs
@@ -0,0 +1,189 @@
+use std::path::Path;
+
+use codeowners::runner::{self, RunConfig};
+
+fn write_file(temp_dir: &Path, file_path: &str, content: &str) {
+    let file_path = temp_dir.join(file_path);
+    let _ = std::fs::create_dir_all(file_path.parent().unwrap());
+    std::fs::write(file_path, content).unwrap();
+}
+
+#[test]
+fn test_file_owners_for_file() {
+    let temp_dir = tempfile::tempdir().unwrap();
+    const DEFAULT_CODE_OWNERSHIP_YML: &str = r#"---
+owned_globs:
+  - "{app,components,config,frontend,lib,packs,spec,ruby}/**/*.{rb,rake,js,jsx,ts,tsx,json,yml,erb}"
+unowned_globs:
+  - config/code_ownership.yml
+javascript_package_paths:
+  - javascript/packages/**
+vendored_gems_path: gems
+team_file_glob:
+  - config/teams/**/*.yml
+"#;
+    write_file(temp_dir.path(), "config/code_ownership.yml", DEFAULT_CODE_OWNERSHIP_YML);
+    ["a", "b", "c"].iter().for_each(|name| {
+        let team_yml = format!(
+            "name: {}\ngithub:\n  team: \"@{}\"\n  members:\n    - {}member\n",
+            name, name, name
+        );
+        write_file(temp_dir.path(), &format!("config/teams/{}.yml", name), &team_yml);
+    });
+    write_file(
+        temp_dir.path(),
+        "app/consumers/deep/nesting/nestdir/deep_file.rb",
+        "# @team b\nclass DeepFile end;",
+    );
+
+    let run_config = RunConfig {
+        project_root: temp_dir.path().to_path_buf(),
+        codeowners_file_path: temp_dir.path().join(".github/CODEOWNERS").to_path_buf(),
+        config_path: temp_dir.path().join("config/code_ownership.yml").to_path_buf(),
+        no_cache: true,
+    };
+
+    let file_owner = runner::file_owner_for_file(&run_config, "app/consumers/deep/nesting/nestdir/deep_file.rb")
+        .unwrap()
+        .unwrap();
+    assert_eq!(file_owner.team.name, "b");
+    assert_eq!(file_owner.team.github_team, "@b");
+    assert!(file_owner.team.path.to_string_lossy().ends_with("config/teams/b.yml"));
+}
+
+#[test]
+fn test_teams_for_files_from_codeowners() {
+    let project_root = Path::new("tests/fixtures/valid_project");
+    let file_paths = [
+        "javascript/packages/items/item.ts",
+        "config/teams/payroll.yml",
+        "ruby/app/models/bank_account.rb",
+        "made/up/file.rb",
+        "ruby/ignored_files/git_ignored.rb",
+    ];
+    let run_config = RunConfig {
+        project_root: project_root.to_path_buf(),
+        codeowners_file_path: project_root.join(".github/CODEOWNERS").to_path_buf(),
+        config_path: project_root.join("config/code_ownership.yml").to_path_buf(),
+        no_cache: true,
+    };
+    let teams = runner::teams_for_files_from_codeowners(
+        &run_config,
+        &file_paths.iter().map(|s| s.to_string()).collect::<Vec<String>>(),
+    )
+    .unwrap();
+    assert_eq!(teams.len(), 5);
+    assert_eq!(
+        teams
+            .get("javascript/packages/items/item.ts")
+            .unwrap()
+            .as_ref()
+            .map(|t| t.name.as_str()),
+        Some("Payroll")
+    );
+    assert_eq!(
+        teams
+            .get("config/teams/payroll.yml")
+            .unwrap()
+            .as_ref()
+            .map(|t| t.name.as_str()),
+        Some("Payroll")
+    );
+    assert_eq!(
+        teams
+            .get("ruby/app/models/bank_account.rb")
+            .unwrap()
+            .as_ref()
+            .map(|t| t.name.as_str()),
+        Some("Payments")
+    );
+    assert_eq!(teams.get("made/up/file.rb").unwrap().as_ref().map(|t| t.name.as_str()), None);
+    assert_eq!(
+        teams
+            .get("ruby/ignored_files/git_ignored.rb")
+            .unwrap()
+            .as_ref()
+            .map(|t| t.name.as_str()),
+        None
+    );
+}
+
+#[test]
+fn test_for_team_reads_codeowners() {
+    let td = tempfile::tempdir().unwrap();
+    // minimal config
+    const DEFAULT_CODE_OWNERSHIP_YML: &str = r#"---
+owned_globs:
+  - "app/**/*"
+unowned_globs:
+  - config/code_ownership.yml
+team_file_glob:
+  - config/teams/**/*.yml
+vendored_gems_path: gems
+javascript_package_paths:
+  - javascript/packages/**
+"#;
+    write_file(td.path(), "config/code_ownership.yml", DEFAULT_CODE_OWNERSHIP_YML);
+
+    // team file for Foo
+    write_file(
+        td.path(),
+        "config/teams/foo.yml",
+        "name: Foo\ngithub:\n  team: \"@Foo\"\n  members:\n    - user\n",
+    );
+    // provide a CODEOWNERS file referencing @Foo
+    write_file(td.path(), ".github/CODEOWNERS", "/app/** @Foo\n");
+
+    let rc = RunConfig {
+        project_root: td.path().to_path_buf(),
+        codeowners_file_path: td.path().join(".github/CODEOWNERS"),
+        config_path: td.path().join("config/code_ownership.yml"),
+        no_cache: true,
+    };
+
+    // Ensure CODEOWNERS file matches generator output to avoid out-of-date errors
+    let _ = runner::generate(&rc, false);
+    let res = runner::for_team(&rc, "Foo");
+    assert!(res.io_errors.is_empty(), "unexpected io errors: {:?}", res.io_errors);
+    assert!(res.validation_errors.is_empty());
+    assert!(res.info_messages.iter().any(|m| m.contains("# Code Ownership Report for `Foo` Team")));
+}
+
+#[test]
+fn test_validate_and_generate_and_validate() {
+    let td = tempfile::tempdir().unwrap();
+    // config and team so generation has inputs
+    const DEFAULT_CODE_OWNERSHIP_YML: &str = r#"---
+owned_globs:
+  - "**/*"
+team_file_glob:
+  - config/teams/**/*.yml
+vendored_gems_path: gems
+javascript_package_paths:
+  - javascript/packages/**
+"#;
+    write_file(td.path(), "config/code_ownership.yml", DEFAULT_CODE_OWNERSHIP_YML);
+    write_file(
+        td.path(),
+        "config/teams/foo.yml",
+        "name: Foo\ngithub:\n  team: \"@Foo\"\n  members:\n    - user\nowned_globs:\n  - \"app/**\"\n  - \"config/code_ownership.yml\"\n",
+    );
+    // create a file to be matched (no annotation to avoid multi-source ownership)
+    write_file(td.path(), "app/x.rb", "puts :x\n");
+
+    let rc = RunConfig {
+        project_root: td.path().to_path_buf(),
+        codeowners_file_path: td.path().join(".github/CODEOWNERS"),
+        config_path: td.path().join("config/code_ownership.yml"),
+        no_cache: true,
+    };
+
+    let gv = runner::generate_and_validate(&rc, vec![], true);
+    assert!(gv.io_errors.is_empty(), "io: {:?}", gv.io_errors);
+    assert!(gv.validation_errors.is_empty(), "val: {:?}", gv.validation_errors);
+    // file should exist after generate
+    let content = std::fs::read_to_string(td.path().join(".github/CODEOWNERS")).unwrap();
+    assert!(!content.is_empty());
+}
+
+
