mod site_commands

module site_commands

The overlap and reach reports the CLI prints.

The MCP tools call these same functions. A second copy of the orchestration would let the two surfaces drift.

Functions

fn run_component_reach(args: &ComponentReachRequest) -> Result<ComponentReachRun>

Write the component-reach report.

fn run_easyblock_reach(args: &EasyblockReachRequest) -> Result<EasyblockReachRun>

Write the easyblock-reach report.

fn run_pr_overlap(args: &PrOverlapRequest) -> Result<PrOverlapRun, PrOverlapError>

Write the pull-request overlap report.

The pr-overlap command and the eb_pr_overlap MCP tool both call this, so a flag means the same thing in both places. --open uses pr_overlap::UreqGet.

fn run_pr_overlap_with(args: &PrOverlapRequest, http: &dyn pr_overlap::HttpGet) -> Result<PrOverlapRun, PrOverlapError>

run_pr_overlap with the client that reads --open.

fn run_rebuild_set(args: &RebuildSetRequest) -> Result<RebuildSetRun>

Write the rebuild-set report.

fn run_stack_batch(args: &StackBatchRequest) -> Result<StackBatchRun>

Plan dependency-disjoint software-layer pull requests and write each one’s easystacks, lock, SBOM, reproduce script, and pull-request body.

fn run_stack_gap(args: &StackGapRequest) -> Result<StackGapRun>

Compare a site’s packages with a stack and name the recipe that closes each gap. Writes gap.tsv, one TSV per route, roots.txt (the recipes on the generation, the input of stack batch --roots-file), and bump-sources.txt (the newest recipe on any toolchain for each name without one), and version-change.tsv (old module versions moved to the target EESSI version, gone, or kept site-only).

fn run_stack_shard(args: &StackShardRequest) -> Result<StackShardRun>

Split a build list into shards whose builds do not overlap, plus a prelude of the dependencies two or more shards need.

A line with --from-commit or --from-pr is resolved the way EasyBuild resolves it: against that commit’s or pull request’s easyconfigs first, then the robot path. Its trees come from --commit-tree, --pr-tree, or --commit-cache, which downloads a missing one. A prelude line for a module only such a tree provides carries the line’s source options. A line eb-stack still cannot resolve is planned as an opaque line, and reported, when EasyBuild fetches its easyconfig or the file is on the robot path but does not parse; any other unresolved line writes nothing.

fn run_stack_shard_sources(args: &StackShardRequest, sources: &StackShardSources) -> Result<StackShardRun>

run_stack_shard with the sources in sources.

fn run_stack_shard_sources_storage(args: &StackShardRequest, extra: &StackShardSources, storage_policy: Option<&Path>) -> Result<StackShardRun>

Plan with optional storage advice while preserving legacy constructor fields.

fn run_stack_shard_with(args: &StackShardRequest, http: &dyn pr_overlap::HttpGet) -> Result<StackShardRun>

run_stack_shard with downloads through http.

fn run_stack_shard_with_sources(args: &StackShardRequest, extra: &StackShardSources, http: &dyn pr_overlap::HttpGet) -> Result<StackShardRun>

run_stack_shard_sources with downloads through http.

fn run_stack_shard_with_storage(args: &StackShardRequest, extra: &StackShardSources, storage_policy_path: Option<&Path>, http: &dyn pr_overlap::HttpGet) -> Result<StackShardRun>

Plan against explicit sources and an optional captured storage policy.

Enums

enum OverlapKind

Which pull-request records pr-overlap closes.

SoftwareLayer

Easystack additions on a software-layer pull request.

Easyconfigs

Easyconfig files on an easybuild-easyconfigs pull request.

enum PrOverlapError

Why pr-overlap stopped before writing a report.

InstalledRequired

--kind software-layer needs the installed module list.

Failed(anyhow::Error)

The report could not be built or written.

Structs and Unions

struct ComponentReachRequest

Inputs of eb-stack component-reach.

component: Option<String>

Component name. ASCII case is ignored. One of this, purl, or cve.

version: Option<String>

Exact version, *, or a requirement such as >=8,<9.

purl: Option<String>

Package URL. Replaces component.

cve: Option<String>

CVE id, or another OSV id. Versions come from OSV.

generation: String

Toolchain generation, for example 2026.1.

easyconfigs: Vec<PathBuf>

Easyconfig trees.

installed: Option<PathBuf>

Installed modules, one per line.

easystacks: Vec<PathBuf>

Deployed easystacks. With none, the generation is the stack.

easystack_urls: Vec<String>

Deployed easystacks fetched over HTTPS.

compat_layer: Option<PathBuf>

Compat-layer components, name version per line.

filter_deps: Vec<String>

