mod easyblock_reach

module easyblock_reach

Which easyblock classes a changed Python file reaches.

The class hierarchy is the class statement, not an import of the base: EB_GROMACS(CMakeMake) is reached by a change to CMakeMake. A nested class counts, and so does the class that encloses it: QuantumESPRESSO delegates to EB_QuantumESPRESSOcmake(CMakeMake). A module-level name bound to a class (Legacy = CMakeMake) is that class. A framework module reaches the easyblocks that import it, and then their subclasses. Imports among easybuild.framework and easybuild.tools are followed transitively, so a change to tools/run.py reaches an easyblock that imports tools/filetools.py when that module imports tools/run.py. Easyconfig matching is layered on top of this index.

Variables

const GENERATED_HEADER: &str

Header on every generated TOML file.

const REACH_SCHEMA_VERSION: u32

Schema of ReachReport.

Functions

fn affected_classes(index: &EasyblockIndex, path: &Path, source: &str) -> Result<ClassReach, String>

Classes a changed file defines, classes that import its module, and subclasses.

A change under easybuild.framework or easybuild.tools also reaches classes that import a framework or tools module which itself imports the changed module, through any number of those packages.

fn descendants(index: &EasyblockIndex, class_name: &str) -> BTreeSet<String>

Proper subclasses of class_name, including subclasses of subclasses.

fn diff_sources(request: &DiffRequest) -> Result<Vec<(PathBuf, String)>, ReachError>

Python files a range or pull request changes, new side, or the base if deleted.

fn index_roots(roots: &[PathBuf]) -> Result<EasyblockIndex, String>

Index every .py file under roots. Earlier roots win a class name.

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

Installed module names, one per line. Blank lines and # comments are ignored.

fn python_module(path: &Path) -> Option<String>

easybuild.tools.filetools for .../easybuild/tools/filetools.py.

fn reach(query: &ReachQuery) -> Result<ReachReport, ReachError>

Which easyconfigs use a reached class, by the easyblock line or EB_<Name>.

fn read_sources(paths: &[PathBuf]) -> Result<Vec<(PathBuf, String)>, ReachError>

Read Python sources from explicit paths.

fn render_markdown(report: &ReachReport) -> String

Reviewer markdown. The HTML comment marks the file as generated.

fn to_json(report: &ReachReport) -> Result<String, serde_json::Error>

Pretty JSON, no generated-file comment.

fn to_toml(report: &ReachReport) -> Result<String, toml::ser::Error>

TOML with the generated-file header.

fn write_report(report: &ReachReport, dir: &Path) -> Result<(), ReachError>

Write reach.toml, reach.json, and reach.md under dir.

Enums

enum ReachError

Why a reach report could not be built.

Message(String)

A parse or argument failure, already worded for the CLI.

Io(std::io::Error)

Reading an easyconfig or easyblock tree failed.

Structs and Unions

struct ClassFact

What a class declares about itself, read from its source.

bases: Vec<String>

Base classes as written, last component or dotted.

exts_default: Option<String>

self.cfg['exts_defaultclass'] = '...' in the class body.

component_default: Option<String>

default_easyblock assigned in extra_options.

struct ClassReach

Classes named by a change, and those plus every subclass.

changed: BTreeSet<String>

Defined in the changed file, or defined in a file that imports it.

reached: BTreeSet<String>

changed plus subclasses.

struct DiffRequest

A commit range or a pull request in a local clone.

repo: PathBuf

Easyblocks or framework clone.

range: Option<String>

Passed to git diff --name-only, for example base..HEAD.

pr: Option<u64>

Fetch refs/pull/N/head and diff it against the merge-base with base.

remote: String

Remote git fetch reads. . is this clone.

base: String

Branch the pull request is based on. Default develop at the CLI.

struct EasyblockIndex

Easyblock classes and the modules that import them.

classes: BTreeMap<String, ClassFact>

Class name to what its source declares.

importers: BTreeMap<String, BTreeSet<String>>

Python module to the classes defined in files that import it.

module_importers: BTreeMap<String, BTreeSet<String>>

Python module to the modules that import it.

enclosing: BTreeMap<String, String>

Nested class to the class whose body defines it.

aliases: BTreeMap<String, String>

Module-level name bound to a different class (Legacy = CMakeMake).

struct ReachHit

One place an easyconfig uses a reached class.

easyconfig: String

Easyconfig path.

module: String

Module that easyconfig installs.

class_name: String

Easyblock class that matched.

via: String

easyblock, implied, extension, exts_defaultclass, exts_classmap, component, or default_easyblock.

detail: String

Extension or component name. Empty for the recipe’s own class.

installed: bool

True when module is in the installed set.

struct ReachQuery

What to resolve.

roots: Vec<PathBuf>

Easyblock and framework roots. Earlier roots win a class name.

easyconfigs: Vec<PathBuf>

Easyconfig files or directories.

changed: Vec<(PathBuf, String)>

Changed path and the Python source classes are read from.

installed: BTreeSet<String>

Installed module names (name/version[-toolchain]versionsuffix).

reverse: bool

Also list modules that depend on a reached module.

generated_at: String

Timestamp stored on the report.

struct ReachReport

Easyconfigs reached by a change to an easyblock or a framework module.

schema_version: u32

REACH_SCHEMA_VERSION.

generated_at: String

Copied from the query.

changed_files: Vec<String>

Changed Python paths.

changed_classes: Vec<String>

Classes defined in those files, plus classes that import them.

reached_classes: Vec<String>

changed_classes plus subclasses.

easyconfig_count: usize

Distinct easyconfigs in hits.

installed_count: usize

Distinct installed modules in hits.

hits: Vec<ReachHit>

One row per matched class on an easyconfig.

reverse: Vec<ReverseRow>

Dependents of a hit. Empty when the query did not ask for them.

skipped: Vec<String>

Easyconfigs that could not be parsed.

struct ReverseRow

A module that uses a reached module and would need a rebuild.

module: String

Dependent module.

easyconfig: String

Easyconfig that installs it, when the tree has one.

kind: String

runtime, builddependency, extension, or toolchain.

via: String

Intermediate modules, nearest to the reached module first.