From 5f9c2984899856b38f6b572919dceb7e5cdd54d2 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Mon, 16 Nov 2026 03:21:02 +0000 Subject: [PATCH] docs(cli): make five help texts match the commands The second stack admit example piped mmlsquota-json into --quota-json - and passed --live-jobs "$(squeue ... | paste -sd,)", so both were read before any lock. The --live-jobs-cmd help, sharding-admission.org and stack-shard.org all say that list can miss a job that reserved in between. The example now takes --lock, --quota-cmd and --live-jobs-cmd, and admits a job with stub commands for mmlsquota-json and squeue. The top-level help listed exit status 0, 1 and 2; stack admit also exits 78 when it refuses the job, as cli.org's table says. campaign --help showed only the campaign status example, and not campaign run. stack generation --help and the generation_lint module doc mapped 2023.06 and 2025.06 but not 2026.06, which the bundled table maps to 2026.1. stack batch --installed-modulerc said "Modulerc file", while load_modulerc also scans a module tree, as the pr-overlap and rebuild-set help say. Five tests in cli_ergonomics.rs check these against cli.org, the bundled table and every command that takes --installed-modulerc. They fail without the fix. cli.org's stack batch text names both forms. --- changelog.d/+cli-help.doc.md | 1 + docs/orgmode/reference/cli.org | 7 +- llms-full.txt | 7 +- src/generation_lint.rs | 4 +- src/main.rs | 18 +++-- tests/cli_ergonomics.rs | 143 +++++++++++++++++++++++++++++++++ 6 files changed, 165 insertions(+), 15 deletions(-) create mode 100644 changelog.d/+cli-help.doc.md diff --git a/changelog.d/+cli-help.doc.md b/changelog.d/+cli-help.doc.md new file mode 100644 index 00000000..46b10344 --- /dev/null +++ b/changelog.d/+cli-help.doc.md @@ -0,0 +1 @@ +The `--help` text matches what the commands do: the top-level help names exit status 78 from `stack admit`; the second `stack admit` example reads the quota and the scheduler inside `--lock` with `--quota-cmd` and `--live-jobs-cmd`, instead of expanding `squeue` before the lock; `campaign --help` shows `campaign run`; `stack generation --help` maps 2026.06 to 2026.1; and `stack batch --installed-modulerc` says it reads a module tree as well as a `.modulerc.lua` file. diff --git a/docs/orgmode/reference/cli.org b/docs/orgmode/reference/cli.org index 62d7185f..6935593b 100644 --- a/docs/orgmode/reference/cli.org +++ b/docs/orgmode/reference/cli.org @@ -525,7 +525,7 @@ eb-stack stack batch \ (--root FILE.eb... | --roots-file ROOTS.txt) \ --easyconfigs TREE [--easyconfigs OVERLAY]... \ [--commit-tree COMMIT=DIR]... \ - --installed INSTALLED.txt [--installed-modulerc MODULERC]... \ + --installed INSTALLED.txt [--installed-modulerc PATH]... \ [--open-prs OPEN.json]... [--open-repo EESSI/software-layer] \ --eessi-version 2026.06 --easybuild-version 5.4.1 --generation 2026.1 \ [--filter-deps NAME,NAME...] \ @@ -841,8 +841,9 @@ together; a root whose set meets an open pull request's waits for it. Open pull requests come from ~--open-prs~ (~pr-overlap --pr~ JSON) and ~--open-repo~, which reads the open pull requests of that repository over HTTPS. ~--commit-tree~ supplies the easyconfigs an open pull request pins -with ~from-commit~. ~--installed-modulerc~ adds ~module_version~ aliases to -the installed list. The rest are packed ~--size~ roots per pull request in +with ~from-commit~. ~--installed-modulerc~, a ~.modulerc.lua~ file or a +module tree, adds ~module_version~ aliases to the installed list. The rest +are packed ~--size~ roots per pull request in a fixed order, so the same inputs give the same plan. With ~--easyconfigs-repo~, a root the ~--easybuild-version~ release lacks gets a ~from-commit~ pin. Each ~batch-NN~ directory holds the EESSI easystacks, a diff --git a/llms-full.txt b/llms-full.txt index 5591be69..a1e95062 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -7184,7 +7184,7 @@ eb-stack stack batch \ (--root FILE.eb... | --roots-file ROOTS.txt) \ --easyconfigs TREE [--easyconfigs OVERLAY]... \ [--commit-tree COMMIT=DIR]... \ - --installed INSTALLED.txt [--installed-modulerc MODULERC]... \ + --installed INSTALLED.txt [--installed-modulerc PATH]... \ [--open-prs OPEN.json]... [--open-repo EESSI/software-layer] \ --eessi-version 2026.06 --easybuild-version 5.4.1 --generation 2026.1 \ [--filter-deps NAME,NAME...] \ @@ -7500,8 +7500,9 @@ together; a root whose set meets an open pull request's waits for it. Open pull requests come from `--open-prs` (`pr-overlap --pr` JSON) and `--open-repo`, which reads the open pull requests of that repository over HTTPS. `--commit-tree` supplies the easyconfigs an open pull request pins -with `from-commit`. `--installed-modulerc` adds `module_version` aliases to -the installed list. The rest are packed `--size` roots per pull request in +with `from-commit`. `--installed-modulerc`, a `.modulerc.lua` file or a +module tree, adds `module_version` aliases to the installed list. The rest +are packed `--size` roots per pull request in a fixed order, so the same inputs give the same plan. With `--easyconfigs-repo`, a root the `--easybuild-version` release lacks gets a `from-commit` pin. Each `batch-NN` directory holds the EESSI easystacks, a diff --git a/src/generation_lint.rs b/src/generation_lint.rs index 2e5ed100..77bcd47c 100644 --- a/src/generation_lint.rs +++ b/src/generation_lint.rs @@ -1,8 +1,8 @@ //! Toolchain generations an EESSI version carries, checked on a plan's easystacks. //! //! Each EESSI version is built on a fixed set of toolchain generations: -//! 2023.06 on 2022b, 2023a and 2023b, 2025.06 on 2024a, 2025a and 2025b. -//! `data/eessi-generations.toml` is that table. An easystack entry on a +//! 2023.06 on 2022b, 2023a and 2023b, 2025.06 on 2024a, 2025a and 2025b, +//! 2026.06 on 2026.1. `data/eessi-generations.toml` is that table. An easystack entry on a //! toolchain outside its version's generations cannot go into that version: //! software-layer #1472 put pv on GCCcore-12.3.0, which is 2023a, into a //! 2025.06 easystack. The bot builds one EESSI version per pull request, so diff --git a/src/main.rs b/src/main.rs index 8223671b..27387c33 100644 --- a/src/main.rs +++ b/src/main.rs @@ -38,7 +38,7 @@ fn is_usage(error: &anyhow::Error) -> bool { name = "eb-stack", version, about = "Canonical SBOM, build-manifest, Resolvo, EasyBuild, and campaign workflows", - after_long_help = "Exit status is 0 when the command finished, 1 when the work failed, and 2 when the command line was rejected.\n\nA directory of artifacts is --out-dir. A single output file is --out.\n\nExamples:\n eb-stack package inspect --source recipe.yaml --format conda-forge --toolchain foss/2026.1 --out-dir bundle\n eb-stack --help" + after_long_help = "Exit status is 0 when the command finished, 1 when the work failed, and 2 when the command line was rejected. `stack admit` exits 78 when it refuses the job.\n\nA directory of artifacts is --out-dir. A single output file is --out.\n\nExamples:\n eb-stack package inspect --source recipe.yaml --format conda-forge --toolchain foss/2026.1 --out-dir bundle\n eb-stack --help" )] struct Cli { #[command(subcommand)] @@ -80,7 +80,9 @@ enum Command { command: TargetCommand, }, /// Run and inspect persisted build campaigns. - #[command(after_long_help = "Examples:\n eb-stack campaign status --state campaign.json")] + #[command( + after_long_help = "Examples:\n eb-stack campaign run --bundle bundle/ --config target.toml --target local --state campaign.json\n eb-stack campaign status --state campaign.json" + )] Campaign { #[command(subcommand)] command: CampaignCommand, @@ -1116,7 +1118,8 @@ struct BatchArgs { /// Installed modules, one `Name/VersionFull` per line. #[arg(long)] installed: PathBuf, - /// Modulerc file with `module_version` aliases. Repeatable. + /// Lmod `.modulerc.lua` file with `module_version` aliases, or a module + /// tree to scan for them. Repeatable. #[arg(long = "installed-modulerc")] installed_modulerc: Vec, /// Open software-layer pull requests, `pr-overlap --pr` JSON. Repeatable. @@ -1705,7 +1708,7 @@ enum StackCommand { /// reservation is never counted. Prints one JSON line. Exits 0 when /// admitted, 78 when refused. #[command( - after_long_help = "Examples:\n eb-stack stack admit --quota-json quota.json --footprint 351000 --job 4411 --reservations reservations --live-jobs 4401,4402\n mmlsquota-json | eb-stack stack admit --quota-json - --footprint 61000 --job 4412 --reservations reservations --live-jobs \"$(squeue --all -h -o %i -u jenkins | paste -sd,)\"" + after_long_help = "Examples:\n eb-stack stack admit --quota-json quota.json --footprint 351000 --job 4411 --reservations reservations --live-jobs 4401,4402\n eb-stack stack admit --lock reservations/admission.lock --quota-cmd mmlsquota-json --footprint 61000 --job 4412 --reservations reservations --live-jobs-cmd 'squeue --all -h -o %i -u jenkins'" )] Admit(Box), /// Refuse a plan an architecture cannot build, and flag shared entries @@ -1816,9 +1819,10 @@ enum StackCommand { /// /// `data/eessi-generations.toml` maps each EESSI version to its /// generations: 2023.06 to 2022b, 2023a and 2023b, 2025.06 to 2024a, - /// 2025a and 2025b. The EESSI version comes from the easystack path. With - /// `--pr`, only the lines each pull request adds are checked, and the rest - /// of the file counts as already in the stack. Exits 1 on any finding. + /// 2025a and 2025b, and 2026.06 to 2026.1. The EESSI version comes from + /// the easystack path. With `--pr`, only the lines each pull request adds + /// are checked, and the rest of the file counts as already in the stack. + /// Exits 1 on any finding. #[command( after_long_help = "Examples:\n eb-stack stack generation --easystack easystacks/software.eessi.io/2025.06/eessi-2025.06-eb-5.4.1-2025b.yml\n eb-stack stack generation --pr pr-1472.json\n eb-stack stack generation --pr pr.json --deployed easystacks/software.eessi.io/2025.06 --allow-versions CMake@2025b" )] diff --git a/tests/cli_ergonomics.rs b/tests/cli_ergonomics.rs index 9e802a1c..a2e3fb59 100644 --- a/tests/cli_ergonomics.rs +++ b/tests/cli_ergonomics.rs @@ -328,6 +328,149 @@ fn stack_gap_help_example_paths_exist() { ); } +#[test] +fn top_level_help_names_every_exit_status_the_reference_lists() { + let help = help_text(&[]); + let paragraph = help + .split("\n\n") + .find(|block| block.starts_with("Exit status")) + .expect("eb-stack --help states the exit status"); + let named: Vec<&str> = paragraph.split(|c: char| !c.is_ascii_digit()).collect(); + let reference = std::fs::read_to_string( + Path::new(env!("CARGO_MANIFEST_DIR")).join("docs/orgmode/reference/cli.org"), + ) + .expect("read cli.org"); + let codes: Vec<&str> = reference + .split_once("* Exit status") + .expect("cli.org has an exit status section") + .1 + .lines() + .skip_while(|line| !line.starts_with('|')) + .take_while(|line| line.starts_with('|')) + .filter_map(|line| line.split('|').nth(1).map(str::trim)) + .filter(|cell| !cell.is_empty() && cell.chars().all(|c| c.is_ascii_digit())) + .collect(); + assert!( + codes.contains(&"78"), + "cli.org exit status table: {codes:?}" + ); + for code in codes { + assert!( + named.contains(&code), + "eb-stack --help does not name exit status {code}:\n{paragraph}" + ); + } +} + +#[test] +fn stack_admit_help_examples_read_the_scheduler_inside_the_lock() { + let text = help_text(&["stack".into(), "admit".into()]); + let examples = text + .split_once("Examples:") + .expect("stack admit help has an example") + .1; + assert!( + !examples.contains("$("), + "a stack admit --help example expands a command before the lock:\n{examples}" + ); + assert!( + examples.contains("--lock ") && examples.contains("--live-jobs-cmd "), + "stack admit --help should show the scheduler read inside --lock:\n{examples}" + ); +} + +#[test] +fn campaign_help_shows_how_to_start_a_campaign() { + let text = help_text(&["campaign".into()]); + let examples = text + .split_once("Examples:") + .expect("campaign help has an example") + .1; + assert!( + examples.contains("eb-stack campaign run "), + "campaign --help should show campaign run:\n{examples}" + ); +} + +#[test] +fn stack_generation_help_maps_every_bundled_eessi_version() { + let help = help_text(&["stack".into(), "generation".into()]); + let mapping = help + .split("\n\n") + .find(|block| block.contains("data/eessi-generations.toml")) + .expect("stack generation --help names the table"); + let table = std::fs::read_to_string( + Path::new(env!("CARGO_MANIFEST_DIR")).join("data/eessi-generations.toml"), + ) + .expect("read the bundled table"); + let mut versions = 0; + let mut lines = table.lines(); + while let Some(line) = lines.next() { + let Some(version) = line + .strip_prefix("eessi = \"") + .and_then(|rest| rest.strip_suffix('"')) + else { + continue; + }; + let generations = lines + .next() + .and_then(|next| next.strip_prefix("generations = [")) + .expect("generations follow eessi"); + assert!( + mapping.contains(&format!("{version} to ")), + "stack generation --help does not map EESSI {version}:\n{mapping}" + ); + for generation in generations + .trim_end_matches(']') + .split(',') + .map(|generation| generation.trim().trim_matches('"')) + { + assert!( + mapping.contains(generation), + "stack generation --help does not name {generation} for {version}:\n{mapping}" + ); + } + versions += 1; + } + assert!(versions >= 3, "read {versions} EESSI versions"); +} + +/// The lines clap prints under one long flag, joined. +fn flag_description(help: &str, flag: &str) -> Option { + let mut lines = help + .lines() + .skip_while(|line| line.trim_start().split(' ').next() != Some(flag)); + lines.next()?; + Some( + lines + .take_while(|line| !line.trim_start().starts_with('-')) + .map(str::trim) + .collect::>() + .join(" "), + ) +} + +#[test] +fn every_installed_modulerc_help_says_a_module_tree_is_read() { + let mut checked = Vec::new(); + for command in leaves() { + let help = help_text(&command); + let Some(description) = flag_description(&help, "--installed-modulerc") else { + continue; + }; + assert!( + description.contains("module tree"), + "{} --installed-modulerc also reads a module tree:\n{description}", + command.join(" ") + ); + checked.push(command.join(" ")); + } + assert!( + checked.len() >= 3, + "commands with --installed-modulerc: {checked:?}" + ); +} + #[test] fn every_command_help_has_an_example_and_describes_every_flag() { let commands = leaves();