Add comments

api/api-npm/imports.d.ts

@@ -2,8 +2,19 @@ import Arborist from "@npmcli/arborist";
 
 import type { Imports } from "./index.d.ts";
 
+/**
+ * Gather imports for aqua compiler from
+ * actual node_modules folder created by npm.
+ * Underneath it uses @npmcli/arborist.
+ * @param path path to project with node_modules folder
+ */
 export declare async function gatherImportsFromNpm(path: string): Imports;
 
+/**
+ * Same as `gatherImportsFromNpm` but uses
+ * already created arborist instance.
+ * @param arborist arborist instance
+ */
 export declare async function gatherImportsFromArborist(
   arborist: Arborist,
 ): Imports;

api/api-npm/imports.js

@@ -12,24 +12,34 @@ export async function gatherImportsFromNpm(path) {
 export async function gatherImportsFromArborist(arborist) {
   const tree = await arborist.loadActual();
 
+  /**
+   * Traverse dependency tree to construct map
+   * (real path of a package) -> (real paths of its immediate dependencies)
+   */
   let result = new Map();
   breadth({
     tree,
     getChildren(node, _) {
       let deps = [];
       for (let edge of node.edgesOut.values()) {
+        // Skip dependencies that are not installed.
         if (edge.to === null) continue;
+        // NOTE: Any errors in edge are ignored.
         const dep = edge.to;
 
+        // Gather dependencies to traverse them.
         deps.push(dep);
+        // Gather dependencies real paths.
         result.set(node.realpath, [
           ...(result.get(node.realpath) || []),
           dep.realpath,
         ]);
       }
+
       return deps;
     },
   });
 
+  // Convert map to object.
   return Object.fromEntries(result);
 }