Get-ClassAst: New command proposal

[johlju]

Command proposal

<#
    .SYNOPSIS
        Returns the AST for a single or all classes.

    .DESCRIPTION
        Returns the AST for a single or all classes.

    .PARAMETER ScriptFile
        The path to the source file that contain the class.

    .PARAMETER ClassName
        The specific class to return the AST for. Optional.

    .EXAMPLE
        Get-ClassAst -ScriptFile '.\output\MyModule\1.0.0\MyModule.psm1'

        Returns AST for all the classes in the script file.

    .EXAMPLE
        Get-ClassAst -ClassName 'myClass' -ScriptFile '.\output\MyModule\1.0.0\MyModule.psm1'

        Returns AST for the class 'myClass' from the script file.
#>
function Get-ClassAst
{
    [CmdletBinding()]
    [OutputType([System.Collections.Generic.IEnumerable`1[System.Management.Automation.Language.Ast]])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ScriptFile,

        [Parameter()]
        [System.String]
        $ClassName
    )

    $tokens, $parseErrors = $null

    $ast = [System.Management.Automation.Language.Parser]::ParseFile($ScriptFile, [ref] $tokens, [ref] $parseErrors)

    if ($parseErrors)
    {
        throw $parseErrors
    }

    if ($PSBoundParameters.ContainsKey('ClassName') -and $ClassName)
    {
        # Get only the specific class resource.
        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.TypeDefinitionAst] `
                -and $args[0].IsClass `
                -and $args[0].Name -eq $ClassName
        }
    }
    else
    {
        # Get all class resources.
        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.TypeDefinitionAst] `
                -and $args[0].IsClass
        }
    }

    $classAst = $ast.FindAll($astFilter, $true)

    return $classAst
}

Tests:

#region HEADER
$script:projectPath = "$PSScriptRoot\..\..\.." | Convert-Path
$script:projectName = (Get-ChildItem -Path "$script:projectPath\*\*.psd1" | Where-Object -FilterScript {
        ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
        $(try
            {
                Test-ModuleManifest -Path $_.FullName -ErrorAction Stop
            }
            catch
            {
                $false
            })
    }).BaseName

$script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Select-Object -First 1
Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue'

Import-Module $script:moduleName -Force -ErrorAction 'Stop'
#endregion HEADER

InModuleScope $script:moduleName {
    Describe 'Get-ClassAst' {
        Context 'When the script file cannot be parsed' {
            BeforeAll {
                $mockBuiltModulePath = Join-Path -Path $TestDrive -ChildPath 'output\MyClassModule\1.0.0'

                New-Item -Path $mockBuiltModulePath -ItemType 'Directory' -Force

                $mockBuiltModuleScriptFilePath = Join-Path -Path $mockBuiltModulePath -ChildPath 'MyClassModule.psm1'

                # The class DSC resource in the built module.
                $mockBuiltModuleScript = @'
[DscResource()]
class MyDscResource
{
    [MyDscResource] Get()
    {
        return [MyDscResource] $this
    }

    [System.Boolean] Test()
    {
        return $true
    }

    [DscProperty(Key)]
    [System.String] $ProjectName
}
'@

                # Uses Microsoft.PowerShell.Utility\Out-File to override the stub that is needed for the mocks.
                $mockBuiltModuleScript | Microsoft.PowerShell.Utility\Out-File -FilePath $mockBuiltModuleScriptFilePath -Encoding ascii -Force
            }

            It 'Should throw an error' {
                # This evaluates just part of the expected error message.
                { Get-ClassAst -ScriptFile $mockBuiltModuleScriptFilePath } | Should -Throw "'MyDscResource' is missing a Set method"
            }
        }

        Context 'When the script file is parsed successfully' {
            BeforeAll {
                $mockBuiltModulePath = Join-Path -Path $TestDrive -ChildPath 'output\MyClassModule\1.0.0'

                New-Item -Path $mockBuiltModulePath -ItemType 'Directory' -Force

                $mockBuiltModuleScriptFilePath = Join-Path -Path $mockBuiltModulePath -ChildPath 'MyClassModule.psm1'

                # The class DSC resource in the built module.
                $mockBuiltModuleScript = @'
class MyBaseClass
{
    [void] MyHelperFunction() {}
}

[DscResource()]
class MyDscResource
{
    [MyDscResource] Get()
    {
        return [MyDscResource] $this
    }

    [System.Boolean] Test()
    {
        return $true
    }

    [void] Set() {}

    [DscProperty(Key)]
    [System.String] $ProjectName
}
'@

                # Uses Microsoft.PowerShell.Utility\Out-File to override the stub that is needed for the mocks.
                $mockBuiltModuleScript | Microsoft.PowerShell.Utility\Out-File -FilePath $mockBuiltModuleScriptFilePath -Encoding ascii -Force
            }

            Context 'When returning all classes in the script file' {
                It 'Should return the correct classes' {
                    $astResult = Get-ClassAst -ScriptFile $mockBuiltModuleScriptFilePath

                    $astResult | Should -HaveCount 2
                    $astResult.Name | Should -Contain 'MyDscResource'
                    $astResult.Name | Should -Contain 'MyBaseClass'
                }
            }

            Context 'When returning a single class from the script file' {
                It 'Should return the correct classes' {
                    $astResult = Get-ClassAst -ScriptFile $mockBuiltModuleScriptFilePath -ClassName 'MyBaseClass'

                    $astResult | Should -HaveCount 1
                    $astResult.Name | Should -Be 'MyBaseClass'
                }
            }
        }
    }
}

Proposed parameters

Parameter	Mandatory	Data type	Description	Default value	Allowed values

• | Yes | String | Detailed description | None | None

Special considerations or limitations

None