@axpecter/lync 2.3.3 → 3.0.0

package/shape/Legality.luau

@@ -0,0 +1,273 @@
+--!strict
+--!optimize 2
+-- What a start will take: the declaration a definition is, and every test made of one.
+
+local Base = require (script.Parent.Parent.codec.Base)
+local Folds = require (script.Parent.Folds)
+local Grid = require (script.Parent.Grid)
+local Joins = require (script.Parent.Joins)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Order = require (script.Parent.Order)
+local Protocol = require (script.Parent.Parent.wire.Protocol)
+local Scalars = require (script.Parent.Parent.codec.Scalars)
+local Serial = require (script.Parent.Serial)
+local Types = require (script.Parent.Parent.Types)
+
+local Legality = {}
+
+-- Constants -----------------------------------------------------------
+
+-- What a set replicates, and how many of its fields one dirty mask covers.
+const RECORD: Base.Kind = "struct"
+const FIELDS = Protocol.MAX_FIELDS
+
+-- The widest leaf a bit run carries, which is the line one computation may not fall across.
+const CEILING = Protocol.BIT_CEILING
+
+-- How far a double counts exactly, which is what a grid's span has to stay under.
+const REACH = Protocol.EXACT
+
+-- What one fire of the lossy lane carries, which is the ceiling a block on it stays under.
+const CAP = Protocol.UNRELIABLE_CAP
+
+-- The punctuation the descriptor grammar separates a namespace with, which no name may hold.
+const SPELLED = table.freeze ({ ";", "=" })
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    Where a definition was written, which is the one fact a refusal here carries that a caller
+    cannot work out for themselves. A start legality is raised inside a compile and a compile runs a
+    long way from the line that declared the thing, so a message without this says a schema is wrong
+    and leaves finding it to a search.
+]]
+export type Site = { read file: string, read line: number }
+
+-- A definition as its caller declared it, which is what they said rather than what it means.
+export type Packet = {
+    read kind: "packet",
+    read of: Types.Codec<any>,
+    read isUnreliable: boolean,
+    read isNewest: boolean,
+    read hz: number?,
+    read isTimestamped: boolean,
+    read at: Site,
+}
+
+export type Query = {
+    read kind: "query",
+    read of: Types.Codec<any>,
+    read reply: Types.Codec<any>,
+    read at: Site,
+}
+
+export type Set = {
+    read kind: "set",
+    read of: Types.Codec<any>,
+    read keyField: string?,
+    read at: Site,
+}
+
+export type Declared = Packet | Query | Set
+
+-- Private -------------------------------------------------------------
+
+-- A refusal, as the one line whoever wrote the schema reads.
+local function refuse (name: string, at: Site, said: string): never
+    return Log.refuse (`{name} {said}, declared at {at.file}:{at.line}`)
+end
+
+-- The first node under here carrying a state marker, and the marker it carries.
+local function marked (of: Base.Cell, at: string): (string?, Base.Marker)
+    if of.marker ~= "none" then return at, of.marker end
+
+    local children = of.children
+    if children == nil then return nil, "none" end
+
+    for _, name in Order.names (children) do
+        local where, mark = marked (children[name], Serial.under (at, name))
+        if where ~= nil then return where, mark end
+    end
+    return nil, "none"
+end
+
+-- How many points a declaration's grid holds, where a division decides that rather than a count.
+local function points (of: Base.Cell): number?
+    local kind, params = of.kind, of.params
+
+    if kind == "int" then return (params.max :: number) - (params.min :: number) end
+    if kind == "quant" then
+        return ((params.max :: number) - (params.min :: number)) / (params.step :: number)
+    end
+    if kind == "angle" then return Scalars.TURN / (params.step :: number) end
+    return nil
+end
+
+-- Whether one computation's leaves fall either side of the bit run's ceiling.
+local function straddles (of: Base.Cell): boolean
+    local fold = Folds.fold (of)
+    if fold == nil then return false end
+
+    local under, over = false, false
+    for _, grid in fold.leaves do
+        if grid.width > CEILING then
+            over = true
+        else
+            under = true
+        end
+    end
+    return under and over
+end
+
+-- What one node declares that its constructor could not refuse, as the clause a message reads.
+local function imprecise (of: Base.Cell, at: string): string?
+    local span = points (of)
+    if span ~= nil and span >= REACH then
+        return `declares {at} over {span} points, which is past what a double counts exactly`
+    end
+
+    if of.kind == "angle" then
+        local step = of.params.step :: number
+        if not Grid.divides (Scalars.TURN, step) then
+            return `declares {at} to {step} degrees, which does not divide a turn`
+        end
+    end
+
+    if not straddles (of) then return nil end
+    return `declares {at} to a precision whose parts fall either side of {CEILING} bits`
+end
+
+-- Every node of a tree, in the one order a walk of this library visits children in.
+local function imprecision (of: Base.Cell, at: string): string?
+    local said = imprecise (of, at)
+    if said ~= nil then return said end
+
+    local children = of.children
+    if children == nil then return nil end
+
+    for _, name in Order.names (children) do
+        local under = imprecision (children[name], Serial.under (at, name))
+        if under ~= nil then return under end
+    end
+    return nil
+end
+
+-- A tree carrying no state between frames, which is every tree outside a set.
+local function stateless (name: string, at: Site, what: string, of: Base.Cell, root: string)
+    local where, mark = marked (of, root)
+    if where ~= nil then
+        refuse (name, at, `declares {mark} at {where}, and {what} keeps nothing to differ from`)
+    end
+
+    local why = imprecision (of, root)
+    if why == nil then return end
+    refuse (name, at, why)
+end
+
+-- A record a set replicates, and the four things a set decides about it that nothing else does.
+local function replicated (name: string, at: Site, of: Set)
+    local cell = Base.cell (of.of)
+    if cell.kind ~= RECORD then
+        refuse (name, at, `replicates a {cell.kind}, and a set replicates records`)
+    end
+
+    local fields = cell.children :: { [string]: Base.Cell }
+    local names = Order.names (fields)
+    local reach = #names
+
+    if reach == 0 then refuse (name, at, "replicates a record of no fields") end
+    if reach > FIELDS then
+        refuse (name, at, `replicates {reach} fields, and one dirty mask covers {FIELDS}`)
+    end
+
+    for _, field in names do
+        local children = fields[field].children
+        if children == nil then continue end
+
+        local under = Serial.under (name, field)
+        for _, inner in Order.names (children) do
+            local where, mark = marked (children[inner], Serial.under (under, inner))
+            if where == nil then continue end
+            refuse (name, at, `declares {mark} at {where}, and a set deltas its own fields`)
+        end
+    end
+
+    local why = imprecision (cell, name)
+    if why ~= nil then refuse (name, at, why) end
+
+    local key = of.keyField
+    if key == nil then return end
+
+    local held = fields[key]
+    if held == nil then
+        refuse (name, at, `is keyed by {key}, which its record does not declare`)
+    end
+
+    if held.marker == "newest" then
+        refuse (name, at, `is keyed by {key} and declares newest on it, and a key has to arrive`)
+    end
+
+    if Joins.grid (held) ~= nil then return end
+    refuse (name, at, `is keyed by {key}, and its {held.kind} is not one number to partition by`)
+end
+
+-- Public --------------------------------------------------------------
+
+-- Which of the three lanes a packet asked for.
+function Legality.delivery (of: Packet): Serial.Delivery
+    if of.isUnreliable then return "unreliable" end
+    if of.isNewest then return "newest" end
+    return "reliable"
+end
+
+-- A block that has to fit one fire, refused where it cannot.
+function Legality.block (name: string, of: Packet, bytes: number)
+    local lane = Legality.delivery (of)
+    if lane == "reliable" or bytes <= CAP then return end
+
+    refuse (
+        name,
+        of.at,
+        `is {lane} and its widest block is {bytes} bytes, past the {CAP} one fire carries`
+    )
+end
+
+-- What a query's two halves are called, wherever one of them has to be named apart from the other.
+Legality.REQUEST = "request"
+Legality.RESPONSE = "response"
+
+-- Why a name is one the descriptor cannot spell back, or nothing.
+function Legality.named (name: string): string?
+    for _, mark in SPELLED do
+        if string.find (name, mark, 1, true) == nil then continue end
+        return `holds a {mark}, which is what a descriptor separates its own names with`
+    end
+    return nil
+end
+
+-- One definition, refused on the first thing wrong with it.
+function Legality.definition (name: string, of: Declared)
+    local at = of.at
+
+    local why = Legality.named (name)
+    if why ~= nil then refuse (name, at, why) end
+
+    if of.kind == "packet" then
+        if of.isUnreliable and of.isNewest then
+            refuse (name, at, "declares two ways of delivering itself, unreliable and newest")
+        end
+        stateless (name, at, "a packet", Base.cell (of.of), name)
+        return
+    end
+
+    if of.kind == "query" then
+        stateless (name, at, "a query", Base.cell (of.of), Serial.under (name, Legality.REQUEST))
+        local reply = Base.cell (of.reply)
+        stateless (name, at, "a query", reply, Serial.under (name, Legality.RESPONSE))
+        return
+    end
+
+    replicated (name, at, of)
+end
+
+return table.freeze (Legality)

