feat: Added type annotations to config.lua

In some instances this required some restructuring of the code to be
able to properly add the annotations.

.pre-commit-config.yaml

@@ -57,24 +57,12 @@ repos:
         files: (\.rs|Cargo.lock)$
         pass_filenames: false
 
-      - id: audit
-        name: audit
-        description: Audit packages
-        entry: cargo audit
-        args: ["--deny", "warnings"]
+      - id: generate_definitions
+        name: generate definitions
+        description: Generate lua definitions
+        entry: cargo run --bin generate_definitions
         language: system
-        pass_filenames: false
-        verbose: true
-        always_run: true
-
-      - id: udeps
-        name: unused
-        description: Check for unused crates
-        entry: cargo udeps
-        args: ["--workspace"]
-        language: system
-        types: [file]
-        files: (\.rs|Cargo.lock)$
+        types: [rust]
         pass_filenames: false
 
       - id: test
@@ -87,6 +75,26 @@ repos:
         files: (\.rs|Cargo.lock)$
         pass_filenames: false
 
+      - id: udeps
+        name: unused
+        description: Check for unused crates
+        entry: cargo udeps
+        args: ["--workspace"]
+        language: system
+        types: [file]
+        files: (\.rs|Cargo.lock)$
+        pass_filenames: false
+
+      - id: audit
+        name: audit
+        description: Audit packages
+        entry: cargo audit
+        args: ["--deny", "warnings"]
+        language: system
+        pass_filenames: false
+        verbose: true
+        always_run: true
+
   - repo: https://github.com/hadolint/hadolint
     rev: v2.13.1
     hooks:

config.lua

@@ -2,17 +2,21 @@ local devices = require("automation:devices")
 local device_manager = require("automation:device_manager")
 local utils = require("automation:utils")
 local secrets = require("automation:secrets")
-local debug = require("automation:variables").debug or false
+local debug = require("automation:variables").debug and true or false
 
 print(_VERSION)
 
 local host = utils.get_hostname()
 print("Running @" .. host)
 
+--- @param topic string
+--- @return string
 local function mqtt_z2m(topic)
 	return "zigbee2mqtt/" .. topic
 end
 
+--- @param topic string
+--- @return string
 local function mqtt_automation(topic)
 	return "automation/" .. topic
 end
@@ -30,12 +34,19 @@ local mqtt_client = require("automation:mqtt").new(device_manager, {
 	tls = host == "zeus" or host == "hephaestus",
 })
 
+local ntfy_topic = secrets.ntfy_topic
+if ntfy_topic == nil then
+	error("Ntfy topic is not specified")
+end
 local ntfy = devices.Ntfy.new({
-	topic = secrets.ntfy_topic,
+	topic = ntfy_topic,
 })
 device_manager:add(ntfy)
 
+--- @type {[string]: number}
 local low_battery = {}
+--- @param device DeviceInterface
+--- @param battery number
 local function check_battery(device, battery)
 	local id = device:get_id()
 	if battery < 15 then
@@ -66,11 +77,13 @@ device_manager:schedule("0 0 21 */1 * *", function()
 	})
 end)
 
