codeowners_rs/
lib.rs

1//! This is a library for working with GitHub [CODEOWNERS
2//! files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
3//! CODEOWNERS files declare which GitHub users or teams are responsible for
4//! files in a repository. The pattern syntax is loosely based on the glob-style
5//! patterns used in .gitignore files.
6//!
7//! ## Parsing CODEOWNERS files
8//! The [`parse`] and [`parse_file`] functions can be used to parse a CODEOWNERS
9//! file into a [`parser::ParseResult`], which wraps a vec of [`parser::Rule`]s
10//! and a vec of any [`parser::ParseError`]s that were encountered. The
11//! [`parser::Rule`] struct contains full syntactic information about the rule,
12//! including the leading and trailing comments, and the byte offsets for each
13//! component of the rule. This is useful when you care about the CODEOWNERS
14//! syntax, for instance when writing a syntax highlighter, but it's not very
15//! ergonomic for most use cases.
16//!
17//! The [`RuleSet`] struct provides a more ergonomic interface for working with
18//! CODEOWNERS files. It can be constructed by calling
19//! [`into_ruleset`](fn@parser::ParseResult::into_ruleset) on a
20//! [`parser::ParseResult`].
21//!
22//! ## Matching paths against CODEOWNERS files
23//! The [`RuleSet`] struct provides a [`owners`](fn@RuleSet::owners) method that
24//! can be used to match a path against a CODEOWNERS file. To get the matching
25//! rule rather than just the owners, use the
26//! [`matching_rule`](fn@RuleSet::matching_rule) method.
27//!
28//!
29//! ## Example
30//! ```
31//! use codeowners_rs::{parse, RuleSet};
32//!
33//! let ruleset = parse("
34//! *.rs @github/rustaceans
35//! /docs/**/*.md @github/docs-team
36//! ").into_ruleset();
37//!
38//! for path in &["src/main.rs", "docs/README.md", "README.md"] {
39//!    let owners = ruleset.owners(path);
40//!    println!("{}: {:?}", path, owners);
41//! }
42//! ```
43//!
44//! ## Command line interface
45//! There is a companion binary crate that provides a simple CLI for matching
46//! paths against a CODEOWNERS file.
47
48pub mod parser;
49pub mod patternset;
50mod ruleset;
51
52pub use parser::{parse, parse_file};
53pub use ruleset::{Owner, Rule, RuleSet};