Fix ESLint errors, add some docs

app/common/src/accessToken.ts

@@ -14,7 +14,9 @@ export interface AccessToken {
  readonly refreshToken: string
  /** The Cognito url to refresh the token. */
  readonly refreshUrl: string
- /** The when the token will expire.
- * This is a string representation of a date in ISO 8601 format (e.g. "2021-01-01T00:00:00Z"). */
+ /**
+ * The when the token will expire.
+ * This is a string representation of a date in ISO 8601 format (e.g. "2021-01-01T00:00:00Z").
+ */
  readonly expireAt: string
 }

app/common/src/appConfig.d.ts

@@ -1,17 +1,21 @@
 /** @file Functions for managing app configuration. */
 
-/** Read environment variables from a file based on the `ENSO_CLOUD_ENV_FILE_NAME`
+/**
+ * Read environment variables from a file based on the `ENSO_CLOUD_ENV_FILE_NAME`
  * environment variable. Reads from `.env` if the variable is blank or absent.
- * DOES NOT override existing environment variables if the variable is absent. */
+ * DOES NOT override existing environment variables if the variable is absent.
+ */
 export function readEnvironmentFromFile(): Promise<void>
 
-/** An object containing app configuration to inject.
+/**
+ * An object containing app configuration to inject.
  *
  * This includes:
  * - the base URL for backend endpoints
  * - the WebSocket URL for the chatbot
  * - the unique identifier for the cloud environment, for use in Sentry logs
- * - Stripe, Sentry and Amplify public keys */
+ * - Stripe, Sentry and Amplify public keys
+ */
 export function getDefines(serverPort?: number): Record<string, string>
 
 /** Load test environment variables, useful for when the Cloud backend is mocked or unnecessary. */

app/common/src/appConfig.js

@@ -1,6 +1,7 @@
 /** @file Functions for managing app configuration. */
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
+import * as process from 'node:process'
 import * as url from 'node:url'
 
 // ===============================
