Merge pull request #11558 from ethereum/KeyValueParser

Yul: custom source locations (`@src`)

libsolidity/interface/CompilerStack.cpp

@@ -80,7 +80,6 @@
 
 #include <utility>
 #include <map>
-#include <range/v3/view/concat.hpp>
 
 #include <boost/algorithm/string/replace.hpp>
 
@@ -927,6 +926,19 @@ map<string, unsigned> CompilerStack::sourceIndices() const
 	return indices;
 }
 
+map<unsigned, shared_ptr<CharStream>> CompilerStack::indicesToCharStreams() const
+{
+	map<unsigned, shared_ptr<CharStream>> result;
+	unsigned index = 0;
+	for (auto const& s: m_sources)
+		result[index++] = s.second.scanner->charStream();
+
+	// NB: CompilerContext::yulUtilityFileName() does not have a source,
+	result[index++] = shared_ptr<CharStream>{};
+
+	return result;
+}
+
 Json::Value const& CompilerStack::contractABI(string const& _contractName) const
 {
 	if (m_stackState < AnalysisPerformed)

libsolidity/interface/CompilerStack.h

@@ -239,6 +239,10 @@ public:
 	/// by sourceNames().
 	std::map<std::string, unsigned> sourceIndices() const;
 
+	/// @returns the reverse mapping of source indices to their respective
+	/// CharStream instances.
+	std::map<unsigned, std::shared_ptr<langutil::CharStream>> indicesToCharStreams() const;
+
 	/// @returns the previously used scanner, useful for counting lines during error reporting.
 	langutil::Scanner const& scanner(std::string const& _sourceName) const;
 

libyul/AsmParser.cpp

@@ -29,9 +29,12 @@
 #include <libsolutil/Common.h>
 #include <libsolutil/Visitor.h>
 
+#include <range/v3/view/subrange.hpp>
+
 #include <boost/algorithm/string.hpp>
 
 #include <algorithm>
+#include <regex>
 
 using namespace std;
 using namespace solidity;
@@ -53,6 +56,18 @@ shared_ptr<DebugData const> updateLocationEndFrom(
 	return make_shared<DebugData const>(updatedLocation);
 }
 
+optional<int> toInt(string const& _value)
+{
+	try
+	{
+		return stoi(_value);
+	}
+	catch (...)
+	{
+		return nullopt;
+	}
+}
+
 }
 
 unique_ptr<Block> Parser::parse(std::shared_ptr<Scanner> const& _scanner, bool _reuseScanner)
