Discuss project file (psd1) management with Plaster

[daviwil]

@kapilmb and I were talking about Script Analyzer improvements a few days ago, specifically around module-level analysis that can take all of the module's script files into account. One thing we will need for that is a way to easily find which .psd1 files actually get loaded as part of the module so that we can consider them in analysis. It seems that the best way to accomplish this is to encourage module authors to keep their .psd1's ScriptsToProcess field up to date with a complete list of files to be loaded.

Since nobody wants to maintain this by hand, it makes sense that some component in our editor tooling ecosystem take care of this for the user. Plaster seems like an obvious choice because we already enable single-file creation. It's not hard to imagine Plaster also updating the .psd1 when a new file is created as part of a project.

What do you think about adding some new commands to the module which enable file management for module projects? Maybe something like the following (definitely not married to the name):

Add-ModuleScript -Path ScriptToAdd.ps1 -ModulePath ..\path\to\MyModule.psd1

For existing projects which already have a bunch of files which aren't added explicitly to the .psd1, the VS Code integration could prompt the user to add them or provide some quick means of doing so (like an "Add to Project/Module" command or something.

This will also be very useful once we start adding templates for creating individual files to be added to a module. I think there is a great deal that Plaster can help the developer with after the initial project is created from a template.

What do you think?

[rkeithhill]

I don't think you want to use ScriptsToProcess that is for a different purpose:

Specifies script (.ps1) files that run in the caller's session state when the module is imported. 
You can use these scripts to prepare an environment, just as you might use a login script.

But FileList would apply. In fact, I was thinking that for PlasterBuild, one of the helper functions would update the module manifest's FileList with the list of files that get dropped into Release folder. I "think" that is where this belongs.

[daviwil]

Hmmm, you're right, ScriptsToProcess isn't right for that. I guess the problem with FileList is that it's treated as an "inventory" rather than as a list of scripts that get loaded by PowerShell when the module is loaded. I'm trying to find a way to keep people from using Get-ChildItem on their .psd1 files and dot sourcing them since that can be tricky for us to evaluate at analysis time.

Maybe we can provide a helper function for the .psm1 file that can load the files listed in FileList? Or maybe the assumption can be that they can load their module's script files whenever and however they want, but FileList must be filled in to get accurate module-level analysis.

[rkeithhill]

using Get-ChildItem on their .psd1 files

Do you mean .ps1 files? Could this be a setting in the PSSA settings file? I would like to be able to specify directories to examine/ignore in the settings file.

[daviwil]

@rkeithhill yep, mistyped that. Well... maybe it could be a setting on PSSA settings, but I kinda feel like this should be something that's a part of a "project definition", i.e. the .psd1. It could be useful to tools other than PSSA. I'm not ruling that option out, though, since PSSA would be the primary consumer of that information at first.

[rkeithhill]

Could we analyze files in FileList that have extension *.ps1 and ignore the rest? That would result in some extra files (like examples) but that might not be too bad.

[daviwil]

Yep, that's what I had in mind. Looks like there are a fair amount of GitHub repos with usage of FileList, including non-ps1 files:

https://github.com/search?utf8=%E2%9C%93&q=filelist+extension%3Apsd1&type=Code&ref=advsearch&l=&l=

I wonder if maybe it's better to use something else though just to avoid confusion or conflict with other uses of that field.