@oazmi/superbuild 0.1.0

package/esm/funcdefs.d.ts

@@ -0,0 +1,89 @@
+/** a utility functions submodule.
+ *
+ * @module
+*/
+import type { EsbuildEntryPointsType } from "./esbuild/typedefs.js";
+import type { LoggerFunction } from "./typedefs.js";
+export declare const concatArrays: <T>(arr1?: Array<T>, arr2?: Array<T>) => Array<T> | undefined;
+export declare const mergeMapArrays: <K, T>(map1: Map<K, Array<T>>, map2: Map<K, Array<T>>) => Map<K, Array<T>>;
+/** this function wraps on top of a promise-resolver function, and returns two functions.
+ * the first function, when called, will resolve the original `promise_resolver` _after_ the specified `delay` amount of milliseconds have passed.
+ * during this delay time, you may use the second function that is returned to cancel the task of running the `promise_resolver` before it times out.
+ * you also have the option to specify the `delay` for the next time the returned `resolve` function is called.
+ * if it is not specified, then the `original_delay` will be used in its place.
+*/
+export declare const cancelableDelayedPromiseResolver: <T>(promise_resolver: (value: T) => void, original_delay: number, logger?: LoggerFunction) => [resolve: (value: T) => void, cancel: (delay?: number) => void];
+/** generates `segments` number of 8-character (32-bit) uuid based on the current time stamp. */
+export declare const generateUuid: (segments?: number, current_time?: number) => string;
+export declare const splitNamespacedPath: (resolved_namespaced_path: string) => {
+    namespace: string;
+    path: string;
+};
+/** alias for `console.log`. this is the default logging function. */
+export declare const logLogger: LoggerFunction;
+/** the history of the {@link arrayLogger} function gets contained here. */
+export declare const arrayLoggerHistory: Array<any[]>;
+/** an array based logging function. the log history is kept in the {@link arrayLoggerHistory} array. */
+export declare const arrayLogger: LoggerFunction;
+/** a no operation logger function that does nothing. */
+export declare const noopLogger: LoggerFunction;
+/** this function accepts various forms of entry-points that are accepted by esbuild, and transforms them into an array of 2-tuples.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * // aliasing our functions for brevity
+ * const
+ * 	fn = entryPointsToImportMapEntries,
+ * 	eq = assertEquals
+ *
+ * eq(fn(["input-a", "input-b", "input-c"]), [
+ * 	["input-a", "input-a"],
+ * 	["input-b", "input-b"],
+ * 	["input-c", "input-c"],
+ * ])
+ *
+ * eq(fn({
+ * 	"input-a": "output-a",
+ * 	"input-b": "output-b",
+ * 	"input-c": "output-c",
+ * }), [
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ *
+ * eq(fn([
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ]), [
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ *
+ * eq(fn([
+ * 	{ in: "input-a", out: "output-a" },
+ * 	{ in: "input-b", out: "output-b" },
+ * 	{ in: "input-c", out: "output-c" },
+ * ]), [
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ *
+ * eq(fn([
+ * 	"input-a",
+ * 	["input-b", "output-b"],
+ * 	{ in: "input-c", out: "output-c" },
+ * ]), [
+ * 	["input-a", "input-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ * ```
+*/
+export declare const entryPointsToImportMapEntries: (entry_points: EsbuildEntryPointsType) => Array<[input: string, output: string]>;
+//# sourceMappingURL=funcdefs.d.ts.map

