refactor(linter/plugins): rename assertion functions (#15968)

Rename assertion functions to clarify that they're not "real" assertions which we can rely on for validating input, and are only for compile-time testing or debug assertions.

`typeAssertIs` is not a great name, but I couldn't come up with anything better. `debugAssertIs` would be not be accurate, as it'd imply that in debug builds in performs an actual assertion, which it doesn't.

In any case, we should replace `typeAssertIs` with specialized assertion functions which do actually perform runtime assertions in debug builds (e.g. `typeAssertIs<Fix>()` -> `debugAssertIsFix()`).

Author: overlookmotel

apps/oxlint/src-js/cli.ts

@@ -1,5 +1,5 @@
 import { lint } from './bindings.js';
-import { assertIsNonNull } from './utils/asserts.js';
+import { debugAssertIsNonNull } from './utils/asserts.js';
 
 // Lazy-loaded JS plugin-related functions.
 // Using `typeof wrapper` here makes TS check that the function signatures of `loadPlugin` and `loadPluginWrapper`
@@ -25,7 +25,7 @@ function loadPluginWrapper(path: string, packageName: string | null): Promise<st
       return loadPlugin(path, packageName);
     });
   }
-  assertIsNonNull(loadPlugin);
+  debugAssertIsNonNull(loadPlugin);
   return loadPlugin(path, packageName);
 }
 
@@ -50,7 +50,7 @@ function lintFileWrapper(
 ): string {
   // `lintFileWrapper` is never called without `loadPluginWrapper` being called first,
   // so `lintFile` must be defined here
-  assertIsNonNull(lintFile);
+  debugAssertIsNonNull(lintFile);
   return lintFile(filePath, bufferId, buffer, ruleIds, settingsJSON);
 }
 

apps/oxlint/src-js/index.ts

@@ -1,4 +1,4 @@
-import { assertIsNonNull } from './utils/asserts.js';
+import { debugAssertIsNonNull } from './utils/asserts.js';
 
 import type { Context, FileContext, LanguageOptions } from './plugins/context.ts';
 import type { CreateOnceRule, Plugin, Rule } from './plugins/load.ts';
