Skip to content

Commit d1faccf

Browse files
Render Show Help in a read-only editor pane
Show Help previously printed `Get-Help` output into the integrated console and, when nothing was selected, sent the entire document as the help target. The latter was a `getWordRangeAtPosition` bug: off a word it returns `undefined`, and `doc.getText(undefined)` returns the whole document. Resolve the word at the cursor explicitly (falling back to the selection), send it to the new `powerShell/showHelp` request, and render the returned text in a read-only virtual document so help opens in a proper editor pane instead of an editable untitled buffer. Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 75097e8 commit d1faccf

1 file changed

Lines changed: 116 additions & 26 deletions

File tree

‎src/features/ShowHelp.ts‎

Lines changed: 116 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,56 +2,146 @@
22
// Licensed under the MIT License.
33

44
import vscode = require("vscode");
5-
import { NotificationType } from "vscode-languageclient";
5+
import { RequestType } from "vscode-languageclient";
66
import type { LanguageClient } from "vscode-languageclient/node";
77
import { LanguageClientConsumer } from "../languageClientConsumer";
88

9-
interface IShowHelpNotificationArguments {}
9+
export interface IShowHelpArguments {
10+
text: string;
11+
}
12+
13+
export interface IShowHelpResult {
14+
helpText: string;
15+
}
16+
17+
export const ShowHelpRequestType = new RequestType<
18+
IShowHelpArguments,
19+
IShowHelpResult,
20+
void
21+
>("powerShell/showHelp");
22+
23+
// Serves Get-Help output as read-only virtual documents (scheme "powershell-help"),
24+
// so help opens in an editor pane that is searchable and copyable but never marked
25+
// dirty (no save/discard prompt). The command name is carried in the URI path.
26+
class ShowHelpContentProvider implements vscode.TextDocumentContentProvider {
27+
private readonly onDidChangeEmitter = new vscode.EventEmitter<vscode.Uri>();
28+
public readonly onDidChange = this.onDidChangeEmitter.event;
29+
30+
public refresh(uri: vscode.Uri): void {
31+
this.onDidChangeEmitter.fire(uri);
32+
}
1033

11-
export const ShowHelpNotificationType =
12-
new NotificationType<IShowHelpNotificationArguments>("powerShell/showHelp");
34+
public async provideTextDocumentContent(uri: vscode.Uri): Promise<string> {
35+
const commandName = uri.path;
36+
const client = await LanguageClientConsumer.getLanguageClient();
37+
const result = await client.sendRequest(ShowHelpRequestType, {
38+
text: commandName,
39+
});
40+
return result.helpText || `No help found for '${commandName}'.`;
41+
}
42+
43+
public dispose(): void {
44+
this.onDidChangeEmitter.dispose();
45+
}
46+
}
1347

1448
export class ShowHelpFeature extends LanguageClientConsumer {
49+
public static readonly scheme = "powershell-help";
50+
1551
private command: vscode.Disposable;
52+
private contentProvider: ShowHelpContentProvider;
53+
private providerRegistration: vscode.Disposable;
1654

1755
constructor() {
1856
super();
57+
this.contentProvider = new ShowHelpContentProvider();
58+
this.providerRegistration =
59+
vscode.workspace.registerTextDocumentContentProvider(
60+
ShowHelpFeature.scheme,
61+
this.contentProvider,
62+
);
63+
1964
this.command = vscode.commands.registerCommand(
2065
"PowerShell.ShowHelp",
2166
async (item?) => {
22-
if (!item?.Name) {
23-
const editor = vscode.window.activeTextEditor;
24-
if (editor === undefined) {
25-
return;
26-
}
27-
28-
const selection = editor.selection;
29-
const doc = editor.document;
30-
const cwr = doc.getWordRangeAtPosition(selection.active);
31-
const text = doc.getText(cwr);
32-
33-
const client =
34-
await LanguageClientConsumer.getLanguageClient();
35-
await client.sendNotification(ShowHelpNotificationType, {
36-
text,
37-
});
38-
} else {
39-
const client =
40-
await LanguageClientConsumer.getLanguageClient();
41-
await client.sendNotification(ShowHelpNotificationType, {
42-
text: item.Name,
43-
});
67+
const text = ShowHelpFeature.resolveCommandName(item);
68+
if (text === undefined) {
69+
return;
4470
}
71+
72+
await this.showHelp(text);
4573
},
4674
);
4775
}
4876

77+
// Determines the command to show help for: an explicit item, the current
78+
// selection, or the word under the cursor. Returns undefined (and surfaces a
79+
// hint) when there's nothing to look up, rather than falling back to the
80+
// entire document.
81+
private static resolveCommandName(item?: {
82+
Name?: string;
83+
}): string | undefined {
84+
if (item?.Name) {
85+
return item.Name;
86+
}
87+
88+
const editor = vscode.window.activeTextEditor;
89+
if (editor === undefined) {
90+
return undefined;
91+
}
92+
93+
const document = editor.document;
94+
const selection = editor.selection;
95+
96+
if (!selection.isEmpty) {
97+
return document.getText(selection);
98+
}
99+
100+
const wordRange = document.getWordRangeAtPosition(selection.active);
101+
if (wordRange === undefined) {
102+
void vscode.window.showInformationMessage(
103+
"Place the cursor on a PowerShell command to show its help.",
104+
);
105+
return undefined;
106+
}
107+
108+
return document.getText(wordRange);
109+
}
110+
111+
private async showHelp(commandName: string): Promise<void> {
112+
const uri = vscode.Uri.from({
113+
scheme: ShowHelpFeature.scheme,
114+
path: commandName,
115+
});
116+
117+
// Re-fetch in case the help changed since this document was last opened.
118+
this.contentProvider.refresh(uri);
119+
120+
// If this command's help is already open, reuse that editor's column so
121+
// repeated clicks focus the existing pane instead of stacking duplicates.
122+
const existingColumn = vscode.window.tabGroups.all
123+
.flatMap((group) => group.tabs)
124+
.find(
125+
(tab) =>
126+
tab.input instanceof vscode.TabInputText &&
127+
tab.input.uri.toString() === uri.toString(),
128+
)?.group.viewColumn;
129+
130+
const document = await vscode.workspace.openTextDocument(uri);
131+
await vscode.window.showTextDocument(document, {
132+
preview: true,
133+
viewColumn: existingColumn ?? vscode.ViewColumn.Beside,
134+
});
135+
}
136+
49137
public override onLanguageClientSet(
50138
_languageClient: LanguageClient,
51139
// eslint-disable-next-line @typescript-eslint/no-empty-function
52140
): void {}
53141

54142
public dispose(): void {
55143
this.command.dispose();
144+
this.providerRegistration.dispose();
145+
this.contentProvider.dispose();
56146
}
57147
}

0 commit comments

Comments
 (0)