Skip to content

Commit 4e31ef6

Browse files
committed
feat(stack): write the solved dependency DAG as Graphviz DOT
stack solve --dot-out and the MCP field dot_out write the solved dependency graph. A node is name/version plus the toolchain and the versionsuffix. An edge carries the requirement, and a builddependency is dashed. A .svg or .png path is rendered with dot.
1 parent 02a4351 commit 4e31ef6

9 files changed

Lines changed: 393 additions & 3 deletions

File tree

‎.github/workflows/ci_test.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@ jobs:
195195
--test sbom_page_drift \
196196
--test sbom_schema \
197197
--test skill_easyblock_fix \
198+
--test solved_dot \
198199
--test solver_completeness \
199200
--test stack_files \
200201
--test stack_order_filter \

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -387,6 +387,12 @@ All notable changes to this project are documented here.
387387

388388
### Added
389389

390+
- `stack solve --dot-out` and the MCP field `dot_out` write the solved
391+
dependency DAG. A node is `name/version` plus the toolchain, and the
392+
versionsuffix when the recipe has one. An edge points from a package to a
393+
dependency it selected and is labelled with the requirement; a
394+
builddependency is dashed. A `.svg` or `.png` path is rendered with
395+
Graphviz `dot`. Any other suffix is the DOT source.
390396
- `stack generation` and `eb_stack_generation` check each added entry's
391397
toolchain generation against the generation the easystack file name names,
392398
the token after `eb-<X.Y.Z>-` such as `-2025b.yml`. An entry whose

‎docs/orgmode/reference/cli.org‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -412,7 +412,8 @@ eb-stack stack solve \
412412
[--build-list-out /tmp/build.list] [--build-list-excludes-baseline] \
413413
[--jenkins-build-list-out /tmp/next.list [--jenkins-flags-from /tmp/previous.list]... \
414414
[--jenkins-gpu-systems gpu-a,gpu-b] [--jenkins-roots-only]] \
415-
[--stack-diff-out /tmp/stack.diff.md]
415+
[--stack-diff-out /tmp/stack.diff.md] \
416+
[--dot-out /tmp/stack.dot]
416417

417418
eb-stack stack sbom --lock /tmp/stack.lock.json [--out /tmp/stack.cdx.json]
418419

@@ -536,6 +537,13 @@ preferences use the TOML schema documented with the package workflow; whole
536537
stack solving uses the JSON ~Policy~ schema. The policy file is
537538
~--stack-policy~, the same flag ~package plan~ and ~package bump~ take.
538539

540+
~--dot-out~ writes the solved dependency DAG. A node is ~name/version~ plus
541+
the toolchain, and the versionsuffix when the recipe has one. An edge points
542+
from a package to a dependency it selected and is labelled with the
543+
requirement; a builddependency is dashed. A ~.svg~ or ~.png~ path is rendered
544+
with the Graphviz ~dot~ program. Any other suffix, including ~.dot~, is the
545+
DOT source. The MCP field ~dot_out~ writes the same file.
546+
539547
The baseline is either a previous generation (~--baseline-easyconfigs~, by
540548
default the first ~--easyconfigs~ tree) or what a set of easystacks installs
541549
(~--baseline-easystack~, repeatable). An easystack baseline is every entry

‎llms-full.txt‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4753,7 +4753,8 @@ eb-stack stack solve \
47534753
[--build-list-out /tmp/build.list] [--build-list-excludes-baseline] \
47544754
[--jenkins-build-list-out /tmp/next.list [--jenkins-flags-from /tmp/previous.list]... \
47554755
[--jenkins-gpu-systems gpu-a,gpu-b] [--jenkins-roots-only]] \
4756-
[--stack-diff-out /tmp/stack.diff.md]
4756+
[--stack-diff-out /tmp/stack.diff.md] \
4757+
[--dot-out /tmp/stack.dot]
47574758

47584759
eb-stack stack sbom --lock /tmp/stack.lock.json [--out /tmp/stack.cdx.json]
47594760

@@ -4877,6 +4878,13 @@ preferences use the TOML schema documented with the package workflow; whole
48774878
stack solving uses the JSON `Policy` schema. The policy file is
48784879
`--stack-policy`, the same flag `package plan` and `package bump` take.
48794880

