@quenty/studio-bridge 0.21.1 → 0.22.1

package/src/commands/explorer/find/find-instances.lua

@@ -0,0 +1,174 @@
+--!strict
+--[=[
+	Action that searches the DataModel for instances by name, class and tag,
+	answering with the first `limit` matches.
+
+	- `name` matches case-insensitively anywhere in the instance's name, or the
+	  whole name with `exactName`.
+	- `className` matches with IsA, so `BasePart` finds every part.
+	- Without `root`, searches every service the plugin can read, other than
+	  Studio's own (CoreGui and the like).
+
+	Request: `{ type: "findInstances", payload: { root?, name?, exactName?, className?, tag?, limit? } }`
+	Response: `{ type: "findInstancesResult", payload: { instances, searched, truncated } }`
+
+	@class FindInstancesAction
+]=]
+
+local DEFAULT_LIMIT = 200
+local YIELD_EVERY = 5000
+-- Studio's own instances, which the place does not contain
+local ENGINE_SERVICES = table.freeze({
+	CoreGui = true,
+	CorePackages = true,
+	RobloxReplicatedStorage = true,
+})
+
+local FindInstancesAction = {}
+
+type FoundInstance = {
+	path: string,
+	name: string,
+	className: string,
+}
+
+--[=[
+	Registers the `findInstances` handler.
+]=]
+function FindInstancesAction.register(router: any)
+	router:setResponseType("findInstances", "findInstancesResult")
+	router:register(
+		"findInstances",
+		function(payload: { [string]: any }, _requestId: string, _sessionId: string): { [string]: any }?
+			local root: Instance? = game
+			if type(payload.root) == "string" then
+				root = FindInstancesAction._resolveInstance(payload.root)
+				if not root then
+					return {
+						success = false,
+						code = "INSTANCE_NOT_FOUND",
+						message = `Instance not found at path: {payload.root}`,
+					}
+				end
+			end
+
+			local matches = FindInstancesAction._createMatcher(payload)
+			local limit = if type(payload.limit) == "number" then payload.limit else DEFAULT_LIMIT
+
+			local found: { FoundInstance } = {}
+			local searched = 0
+			local truncated = false
+			for _, instance in FindInstancesAction._getSearchable(root :: Instance) do
+				searched += 1
+				if searched % YIELD_EVERY == 0 then
+					task.wait()
+				end
+
+				if matches(instance) then
+					if #found >= limit then
+						truncated = true
+						break
+					end
+					table.insert(found, {
+						path = instance:GetFullName(),
+						name = instance.Name,
+						className = instance.ClassName,
+					})
+				end
+			end
+
+			return {
+				instances = found,
+				searched = searched,
+				truncated = truncated,
+			}
+		end
+	)
+end
+
+function FindInstancesAction._createMatcher(payload: { [string]: any }): (Instance) -> boolean
+	local name = if type(payload.name) == "string" and payload.name ~= "" then string.lower(payload.name) else nil
+	local exactName = payload.exactName == true
+	local className = if type(payload.className) == "string" then payload.className else nil
+	local tag = if type(payload.tag) == "string" then payload.tag else nil
+
+	return function(instance: Instance): boolean
+		if name then
+			local instanceName = string.lower(instance.Name)
+			if exactName then
+				if instanceName ~= name then
+					return false
+				end
+			elseif not string.find(instanceName, name, 1, true) then
+				return false
+			end
+		end
+
+		if className and not instance:IsA(className) then
+			return false
+		end
+
+		if tag and not instance:HasTag(tag) then
+			return false
+		end
+
+		return true
+	end
+end
+
+--[[
+	Returns the descendants of `root`. For game, that is the descendants of
+	each place service the plugin may read, since some refuse access.
+]]
+function FindInstancesAction._getSearchable(root: Instance): { Instance }
+	if root ~= game then
+		return root:GetDescendants()
+	end
+
+	local searchable = {}
+	for _, service in game:GetChildren() do
+		if ENGINE_SERVICES[service.ClassName] then
+			continue
+		end
+		local ok, descendants = pcall(service.GetDescendants, service)
+		if ok then
+			table.insert(searchable, service)
+			table.move(descendants, 1, #descendants, #searchable + 1, searchable)
+		end
+	end
+	return searchable
+end
+
+--[[
+	Walks `path` down from game, falling back to GetService for top-level names
+	that are not children by that name. A leading "game" is optional.
+]]
+function FindInstancesAction._resolveInstance(path: string): Instance?
+	local parts = string.split(path, ".")
+	local startIndex = if parts[1] == "game" then 2 else 1
+
+	local current: Instance = game
+	for index = startIndex, #parts do
+		local part = parts[index]
+
+		local ok, child = pcall(current.FindFirstChild, current, part)
+		if ok and child then
+			current = child
+			continue
+		end
+
+		if current ~= game then
+			return nil
+		end
+
+		local serviceOk, service = pcall(game.GetService, game, part)
+		if not (serviceOk and service) then
+			return nil
+		end
+		current = service
+	end
+
+	return current
+end
+
+return FindInstancesAction

package/src/commands/explorer/find/find-instances.spec.lua

@@ -0,0 +1,122 @@
+--!strict
+--[[
+	@class find-instances.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local HttpService = game:GetService("HttpService")
+
+local ActionRouter = require("ActionRouter")
+local FindInstancesAction = require("find-instances")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(): any
+	local router = ActionRouter.new()
+	FindInstancesAction.register(router)
+
+	local root = Instance.new("Folder")
+	root.Name = `FindInstancesSpec{HttpService:GenerateGUID(false)}`
+
+	local spawnPart = Instance.new("Part")
+	spawnPart.Name = "RedSpawn"
+	spawnPart:AddTag("Spawn")
+	spawnPart.Parent = root
+
+	local wedge = Instance.new("WedgePart")
+	wedge.Name = "BlueSpawn"
+	wedge.Parent = root
+
+	local value = Instance.new("StringValue")
+	value.Name = "SpawnName"
+	value.Parent = root
+
+	root.Parent = workspace
+
+	local controller = {
+		root = root,
+		rootPath = `Workspace.{root.Name}`,
+		find = function(payload: { [string]: any }): any
+			return router:Dispatch({ type = "findInstances", sessionId = "session-1", payload = payload })
+		end,
+		Destroy = function(_self)
+			root:Destroy()
+		end,
+	}
+
+	return controller
+end
+
+local function getNames(response: any): { string }
+	local names = {}
+	for _, found in response.payload.instances do
+		table.insert(names, found.name)
+	end
+	table.sort(names)
+	return names
+end
+
+describe("findInstances", function()
+	it("should match names case-insensitively anywhere in the name", function()
+		local controller = setup()
+
+		local response = controller.find({ root = controller.rootPath, name = "spawn" })
+
+		expect(response.type).toEqual("findInstancesResult")
+		expect(getNames(response)).toEqual({ "BlueSpawn", "RedSpawn", "SpawnName" })
+		controller:Destroy()
+	end)
+
+	it("should match the whole name with exactName", function()
+		local controller = setup()
+
+		local response = controller.find({ root = controller.rootPath, name = "redspawn", exactName = true })
+
+		expect(getNames(response)).toEqual({ "RedSpawn" })
+		expect(response.payload.instances[1].path).toEqual(`{controller.root:GetFullName()}.RedSpawn`)
+		expect(response.payload.instances[1].className).toEqual("Part")
+		controller:Destroy()
+	end)
+
+	it("should match a class and its subclasses", function()
+		local controller = setup()
+
+		local response = controller.find({ root = controller.rootPath, className = "BasePart" })
+
+		expect(getNames(response)).toEqual({ "BlueSpawn", "RedSpawn" })
+		controller:Destroy()
+	end)
+
+	it("should match a tag", function()
+		local controller = setup()
+
+		local response = controller.find({ root = controller.rootPath, tag = "Spawn" })
+
+		expect(getNames(response)).toEqual({ "RedSpawn" })
+		controller:Destroy()
+	end)
+
+	it("should stop at the limit and say so", function()
+		local controller = setup()
+
+		local response = controller.find({ root = controller.rootPath, name = "spawn", limit = 2 })
+
+		expect(#response.payload.instances).toEqual(2)
+		expect(response.payload.truncated).toEqual(true)
+		controller:Destroy()
+	end)
+
+	it("should fail when the root does not resolve", function()
+		local controller = setup()
+
+		local response = controller.find({ root = "Workspace.DoesNotExist" })
+
+		expect(response.type).toEqual("error")
+		expect(response.payload.code).toEqual("INSTANCE_NOT_FOUND")
+		controller:Destroy()
+	end)
+end)

package/src/commands/explorer/find/find.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest';
+import { findInstancesHandlerAsync, formatFindText } from './find.js';
+
+function createSession(result: unknown) {
+  return { findInstancesAsync: vi.fn().mockResolvedValue(result) } as any;
+}
+
+describe('findInstancesHandlerAsync', () => {
+  it('passes the search through and summarizes it', async () => {
+    const session = createSession({
+      instances: [
+        { path: 'Workspace.RedSpawn', name: 'RedSpawn', className: 'Part' },
+      ],
+      searched: 120,
+      truncated: false,
+    });
+
+    const result = await findInstancesHandlerAsync(session, {
+      name: 'spawn',
+      className: 'BasePart',
+      exact: true,
+    });
+
+    expect(session.findInstancesAsync).toHaveBeenCalledWith({
+      name: 'spawn',
+      className: 'BasePart',
+      exactName: true,
+      root: undefined,
+      tag: undefined,
+      limit: undefined,
+    });
+    expect(result.summary).toBe('1 match(es) among 120 instances');
+    expect(formatFindText(result)).toContain('Workspace.RedSpawn');
+  });
+
+  it('says when it stopped at the limit', async () => {
+    const session = createSession({
+      instances: [{ path: 'Workspace.A', name: 'A', className: 'Part' }],
+      searched: 10,
+      truncated: true,
+    });
+
+    const result = await findInstancesHandlerAsync(session, { tag: 'Spawn' });
+
+    expect(result.summary).toBe('First 1 matches; raise --limit to see more');
+  });
+
+  it('needs something to search for', async () => {
+    await expect(
+      findInstancesHandlerAsync(createSession({}), {})
+    ).rejects.toThrow('Give a name, --class or --tag to search for');
+  });
+});

package/src/commands/explorer/find/find.ts

@@ -0,0 +1,113 @@
+/**
+ * `explorer find` — search the DataModel for instances by name, class and tag.
+ */
+
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  formatTable,
+  type TableColumn,
+} from '@quenty/cli-output-helpers/reporting';
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+import type { FoundInstance } from '../../../server/web-socket-protocol.js';
+
+export interface FindOptions {
+  name?: string;
+  exact?: boolean;
+  className?: string;
+  tag?: string;
+  root?: string;
+  limit?: number;
+}
+
+export interface FindResult {
+  instances: FoundInstance[];
+  searched: number;
+  /** True when the search stopped at --limit; there may be more. */
+  truncated: boolean;
+  summary: string;
+}
+
+export async function findInstancesHandlerAsync(
+  session: BridgeSession,
+  options: FindOptions
+): Promise<FindResult> {
+  if (!options.name && !options.className && !options.tag) {
+    throw new Error('Give a name, --class or --tag to search for');
+  }
+
+  const result = await session.findInstancesAsync({
+    root: options.root,
+    name: options.name,
+    exactName: options.exact,
+    className: options.className,
+    tag: options.tag,
+    limit: options.limit,
+  });
+
+  return {
+    ...result,
+    summary: result.truncated
+      ? `First ${result.instances.length} matches; raise --limit to see more`
+      : `${result.instances.length} match(es) among ${result.searched} instances`,
+  };
+}
+
+const columns: TableColumn<FoundInstance>[] = [
+  {
+    header: 'Path',
+    value: (i) => i.path,
+    format: (v) => OutputHelper.formatHint(v),
+  },
+  { header: 'Class', value: (i) => i.className },
+];
+
+export function formatFindText(result: FindResult): string {
+  if (result.instances.length === 0) return 'No instances match';
+  return `${formatTable(result.instances, columns)}\n${OutputHelper.formatDim(
+    result.summary
+  )}`;
+}
+
+interface FindArgs extends Omit<FindOptions, 'className'> {
+  class?: string;
+}
+
+export const findCommand = defineCommand<FindArgs, FindResult>({
+  group: 'explorer',
+  name: 'find',
+  description: 'Find instances by name, class or tag',
+  category: 'execution',
+  safety: 'read',
+  scope: 'session',
+  args: {
+    name: arg.positional({
+      description: 'Text in the instance name (case-insensitive)',
+      required: false,
+    }),
+    exact: arg.flag({
+      description: 'Match the whole name instead of part of it',
+    }),
+    class: arg.option({
+      description: 'Only instances of this class or a subclass (IsA)',
+    }),
+    tag: arg.option({
+      description: 'Only instances with this CollectionService tag',
+    }),
+    root: arg.option({
+      description:
+        'Dot-separated path to search under (default: the whole DataModel)',
+    }),
+    limit: arg.option({
+      description: 'Stop after this many matches (default: 200)',
+      type: 'number',
+      alias: 'n',
+    }),
+  },
+  cli: {
+    format: formatFindText,
+  },
+  handler: async (session, { class: className, ...args }) =>
+    findInstancesHandlerAsync(session, { ...args, className }),
+});

package/src/commands/explorer/grep/grep-scripts.lua

@@ -0,0 +1,214 @@
+--!strict
+--[=[
+	Action that searches the source of every script under `root` for `pattern`,
+	answering with each matching line.
+
+	- Matches the text plainly and case-insensitively by default. `luaPattern`
+	  treats `pattern` as a Lua pattern, and `caseSensitive` keeps case.
+	- Reads a script's open editor text when it has one, so unsaved edits are
+	  searched as they read in Studio.
+	- Stops after `limit` matching lines.
+
+	Request: `{ type: "grepScripts", payload: { pattern, root?, luaPattern?, caseSensitive?, limit? } }`
+	Response: `{ type: "grepScriptsResult", payload: { matches, searched, truncated } }`
+
+	@class GrepScriptsAction
+]=]
+
+local DEFAULT_LIMIT = 200
+local MAX_LINE_LENGTH = 300
+local YIELD_EVERY = 200
+-- Studio's own instances, which the place does not contain
+local ENGINE_SERVICES = table.freeze({
+	CoreGui = true,
+	CorePackages = true,
+	RobloxReplicatedStorage = true,
+})
+
+local GrepScriptsAction = {}
+
+type GrepMatch = {
+	path: string,
+	className: string,
+	line: number,
+	text: string,
+}
+
+--[=[
+	Registers the `grepScripts` handler.
+]=]
+function GrepScriptsAction.register(router: any)
+	router:setResponseType("grepScripts", "grepScriptsResult")
+	router:register(
+		"grepScripts",
+		function(payload: { [string]: any }, _requestId: string, _sessionId: string): { [string]: any }?
+			local pattern = payload.pattern
+			if type(pattern) ~= "string" or pattern == "" then
+				return {
+					success = false,
+					code = "INVALID_PAYLOAD",
+					message = "grepScripts needs a pattern",
+				}
+			end
+
+			local luaPattern = payload.luaPattern == true
+			local caseSensitive = payload.caseSensitive == true
+			if luaPattern then
+				local ok, err = pcall(string.find, "", pattern)
+				if not ok then
+					return {
+						success = false,
+						code = "INVALID_PAYLOAD",
+						message = `Invalid Lua pattern: {err}`,
+					}
+				end
+			end
+
+			local root: Instance? = game
+			if type(payload.root) == "string" then
+				root = GrepScriptsAction._resolveInstance(payload.root)
+				if not root then
+					return {
+						success = false,
+						code = "INSTANCE_NOT_FOUND",
+						message = `Instance not found at path: {payload.root}`,
+					}
+				end
+			end
+
+			local needle = if caseSensitive
+				then pattern
+				elseif luaPattern then GrepScriptsAction._lowerPattern(pattern)
+				else string.lower(pattern)
+			local limit = if type(payload.limit) == "number" then payload.limit else DEFAULT_LIMIT
+
+			local matches: { GrepMatch } = {}
+			local searched = 0
+			local truncated = false
+			for _, script in GrepScriptsAction._getScripts(root :: Instance) do
+				searched += 1
+				if searched % YIELD_EVERY == 0 then
+					task.wait()
+				end
+
+				local source = GrepScriptsAction._readSource(script)
+				for lineNumber, rawText in string.split(source, "\n") do
+					local text = string.gsub(rawText, "\r$", "")
+					local haystack = if caseSensitive then text else string.lower(text)
+					if string.find(haystack, needle, 1, not luaPattern) then
+						if #matches >= limit then
+							truncated = true
+							break
+						end
+						table.insert(matches, {
+							path = script:GetFullName(),
+							className = script.ClassName,
+							line = lineNumber,
+							text = string.sub(text, 1, MAX_LINE_LENGTH),
+						})
+					end
+				end
+
+				if truncated then
+					break
+				end
+			end
+
+			return {
+				matches = matches,
+				searched = searched,
+				truncated = truncated,
+			}
+		end
+	)
+end
+
+--[[
+	Lowercases a Lua pattern's literal letters, leaving each character after a
+	`%` alone, since `%S` and `%s` are opposite classes.
+]]
+function GrepScriptsAction._lowerPattern(pattern: string): string
+	local lowered = {}
+	local isEscaped = false
+	for _, char in string.split(pattern, "") do
+		table.insert(lowered, if isEscaped then char else string.lower(char))
+		isEscaped = not isEscaped and char == "%"
+	end
+	return table.concat(lowered)
+end
+
+function GrepScriptsAction._readSource(script: LuaSourceContainer): string
+	local editorOk, editorSource = pcall(function()
+		return game:GetService("ScriptEditorService"):GetEditorSource(script)
+	end)
+	if editorOk and type(editorSource) == "string" then
+		return editorSource
+	end
+
+	local ok, source = pcall(function()
+		return (script :: any).Source
+	end)
+	return if ok and type(source) == "string" then source else ""
+end
+
+--[[
+	Returns the scripts under `root`. For game, that is those of each place
+	service the plugin may read, since some refuse access.
+]]
+function GrepScriptsAction._getScripts(root: Instance): { LuaSourceContainer }
+	local roots = if root == game then game:GetChildren() else { root }
+
+	local scripts = {}
+	for _, searchRoot in roots do
+		if root == game and ENGINE_SERVICES[searchRoot.ClassName] then
+			continue
+		end
+		local ok, descendants = pcall(searchRoot.GetDescendants, searchRoot)
+		if not ok then
+			continue
+		end
+		if searchRoot:IsA("LuaSourceContainer") then
+			table.insert(scripts, searchRoot)
+		end
+		for _, descendant in descendants do
+			if descendant:IsA("LuaSourceContainer") then
+				table.insert(scripts, descendant)
+			end
+		end
+	end
+	return scripts
+end
+
+--[[
+	Walks `path` down from game, falling back to GetService for top-level names
+	that are not children by that name. A leading "game" is optional.
+]]
+function GrepScriptsAction._resolveInstance(path: string): Instance?
+	local parts = string.split(path, ".")
+	local startIndex = if parts[1] == "game" then 2 else 1
+
+	local current: Instance = game
+	for index = startIndex, #parts do
+		local part = parts[index]
+
+		local ok, child = pcall(current.FindFirstChild, current, part)
+		if ok and child then
+			current = child
+			continue
+		end
+
+		if current ~= game then
+			return nil
+		end
+
+		local serviceOk, service = pcall(game.GetService, game, part)
+		if not (serviceOk and service) then
+			return nil
+		end
+		current = service
+	end
+
+	return current
+end
+
+return GrepScriptsAction