package/esm/funcdefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"funcdefs.d.ts","sourceRoot":"","sources":["../src/funcdefs.ts"],"names":[],"mappings":"AAAA;;;EAGE;AAGF,OAAO,KAAK,EAAE,sBAAsB,EAAyB,MAAM,uBAAuB,CAAA;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGnD,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,CAAC,GAAG,SAK7E,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAG,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAQpG,CAAA;AAED;;;;;EAKE;AACF,eAAO,MAAM,gCAAgC,GAAI,CAAC,oBAC/B,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,kBACpB,MAAM,WACd,cAAc,KACpB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAkBhE,CAAA;AAID,gGAAgG;AAChG,eAAO,MAAM,YAAY,qCAAiC,MAAM,WAW/D,CAAA;AAED,eAAO,MAAM,mBAAmB,6BAA8B,MAAM,KAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAMvG,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,SAAS,EAAE,cAA4B,CAAA;AAOpD,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,GAAG,EAAE,CAAM,CAAA;AAElD,wGAAwG;AACxG,eAAO,MAAM,WAAW,EAAE,cAAqE,CAAA;AAE/F,wDAAwD;AACxD,eAAO,MAAM,UAAU,EAAE,cAAqB,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDE;AACF,eAAO,MAAM,6BAA6B,iBAAkB,sBAAsB,KAAG,KAAK,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAQzH,CAAA"}

package/esm/funcdefs.js

@@ -0,0 +1,145 @@
+/** a utility functions submodule.
+ *
+ * @module
+*/
+import { bind_array_push, console_log, crc32, date_now, DEBUG, dom_clearTimeout, dom_setTimeout, isArray, isString, math_max, noop, object_entries } from "./deps.js";
+export const concatArrays = (arr1, arr2) => {
+    return (!arr1 && !arr2) ? undefined
+        : !arr1 ? arr2
+            : !arr2 ? arr1
+                : [...arr1, ...arr2];
+};
+export const mergeMapArrays = (map1, map2) => {
+    const result = new Map(map1);
+    for (const [key, arr] of map2) {
+        const existing_arr = result.get(key);
+        if (existing_arr === undefined) {
+            result.set(key, arr);
+        }
+        else {
+            result.set(key, existing_arr.concat(arr));
+        }
+    }
+    return result;
+};
+/** this function wraps on top of a promise-resolver function, and returns two functions.
+ * the first function, when called, will resolve the original `promise_resolver` _after_ the specified `delay` amount of milliseconds have passed.
+ * during this delay time, you may use the second function that is returned to cancel the task of running the `promise_resolver` before it times out.
+ * you also have the option to specify the `delay` for the next time the returned `resolve` function is called.
+ * if it is not specified, then the `original_delay` will be used in its place.
+*/
+export const cancelableDelayedPromiseResolver = (promise_resolver, original_delay, logger = noopLogger) => {
+    let 
+    // bloody deno's node-compatibility "enhancements" is creating more incompatibilities with existing well known web-compatible constructs.
+    // man, do I hate the direction deno is heading. this didn't use to be an issue pre-v2.8 of deno.
+    timer_id = -1, delay = original_delay;
+    const resolve = (value) => {
+        dom_clearTimeout(timer_id); // clear out any previous timer.
+        if (DEBUG.LOG) {
+            logger(`delayed promise will resolve in ${delay}ms.`);
+        }
+        timer_id = dom_setTimeout(promise_resolver, delay, value);
+    }, cancel = (new_delay = original_delay) => {
+        dom_clearTimeout(timer_id); // clear out any previous timer.
+        if (DEBUG.LOG) {
+            logger(`delayed promise was canceled.`);
+        }
+        delay = new_delay;
+    };
+    return [resolve, cancel];
+};
+let uuid_counter = -1;
+/** generates `segments` number of 8-character (32-bit) uuid based on the current time stamp. */
+export const generateUuid = (segments = 1, current_time) => {
+    current_time ??= date_now();
+    uuid_counter++;
+    const crc32_segments = Array(math_max(segments, 0)).fill(current_time).map((time, i) => {
+        const seed = uuid_counter + time + i, seed_arr = new Uint8Array((new Uint32Array([seed])).buffer), uuid_segment = crc32(seed_arr);
+        return uuid_segment.toString(16).padStart(8, "0");
+    });
+    return crc32_segments.join("-");
+};
+export const splitNamespacedPath = (resolved_namespaced_path) => {
+    const namespace_splitting_idx = resolved_namespaced_path.indexOf(":"), namespace = resolved_namespaced_path.slice(0, namespace_splitting_idx), path = resolved_namespaced_path.slice(namespace_splitting_idx + 1);
+    return { namespace, path };
+};
+/** alias for `console.log`. this is the default logging function. */
+export const logLogger = console_log;
+const arrayLoggerFactory = (history) => {
+    const history_push = bind_array_push(history);
+    return (...data) => { history_push(data); };
+};
+/** the history of the {@link arrayLogger} function gets contained here. */
+export const arrayLoggerHistory = [];
+/** an array based logging function. the log history is kept in the {@link arrayLoggerHistory} array. */
+export const arrayLogger = /*@__PURE__*/ arrayLoggerFactory(arrayLoggerHistory);
+/** a no operation logger function that does nothing. */
+export const noopLogger = noop;
+/** this function accepts various forms of entry-points that are accepted by esbuild, and transforms them into an array of 2-tuples.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * // aliasing our functions for brevity
+ * const
+ * 	fn = entryPointsToImportMapEntries,
+ * 	eq = assertEquals
+ *
+ * eq(fn(["input-a", "input-b", "input-c"]), [
+ * 	["input-a", "input-a"],
+ * 	["input-b", "input-b"],
+ * 	["input-c", "input-c"],
+ * ])
+ *
+ * eq(fn({
+ * 	"input-a": "output-a",
+ * 	"input-b": "output-b",
+ * 	"input-c": "output-c",
+ * }), [
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ *
+ * eq(fn([
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ]), [
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ *
+ * eq(fn([
+ * 	{ in: "input-a", out: "output-a" },
+ * 	{ in: "input-b", out: "output-b" },
+ * 	{ in: "input-c", out: "output-c" },
+ * ]), [
+ * 	["input-a", "output-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ *
+ * eq(fn([
+ * 	"input-a",
+ * 	["input-b", "output-b"],
+ * 	{ in: "input-c", out: "output-c" },
+ * ]), [
+ * 	["input-a", "input-a"],
+ * 	["input-b", "output-b"],
+ * 	["input-c", "output-c"],
+ * ])
+ * ```
+*/
+export const entryPointsToImportMapEntries = (entry_points) => {
+    if (!isArray(entry_points)) {
+        entry_points = object_entries(entry_points);
+    }
+    return entry_points.map((entry) => {
+        return isString(entry) ? ([entry, entry])
+            : !isArray(entry) ? ([entry.in, entry.out])
+                : (entry);
+    });
+};

