webpack 4.13.0 → 4.16.0

package/lib/Compilation.js

@@ -26,7 +26,6 @@ const ChunkTemplate = require("./ChunkTemplate");
 const HotUpdateChunkTemplate = require("./HotUpdateChunkTemplate");
 const ModuleTemplate = require("./ModuleTemplate");
 const RuntimeTemplate = require("./RuntimeTemplate");
-const Dependency = require("./Dependency");
 const ChunkRenderError = require("./ChunkRenderError");
 const AsyncDependencyToInitialChunkError = require("./AsyncDependencyToInitialChunkError");
 const Stats = require("./Stats");
@@ -35,17 +34,91 @@ const createHash = require("./util/createHash");
 const Queue = require("./util/Queue");
 const SortableSet = require("./util/SortableSet");
 const GraphHelpers = require("./GraphHelpers");
+const ModuleDependency = require("./dependencies/ModuleDependency");
+const compareLocations = require("./compareLocations");
 
 /** @typedef {import("./Module")} Module */
+/** @typedef {import("./Compiler")} Compiler */
+/** @typedef {import("webpack-sources").Source} Source */
+/** @typedef {import("./WebpackError")} WebpackError */
+/** @typedef {import("./DependenciesBlockVariable")} DependenciesBlockVariable */
+/** @typedef {import("./dependencies/SingleEntryDependency")} SingleEntryDependency */
+/** @typedef {import("./dependencies/MultiEntryDependency")} MultiEntryDependency */
+/** @typedef {import("./dependencies/DllEntryDependency")} DllEntryDependency */
+/** @typedef {import("./dependencies/DependencyReference")} DependencyReference */
 /** @typedef {import("./DependenciesBlock")} DependenciesBlock */
 /** @typedef {import("./AsyncDependenciesBlock")} AsyncDependenciesBlock */
-
+/** @typedef {import("./Dependency")} Dependency */
+/** @typedef {import("./Dependency").DependencyLocation} DependencyLocation */
+/** @typedef {import("./Dependency").DependencyTemplate} DependencyTemplate */
+/** @typedef {import("./util/createHash").Hash} Hash */
+
+// TODO use @callback
+/** @typedef {{[assetName: string]: Source}} CompilationAssets */
+/** @typedef {(err: Error|null, result?: Module) => void } ModuleCallback */
+/** @typedef {(err?: Error|null, result?: Module) => void } ModuleChainCallback */
+/** @typedef {(module: Module) => void} OnModuleCallback */
+/** @typedef {(err?: Error|null) => void} Callback */
+/** @typedef {(d: Dependency) => any} DepBlockVarDependenciesCallback */
+/** @typedef {new (...args: any[]) => Dependency} DepConstructor */
+/** @typedef {{apply: () => void}} Plugin */
+
+/**
+ * @typedef {Object} ModuleFactoryCreateDataContextInfo
+ * @property {string} issuer
+ * @property {string} compiler
+ */
+
+/**
+ * @typedef {Object} ModuleFactoryCreateData
+ * @property {ModuleFactoryCreateDataContextInfo} contextInfo
+ * @property {any=} resolveOptions
+ * @property {string} context
+ * @property {Dependency[]} dependencies
+ */
+
+/**
+ * @typedef {Object} ModuleFactory
+ * @property {(data: ModuleFactoryCreateData, callback: ModuleCallback) => any} create
+ */
+
+/**
+ * @typedef {Object} SortedDependency
+ * @property {ModuleFactory} factory
+ * @property {Dependency[]} dependencies
+ */
+
+/**
+ * @typedef {Object} AvailableModulesChunkGroupMapping
+ * @property {ChunkGroup} chunkGroup
+ * @property {Set<Module>} availableModules
+ */
+
+/**
+ * @typedef {Object} DependenciesBlockLike
+ * @property {Dependency[]} dependencies
+ * @property {AsyncDependenciesBlock[]} blocks
+ * @property {DependenciesBlockVariable[]} variables
+ */
+
+/**
+ * @param {Chunk} a first chunk to sort by id
+ * @param {Chunk} b second chunk to sort by id
+ * @returns {-1|0|1} sort value
+ */
 const byId = (a, b) => {
-	if (a.id < b.id) return -1;
-	if (a.id > b.id) return 1;
+	if (a.id !== null && b.id !== null) {
+		if (a.id < b.id) return -1;
+		if (a.id > b.id) return 1;
+	}
 	return 0;
 };
 
