resolve-everything 0.1.0 → 0.1.2

package/.node-version

@@ -0,0 +1 @@
+v18.18.0

package/.npm-version

@@ -0,0 +1 @@
+9.8.1

package/README.md

@@ -45,17 +45,20 @@ which outputs JSON shaped like:
 
 - `--only-entrypoint` (boolean): if true, only the imports/requires in the entrypoint file will be resolved, and no other files will be walked over.
 
-- `--resolver` (path): module which exports a JS function that locates modules. Uses the same resolver format as [kame](https://github.com/suchipi/kame#config-hell).
+- `--sort` (boolean): if true, results will be sorted lexicographically. If you want results to be stable, you should enable this, as the order is non-deterministic otherwise (because we crawl the filesystem concurrently).
+
+- `--resolver` (path): module which exports a JS function that locates modules. Uses a resolver format compatible with [kame](https://github.com/suchipi/kame#config-hell), but with an added optional `async` property.
 
 - `--full-errors` (boolean): If reading, parsing, traversal, or resolution errors occur, print as much error information as possible.
 
 ### Node API
 
 ```ts
-import { walk } from "resolve-everything";
+import { walk, walkAsync } from "resolve-everything";
 
 const entrypoint = "/home/someone/some-file.js";
 const { errors, modules } = walk(entrypoint /* , options */);
+// or you could do: await walkAsync(entrypoint, /* options */);
 
 // modules is a Map<string, { id: string, requests: Map<string, string> }>
 ```
@@ -78,12 +81,24 @@ export type WalkOptions = {
    */
   onlyEntrypoint?: boolean;
 
+  /**
+   * If true, results will be sorted lexicographically. If you want results to
+   * be stable when using `walkSync`, you should enable this, as the order is
+   * non-deterministic otherwise (because we walk the filesystem concurrently).
+   */
+  sort?: boolean;
+
   /**
    * A function which translates the string-part of an import/require into the
    * absolute path to the file on disk, OR, if there is no file for that module
    * (ie. it's a node builtin), a string starting with "external:".
+   *
+   * The 'async' property is optional and will only be used by `walkAsync`.
+   * If not present, the normal synchronous resolver will be used.
    */
-  resolver?: (id: string, fromFilePath: string) => string;
+  resolver?: ((id: string, fromFilePath: string) => string) & {
+    async?: (id: string, fromFilePath: string) => Promise<string>;
+  };
 };
 ```
 

package/dist/cli.js

@@ -15,9 +15,10 @@ const _1 = require(".");
     skip: clefairy_1.optionalString,
     json: clefairy_1.optionalBoolean,
     onlyEntrypoint: clefairy_1.optionalBoolean,
+    sort: clefairy_1.optionalBoolean,
     help: clefairy_1.optionalBoolean,
     h: clefairy_1.optionalBoolean,
-}, async ({ entrypoint, resolver, fullErrors, skip, json, onlyEntrypoint, help, h, }) => {
+}, async ({ entrypoint, resolver, fullErrors, skip, json, onlyEntrypoint, sort, help, h, }) => {
     if (help || h) {
         const helpText = require("./help-text").default;
         console.log(helpText);
@@ -30,6 +31,7 @@ const _1 = require(".");
         throw new Error("No such file: " + entrypoint);
     }
     const walkOptions = {
+        sort,
         onError: (err) => {
             if (!fullErrors && /node_modules/.test(err.filename || "")) {
                 // Don't report resolution errors under node_modules dirs because
@@ -86,7 +88,7 @@ const _1 = require(".");
             throw new Error(`Resolver at ${JSON.stringify(resolver)} didn't export a 'resolve' function.`);
         }
     }
