Modul:Entity/Contract
Aus Star Citizen Wiki
Weitere Optionen
Die Dokumentation für dieses Modul kann unter Modul:Entity/Contract/doc erstellt werden
require('strict')
--- @module Entity/Contract
--- The Entity component contract as data + a checker. Defines, per role, which
--- lifecycle hooks exist and which are required, and validates a component
--- module against a role. Used by the registry conformance test so a mis-wired
--- kind or facet fails a unit test rather than silently no-opping on-wiki.
---
--- Roles: CONTRIBUTOR (every chain link), KIND (identity + contributor), FACET.
local p = {}
--- Contributor: the hook set every chain link (Base, a kind, a subtype leaf)
--- may implement. Every hook is optional — a link implements only what it
--- adds. How each hook's answers combine across the chain is
--- Module:Entity/Assembly.POLICIES, applied by Assembly.run; its test fails
--- when a hook declared here has no policy there.
--- @type table<string, boolean>
p.CONTRIBUTOR = {
getSections = false,
getStructuredData = false,
getStructuredRows = false,
getShortDescription = false,
getExternalSiteItems = false,
getFooterButtons = false,
getMetadataItems = false,
getTypeInfo = false,
getApiConfigs = false,
getSubtitle = false,
getTitleAnnotation = false,
getHeaderBadge = false,
enrich = false,
getEditorialManifest = false,
getCategories = false,
getAcquisition = false,
getRelated = false,
getBlueprints = false,
getPorts = false,
}
--- Chain link is the contributor role under its older name; kept so existing
--- callers (the Location leaf conformance test) keep validating.
p.CHAIN_LINK = p.CONTRIBUTOR
--- Kind identity: what a registered kind owns beyond being a contributor.
--- `matches` + `getApiConfigs` identify it (the probe and the declared-kind
--- gate); `resolveSubtype` refines it to a leaf.
--- @type table<string, boolean>
p.KIND_IDENTITY = {
matches = true,
getApiConfigs = true,
resolveSubtype = false,
}
--- Kind: identity plus every contributor hook, built from the two specs so the
--- three can never drift. getApiConfigs is required here (identity) even
--- though a plain contributor may omit it.
--- @type table<string, boolean>
p.KIND = {}
for hook, required in pairs(p.CONTRIBUTOR) do
p.KIND[hook] = required
end
for hook, required in pairs(p.KIND_IDENTITY) do
p.KIND[hook] = required
end
--- Non-function KIND fields with declared scalar types. validate() rejects any
--- non-function spec key, so typed scalar fields — the canonical kind `name`, the
--- `editorialMode` opt-in and the `hasManufacturer` flag — live here and are
--- checked by validateFields(), run alongside validate() by the Registry
--- conformance test.
--- @type table<string, { type: string, required: boolean }>
p.KIND_FIELDS = {
name = { type = 'string', required = true },
editorialMode = { type = 'boolean', required = false },
hasManufacturer = { type = 'boolean', required = false },
}
--- Facet: a cross-cutting additive aspect matched on a data field.
--- @type table<string, boolean>
p.FACET = {
matches = true,
getSections = true,
getStructuredData = false,
getShortDescriptionPrefix = false,
}
--- Union of every hook name across all role specs; used by validate()'s strict
--- pass to distinguish a misspelled hook from one valid in a different role.
--- @type table<string, boolean>
p.ALL_HOOKS = {}
for _, spec in ipairs({ p.KIND, p.FACET, p.CHAIN_LINK }) do
for hook in pairs(spec) do
p.ALL_HOOKS[hook] = true
end
end
--- Validates a component against a role spec. Each required hook must be present
--- and a function; each present spec-hook must be a function. Unknown keys are
--- not flagged (modules expose legitimate public helpers), so a misspelled
--- optional hook is not caught — required hooks are.
---
--- "Required" means the role is inert without that hook (the conformance gate),
--- NOT that a caller throws — Entity.lua still guards each call with `if mod.x`.
--- The contract is deliberately stricter than the lenient runtime: a facet with
--- no getSections wouldn't crash, but it would do nothing, so it's a wiring bug.
---
--- @param component table The module to check
--- @param spec table<string, boolean> A role spec (p.KIND / p.FACET / p.CHAIN_LINK)
--- @param options nil|{ strict: boolean } When strict, also flag component keys that look like a misspelled hook (a function whose name is not in spec and not in p.ALL_HOOKS). Default: off (byte-identical to the pre-PR1 behavior).
--- @return boolean ok True when there are no errors
--- @return string[] errors Human-readable messages (empty when ok)
function p.validate(component, spec, options)
if type(component) ~= 'table' then
return false, { 'component is not a table (got ' .. type(component) .. ')' }
end
local errors = {}
for hook, required in pairs(spec) do
local value = component[hook]
if value == nil then
if required then
table.insert(errors, 'missing required hook: ' .. hook)
end
elseif type(value) ~= 'function' then
table.insert(errors, 'hook is not a function: ' .. hook .. ' (got ' .. type(value) .. ')')
end
end
if options and options.strict then
for key, value in pairs(component) do
if
type(value) == 'function'
and spec[key] == nil
and not p.ALL_HOOKS[key]
and (key:find('^get') or key == 'matches' or key == 'resolveSubtype' or key == 'enrich')
then
table.insert(errors, 'unknown hook (typo?): ' .. key)
end
end
end
return #errors == 0, errors
end
--- Validates a chain's editorial manifest fragments against the merge policy.
--- Module:Entity/Assembly.mergeEditorialManifests replaces a whole field entry
--- when a later link redeclares the field, so a redeclaration that leaves out a
--- key an earlier link set drops that key: a missing `property` still renders
--- the value but never stores it, and no render or unit test of the leaf alone
--- notices. A link redeclares an inherited field only to add to it, repeating
--- every key the earlier entry set.
---
--- @param chain table[] Root-first chain (Module:Entity/Assembly.buildChain)
--- @return boolean ok True when no redeclaration drops a key
--- @return string[] errors Human-readable messages (empty when ok)
function p.validateEditorialChain(chain)
local seen, errors = {}, {}
for i, link in ipairs(chain) do
local fragment = link.getEditorialManifest and link.getEditorialManifest()
if type(fragment) == 'table' then
for field, def in pairs(fragment) do
local prior = seen[field]
if type(prior) == 'table' and type(def) == 'table' then
for key in pairs(prior) do
if def[key] == nil then
table.insert(
errors,
'link #' .. i .. " redeclares '" .. field .. "' without the inherited '" .. key .. "'"
)
end
end
end
seen[field] = def
end
end
end
return #errors == 0, errors
end
--- Validates a component's non-function declared fields against a field spec.
--- Each required field must be present and of the declared type; each present
--- field must match its declared type. Complements validate() (function hooks)
--- for scalar fields like `name` and `editorialMode`.
---
--- @param component table The module to check
--- @param fieldSpec table<string, { type: string, required: boolean }>
--- @return boolean ok True when there are no errors
--- @return string[] errors Human-readable messages (empty when ok)
function p.validateFields(component, fieldSpec)
if type(component) ~= 'table' then
return false, { 'component is not a table (got ' .. type(component) .. ')' }
end
local errors = {}
for field, decl in pairs(fieldSpec) do
local value = component[field]
if value == nil then
if decl.required then
table.insert(errors, 'missing required field: ' .. field)
end
elseif type(value) ~= decl.type then
table.insert(
errors,
'field has wrong type: ' .. field .. ' (expected ' .. decl.type .. ', got ' .. type(value) .. ')'
)
end
end
return #errors == 0, errors
end
return p