DiffAPI.lua

--[[

# DiffAPI

This function is used to get the differences between to API versions.

## Usage

The DiffAPI function expects two API dumps that have been generated by
ParseAPI or LexAPI.

	local DiffAPI = require 'DiffAPI'

	local oldDump = LexAPI(oldSource)
	local newDump = LexAPI(newSource)

	local diff = DiffAPI(oldDump, newDump)

DiffAPI returns a table containing the differences between the two versions.
The format of this table is described here:

https://github.com/Anaminus/roblox-api-dump/wiki/API-diff-format

## More Info

https://github.com/Anaminus/roblox-api-dump

]]

-- Check if two lists of arguments match. If not, return a copy of the newer
-- list.
local function argDiff(a,b)
	local equal = true
	if #a ~= #b then
		equal = false
	else
		for i = 1,#a do
			if a[i].Name ~= b[i].Name or a[i].Type ~= b[i].Type or a[i].Default ~= b[i].Default then
				equal = false
				break
			end
		end
	end

	if not equal then
		local copy = {}
		for i = 1,#b do
			local arg = b[i]
			copy[i] = {Type=arg.Type, Name=arg.Name, Default=arg.Default}
		end
		return copy
	else
		return nil
	end
end

-- Returns an immutable identifer for the given item.
local function itemName(item)
	if item.Class then
		return item.Class .. '.' .. item.Name
	elseif item.type == 'EnumItem' then
		return item.Enum .. '.' .. item.Name
	else
		return item.Name
	end
end

-- Return hash table of dump list, so that items are easily comparable.
local function getRef(dump)
	local ref = {}

	for i = 1,#dump do
		local item = dump[i]
		ref[item.type .. ' ' .. itemName(item)] = item
	end

	return ref
end

