memorydetective 1.1.0 → 1.2.1

package/dist/runtime/sourcekit/pool.js

@@ -0,0 +1,101 @@
+/**
+ * Pool of `sourcekit-lsp` clients, keyed by project root.
+ *
+ * Why a pool: starting `sourcekit-lsp` and waiting for it to be ready costs
+ * ~2 seconds. Doing that on every tool call would kill the agent loop.
+ * Instead we keep one client alive per project root and reuse it across
+ * tool invocations. After an idle window we shut it down so we're not
+ * blocking the user's build/test pipeline.
+ */
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { createSourceKitClient, } from "./client.js";
+const DEFAULT_IDLE_MS = 5 * 60_000; // 5 minutes
+const pool = new Map();
+/** Resolve a file path to its enclosing project root by walking up to the
+ *  nearest `Package.swift`, `*.xcodeproj`, or `*.xcworkspace`. Falls back
+ *  to the file's directory if nothing is found. */
+export function projectRootFor(filePath) {
+    let dir = resolvePath(filePath);
+    try {
+        dir = realpathSync(dir);
+    }
+    catch { }
+    let prev = "";
+    while (dir !== prev) {
+        if (dirHas(dir, "Package.swift") ||
+            dirHasGlob(dir, ".xcodeproj") ||
+            dirHasGlob(dir, ".xcworkspace")) {
+            return dir;
+        }
+        prev = dir;
+        dir = resolvePath(dir, "..");
+    }
+    // No marker found — use the original directory.
+    return resolvePath(filePath, "..");
+}
+function dirHas(dir, name) {
+    try {
+        return existsSync(resolvePath(dir, name));
+    }
+    catch {
+        return false;
+    }
+}
+function dirHasGlob(dir, suffix) {
+    try {
+        return readdirSync(dir).some((entry) => entry.endsWith(suffix));
+    }
+    catch {
+        return false;
+    }
+}
+/** Acquire an LSP client for a project root. Reuses an existing one if
+ *  warm, spawns + initializes one otherwise. */
+export async function acquireClient(projectRoot, opts = {}) {
+    const key = resolvePath(projectRoot);
+    const idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+    let entry = pool.get(key);
+    if (!entry) {
+        const client = await createSourceKitClient({ projectRoot: key });
+        entry = { client, lastUsed: Date.now() };
+        pool.set(key, entry);
+    }
+    entry.lastUsed = Date.now();
+    if (entry.idleTimer)
+        clearTimeout(entry.idleTimer);
+    entry.idleTimer = setTimeout(() => {
+        void shutdownClient(key);
+    }, idleMs);
+    return entry.client;
+}
+/** Manually shut down the client for a given project root. */
+export async function shutdownClient(projectRoot) {
+    const key = resolvePath(projectRoot);
+    const entry = pool.get(key);
+    if (!entry)
+        return;
+    pool.delete(key);
+    if (entry.idleTimer)
+        clearTimeout(entry.idleTimer);
+    await entry.client.dispose();
+}
+/** Shut down all pooled clients. Useful in tests + on process exit. */
+export async function shutdownAll() {
+    const keys = Array.from(pool.keys());
+    for (const key of keys) {
+        await shutdownClient(key);
+    }
+}
+// Best-effort cleanup on process exit.
+process.once("exit", () => {
+    // Synchronous only — async cleanups won't run here, but the OS will
+    // reap the subprocess.
+});
+process.once("SIGINT", () => {
+    void shutdownAll().finally(() => process.exit(0));
+});
+process.once("SIGTERM", () => {
+    void shutdownAll().finally(() => process.exit(0));
+});
+//# sourceMappingURL=pool.js.map

package/dist/runtime/sourcekit/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../../src/runtime/sourcekit/pool.ts"],"names":[],"mappings":"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"}