@@ -19,14 +20,13 @@ export async function readEnvironmentFromFile() {
  const filePath = path.join(url.fileURLToPath(new URL('../..', import.meta.url)), fileName)
  const buildInfo = await (async () => {
  try {
- return await import('../../../../build.json', { with: { type: 'json' } })
+ return await import('../../../build.json', { with: { type: 'json' } })
  } catch {
  return { commit: '', version: '', engineVersion: '', name: '' }
  }
  })()
  try {
  const file = await fs.readFile(filePath, { encoding: 'utf-8' })
- // eslint-disable-next-line jsdoc/valid-types
  /** @type {readonly (readonly [string, string])[]} */
  let entries = file.split('\n').flatMap(line => {
  if (/^\s*$|^.s*#/.test(line)) {
@@ -47,14 +47,10 @@ export async function readEnvironmentFromFile() {
  if (!isProduction || entries.length > 0) {
  Object.assign(process.env, variables)
  }
- // @ts-expect-error This is the only file where `process.env` should be written to.
  process.env.ENSO_CLOUD_DASHBOARD_VERSION ??= buildInfo.version
- // @ts-expect-error This is the only file where `process.env` should be written to.
  process.env.ENSO_CLOUD_DASHBOARD_COMMIT_HASH ??= buildInfo.commit
  } catch (error) {
- // @ts-expect-error This is the only file where `process.env` should be written to.
  process.env.ENSO_CLOUD_DASHBOARD_VERSION ??= buildInfo.version
- // @ts-expect-error This is the only file where `process.env` should be written to.
  process.env.ENSO_CLOUD_DASHBOARD_COMMIT_HASH ??= buildInfo.commit
  const expectedKeys = Object.keys(DUMMY_DEFINES)
  .map(key => key.replace(/^process[.]env[.]/, ''))
@@ -147,7 +143,6 @@ const DUMMY_DEFINES = {
 /** Load test environment variables, useful for when the Cloud backend is mocked or unnecessary. */
 export function loadTestEnvironmentVariables() {
  for (const [k, v] of Object.entries(DUMMY_DEFINES)) {
- // @ts-expect-error This is the only file where `process.env` should be written to.
  process.env[k.replace(/^process[.]env[.]/, '')] = v
  }
 }

app/common/src/buildUtils.d.ts

@@ -3,26 +3,34 @@
 /** Indent size for stringifying JSON. */
 export const INDENT_SIZE: number
 
-/** Get the environment variable value.
+/**
+ * Get the environment variable value.
  * @param name - The name of the environment variable.
  * @returns The value of the environment variable.
- * @throws {Error} If the environment variable is not set. */
+ * @throws {Error} If the environment variable is not set.
+ */
 export function requireEnv(name: string): string
 
-/** Read the path from environment variable and resolve it.
+/**
+ * Read the path from environment variable and resolve it.
  * @param name - The name of the environment variable.
  * @returns The resolved path.
- * @throws {Error} If the environment variable is not set. */
+ * @throws {Error} If the environment variable is not set.
+ */
 export function requireEnvResolvedPath(name: string): string
 
-/** Read the path from environment variable and resolve it. Verify that it exists.
+/**
+ * Read the path from environment variable and resolve it. Verify that it exists.
  * @param name - The name of the environment variable.
  * @returns The resolved path.
- * @throws {Error} If the environment variable is not set or path does not exist. */
+ * @throws {Error} If the environment variable is not set or path does not exist.
+ */
 export function requireEnvPathExist(name: string): string
 
-/** Get the common prefix of the two strings.
+/**
+ * Get the common prefix of the two strings.
  * @param a - the first string.
  * @param b - the second string.
- * @returns The common prefix. */
+ * @returns The common prefix.
+ */
 export function getCommonPrefix(a: string, b: string): string

app/common/src/detect.ts

@@ -23,8 +23,10 @@ export enum Platform {
  android = 'Android',
 }
 
-/** The platform the app is currently running on.
- * This is used to determine whether `metaKey` or `ctrlKey` is used in shortcuts. */
+/**
+ * The platform the app is currently running on.
+ * This is used to determine whether `metaKey` or `ctrlKey` is used in shortcuts.
+ */
 export function platform() {
  if (isOnWindowsPhone()) {
  // MUST be before Android and Windows.
@@ -96,8 +98,10 @@ export enum Browser {
  opera = 'Opera',
 }
 
-/** Return the platform the app is currently running on.
- * This is used to determine whether `metaKey` or `ctrlKey` is used in shortcuts. */
+/**
+ * Return the platform the app is currently running on.
+ * This is used to determine whether `metaKey` or `ctrlKey` is used in shortcuts.
+ */
 export function browser(): Browser {
  if (isOnElectron()) {
  return Browser.electron
@@ -117,10 +121,12 @@ export function browser(): Browser {
  return Browser.unknown
  }
 }
-/** Returns `true` if running in Electron, else `false`.
+/**
+ * Returns `true` if running in Electron, else `false`.
  * This is used to determine whether to use a `MemoryRouter` (stores history in an array)
  * or a `BrowserRouter` (stores history in the path of the URL).
- * It is also used to determine whether to send custom state to Amplify for a workaround. */
+ * It is also used to determine whether to send custom state to Amplify for a workaround.
+ */
 export function isOnElectron() {
  return /electron/i.test(navigator.userAgent)
 }

app/common/src/gtag.ts

@@ -17,7 +17,7 @@ window.dataLayer = window.dataLayer || []
 export function gtag(_action: 'config' | 'event' | 'js' | 'set', ..._args: unknown[]) {
  // @ts-expect-error This is explicitly not given types as it is a mistake to acess this
  // anywhere else.
- // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, prefer-rest-params
  window.dataLayer.push(arguments)
 }
 
@@ -27,7 +27,7 @@ export function event(name: string, params?: object) {
 }
 
 gtag('js', new Date())
-// eslint-disable-next-line @typescript-eslint/naming-convention
+// eslint-disable-next-line @typescript-eslint/naming-convention, camelcase
 gtag('set', 'linker', { accept_incoming: true })
 gtag('config', GOOGLE_ANALYTICS_TAG)
 if (GOOGLE_ANALYTICS_TAG === 'G-CLTBJ37MDM') {

app/common/src/index.d.ts

@@ -1,18 +1,22 @@
-/** @file This module contains metadata about the product and distribution,
+/**
+ * @file This module contains metadata about the product and distribution,
  * and various other constants that are needed in multiple sibling packages.
  *
  * Code in this package is used by two or more sibling packages of this package. The code is defined
  * here when it is not possible for a sibling package to own that code without introducing a
- * circular dependency in our packages. */
+ * circular dependency in our packages.
+ */
 
 // ========================
 // === Product metadata ===
 // ========================
 
-/** URL protocol scheme for deep links to authentication flow pages, without the `:` suffix.
+/**
+ * URL protocol scheme for deep links to authentication flow pages, without the `:` suffix.
  *
  * For example: the deep link URL
- * `enso://authentication/register?code=...&state=...` uses this scheme. */
+ * `enso://authentication/register?code=...&state=...` uses this scheme.
+ */
 export const DEEP_LINK_SCHEME: string
 
 /** Name of the product. */
@@ -21,12 +25,16 @@ export const PRODUCT_NAME: string
 /** Company name, used as the copyright holder. */
 export const COMPANY_NAME: string
 
-/** The domain on which the Cloud Dashboard web app is hosted.
- * Excludes the protocol (`https://`). */
+/**
+ * The domain on which the Cloud Dashboard web app is hosted.
+ * Excludes the protocol (`https://`).
+ */
 export const CLOUD_DASHBOARD_DOMAIN: string
 
-/** COOP, COEP, and CORP headers: https://web.dev/coop-coep/
+/**
+ * COOP, COEP, and CORP headers: https://web.dev/coop-coep/
  *
  * These are required to increase the resolution of `performance.now()` timers,
- * making profiling a lot more accurate and consistent. */
+ * making profiling a lot more accurate and consistent.
+ */
 export const COOP_COEP_CORP_HEADERS: [header: string, value: string][]