Skip to content

Commit ed7dcf9

Browse files
rebelinuxrebelinux
authored
Merge pull request #12 from AsBuiltReport/copilot/scan-source-code-documentation
2 parents 2ac6253 + bb06ea8 commit ed7dcf9

10 files changed

Lines changed: 399 additions & 57 deletions

‎AsBuiltReport.System.Resources.psm1‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,19 @@
1-
# Get public and private function definition files and dot source them
1+
# Module loader for AsBuiltReport.System.Resources
2+
#
3+
# This script is executed automatically by PowerShell when the module is imported. It uses a
4+
# common AsBuiltReport pattern of separating functions into two directories:
5+
#
6+
# Src/Public/ - Functions exported to the caller (visible after Import-Module).
7+
# Typically a single Invoke-AsBuiltReport.<ModuleName> entry point.
8+
# Src/Private/ - Internal helper functions used only within the module. They are dot-sourced
9+
# into the module scope but are also exported so that AsBuiltReport.Core can
10+
# call them from within the report document script block, which runs in the
11+
# caller's scope.
12+
#
13+
# Any file that fails to dot-source (e.g. due to a syntax error) will emit an error message
14+
# via Write-Error but will not prevent the remaining files from being loaded.
15+
16+
# Collect all public and private function files.
217
$Public = @(Get-ChildItem -Path $PSScriptRoot\Src\Public\*.ps1 -ErrorAction SilentlyContinue)
318
$Private = @(Get-ChildItem -Path $PSScriptRoot\Src\Private\*.ps1 -ErrorAction SilentlyContinue)
419

@@ -10,5 +25,8 @@ foreach ($Module in @($Public + $Private)) {
1025
}
1126
}
1227

28+
# Export public functions by name so they are available to module consumers.
1329
Export-ModuleMember -Function $Public.BaseName
30+
# Export private functions so that AsBuiltReport.Core can invoke them from within the
31+
# PScribo document script block, which executes in the caller's session scope.
1432
Export-ModuleMember -Function $Private.BaseName

‎Src/Private/Export-AbrDiagram.ps1‎