package/dist/runtime/sourcekit/protocol.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Typed wrappers around the LSP methods we use.
+ *
+ * Imports types from `vscode-languageserver-protocol` and converts to/from
+ * the file:// URI format LSP servers expect. All paths in the public API
+ * are absolute filesystem paths; LSP URIs only show up internally.
+ */
+import type { InitializedClient } from "./client.js";
+export interface SourceLocation {
+    filePath: string;
+    line: number;
+    character: number;
+    /** Optional end position when the LSP server returns a range. */
+    endLine?: number;
+    endCharacter?: number;
+}
+export interface ResolvedSymbol {
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    startCharacter: number;
+    endLine: number;
+    endCharacter: number;
+    /** Children symbols (methods inside a class, properties, etc.) when hierarchical. */
+    children?: ResolvedSymbol[];
+}
+/** LSP `textDocument/definition` — returns 0+ source locations. */
+export declare function lspDefinition(client: InitializedClient, filePath: string, line: number, character: number): Promise<SourceLocation[]>;
+/** LSP `textDocument/references` — returns all references in indexed projects. */
+export declare function lspReferences(client: InitializedClient, filePath: string, line: number, character: number, includeDeclaration?: boolean): Promise<SourceLocation[]>;
+/** LSP `textDocument/hover` — returns type info / docs at a position. */
+export declare function lspHover(client: InitializedClient, filePath: string, line: number, character: number): Promise<{
+    contents: string;
+} | null>;
+/** LSP `textDocument/documentSymbol` — returns top-level + nested symbols. */
+export declare function lspDocumentSymbol(client: InitializedClient, filePath: string): Promise<ResolvedSymbol[]>;

package/dist/runtime/sourcekit/protocol.js

