refactor(linter/plugins): move assertions into own file (#15945)

overlookmotel · overlookmotel · commit 512e43a204b2 · 2025-11-21T14:42:25.000Z
Pure refactor. Split up `plugins/utils.ts` into 3 files in `utils` directory. Most importantly, assertion functions are by themselves in an `asserts.ts` file. This paves the way for the next PR (#15946).
diff --git a/apps/oxlint/src-js/index.ts b/apps/oxlint/src-js/index.ts
@@ -1,11 +1,11 @@
-import { assertIsNonNull } from './plugins/utils.js';
+import { assertIsNonNull } from './utils/asserts.js';
 
 import type { Context, FileContext, LanguageOptions } from './plugins/context.ts';
 import type { CreateOnceRule, Plugin, Rule } from './plugins/load.ts';
 import type { Settings } from './plugins/settings.ts';
 import type { SourceCode } from './plugins/source_code.ts';
 import type { BeforeHook, Visitor, VisitorWithHooks } from './plugins/types.ts';
-import type { SetNullable } from './plugins/utils.ts';
+import type { SetNullable } from './utils/types.ts';
 
 export type * as ESTree from './generated/types.d.ts';
 export type { Context, LanguageOptions } from './plugins/context.ts';
diff --git a/apps/oxlint/src-js/plugins/comments.ts b/apps/oxlint/src-js/plugins/comments.ts
@@ -3,7 +3,7 @@
  */
 
 import { ast, initAst, sourceText } from './source_code.js';
-import { assertIsNonNull } from './utils.js';
+import { assertIsNonNull } from '../utils/asserts.js';
 
 import type { Comment, Node, NodeOrToken } from './types.ts';
 
diff --git a/apps/oxlint/src-js/plugins/context.ts b/apps/oxlint/src-js/plugins/context.ts
@@ -29,7 +29,7 @@
 import { ast, initAst, SOURCE_CODE } from './source_code.js';
 import { report } from './report.js';
 import { settings, initSettings } from './settings.js';
-import { assertIsNonNull } from './utils.js';
+import { assertIsNonNull } from '../utils/asserts.js';
 
 import type { Options, RuleDetails } from './load.ts';
 import type { Diagnostic } from './report.ts';
diff --git a/apps/oxlint/src-js/plugins/fix.ts b/apps/oxlint/src-js/plugins/fix.ts
@@ -1,4 +1,4 @@
-import { assertIs } from './utils.js';
+import { assertIs } from '../utils/asserts.js';
 
 import type { RuleDetails } from './load.ts';
 import type { Range, Ranged } from './location.ts';
diff --git a/apps/oxlint/src-js/plugins/lint.ts b/apps/oxlint/src-js/plugins/lint.ts
@@ -3,7 +3,8 @@ import { registeredRules } from './load.js';
 import { diagnostics } from './report.js';
 import { setSettingsForFile, resetSettings } from './settings.js';
 import { ast, initAst, resetSourceAndAst, setupSourceForFile } from './source_code.js';
-import { assertIs, assertIsNonNull, getErrorMessage } from './utils.js';
+import { assertIs, assertIsNonNull } from '../utils/asserts.js';
+import { getErrorMessage } from '../utils/utils.js';
 import { addVisitorToCompiled, compiledVisitor, finalizeCompiledVisitor, initCompiledVisitor } from './visitor.js';
 
 // Lazy implementation
diff --git a/apps/oxlint/src-js/plugins/load.ts b/apps/oxlint/src-js/plugins/load.ts
@@ -1,14 +1,14 @@
 import { pathToFileURL } from 'node:url';
 
 import { createContext } from './context.js';
-import { getErrorMessage } from './utils.js';
+import { getErrorMessage } from '../utils/utils.js';
 
 import type { Writable } from 'type-fest';
 import type { Context } from './context.ts';
 import type { JsonValue } from './json.ts';
 import type { RuleMeta } from './rule_meta.ts';
 import type { AfterHook, BeforeHook, Visitor, VisitorWithHooks } from './types.ts';
-import type { SetNullable } from './utils.ts';
+import type { SetNullable } from '../utils/types.ts';
 
 const ObjectKeys = Object.keys;
 
diff --git a/apps/oxlint/src-js/plugins/location.ts b/apps/oxlint/src-js/plugins/location.ts
@@ -4,7 +4,7 @@
  */
 
 import { initSourceText, sourceText } from './source_code.js';
-import { assertIsNonNull } from './utils.js';
+import { assertIsNonNull } from '../utils/asserts.js';
 
 import type { Node } from './types.ts';
 
diff --git a/apps/oxlint/src-js/plugins/scope.ts b/apps/oxlint/src-js/plugins/scope.ts
@@ -8,10 +8,10 @@ import {
   type ScopeManager as TSESLintScopeManager,
 } from '@typescript-eslint/scope-manager';
 import { ast, initAst } from './source_code.js';
-import { assertIs, assertIsNonNull } from './utils.js';
+import { assertIs, assertIsNonNull } from '../utils/asserts.js';
 
 import type * as ESTree from '../generated/types.d.ts';
-import type { SetNullable } from './utils.ts';
+import type { SetNullable } from '../utils/types.ts';
 
 export interface Scope {
   type: ScopeType;
diff --git a/apps/oxlint/src-js/plugins/settings.ts b/apps/oxlint/src-js/plugins/settings.ts
@@ -3,7 +3,7 @@
  */
 
 import { deepFreezeJsonValue } from './json.js';
-import { assertIsNonNull } from './utils.js';
+import { assertIsNonNull } from '../utils/asserts.js';
 
 import type { JsonObject } from './json.ts';
 
diff --git a/apps/oxlint/src-js/plugins/source_code.ts b/apps/oxlint/src-js/plugins/source_code.ts
@@ -18,7 +18,7 @@ import {
 import { resetScopeManager, SCOPE_MANAGER } from './scope.js';
 import * as scopeMethods from './scope.js';
 import * as tokenMethods from './tokens.js';
-import { assertIsNonNull } from './utils.js';
+import { assertIsNonNull } from '../utils/asserts.js';
 
 import type { Program } from '../generated/types.d.ts';
 import type { Ranged } from './location.ts';
diff --git a/apps/oxlint/src-js/plugins/tokens.ts b/apps/oxlint/src-js/plugins/tokens.ts
@@ -3,7 +3,7 @@
  */
 
 import { sourceText, initSourceText } from './source_code.js';
-import { assertIsNonNull } from './utils.js';
+import { assertIsNonNull } from '../utils/asserts.js';
 
 import type { Comment, Node, NodeOrToken, Token } from './types.ts';
 
diff --git a/apps/oxlint/src-js/plugins/utils.ts b/apps/oxlint/src-js/plugins/utils.ts
diff --git a/apps/oxlint/src-js/plugins/visitor.ts b/apps/oxlint/src-js/plugins/visitor.ts
@@ -76,7 +76,7 @@ import { LEAF_NODE_TYPES_COUNT, NODE_TYPE_IDS_MAP, NODE_TYPES_COUNT } from '../g
 import { parseSelector, wrapVisitFnWithSelectorMatch } from './selector.js';
 
 import type { CompiledVisitorEntry, EnterExit, Node, VisitFn, Visitor } from './types.ts';
-import { assertIs, assertIsNonNull } from './utils.js';
+import { assertIs, assertIsNonNull } from '../utils/asserts.js';
 
 const ObjectKeys = Object.keys,
   { isArray } = Array;
diff --git a/apps/oxlint/src-js/utils/asserts.ts b/apps/oxlint/src-js/utils/asserts.ts
@@ -0,0 +1,27 @@
+/**
+ * Assert a value is of a certain type.
+ *
+ * Has no runtime effect - only for guiding the type-checker.
+ * Minification removes this function and all calls to it, so it has zero runtime cost.
+ *
+ * @param value - Value
+ */
+// oxlint-disable-next-line no-unused-vars
+export function assertIs<T>(value: unknown): asserts value is T {}
+
+/**
+ * Assert a value is not `null` or `undefined`.
+ *
+ * In release builds, is a no-op. Only does runtime checks in debug builds.
+ * Minification removes this function and all calls to it in release builds, so it has zero runtime cost.
+ *
+ * @param value - Value
+ */
+export function assertIsNonNull<T>(value: T | null | undefined): asserts value is T {
+  if (!DEBUG) return;
+
+  if (value === null || value === undefined) {
+    // oxlint-disable-next-line typescript/restrict-template-expressions
+    throw new Error(`Expected non-null value, got ${value}`);
+  }
+}
diff --git a/apps/oxlint/src-js/utils/types.ts b/apps/oxlint/src-js/utils/types.ts
@@ -0,0 +1,13 @@
+/**
+ * Utility type to make specified properties of a type nullable.
+ *
+ * @example
+ * ```ts
+ * type Foo = { str: string, num: number };
+ * type FooWithNullableNum = SetNullable<Foo, 'num'>;
+ * // { str: string, num: number | null }
+ * ```
+ */
+export type SetNullable<BaseType, Keys extends keyof BaseType = keyof BaseType> = {
+  [Key in keyof BaseType]: Key extends Keys ? BaseType[Key] | null : BaseType[Key];
+};
diff --git a/apps/oxlint/src-js/utils/utils.ts b/apps/oxlint/src-js/utils/utils.ts
@@ -0,0 +1,32 @@
+/**
+ * Get error message from an error.
+ *
+ * `err` is expected to be an `Error` object, but can be anything.
+ *
+ * * If it's an `Error`, the error message and stack trace is returned.
+ * * If it's another object with a string `message` property, `message` is returned.
+ * * Otherwise, a generic "Unknown error" message is returned.
+ *
+ * This function will never throw, and always returns a non-empty string, even if:
+ *
+ * * `err` is `null` or `undefined`.
+ * * `err` is an object with a getter for `message` property which throws.
+ * * `err` has a getter for `stack` or `message` property which returns a different value each time it's accessed.
+ *
+ * @param err - Error
+ * @returns Error message
+ */
+export function getErrorMessage(err: unknown): string {
+  try {
+    if (err instanceof Error) {
+      // Note: `stack` includes the error message
+      const { stack } = err;
+      if (typeof stack === 'string' && stack !== '') return stack;
+    }
+
+    const { message } = err as { message?: unknown };
+    if (typeof message === 'string' && message !== '') return message;
+  } catch {}
+
+  return 'Unknown error';
+}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { assertIs } from './utils.js';`
	`1`	`+import { assertIs } from '../utils/asserts.js';`
`2`	`2`
`3`	`3`	`import type { RuleDetails } from './load.ts';`
`4`	`4`	`import type { Range, Ranged } from './location.ts';`