return function(a,b)
	local diffs = {}

	-- compare mutable fields of two items for changes, per item type
	local compare = {}

	function compare.Class(a,b)
		if b.Superclass ~= a.Superclass then
			diffs[#diffs+1] = {0,'Superclass',a,b.Superclass}
		end
	end

	function compare.Property(a,b)
		if b.ValueType ~= a.ValueType then
			diffs[#diffs+1] = {0,'ValueType',a,b.ValueType}
		end
	end

	function compare.Function(a,b)
		if b.ReturnType ~= a.ReturnType then
			diffs[#diffs+1] = {0,'ReturnType',a,b.ReturnType}
		end
		local d = argDiff(a.Arguments,b.Arguments)
		if d then
			diffs[#diffs+1] = {0,'Arguments',a,d}
		end
	end

	compare.YieldFunction = compare.Function

	compare.Callback = compare.Function

	function compare.Event(a,b)
		local d = argDiff(a.Arguments,b.Arguments)
		if d then
			diffs[#diffs+1] = {0,'Arguments',a,d}
		end
	end

	function compare.Enum(a,b)

	end

	function compare.EnumItem(a,b)
		if a.Value ~= b.Value then
			diffs[#diffs+1] = {0,'Value',a,b.Value}
		end
	end

	local aref = getRef(a)
	local bref = getRef(b)

	-- Do initial search through table, looking for added/removed classes and
	-- enums. This will be used later to exclude their members/enumitems from
	-- the top-level diff list, which would also be added/removed.
	local addClass = {}
	local delClass = {}

	local addEnum = {}
	local delEnum = {}

	for name,item in pairs(bref) do
		if not aref[name] then
			if item.type == 'Class' then
				local list = {}
				addClass[item.Name] = list
				-- Add the difference right now. Since the member list is
				-- referenced, it will be populated later.
				diffs[#diffs+1] = {1,'Class',item,list}
			elseif item.type == 'Enum' then
				local list = {}
				addEnum[item.Name] = list
				diffs[#diffs+1] = {1,'Enum',item,list}
			end
		end
	end
	for name,item in pairs(aref) do
		if not bref[name] then
			if item.type == 'Class' then
				local list = {}
				delClass[item.Name] = list
				diffs[#diffs+1] = {-1,'Class',item,list}
			elseif item.type == 'Enum' then
				local list = {}
				delEnum[item.Name] = list
				diffs[#diffs+1] = {-1,'Enum',item,list}
			end
		end
	end

	local secTag = {
		['LocalUserSecurity'] = true;
		['RobloxSecurity'] = true;
		['RobloxPlaceSecurity'] = true;
		['RobloxScriptSecurity'] = true;
		['WritePlayerSecurity'] = true;
	}

	for name,item in pairs(bref) do
		local aitem = aref[name]
		if aitem then
			-- item exists in both `a` and `b`, so compare them for changes
			compare[item.type](aitem,item)

			-- Security tags are (hopefully) mutually exclusive, so we'll
			-- detect them as a change in security level, instead of the
			-- removal of one tag, and the addition of another.
			local secAdd,secRem
			for tag in pairs(item.tags) do
				if not aitem.tags[tag] then
					if secTag[tag] then
						secAdd = tag
					else
						diffs[#diffs+1] = {1,'Tag',aitem,tag}
					end
				end
			end
			for tag in pairs(aitem.tags) do
				if not item.tags[tag] then
					if secTag[tag] then
						secRem = tag
					else
						diffs[#diffs+1] = {-1,'Tag',aitem,tag}
					end
				end
			end
			if secAdd or secRem then
				-- secAdd or secRem may be nil, which can be interpreted as no
				-- security
				diffs[#diffs+1] = {0,'Security',aitem,secRem,secAdd}
			end
		else
			-- Item does not exist in `a`, which means it was added.
			if item.Class then
				-- If the item is a member, check to see if it was added
				-- because its class was added.
				local list = addClass[item.Class]
				if list then
					-- If so, then add it do that class's member list, which
					-- will be included with the class's diff struct.
					list[#list+1] = item
				else
					-- If not, then the member is an addition to an existing
					-- class.
					diffs[#diffs+1] = {1,'Item',item}
				end
			elseif item.type == 'EnumItem' then
				-- Same thing as members, but for enumitems.
				local list = addEnum[item.Enum]
				if list then
					list[#list+1] = item
				else
					diffs[#diffs+1] = {1,'Item',item}
				end
			elseif item.type ~= 'Class' and item.type ~= 'Enum' then
				-- Classes and Enum were already added to the diff list.
				diffs[#diffs+1] = {1,'Item',item}
			end
		end
	end
	-- detect removals
	for name,item in pairs(aref) do
		if not bref[name] then
			if item.Class then
				local list = delClass[item.Class]
				if list then
					list[#list+1] = item
				else
					diffs[#diffs+1] = {-1,'Item',item}
				end
			elseif item.type == 'EnumItem' then
				local list = delEnum[item.Enum]
				if list then
					list[#list+1] = item
				else
					diffs[#diffs+1] = {-1,'Item',item}
				end
			elseif item.type ~= 'Class' and item.type ~= 'Enum' then
				diffs[#diffs+1] = {-1,'Item',item}
			end
		end
	end

	local typeSort = {
		Class = 1;
		Property = 2;
		Function = 3;
		YieldFunction = 4;
		Event = 5;
		Callback = 6;
		Enum = 7;
		EnumItem = 8;
	}

	-- Diffs will probably be sorted in some way by the user, but it's nice to
	-- have a consistent order to begin with. Because these are generated from
	-- hash tables, they may not be the same every time. Sorts by diff type,
	-- then item type, then item name.
	table.sort(diffs,function(a,b)
		if a[1] == b[1] then
			if a[3].type == b[3].type then
				return itemName(a[3]) < itemName(b[3])
			else
				return typeSort[a[3].type] < typeSort[b[3].type]
			end
		else
			return a[1] > b[1]
		end
	end)

	-- Also sort the member and enumitem lists.
	local function sort(a,b)
		if a.type == b.type then
			return a.Name < b.Name
		else
			return typeSort[a.type] < typeSort[b.type]
		end
	end
	for _,list in pairs(addClass) do
		table.sort(list,sort)
	end
	for _,list in pairs(delClass) do
		table.sort(list,sort)
	end

	local function sort(a,b)
		return a.Value < b.Value
	end
	for _,list in pairs(addEnum) do
		table.sort(list,sort)
	end
	for _,list in pairs(delEnum) do
		table.sort(list,sort)
	end

	return diffs
end