Add RGBASM -Winclude-shadow warning (#2180)

contrib/bash_compl/_rgbasm.bash

@@ -185,6 +185,7 @@ _rgbasm_completions() {
 				empty-macro-arg
 				empty-strrpl
 				export-undefined
+				include-shadow
 				large-constant
 				macro-shift
 				nested-comment

contrib/zsh_compl/_rgbasm

@@ -17,6 +17,7 @@ _rgbasm_warnings() {
 		'empty-macro-arg:Warn on empty macro arg'
 		'empty-strrpl:Warn on calling STRRPL with empty pattern'
 		'export-undefined:Warn on EXPORT of an undefined symbol'
+		'include-shadow:Warn on multiple INCLUDE/INCBIN file candidates'
 		'large-constant:Warn on constants too large for a signed 32-bit int'
 		'macro-shift:Warn when shifting macro args part their limits'
 		'nested-comment:Warn on "/*" inside block comments'

include/asm/warning.hpp

@@ -24,6 +24,7 @@ enum WarningID {
 	WARNING_EMPTY_MACRO_ARG,      // Empty macro argument
 	WARNING_EMPTY_STRRPL,         // Empty second argument in `STRRPL`
 	WARNING_EXPORT_UNDEFINED,     // `EXPORT` of an undefined symbol
+	WARNING_INCLUDE_SHADOW,       // Multiple `INCLUDE/INCBIN` file candidates
 	WARNING_LARGE_CONSTANT,       // Constants too large
 	WARNING_MACRO_SHIFT,          // `SHIFT` past available arguments in macro
 	WARNING_NESTED_COMMENT,       // Comment-start delimiter in a block comment

man/rgbasm.1

@@ -473,6 +473,13 @@ This warning is enabled by
 Warn when exporting an undefined symbol.
 This warning is enabled by
 .Fl Wall .
+.It Fl Winclude-shadow
+Warn when there are multiple files with the same name in different include paths.
+(The one in the first include path
+.Dq shadows
+the others.)
+This warning is enabled by
+.Fl Weverything .
 .It Fl Wno-large-constant
 Warn when a constant too large to fit in a signed 32-bit integer is encountered.
 .It Fl Wmacro-shift

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);
+			if (foundFile.has_value()) {
-			return fullPath;
+				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   },

test/asm/include-shadow.asm

@@ -0,0 +1,2 @@
+INCLUDE "include-shadow.inc"
+PRINTLN "N = {d:N}"

test/asm/include-shadow.err

@@ -0,0 +1,2 @@
+warning: File "include-shadow.inc" shadows "include/include-shadow.inc" and 1 other [-Winclude-shadow]
+    at include-shadow.asm(1)

test/asm/include-shadow.flags

@@ -0,0 +1 @@
+-I include -I include/include2

test/asm/include-shadow.inc

@@ -0,0 +1 @@
+DEF N EQU 1

test/asm/include-shadow.out

@@ -0,0 +1 @@
+N = 1

test/asm/include/include-shadow.inc

@@ -0,0 +1 @@
+DEF N EQU 2

test/asm/include/include2/include-shadow.inc

@@ -0,0 +1 @@
+DEF N EQU 3