From 2bd8b599283f4dfd8700caf22f16e50124ec6683 Mon Sep 17 00:00:00 2001
From: Peter van der Zee <github-public@qfox.nl>
Date: Thu, 13 Feb 2025 15:31:49 +0100
Subject: [PATCH] Refactor the analytics command

---
 src/cli.ts                                    |   2 +-
 src/commands/analytics/analytics-command.ts   | 112 ++++++++
 .../run-analytics.ts}                         | 259 +++++-------------
 src/commands/types.ts                         |   7 +
 src/flags.ts                                  |  19 +-
 src/utils/fs.ts                               |   2 +-
 src/utils/meow-with-subcommands.ts            |  13 +-
 7 files changed, 219 insertions(+), 195 deletions(-)
 create mode 100644 src/commands/analytics/analytics-command.ts
 rename src/commands/{analytics.ts => analytics/run-analytics.ts} (64%)
 create mode 100644 src/commands/types.ts

diff --git a/src/cli.ts b/src/cli.ts
index c847b1820..d4970c20b 100755
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -8,7 +8,7 @@ import updateNotifier from 'tiny-updater'
 import colors from 'yoctocolors-cjs'
 
 import { actionCommand } from './commands/action'
-import { analyticsCommand } from './commands/analytics'
+import { analyticsCommand } from './commands/analytics/analytics-command'
 import { auditLogCommand } from './commands/audit-log'
 import { cdxgenCommand } from './commands/cdxgen'
 import { dependenciesCommand } from './commands/dependencies'
diff --git a/src/commands/analytics/analytics-command.ts b/src/commands/analytics/analytics-command.ts
new file mode 100644
index 000000000..3a44f0765
--- /dev/null
+++ b/src/commands/analytics/analytics-command.ts
@@ -0,0 +1,112 @@
+import meowOrDie from 'meow'
+import colors from 'yoctocolors-cjs'
+
+import { runAnalytics } from './run-analytics.ts'
+import { commonFlags, outputFlags } from '../../flags'
+import { AuthError, InputError } from '../../utils/errors'
+import { getFlagListOutput } from '../../utils/output-formatting'
+import { getDefaultToken } from '../../utils/sdk.ts'
+
+import type { CliCommandConfig } from '../../utils/meow-with-subcommands'
+import type { CommandContext } from '../types.ts'
+
+const config: CliCommandConfig = {
+  commandName: 'analytics',
+  description: `Look up analytics data`,
+  hidden: false,
+  flags: {
+    ...commonFlags,
+    ...outputFlags,
+    scope: {
+      type: 'string',
+      shortFlag: 's',
+      default: 'org',
+      description:
+        "Scope of the analytics data - either 'org' or 'repo', default: org"
+    },
+    time: {
+      type: 'number',
+      shortFlag: 't',
+      default: 7,
+      description: 'Time filter - either 7, 30 or 90, default: 7'
+    },
+    repo: {
+      type: 'string',
+      shortFlag: 'r',
+      default: '',
+      description: 'Name of the repository'
+    },
+    file: {
+      type: 'string',
+      shortFlag: 'f',
+      default: '',
+      description: 'Path to a local file to save the output'
+    }
+  },
+  help: (parentName, { commandName, flags }) => `
+    Usage
+      $ ${parentName} ${commandName} --scope=<scope> --time=<time filter>
+
+    Default parameters are set to show the organization-level analytics over the
+    last 7 days.
+
+    Options
+      ${getFlagListOutput(flags, 6)}
+
+    Examples
+      $ ${parentName} ${commandName} --scope=org --time=7
+      $ ${parentName} ${commandName} --scope=org --time=30
+      $ ${parentName} ${commandName} --scope=repo --repo=test-repo --time=30
+  `
+}
+
+export const analyticsCommand = {
+  description: config.description,
+  hidden: config.hidden,
+  run: run
+}
+
+async function run(
+  argv: readonly string[],
+  importMeta: ImportMeta,
+  { parentName }: { parentName: string }
+): Promise<void> {
+  const cli = meowOrDie(config.help(parentName, config), {
+    argv,
+    description: config.description,
+    importMeta,
+    flags: config.flags
+  })
+
+  const { repo, scope, time } = cli.flags
+
+  if (scope !== 'org' && scope !== 'repo') {
+    throw new InputError("The scope must either be 'org' or 'repo'")
+  }
+
+  if (time !== 7 && time !== 30 && time !== 90) {
+    throw new InputError('The time filter must either be 7, 30 or 90')
+  }
+
+  if (scope === 'repo' && !repo) {
+    console.error(
+      `${colors.bgRed(colors.white('Input error'))}: Please provide a repository name when using the repository scope.`
+    )
+    cli.showHelp()
+  }
+
+  const apiToken = getDefaultToken()
+  if (!apiToken) {
+    throw new AuthError(
+      'User must be authenticated to run this command. To log in, run the command `socket login` and enter your API token.'
+    )
+  }
+
+  return await runAnalytics(apiToken, {
+    scope,
+    time,
+    repo,
+    outputJson: cli.flags['json'],
+    file: cli.flags['file']
+  } as CommandContext)
+}
diff --git a/src/commands/analytics.ts b/src/commands/analytics/run-analytics.ts
similarity index 64%
rename from src/commands/analytics.ts
rename to src/commands/analytics/run-analytics.ts
index 6c877206b..907d8158a 100644
--- a/src/commands/analytics.ts
+++ b/src/commands/analytics/run-analytics.ts
@@ -1,160 +1,46 @@
 import fs from 'node:fs/promises'
 
