Docs onboarding v2 (Azure#26682)

Requires eng/common changes in
Azure/azure-sdk-tools#6632.
Note: There's also a cleanup
[PR](Azure/azure-sdk-tools#6800) to cleanup
older language specific items.

Test run of
docindex:https://dev.azure.com/azure-sdk/internal/_build/results?buildId=2970911&view=logs&j=dc056dfc-c0cf-5958-c8c4-8da4f91a3739

Converts a collection of metadata JSON files into an onboarding spec.

Author: danieljurek

eng/scripts/Language-Settings.ps1

@@ -232,10 +232,11 @@ function ValidatePackagesForDocs($packages, $DocValidationImageId) {
 
   $scriptRoot = $PSScriptRoot
   # Run this in parallel as each step takes a long time to run
-  $validationOutput = $packages | Foreach-Object -Parallel {
+  $validationOutput = $packages | ForEach-Object { [PSCustomObject]$_ } | Foreach-Object -Parallel {
     # Get value for variables outside of the Foreach-Object scope
     $scriptRoot = "$using:scriptRoot"
     $workingDirectory = "$using:tempDirectory"
+    Write-Host "`"$scriptRoot\validate-docs-package.ps1`" -Package $_ -DocValidationImageId `"$($using:DocValidationImageId)`" -WorkingDirectory $workingDirectory"
     return ."$scriptRoot\validate-docs-package.ps1" -Package $_ -DocValidationImageId "$using:DocValidationImageId" -WorkingDirectory $workingDirectory 
   }
 

eng/scripts/docs/Docs-Onboarding.ps1

@@ -0,0 +1,78 @@
+. "$PSScriptRoot/Docs-ToC.ps1"
+
+# $SetDocsPackageOnboarding = "Set-${Language}-DocsPackageOnboarding"
+function Set-javascript-DocsPackageOnboarding($moniker, $metadata, $docRepoLocation, $packageSourceOverride) {
+  $onboardingFile = GetOnboardingFile `
+    -docRepoLocation $docRepoLocation `
+    -moniker $moniker
+
+  $onboardingSpec = Get-Content $onboardingFile -Raw | ConvertFrom-Json -AsHashtable
+
+  $packagesToOnboard = @()
+  foreach ($package in $metadata) { 
+    $packageSpec = [ordered]@{
+      name = Get-DocsMsPackageName `
+        -packageName $package.Name `
+        -packageVersion $package.Version
+    }
+
+    # $packageSourceOverride is irrelevant here as preview packages are 
+    # published up to NPM directly as alpha versions. The version from the 
+    # package metadata is sufficient.
+
+    # Merge properties from from overrides, duplicate keys will be overwritten
+    if ($package.ContainsKey('DocsCiConfigProperties')) {
+      $overrides = $package['DocsCiConfigProperties']
+      foreach ($key in $overrides.Keys) { 
+        $packageSpec[$key] = $overrides[$key]
+      }
+    }
+
+    $packagesToOnboard += $packageSpec
+  }
+
+  $onboardingSpec['npm_package_sources'] = $packagesToOnboard
+
+  Set-Content `
+    -Path $onboardingFile `
+    -Value ($onboardingSpec | ConvertTo-Json -Depth 100)
+}
+
+function GetPackageInfoFromDocsMsConfig($packageName) {
+  if (!$packageName) { 
+    throw "Package name must not be empty"
+  }
+
+  $name = $packageName
+  $version = ''
+  if ($packageName.IndexOf('@', 1) -ne -1) {
+    $secondAtIndex = $packageName.IndexOf('@', 1)
+
+    # "@azure/package@1.2.3" -> "@azure/package"
+    $name = $packageName.Substring(0, $secondAtIndex)
+
+    # "@azure/package@1.2.3" -> "1.2.3"
+    $version = $packageName.Substring($secondAtIndex + 1)
+  }
+
+  return @{
+    Name    = $name
+    Version = $version
+  }
+}
+
+# $GetDocsPackagesAlreadyOnboarded = "Get-${Language}-DocsPackagesAlreadyOnboarded"
+function Get-javascript-DocsPackagesAlreadyOnboarded($docRepoLocation, $moniker) {
+  $packageOnboardingFile = GetOnboardingFile `
+    -docRepoLocation $DocRepoLocation `
+    -moniker $moniker
+  
+  $onboardedPackages = @{}
+  $onboardingSpec = ConvertFrom-Json (Get-Content $packageOnboardingFile -Raw)
+  foreach ($spec in $onboardingSpec.npm_package_sources) {
+    $packageInfo = GetPackageInfoFromDocsMsConfig $spec.name
+    $onboardedPackages[$packageInfo.Name] = $packageInfo
+  }
+
+  return $onboardedPackages
+}

eng/scripts/docs/Docs-ToC.ps1

@@ -1,3 +1,15 @@
+function GetOnboardingFile($docRepoLocation, $moniker) { 
+  $packageOnboardingFile = "$docRepoLocation/ci-configs/packages-latest.json"
+  if ("preview" -eq $moniker) {
+    $packageOnboardingFile = "$docRepoLocation/ci-configs/packages-preview.json"
+  }
+  elseif ("legacy" -eq $moniker) { 
+    $packageOnboardingFile = "$docRepoLocation/ci-configs/packages-legacy.json"
+  }
+
+  return $packageOnboardingFile
+}
+
 function Get-javascript-OnboardedDocsMsPackages($DocRepoLocation) {
   $packageOnboardingFiles = @(
     "$DocRepoLocation/ci-configs/packages-latest.json",
@@ -21,14 +33,10 @@ function Get-javascript-OnboardedDocsMsPackages($DocRepoLocation) {
 }
 
 function Get-javascript-OnboardedDocsMsPackagesForMoniker($DocRepoLocation, $moniker) {
-  $packageOnboardingFile = ""
-  if ("latest" -eq $moniker) {
-    $packageOnboardingFile = "$DocRepoLocation/ci-configs/packages-latest.json"
-  }
-  if ("preview" -eq $moniker) {
-    $packageOnboardingFile = "$DocRepoLocation/ci-configs/packages-preview.json"
-  }
-
+  $packageOnboardingFile = GetOnboardingFile `
+    -docRepoLocation $DocRepoLocation `
+    -moniker $moniker
+  
   $onboardedPackages = @{}
   $onboardingSpec = ConvertFrom-Json (Get-Content $packageOnboardingFile -Raw)
   foreach ($spec in $onboardingSpec.npm_package_sources) {

eng/scripts/docs/tests/Docs-Onboarding.tests.ps1

@@ -0,0 +1,24 @@
+Import-Module Pester
+
+BeforeAll { 
+  . $PSScriptRoot/../Docs-Onboarding.ps1
+}
+
+Describe 'GetPackageInfoFromDocsMsConfig' { 
+  It 'Returns expected values' -ForEach @(
+    @{ inputValue = '@azure/package@1.2.3'; expectedValue = @{ Name = '@azure/package'; Version = '1.2.3' } },
+    @{ inputValue = '@azure/package'; expectedValue = @{ Name = '@azure/package'; Version = '' } }
+  ) { 
+    $result = GetPackageInfoFromDocsMsConfig $inputValue
+    $result.Name | Should -Be $expectedValue.Name
+    $result.Version | Should -Be $expectedValue.Version
+  }
+
+  It 'Throws when given $null' { 
+    { GetPackageInfoFromDocsMsConfig $null } | Should -Throw
+  }
+
+  It 'Throws when given an empty string' { 
+    { GetPackageInfoFromDocsMsConfig '' } | Should -Throw
+  }
+}