-- Display assertion for the report when a test fails.
-- New format: rejects/resolves, not, and matcher name have black color
-- Old format: matcher name has dim color

function matcherHint(matcherName: string, received: string?, expected: string?, options: MatcherHintOptions?): string
	received = received or "received"
	expected = expected or "expected"
	options = options or {}

	--[[
		ROBLOX TODO: Remove the "if options" check once it can pass through
		Luau cleanly and define all of the variables in-line i.e.
		local comment = options.comment or ""
	]]
	local comment, expectedColor, isDirectExpectCall, isNot, promise, receivedColor, secondArgument, secondArgumentColor
	if options then
		comment = options.comment or ""
		expectedColor = options.expectedColor or EXPECTED_COLOR
		isDirectExpectCall = options.isDirectExpectCall or false
		isNot = options.isNot or false
		promise = options.promise or ""
		receivedColor = options.receivedColor or RECEIVED_COLOR
		secondArgument = options.secondArgument or ""
		secondArgumentColor = options.secondArgumentColor or EXPECTED_COLOR
	end

	local hint = ""
	local dimString = "expect" -- concatenate adjacent dim substrings

	if not isDirectExpectCall and received ~= "" then
		hint = hint .. DIM_COLOR(dimString .. "(") .. receivedColor(received)
		dimString = ")"
	end

	if promise ~= "" then
		hint = hint .. DIM_COLOR(dimString .. ".") .. promise
		dimString = ""
	end

	if isNot then
		hint = hint .. DIM_COLOR(dimString .. ".") .. "never"
		dimString = ""
	end

	if string.find(matcherName, "%.") then
		-- Old format: for backward compatibility,
		-- especially without promise or isNot options
		dimString = dimString .. matcherName
	else
		-- New format: omit period from matcherName arg
		hint = hint .. DIM_COLOR(dimString .. ".") .. matcherName
		dimString = ""
	end

	if expected == "" then
		dimString = dimString .. "()"
	else
		hint = hint .. DIM_COLOR(dimString .. "(") .. expectedColor(expected)
		if secondArgument ~= "" then
			hint = hint .. DIM_COLOR(", ") .. secondArgumentColor(secondArgument)
		end
		dimString = ")"
	end

	if comment ~= "" then
		dimString = dimString .. " -- " .. comment
	end

	if dimString ~= "" then
		hint = hint .. DIM_COLOR(dimString)
	end

	return hint
end

return {
	EXPECTED_COLOR = EXPECTED_COLOR,
	RECEIVED_COLOR = RECEIVED_COLOR,
	INVERTED_COLOR = INVERTED_COLOR,
	BOLD_WEIGHT = BOLD_WEIGHT,
	DIM_COLOR = DIM_COLOR,

	SUGGEST_TO_CONTAIN_EQUAL = SUGGEST_TO_CONTAIN_EQUAL,

	stringify = stringify,
	highlightTrailingWhitespace = highlightTrailingWhitespace,
	printReceived = printReceived,
	printExpected = printExpected,
	printWithType = printWithType,
	ensureNoExpected = ensureNoExpected,
	ensureActualIsNumber = ensureActualIsNumber,
	ensureExpectedIsNumber = ensureExpectedIsNumber,
	ensureNumbers = ensureNumbers,
	ensureExpectedIsNonNegativeInteger = ensureExpectedIsNonNegativeInteger,
	printDiffOrStringify = printDiffOrStringify,
	diff = diff,
	pluralize = pluralize,
	getLabelPrinter = getLabelPrinter,
	matcherErrorMessage = matcherErrorMessage,
	matcherHint = matcherHint,
}
