Add RGBASM -Winclude-shadow warning (#2180)

src/asm/fstack.cpp

@@ -186,13 +186,47 @@ static void printDep(std::string const &path) {
 }
 
 std::optional<std::string> fstk_FindFile(std::string const &path) {
+	std::optional<std::string> foundFile = std::nullopt;
+	std::vector<std::string> shadowed;
+
+	bool warnIncludeShadow =
+	    warnings.getWarningBehavior(WARNING_INCLUDE_SHADOW) != WarningBehavior::DISABLED;
+
 	for (std::string &incPath : includePaths) {
 		if (std::string fullPath = incPath + path; isValidFilePath(fullPath)) {
-			printDep(fullPath);
-			return fullPath;
+			if (foundFile.has_value()) {
+				shadowed.push_back(fullPath);
+			} else {
+				foundFile = fullPath;
+				// If this does not need to print a `-Winclude-shadow` warning, it can immediately
+				// use the first path found instead of collecting all the `shadowed` paths.
+				if (!warnIncludeShadow) {
+					break;
+				}
+			}
 		}
 	}
 
+	if (!shadowed.empty()) {
+		assume(foundFile.has_value());
+		size_t nbSummarized = shadowed.size() - 1;
+		std::string summary = nbSummarized > 0 ? " and " + std::to_string(nbSummarized) + " other"
+		                                             + (nbSummarized != 1 ? "s" : "")
+		                                       : "";
+		warning(
+		    WARNING_INCLUDE_SHADOW,
+		    "File \"%s\" shadows \"%s\"%s",
+		    foundFile->c_str(),
+		    shadowed[0].c_str(),
+		    summary.c_str()
+		);
+	}
+
+	if (foundFile.has_value()) {
+		printDep(*foundFile);
+		return foundFile;
+	}
+
 	if (options.missingIncludeState != INC_ERROR) {
 		printDep(path);
 	}

src/asm/warning.cpp

@@ -31,6 +31,7 @@ Diagnostics<WarningLevel, WarningID> warnings = {
         {"empty-macro-arg",      LEVEL_EXTRA     },
         {"empty-strrpl",         LEVEL_ALL       },
         {"export-undefined",     LEVEL_ALL       },
+        {"include-shadow",       LEVEL_EVERYTHING},
         {"large-constant",       LEVEL_DEFAULT   },
         {"macro-shift",          LEVEL_EXTRA     },
         {"nested-comment",       LEVEL_DEFAULT   },