🩹 [Patch]: Add Get-ScriptAST, -FunctionAST and FunctionType (#12)

## Description

This pull request includes several new functions and refactors existing
ones to improve the handling and extraction of function definitions from
PowerShell scripts using the Abstract Syntax Tree (AST). The most
important changes include the addition of new functions
`Get-FunctionAST`, `Get-ScriptAST`, and `Get-FunctionType`, as well as
the refactoring of existing functions to utilize these new utilities.

### New Functions:

*
[`src/functions/public/Core/Get-FunctionAST.ps1`](diffhunk://#diff-ebd4e1ad30387639d36d84e6a48c5b48cb76c42514fa21253a16d440b7cb4021R1-R43):
Added a new function `Get-FunctionAST` to retrieve the AST of function
definitions from a specified PowerShell script. This function allows
filtering by function name and provides detailed documentation and
examples.
*
[`src/functions/public/Core/Get-ScriptAST.ps1`](diffhunk://#diff-dfd1b919296a66069c792bbb32868f85ab37b6952f7646b18ba660edfb779a28R1-R71):
Added a new function `Get-ScriptAST` to parse a PowerShell script from a
file or string input and return its AST. This function also supports
capturing tokens and errors.
*
[`src/functions/public/Functions/Get-FunctionType.ps1`](diffhunk://#diff-4c982e7ebeb1e1b4552abb41872c1ca4dd2126b8b5cde5ed026f5ceb668fd366R1-R45):
Added a new function `Get-FunctionType` to extract function types from a
specified PowerShell script using the AST. This function provides
detailed documentation and examples.

### Refactored Functions:

*
[`src/functions/public/Functions/Get-FunctionAlias.ps1`](diffhunk://#diff-e26de7cad073f2ba65d1125962f4c71c7b929e02acea0c4b39d158a34cd3cf57R28-R33):
Refactored to use the new `Get-FunctionAST` function for extracting
function definitions from the script file. This change simplifies the
code and improves maintainability.
*
[`src/functions/public/Functions/Get-FunctionName.ps1`](diffhunk://#diff-5db9010fc5dab3435eb93a1af8edabf08660687f56a1f9fb96c2c2e3c54f9c18R24-R29):
Refactored to use the new `Get-FunctionAST` function for extracting
function definitions from the script file. This change simplifies the
code and improves maintainability.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

src/functions/public/Core/Get-FunctionAST.ps1

@@ -0,0 +1,43 @@
+function Get-FunctionAST {
+    <#
+        .SYNOPSIS
+        Retrieves the abstract syntax tree (AST) of function definitions from a PowerShell script.
+
+        .DESCRIPTION
+        Parses a specified PowerShell script file and extracts function definitions matching the given name.
+        By default, it returns all function definitions if no specific name is provided.
+
+        .EXAMPLE
+        Get-FunctionAST -Path "C:\Scripts\MyScript.ps1"
+
+        Retrieves all function definitions from "MyScript.ps1".
+
+        .EXAMPLE
+        Get-FunctionAST -Name "Get-Data" -Path "C:\Scripts\MyScript.ps1"
+
+        Retrieves only the function definition named "Get-Data" from "MyScript.ps1".
+    #>
+    [CmdletBinding()]
+    param (
+        # The name of the function to search for. Defaults to all functions ('*').
+        [Parameter()]
+        [string] $Name = '*',
+
+        # The path to the PowerShell script file to be parsed.
+        [Parameter(Mandatory)]
+        [ValidateScript({ Test-Path -Path $_ -PathType Leaf })]
+        [string] $Path
+    )
+
+    begin {}
+
+    process {
+        # Parse the script file into an AST
+        $ast = Get-ScriptAST -Path $Path
+
+        # Extract function definitions
+        $ast.FindAll({ $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true) | Where-Object { $_.Name -like $Name }
+    }
+
+    end {}
+}

src/functions/public/Core/Get-ScriptAST.ps1

@@ -0,0 +1,71 @@
+function Get-ScriptAST {
+    <#
+        .SYNOPSIS
+        Parses a PowerShell script or script file and returns its Abstract Syntax Tree (AST).
+
+        .DESCRIPTION
+        This function parses a PowerShell script from a file or a string input and returns its AST.
+        It can optionally provide token and error information.
+
+        .EXAMPLE
+        Get-ScriptAST -Path "C:\Scripts\MyScript.ps1"
+
+        Parses the PowerShell script at "MyScript.ps1" and returns its AST.
+
+        .EXAMPLE
+        Get-ScriptAST -Script "Get-Process | Select-Object Name"
+
+        Parses the provided PowerShell script string and returns its AST.
+
+        .EXAMPLE
+        Get-ScriptAST -Path "C:\Scripts\MyScript.ps1" -Tokens ([ref]$tokens) -Errors ([ref]$errors)
+
+        Parses the script file while also capturing tokens and errors.
+    #>
+    [outputType([System.Management.Automation.Language.ScriptBlockAst])]
+    [CmdletBinding()]
+    param (
+        # The path to the PowerShell script file to be parsed.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName,
+            ParameterSetName = 'Path'
+        )]
+        # Validate using Test-Path
+        [ValidateScript({ Test-Path -Path $_ -PathType Leaf })]
+        [string] $Path,
+
+        # The PowerShell script to be parsed.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName,
+            ParameterSetName = 'Script'
+        )]
+        [string] $Script,
+
+        # Reference variable to store parsed tokens.
+        [Parameter()]
+        [ref] $Tokens,
+
+        # Reference variable to store parsing errors.
+        [Parameter()]
+        [ref] $Errors
+    )
+
+    begin {}
+
+    process {
+        switch ($PSCmdlet.ParameterSetName) {
+            'Path' {
+                [System.Management.Automation.Language.Parser]::ParseFile($Path, [ref]$Tokens, [ref]$Errors)
+            }
+            'Script' {
+                [System.Management.Automation.Language.Parser]::ParseInput($Script, [ref]$Tokens, [ref]$Errors)
+            }
+        }
+    }
+
+    end {}
+}

…c/functions/public/Get-FunctionAlias.ps1 …s/public/Functions/Get-FunctionAlias.ps1src/functions/public/Get-FunctionAlias.ps1 renamed to src/functions/public/Functions/Get-FunctionAlias.ps1 src/functions/public/Get-FunctionAlias.ps1 renamed to src/functions/public/Functions/Get-FunctionAlias.ps1

@@ -25,14 +25,12 @@
 
         # The path to the PowerShell script file to be parsed.
         [Parameter(Mandatory)]
+        [ValidateScript({ Test-Path -Path $_ -PathType Leaf })]
         [string] $Path
     )
 
-    # Parse the script file into an AST
-    $ast = [System.Management.Automation.Language.Parser]::ParseFile($Path, [ref]$null, [ref]$null)
-
     # Extract function definitions
-    $functions = $ast.FindAll({ $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true)
+    $functions = Get-FunctionAST -Path $Path
 
     # Process each function and extract aliases
     $functions | ForEach-Object {

src/functions/public/Get-FunctionName.ps1 …ns/public/Functions/Get-FunctionName.ps1src/functions/public/Get-FunctionName.ps1 renamed to src/functions/public/Functions/Get-FunctionName.ps1 src/functions/public/Get-FunctionName.ps1 renamed to src/functions/public/Functions/Get-FunctionName.ps1

@@ -21,14 +21,12 @@
     param (
         # The path to the script file to parse
         [Parameter(Mandatory)]
+        [ValidateScript({ Test-Path -Path $_ -PathType Leaf })]
         [string] $Path
     )
 
-    # Parse the script file into an AST
-    $ast = [System.Management.Automation.Language.Parser]::ParseFile($Path, [ref]$null, [ref]$null)
-
     # Extract function definitions
-    $functions = $ast.FindAll({ $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true)
+    $functions = Get-FunctionAST -Path $Path
 
     # Process each function and extract the name
     $functions | ForEach-Object {

src/functions/public/Functions/Get-FunctionType.ps1

@@ -0,0 +1,45 @@
+function Get-FunctionType {
+    <#
+        .SYNOPSIS
+        Extracts function types from a specified PowerShell script.
+
+        .DESCRIPTION
+        Parses the given PowerShell script file and retrieves all function types
+        defined within it. This function utilizes the PowerShell Abstract Syntax Tree (AST)
+        to analyze the script and extract function definitions.
+
+        .EXAMPLE
+        Get-FunctionType -Path "C:\Scripts\MyScript.ps1"
+
+        Retrieves all function types defined in the specified script file.
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param(
+        # The path to the PowerShell script file to be parsed.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName,
+            ParameterSetName = 'Path'
+        )]
+        [ValidateScript({ Test-Path -Path $_ -PathType Leaf })]
+        [string] $Path
+    )
+
+    begin {}
+
+    process {
+        $functionAST = Get-FunctionAST -Path $Path
+
+        $functionAST | ForEach-Object {
+            $type = $_.IsFilter ? 'Filter' : $_.IsWorkflow ? 'Workflow' : $_.IsConfiguration ? 'Configuration' : 'Function'
+            [pscustomobject]@{
+                Name = $_.Name
+                Type = $type
+            }
+        }
+    }
+
+    end {}
+}

tests/Module.Tests.ps1

@@ -1,4 +1,30 @@
-Describe 'Module' {
+Describe 'Core' {
+    Context "Function: 'Get-ScriptAST'" {
+        It 'Get-ScriptAST gets the script AST' {
+            $path = Join-Path $PSScriptRoot 'src\Test-Function.ps1'
+            $ast = Get-ScriptAST -Path $path
+            $ast | Should -Not -BeNullOrEmpty
+            $ast | Should -BeOfType [System.Management.Automation.Language.ScriptBlockAst]
+        }
+    }
+    Context "Function: 'Get-FunctionAST'" {
+        It 'Get-FunctionAST gets the function AST' {
+            $path = Join-Path $PSScriptRoot 'src\Test-Function.ps1'
+            $ast = Get-FunctionAST -Path $path
+            $ast | Should -Not -BeNullOrEmpty
+            $ast | Should -BeOfType [System.Management.Automation.Language.FunctionDefinitionAst]
+        }
+    }
+}
+
+Describe 'Functions' {
+    Context "Function: 'Get-FunctionType'" {
+        It 'Get-FunctionAlias gets the function alias' {
+            $path = Join-Path $PSScriptRoot 'src\Test-Function.ps1'
+            $functionType = Get-FunctionType -Path $path
+            $functionType.Type | Should -Be 'Function'
+        }
+    }
     Context "Function: 'Get-FunctionName'" {
         It 'Get-FunctionName gets the function name' {
             $path = Join-Path $PSScriptRoot 'src\Test-Function.ps1'