fixup! engine(lua): Improve usage of types with Lua

engine/lua/cloe-engine/init.lua

@@ -26,28 +26,68 @@
 ---
 
 local engine = {
-    -- Contains data that will be processed at simulation start,
-    -- but will not be considered afterward.
+    --- Contains data that will be processed at simulation start,
+    --- but will not be considered afterward.
     initial_input = {
+        --- @type TriggerConf[] Initial set of triggers to insert into simulation.
         triggers = {},
+
+        --- @type number Number of triggers processed from the initial input.
         triggers_processed = 0,
+
+        --- @type table<string, string> Map of signal names to regular expression matches.
         signal_aliases = {},
+
+        --- @type string[] List of signals to make available during simulation.
         signal_requires = {},
     },
 
-    -- Contains engine state for a simulation.
+    --- Contains engine state for a simulation.
     state = {
-        features = {},
+        --- @type StackConf The current active stack configuration (volatile).
+        config = {},
+
+        --- @type table<string, boolean> A table of feature flags.
+        features = {
+            ["cloe-0.18.0"] = true,
+            ["cloe-0.18"] = true,
+            ["cloe-0.19.0"] = true,
+            ["cloe-0.19"] = true,
+            ["cloe-0.20.0"] = true,
+            ["cloe-0.20"] = true,
+
+            ["cloe-stackfile"] = true,
+            ["cloe-stackfile-4"] = true,
+            ["cloe-stackfile-4.0"] = true,
+            ["cloe-stackfile-4.1"] = true,
+
+            ["cloe-server"] = false,
+            ["cloe-lrdb"] = false,
+        },
+
+        --- @type table Lua table dumped as JSON report at end of simulation.
         report = {},
+
+        --- @type Coordinator|nil Reference to simulation trigger coordinator type.
         scheduler = nil,
+
+        --- @type Stack Reference to simulation stack type.
         stack = nil,
+
+        --- @type string|nil Path to currently executing Lua script file.
         current_script_file = nil,
+
+        --- @type string|nil Path to directory containing currently executing Lua script file.
         current_script_dir = nil,
+
+        --- @type string[] List of Lua scripts that have so far been processed.
         scripts_loaded = {},
     },
 
+    --- @type table<string, table> Namespaced Lua interfaces of instantiated plugins.
     plugins = {},
 
+    --- @type table<string, userdata> Table of required signals.
     signals = {},
 }
 

engine/lua/cloe-engine/types.lua

@@ -32,6 +32,7 @@ local Stack = {}
 --- @field version string version of stack (should be "4")
 --- @field include? string[] list of files to include
 --- @field engine? EngineConf engine configuration
+--- @field simulation? SimulationConf simulation configuration
 --- @field server? ServerConf server configuration
 --- @field plugins? PluginConf[] list of plugin configurations
 --- @field defaults? DefaultsConf default arguments to apply to plugins

engine/lua/cloe/engine.lua

@@ -53,6 +53,16 @@ function engine.require_feature(id)
     end
 end
 
+--- Return the active stack configuration as a table.
+---
+--- Modifying the values here have no effect. It is simply a dump
+--- of the JSON representation of a stack configuration.
+---
+--- @return StackConf
+function engine.config()
+    return api.state.config
+end
+
 --- Try to load (merge) stackfile.
 ---
 --- @param file string file path, possibly relative to calling file
@@ -91,9 +101,9 @@ function engine.apply_stack(stack)
     validate("cloe.apply_stack(string|table)", stack)
     local file = api.state.current_script_file or ""
     if type(stack) == "table" then
-        api.state.stack:merge_stacktable(stack, file)
+        api.state.stack:merge_stacktable(stack --[[ @as table ]], file)
     else
-        api.state.stack:merge_stackjson(stack, file)
+        api.state.stack:merge_stackjson(stack --[[ @as string ]], file)
     end
 end
 

engine/lua/cloe/events.lua

@@ -26,23 +26,21 @@ local events = {}
 ---
 --- Example:
 ---
----     local events = require("cloe.testing").events
----
 ---     cloe.schedule_test {
 ---         id = "TEST-A",
----         on = "start",
+---         on = cloe.events.start(),
 ---         -- ...
 ---     }
 ---
 ---     cloe.schedule_test {
 ---         id = "TEST-B",
----         on = events.after_tests("TEST-A"),
+---         on = cloe.events.after_tests("TEST-A"),
 ---         -- ...
 ---     }
 ---
 ---     cloe.schedule_test {
 ---         id = "FINAL",
----         on = events.after_tests("TEST-A", "TEST-B"),
+---         on = cloe.events.after_tests("TEST-A", "TEST-B"),
 ---         -- ...
 ---     }
 ---
@@ -80,7 +78,7 @@ function events.every(duration)
     if type(duration) == "string" then
         duration = types.Duration.new(duration)
     end
-    if duration:ms() % api.state.stack.simulation.model_step_width:ms() ~= 0 then
+    if duration:ns() % api.state.config.simulation.model_step_width ~= 0 then
         error("interval duration is not a multiple of nominal step width")
     end
     return function(sync)