Convert src/ai-editors and src/metrics JavaScript files to TypeScript (#56353)

Co-authored-by: Sarah Schneider <[email protected]>

Author: heiskr

package.json

@@ -16,6 +16,7 @@
   },
   "exports": "./src/frame/server.ts",
   "scripts": {
+    "ai-edit": "tsx src/ai-editors/scripts/ai-edit.ts",
     "all-documents": "tsx src/content-render/scripts/all-documents/cli.ts",
     "analyze-text": "tsx src/search/scripts/analyze-text.ts",
     "analyze-comment": "tsx src/events/scripts/analyze-comment-cli.ts",
@@ -30,6 +31,8 @@
     "create-enterprise-issue": "tsx src/ghes-releases/scripts/create-enterprise-issue.ts",
     "debug": "cross-env NODE_ENV=development ENABLED_LANGUAGES=en nodemon --inspect src/frame/server.ts",
     "delete-orphan-translation-files": "tsx src/workflows/delete-orphan-translation-files.ts",
+    "docsaudit": "tsx src/metrics/scripts/docsaudit.ts",
+    "docstat": "tsx src/metrics/scripts/docstat.ts",
     "deleted-assets-pr-comment": "tsx src/assets/scripts/deleted-assets-pr-comment.ts",
     "deleted-features-pr-comment": "tsx src/data-directory/scripts/deleted-features-pr-comment.ts",
     "deprecate-ghes": "tsx src/ghes-releases/scripts/deprecate/index.ts",

src/ai-editors/lib/call-models-api.js

@@ -0,0 +1,60 @@
+const modelsCompletionsEndpoint = 'https://models.github.ai/inference/chat/completions'
+
+interface ChatMessage {
+  role: string
+  content: string
+}
+
+interface ChatCompletionRequest {
+  messages: ChatMessage[]
+  model?: string
+  temperature?: number
+  max_tokens?: number
+}
+
+interface ChatCompletionChoice {
+  message: {
+    content: string
+    role: string
+  }
+  finish_reason: string
+  index: number
+}
+
+interface ChatCompletionResponse {
+  choices: ChatCompletionChoice[]
+  id: string
+  object: string
+  created: number
+  model: string
+  usage?: {
+    prompt_tokens: number
+    completion_tokens: number
+    total_tokens: number
+  }
+}
+
+export async function callModelsApi(promptWithContent: ChatCompletionRequest): Promise<string> {
+  let aiResponse: ChatCompletionChoice
+
+  try {
+    const response = await fetch(modelsCompletionsEndpoint, {
+      method: 'post',
+      body: JSON.stringify(promptWithContent),
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
+        'X-GitHub-Api-Version': '2022-11-28',
+        Accept: 'Accept: application/vnd.github+json',
+      },
+    })
+
+    const data: ChatCompletionResponse = await response.json()
+    aiResponse = data.choices[0]
+  } catch (error) {
+    console.error('Error calling GitHub Models REST API')
+    throw error
+  }
+
+  return aiResponse.message.content
+}

src/ai-editors/lib/call-models-api.ts

@@ -6,8 +6,9 @@ import fs from 'fs'
 import yaml from 'js-yaml'
 import path from 'path'
 import ora from 'ora'
-import github from '#src/workflows/github.ts'
-import { callModelsApi } from '#src/ai-editors/lib/call-models-api.js'
+import { callModelsApi } from '@/ai-editors/lib/call-models-api'
+import dotenv from 'dotenv'
+dotenv.config()
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const promptDir = path.join(__dirname, '../prompts')
@@ -16,15 +17,36 @@ if (!process.env.GITHUB_TOKEN) {
   throw new Error('Error! You must have a GITHUB_TOKEN set in an .env file to run this script.')
 }
 