@@ -65,6 +80,8 @@ unique_ptr<Block> Parser::parse(std::shared_ptr<Scanner> const& _scanner, bool _
 	try
 	{
 		m_scanner = _scanner;
+		if (m_charStreamMap)
+			fetchSourceLocationFromComment();
 		auto block = make_unique<Block>(parseBlock());
 		if (!_reuseScanner)
 			expectToken(Token::EOS);
@@ -78,6 +95,57 @@ unique_ptr<Block> Parser::parse(std::shared_ptr<Scanner> const& _scanner, bool _
 	return nullptr;
 }
 
+langutil::Token Parser::advance()
+{
+	auto const token = ParserBase::advance();
+	if (m_useSourceLocationFrom == UseSourceLocationFrom::Comments)
+		fetchSourceLocationFromComment();
+	return token;
+}
+
+void Parser::fetchSourceLocationFromComment()
+{
+	solAssert(m_charStreamMap.has_value(), "");
+
+	if (m_scanner->currentCommentLiteral().empty())
+		return;
+
+	static regex const lineRE = std::regex(
+		R"~~~((^|\s*)@src\s+(-1|\d+):(-1|\d+):(-1|\d+)(\s+|$))~~~",
+		std::regex_constants::ECMAScript | std::regex_constants::optimize
+	);
+
+	string const text = m_scanner->currentCommentLiteral();
+	auto from = sregex_iterator(text.begin(), text.end(), lineRE);
+	auto to = sregex_iterator();
+
+	for (auto const& matchResult: ranges::make_subrange(from, to))
+	{
+		solAssert(matchResult.size() == 6, "");
+
+		auto const sourceIndex = toInt(matchResult[2].str());
+		auto const start = toInt(matchResult[3].str());
+		auto const end = toInt(matchResult[4].str());
+
+		auto const commentLocation = m_scanner->currentCommentLocation();
+		m_debugDataOverride = DebugData::create();
+		if (!sourceIndex || !start || !end)
+			m_errorReporter.syntaxError(6367_error, commentLocation, "Invalid value in source location mapping. Could not parse location specification.");
+		else if (!((*start < 0 && *end < 0) || (*start >= 0 && *start <= *end)))
+			m_errorReporter.syntaxError(5798_error, commentLocation, "Invalid value in source location mapping. Start offset larger than end offset.");
+		else if (sourceIndex == -1 && (0 <= *start && *start <= *end)) // Use source index -1 to indicate original source.
+			m_debugDataOverride = DebugData::create(SourceLocation{*start, *end, ParserBase::currentLocation().source});
+		else if (!(sourceIndex >= 0 && m_charStreamMap->count(static_cast<unsigned>(*sourceIndex))))
+			m_errorReporter.syntaxError(2674_error, commentLocation, "Invalid source mapping. Source index not defined via @use-src.");
+		else
+		{
+			shared_ptr<CharStream> charStream = m_charStreamMap->at(static_cast<unsigned>(*sourceIndex));
+			solAssert(charStream, "");
+			m_debugDataOverride = DebugData::create(SourceLocation{*start, *end, charStream});
+		}
+	}
+}
+
 Block Parser::parseBlock()
 {
 	RecursionGuard recursionGuard(*this);
@@ -85,7 +153,8 @@ Block Parser::parseBlock()
 	expectToken(Token::LBrace);
 	while (currentToken() != Token::RBrace)
 		block.statements.emplace_back(parseStatement());
-	block.debugData = updateLocationEndFrom(block.debugData, currentLocation());
+	if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+		block.debugData = updateLocationEndFrom(block.debugData, currentLocation());
 	advance();
 	return block;
 }
@@ -107,7 +176,8 @@ Statement Parser::parseStatement()
 		advance();
 		_if.condition = make_unique<Expression>(parseExpression());
 		_if.body = parseBlock();
-		_if.debugData = updateLocationEndFrom(_if.debugData, _if.body.debugData->location);
+		if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+			_if.debugData = updateLocationEndFrom(_if.debugData, _if.body.debugData->location);
 		return Statement{move(_if)};
 	}
 	case Token::Switch:
@@ -125,7 +195,8 @@ Statement Parser::parseStatement()
 			fatalParserError(4904_error, "Case not allowed after default case.");
 		if (_switch.cases.empty())
 			fatalParserError(2418_error, "Switch statement without any cases.");
-		_switch.debugData = updateLocationEndFrom(_switch.debugData, _switch.cases.back().body.debugData->location);
+		if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+			_switch.debugData = updateLocationEndFrom(_switch.debugData, _switch.cases.back().body.debugData->location);
 		return Statement{move(_switch)};
 	}
 	case Token::For:
@@ -207,7 +278,8 @@ Statement Parser::parseStatement()
 		expectToken(Token::AssemblyAssign);
 
 		assignment.value = make_unique<Expression>(parseExpression());
-		assignment.debugData = updateLocationEndFrom(assignment.debugData, locationOf(*assignment.value));
+		if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+			assignment.debugData = updateLocationEndFrom(assignment.debugData, locationOf(*assignment.value));
 
 		return Statement{move(assignment)};
 	}
@@ -237,7 +309,8 @@ Case Parser::parseCase()
 	else
 		yulAssert(false, "Case or default case expected.");
 	_case.body = parseBlock();
-	_case.debugData = updateLocationEndFrom(_case.debugData, _case.body.debugData->location);
+	if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+		_case.debugData = updateLocationEndFrom(_case.debugData, _case.body.debugData->location);
 	return _case;
 }
 
@@ -257,7 +330,8 @@ ForLoop Parser::parseForLoop()
 	forLoop.post = parseBlock();
 	m_currentForLoopComponent = ForLoopComponent::ForLoopBody;
 	forLoop.body = parseBlock();
-	forLoop.debugData = updateLocationEndFrom(forLoop.debugData, forLoop.body.debugData->location);
+	if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+		forLoop.debugData = updateLocationEndFrom(forLoop.debugData, forLoop.body.debugData->location);
 
 	m_currentForLoopComponent = outerForLoopComponent;
 
