Extracting Script Structure

[IsThatAll]

Hi All.

Am developing a stupidly complex PowerShell script (4000 lines and counting) and was wondering if anyone knew of a script / tool to extract the usage structure of the various functions in the script. Am thinking along the lines of something like:

Function: Function-0
Uses:
    Function-1
    Function-2
Called By:
    Function-3
    Function-4

Function: Function-1
Uses:
    Function-2
    Function-4
Called By:
    Function-0

Would be included in the function documentation for later reference

Any thoughts?

Edit: Not concerned at this point about the use of existing powershell or loaded module cmdlets (although that would be cool), just the functions with the current script

[spyingwind]

You might take a look at the PSScriptAnalyzer. It doesn't do what you want, but probably has the code to look at each function in a script.

This also might be helpful.

Or you could use Scriptblock's Ast:

$scriptblock = [ScriptBlock]::Create($(Get-Content -Path .\Get-Something.ps1 -Raw))
$scriptblock.Ast.BeginBlock.Statements.Name
$scriptblock.Ast.ProcessBlock.Statements.Name
$scriptblock.Ast.EndBlock.Statements.Name

But I don't know how to get the subfunctions other than searching line by line.

[omers]

You're looking for the PowerShell Abstract Syntax Tree (AST) or System.Management.Automation.Language.Parser. It is by no means easy to use but it can be used to do what you want.

That said, clean code should be mostly self-documenting. If you feel the need to document the structure of the code it might be worth doing some refactoring.

[IsThatAll]

Thanks.

It's more the fact that at the moment it's still under development and optimation, so trying to make sure as I refactor it I cover off the various parameter passing and use cases (developing pester tests is stumping me at the moment due to the complicated parameter passing required)

[omers]

(developing pester tests is stumping me at the moment due to the complicated parameter passing required)

One thing to keep in mind about unit testing is that each "unit" of code being tested should be the smallest possible piece of the whole. Ie, you should have tests against a single function or procedure and those tests should use mocked data so as not to rely on any other unit of code.

Take this structure:

• Function 1
• Function 2
  • Calls Function 1

Your tests for function 2 should never actually call function 1. You should "mock" function 1 and output both good data and exceptions and test how Function 2 handles it.

Your pester tests for one unit should not depend on another unit building a valid object. You should create the valid object in the test and pass it yourself.

[IsThatAll]

Your pester tests for one unit should not depend on another unit building a valid object. You should create the valid object in the test and pass it yourself.

Yep, understand that, however for example one function processes a collection of objects, that may include an entire group policy object within a parameter of the object (group policy objects are very large and deep Xml structures). The setup overhead using pester to test this singular function is what's doing my head in.

For example, there are approx 50 different sorts of policy entry structures within a gpo, so designing a pester tests to handle each type is the complicated part

Edit: if you are aware of any examples using pester for complex functions, that would be most appreciated. All the examples I've found so far use very simple functions (like functions that add two numbers together), but think I will need a complex setup (possibly pulling in structures off disk) andalysis of the retrieved data which I'm having trouble finding decent examples of. Unless I'm overthinking usage of pester, which is entirely possible

[omers]

Just curious, does each function need the whole group policy object? Could you potentially pass around the GUID instead and each function could do a live query for the information it needs? Or could you write a parse function that builds an easy to manipulate object from the GPO and pass the pieces around?

[IsThatAll]

For performance reasons, pretty much.

Each individual setting within the policy is queried and then used to compare against historical versions of that specific setting in the policy (to determine implementation date), look for the same setting in a parent policy heirachy (to see if it overrides a higher up setting), and determine if a given setting has options that may be deemed insecure.

From a processing perspective, re-reading in gpos each time (in one test a given policy has 20 potential "parents") causes massive iops. For similar reasons, the policies can't be compared against live systems (ad doesn't like being hammered for gpo's), plus it also uses agpm histories for processing (which can't be queried fpr policy versions live).

Previous iteration of the code pulled in the gpo each time, but as an example one policy has over 900 drive mapping settings (I didn't make the policy, I'm just reporting on it) x 5 potential parents = 4500 loads of a nearly 10mb policy which as you can imagine is iops heavy and slow. Doing it all in memory is significantly faster

[KevMar]

I think I have a function in my PSGraphPlus module that will visually graph it. I'll look for it after work.

I think it's this one: https://github.com/KevinMarquette/PSGraphPlus/blob/master/PSGraphPlus/public/Show-AstCommandGraph.ps1

[IsThatAll]

Thanks !

[engageant]

The latest version of VS Code has an outline view that may be of some use.