-local on_presence = {
-	add = function(self, f)
-		self[#self + 1] = f
-	end,
-}
+--- @class OnPresence
+--- @field [integer] fun(presence: boolean)
+local on_presence = {}
+--- @param f fun(presence: boolean)
+function on_presence:add(f)
+	self[#self + 1] = f
+end
 
 local presence_system = devices.Presence.new({
 	topic = mqtt_automation("presence/+/#"),
@@ -110,11 +123,13 @@ on_presence:add(function(presence)
 	})
 end)
 
-local window_sensors = {
-	add = function(self, f)
-		self[#self + 1] = f
-	end,
-}
+--- @class WindowSensor
+--- @field [integer] OpenCloseInterface
+local window_sensors = {}
+--- @param sensor OpenCloseInterface
+function window_sensors:add(sensor)
+	self[#self + 1] = sensor
+end
 on_presence:add(function(presence)
 	if not presence then
 		local open = {}
@@ -139,6 +154,7 @@ on_presence:add(function(presence)
 	end
 end)
 
+--- @param device OnOffInterface
 local function turn_off_when_away(device)
 	on_presence:add(function(presence)
 		if not presence then
@@ -147,11 +163,13 @@ local function turn_off_when_away(device)
 	end)
 end
 
-local on_light = {
-	add = function(self, f)
-		self[#self + 1] = f
-	end,
-}
+--- @class OnLight
+--- @field [integer] fun(light: boolean)
+local on_light = {}
+--- @param f fun(light: boolean)
+function on_light:add(f)
+	self[#self + 1] = f
+end
 device_manager:add(devices.LightSensor.new({
 	identifier = "living_light_sensor",
 	topic = mqtt_z2m("living/light"),
@@ -175,6 +193,9 @@ end)
 
 local hue_ip = "10.0.0.102"
 local hue_token = secrets.hue_token
+if hue_token == nil then
+	error("Hue token is not specified")
+end
 
 local hue_bridge = devices.HueBridge.new({
 	identifier = "hue_bridge",
@@ -287,6 +308,7 @@ device_manager:add(devices.IkeaRemote.new({
 	battery_callback = check_battery,
 }))
 
+--- @return fun(self: OnOffInterface, state: {state: boolean, power: number})
 local function kettle_timeout()
 	local timeout = utils.Timeout.new()
 
@@ -301,6 +323,7 @@ local function kettle_timeout()
 	end
 end
 
+--- @type OutletPower
 local kettle = devices.OutletPower.new({
 	outlet_type = "Kettle",
 	name = "Kettle",
@@ -312,6 +335,7 @@ local kettle = devices.OutletPower.new({
 turn_off_when_away(kettle)
 device_manager:add(kettle)
 
+--- @param on boolean
 local function set_kettle(_, on)
 	kettle:set_on(on)
 end
@@ -336,6 +360,8 @@ device_manager:add(devices.IkeaRemote.new({
 	battery_callback = check_battery,
 }))
 
+--- @param duration number
+--- @return fun(self: OnOffInterface, state: {state: boolean})
 local function off_timeout(duration)
 	local timeout = utils.Timeout.new()
 
@@ -455,60 +481,66 @@ device_manager:add(devices.HueSwitch.new({
 local hallway_light_automation = {
 	timeout = utils.Timeout.new(),
 	forced = false,
-	switch_callback = function(self)
-		return function(_, on)
+	trash = nil,
+	door = nil,
+}
+---@return fun(_, on: boolean)
+function hallway_light_automation:switch_callback()
+	return function(_, on)
+		self.timeout:cancel()
+		self.group.set_on(on)
+		self.forced = on
+	end
+end
+---@return fun(_, open: boolean)
+function hallway_light_automation:door_callback()
+	return function(_, open)
+		if open then
 			self.timeout:cancel()
-			self.group.set_on(on)
-			self.forced = on
-		end
-	end,
-	door_callback = function(self)
-		return function(_, open)
-			if open then
-				self.timeout:cancel()
 
-				self.group.set_on(true)
-			elseif not self.forced then
-				self.timeout:start(debug and 10 or 2 * 60, function()
-					if self.trash == nil or self.trash:open_percent() == 0 then
-						self.group.set_on(false)
-					end
-				end)
-			end
-		end
-	end,
-	trash_callback = function(self)
-		return function(_, open)
-			if open then
-				self.group.set_on(true)
-			else
-				if
-					not self.timeout:is_waiting()
-					and (self.door == nil or self.door:open_percent() == 0)
-					and not self.forced
-				then
+			self.group.set_on(true)
+		elseif not self.forced then
+			self.timeout:start(debug and 10 or 2 * 60, function()
+				if self.trash == nil or self.trash:open_percent() == 0 then
 					self.group.set_on(false)
 				end
-			end
+			end)
 		end
-	end,
-	light_callback = function(self)
-		return function(_, state)
+	end
+end
+---@return fun(_, open: boolean)
+function hallway_light_automation:trash_callback()
+	return function(_, open)
+		if open then
+			self.group.set_on(true)
+		else
 			if
-				state.on
-				and (self.trash == nil or self.trash:open_percent()) == 0
+				not self.timeout:is_waiting()
 				and (self.door == nil or self.door:open_percent() == 0)
+				and not self.forced
 			then
-				-- If the door and trash are not open, that means the light got turned on manually
-				self.timeout:cancel()
-				self.forced = true
-			elseif not state.on then
-				-- The light is never forced when it is off
-				self.forced = false
+				self.group.set_on(false)
 			end
 		end
-	end,
-}
+	end
+end
+---@return fun(_, state: { on: boolean })
+function hallway_light_automation:light_callback()
+	return function(_, state)
+		if
+			state.on
+			and (self.trash == nil or self.trash:open_percent()) == 0
+			and (self.door == nil or self.door:open_percent() == 0)
+		then
+			-- If the door and trash are not open, that means the light got turned on manually
+			self.timeout:cancel()
+			self.forced = true
+		elseif not state.on then
+			-- The light is never forced when it is off
+			self.forced = false
+		end
+	end
+end
 
 local hallway_storage = devices.LightBrightness.new({
 	name = "Storage",
@@ -540,6 +572,8 @@ hallway_light_automation.group = {
 	end,
 }
 
+---@param duration number
+---@return fun(_, open: boolean)
 local function presence(duration)
 	local timeout = utils.Timeout.new()
 

definitions/automation:device_manager.lua

@@ -0,0 +1,12 @@
+---@meta
+
+---@class DeviceManager
+local DeviceManager
+---@param device DeviceInterface
+function DeviceManager:add(device) end
+
+---@param cron string
+---@param callback fun()
+function DeviceManager:schedule(cron, callback) end
+
+return DeviceManager

definitions/automation:devices.lua

@@ -0,0 +1,337 @@
+-- DO NOT MODIFY, FILE IS AUTOMATICALLY GENERATED
+---@meta
+
+local devices
+
+---@class KasaOutletConfig
+---@field identifier string
+---@field ip string
+local KasaOutletConfig
+
+---@class KasaOutlet: DeviceInterface, OnOffInterface
+local KasaOutlet
+devices.KasaOutlet = {}
+---@param config KasaOutletConfig
+---@return KasaOutlet
+function devices.KasaOutlet.new(config) end
+
+---@class AirFilter: DeviceInterface, OnOffInterface
+local AirFilter
+devices.AirFilter = {}
+---@param config AirFilterConfig
+---@return AirFilter
+function devices.AirFilter.new(config) end
+
+---@class AirFilterConfig
+---@field name string
+---@field room string?
+---@field url string
+local AirFilterConfig
+
+---@class Presence: DeviceInterface
+local Presence
+devices.Presence = {}
+---@param config PresenceConfig
+---@return Presence
+function devices.Presence.new(config) end
+---@async
+---@return boolean
+function Presence:overall_presence() end
+
+---@class PresenceConfig
+---@field topic string
+---@field callback fun(_: Presence, _: boolean) | fun(_: Presence, _: boolean)[]?
+---@field client AsyncClient
+local PresenceConfig
+
+---@class HueBridge: DeviceInterface
+local HueBridge
+devices.HueBridge = {}
+---@param config HueBridgeConfig
+---@return HueBridge
+function devices.HueBridge.new(config) end
+---@async
+---@param flag Flag
+---@param value boolean
+function HueBridge:set_flag(flag, value) end
+
+---@class FlagIDs
+---@field presence integer
+---@field darkness integer
+local FlagIDs
+
+---@class HueBridgeConfig
+---@field identifier string
+---@field ip string
+---@field login string
+---@field flags FlagIDs
+local HueBridgeConfig
+
+---@alias Flag
+---| "presence"
+---| "darkness"
+
+---@class WasherConfig
+---@field identifier string
+---@field topic string
+---@field threshold number
+---@field done_callback fun(_: Washer) | fun(_: Washer)[]?
+---@field client AsyncClient
+local WasherConfig
+
+---@class Washer: DeviceInterface
+local Washer
+devices.Washer = {}
+---@param config WasherConfig
+---@return Washer
+function devices.Washer.new(config) end
+
+---@class LightSensor: DeviceInterface
+local LightSensor
+devices.LightSensor = {}
+---@param config LightSensorConfig
+---@return LightSensor
+function devices.LightSensor.new(config) end
+
+---@class LightSensorConfig
+---@field identifier string
+---@field topic string
+---@field min integer
+---@field max integer
+---@field callback fun(_: LightSensor, _: boolean) | fun(_: LightSensor, _: boolean)[]?
+---@field client AsyncClient
+local LightSensorConfig
+
+---@class HueGroupConfig
+---@field identifier string
+---@field ip string
+---@field login string
+---@field group_id integer
+---@field scene_id string
+local HueGroupConfig
+
+---@class HueGroup: DeviceInterface, OnOffInterface
+local HueGroup
+devices.HueGroup = {}
+---@param config HueGroupConfig
+---@return HueGroup
+function devices.HueGroup.new(config) end
+
+---@class IkeaRemote: DeviceInterface
+local IkeaRemote
+devices.IkeaRemote = {}
+---@param config IkeaRemoteConfig
+---@return IkeaRemote
+function devices.IkeaRemote.new(config) end
+
+---@class IkeaRemoteConfig
+---@field name string
+---@field room string?
+---@field single_button boolean?
+---@field topic string
+---@field client AsyncClient
+---@field callback fun(_: IkeaRemote, _: boolean) | fun(_: IkeaRemote, _: boolean)[]?
+---@field battery_callback fun(_: IkeaRemote, _: number) | fun(_: IkeaRemote, _: number)[]?
+local IkeaRemoteConfig
+
+---@class WolConfig
+---@field name string
+---@field room string?
+---@field topic string
+---@field mac_address string
+---@field broadcast_ip string?
+---@field client AsyncClient
+local WolConfig
+
+---@class WakeOnLAN: DeviceInterface
+local WakeOnLAN
+devices.WakeOnLAN = {}
+---@param config WolConfig
+---@return WakeOnLAN
+function devices.WakeOnLAN.new(config) end
+
+---@class ConfigOutletOutletStateOnOff
+---@field name string
+---@field room string?
+---@field topic string
+---@field outlet_type OutletType?
+---@field callback fun(_: OutletOnOff, _: OutletStateOnOff) | fun(_: OutletOnOff, _: OutletStateOnOff)[]?
+---@field client AsyncClient
+local ConfigOutletOutletStateOnOff
+
+---@class OutletStatePower
+---@field state boolean
+---@field power number
+local OutletStatePower
+
+---@class ConfigOutletOutletStatePower
+---@field name string
+---@field room string?
+---@field topic string
+---@field outlet_type OutletType?
+---@field callback fun(_: OutletPower, _: OutletStatePower) | fun(_: OutletPower, _: OutletStatePower)[]?
+---@field client AsyncClient
+local ConfigOutletOutletStatePower
+
+---@alias OutletType
+---| "Outlet"
+---| "Kettle"
+
+---@class OutletStateOnOff
+---@field state boolean
+local OutletStateOnOff
+
+---@class OutletOnOff: DeviceInterface, OnOffInterface
+local OutletOnOff
+devices.OutletOnOff = {}
+---@param config ConfigOutletOutletStateOnOff
+---@return OutletOnOff
+function devices.OutletOnOff.new(config) end
+
+---@class OutletPower: DeviceInterface, OnOffInterface
+local OutletPower
+devices.OutletPower = {}
+---@param config ConfigOutletOutletStatePower
+---@return OutletPower
+function devices.OutletPower.new(config) end
+
+---@class ContactSensorConfig
+---@field name string
+---@field room string?
+---@field topic string
+---@field sensor_type SensorType?
+---@field callback fun(_: ContactSensor, _: boolean) | fun(_: ContactSensor, _: boolean)[]?
+---@field battery_callback fun(_: ContactSensor, _: number) | fun(_: ContactSensor, _: number)[]?
+---@field client AsyncClient?
+local ContactSensorConfig
+
+---@alias SensorType
+---| "Door"
+---| "Drawer"
+---| "Window"
+
+---@class ContactSensor: DeviceInterface, OpenCloseInterface
+local ContactSensor
+devices.ContactSensor = {}
+---@param config ContactSensorConfig
+---@return ContactSensor
+function devices.ContactSensor.new(config) end
+
+---@class LightStateOnOff
+---@field state boolean
+local LightStateOnOff
+
+---@class ConfigLightLightStateColorTemperature
+---@field name string
+---@field room string?
+---@field topic string
+---@field callback fun(_: LightColorTemperature, _: LightStateColorTemperature) | fun(_: LightColorTemperature, _: LightStateColorTemperature)[]?
+---@field client AsyncClient?
+local ConfigLightLightStateColorTemperature
+
+---@class LightStateBrightness
+---@field state boolean
+---@field brightness number
+local LightStateBrightness
+
+---@class LightStateColorTemperature
+---@field state boolean
+---@field brightness number
+---@field color_temp integer
+local LightStateColorTemperature
+
+---@class LightBrightness: DeviceInterface, OnOffInterface, BrightnessInterface
+local LightBrightness
+devices.LightBrightness = {}
+---@param config ConfigLightLightStateBrightness
+---@return LightBrightness
+function devices.LightBrightness.new(config) end
+
+---@class LightColorTemperature: DeviceInterface, OnOffInterface, BrightnessInterface, ColorSettingInterface
+local LightColorTemperature
+devices.LightColorTemperature = {}
+---@param config ConfigLightLightStateColorTemperature
+---@return LightColorTemperature
+function devices.LightColorTemperature.new(config) end
+
+---@class ConfigLightLightStateOnOff
+---@field name string
+---@field room string?
+---@field topic string
+---@field callback fun(_: LightOnOff, _: LightStateOnOff) | fun(_: LightOnOff, _: LightStateOnOff)[]?
+---@field client AsyncClient?
+local ConfigLightLightStateOnOff
+
+---@class ConfigLightLightStateBrightness
+---@field name string
+---@field room string?
+---@field topic string
+---@field callback fun(_: LightBrightness, _: LightStateBrightness) | fun(_: LightBrightness, _: LightStateBrightness)[]?
+---@field client AsyncClient?
+local ConfigLightLightStateBrightness
+
+---@class LightOnOff: DeviceInterface, OnOffInterface
+local LightOnOff
+devices.LightOnOff = {}
+---@param config ConfigLightLightStateOnOff
+---@return LightOnOff
+function devices.LightOnOff.new(config) end
+
+---@class Action
+---@field action
+---| "broadcast"
+---@field extras table<string, string>?
+---@field label string
+---@field clear boolean?
+local Action
+
+---@class NtfyConfig
+---@field url string?
+---@field topic string
+local NtfyConfig
+
+---@class Notification
+---@field title string
+---@field message string?
+---@field tags string[]?
+---@field priority Priority?
+---@field actions Action[]?
+local Notification
+
+---@alias Priority
+---| "min"
+---| "low"
+---| "default"
+---| "high"
+---| "max"
+
+---@class Ntfy: DeviceInterface
+local Ntfy
+devices.Ntfy = {}
+---@param config NtfyConfig
+---@return Ntfy
+function devices.Ntfy.new(config) end
+---@async
+---@param notification Notification
+function Ntfy:send_notification(notification) end
+
+---@class HueSwitch: DeviceInterface
+local HueSwitch
+devices.HueSwitch = {}
+---@param config HueSwitchConfig
+---@return HueSwitch
+function devices.HueSwitch.new(config) end
+
+---@class HueSwitchConfig
+---@field name string
+---@field room string?
+---@field topic string
+---@field client AsyncClient
+---@field left_callback fun(_: HueSwitch) | fun(_: HueSwitch)[]?
+---@field right_callback fun(_: HueSwitch) | fun(_: HueSwitch)[]?
+---@field left_hold_callback fun(_: HueSwitch) | fun(_: HueSwitch)[]?
+---@field right_hold_callback fun(_: HueSwitch) | fun(_: HueSwitch)[]?
+---@field battery_callback fun(_: HueSwitch, _: number) | fun(_: HueSwitch, _: number)[]?
+local HueSwitchConfig
+
+return devices

definitions/automation:mqtt.lua

@@ -0,0 +1,27 @@
+-- DO NOT MODIFY, FILE IS AUTOMATICALLY GENERATED
+---@meta
+
+local mqtt
+
+---@class MqttConfig
+---@field host string
+---@field port integer
+---@field client_name string
+---@field username string
+---@field password string
+---@field tls boolean
+local MqttConfig
+
+---@class AsyncClient
+local AsyncClient
+---@async
+---@param topic string
+---@param message table?
+function AsyncClient:send_message(topic, message) end
+mqtt.AsyncClient = {}
+---@param device_manager DeviceManager
+---@param config MqttConfig
+---@return AsyncClient
+function mqtt.new(device_manager, config) end
+
+return mqtt

definitions/automation:secrets.lua

@@ -0,0 +1,6 @@
+---@meta
+
+---@type table<string, string?>
+local secrets
+
+return secrets

definitions/automation:utils.lua

@@ -0,0 +1,27 @@
+-- DO NOT MODIFY, FILE IS AUTOMATICALLY GENERATED
+---@meta
+
+local utils
+
+---@class Timeout
+local Timeout
+---@async
+---@param timeout number
+---@param callback fun() | fun()[]
+function Timeout:start(timeout, callback) end
+---@async
+function Timeout:cancel() end
+---@async
+---@return boolean
+function Timeout:is_waiting() end
+utils.Timeout = {}
+---@return Timeout
+function utils.Timeout.new() end
+
+---@return string
+function utils.get_hostname() end
+
+---@return integer
+function utils.get_epoch() end
+
+return utils

definitions/automation:variables.lua

@@ -0,0 +1,6 @@
+---@meta
+
+---@type table<string, string?>
+local variables
+
+return variables

src/bin/generate_definitions.rs

@@ -22,11 +22,11 @@ fn main() -> std::io::Result<()> {
 
             file.write_all(b"-- DO NOT MODIFY, FILE IS AUTOMATICALLY GENERATED\n")?;
             file.write_all(definitions.as_bytes())?;
+            file.write_all(b"\n")?;
         } else {
             warn!(name = module.get_name(), "No definitions");
         }
     }
 
     Ok(())
-    // automation_devices::generate_definitions()
 }