+/**
+ * @param {Module} a first module to sort by
+ * @param {Module} b second module to sort by
+ * @returns {-1|0|1} sort value
+ */
 const byIdOrIdentifier = (a, b) => {
 	if (a.id < b.id) return -1;
 	if (a.id > b.id) return 1;
@@ -56,6 +129,11 @@ const byIdOrIdentifier = (a, b) => {
 	return 0;
 };
 
+/**
+ * @param {Module} a first module to sort by
+ * @param {Module} b second module to sort by
+ * @returns {-1|0|1} sort value
+ */
 const byIndexOrIdentifier = (a, b) => {
 	if (a.index < b.index) return -1;
 	if (a.index > b.index) return 1;
@@ -66,14 +144,24 @@ const byIndexOrIdentifier = (a, b) => {
 	return 0;
 };
 
+/**
+ * @param {Compilation} a first compilation to sort by
+ * @param {Compilation} b second compilation to sort by
+ * @returns {-1|0|1} sort value
+ */
 const byNameOrHash = (a, b) => {
 	if (a.name < b.name) return -1;
 	if (a.name > b.name) return 1;
 	if (a.fullHash < b.fullHash) return -1;
-	if (a.fullhash > b.fullHash) return 1;
+	if (a.fullHash > b.fullHash) return 1;
 	return 0;
 };
 
+/**
+ * @param {DependenciesBlockVariable[]} variables DepBlock Variables to iterate over
+ * @param {DepBlockVarDependenciesCallback} fn callback to apply on iterated elements
+ * @returns {void}
+ */
 const iterationBlockVariable = (variables, fn) => {
 	for (
 		let indexVariable = 0;
@@ -87,105 +175,194 @@ const iterationBlockVariable = (variables, fn) => {
 	}
 };
 
+/**
+ * @template T
+ * @param {T[]} arr array of elements to iterate over
+ * @param {function(T): void} fn callback applied to each element
+ * @returns {void}
+ */
 const iterationOfArrayCallback = (arr, fn) => {
 	for (let index = 0; index < arr.length; index++) {
 		fn(arr[index]);
 	}
 };
 
-function addAllToSet(set, otherSet) {
+/**
+ * @template T
+ * @param {Set<T>} set set to add items to
+ * @param {Set<T>} otherSet set to add items from
+ * @returns {void}
+ */
+const addAllToSet = (set, otherSet) => {
 	for (const item of otherSet) {
 		set.add(item);
 	}
-}
+};
 
 class Compilation extends Tapable {
+	/**
+	 * Creates an instance of Compilation.
+	 * @param {Compiler} compiler the compiler which created the compilation
+	 */
 	constructor(compiler) {
 		super();
 		this.hooks = {
+			/** @type {SyncHook<Module>} */
 			buildModule: new SyncHook(["module"]),
+			/** @type {SyncHook<Module>} */
 			rebuildModule: new SyncHook(["module"]),
+			/** @type {SyncHook<Module, Error>} */
 			failedModule: new SyncHook(["module", "error"]),
+			/** @type {SyncHook<Module>} */
 			succeedModule: new SyncHook(["module"]),
 
+			/** @type {SyncWaterfallHook<DependencyReference, Dependency, Module>} */
+			dependencyReference: new SyncWaterfallHook([
+				"dependencyReference",
+				"dependency",
+				"module"
+			]),
+
+			/** @type {SyncHook<Module[]>} */
 			finishModules: new SyncHook(["modules"]),
+			/** @type {SyncHook<Module>} */
 			finishRebuildingModule: new SyncHook(["module"]),
-
+			/** @type {SyncHook} */
 			unseal: new SyncHook([]),
+			/** @type {SyncHook} */
 			seal: new SyncHook([]),
 
+			/** @type {SyncHook} */
+			beforeChunks: new SyncHook([]),
+			/** @type {SyncHook<Chunk[]>} */
+			afterChunks: new SyncHook(["chunks"]),
+
+			/** @type {SyncBailHook<Module[]>} */
 			optimizeDependenciesBasic: new SyncBailHook(["modules"]),
+			/** @type {SyncBailHook<Module[]>} */
 			optimizeDependencies: new SyncBailHook(["modules"]),
+			/** @type {SyncBailHook<Module[]>} */
 			optimizeDependenciesAdvanced: new SyncBailHook(["modules"]),
+			/** @type {SyncBailHook<Module[]>} */
 			afterOptimizeDependencies: new SyncHook(["modules"]),
 
+			/** @type {SyncHook} */
 			optimize: new SyncHook([]),
-
+			/** @type {SyncBailHook<Module[]>} */
 			optimizeModulesBasic: new SyncBailHook(["modules"]),
+			/** @type {SyncBailHook<Module[]>} */
 			optimizeModules: new SyncBailHook(["modules"]),
+			/** @type {SyncBailHook<Module[]>} */
 			optimizeModulesAdvanced: new SyncBailHook(["modules"]),
+			/** @type {SyncHook<Module[]>} */
 			afterOptimizeModules: new SyncHook(["modules"]),
 
+			/** @type {SyncBailHook<Chunk[], ChunkGroup[]>} */
 			optimizeChunksBasic: new SyncBailHook(["chunks", "chunkGroups"]),
+			/** @type {SyncBailHook<Chunk[], ChunkGroup[]>} */
 			optimizeChunks: new SyncBailHook(["chunks", "chunkGroups"]),
+			/** @type {SyncBailHook<Chunk[], ChunkGroup[]>} */
 			optimizeChunksAdvanced: new SyncBailHook(["chunks", "chunkGroups"]),
+			/** @type {SyncHook<Chunk[], ChunkGroup[]>} */
 			afterOptimizeChunks: new SyncHook(["chunks", "chunkGroups"]),
 
+			/** @type {AsyncSeriesHook<Chunk[], Module[]>} */
 			optimizeTree: new AsyncSeriesHook(["chunks", "modules"]),
+			/** @type {SyncHook<Chunk[], Module[]>} */
 			afterOptimizeTree: new SyncHook(["chunks", "modules"]),
 
+			/** @type {SyncBailHook<Chunk[], Module[]>} */
 			optimizeChunkModulesBasic: new SyncBailHook(["chunks", "modules"]),
+			/** @type {SyncBailHook<Chunk[], Module[]>} */
 			optimizeChunkModules: new SyncBailHook(["chunks", "modules"]),
+			/** @type {SyncBailHook<Chunk[], Module[]>} */
 			optimizeChunkModulesAdvanced: new SyncBailHook(["chunks", "modules"]),
+			/** @type {SyncHook<Chunk[], Module[]>} */
 			afterOptimizeChunkModules: new SyncHook(["chunks", "modules"]),
+			/** @type {SyncBailHook} */
 			shouldRecord: new SyncBailHook([]),
 
+			/** @type {SyncHook<Module[], any>} */
 			reviveModules: new SyncHook(["modules", "records"]),
+			/** @type {SyncHook<Module[]>} */
 			optimizeModuleOrder: new SyncHook(["modules"]),
+			/** @type {SyncHook<Module[]>} */
 			advancedOptimizeModuleOrder: new SyncHook(["modules"]),
+			/** @type {SyncHook<Module[]>} */
 			beforeModuleIds: new SyncHook(["modules"]),
+			/** @type {SyncHook<Module[]>} */
 			moduleIds: new SyncHook(["modules"]),
+			/** @type {SyncHook<Module[]>} */
 			optimizeModuleIds: new SyncHook(["modules"]),
+			/** @type {SyncHook<Module[]>} */
 			afterOptimizeModuleIds: new SyncHook(["modules"]),
 
+			/** @type {SyncHook<Chunk[], any>} */
 			reviveChunks: new SyncHook(["chunks", "records"]),
+			/** @type {SyncHook<Chunk[]>} */
 			optimizeChunkOrder: new SyncHook(["chunks"]),
+			/** @type {SyncHook<Chunk[]>} */
 			beforeChunkIds: new SyncHook(["chunks"]),
+			/** @type {SyncHook<Chunk[]>} */
 			optimizeChunkIds: new SyncHook(["chunks"]),
+			/** @type {SyncHook<Chunk[]>} */
 			afterOptimizeChunkIds: new SyncHook(["chunks"]),
 
+			/** @type {SyncHook<Module[], any>} */
 			recordModules: new SyncHook(["modules", "records"]),
+			/** @type {SyncHook<Chunk[], any>} */
 			recordChunks: new SyncHook(["chunks", "records"]),
 
+			/** @type {SyncHook} */
 			beforeHash: new SyncHook([]),
+			/** @type {SyncHook<Chunk>} */
 			contentHash: new SyncHook(["chunk"]),
+			/** @type {SyncHook} */
 			afterHash: new SyncHook([]),
-
+			/** @type {SyncHook<any>} */
 			recordHash: new SyncHook(["records"]),
-
+			/** @type {SyncHook<Compilation, any>} */
 			record: new SyncHook(["compilation", "records"]),
 
+			/** @type {SyncHook} */
 			beforeModuleAssets: new SyncHook([]),
+			/** @type {SyncBailHook} */
 			shouldGenerateChunkAssets: new SyncBailHook([]),
+			/** @type {SyncHook} */
 			beforeChunkAssets: new SyncHook([]),
+			/** @type {SyncHook<Chunk[]>} */
 			additionalChunkAssets: new SyncHook(["chunks"]),
 
+			/** @type {AsyncSeriesHook} */
 			additionalAssets: new AsyncSeriesHook([]),
+			/** @type {AsyncSeriesHook<Chunk[]>} */
 			optimizeChunkAssets: new AsyncSeriesHook(["chunks"]),
+			/** @type {SyncHook<Chunk[]>} */
 			afterOptimizeChunkAssets: new SyncHook(["chunks"]),
+			/** @type {AsyncSeriesHook<CompilationAssets>} */
 			optimizeAssets: new AsyncSeriesHook(["assets"]),
+			/** @type {SyncHook<CompilationAssets>} */
 			afterOptimizeAssets: new SyncHook(["assets"]),
 
+			/** @type {SyncBailHook} */
 			needAdditionalSeal: new SyncBailHook([]),
+			/** @type {AsyncSeriesHook} */
 			afterSeal: new AsyncSeriesHook([]),
 
+			/** @type {SyncHook<Chunk, Hash>} */
 			chunkHash: new SyncHook(["chunk", "chunkHash"]),
+			/** @type {SyncHook<Module, string>} */
 			moduleAsset: new SyncHook(["module", "filename"]),
+			/** @type {SyncHook<Chunk, string>} */
 			chunkAsset: new SyncHook(["chunk", "filename"]),
 
+			/** @type {SyncWaterfallHook<string, TODO>} */
 			assetPath: new SyncWaterfallHook(["filename", "data"]), // TODO MainTemplate
 
+			/** @type {SyncBailHook} */
 			needAdditionalPass: new SyncBailHook([]),
+
+			/** @type {SyncHook<Compiler, string, number>} */
 			childCompiler: new SyncHook([
 				"childCompiler",
 				"compilerName",
@@ -194,11 +371,16 @@ class Compilation extends Tapable {
 
 			// TODO the following hooks are weirdly located here
 			// TODO move them for webpack 5
+			/** @type {SyncHook<object, Module>} */
 			normalModuleLoader: new SyncHook(["loaderContext", "module"]),
 
+			/** @type {SyncBailHook<Chunk[]>} */
 			optimizeExtractedChunksBasic: new SyncBailHook(["chunks"]),
+			/** @type {SyncBailHook<Chunk[]>} */
 			optimizeExtractedChunks: new SyncBailHook(["chunks"]),
+			/** @type {SyncBailHook<Chunk[]>} */
 			optimizeExtractedChunksAdvanced: new SyncBailHook(["chunks"]),
+			/** @type {SyncHook<Chunk[]>} */
 			afterOptimizeExtractedChunks: new SyncHook(["chunks"])
 		};
 		this._pluginCompat.tap("Compilation", options => {
@@ -212,7 +394,9 @@ class Compilation extends Tapable {
 					break;
 			}
 		});
+		/** @type {string=} */
 		this.name = undefined;
+		/** @type {Compiler} */
 		this.compiler = compiler;
 		this.resolverFactory = compiler.resolverFactory;
 		this.inputFileSystem = compiler.inputFileSystem;
@@ -220,6 +404,7 @@ class Compilation extends Tapable {
 
 		const options = (this.options = compiler.options);
 		this.outputOptions = options && options.output;
+		/** @type {boolean=} */
 		this.bail = options && options.bail;
 		this.profile = options && options.profile;
 		this.performance = options && options.performance;
@@ -241,32 +426,53 @@ class Compilation extends Tapable {
 		this.semaphore = new Semaphore(options.parallelism || 100);
 
 		this.entries = [];
+		/** @private @type {{name: string, request: string, module: Module}[]} */
 		this._preparedEntrypoints = [];
 		this.entrypoints = new Map();
+		/** @type {Chunk[]} */
 		this.chunks = [];
+		/** @type {ChunkGroup[]} */
 		this.chunkGroups = [];
+		/** @type {Map<string, ChunkGroup>} */
 		this.namedChunkGroups = new Map();
+		/** @type {Map<string, Chunk>} */
 		this.namedChunks = new Map();
+		/** @type {Module[]} */
 		this.modules = [];
+		/** @private @type {Map<string, Module>} */
 		this._modules = new Map();
 		this.cache = null;
 		this.records = null;
+		/** @type {string[]} */
 		this.additionalChunkAssets = [];
+		/** @type {CompilationAssets} */
 		this.assets = {};
+		/** @type {WebpackError[]} */
 		this.errors = [];
+		/** @type {WebpackError[]} */
 		this.warnings = [];
+		/** @type {Compilation[]} */
 		this.children = [];
+		/** @type {Map<DepConstructor, ModuleFactory>} */
 		this.dependencyFactories = new Map();
+		/** @type {Map<DepConstructor|string, DependencyTemplate|string>} */
 		this.dependencyTemplates = new Map();
+		// TODO refactor this in webpack 5 to a custom DependencyTemplates class with a hash property
 		this.dependencyTemplates.set("hash", "");
 		this.childrenCounters = {};
+		/** @type {Set<number|string>} */
 		this.usedChunkIds = null;
+		/** @type {Set<number>} */
 		this.usedModuleIds = null;
+		/** @type {Map<string, number>=} */
 		this.fileTimestamps = undefined;
+		/** @type {Map<string, number>=} */
 		this.contextTimestamps = undefined;
+		/** @type {Set<string>=} */
 		this.compilationDependencies = undefined;
-
+		/** @private @type {Map<Module, Callback[]>} */
 		this._buildingModules = new Map();
+		/** @private @type {Map<Module, Callback[]>} */
 		this._rebuildingModules = new Map();
 	}
 
@@ -274,6 +480,20 @@ class Compilation extends Tapable {
 		return new Stats(this);
 	}
 
+	/**
+	 * @typedef {Object} AddModuleResult
+	 * @property {Module} module the added or existing module
+	 * @property {boolean} issuer was this the first request for this module
+	 * @property {boolean} build should the module be build
+	 * @property {boolean} dependencies should dependencies be walked
+	 */
+
+	/**
+	 * @param {Module} module module to be added that was created
+	 * @param {any=} cacheGroup cacheGroup it is apart of
+	 * @returns {AddModuleResult} returns meta about whether or not the module had built
+	 * had an issuer, or any dependnecies
+	 */
 	addModule(module, cacheGroup) {
 		const identifier = module.identifier();
 		const alreadyAddedModule = this._modules.get(identifier);
@@ -334,15 +554,30 @@ class Compilation extends Tapable {
 		};
 	}
 
+	/**
+	 * Fetches a module from a compilation by its identifier
+	 * @param {Module} module the module provided
+	 * @returns {Module} the module requested
+	 */
 	getModule(module) {
 		const identifier = module.identifier();
 		return this._modules.get(identifier);
 	}
 
+	/**
+	 * Attempts to search for a module by its identifier
+	 * @param {string} identifier identifier (usually path) for module
+	 * @returns {Module|undefined} attempt to search for module and return it, else undefined
+	 */
 	findModule(identifier) {
 		return this._modules.get(identifier);
 	}
 
+	/**
+	 * @param {Module} module module with its callback list
+	 * @param {Callback} callback the callback function
+	 * @returns {void}
+	 */
 	waitForBuildingFinished(module, callback) {
 		let callbackList = this._buildingModules.get(module);
 		if (callbackList) {
@@ -352,6 +587,16 @@ class Compilation extends Tapable {
 		}
 	}
 
+	/**
+	 * Builds the module object
+	 *
+	 * @param {Module} module module to be built
+	 * @param {boolean} optional optional flag
+	 * @param {Module=} origin origin module this module build was requested from
+	 * @param {Dependency[]=} dependencies optional dependencies from the module to be built
+	 * @param {TODO} thisCallback the callback
+	 * @returns {TODO} returns the callback function with results
+	 */
 	buildModule(module, optional, origin, dependencies, thisCallback) {
 		let callbackList = this._buildingModules.get(module);
 		if (callbackList) {
@@ -397,7 +642,7 @@ class Compilation extends Tapable {
 					war.dependencies = dependencies;
 					this.warnings.push(war);
 				}
-				module.dependencies.sort(Dependency.compare);
+				module.dependencies.sort((a, b) => compareLocations(a.loc, b.loc));
 				if (error) {
 					this.hooks.failedModule.call(module, error);
 					return callback(error);
@@ -408,6 +653,11 @@ class Compilation extends Tapable {
 		);
 	}
 
+	/**
+	 * @param {Module} module to be processed for deps
+	 * @param {ModuleCallback} callback callback to be triggered
+	 * @returns {void}
+	 */
 	processModuleDependencies(module, callback) {
 		const dependencies = new Map();
 
@@ -471,6 +721,15 @@ class Compilation extends Tapable {
 		);
 	}
 
+	/**
+	 * @param {Module} module module to add deps to
+	 * @param {SortedDependency[]} dependencies set of sorted dependencies to iterate through
+	 * @param {(boolean|null)=} bail whether to bail or not
+	 * @param {TODO} cacheGroup optional cacheGroup
+	 * @param {boolean} recursive whether it is recursive traversal
+	 * @param {function} callback callback for when dependencies are finished being added
+	 * @returns {void}
+	 */
 	addModuleDependencies(
 		module,
 		dependencies,
@@ -638,6 +897,14 @@ class Compilation extends Tapable {
 		);
 	}
 
+	/**
+	 *
+	 * @param {string} context context string path
+	 * @param {Dependency} dependency dependency used to create Module chain
+	 * @param {OnModuleCallback} onModule function invoked on modules creation
+	 * @param {ModuleChainCallback} callback callback for when module chain is complete
+	 * @returns {void} will throw if dependency instance is not a valid Dependency
+	 */
 	_addModuleChain(context, dependency, onModule, callback) {
 		const start = this.profile && Date.now();
 		const currentProfile = this.profile && {};
@@ -659,8 +926,8 @@ class Compilation extends Tapable {
 		) {
 			throw new Error("Parameter 'dependency' must be a Dependency");
 		}
-
-		const moduleFactory = this.dependencyFactories.get(dependency.constructor);
+		const Dep = /** @type {DepConstructor} */ (dependency.constructor);
+		const moduleFactory = this.dependencyFactories.get(Dep);
 		if (!moduleFactory) {
 			throw new Error(
 				`No dependency factory available for this dependency type: ${
@@ -746,12 +1013,25 @@ class Compilation extends Tapable {
 		});
 	}
 
+	/**
+	 *
+	 * @param {string} context context path for entry
+	 * @param {Dependency} entry entry dependency being created
+	 * @param {string} name name of entry
+	 * @param {ModuleCallback} callback callback function
+	 * @returns {void} returns
+	 */
 	addEntry(context, entry, name, callback) {
 		const slot = {
 			name: name,
-			request: entry.request,
+			request: null,
 			module: null
 		};
+
+		if (entry instanceof ModuleDependency) {
+			slot.request = entry.request;
+		}
+
 		this._preparedEntrypoints.push(slot);
 		this._addModuleChain(
 			context,
@@ -775,6 +1055,12 @@ class Compilation extends Tapable {
 		);
 	}
 
+	/**
+	 * @param {string} context context path string
+	 * @param {Dependency} dependency dep used to create module
+	 * @param {ModuleCallback} callback module callback sending module up a level
+	 * @returns {void}
+	 */
 	prefetch(context, dependency, callback) {
 		this._addModuleChain(
 			context,
@@ -786,6 +1072,11 @@ class Compilation extends Tapable {
 		);
 	}
 
+	/**
+	 * @param {Module} module module to be rebuilt
+	 * @param {Callback} thisCallback callback when module finishes rebuilding
+	 * @returns {void}
+	 */
 	rebuildModule(module, thisCallback) {
 		let callbackList = this._rebuildingModules.get(module);
 		if (callbackList) {
@@ -848,6 +1139,10 @@ class Compilation extends Tapable {
 		}
 	}
 
+	/**
+	 * @param {Callback} callback signals when the seal method is finishes
+	 * @returns {void}
+	 */
 	seal(callback) {
 		this.hooks.seal.call();
 
@@ -860,6 +1155,7 @@ class Compilation extends Tapable {
 		}
 		this.hooks.afterOptimizeDependencies.call(this.modules);
 
+		this.hooks.beforeChunks.call();
 		for (const preparedEntrypoint of this._preparedEntrypoints) {
 			const module = preparedEntrypoint.module;
 			const name = preparedEntrypoint.name;
@@ -881,6 +1177,8 @@ class Compilation extends Tapable {
 		}
 		this.processDependenciesBlocksForChunkGroups(this.chunkGroups.slice());
 		this.sortModules(this.modules);
+		this.hooks.afterChunks.call(this.chunks);
+
 		this.hooks.optimize.call();
 
 		while (
@@ -989,10 +1287,22 @@ class Compilation extends Tapable {
 		});
 	}
 
+	/**
+	 * @param {Module[]} modules the modules array on compilation to perform the sort for
+	 * @returns {void}
+	 */
 	sortModules(modules) {
+		// TODO webpack 5: this should only be enabled when `moduleIds: "natural"`
+		// TODO move it into a plugin (NaturalModuleIdsPlugin) and use this in WebpackOptionsApply
+		// TODO remove this method
 		modules.sort(byIndexOrIdentifier);
 	}
 
+	/**
+	 * @param {Module} module moulde to report from
+	 * @param {DependenciesBlock[]} blocks blocks to report from
+	 * @returns {void}
+	 */
 	reportDependencyErrorsAndWarnings(module, blocks) {
 		for (let indexBlock = 0; indexBlock < blocks.length; indexBlock++) {
 			const block = blocks[indexBlock];
@@ -1028,7 +1338,7 @@ class Compilation extends Tapable {
 	/**
 	 * @param {TODO} groupOptions options for the chunk group
 	 * @param {Module} module the module the references the chunk group
-	 * @param {TODO} loc the location from with the chunk group is reference (inside of module)
+	 * @param {DependencyLocation} loc the location from with the chunk group is referenced (inside of module)
 	 * @param {string} request the request from which the the chunk group is referenced
 	 * @returns {ChunkGroup} the new or existing chunk group
 	 */
@@ -1060,6 +1370,13 @@ class Compilation extends Tapable {
 		return chunkGroup;
 	}
 
+	/**
+	 * This method first looks to see if a name is provided for a new chunk,
+	 * and first looks to see if any named chunks already exist and reuse that chunk instead.
+	 *
+	 * @param {string=} name optional chunk name to be provided
+	 * @returns {Chunk} create a chunk (invoked during seal event)
+	 */
 	addChunk(name) {
 		if (name) {
 			const chunk = this.namedChunks.get(name);
@@ -1075,12 +1392,20 @@ class Compilation extends Tapable {
 		return chunk;
 	}
 
+	/**
+	 * @param {Module} module module to assign depth
+	 * @returns {void}
+	 */
 	assignDepth(module) {
 		const queue = new Set([module]);
 		let depth;
 
 		module.depth = 0;
 
+		/**
+		 * @param {Module} module module for processeing
+		 * @returns {void}
+		 */
 		const enqueueJob = module => {
 			const d = module.depth;
 			if (typeof d === "number" && d <= depth) return;
@@ -1088,12 +1413,20 @@ class Compilation extends Tapable {
 			module.depth = depth;
 		};
 
-		const assignDepthToDependency = (dependency, depth) => {
+		/**
+		 * @param {Dependency} dependency dependency to assign depth to
+		 * @returns {void}
+		 */
+		const assignDepthToDependency = dependency => {
 			if (dependency.module) {
 				enqueueJob(dependency.module);
 			}
 		};
 
+		/**
+		 * @param {DependenciesBlock} block block to assign depth to
+		 * @returns {void}
+		 */
 		const assignDepthToDependencyBlock = block => {
 			if (block.variables) {
 				iterationBlockVariable(block.variables, assignDepthToDependency);
@@ -1117,6 +1450,19 @@ class Compilation extends Tapable {
 		}
 	}
 
+	/**
+	 * @param {Module} module the module containing the dependency
+	 * @param {Dependency} dependency the dependency
+	 * @returns {DependencyReference} a reference for the dependency
+	 */
+	getDependencyReference(module, dependency) {
+		// TODO remove dep.getReference existence check in webpack 5
+		if (typeof dependency.getReference !== "function") return null;
+		const ref = dependency.getReference();
+		if (!ref) return null;
+		return this.hooks.dependencyReference.call(ref, dependency, module);
+	}
+
 	/**
 	 * This method creates the Chunk graph from the Module graph
 	 * @private
@@ -1132,7 +1478,7 @@ class Compilation extends Tapable {
 		//   eachother and Blocks with Chunks. It stops traversing when all modules
 		//   for a chunk are already available. So it doesn't connect unneeded chunks.
 
-		/** @type {Map<Chunk, {block: DependenciesBlock, chunkGroup: ChunkGroup}[]>} */
+		/** @type {Map<ChunkGroup, {block: AsyncDependenciesBlock, chunkGroup: ChunkGroup}[]>} */
 		const chunkDependencies = new Map();
 		const allCreatedChunkGroups = new Set();
 
@@ -1140,9 +1486,13 @@ class Compilation extends Tapable {
 		/** @type {Map<DependenciesBlock, { modules: Module[], blocks: AsyncDependenciesBlock[]}>} */
 		const blockInfoMap = new Map();
 
+		/**
+		 * @param {Dependency} d dependency to iterate over
+		 * @returns {void}
+		 */
 		const iteratorDependency = d => {
 			// We skip Dependencies without Reference
-			const ref = d.getReference();
+			const ref = this.getDependencyReference(currentModule, d);
 			if (!ref) {
 				return;
 			}
@@ -1159,22 +1509,29 @@ class Compilation extends Tapable {
 			blockInfoModules.add(refModule);
 		};
 
+		/**
+		 * @param {AsyncDependenciesBlock} b blocks to prepare
+		 * @returns {void}
+		 */
 		const iteratorBlockPrepare = b => {
 			blockInfoBlocks.push(b);
 			blockQueue.push(b);
 		};
 
+		/** @type {Module} */
+		let currentModule;
 		/** @type {DependenciesBlock} */
 		let block;
-		/** @type {TODO} */
+		/** @type {DependenciesBlock[]} */
 		let blockQueue;
-		/** @type {Set<TODO>} */
+		/** @type {Set<Module>} */
 		let blockInfoModules;
-		/** @type {TODO[]} */
+		/** @type {AsyncDependenciesBlock[]} */
 		let blockInfoBlocks;
 
 		for (const module of this.modules) {
 			blockQueue = [module];
+			currentModule = module;
 			while (blockQueue.length > 0) {
 				block = blockQueue.pop();
 				blockInfoModules = new Set();
@@ -1246,9 +1603,18 @@ class Compilation extends Tapable {
 		/** @type {QueueItem[]} */
 		let queueDelayed = [];
 
-		let module, chunk, chunkGroup;
+		/** @type {Module} */
+		let module;
+		/** @type {Chunk} */
+		let chunk;
+		/** @type {ChunkGroup} */
+		let chunkGroup;
 
 		// For each async Block in graph
+		/**
+		 * @param {AsyncDependenciesBlock} b iterating over each Async DepBlock
+		 * @returns {void}
+		 */
 		const iteratorBlock = b => {
 			// 1. We create a chunk for this Block
 			// but only once (blockChunkGroups map)
@@ -1390,9 +1756,10 @@ class Compilation extends Tapable {
 		}
 
 		// PART TWO
-
+		/** @type {Set<Module>} */
 		let availableModules;
 		let newAvailableModules;
+		/** @type {Queue<AvailableModulesChunkGroupMapping>} */
 		const queue2 = new Queue(
 			inputChunkGroups.map(chunkGroup => ({
 				chunkGroup,
@@ -1400,7 +1767,13 @@ class Compilation extends Tapable {
 			}))
 		);
 
-		// Helper function to check if all modules of a chunk are available
+		/**
+		 * Helper function to check if all modules of a chunk are available
+		 *
+		 * @param {ChunkGroup} chunkGroup the chunkGroup to scan
+		 * @param {Set<Module>} availableModules the comparitor set
+		 * @returns {boolean} return true if all modules of a chunk are available
+		 */
 		const areModulesAvailable = (chunkGroup, availableModules) => {
 			for (const chunk of chunkGroup.chunks) {
 				for (const module of chunk.modulesIterable) {
@@ -1411,14 +1784,18 @@ class Compilation extends Tapable {
 		};
 
 		// For each edge in the basic chunk graph
+		/**
+		 * @param {TODO} dep the dependency used for filtering
+		 * @returns {boolean} used to filter "edges" (aka Dependencies) that were pointing
+		 * to modules that are already available. Also filters circular dependencies in the chunks graph
+		 */
 		const filterFn = dep => {
-			// Filter egdes that are not needed because all modules are already available
-			// This also filters circular dependencies in the chunks graph
 			const depChunkGroup = dep.chunkGroup;
 			if (areModulesAvailable(depChunkGroup, newAvailableModules)) return false; // break all modules are already available
 			return true;
 		};
 
+		/** @type {Map<ChunkGroup, Set<Module>>} */
 		const minAvailableModulesMap = new Map();
 
 		// Iterative traversing of the basic chunk graph
@@ -1503,6 +1880,12 @@ class Compilation extends Tapable {
 		}
 	}
 
+	/**
+	 *
+	 * @param {Module} module module relationship for removal
+	 * @param {DependenciesBlockLike} block //TODO: good description
+	 * @returns {void}
+	 */
 	removeReasonsOfDependencyBlock(module, block) {
 		const iteratorDependency = d => {
 			if (!d.module) {
@@ -1530,6 +1913,11 @@ class Compilation extends Tapable {
 		}
 	}
 
+	/**
+	 * @param {Module} module module to patch tie
+	 * @param {Chunk} chunk chunk to patch tie
+	 * @returns {void}
+	 */
 	patchChunksAfterReasonRemoval(module, chunk) {
 		if (!module.hasReasons()) {
 			this.removeReasonsOfDependencyBlock(module, module);
@@ -1541,6 +1929,12 @@ class Compilation extends Tapable {
 		}
 	}
 
+	/**
+	 *
+	 * @param {DependenciesBlock} block block tie for Chunk
+	 * @param {Chunk} chunk chunk to remove from dep
+	 * @returns {void}
+	 */
 	removeChunkFromDependencies(block, chunk) {
 		const iteratorDependency = d => {
 			if (!d.module) {
@@ -1551,12 +1945,16 @@ class Compilation extends Tapable {
 
 		const blocks = block.blocks;
 		for (let indexBlock = 0; indexBlock < blocks.length; indexBlock++) {
-			const chunks = blocks[indexBlock].chunks;
+			const asyncBlock = blocks[indexBlock];
+			// Grab all chunks from the first Block's AsyncDepBlock
+			const chunks = asyncBlock.chunkGroup.chunks;
+			// For each chunk in chunkGroup
 			for (let indexChunk = 0; indexChunk < chunks.length; indexChunk++) {
-				const blockChunk = chunks[indexChunk];
-				chunk.removeChunk(blockChunk);
-				blockChunk.removeParent(chunk);
-				this.removeChunkFromDependencies(chunks, blockChunk);
+				const iteratedChunk = chunks[indexChunk];
+				asyncBlock.chunkGroup.removeChunk(iteratedChunk);
+				asyncBlock.chunkGroup.removeParent(iteratedChunk);
+				// Recurse
+				this.removeChunkFromDependencies(block, iteratedChunk);
 			}
 		}
 
@@ -1620,6 +2018,7 @@ class Compilation extends Tapable {
 	}
 
 	applyChunkIds() {
+		/** @type {Set<number>} */
 		const usedIds = new Set();
 
 		// Get used ids from usedChunkIds property (i. e. from records)
@@ -1654,6 +2053,7 @@ class Compilation extends Tapable {
 		nextFreeChunkId++;
 
 		// Determine free chunk ids from 0 to maximum
+		/** @type {number[]} */
 		const unusedIds = [];
 		if (nextFreeChunkId > 0) {
 			let index = nextFreeChunkId;
@@ -1690,7 +2090,7 @@ class Compilation extends Tapable {
 
 		const chunks = this.chunks;
 		for (let indexChunk = 0; indexChunk < chunks.length; indexChunk++) {
-			chunks[indexChunk].sortItems(false);
+			chunks[indexChunk].sortItems();
 		}
 	}
 
@@ -1711,9 +2111,19 @@ class Compilation extends Tapable {
 
 		const chunks = this.chunks;
 		for (let indexChunk = 0; indexChunk < chunks.length; indexChunk++) {
-			chunks[indexChunk].sortItems(true);
+			chunks[indexChunk].sortItems();
 		}
 
+		/**
+		 * Used to sort errors and warnings in compilation. this.warnings, and
+		 * this.errors contribute to the compilation hash and therefore should be
+		 * updated whenever other references (having a chunk id) are sorted. This preserves the hash
+		 * integrity
+		 *
+		 * @param {WebpackError} a first WebpackError instance (including subclasses)
+		 * @param {WebpackError} b second WebpackError instance (including subclasses)
+		 * @returns {-1|0|1} sort order index
+		 */
 		const byMessage = (a, b) => {
 			const ma = `${a.message}`;
 			const mb = `${b.message}`;
@@ -1841,6 +2251,10 @@ class Compilation extends Tapable {
 		this.hash = this.fullHash.substr(0, hashDigestLength);
 	}
 
+	/**
+	 * @param {string} update extra information
+	 * @returns {void}
+	 */
 	modifyHash(update) {
 		const outputOptions = this.outputOptions;
 		const hashFunction = outputOptions.hashFunction;
@@ -1869,6 +2283,8 @@ class Compilation extends Tapable {
 	createChunkAssets() {
 		const outputOptions = this.outputOptions;
 		const cachedSourceMap = new Map();
+		/** @type {Map<string, {hash: string, source: Source, chunk: Chunk}>} */
+		const alreadyWrittenFiles = new Map();
 		for (let i = 0; i < this.chunks.length; i++) {
 			const chunk = this.chunks[i];
 			chunk.files = [];
@@ -1891,6 +2307,28 @@ class Compilation extends Tapable {
 					const cacheName = fileManifest.identifier;
 					const usedHash = fileManifest.hash;
 					filenameTemplate = fileManifest.filenameTemplate;
+					file = this.getPath(filenameTemplate, fileManifest.pathOptions);
+
+					// check if the same filename was already written by another chunk
+					const alreadyWritten = alreadyWrittenFiles.get(file);
+					if (alreadyWritten !== undefined) {
+						if (alreadyWritten.hash === usedHash) {
+							if (this.cache) {
+								this.cache[cacheName] = {
+									hash: usedHash,
+									source: alreadyWritten.source
+								};
+							}
+							chunk.files.push(file);
+							this.hooks.chunkAsset.call(chunk, file);
+							continue;
+						} else {
+							throw new Error(
+								`Conflict: Multiple chunks emit assets to the same filename ${file}` +
+									` (chunks ${alreadyWritten.chunk.id} and ${chunk.id})`
+							);
+						}
+					}
 					if (
 						this.cache &&
 						this.cache[cacheName] &&
@@ -1917,7 +2355,6 @@ class Compilation extends Tapable {
 							};
 						}
 					}
-					file = this.getPath(filenameTemplate, fileManifest.pathOptions);
 					if (this.assets[file] && this.assets[file] !== source) {
 						throw new Error(
 							`Conflict: Multiple assets emit to the same filename ${file}`
@@ -1926,6 +2363,11 @@ class Compilation extends Tapable {
 					this.assets[file] = source;
 					chunk.files.push(file);
 					this.hooks.chunkAsset.call(chunk, file);
+					alreadyWrittenFiles.set(file, {
+						hash: usedHash,
+						source,
+						chunk
+					});
 				}
 			} catch (err) {
 				this.errors.push(
@@ -1935,12 +2377,27 @@ class Compilation extends Tapable {
 		}
 	}
 
+	/**
+	 * @param {string} filename used to get asset path with hash
+	 * @param {TODO=} data // TODO: figure out this param type
+	 * @returns {string} interpolated path
+	 */
 	getPath(filename, data) {
 		data = data || {};
 		data.hash = data.hash || this.hash;
 		return this.mainTemplate.getAssetPath(filename, data);
 	}
 
+	/**
+	 * This function allows you to run another instance of webpack inside of webpack however as
+	 * a child with different settings and configurations (if desired) applied. It copies all hooks, plugins
+	 * from parent (or top level compiler) and creates a child Compilation
+	 *
+	 * @param {string} name name of the child compiler
+	 * @param {TODO} outputOptions // Need to convert config schema to types for this
+	 * @param {Plugin[]} plugins webpack plugins that will be applied
+	 * @returns {Compiler} creates a child Compiler instance
+	 */
 	createChildCompiler(name, outputOptions, plugins) {
 		const idx = this.childrenCounters[name] || 0;
 		this.childrenCounters[name] = idx + 1;
@@ -1954,6 +2411,7 @@ class Compilation extends Tapable {
 	}
 
 	checkConstraints() {
+		/** @type {Set<number|string>} */
 		const usedIds = new Set();
 
 		const modules = this.modules;