@@ -296,7 +370,7 @@ variant<Literal, Identifier> Parser::parseLiteralOrIdentifier()
 	{
 	case Token::Identifier:
 	{
-		Identifier identifier{DebugData::create(currentLocation()), YulString{currentLiteral()}};
+		Identifier identifier{createDebugData(), YulString{currentLiteral()}};
 		advance();
 		return identifier;
 	}
@@ -327,7 +401,7 @@ variant<Literal, Identifier> Parser::parseLiteralOrIdentifier()
 		}
 
 		Literal literal{
-			DebugData::create(currentLocation()),
+			createDebugData(),
 			kind,
 			YulString{currentLiteral()},
 			kind == LiteralKind::Boolean ? m_dialect.boolType : m_dialect.defaultType
@@ -336,7 +410,8 @@ variant<Literal, Identifier> Parser::parseLiteralOrIdentifier()
 		if (currentToken() == Token::Colon)
 		{
 			expectToken(Token::Colon);
-			literal.debugData = updateLocationEndFrom(literal.debugData, currentLocation());
+			if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+				literal.debugData = updateLocationEndFrom(literal.debugData, currentLocation());
 			literal.type = expectAsmIdentifier();
 		}
 
@@ -368,9 +443,10 @@ VariableDeclaration Parser::parseVariableDeclaration()
 	{
 		expectToken(Token::AssemblyAssign);
 		varDecl.value = make_unique<Expression>(parseExpression());
-		varDecl.debugData = updateLocationEndFrom(varDecl.debugData, locationOf(*varDecl.value));
+		if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+			varDecl.debugData = updateLocationEndFrom(varDecl.debugData, locationOf(*varDecl.value));
 	}
-	else
+	else if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
 		varDecl.debugData = updateLocationEndFrom(varDecl.debugData, varDecl.variables.back().debugData->location);
 
 	return varDecl;
@@ -417,7 +493,8 @@ FunctionDefinition Parser::parseFunctionDefinition()
 	m_insideFunction = true;
 	funDef.body = parseBlock();
 	m_insideFunction = preInsideFunction;
-	funDef.debugData = updateLocationEndFrom(funDef.debugData, funDef.body.debugData->location);
+	if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+		funDef.debugData = updateLocationEndFrom(funDef.debugData, funDef.body.debugData->location);
 
 	m_currentForLoopComponent = outerForLoopComponent;
 	return funDef;
@@ -444,7 +521,8 @@ FunctionCall Parser::parseCall(variant<Literal, Identifier>&& _initialOp)
 			ret.arguments.emplace_back(parseExpression());
 		}
 	}
-	ret.debugData = updateLocationEndFrom(ret.debugData, currentLocation());
+	if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+		ret.debugData = updateLocationEndFrom(ret.debugData, currentLocation());
 	expectToken(Token::RParen);
 	return ret;
 }
@@ -457,7 +535,8 @@ TypedName Parser::parseTypedName()
 	if (currentToken() == Token::Colon)
 	{
 		expectToken(Token::Colon);
-		typedName.debugData = updateLocationEndFrom(typedName.debugData, currentLocation());
+		if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+			typedName.debugData = updateLocationEndFrom(typedName.debugData, currentLocation());
 		typedName.type = expectAsmIdentifier();
 	}
 	else

libyul/AsmParser.h

@@ -23,6 +23,7 @@
 
 #pragma once
 
+#include <libyul/AST.h>
 #include <libyul/ASTForward.h>
 #include <libyul/Dialect.h>
 
@@ -45,6 +46,11 @@ public:
 		None, ForLoopPre, ForLoopPost, ForLoopBody
 	};
 
+	enum class UseSourceLocationFrom
+	{
+		Scanner, LocationOverride, Comments,
+	};
+
 	explicit Parser(
 		langutil::ErrorReporter& _errorReporter,
 		Dialect const& _dialect,
@@ -52,7 +58,27 @@ public:
 	):
 		ParserBase(_errorReporter),
 		m_dialect(_dialect),
