Replace 'any' types with 'unknown' or specific types (#58694)

Author: heiskr

src/content-linter/lib/helpers/liquid-utils.ts

@@ -1,20 +1,16 @@
 import { Tokenizer, TokenKind } from 'liquidjs'
+import type { TopLevelToken, TagToken } from 'liquidjs'
 
 import { deprecated } from '@/versions/lib/enterprise-server-releases'
 
-// 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>()
+// Cache for liquid tokens to improve performance
+const liquidTokenCache = new Map<string, TopLevelToken[]>()
 
-// 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.
+// Returns TopLevelToken array from liquidjs which is a union of TagToken, OutputToken, and HTMLToken
 export function getLiquidTokens(
   content: string,
   { noCache = false }: { noCache?: boolean } = {},
-): any[] {
+): TopLevelToken[] {
   if (!content) return []
 
   if (noCache) {
@@ -23,13 +19,13 @@ export function getLiquidTokens(
   }
 
   if (liquidTokenCache.has(content)) {
-    return liquidTokenCache.get(content)
+    return liquidTokenCache.get(content)!
   }
 
   const tokenizer = new Tokenizer(content)
   const tokens = tokenizer.readTopLevelTokens()
   liquidTokenCache.set(content, tokens)
-  return liquidTokenCache.get(content)
+  return liquidTokenCache.get(content)!
 }
 
 export const OUTPUT_OPEN = '{%'
@@ -40,10 +36,9 @@ export const TAG_CLOSE = '}}'
 export const conditionalTags = ['if', 'elseif', 'unless', 'case', 'ifversion']
 const CONDITIONAL_TAG_NAMES = ['if', 'ifversion', 'elsif', 'else', 'endif']
 
-// 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.
+// Token parameter uses TopLevelToken which has begin and end properties
 export function getPositionData(
-  token: any,
+  token: TopLevelToken,
   lines: string[],
 ): { lineNumber: number; column: number; length: number } {
   // Liquid indexes are 0-based, but we want to
@@ -77,9 +72,9 @@ export function getPositionData(
  * by Markdownlint:
  * [ { lineNumber: 1, column: 1, deleteCount: 3, }]
  */
-// Token is `any` because it's used with different token types from liquidjs.
+// Token parameter uses TopLevelToken from liquidjs
 export function getContentDeleteData(
-  token: any,
+  token: TopLevelToken,
   tokenEnd: number,
   lines: string[],
 ): Array<{ lineNumber: number; column: number; deleteCount: number }> {
@@ -123,15 +118,14 @@ export function getContentDeleteData(
 // related elsif, else, and endif tags).
 // Docs doesn't use the standard `if` tag for versioning, instead the
 // `ifversion` tag is used.
-// 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[] {
+// Returns TagToken array since we filter to only Tag tokens
+export function getLiquidIfVersionTokens(content: string): TagToken[] {
   const tokens = getLiquidTokens(content)
-    .filter((token) => token.kind === TokenKind.Tag)
+    .filter((token): token is TagToken => token.kind === TokenKind.Tag)
     .filter((token) => CONDITIONAL_TAG_NAMES.includes(token.name))
 
   let inIfStatement = false
-  const ifVersionTokens: any[] = []
+  const ifVersionTokens: TagToken[] = []
   for (const token of tokens) {
     if (token.name === 'if') {
       inIfStatement = true

src/content-linter/lib/helpers/utils.ts

@@ -11,18 +11,20 @@ export function addFixErrorDetail(
   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,
+  // Using unknown for fixInfo as markdownlint-rule-helpers accepts various fix info structures
+  fixInfo: unknown,
 ): void {
   addError(onError, lineNumber, `Expected: ${expected}`, ` Actual: ${actual}`, range, fixInfo)
 }
 
 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,
+  // Handler uses `any` for function parameter variance reasons. TypeScript's contravariance rules for function
+  // parameters mean that a function accepting a specific type cannot be assigned to a parameter of type `unknown`.
+  // Therefore, `unknown` cannot be used here, as different linting rules pass tokens with varying structures
+  // beyond the base MarkdownToken interface, and some handlers are async.
+  handler: (child: any, token?: any) => void | Promise<void>,
 ): void {
   filterTokens(params, 'inline', (token: MarkdownToken) => {
     for (const child of token.children!.filter((c) => c.type === type)) {
@@ -146,8 +148,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.
-// Returns frontmatter as a Record with any values since YAML can contain various types
-export function getFrontmatter(lines: string[]): Record<string, any> | null {
+// Returns frontmatter as a Record with unknown values since YAML can contain various types
+export function getFrontmatter(lines: string[]): Record<string, unknown> | null {
   const fmString = lines.join('\n')
   const { data } = matter(fmString)
   // If there is no frontmatter or the frontmatter contains

src/content-linter/lib/linting-rules/internal-links-slash.ts

@@ -1,16 +1,16 @@
 import { filterTokens } from 'markdownlint-rule-helpers'
 
 import { addFixErrorDetail, getRange } from '../helpers/utils'
-import type { RuleParams, RuleErrorCallback, Rule } from '../../types'
+import type { RuleParams, RuleErrorCallback, Rule, MarkdownToken } from '../../types'
 
 export const internalLinksSlash: Rule = {
   names: ['GHD003', 'internal-links-slash'],
   description: 'Internal links must start with a /',
   tags: ['links', 'url'],
   parser: 'markdownit',
   function: (params: RuleParams, onError: RuleErrorCallback) => {
-    // Using 'any' type for token as markdownlint-rule-helpers doesn't provide TypeScript types
-    filterTokens(params, 'inline', (token: any) => {
+    filterTokens(params, 'inline', (token: MarkdownToken) => {
+      if (!token.children) return
       for (const child of token.children) {
         if (child.type !== 'link_open') continue
 
@@ -20,6 +20,7 @@ export const internalLinksSlash: Rule = {
         //  ['rel', 'canonical'],
         // ]
         // Attribute arrays are tuples of [attributeName, attributeValue] from markdownit parser
+        if (!child.attrs) continue
         const hrefsMissingSlashes = child.attrs
           // The attribute could also be `target` or `rel`
           .filter((attr: [string, string]) => attr[0] === 'href')

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

@@ -1,5 +1,6 @@
 import { addError } from 'markdownlint-rule-helpers'
 import { TokenKind } from 'liquidjs'
+import type { TagToken } from 'liquidjs'
 
 import { getDataByLanguage } from '@/data-directory/lib/get-data'
 import {
@@ -23,10 +24,9 @@ export const liquidDataReferencesDefined = {
   parser: 'markdownit',
   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: any) => token.kind === TokenKind.Tag)
-      .filter((token: any) => token.name === 'data' || token.name === 'indented_data_reference')
+      .filter((token): token is TagToken => token.kind === TokenKind.Tag)
+      .filter((token) => token.name === 'data' || token.name === 'indented_data_reference')
 
     if (!tokens.length) return
 
@@ -60,13 +60,11 @@ export const liquidDataTagFormat = {
   function: (params: RuleParams, onError: RuleErrorCallback) => {
     const CHECK_LIQUID_TAGS = [OUTPUT_OPEN, OUTPUT_CLOSE, '{', '}']
     const content = params.lines.join('\n')
-    // 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',
+    const tokenTags = getLiquidTokens(content).filter(
+      (token): token is TagToken => token.kind === TokenKind.Tag,
     )
+    const dataTags = tokenTags.filter((token) => token.name === 'data')
+    const indentedDataTags = tokenTags.filter((token) => token.name === 'indented_data_reference')
 
     for (const token of dataTags) {
       // A data tag has only one argument, the data directory path.

src/content-linter/lib/linting-rules/liquid-ifversion-versions.ts

@@ -1,4 +1,5 @@
 import { addError } from 'markdownlint-rule-helpers'
+import type { TopLevelToken } from 'liquidjs'
 
 import {
   getLiquidIfVersionTokens,
@@ -35,8 +36,11 @@ export const liquidIfversionVersions = {
     const fileVersionsFm = params.name.startsWith('data')
       ? { ghec: '*', ghes: '*', fpt: '*' }
       : fm
-        ? fm.versions
-        : getFrontmatter(params.frontMatterLines)?.versions
+        ? (fm.versions as string | Record<string, string> | undefined)
+        : (getFrontmatter(params.frontMatterLines)?.versions as
+            | string
+            | Record<string, string>
+            | undefined)
     // This will only contain valid (non-deprecated) and future versions
     const fileVersions = getApplicableVersions(fileVersionsFm, '', {
       doNotThrow: true,
@@ -134,7 +138,7 @@ function setLiquidErrors(condTagItems: any[], onError: RuleErrorCallback, lines:
         {
           begin: item.begin,
           end: item.end,
-        },
+        } as TopLevelToken,
         lines,
       )
       const deleteCount = length - column + 1 === lines[lineNumber - 1].length ? -1 : length
@@ -159,7 +163,7 @@ function setLiquidErrors(condTagItems: any[], onError: RuleErrorCallback, lines:
         {
           begin: item.contentrange[0],
           end: item.contentrange[1],
-        },
+        } as TopLevelToken,
         lines,
       )
       const insertText = `${item.action.name || item.name} ${item.action.cond || item.cond}`

src/content-linter/lib/linting-rules/liquid-quoted-conditional-arg.ts

@@ -1,4 +1,5 @@
 import { TokenKind } from 'liquidjs'
+import type { TagToken } from 'liquidjs'
 import { addError } from 'markdownlint-rule-helpers'
 
 import { getLiquidTokens, conditionalTags, getPositionData } from '../helpers/liquid-utils'
@@ -19,14 +20,12 @@ export const liquidQuotedConditionalArg: Rule = {
   tags: ['liquid', 'format'],
   function: (params: RuleParams, onError: RuleErrorCallback) => {
     const content = params.lines.join('\n')
-    // Using 'any' type for tokens as getLiquidTokens returns tokens from liquid-utils.ts which lacks type definitions
     const tokens = getLiquidTokens(content)
-      .filter((token: any) => token.kind === TokenKind.Tag)
-      .filter((token: any) => conditionalTags.includes(token.name))
-      .filter((token: any) => {
+      .filter((token): token is TagToken => token.kind === TokenKind.Tag)
+      .filter((token) => conditionalTags.includes(token.name))
+      .filter((token) => {
         const tokensArray = token.args.split(/\s+/g)
-        // Using 'any' for args as they come from the untyped liquid token structure
-        if (tokensArray.some((arg: any) => isStringQuoted(arg))) return true
+        if (tokensArray.some((arg) => isStringQuoted(arg))) return true
         return false
       })
 

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

@@ -33,6 +33,7 @@ export const frontmatterLiquidSyntax = {
 
     for (const key of keysWithLiquid) {
       const value = fm[key]
+      if (typeof value !== 'string') continue
       try {
         liquid.parse(value)
       } catch (error) {

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

@@ -1,4 +1,5 @@
 import { TokenKind } from 'liquidjs'
+import type { TopLevelToken } from 'liquidjs'
 
 import { getLiquidTokens, getPositionData } from '../helpers/liquid-utils'
 import { addFixErrorDetail } from '../helpers/utils'
@@ -36,7 +37,10 @@ export const liquidTagWhitespace: Rule = {
       (token: LiquidToken) => token.kind === TokenKind.Tag,
     )
     for (const token of tokens) {
-      const { lineNumber, column, length } = getPositionData(token, params.lines)
+      const { lineNumber, column, length } = getPositionData(
+        token as unknown as TopLevelToken,
+        params.lines,
+      )
 
       const range = [column, length]
       const tag = params.lines[lineNumber - 1].slice(column - 1, column - 1 + length)

src/content-linter/lib/linting-rules/liquid-versioning.ts

@@ -1,5 +1,6 @@
 import semver from 'semver'
 import { TokenKind } from 'liquidjs'
+import type { TagToken } from 'liquidjs'
 import { addError } from 'markdownlint-rule-helpers'
 
 import { getRange, addFixErrorDetail } from '../helpers/utils'
@@ -13,7 +14,7 @@ import type { RuleParams, RuleErrorCallback } from '@/content-linter/types'
 
 interface Feature {
   versions: Record<string, string>
-  [key: string]: any
+  [key: string]: unknown
 }
 
 type AllFeatures = Record<string, Feature>
@@ -60,12 +61,13 @@ export const liquidIfTags = {
   function: (params: RuleParams, onError: RuleErrorCallback) => {
     const content = params.lines.join('\n')
 
-    const tokens = getLiquidTokens(content).filter(
-      (token) =>
-        token.kind === TokenKind.Tag &&
-        token.name === 'if' &&
-        token.args.split(/\s+/).some((arg: string) => getAllPossibleVersionNames().has(arg)),
-    )
+    const tokens = getLiquidTokens(content)
+      .filter((token): token is TagToken => token.kind === TokenKind.Tag)
+      .filter(
+        (token) =>
+          token.name === 'if' &&
+          token.args.split(/\s+/).some((arg: string) => getAllPossibleVersionNames().has(arg)),
+      )
 
     for (const token of tokens) {
       const args = token.args
@@ -90,7 +92,7 @@ export const liquidIfVersionTags = {
   function: (params: RuleParams, onError: RuleErrorCallback) => {
     const content = params.lines.join('\n')
     const tokens = getLiquidTokens(content)
-      .filter((token) => token.kind === TokenKind.Tag)
+      .filter((token): token is TagToken => token.kind === TokenKind.Tag)
       .filter((token) => token.name === 'ifversion' || token.name === 'elsif')
 
     for (const token of tokens) {

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

@@ -1,5 +1,6 @@
 import { addError } from 'markdownlint-rule-helpers'
 import { TokenKind } from 'liquidjs'
+import type { TopLevelToken } from 'liquidjs'
 import path from 'path'
 
 import { getFrontmatter } from '../helpers/utils'
@@ -45,7 +46,10 @@ export const raiReusableUsage: Rule = {
       if (dataDirectoryReference.startsWith('reusables.rai')) continue
 
       const lines = params.lines
-      const { lineNumber, column, length } = getPositionData(token, lines)
+      const { lineNumber, column, length } = getPositionData(
+        token as unknown as TopLevelToken,
+        lines,
+      )
       addError(
         onError,
         lineNumber,