-// @ts-ignore
-import ScreenWidget from 'blessed/lib/widgets/screen'
-// @ts-ignore
-import GridLayout from 'blessed-contrib/lib/layout/grid'
-// @ts-ignore
-import BarChart from 'blessed-contrib/lib/widget/charts/bar'
-// @ts-ignore
-import LineChart from 'blessed-contrib/lib/widget/charts/line'
-import meow from 'meow'
-import colors from 'yoctocolors-cjs'
+import { Widgets } from 'blessed'
+import contrib from 'blessed-contrib'
 
 import { Spinner } from '@socketsecurity/registry/lib/spinner'
 
-import { commonFlags, outputFlags } from '../flags'
-import { handleApiCall, handleUnsuccessfulApiResponse } from '../utils/api'
-import { AuthError, InputError } from '../utils/errors'
-import { getFlagListOutput } from '../utils/output-formatting'
-import { getDefaultToken, setupSdk } from '../utils/sdk'
+import { handleApiCall, handleUnsuccessfulApiResponse } from '../../utils/api'
+import { setupSdk } from '../../utils/sdk'
 
-import type { CliSubcommand } from '../utils/meow-with-subcommands'
+import type { CommandContext } from '../types.ts'
 
-const description = `Look up analytics data\n                        Default parameters are set to show the organization-level analytics over the last 7 days.`
-
-export const analyticsCommand: CliSubcommand = {
-  description,
-  async run(argv, importMeta, { parentName }) {
-    const name = parentName + ' analytics'
-
-    const input = setupCommand(name, description, argv, importMeta)
-    if (input) {
-      const apiToken = getDefaultToken()
-      if (!apiToken) {
-        throw new AuthError(
-          'User must be authenticated to run this command. To log in, run the command `socket login` and enter your API key.'
-        )
-      }
-      const spinner = new Spinner({ text: 'Fetching analytics data' }).start()
-      if (input.scope === 'org') {
-        await fetchOrgAnalyticsData(
-          input.time,
-          spinner,
-          apiToken,
-          input.outputJson,
-          input.file
-        )
-      } else {
-        if (input.repo) {
-          await fetchRepoAnalyticsData(
-            input.repo,
-            input.time,
-            spinner,
-            apiToken,
-            input.outputJson,
-            input.file
-          )
-        }
-      }
-    }
-  }
-}
-
-const analyticsFlags = {
-  scope: {
-    type: 'string',
-    shortFlag: 's',
-    default: 'org',
-    description: "Scope of the analytics data - either 'org' or 'repo'"
-  },
-  time: {
-    type: 'number',
-    shortFlag: 't',
-    default: 7,
-    description: 'Time filter - either 7, 30 or 90'
-  },
-  repo: {
-    type: 'string',
-    shortFlag: 'r',
-    default: '',
-    description: 'Name of the repository'
-  },
-  file: {
-    type: 'string',
-    shortFlag: 'f',
-    default: '',
-    description: 'Path to a local file to save the output'
-  }
-}
-
-// Internal functions
-
-type CommandContext = {
-  scope: string
-  time: number
-  repo: string
-  outputJson: boolean
-  file: string
+type FormattedData = {
+  top_five_alert_types: { [key: string]: number }
+  total_critical_alerts: { [key: string]: number }
+  total_high_alerts: { [key: string]: number }
+  total_medium_alerts: { [key: string]: number }
+  total_low_alerts: { [key: string]: number }
+  total_critical_added: { [key: string]: number }
+  total_medium_added: { [key: string]: number }
+  total_low_added: { [key: string]: number }
+  total_high_added: { [key: string]: number }
+  total_critical_prevented: { [key: string]: number }
+  total_high_prevented: { [key: string]: number }
+  total_medium_prevented: { [key: string]: number }
+  total_low_prevented: { [key: string]: number }
 }
 
-function setupCommand(
-  name: string,
-  description: string,
-  argv: readonly string[],
-  importMeta: ImportMeta
-): void | CommandContext {
-  const flags: { [key: string]: any } = {
-    ...commonFlags,
-    ...outputFlags,
-    ...analyticsFlags
-  }
-  const cli = meow(
-    `
-    Usage
-      $ ${name} --scope=<scope> --time=<time filter>
-
-    Options
-      ${getFlagListOutput(flags, 6)}
-
-    Examples
-      $ ${name} --scope=org --time=7
-      $ ${name} --scope=org --time=30
-      $ ${name} --scope=repo --repo=test-repo --time=30
-  `,
-    {
-      argv,
-      description,
-      importMeta,
-      flags
-    }
-  )
-  const { repo, scope, time } = cli.flags
-  if (scope !== 'org' && scope !== 'repo') {
-    throw new InputError("The scope must either be 'org' or 'repo'")
-  }
-  if (time !== 7 && time !== 30 && time !== 90) {
-    throw new InputError('The time filter must either be 7, 30 or 90')
-  }
-  let showHelp = cli.flags['help']
-  if (scope === 'repo' && !repo) {
-    showHelp = true
-    console.error(
-      `${colors.bgRed(colors.white('Input error'))}: Please provide a repository name when using the repository scope.`
-    )
-  }
-  if (showHelp) {
-    cli.showHelp()
-    return
-  }
-  return <CommandContext>{
-    scope,
-    time,
-    repo,
-    outputJson: cli.flags['json'],
-    file: cli.flags['file']
-  }
-}
+// Note: This maps `new Date(date).getMonth()` to English three letters
+export const Months = [
+  'Jan',
+  'Feb',
+  'Mar',
+  'Apr',
+  'May',
+  'Jun',
+  'Jul',
+  'Aug',
+  'Sep',
+  'Oct',
+  'Nov',
+  'Dec'
+] as const
 
 const METRICS = [
   'total_critical_alerts',
@@ -171,24 +57,38 @@ const METRICS = [
   'total_low_prevented'
 ] as const
 
-const MONTHS = [
-  'Jan',
-  'Feb',
-  'Mar',
-  'Apr',
-  'May',
-  'Jun',
-  'Jul',
-  'Aug',
-  'Sep',
-  'Oct',
-  'Nov',
-  'Dec'
-] as const
+export async function runAnalytics(
+  apiToken: string,
+  input: CommandContext
+): Promise<void> {
+  if (input) {
+    const spinner = new Spinner({ text: 'Fetching analytics data' }).start()
+    if (input.scope === 'org') {
+      await fetchOrgAnalyticsData(
+        input.time,
+        spinner,
+        apiToken,
+        input.outputJson,
+        input.file
+      )
+    } else {
+      if (input.repo) {
+        await fetchRepoAnalyticsData(
+          input.repo,
+          input.time,
+          spinner,
+          apiToken,
+          input.outputJson,
+          input.file
+        )
+      }
+    }
+  }
+}
 
-function displayAnalyticsScreen(data: any) {
-  const screen = new ScreenWidget()
-  const grid = new GridLayout({ rows: 5, cols: 4, screen })
+function displayAnalyticsScreen(data: FormattedData): void {
+  const screen = new Widgets.Screen({})
+  const grid = new contrib.grid({ rows: 5, cols: 4, screen })
 
   renderLineCharts(
     grid,
@@ -247,7 +147,7 @@ function displayAnalyticsScreen(data: any) {
     data['total_low_prevented']
   )
 
-  const bar = grid.set(4, 0, 1, 2, BarChart, {
+  const bar = grid.set(4, 0, 1, 2, contrib.bar, {
     label: 'Top 5 alert types',
     barWidth: 10,
     barSpacing: 17,
@@ -350,22 +250,6 @@ async function fetchRepoAnalyticsData(
   return displayAnalyticsScreen(data)
 }
 
-type FormattedData = {
-  top_five_alert_types: { [key: string]: number }
-  total_critical_alerts: { [key: string]: number }
-  total_high_alerts: { [key: string]: number }
-  total_medium_alerts: { [key: string]: number }
-  total_low_alerts: { [key: string]: number }
-  total_critical_added: { [key: string]: number }
-  total_medium_added: { [key: string]: number }
-  total_low_added: { [key: string]: number }
-  total_high_added: { [key: string]: number }
-  total_critical_prevented: { [key: string]: number }
-  total_high_prevented: { [key: string]: number }
-  total_medium_prevented: { [key: string]: number }
-  total_low_prevented: { [key: string]: number }
-}
-
 function formatData(
   data: { [key: string]: any }[],
   scope: string
@@ -431,19 +315,18 @@ function formatData(
     top_five_alert_types: sortedTopFiveAlerts
   }
 }
-
-function formatDate(date: string) {
-  return `${MONTHS[new Date(date).getMonth()]} ${new Date(date).getDate()}`
+function formatDate(date: string): string {
+  return `${Months[new Date(date).getMonth()]} ${new Date(date).getDate()}`
 }
 
 function renderLineCharts(
-  grid: any,
+  grid: contrib.grid,
   screen: any,
   title: string,
   coords: number[],
   data: { [key: string]: number }
-) {
-  const line = grid.set(...coords, LineChart, {
+): void {
+  const line = grid.set(...coords, contrib.line, {
     style: { line: 'cyan', text: 'cyan', baseline: 'black' },
     xLabelPadding: 0,
     xPadding: 0,
diff --git a/src/commands/types.ts b/src/commands/types.ts
new file mode 100644
index 000000000..d3e4e28fa
--- /dev/null
+++ b/src/commands/types.ts
@@ -0,0 +1,7 @@
+export interface CommandContext {
+  scope: string
+  time: number
+  repo: string
+  outputJson: boolean
+  file: string
+}
diff --git a/src/flags.ts b/src/flags.ts
index 19d7907ab..82cfd7346 100644
--- a/src/flags.ts
+++ b/src/flags.ts
@@ -1,4 +1,15 @@
-export const commonFlags = {
+import type { Flag } from 'meow'
+
+// TODO: not sure if I'm missing something but meow doesn't seem to expose this?
+type StringFlag = Flag<'string', string> | Flag<'string', string[], true>
+type BooleanFlag = Flag<'boolean', boolean> | Flag<'boolean', boolean[], true>
+type NumberFlag = Flag<'number', number> | Flag<'number', number[], true>
+type AnyFlag = StringFlag | BooleanFlag | NumberFlag
+
+// Note: we use this description in getFlagListOutput, meow doesn't care
+export type MeowFlags = Record<string, AnyFlag & { description: string }>
+
+export const commonFlags: MeowFlags = {
   help: {
     type: 'boolean',
     default: false,
@@ -7,7 +18,7 @@ export const commonFlags = {
   }
 }
 
-export const commandFlags = {
+export const commandFlags: MeowFlags = {
   enable: {
     type: 'boolean',
     default: false,
@@ -20,7 +31,7 @@ export const commandFlags = {
   }
 }
 
-export const outputFlags = {
+export const outputFlags: MeowFlags = {
   json: {
     type: 'boolean',
     shortFlag: 'j',
@@ -35,7 +46,7 @@ export const outputFlags = {
   }
 }
 
-export const validationFlags = {
+export const validationFlags: MeowFlags = {
   all: {
     type: 'boolean',
     default: false,
diff --git a/src/utils/fs.ts b/src/utils/fs.ts
index e92661f8e..52ce1944a 100644
--- a/src/utils/fs.ts
+++ b/src/utils/fs.ts
@@ -8,7 +8,7 @@ import type { FileHandle } from 'node:fs/promises'
 
 export async function findUp(
   name: string | string[],
-  { cwd = process.cwd() }: { cwd: string | undefined }
+  { cwd = process.cwd() }: { cwd: string }
 ): Promise<string | undefined> {
   let dir = path.resolve(cwd)
   const { root } = path.parse(dir)
diff --git a/src/utils/meow-with-subcommands.ts b/src/utils/meow-with-subcommands.ts
index 9c62210e5..6f4fd8e3d 100644
--- a/src/utils/meow-with-subcommands.ts
+++ b/src/utils/meow-with-subcommands.ts
@@ -3,7 +3,7 @@ import meow from 'meow'
 import { toSortedObject } from '@socketsecurity/registry/lib/objects'
 
 import { getFlagListOutput, getHelpListOutput } from './output-formatting'
-import { commonFlags } from '../flags'
+import { MeowFlags, commonFlags } from '../flags'
 
 import type { Options } from 'meow'
 
@@ -27,6 +27,17 @@ export interface CliSubcommand {
   run: CliSubcommandRun
 }
 
+// Property names are picked such that the name is at the top when the props
+// get ordered by alphabet while flags is near the bottom and the help text
+// at the bottom, because they tend ot occupy the most lines of code.
+export interface CliCommandConfig {
+  commandName: string // tmp optional while we migrate
+  description: string
+  hidden: boolean
+  flags: MeowFlags // tmp optional while we migrate
+  help: (parentName: string, config: CliCommandConfig) => string
+}
+
 interface MeowOptions extends Options<any> {
   aliases?: CliAliases
   argv: readonly string[]