docs/generated/contracts.mdgenerated from code
Reference · 3 min read
paths
Contracts: paths.
Read as
Source: crates/lvcs-doc/src/paths/mod.rs.
1/// A set of gitignore-syntax patterns, matched against document addresses2/// (discussion:owner/64). The lines keep their gitignore meaning: the last line that3/// matches the address, or a directory above it, decides, so a `!` line4/// re-includes what an earlier line matched, and blank and `#` lines match5/// nothing. With `case_insensitive`, ASCII letters match either case and6/// every other character matches only itself (ASCII folding, discussion:owner/122),7/// as a case-insensitive filesystem resolves `BUILD.RS` to `build.rs`.8#[derive(Debug, Clone)]9pub struct PathSet {10 matcher: Arc<Gitignore>,11}1213/// Why a [`PathSet`] didn't build.14#[derive(Debug, Clone, PartialEq, Eq)]15pub enum PathSetError {16 /// A line gitignore syntax refuses, with the reason.17 Pattern { pattern: String, reason: String },18 /// Every line parsed, but the set didn't compile.19 Build { reason: String },20}2122impl PathSet {23 /// The set of `patterns`, one gitignore line each, in order. A set24 /// built before from the same lines is shared rather than compiled25 /// again ([`COMPILED`]).26 pub fn new<I>(patterns: I, case_insensitive: bool) -> Result<Self, PathSetError>27 where28 I: IntoIterator,29 I::Item: AsRef<str>,30 {31 let lines: Vec<String> = patterns32 .into_iter()33 .map(|pattern| pattern.as_ref().to_owned())34 .collect();35 let key = (case_insensitive, lines);36 let compiled = || COMPILED.lock().unwrap_or_else(PoisonError::into_inner);37 if let Some(matcher) = compiled().get(&key) {38 return Ok(Self {39 matcher: Arc::clone(matcher),40 });41 }42 let build = |err: ignore::Error| PathSetError::Build {43 reason: err.to_string(),44 };45 let mut builder = GitignoreBuilder::new("");46 // Before any line: the setting applies to lines added after it.47 builder.case_insensitive(case_insensitive).map_err(build)?;48 for pattern in &key.1 {49 builder50 .add_line(None, pattern)51 .map_err(|err| PathSetError::Pattern {52 pattern: pattern.clone(),53 reason: err.to_string(),54 })?;55 }56 let matcher = Arc::new(builder.build().map_err(build)?);57 let mut cache = compiled();58 if cache.len() >= COMPILED_MAX {59 cache.clear();60 }61 cache.insert(key, Arc::clone(&matcher));62 Ok(Self { matcher })63 }6465 /// Whether the set matches the file at `address`: a line matches it or66 /// a directory above it, and no later `!` line re-includes it. An67 /// address that isn't a plain relative path, one whose every68 /// `/`-separated segment is a name (not empty, `.`, or `..`), matches69 /// nothing; no valid address (discussion:owner/64) is one.70 pub fn matches(&self, address: &str) -> bool {71 let plain = address72 .split('/')73 .all(|segment| !matches!(segment, "" | "." | ".."));74 plain75 && self76 .matcher77 .matched_path_or_any_parents(Path::new(address), false)78 .is_ignore()79 }80}8182/// Every [`PathSet`] built, by its case setting and lines: a set compiles83/// its lines into regular expressions, which a grant check, an inbox84/// interest, or an action's inputs did again on every call (a chain of85/// 1,500 held saves spent a quarter of the daemon's time compiling one86/// grant's paths). A set is a pure function of its key, so sharing one87/// changes no match.88static COMPILED: LazyLock<Mutex<Compiled>> = LazyLock::new(|| Mutex::new(HashMap::new()));8990/// [`COMPILED`]'s map: each set's matcher by its case setting and lines.91type Compiled = HashMap<(bool, Vec<String>), Arc<Gitignore>>;9293/// The most sets [`COMPILED`] keeps; past it, it starts over.94const COMPILED_MAX: usize = 4096;9596/// `DEFAULT_PROTECTED` as one case-insensitive [`PathSet`], built once:97/// the protected-path rule (discussion:owner/122).98pub fn protected() -> &'static PathSet {99 static PROTECTED: LazyLock<PathSet> = LazyLock::new(|| {100 PathSet::new(DEFAULT_PROTECTED.iter().map(|rule| rule.pattern), true)101 .expect("DEFAULT_PROTECTED is valid gitignore syntax")102 });103 &PROTECTED104}