chore: resolution debugging tool (#86)

Author: dsherret

.github/workflows/ci.yml

@@ -6,7 +6,7 @@ on:
   push:
     branches: [main]
     tags:
-    - '*'
+      - "*"
   workflow_dispatch:
 
 jobs:

.github/workflows/release.yml

@@ -4,8 +4,8 @@ on:
   workflow_dispatch:
     inputs:
       releaseKind:
-        description: 'Kind of release'
-        default: 'minor'
+        description: "Kind of release"
+        default: "minor"
         type: choice
         options:
           - patch

Cargo.toml

@@ -9,6 +9,9 @@ documentation = "https://docs.rs/deno_npm"
 authors = ["the Deno authors"]
 license = "MIT"
 
+[features]
+tracing = []
+
 [dependencies]
 async-trait = "0.1.68"
 deno_semver = "0.7.0"

src/resolution/graph.rs

@@ -332,6 +332,8 @@ pub struct Graph {
   // This will be set when creating from a snapshot, then
   // inform the final snapshot creation.
   packages_to_copy_index: HashMap<NpmPackageId, u8>,
+  #[cfg(feature = "tracing")]
+  traces: Vec<super::tracing::TraceGraphSnapshot>,
 }
 
 impl Graph {
@@ -436,6 +438,8 @@ impl Graph {
       package_name_versions: Default::default(),
       resolved_node_ids: Default::default(),
       root_packages: Default::default(),
+      #[cfg(feature = "tracing")]
+      traces: Default::default(),
     };
     let mut created_package_ids =
       HashMap::with_capacity(snapshot.packages.len());
@@ -599,6 +603,11 @@ impl Graph {
     api: &TNpmRegistryApi,
     patch_packages: &HashMap<PackageName, Vec<NpmPackageVersionInfo>>,
   ) -> Result<NpmResolutionSnapshot, NpmRegistryPackageInfoLoadError> {
+    #[cfg(feature = "tracing")]
+    if !self.traces.is_empty() {
+      super::tracing::output(&self.traces);
+    }
+
     let packages_to_pkg_ids = self
       .nodes
       .keys()
@@ -1036,6 +1045,25 @@ impl<'a, TNpmRegistryApi: NpmRegistryApi>
               }
             };
 
+            #[cfg(feature = "tracing")]
+            {
+              self.graph.traces.push(build_trace_graph_snapshot(
+                self.graph,
+                &self.dep_entry_cache,
+                &parent_path.with_id(
+                  child_id,
+                  dep.bare_specifier.clone(),
+                  self
+                    .graph
+                    .resolved_node_ids
+                    .get(child_id)
+                    .unwrap()
+                    .nv
+                    .clone(),
+                ),
+              ));
+            }
+
             if !found_peer {
               found_peer = !self.graph.borrow_node_mut(child_id).no_peers;
             }
@@ -1053,6 +1081,25 @@ impl<'a, TNpmRegistryApi: NpmRegistryApi>
               &parent_path,
             )?;
 
+            #[cfg(feature = "tracing")]
+            if let Some(child_id) = maybe_new_id {
+              self.graph.traces.push(build_trace_graph_snapshot(
+                self.graph,
+                &self.dep_entry_cache,
+                &parent_path.with_id(
+                  child_id,
+                  dep.bare_specifier.clone(),
+                  self
+                    .graph
+                    .resolved_node_ids
+                    .get(child_id)
+                    .unwrap()
+                    .nv
+                    .clone(),
+                ),
+              ));
+            }
+
             // For optional peer dependencies, we want to resolve them if any future
             // same parent version resolves them. So when not resolved, store them to be
             // potentially resolved later.
@@ -1477,6 +1524,71 @@ impl<'a, TNpmRegistryApi: NpmRegistryApi>
   }
 }
 
