Migrate TypeScript: 9 files converted (#57928)

Author: heiskr

src/content-linter/lib/helpers/liquid-utils.js renamed to src/content-linter/lib/helpers/liquid-utils.ts

@@ -2,9 +2,19 @@ import { Tokenizer, TokenKind } from 'liquidjs'
 
 import { deprecated } from '@/versions/lib/enterprise-server-releases'
 
-const liquidTokenCache = new Map()
-
-export function getLiquidTokens(content, { noCache = false } = {}) {
+// Using `any` for the cache because TopLevelToken is a complex union type from liquidjs
+// that includes TagToken, OutputToken, and HTMLToken with different properties.
+// The cache is private to this module and we control all access to it.
+const liquidTokenCache = new Map<string, any>()
+
+// Returns `any[]` instead of `TopLevelToken[]` because TopLevelToken is a union type
+// (TagToken | OutputToken | HTMLToken) and consumers of this function access properties
+// like `name` and `args` that only exist on TagToken. Using `any` here avoids complex
+// type narrowing throughout the codebase.
+export function getLiquidTokens(
+  content: string,
+  { noCache = false }: { noCache?: boolean } = {},
+): any[] {
   if (!content) return []
 
   if (noCache) {
@@ -30,7 +40,12 @@ export const TAG_CLOSE = '}}'
 export const conditionalTags = ['if', 'elseif', 'unless', 'case', 'ifversion']
 const CONDITIONAL_TAG_NAMES = ['if', 'ifversion', 'elsif', 'else', 'endif']
 
-export function getPositionData(token, lines) {
+// Token is `any` because it's used with different token types from liquidjs
+// that all have `begin` and `end` properties but are part of complex union types.
+export function getPositionData(
+  token: any,
+  lines: string[],
+): { lineNumber: number; column: number; length: number } {
   // Liquid indexes are 0-based, but we want to
   // covert to the system used by Markdownlint
   const begin = token.begin + 1
@@ -62,9 +77,14 @@ export function getPositionData(token, lines) {
  * by Markdownlint:
  * [ { lineNumber: 1, column: 1, deleteCount: 3, }]
  */
-export function getContentDeleteData(token, tokenEnd, lines) {
+// Token is `any` because it's used with different token types from liquidjs.
+export function getContentDeleteData(
+  token: any,
+  tokenEnd: number,
+  lines: string[],
+): Array<{ lineNumber: number; column: number; deleteCount: number }> {
   const { lineNumber, column } = getPositionData(token, lines)
-  const errorInfo = []
+  const errorInfo: Array<{ lineNumber: number; column: number; deleteCount: number }> = []
   let begin = column - 1
   // Subtract one from end of next token tag. The end of the
   // current tag is one position before that.
@@ -103,13 +123,15 @@ export function getContentDeleteData(token, tokenEnd, lines) {
 // related elsif, else, and endif tags).
 // Docs doesn't use the standard `if` tag for versioning, instead the
 // `ifversion` tag is used.
-export function getLiquidIfVersionTokens(content) {
+// Returns `any[]` because the tokens need to be accessed as TagToken with `name` and `args` properties,
+// but TopLevelToken union type would require complex type narrowing.
+export function getLiquidIfVersionTokens(content: string): any[] {
   const tokens = getLiquidTokens(content)
     .filter((token) => token.kind === TokenKind.Tag)
     .filter((token) => CONDITIONAL_TAG_NAMES.includes(token.name))
 
   let inIfStatement = false
-  const ifVersionTokens = []
+  const ifVersionTokens: any[] = []
   for (const token of tokens) {
     if (token.name === 'if') {
       inIfStatement = true
@@ -125,7 +147,7 @@ export function getLiquidIfVersionTokens(content) {
   return ifVersionTokens
 }
 
-export function getSimplifiedSemverRange(release) {
+export function getSimplifiedSemverRange(release: string): string {
   // Liquid conditionals only use the format > or < but not
   // >= or <=. Not sure exactly why.
   // if startswith >, we'll check to see if the release number

src/content-linter/style/base.js renamed to src/content-linter/style/base.ts

@@ -2,10 +2,21 @@ import fs from 'fs'
 import yaml from 'js-yaml'
 
 const allowedCodeFenceLanguages = Object.keys(
-  yaml.load(fs.readFileSync('data/code-languages.yml', 'utf8')),
+  yaml.load(fs.readFileSync('data/code-languages.yml', 'utf8')) as Record<string, unknown>,
 )
 
-export const baseConfig = {
+type RuleConfig = {
+  severity: 'error' | 'warning'
+  'partial-markdown-files': boolean
+  'yml-files': boolean
+  [key: string]: any
+}
+
+type BaseConfig = {
+  [key: string]: boolean | RuleConfig
+}
+
+export const baseConfig: BaseConfig = {
   // Don't run all rules by default. This must be done first to
   // enable a specific set of rules.
   default: false,

src/content-linter/tests/unit/expired-content.js renamed to src/content-linter/tests/unit/expired-content.ts

@@ -47,7 +47,7 @@ function getDeletedContentFiles() {
   return getContentFiles(process.env.DELETED_FILES)
 }
 
-function getContentFiles(spaceSeparatedList) {
+function getContentFiles(spaceSeparatedList: string | undefined): string[] {
   return (spaceSeparatedList || '').split(/\s+/g).filter((filePath) => {
     // This filters out things like '', or `data/foo.md` or `content/something/README.md`
     return (
@@ -69,23 +69,25 @@ describe('changed-content', () => {
 
   // `test.each` will throw if the array is empty, so we need to add a dummy
   // when there are no changed files in the environment.
-  if (!changedContentFiles.length) changedContentFiles.push(EMPTY)
+  const testFiles: Array<string | symbol> = changedContentFiles.length
+    ? changedContentFiles
+    : [EMPTY]
 
-  test.each(changedContentFiles)('changed-content: %s', async (file) => {
+  test.each(testFiles)('changed-content: %s', async (file: string | symbol) => {
     // Necessary because `test.each` will throw if the array is empty
     if (file === EMPTY) return
 
     const page = pageList.find((p) => {
       return path.join(p.basePath, p.relativePath) === file
     })
     if (!page) {
-      throw new Error(`Could not find page for ${file} in all loaded English content`)
+      throw new Error(`Could not find page for ${file as string} in all loaded English content`)
     }
     // Each version of the page should successfully render
     for (const { href } of page.permalinks) {
       const res = await get(href)
       if (!res.ok) {
-        let msg = `This error happened when rendering from: ${file}\n`
+        let msg = `This error happened when rendering from: ${file as string}\n`
         msg +=
           'To see the full error from vitest re-run the test with DEBUG_MIDDLEWARE_TESTS=true set\n'
         msg += `Or, to view it locally start the server (npm run dev) and visit http://localhost:4000${href}`
@@ -101,30 +103,34 @@ describe('deleted-content', () => {
 
   // `test.each` will throw if the array is empty, so we need to add a dummy
   // when there are no deleted files in the environment.
-  if (!deletedContentFiles.length) deletedContentFiles.push(EMPTY)
+  const testFiles: Array<string | symbol> = deletedContentFiles.length
+    ? deletedContentFiles
+    : [EMPTY]
 
-  test.each(deletedContentFiles)('deleted-content: %s', async (file) => {
+  test.each(testFiles)('deleted-content: %s', async (file: string | symbol) => {
     // Necessary because `test.each` will throw if the array is empty
     if (file === EMPTY) return
 
     const page = pageList.find((p) => {
       return path.join(p.basePath, p.relativePath) === file
     })
     if (page) {
-      throw new Error(`The supposedly deleted file ${file} is still in list of loaded pages`)
+      throw new Error(
+        `The supposedly deleted file ${file as string} is still in list of loaded pages`,
+      )
     }
     // You can't know what the possible permalinks were for a deleted page,
     // because it's deleted so we can't look at its `versions` front matter.
     // However, we always make sure all pages work in versionless.
     const indexmdSuffixRegex = new RegExp(`${path.sep}index\\.md$`)
     const mdSuffixRegex = /\.md$/
-    const relativePath = file.split(path.sep).slice(1).join(path.sep)
+    const relativePath = (file as string).split(path.sep).slice(1).join(path.sep)
     const href = `/en/${relativePath.replace(indexmdSuffixRegex, '').replace(mdSuffixRegex, '')}`
 
     const res = await head(href)
     const error =
       res.statusCode === 404
-        ? `The deleted file ${file} did not set up a redirect when deleted.`
+        ? `The deleted file ${file as string} did not set up a redirect when deleted.`
         : ''
     // Certain articles that are deleted and moved under a directory with the same article name
     // should just route to the subcategory page instead of redirecting (docs content team confirmed).

src/content-linter/tests/unit/frontmatter-landing-recommended.js renamed to src/content-linter/tests/unit/frontmatter-landing-recommended.ts

@@ -9,15 +9,17 @@ const supportedVersions = new Set(Object.keys(allVersions))
 
 // Extracts the language code from the path
 // if href is '/en/something', returns 'en'
-export function getLangFromPath(href) {
+export function getLangFromPath(href: string | undefined): string | null {
+  if (!href) return null
   // first remove the version from the path so we don't match, say, `/free-pro-team` as `/fr/`
   const match = getPathWithoutVersion(href).match(patterns.getLanguageCode)
   return match ? match[1] : null
 }
 
 // Add the language to the given HREF
 // /articles/foo -> /en/articles/foo
-export function getPathWithLanguage(href, languageCode) {
+export function getPathWithLanguage(href: string | undefined, languageCode: string): string {
+  if (!href) return `/${languageCode}`
   return slash(path.posix.join('/', languageCode, getPathWithoutLanguage(href))).replace(
     patterns.trailingSlash,
     '$1',
@@ -26,12 +28,14 @@ export function getPathWithLanguage(href, languageCode) {
 
 // Remove the language from the given HREF
 // /en/articles/foo -> /articles/foo
-export function getPathWithoutLanguage(href) {
+export function getPathWithoutLanguage(href: string | undefined): string {
+  if (!href) return '/'
   return slash(href.replace(patterns.hasLanguageCode, '/'))
 }
 
 // Remove the version segment from the path
-export function getPathWithoutVersion(href) {
+export function getPathWithoutVersion(href: string | undefined): string {
+  if (!href) return '/'
   const versionFromPath = getVersionStringFromPath(href)
 
   // If the derived version is not found in the list of all versions, just return the HREF
@@ -41,7 +45,16 @@ export function getPathWithoutVersion(href) {
 }
 
 // Return the version segment in a path
-export function getVersionStringFromPath(href, supportedOnly = false) {
+export function getVersionStringFromPath(
+  href: string | undefined,
+  supportedOnly: true,
+): string | undefined
+export function getVersionStringFromPath(href: string | undefined, supportedOnly?: false): string
+export function getVersionStringFromPath(
+  href: string | undefined,
+  supportedOnly = false,
+): string | undefined {
+  if (!href) return nonEnterpriseDefaultVersion
   href = getPathWithoutLanguage(href)
 
   // Some URLs don't ever have a version in the URL and it won't be found
@@ -90,15 +103,16 @@ export function getVersionStringFromPath(href, supportedOnly = false) {
 }
 
 // Return the corresponding object for the version segment in a path
-export function getVersionObjectFromPath(href) {
-  const versionFromPath = getVersionStringFromPath(href)
+export function getVersionObjectFromPath(href: string | undefined) {
+  const versionFromPath = getVersionStringFromPath(href, false)
 
   return allVersions[versionFromPath]
 }
 
 // TODO needs refactoring + tests
 // Return the product segment from the path
-export function getProductStringFromPath(href) {
+export function getProductStringFromPath(href: string | undefined): string {
+  if (!href) return 'homepage'
   href = getPathWithoutLanguage(href)
 
   if (href === '/') return 'homepage'
@@ -124,14 +138,15 @@ export function getProductStringFromPath(href) {
   return productString
 }
 
-export function getCategoryStringFromPath(href) {
+export function getCategoryStringFromPath(href: string | undefined): string | undefined {
+  if (!href) return undefined
   href = getPathWithoutLanguage(href)
 
-  if (href === '/') return null
+  if (href === '/') return undefined
 
   const pathParts = href.split('/')
 
-  if (pathParts.includes('early-access')) return null
+  if (pathParts.includes('early-access')) return undefined
 
   const productIndex = productIds.includes(pathParts[2]) ? 2 : 1