From 189e6d6554aab3258191d64be630daf51070d931 Mon Sep 17 00:00:00 2001
From: LuigiLink <jcdrouhin@yahoo.fr>
Date: Thu, 9 Jul 2026 16:42:10 +0200
Subject: [PATCH 1/4] feat: add results history and HTML report functions to
 SPSCleanDependencies.Common

Add the building blocks for issue #8 (results history + HTML report), reusing the
conventions proven across the sibling luigilink projects:

History (Public):
- Backup-SPSJsonFile: archive the current results JSON into Results/history with a
  yyyyMMdd-HHmm timestamp before it is overwritten (pattern from SPSUserSync).
- Clear-SPSLogFolder: single rotation implementation reused for transcript logs
  (*.log) and archived snapshots (*.json); Retention = 0 disables pruning.

HTML report (Private helpers + Public exporter, pattern from SPSUpdate.Common):
- ConvertTo-SPSHtmlEncoded, Get-SPSReportHtmlHead, Get-SPSReportCardHtml,
  Get-SPSReportHtmlScript.
- Export-SPSCleanDependenciesReport: renders the results JSON as a self-contained,
  dependency-free HTML file - one summary card per dependency category plus a
  filterable/sortable table per non-empty category, or a clean 'nothing to clean'
  state. Atomic write (temp file + Move-Item).

Bump the module manifest to 1.4.0 and export the three new public functions.

Refs #8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../Private/ConvertTo-SPSHtmlEncoded.ps1      |  50 ++++
 .../Private/Get-SPSReportCardHtml.ps1         |  45 ++++
 .../Private/Get-SPSReportHtmlHead.ps1         |  55 +++++
 .../Private/Get-SPSReportHtmlScript.ps1       | 109 +++++++++
 .../Public/Backup-SPSJsonFile.ps1             |  68 ++++++
 .../Public/Clear-SPSLogFolder.ps1             |  79 ++++++
 .../Export-SPSCleanDependenciesReport.ps1     | 227 ++++++++++++++++++
 .../SPSCleanDependencies.Common.psd1          |   5 +-
 8 files changed, 637 insertions(+), 1 deletion(-)
 create mode 100644 src/Modules/SPSCleanDependencies.Common/Private/ConvertTo-SPSHtmlEncoded.ps1
 create mode 100644 src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportCardHtml.ps1
 create mode 100644 src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlHead.ps1
 create mode 100644 src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlScript.ps1
 create mode 100644 src/Modules/SPSCleanDependencies.Common/Public/Backup-SPSJsonFile.ps1
 create mode 100644 src/Modules/SPSCleanDependencies.Common/Public/Clear-SPSLogFolder.ps1
 create mode 100644 src/Modules/SPSCleanDependencies.Common/Public/Export-SPSCleanDependenciesReport.ps1

