@ms-cloudpack/eslint-plugin-deprecated 0.1.1

package/README.md

@@ -0,0 +1,15 @@
+# @ms-cloudpack/eslint-plugin-deprecated
+
+Fork of `eslint-plugin-etc`'s [`no-deprecated` rule](https://github.com/cartant/eslint-plugin-etc/blob/main/source/rules/no-deprecated.ts) with updated dependencies.
+
+This plugin **requires type information** (see [setup instructions](https://typescript-eslint.io/linting/typed-linting)) and only works with flat config.
+
+## Rules
+
+### `@ms-cloudpack/no-deprecated`
+
+Forbids the use of deprecated APIs.
+
+Options:
+
+- `ignoredSelectors` (optional): Ignore deprecated APIs matching these selectors, using [esquery syntax](https://github.com/estools/esquery).

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ms-cloudpack/eslint-plugin-deprecated",
+  "version": "0.1.1",
+  "description": "ESLint rule banning usage of deprecated APIs",
+  "license": "MIT",
+  "type": "module",
+  "exports": "./src/index.ts",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "cloudpack-scripts build",
+    "lint": "cloudpack-scripts lint",
+    "test": "cloudpack-scripts test"
+  },
+  "dependencies": {
+    "@phenomnomnominal/tsquery": "^6.1.3",
+    "@typescript-eslint/utils": "^8.0.0",
+    "tsutils": "^3.21.0"
+  },
+  "peerDependencies": {
+    "eslint": "^8.0.0 || ^9.0.0 || ^10.0.0",
+    "typescript": ">=5.0.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "devDependencies": {
+    "@ms-cloudpack/scripts": "workspace:^",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/rule-tester": "^8.0.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-eslint-plugin": "^7.3.3",
+    "typescript": "~5.9.0"
+  },
+  "files": [
+    "src/**/!(*.test.*)"
+  ]
+}

package/src/__fixtures__/createInvalidCases.ts

@@ -0,0 +1,45 @@
+/**
+ * Heavily modified from https://github.com/cartant/eslint-etc/blob/main/source/from-fixture.ts
+ * for no-deprecated rule tests.
+ */
+import type { InvalidTestCase, TestCaseError } from '@typescript-eslint/rule-tester';
+
+const markerRegexp = /^(?<indent>\s*)(?<marker>~+)$/;
+
+/**
+ * Convert a string with marker comment to an invalid test case.
+ * ```
+ * let a: DeprecatedInterface;
+ *        ~~~~~~~~~~~~~~~~~~~
+ * ```
+ */
+export function createInvalidCases<MessageIds extends string, TData extends Readonly<Record<string, unknown>>>(
+  cases: Omit<InvalidTestCase<MessageIds, never>, 'code' | 'errors'> &
+    {
+      code: string;
+      errors: { messageId: MessageIds; data?: TData }[];
+    }[],
+): InvalidTestCase<MessageIds, never>[] {
+  return cases.map(({ code, errors: partialErrors, ...testCase }) => {
+    const lines: string[] = [];
+    const errors: TestCaseError<MessageIds>[] = [];
+
+    for (const line of code.split('\n')) {
+      const match = line.match(markerRegexp);
+      if (match?.groups) {
+        const error = partialErrors[errors.length];
+        if (!error) {
+          throw new Error('More marker comments found than expected');
+        }
+        const column = match.groups.indent.length + 1;
+        const endColumn = column + match.groups.marker.length;
+        const lineNum = lines.length;
+        errors.push({ ...error, line: lineNum, column, endLine: lineNum, endColumn });
+      } else {
+        lines.push(line);
+      }
+    }
+
+    return { code: lines.join('\n'), errors, ...testCase };
+  });
+}

package/src/__fixtures__/deprecated.ts

@@ -0,0 +1,153 @@
+/**
+ * Copied from https://github.com/cartant/eslint-plugin-etc/blob/main/tests/modules/deprecated.ts
+ * due to lack of updates for new dependency versions.
+ */
+/** */
+
+export interface NotDeprecatedInterface {
+  notDeprecatedProperty: string;
+  notDeprecatedMethod(): void;
+}
+
+export type NotDeprecatedType = {
+  notDeprecatedProperty: string;
+  notDeprecatedMethod(): void;
+};
+
+export class NotDeprecatedClass {
+  static notDeprecatedStaticMethod(): void {}
+  notDeprecatedProperty: string = '';
+  get notDeprecatedGetter(): string {
+    return '';
+  }
+  set notDeprecatedSetter(value: string) {}
+  notDeprecatedMethod(): void {}
+}
+
+// Note: this gets an editor diagnostics error, but is correct at actual build time
+// @ts-expect-error -- not valid with erasable syntax, but fine for a test fixture
+export enum NotDeprecatedEnum {
+  NotDeprecatedMember = 1,
+}
+
+export const notDeprecatedVariable = {};
+
+export function notDeprecatedFunction(): void {}
+
+// Deprecated
+
+/** @deprecated Don't use this */
+export interface DeprecatedInterface {
+  notDeprecatedProperty: string;
+  notDeprecatedMethod(): void;
+}
+
+/** @deprecated Don't use this */
+export type DeprecatedType = {
+  notDeprecatedProperty: string;
+  notDeprecatedMethod(): void;
+};
+
+/** @deprecated Don't use this */
+export class DeprecatedClass {
+  static notDeprecatedStaticMethod(): void {}
+  notDeprecatedProperty: string = '';
+  get notDeprecatedGetter(): string {
+    return '';
+  }
+  set notDeprecatedSetter(value: string) {}
+  notDeprecatedMethod(): void {}
+}
+
+/** @deprecated Don't use this */
+// @ts-expect-error -- not valid with erasable syntax, but fine for a test fixture
+export enum DeprecatedEnum {
+  NotDeprecatedMember = 1,
+}
+
+/** @deprecated Don't use this */
+export const deprecatedVariable = {};
+
+/** @deprecated Don't use this */
+export function deprecatedFunction(): void {}
+
+// Some proeprties/methods deprecated
+
+export interface SomeDeprecatedInterface {
+  /** @deprecated Don't use this */
+  deprecatedProperty: string;
+  notDeprecatedProperty: string;
+  /** @deprecated Don't use this */
+  deprecatedMethod(): void;
+  notDeprecatedMethod(): void;
+}
+
+export type SomeDeprecatedType = {
+  /** @deprecated Don't use this */
+  deprecatedProperty: string;
+  notDeprecatedProperty: string;
+  /** @deprecated Don't use this */
+  deprecatedMethod(): void;
+  notDeprecatedMethod(): void;
+};
+
+export class SomeDeprecatedClass {
+  /** @deprecated Don't use this */
+  static deprecatedStaticMethod(): void {}
+  static notDeprecatedStaticMethod(): void {}
+  /** @deprecated Don't use this */
+  deprecatedProperty: string = '';
+  notDeprecatedProperty: string = '';
+  /** @deprecated Don't use this */
+  get deprecatedGetter(): string {
+    return '';
+  }
+  get notDeprecatedGetter(): string {
+    return '';
+  }
+  /** @deprecated Don't use this */
+  set deprecatedSetter(value: string) {}
+  set notDeprecatedSetter(value: string) {}
+  /** @deprecated Don't use this */
+  deprecatedMethod(): void {}
+  notDeprecatedMethod(): void {}
+}
+
+// @ts-expect-error -- not valid with erasable syntax, but fine for a test fixture
+export enum SomeDeprecatedEnum {
+  /** @deprecated Don't use this */
+  DeprecatedMember = 1,
+  NotDeprecatedMember = 2,
+}
+
+// Some deprecated signatures
+
+export class DeprecatedSignatureClass {
+  static deprecatedSignatureStaticMethod(value: number): void;
+  /** @deprecated Don't use this */
+  static deprecatedSignatureStaticMethod(value: string): void;
+  static deprecatedSignatureStaticMethod(_value: unknown): void {}
+  deprecatedSignatureMethod(value: number): void;
+  /** @deprecated Don't use this */
+  deprecatedSignatureMethod(value: string): void;
+  deprecatedSignatureMethod(_value: unknown): void {}
+}
+
+export function deprecatedSignatureFunction(value: number): void;
+/** @deprecated Don't use this */
+export function deprecatedSignatureFunction(value: string): void;
+export function deprecatedSignatureFunction(_value: unknown): void {}
+
+// Deprecated constructor
+
+export class DeprecatedConstructorClass {
+  /** @deprecated Don't use this */
+  constructor() {}
+}
+
+export class DeprecatedConstructorSignatureClass {
+  constructor(value: number);
+  /** @deprecated Don't use this */
+  constructor(value: string);
+  constructor(_value: unknown) {}
+}

package/src/__fixtures__/file.ts

@@ -0,0 +1 @@
+// placeholder for tests (must exist on disk, but contents will be virtualized)

package/src/__fixtures__/tsconfig.json

@@ -0,0 +1,13 @@
+// tsconfig used as `project` for no-deprecated tests
+{
+  "compilerOptions": {
+    "lib": ["esnext"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "target": "esnext",
+    // very important for test performance!
+    "types": []
+  },
+  "include": ["file.ts", "deprecated.ts"]
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import fs from 'fs';
+import path from 'path';
+import type { TSESLint } from '@typescript-eslint/utils';
+import noDeprecated from './rules/no-deprecated.ts';
+
+const { name, version } = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, '../package.json'), 'utf8')) as {
+  name: string;
+  version: string;
+};
+
+const plugin = {
+  meta: { name, version, namespace: '@ms-cloudpack' },
+  configs: {
+    recommended: {
+      rules: {
+        '@ms-cloudpack/no-deprecated': 'error',
+      },
+    },
+  },
+  rules: {
+    '@ms-cloudpack/no-deprecated': noDeprecated,
+  },
+  // Use `satisfies` to preserve the original property names
+} satisfies TSESLint.FlatConfig.Plugin;
+
+export default plugin;

