validator

Orchestrator and public entry point for the world validator. Composes the sibling vfsScanner, scriptValidator, assetValidator, and reportFormatter modules into one require-able surface. This is the module the toolbox tools pull in to do their work.

Exports

• M.check(opts?) -> Report — full pass (world + every library).
• M.validateWorld(opts?) -> Report — only /source/ minus libs/.
• M.validateLibraries(opts?) -> Report — every library under /source/libs/.
• M.validateLibrary(name, opts?) -> Report — one named library; reports library.missing if absent.
• M.filter(report, opts) -> Report — re-filter a built report.
• M.format(report, format?) -> string — render to human / markdown / json / summary.
• M.summary(report) -> string — one-line summary.
• M.saveReport(report, path, opts?) -> ok, message? — write the rendered report to path (format inferred from extension when not set).
• M.placeholders() -> { { code, reason } } — the list of intentional placeholder checks the validator currently runs.

Report shape

{
    ok           = boolean,
    generatedAt  = unix_seconds,
    durationMs   = number,
    scope        = "all" | "world" | "libraries" | "library:<name>",
    counts       = { error, warning, info, placeholder },
    world        = Bucket | nil,        -- nil when the scope excluded the world
    libraries    = { [name]: Bucket },  -- keyed by library name (e.g. "@builtin")
    placeholders = { { code, reason } },
    truncated    = boolean,             -- true if `opts.limit` was reached
}

Each Bucket:

{
    problems       = { Problem, … },
    counts         = { error, warning, info, placeholder },
    scriptsScanned = number,
    assetsScanned  = number,
}

A Problem:

{
    severity = "error" | "warning" | "info",
    category = "structure" | "syntax" | "semantic"
             | "reference" | "schema" | "placeholder",
    code     = "<short.code>",
    path     = "<vfs path>",
    message  = "<one-line reason>",
    source   = "world" | "library:<name>",
    placeholder = boolean,
}

Usage

From outside the package — use the canonical or package-alias identity:

local V = require("@builtin::~worldValidation.validator")
-- or the canonical form:
-- local V = require("@builtin::systems.worldValidation.validator")

-- Full pass
local r = V.check()
print(V.summary(r))                       -- one line
if not r.ok then print(V.format(r)) end   -- detailed only on failure

-- Filtered: errors only, no placeholders, world only
local errs = V.validateWorld({
    severity = "error",
    includePlaceholders = false,
})

-- Save a markdown report
V.saveReport(errs, "/source/.validation/last-run.md")

-- Re-filter an existing report without re-scanning
local libsOnly = V.filter(r, { source = "library:@builtin" })

From inside the package, prefer the ~ package-relative form so the require keeps resolving if the package is moved:

local V = require("~.validator")

Placeholders

Every layer is served by a real primitive: Luau syntax and type-check by lsp.check(path) inside scriptValidator, asset structure / content / semantics by asset.validate inside assetValidator. M.placeholders() returns the list of stub checks — currently empty. A future check that lands before its engine primitive registers here so the gap stays visible in every report.

Notes

• Validation is single-frame and synchronous. A full pass over a large world takes O(filesInSource) vfs.list + vfs.read calls.
• The validator does not mutate world state. saveReport writes only to the destination path the caller supplied.
• Hot reload: edits to this module or any of its dependencies reload on the next require.