package/shape/Lower.luau

@@ -0,0 +1,419 @@
+--!strict
+--!optimize 2
+-- A codec tree as the nodes the emitter writes, which is the whole of what a schema decides.
+
+local Base = require (script.Parent.Parent.codec.Base)
+local Folds = require (script.Parent.Folds)
+local Grid = require (script.Parent.Grid)
+local Ir = require (script.Parent.Ir)
+local Joins = require (script.Parent.Joins)
+local Order = require (script.Parent.Order)
+local Regions = require (script.Parent.Regions)
+local Serial = require (script.Parent.Serial)
+local Words = require (script.Parent.Words)
+
+local Lower = {}
+
+-- Constants -----------------------------------------------------------
+
+--[[
+    The names a value in parts is read off, in the order they are written.
+
+    Cloned at every use rather than handed over, because the constructor freezes the array it is
+    given and a second freeze on a frozen table raises. What is shared is the reading of them.
+]]
+const PLANE = table.freeze ({ "X", "Y" })
+const SPACE = table.freeze ({ "X", "Y", "Z" })
+const LIGHT = table.freeze ({ "R", "G", "B" })
+const FRAME = table.freeze ({ "Position", "Rotation" })
+
+-- The third of the three a vector and a colour are each read off.
+const THIRD = #SPACE
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    The two tables a walk interns into, which is everything a lowering needs that is not the
+    declaration it is on. A record rather than two arguments, because the walk is recursive and the
+    pair travels together to every node of a tree.
+]]
+export type Site = {
+    read paths: Serial.Interner,
+    read expected: Serial.Interner,
+}
+
+-- Private -------------------------------------------------------------
+
+-- Where a declaration is and what it wanted, with the caller's own checks where there are any.
+local function tagged (of: Base.Cell, at: string, site: Site): Ir.Tag
+    local pathId, expectId = Serial.tagged (site.paths, site.expected, at, of)
+    local checks = of.validates
+
+    return table.freeze ({
+        pathId = pathId,
+        expectId = expectId,
+        checks = if #checks == 0 then nil else checks,
+    })
+end
+
+-- The same place, for the nodes under the one the checks are on and for the bits that are no node.
+local function plain (of: Base.Cell, at: string, site: Site): Ir.Tag
+    local pathId, expectId = Serial.tagged (site.paths, site.expected, at, of)
+    return table.freeze ({ pathId = pathId, expectId = expectId })
+end
+
+local function counted (of: Base.Params): Ir.Span
+    return { min = of.min :: number, max = of.max :: number }
+end
+
+-- Where a field is, spelled from where the record holding it is, one dissolved name at a time.
+local function pathed (at: string, path: { string }): string
+    local out = at
+    for _, name in path do
+        out = Serial.under (out, name)
+    end
+    return out
+end
+
+-- The same, as the one string a table of them can be keyed by.
+local function spelled (path: { string }, deep: number): string
+    return table.concat (path, ".", 1, deep)
+end
+
+-- Whether a field is there, which is the whole of what a presence bit is filled from.
+local function there (value: any, into: { number }, at: number): boolean
+    into[at] = if value == nil then 0 else 1
+    return true
+end
+
+-- What a presence bit answers, which is nothing.
+local function nothing (): any return nil end
+
+local function planar (from: { any }): any return Vector2.new (from[1], from[2]) end
+
+local function spatial (from: { any }): any return Vector3.new (from[1], from[2], from[THIRD]) end
+
+local function lit (from: { any }): any return Color3.new (from[1], from[2], from[THIRD]) end
+
+--[[
+    A frame from its two halves, which is a turn moved to where it sits. The rotation comes back as
+    a frame at the origin and adding a vector to a frame is the translation the position is written
+    as, so there is nothing to compose here that the engine does not.
+]]
+local function framed (from: { any }): any return from[2] + from[1] end
+
+-- A declaration whose value is one bit run, as the region it is on its own.
+local function worded (of: Base.Cell, at: string, site: Site, tag: Ir.Tag): Ir.Word
+    local held = plain (of, at, site)
+
+    local made = Joins.of (of, held, 1, nil)
+    if made == nil then made = Folds.of (of, held, 1, nil) end
+
+    local field = made :: Joins.Field
+    local widths = table.create (#field.leaves) :: { number }
+    for index, grid in field.leaves do
+        widths[index] = grid.width
+    end
+
+    return Ir.word (tag, Words.plan (widths), field.leaves, { field.join })
+end
+
+-- A record, as the four regions and the records that dissolved into it.
+local function recorded (
+    of: Base.Cell,
+    at: string,
+    site: Site,
+    tag: Ir.Tag,
+    carries: string?
+): Ir.Group
+    local split = Regions.of (of.children :: { [string]: Base.Cell })
+
+    --[[
+        The records that dissolved, each hanging off the one above it. They arrive in depth order,
+        so the one a nest hangs off has always been made by the time the nest is.
+    ]]
+    local nests = table.create (#split.nests) :: { Ir.Nest }
+    local under: { [string]: number } = {}
+
+    -- The names each of these records may carry, one set per record.
+    local allow: { [string]: boolean } = {}
+    local allows = table.create (#split.nests) :: { { [string]: boolean } }
+
+    for index, entry in split.nests do
+        local path = entry.at
+        local deep = #path
+
+        allows[index] = {}
+        nests[index] = {
+            key = path[deep],
+            under = if deep == 1 then nil else under[spelled (path, deep - 1)],
+            allow = allows[index],
+            tag = plain (entry.of, pathed (at, path), site),
+        }
+        under[spelled (path, deep)] = index
+    end
+
+    local function inside (path: { string }): number?
+        if #path == 1 then return nil end
+        return under[spelled (path, #path - 1)]
+    end
+
+    --[[
+        Every nest is made before any name is declared, so a field at any depth reaches the record
+        it belongs to. An optional's bit and its payload are one declaration under one name, so the
+        presence list has nothing here the variable list does not.
+    ]]
+    local function declare (path: { string })
+        local deep = #path
+        local into = if deep == 1 then allow else allows[under[spelled (path, deep - 1)] ]
+        into[path[deep] ] = true
+    end
+
+    for _, entry in split.nests do
+        declare (entry.at)
+    end
+    for _, entry in split.bits do
+        declare (entry.at)
+    end
+    for _, entry in split.bytes do
+        declare (entry.at)
+    end
+    for _, entry in split.vars do
+        declare (entry.at)
+    end
+    --[[
+        The one name a record may carry that its own declaration does not hold, which is the tag a
+        variant was chosen by. Every variant is a struct and none of them declares the tag, both of
+        which the constructor holds them to, so this adds a name and never replaces one.
+    ]]
+    if carries ~= nil then allow[carries] = true end
+
+    for _, one in allows do
+        table.freeze (one)
+    end
+
+    --[[
+        Which leaf each optional's bit is, which the payload needs and the partition already knows:
+        the bits are the first leaves of the region in the order the presence list holds them, and
+        the same entry is in the variable list under the same field's name.
+    ]]
+    local bit: { [Regions.Entry]: number } = {}
+    local leaves: { Grid.Grid } = {}
+    local joins: { Ir.Join } = {}
+
+    for index, entry in split.presence do
+        local path = entry.at
+        bit[entry] = index
+
+        table.insert (leaves, Grid.flag ())
+        table.insert (joins, {
+            at = index,
+            count = 1,
+            key = path[#path],
+            nest = inside (path),
+            tag = plain (entry.of, pathed (at, path), site),
+            pull = there,
+            push = nothing,
+        })
+    end
+
+    for _, entry in split.bits do
+        local path = entry.at
+        local held = tagged (entry.of, pathed (at, path), site)
+        local key, nest = path[#path], inside (path)
+
+        local made = Joins.of (entry.of, held, #leaves + 1, key, nest)
+        if made == nil then made = Folds.of (entry.of, held, #leaves + 1, key, nest) end
+
+        local field = made :: Joins.Field
+        for _, grid in field.leaves do
+            table.insert (leaves, grid)
+        end
+        table.insert (joins, field.join)
+    end
+
+    local parts: { Ir.Part } = {}
+
+    for _, entry in split.bytes do
+        local path = entry.at
+        table.insert (parts, {
+            key = path[#path],
+            nest = inside (path),
+            of = Lower.of (entry.of, pathed (at, path), site),
+        })
+    end
+
+    --[[
+        An optional is its payload and the bit that says whether it is there, and the bit was laid
+        down above. The checks a caller declared on it ride on the node that may not be reached, so
+        an absent field is one they never run on.
+    ]]
+    for _, entry in split.vars do
+        local path = entry.at
+        local where = pathed (at, path)
+        local place = bit[entry]
+
+        local made: Ir.Shape
+        if place == nil then
+            made = Lower.of (entry.of, where, site)
+        else
+            local inner = (entry.of.children :: any).inner :: Base.Cell
+            made = Ir.opt (
+                tagged (entry.of, where, site),
+                place,
+                Lower.of (inner, Serial.under (where, "inner"), site)
+            )
+        end
+
+        table.insert (parts, { key = path[#path], nest = inside (path), of = made })
+    end
+
+    local word: Ir.Word? = nil
+    if #joins > 0 then
+        local widths = table.create (#leaves) :: { number }
+        for index, grid in leaves do
+            widths[index] = grid.width
+        end
+        word = Ir.word (plain (of, at, site), Words.plan (widths), leaves, joins)
+    end
+
+    return Ir.group (tag, word, parts, if #nests == 0 then nil else nests, allow)
+end
+
+-- One declaration to the node it becomes, with everything under it already its own.
+local function shaped (
+    of: Base.Cell,
+    at: string,
+    site: Site,
+    tag: Ir.Tag,
+    carries: string?
+): Ir.Shape
+    local kind, params = of.kind, of.params
+    if Regions.packs (of) then return worded (of, at, site, tag) end
+
+    -- A field the language carries whose one leaf is too wide to flow, which is whole bytes.
+    local single = Joins.grid (of)
+    if single ~= nil then return Ir.wide (tag, single) end
+
+    if kind == "f32" then return Ir.float (tag, false) end
+    if kind == "f64" then return Ir.float (tag, true) end
+    if kind == "vlq" then return Ir.varint (tag, false) end
+    if kind == "vli" then return Ir.varint (tag, true) end
+    if kind == "inst" then return Ir.slot (tag, params.class) end
+
+    if kind == "str" then return Ir.bytes (tag, counted (params), "string", params.symbols) end
+    if kind == "buffer" then return Ir.bytes (tag, counted (params), "buffer", nil) end
+
+    --[[
+        An array is a packed run where its element is one leaf that fits, and a list of aligned
+        elements otherwise. An element of several leaves that would all fit is a list too, and pays
+        up to seven pad bits each for it, because a run carries one grid and a bitfield or a
+        quantized vector is more than one. Closing that means a run whose element is a region.
+    ]]
+    if kind == "array" then
+        local element = (of.children :: any).element :: Base.Cell
+        local grid = if Regions.packs (element) then Joins.grid (element) else nil
+        if grid ~= nil then return Ir.run (tag, counted (params), grid) end
+
+        return Ir.list (
+            tag,
+            counted (params),
+            Lower.of (element, Serial.under (at, "element"), site)
+        )
+    end
+
+    if kind == "map" then
+        local children = of.children :: any
+        return Ir.pairs (
+            tag,
+            counted (params),
+            Lower.of (children.key, Serial.under (at, "key"), site),
+            Lower.of (children.value, Serial.under (at, "value"), site)
+        )
+    end
+
+    --[[
+        An optional whose whole definition it is. Its bit has no region to live in, so it gets one
+        of its own, and both the bit and the payload are nameless because what comes back is the
+        value rather than a record of one field.
+    ]]
+    if kind == "optional" then
+        local held = plain (of, at, site)
+        local join: Ir.Join = {
+            at = 1,
+            count = 1,
+            key = nil,
+            tag = held,
+            pull = there,
+            push = nothing,
+        }
+
+        local inner = (of.children :: any).inner :: Base.Cell
+        local part: Ir.Part = {
+            of = Ir.opt (tag, 1, Lower.of (inner, Serial.under (at, "inner"), site)),
+        }
+
+        return Ir.group (
+            held,
+            Ir.word (held, Words.plan ({ 1 }), { Grid.flag () }, { join }),
+            { part }
+        )
+    end
+
+    if kind == "tagged" then
+        local variants = of.children :: { [string]: Base.Cell }
+        local names = Order.names (variants)
+        local field = params.field :: string
+
+        local arms = table.create (#names) :: { Ir.Shape }
+        for index, name in names do
+            arms[index] = Lower.of (variants[name], Serial.under (at, name), site, field)
+        end
+
+        return Ir.branch (tag, field, names, arms)
+    end
+
+    if kind == "struct" then return recorded (of, at, site, tag, carries) end
+
+    --[[
+        A vector and a colour of components too wide to flow, which is every one whose components
+        are floats. The component is lowered once and stood in every place, since the three are one
+        declaration and a node is a value.
+    ]]
+    if kind == "vec2" or kind == "vec3" or kind == "color3" then
+        local children = of.children
+        local component = if children == nil then nil else children.component
+
+        local one = if component == nil
+            then Ir.float (plain (of, at, site), false) :: Ir.Shape
+            else Lower.of (component, Serial.under (at, "component"), site)
+
+        if kind == "vec2" then
+            return Ir.apart (tag, Folds.ENGINE.vec2, table.clone (PLANE), { one, one }, planar)
+        end
+
+        local push = if kind == "vec3" then spatial else lit
+        local keys = if kind == "vec3" then SPACE else LIGHT
+        local engine = if kind == "vec3" then Folds.ENGINE.vec3 else Folds.ENGINE.color3
+        return Ir.apart (tag, engine, table.clone (keys), { one, one, one }, push)
+    end
+
+    local children = of.children :: any
+    return Ir.apart (tag, Folds.ENGINE.cframe, table.clone (FRAME), {
+        Lower.of (children.position, Serial.under (at, "position"), site),
+        Lower.of (children.rotation, Serial.under (at, "rotation"), site),
+    }, framed)
+end
+
+-- Public --------------------------------------------------------------
+
+-- A declaration, at the path a refusal in it reads as, and everything under it.
+function Lower.of (of: Base.Cell, at: string, site: Site, carries: string?): Ir.Shape
+    local lift = of.lift
+    if lift == nil then return shaped (of, at, site, tagged (of, at, site), carries) end
+
+    local inner = shaped (of, at, site, plain (of, at, site), carries)
+    return Ir.xform (tagged (of, at, site), inner, lift, of.lower :: (any) -> any)
+end
+
+return table.freeze (Lower)