@@ -129,7 +129,7 @@ export function defineRule(rule: Rule): Rule {
     if (context === null) {
       ({ context, visitor, beforeHook } = createContextAndVisitor(rule));
     }
-    assertIsNonNull(visitor);
+    debugAssertIsNonNull(visitor);
 
     // Copy properties from ESLint's context object to `context`.
     // ESLint's context object is an object of form `{ id, options, report }`, with all other properties

apps/oxlint/src-js/plugins/comments.ts

@@ -3,7 +3,7 @@
  */
 
 import { ast, initAst, sourceText } from './source_code.js';
-import { assertIsNonNull } from '../utils/asserts.js';
+import { debugAssertIsNonNull } from '../utils/asserts.js';
 
 import type { Comment, Node, NodeOrToken } from './types.ts';
 
@@ -16,7 +16,7 @@ const WHITESPACE_ONLY_REGEXP = /^\s*$/;
  */
 export function getAllComments(): Comment[] {
   if (ast === null) initAst();
-  assertIsNonNull(ast);
+  debugAssertIsNonNull(ast);
 
   // `comments` property is a getter. Comments are deserialized lazily.
   return ast.comments;
@@ -41,8 +41,8 @@ export function getAllComments(): Comment[] {
  */
 export function getCommentsBefore(nodeOrToken: NodeOrToken): Comment[] {
   if (ast === null) initAst();
-  assertIsNonNull(ast);
-  assertIsNonNull(sourceText);
+  debugAssertIsNonNull(ast);
+  debugAssertIsNonNull(sourceText);
 
   const { comments } = ast,
     commentsLength = comments.length;
@@ -98,8 +98,8 @@ export function getCommentsBefore(nodeOrToken: NodeOrToken): Comment[] {
  */
 export function getCommentsAfter(nodeOrToken: NodeOrToken): Comment[] {
   if (ast === null) initAst();
-  assertIsNonNull(ast);
-  assertIsNonNull(sourceText);
+  debugAssertIsNonNull(ast);
+  debugAssertIsNonNull(sourceText);
 
   const { comments } = ast,
     commentsLength = comments.length;
@@ -142,7 +142,7 @@ export function getCommentsAfter(nodeOrToken: NodeOrToken): Comment[] {
  */
 export function getCommentsInside(node: Node): Comment[] {
   if (ast === null) initAst();
-  assertIsNonNull(ast);
+  debugAssertIsNonNull(ast);
 
   const { comments } = ast,
     commentsLength = comments.length;
@@ -186,7 +186,7 @@ export function getCommentsInside(node: Node): Comment[] {
  */
 export function commentsExistBetween(nodeOrToken1: NodeOrToken, nodeOrToken2: NodeOrToken): boolean {
   if (ast === null) initAst();
-  assertIsNonNull(ast);
+  debugAssertIsNonNull(ast);
 
   // Find the first comment after `nodeOrToken1` ends.
   const { comments } = ast,

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/asserts.js';
+import { debugAssertIsNonNull } from '../utils/asserts.js';
 
 import type { Options, RuleDetails } from './load.ts';
 import type { Diagnostic } from './report.ts';
@@ -79,7 +79,7 @@ const PARSER_OPTIONS = freeze({
     // in case it's used in `create` to return an empty visitor if wrong type.
     // TODO: ESLint also has `commonjs` option.
     if (ast === null) initAst();
-    assertIsNonNull(ast);
+    debugAssertIsNonNull(ast);
 
     return ast.sourceType;
   },
@@ -95,7 +95,7 @@ const LANGUAGE_OPTIONS = freeze({
     // in case it's used in `create` to return an empty visitor if wrong type.
     // TODO: ESLint also has `commonjs` option.
     if (ast === null) initAst();
-    assertIsNonNull(ast);
+    debugAssertIsNonNull(ast);
 
     return ast.sourceType;
   },
@@ -257,7 +257,7 @@ const FILE_CONTEXT = freeze({
     if (filePath === null) throw new Error('Cannot access `context.settings` in `createOnce`');
 
     if (settings === null) initSettings();
-    assertIsNonNull(settings);
+    debugAssertIsNonNull(settings);
 
     return settings;
   },

apps/oxlint/src-js/plugins/fix.ts

@@ -1,4 +1,4 @@
-import { assertIs } from '../utils/asserts.js';
+import { typeAssertIs } from '../utils/asserts.js';
 
 import type { RuleDetails } from './load.ts';
 import type { Range, Ranged } from './location.ts';
@@ -159,7 +159,7 @@ export function getFixes(diagnostic: Diagnostic, ruleDetails: RuleDetails): Fix[
  * @returns `Fix` object
  */
 function validateAndConformFix(fix: unknown): Fix {
-  assertIs<Fix>(fix);
+  typeAssertIs<Fix>(fix);
   let { range, text } = fix;
 
   // These checks follow ESLint, which throws if `range` is missing or invalid

apps/oxlint/src-js/plugins/lint.ts

@@ -3,7 +3,7 @@ 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 } from '../utils/asserts.js';
+import { typeAssertIs, debugAssertIsNonNull } from '../utils/asserts.js';
 import { getErrorMessage } from '../utils/utils.js';
 import { addVisitorToCompiled, compiledVisitor, finalizeCompiledVisitor, initCompiledVisitor } from './visitor.js';
 
@@ -87,7 +87,7 @@ function lintFileImpl(
     // Rust will only send a `bufferId` alone, if it previously sent a buffer with this same ID
     buffer = buffers[bufferId]!;
   } else {
-    assertIs<BufferWithArrays>(buffer);
+    typeAssertIs<BufferWithArrays>(buffer);
     const { buffer: arrayBuffer, byteOffset } = buffer;
     buffer.uint32 = new Uint32Array(arrayBuffer, byteOffset);
     buffer.float64 = new Float64Array(arrayBuffer, byteOffset);
@@ -97,7 +97,7 @@ function lintFileImpl(
     }
     buffers[bufferId] = buffer;
   }
-  assertIs<BufferWithArrays>(buffer);
+  typeAssertIs<BufferWithArrays>(buffer);
 
   if (DEBUG) {
     if (typeof filePath !== 'string' || filePath.length === 0) {
@@ -139,7 +139,7 @@ function lintFileImpl(
     let { visitor } = ruleDetails;
     if (visitor === null) {
       // Rule defined with `create` method
-      assertIsNonNull(ruleDetails.rule.create);
+      debugAssertIsNonNull(ruleDetails.rule.create);
       visitor = ruleDetails.rule.create(ruleDetails.context);
     } else {
       // Rule defined with `createOnce` method

apps/oxlint/src-js/plugins/location.ts

@@ -4,7 +4,7 @@
  */
 
 import { initSourceText, sourceText } from './source_code.js';
-import { assertIsNonNull } from '../utils/asserts.js';
+import { debugAssertIsNonNull } from '../utils/asserts.js';
 
 import type { Node } from './types.ts';
 
@@ -61,7 +61,7 @@ const lineStartOffsets: number[] = [0];
  */
 export function initLines(): void {
   if (sourceText === null) initSourceText();
-  assertIsNonNull(sourceText);
+  debugAssertIsNonNull(sourceText);
 
   // This implementation is based on the one in ESLint.
   // TODO: Investigate if using `String.prototype.matchAll` is faster.
@@ -111,7 +111,7 @@ export function getLineColumnFromOffset(offset: number): LineColumn {
   // Build `lines` and `lineStartOffsets` tables if they haven't been already.
   // This also decodes `sourceText` if it wasn't already.
   if (lines.length === 0) initLines();
-  assertIsNonNull(sourceText);
+  debugAssertIsNonNull(sourceText);
 
   if (offset > sourceText.length) {
     throw new RangeError(
@@ -161,7 +161,7 @@ export function getOffsetFromLineColumn(loc: LineColumn): number {
       // Build `lines` and `lineStartOffsets` tables if they haven't been already.
       // This also decodes `sourceText` if it wasn't already.
       if (lines.length === 0) initLines();
-      assertIsNonNull(sourceText);
+      debugAssertIsNonNull(sourceText);
 
       const linesCount = lineStartOffsets.length;
       if (line <= 0 || line > linesCount) {

apps/oxlint/src-js/plugins/scope.ts

@@ -8,7 +8,7 @@ import {
   type ScopeManager as TSESLintScopeManager,
 } from '@typescript-eslint/scope-manager';
 import { ast, initAst } from './source_code.js';
-import { assertIs, assertIsNonNull } from '../utils/asserts.js';
+import { typeAssertIs, debugAssertIsNonNull } from '../utils/asserts.js';
 
 import type * as ESTree from '../generated/types.d.ts';
 import type { SetNullable } from '../utils/types.ts';
@@ -109,10 +109,10 @@ const analyzeOptions: SetNullable<AnalyzeOptions, 'sourceType'> = {
  */
 function initTsScopeManager() {
   if (ast === null) initAst();
-  assertIsNonNull(ast);
+  debugAssertIsNonNull(ast);
 
   analyzeOptions.sourceType = ast.sourceType;
-  assertIs<AnalyzeOptions>(analyzeOptions);
+  typeAssertIs<AnalyzeOptions>(analyzeOptions);
   // The effectiveness of this assertion depends on our alignment with ESTree.
   // It could eventually be removed as we align the remaining corner cases and the typegen.
   // @ts-expect-error // TODO: Our types don't quite align yet
@@ -200,7 +200,7 @@ export function isGlobalReference(node: ESTree.Node): boolean {
   if (node.type !== 'Identifier') return false;
 
   if (tsScopeManager === null) initTsScopeManager();
-  assertIsNonNull(tsScopeManager);
+  debugAssertIsNonNull(tsScopeManager);
 
   const { scopes } = tsScopeManager;
   if (scopes.length === 0) return false;
@@ -231,7 +231,7 @@ export function isGlobalReference(node: ESTree.Node): boolean {
 export function getDeclaredVariables(node: ESTree.Node): Variable[] {
   // ref: https://github.com/eslint/eslint/blob/e7cda3bdf1bdd664e6033503a3315ad81736b200/lib/languages/js/source-code/source-code.js#L904
   if (tsScopeManager === null) initTsScopeManager();
-  assertIsNonNull(tsScopeManager);
+  debugAssertIsNonNull(tsScopeManager);
 
   // @ts-expect-error // TODO: Our types don't quite align yet
   return tsScopeManager.getDeclaredVariables(node);
@@ -247,7 +247,7 @@ export function getScope(node: ESTree.Node): Scope {
   if (!node) throw new TypeError('Missing required argument: `node`');
 
   if (tsScopeManager === null) initTsScopeManager();
-  assertIsNonNull(tsScopeManager);
+  debugAssertIsNonNull(tsScopeManager);
 
   const inner = node.type !== 'Program';
 

apps/oxlint/src-js/plugins/settings.ts

@@ -3,7 +3,7 @@
  */
 
 import { deepFreezeJsonValue } from './json.js';
-import { assertIsNonNull } from '../utils/asserts.js';
+import { debugAssertIsNonNull } from '../utils/asserts.js';
 
 import type { JsonObject } from './json.ts';
 
@@ -36,7 +36,7 @@ export function setSettingsForFile(settingsJSONInput: string): undefined {
  * Deserialize settings from JSON.
  */
 export function initSettings(): undefined {
-  assertIsNonNull(settingsJSON);
+  debugAssertIsNonNull(settingsJSON);
   settings = JSON.parse(settingsJSON);
   // Deep freeze the settings object, to prevent any mutation of the settings from plugins
   deepFreezeJsonValue(settings);

apps/oxlint/src-js/plugins/source_code.ts

@@ -19,7 +19,7 @@ import { resetScopeManager, SCOPE_MANAGER } from './scope.js';
 import * as scopeMethods from './scope.js';
 import { resetTokens } from './tokens.js';
 import * as tokenMethods from './tokens.js';
-import { assertIsNonNull } from '../utils/asserts.js';
+import { debugAssertIsNonNull } from '../utils/asserts.js';
 
 import type { Program } from '../generated/types.d.ts';
 import type { Ranged } from './location.ts';
@@ -66,7 +66,7 @@ export function setupSourceForFile(
  * Decode source text from buffer.
  */
 export function initSourceText(): void {
-  assertIsNonNull(buffer);
+  debugAssertIsNonNull(buffer);
   const { uint32 } = buffer,
     programPos = uint32[DATA_POINTER_POS_32];
   sourceByteLen = uint32[(programPos + SOURCE_LEN_OFFSET) >> 2];
@@ -116,7 +116,7 @@ export const SOURCE_CODE = Object.freeze({
   // Get source text.
   get text(): string {
     if (sourceText === null) initSourceText();
-    assertIsNonNull(sourceText);
+    debugAssertIsNonNull(sourceText);
     return sourceText;
   },
 
@@ -128,7 +128,7 @@ export const SOURCE_CODE = Object.freeze({
   // Get AST of the file.
   get ast(): Program {
     if (ast === null) initAst();
-    assertIsNonNull(ast);
+    debugAssertIsNonNull(ast);
     return ast;
   },
 
@@ -144,7 +144,7 @@ export const SOURCE_CODE = Object.freeze({
 
   // Get parser services for the file.
   get parserServices(): Record<string, unknown> {
-    assertIsNonNull(parserServices);
+    debugAssertIsNonNull(parserServices);
     return parserServices;
   },
 
@@ -163,7 +163,7 @@ export const SOURCE_CODE = Object.freeze({
    */
   getText(node?: Ranged | null, beforeCount?: number | null, afterCount?: number | null): string {
     if (sourceText === null) initSourceText();
-    assertIsNonNull(sourceText);
+    debugAssertIsNonNull(sourceText);
 
     // ESLint treats all falsy values for `node` as undefined
     if (!node) return sourceText;