Migrate 18 JavaScript files to TypeScript (#57857)

Author: heiskr

src/content-linter/lib/linting-rules/image-alt-text-end-punctuation.ts

@@ -5,16 +5,16 @@ import {
   isStringQuoted,
   isStringPunctuated,
 } from '../helpers/utils'
-import type { RuleParams, RuleErrorCallback } from '../../types'
+import type { RuleParams, RuleErrorCallback, Rule, MarkdownToken } from '../../types'
 
-export const imageAltTextEndPunctuation = {
+export const imageAltTextEndPunctuation: Rule = {
   names: ['GHD032', 'image-alt-text-end-punctuation'],
   description: 'Alternate text for images should end with punctuation',
   tags: ['accessibility', 'images'],
   parser: 'markdownit',
   function: (params: RuleParams, onError: RuleErrorCallback) => {
-    forEachInlineChild(params, 'image', function forToken(token: any) {
-      const imageAltText = token.content.trim()
+    forEachInlineChild(params, 'image', function forToken(token: MarkdownToken) {
+      const imageAltText = token.content?.trim()
 
       // If the alt text is empty, there is nothing to check and you can't
       // produce a valid range.

src/content-linter/lib/linting-rules/internal-links-old-version.js renamed to src/content-linter/lib/linting-rules/internal-links-old-version.ts

@@ -1,21 +1,24 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't have TypeScript declarations
 import { addError, filterTokens } from 'markdownlint-rule-helpers'
 
 import { getRange } from '../helpers/utils'
+import type { RuleParams, RuleErrorCallback, MarkdownToken, Rule } from '../../types'
 
-export const internalLinksOldVersion = {
+export const internalLinksOldVersion: Rule = {
   names: ['GHD006', 'internal-links-old-version'],
   description: 'Internal links must not have a hardcoded version using old versioning syntax',
   tags: ['links', 'url', 'versioning'],
   parser: 'markdownit',
-  function: (params, onError) => {
-    filterTokens(params, 'inline', (token) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
+    filterTokens(params, 'inline', (token: MarkdownToken) => {
       if (
         params.name.endsWith('migrating-from-github-enterprise-1110x-to-2123.md') ||
         params.name.endsWith('all-releases.md')
       )
         return
-      for (const child of token.children) {
+      for (const child of token.children || []) {
         if (child.type !== 'link_open') continue
+        if (!child.attrs) continue
         // Things matched by this RegExp:
         //  - /enterprise/2.19/admin/blah
         //  - https://docs.github.com/enterprise/11.10.340/admin/blah

src/content-linter/lib/linting-rules/link-quotation.js renamed to src/content-linter/lib/linting-rules/link-quotation.ts

@@ -1,36 +1,41 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't have TypeScript declarations
 import { addError, filterTokens } from 'markdownlint-rule-helpers'
 import { getRange, quotePrecedesLinkOpen } from '../helpers/utils'
 import { escapeRegExp } from 'lodash-es'
+import type { RuleParams, RuleErrorCallback, MarkdownToken, Rule } from '../../types'
 
-export const linkQuotation = {
+export const linkQuotation: Rule = {
   names: ['GHD043', 'link-quotation'],
   description: 'Internal link titles must not be surrounded by quotations',
   tags: ['links', 'url'],
   parser: 'markdownit',
-  function: (params, onError) => {
-    filterTokens(params, 'inline', (token) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
+    filterTokens(params, 'inline', (token: MarkdownToken) => {
       const { children } = token
-      let previous_child = children[0]
+      if (!children) return
+      let previous_child: MarkdownToken = children[0]
       let inLinkWithPrecedingQuotes = false
       let linkUrl = ''
-      let content = []
-      let line = ''
+      let content: string[] = []
       for (let i = 1; i < children.length; i++) {
         const child = children[i]
-        if (child.type === 'link_open' && quotePrecedesLinkOpen(previous_child.content)) {
+        if (child.type === 'link_open' && quotePrecedesLinkOpen(previous_child.content || '')) {
+          if (!child.attrs) continue
           inLinkWithPrecedingQuotes = true
           linkUrl = escapeRegExp(child.attrs[0][1])
-          line = child.line
         } else if (inLinkWithPrecedingQuotes && child.type === 'text') {
-          content.push(escapeRegExp(child.content.trim()))
+          content.push(escapeRegExp((child.content || '').trim()))
         } else if (inLinkWithPrecedingQuotes && child.type === 'code_inline') {
-          content.push('`' + escapeRegExp(child.content.trim()) + '`')
+          content.push('`' + escapeRegExp((child.content || '').trim()) + '`')
         } else if (child.type === 'link_close') {
           const title = content.join(' ')
           const regex = new RegExp(`"\\[${title}\\]\\(${linkUrl}\\)({%.*%})?(!|\\.|\\?|,)?"`)
           if (regex.test(child.line)) {
-            const match = child.line.match(regex)[0]
+            const matchResult = child.line.match(regex)
+            if (!matchResult) continue
+            const match = matchResult[0]
             const range = getRange(child.line, match)
+            if (!range) continue
             let newLine = match
             if (newLine.startsWith('"')) {
               newLine = newLine.slice(1)
@@ -58,7 +63,6 @@ export const linkQuotation = {
           }
           inLinkWithPrecedingQuotes = false
           content = []
-          line = ''
           linkUrl = ''
         }
         previous_child = child

src/content-linter/lib/linting-rules/liquid-tag-whitespace.js renamed to src/content-linter/lib/linting-rules/liquid-tag-whitespace.ts

@@ -2,6 +2,15 @@ import { TokenKind } from 'liquidjs'
 
 import { getLiquidTokens, getPositionData } from '../helpers/liquid-utils'
 import { addFixErrorDetail } from '../helpers/utils'
+import type { RuleParams, RuleErrorCallback, Rule } from '../../types'
+
+interface LiquidToken {
+  kind: number
+  content: string
+  contentRange: [number, number]
+  begin: number
+  end: number
+}
 
 /*
 Liquid tags should start and end with one whitespace. For example:
@@ -16,14 +25,16 @@ Liquid tags should start and end with one whitespace. For example:
   {%data  arg1   arg2  %}
 */
 
-export const liquidTagWhitespace = {
+export const liquidTagWhitespace: Rule = {
   names: ['GHD042', 'liquid-tag-whitespace'],
   description:
     'Liquid tags should start and end with one whitespace. Liquid tag arguments should be separated by only one whitespace.',
   tags: ['liquid', 'format'],
-  function: (params, onError) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
     const content = params.lines.join('\n')
-    const tokens = getLiquidTokens(content).filter((token) => token.kind === TokenKind.Tag)
+    const tokens = (getLiquidTokens(content) as LiquidToken[]).filter(
+      (token: LiquidToken) => token.kind === TokenKind.Tag,
+    )
     for (const token of tokens) {
       const { lineNumber, column, length } = getPositionData(token, params.lines)
 

src/content-linter/lib/linting-rules/list-first-word-capitalization.js renamed to src/content-linter/lib/linting-rules/list-first-word-capitalization.ts

@@ -1,38 +1,40 @@
 import { addFixErrorDetail, getRange, filterTokensByOrder } from '../helpers/utils'
+import type { RuleParams, RuleErrorCallback, MarkdownToken, Rule } from '../../types'
 
-export const listFirstWordCapitalization = {
+export const listFirstWordCapitalization: Rule = {
   names: ['GHD034', 'list-first-word-capitalization'],
   description: 'First word of list item should be capitalized',
   tags: ['ul', 'ol'],
-  function: (params, onError) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
     // Skip site-policy directory as these are legal documents with specific formatting requirements
     if (params.name && params.name.includes('content/site-policy/')) return
 
     // We're going to look for a sequence of 3 tokens. If the markdown
     // is a really small string, it might not even have that many tokens
     // in it. Can bail early.
-    if (params.tokens.length < 3) return
+    if (!params.tokens || params.tokens.length < 3) return
 
     const inlineListItems = filterTokensByOrder(params.tokens, [
       'list_item_open',
       'paragraph_open',
       'inline',
-    ]).filter((token) => token.type === 'inline')
+    ]).filter((token: MarkdownToken) => token.type === 'inline')
 
-    inlineListItems.forEach((token) => {
+    inlineListItems.forEach((token: MarkdownToken) => {
       // Only proceed if all of the token's children start with a text
       // node that is not empty.
       // This filters out cases where the list item is inline code, or
       // a link, or an image, etc.
       // This also avoids cases like `- **bold** text` where the first
       // child is a text node string but the text node content is empty.
       const firstWordTextNode =
+        token.children &&
         token.children.length > 0 &&
         token.children[0].type === 'text' &&
         token.children[0].content !== ''
       if (!firstWordTextNode) return
 
-      const content = token.content.trim()
+      const content = (token.content || '').trim()
       const firstWord = content.trim().split(' ')[0]
 
       // If the first character in the first word is not an alphanumeric,
@@ -49,6 +51,7 @@ export const listFirstWordCapitalization = {
 
       const lineNumber = token.lineNumber
       const range = getRange(token.line, firstWord)
+      if (!range) return
       addFixErrorDetail(
         onError,
         lineNumber,

src/content-linter/lib/linting-rules/rai-reusable-usage.js renamed to src/content-linter/lib/linting-rules/rai-reusable-usage.ts

@@ -1,24 +1,43 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't have TypeScript declarations
 import { addError } from 'markdownlint-rule-helpers'
 import { TokenKind } from 'liquidjs'
 import path from 'path'
 
 import { getFrontmatter } from '../helpers/utils'
 import { getLiquidTokens, getPositionData } from '../helpers/liquid-utils'
+import type { RuleParams, RuleErrorCallback, Rule } from '../../types'
 
-export const raiReusableUsage = {
+interface Frontmatter {
+  type?: string
+  // Allow any additional frontmatter properties since we only care about 'type'
+  [key: string]: any
+}
+
+interface LiquidToken {
+  kind: number
+  name?: string
+  args: string
+  content: string
+  begin: number
+  end: number
+}
+
+export const raiReusableUsage: Rule = {
   names: ['GHD035', 'rai-reusable-usage'],
   description:
     'RAI articles and reusables can only reference reusable content in the data/reusables/rai directory',
   tags: ['feature', 'rai'],
-  function: (params, onError) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
     if (!isFileRai(params)) return
 
     const content = params.lines.join('\n')
-    const tokens = getLiquidTokens(content)
-      .filter((token) => token.kind === TokenKind.Tag)
-      .filter((token) => token.name === 'data' || token.name === 'indented_data_reference')
+    const tokens = (getLiquidTokens(content) as LiquidToken[])
+      .filter((token: LiquidToken) => token.kind === TokenKind.Tag)
+      .filter(
+        (token: LiquidToken) => token.name === 'data' || token.name === 'indented_data_reference',
+      )
       // It's ok to reference variables from rai content
-      .filter((token) => !token.args.startsWith('variables'))
+      .filter((token: LiquidToken) => !token.args.startsWith('variables'))
 
     for (const token of tokens) {
       // if token is 'data  foo.bar` or `indented_data_reference foo.bar  depth=3`
@@ -42,7 +61,7 @@ export const raiReusableUsage = {
 
 // Rai file content can be in either the data/reusables/rai directory
 // or anywhere in the content directory
-function isFileRai(params) {
+function isFileRai(params: RuleParams): boolean {
   // ROOT is set in the test environment to src/fixtures/fixtures otherwise
   // it is set to the root of the project.
   const ROOT = process.env.ROOT || '.'
@@ -53,6 +72,6 @@ function isFileRai(params) {
     return params.name.startsWith(dataRai)
   }
 
-  const fm = getFrontmatter(params.frontMatterLines) || {}
+  const fm: Frontmatter = (getFrontmatter(params.frontMatterLines) as Frontmatter) || {}
   return fm.type === 'rai'
 }

src/content-linter/lib/linting-rules/yaml-scheduled-jobs.js renamed to src/content-linter/lib/linting-rules/yaml-scheduled-jobs.ts

@@ -1,21 +1,35 @@
 import yaml from 'js-yaml'
+// @ts-ignore - markdownlint-rule-helpers doesn't have TypeScript declarations
 import { addError, filterTokens } from 'markdownlint-rule-helpers'
 
 import { liquid } from '@/content-render/index'
 import { allVersions } from '@/versions/lib/all-versions'
+import type { RuleParams, RuleErrorCallback, MarkdownToken, Rule } from '../../types'
 
-const scheduledYamlJobs = []
+interface YamlSchedule {
+  cron: string
+}
+
+interface YamlWorkflow {
+  on?: {
+    schedule?: YamlSchedule[]
+  }
+}
+
+const scheduledYamlJobs: string[] = []
 
-export const yamlScheduledJobs = {
+export const yamlScheduledJobs: Rule = {
   names: ['GHD021', 'yaml-scheduled-jobs'],
   description:
     'YAML snippets that include scheduled workflows must not run on the hour and must be unique',
   tags: ['feature', 'actions'],
   parser: 'markdownit',
   asynchronous: true,
-  function: (params, onError) => {
-    filterTokens(params, 'fence', async (token) => {
-      const lang = token.info.trim().split(/\s+/u).shift().toLowerCase()
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
+    filterTokens(params, 'fence', async (token: MarkdownToken) => {
+      if (!token.info) return
+      if (!token.content) return
+      const lang = token.info.trim().split(/\s+/u).shift()?.toLowerCase()
       if (lang !== 'yaml' && lang !== 'yml') return
       if (!token.content.includes('schedule:')) return
       if (!token.content.includes('- cron:')) return
@@ -26,15 +40,15 @@ export const yamlScheduledJobs = {
       }
       // If we don't parse the Liquid first, yaml loading chokes on {% raw %} tags
       const renderedYaml = await liquid.parseAndRender(token.content, context)
-      const yamlObj = yaml.load(renderedYaml)
+      const yamlObj = yaml.load(renderedYaml) as YamlWorkflow
       if (!yamlObj.on) return
       if (!yamlObj.on.schedule) return
 
-      yamlObj.on.schedule.forEach((schedule) => {
+      yamlObj.on.schedule.forEach((schedule: YamlSchedule) => {
         if (schedule.cron.split(' ')[0] === '0') {
           addError(
             onError,
-            getLineNumber(token.content, schedule.cron) + token.lineNumber,
+            getLineNumber(token.content!, schedule.cron) + token.lineNumber,
             `YAML scheduled workflow must not run on the hour`,
             schedule.cron,
           )
@@ -43,7 +57,7 @@ export const yamlScheduledJobs = {
         if (scheduledYamlJobs.includes(schedule.cron)) {
           addError(
             onError,
-            getLineNumber(token.content, schedule.cron) + token.lineNumber,
+            getLineNumber(token.content!, schedule.cron) + token.lineNumber,
             `YAML scheduled workflow must be unique`,
             schedule.cron,
           )
@@ -55,7 +69,7 @@ export const yamlScheduledJobs = {
   },
 }
 
-function getLineNumber(tokenContent, schedule) {
+function getLineNumber(tokenContent: string, schedule: string): number {
   const contentLines = tokenContent.split('\n')
   return contentLines.findIndex((line) => line.includes(schedule)) + 1
 }

src/content-linter/tests/site-data-references.js renamed to src/content-linter/tests/site-data-references.ts

@@ -17,7 +17,7 @@ const getDataPathRegex =
 
 const rawLiquidPattern = /{%\s*raw\s*%}.*?{%\s*endraw\s*%}/gs
 
-const getDataReferences = (content) => {
+const getDataReferences = (content: string): string[] => {
   // When looking for things like `{% data reusables.foo %}` in the
   // content, we first have to exclude any Liquid that isn't real.
   // E.g.
@@ -26,14 +26,15 @@ const getDataReferences = (content) => {
   //  {% endraw %}
   const withoutRawLiquidBlocks = content.replace(rawLiquidPattern, '')
   const refs = withoutRawLiquidBlocks.match(patterns.dataReference) || []
-  return refs.map((ref) => ref.replace(getDataPathRegex, '$1'))
+  return refs.map((ref: string) => ref.replace(getDataPathRegex, '$1'))
 }
 
 describe('data references', () => {
   vi.setConfig({ testTimeout: 60 * 1000 })
 
   test('every data reference found in English variable files is defined and has a value', async () => {
-    let errors = []
+    // value can be any type returned by getDataByLanguage - we check if it's a string
+    let errors: Array<{ key: string; value: unknown; variableFile: string }> = []
     const allVariables = getDeepDataByLanguage('variables', 'en')
     const variables = Object.values(allVariables)
     expect(variables.length).toBeGreaterThan(0)
@@ -42,13 +43,11 @@ describe('data references', () => {
       variables.map(async (variablesPerFile) => {
         const variableRefs = getDataReferences(JSON.stringify(variablesPerFile))
 
-        variableRefs.forEach((key) => {
+        variableRefs.forEach((key: string) => {
           const value = getDataByLanguage(key, 'en')
           if (typeof value !== 'string') {
-            const variableFile = path.join(
-              'data/variables',
-              getFilenameByValue(allVariables, variablesPerFile),
-            )
+            const filename = getFilenameByValue(allVariables, variablesPerFile)
+            const variableFile = path.join('data/variables', filename || '')
             errors.push({ key, value, variableFile })
           }
         })
@@ -60,6 +59,7 @@ describe('data references', () => {
   })
 })
 
-function getFilenameByValue(object, value) {
+// object is the allVariables object with dynamic keys, value is the nested object we're searching for
+function getFilenameByValue(object: Record<string, unknown>, value: unknown): string | undefined {
   return Object.keys(object).find((key) => object[key] === value)
 }