mod pr_overlap

module pr_overlap

Which open pull requests to a software layer would build the same modules.

A software-layer pull request adds lines to an easystack, and what it really asks for is everything eb –easystack <file> –robot would install for those lines on the current stack: the named easyconfigs plus every dependency not installed yet. Two pull requests that both need a module nobody has built will both build it, and the reviewer who has to order them works that out by hand today.

This module answers it from the recipes alone, with no build and no model. Per pull request it reads the easystack entries the change adds, finds their easyconfigs on the robot path (the release tree plus, for an entry pinned with from-commit, the easyconfigs tree at that commit ahead of it), and closes them with crate::build_order::closure_against_installed against the list of installed modules. An installed module is a leaf, as it is for the robot. The overlap report is then a set intersection over the to-build sets.

The pull request’s files are read as data. Nothing from a pull request is executed, which is what lets a scheduled job on the base repository run this over pull requests from forks.

Types

type EasystackChange

One changed easystack file. Same fields and serde shape as FileChange.

Variables

const CHANGED_EASYSTACK_SCOPE: &str

build_scope written on a record when BuildScope::ChangedEasystack ran.

const EASYCONFIG_PR_SCHEMA_VERSION: u32

Schema of an easyconfigs pull-request record. A software-layer record stays at PR_OVERLAP_SCHEMA_VERSION so an existing file is unchanged.

const GENERATED_HEADER: &str

Header written at the top of every generated file.

const GITHUB_PR_FILES_TRUNCATED: &str

Note recorded when GitHub’s pulls files API stops at its cap.

That API returns at most 3000 files. At 100 files a page, the maximum page size, that is 30 pages. Files past the cap are not read.

const PR_OVERLAP_SCHEMA_VERSION: u32

Schema of the per-PR record and the index. Bumped on any breaking change.

Functions

fn added_entries(change: &EasystackChange) -> Vec<EasystackEntry>

Entries present at head and not on base, in head order.

fn combine_arch_records(groups: Vec<(String, Vec<PrRecord>)>) -> Vec<PrRecord>

Fold per-architecture records into one record per pull request.

One architecture is returned unchanged, so to_build stays that architecture’s build set and merge order reads it directly. Two or more move each build set onto build_sets and leave the top-level to_build empty. The architecture order is the order of groups.

fn easyconfig_record(pr: &PrInput, base: &[Candidate], installed: Option<&BTreeSet<String>>, config: &OverlapConfig) -> Option<PrRecord>

The record for one easyconfigs pull request, or None when it carries no easyconfig changes.

A pull request whose changed-file list stopped at GitHub’s cap still produces a record, including when none of the returned files is an easyconfig. Its notes contain GITHUB_PR_FILES_TRUNCATED.

fn easyconfig_record_seeing(pr: &PrInput, base: &[Candidate], other_easyconfigs: &[FileChange], installed: Option<&BTreeSet<String>>, config: &OverlapConfig) -> Option<PrRecord>

Like easyconfig_record, and other open pull requests’ easyconfig files are visible while resolving.

Those files sit above the base tree and under this pull request’s own files. Added and modified files replace base text, and a deleted file is removed. A module only they provide is still new: new_modules is compared to base alone. One pull request on its own passes an empty slice, which is easyconfig_record.

to_build starts as new_modules, or as the closure minus --installed when that list is passed. modules_to_rebuild is then added, and those modules are removed from already_installed, so a patched recipe and a bundle that ships it are scheduled even when the name is already installed. review and no-rebuild reverse dependents stay on the record and out of to_build. Merge order and impact read to_build, so that is the set they schedule.

fn eb_version_of(path: &str) -> Option<String>

EasyBuild version from an easystack file name such as eessi-2026.06-eb-5.4.0-2026.1.yml.

fn eessi_version_of(path: &str) -> Option<String>

Stack version from an easystack path under easystacks/software.eessi.io/.

fn fetch_open_easyconfig_prs(http: &dyn HttpGet, query: &OpenEasyconfigQuery) -> anyhow::Result<Vec<PrInput>>

Read open easyconfigs pull requests over HTTPS.

The open list and the changed-file list come from https://api.github.com. Head text is https://raw.githubusercontent.com/<repo>/<sha>/<path>. Base text is the same URL with OpenEasyconfigQuery::base_ref. A 404 on the base means the file was added. GITHUB_TOKEN or GH_TOKEN is sent to api.github.com when set. The file text is data: nothing from a pull request is executed.