Dependency specs to drop before the closure.

generated_at: Option<String>

RFC 3339 timestamp. None means now, in UTC.

out_dir: PathBuf

Directory for component-reach.toml, .json, and .md.

osv_cache: Option<PathBuf>

Recorded OSV responses. Absent, the command asks api.osv.dev.

struct ComponentReachRun

Counts component-reach prints.

component: String

Component that was asked for.

version: String

Version requirement that was asked for.

generation: String

Generation that was asked for.

carriers: usize

Easyconfigs and compat entries that carry it.

changed: usize

Carrier recipes fed into the rebuild closure.

must_rebuild: usize

Modules that must be rebuilt.

review: usize

Build-dependency dependents left for review.

no_rebuild: usize

Dependents that do not need a rebuild.

out_dir: PathBuf

Directory the report was written to.

document: serde_json::Value

The document written under out_dir. A CVE run is the CVE document.

Implementations

impl ComponentReachRun

Functions

fn summary(&self) -> String

The line eb-stack component-reach prints.

struct EasyblockReachRequest

Inputs of eb-stack easyblock-reach.

easyblocks: Vec<PathBuf>

Easyblock trees. Earlier roots win a class name.

framework: Vec<PathBuf>

Framework trees, indexed the same way.

easyconfigs: Vec<PathBuf>

Easyconfig files or trees.

file: Vec<PathBuf>

Changed Python files.

range: Option<String>

git diff --name-only range, for example base..HEAD.

pr: Option<u64>

Pull request number, fetched as refs/pull/N/head.

remote: String

Remote to fetch the pull request from.

base: String

Base branch for the pull request merge-base.

repo: Option<PathBuf>

Clone git reads. Defaults to the first easyblocks path when None.

installed: Option<PathBuf>

Installed module names, one per line.

reverse: bool

Also list modules that depend on a reached module.

generated_at: Option<String>

RFC 3339 timestamp. None means now.

out_dir: PathBuf

Directory for reach.toml, reach.json, and reach.md.

struct EasyblockReachRun

Counts easyblock-reach prints.

easyconfigs: usize

Easyconfigs the change reaches.

installed: usize

Installed modules the change reaches.

classes: usize

Classes the change reaches.

reverse: usize

Reverse-dependency modules.

out_dir: PathBuf

Directory the report was written to.

Implementations

impl EasyblockReachRun

Functions

fn summary(&self) -> String

The line eb-stack easyblock-reach prints.

struct PrOverlapRequest

Inputs of eb-stack pr-overlap, without the clap layer.

prs: Vec<PathBuf>

Pull-request JSON files.

kind: OverlapKind

Easystack additions, or easyconfig file changes.

easyconfigs: Vec<PathBuf>

Easyconfig trees, later ones taking precedence.

commit_trees: Vec<String>

Commit=directory trees for from-commit pins.

installed: Option<PathBuf>

Installed modules, one Name/VersionFull per line.

eessi_version: String

Stack version whose easystacks count. Empty for easyconfigs.

installed_label: String

Label for where the installed list came from.

exclude_paths: Vec<String>

Skip easystack paths containing one of these substrings.

include_paths: Vec<String>

Keep only easystack paths containing one of these substrings.

filter_deps: Vec<String>

Dependency specs to drop, EasyBuild --filter-deps tokens.

installed_modulerc: Vec<PathBuf>

Lmod .modulerc.lua files, or trees to scan.

easyblocks: Vec<PathBuf>

Installed easyblocks package roots.

easyblocks_commits: Vec<String>

Commit=directory for one include-easyblocks-from-commit.

generated_at: Option<String>

RFC 3339 timestamp. None means now, in UTC.

merge_order: bool

Also write merge-order.toml.

merged: Vec<u64>

Pull requests already merged. Implies a merge order.

impact: Vec<u64>

Pull requests judged on their own. Writes merge-impact.toml.

repo_url: Option<String>

Repository URL for Markdown links.

out_dir: PathBuf

Directory for prs/, overlap.toml, and overlap.md.

open_repo: Option<String>

owner/name whose open easyconfigs pull requests are fetched.

None reads only Self::prs. Set only with OverlapKind::Easyconfigs.

base_ref: Option<String>

Git ref for the base text of Self::open_repo. None is develop.

bot_build_set: bool

Close every head entry of each changed easystack, not only added lines.

Implied by Self::arch_installed.

arch_installed: Vec<String>

Installed modules for one architecture, ARCH=FILE. Repeatable.

struct PrOverlapRun

Counts pr-overlap prints on its one summary line.

prs: usize

Pull requests read from the JSON inputs.

records: usize

Records written.

shared_modules: usize

Modules more than one pull request would build.

