Module:Dependencies
From Shroudforge
More actions
Documentation for this module may be created at Module:Dependencies/doc
require('strict')
--- @module Dependencies
--- The folded "Technical details" panel Module:Documentation shows on module and
--- template pages: which pages use the page, what it uses, and the functions a
--- module defines; and the `dependencies` Bucket row each page writes so the
--- modules and stylesheets it uses can list it. Forward lists come from the
--- page's own source; reverse lists come from the rows other pages wrote.
local parse = require('Module:Dependencies/Parse')
local mbox = require('Module:Mbox')
local icon = require('Module:Icon')
local yesno = require('Module:Yesno')
local p = {}
local BUCKET = 'dependencies'
local NS_TEMPLATE = 10
local NS_MODULE = 828
local HEADING = 'Technical details'
local ICON = 'WikimediaUI-Code.svg'
local ROW_ICONS = {
source = 'CdxIconReference.svg',
usedBy = 'CdxIconArrowPrevious.svg',
uses = 'CdxIconArrowNext.svg',
functions = 'CdxIconFunction.svg',
}
local UNUSED_TEXT = 'No template invokes it and no module requires or loads it. '
.. 'If an article invokes it directly, call it through a template instead.'
local UNAVAILABLE_TEXT = 'Unavailable: looking up the pages that use it failed on this render. '
.. 'Purge the page to retry.'
--- @class DependenciesContext
--- @field title string the documented page, e.g. `Module:Mbox`
--- @field prefix string its namespace with the colon, e.g. `Module:`
--- @field namespace integer
--- @field content string|nil its source
--- @field isCurrent boolean the render is the page itself, not its /doc or another page
--- @field excluded boolean a sandbox or testcases page, whose dependencies are not real usage
--- @class DependenciesGroup
--- @field label string e.g. `Required by`
--- @field items string[] wikitext, one per list item
--- @field note string|nil wikitext under the list
--- @field modifier string|nil the list's `t-dependencies__list--` modifier
--- @class DependenciesReport
--- @field usedBy DependenciesGroup[]|nil nil when the reverse lookup failed
--- @field uses DependenciesGroup[]
--- @field usedByCount integer distinct pages across `usedBy`
--- @field usesCount integer entries across `uses`
--- @field unused boolean a module nothing invokes, requires or loads
--- @field functions ModuleTocFunction[]
--- @class DependenciesSource
--- @field label string plain text for the folded header, e.g. `wiki-tools`
--- @field text string wikitext, one line of the Source row
--- @class DependenciesPanelOptions
--- @field page string|nil the page to describe; default the current page, or the page a /doc documents
--- @field addCategories boolean|string|nil defaults to true except on a /doc render
--- @field sources DependenciesSource[]|nil
--- @param title table mw.title
--- @return boolean
local function isExcluded(title)
local text = title.text:lower()
return text:find('^sandbox/') ~= nil or text:find('/sandbox') ~= nil or text:find('/testcases') ~= nil
end
--- @param pageName string|nil
--- @return DependenciesContext|nil
local function context(pageName)
local current = mw.title.getCurrentTitle()
local target = pageName and mw.title.new(pageName) or current
if target == nil then
return nil
end
if target.isSubpage and target.subpageText:lower() == 'doc' then
target = target.basePageTitle
end
if target.namespace ~= NS_TEMPLATE and target.namespace ~= NS_MODULE then
return nil
end
return {
title = target.prefixedText,
prefix = target.prefixedText:match('^[^:]+:'),
namespace = target.namespace,
content = target:getContent(),
isCurrent = current.prefixedText == target.prefixedText,
excluded = isExcluded(target),
}
end
--- @param list any
--- @param value string
--- @return boolean
local function contains(list, value)
for _, item in ipairs(type(list) == 'table' and list or {}) do
if item == value then
return true
end
end
return false
end
--- `files` with the files `extra` names added.
--- @param files DependenciesFiles
--- @param extra DependenciesFiles
--- @return DependenciesFiles
local function mergeFiles(files, extra)
local merged = { names = {}, urls = {}, dynamic = {} }
for _, key in ipairs({ 'names', 'dynamic' }) do
local seen = {}
for _, list in ipairs({ files[key], extra[key] }) do
for _, value in ipairs(list) do
if not seen[value] then
seen[value] = true
merged[key][#merged[key] + 1] = value
end
end
end
table.sort(merged[key])
end
local seen = {}
for _, list in ipairs({ files.urls, extra.urls }) do
for _, url in ipairs(list) do
local key = url.name .. '|' .. url.path
if not seen[key] then
seen[key] = true
merged.urls[#merged.urls + 1] = url
end
end
end
return merged
end
--- What the page itself uses: a module's requires, loads, stylesheets and
--- files, a template's invokes, stylesheets and files. The files include those
--- the page's own `/styles.css` names when the page loads it; any other
--- stylesheet lists its files on the page that owns it.
--- @param ctx DependenciesContext
--- @return table
local function forward(ctx)
local found
if ctx.namespace == NS_MODULE then
found = parse.lua(ctx.content)
found.invokes = {}
else
found = {
requires = {},
loads = {},
dynamic = {},
strict = false,
invokes = parse.invokes(ctx.content),
styles = parse.styles(ctx.content),
files = parse.files(ctx.content),
}
end
local own = ctx.title .. '/styles.css'
local stylesheet = contains(found.styles, own) and mw.title.new(own)
local css = stylesheet and stylesheet:getContent()
if css then
found.files = mergeFiles(found.files, parse.stylesheetFiles(css))
end
return found
end
--- The page's `dependencies` row, or nil when it uses nothing.
--- @param found table
--- @return table|nil
local function rowFor(found)
local invokes, calls, seen = {}, {}, {}
for _, call in ipairs(found.invokes) do
if not seen[call.module] then
seen[call.module] = true
invokes[#invokes + 1] = call.module
end
calls[#calls + 1] = call.module .. '|' .. call.func
end
local row = {}
local function set(field, list)
if list[1] ~= nil then
row[field] = list
end
end
set('requires', found.requires)
set('loads', found.loads)
set('invokes', invokes)
set('invoke_calls', calls)
set('styles', found.styles)
if next(row) == nil then
return nil
end
return row
end
--- @param ctx DependenciesContext
--- @param found table
local function write(ctx, found)
if not ctx.isCurrent or ctx.excluded then
return
end
local row = rowFor(found)
if row == nil then
return
end
pcall(function()
mw.ext.bucket(BUCKET).put(row)
end)
end
--- Splits the rows naming `title` into the pages that invoke, require and load
--- it, and the pages that load its `/styles.css`.
--- @param rows table[] raw Bucket rows keyed by field name (page_name, requires, loads, invokes, invoke_calls, styles)
--- @param title string
--- @return { invokedBy: { page: string, funcs: string[] }[], requiredBy: string[], loadedBy: string[], styledBy: string[] }
local function group(rows, title)
local back = { invokedBy = {}, requiredBy = {}, loadedBy = {}, styledBy = {} }
local prefix = title .. '|'
local stylesheet = title .. '/styles.css'
for _, row in ipairs(rows) do
local page = row.page_name
if page and page ~= title then
if contains(row.invokes, title) then
local funcs, seen = {}, {}
for _, call in ipairs(type(row.invoke_calls) == 'table' and row.invoke_calls or {}) do
local func = call:sub(1, #prefix) == prefix and call:sub(#prefix + 1) or nil
if func and not seen[func] then
seen[func] = true
funcs[#funcs + 1] = func
end
end
back.invokedBy[#back.invokedBy + 1] = { page = page, funcs = funcs }
end
if contains(row.requires, title) then
back.requiredBy[#back.requiredBy + 1] = page
end
if contains(row.loads, title) then
back.loadedBy[#back.loadedBy + 1] = page
end
if contains(row.styles, stylesheet) then
back.styledBy[#back.styledBy + 1] = page
end
end
end
table.sort(back.invokedBy, function(a, b)
return a.page < b.page
end)
table.sort(back.requiredBy)
table.sort(back.loadedBy)
table.sort(back.styledBy)
return back
end
--- The pages that use `title`, or nil when the lookup failed.
--- Queries Bucket directly: Module:BucketQuery would load and link every
--- manifest registered ahead of this one on each documentation render.
--- @param title string
--- @return table|nil
local function reverse(title)
local ok, rows = pcall(function()
local bucket = mw.ext.bucket
return bucket(BUCKET)
.select('page_name', 'requires', 'loads', 'invokes', 'invoke_calls', 'styles')
.where(
bucket.Or(
{ 'requires', title },
{ 'loads', title },
{ 'invokes', title },
{ 'styles', title .. '/styles.css' }
)
)
.limit(5000)
.run()
end)
if not ok or type(rows) ~= 'table' then
return nil
end
return group(rows, title)
end
--- @param text string
--- @return string
local function code(text)
return '<code>' .. mw.text.nowiki(text) .. '</code>'
end
--- A link to `name` as a row shows it: one of the documented page's own subpages
--- relative (`/styles.css`), otherwise without `prefix`, the namespace the row
--- already implies.
--- @param name string
--- @param ctx DependenciesContext
--- @param prefix string
--- @return string
local function link(name, ctx, prefix)
local own = ctx.title .. '/'
local text = name
if name:sub(1, #own) == own then
text = name:sub(#own)
elseif name:sub(1, #prefix) == prefix then
text = name:sub(#prefix + 1)
end
if text == name then
return '[[' .. name .. ']]'
end
return '[[' .. name .. '|' .. text .. ']]'
end
--- @param names string[]
--- @param ctx DependenciesContext
--- @param prefix string
--- @return string[]
local function links(names, ctx, prefix)
local items = {}
for i, name in ipairs(names) do
items[i] = link(name, ctx, prefix)
end
return items
end
--- The templates that invoke the page, each with the functions it calls. When
--- every one calls the same single function, the note names it once instead.
--- @param entries { page: string, funcs: string[] }[]
--- @param ctx DependenciesContext
--- @return string[] items
--- @return string|nil note
local function invokers(entries, ctx)
local shared = entries[1] and entries[1].funcs[1]
for _, entry in ipairs(entries) do
if #entry.funcs ~= 1 or entry.funcs[1] ~= shared then
shared = nil
break
end
end
local items = {}
for i, entry in ipairs(entries) do
items[i] = link(entry.page, ctx, 'Template:')
if shared == nil and entry.funcs[1] ~= nil then
local funcs = {}
for j, func in ipairs(entry.funcs) do
funcs[j] = code(func)
end
items[i] = items[i] .. ' (' .. table.concat(funcs, ', ') .. ')'
end
end
if shared == nil then
return items, nil
end
return items, (#entries > 1 and 'All via ' or 'Via ') .. code(shared)
end
--- @param into DependenciesGroup[]
--- @param label string
--- @param items string[]
--- @param note string|nil
--- @param modifier string|nil
local function addGroup(into, label, items, note, modifier)
if items[1] ~= nil then
into[#into + 1] = { label = label, items = items, note = note, modifier = modifier }
end
end
--- What is wrong with each media URL, by file name: a path that is not the
--- md5 directories of the name, or a file that has moved, which `[[File:]]`
--- follows but a URL does not.
--- @param urls DependenciesFileUrl[]
--- @return table<string, string[]>
local function urlProblems(urls)
local problems, checked = {}, {}
local function add(name, text)
problems[name] = problems[name] or {}
problems[name][#problems[name] + 1] = text
end
for _, url in ipairs(urls) do
local md5 = mw.hash.hashValue('md5', (url.name:gsub(' ', '_')))
local expected = md5:sub(1, 1) .. '/' .. md5:sub(1, 2)
if url.path ~= expected then
add(url.name, 'URL path ' .. code(url.path) .. ' should be ' .. code(expected))
end
if not checked[url.name] then
checked[url.name] = true
-- isRedirect is an expensive lookup: past the page's limit it throws.
local ok, target = pcall(function()
local title = mw.title.new('File:' .. url.name)
return title and title.isRedirect and title.redirectTarget
end)
if ok and target then
add(url.name, 'moved to [[:File:' .. target.text .. '|' .. target.text .. ']], update the URL')
end
end
end
return problems
end
--- The Files group's items. On the page itself each name follows a thumbnail,
--- which records the file as used by the page; anywhere else (its /doc, a
--- sandbox) the name alone, so only the page whose source names a file is
--- recorded as using it.
--- @param files DependenciesFiles
--- @param ctx DependenciesContext
--- @return string[]
local function fileItems(files, ctx)
local thumbnails = ctx.isCurrent and not ctx.excluded
local problems = urlProblems(files.urls)
local items = {}
for _, name in ipairs(files.names) do
local item = '[[:File:' .. name .. '|' .. name .. ']]'
if thumbnails then
-- The wiki recolours most icons, so an SVG shows as a silhouette in the text
-- colour: styles.css blackens it and `skin-invert` whitens it on a dark theme.
local class = name:lower():find('%.svg$') and 't-dependencies__thumb t-dependencies__thumb--svg skin-invert'
or 't-dependencies__thumb'
item = '<span class="' .. class .. '">[[File:' .. name .. '|20x20px|link=|alt=]]</span>' .. item
end
if problems[name] then
item = item
.. ' <span class="t-dependencies__warning">('
.. table.concat(problems[name], '; ')
.. ')</span>'
end
items[#items + 1] = item
end
for _, pattern in ipairs(files.dynamic) do
items[#items + 1] = code(pattern)
end
return items
end
--- @param back table
--- @return integer
local function countPages(back)
local seen, count = {}, 0
local function add(page)
if not seen[page] then
seen[page] = true
count = count + 1
end
end
for _, entry in ipairs(back.invokedBy) do
add(entry.page)
end
for _, key in ipairs({ 'requiredBy', 'loadedBy', 'styledBy' }) do
for _, page in ipairs(back[key]) do
add(page)
end
end
return count
end
--- What the panel shows for the page, before any markup.
--- @param ctx DependenciesContext
--- @param found table forward()'s result
--- @param back table|nil reverse()'s result; nil when the lookup failed
--- @return DependenciesReport
local function report(ctx, found, back)
local uses, usesCount = {}, 0
if ctx.namespace == NS_TEMPLATE then
local calls = {}
for i, call in ipairs(found.invokes) do
calls[i] = code(call.func) .. ' in [[' .. call.module .. ']]'
end
addGroup(uses, 'Invokes', calls)
usesCount = #calls
else
local requires = links(found.requires, ctx, 'Module:')
for _, pattern in ipairs(found.dynamic) do
requires[#requires + 1] = code(pattern)
end
addGroup(uses, 'Requires', requires)
addGroup(uses, 'Loads', links(found.loads, ctx, 'Module:'))
usesCount = #requires + #found.loads
end
addGroup(uses, 'Styles', links(found.styles, ctx, ctx.prefix))
addGroup(uses, 'Files', fileItems(found.files, ctx), nil, 'files')
usesCount = usesCount + #found.styles + #found.files.names + #found.files.dynamic
local result = {
uses = uses,
usesCount = usesCount,
usedByCount = 0,
unused = false,
functions = {},
}
if back ~= nil then
local usedBy = {}
local items, note = invokers(back.invokedBy, ctx)
addGroup(usedBy, 'Invoked by', items, note)
addGroup(usedBy, 'Required by', links(back.requiredBy, ctx, 'Module:'))
addGroup(usedBy, 'Loaded by', links(back.loadedBy, ctx, 'Module:'))
addGroup(usedBy, 'Styles used by', links(back.styledBy, ctx, ctx.prefix))
result.usedBy = usedBy
result.usedByCount = countPages(back)
result.unused = ctx.namespace == NS_MODULE
and not ctx.excluded
and back.invokedBy[1] == nil
and back.requiredBy[1] == nil
and back.loadedBy[1] == nil
end
if ctx.namespace == NS_MODULE then
-- Required here, not at the top: every page records the modules it loads
-- and re-parses when one changes, and template pages never need this one.
result.functions = require('Module:Module toc').functions(ctx.content)
end
return result
end
--- @param ctx DependenciesContext
--- @param found table
--- @param result DependenciesReport
--- @return string
local function categories(ctx, found, result)
local out = {}
if ctx.namespace == NS_TEMPLATE and found.invokes[1] ~= nil then
out[#out + 1] = '[[Category:Lua-based templates]]'
end
if ctx.namespace == NS_MODULE and found.strict then
out[#out + 1] = '[[Category:Strict mode modules]]'
end
if result.unused then
out[#out + 1] = '[[Category:Unused modules]]'
end
return table.concat(out)
end
--- @param addCategories boolean|string|nil
--- @return boolean
local function categoriesEnabled(addCategories)
-- Yesno's `default` only covers an unrecognised string, not a nil argument
-- (a #invoke omitting the parameter, or a Lua caller passing nothing).
local enabled = yesno(addCategories)
if enabled == nil then
local current = mw.title.getCurrentTitle()
return not (current.isSubpage and current.subpageText:lower() == 'doc')
end
return enabled == true
end
--- @param items string[]
--- @param modifier string|nil
--- @return table mw.html
local function list(items, modifier)
local root = mw.html.create('ul'):addClass('t-dependencies__list')
if modifier then
root:addClass('t-dependencies__list--' .. modifier)
end
for _, item in ipairs(items) do
root:tag('li'):wikitext(item)
end
return root
end
--- @param groups DependenciesGroup[]
--- @return string
local function groupsHtml(groups)
local root = mw.html.create('div'):addClass('t-dependencies__groups')
for _, entry in ipairs(groups) do
root:tag('div')
:addClass('t-dependencies__sublabel')
:wikitext(entry.label)
:tag('span')
:addClass('t-dependencies__count')
:wikitext(#entry.items)
local body = root:tag('div'):addClass('t-dependencies__items'):node(list(entry.items, entry.modifier))
if entry.note then
body:tag('div'):addClass('t-dependencies__note'):wikitext(entry.note)
end
end
return tostring(root)
end
--- @param title string
--- @param functions ModuleTocFunction[]
--- @return string
local function functionsHtml(title, functions)
local items = {}
for i, func in ipairs(functions) do
items[i] = string.format(
'[[%s#L-%d|%s]]<span class="t-dependencies__line">L%d</span>',
title,
func.line,
mw.text.nowiki(func.name),
func.line
)
end
return tostring(list(items, 'code'))
end
--- @param label string
--- @param file string
--- @param content string wikitext
--- @param modifier string|nil
--- @return string
local function row(label, file, content, modifier)
local root = mw.html.create('div'):addClass('t-dependencies__row')
if modifier then
root:addClass('t-dependencies__row--' .. modifier)
end
root:tag('div')
:addClass('t-dependencies__label')
:wikitext(icon.render({ icon = file, mask = true, size = '1em', class = 't-dependencies__icon' }))
:wikitext(label)
root:tag('div'):addClass('t-dependencies__content'):wikitext(content)
return tostring(root)
end
--- The folded header: the heading, then plain-text facts. It sits inside
--- <summary>, so it must hold no link.
--- @param facts string[]
--- @param unused boolean
--- @return string
local function summary(facts, unused)
local root = mw.html.create('span'):addClass('t-dependencies__summary')
root:tag('span'):addClass('t-dependencies__heading'):wikitext(HEADING)
if unused or facts[1] ~= nil then
local meta = root:tag('span'):addClass('t-dependencies__meta')
if unused then
meta:tag('span'):addClass('t-dependencies__chip'):wikitext('Unused')
end
if facts[1] ~= nil then
meta:tag('span'):wikitext(table.concat(facts, ' · '))
end
end
return tostring(root)
end
--- The panel for `options.page`, followed by its categories. Writes the page's
--- row when the render is the page itself.
--- @param options DependenciesPanelOptions|nil
--- @return string
function p.panel(options)
options = options or {}
local rows, facts, unused, cats = {}, {}, false, ''
local lines = {}
for _, source in ipairs(options.sources or {}) do
lines[#lines + 1] = '<div>' .. source.text .. '</div>'
facts[#facts + 1] = source.label
end
if lines[1] ~= nil then
rows[#rows + 1] = row('Source', ROW_ICONS.source, table.concat(lines))
end
local ctx = context(options.page)
if ctx ~= nil and ctx.content ~= nil then
local found = forward(ctx)
write(ctx, found)
local back = reverse(ctx.title)
local result = report(ctx, found, back)
unused = result.unused
if unused then
local content = '<div>' .. UNUSED_TEXT .. '</div>'
if result.usedBy[1] ~= nil then
content = content .. groupsHtml(result.usedBy)
end
rows[#rows + 1] = row('Used by', ROW_ICONS.usedBy, content, 'warning')
elseif back == nil then
if ctx.namespace == NS_MODULE then
rows[#rows + 1] = row('Used by', ROW_ICONS.usedBy, UNAVAILABLE_TEXT, 'muted')
end
elseif result.usedBy[1] ~= nil then
rows[#rows + 1] = row('Used by', ROW_ICONS.usedBy, groupsHtml(result.usedBy))
facts[#facts + 1] = 'used by ' .. result.usedByCount
end
if result.uses[1] ~= nil then
rows[#rows + 1] = row('Uses', ROW_ICONS.uses, groupsHtml(result.uses))
facts[#facts + 1] = 'uses ' .. result.usesCount
end
if result.functions[1] ~= nil then
rows[#rows + 1] = row('Functions', ROW_ICONS.functions, functionsHtml(ctx.title, result.functions))
end
if categoriesEnabled(options.addCategories) then
cats = categories(ctx, found, result)
end
end
if rows[1] == nil then
return cats
end
local frame = mw.getCurrentFrame()
-- Module:Icon leaves its stylesheet to the caller; the row icons need it.
local styles = frame:extensionTag({ name = 'templatestyles', args = { src = 'Module:Icon/styles.css' } })
.. frame:extensionTag({ name = 'templatestyles', args = { src = 'Module:Dependencies/styles.css' } })
return styles
.. mbox.render({
title = summary(facts, unused),
text = table.concat(rows),
icon = ICON,
class = 't-dependencies',
})
.. cats
end
--- `{{#invoke:Dependencies|main}}`, for MediaWiki:Scribunto-doc-page-does-not-exist.
--- @param frame table
--- @return string
function p.main(frame)
return p.panel()
end
-- Test-only exports. Not part of the public API.
p._internal = {
group = group,
report = report,
rowFor = rowFor,
}
return p