4881+
`--dot-out` writes the solved dependency DAG. A node is `name/version` plus
4882+
the toolchain, and the versionsuffix when the recipe has one. An edge points
4883+
from a package to a dependency it selected and is labelled with the
4884+
requirement; a builddependency is dashed. A `.svg` or `.png` path is rendered
4885+
with the Graphviz `dot` program. Any other suffix, including `.dot`, is the
4886+
DOT source. The MCP field `dot_out` writes the same file.
4887+
48804888
The baseline is either a previous generation (`--baseline-easyconfigs`, by
48814889
default the first `--easyconfigs` tree) or what a set of easystacks installs
48824890
(`--baseline-easystack`, repeatable). An easystack baseline is every entry

‎src/lib.rs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,8 @@ pub use sbom::{
196196
artifact_facts_for_lock, build_dep_map_from_universe, dep_map_from_universe, dep_maps_for_lock,
197197
host_build_environment, lock_to_bom, lock_to_bom_with_facts, lock_to_cyclonedx,
198198
lock_to_cyclonedx_from_recipes, lock_to_cyclonedx_with_deps, lock_to_cyclonedx_with_facts,
199-
lock_to_cyclonedx_with_runtime_and_build, ArtifactFacts, SbomFacts, SbomReadStats,
199+
lock_to_cyclonedx_with_runtime_and_build, solved_dependency_dot, write_solved_dependency_graph,
200+
ArtifactFacts, SbomFacts, SbomReadStats,
200201
};
201202
pub use select::{resolvo_resolve_dep_versions, select_stack, SelectError};
202203

‎src/main.rs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -899,6 +899,15 @@ struct SolveArgs {
899899
/// Markdown diff of this solve against the baseline.
900900
#[arg(long)]
901901
stack_diff_out: Option<PathBuf>,
902+
/// Graphviz drawing of the solved dependency DAG.
903+
///
904+
/// A node is `name/version` plus the toolchain, and the versionsuffix
905+
/// when the recipe has one. An edge points from a package to a
906+
/// dependency it selected and is labelled with that requirement; a
907+
/// builddependency is dashed. A `.svg` or `.png` path is rendered with
908+
/// `dot`. Any other suffix is the DOT source.
909+
#[arg(long)]
910+
dot_out: Option<PathBuf>,
902911
}
903912

