feat: add replacements plugin (#32)

Adds a replacements plugin which detects replaceable modules.

This only checks the root `package.json` for now, and only
`dependencies` (not `devDependencies`).

Author: 43081j

src/analyze/attw.ts

@@ -6,11 +6,18 @@ import {
 import {groupProblemsByKind} from '@arethetypeswrong/core/utils';
 import {filterProblems, problemKindInfo} from '@arethetypeswrong/core/problems';
 import {Message} from '../types.js';
+import type {FileSystem} from '../file-system.js';
+import {TarballFileSystem} from '../tarball-file-system.js';
 
-export async function runAttw(tarball: ArrayBuffer) {
+export async function runAttw(fileSystem: FileSystem) {
   const messages: Message[] = [];
 
-  const pkg = createPackageFromTarballData(new Uint8Array(tarball));
+  // Only support tarballs for now
+  if (!(fileSystem instanceof TarballFileSystem)) {
+    return messages;
+  }
+
+  const pkg = createPackageFromTarballData(new Uint8Array(fileSystem.tarball));
   const result = await checkPackage(pkg);
 
   if (result.types === false) {

src/analyze/dependencies.ts

@@ -53,7 +53,7 @@ export async function analyzeDependencies(
   let pkg: PackageJsonLike;
 
   try {
-    pkg = JSON.parse(await fileSystem.readFile(rootDir + '/package.json'));
+    pkg = JSON.parse(await fileSystem.readFile('/package.json'));
   } catch {
     throw new Error('No package.json found.');
   }

src/analyze/publint.ts

@@ -1,11 +1,17 @@
 import {publint} from 'publint';
 import {formatMessage} from 'publint/utils';
 import {Message} from '../types.js';
+import type {FileSystem} from '../file-system.js';
+import {TarballFileSystem} from '../tarball-file-system.js';
 
-export async function runPublint(tarball: ArrayBuffer) {
+export async function runPublint(fileSystem: FileSystem) {
   const messages: Message[] = [];
 
-  const result = await publint({pack: {tarball}});
+  if (!(fileSystem instanceof TarballFileSystem)) {
+    return messages;
+  }
+
+  const result = await publint({pack: {tarball: fileSystem.tarball}});
   for (const problem of result.messages) {
     messages.push({
       severity: problem.type,

src/analyze/replacements.ts

@@ -0,0 +1,90 @@
+import * as replacements from 'module-replacements';
+import {Message, PackageJsonLike} from '../types.js';
+import type {FileSystem} from '../file-system.js';
+
+/**
+ * Generates a standard URL to the docs of a given rule
+ * @param {string} name Rule name
+ * @return {string}
+ */
+export function getDocsUrl(name: string): string {
+  return `https://github.com/es-tooling/eslint-plugin-depend/blob/main/docs/rules/${name}.md`;
+}
+
+/**
+ * Generates a URL for the given path on MDN
+ * @param {string} path Docs path
+ * @return {string}
+ */
+export function getMdnUrl(path: string): string {
+  return `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/${path}`;
+}
+
+export async function runReplacements(fileSystem: FileSystem) {
+  const messages: Message[] = [];
+
+  let packageJsonText: string;
+
+  try {
+    packageJsonText = await fileSystem.readFile('/package.json');
+  } catch {
+    // No package.json found
+    return messages;
+  }
+
+  let packageJson: PackageJsonLike;
+
+  try {
+    packageJson = JSON.parse(packageJsonText);
+  } catch {
+    // Not parseable
+    return messages;
+  }
+
+  if (!packageJson.dependencies) {
+    // No dependencies
+    return messages;
+  }
+
+  for (const name of Object.keys(packageJson.dependencies)) {
+    const replacement = replacements.all.moduleReplacements.find(
+      (replacement) => replacement.moduleName === name
+    );
+
+    if (!replacement) {
+      continue;
+    }
+
+    if (replacement.type === 'none') {
+      messages.push({
+        severity: 'warning',
+        score: 0,
+        message: `Module "${name}" can be removed, and native functionality used instead`
+      });
+    } else if (replacement.type === 'simple') {
+      messages.push({
+        severity: 'warning',
+        score: 0,
+        message: `Module "${name}" can be replaced. ${replacement.replacement}.`
+      });
+    } else if (replacement.type === 'native') {
+      const mdnPath = getMdnUrl(replacement.mdnPath);
+      // TODO (43081j): support `nodeVersion` here, check it against the
+      // packageJson.engines field, if there is one.
+      messages.push({
+        severity: 'warning',
+        score: 0,
+        message: `Module "${name}" can be replaced with native functionality. Use "${replacement.replacement}" instead. You can read more at ${mdnPath}.`
+      });
+    } else if (replacement.type === 'documented') {
+      const docUrl = getDocsUrl(replacement.docPath);
+      messages.push({
+        severity: 'warning',
+        score: 0,
+        message: `Module "${name}" can be replaced with a more performant alternative. See the list of available alternatives at ${docUrl}.`
+      });
+    }
+  }
+
+  return messages;
+}

src/analyze/report.ts

@@ -7,8 +7,9 @@ import type {FileSystem} from '../file-system.js';
 import {Message, Options} from '../types.js';
 import {runAttw} from './attw.js';
 import {runPublint} from './publint.js';
+import {runReplacements} from './replacements.js';
 
-export type ReportPlugin = (tarball: ArrayBuffer) => Promise<Message[]>;
+export type ReportPlugin = (fileSystem: FileSystem) => Promise<Message[]>;
 
 export interface ReportResult {
   info: {
@@ -20,13 +21,11 @@ export interface ReportResult {
   dependencies: DependencyStats;
 }
 
-const plugins: ReportPlugin[] = [runAttw, runPublint];
+const plugins: ReportPlugin[] = [runAttw, runPublint, runReplacements];
 
 async function computeInfo(fileSystem: FileSystem) {
-  const rootDir = await fileSystem.getRootDir();
-
   try {
-    const pkgJson = await fileSystem.readFile(rootDir + '/package.json');
+    const pkgJson = await fileSystem.readFile('/package.json');
     const pkg = JSON.parse(pkgJson);
     return {
       name: pkg.name,
@@ -56,13 +55,13 @@ export async function report(options: Options) {
     }
 
     fileSystem = new TarballFileSystem(tarball);
+  }
 
-    for (const plugin of plugins) {
-      const result = await plugin(tarball);
+  for (const plugin of plugins) {
+    const result = await plugin(fileSystem);
 
-      for (const message of result) {
-        messages.push(message);
-      }
+    for (const message of result) {
+      messages.push(message);
     }
   }
 

src/local-file-system.ts

@@ -43,8 +43,8 @@ export class LocalFileSystem implements FileSystem {
     }
   }
 
-  async readFile(path: string): Promise<string> {
-    return await readFile(path, 'utf8');
+  async readFile(filePath: string): Promise<string> {
+    return await readFile(path.join(this.#root, filePath), 'utf8');
   }
 
   async getInstallSize(): Promise<number> {

src/tarball-file-system.ts

@@ -1,10 +1,15 @@
 import {unpack, type UnpackResult} from '@publint/pack';
 import type {FileSystem} from './file-system.js';
+import path from 'node:path';
 
 export class TarballFileSystem implements FileSystem {
   #tarball: ArrayBuffer;
   #unpackResult?: UnpackResult;
 
+  public get tarball(): ArrayBuffer {
+    return this.#tarball;
+  }
+
   constructor(tarball: ArrayBuffer) {
     this.#tarball = tarball;
   }
@@ -29,11 +34,12 @@ export class TarballFileSystem implements FileSystem {
       .map((file) => file.name);
   }
 
-  async readFile(path: string): Promise<string> {
+  async readFile(filePath: string): Promise<string> {
     const {files} = await this.#getUnpackResult();
-    const file = files.find((f) => f.name === path);
+    const fullPath = path.join(await this.getRootDir(), filePath);
+    const file = files.find((f) => f.name === fullPath);
     if (!file) {
-      throw new Error(`File not found: ${path}`);
+      throw new Error(`File not found: ${filePath}`);
     }
     return new TextDecoder().decode(file.data);
   }