diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index abb437af..92b31e0b 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -234,7 +234,9 @@ bash demo/run_merge_ergonomics_demo.sh # sc conflicts/sc resolve proof (P # conflict both resolved end-to-end with no # hand-edited markers cargo run --bin sc -- sparse set [--identity ] # narrow the working tree to - # these path prefixes; re-lays disk now (P24) + # these path prefixes; re-lays disk now (P24). Warns per + # prefix that matches no tracked path; at least one + # prefix is required (`sparse disable` is the full view) cargo run --bin sc -- sparse show [--json] # list the active sparse prefixes ("disabled" if # the spec is empty/absent) (P24) cargo run --bin sc -- sparse disable [--identity ] # clear the spec and rematerialize diff --git a/ROADMAP.md b/ROADMAP.md index b8d9e2c1..7513fc6c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -743,11 +743,12 @@ scale-&-reach horizon): not a disclosure (an authorized identity produced it), documented in ADR-0034 — but the sparse view is briefly wider than advertised. Extend the gate to those write loops. -- **Sparse ergonomics (P24 final-review Minors).** A bogus/no-match - `sc sparse set ` empties the working tree with no warning - (recoverable via disable); a zero-arg `sc sparse set` silently equals - `disable`; blank lines in a hand-edited `.sc/sparse` want tolerant - parsing. Small usability hardening. +- **Sparse ergonomics (P24 final-review Minors) — shipped.** `sc sparse set` + warns for each prefix that matches no tracked path at HEAD (the tree is still + laid out, empty, and `sc sparse disable` is named as the way back); a bare + `sc sparse set` on a full clone is refused with a pointer to `sc sparse + disable` (a partial clone keeps its `sc backfill` refusal); and `.sc/sparse` + parsing ignores blank lines. - **Transparent lazy-fetch for partial clones (P27).** `sc backfill` is explicit-only by design (ADR-0037's "no network in read paths" choice); the identical filtered-walk/gap infra could instead dial the promisor diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index b6d2d10b..71aa530c 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -1088,9 +1088,33 @@ fn run_sparse(op: SparseOp) -> Result<()> { } SparseOp::Set { prefixes, identity } => { let repo = open_repo()?; + // No prefix is a full checkout, which is what `sparse disable` + // says. A partial clone still reaches the library, whose refusal + // names `sc backfill`. + if prefixes.is_empty() && repo.promisor()?.is_none() { + anyhow::bail!( + "no prefix given: `sc sparse set` needs at least one path prefix; \ + use `sc sparse disable` for a full checkout" + ); + } let sk = resolve_identity_opt(identity)?; let skipped = repo.set_sparse(&prefixes, sk.as_ref())?; println!("sparse set: {} prefix(es)", prefixes.len()); + // After the set: a lazy partial clone fills the new view during + // it, so a check before would warn about paths that then arrive. + let partial = repo.promisor()?.is_some(); + for p in repo.sparse_prefixes_matching_nothing(&prefixes)? { + let way_back = if partial { + "this is a partial clone: choose a prefix inside what was fetched, or run \ + `sc backfill --all` first and then `sc sparse disable`" + } else { + "`sc sparse disable` restores the full checkout" + }; + eprintln!( + "warning: prefix {p:?} matches no tracked path at HEAD, so none of it is on \ + disk; {way_back}" + ); + } for path in &skipped { eprintln!("skipped (no key): {path}"); } diff --git a/crates/cli/tests/sparse_ergonomics.rs b/crates/cli/tests/sparse_ergonomics.rs new file mode 100644 index 00000000..d667976e --- /dev/null +++ b/crates/cli/tests/sparse_ergonomics.rs @@ -0,0 +1,74 @@ +//! `sc sparse set` usability guards (P24 follow-ons): a prefix that matches +//! nothing is warned about, and a bare `sparse set` points at `sparse disable`. + +use std::process::Command; + +fn sc(dir: &std::path::Path, args: &[&str]) -> std::process::Output { + Command::new(env!("CARGO_BIN_EXE_sc")) + .args(args) + .current_dir(dir) + .output() + .expect("sc runs") +} + +fn stderr(out: &std::process::Output) -> String { + String::from_utf8_lossy(&out.stderr).into_owned() +} + +fn repo(tag: &str) -> std::path::PathBuf { + let root = + std::env::temp_dir().join(format!("scl-cli-sparse-ergo-{tag}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(root.join("src")).unwrap(); + std::fs::create_dir_all(root.join("docs")).unwrap(); + assert!(sc(&root, &["init"]).status.success()); + std::fs::write(root.join("src/a.txt"), "a\n").unwrap(); + std::fs::write(root.join("docs/b.txt"), "b\n").unwrap(); + assert!(sc(&root, &["commit", "-m", "c1"]).status.success()); + root +} + +/// A prefix naming nothing empties the tree; the command still succeeds, but +/// says so, and names the way back. +#[test] +fn a_prefix_matching_no_tracked_path_is_warned_about() { + let root = repo("nomatch"); + let out = sc(&root, &["sparse", "set", "sorc/"]); + assert!(out.status.success(), "{}", stderr(&out)); + let err = stderr(&out); + assert!(err.contains("matches no tracked path"), "{err}"); + assert!(err.contains("sc sparse disable"), "{err}"); + assert!(!root.join("src/a.txt").exists(), "the view really is empty"); + + // A real prefix draws no warning, and a mixed set warns only for the miss. + assert!(sc(&root, &["sparse", "disable"]).status.success()); + let ok = sc(&root, &["sparse", "set", "src/"]); + assert!(ok.status.success()); + assert!( + !stderr(&ok).contains("matches no tracked path"), + "{}", + stderr(&ok) + ); + let mixed = sc(&root, &["sparse", "set", "src/", "nope/"]); + assert!(mixed.status.success()); + let err = stderr(&mixed); + assert!(err.contains("\"nope/\""), "{err}"); + assert!(!err.contains("\"src/\""), "{err}"); + std::fs::remove_dir_all(&root).unwrap(); + assert!(!root.exists()); +} + +/// With no prefix `sparse set` was a silent `sparse disable`; it now refuses +/// and says which command means that. +#[test] +fn a_bare_sparse_set_points_at_disable() { + let root = repo("bare"); + assert!(sc(&root, &["sparse", "set", "src/"]).status.success()); + let out = sc(&root, &["sparse", "set"]); + assert!(!out.status.success(), "a bare `sparse set` must be refused"); + let err = stderr(&out); + assert!(err.contains("sc sparse disable"), "{err}"); + assert!(!root.join("docs/b.txt").exists(), "nothing was re-laid"); + std::fs::remove_dir_all(&root).unwrap(); + assert!(!root.exists()); +} diff --git a/crates/repo/src/sparse.rs b/crates/repo/src/sparse.rs index b6b937a6..57de9173 100644 --- a/crates/repo/src/sparse.rs +++ b/crates/repo/src/sparse.rs @@ -89,7 +89,14 @@ fn remove_if_exists(path: &std::path::Path) -> Result<()> { pub fn load(layout: &Layout) -> Result { match std::fs::read_to_string(layout.sparse_path()) { Ok(text) => { - let prefixes = text.lines().map(|l| l.to_string()).collect(); + // Blank lines (a hand edit, a trailing newline doubled) name no + // prefix; keep them out of the spec. + // `trim` only decides what is blank: a prefix keeps its bytes. + let prefixes = text + .lines() + .filter(|l| !l.trim().is_empty()) + .map(String::from) + .collect(); Ok(Sparse { prefixes }) } Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Sparse::default()), @@ -97,10 +104,27 @@ pub fn load(layout: &Layout) -> Result { } } +/// Refuse a blank prefix (empty or whitespace-only). It would be persisted as a +/// blank line, which `load` reads back as no prefix at all: a laid-out empty +/// view would turn into a full checkout on the next process, and every absent +/// file would then read as a deletion. No prefix at all (an empty list) is the +/// one spelling of a full view and is accepted. +pub(crate) fn validate_prefixes(prefixes: &[String]) -> Result<()> { + match prefixes.iter().find(|p| p.trim().is_empty()) { + Some(p) => Err(crate::error::Error::InvalidArgument(format!( + "empty sparse prefix {p:?}; name a path, or use `sc sparse disable` for a full checkout" + ))), + None => Ok(()), + } +} + /// Persist the repo's sparse spec, atomically. An empty spec removes the /// file entirely rather than writing an empty one, so `load` sees the same /// "no sparseness" state whether the file was never written or was cleared. pub fn store(layout: &Layout, s: &Sparse) -> Result<()> { + // The shared persistence boundary: a blank prefix would become a blank + // line that `load` reads back as no prefix. + validate_prefixes(&s.prefixes)?; if s.prefixes.is_empty() { return remove_if_exists(&layout.sparse_path()); } @@ -158,6 +182,35 @@ pub fn clear(layout: &Layout) -> Result<()> { remove_if_exists(&layout.sparse_path()) } +/// Whether the path `bare` (no trailing slash) exists in the tree at `root`, +/// as a file or a directory: `Some(true)`/`Some(false)`, or `None` when a tree +/// on the way is not held (a partial clone's gap), which is not an answer. +fn prefix_present( + store: &mut scl_core::Store, + root: scl_core::ObjectId, + bare: &str, +) -> Option { + // Literal components, as `Sparse::matches` reads the prefix: a leading + // slash or a doubled one names nothing, it is not skipped. + let comps: Vec<&str> = bare.split('/').collect(); + let mut cur = root; + for (i, comp) in comps.iter().enumerate() { + if !store.contains(&cur) { + return None; + } + let tree = store.get_tree(&cur).ok()?; + let Some(e) = tree.get(comp) else { + return Some(false); + }; + let last = i + 1 == comps.len(); + match e.kind { + scl_core::EntryKind::Tree if !last => cur = e.id, + _ => return Some(last), + } + } + Some(true) +} + impl Repo { /// The repo's current sparse-checkout spec (thin wrapper over `load`). pub fn sparse_spec(&self) -> Result { @@ -188,6 +241,8 @@ impl Repo { identity: Option<&scl_crypto::SecretKey>, ) -> Result> { self.refuse_on_private("sc sparse set")?; + // Before any side effect (the shared `store` checks again). + validate_prefixes(prefixes)?; if crate::merge_state::in_progress(&self.layout) { return Err(Error::MergeInProgress); } @@ -303,6 +358,28 @@ impl Repo { Ok(skipped) } + /// The prefixes in `prefixes` that match no tracked path at HEAD, so a + /// typo or a path that does not exist is not silently taken for a narrow + /// view that happens to be empty. Each prefix is one path-directed lookup + /// (depth, not tree size). A prefix whose answer needs an object this + /// partial clone does not hold is left out: the report is advice, never a + /// refusal, and never a guess. An unborn HEAD has no paths and reports + /// nothing; a private branch refuses, as `sparse set` does. + pub fn sparse_prefixes_matching_nothing(&self, prefixes: &[String]) -> Result> { + self.refuse_on_private("sc sparse set")?; + let Some(tip) = self.head_tip()? else { + return Ok(Vec::new()); + }; + let root = self.snapshot(&tip)?.root; + let store_arc = self.vfs().store(); + let mut store = store_arc.lock().unwrap(); + Ok(prefixes + .iter() + .filter(|p| prefix_present(&mut store, root, p.trim_end_matches('/')) == Some(false)) + .cloned() + .collect()) + } + /// Disable sparse checkout: clear the persisted spec and re-materialize /// HEAD's tree in full, restoring every previously-excluded file to disk. /// An unborn HEAD has no working tree to re-lay; the spec is still @@ -698,4 +775,113 @@ mod tests { std::fs::remove_dir_all(&src_root).unwrap(); std::fs::remove_dir_all(&dst_root).unwrap(); } + + #[test] + fn load_ignores_blank_lines_in_a_hand_edited_spec() { + let layout = tmp_layout("blank-lines"); + std::fs::write(layout.sparse_path(), "src/\n\n \ndocs/\n\n").unwrap(); + let spec = load(&layout).unwrap(); + assert_eq!(spec.prefixes(), ["src/", "docs/"]); + assert!( + !spec.matches("lib/x.txt"), + "a blank line must not widen the view" + ); + + // A nonblank prefix is kept byte for byte, significant whitespace + // included, across a store/load round trip. + let odd = Sparse::new(vec![" lead/".to_string(), "trail /".to_string()]); + store(&layout, &odd).unwrap(); + assert_eq!(load(&layout).unwrap().prefixes(), odd.prefixes()); + std::fs::remove_dir_all(&layout.root).unwrap(); + } + + #[test] + fn set_sparse_refuses_a_blank_prefix_and_leaves_the_tree_alone() { + let root = + std::env::temp_dir().join(format!("scl-sparse-blank-prefix-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(root.join("src")).unwrap(); + let repo = Repo::init(&root).unwrap(); + std::fs::write(root.join("src/a.txt"), b"a\n").unwrap(); + repo.commit("t", "c1").unwrap(); + for bad in ["", " "] { + let err = repo.set_sparse(&[bad.to_string()], None).unwrap_err(); + assert!( + matches!(&err, Error::InvalidArgument(m) if m.contains("empty sparse prefix")), + "got {err:?}" + ); + } + assert!(root.join("src/a.txt").exists(), "nothing was removed"); + assert!( + repo.sparse_spec().unwrap().is_full(), + "the spec is untouched" + ); + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + assert!(!root.exists()); + } + + #[test] + fn prefixes_matching_nothing_is_a_path_lookup() { + let root = std::env::temp_dir().join(format!("scl-sparse-nomatch-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&root); + std::fs::create_dir_all(root.join("src/deep")).unwrap(); + let repo = Repo::init(&root).unwrap(); + std::fs::write(root.join("src/deep/a.txt"), b"a\n").unwrap(); + std::fs::write(root.join("top.txt"), b"t\n").unwrap(); + repo.commit("t", "c1").unwrap(); + let ask = |ps: &[&str]| { + let ps: Vec = ps.iter().map(|p| p.to_string()).collect(); + repo.sparse_prefixes_matching_nothing(&ps).unwrap() + }; + assert!(ask(&["src/", "src/deep", "top.txt", "src/deep/a.txt"]).is_empty()); + assert_eq!( + ask(&["sorc/", "src/nope", "top.txt/x", "src/deep/a.txt/y"]).len(), + 4 + ); + // Literal, like `Sparse::matches`: a leading or doubled slash names + // nothing, so these are reported rather than read as `src/`. + let odd = ask(&["/src/", "src//deep", "/"]); + assert_eq!(odd.len(), 3, "got {odd:?}"); + drop(repo); + std::fs::remove_dir_all(&root).unwrap(); + assert!(!root.exists()); + } + + #[test] + fn a_blank_clone_filter_is_refused_before_anything_is_created() { + let src = std::env::temp_dir().join(format!("scl-blank-filter-src-{}", std::process::id())); + let dst = std::env::temp_dir().join(format!("scl-blank-filter-dst-{}", std::process::id())); + for r in [&src, &dst] { + let _ = std::fs::remove_dir_all(r); + } + std::fs::create_dir_all(&src).unwrap(); + let origin = Repo::init(&src).unwrap(); + std::fs::write(src.join("a.txt"), b"a\n").unwrap(); + origin.commit("t", "c1").unwrap(); + for bad in ["", " "] { + let Err(err) = + Repo::clone_url_filtered(src.to_str().unwrap(), &dst, Some(&[bad.to_string()])) + else { + panic!("a blank clone filter must be refused"); + }; + assert!( + matches!(&err, Error::InvalidArgument(m) if m.contains("empty sparse prefix")), + "got {err:?}" + ); + assert!(!dst.exists(), "no clone directory may be left behind"); + } + drop(origin); + std::fs::remove_dir_all(&src).unwrap(); + assert!(!src.exists()); + } + + #[test] + fn store_refuses_a_blank_prefix() { + let layout = tmp_layout("store-blank"); + let err = store(&layout, &Sparse::new(vec!["src/".into(), " ".into()])).unwrap_err(); + assert!(matches!(&err, Error::InvalidArgument(_)), "got {err:?}"); + assert!(!layout.sparse_path().exists(), "nothing was written"); + std::fs::remove_dir_all(&layout.root).unwrap(); + } } diff --git a/crates/repo/src/sync.rs b/crates/repo/src/sync.rs index fc98eaa7..5ca6a6a7 100644 --- a/crates/repo/src/sync.rs +++ b/crates/repo/src/sync.rs @@ -80,6 +80,11 @@ impl Repo { dst: impl AsRef, filter: Option<&[String]>, ) -> Result { + // Before the network or the destination directory: a blank prefix + // would be persisted as a sparse line that reloads as a full view. + if let Some(f) = filter { + crate::sparse::validate_prefixes(f)?; + } let transport = open_transport(src_url)?; let remote_refs = transport.list_refs()?; let head_branch = transport.head_branch()?;