build(linter/plugins): fully remove debug assertions (#16163)

`debugAssert` and friends are meant to be completely removed in release build (like `debug_assert!` in Rust). Turns out they weren't.

Minifier does remove all calls to these functions, but it can't always prove that the expressions *inside* the function calls don't have side effects, so was leaving them in place in some cases.

Fix that by visiting the AST in TSDown plugin, and removing all calls to debug assert functions entirely.

Source code:

```ts
if (visitor === null) {
    debugAssertIsNonNull(ruleDetails.rule.create);
    visitor = ruleDetails.rule.create(ruleDetails.context);
}
```

Release build, before this PR:

```ts
if (visitor === null) ruleDetails.rule.create, visitor = ruleDetails.rule.create(ruleDetails.context);
```

After this PR:

```ts
if (visitor === null) visitor = ruleDetails.rule.create(ruleDetails.context);
```

Author: overlookmotel

apps/oxlint/package.json

@@ -29,6 +29,7 @@
     "esquery": "^1.6.0",
     "execa": "^9.6.0",
     "jiti": "^2.6.0",
+    "oxc-parser": "^0.99.0",
     "rolldown": "catalog:",
     "tsdown": "catalog:",
     "type-fest": "^5.2.0",

apps/oxlint/tsdown.config.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { defineConfig } from "tsdown";
+import { parseSync, Visitor } from "oxc-parser";
 
 import type { Plugin } from "rolldown";
 
@@ -58,26 +59,47 @@ export default defineConfig([
 ]);
 
 /**
- * Create a plugin to remove imports of `assert*` functions from `src-js/utils/asserts.ts`,
- * and replace those imports with empty function declarations.
+ * Create a plugin to remove imports of `debugAssert*` / `typeAssert*` functions from `src-js/utils/asserts.ts`,
+ * and all their call sites.
  *
  * ```ts
  * // Original code
- * import { assertIs, assertIsNonNull } from '../utils/asserts.ts';
+ * import { debugAssertIsNonNull } from '../utils/asserts.ts';
+ * const foo = getFoo();
+ * debugAssertIsNonNull(foo.bar);
  *
  * // After transform
- * function assertIs() {}
- * function assertIsNonNull() {}
+ * const foo = getFoo();
  * ```
  *
+ * This solves 2 problems:
+ *
+ * # 1. Minifier works chunk-by-chunk
+ *
  * Minifier can already remove all calls to these functions as dead code, but only if the functions are defined
  * in the same file as the call sites.
  *
  * Problem is that `asserts.ts` is imported by files which end up in all output chunks.
  * So without this transform, TSDown creates a shared chunk for `asserts.ts`. Minifier works chunk-by-chunk,
  * so can't see that these functions are no-ops, and doesn't remove the function calls.
  *
- * Inlining these functions in each file solves the problem, and minifier removes all trace of them.
+ * # 2. Not entirely removed
+ *
+ * Even if minifier does remove all calls to these functions, it can't prove that expressions *inside* the calls
+ * don't have side effects.
+ *
+ * In example above, it can't know if `foo` has a getter for `bar` property.
+ * So it removes the call to `debugAssertIsNonNull`, but leaves behind the `foo.bar` expression.
+ *
+ * ```ts
+ * const foo = getFoo();
+ * foo.bar;
+ * ```
+ *
+ * This plugin visits AST and removes all calls to `debugAssert*` / `typeAssert*` functions entirely,
+ * *including* the expressions inside the calls.
+ *
+ * This makes these debug assertion functions act like `debug_assert!` in Rust.
  *
  * @returns Plugin
  */
@@ -90,31 +112,63 @@ function createReplaceAssertsPlugin(): Plugin {
       // Only process TS files in `src-js` directory
       filter: { id: /\/src-js\/.+\.ts$/ },
 
-      async handler(code, id, meta) {
+      async handler(code, path, meta) {
         const magicString = meta.magicString!;
-        const program = this.parse(code, { lang: "ts" });
+        const { program, errors } = parseSync(path, code);
+        if (errors.length !== 0) throw new Error(`Failed to parse ${path}: ${errors[0].message}`);
 
-        stmts: for (const stmt of program.body) {
+        // Gather names of assertion functions imported from `asserts.ts`.
+        // Also gather all identifiers used in the `import` statements, so can avoid erroring on them in visitor below.
+        const assertFnNames: Set<string> = new Set(),
+          idents = new Set();
+        for (const stmt of program.body) {
           if (stmt.type !== "ImportDeclaration") continue;
 
           // Check if import is from `utils/asserts.ts`.
           // `endsWith` check is just a shortcut to avoid resolving the specifier to a full path for most imports.
           const source = stmt.source.value;
           if (!source.endsWith("/asserts.ts") && !source.endsWith("/asserts.js")) continue;
           // oxlint-disable-next-line no-await-in-loop
-          const importedId = await this.resolve(source, id);
+          const importedId = await this.resolve(source, path);
           if (importedId === null || importedId.id !== ASSERTS_PATH) continue;
 
-          // Replace `import` statement with empty function declarations
-          let functionsCode = "";
+          // Remove `import` statement
           for (const specifier of stmt.specifiers) {
-            // Skip this `import` statement if it's a default or namespace import - can't handle those
-            if (specifier.type !== "ImportSpecifier") continue stmts;
-            functionsCode += `function ${specifier.local.name}() {}\n`;
+            if (specifier.type !== "ImportSpecifier") {
+              throw new Error(`Only use named imports when importing from \`asserts.ts\`: ${path}`);
+            }
+            idents.add(specifier.local);
+            if (specifier.imported.type === "Identifier") idents.add(specifier.imported);
+            assertFnNames.add(specifier.local.name);
           }
-          magicString.overwrite(stmt.start, stmt.end, functionsCode);
+          magicString.remove(stmt.start, stmt.end);
         }
 
+        if (assertFnNames.size === 0) return;
+
+        // Visit AST and remove all calls to assertion functions
+        const visitor = new Visitor({
+          // Replace `debugAssert(...)` calls with `null`. Minifier will remove the `null`.
+          CallExpression(node) {
+            const { callee } = node;
+            if (callee.type !== "Identifier") return;
+            if (assertFnNames.has(callee.name)) {
+              idents.add(callee);
+              magicString.overwrite(node.start, node.end, "null");
+            }
+          },
+          // Error if assertion functions are used in any other way. We lack logic to deal with that.
+          Identifier(node) {
+            const { name } = node;
+            if (assertFnNames.has(name) && !idents.has(node)) {
+              throw new Error(
+                `Do not use \`${name}\` imported from \`asserts.ts\` except in function calls: ${path}`,
+              );
+            }
+          },
+        });
+        visitor.visit(program);
+
         return { code: magicString };
       },
     },