diff --git a/src/Modules/SPSCleanDependencies.Common/Private/ConvertTo-SPSHtmlEncoded.ps1 b/src/Modules/SPSCleanDependencies.Common/Private/ConvertTo-SPSHtmlEncoded.ps1
new file mode 100644
index 0000000..a102397
--- /dev/null
+++ b/src/Modules/SPSCleanDependencies.Common/Private/ConvertTo-SPSHtmlEncoded.ps1
@@ -0,0 +1,50 @@
+function ConvertTo-SPSHtmlEncoded {
+    <#
+        .SYNOPSIS
+        HTML-encodes a string for safe insertion into generated HTML reports.
+
+        .DESCRIPTION
+        Replaces the five characters that are significant in HTML markup
+        (& < > " ') with their entity equivalents. Used by
+        Export-SPSCleanDependenciesReport to neutralize values (database names,
+        site/web IDs, logins, messages) before baking them into the report.
+
+        Returns an empty string for null or empty input.
+
+        .PARAMETER Value
+        The string to encode.
+
+        .EXAMPLE
+        ConvertTo-SPSHtmlEncoded -Value 'DB <prod> & "co"'
+        # DB &lt;prod&gt; &amp; &quot;co&quot;
+    #>
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [AllowEmptyString()]
+        [AllowNull()]
+        [System.String]
+        $Value
+    )
+
+    process {
+        if ([string]::IsNullOrEmpty($Value)) {
+            return ''
+        }
+
+        $sb = [System.Text.StringBuilder]::new()
+        foreach ($char in $Value.ToCharArray()) {
+            switch ($char) {
+                '&' { [void]$sb.Append('&amp;') }
+                '<' { [void]$sb.Append('&lt;') }
+                '>' { [void]$sb.Append('&gt;') }
+                '"' { [void]$sb.Append('&quot;') }
+                "'" { [void]$sb.Append('&#39;') }
+                default { [void]$sb.Append($char) }
+            }
+        }
+        return $sb.ToString()
+    }
+}
diff --git a/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportCardHtml.ps1 b/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportCardHtml.ps1
new file mode 100644
index 0000000..0a8d9d4
--- /dev/null
+++ b/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportCardHtml.ps1
@@ -0,0 +1,45 @@
+function Get-SPSReportCardHtml {
+    <#
+        .SYNOPSIS
+        Builds the HTML for one summary "card" (a big number plus a label).
+
+        .PARAMETER Value
+        The value shown as the big number.
+
+        .PARAMETER Label
+        The label shown under the value.
+
+        .PARAMETER Sub
+        Optional sub-label shown under the label.
+
+        .PARAMETER Tone
+        Optional visual tone: '', 'accent', 'clean' (green) or 'alert' (red).
+    #>
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        $Value,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Label,
+
+        [Parameter()]
+        [System.String]
+        $Sub = '',
+
+        [Parameter()]
+        [ValidateSet('', 'accent', 'clean', 'alert')]
+        [System.String]
+        $Tone = ''
+    )
+
+    $encValue = ConvertTo-SPSHtmlEncoded -Value ("$Value")
+    $encLabel = ConvertTo-SPSHtmlEncoded -Value $Label
+    $encSub = ConvertTo-SPSHtmlEncoded -Value $Sub
+    $toneClass = if ([string]::IsNullOrEmpty($Tone)) { '' } else { " $Tone" }
+    $subHtml = if ([string]::IsNullOrEmpty($encSub)) { '' } else { "<div class=`"card-sub`">$encSub</div>" }
+    return "<div class=`"card$toneClass`"><div class=`"card-value`">$encValue</div><div class=`"card-label`">$encLabel</div>$subHtml</div>"
+}
diff --git a/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlHead.ps1 b/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlHead.ps1
new file mode 100644
index 0000000..e112460
--- /dev/null
+++ b/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlHead.ps1
@@ -0,0 +1,55 @@
+function Get-SPSReportHtmlHead {
+    <#
+        .SYNOPSIS
+        Returns the document head (with the embedded stylesheet) and the opening body tag.
+
+        .DESCRIPTION
+        Emits a self-contained <head> block (no CDN, works offline on a SharePoint
+        server) with the embedded SPSCleanDependencies report stylesheet, followed by
+        the opening <body> tag.
+
+        .PARAMETER Title
+        Page title used in the <title> element.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Title
+    )
+
+    $css = @'
+:root{--brand:#1f6fb2;--brand-dark:#155a91;--ink:#222;--muted:#666;--line:#e3e3e3;--zebra:#f7f9fb;--ok:#2e9b57;--warn:#c19c00;--alert:#c0392b}
+*{box-sizing:border-box}
+body{font-family:'Aptos','Segoe UI',-apple-system,BlinkMacSystemFont,sans-serif;color:var(--ink);margin:0;padding:24px;background:#fff}
+h1{color:var(--brand);font-size:22px;margin:0 0 4px}
+h2{color:var(--brand);font-size:16px;margin:24px 0 8px;border-bottom:2px solid var(--brand);padding-bottom:4px}
+h3{color:var(--brand-dark);font-size:13px;margin:0 0 6px}
+.meta{color:var(--muted);font-size:12px;margin-bottom:16px}
+.summary{background:#eef5fb;border:1px solid #cfe0ef;border-left:4px solid var(--brand);border-radius:6px;padding:16px;margin-bottom:8px}
+.cards{display:flex;flex-wrap:wrap;gap:12px}
+.card{background:#fff;border:1px solid var(--line);border-radius:6px;padding:12px 16px;min-width:120px}
+.card-value{font-size:24px;font-weight:700;color:var(--brand)}
+.card-label{font-size:12px;color:var(--muted)}
+.card-sub{font-size:11px;color:var(--muted);margin-top:2px}
+.card.accent{background:#eef5fb;border-color:#cfe0ef}
+.card.clean .card-value{color:var(--ok)}
+.card.alert .card-value{color:var(--alert)}
+table{border-collapse:collapse;width:100%;font-size:12px}
+th,td{text-align:left;padding:6px 8px;border-bottom:1px solid var(--line);vertical-align:top;word-break:break-word}
+th{background:var(--brand);color:#fff;cursor:pointer;user-select:none;position:sticky;top:0}
+td.num,th.num{text-align:right}
+tbody tr:nth-child(even){background:var(--zebra)}
+.controls{display:flex;justify-content:space-between;align-items:center;margin:12px 0;flex-wrap:wrap;gap:8px}
+.search{padding:6px 10px;border:1px solid var(--line);border-radius:4px;font-size:13px;width:280px;max-width:100%}
+.pager{display:flex;gap:8px;align-items:center;font-size:12px}
+.pager button{padding:4px 10px;border:1px solid var(--line);background:#fff;border-radius:4px;cursor:pointer}
+.pager button:disabled{opacity:.4;cursor:default}
+.empty{color:var(--ok);font-size:13px;margin:8px 0 20px;font-weight:600}
+.footer{color:var(--muted);font-size:11px;margin-top:24px;border-top:1px solid var(--line);padding-top:8px}
+'@
+
+    return "<!DOCTYPE html><html lang=`"en`"><head><meta charset=`"utf-8`"><meta name=`"viewport`" content=`"width=device-width, initial-scale=1`"><title>$Title</title><style>$css</style></head><body>"
+}
diff --git a/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlScript.ps1 b/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlScript.ps1
new file mode 100644
index 0000000..939bc5f
--- /dev/null
+++ b/src/Modules/SPSCleanDependencies.Common/Private/Get-SPSReportHtmlScript.ps1
@@ -0,0 +1,109 @@
+function Get-SPSReportHtmlScript {
+    <#
+        .SYNOPSIS
+        Returns the vanilla-JavaScript block that renders the interactive per-category tables.
+
+        .DESCRIPTION
+        Reads a single JSON payload (embedded in a <script type="application/json"
+        id="spsReportData"> element) describing one or more sections. Each section has
+        an id, a list of columns and a list of rows. For every section the script wires
+        a per-section search box (filter) and clickable column headers (sort) against
+        the matching <table> rendered by Export-SPSCleanDependenciesReport. No external
+        dependency (works offline on a SharePoint server).
+    #>
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param ()
+
+    $js = @'
+(function(){
+  var node = document.getElementById('spsReportData');
+  if (!node) { return; }
+  var data = JSON.parse(node.textContent || node.innerText);
+  var sections = data.sections || [];
+
+  sections.forEach(function(section){
+    var cols = section.columns || [];
+    var rows = section.rows || [];
+    var sortField = null, sortDir = 1, view = rows;
+    var search = document.getElementById('search-' + section.id);
+    var thead = document.getElementById('thead-' + section.id);
+    var tbody = document.getElementById('tbody-' + section.id);
+    var info = document.getElementById('info-' + section.id);
+    if (!thead || !tbody) { return; }
+
+    function isNum(c){ return c.type === 'num'; }
+
+    function buildHead(){
+      var tr = document.createElement('tr');
+      cols.forEach(function(c){
+        var th = document.createElement('th');
+        if (isNum(c)) { th.className = 'num'; }
+        th.textContent = c.label + '  \u2195';
+        th.addEventListener('click', function(){
+          if (sortField === c.field) { sortDir = -sortDir; } else { sortField = c.field; sortDir = 1; }
+          applySort(); render();
+        });
+        tr.appendChild(th);
+      });
+      thead.appendChild(tr);
+    }
+
+    function applyFilter(){
+      var q = (search && search.value || '').trim().toLowerCase();
+      if (!q) { view = rows; }
+      else {
+        view = rows.filter(function(r){
+          return cols.some(function(c){
+            var v = r[c.field];
+            return v != null && String(v).toLowerCase().indexOf(q) !== -1;
+          });
+        });
+      }
+    }
+
+    function applySort(){
+      if (!sortField) { return; }
+      var col = null;
+      cols.forEach(function(c){ if (c.field === sortField) { col = c; } });
+      var numeric = col && isNum(col);
+      view = view.slice().sort(function(a,b){
+        var x = a[sortField], y = b[sortField];
+        if (numeric) {
+          x = parseFloat(x); y = parseFloat(y);
+          if (isNaN(x)) { x = -Infinity; } if (isNaN(y)) { y = -Infinity; }
+          return (x - y) * sortDir;
+        }
+        x = x == null ? '' : String(x).toLowerCase();
+        y = y == null ? '' : String(y).toLowerCase();
+        if (x < y) { return -1 * sortDir; }
+        if (x > y) { return 1 * sortDir; }
+        return 0;
+      });
+    }
+
+    function render(){
+      tbody.innerHTML = '';
+      view.forEach(function(r){
+        var tr = document.createElement('tr');
+        cols.forEach(function(c){
+          var td = document.createElement('td');
+          if (isNum(c)) { td.className = 'num'; }
+          td.textContent = r[c.field] == null ? '' : r[c.field];
+          tr.appendChild(td);
+        });
+        tbody.appendChild(tr);
+      });
+      if (info) { info.textContent = view.length + ' / ' + rows.length + ' rows'; }
+    }
+
+    if (search) {
+      search.addEventListener('input', function(){ applyFilter(); applySort(); render(); });
+    }
+    buildHead(); render();
+  });
+})();
+'@
+
+    return "<script>$js</script>"
+}
diff --git a/src/Modules/SPSCleanDependencies.Common/Public/Backup-SPSJsonFile.ps1 b/src/Modules/SPSCleanDependencies.Common/Public/Backup-SPSJsonFile.ps1
new file mode 100644
index 0000000..4dd6a7d
--- /dev/null
+++ b/src/Modules/SPSCleanDependencies.Common/Public/Backup-SPSJsonFile.ps1
@@ -0,0 +1,68 @@
+function Backup-SPSJsonFile {
+    <#
+        .SYNOPSIS
+        Archives an existing results JSON snapshot into a history folder before it is overwritten.
+
+        .DESCRIPTION
+        Backup-SPSJsonFile copies the file at -Path into -HistoryFolder, appending a
+        timestamp to the file name (e.g. CONTOSO-PROD-SPSE-20260709-1615.json). The
+        original file is left untouched so the caller can overwrite it with a fresh
+        audit afterwards.
+
+        The function does not perform retention/rotation itself: call
+        Clear-SPSLogFolder -Extension '*.json' on the history folder to prune old
+        snapshots, reusing the toolkit's single rotation implementation.
+
+        Returns the full path of the backup that was created, or $null when -Path does
+        not exist (first run, nothing to archive).
+
+        .PARAMETER Path
+        The results JSON file about to be overwritten.
+
+        .PARAMETER HistoryFolder
+        Destination folder for the timestamped copy. Created if missing.
+
+        .PARAMETER TimeStamp
+        Timestamp string injected into the backup file name. Defaults to the current
+        date/time as yyyyMMdd-HHmm. Exposed mainly for deterministic testing.
+
+        .EXAMPLE
+        $previous = Backup-SPSJsonFile -Path $pathJsonFile -HistoryFolder $historyFolder
+    #>
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Path,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $HistoryFolder,
+
+        [Parameter()]
+        [System.String]
+        $TimeStamp = (Get-Date -Format yyyyMMdd-HHmm)
+    )
+
+    if (-not (Test-Path -Path $Path)) {
+        Write-Verbose -Message "Backup-SPSJsonFile: no existing file to archive at '$Path'."
+        return $null
+    }
+
+    if (-not (Test-Path -Path $HistoryFolder)) {
+        $null = New-Item -Path $HistoryFolder -ItemType Directory -Force
+    }
+
+    $leaf = Split-Path -Path $Path -Leaf
+    $name = [System.IO.Path]::GetFileNameWithoutExtension($leaf)
+    $extension = [System.IO.Path]::GetExtension($leaf)
+    $backupName = "$name-$TimeStamp$extension"
+    $backupPath = Join-Path -Path $HistoryFolder -ChildPath $backupName
+
+    Copy-Item -Path $Path -Destination $backupPath -Force
+    Write-Verbose -Message "Backup-SPSJsonFile: archived '$Path' to '$backupPath'."
+
+    return $backupPath
+}
diff --git a/src/Modules/SPSCleanDependencies.Common/Public/Clear-SPSLogFolder.ps1 b/src/Modules/SPSCleanDependencies.Common/Public/Clear-SPSLogFolder.ps1
new file mode 100644
index 0000000..873682c
--- /dev/null
+++ b/src/Modules/SPSCleanDependencies.Common/Public/Clear-SPSLogFolder.ps1
@@ -0,0 +1,79 @@
+function Clear-SPSLogFolder {
+    <#
+        .SYNOPSIS
+        Deletes old files from a folder based on a retention window.
+
+        .DESCRIPTION
+        Clear-SPSLogFolder removes files older than the requested number of days from
+        the specified folder (recursively). The retention window is evaluated against
+        each file's LastWriteTime. It is the toolkit's single rotation implementation,
+        reused for both the transcript logs (Logs\) and the archived results snapshots
+        (Results\history\, via -Extension '*.json').
+
+        A Retention of 0 disables pruning (nothing is deleted). The function emits
+        banner lines on stdout so it stays visible inside the Start-Transcript output
+        produced by SPSCleanDependencies.
+
+        .PARAMETER Path
+        Directory to scan. Subdirectories are scanned recursively.
+
+        .PARAMETER Retention
+        Number of days to keep. Files older than this are deleted. Defaults to 90 days.
+        A value of 0 disables pruning.
+
+        .PARAMETER Extension
+        File name pattern to filter on. Defaults to '*.log'.
+
+        .EXAMPLE
+        Clear-SPSLogFolder -Path 'D:\Tools\Logs' -Retention 30
+
+        .EXAMPLE
+        Clear-SPSLogFolder -Path $historyFolder -Retention 30 -Extension '*.json'
+    #>
+    [CmdletBinding(SupportsShouldProcess = $true)]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Path,
+
+        [Parameter()]
+        [System.UInt32]
+        $Retention = 90,
+
+        [Parameter()]
+        [System.String]
+        $Extension = '*.log'
+    )
+
+    if ($Retention -eq 0) {
+        Write-Verbose -Message 'Clear-SPSLogFolder: retention disabled (Retention = 0), nothing to prune.'
+        return
+    }
+
+    if (-not (Test-Path -Path $Path)) {
+        return
+    }
+
+    $lastWrite = (Get-Date).AddDays(-$Retention)
+
+    $files = Get-ChildItem -Path $Path -Include $Extension -Recurse -File -ErrorAction SilentlyContinue |
+        Where-Object -FilterScript { $_.LastWriteTime -le $lastWrite }
+
+    Write-Output '--------------------------------------------------------------'
+    if ($files) {
+        Write-Output "Cleaning files ($Extension) older than $Retention days in $Path ..."
+        foreach ($file in $files) {
+            if ($null -ne $file) {
+                if ($PSCmdlet.ShouldProcess($file.FullName, 'Remove file')) {
+                    Write-Output "Deleting file $($file.FullName) ..."
+                    Remove-Item -Path $file.FullName -Force -ErrorAction SilentlyContinue | Out-Null
+                }
+            }
+        }
+    }
+    else {
+        Write-Output "$Path - No files ($Extension) to delete"
+    }
+    Write-Output '--------------------------------------------------------------'
+}
diff --git a/src/Modules/SPSCleanDependencies.Common/Public/Export-SPSCleanDependenciesReport.ps1 b/src/Modules/SPSCleanDependencies.Common/Public/Export-SPSCleanDependenciesReport.ps1
new file mode 100644
index 0000000..ae6101c
--- /dev/null
+++ b/src/Modules/SPSCleanDependencies.Common/Public/Export-SPSCleanDependenciesReport.ps1
@@ -0,0 +1,227 @@
+function Export-SPSCleanDependenciesReport {
+    <#
+        .SYNOPSIS
+        Generates a self-contained HTML report from a SPSCleanDependencies results JSON.
+
+        .DESCRIPTION
+        Export-SPSCleanDependenciesReport renders the results produced by
+        Get-SPSMissingServerDependencies (the Results\<FileName>.json audit file) as a
+        single, dependency-free HTML file (no CDN, works offline on a SharePoint server).
+
+        The report shows one summary card per dependency category (count of items found)
+        and, for every non-empty category, a filterable / sortable table of the items
+        with their identifying fields. When the audit found nothing, the report renders a
+        clean "no missing dependencies" state.
+
+        The data can be supplied either as a file (-InputFile, the JSON results) or as an
+        already-parsed object (-InputObject). Returns the path of the report written.
+
+        .PARAMETER InputFile
+        Path of the results JSON file to read.
+
+        .PARAMETER InputObject
+        An already-parsed results object (as returned by ConvertFrom-Json).
+
+        .PARAMETER OutputFile
+        Destination path of the generated .html file.
+
+        .PARAMETER Title
+        Heading shown at the top of the report. Defaults to a generic title.
+
+        .PARAMETER FarmName
+        Farm / file label shown in the metadata line (e.g. CONTOSO-PROD-SPSE).
+
+        .PARAMETER Version
+        SPSCleanDependencies version stamped in the report footer. Defaults to the
+        SPSCleanDependencies.Common module version.
+
+        .EXAMPLE
+        Export-SPSCleanDependenciesReport -InputFile $json -OutputFile $html -FarmName 'CONTOSO-PROD-SPSE'
+    #>
+    [CmdletBinding(DefaultParameterSetName = 'ByFile')]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true, ParameterSetName = 'ByFile')]
+        [System.String]
+        $InputFile,
+
+        [Parameter(Mandatory = $true, ParameterSetName = 'ByObject')]
+        $InputObject,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $OutputFile,
+
+        [Parameter()]
+        [System.String]
+        $Title,
+
+        [Parameter()]
+        [System.String]
+        $FarmName,
+
+        [Parameter()]
+        [System.String]
+        $Version
+    )
+
+    # ---- Load the results ---------------------------------------------------------
+    if ($PSCmdlet.ParameterSetName -eq 'ByFile') {
+        if (-not (Test-Path -Path $InputFile)) {
+            throw "Export-SPSCleanDependenciesReport: input file not found: $InputFile"
+        }
+        $raw = Get-Content -Path $InputFile -Raw -Encoding UTF8
+        $results = if ([string]::IsNullOrWhiteSpace($raw)) { $null } else { $raw | ConvertFrom-Json }
+    }
+    else {
+        $results = $InputObject
+    }
+
+    if ([string]::IsNullOrEmpty($Title)) { $Title = 'SPSCleanDependencies - Missing Server Dependencies Report' }
+
+    if ([string]::IsNullOrEmpty($Version)) {
+        $moduleVersion = (Get-Module -Name SPSCleanDependencies.Common -ErrorAction SilentlyContinue).Version
+        $Version = if ($null -ne $moduleVersion) { $moduleVersion.ToString() } else { 'unknown' }
+    }
+
+    # ---- Category metadata (JSON key -> label + table columns) --------------------
+    $categories = @(
+        [PSCustomObject]@{ Key = 'MissingFeature'; Label = 'Missing Features'; Columns = @(
+                @{ field = 'Database'; label = 'Database'; type = 'text' }
+                @{ field = 'FeatureID'; label = 'Feature ID'; type = 'text' }
+                @{ field = 'SiteID'; label = 'Site ID'; type = 'text' }
+                @{ field = 'Path'; label = 'Path'; type = 'text' }
+            ) }
+        [PSCustomObject]@{ Key = 'MissingWebPart'; Label = 'Missing WebParts'; Columns = @(
+                @{ field = 'Database'; label = 'Database'; type = 'text' }
+                @{ field = 'WebPartID'; label = 'WebPart ID'; type = 'text' }
+                @{ field = 'ClassName'; label = 'Class'; type = 'text' }
+                @{ field = 'SiteID'; label = 'Site ID'; type = 'text' }
+                @{ field = 'WebID'; label = 'Web ID'; type = 'text' }
+                @{ field = 'DirName'; label = 'Dir'; type = 'text' }
+                @{ field = 'LeafName'; label = 'Page'; type = 'text' }
+            ) }
+        [PSCustomObject]@{ Key = 'MissingSetupFile'; Label = 'Missing Setup Files'; Columns = @(
+                @{ field = 'Database'; label = 'Database'; type = 'text' }
+                @{ field = 'SetupPath'; label = 'Setup Path'; type = 'text' }
+                @{ field = 'FileID'; label = 'File ID'; type = 'text' }
+                @{ field = 'SiteID'; label = 'Site ID'; type = 'text' }
+                @{ field = 'WebID'; label = 'Web ID'; type = 'text' }
+            ) }
+        [PSCustomObject]@{ Key = 'MissingAssembly'; Label = 'Missing Assemblies'; Columns = @(
+                @{ field = 'Database'; label = 'Database'; type = 'text' }
+                @{ field = 'AssemblyInfo'; label = 'Assembly'; type = 'text' }
+                @{ field = 'AssemblyID'; label = 'Assembly ID'; type = 'text' }
+                @{ field = 'HostType'; label = 'Host Type'; type = 'text' }
+                @{ field = 'HostID'; label = 'Host ID'; type = 'text' }
+                @{ field = 'SiteID'; label = 'Site ID'; type = 'text' }
+                @{ field = 'WebID'; label = 'Web ID'; type = 'text' }
+            ) }
+        [PSCustomObject]@{ Key = 'Configuration'; Label = 'Configuration (Classic Auth Admins)'; Columns = @(
+                @{ field = 'Database'; label = 'Database'; type = 'text' }
+                @{ field = 'SiteID'; label = 'Site ID'; type = 'text' }
+                @{ field = 'Login'; label = 'Login'; type = 'text' }
+            ) }
+        [PSCustomObject]@{ Key = 'MissingSiteDefinition'; Label = 'Missing Site Definitions (audit only)'; Columns = @(
+                @{ field = 'Database'; label = 'Database'; type = 'text' }
+                @{ field = 'Message'; label = 'Message'; type = 'text' }
+                @{ field = 'Remedy'; label = 'Remedy'; type = 'text' }
+            ) }
+        [PSCustomObject]@{ Key = 'SiteOrphan'; Label = 'Orphaned Sites'; Columns = @(
+                @{ field = 'Database'; label = 'Database'; type = 'text' }
+                @{ field = 'SiteID'; label = 'Site ID'; type = 'text' }
+            ) }
+    )
+
+    # ---- Build cards, sections and JSON payload -----------------------------------
+    $cards = @()
+    $sectionsHtml = ''
+    $payloadSections = @()
+    $totalItems = 0
+
+    foreach ($category in $categories) {
+        $items = @()
+        if ($null -ne $results -and ($results.PSObject.Properties.Name -contains $category.Key)) {
+            $items = @($results.$($category.Key) | Where-Object { $null -ne $_ })
+        }
+        $count = $items.Count
+        $totalItems += $count
+
+        $tone = if ($count -eq 0) { 'clean' } else { 'alert' }
+        $cards += (Get-SPSReportCardHtml -Value $count -Label $category.Label -Tone $tone)
+
+        if ($count -eq 0) { continue }
+
+        $sectionId = $category.Key
+        $rows = foreach ($item in $items) {
+            $ordered = [ordered]@{}
+            foreach ($col in $category.Columns) {
+                $ordered[$col.field] = "$($item.$($col.field))"
+            }
+            [PSCustomObject]$ordered
+        }
+
+        $payloadSections += [ordered]@{
+            id      = $sectionId
+            columns = $category.Columns
+            rows    = @($rows)
+        }
+
+        $encLabel = ConvertTo-SPSHtmlEncoded -Value $category.Label
+        $sectionsHtml += "<h2>$encLabel <span style=`"color:#666;font-weight:400;font-size:13px`">($count)</span></h2>" +
+        "<div class=`"controls`"><input id=`"search-$sectionId`" class=`"search`" placeholder=`"Filter...`"><div class=`"pager`"><span id=`"info-$sectionId`"></span></div></div>" +
+        "<table><thead id=`"thead-$sectionId`"></thead><tbody id=`"tbody-$sectionId`"></tbody></table>"
+    }
+
+    $payload = [ordered]@{ sections = @($payloadSections) }
+    $json = $payload | ConvertTo-Json -Depth 6 -Compress
+    # Neutralize any sequence that could break out of the <script> block
+    $json = $json -replace '<', '\u003c' -replace '>', '\u003e' -replace '&', '\u0026'
+
+    # ---- Metadata -----------------------------------------------------------------
+    $encTitle = ConvertTo-SPSHtmlEncoded -Value $Title
+    $encFarm = ConvertTo-SPSHtmlEncoded -Value $FarmName
+    $encVersion = ConvertTo-SPSHtmlEncoded -Value $Version
+    $generated = Get-Date -Format 'yyyy-MM-dd HH:mm'
+
+    $metaParts = @()
+    if (-not [string]::IsNullOrEmpty($encFarm)) { $metaParts += "Farm: $encFarm" }
+    $metaParts += "Generated: $generated"
+    $metaParts += "SPSCleanDependencies $encVersion"
+    $metaLine = $metaParts -join ' &middot; '
+
+    $totalTone = if ($totalItems -eq 0) { 'clean' } else { 'alert' }
+    $totalCard = Get-SPSReportCardHtml -Value $totalItems -Label 'Total items' -Tone $totalTone
+    $summaryInner = "<div class=`"cards`">$totalCard$($cards -join '')</div>"
+
+    $emptyNote = if ($totalItems -eq 0) {
+        '<div class="empty">No missing server side dependencies were found. Nothing to clean.</div>'
+    }
+    else { '' }
+
+    # ---- Assemble the document ----------------------------------------------------
+    $html = (Get-SPSReportHtmlHead -Title $encTitle) +
+    "<h1>$encTitle</h1>" +
+    "<div class=`"meta`">$metaLine</div>" +
+    "<div class=`"summary`"><h3 style=`"margin-top:0`">Summary</h3>$summaryInner</div>" +
+    $emptyNote +
+    $sectionsHtml +
+    "<div class=`"footer`">Generated by SPSCleanDependencies $encVersion. Back up your content databases and review this report before running the script with the -Clean switch.</div>" +
+    "<script type=`"application/json`" id=`"spsReportData`">$json</script>" +
+    (Get-SPSReportHtmlScript) +
+    '</body></html>'
+
+    # ---- Atomic write -------------------------------------------------------------
+    $outDir = Split-Path -Path $OutputFile -Parent
+    if (-not [string]::IsNullOrEmpty($outDir) -and -not (Test-Path -Path $outDir)) {
+        $null = New-Item -Path $outDir -ItemType Directory -Force
+    }
+
+    $encoding = [System.Text.UTF8Encoding]::new($true)
+    $tmpPath = '{0}.tmp.{1}' -f $OutputFile, ([guid]::NewGuid().ToString('N'))
+    [System.IO.File]::WriteAllText($tmpPath, $html, $encoding)
+    Move-Item -Path $tmpPath -Destination $OutputFile -Force
+
+    return $OutputFile
+}
diff --git a/src/Modules/SPSCleanDependencies.Common/SPSCleanDependencies.Common.psd1 b/src/Modules/SPSCleanDependencies.Common/SPSCleanDependencies.Common.psd1
index 2d301eb..23aeaec 100644
--- a/src/Modules/SPSCleanDependencies.Common/SPSCleanDependencies.Common.psd1
+++ b/src/Modules/SPSCleanDependencies.Common/SPSCleanDependencies.Common.psd1
@@ -1,6 +1,6 @@
 @{
     RootModule        = 'SPSCleanDependencies.Common.psm1'
-    ModuleVersion     = '1.3.0'
+    ModuleVersion     = '1.4.0'
     GUID              = 'aa259ca2-c421-487d-80ec-b7d7b440c584'
     Author            = 'Jean-Cyril DROUHIN'
     CompanyName       = 'luigilink'
@@ -10,6 +10,9 @@
     PowerShellVersion = '5.1'
 
     FunctionsToExport = @(
+        'Backup-SPSJsonFile'
+        'Clear-SPSLogFolder'
+        'Export-SPSCleanDependenciesReport'
         'Get-SPSInstalledProductVersion'
         'Get-SPSMissingServerDependencies'
         'Remove-SPSMissingAssembly'

From a02e39210670bc1059cddb2b7cfbdea2d2c768b8 Mon Sep 17 00:00:00 2001
From: LuigiLink <jcdrouhin@yahoo.fr>
Date: Thu, 9 Jul 2026 16:43:03 +0200
Subject: [PATCH 2/4] feat: wire history archiving and HTML report into the
 audit run

In the audit branch (no -Clean), the entry script now:
- archives the previous Results\<FileName>.json into Results\history (timestamped)
  before the fresh audit overwrites it;
- generates a Results\<FileName>.html report from the new results;
- prunes old history snapshots and transcript logs.

The current Results\<FileName>.json is kept stable (it remains the exact input
consumed by the -Clean run); only the history copies are timestamped. Retention
is configurable via the new -HistoryRetentionDays (default 30) and
-LogRetentionDays (default 180) parameters; 0 disables pruning.

Refs #8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/SPSCleanDependencies.ps1 | 39 +++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/SPSCleanDependencies.ps1 b/src/SPSCleanDependencies.ps1
index cc7818e..f36a692 100644
--- a/src/SPSCleanDependencies.ps1
+++ b/src/SPSCleanDependencies.ps1
@@ -16,6 +16,15 @@
     .PARAMETER Clean
     Use the switch Clean parameter if you want to clean up Missing server side dependencies
 
+    .PARAMETER HistoryRetentionDays
+    Number of days of archived result snapshots to keep in the Results\history folder.
+    Before each audit the current Results\<FileName>.json is copied there with a
+    timestamp; snapshots older than this are pruned. Defaults to 30. Set to 0 to disable pruning.
+
+    .PARAMETER LogRetentionDays
+    Number of days of transcript log files to keep in the Logs folder. Defaults to 180.
+    Set to 0 to disable pruning.
+
     .EXAMPLE
     SPSCleanDependencies.ps1 -FileName 'CONTOSO-PROD-SP2019'
     This command will create a JSON file in the Results folder with the name CONTOSO-PROD-SP2019.json
@@ -38,7 +47,15 @@ param(
 
     [Parameter(Position = 2)]
     [switch]
-    $Clean
+    $Clean,
+
+    [Parameter()]
+    [System.UInt32]
+    $HistoryRetentionDays = 30,
+
+    [Parameter()]
+    [System.UInt32]
+    $LogRetentionDays = 180
 )
 
 #requires -Version 5.1
@@ -125,6 +142,8 @@ if (-not(Test-Path $pathResultsFolder)) {
 }
 $pathLogFile = Join-Path -Path $pathLogsFolder -ChildPath "$($FileName)_$([datetime]::Now.ToString('yyyyMMddHHmmss')).log"
 $pathJsonFile = Join-Path -Path $pathResultsFolder -ChildPath ("$($FileName).json")
+$pathHtmlFile = Join-Path -Path $pathResultsFolder -ChildPath ("$($FileName).html")
+$pathHistoryFolder = Join-Path -Path $pathResultsFolder -ChildPath 'history'
 $DateStarted = Get-date
 $psVersion = ($host).Version.ToString()
 
@@ -220,7 +239,25 @@ if ($Clean) {
 }
 else {
     Write-Output 'Getting Missing Server Side Dependencies'
+
+    # Archive the previous results snapshot (if any) before it is overwritten,
+    # so a history of past audits is kept under Results\history.
+    [void](Backup-SPSJsonFile -Path $pathJsonFile -HistoryFolder $pathHistoryFolder)
+
     Get-SPSMissingServerDependencies -Path $pathJsonFile
+
+    # Generate a self-contained HTML report from the fresh results.
+    if (Test-Path $pathJsonFile) {
+        Write-Output "Generating HTML report: $pathHtmlFile"
+        [void](Export-SPSCleanDependenciesReport -InputFile $pathJsonFile `
+                -OutputFile $pathHtmlFile `
+                -FarmName $FileName `
+                -Version $SPSCleanDependenciesVersion)
+    }
+
+    # Prune old history snapshots and transcript logs.
+    Clear-SPSLogFolder -Path $pathHistoryFolder -Retention $HistoryRetentionDays -Extension '*.json'
+    Clear-SPSLogFolder -Path $pathLogsFolder -Retention $LogRetentionDays -Extension '*.log'
 }
 #endregion
 

From 97456a42d920dcc13750fd573a727cb46194930c Mon Sep 17 00:00:00 2001
From: LuigiLink <jcdrouhin@yahoo.fr>
Date: Thu, 9 Jul 2026 16:44:43 +0200
Subject: [PATCH 3/4] test: cover history and HTML report functions

Extend the Pester suite for the 1.4.0 feature:

- Module tests: add Backup-SPSJsonFile (no-op on missing source, timestamped
  archive leaving the original in place), Clear-SPSLogFolder (retention prune,
  Retention=0 no-op, ShouldProcess), Export-SPSCleanDependenciesReport (section
  per non-empty category, HTML-encoding of result values, clean empty state,
  throw on missing input) and the private HTML helpers; refresh the exported-set
  and FunctionsToExport assertions.
- Entry-script tests: assert the new -HistoryRetentionDays/-LogRetentionDays
  parameters and the audit-branch wiring (Backup-SPSJsonFile,
  Export-SPSCleanDependenciesReport, Clear-SPSLogFolder).

100/100 green locally.

Refs #8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../SPSCleanDependencies.Common.Tests.ps1     | 140 ++++++++++++++++++
 tests/SPSCleanDependencies.Tests.ps1          |  30 +++-
 2 files changed, 168 insertions(+), 2 deletions(-)

diff --git a/tests/Modules/SPSCleanDependencies.Common.Tests.ps1 b/tests/Modules/SPSCleanDependencies.Common.Tests.ps1
index a66f1db..faaf877 100644
--- a/tests/Modules/SPSCleanDependencies.Common.Tests.ps1
+++ b/tests/Modules/SPSCleanDependencies.Common.Tests.ps1
@@ -62,6 +62,9 @@ Describe 'SPSCleanDependencies.Common Module' {
 Describe 'SPSCleanDependencies.Common Public Functions' {
 
     $publicFunctions = @(
+        'Backup-SPSJsonFile',
+        'Clear-SPSLogFolder',
+        'Export-SPSCleanDependenciesReport',
         'Get-SPSInstalledProductVersion',
         'Get-SPSMissingServerDependencies',
         'Remove-SPSMissingFeature',
@@ -78,6 +81,9 @@ Describe 'SPSCleanDependencies.Common Public Functions' {
 
     It 'manifest FunctionsToExport matches the exported set' {
         $expectedExports = @(
+            'Backup-SPSJsonFile',
+            'Clear-SPSLogFolder',
+            'Export-SPSCleanDependenciesReport',
             'Get-SPSInstalledProductVersion',
             'Get-SPSMissingServerDependencies',
             'Remove-SPSMissingFeature',
@@ -114,6 +120,140 @@ Describe 'SPSCleanDependencies.Common Private SQL Helpers' {
     }
 }
 
+Describe 'SPSCleanDependencies.Common Private HTML Report Helpers' {
+
+    $htmlHelpers = @(
+        'ConvertTo-SPSHtmlEncoded',
+        'Get-SPSReportHtmlHead',
+        'Get-SPSReportCardHtml',
+        'Get-SPSReportHtmlScript'
+    )
+
+    It 'defines internal helper <_> (module scope)' -ForEach $htmlHelpers {
+        $helper = $_
+        InModuleScope -ModuleName 'SPSCleanDependencies.Common' -Parameters @{ helper = $helper } {
+            param($helper)
+            Get-Command -Name $helper -ErrorAction SilentlyContinue | Should -Not -BeNullOrEmpty
+        }
+    }
+
+    It 'does not export the HTML helpers to callers <_>' -ForEach $htmlHelpers {
+        (Get-Module -Name $script:moduleName).ExportedFunctions.Keys | Should -Not -Contain $_
+    }
+
+    It 'ConvertTo-SPSHtmlEncoded escapes HTML metacharacters' {
+        InModuleScope -ModuleName 'SPSCleanDependencies.Common' {
+            ConvertTo-SPSHtmlEncoded -Value 'a<b>&"x''y' | Should -Be 'a&lt;b&gt;&amp;&quot;x&#39;y'
+        }
+    }
+}
+
+Describe 'Backup-SPSJsonFile' {
+
+    BeforeEach {
+        $script:tempRoot = Join-Path -Path $TestDrive -ChildPath ([guid]::NewGuid().ToString('N'))
+        $null = New-Item -Path $script:tempRoot -ItemType Directory -Force
+        $script:jsonPath = Join-Path -Path $script:tempRoot -ChildPath 'CONTOSO-PROD-SPSE.json'
+        $script:historyFolder = Join-Path -Path $script:tempRoot -ChildPath 'history'
+    }
+
+    It 'returns $null and creates nothing when the source does not exist' {
+        $result = Backup-SPSJsonFile -Path $script:jsonPath -HistoryFolder $script:historyFolder
+        $result | Should -BeNullOrEmpty
+        Test-Path $script:historyFolder | Should -BeFalse
+    }
+
+    It 'archives an existing file with a timestamped name and leaves the original in place' {
+        '{}' | Set-Content -Path $script:jsonPath
+        $result = Backup-SPSJsonFile -Path $script:jsonPath -HistoryFolder $script:historyFolder -TimeStamp '20260709-1615'
+        $result | Should -Not -BeNullOrEmpty
+        Split-Path $result -Leaf | Should -Be 'CONTOSO-PROD-SPSE-20260709-1615.json'
+        Test-Path $result | Should -BeTrue
+        Test-Path $script:jsonPath | Should -BeTrue
+    }
+}
+
+Describe 'Clear-SPSLogFolder' {
+
+    BeforeEach {
+        $script:folder = Join-Path -Path $TestDrive -ChildPath ([guid]::NewGuid().ToString('N'))
+        $null = New-Item -Path $script:folder -ItemType Directory -Force
+        $script:oldFile = Join-Path -Path $script:folder -ChildPath 'old.json'
+        $script:newFile = Join-Path -Path $script:folder -ChildPath 'new.json'
+        '{}' | Set-Content -Path $script:oldFile
+        '{}' | Set-Content -Path $script:newFile
+        (Get-Item $script:oldFile).LastWriteTime = (Get-Date).AddDays(-40)
+    }
+
+    It 'declares SupportsShouldProcess' {
+        $params = (Get-Command Clear-SPSLogFolder).Parameters.Keys
+        $params | Should -Contain 'WhatIf'
+        $params | Should -Contain 'Confirm'
+    }
+
+    It 'removes files older than the retention window and keeps recent ones' {
+        Clear-SPSLogFolder -Path $script:folder -Retention 30 -Extension '*.json' | Out-Null
+        Test-Path $script:oldFile | Should -BeFalse
+        Test-Path $script:newFile | Should -BeTrue
+    }
+
+    It 'does nothing when Retention is 0' {
+        Clear-SPSLogFolder -Path $script:folder -Retention 0 -Extension '*.json' | Out-Null
+        Test-Path $script:oldFile | Should -BeTrue
+        Test-Path $script:newFile | Should -BeTrue
+    }
+}
+
+Describe 'Export-SPSCleanDependenciesReport' {
+
+    BeforeEach {
+        $script:reportRoot = Join-Path -Path $TestDrive -ChildPath ([guid]::NewGuid().ToString('N'))
+        $null = New-Item -Path $script:reportRoot -ItemType Directory -Force
+        $script:inJson = Join-Path -Path $script:reportRoot -ChildPath 'in.json'
+        $script:outHtml = Join-Path -Path $script:reportRoot -ChildPath 'out.html'
+    }
+
+    It 'renders a self-contained report with a section per non-empty category' {
+        $sample = [ordered]@{
+            MissingFeature = @(@{ Database = 'WSS'; FeatureID = 'f1'; SiteID = 's1'; Path = '/a' })
+            SiteOrphan     = @(@{ Database = 'WSS'; SiteID = 's2' })
+        }
+        $sample | ConvertTo-Json -Depth 6 | Set-Content -Path $script:inJson -Encoding UTF8
+
+        $out = Export-SPSCleanDependenciesReport -InputFile $script:inJson -OutputFile $script:outHtml -FarmName 'CONTOSO-PROD-SPSE'
+        $out | Should -Be $script:outHtml
+        Test-Path $script:outHtml | Should -BeTrue
+
+        $html = Get-Content -Path $script:outHtml -Raw
+        $html | Should -Match '^\ufeff?<!DOCTYPE html>'
+        $html.TrimEnd() | Should -Match '</html>$'
+        $html | Should -Match 'thead-MissingFeature'
+        $html | Should -Match 'thead-SiteOrphan'
+        $html | Should -Match 'Total items'
+    }
+
+    It 'HTML-encodes values coming from the results (no raw markup leaks)' {
+        $sample = [ordered]@{
+            MissingWebPart = @(@{ Database = 'WSS'; WebPartID = 'wp'; ClassName = 'Contoso.WP<script>'; StorageKey = 'k'; SiteID = 's'; WebID = 'w'; ListID = 'l'; DirName = 'd'; LeafName = 'p.aspx' })
+        }
+        $sample | ConvertTo-Json -Depth 6 | Set-Content -Path $script:inJson -Encoding UTF8
+        [void](Export-SPSCleanDependenciesReport -InputFile $script:inJson -OutputFile $script:outHtml)
+        $html = Get-Content -Path $script:outHtml -Raw
+        $html | Should -Not -Match 'Contoso\.WP<script>'
+    }
+
+    It 'renders a clean "nothing to clean" state when the results are empty' {
+        '{}' | Set-Content -Path $script:inJson
+        [void](Export-SPSCleanDependenciesReport -InputFile $script:inJson -OutputFile $script:outHtml)
+        (Get-Content -Path $script:outHtml -Raw) | Should -Match 'No missing server side dependencies'
+    }
+
+    It 'throws when the input file is missing' {
+        { Export-SPSCleanDependenciesReport -InputFile (Join-Path $script:reportRoot 'nope.json') -OutputFile $script:outHtml } |
+            Should -Throw
+    }
+}
+
 Describe 'SPSCleanDependencies.Common Function Parameter Contracts' {
 
     It 'Get-SPSMissingServerDependencies has a Path parameter' {
diff --git a/tests/SPSCleanDependencies.Tests.ps1 b/tests/SPSCleanDependencies.Tests.ps1
index 07ed494..c5ee288 100644
--- a/tests/SPSCleanDependencies.Tests.ps1
+++ b/tests/SPSCleanDependencies.Tests.ps1
@@ -102,8 +102,14 @@ Describe 'SPSCleanDependencies.ps1 Parameters' {
         $typeAttr.TypeName.FullName | Should -Be 'switch'
     }
 
-    It 'Should have exactly two parameters' {
-        $script:paramBlock.Parameters.Count | Should -Be 2
+    It 'Should expose the HistoryRetentionDays and LogRetentionDays parameters' {
+        $names = $script:paramBlock.Parameters | ForEach-Object { $_.Name.VariablePath.UserPath }
+        $names | Should -Contain 'HistoryRetentionDays'
+        $names | Should -Contain 'LogRetentionDays'
+    }
+
+    It 'Should have exactly four parameters' {
+        $script:paramBlock.Parameters.Count | Should -Be 4
     }
 }
 
@@ -180,3 +186,23 @@ Describe 'SPSCleanDependencies.ps1 Clean Branch' {
         $script:scriptContent | Should -Match 'Throw\s+"Missing\s+\$pathJsonFile'
     }
 }
+Describe 'SPSCleanDependencies.ps1 Audit Branch (history + report)' {
+
+    It 'Should archive the previous results with Backup-SPSJsonFile before the audit' {
+        $script:scriptContent | Should -Match 'Backup-SPSJsonFile\s+-Path\s+\$pathJsonFile'
+    }
+
+    It 'Should generate the HTML report with Export-SPSCleanDependenciesReport' {
+        $script:scriptContent | Should -Match 'Export-SPSCleanDependenciesReport\s+-InputFile\s+\$pathJsonFile'
+    }
+
+    It 'Should prune the history folder and the logs folder with Clear-SPSLogFolder' {
+        $script:scriptContent | Should -Match 'Clear-SPSLogFolder\s+-Path\s+\$pathHistoryFolder'
+        $script:scriptContent | Should -Match 'Clear-SPSLogFolder\s+-Path\s+\$pathLogsFolder'
+    }
+
+    It 'Should derive the html file and history folder paths' {
+        $script:scriptContent | Should -Match '\$pathHtmlFile\s*='
+        $script:scriptContent | Should -Match '\$pathHistoryFolder\s*='
+    }
+}

From c253408103a423434c51035969e453286efc298d Mon Sep 17 00:00:00 2001
From: LuigiLink <jcdrouhin@yahoo.fr>
Date: Thu, 9 Jul 2026 16:46:11 +0200
Subject: [PATCH 4/4] docs: document results history and HTML report (1.4.0)

- CHANGELOG: add the 1.4.0 entry (history backup + retention, HTML report,
  new -HistoryRetentionDays/-LogRetentionDays parameters).
- RELEASE-NOTES: rewrite for 1.4.0 (used verbatim as the GitHub Release body).
- Wiki: new Reports-and-History page (report layout, history folder, retention),
  add it to the sidebar and cross-link from Usage/Dependency-Types; document the
  two new parameters in Usage; refresh the Home key-features list.

Refs #8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                | 15 +++++++++++
 RELEASE-NOTES.md            | 22 ++++++---------
 wiki/Dependency-Types.md    |  1 +
 wiki/Home.md                |  3 +++
 wiki/Reports-and-History.md | 53 +++++++++++++++++++++++++++++++++++++
 wiki/Usage.md               |  3 +++
 wiki/_Sidebar.md            |  1 +
 7 files changed, 84 insertions(+), 14 deletions(-)
 create mode 100644 wiki/Reports-and-History.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58bf683..9ac41b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,21 @@
 The format is based on and uses the types of changes according to [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-07-09
+
+### Added
+
+- Results history:
+  - New `Backup-SPSJsonFile` public function archives the current `Results\<FileName>.json` into `Results\history\` with a `yyyyMMdd-HHmm` timestamp before each audit overwrites it (pattern reused from SPSUserSync / SPSWeather).
+  - New `Clear-SPSLogFolder` public function — a single retention/rotation implementation reused for both the transcript logs (`*.log`) and the archived snapshots (`*.json`). `Retention = 0` disables pruning.
+- HTML report:
+  - New `Export-SPSCleanDependenciesReport` public function renders the results JSON as a self-contained, dependency-free HTML report — one summary card per dependency category plus a filterable/sortable table per non-empty category, or a clean "nothing to clean" state. Uses an atomic write (temp file + `Move-Item`).
+  - New internal helpers (Private, not exported): `ConvertTo-SPSHtmlEncoded`, `Get-SPSReportHtmlHead`, `Get-SPSReportCardHtml`, `Get-SPSReportHtmlScript` (pattern reused from SPSUpdate.Common).
+- `SPSCleanDependencies.ps1`:
+  - The audit run now archives the previous results, generates `Results\<FileName>.html`, and prunes old history/logs. The current `Results\<FileName>.json` stays stable (still the exact input consumed by `-Clean`); only the history copies are timestamped.
+  - New `-HistoryRetentionDays` (default 30) and `-LogRetentionDays` (default 180) parameters control retention; `0` disables pruning. [issue #8](https://github.com/luigilink/SPSCleanDependencies/issues/8)
+- Pester coverage for the new functions and the audit-branch wiring.
+
 ## [1.3.0] - 2026-07-09
 
 ### Changed
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 613a217..a08c341 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,20 +1,14 @@
 # SPSCleanDependencies - Release Notes
 
-## [1.3.0] - 2026-07-09
+## [1.4.0] - 2026-07-09
 
-### Changed
+### Added
 
-- Restructure the helper module into `src/Modules/SPSCleanDependencies.Common` (aligned on the `SPSUpdate` pattern):
-  - One function per file under `Public/`, internal SQL helpers under `Private/` (`Get-SQLMissing*`, no longer exported).
-  - A loader `.psm1` dot-sourcing `Private/` + `Public/`, and a clean `.psd1` manifest (`ModuleVersion` 1.3.0, correct `FunctionsToExport`) replacing the mis-named, never-imported `SPSCleanDependencies.util.util.psd1`.
-  - The former module-level classes / `ArrayList` collections / `jsonObject` are folded into `Get-SPSMissingServerDependencies`, so the module holds no mutable state.
-- The entry script moves to `src/SPSCleanDependencies.ps1`, imports the module through its manifest, and sources its version from `(Get-Module SPSCleanDependencies.Common).Version`.
-- The import-time prelude (administrator check, High Performance power plan, SharePoint snap-in load) moves from the module into the entry script, making the module import-safe by design.
-- Behaviour on a real SharePoint farm is unchanged.
-
-### CI
-
-- Workflows adapted to the `src/` layout (`paths`, PSScriptAnalyzer targets, release ZIP of `src/` contents).
-- Deprecated GitHub Actions bumped: `actions/checkout@v4` -> `v7`, `actions/upload-artifact@v4` -> `v7`, `softprops/action-gh-release@v2` -> `v3`.
+- **Results history** — the audit no longer overwrites its output blindly. Before each run the current `Results\<FileName>.json` is archived into `Results\history\` with a `yyyyMMdd-HHmm` timestamp:
+  - `Backup-SPSJsonFile` (public) creates the timestamped copy.
+  - `Clear-SPSLogFolder` (public) is the single retention/rotation implementation, reused for both transcript logs (`*.log`) and archived snapshots (`*.json`). `Retention = 0` disables pruning.
+- **HTML report** — `Export-SPSCleanDependenciesReport` (public) renders the results JSON as a self-contained, dependency-free HTML file: one summary card per dependency category plus a filterable/sortable table per non-empty category, or a clean "nothing to clean" state. Backed by internal helpers `ConvertTo-SPSHtmlEncoded`, `Get-SPSReportHtmlHead`, `Get-SPSReportCardHtml`, `Get-SPSReportHtmlScript` (pattern from SPSUpdate.Common).
+- **Entry script** — the audit run now archives the previous results, writes `Results\<FileName>.html`, and prunes old history/logs. The current `Results\<FileName>.json` stays stable (still the exact input consumed by `-Clean`); only the history copies are timestamped. New `-HistoryRetentionDays` (default 30) and `-LogRetentionDays` (default 180) parameters control retention; `0` disables pruning.
+- Pester coverage for the new functions and the audit-branch wiring.
 
 A full list of changes in each version can be found in the [change log](CHANGELOG.md)
diff --git a/wiki/Dependency-Types.md b/wiki/Dependency-Types.md
index ccf5f7b..cefdc1d 100644
--- a/wiki/Dependency-Types.md
+++ b/wiki/Dependency-Types.md
@@ -94,4 +94,5 @@ In audit mode the results file (`Results\<FileName>.json`) is a single object wh
 ## See also
 
 - [Usage](Usage)
+- [Reports & History](Reports-and-History)
 - [Troubleshooting](Troubleshooting)
diff --git a/wiki/Home.md b/wiki/Home.md
index 1e6f4e4..9c0e6c6 100644
--- a/wiki/Home.md
+++ b/wiki/Home.md
@@ -17,6 +17,9 @@ SPSCleanDependencies is a PowerShell script tool to clean Missing Server Depende
 - Logging:
   - Creates a log file in the Logs folder with a timestamped filename.
   - Outputs script metadata, including version, start time, and PowerShell version.
+- Results history & report:
+  - Archives the previous `Results\<FileName>.json` into `Results\history\` (timestamped) before each audit, with configurable retention.
+  - Generates a self-contained `Results\<FileName>.html` report summarising the missing dependencies per category.
 
 For details on usage, configuration, and parameters, explore the links below:
 
diff --git a/wiki/Reports-and-History.md b/wiki/Reports-and-History.md
new file mode 100644
index 0000000..fe5b08e
--- /dev/null
+++ b/wiki/Reports-and-History.md
@@ -0,0 +1,53 @@
+# Reports & History
+
+Since v1.4.0 every audit run (SPSCleanDependencies.ps1 without `-Clean`) produces three things next to the script:
+
+```
+Logs/
+  <FileName>_<timestamp>.log        # transcript of the run
+Results/
+  <FileName>.json                   # current results (consumed by -Clean)
+  <FileName>.html                   # human-readable report of this run
+  history/
+    <FileName>-yyyyMMdd-HHmm.json   # timestamped archive of each previous run
+```
+
+## HTML report
+
+`Results\<FileName>.html` is a self-contained, dependency-free HTML file (no CDN — it opens offline on a SharePoint server). It contains:
+
+- A **summary** with one card per dependency category showing how many items were found (green when a category is empty, red when it has items), plus a **Total items** card.
+- For every **non-empty** category, a **filterable and sortable** table of the items with their identifying fields (database, IDs, page, login, …). See [Dependency Types](./Dependency-Types) for the meaning of each category and its fields.
+- A clean **"No missing server side dependencies were found"** state when the farm is clean.
+
+All values coming from the farm are HTML-encoded, so database names, messages and logins cannot break the report layout.
+
+> [!TIP]
+> The report is a convenience view of `Results\<FileName>.json`. The JSON remains the exact input consumed by the `-Clean` run — always review it (and back up your content databases) before cleaning.
+
+## Results history
+
+Before each audit overwrites `Results\<FileName>.json`, the previous file is copied into `Results\history\` with a `yyyyMMdd-HHmm` timestamp (e.g. `CONTOSO-PROD-SPSE-20260709-1615.json`). This keeps a trail of how the missing-dependency situation evolved over time, without changing the name of the current file.
+
+Only the **history copies** are timestamped; the current `Results\<FileName>.json` and `Results\<FileName>.html` keep their stable names so `-Clean` and any downstream tooling always find the latest run.
+
+## Retention
+
+Old files are pruned automatically at the end of each audit run:
+
+| What | Parameter | Default | Disable |
+|---|---|---|---|
+| History snapshots (`Results\history\*.json`) | `-HistoryRetentionDays` | 30 days | `0` |
+| Transcript logs (`Logs\*.log`) | `-LogRetentionDays` | 180 days | `0` |
+
+Example — keep 90 days of history and never prune logs:
+
+```powershell
+.\SPSCleanDependencies.ps1 -FileName 'CONTOSO-PROD-SPSE' -HistoryRetentionDays 90 -LogRetentionDays 0
+```
+
+## See also
+
+- [Usage](./Usage)
+- [Dependency Types](./Dependency-Types)
+- [Troubleshooting](./Troubleshooting)
diff --git a/wiki/Usage.md b/wiki/Usage.md
index df32808..85f3ee2 100644
--- a/wiki/Usage.md
+++ b/wiki/Usage.md
@@ -6,6 +6,8 @@
 | ----------- | -------------------------------------------------- |
 | `FileName` | Specifies the name of the configuration json file. |
 | `Clean`    | Remove missing server side dependencies            |
+| `HistoryRetentionDays` | Days of archived result snapshots to keep in `Results\history` (default 30; `0` disables pruning). |
+| `LogRetentionDays` | Days of transcript logs to keep in `Logs` (default 180; `0` disables pruning). |
 
 ### Basic Usage Example
 
@@ -28,5 +30,6 @@ Remove missing server side dependencies on SharePoint farm:
 
 ## Next Steps
 
+- [Reports & History](./Reports-and-History) — the generated HTML report and the timestamped results history.
 - [Dependency Types](./Dependency-Types) — the categories detected and cleaned, and the results JSON shape.
 - [Troubleshooting](./Troubleshooting) — common issues and how to resolve them.
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index 6a9a516..ae48d0c 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -4,6 +4,7 @@
 - [🚀 Getting Started](Getting-Started)
 - [📖 Usage](Usage)
 - [🧩 Dependency Types](Dependency-Types)
+- [📊 Reports & History](Reports-and-History)
 - [🛠️ Troubleshooting](Troubleshooting)
 - [📦 Release Process](Release-Process)