package/esm/mod.d.ts

@@ -0,0 +1,4 @@
+/** exports a wrapper on top of esbuild to provide you with extended esbuild plugin-api capabilities (hence a super set of esbuild). */
+export type * from "./super/mod.js";
+export { INNER_PLUGIN_BUILD, SuperBuild, SuperBuildContext, SuperPluginBuild } from "./super/mod.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,uIAAuI;AAEvI,mBAAmB,gBAAgB,CAAA;AACnC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}

package/esm/mod.js

@@ -0,0 +1,2 @@
+/** exports a wrapper on top of esbuild to provide you with extended esbuild plugin-api capabilities (hence a super set of esbuild). */
+export { INNER_PLUGIN_BUILD, SuperBuild, SuperBuildContext, SuperPluginBuild } from "./super/mod.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/plugins/emissions_driver.d.ts

@@ -0,0 +1,33 @@
+/** an internal super-build plugin that drives and governs the {@link SuperPluginBuild.onEmit} and {@link SuperPluginBuild.onEnd} hooks,
+ * in order to make it possible for other plugins to modify the final output files (after their transformation and bundling)
+ * before they get emitted into the file system.
+ *
+ * this plugin should generally go in second place, after the long-build plugin, and before all other user plugins.
+ *
+ * @module
+*/
+import type { EsbuildPlugin, EsbuildPluginSetup } from "../esbuild/strongtypes.js";
+import type { SuperBuildContext } from "../super/build_context.js";
+export interface EmissionsDriverPluginSetupConfig {
+    ctx: SuperBuildContext;
+}
+/** this plugin drives all {@link SuperPluginBuild.onEmit} and {@link SuperPluginBuild.onEnd} hooks,
+ * in order to make it possible for other plugins to modify the final output files (after their transformation and bundling).
+ *
+ * > [!note]
+ * > this plugin should generally go in second place, after the long-build plugin, and before all other user plugins.
+ *
+ * > Hello Maddam Siiir, you're vehicle has failed its emissions inspection.
+ * > you must subscribe to UK's £19/day _unclean vehicle_ program in order to use your vehicle,
+ * > so that we can offset your unclean carbon emissions and keep our planet clean. thank you for understanding.
+ * >
+ * > _meanwhile, at the hall of jeffery, circa 2013_
+ * >
+ * > _Larry McOracle_: jeffery, my second best friend, how many data centers did our supreme minister say he would like on 300 acre patches of american soil?
+ * >
+ * > _Jeffy McEpstien_: he says yes. and also get peter griffin, I mean thiel, onboard for a new mass surveillance initiative.
+*/
+export declare const emissionsDriverPluginSetup: (config: EmissionsDriverPluginSetupConfig) => EsbuildPluginSetup;
+/** {@inheritDoc emissionsDriverPluginSetup} */
+export declare const emissionsDriverPlugin: (config: EmissionsDriverPluginSetupConfig) => EsbuildPlugin;
+//# sourceMappingURL=emissions_driver.d.ts.map