GitHub returns at most 3000 changed files (30 pages at per_page=100). The list is paged with the Link header’s rel="next" until that cap. A list that stops there is not an error: the pull request is kept, with PrInput::file_list_truncated set, and the record notes GITHUB_PR_FILES_TRUNCATED.

fn fetch_open_software_layer_prs(http: &dyn HttpGet, query: &OpenEasyconfigQuery) -> anyhow::Result<Vec<PrInput>>

Read open software-layer pull requests over HTTPS: each changed easystack file under easystacks/, with its base text from OpenEasyconfigQuery::base_ref (main for EESSI/software-layer) and its head text. A pull request that changes no easystack is left out, unless GitHub truncated its changed-file list: that pull request is kept with PrInput::file_list_truncated set, and the record notes GITHUB_PR_FILES_TRUNCATED. The file text is data: nothing from a pull request is executed.

fn file_revisions(pr: &PrInput, config: &OverlapConfig) -> Vec<FileRevision>

Easystack revisions for this stack version, then easyconfig files.

Conflict detection reads these later, so the text or blob has to be here even when the closure itself is already stored.

fn head_entries(change: &EasystackChange) -> Vec<EasystackEntry>

Every easystack entry at head, in head order.

A deleted file has no head text, so it contributes nothing. The bot does not build a file the pull request removes.

fn overlap_index(records: &[PrRecord], config: &OverlapConfig) -> OverlapIndex

Intersect the to-build sets of every record.

fn parse_installed(text: &str) -> BTreeSet<String>

Read an installed-module list: one Name/VersionFull per line, as listed under an install tree’s software/ or modules/all/. Blank lines and # comments are skipped; a trailing .lua and a trailing / are dropped.

fn pr_record(pr: &PrInput, trees: &RobotTrees, installed: &BTreeSet<String>, config: &OverlapConfig) -> Option<PrRecord>

The record for one pull request, or None when it changes no easystack of the configured version.

A pull request whose changed-file list stopped at GitHub’s cap still produces a record. Its notes contain GITHUB_PR_FILES_TRUNCATED.

fn read_pr_inputs(path: &std::path::Path, flag: &str) -> anyhow::Result<Vec<PrInput>>

Read pull-request JSON: one PrInput object, or an array of them. flag is the command-line flag the path came from, for the error.

fn record_to_toml(record: &PrRecord) -> Result<String, toml::ser::Error>

One pull request’s record, with to_build as one sorted line per module.

The same line in two prs/<N>.toml files is a module both pull requests would build. git diff shows a deploy dropping that line, and sort | uniq -d across the to_build lines is the overlap.

fn records_for_arch(records: &[PrRecord], arch: &str) -> Vec<PrRecord>

Records whose to_build is the build set for arch.

Merge order and impact read to_build. A multi-architecture record keeps each architecture on build_sets, so this view is what those two consume.

fn render_markdown(records: &[PrRecord], index: &OverlapIndex, repo_url: &str) -> String

The overlap report for reviewers, as Markdown.

Pull requests are written as plain #N text inside a file, which links on GitHub without adding anything to the pull requests’ timelines.

fn to_toml<T: Serialize>(value: &T) -> Result<String, toml::ser::Error>

A record or index as TOML, with the generated-file header.

fn validate_open_easyconfig_query(repo: &str, base_ref: Option<&str>) -> anyhow::Result<()>

Reject a repository or base ref that cannot be placed in a GitHub URL.

An empty or absent base ref means develop and is not checked. This does not open a connection.

Traits

trait HttpGet

GET used to read pull requests. The live client is UreqGet.

Functions

fn get(&self, url: &str) -> Result<HttpResponse, String>

Fetch url. A transport failure is Err. An HTTP error status is Ok.

Enums

enum BuildScope

Which easystack lines seed a software-layer closure.

Added

Entries present at head and absent from base.

ChangedEasystack

Every entry at the head of each changed easystack.

This is what the EESSI bot builds: the whole changed file, not only the lines the pull request adds. An entry that is already installed is still a leaf.

Structs and Unions

struct ArchBuildSet

One architecture’s build set for a pull request.

Present when --arch-installed names more than one architecture. A single installed list keeps that set in PrRecord::to_build instead.

arch: String

Label from --arch-installed, for example riscv64.

to_build: Vec<String>

Modules the bot would build on this architecture, sorted.

already_installed: Vec<String>

Installed modules the walk reached and stopped at, sorted.

unresolved: Vec<String>

Requirements no easyconfig on the robot path satisfies.

carried: Vec<String>

Head entries in to_build that this pull request did not add.

struct ArchOverlap

Shared modules on one architecture.

arch: String

