Repair release bundle guide links and explain VS Code installation

Author: Elektryk-Andrzej

VS Code Extension/README.md

@@ -30,13 +30,25 @@ Start with the
 or run `serhelp start` on a server to locate the active script directory and
 see the first-run workflow.
 
-This extension is maintained together with the main SER repository. SER's build
-regenerates the reflection-backed language manifest. The shared tooling build
-then produces the extension, visual-editor webview and standalone editor from
-that same manifest and shared language core.
+## Install
 
-The maintainable extension source is in `src`. Files in `out` are synchronized
-build artifacts used by VS Code.
+If you downloaded a SER release, install the extension from its `.vsix` file:
+
+1. Find `ser-<version>.vsix` in the release files. The Complete zip also has it
+   in its `VS Code Extension` folder.
+2. In VS Code, open **Extensions**, select the **...** menu, choose
+   **Install from VSIX...**, and pick the file. You can also run
+   `code --install-extension ser-<version>.vsix` in a terminal.
+3. Reload VS Code if it asks.
+
+## Build from source
+
+This extension is maintained together with the main SER repository. The
+extension, its Blocks editor and the standalone Blocks editor are all built
+from the same SER language data that the plugin's build creates.
+
+The editable source is in `src`. Files in `out` are generated from it and are
+what VS Code loads, so do not edit them by hand.
 
 From the repository's `Tooling` directory:
 