-		m_locationOverride(std::move(_locationOverride))
+		m_locationOverride{_locationOverride ? *_locationOverride : langutil::SourceLocation{}},
+		m_debugDataOverride{},
+		m_useSourceLocationFrom{
+			_locationOverride ?
+			UseSourceLocationFrom::LocationOverride :
+			UseSourceLocationFrom::Scanner
+		}
+	{}
+
+	/// Constructs a Yul parser that is using the source locations
+	/// from the comments (via @src).
+	explicit Parser(
+		langutil::ErrorReporter& _errorReporter,
+		Dialect const& _dialect,
+		std::map<unsigned, std::shared_ptr<langutil::CharStream>> _charStreamMap
+	):
+		ParserBase(_errorReporter),
+		m_dialect(_dialect),
+		m_charStreamMap{std::move(_charStreamMap)},
+		m_debugDataOverride{DebugData::create()},
+		m_useSourceLocationFrom{UseSourceLocationFrom::Comments}
 	{}
 
 	/// Parses an inline assembly block starting with `{` and ending with `}`.
@@ -63,14 +89,35 @@ public:
 protected:
 	langutil::SourceLocation currentLocation() const override
 	{
-		return m_locationOverride ? *m_locationOverride : ParserBase::currentLocation();
+		if (m_useSourceLocationFrom == UseSourceLocationFrom::Scanner)
+			return ParserBase::currentLocation();
+		return m_locationOverride;
+	}
+
+	langutil::Token advance() override;
+
+	void fetchSourceLocationFromComment();
+
+	/// Creates a DebugData object with the correct source location set.
+	std::shared_ptr<DebugData const> createDebugData() const
+	{
+		switch (m_useSourceLocationFrom)
+		{
+			case UseSourceLocationFrom::Scanner:
+				return DebugData::create(ParserBase::currentLocation());
+			case UseSourceLocationFrom::LocationOverride:
+				return DebugData::create(m_locationOverride);
+			case UseSourceLocationFrom::Comments:
+				return m_debugDataOverride;
+		}
+		solAssert(false, "");
 	}
 
 	/// Creates an inline assembly node with the current source location.
 	template <class T> T createWithLocation() const
 	{
 		T r;
-		r.debugData = DebugData::create(currentLocation());
+		r.debugData = createDebugData();
 		return r;
 	}
 
@@ -96,7 +143,11 @@ protected:
 
 private:
 	Dialect const& m_dialect;
-	std::optional<langutil::SourceLocation> m_locationOverride;
+
+	std::optional<std::map<unsigned, std::shared_ptr<langutil::CharStream>>> m_charStreamMap;
+	langutil::SourceLocation m_locationOverride;
+	std::shared_ptr<DebugData const> m_debugDataOverride;
+	UseSourceLocationFrom m_useSourceLocationFrom = UseSourceLocationFrom::Scanner;
 	ForLoopComponent m_currentForLoopComponent = ForLoopComponent::None;
 	bool m_insideFunction = false;
 };

scripts/error_codes.py

