Convert landings and products directories JavaScript files to TypeScript (#55560)

Author: heiskr

src/events/lib/schema.ts

@@ -1,6 +1,6 @@
 import { languageKeys } from '#src/languages/lib/languages.js'
 import { allVersionKeys } from '#src/versions/lib/all-versions.js'
-import { productIds } from '#src/products/lib/all-products.js'
+import { productIds } from '#src/products/lib/all-products.ts'
 import { allTools } from 'src/tools/lib/all-tools.js'
 
 const versionPattern = '^\\d+(\\.\\d+)?(\\.\\d+)?$' // eslint-disable-line

src/frame/lib/get-toc-items.js

@@ -1,4 +1,4 @@
-import { productMap } from '#src/products/lib/all-products.js'
+import { productMap } from '#src/products/lib/all-products.ts'
 const productTOCs = Object.values(productMap)
   .filter((product) => !product.external)
   .map((product) => product.toc.replace('content/', ''))

src/frame/lib/page.js

@@ -9,7 +9,7 @@ import getTocItems from './get-toc-items.js'
 import Permalink from './permalink.js'
 import { renderContent } from '#src/content-render/index.js'
 import processLearningTracks from '#src/learning-track/lib/process-learning-tracks.js'
-import { productMap } from '#src/products/lib/all-products.js'
+import { productMap } from '#src/products/lib/all-products.ts'
 import slash from 'slash'
 import readFileContents from './read-file-contents.js'
 import getLinkData from '#src/learning-track/lib/get-link-data.js'

src/frame/lib/path-utils.js

@@ -2,7 +2,7 @@ import slash from 'slash'
 import path from 'path'
 import patterns from './patterns.js'
 import { latest } from '#src/versions/lib/enterprise-server-releases.js'
-import { productIds } from '#src/products/lib/all-products.js'
+import { productIds } from '#src/products/lib/all-products.ts'
 import { allVersions } from '#src/versions/lib/all-versions.js'
 import nonEnterpriseDefaultVersion from '#src/versions/lib/non-enterprise-default-version.js'
 const supportedVersions = new Set(Object.keys(allVersions))

src/landings/tests/curated-homepage-links.js renamed to src/landings/tests/curated-homepage-links.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test, vi } from 'vitest'
+import cheerio from 'cheerio'
 
 import { getDOM } from '#src/tests/helpers/e2etest.js'
 