Lines changed: 55 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,65 @@
11
function Export-AbrDiagram {
22
<#
33
.SYNOPSIS
4-
Used by As Built Report to export diagrams
4+
Used by As Built Report to export diagrams.
55
.DESCRIPTION
6-
Exports diagrams using the Diagrammer module based on user options set in the report options.
6+
Renders and embeds a Graphviz diagram into the active PScribo report section using the
7+
AsBuiltReport.Diagram module's New-Diagrammer cmdlet. Optionally, the diagram can also
8+
be saved to disk in one or more formats.
9+
10+
Behaviour is driven by the Options block of the report configuration JSON:
11+
12+
EnableDiagrams - Master switch. When false the function exits immediately.
13+
DiagramTheme - 'Black', 'Neon', or 'White' (default). Controls background
14+
and font colours passed to New-Diagrammer.
15+
DiagramWaterMark - Text watermark overlaid on the diagram image.
16+
ExportDiagrams - When true, saves the diagram to OutputFolderPath on disk.
17+
ExportDiagramsFormat - Array of formats to save (e.g. @('png', 'pdf', 'svg')).
18+
Defaults to 'png' if not set.
19+
EnableDiagramDebug - When true, passes DraftMode to New-Diagrammer so that
20+
Graphviz debug styling (red borders, visible edges) is
21+
rendered, which is useful for troubleshooting layout.
22+
EnableDiagramSignature - When true, adds an author/company signature block.
23+
SignatureAuthorName - Author name shown in the signature block.
24+
SignatureCompanyName - Company name shown in the signature block.
25+
EnableDiagramMainLogo - Controls whether the main logo is shown in the diagram.
26+
27+
The diagram is always rendered as base64 and embedded in the report via the PScribo
28+
Image cmdlet. If ExportDiagrams is also enabled the diagram is additionally written to
29+
disk in the requested format(s) before the base64 pass.
30+
.PARAMETER DiagramObject
31+
The Graphviz graph object produced by the diagram builder function (e.g.
32+
Get-AbrProcessDiagram). This is passed directly to New-Diagrammer as its -InputObject.
33+
.PARAMETER MainDiagramLabel
34+
Human-readable label used as the diagram title and as the PScribo Section heading.
35+
Defaults to 'Change Me' if not specified.
36+
.PARAMETER FileName
37+
Base file name (without extension) used when saving the diagram to disk.
38+
Required when ExportDiagrams is enabled.
39+
.INPUTS
40+
None. This function does not accept pipeline input.
41+
.OUTPUTS
42+
None. Output is written directly to the PScribo document object via Section and Image
43+
cmdlets. If ExportDiagrams is enabled, files are also written to OutputFolderPath.
44+
.EXAMPLE
45+
# Typically called from within a report section function such as Get-AbrProcessInfo:
46+
$diagram = Get-AbrProcessDiagram
47+
Export-AbrDiagram -DiagramObject $diagram -MainDiagramLabel 'Process Hierarchy Diagram' -FileName 'AsBuiltReport.System.Resources.Cluster'
748
.NOTES
849
Version: 0.1.2
950
Author: AsBuiltReport Community
1051
Twitter: @AsBuiltReport
1152
Github: AsBuiltReport
12-
1353
.LINK
14-
54+
https://github.com/AsBuiltReport/AsBuiltReport.System.Resources
1555
#>
1656

1757
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingCmdletAliases', '', Scope = 'Function')]
1858

1959
[CmdletBinding()]
2060
param (
61+
# The Graphviz graph object to render. No type constraint is applied because the
62+
# PSGraph DSL returns a custom object type from the AsBuiltReport.Diagram module.
2163
$DiagramObject,
2264
[string] $MainDiagramLabel = 'Change Me',
2365
[Parameter(Mandatory = $true)]
@@ -32,9 +74,12 @@ function Export-AbrDiagram {
3274
if ($Options.EnableDiagrams) {
3375
Write-PScriboMessage -Message "Collecting $MainDiagramLabel diagram"
3476

77+
# Resolve the icons directory relative to the module root so that icon images can
78+
# be embedded into diagram nodes by New-Diagrammer.
3579
$RootPath = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
3680
[System.IO.FileInfo]$IconPath = Join-Path -Path $RootPath -ChildPath 'icons'
3781

82+
# Build the core parameter set shared by all New-Diagrammer invocations.
3883
$DiagramParams = @{
3984
'FileName' = $FileName
4085
'OutputFolderPath' = $OutputFolderPath
@@ -52,6 +97,7 @@ function Export-AbrDiagram {
5297
'DisableMainDiagramLogo' = $Options.EnableDiagramMainLogo
5398
}
5499

100+
# Apply theme-specific colour overrides on top of the defaults.
55101
if ($Options.DiagramTheme -eq 'Black') {
56102
$DiagramParams.add('MainGraphBGColor', 'Black')
57103
$DiagramParams.add('Edgecolor', 'White')
@@ -68,6 +114,7 @@ function Export-AbrDiagram {
68114
$DiagramParams.add('WaterMarkColor', '#333333')
69115
}
70116

117+
# When ExportDiagrams is enabled, write the diagram to disk in the requested formats.
71118
if ($Options.ExportDiagrams) {
72119
if (-not $Options.ExportDiagramsFormat) {
73120
$DiagramFormat = 'png'
@@ -80,9 +127,9 @@ function Export-AbrDiagram {
80127
}
81128

82129
if ($Options.EnableDiagramDebug) {
83-
130+
# DraftMode enables Graphviz debug output (e.g. red borders on nodes/edges)
131+
# to help identify layout problems during development.
84132
$DiagramParams.Add('DraftMode', $True)
85-
86133
}
87134

88135
if ($Options.EnableDiagramSignature) {
@@ -108,6 +155,8 @@ function Export-AbrDiagram {
108155
Write-PScriboMessage -IsWarning -Message "Unable to export the $MainDiagramLabel Diagram: $($_.Exception.Message)"
109156
}
110157
}
158+
# Always render the diagram as base64 for embedding in the report, regardless of
159+
# whether ExportDiagrams is enabled. Reuse $DiagramParams but swap the Format.
111160
try {
112161
$DiagramParams.Remove('Format')
113162
$DiagramParams.Add('Format', 'base64')

‎Src/Private/Get-AbrDate.ps1‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,43 @@
11
function Get-AbrDate {
22
<#
33
.SYNOPSIS
4-
Used by As Built Report to retrieve System Date information
4+
Used by As Built Report to retrieve System Date information.
55
.DESCRIPTION
6+
Collects the current system date and time, then formats and renders it into the report
7+
using PScribo cmdlets (Section, Table, Paragraph). The level of detail in the output
8+
is controlled by the InfoLevel.Date setting in the report configuration JSON:
69
10+
0 - Disabled. The section is skipped entirely.
11+
1 - Summary. A single compact table showing Date and Hour for all targets.
12+
2 - Detailed. A per-target subsection with a list-style table.
13+
14+
Localization is handled through the $reportTranslate variable, which is populated by
15+
AsBuiltReport.Core from the appropriate Language/*.psd1 file.
16+
.INPUTS
17+
None. This function does not accept pipeline input. It reads from script-scoped
18+
variables ($InfoLevel, $reportTranslate, $Report, $System) that are set by the
19+
AsBuiltReport framework before this function is called.
20+
.OUTPUTS
21+
None. Output is written directly to the PScribo document object via Section, Table,
22+
Paragraph, and BlankLine cmdlets.
23+
.EXAMPLE
24+
# This function is called automatically by Invoke-AsBuiltReport.System.Resources.
25+
# It is not designed to be called directly by end users.
26+
Get-AbrDate
727
.NOTES
828
Version: 0.1.1
929
Author: AsBuiltReport Community
1030
Twitter: @AsBuiltReport
1131
Github: AsBuiltReport
12-
.EXAMPLE
13-
1432
.LINK
15-
33+
https://github.com/AsBuiltReport/AsBuiltReport.System.Resources
1634
#>
1735
[CmdletBinding()]
1836
param (
1937
)
2038

2139
begin {
40+
# Narrow the translation lookup to the GetAbrDate section of the language data.
2241
$reportTranslate = $reportTranslate.GetAbrDate
2342
Write-PScriboMessage ($($reportTranslate.InfoLevel) -f 'Date', $($InfoLevel.Date))
2443
}
@@ -30,6 +49,8 @@ function Get-AbrDate {
3049
if ($SystemDate) {
3150
Write-PScriboMessage $reportTranslate.Collecting
3251
Section -Style Heading2 $($reportTranslate.Heading) {
52+
# Build an array of ordered hashtables so column order is preserved when
53+
# converting to PSCustomObjects for the PScribo Table cmdlet.
3354
$SystemDateInfo = @()
3455
foreach ($Date in $SystemDate) {
3556
$InObj = [Ordered]@{
@@ -40,6 +61,7 @@ function Get-AbrDate {
4061
}
4162

4263
if ($InfoLevel.Date -ge 2) {
64+
# InfoLevel 2: render each target as its own subsection with a list-style table.
4365
Paragraph $reportTranslate.ParagraphDetail
4466
foreach ($DateInfo in $SystemDateInfo) {
4567
Section -Style NOTOCHeading4 -ExcludeFromTOC "$($System)" {
@@ -55,6 +77,7 @@ function Get-AbrDate {
5577
}
5678
}
5779
} else {
80+
# InfoLevel 1: render a single compact table across all targets.
5881
Paragraph $reportTranslate.ParagraphSummary
5982
BlankLine
6083
$TableParams = @{

‎Src/Private/Get-AbrPSHost.ps1‎

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,51 @@
22
function Get-AbrPSHost {
33
<#
44
.SYNOPSIS
5-
Used by As Built Report to retrieve system PowerShell host information
5+
Used by As Built Report to retrieve system PowerShell host information.
66
.DESCRIPTION
7+
Queries the current PowerShell host environment using Get-Host and renders the results
8+
into the report using PScribo cmdlets. The following fields are captured:
79
10+
- Name : The name of the PowerShell host application (e.g. 'ConsoleHost').
11+
- Version : The version string of the PowerShell host (e.g. '7.4.0').
12+
- CurrentCulture : The language/regional culture for formatting (e.g. 'en-US').
13+
- CurrentUICulture : The culture used for localized UI messages (e.g. 'en-US').
14+
- DebuggerEnabled : Whether the PowerShell debugger is currently enabled.
15+
16+
The level of detail in the output is controlled by the InfoLevel.PSHost setting in
17+
the report configuration JSON:
18+
19+
0 - Disabled. The section is skipped entirely.
20+
1 - Summary. A single compact table showing key fields for all targets.
21+
2 - Detailed. A per-target subsection with a full list-style table.
22+
23+
Localization is handled through the $reportTranslate variable, which is populated by
24+
AsBuiltReport.Core from the appropriate Language/*.psd1 file.
25+
.INPUTS
26+
None. This function does not accept pipeline input. It reads from script-scoped
27+
variables ($InfoLevel, $reportTranslate, $Report, $System) that are set by the
28+
AsBuiltReport framework before this function is called.
29+
.OUTPUTS
30+
None. Output is written directly to the PScribo document object via Section, Table,
31+
Paragraph, and BlankLine cmdlets.
32+
.EXAMPLE
33+
# This function is called automatically by Invoke-AsBuiltReport.System.Resources.
34+
# It is not designed to be called directly by end users.
35+
Get-AbrPSHost
836
.NOTES
937
Version: 0.1.1
1038
Author: AsBuiltReport Community
1139
Twitter: @AsBuiltReport
1240
Github: AsBuiltReport
13-
.EXAMPLE
14-
1541
.LINK
16-
42+
https://github.com/AsBuiltReport/AsBuiltReport.System.Resources
1743
#>
1844
[CmdletBinding()]
1945
param (
2046
)
2147

2248
begin {
49+
# Narrow the translation lookup to the GetAbrPSHost section of the language data.
2350
$reportTranslate = $reportTranslate.GetAbrPSHost
2451
Write-PScriboMessage ($($reportTranslate.InfoLevel) -f 'PSHost', $($InfoLevel.PSHost))
2552
}
@@ -31,13 +58,16 @@ function Get-AbrPSHost {
3158
if ($SystemPSHost) {
3259
Write-PScriboMessage $reportTranslate.Collecting
3360
Section -Style Heading2 $($reportTranslate.Heading) {
61+
# Build an array of ordered hashtables so column order is preserved when
62+
# converting to PSCustomObjects for the PScribo Table cmdlet.
3463
$SystemPSHostInfo = @()
3564
foreach ($PSHost in $SystemPSHost) {
3665
$InObj = [Ordered]@{
3766
$($reportTranslate.Name) = $PSHost.Name
3867
$($reportTranslate.Version) = $PSHost.Version.ToString()
3968
$($reportTranslate.CurrentCulture) = $PSHost.CurrentCulture
4069
$($reportTranslate.CurrentUICulture) = $PSHost.CurrentUICulture
70+
# Convert the boolean Debugger.IsEnabled to a localized Yes/No string.
4171
$($reportTranslate.DebuggerEnabled) = switch ($PSHost.Debugger.IsEnabled) {
4272
$true { $($reportTranslate.Yes) }
4373
$false { $($reportTranslate.No) }
@@ -48,6 +78,7 @@ function Get-AbrPSHost {
4878
}
4979

5080
if ($InfoLevel.PSHost -ge 2) {
81+
# InfoLevel 2: render each target as its own subsection with a list-style table.
5182
Paragraph $reportTranslate.ParagraphDetail
5283
foreach ($PSHostInfo in $SystemPSHostInfo) {
5384
Section -Style NOTOCHeading4 -ExcludeFromTOC "$($System)" {
@@ -63,6 +94,8 @@ function Get-AbrPSHost {
6394
}
6495
}
6596
} else {
97+
# InfoLevel 1: render a single compact table across all targets, showing
98+
# a subset of the most useful fields.
6699
Paragraph $reportTranslate.ParagraphSummary
67100
BlankLine
68101
$TableParams = @{

0 commit comments

Comments
 (0)