skipped_easyconfigs: usize

Easyconfigs the parser skipped.

out_dir: PathBuf

Directory the report was written to.

Implementations

impl PrOverlapRun

Functions

fn summary(&self) -> String

The line eb-stack pr-overlap prints.

struct RebuildSetRequest

Inputs of eb-stack rebuild-set.

changed: Vec<String>

Patched easyconfig filenames, or a list file.

easystacks: Vec<PathBuf>

Deployed easystacks. Empty means every installed module is a root.

findings: Option<PathBuf>

Scanner findings export. Each installed module it names is patched.

reachability: Option<PathBuf>

Site reachability file. Requires Self::findings.

easyconfigs: Vec<PathBuf>

Easyconfig trees, later ones taking precedence.

commit_trees: Vec<String>

Commit=directory trees for from-commit pins.

installed: PathBuf

Installed modules, one Name/VersionFull per line.

installed_label: String

Label for where the installed list came from.

filter_deps: Vec<String>

Dependency specs to drop.

installed_modulerc: Vec<PathBuf>

Lmod .modulerc.lua files, or trees to scan.

easyblocks: Vec<PathBuf>

Installed easyblocks package roots.

easyblocks_commits: Vec<String>

Commit=directory for one include-easyblocks-from-commit.

generated_at: Option<String>

RFC 3339 timestamp. None means now, in UTC.

prefix: Option<PathBuf>

Installed prefix whose static archives are read.

check_static: bool

Compare defined dynamic symbols when --prefix is set.

out_dir: PathBuf

Directory for rebuild-set.json, .md, and rebuilds/.

struct RebuildSetRun

Counts rebuild-set prints.

changed: usize

Patched easyconfigs.

rows: usize

Installed reverse dependents.

must_rebuild: usize

Modules that must be rebuilt.

review: usize

Build-dependency dependents left for review.

no_rebuild: usize

Dependents that do not need a rebuild.

missing: usize

Easyconfigs the closure could not find.

easystacks: usize

Easystack files written under rebuilds/.

skipped_easyconfigs: usize

Easyconfigs the parser skipped.

findings_modules: Option<usize>

Installed modules with a finding, when --findings was given.

backport_modules: Option<usize>

Modules on the backport list, when --findings was given.

fix_routes: Option<usize>

Findings in the fix-cost table, when --findings was given.

fix_cost: Option<(usize, usize, usize, usize)>

Bump, in-place, and recommended module counts, then the stack size.

out_dir: PathBuf

Directory the report was written to.

Implementations

impl RebuildSetRun

Functions

fn summary(&self) -> String

The line eb-stack rebuild-set prints.

struct StackBatchRequest

Arguments for stack batch.

roots: Vec<String>

Root easyconfig file names.

easyconfigs: Vec<PathBuf>

Robot-path easyconfig trees (the easyconfigs the roots come from).

commit_trees: Vec<String>

Commit=directory trees for from-commit pins the open pull requests use.

installed: PathBuf

Installed modules, one Name/VersionFull per line.

installed_modulerc: Vec<PathBuf>

Modulerc files with module_version aliases.

open_prs: Vec<PathBuf>

Open software-layer pull requests as pr-overlap --pr JSON.

open_repo: Option<String>

Read the open pull requests of this OWNER/NAME over HTTPS too.

eessi_version: String

EESSI version, 2026.06.

easybuild_version: String

EasyBuild release the entries are built with, 5.4.1.

generation: String

Toolchain generation, 2026.1.

filter_deps: Vec<String>

--filter-deps as EESSI-extend sets it.

allow_versions: Vec<String>

NAME or NAME@GENERATION allowed a second version by the stack generation second-version check stack batch runs.

size: usize

Most roots per pull request.

easyconfigs_repo: Option<PathBuf>

easybuild-easyconfigs checkout: a root not in the release tag gets a from-commit pin to the last commit that touched its file.

generated_at: Option<String>

RFC 3339 time written into the plan; absent is now.

arches: Vec<String>

Architecture families to judge the plan against. Empty checks every family in the unsupported list.

unsupported: Option<PathBuf>

Replace the bundled unsupported list.

known_failures: Option<PathBuf>

Replace the bundled known-failure table.

oom_profile: Option<PathBuf>

Replace the bundled build-memory profile table used by stack oom.

oom_resources: Option<PathBuf>

Replace the bundled bot-resource table used by stack oom.

command_line: String

The command line, written into every reproduce script.

out_dir: PathBuf

Output directory.

struct StackBatchRun

What stack batch wrote.

out_dir: PathBuf

Where the batches were written.

plan: crate::batch::BatchPlan

The plan.

digest: String

Sha256 over the inputs that decide the plan.