@@ -11,8 +12,8 @@ describe('curated homepage links', () => {
     expect($links.length).toBeGreaterThanOrEqual(6)
 
     // Check that each link is localized and includes a title and intro
-    $links.each((i, el) => {
-      const linkUrl = $(el).attr('href')
+    $links.each((i: number, el: cheerio.Element) => {
+      const linkUrl = $(el).attr('href') as string
 
       expect(linkUrl.startsWith('/en/')).toBe(true)
       expect(

src/landings/tests/homepage.js renamed to src/landings/tests/homepage.ts

@@ -0,0 +1,85 @@
+import fs from 'fs/promises'
+import path from 'path'
+import frontmatter from '#src/frame/lib/read-frontmatter.js'
+import getApplicableVersions from '#src/versions/lib/get-applicable-versions.js'
+import removeFPTFromPath from '#src/versions/lib/remove-fpt-from-path.js'
+import { ROOT } from '#src/frame/lib/constants.js'
+
+/**
+ * Represents a product in the documentation
+ */
+export interface Product {
+  /** Unique identifier for the product */
+  id: string
+  /** Display name of the product (short title or title) */
+  name: string
+  /** URL path to the product's landing page */
+  href: string
+  /** Directory path to the product's content */
+  dir: string
+  /** Path to the product's table of contents file */
+  toc: string
+  /** Whether the product is a work in progress */
+  wip: boolean
+  /** Whether the product is hidden from the UI */
+  hidden: boolean
+  /** Applicable versions for the product */
+  versions: string[]
+  /** Rendered name (added later by middleware) */
+  nameRendered?: string
+  /** Whether the product is external */
+  external?: boolean
+}
+
+/**
+ * Map of product IDs to their corresponding product data
+ */
+export interface ProductMap {
+  [productId: string]: Product
+}
+
+// Both internal and external products are specified in content/index.md
+const homepage = path.posix.join(ROOT, 'content/index.md')
+export const { data } = frontmatter(await fs.readFile(homepage, 'utf8'))
+
+export const productIds: string[] = data?.children || []
+
+const externalProducts = (data?.externalProducts || {}) as ProductMap
+const internalProducts: ProductMap = {}
+
+for (const productId of productIds) {
+  const relPath = productId
+  const dir = path.join(ROOT, 'content', relPath)
+
+  // Early Access may not exist in the current checkout
+  try {
+    await fs.readdir(dir)
+  } catch {
+    continue
+  }
+
+  const toc = path.posix.join(dir, 'index.md')
+  const fileContent = await fs.readFile(toc, 'utf8')
+  const { data: tocData } = frontmatter(fileContent)
+  if (tocData) {
+    const applicableVersions = getApplicableVersions(tocData.versions, toc)
+    const href = removeFPTFromPath(path.posix.join('/', applicableVersions[0], productId))
+
+    // Note that a special middleware called `render-product-map.js` later
+    // mutates this object by adding a `nameRendered` property to each product.
+    // It's the outcome of rendering out possible Liquid from the
+    // `shortTitle` or `title` after all the other contextualizers have run.
+    internalProducts[productId] = {
+      id: productId,
+      name: tocData.shortTitle || tocData.title || productId,
+      href,
+      dir,
+      toc,
+      wip: tocData.wip || false,
+      hidden: tocData.hidden || false,
+      versions: applicableVersions,
+    }
+  }
+}
+
+export const productMap: ProductMap = Object.assign({}, internalProducts, externalProducts)

src/products/lib/all-products.js

@@ -86,20 +86,30 @@ async function getPage(
   }
 }
 
+interface ProductGroupData {
+  name: string
+  icon?: string
+  octicon?: string
+  children: string[]
+}
+
 export async function getProductGroups(
   pageMap: PageMap,
   lang: string,
   context: Context,
 ): Promise<ProductGroup[]> {
+  // Handle case where data or childGroups might be undefined
+  const childGroups = data?.childGroups || []
+
   return await Promise.all(
-    data.childGroups!.map(async (group) => {
+    childGroups.map(async (group: ProductGroupData) => {
       return {
         name: group.name,
         icon: group.icon || null,
         octicon: group.octicon || null,
         // Typically the children are product IDs, but we support deeper page paths too
         children: (
-          await Promise.all(group.children.map((id) => getPage(id, lang, pageMap, context)))
+          await Promise.all(group.children.map((id: string) => getPage(id, lang, pageMap, context)))
         ).filter(Boolean) as ProductGroupChild[],
       }
     }),

src/products/lib/all-products.ts

@@ -1,8 +1,9 @@
 import { describe, expect, test } from 'vitest'
 
 import { getJsonValidator } from '#src/tests/lib/validate-json-schema.js'
-import { productMap } from '#src/products/lib/all-products.js'
+import { productMap } from '#src/products/lib/all-products.ts'
 import { formatAjvErrors } from '#src/tests/helpers/schemas.js'
+// @ts-ignore - Products schema doesn't have TypeScript types yet
 import schema from '#src/tests/helpers/schemas/products-schema.js'
 
 const validate = getJsonValidator(schema)
@@ -16,9 +17,9 @@ describe('products module', () => {
   test('every product is valid', () => {
     Object.values(productMap).forEach((product) => {
       const isValid = validate(product)
-      let errors
+      let errors: string | undefined
 
-      if (!isValid) {
+      if (!isValid && validate.errors) {
         errors = formatAjvErrors(validate.errors)
       }
       expect(isValid, errors).toBe(true)