Add Generalised Tooling Support

cli/src/main.rs

@@ -65,6 +65,16 @@ fn main() -> Result<()> {
 
 			std::fs::write(file_path, defs)?;
 		}
+
+		if let Some(tooling) = code.tooling {
+			let tooling_path = config_path.parent().unwrap().join(tooling.path);
+
+			if let Some(parent) = tooling_path.parent() {
+				std::fs::create_dir_all(parent)?;
+			}
+
+			std::fs::write(tooling_path, tooling.code)?;
+		}
 	}
 
 	if diagnostics.is_empty() {

docs/.vitepress/components/Editor.vue

@@ -114,7 +114,7 @@ const beforeMount = (monaco: Monaco) => {
 
 	const Calls = ["SingleSync", "SingleAsync", "ManySync", "ManyAsync"] as const;
 
-	const Options = ["write_checks", "typescript", "typescript_max_tuple_length", "manual_event_loop", "remote_scope", "server_output", "client_output", "casing", "yield_type", "async_lib"] as const;
+	const Options = ["write_checks", "typescript", "typescript_max_tuple_length", "manual_event_loop", "remote_scope", "server_output", "client_output", "casing", "yield_type", "async_lib", "tooling", "tooling_output", "tooling_show_internal_data"] as const;
 
 	const Casing = ["PascalCase", "camelCase", "snake_case"].map((value) => `"${value}"`);
 	const YieldType = ["yield", "future", "promise"].map((value) => `"${value}"`);
@@ -153,17 +153,22 @@ const beforeMount = (monaco: Monaco) => {
 
 		opt: Options,
 
-		casing: Casing,
-		yield_type: YieldType,
-
 		typescript: Operators,
 		typescript_max_tuple_length: [],
+
+		tooling: Operators,
+		tooling_show_internal_data: Operators,
+
 		write_checks: Operators,
 		manual_event_loop: Operators,
-
 		remote_scope: [],
+
 		server_output: [],
 		client_output: [],
+		tooling_output: [],
+
+		casing: Casing,
+		yield_type: YieldType,
 		async_lib: [],
 	} as const;
 

docs/.vitepress/config.mts

@@ -27,6 +27,7 @@ const sidebar = [
     items: [
       { text: 'Generate Code', link: '/usage/generation' },
       { text: 'Event Usage', link: '/usage/events' },
+      { text: 'Tooling Intergration', link: '/usage/tooling' },
     ]
   }
 ]

docs/config/options.md

@@ -7,6 +7,16 @@ opt client_output = "src/client/zap.luau"`
 
 const asyncLibExample = `opt yield_type = "promise"
 opt async_lib = "require(game:GetService('ReplicatedStorage').Promise)"`
+
+const toolingOutputExample = `opt tooling = true
+opt tooling_output = "src/ReplicatedStorage/RemoteName.profiler.luau"`
+
+const toolingOutputExample2 = `opt typescript = true
+opt tooling = true
+opt tooling_output = "src/include/RemoteName.profiler.lua"`
+
+const toolingShowInternalDataExample = `opt tooling = true
+opt tooling_show_internal_data = true`
 </script>
 
 # Options
@@ -227,3 +237,45 @@ The path is empty.
 ### Example
 
 <CodeBlock :code="asyncLibExample" />
+
+## `tooling`
+
+This option determines if Zap should generate a file to allow it to inteface with other tooling. More information on this feature can be found on the [tooling intergration](../usage/tooling.md) page.
+
+### Default
+
+`false`
+
+### Example
+
+<CodeBlock code="opt tooling = true" />
+
+## `tooling_output`
+
+This options allows you to configure where Zap will output its generated [tooling code](../usage/tooling.md). If you're not using the CLI these options can be ignored.
+
+The path is relative to the configuration file and should point to a lua(u) file.
+
+### Default
+
+<CodeBlock code='opt tooling_output = "./network/tooling.lua"' />
+
+### Example
+
+<CodeBlock :code="toolingOutputExample" />
+
+or
+
+<CodeBlock :code="toolingOutputExample2" />
+
+## `tooling_show_internal_data`
+
+This option will add an additional element to the start of the [arguments array](../usage/tooling.md#tooling-format-returns) returned by the [tooling intergration](../usage/tooling.md) function. More information on its structure can be found [here](../usage/tooling.md#tooling-format-returns).
+
+### Default
+
+`false`
+
+### Example
+
+<CodeBlock :code="toolingShowInternalDataExample" />

docs/playground.md

@@ -50,6 +50,13 @@
 			:isCodeBlock="false"
 		/>
 	</PluginTabsTab>
+	<PluginTabsTab label="Tooling" v-if="compiledResult.code && compiledResult.code.tooling">
+		<CodeBlock
+			:code="compiledResult.code.tooling.code"
+			lang="lua"
+			:isCodeBlock="false"
+		/>
+	</PluginTabsTab>
 </PluginTabs>
 
 </ClientOnly>

docs/usage/tooling.md

@@ -0,0 +1,79 @@
+# Tooling Intergration
+
+Zap supports the ability to output a lua file that can deseralise compressed data so that it can be read by plugins and/or scripts such as [PacketProfiler](https://github.com/Pyseph/PacketProfiler/).
+
+Zap and PacketProfiler have created a common format for this interfacing as detailed below:
+
+## Tooling Format - Parameters
+
+To deseralise this data, the function generated by Zap has the following parameters:
+
+- The remote instance itself (`RemoteEvent | UnreliableRemoteEvent`)
+- ALL arguments sent through the remote
+
+An example is below:
+
+::: danger
+It is not intended behavior for you to run side effects if you deserialise the data yourself.
+:::
+
+
+<CodeBlock lang="lua" :code="example1" />
+
+## Tooling Format - Returns
+
+The function then returns an array in this format:
+
+Lua:
+<CodeBlock lang="lua" :code="returnsLua" />
+
+TS:
+<CodeBlock lang="typescript" :code="returnsTS" />
+
+If the [`tooling_show_internal_data`](../config/options.md#tooling-show-internal-data) argument is `true`, then the first argument is of the type (although this type will respect your casing option):
+
+Lua:
+<CodeBlock lang="lua" :code="internalDataLua" />
+
+TS:
+<CodeBlock lang="typescript" :code="internalDataTS" />
+
+And then the next argument in the array is the data deserialised from the event itself (if it exists).
+
+<script setup lang="ts">
+const example1 = `local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local zap_deserialiser = require(path.to.deserialiser)
+
+local reliable = ReplicatedStorage:WaitForChild("ZAP_RELIABLE")
+local unreliable = ReplicatedStorage:WaitForChild("ZAP_UNRELIABLE")
+
+reliable.OnClientEvent:Connect(function(...)
+	local data = zap_deserialiser(reliable, unpack(...))
+	print(data)
+end)
+
+unreliable.OnClientEvent:Connect(function(...)
+	local data = zap_deserialiser(unreliable, unpack(...))
+	print(data)
+end)`
+
+const returnsLua = `type DecompressedData = { {
+    Name: string,
+    Arguments: { any },
+} }`
+
+const returnsTS = `type DecompressedData = {
+    Name: string,
+    Arguments: unknown[],
+}[]`
+
+const internalDataLua = `type InternalData = {
+    EventId: number,
+    CallId: number?
+}`
+
+const internalDataTS = `interface InternalData {
+    EventId: number,
+    CallId?: number
+}`
+</script>

zap/src/config.rs

@@ -9,15 +9,19 @@ pub struct Config<'src> {
 	pub evdecls: Vec<EvDecl<'src>>,
 	pub fndecls: Vec<FnDecl<'src>>,
 
-	pub write_checks: bool,
 	pub typescript: bool,
 	pub typescript_max_tuple_length: f64,
-	pub manual_event_loop: bool,
 
+	pub tooling: bool,
+	pub tooling_show_internal_data: bool,
+
+	pub write_checks: bool,
+	pub manual_event_loop: bool,
 	pub remote_scope: &'src str,
 
 	pub server_output: &'src str,
 	pub client_output: &'src str,
+	pub tooling_output: &'src str,
 
 	pub casing: Casing,
 	pub yield_type: YieldType,

zap/src/lib.rs

@@ -38,6 +38,7 @@ pub struct Output {
 pub struct Code {
 	pub server: Output,
 	pub client: Output,
+	pub tooling: Option<Output>,
 }
 
 #[derive(Debug)]
@@ -72,6 +73,7 @@ pub fn run(input: &str) -> Return {
 					code: output::luau::client::code(&config),
 					defs: output::typescript::client::code(&config),
 				},
+				tooling: output::tooling::output(&config),
 			}),
 			diagnostics: reports.into_iter().map(|report| report.into()).collect(),
 		}
@@ -110,6 +112,7 @@ pub fn run(input: &str) -> Return {
 					code: output::luau::client::code(&config),
 					defs: output::typescript::client::code(&config),
 				},
+				tooling: output::tooling::output(&config),
 			}),
 			diagnostics,
 		}

zap/src/output/mod.rs

@@ -1,2 +1,3 @@
 pub mod luau;
+pub mod tooling;
 pub mod typescript;