@@ -0,0 +1,161 @@
+/**
+ * Typed wrappers around the LSP methods we use.
+ *
+ * Imports types from `vscode-languageserver-protocol` and converts to/from
+ * the file:// URI format LSP servers expect. All paths in the public API
+ * are absolute filesystem paths; LSP URIs only show up internally.
+ */
+import { resolve as resolvePath } from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { SymbolKind, } from "vscode-languageserver-protocol";
+const SYMBOL_KIND_NAMES = {
+    [SymbolKind.File]: "file",
+    [SymbolKind.Module]: "module",
+    [SymbolKind.Namespace]: "namespace",
+    [SymbolKind.Package]: "package",
+    [SymbolKind.Class]: "class",
+    [SymbolKind.Method]: "method",
+    [SymbolKind.Property]: "property",
+    [SymbolKind.Field]: "field",
+    [SymbolKind.Constructor]: "constructor",
+    [SymbolKind.Enum]: "enum",
+    [SymbolKind.Interface]: "interface",
+    [SymbolKind.Function]: "function",
+    [SymbolKind.Variable]: "variable",
+    [SymbolKind.Constant]: "constant",
+    [SymbolKind.String]: "string",
+    [SymbolKind.Number]: "number",
+    [SymbolKind.Boolean]: "boolean",
+    [SymbolKind.Array]: "array",
+    [SymbolKind.Object]: "object",
+    [SymbolKind.Key]: "key",
+    [SymbolKind.Null]: "null",
+    [SymbolKind.EnumMember]: "enum-member",
+    [SymbolKind.Struct]: "struct",
+    [SymbolKind.Event]: "event",
+    [SymbolKind.Operator]: "operator",
+    [SymbolKind.TypeParameter]: "type-parameter",
+};
+function uriOf(filePath) {
+    return pathToFileURL(resolvePath(filePath)).href;
+}
+function pathOf(uri) {
+    return fileURLToPath(uri);
+}
+/** LSP `textDocument/definition` — returns 0+ source locations. */
+export async function lspDefinition(client, filePath, line, character) {
+    client.didOpen(filePath);
+    const params = {
+        textDocument: { uri: uriOf(filePath) },
+        position: { line, character },
+    };
+    const result = await client.sendRequest("textDocument/definition", params);
+    return locationsToArray(result);
+}
+/** LSP `textDocument/references` — returns all references in indexed projects. */
+export async function lspReferences(client, filePath, line, character, includeDeclaration = true) {
+    client.didOpen(filePath);
+    const params = {
+        textDocument: { uri: uriOf(filePath) },
+        position: { line, character },
+        context: { includeDeclaration },
+    };
+    const result = await client.sendRequest("textDocument/references", params);
+    return locationsToArray(result);
+}
+/** LSP `textDocument/hover` — returns type info / docs at a position. */
+export async function lspHover(client, filePath, line, character) {
+    client.didOpen(filePath);
+    const params = {
+        textDocument: { uri: uriOf(filePath) },
+        position: { line, character },
+    };
+    const result = await client.sendRequest("textDocument/hover", params);
+    if (!result)
+        return null;
+    const contents = hoverContentsToString(result.contents);
+    return { contents };
+}
+/** LSP `textDocument/documentSymbol` — returns top-level + nested symbols. */
+export async function lspDocumentSymbol(client, filePath) {
+    client.didOpen(filePath);
+    const params = {
+        textDocument: { uri: uriOf(filePath) },
+    };
+    const result = await client.sendRequest("textDocument/documentSymbol", params);
+    if (!result)
+        return [];
+    // Hierarchical case (DocumentSymbol[]).
+    if (result.length > 0 && "range" in result[0] && "children" in result[0]) {
+        return result.map((s) => docSymbolToResolved(s, filePath));
+    }
+    // Flat case (SymbolInformation[]).
+    return result.map((s) => symInfoToResolved(s));
+}
+function docSymbolToResolved(s, filePath) {
+    return {
+        name: s.name,
+        kind: SYMBOL_KIND_NAMES[s.kind] ?? `kind-${s.kind}`,
+        filePath,
+        startLine: s.range.start.line,
+        startCharacter: s.range.start.character,
+        endLine: s.range.end.line,
+        endCharacter: s.range.end.character,
+        children: s.children?.map((c) => docSymbolToResolved(c, filePath)),
+    };
+}
+function symInfoToResolved(s) {
+    return {
+        name: s.name,
+        kind: SYMBOL_KIND_NAMES[s.kind] ?? `kind-${s.kind}`,
+        filePath: pathOf(s.location.uri),
+        startLine: s.location.range.start.line,
+        startCharacter: s.location.range.start.character,
+        endLine: s.location.range.end.line,
+        endCharacter: s.location.range.end.character,
+    };
+}
+function locationsToArray(result) {
+    if (!result)
+        return [];
+    const arr = Array.isArray(result) ? result : [result];
+    const out = [];
+    for (const item of arr) {
+        if ("targetUri" in item) {
+            // LocationLink
+            out.push({
+                filePath: pathOf(item.targetUri),
+                line: item.targetSelectionRange.start.line,
+                character: item.targetSelectionRange.start.character,
+                endLine: item.targetSelectionRange.end.line,
+                endCharacter: item.targetSelectionRange.end.character,
+            });
+        }
+        else {
+            // Location
+            out.push({
+                filePath: pathOf(item.uri),
+                line: item.range.start.line,
+                character: item.range.start.character,
+                endLine: item.range.end.line,
+                endCharacter: item.range.end.character,
+            });
+        }
+    }
+    return out;
+}
+function hoverContentsToString(c) {
+    if (!c)
+        return "";
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c)) {
+        return c
+            .map((part) => (typeof part === "string" ? part : part.value))
+            .join("\n");
+    }
+    if ("value" in c)
+        return c.value;
+    return "";
+}
+//# sourceMappingURL=protocol.js.map

package/dist/runtime/sourcekit/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/runtime/sourcekit/protocol.ts"],"names":[],"mappings":"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"}

package/dist/tools/swift/_helpers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared utilities for the Swift source-bridging tools.
+ *
+ * Position-finding via local regex pre-scan is the load-bearing trick: we
+ * locate the symbol's declaration in a candidate file with a quick regex
+ * before sending its position to SourceKit-LSP. This avoids LSP's
+ * comparatively slow workspace symbol search.
+ */
+export interface SymbolPosition {
+    line: number;
+    character: number;
+    matchedText: string;
+}
+/**
+ * Find the first declaration of `symbolName` in the file.
+ *
+ * Looks for the symbol after one of Swift's declaration keywords
+ * (`class`, `struct`, `enum`, `protocol`, `func`, `var`, `let`,
+ * `actor`, `extension`). Falls back to the first standalone-word
+ * occurrence so we still surface a position when the name is referenced
+ * but not declared in the file (e.g. an extension method on a type
+ * declared elsewhere).
+ *
+ * Returns 0-based positions matching LSP's convention.
+ */
+export declare function findSymbolDeclaration(filePath: string, symbolName: string): SymbolPosition | null;
+export declare function escapeRegex(s: string): string;
+/** Extract a few lines of context around `line` for snippet display. */
+export declare function snippetAt(filePath: string, line: number, padding?: number): string;