+#[cfg(feature = "tracing")]
+fn build_trace_graph_snapshot(
+  graph: &Graph,
+  dep_entry_cache: &DepEntryCache,
+  current_path: &GraphPath,
+) -> super::tracing::TraceGraphSnapshot {
+  use super::tracing::*;
+
+  fn build_path(current_path: &GraphPath) -> TraceGraphPath {
+    TraceGraphPath {
+      specifier: current_path.specifier.to_string(),
+      node_id: current_path.node_id().0,
+      nv: current_path.nv.to_string(),
+      previous: current_path.previous_node.as_ref().and_then(|n| match n {
+        GraphPathNodeOrRoot::Node(graph_path) => {
+          Some(Box::new(build_path(graph_path)))
+        }
+        GraphPathNodeOrRoot::Root(_) => None,
+      }),
+    }
+  }
+
+  TraceGraphSnapshot {
+    nodes: graph
+      .nodes
+      .iter()
+      .map(|(node_id, node)| {
+        let id = graph.get_npm_pkg_id(*node_id);
+        TraceNode {
+          id: node_id.0,
+          resolved_id: id.as_serialized().to_string(),
+          children: node
+            .children
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.0))
+            .collect(),
+          dependencies: dep_entry_cache
+            .get(&id.nv)
+            .map(|d| {
+              d.iter()
+                .map(|dep| TraceNodeDependency {
+                  kind: format!("{:?}", dep.kind),
+                  bare_specifier: dep.bare_specifier.to_string(),
+                  name: dep.name.to_string(),
+                  version_req: dep.version_req.to_string(),
+                  peer_dep_version_req: dep
+                    .peer_dep_version_req
+                    .as_ref()
+                    .map(|r| r.to_string()),
+                })
+                .collect()
+            })
+            .unwrap_or_default(),
+        }
+      })
+      .collect(),
+    roots: graph
+      .root_packages
+      .iter()
+      .map(|(nv, id)| (nv.to_string(), id.0))
+      .collect(),
+    path: build_path(current_path),
+  }
+}
+
 #[cfg(test)]
 mod test {
   use std::borrow::Cow;
@@ -2383,6 +2495,7 @@ mod test {
       ]
     );
   }
+
   #[tokio::test]
   async fn resolve_peer_dep_other_specifier_slot() {
     let api = TestNpmRegistryApi::default();

src/resolution/mod.rs

@@ -4,6 +4,8 @@ mod collections;
 mod common;
 mod graph;
 mod snapshot;
+#[cfg(feature = "tracing")]
+mod tracing;
 
 pub use common::NpmPackageVersionNotFound;
 pub use common::NpmPackageVersionResolutionError;

src/resolution/tracing/README.md

@@ -0,0 +1,19 @@
+# tracing
+
+This is a tool for debugging the npm resolution.
+
+To use it, compile with `--feature tracing`. For example:
+
+```sh
+cargo test grand_child_package_has_self_as_peer_dependency_root --features tracing -- --nocapture
+```
+
+This will output something like:
+
+```
+==============
+Trace output ready! Please open your browser to: file:///.../deno-npm-trace.html
+==============
+```
+
+Follow that and open your browser to see the output.

src/resolution/tracing/app.css

@@ -0,0 +1,56 @@
+html, body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+#container {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+}
+
+#slider {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px;
+  background: #f0f0f0;
+}
+
+#slider input[type="range"] {
+  flex: 1;
+  min-width: 0;
+}
+
+#stepText {
+  flex: 0;
+  white-space: nowrap;
+}
+
+#main {
+  display: flex;
+  flex: 1;
+  flex-direction: row;
+  height: 100vh;
+}
+
+#graph {
+  flex: 1;
+  overflow: hidden;
+}
+
+#info h3 {
+  padding-top: 0;
+  margin-top: 0;
+}
+
+#info {
+  padding: 20px;
+  background: #f0f0f0;
+  flex: 0 0 400px;
+  overflow-y: scroll;
+}