Label from --arch-installed.

shared: BTreeMap<String, Vec<u64>>

Module to the pull requests that would build it, for modules more than one would build.

pairs: BTreeMap<String, BTreeMap<String, Vec<String>>>

Per pull request, the other pull requests it shares modules with.

struct ChangedEasyconfig

One easyconfig a pull request adds, changes, or deletes.

path: String

Path in the repository.

status: String

added, modified, or deleted.

module: Option<String>

Module the file provides. Absent when the text did not parse.

struct EasyblockCatalog

Easyblock classes a run can see.

base is the installed easyblocks package. commits holds the classes from each include-easyblocks-from-commit tree that was passed in. A class in a commit tree is what --include-easyblocks-from-commit adds ahead of the installed package. check is set only when that installed package was passed in: without it, every derived class would look missing.

check: bool

When true, a class in neither base nor the entry’s commit trees is easyblock <class> missing and is not counted as a module to build.

base: BTreeMap<String, String>

Class name to the file that defines it in the installed package.

commits: BTreeMap<String, BTreeMap<String, String>>

Per commit: class name to the file that defines it.

struct FileChange

One changed file in a pull request: path plus the text on each side.

path: String

Path in the repository.

base: Option<String>

File text on the base branch; absent for a file the PR adds.

head: Option<String>

File text at the PR head; absent for a file the PR deletes.

base_blob: Option<String>

Git blob id of base, when the fetch recorded it.

head_blob: Option<String>

Git blob id of head, when the fetch recorded it.

struct FileRevision

One changed file stored on a record: path, kind, and base/head text or blob.

path: String

Path in the software-layer repository, or an easyconfig filename.

kind: String

easystack or easyconfig.

base_blob: Option<String>

Git blob id of the base text.

head_blob: Option<String>

Git blob id of the head text.

base: Option<String>

Base text. Absent when the fetch stored only a blob id.

head: Option<String>

Head text. Absent when the fetch stored only a blob id.

struct HttpResponse

HTTP status and body. A 404 is Ok: a missing base file is data.

status: u16

Status code.

body: Vec<u8>

Response body.

Link header, when the server sent one.

The pulls files API pages with rel="next". A client that does not record the header leaves this empty, and a full page is treated as “there may be another page”.

struct OpenEasyconfigQuery

Which open easyconfigs pull requests to read, and where to stop.

repo: String

owner/name.

base_ref: String

Git ref for the base text of a changed file. develop when empty.

max_pages: Option<usize>

Stop after this many open-list pages. None reads every page.

max_prs: Option<usize>

Stop after this many pull requests that change an easyconfig.

max_files: Option<usize>

Stop after this many easyconfig files on one pull request.

page_size: Option<usize>

Items per GitHub page. None is 100, the GitHub maximum.

Implementations

impl OpenEasyconfigQuery

Functions

fn new(repo: impl Into<String>) -> Self

Read every open pull request of repo against develop.

struct OverlapConfig

Settings shared by every record of one run.

eessi_version: String

Stack version whose easystacks count, e.g. 2026.06.

installed_source: String

Where the installed list came from, e.g. x86_64/amd/zen4.

exclude_paths: Vec<String>

Easystack paths containing any of these substrings are left out (accelerator or arch-specific stacks the installed list does not cover).

include_paths: Vec<String>

When non-empty, only easystack paths containing one of these substrings are kept. Used to run a second pass over an arch the first pass excluded.

generated_at: String

RFC 3339 timestamp written into every record.

filter_deps: FilterDeps

Dependencies dropped the way EasyBuild’s --filter-deps drops them, together with everything reachable only through them.

easyblocks: Option<EasyblockCatalog>

Easyblock classes to resolve. None skips the check.

build_scope: BuildScope

Which easystack lines seed the closure. Added lines unless a bot build set was requested.

struct OverlapIndex

Shared to-build modules across records.

schema_version: u32

Index schema.

generated_at: String

When it was computed.

eessi_version: String

Stack version. Empty, and omitted, for an easyconfigs run.

installed_source: String

Where the installed list came from.

prs: Vec<u64>

Pull requests with a record, ascending.

shared: BTreeMap<String, Vec<u64>>

Module to the pull requests that would build it, for modules more than one would build.

pairs: BTreeMap<String, BTreeMap<String, Vec<String>>>

Per pull request: the other pull requests it shares modules with, and which modules, keyed by the pull request number as a string.

rows: Vec<OverlapRow>

Typed overlap rows for an easyconfigs run. Empty, and omitted, for a software-layer run, which keeps the schema 1 field set.

