Unsafe characters in command names breaks markdown file creation on Windows

ShaunLawrie commented 1 year ago

Prerequisites

[X] Write a descriptive title.
[X] Make sure you are able to repro it on the latest released version
[X] Search the existing issues.

Steps to reproduce

Creating markdown help for commands that have unsafe characters in their name causes the file creation to fail on Windows. I ran into this trying to generate help docs for PowerShellAI because it uses some unusual command names that contain question marks in them.

Expected behavior

PS> New-MarkdownHelp -Module "PowerShellAI"

# Markdown is created for all exported functions and aliases

Actual behavior

PS5> New-MarkdownHelp -Module "PowerShellAI"

# Most functions are exported to markdown then the file creation fails for "gh?"

PSCore> New-MarkdownHelp -Module "PowerShellAI"

# Most functions are exported to markdown then the file creation fails for "gh?"

Error details

Set-Content : An object at the specified path psaihelp4\gh?.md does not exist, or has been filtered by the -Include or -Exclude parameter.
At C:\Users\shaun.lawrie\Documents\WindowsPowerShell\Modules\platyPS\0.14.2\platyPS.psm1:1956 char:5
+     Set-Content -Path $Path -Value ''
+     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (System.String[]:String[]) [Set-Content], Exception
    + FullyQualifiedErrorId : ItemNotFound,Microsoft.PowerShell.Commands.SetContentCommand

Exception calling "WriteAllText" with "3" argument(s): "Empty path name is not legal."
At C:\Users\shaun.lawrie\Documents\WindowsPowerShell\Modules\platyPS\0.14.2\platyPS.psm1:1958 char:5
+     [System.IO.File]::WriteAllText($resolvedPath, $value, $Encoding)
+     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : ArgumentException

Environment data

PS> Get-Module platyPS -ListAvailable

    Directory: C:\Users\shaun.lawrie\Documents\WindowsPowerShell\Modules

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Script     0.14.2     platyPS                             {New-MarkdownHelp, Get-MarkdownMetadata, New-ExternalHelp, New-YamlHelp...}

PS> $PSVersionTable

Name                           Value
----                           -----
PSVersion                      5.1.22000.1335
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.22000.1335
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

# This also fails in PowerShell core 7

Name                           Value
----                           -----
PSVersion                      7.3.4
PSEdition                      Core
GitCommitId                    7.3.4
OS                             Microsoft Windows 10.0.22000
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Visuals

sdwheeler commented 10 months ago

I am not sure what the impact of unsafe characters would be on Get-Help and Update-Help. The filename wouldn't match the true command name. This is a pattern that we would never support internally.

I am not sure we should try to support this for external customers.

sdwheeler commented 3 months ago

See this documentation for a list of characters not allowed in command names:

https://learn.microsoft.com/powershell/scripting/developer/cmdlet/required-development-guidelines#cmdlet-names-characters-that-cannot-be-used-rd02

PowerShell / platyPS