Convert 21 JavaScript files to TypeScript (#57896)

Author: heiskr

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

@@ -1,20 +1,38 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't provide TypeScript declarations
 import { addError, filterTokens } from 'markdownlint-rule-helpers'
 import matter from '@gr2m/gray-matter'
 
+import type { RuleParams, RuleErrorCallback, MarkdownToken } from '@/content-linter/types'
+
 // Adds an error object with details conditionally via the onError callback
-export function addFixErrorDetail(onError, lineNumber, expected, actual, range, fixInfo) {
+export function addFixErrorDetail(
+  onError: RuleErrorCallback,
+  lineNumber: number,
+  expected: string,
+  actual: string,
+  // Using flexible type to accommodate different range formats from various linting rules
+  range: [number, number] | number[] | null,
+  // Using any for fixInfo as markdownlint-rule-helpers accepts various fix info structures
+  fixInfo: any,
+): void {
   addError(onError, lineNumber, `Expected: ${expected}`, ` Actual: ${actual}`, range, fixInfo)
 }
 
-export function forEachInlineChild(params, type, handler) {
-  filterTokens(params, 'inline', (token) => {
-    for (const child of token.children.filter((c) => c.type === type)) {
+export function forEachInlineChild(
+  params: RuleParams,
+  type: string,
+  // Using any for child and token types because different linting rules pass tokens with varying structures
+  // beyond the base MarkdownToken interface (e.g., ImageToken with additional properties)
+  handler: (child: any, token: any) => void,
+): void {
+  filterTokens(params, 'inline', (token: MarkdownToken) => {
+    for (const child of token.children!.filter((c) => c.type === type)) {
       handler(child, token)
     }
   })
 }
 
-export function getRange(line, content) {
+export function getRange(line: string, content: string): [number, number] | null {
   if (content.length === 0) {
     // This function assumes that the content is something. If it's an
     // empty string it can never produce a valid range.
@@ -24,15 +42,15 @@ export function getRange(line, content) {
   return startColumnIndex !== -1 ? [startColumnIndex + 1, content.length] : null
 }
 
-export function isStringQuoted(text) {
+export function isStringQuoted(text: string): boolean {
   // String starts with either a single or double quote
   // ends with either a single or double quote
   // and optionally ends with a question mark or exclamation point
   // because that punctuation can exist outside of the quoted string
   return /^['"].*['"][?!]?$/.test(text)
 }
 
-export function isStringPunctuated(text) {
+export function isStringPunctuated(text: string): boolean {
   // String ends with punctuation of either
   // . ? ! and optionally ends with single
   // or double quotes. This also allows
@@ -41,7 +59,7 @@ export function isStringPunctuated(text) {
   return /^.*[.?!]['"]?$/.test(text)
 }
 
-export function doesStringEndWithPeriod(text) {
+export function doesStringEndWithPeriod(text: string): boolean {
   // String ends with punctuation of either
   // . ? ! and optionally ends with single
   // or double quotes. This also allows
@@ -50,7 +68,7 @@ export function doesStringEndWithPeriod(text) {
   return /^.*\.['"]?$/.test(text)
 }
 
-export function quotePrecedesLinkOpen(text) {
+export function quotePrecedesLinkOpen(text: string | undefined): boolean {
   if (!text) return false
   return text.endsWith('"') || text.endsWith("'")
 }
@@ -87,12 +105,15 @@ export function quotePrecedesLinkOpen(text) {
 //      { type: 'paragraph_close'},   <-- Index 5 - NOT INCLUDED
 //   ]
 //
-export function filterTokensByOrder(tokens, tokenOrder) {
-  const matches = []
+export function filterTokensByOrder(
+  tokens: MarkdownToken[],
+  tokenOrder: string[],
+): MarkdownToken[] {
+  const matches: MarkdownToken[] = []
 
   // Get a list of token indexes that match the
   // first token (root) in the tokenOrder array
-  const tokenRootIndexes = []
+  const tokenRootIndexes: number[] = []
   const firstTokenOrderType = tokenOrder[0]
   tokens.forEach((token, index) => {
     if (token.type === firstTokenOrderType) {
@@ -125,7 +146,8 @@ export const docsDomains = ['docs.github.com', 'help.github.com', 'developer.git
 // This is the format we get from Markdownlint.
 // Returns null if the lines do not contain
 // frontmatter properties.
-export function getFrontmatter(lines) {
+// Returns frontmatter as a Record with any values since YAML can contain various types
+export function getFrontmatter(lines: string[]): Record<string, any> | null {
   const fmString = lines.join('\n')
   const { data } = matter(fmString)
   // If there is no frontmatter or the frontmatter contains
@@ -134,7 +156,7 @@ export function getFrontmatter(lines) {
   return data
 }
 
-export function getFrontmatterLines(lines) {
+export function getFrontmatterLines(lines: string[]): string[] {
   const indexStart = lines.indexOf('---')
   if (indexStart === -1) return []
   const indexEnd = lines.indexOf('---', indexStart + 1)

src/content-linter/lib/linting-rules/british-english-quotes.js renamed to src/content-linter/lib/linting-rules/british-english-quotes.ts

@@ -1,14 +1,17 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't provide TypeScript declarations
 import { addError } from 'markdownlint-rule-helpers'
 import { getRange } from '../helpers/utils'
 import frontmatter from '@/frame/lib/read-frontmatter'
 
+import type { RuleParams, RuleErrorCallback } from '@/content-linter/types'
+
 export const britishEnglishQuotes = {
   names: ['GHD048', 'british-english-quotes'],
   description:
     'Periods and commas should be placed inside quotation marks (American English style)',
   tags: ['punctuation', 'quotes', 'style', 'consistency'],
   severity: 'warning', // Non-blocking as requested in the issue
-  function: (params, onError) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
     // Skip autogenerated files
     const frontmatterString = params.frontMatterLines.join('\n')
     const fm = frontmatter(frontmatterString).data
@@ -33,7 +36,7 @@ export const britishEnglishQuotes = {
 /**
  * Check if the current position is within a code context (code blocks, inline code, URLs)
  */
-function isInCodeContext(line, allLines, lineIndex) {
+function isInCodeContext(line: string, allLines: string[], lineIndex: number): boolean {
   // Skip if line contains code fences
   if (line.includes('```') || line.includes('~~~')) {
     return true
@@ -67,18 +70,22 @@ function isInCodeContext(line, allLines, lineIndex) {
 /**
  * Find and report British English quote patterns in a line
  */
-function findAndReportBritishQuotes(line, lineNumber, onError) {
+function findAndReportBritishQuotes(
+  line: string,
+  lineNumber: number,
+  onError: RuleErrorCallback,
+): void {
   // Pattern to find quote followed by punctuation outside
   // Matches: "text". or 'text', or "text",  etc.
   const britishPattern = /(["'])([^"']*?)\1\s*([.,])/g
 
-  let match
+  let match: RegExpMatchArray | null
   while ((match = britishPattern.exec(line)) !== null) {
     const quoteChar = match[1]
     const quotedText = match[2]
     const punctuation = match[3]
     const fullMatch = match[0]
-    const startIndex = match.index
+    const startIndex = match.index ?? 0
 
     // Create the corrected version (punctuation inside quotes)
     const correctedText = quoteChar + quotedText + punctuation + quoteChar

src/content-linter/lib/linting-rules/header-content-requirement.js renamed to src/content-linter/lib/linting-rules/header-content-requirement.ts

@@ -1,18 +1,28 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't provide TypeScript declarations
 import { addError, filterTokens } from 'markdownlint-rule-helpers'
 
+import type { RuleParams, RuleErrorCallback, MarkdownToken } from '@/content-linter/types'
+
+interface HeadingInfo {
+  token: MarkdownToken
+  lineNumber: number
+  level: number
+  line: string
+}
+
 export const headerContentRequirement = {
   names: ['GHD053', 'header-content-requirement'],
   description: 'Headers must have content between them, such as an introduction',
   tags: ['headers', 'structure', 'content'],
-  function: (params, onError) => {
-    const headings = []
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
+    const headings: HeadingInfo[] = []
 
     // Collect all heading tokens with their line numbers and levels
-    filterTokens(params, 'heading_open', (token) => {
+    filterTokens(params, 'heading_open', (token: MarkdownToken) => {
       headings.push({
         token,
         lineNumber: token.lineNumber,
-        level: parseInt(token.tag.slice(1)), // Extract number from h1, h2, etc.
+        level: parseInt(token.tag!.slice(1)), // Extract number from h1, h2, etc.
         line: params.lines[token.lineNumber - 1],
       })
     })
@@ -49,7 +59,11 @@ export const headerContentRequirement = {
  * Check if there is meaningful content between two headings
  * Returns true if content exists, false if only whitespace/empty lines
  */
-function checkForContentBetweenHeadings(lines, startLineNumber, endLineNumber) {
+function checkForContentBetweenHeadings(
+  lines: string[],
+  startLineNumber: number,
+  endLineNumber: number,
+): boolean {
   // Convert to 0-based indexes and skip the heading lines themselves
   const startIndex = startLineNumber // Skip the current heading line
   const endIndex = endLineNumber - 2 // Stop before the next heading line
@@ -82,7 +96,7 @@ function checkForContentBetweenHeadings(lines, startLineNumber, endLineNumber) {
  * Check if a line contains only Liquid tags that don't produce visible content
  * This helps avoid false positives for conditional blocks
  */
-function isNonContentLiquidTag(line) {
+function isNonContentLiquidTag(line: string): boolean {
   // Match common non-content Liquid tags
   const nonContentTags = [
     /^{%\s*ifversion\s+.*%}$/,

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

@@ -1,4 +1,6 @@
+// @ts-ignore - markdownlint-rule-search-replace doesn't provide TypeScript declarations
 import searchReplace from 'markdownlint-rule-search-replace'
+// @ts-ignore - @github/markdownlint-github doesn't provide TypeScript declarations
 import markdownlintGitHub from '@github/markdownlint-github'
 
 import { codeFenceLineLength } from '@/content-linter/lib/linting-rules/code-fence-line-length'
@@ -57,10 +59,13 @@ import { thirdPartyActionsReusable } from '@/content-linter/lib/linting-rules/th
 import { frontmatterLandingRecommended } from '@/content-linter/lib/linting-rules/frontmatter-landing-recommended'
 import { ctasSchema } from '@/content-linter/lib/linting-rules/ctas-schema'
 
-const noDefaultAltText = markdownlintGitHub.find((elem) =>
+// Using any type because @github/markdownlint-github doesn't provide TypeScript declarations
+// The elements in the array have a 'names' property that contains rule identifiers
+const noDefaultAltText = markdownlintGitHub.find((elem: any) =>
   elem.names.includes('no-default-alt-text'),
 )
-const noGenericLinkText = markdownlintGitHub.find((elem) =>
+// Using any type because @github/markdownlint-github doesn't provide TypeScript declarations
+const noGenericLinkText = markdownlintGitHub.find((elem: any) =>
   elem.names.includes('no-generic-link-text'),
 )
 

src/content-linter/lib/linting-rules/liquid-data-tags.js renamed to src/content-linter/lib/linting-rules/liquid-data-tags.ts

@@ -1,5 +1,6 @@
-import { TokenKind } from 'liquidjs'
+// @ts-ignore - markdownlint-rule-helpers doesn't provide TypeScript declarations
 import { addError } from 'markdownlint-rule-helpers'
+import { TokenKind } from 'liquidjs'
 
 import { getDataByLanguage } from '@/data-directory/lib/get-data'
 import {
@@ -9,6 +10,8 @@ import {
   OUTPUT_CLOSE,
 } from '../helpers/liquid-utils'
 
+import type { RuleParams, RuleErrorCallback } from '@/content-linter/types'
+
 /*
   Checks for instances where a Liquid data or indented_data_reference
   tag is used but is not defined.
@@ -19,11 +22,12 @@ export const liquidDataReferencesDefined = {
     'Liquid data or indented data references were found in content that have no value or do not exist in the data directory',
   tags: ['liquid'],
   parser: 'markdownit',
-  function: (params, onError) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
     const content = params.lines.join('\n')
+    // Using any type because getLiquidTokens returns tokens from liquidjs library without complete type definitions
     const tokens = getLiquidTokens(content)
-      .filter((token) => token.kind === TokenKind.Tag)
-      .filter((token) => token.name === 'data' || token.name === 'indented_data_reference')
+      .filter((token: any) => token.kind === TokenKind.Tag)
+      .filter((token: any) => token.name === 'data' || token.name === 'indented_data_reference')
 
     if (!tokens.length) return
 
@@ -54,12 +58,16 @@ export const liquidDataTagFormat = {
   description:
     'Liquid data or indented data references tags must be correctly formatted and have the correct number of arguments and spacing',
   tags: ['liquid', 'format'],
-  function: (params, onError) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
     const CHECK_LIQUID_TAGS = [OUTPUT_OPEN, OUTPUT_CLOSE, '{', '}']
     const content = params.lines.join('\n')
-    const tokenTags = getLiquidTokens(content).filter((token) => token.kind === TokenKind.Tag)
-    const dataTags = tokenTags.filter((token) => token.name === 'data')
-    const indentedDataTags = tokenTags.filter((token) => token.name === 'indented_data_reference')
+    // Using any type because getLiquidTokens returns tokens from liquidjs library without complete type definitions
+    // Tokens have properties like 'kind', 'name', 'args', and 'content' that aren't fully typed
+    const tokenTags = getLiquidTokens(content).filter((token: any) => token.kind === TokenKind.Tag)
+    const dataTags = tokenTags.filter((token: any) => token.name === 'data')
+    const indentedDataTags = tokenTags.filter(
+      (token: any) => token.name === 'indented_data_reference',
+    )
 
     for (const token of dataTags) {
       // A data tag has only one argument, the data directory path.
@@ -125,9 +133,9 @@ export const liquidDataTagFormat = {
 }
 
 // Convenient wrapper because linting is always about English content
-const getData = (liquidRef) => getDataByLanguage(liquidRef, 'en')
+const getData = (liquidRef: string) => getDataByLanguage(liquidRef, 'en')
 
-const hasData = (liquidRef) => {
+const hasData = (liquidRef: string): boolean => {
   try {
     // If a reusable contains a nonexistent data reference, it will
     // return undefined. If the data reference is inherently broken

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

@@ -1,9 +1,18 @@
+// @ts-ignore - markdownlint-rule-helpers doesn't provide TypeScript declarations
 import { addError } from 'markdownlint-rule-helpers'
 
 import { getFrontmatter } from '../helpers/utils'
 import { liquid } from '@/content-render/index'
 import { isLiquidError } from '@/languages/lib/render-with-fallback'
 
+import type { RuleParams, RuleErrorCallback } from '@/content-linter/types'
+
+interface ErrorMessageInfo {
+  errorDescription: string
+  lineNumber: number
+  columnNumber: number
+}
+
 /*
   Attempts to parse all liquid in the frontmatter of a file
   to verify the syntax is correct.
@@ -12,7 +21,7 @@ export const frontmatterLiquidSyntax = {
   names: ['GHD017', 'frontmatter-liquid-syntax'],
   description: 'Frontmatter properties must use valid Liquid',
   tags: ['liquid', 'frontmatter'],
-  function: (params, onError) => {
+  function: (params: RuleParams, onError: RuleErrorCallback) => {
     const fm = getFrontmatter(params.lines)
     if (!fm) return
 
@@ -31,7 +40,7 @@ export const frontmatterLiquidSyntax = {
         // If the error source is not a Liquid error but rather a
         // ReferenceError or bad type we should allow that error to be thrown
         if (!isLiquidError(error)) throw error
-        const { errorDescription, columnNumber } = getErrorMessageInfo(error.message)
+        const { errorDescription, columnNumber } = getErrorMessageInfo((error as Error).message)
         const lineNumber = params.lines.findIndex((line) => line.trim().startsWith(`${key}:`)) + 1
         // Add the key length plus 3 to the column number to account colon and
         // for the  space after the key and column number starting at 1.
@@ -42,7 +51,7 @@ export const frontmatterLiquidSyntax = {
           startRange + value.length - 1 > params.lines[lineNumber - 1].length
             ? params.lines[lineNumber - 1].length - startRange + 1
             : value.length
-        const range = [startRange, endRange]
+        const range: [number, number] = [startRange, endRange]
         addError(
           onError,
           lineNumber,
@@ -64,20 +73,22 @@ export const liquidSyntax = {
   names: ['GHD018', 'liquid-syntax'],
   description: 'Markdown content must use valid Liquid',
   tags: ['liquid'],
-  function: function GHD018(params, onError) {
+  function: function GHD018(params: RuleParams, onError: RuleErrorCallback) {
     try {
       liquid.parse(params.lines.join('\n'))
     } catch (error) {
       // If the error source is not a Liquid error but rather a
       // ReferenceError or bad type we should allow that error to be thrown
       if (!isLiquidError(error)) throw error
-      const { errorDescription, lineNumber, columnNumber } = getErrorMessageInfo(error.message)
+      const { errorDescription, lineNumber, columnNumber } = getErrorMessageInfo(
+        (error as Error).message,
+      )
       const line = params.lines[lineNumber - 1]
       // We don't have enough information to know the length of the full
       // liquid tag without doing some regex testing and making assumptions
       // about if the end tag is correctly formed, so we just give a
       // range from the start of the tag to the end of the line.
-      const range = [columnNumber, line.slice(columnNumber - 1).length]
+      const range: [number, number] = [columnNumber, line.slice(columnNumber - 1).length]
       addError(
         onError,
         lineNumber,
@@ -90,7 +101,7 @@ export const liquidSyntax = {
   },
 }
 
-function getErrorMessageInfo(message) {
+function getErrorMessageInfo(message: string): ErrorMessageInfo {
   const [errorDescription, lineString, columnString] = message.split(',')
   // There has to be a line number so we'll default to line 1 if the message
   // doesn't contain a line number.