arches: Vec<ArchOverlap>

Per-architecture overlap. Empty, and omitted, for a single installed list.

struct OverlapRow

One overlap between easyconfigs pull requests.

kind: String

same-file, same-module, shared-new-module, or depends-on.

prs: Vec<u64>

Pull requests that share a path or a module, ascending.

path: String

Path two pull requests both change. Empty for the other kinds.

module: String

Module two pull requests both add, or both list as new.

from: Option<u64>

Pull request that adds the module, for depends-on.

to: Option<u64>

Pull request whose closure contains that module, for depends-on.

modules: Vec<String>

Modules to takes from from.

struct PrInput

One pull request as read from the forge: identity plus easystack changes.

number: u64

Pull request number.

head_sha: String

Head commit the files were read at.

title: Option<String>

Title, for the report.

easystacks: Vec<EasystackChange>

Changed easystack files.

files: Vec<FileRevision>

Changed easyconfig files (*.eb), with base and head text or blob ids.

A later merge-order reads these to see a hunk collision without the original JSON.

easyconfigs: Vec<FileChange>

Changed easyconfig files (path ending in .eb) to close over the base tree. Other paths are ignored and named in the record’s notes.

file_list_truncated: bool

GitHub returned only part of the changed-file list. A record notes GITHUB_PR_FILES_TRUNCATED. The files above are the ones returned.

struct PrRecord

What one pull request would build, as stored on the data branch.

schema_version: u32

Record schema.

pr: u64

Pull request number.

head_sha: String

Head commit the record was computed for.

title: Option<String>

Title at that commit.

generated_at: String

When the record was computed.

eessi_version: String

Stack version. Empty, and omitted, for an easyconfigs pull request.

installed_source: String

Where the installed list came from.

easystack_files: Vec<String>

Easystack files the pull request changes for that version.

to_build: Vec<String>

Module names that would be built, sorted.

already_installed: Vec<String>

Installed modules the closure reached and stopped at, sorted.

unresolved: Vec<String>

Requirements no easyconfig on the robot path satisfies, and easyblock classes the run cannot resolve (easyblock EB_eOn missing).

notes: Vec<String>

Easyblocks supplied by a commit or pull request, and commits named by an entry whose tree was not passed in.

entries: Vec<RecordEntry>

The easystack entries the pull request adds.

revisions: Vec<FileRevision>

Easystack and easyconfig files this pull request changes. Base and head text, or their blob ids, are what a later merge-order uses to see a hunk collision without the original JSON.

kind: String

software-layer or easyconfigs. Empty on a software-layer record, which keeps the schema 1 field set.

changed_easyconfigs: Vec<ChangedEasyconfig>

Easyconfigs this pull request adds, changes, or deletes.

closure: Vec<String>

Every module the changed easyconfigs reach, sorted, including the pull request’s own modules.

new_modules: Vec<String>

Closure modules the base tree alone does not provide, sorted.

reverse_dependents: Vec<ReverseDependent>

Base-tree modules that depend on a file this pull request modifies or deletes, nearest first.

build_scope: String

changed-easystack when the closure started from every head entry. Empty, and omitted, for the added-lines default.

carried: Vec<String>

Head entries in to_build that this pull request did not add. Empty, and omitted, for the added-lines default.

build_sets: Vec<ArchBuildSet>

One build set per architecture. Empty, and omitted, for a single installed list, whose set is to_build.

struct RecordEntry

One easystack entry a pull request adds.

easystack: String

Easystack file the entry is in.

easyconfig: String

Easyconfig file name.

from_commit: Option<String>

from-commit pin, when the entry has one.

eb_version: Option<String>

EasyBuild version from the easystack’s file name, when it carries one.

struct ReverseDependent

A base-tree module that resolves a dependency to a file this pull request modifies or deletes. depth 1 is direct.

module: String

Module name, name/version[-toolchain]versionsuffix.

depth: u32

Shortest dependency distance from a changed file.

class: String

must-rebuild, review, or no-rebuild.

The spellings match rebuild-set. must-rebuild is copied into to_build. The other two stay on this list.

struct RobotTrees

Robot-path trees: the release tree, and per from-commit the easyconfigs tree at that commit, which EasyBuild puts ahead of the release tree.

base: Vec<Candidate>

Easyconfigs of the EasyBuild release the stack uses.

commits: BTreeMap<String, Vec<Candidate>>

Easyconfigs fetched for one from-commit, keyed by commit.

struct UreqGet

Live HTTPS client. The default test gate does not construct it.

Traits implemented

impl HttpGet for UreqGet