PSResourceGet module assumes the required modules statement location in script file in specific place

[peetrike]

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

About Requires states that the #Requires statements can appear on any line in a script. Yet the module PSResourceGet assumes that #Requires -Modules statement is above comment based help block.

@'
<#PSScriptInfo
.VERSION 1.0.0
.GUID {0}
.AUTHOR Me
.TAGS
#>
<#
.DESCRIPTION
just for testing
#>

#Requires -Modules mymodule
'@ -f (new-guid) | set-content -path test.ps1

Get-PSScriptFileInfo -Path .\test.ps1 | select -ExpandProperty scriptRequiresComment

Expected behavior

RequiredModules
---------------
{mymodule}

Actual behavior

RequiredModules
---------------
{}

Error details

No response

Environment data

PSResourceGet: 0.5.22 PowerShell: 5.1 or 7.3.5

Visuals

No response

[peetrike]

Publish-PSResource makes the same assumption

[alerickson]

@anamnavi this should probably be tacked on with the others, let me know if you want me to look at this

[anamnavi]

@peetrike You're right that this differs from the docs. We can update this to mention how PSResourceGet differs. We would recommend that users place the #Requires comments before the help comment block (the one that includes .DESCRIPTION

From our code perspective, this was intentional. We assume the last "script metadata" like info will be within the help block. Anything after the closing bracket of the help block is "the rest of the file" to us. And we just grab those lines and dump it in a bucket until we reach the end of the file, without actually making meaning of that portion's contents.

So per our code the Requires has to come before the help block. If you wanted to, you could put the requires anywhere before that, but not in the script metadata block (ie the one that is <#PSScriptInfo ... #>)

[peetrike]

As this is different from PowerShellGet module and About Requires document, this should definitely be documented. As well as location of script metadata block. I assume that this is also expected to be before help block.

It would be nice, if Test-PSScriptFileInfo could explain, what exactly is non-conformant with script. For example in Verbose or Warning stream. Or when adding separate command-line parameter.

[anamnavi]

@sdwheeler we need to include this in the docs, thanks!

[sdwheeler]

@peetrike Note that for Get-Help to work for the comment-based help, you need a blank line between the comment blocks. This doesn't affect the PSResourceGet issue but I wanted to call it out.

[peetrike]

actually, it did affect PowerShellGet, when there was no blank line between script metadata and help block. Not sure about Get-Help. I just added Description as this was required to publish script.