package/src/rules/no-deprecated.ts

@@ -0,0 +1,271 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+import { ESLintUtils } from '@typescript-eslint/utils';
+import ts from 'typescript';
+import { tsquery } from '@phenomnomnominal/tsquery';
+import tsutils from 'tsutils';
+
+export type MessageIds = 'forbidden';
+export type MessageData = { name: string; comment: string };
+type Options = { ignoredSelectors?: string[] };
+
+const deprecatedNamesByProgram = new WeakMap<ts.Program, Set<string>>();
+
+/**
+ * Copied from https://github.com/cartant/eslint-plugin-etc/blob/main/source/rules/no-deprecated.ts
+ * due to lack of updates for new dependency versions.
+ * Also added a new `ignoredSelectors` option.
+ *
+ * License for `eslint-plugin-etc` (excluding new `ignoredSelectors` option):
+ *
+ * MIT License
+ *
+ * Copyright (c) 2019-2021 Nicholas Jamieson and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+const rule: TSESLint.RuleModule<MessageIds, [Options?]> = {
+  defaultOptions: [],
+  meta: {
+    docs: {
+      description: 'disallow the use of deprecated APIs',
+    },
+    messages: {
+      forbidden: `"{{name}}" is deprecated: {{comment}}`,
+    },
+    schema: [
+      {
+        properties: {
+          ignoredSelectors: {
+            description: 'Selectors for nodes to ignore',
+            type: 'array',
+            items: { type: 'string' },
+          },
+        },
+        type: 'object',
+      },
+    ],
+    defaultOptions: [{}],
+    type: 'problem',
+  },
+  create: (context) => {
+    const [{ ignoredSelectors } = {}] = context.options;
+    let ignoredNodes: ts.Node[] | undefined;
+
+    const { esTreeNodeToTSNodeMap, program } = ESLintUtils.getParserServices(context);
+    const typeChecker = program.getTypeChecker();
+
+    let deprecatedNames = deprecatedNamesByProgram.get(program);
+    if (!deprecatedNames) {
+      deprecatedNames = findTaggedNames('deprecated', program);
+      deprecatedNamesByProgram.set(program, deprecatedNames);
+    }
+
+    return {
+      Identifier: (node) => {
+        const parentType = node.parent?.type;
+        if (
+          parentType === 'ExportSpecifier' ||
+          parentType === 'ImportDefaultSpecifier' ||
+          parentType === 'ImportNamespaceSpecifier' ||
+          parentType === 'ImportSpecifier'
+        ) {
+          return;
+        }
+        const identifier = esTreeNodeToTSNodeMap.get(node) as ts.Identifier;
+        if (!deprecatedNames.has(identifier.text) || isDeclaration(identifier)) {
+          return;
+        }
+
+        // NEW: check if this node matches any ignored selectors
+        if (ignoredSelectors?.length) {
+          ignoredNodes ??= tsquery(identifier.getSourceFile(), ignoredSelectors.join(', '));
+          if (ignoredNodes.includes(identifier)) {
+            return;
+          }
+        }
+
+        const tags = getTags('deprecated', identifier, typeChecker);
+        for (const tag of tags) {
+          context.report({
+            data: {
+              comment: tag.trim().replace(/\s+/g, ' '),
+              name: identifier.text,
+            },
+            messageId: 'forbidden',
+            node,
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;
+
+function isDeclaration(identifier: ts.Identifier): boolean {
+  const parent = identifier.parent;
+  switch (parent.kind) {
+    case ts.SyntaxKind.ClassDeclaration:
+    case ts.SyntaxKind.ClassExpression:
+    case ts.SyntaxKind.InterfaceDeclaration:
+    case ts.SyntaxKind.TypeParameter:
+    case ts.SyntaxKind.FunctionExpression:
+    case ts.SyntaxKind.FunctionDeclaration:
+    case ts.SyntaxKind.LabeledStatement:
+    case ts.SyntaxKind.JsxAttribute:
+    case ts.SyntaxKind.MethodDeclaration:
+    case ts.SyntaxKind.MethodSignature:
+    case ts.SyntaxKind.PropertySignature:
+    case ts.SyntaxKind.TypeAliasDeclaration:
+    case ts.SyntaxKind.GetAccessor:
+    case ts.SyntaxKind.SetAccessor:
+    case ts.SyntaxKind.EnumDeclaration:
+    case ts.SyntaxKind.ModuleDeclaration:
+      return true;
+    case ts.SyntaxKind.VariableDeclaration:
+    case ts.SyntaxKind.Parameter:
+    case ts.SyntaxKind.PropertyDeclaration:
+    case ts.SyntaxKind.EnumMember:
+    case ts.SyntaxKind.ImportEqualsDeclaration:
+      return (parent as ts.NamedDeclaration).name === identifier;
+    case ts.SyntaxKind.PropertyAssignment:
+      return (
+        (parent as ts.PropertyAssignment).name === identifier &&
+        !tsutils.isReassignmentTarget(identifier.parent.parent as ts.ObjectLiteralExpression)
+      );
+    case ts.SyntaxKind.BindingElement:
+      // return true for `b` in `const {a: b} = obj`
+      return (
+        (parent as ts.BindingElement).name === identifier && (parent as ts.BindingElement).propertyName !== undefined
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Get all identifiers with jsdoc tag `@tagName` in the program.
+ */
+function findTaggedNames(tagName: string, program: ts.Program): Set<string> {
+  const taggedNames = new Set<string>();
+  for (const sourceFile of program.getSourceFiles()) {
+    if (!sourceFile.text.includes(`@${tagName}`)) {
+      continue;
+    }
+    const nodes = tsquery(
+      sourceFile,
+      `ClassDeclaration, Constructor, EnumDeclaration, EnumMember, FunctionDeclaration, GetAccessor, ` +
+        `InterfaceDeclaration, MethodDeclaration, MethodSignature, PropertyDeclaration, PropertySignature, ` +
+        `SetAccessor, TypeAliasDeclaration, VariableDeclaration`,
+    );
+    for (const node of nodes) {
+      const tags = ts.getJSDocTags(node);
+      if (tags.some((tag) => tag.tagName.text === tagName)) {
+        const name = ts.isConstructorDeclaration(node)
+          ? node.parent.name
+          : (node as ts.Node & { name?: ts.Identifier }).name;
+        if (name?.text) {
+          taggedNames.add(name.text);
+        }
+      }
+    }
+  }
+  return taggedNames;
+}
+
+/**
+ * Get the text of all tags of `node`'s type matching `tagName`.
+ */
+function getTags(tagName: string, node: ts.Identifier, tc: ts.TypeChecker): string[] {
+  const callExpression = getCallExpression(node);
+  if (callExpression) {
+    const signature = tc.getResolvedSignature(callExpression);
+    const tags = signature && findTags(tagName, signature.getJsDocTags());
+    if (tags?.length) {
+      return tags;
+    }
+  }
+
+  let symbol: ts.Symbol | undefined;
+  const parent = node.parent;
+  if (parent.kind === ts.SyntaxKind.BindingElement) {
+    symbol = tc.getTypeAtLocation(parent.parent).getProperty(node.text);
+  } else if (
+    (tsutils.isPropertyAssignment(parent) && parent.name === node) ||
+    (tsutils.isShorthandPropertyAssignment(parent) && parent.name === node && tsutils.isReassignmentTarget(node))
+  ) {
+    symbol = tc.getPropertySymbolOfDestructuringAssignment(node);
+  } else {
+    symbol = tc.getSymbolAtLocation(node);
+  }
+
+  if (symbol && tsutils.isSymbolFlagSet(symbol, ts.SymbolFlags.Alias)) {
+    symbol = tc.getAliasedSymbol(symbol);
+  }
+  if (
+    !symbol ||
+    // if this is a CallExpression and the declaration is a function or method,
+    // stop here to avoid collecting JsDoc of all overload signatures
+    (callExpression && isFunctionOrMethod(symbol.declarations))
+  ) {
+    return [];
+  }
+  return findTags(tagName, symbol.getJsDocTags());
+}
+
+/**
+ * Get the text of all `tags` matching `tagName`.
+ */
+function findTags(tagName: string, tags: ts.JSDocTagInfo[]): string[] {
+  const result: string[] = [];
+  for (const tag of tags) {
+    if (tag.name === tagName) {
+      const { text = '' } = tag;
+      if (typeof text === 'string') {
+        result.push(text);
+      } else {
+        result.push(text.reduce((t, part) => t + part.text, ''));
+      }
+    }
+  }
+  return result;
+}
+
+function getCallExpression(node: ts.Expression): ts.CallLikeExpression | undefined {
+  let parent = node.parent;
+  if (tsutils.isPropertyAccessExpression(parent) && parent.name === node) {
+    parent = parent.parent;
+  }
+  return tsutils.isCallLikeExpression(parent) ? parent : undefined;
+}
+
+function isFunctionOrMethod(declarations: ts.Declaration[] | undefined): boolean {
+  if (!declarations?.length) {
+    return false;
+  }
+  switch (declarations[0].kind) {
+    case ts.SyntaxKind.MethodDeclaration:
+    case ts.SyntaxKind.FunctionDeclaration:
+    case ts.SyntaxKind.FunctionExpression:
+    case ts.SyntaxKind.MethodSignature:
+      return true;
+    default:
+      return false;
+  }
+}