@@ -191,6 +191,9 @@ def examine_id_coverage(top_dir, source_id_to_file_names, new_ids_only=False):
 
     # white list of ids which are not covered by tests
     white_ids = {
+        "6367", # these three are temporarily whitelisted until both PRs are merged.
+        "5798",
+        "2674",
         "3805", # "This is a pre-release compiler version, please do not use it in production."
                 # The warning may or may not exist in a compiler build.
         "4591", # "There are more than 256 warnings. Ignoring the rest."

test/libyul/Parser.cpp

@@ -51,12 +51,25 @@ namespace solidity::yul::test
 namespace
 {
 
+string_view constexpr g_strAlternateSourceText = "{}";
+
 shared_ptr<Block> parse(string const& _source, Dialect const& _dialect, ErrorReporter& errorReporter)
 {
 	try
 	{
 		auto scanner = make_shared<Scanner>(CharStream(_source, ""));
-		auto parserResult = yul::Parser(errorReporter, _dialect).parse(scanner, false);
+		map<unsigned, shared_ptr<CharStream>> indicesToCharStreams;
+		indicesToCharStreams[0] = scanner->charStream();
+		indicesToCharStreams[1] = make_shared<CharStream>(
+			string(g_strAlternateSourceText.data(), g_strAlternateSourceText.size()),
+			"alternate.sol"
+		);
+
+		auto parserResult = yul::Parser(
+			errorReporter,
+			_dialect,
+			move(indicesToCharStreams)
+		).parse(scanner, false);
 		if (parserResult)
 		{
 			yul::AsmAnalysisInfo analysisInfo;
@@ -187,7 +200,383 @@ BOOST_AUTO_TEST_CASE(default_types_set)
 	);
 }
 
+#define CHECK_LOCATION(_actual, _sourceText, _start, _end) \
+	do { \
+		BOOST_CHECK_EQUAL((_sourceText), ((_actual).source ? (_actual).source->source() : "")); \
+		BOOST_CHECK_EQUAL((_start), (_actual).start); \
+		BOOST_CHECK_EQUAL((_end), (_actual).end); \
+	} while (0)
 
+BOOST_AUTO_TEST_CASE(customSourceLocations_empty_block)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"/// @src 0:234:543\n"
+		"{}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	CHECK_LOCATION(result->debugData->location, sourceText, 234, 543);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_block_with_children)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"/// @src 0:234:543\n"
+		"{\n"
+			"let x:bool := true:bool\n"
+			"/// @src 0:123:432\n"
+			"let z:bool := true\n"
+			"let y := add(1, 2)\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	CHECK_LOCATION(result->debugData->location, sourceText, 234, 543);
+	BOOST_REQUIRE_EQUAL(3, result->statements.size());
+	CHECK_LOCATION(locationOf(result->statements.at(0)), sourceText, 234, 543);
+	CHECK_LOCATION(locationOf(result->statements.at(1)), sourceText, 123, 432);
+	// [2] is inherited source location
+	CHECK_LOCATION(locationOf(result->statements.at(2)), sourceText, 123, 432);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_block_different_sources)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"/// @src 0:234:543\n"
+		"{\n"
+			"let x:bool := true:bool\n"
+			"/// @src 1:123:432\n"
+			"let z:bool := true\n"
+			"let y := add(1, 2)\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	CHECK_LOCATION(result->debugData->location, sourceText, 234, 543);
+	BOOST_REQUIRE_EQUAL(3, result->statements.size());
+	CHECK_LOCATION(locationOf(result->statements.at(0)), sourceText, 234, 543);
+	CHECK_LOCATION(locationOf(result->statements.at(1)), g_strAlternateSourceText, 123, 432);
+	// [2] is inherited source location
+	CHECK_LOCATION(locationOf(result->statements.at(2)), g_strAlternateSourceText, 123, 432);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_block_nested)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"/// @src 0:234:543\n"
+		"{\n"
+			"let y := add(1, 2)\n"
+			"/// @src 0:343:434\n"
+			"switch y case 0 {} default {}\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	CHECK_LOCATION(result->debugData->location, sourceText, 234, 543);
+	BOOST_REQUIRE_EQUAL(2, result->statements.size());
+	CHECK_LOCATION(locationOf(result->statements.at(1)), sourceText, 343, 434);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_block_switch_case)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"/// @src 0:234:543\n"
+		"{\n"
+			"let y := add(1, 2)\n"
+			"/// @src 0:343:434\n"
+			"switch y\n"
+			"/// @src 0:3141:59265\n"
+			"case 0 {\n"
+			"    /// @src 0:271:828\n"
+			"    let z := add(3, 4)\n"
+			"}\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	CHECK_LOCATION(result->debugData->location, sourceText, 234, 543);
+
+	BOOST_REQUIRE_EQUAL(2, result->statements.size());
+	BOOST_REQUIRE(holds_alternative<Switch>(result->statements.at(1)));
+	auto const& switchStmt = get<Switch>(result->statements.at(1));
+
+	CHECK_LOCATION(switchStmt.debugData->location, sourceText, 343, 434);
+	BOOST_REQUIRE_EQUAL(1, switchStmt.cases.size());
+	CHECK_LOCATION(switchStmt.cases.at(0).debugData->location, sourceText, 3141, 59265);
+
+	auto const& caseBody = switchStmt.cases.at(0).body;
+	BOOST_REQUIRE_EQUAL(1, caseBody.statements.size());
+	CHECK_LOCATION(locationOf(caseBody.statements.at(0)), sourceText, 271, 828);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_inherit_into_outer_scope)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"/// @src 0:1:100\n"
+		"{\n"
+			"{\n"
+				"/// @src 0:123:432\n"
+				"let x:bool := true:bool\n"
+			"}\n"
+			"let z:bool := true\n"
+			"let y := add(1, 2)\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+
+	CHECK_LOCATION(result->debugData->location, sourceText, 1, 100);
+
+	BOOST_REQUIRE_EQUAL(3, result->statements.size());
+	CHECK_LOCATION(locationOf(result->statements.at(0)), sourceText, 1, 100);
+
+	// First child element must be a block itself with one statement.
+	BOOST_REQUIRE(holds_alternative<Block>(result->statements.at(0)));
+	BOOST_REQUIRE_EQUAL(get<Block>(result->statements.at(0)).statements.size(), 1);
+	CHECK_LOCATION(locationOf(get<Block>(result->statements.at(0)).statements.at(0)), sourceText, 123, 432);
+
+	// The next two elements have an inherited source location from the prior inner scope.
+	CHECK_LOCATION(locationOf(result->statements.at(1)), sourceText, 123, 432);
+	CHECK_LOCATION(locationOf(result->statements.at(2)), sourceText, 123, 432);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_assign_empty)
+{
+	// Tests single AST node (e.g. VariableDeclaration) with different source locations for each child.
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"{\n"
+			"/// @src 0:123:432\n"
+			"let a:bool\n"
+			"/// @src 1:1:10\n"
+			"a := true:bool\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result); // should still parse
+	BOOST_REQUIRE_EQUAL(2, result->statements.size());
+	CHECK_LOCATION(locationOf(result->statements.at(0)), sourceText, 123, 432);
+	CHECK_LOCATION(locationOf(result->statements.at(1)), g_strAlternateSourceText, 1, 10);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_invalid_source_index)
+{
+	// Tests single AST node (e.g. VariableDeclaration) with different source locations for each child.
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"{\n"
+			"/// @src 1:123:432\n"
+			"let a:bool := true:bool\n"
+			"/// @src 2345:0:8\n"
+			"let b:bool := true:bool\n"
+			"\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result); // should still parse
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_mixed_locations_1)
+{
+	// Tests single AST node (e.g. VariableDeclaration) with different source locations for each child.
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText =
+		"{\n"
+			"/// @src 0:123:432\n"
+			"let x:bool \n"
+			"/// @src 0:234:2026\n"
+			":= true:bool\n"
+		"}\n";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+
+	BOOST_REQUIRE_EQUAL(1, result->statements.size());
+	CHECK_LOCATION(locationOf(result->statements.at(0)), sourceText, 123, 432);
+	BOOST_REQUIRE(holds_alternative<VariableDeclaration>(result->statements.at(0)));
+	VariableDeclaration const& varDecl = get<VariableDeclaration>(result->statements.at(0));
+	CHECK_LOCATION(locationOf(*varDecl.value), sourceText, 234, 2026);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_mixed_locations_2)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText = R"(
+		/// @src 0:0:5
+		{
+			let x := /// @src 1:2:3
+			add(1,   /// @src 0:4:8
+			2)
+		}
+	)";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	BOOST_REQUIRE_EQUAL(1, result->statements.size());
+	CHECK_LOCATION(result->debugData->location, sourceText, 0, 5);
+
+	// `let x := add(1, `
+	BOOST_REQUIRE(holds_alternative<VariableDeclaration>(result->statements.at(0)));
+	VariableDeclaration const& varDecl = get<VariableDeclaration>(result->statements.at(0));
+	CHECK_LOCATION(varDecl.debugData->location, sourceText, 0, 5);
+	BOOST_REQUIRE(!!varDecl.value);
+	BOOST_REQUIRE(holds_alternative<FunctionCall>(*varDecl.value));
+	FunctionCall const& call = get<FunctionCall>(*varDecl.value);
+	CHECK_LOCATION(call.debugData->location, g_strAlternateSourceText, 2, 3);
+
+	// `2`
+	BOOST_REQUIRE_EQUAL(2, call.arguments.size());
+	CHECK_LOCATION(locationOf(call.arguments.at(1)), sourceText, 4, 8);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_mixed_locations_3)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText = R"(
+		/// @src 1:23:45
+		{								// Block
+			{							// Block
+				sstore(0, 1)			// FunctionCall
+				/// @src 0:420:680
+			}
+			mstore(1, 2)				// FunctionCall
+		}
+	)";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	BOOST_REQUIRE_EQUAL(2, result->statements.size());
+	CHECK_LOCATION(result->debugData->location, g_strAlternateSourceText, 23, 45);
+
+	BOOST_REQUIRE(holds_alternative<Block>(result->statements.at(0)));
+	Block const& innerBlock = get<Block>(result->statements.at(0));
+	CHECK_LOCATION(innerBlock.debugData->location, g_strAlternateSourceText, 23, 45);
+
+	BOOST_REQUIRE_EQUAL(1, innerBlock.statements.size());
+	BOOST_REQUIRE(holds_alternative<ExpressionStatement>(result->statements.at(1)));
+	ExpressionStatement const& sstoreStmt = get<ExpressionStatement>(innerBlock.statements.at(0));
+	BOOST_REQUIRE(holds_alternative<FunctionCall>(sstoreStmt.expression));
+	FunctionCall const& sstoreCall = get<FunctionCall>(sstoreStmt.expression);
+	CHECK_LOCATION(sstoreCall.debugData->location, g_strAlternateSourceText, 23, 45);
+
+	BOOST_REQUIRE(holds_alternative<ExpressionStatement>(result->statements.at(1)));
+	ExpressionStatement mstoreStmt = get<ExpressionStatement>(result->statements.at(1));
+	BOOST_REQUIRE(holds_alternative<FunctionCall>(mstoreStmt.expression));
+	FunctionCall const& mstoreCall = get<FunctionCall>(mstoreStmt.expression);
+	CHECK_LOCATION(mstoreCall.debugData->location, sourceText, 420, 680);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_invalid_comments_after_valid)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText = R"(
+		/// @src 1:23:45
+		{
+			/// @src 0:420:680
+			/// @invalid
+			let a:bool := true
+		}
+	)";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	BOOST_REQUIRE_EQUAL(1, result->statements.size());
+	CHECK_LOCATION(result->debugData->location, g_strAlternateSourceText, 23, 45);
+
+	BOOST_REQUIRE(holds_alternative<VariableDeclaration>(result->statements.at(0)));
+	VariableDeclaration const& varDecl = get<VariableDeclaration>(result->statements.at(0));
+	CHECK_LOCATION(varDecl.debugData->location, sourceText, 420, 680);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_invalid_suffix)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText = R"(
+		/// @src 0:420:680foo
+		{}
+	)";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	CHECK_LOCATION(result->debugData->location, "", -1, -1);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_unspecified)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText = R"(
+		/// @src -1:-1:-1
+		{}
+	)";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	CHECK_LOCATION(result->debugData->location, "", -1, -1);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_ensure_last_match)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText = R"(
+		/// @src 0:123:432
+		{
+			/// @src 1:10:20
+			/// @src 0:30:40
+			let x:bool := true
+		}
+	)";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	BOOST_REQUIRE(holds_alternative<VariableDeclaration>(result->statements.at(0)));
+	VariableDeclaration const& varDecl = get<VariableDeclaration>(result->statements.at(0));
+
+	// Ensure the latest @src per documentation-comment is used (0:30:40).
+	CHECK_LOCATION(varDecl.debugData->location, sourceText, 30, 40);
+}
+
+BOOST_AUTO_TEST_CASE(customSourceLocations_reference_original_sloc)
+{
+	ErrorList errorList;
+	ErrorReporter reporter(errorList);
+	auto const sourceText = R"(
+		/// @src 1:2:3
+		{
+			/// @src -1:10:20
+			let x:bool := true
+		}
+	)";
+	EVMDialectTyped const& dialect = EVMDialectTyped::instance(EVMVersion{});
+	shared_ptr<Block> result = parse(sourceText, dialect, reporter);
+	BOOST_REQUIRE(!!result);
+	BOOST_REQUIRE(holds_alternative<VariableDeclaration>(result->statements.at(0)));
+	VariableDeclaration const& varDecl = get<VariableDeclaration>(result->statements.at(0));
+
+	// -1 points to original source code, which in this case is `sourceText` (which is also
+	// available via `0`, that's why the first @src is set to `1` instead.)
+	CHECK_LOCATION(varDecl.debugData->location, sourceText, 10, 20);
+}
 
 BOOST_AUTO_TEST_SUITE_END()