904913
#[derive(clap::Args, Debug)]
@@ -2483,6 +2492,7 @@ fn run_stack(command: StackCommand) -> Result<()> {
24832492
jenkins_gpu_systems,
24842493
jenkins_roots_only,
24852494
stack_diff_out,
2495+
dot_out,
24862496
} = *args;
24872497
for path in &roots_from_build_list {
24882498
let text = std::fs::read_to_string(path)
@@ -2637,11 +2647,18 @@ fn run_stack(command: StackCommand) -> Result<()> {
26372647
error
26382648
}
26392649
})?;
2650+
if let Some(path) = &dot_out {
2651+
eb_stack::write_solved_dependency_graph(&lock, &lock_out, path)
2652+
.map_err(|error| anyhow::anyhow!(error))?;
2653+
}
26402654
println!(
26412655
"lock={} packages={}",
26422656
lock_out.display(),
26432657
lock.packages.len()
26442658
);
2659+
if let Some(path) = &dot_out {
2660+
println!("dot={}", path.display());
2661+
}
26452662
Ok(())
26462663
}
26472664
StackCommand::Order {

‎src/mcp.rs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,7 @@ fn tool_catalog() -> Vec<Value> {
338338
("jenkins_gpu_systems", "array"),
339339
("jenkins_roots_only", "boolean"),
340340
("stack_diff_out", "string"),
341+
("dot_out", "string"),
341342
],
342343
),
343344
tool_with_optional(
@@ -2812,6 +2813,9 @@ fn stack_solve(arguments: &Value) -> Result<Value, String> {
28122813
},
28132814
)
28142815
.map_err(|error| error.to_string())?;
2816+
if let Some(path) = optional_path(arguments, "dot_out") {
2817+
crate::sbom::write_solved_dependency_graph(&lock, &lock_out, &path)?;
2818+
}
28152819
Ok(json!({
28162820
"lock": lock_out,
28172821
"packages": lock.packages.len(),

‎src/sbom.rs‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -651,6 +651,198 @@ pub fn closure_edges_for_lock(lock: &StackLock, lock_file: &Path) -> HashMap<Str
651651
edges
652652
}
653653

654+
/// Graphviz DOT for the dependency DAG of a solved lock.
655+
///
656+
/// A node is `name/version` plus the toolchain, and the versionsuffix when
657+
/// the selected recipe has one. An edge points from a package to a
658+
/// dependency it selected. The label is the requirement as the solver read
659+
/// it, plus a versionsuffix or an explicit toolchain when the tuple carries
660+
/// one. A builddependency that is not also a runtime dependency is dashed.
661+
///
662+
/// Edges come from the easyconfigs the lock names, the same walk as
663+
/// [`closure_edges_for_lock`]. A dependency the lock did not select is left
664+
/// out. Node order is the lock's package order made deterministic by name,
665+
/// version, versionsuffix, and toolchain.
666+
pub fn solved_dependency_dot(lock: &StackLock, lock_file: &Path) -> String {
667+
let lock_dir = lock_directory(lock_file);
668+
let mut nodes: Vec<&crate::domain::LockPackage> = lock.packages.iter().collect();
669+
nodes.sort_by(|a, b| {
670+
(
671+
&a.name,
672+
&a.version,
673+
a.versionsuffix.as_deref().unwrap_or(""),
674+
toolchain_text(&a.toolchain),
675+
)
676+
.cmp(&(
677+
&b.name,
678+
&b.version,
679+
b.versionsuffix.as_deref().unwrap_or(""),
680+
toolchain_text(&b.toolchain),
681+
))
682+
});
683+
let mut id_of: HashMap<String, String> = HashMap::new();
684+
for (index, package) in nodes.iter().enumerate() {
685+
id_of.insert(package_identity(package), format!("n{index}"));
686+
}
687+
688+
let mut edges: BTreeMap<(String, String), (String, bool)> = BTreeMap::new();
689+
for package in &lock.packages {
690+
let Some(resolved) = (!package.easyconfig_path.is_empty())
691+
.then(|| {
692+
crate::eb_parse::resolve_easyconfig_file(&resolve_lock_easyconfig(
693+
lock_dir,
694+
&package.easyconfig_path,
695+
))
696+
.ok()
697+
})
698+
.flatten()
699+
else {
700+
continue;
701+
};
702+
let candidate = resolved.to_candidate();
703+
let from = package_identity(package);
704+
for (dep, runtime) in candidate
705+
.dependencies
706+
.iter()
707+
.map(|dep| (dep, true))
708+
.chain(candidate.builddependencies.iter().map(|dep| (dep, false)))
709+
{
710+
let Some(target) = resolve_locked_dep(lock, package, dep) else {
711+
continue;
712+
};
713+
let key = (from.clone(), package_identity(target));
714+
let label = dependency_edge_label(dep);
715+
if let Some(drawn) = edges.get_mut(&key) {
716+
if runtime {
717+
*drawn = (label, true);
718+
}
719+
} else {
720+
edges.insert(key, (label, runtime));
721+
}
722+
}
723+
}
724+
725+
let mut out = String::from("digraph solved {\n");
726+
out.push_str(" rankdir=TB;\n");
727+
out.push_str(" graph [fontname=\"Helvetica\"];\n");
728+
out.push_str(" node [shape=box, fontname=\"Helvetica\", fontsize=11];\n");
729+
out.push_str(" edge [fontname=\"Helvetica\", fontsize=9];\n");
730+
for package in &nodes {
731+
let id = &id_of[&package_identity(package)];
732+
let version = format!(
733+
"{}{}",
734+
package.version,
735+
package.versionsuffix.as_deref().unwrap_or("")
736+
);
737+
// Graphviz `\n`, written as two characters so a node stays one source line.
738+
let label = format!(
739+
"{}\\n{}",
740+
dot_escape(&format!("{}/{}", package.name, version)),
741+
dot_escape(&toolchain_text(&package.toolchain))
742+
);
743+
out.push_str(&format!(" {id} [label=\"{label}\"];\n"));
744+
}
745+
for ((from, to), (label, runtime)) in &edges {
746+
let Some(from_id) = id_of.get(from) else {
747+
continue;
748+
};
749+
let Some(to_id) = id_of.get(to) else {
750+
continue;
751+
};
752+
let style = if *runtime { "" } else { ", style=dashed" };
753+
out.push_str(&format!(
754+
" {from_id} -> {to_id} [label=\"{}\", color=\"#004D40\"{style}];\n",
755+
dot_escape(label)
756+
));
757+
}
758+
out.push_str("}\n");
759+
out
760+
}
761+
762+
/// Write the solved dependency DAG.
763+
///
764+
/// `.svg` and `.png` are rendered with the Graphviz `dot` program. Any other
765+
/// suffix, including `.dot`, is the DOT source.
766+
pub fn write_solved_dependency_graph(
767+
lock: &StackLock,
768+
lock_file: &Path,
769+
out: &Path,
770+
) -> Result<(), String> {
771+
let dot = solved_dependency_dot(lock, lock_file);
772+
if let Some(parent) = out.parent() {
773+
if !parent.as_os_str().is_empty() {
774+
std::fs::create_dir_all(parent)
775+
.map_err(|error| format!("create {}: {error}", parent.display()))?;
776+
}
777+
}
778+
let kind = out
779+
.extension()
780+
.and_then(|ext| ext.to_str())
781+
.unwrap_or("")
782+
.to_ascii_lowercase();
783+
if kind == "svg" || kind == "png" {
784+
let mut child = std::process::Command::new("dot")
785+
.arg(format!("-T{kind}"))
786+
.arg("-o")
787+
.arg(out)
788+
.stdin(std::process::Stdio::piped())
789+
.spawn()
790+
.map_err(|error| {
791+
format!(
792+
"rendering {} needs the graphviz dot program: {error}",
793+
out.display()
794+
)
795+
})?;
796+
let stdin = child.stdin.as_mut().ok_or("dot stdin")?;
797+
std::io::Write::write_all(stdin, dot.as_bytes())
798+
.map_err(|error| format!("write dot source: {error}"))?;
799+
// Drop stdin before waiting so dot sees EOF.
800+
child.stdin.take();
801+
let status = child
802+
.wait()
803+
.map_err(|error| format!("wait for dot: {error}"))?;
804+
if !status.success() {
805+
return Err(format!("dot exited {status}"));
806+
}
807+
return Ok(());
808+
}
809+
std::fs::write(out, dot).map_err(|error| format!("write {}: {error}", out.display()))?;
810+
Ok(())
811+
}
812+
813+
fn toolchain_text(toolchain: &crate::domain::Toolchain) -> String {
814+
if crate::hierarchy::is_system_toolchain(toolchain) {
815+
"system".to_string()
816+
} else {
817+
format!("{}-{}", toolchain.name, toolchain.version)
818+
}
819+
}
820+
821+
fn dependency_edge_label(dep: &crate::domain::DepReq) -> String {
822+
let mut label = dep.version_req.clone();
823+
if let Some(suffix) = dep.versionsuffix.as_deref() {
824+
if !suffix.is_empty() {
825+
label.push_str(" suffix ");
826+
label.push_str(suffix);
827+
}
828+
}
829+
if let Some(toolchain) = &dep.toolchain {
830+
label.push_str(" toolchain ");
831+
if crate::hierarchy::is_system_toolchain(toolchain) {
832+
label.push_str("system");
833+
} else {
834+
label.push_str(&toolchain.name);
835+
label.push('/');
836+
label.push_str(&toolchain.version);
837+
}
838+
}
839+
label
840+
}
841+
842+
fn dot_escape(text: &str) -> String {
843+
text.replace('\\', "\\\\").replace('"', "\\\"")
844+
}
845+
654846
/// How many recipes a lock SBOM could read.
655847
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
656848
pub struct SbomReadStats {

0 commit comments

Comments
 (0)