-const responseTypes = {
+interface ResponseTypes {
+  rewrite: string
+  list: string
+  json: string
+}
+
+const responseTypes: ResponseTypes = {
   rewrite: 'Edit the versioning only. Return the edited content.',
   list: `Do NOT rewrite the content. Report your edits in numbered list format.`,
   json: `Do NOT rewrite the content. Report your edits as a JSON list, with the format { lineNumber, currentText, suggestion }.`,
 }
 
-const validResponseTypes = Object.keys(responseTypes)
+const validResponseTypes = Object.keys(responseTypes) as Array<keyof ResponseTypes>
+
+interface EditorType {
+  promptFile: string
+  description: string
+}
+
+interface EditorTypes {
+  versioning: EditorType
+  // TODO
+  // scannability: EditorType
+  // readability: EditorType
+  // technical: EditorType
+  // styleguide: EditorType
+  // contentModels: EditorType
+}
 
-const editorTypes = {
+const editorTypes: EditorTypes = {
   versioning: {
     promptFile: 'versioning-editor.prompt.yml',
     description: 'Review against simplifying versioning guidelines.',
@@ -54,14 +76,21 @@ const editorTypes = {
   // Add more here...
 }
 
-const editorDescriptions = () => {
+const editorDescriptions = (): string => {
   let str = '\n\n'
   Object.entries(editorTypes).forEach(([ed, edObj]) => {
     str += `\t${ed}\n\t\t\t${edObj.description}\n\n`
   })
   return str
 }
 
+interface CliOptions {
+  verbose?: boolean
+  editor?: Array<keyof EditorTypes>
+  response?: keyof ResponseTypes
+  files: string[]
+}
+
 const program = new Command()
 
 program
@@ -80,15 +109,15 @@ program
     '-f, --files <files...>',
     'One or more content file paths in the content directory',
   )
-  .action((options) => {
+  .action((options: CliOptions) => {
     ;(async () => {
       const spinner = ora('Starting AI review...').start()
 
       const files = options.files
       const editors = options.editor || ['versioning']
       const response = options.response || 'rewrite'
 
-      let responseTypeInstruction
+      let responseTypeInstruction: string
       if (validResponseTypes.includes(response)) {
         responseTypeInstruction = responseTypes[response]
       } else {
@@ -126,7 +155,8 @@ program
             }
           }
         } catch (err) {
-          spinner.fail(`Error processing file ${file}: ${err.message}`)
+          const error = err as Error
+          spinner.fail(`Error processing file ${file}: ${error.message}`)
           process.exitCode = 1
         }
       }
@@ -135,13 +165,31 @@ program
 
 program.parse(process.argv)
 
-async function callEditor(editorType, responseTypeInstruction, content) {
+interface PromptMessage {
+  content: string
+  role: string
+}
+
+interface PromptData {
+  messages: PromptMessage[]
+  model?: string
+  temperature?: number
+  max_tokens?: number
+}
+
+async function callEditor(
+  editorType: keyof EditorTypes,
+  responseTypeInstruction: string,
+  content: string,
+): Promise<string> {
   const promptName = editorTypes[editorType].promptFile
   const promptPath = path.join(promptDir, promptName)
-  const prompt = yaml.load(fs.readFileSync(promptPath, 'utf8'))
+  const prompt = yaml.load(fs.readFileSync(promptPath, 'utf8')) as PromptData
+
   prompt.messages.forEach((msg) => {
     msg.content = msg.content.replace('{{responseTypeInstruction}}', responseTypeInstruction)
     msg.content = msg.content.replace('{{input}}', content)
   })
+
   return callModelsApi(prompt)
 }

src/ai-editors/scripts/ai-edit.js renamed to src/ai-editors/scripts/ai-edit.ts

@@ -1,11 +1,17 @@
-const dateOpts = {
+const dateOpts: Intl.DateTimeFormatOptions = {
   year: 'numeric',
   month: 'long',
   day: 'numeric',
 }
 
+export interface DateRange {
+  endDate: string
+  startDate: string
+  friendlyRange: string
+}
+
 // Default to 30 days ago if a range option is not provided
-export function getDates(range = '30') {
+export function getDates(range: string | number = '30'): DateRange {
   // Get current datetime in ISO format
   const today = new Date()
   const todayISO = today.toISOString()
@@ -21,7 +27,7 @@ export function getDates(range = '30') {
   }
 }
 
-function getDaysAgo(range) {
+function getDaysAgo(range: number): Date {
   const daysAgo = new Date()
   daysAgo.setDate(daysAgo.getDate() - range)
   return daysAgo

src/metrics/lib/dates.js renamed to src/metrics/lib/dates.ts

@@ -1,27 +1,46 @@
-import { Client as KustoClient, KustoConnectionStringBuilder } from 'azure-kusto-data'
+import {
+  Client as KustoClient,
+  KustoConnectionStringBuilder,
+  KustoResultTable,
+} from 'azure-kusto-data'
 
 import dotenv from 'dotenv'
+
 dotenv.config()
+
 if (!(process.env.KUSTO_CLUSTER || process.env.KUSTO_DATABASE)) {
   console.error(`Add KUSTO_CLUSTER and KUSTO_DATABASE to your .env file`)
   process.exit(0)
 }
-const KUSTO_CLUSTER = process.env.KUSTO_CLUSTER
-const KUSTO_DATABASE = process.env.KUSTO_DATABASE
 
-export function getKustoClient() {
-  let client
+const KUSTO_CLUSTER = process.env.KUSTO_CLUSTER!
+const KUSTO_DATABASE = process.env.KUSTO_DATABASE!
+
+export interface KustoQueryResult {
+  primaryResults: KustoResultTable[]
+}
+
+export function getKustoClient(): KustoClient | undefined {
+  let client: KustoClient | undefined
+
   try {
     const kcsb = KustoConnectionStringBuilder.withAzLoginIdentity(KUSTO_CLUSTER)
     client = new KustoClient(kcsb)
   } catch (error) {
     console.error('Error connecting to Kusto')
     console.error(error)
   }
+
   return client
 }
 
-export async function runQuery(pathToFetch, query, client, queryType, verbose = false) {
+export async function runQuery(
+  pathToFetch: string | string[],
+  query: string,
+  client: KustoClient,
+  queryType: string,
+  verbose: boolean = false,
+): Promise<KustoQueryResult | null> {
   // Display query if verbose mode is on
   if (verbose) {
     console.log(`\n--- EXECUTING QUERY FOR "${queryType.toUpperCase()}" ---`)

src/metrics/lib/kusto-client.js renamed to src/metrics/lib/kusto-client.ts

@@ -1,25 +1,36 @@
-import { runQuery } from '#src/metrics/lib/kusto-client.js'
-import { SHARED_DECLARATIONS, SHARED_FILTERS } from '#src/metrics/queries/constants.js'
+import { runQuery } from '@/metrics/lib/kusto-client'
+import { SHARED_DECLARATIONS, SHARED_FILTERS } from '@/metrics/queries/constants'
+import type { DateRange } from '@/metrics/lib/dates'
+import type { Client as KustoClient } from 'azure-kusto-data'
 
 const QUERY_TYPE = 'bounces'
 
 export async function getBounces(
-  pathToFetch,
-  client,
-  dates,
-  version = null,
-  verbose = false,
-  queryType = QUERY_TYPE,
-) {
+  pathToFetch: string | string[],
+  client: KustoClient,
+  dates: DateRange,
+  version: string | null = null,
+  verbose: boolean = false,
+  queryType: string = QUERY_TYPE,
+): Promise<string> {
   const query = getBouncesQuery(pathToFetch, dates, version)
   const results = await runQuery(pathToFetch, query, client, queryType, verbose)
+
+  if (!results) {
+    return '0%'
+  }
+
   const data = JSON.parse(results.primaryResults[0].toString()).data[0]
   // Extract Bounces
   const bounces = data.Bounces
   return bounces
 }
 
-export function getBouncesQuery(pathToFetch, dates, version) {
+export function getBouncesQuery(
+  pathToFetch: string | string[],
+  dates: DateRange,
+  version: string | null,
+): string {
   return `
     ${SHARED_DECLARATIONS(pathToFetch, dates, version)}
     let _exits = () {
@@ -28,8 +39,8 @@ export function getBouncesQuery(pathToFetch, dates, version) {
     };
     _exits
     | summarize Bounces=round(
-        countif(exit_scroll_length < 0.1 and exit_visit_duration < 5) / 
-          toreal(count()), 
+        countif(exit_scroll_length < 0.1 and exit_visit_duration < 5) /
+          toreal(count()),
         2
       )
     | project Bounces=strcat(toint(

src/metrics/queries/bounces.js renamed to src/metrics/queries/bounces.ts

@@ -1,5 +1,11 @@
+import type { DateRange } from '@/metrics/lib/dates'
+
 // SHARED QUERY CONSTANTS
-export const SHARED_DECLARATIONS = (path, dates, version) =>
+export const SHARED_DECLARATIONS = (
+  path: string | string[],
+  dates: DateRange,
+  version: string | null,
+): string =>
   `
     let _article = dynamic(['${Array.isArray(path) ? path.join("', '") : path}']);
     let _articleType = dynamic(null);