package/dist/tools/swift/_helpers.js

@@ -0,0 +1,64 @@
+/**
+ * Shared utilities for the Swift source-bridging tools.
+ *
+ * Position-finding via local regex pre-scan is the load-bearing trick: we
+ * locate the symbol's declaration in a candidate file with a quick regex
+ * before sending its position to SourceKit-LSP. This avoids LSP's
+ * comparatively slow workspace symbol search.
+ */
+import { readFileSync } from "node:fs";
+/**
+ * Find the first declaration of `symbolName` in the file.
+ *
+ * Looks for the symbol after one of Swift's declaration keywords
+ * (`class`, `struct`, `enum`, `protocol`, `func`, `var`, `let`,
+ * `actor`, `extension`). Falls back to the first standalone-word
+ * occurrence so we still surface a position when the name is referenced
+ * but not declared in the file (e.g. an extension method on a type
+ * declared elsewhere).
+ *
+ * Returns 0-based positions matching LSP's convention.
+ */
+export function findSymbolDeclaration(filePath, symbolName) {
+    const text = readFileSync(filePath, "utf8");
+    const lines = text.split(/\r?\n/);
+    const declRe = new RegExp(`\\b(?:class|struct|enum|protocol|func|var|let|actor|extension)\\s+${escapeRegex(symbolName)}\\b`);
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(declRe);
+        if (m) {
+            const ch = lines[i].indexOf(symbolName, m.index ?? 0);
+            if (ch >= 0) {
+                return { line: i, character: ch, matchedText: lines[i] };
+            }
+        }
+    }
+    const wordRe = new RegExp(`\\b${escapeRegex(symbolName)}\\b`);
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(wordRe);
+        if (m) {
+            return {
+                line: i,
+                character: m.index ?? 0,
+                matchedText: lines[i],
+            };
+        }
+    }
+    return null;
+}
+export function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Extract a few lines of context around `line` for snippet display. */
+export function snippetAt(filePath, line, padding = 1) {
+    try {
+        const text = readFileSync(filePath, "utf8");
+        const lines = text.split(/\r?\n/);
+        const start = Math.max(0, line - padding);
+        const end = Math.min(lines.length - 1, line + padding);
+        return lines.slice(start, end + 1).join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=_helpers.js.map

package/dist/tools/swift/_helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_helpers.js","sourceRoot":"","sources":["../../../src/tools/swift/_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQvC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,UAAkB;IAElB,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,qEAAqE,WAAW,CAAC,UAAU,CAAC,KAAK,CAClG,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;YACtD,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;gBACZ,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC;YACN,OAAO;gBACL,IAAI,EAAE,CAAC;gBACP,SAAS,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;gBACvB,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;aACtB,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,IAAY,EAAE,OAAO,GAAG,CAAC;IACnE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC;QACvD,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/tools/swift/findSymbolReferences.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { type SourceLocation } from "../../runtime/sourcekit/protocol.js";
+export declare const swiftFindSymbolReferencesSchema: z.ZodObject<{
+    symbolName: z.ZodString;
+    filePath: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    includeDeclaration: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    symbolName: string;
+    filePath: string;
+    includeDeclaration: boolean;
+    projectRoot?: string | undefined;
+}, {
+    symbolName: string;
+    filePath: string;
+    projectRoot?: string | undefined;
+    includeDeclaration?: boolean | undefined;
+}>;
+export type SwiftFindSymbolReferencesInput = z.infer<typeof swiftFindSymbolReferencesSchema>;
+export interface SwiftFindSymbolReferencesResult {
+    ok: boolean;
+    symbolName: string;
+    totalReferences: number;
+    references: Array<SourceLocation & {
+        snippet?: string;
+    }>;
+    /** True when the IndexStoreDB was missing — references are likely incomplete. Build the index with `swift build -Xswiftc -index-store-path -Xswiftc <project>/.build/index/store`. */
+    needsIndex?: boolean;
+}
+export declare function swiftFindSymbolReferences(input: SwiftFindSymbolReferencesInput): Promise<SwiftFindSymbolReferencesResult>;

package/dist/tools/swift/findSymbolReferences.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { acquireClient, projectRootFor } from "../../runtime/sourcekit/pool.js";
+import { lspReferences, } from "../../runtime/sourcekit/protocol.js";
+import { findSymbolDeclaration, snippetAt } from "./_helpers.js";
+export const swiftFindSymbolReferencesSchema = z.object({
+    symbolName: z
+        .string()
+        .min(1)
+        .describe("Name of the Swift symbol to find references for."),
+    filePath: z
+        .string()
+        .min(1)
+        .describe("Path to a Swift file where the symbol is declared. The LSP query needs a position; we locate it in this file via a regex pre-scan."),
+    projectRoot: z
+        .string()
+        .optional()
+        .describe("Override the project root. Default discovers the nearest Package.swift / .xcodeproj / .xcworkspace."),
+    includeDeclaration: z
+        .boolean()
+        .default(true)
+        .describe("Include the declaration site itself in the result set."),
+});
+export async function swiftFindSymbolReferences(input) {
+    const file = resolvePath(input.filePath);
+    if (!existsSync(file)) {
+        throw new Error(`File not found: ${file}`);
+    }
+    const root = input.projectRoot
+        ? resolvePath(input.projectRoot)
+        : projectRootFor(file);
+    const pos = findSymbolDeclaration(file, input.symbolName);
+    if (!pos) {
+        return {
+            ok: true,
+            symbolName: input.symbolName,
+            totalReferences: 0,
+            references: [],
+        };
+    }
+    const client = await acquireClient(root);
+    const refs = await lspReferences(client, file, pos.line, pos.character, input.includeDeclaration ?? true);
+    const refsWithSnippets = refs.map((r) => ({
+        ...r,
+        snippet: snippetAt(r.filePath, r.line),
+    }));
+    return {
+        ok: true,
+        symbolName: input.symbolName,
+        totalReferences: refs.length,
+        references: refsWithSnippets,
+        needsIndex: refs.length === 0 ? true : undefined,
+    };
+}
+//# sourceMappingURL=findSymbolReferences.js.map

package/dist/tools/swift/findSymbolReferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findSymbolReferences.js","sourceRoot":"","sources":["../../../src/tools/swift/findSymbolReferences.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EACL,aAAa,GAEd,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEjE,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,kDAAkD,CAAC;IAC/D,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,oIAAoI,CACrI;IACH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,qGAAqG,CACtG;IACH,kBAAkB,EAAE,CAAC;SAClB,OAAO,EAAE;SACT,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,wDAAwD,CAAC;CACtE,CAAC,CAAC;AAeH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAqC;IAErC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW;QAC5B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC;QAChC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAEzB,MAAM,GAAG,GAAG,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;YACL,EAAE,EAAE,IAAI;YACR,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,eAAe,EAAE,CAAC;YAClB,UAAU,EAAE,EAAE;SACf,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,aAAa,CAC9B,MAAM,EACN,IAAI,EACJ,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,SAAS,EACb,KAAK,CAAC,kBAAkB,IAAI,IAAI,CACjC,CAAC;IAEF,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACxC,GAAG,CAAC;QACJ,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC;KACvC,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,EAAE,EAAE,IAAI;QACR,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,eAAe,EAAE,IAAI,CAAC,MAAM;QAC5B,UAAU,EAAE,gBAAgB;QAC5B,UAAU,EAAE,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;KACjD,CAAC;AACJ,CAAC"}

package/dist/tools/swift/getHoverInfo.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const swiftGetHoverInfoSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    line: z.ZodNumber;
+    character: z.ZodNumber;
+    projectRoot: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    line: number;
+    character: number;
+    filePath: string;
+    projectRoot?: string | undefined;
+}, {
+    line: number;
+    character: number;
+    filePath: string;
+    projectRoot?: string | undefined;
+}>;
+export type SwiftGetHoverInfoInput = z.infer<typeof swiftGetHoverInfoSchema>;
+export interface SwiftGetHoverInfoResult {
+    ok: boolean;
+    filePath: string;
+    /** Markdown / plaintext hover content from SourceKit-LSP. */
+    contents: string;
+    /** Best-effort extracted declaration fragment (e.g. "class DetailViewModel : ObservableObject"). */
+    typeName?: string;
+}
+export declare function swiftGetHoverInfo(input: SwiftGetHoverInfoInput): Promise<SwiftGetHoverInfoResult>;

package/dist/tools/swift/getHoverInfo.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { acquireClient, projectRootFor } from "../../runtime/sourcekit/pool.js";
+import { lspHover } from "../../runtime/sourcekit/protocol.js";
+export const swiftGetHoverInfoSchema = z.object({
+    filePath: z.string().min(1).describe("Absolute path to a Swift source file."),
+    line: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Zero-based line number (LSP convention)."),
+    character: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Zero-based UTF-16 character offset within the line."),
+    projectRoot: z.string().optional(),
+});
+export async function swiftGetHoverInfo(input) {
+    const file = resolvePath(input.filePath);
+    if (!existsSync(file)) {
+        throw new Error(`File not found: ${file}`);
+    }
+    const root = input.projectRoot
+        ? resolvePath(input.projectRoot)
+        : projectRootFor(file);
+    const client = await acquireClient(root);
+    const result = await lspHover(client, file, input.line, input.character);
+    const contents = result?.contents ?? "";
+    const typeName = extractTypeName(contents);
+    return { ok: true, filePath: file, contents, typeName };
+}
+function extractTypeName(hover) {
+    // Hover output usually leads with a code fence containing the
+    // declaration line (e.g. "let foo: Bar" or "class Baz : Quux").
+    const m = hover.match(/\b(class|struct|enum|protocol|actor|func|var|let)\s+\S+/);
+    return m ? m[0] : undefined;
+}
+//# sourceMappingURL=getHoverInfo.js.map

package/dist/tools/swift/getHoverInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getHoverInfo.js","sourceRoot":"","sources":["../../../src/tools/swift/getHoverInfo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAE/D,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IAC7E,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,EAAE;SACL,WAAW,EAAE;SACb,QAAQ,CAAC,0CAA0C,CAAC;IACvD,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,EAAE;SACL,WAAW,EAAE;SACb,QAAQ,CAAC,qDAAqD,CAAC;IAClE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAaH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAA6B;IAE7B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW;QAC5B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC;QAChC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACzB,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC3C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,8DAA8D;IAC9D,gEAAgE;IAChE,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CACnB,yDAAyD,CAC1D,CAAC;IACF,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9B,CAAC"}

package/dist/tools/swift/getSymbolDefinition.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { type SourceLocation } from "../../runtime/sourcekit/protocol.js";
+export declare const swiftGetSymbolDefinitionSchema: z.ZodObject<{
+    symbolName: z.ZodString;
+    hint: z.ZodOptional<z.ZodObject<{
+        filePath: z.ZodOptional<z.ZodString>;
+        module: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        module?: string | undefined;
+        filePath?: string | undefined;
+    }, {
+        module?: string | undefined;
+        filePath?: string | undefined;
+    }>>;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    candidatePaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    symbolName: string;
+    hint?: {
+        module?: string | undefined;
+        filePath?: string | undefined;
+    } | undefined;
+    projectRoot?: string | undefined;
+    candidatePaths?: string[] | undefined;
+}, {
+    symbolName: string;
+    hint?: {
+        module?: string | undefined;
+        filePath?: string | undefined;
+    } | undefined;
+    projectRoot?: string | undefined;
+    candidatePaths?: string[] | undefined;
+}>;
+export type SwiftGetSymbolDefinitionInput = z.infer<typeof swiftGetSymbolDefinitionSchema>;
+export interface SwiftGetSymbolDefinitionResult {
+    ok: boolean;
+    symbolName: string;
+    /** Definition locations returned by SourceKit-LSP (or pre-scan when LSP returns nothing). */
+    definitions: SourceLocation[];
+    /** When set, indicates we located the symbol via filename pre-scan rather than a true LSP query. */
+    preScanHit?: {
+        filePath: string;
+        matchedText: string;
+    };
+}
+export declare function swiftGetSymbolDefinition(input: SwiftGetSymbolDefinitionInput): Promise<SwiftGetSymbolDefinitionResult>;