Implementations

impl StackBatchRun

Functions

fn summary(&self) -> String

One line for the CLI.

struct StackGapRequest

Release easyconfigs plus one tree per commit pin. Arguments for stack gap.

site: Vec<PathBuf>

Site module trees or listings. Repeatable.

older: Vec<PathBuf>

Older EESSI module trees or listings users load beside the site. Repeatable.

installed: Vec<PathBuf>

Target module trees or listings. Repeat for a CPU tree and an accelerator tree.

easyconfigs: Vec<PathBuf>

Easyconfig trees to find recipes in.

generation: String

Toolchain generation, 2026.1.

exclude_file: Option<PathBuf>

name<TAB>reason lines for names the stack does not carry.

filter_deps: Vec<String>

Names filtered to the compatibility layer, as EESSI-extend sets them.

open_layer: Vec<PathBuf>

Open software-layer pull requests, pr-overlap --pr JSON. Repeatable.

open_easyconfigs: Vec<PathBuf>

Open easybuild-easyconfigs pull requests, pr-overlap --pr JSON. Repeatable.

eessi_version: Option<String>

Keep open software-layer easystacks of this EESSI version only, 2026.06.

out_dir: PathBuf

Output directory.

struct StackGapRun

What stack gap found.

rows: Vec<crate::gap::GapRow>

One row per site package.

out_dir: PathBuf

Where the files were written.

Implementations

impl StackGapRun

Functions

fn summary(&self) -> String

One line for the CLI.

struct StackShardRequest

Arguments for stack shard.

build_list: PathBuf

Jenkins build list of one node type.

easyconfigs: Vec<PathBuf>

Robot-path easyconfig trees; later trees take precedence.

commit_trees: Vec<String>

COMMIT=DIR: the easyconfigs of one --from-commit pin.

pr_trees: Vec<String>

N=DIR: the easyconfigs one --from-pr pull request changes.

commit_cache: Option<PathBuf>

Directory the trees of fetched lines are found in or downloaded to.

installed: Vec<PathBuf>

Installed-module lists, one Name/VersionFull per line.

installed_modules_dirs: Vec<PathBuf>

Lmod modules/all trees whose modules count as installed.

shards: usize

Upper bound on the number of shards.

weights: Option<PathBuf>

module<TAB>seconds per line.

default_weight: u64

Weight of a module weights does not list.

filter_deps: Vec<String>

--filter-deps as EasyBuild takes it.

generated_at: Option<String>

RFC 3339 time written into the plan; absent is now.

out_dir: PathBuf

Output directory.

inode_quota: Option<u64>

Scratch inode quota the shards share; caps how many run at once.

inode_footprints: Option<PathBuf>

footprints.json from stack footprints; absent is the built-in class table.

inode_margin: u64

Inodes kept free under the quota.

inode_line_overhead: u64

Inodes each build-list line keeps beside its build tree.

lift_cpu_prerequisites: bool

Opt-in: lift CPU-only prerequisites of accelerator roots into the prelude even when only one root needs them. Default is false (shared dependencies only), matching historical stack shard behaviour.

struct StackShardRun

What stack shard wrote.

shards: usize

Shards written.

prelude: usize

Prelude modules.

cpu_prerequisites: usize

CPU-prerequisite modules (opt-in lift). Zero when the flag is off.

lift_cpu_prerequisites: bool

Whether --lift-cpu-prerequisites was set.

lines: usize

Build-list lines.

max_concurrent: usize

Shards that fit under the quota at once; the shard count without a quota.

capped: bool

Whether a quota was given, so the summary names the cap.

opaque: usize

Lines planned without a closure.

warnings: Vec<String>

One line per opaque line and per other planning caveat, for stderr.

Implementations

impl StackShardRun

Functions

fn summary(&self) -> String

One line for the CLI. Legacy format when the CPU-lift flag is off.

struct StackShardSources

Where stack shard reads --from-commit trees from besides StackShardRequest, and whether it writes lists that run without fetching them again.

easyconfigs_repo: Option<PathBuf>

easybuild-easyconfigs git repository (a checkout, a bare repository, or a blobless clone) whose objects hold the commits of --from-commit lines. A commit found there is read in place; --commit-cache serves only a commit it lacks. --commit-tree still comes first.

materialize: bool

Write sources/v1/<commit>/ with the files the plan reads from each commit, its manifest sources/v1/<commit>.json, and prelude.local.list and shard-NN.local.list, whose --from-commit lines read that directory instead of fetching the commit.

build_robot_paths: Vec<String>

The build host’s EasyBuild robot paths, in EasyBuild’s order, as eb --show-config reports robot-paths. An executable line passes them, then its sources directory, as --robot-paths.