Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/spawn-quests/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ If you are unsure of the best course of action, ask the user for clarification b
The scope consists of all ready quests that are not claimed.
Use the argument (if provided) to filter to specific quests/questlines.
Main's tree lags its lines: a child finished on its line branch still looks ready from `main`.
Judge readiness from each line branch's own quest directory.
Fetch, then judge readiness with `quest ready --remote origin`, which reads each line from its branch.
Inspect any blocked quests, and determine if they can be unblocked.
A line whose `Quests` list has emptied is a ready quest too: finishing it marks the line's PR ready.

Expand Down
4 changes: 3 additions & 1 deletion docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,9 @@ quest branch quest/m0/some-quest.md
```

`branch` prints that quest's branch and each branch it merges through, ending
at `main`. Milestones themselves have no branch.
at `main`. Milestones themselves have no branch. Children merge into their
line's branch first, so after a `git fetch`, `quest ready --remote origin`
reads each line from its branch instead of the working tree.

Review the plan before starting it. `/start-quest` works on one quest;
`/spawn-quests` coordinates multiple agents when your session supports them.
Expand Down
2 changes: 2 additions & 0 deletions flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@
quest = craneLib.buildPackage {
src = craneLib.cleanCargoSource ./.;
strictDeps = true;
# The line-branch readiness tests build real repositories.
nativeCheckInputs = [ pkgs.git ];
};
in
{
Expand Down
10 changes: 6 additions & 4 deletions quest/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,12 @@ Current decisions, open questions, or implementation guidance.
repository; remove it when it clears. `Required` must be acyclic.
- `quest check` enforces this structure; run it before submitting quest
changes. `quest ready [<path>]` prints what blocks a quest, or every ready
quest. `quest branch <path>` prints the branch and every branch it merges
through, nearest first and ending at `main`. The root instructions say how
to run `quest` when it is not on `PATH`. It reads the tree alone: whether a
PR already claims a quest is GitHub's question.
quest; `--remote origin` reads each line from its fetched branch, where its
children finish before `main` sees them. `quest branch <path>` prints the
branch and every branch it merges through, nearest first and ending at
`main`. The root instructions say how to run `quest` when it is not on
`PATH`. Only `--remote` reads git; nothing asks GitHub whether a PR already
claims a quest.

## Creation

Expand Down
99 changes: 93 additions & 6 deletions src/branch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@
//!
//! The mapping is the path alone: a quest's branch is its path without `.md`
//! and a questline's is its README's. Milestones have no branch, so a
//! milestone's direct children merge into `main`. Nothing here asks git, so the
//! answer is the same on every machine and a missing line branch is simply
//! created from the next one in the chain.
//! milestone's direct children merge into `main`. Naming a branch never asks
//! git, so the answer is the same on every machine and a missing line branch is
//! simply created from the next one in the chain. Only [`overlay`] reads the
//! branches themselves, and only when asked.

use std::collections::BTreeMap;
use std::path::Path;
use std::collections::{BTreeMap, BTreeSet, VecDeque};
use std::path::{Path, PathBuf};
use std::process::Command;

use anyhow::{Result, bail};
use anyhow::{Context, Result, bail};

use crate::doc::Doc;

Expand All @@ -30,3 +32,88 @@ pub fn chain(root: &Path, path: &Path) -> Result<Vec<String>> {
out.push("main".to_string());
Ok(out)
}

/// The tree as the line branches on `remote` see it.
///
/// A line's children merge into its branch, not `main`, so until the line lands
/// the working tree still lists quests that are already done. Each line whose
/// branch exists replaces its directory with that branch's copy, outermost
/// first, so a nested line's own branch has the last word on its subtree. A
/// line that an outer branch already completed stays gone even if its own
/// branch lingers.
pub(crate) fn overlay(root: &Path, docs: Vec<Doc>, remote: &str) -> Result<Vec<Doc>> {
// Fail on a typo'd remote or a tree outside git, rather than read every line
// as absent and report the working tree as if it were the answer.
git(root, &["remote", "get-url", remote])?;

let mut docs: BTreeMap<PathBuf, Doc> = docs.into_iter().map(|d| (d.path.clone(), d)).collect();
let mut lines: Vec<PathBuf> = docs.keys().filter(|p| is_line(p)).cloned().collect();
lines.sort_by_key(|p| p.components().count());
let mut pending = VecDeque::from(lines);
let mut seen = BTreeSet::new();

while let Some(readme) = pending.pop_front() {
if !docs.contains_key(&readme) || !seen.insert(readme.clone()) {
continue;
}
let rev = format!("refs/remotes/{remote}/{}", readme.with_extension("").display());
// A line nobody has started has no branch yet.
if git(
root,
&["rev-parse", "--verify", "--quiet", &format!("{rev}^{{commit}}")],
)
.is_err()
{
continue;
}

let dir = readme.parent().unwrap_or(Path::new(""));
docs.retain(|path, _| !path.starts_with(dir));
let listing = git(
root,
&[
"ls-tree",
"-r",
"-z",
"--name-only",
&rev,
"--",
&format!("{}/", dir.display()),
],
)?;
for path in listing.split('\0').filter(|p| !p.is_empty()).map(PathBuf::from) {
if !crate::is_quest(&path) {
continue;
}
let text = git(root, &["show", &format!("{rev}:./{}", path.display())])?;
if is_line(&path) {
pending.push_back(path.clone());
}
docs.insert(path.clone(), Doc::from_str(path, &text));
}
}
Ok(docs.into_values().collect())
}

/// A README with a branch: anything but the root and the milestones.
fn is_line(path: &Path) -> bool {
path.file_name().is_some_and(|n| n == "README.md") && !Doc::permanent(path)
}

/// Run git in `root`, returning stdout; a failure is an error carrying stderr.
fn git(root: &Path, args: &[&str]) -> Result<String> {
let out = Command::new("git")
.arg("-C")
.arg(root)
.args(args)
.output()
.context("running git")?;
if !out.status.success() {
bail!(
"git {} failed: {}",
args.join(" "),
String::from_utf8_lossy(&out.stderr).trim()
);
}
String::from_utf8(out.stdout).context("git printed non-UTF-8")
}
23 changes: 18 additions & 5 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -41,17 +41,21 @@ fn walk(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
let kind = entry.file_type()?;
if kind.is_dir() {
walk(root, &path, out)?;
} else if path.extension().is_some_and(|e| e == "md")
&& !path
.file_name()
.is_some_and(|n| NOT_QUESTS.iter().any(|skip| n == *skip))
{
} else if is_quest(&path) {
out.push(path.strip_prefix(root).unwrap_or(&path).to_path_buf());
}
}
Ok(())
}

/// A Markdown file other than agent instructions.
fn is_quest(path: &Path) -> bool {
path.extension().is_some_and(|e| e == "md")
&& !path
.file_name()
.is_some_and(|n| NOT_QUESTS.iter().any(|skip| n == *skip))
}

/// Parse and validate the tree. Returns every finding, worst-case empty.
pub fn check(root: &Path) -> Result<Vec<Finding>> {
Ok(rules::check(root, &load(root)?))
Expand All @@ -65,3 +69,12 @@ fn load(root: &Path) -> Result<Vec<Doc>> {
}
paths.into_iter().map(|p| Doc::parse(root, p)).collect()
}

/// [`load`], with each line read from its branch on `remote` when one is given.
fn load_from(root: &Path, remote: Option<&str>) -> Result<Vec<Doc>> {
let docs = load(root)?;
match remote {
Some(remote) => branch::overlay(root, docs, remote),
None => Ok(docs),
}
}
17 changes: 13 additions & 4 deletions src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ enum Command {
Ready {
/// Quest to explain. Omit to list every ready quest in tree order.
path: Option<PathBuf>,

/// Read each questline from its branch on this remote (`origin`) when
/// that branch exists: a line's children finish there before the line
/// reaches the working tree. Fetch first; this reads remote-tracking refs.
#[arg(long)]
remote: Option<String>,
},

/// Print the branch carrying a quest, then every branch it merges through.
Expand Down Expand Up @@ -60,8 +66,11 @@ fn main() -> Result<ExitCode> {
}
Ok(ExitCode::FAILURE)
}
Command::Ready { path: Some(path) } => {
let blockers = quest::ready::blockers(&cli.root, &path)?;
Command::Ready {
path: Some(path),
remote,
} => {
let blockers = quest::ready::blockers(&cli.root, &path, remote.as_deref())?;
for blocker in &blockers {
print!("{blocker}");
}
Expand All @@ -75,8 +84,8 @@ fn main() -> Result<ExitCode> {
}
Ok(ExitCode::SUCCESS)
}
Command::Ready { path: None } => {
for path in quest::ready::quests(&cli.root)? {
Command::Ready { path: None, remote } => {
for path in quest::ready::quests(&cli.root, remote.as_deref())? {
println!("{}", path.display());
}
Ok(ExitCode::SUCCESS)
Expand Down
13 changes: 7 additions & 6 deletions src/ready.rs
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,10 @@ impl fmt::Display for Blocker {
/// holds. Empty means ready.
///
/// `path` is the quest as the tree writes it (`/quest/m0/one.md`), as the shell
/// completes it (`quest/m0/one.md`), or as an absolute filesystem path.
pub fn blockers(root: &Path, path: &Path) -> Result<Vec<Blocker>> {
let docs = crate::load(root)?;
/// completes it (`quest/m0/one.md`), or as an absolute filesystem path. With a
/// `remote`, each line is read from its branch there; see [`crate::branch::overlay`].
pub fn blockers(root: &Path, path: &Path, remote: Option<&str>) -> Result<Vec<Blocker>> {
let docs = crate::load_from(root, remote)?;
let by_path: BTreeMap<&Path, &Doc> = docs.iter().map(|d| (d.path.as_path(), d)).collect();
let path = locate(root, path, &by_path)?;
Ok(expand(&by_path, by_path[path.as_path()], &mut vec![path.clone()]))
Expand All @@ -74,9 +75,9 @@ pub fn blockers(root: &Path, path: &Path) -> Result<Vec<Blocker>> {
/// A questline is not listed while it still indexes children; a README with
/// no `## Quests` left is the line's own remaining work and lists like any
/// other quest. The absence of a `## Required` heading is what quest/AGENTS.md
/// defines as ready.
pub fn quests(root: &Path) -> Result<Vec<PathBuf>> {
let docs = crate::load(root)?;
/// defines as ready. `remote` is as for [`blockers`].
pub fn quests(root: &Path, remote: Option<&str>) -> Result<Vec<PathBuf>> {
let docs = crate::load_from(root, remote)?;
let mut remaining: BTreeMap<PathBuf, &Doc> = docs.iter().map(|doc| (doc.path.clone(), doc)).collect();
let mut pending = vec![PathBuf::from("quest/README.md")];
let mut ready = Vec::new();
Expand Down
Loading
Loading