package/esm/plugins/emissions_driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emissions_driver.d.ts","sourceRoot":"","sources":["../../src/plugins/emissions_driver.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AAKF,OAAO,KAAK,EAAoF,aAAa,EAAsB,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAExL,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAOlE,MAAM,WAAW,gCAAgC;IAChD,GAAG,EAAE,iBAAiB,CAAA;CACtB;AAED;;;;;;;;;;;;;;;EAeE;AACF,eAAO,MAAM,0BAA0B,WAAY,gCAAgC,KAAG,kBAoGrF,CAAA;AAED,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,WAAY,gCAAgC,KAAG,aAKhF,CAAA"}

package/esm/plugins/emissions_driver.js

@@ -0,0 +1,260 @@
+/** an internal super-build plugin that drives and governs the {@link SuperPluginBuild.onEmit} and {@link SuperPluginBuild.onEnd} hooks,
+ * in order to make it possible for other plugins to modify the final output files (after their transformation and bundling)
+ * before they get emitted into the file system.
+ *
+ * this plugin should generally go in second place, after the long-build plugin, and before all other user plugins.
+ *
+ * @module
+*/
+import { array_isEmpty, ensureEndSlash, fileUrlToLocalPath, getRuntimeCwd, identifyCurrentRuntime, isArray, isNull, pathToPosixPath, promise_all, promiseOutside, resolveAsUrl, resolvePathFactory, textDecoder } from "../deps.js";
+import { concatArrays } from "../funcdefs.js";
+import { INNER_PLUGIN_BUILD } from "../super/typedefs.js";
+/** this plugin drives all {@link SuperPluginBuild.onEmit} and {@link SuperPluginBuild.onEnd} hooks,
+ * in order to make it possible for other plugins to modify the final output files (after their transformation and bundling).
+ *
+ * > [!note]
+ * > this plugin should generally go in second place, after the long-build plugin, and before all other user plugins.
+ *
+ * > Hello Maddam Siiir, you're vehicle has failed its emissions inspection.
+ * > you must subscribe to UK's £19/day _unclean vehicle_ program in order to use your vehicle,
+ * > so that we can offset your unclean carbon emissions and keep our planet clean. thank you for understanding.
+ * >
+ * > _meanwhile, at the hall of jeffery, circa 2013_
+ * >
+ * > _Larry McOracle_: jeffery, my second best friend, how many data centers did our supreme minister say he would like on 300 acre patches of american soil?
+ * >
+ * > _Jeffy McEpstien_: he says yes. and also get peter griffin, I mean thiel, onboard for a new mass surveillance initiative.
+*/
+export const emissionsDriverPluginSetup = (config) => {
+    const ctx = config.ctx;
+    return (build) => {
+        const abs_working_dir = pathToPosixPath(build.initialOptions.absWorkingDir ?? "./"), runtime_cwd = ensureEndSlash(getRuntimeCwd(identifyCurrentRuntime())), cwd = fileUrlToLocalPath(resolveAsUrl(abs_working_dir, runtime_cwd)), resolve_path = resolvePathFactory(cwd), base_plugin_build = INNER_PLUGIN_BUILD in build
+            ? build[INNER_PLUGIN_BUILD]
+            : build;
+        const longBuildController = ctx.longBuildController, onEmitHandlers = ctx.onEmitHandlers, onEndHandlers = ctx.onEndHandlers;
+        // handles all registered `onEmit` hooks.
+        const performOnEmit = async (metafile) => {
+            const ctx = {
+                longBuildController,
+                metafile,
+                resolvePath: resolve_path,
+                warnings: metafile.warnings,
+                errors: [],
+            };
+            const longbuild_file = findLongBuildFile(ctx);
+            if (isNull(longbuild_file)) {
+                return { warnings: ctx.warnings, errors: ctx.errors };
+            }
+            await incorporateLongBuildImportedEntities(ctx, longbuild_file);
+            const files_dependency_graph = metafile.createFileDependencyGraph(), dependency_graph = DependencyGraphNode.fromGraph(files_dependency_graph), source_resource_nodes = DependencyGraphNode.chainNodePromises(dependency_graph), all_node_promises = Promise.all([...dependency_graph.values()].map((node) => (node.promise))), on_emit_callback = async (node, dependency_results) => {
+                const entity = node.key, on_emit_result = await entity.performOnEmit(onEmitHandlers);
+                // if any error is encountered in the user's `onEmit` hook function's return value,
+                // exit the build early by rejecting the promise, and cancelling everything downstream.
+                if ((on_emit_result?.errors?.length ?? 0) > 0) {
+                    node.reject(on_emit_result.errors);
+                }
+                return on_emit_result;
+            };
+            dependency_graph.forEach((node) => { node.setCallback(on_emit_callback); });
+            source_resource_nodes.forEach((node) => { node.fire(); });
+            // waiting for all of the `onEmit` hooks to take action, and then accumulate all warnings and errors.
+            await all_node_promises
+                .then((all_on_emit_results) => {
+                for (const on_emit_result of all_on_emit_results) {
+                    if (on_emit_result?.warnings) {
+                        ctx.warnings.push(...on_emit_result.warnings);
+                    }
+                    // there shouldn't be any errors by this point. but I'll just put this case, just in case.
+                    if (on_emit_result?.errors) {
+                        ctx.errors.push(...on_emit_result.errors);
+                    }
+                }
+            }).catch((errors) => {
+                if (isArray(errors)) {
+                    ctx.errors.push(...errors);
+                }
+                else {
+                    ctx.errors.push(errors);
+                }
+            });
+            return { warnings: ctx.warnings, errors: ctx.errors };
+        };
+        // handle all registered `onEnd` hooks.
+        const performOnEnd = async (result) => {
+            const on_end_promises = onEndHandlers.map(async (handler) => {
+                const { pluginName, callback } = handler, on_end_result = await callback(result);
+                // inserting the original plugin names of the plugins where the errors and warnings originated from.
+                on_end_result?.warnings?.forEach((warning) => { if (!warning.pluginName) {
+                    warning.pluginName = pluginName;
+                } });
+                on_end_result?.errors?.forEach((error) => { if (!error.pluginName) {
+                    error.pluginName = pluginName;
+                } });
+                return on_end_result;
+            });
+            const warnings = [], errors = [];
+            for (const value of await promise_all(on_end_promises)) {
+                if (value?.warnings) {
+                    warnings.push(...value.warnings);
+                }
+                if (value?.errors) {
+                    errors.push(...value.errors);
+                }
+            }
+            return { warnings, errors };
+        };
+        base_plugin_build.onEnd(async (result) => {
+            const metafile = ctx.createMetafile(result, { resolvePath: resolve_path }), on_emit_results = await performOnEmit(metafile), on_end_results = await performOnEnd(result), warnings = concatArrays(on_emit_results?.warnings, on_end_results?.warnings), errors = concatArrays(on_emit_results?.errors, on_end_results?.errors);
+            // end this build by informing the build context via its `endBuild` method.
+            await ctx.endBuild(metafile);
+            return { warnings, errors };
+        });
+    };
+};
+/** {@inheritDoc emissionsDriverPluginSetup} */
+export const emissionsDriverPlugin = (config) => {
+    return {
+        name: "oazmi-superbuild-emissions_driver-plugin",
+        setup: emissionsDriverPluginSetup(config),
+    };
+};
+/** searches for the long-build file (that originates from the {@link longBuildPlugin}) in the list of bundled output files generated by esbuild. */
+const findLongBuildFile = (ctx) => {
+    const { longBuildController, metafile, errors } = ctx;
+    const longbuild_plugin_namespace = longBuildController.pluginNamespace, longbuild_files = metafile.findFileFromSources((input_sources) => {
+        const does_include_longbuild_source_file = input_sources.some(({ path: _source_resolved_path, namespace }) => {
+            return namespace === longbuild_plugin_namespace;
+        });
+        return does_include_longbuild_source_file;
+    });
+    if (longbuild_files.length !== 1) {
+        errors.push({ text: `[findLongBuildFile]: expected there to be only a single long-build file after bundling, instead found: ${longbuild_files.length} files.` });
+        return;
+    }
+    const longbuild_file = longbuild_files[0];
+    return longbuild_file;
+};
+/** parses the long-build plugin's output js file to discover additional user-made imports (specified during the transformation stage),
+ * and then adds them to their respective importer's {@link OutputFileEntity}.
+*/
+const incorporateLongBuildImportedEntities = async (ctx, longbuild_file) => {
+    const { longBuildController, metafile, resolvePath, warnings, } = ctx;
+    const longbuild_path = longbuild_file.initialPath ?? longbuild_file.outputPath, longbuild_contents = textDecoder.decode(longbuild_file.contents), import_entities = await longBuildController.parseLongBuildFileContent(longbuild_contents);
+    for (let [importer_resolved_path, entities_to_import] of import_entities) {
+        // `entities_to_import` are the runtime-based imports in the output file made by the user (i.e. plugins) during the transformation stage.
+        // our goal below is to first identify which output file entity(ies) originate from the `importer_resolved_path` source file,
+        // and then we shall inject the new (user made) imports into it/them (if there were multiple files using the same importer as their source file).
+        importer_resolved_path = importer_resolved_path.toLowerCase();
+        const entities_using_importer_as_input_source = metafile.findFileFromSources((input_sources) => {
+            const entity_uses_importer_as_source = input_sources.some(({ path, namespace }) => {
+                return (namespace + ":" + path).toLowerCase() === importer_resolved_path;
+            });
+            return entity_uses_importer_as_source;
+        });
+        if (array_isEmpty(entities_using_importer_as_input_source)) {
+            warnings.push({ text: `[incorporateLongBuildImportedEntities]: failed to find an output file that uses the following source as its input: "${importer_resolved_path}".` });
+            continue;
+        }
+        // TODO: re-consider what scenarios can lead to the warnable situation below. is it even a problem if it occurs?
+        if (entities_using_importer_as_input_source.length > 1) {
+            warnings.push({ text: `[incorporateLongBuildImportedEntities]: we usually expect only a single output file to be made out of the given input source: "${importer_resolved_path}".` });
+        }
+        // collect all import entity nodes that is to be incorporated into each entity using these imports.
+        const imported_entity_nodes = entities_to_import.map((import_entity) => {
+            // note: remember, `import_entity.path` is relative to the longbuild file, and not the importer's `initial_output_path`.
+            // moreover, only non-external entities must go through the local-file output path resolution.
+            const { key, path, with: with_attr = {}, external = false } = import_entity, kind = "user-import", // this is our standard `kind` label for user imports that originate from the transformation stage.
+            entity = external
+                ? { externalPath: path }
+                : metafile.getFile(resolvePath(longbuild_path, path));
+            return { key, kind, with: with_attr, external, entity };
+        });
+        // finally, we add append copies of the `imported_entity_nodes` to each file entity that uses the `importer` file as an input source.
+        for (const file_entity of entities_using_importer_as_input_source) {
+            const initial_output_path = file_entity.initialPath ?? file_entity.outputPath, number_of_sources = file_entity.inputs.length;
+            // TODO: I'm not sure why I considered the situation below to be harmful. re-consider if there even is an issue with this scenario.
+            if (number_of_sources > 1) {
+                const input_sources = file_entity.inputs.map((input_source) => (input_source.namespace + ":" + input_source.path));
+                warnings.push({
+                    text: `[incorporateLongBuildImportedEntities]: expected the output file "${initial_output_path}" to be composed of just a single file, `
+                        + `but instead found it to be comprised of ${number_of_sources} source: [${input_sources.join(",\n")}]`
+                });
+            }
+            // appending copies of the `imported_entity_nodes` into this file entity's `imports`.
+            file_entity.imports.push(...imported_entity_nodes.map((node) => { return { ...node }; }));
+        }
+    }
+};
+class DependencyGraphNode {
+    key;
+    dependencies;
+    promise;
+    resolve;
+    reject;
+    callback;
+    constructor(key, dependencies) {
+        this.key = key;
+        this.dependencies = new Set(dependencies);
+        const [promise, resolve, reject] = promiseOutside();
+        this.promise = promise;
+        this.resolve = resolve;
+        this.reject = reject;
+    }
+    /** set the callback function to run once the {@link promise | promises} of _this_ node's {@link dependencies} get resolved.
+     * once your callback has been executed and waited for, the {@link promise} of _this_ node will also get resolved.
+    */
+    setCallback(callback) {
+        this.callback = callback;
+    }
+    /** manually fire the {@link callback} function of this node, and have its {@Link promise} get resolved.
+     * this is only intended to be used for source nodes (which carry no dependencies), although it is not enforced.
+    */
+    async fire() {
+        if (this.callback) {
+            this.callback(this, []).then(this.resolve, this.reject);
+        }
+        else {
+            this.reject([{ text: `[DependencyGraphNode.fire]: no callback was set for node id: "${this.key}".` }]);
+        }
+        return this.promise;
+    }
+    /** create a dependency graph from an existing graph `Map`. */
+    static fromGraph(dependency_graph) {
+        const graph = [...dependency_graph].map(([key, dependencies]) => {
+            const node = new this(key, dependencies);
+            return [key, node];
+        });
+        return new Map(graph);
+    }
+    /** chains the promises of a dependency graph, so that each node's {@link callback} is fired after all of it dependencies have been fired,
+     * while maintaining asynchronocity among all branches.
+     * the returned value contains an array of all nodes that are source nodes (carry no dependency).
+    */
+    static chainNodePromises(dependency_graph) {
+        const source_nodes = [];
+        for (const [id, node] of dependency_graph) {
+            if (node.dependencies.size <= 0) {
+                source_nodes.push(node);
+                continue;
+            }
+            const dependency_promises = [...node.dependencies].map((dep_id) => {
+                const dep_node = dependency_graph.get(dep_id);
+                return dep_node.promise;
+            });
+            Promise.all(dependency_promises)
+                .then((dependency_results) => {
+                const callback = node.callback;
+                if (!callback) {
+                    node.reject([{
+                            text: `[DependencyGraphNode::chainNodePromises]: no callback was set for node id: "${node.key}".`
+                        }]);
+                }
+                else {
+                    node.resolve(callback(node, dependency_results));
+                }
+            })
+                .catch((reason) => node.reject(reason));
+        }
+        return source_nodes;
+    }
+}