@@ -45,10 +57,25 @@ npm install
 npm run verify
 ```
 
-If the tooling dependencies are installed, the normal SER build runs this
-synchronization automatically before copying the extension to
-`%USERPROFILE%\\.vscode\\extensions\\ser`.
+Once these dependencies are installed, each SER build also refreshes the
+extension files in this folder.
+
+### Building does not install the extension
+
+A normal SER build only refreshes the extension files in this folder. It does
+not change the extension your VS Code uses.
+
+To also copy the extension into VS Code during the build, add
+`/p:InstallSerExtensionAfterBuild=true`:
+
+```powershell
+dotnet build SER.csproj -c Release --no-restore /p:InstallSerExtensionAfterBuild=true
+```
+
+This copies the extension to `%USERPROFILE%\.vscode\extensions\ser`. Reload
+VS Code afterwards to use the new version.
 
-To use a different installed-extension path, pass
-`/p:SerExtensionInstallDirectory="C:\\path\\to\\.vscode\\extensions\\ser"`
-to MSBuild.
+To copy it somewhere else, such as a VS Code Insiders profile, also pass
+`/p:SerExtensionInstallDirectory="C:\path\to\.vscode\extensions\ser"`. This
+setting only changes the destination. On its own, without
+`/p:InstallSerExtensionAfterBuild=true`, it copies nothing.

tools/package-release.ps1

@@ -35,13 +35,145 @@ function Invoke-CheckedCommand {
     }
 }
 
+# Online fallbacks for links whose target is not shipped in a bundle.
+$onlineDocsBaseUrl = 'https://scriptedevents.github.io/ScriptedEventsReloaded/'
+$repositoryWebUrl = 'https://github.com/ScriptedEvents/ScriptedEventsReloaded'
+$repositoryRawUrl = 'https://raw.githubusercontent.com/ScriptedEvents/ScriptedEventsReloaded/main'
+$markdownLinkPattern = '(?<prefix>\]\(|\bsrc=")(?<target>[^)"\s]+)(?<suffix>[)"])'
+
+function ConvertTo-UrlPath {
+    param([Parameter(Mandatory)] [AllowEmptyString()] [string]$RelativePath)
+
+    (($RelativePath -split '[\\/]') | ForEach-Object { [System.Uri]::EscapeDataString($_) }) -join '/'
+}
+
+function Test-IsRelativeLinkTarget {
+    param([Parameter(Mandatory)] [string]$Target)
+
+    # Skip web/mail links, in-page anchors and site-root paths.
+    return -not ($Target -match '^(?:[a-zA-Z][a-zA-Z0-9+.-]*:|#|/)')
+}
+
+function Split-LinkTarget {
+    param([Parameter(Mandatory)] [string]$Target)
+
+    $hashIndex = $Target.IndexOf('#')
+    if ($hashIndex -lt 0) {
+        return @([System.Uri]::UnescapeDataString($Target), '')
+    }
+    return @([System.Uri]::UnescapeDataString($Target.Substring(0, $hashIndex)), $Target.Substring($hashIndex))
+}
+
+function Get-OnlineLinkTarget {
+    param(
+        [Parameter(Mandatory)] [string]$RepositoryRelativePath,
+        [switch]$RawFile
+    )
+
+    $path = $RepositoryRelativePath -replace '\\', '/'
+    if ($path -match '^docs/(?<page>.+)\.md$') {
+        $page = $Matches['page']
+        if ($page -eq 'README') {
+            return $onlineDocsBaseUrl
+        }
+        if ($page.EndsWith('/README')) {
+            $page = $page.Substring(0, $page.Length - 'README'.Length)
+        }
+        return $onlineDocsBaseUrl + (ConvertTo-UrlPath $page)
+    }
+    if ($RawFile) {
+        return "$repositoryRawUrl/$(ConvertTo-UrlPath $path)"
+    }
+    $kind = if (Test-Path -LiteralPath (Join-Path $repositoryDirectory $path) -PathType Container) { 'tree' } else { 'blob' }
+    return "$repositoryWebUrl/$kind/main/$(ConvertTo-UrlPath $path)"
+}
+
+# Copies a repository Markdown file to the root of a bundle. Relative links are
+# pointed at the matching file inside that bundle when it is shipped there, and
+# at the online documentation or GitHub repository when it is not.
+function Copy-MarkdownToBundleRoot {
+    param(
+        [Parameter(Mandatory)] [string]$RepositoryRelativePath,
+        [Parameter(Mandatory)] [string]$BundleRoot
+    )
+
+    $sourceFile = Join-Path $repositoryDirectory $RepositoryRelativePath
+    $sourceDirectory = Split-Path -Parent $sourceFile
+    $repositoryPrefix = $repositoryDirectory.TrimEnd('\', '/') + [System.IO.Path]::DirectorySeparatorChar
+    $content = [System.IO.File]::ReadAllText($sourceFile)
+    $output = New-Object System.Text.StringBuilder
+    $position = 0
+
+    foreach ($match in [regex]::Matches($content, $markdownLinkPattern)) {
+        $target = $match.Groups['target'].Value
+        $newTarget = $target
+        if (Test-IsRelativeLinkTarget $target) {
+            $pathPart, $anchor = Split-LinkTarget $target
+            $fullPath = [System.IO.Path]::GetFullPath((Join-Path $sourceDirectory $pathPart))
+            if (-not $fullPath.StartsWith($repositoryPrefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+                throw "$RepositoryRelativePath links outside the repository: $target"
+            }
+            $relativeTarget = $fullPath.Substring($repositoryPrefix.Length).TrimEnd('\', '/')
+            if (Test-Path -LiteralPath (Join-Path $BundleRoot $relativeTarget)) {
+                $newTarget = (ConvertTo-UrlPath $relativeTarget) + $anchor
+            }
+            else {
+                $isImage = $match.Groups['prefix'].Value -ne ']('
+                $newTarget = (Get-OnlineLinkTarget -RepositoryRelativePath $relativeTarget -RawFile:$isImage) + $anchor
+            }
+        }
+
+        $targetGroup = $match.Groups['target']
+        [void]$output.Append($content, $position, $targetGroup.Index - $position)
+        [void]$output.Append($newTarget)
+        $position = $targetGroup.Index + $targetGroup.Length
+    }
+    [void]$output.Append($content, $position, $content.Length - $position)
+
+    $destination = Join-Path $BundleRoot (Split-Path -Leaf $sourceFile)
+    [System.IO.File]::WriteAllText($destination, $output.ToString(), (New-Object System.Text.UTF8Encoding($false)))
+}
+
+# Fails the release if any Markdown file in a bundle links to a local file that
+# is missing from that bundle.
+function Assert-BundleMarkdownLinks {
+    param([Parameter(Mandatory)] [string]$BundleRoot)
+
+    $bundlePrefix = [System.IO.Path]::GetFullPath($BundleRoot).TrimEnd('\', '/') + [System.IO.Path]::DirectorySeparatorChar
+    $brokenLinks = New-Object System.Collections.Generic.List[string]
+    foreach ($file in Get-ChildItem -LiteralPath $BundleRoot -Filter '*.md' -File -Recurse) {
+        $content = [System.IO.File]::ReadAllText($file.FullName)
+        foreach ($match in [regex]::Matches($content, $markdownLinkPattern)) {
+            $target = $match.Groups['target'].Value
+            if (-not (Test-IsRelativeLinkTarget $target)) {
+                continue
+            }
+            $pathPart = (Split-LinkTarget $target)[0]
+            if ($pathPart.Length -eq 0) {
+                continue
+            }
+            $fullPath = [System.IO.Path]::GetFullPath((Join-Path $file.DirectoryName $pathPart))
+            if (-not $fullPath.StartsWith($bundlePrefix, [System.StringComparison]::OrdinalIgnoreCase) -or
+                -not (Test-Path -LiteralPath $fullPath)) {
+                $brokenLinks.Add("$($file.FullName.Substring($bundlePrefix.Length)): $target")
+            }
+        }
+    }
+
+    if ($brokenLinks.Count -gt 0) {
+        throw "Bundle $BundleRoot has links to files it does not contain:`n$($brokenLinks -join "`n")"
+    }
+}
+
 function Copy-ReleaseNotices {
     param([Parameter(Mandatory)] [string]$Destination)
 
     Copy-Item -LiteralPath (Join-Path $repositoryDirectory 'LICENSE') -Destination $Destination
     Copy-Item -LiteralPath (Join-Path $repositoryDirectory 'THIRD_PARTY_LICENSES.txt') -Destination $Destination
-    Copy-Item -LiteralPath (Join-Path $repositoryDirectory 'README.md') -Destination $Destination
-    Copy-Item -LiteralPath (Join-Path $repositoryDirectory 'docs\getting-started\installation.md') -Destination $Destination
+    # Copy these last, after the bundle's other content, so their links can be
+    # pointed at files that are actually in the bundle.
+    Copy-MarkdownToBundleRoot -RepositoryRelativePath 'README.md' -BundleRoot $Destination
+    Copy-MarkdownToBundleRoot -RepositoryRelativePath 'docs\getting-started\installation.md' -BundleRoot $Destination
 }
 
 function Compress-ReleaseDirectory {
@@ -123,6 +255,10 @@ $vsixPath = Join-Path $releaseDirectory "ser-$extensionVersion.vsix"
 Invoke-CheckedCommand -FilePath 'npm' -Arguments @('run', 'package', '--', '--out', $vsixPath) -WorkingDirectory $extensionDirectory
 Copy-Item -LiteralPath $vsixPath -Destination (Join-Path $completeStage 'VS Code Extension')
 
+foreach ($stage in @($learningStage, $editorStage, $completeStage)) {
+    Assert-BundleMarkdownLinks -BundleRoot $stage
+}
+
 Compress-ReleaseDirectory -Source $learningStage -Destination (Join-Path $releaseDirectory "SER-$coreVersion-Examples-and-Documentation.zip")
 Compress-ReleaseDirectory -Source $editorStage -Destination (Join-Path $releaseDirectory "SER-Visual-Editor-$coreVersion.zip")
 Compress-ReleaseDirectory -Source $completeStage -Destination (Join-Path $releaseDirectory "SER-$coreVersion-Complete.zip")