-    const result = (0, _1.walk)(entrypoint, walkOptions);
+    const result = await (0, _1.walkAsync)(entrypoint, walkOptions);
     let toPrint = (0, _1.serialize)(result.modules);
     if (onlyEntrypoint) {
         toPrint = toPrint[entrypoint];

package/dist/default-resolver.d.ts

@@ -1 +1,3 @@
-export declare function defaultResolver(id: string, fromFilePath: string): string;
+export declare const defaultResolver: ((id: string, fromFilePath: string) => string) & {
+    async: (id: string, fromFilePath: string) => Promise<string>;
+};

package/dist/default-resolver.js

@@ -6,16 +6,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultResolver = void 0;
 const node_module_1 = __importDefault(require("node:module"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = __importDefault(require("node:util"));
 const resolve_1 = __importDefault(require("resolve"));
 if (!Array.isArray(node_module_1.default.builtinModules)) {
     throw new Error("your node version seriously way too old bruh");
 }
 const allBuiltins = new Set(node_module_1.default.builtinModules);
-// This is (more or less) a direct copy-paste of kame's default resolver.
-// We copy-paste instead of depending on it directly, though, because kame has a LOT of deps and we just need this piece
+const resolveAsync = node_util_1.default.promisify(resolve_1.default);
+// This is (more or less) a direct copy-paste of kame's default resolver, with
+// async added.
 //
-// // https://github.com/suchipi/kame/blob/ae317caf325d5cbe4925fe30273159b6c04651a6/src/default-resolver.ts#L10
-function defaultResolver(id, fromFilePath) {
+// Part of why we copy-paste it instead of depending on it directly is because
+// kame has a LOT of deps and we just need this piece
+//
+// https://github.com/suchipi/kame/blob/ae317caf325d5cbe4925fe30273159b6c04651a6/src/default-resolver.ts#L10
+exports.defaultResolver = Object.assign(function defaultResolver(id, fromFilePath) {
     if (id.includes(":") && !id.startsWith("file:")) {
         return "external:" + id;
     }
@@ -40,5 +45,31 @@ function defaultResolver(id, fromFilePath) {
         return "external:" + result;
     }
     return result;
-}
-exports.defaultResolver = defaultResolver;
+}, {
+    async: async function defaultResolverAsync(id, fromFilePath) {
+        if (id.includes(":") && !id.startsWith("file:")) {
+            return "external:" + id;
+        }
+        if (allBuiltins.has(id.split("/")[0])) {
+            return "external:" + id;
+        }
+        const result = await resolveAsync(id, {
+            basedir: node_path_1.default.dirname(fromFilePath),
+            preserveSymlinks: false,
+            extensions: [
+                ".js",
+                ".json",
+                ".mjs",
+                ".jsx",
+                ".ts",
+                ".tsx",
+                ".node",
+                ".wasm",
+            ],
+        });
+        if (result.endsWith(".node") || result.endsWith(".wasm")) {
+            return "external:" + result;
+        }
+        return result;
+    },
+});

package/dist/help-text.js

@@ -60,11 +60,23 @@ ${opt("--only-entrypoint")} (boolean):
   If true, only the imports/requires in the entrypoint file will be resolved,
   and no other files will be walked over.
 
+
+${opt("--sort")} (boolean):
+  If true, results will be sorted lexicographically. If you want results to be
+  stable, you should enable this, as the order is non-deterministic otherwise
+  (because we crawl the filesystem concurrently).
+
 ${opt("--resolver")} (path):
-  Module which exports a JS function that locates modules. Uses the same
-  resolver format as https://github.com/suchipi/kame, namely:
+  Module which exports a JS function that locates modules. Uses a resolver
+  format compatible with https://github.com/suchipi/kame, namely:
+
+  export const resolve: {
+    (id: string, fromFilePath: string): string;
+    async?: (id: string, fromFilePath: string) => Promise<string>;
+  }
 
-  export function resolve(id: string, fromFilePath: string): string;
+  The 'async' property is optional; if not present, the normal synchronous
+  resolver will be used.
 
 ${opt("--full-errors")} (boolean):
   If reading, parsing, traversal, or resolution errors occur, print as much

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { walk, type WalkOptions } from "./walk";
+export { walk, walkAsync, type WalkOptions } from "./walk";
 export type { ErrorReport as ReportedError, ResolverFunction } from "./types";
 export { defaultResolver } from "./default-resolver";
 export { Walker, type WalkerOptions } from "./walker";

package/dist/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serialize = exports.Module = exports.Walker = exports.defaultResolver = exports.walk = void 0;
+exports.serialize = exports.Module = exports.Walker = exports.defaultResolver = exports.walkAsync = exports.walk = void 0;
 var walk_1 = require("./walk");
 Object.defineProperty(exports, "walk", { enumerable: true, get: function () { return walk_1.walk; } });
+Object.defineProperty(exports, "walkAsync", { enumerable: true, get: function () { return walk_1.walkAsync; } });
 var default_resolver_1 = require("./default-resolver");
 Object.defineProperty(exports, "defaultResolver", { enumerable: true, get: function () { return default_resolver_1.defaultResolver; } });
 var walker_1 = require("./walker");

package/dist/module.d.ts

@@ -5,7 +5,10 @@ export declare class Module {
     requests: Map<string, string>;
     constructor(id: string);
     read(): string | null;
+    readAsync(): Promise<string | null>;
     parse(code: string): ee.types.File;
     getRequests(ast: ee.types.File): Array<string>;
     resolve(request: string, resolver: ResolverFunction): string;
+    resolveAsync(request: string, resolver: ResolverFunction): Promise<string>;
+    get dependencies(): Set<string>;
 }

package/dist/module.js

@@ -51,6 +51,18 @@ class Module {
         debug_logger_1.debugLogger.returns("Module.read ->", code);
         return code;
     }
+    async readAsync() {
+        debug_logger_1.debugLogger.summary("Module.readAsync", this.id);
+        if (!/\.[cm]?[tj]sx?$/.test(this.id)) {
+            debug_logger_1.debugLogger.summary("doesn't appear to be js/ts:", this.id);
+            debug_logger_1.debugLogger.returns("Module.readAsync -> null");
+            return null;
+        }
+        const code = await fs.promises.readFile(this.id, "utf-8");
+        debug_logger_1.debugLogger.fileContent(code);
+        debug_logger_1.debugLogger.returns("Module.readAsync ->", code);
+        return code;
+    }
     parse(code) {
         debug_logger_1.debugLogger.summary("Module.parse", this.id);
         debug_logger_1.debugLogger.args("Module.parse", code);
@@ -122,5 +134,23 @@ class Module {
         debug_logger_1.debugLogger.returns("Module.resolve ->", resolved);
         return resolved;
     }
+    async resolveAsync(request, resolver) {
+        debug_logger_1.debugLogger.summary("Module.resolveAsync", this.id, request);
+        debug_logger_1.debugLogger.args("Module.resolveAsync", request, resolver);
+        let resolved;
+        if (resolver.async == null) {
+            debug_logger_1.debugLogger.summary("Module.resolveAsync falling back to sync as user-provided resolver doesn't have an 'async' property");
+            resolved = resolver(request, this.id);
+        }
+        else {
+            resolved = await resolver.async(request, this.id);
+        }
+        this.requests.set(request, resolved);
+        debug_logger_1.debugLogger.returns("Module.resolveAsync ->", resolved);
+        return resolved;
+    }
+    get dependencies() {
+        return new Set(this.requests.values());
+    }
 }
 exports.Module = Module;

package/dist/types.d.ts

@@ -4,4 +4,7 @@ export type ErrorReport = {
     stage: "read" | "parse" | "getRequests" | "resolve";
     error: Error;
 };
-export type ResolverFunction = (id: string, fromFilePath: string) => string;
+export type ResolverFunction = {
+    (id: string, fromFilePath: string): string;
+    async?(id: string, fromFilePath: string): Promise<string>;
+};

package/dist/walk.d.ts

@@ -1,12 +1,40 @@
 import type { Module } from "./module";
 import type { ErrorReport, ResolverFunction } from "./types";
 export type WalkOptions = {
+    /**
+     * A function to call whenever an error occurs.
+     */
     onError?: (error: ErrorReport) => void;
+    /**
+     * A function which translates the string-part of an import/require into the
+     * absolute path to the file on disk, OR, if there is no file for that module
+     * (ie. it's a node builtin), a string starting with "external:".
+     */
     resolver?: ResolverFunction;
+    /**
+     * Which files not to parse and find requires/imports in.
+     *
+     * Defaults to `/node_modules/`.
+     * Specify `null` to include node_modules.
+     */
     skip?: RegExp | null;
+    /**
+     * If true, only the imports/requires in the entrypoint file will be
+     * resolved, and no other files will be walked over.
+     */
     onlyEntrypoint?: boolean;
+    /**
+     * If true, results will be sorted lexicographically. If you want results to
+     * be stable when using `walkSync`, you should enable this, as the order is
+     * non-deterministic otherwise (because we walk the filesystem concurrently).
+     */
+    sort?: boolean;
 };
 export declare function walk(entrypoint: string, options?: WalkOptions): {
     errors: ErrorReport[];
     modules: Map<string, Module>;
 };
+export declare function walkAsync(entrypoint: string, options?: WalkOptions): Promise<{
+    errors: ErrorReport[];
+    modules: Map<string, Module>;
+}>;

package/dist/walk.js

@@ -23,14 +23,12 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.walk = void 0;
+exports.walkAsync = exports.walk = void 0;
 const path = __importStar(require("node:path"));
 const walker_1 = require("./walker");
 const debug_logger_1 = require("./debug-logger");
 const default_resolver_1 = require("./default-resolver");
-function walk(entrypoint, options) {
-    debug_logger_1.debugLogger.summary("walk", entrypoint);
-    debug_logger_1.debugLogger.args("walk", entrypoint, options);
+function makeWalker(entrypoint, options) {
     if (!path.isAbsolute(entrypoint)) {
         throw new Error(`entrypoint must be an absolute path. received: ${entrypoint}`);
     }
@@ -45,6 +43,15 @@ function walk(entrypoint, options) {
     if (options?.onError) {
         walker.on("error", options.onError);
     }
+    return walker;
+}
+function walk(entrypoint, options) {
+    debug_logger_1.debugLogger.summary("walk", entrypoint);
+    debug_logger_1.debugLogger.args("walk", entrypoint, options);
+    const walker = makeWalker(entrypoint, options);
+    if (options?.sort) {
+        walker.sort();
+    }
     const { errors } = walker.walk();
     const modules = walker.modules;
     const ret = {
@@ -55,3 +62,20 @@ function walk(entrypoint, options) {
     return ret;
 }
 exports.walk = walk;
+async function walkAsync(entrypoint, options) {
+    debug_logger_1.debugLogger.summary("walkAsync", entrypoint);
+    debug_logger_1.debugLogger.args("walkAsync", entrypoint, options);
+    const walker = makeWalker(entrypoint, options);
+    const { errors } = await walker.walkAsync();
+    if (options?.sort) {
+        walker.sort();
+    }
+    const modules = walker.modules;
+    const ret = {
+        errors,
+        modules,
+    };
+    debug_logger_1.debugLogger.returns("walkAsync ->", ret);
+    return ret;
+}
+exports.walkAsync = walkAsync;

package/dist/walker.d.ts

@@ -15,4 +15,8 @@ export declare class Walker extends EventEmitter {
     walk(): {
         errors: Array<ErrorReport>;
     };
+    walkAsync(): Promise<{
+        errors: Array<ErrorReport>;
+    }>;
+    sort(): void;
 }

package/dist/walker.js

@@ -26,6 +26,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Walker = void 0;
 const path = __importStar(require("node:path"));
 const node_events_1 = require("node:events");
+const parallel_park_1 = require("parallel-park");
 const module_1 = require("./module");
 const debug_logger_1 = require("./debug-logger");
 class Walker extends node_events_1.EventEmitter {
@@ -44,12 +45,10 @@ class Walker extends node_events_1.EventEmitter {
         let filename;
         const errors = [];
         let errorStage = "read";
-        let errorRequest = undefined;
-        const reportError = (error) => {
+        const reportError = (error, request) => {
             const report = {
                 filename,
                 stage: errorStage,
-                request: errorRequest,
                 error,
             };
             debug_logger_1.debugLogger.summary("error reported:", report);
@@ -76,9 +75,7 @@ class Walker extends node_events_1.EventEmitter {
                 errorStage = "getRequests";
                 const requests = mod.getRequests(ast);
                 errorStage = "resolve";
-                errorRequest = undefined;
                 for (const request of requests) {
-                    errorRequest = request;
                     try {
                         const target = mod.resolve(request, this._options.resolver);
                         if (target.startsWith("external:")) {
@@ -94,10 +91,9 @@ class Walker extends node_events_1.EventEmitter {
                         }
                     }
                     catch (error) {
-                        reportError(error);
+                        reportError(error, request);
                     }
                 }
-                errorRequest = undefined;
             }
             catch (error) {
                 reportError(error);
@@ -110,5 +106,90 @@ class Walker extends node_events_1.EventEmitter {
         debug_logger_1.debugLogger.returns("Walker.walk ->", ret);
         return ret;
     }
+    async walkAsync() {
+        debug_logger_1.debugLogger.summary("Walker.walkAsync");
+        const filesToProcess = [this.entrypoint];
+        let filename;
+        const errors = [];
+        let errorStage = "read";
+        const reportError = (error, request) => {
+            const report = {
+                filename,
+                stage: errorStage,
+                request,
+                error,
+            };
+            debug_logger_1.debugLogger.summary("error reported:", report);
+            this.emit("error", report);
+            errors.push(report);
+        };
+        while ((filename = filesToProcess.shift())) {
+            debug_logger_1.debugLogger.summary("Walker.walkAsync -> processing", filename);
+            this.emit("processing", filename);
+            if (this.modules.has(filename)) {
+                // already processed
+                continue;
+            }
+            const mod = new module_1.Module(filename);
+            this.modules.set(filename, mod);
+            try {
+                const code = await mod.readAsync();
+                if (code == null) {
+                    // not a js/ts file
+                    continue;
+                }
+                errorStage = "parse";
+                const ast = mod.parse(code);
+                errorStage = "getRequests";
+                const requests = mod.getRequests(ast);
+                errorStage = "resolve";
+                await (0, parallel_park_1.runJobs)(requests, async (request) => {
+                    try {
+                        const target = await mod.resolveAsync(request, this._options.resolver);
+                        if (target.startsWith("external:")) {
+                            return;
+                        }
+                        if (this._options.skip != null && this._options.skip.test(target)) {
+                            return;
+                        }
+                        if (!this.modules.has(target)) {
+                            debug_logger_1.debugLogger.summary("Walker.walkAsync -> queueing", target);
+                            this.emit("queueing", target);
+                            filesToProcess.push(target);
+                        }
+                    }
+                    catch (error) {
+                        reportError(error, request);
+                    }
+                });
+            }
+            catch (error) {
+                reportError(error);
+            }
+            if (this._options.onlyEntrypoint) {
+                break;
+            }
+        }
+        const ret = { errors };
+        debug_logger_1.debugLogger.returns("Walker.walkAsync ->", ret);
+        return ret;
+    }
+    sort() {
+        const newModules = new Map();
+        const keys = Array.from(this.modules.keys());
+        keys.sort();
+        for (const key of keys) {
+            const mod = this.modules.get(key);
+            const newRequests = new Map();
+            const reqKeys = Array.from(mod.requests.keys());
+            reqKeys.sort();
+            for (const reqKey of reqKeys) {
+                newRequests.set(reqKey, mod.requests.get(reqKey));
+            }
+            mod.requests = newRequests;
+            newModules.set(key, mod);
+        }
+        this.modules = newModules;
+    }
 }
 exports.Walker = Walker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resolve-everything",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "walk your project's import/require tree and print all the relationships",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,12 +12,20 @@
     "test": "vitest",
     "cli": "bun src/cli.ts"
   },
-  "keywords": [],
+  "keywords": [
+    "import",
+    "module",
+    "graph",
+    "tree",
+    "require",
+    "relation"
+  ],
   "author": "Lily Skye <me@suchipi.com>",
   "license": "MIT",
   "devDependencies": {
     "@types/debug": "^4.1.10",
     "@types/resolve": "^1.20.4",
+    "first-base": "^1.3.0",
     "path-less-traveled": "^2.0.0",
     "prettier": "^3.0.3",
     "typescript": "^5.2.2",
@@ -28,8 +36,8 @@
     "clefairy": "^0.4.0",
     "debug": "^4.3.4",
     "equivalent-exchange": "^1.10.0",
-    "first-base": "^1.3.0",
     "kleur": "^4.1.5",
+    "parallel-park": "^0.2.0",
     "pretty-print-ast": "^1.0.1",
     "resolve": "^1.22.8"
   },