Mar 3, 2025 · Mar 3, 2024 · Mar 3, 2024 · Mar 6, 2024 · Jan 24, 2025 · Jan 25, 2025
diff --git a/packages/eslint-plugin/src/rules/no-unused-vars.ts b/packages/eslint-plugin/src/rules/no-unused-vars.ts
 } from '@typescript-eslint/scope-manager';
 import { AST_NODE_TYPES, TSESLint } from '@typescript-eslint/utils';

 import type { MakeRequired } from '../util';

 import {
  collectVariables,
  createRule,
  | 'parameter'
  | 'variable';

 type ModuleDeclarationWithBody = MakeRequired<
  TSESTree.TSModuleDeclaration,
  'body'
 >;

 export default createRule<Options, MessageIds>({
  name: 'no-unused-vars',
  meta: {
  },
  defaultOptions: [{}],
  create(context, [firstOption]) {
    const MODULE_DECL_CACHE = new Map<TSESTree.TSModuleDeclaration, boolean>();
    const MODULE_DECL_CACHE = new Map<
      ModuleDeclarationWithBody | TSESTree.Program,
      boolean
    >();

    const options = ((): TranslatedOptions => {
      const options: TranslatedOptions = {
    }

    return {
      // declaration file handling
      [ambientDeclarationSelector(AST_NODE_TYPES.Program, true)](
      //top-leveldeclaration file handling
      [ambientDeclarationSelector(AST_NODE_TYPES.Program)](
        node: DeclarationSelectorNode,
      ): void {
        if (!isDefinitionFile(context.filename)) {
          return;
        }

        const moduleDecl = nullThrows(
          node.parent,
          NullThrowsReasons.MissingParent,
        ) as TSESTree.Program;

        if (checkForOverridingExportStatements(moduleDecl)) {
          return;
        }

        markDeclarationChildAsUsed(node);
      },

      // children of a namespace that is a child of a declared namespace are auto-exported
      [ambientDeclarationSelector(
        'TSModuleDeclaration[declare = true] > TSModuleBlock TSModuleDeclaration > TSModuleBlock',
        false,
      )](node: DeclarationSelectorNode): void {
        const moduleDecl = nullThrows(
          node.parent.parent,
          NullThrowsReasons.MissingParent,
        ) as ModuleDeclarationWithBody;

        if (checkForOverridingExportStatements(moduleDecl)) {
          return;
        }

        markDeclarationChildAsUsed(node);
      },

      // declared namespace handling
      [ambientDeclarationSelector(
        'TSModuleDeclaration[declare = true] > TSModuleBlock',
        false,
      )](node: DeclarationSelectorNode): void {
        const moduleDecl = nullThrows(
          node.parent.parent,
          NullThrowsReasons.MissingParent,
        ) asTSESTree.TSModuleDeclaration;
        ) asModuleDeclarationWithBody;

        // declared ambient modules with an `export =` statement will only export that one thing
        // all other statements are not automatically exported in this case
        if (
          moduleDecl.id.type === AST_NODE_TYPES.Literal &&
          checkModuleDeclForExportEquals(moduleDecl)
        ) {
        if (checkForOverridingExportStatements(moduleDecl)) {
          return;
        }

        markDeclarationChildAsUsed(node);
      },

      // namespace handling in definition files
      [ambientDeclarationSelector('TSModuleDeclaration > TSModuleBlock')](
        node: DeclarationSelectorNode,
      ): void {
        if (!isDefinitionFile(context.filename)) {
          return;
        }
        const moduleDecl = nullThrows(
          node.parent.parent,
          NullThrowsReasons.MissingParent,
        ) as ModuleDeclarationWithBody;

        if (checkForOverridingExportStatements(moduleDecl)) {
          return;
        }

      },
    };

    functioncheckModuleDeclForExportEquals(
      node: TSESTree.TSModuleDeclaration,
    functioncheckForOverridingExportStatements(
      node:ModuleDeclarationWithBody |TSESTree.Program,
    ): boolean {
      const cached = MODULE_DECL_CACHE.get(node);
      if (cached != null) {
        return cached;
      }

      if (node.body) {
        for (const statement of node.body.body) {
          if (statement.type === AST_NODE_TYPES.TSExportAssignment) {
            MODULE_DECL_CACHE.set(node, true);
            return true;
          }
        }
      const body = getStatementsOfNode(node);

      if (hasOverridingExportStatement(body)) {
        MODULE_DECL_CACHE.set(node, true);
        return true;
      }

      MODULE_DECL_CACHE.set(node, false);
      | TSESTree.TSModuleDeclaration
      | TSESTree.TSTypeAliasDeclaration
      | TSESTree.VariableDeclaration;
    function ambientDeclarationSelector(
      parent: string,
      childDeclare: boolean,
    ): string {
    function ambientDeclarationSelector(parent: string): string {
      return [
        // Types are ambiently exported
        `${parent} > :matches(${[
          AST_NODE_TYPES.TSEnumDeclaration,
          AST_NODE_TYPES.TSModuleDeclaration,
          AST_NODE_TYPES.VariableDeclaration,
        ].join(', ')})${childDeclare ? '[declare = true]' : ''}`,
        ].join(', ')})`,
      ].join(', ');
    }
    function markDeclarationChildAsUsed(node: DeclarationSelectorNode): void {
  },
 });

 function hasOverridingExportStatement(
  body: TSESTree.ProgramStatement[],
 ): boolean {
  for (const statement of body) {
    if (
      (statement.type === AST_NODE_TYPES.ExportNamedDeclaration &&
        statement.declaration == null) ||
      statement.type === AST_NODE_TYPES.ExportAllDeclaration ||
      statement.type === AST_NODE_TYPES.TSExportAssignment
    ) {
      return true;
    }

    if (
      statement.type === AST_NODE_TYPES.ExportDefaultDeclaration &&
      statement.declaration.type === AST_NODE_TYPES.Identifier
    ) {
      return true;
    }
  }

  return false;
 }

 function getStatementsOfNode(
  block: ModuleDeclarationWithBody | TSESTree.Program,
 ): TSESTree.ProgramStatement[] {
  if (block.type === AST_NODE_TYPES.Program) {
    return block.body;
  }

  return block.body.body;
 }

 /*

 ###### TODO ######
Original file line number	Diff line number	Diff line change
Expand Up		@@ -10,6 +10,8 @@ import {
		} from '@typescript-eslint/scope-manager';
		import { AST_NODE_TYPES, TSESLint } from '@typescript-eslint/utils';

		import type { MakeRequired } from '../util';

		import {
		collectVariables,
		createRule,
Expand DownExpand Up		@@ -58,6 +60,11 @@ type VariableType =
		\| 'parameter'
		\| 'variable';

		type ModuleDeclarationWithBody = MakeRequired<
		TSESTree.TSModuleDeclaration,
		'body'
		>;

		export default createRule<Options, MessageIds>({
		name: 'no-unused-vars',
		meta: {
Expand DownExpand Up		@@ -144,7 +151,10 @@ export default createRule<Options, MessageIds>({
		},
		defaultOptions: [{}],
		create(context, [firstOption]) {
		const MODULE_DECL_CACHE = new Map<TSESTree.TSModuleDeclaration, boolean>();
		const MODULE_DECL_CACHE = new Map<
		ModuleDeclarationWithBody \| TSESTree.Program,
		boolean
		>();

		const options = ((): TranslatedOptions => {
		const options: TranslatedOptions = {
Expand DownExpand Up		@@ -557,40 +567,71 @@ export default createRule<Options, MessageIds>({
		}

		return {
		// declaration file handling
		[ambientDeclarationSelector(AST_NODE_TYPES.Program, true)](
		//top-leveldeclaration file handling
		[ambientDeclarationSelector(AST_NODE_TYPES.Program)](
Copy link MemberAuthor ronamiJan 26, 2025• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Testing various edge cases, I think that only checking `declare'd module-level values creates some incorrect reports (playground link). Removing this didn't cause any tests to fail, though I could be missing an edge case. JoshuaKGoldberg reacted with thumbs up emoji
		node: DeclarationSelectorNode,
		): void {
		if (!isDefinitionFile(context.filename)) {
		return;
		}

		const moduleDecl = nullThrows(
		node.parent,
		NullThrowsReasons.MissingParent,
		) as TSESTree.Program;

		if (checkForOverridingExportStatements(moduleDecl)) {
		return;
		}
Comment on lines +578 to +585 Copy link MemberAuthor ronamiFeb 2, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. This addition is so the rule would report the following (playground link): // should be reported but doesn'tdeclareclassFoo{}export{} Along with not reporting on the following (playground link): // reported but shouldn'tclassFoo{}// even though this shows up as a compiler error, this isn't marked as used// uncomment the code below and TypeScript would mark this as unused:// export {}; JoshuaKGoldberg reacted with thumbs up emoji

		markDeclarationChildAsUsed(node);
		},

		// children of a namespace that is a child of a declared namespace are auto-exported
		[ambientDeclarationSelector(
		'TSModuleDeclaration[declare = true] > TSModuleBlock TSModuleDeclaration > TSModuleBlock',
		false,
		)](node: DeclarationSelectorNode): void {
		const moduleDecl = nullThrows(
		node.parent.parent,
		NullThrowsReasons.MissingParent,
		) as ModuleDeclarationWithBody;

		if (checkForOverridingExportStatements(moduleDecl)) {
		return;
		}

		markDeclarationChildAsUsed(node);
		},

		// declared namespace handling
		[ambientDeclarationSelector(
		'TSModuleDeclaration[declare = true] > TSModuleBlock',
		false,
		)](node: DeclarationSelectorNode): void {
		const moduleDecl = nullThrows(
		node.parent.parent,
		NullThrowsReasons.MissingParent,
		) asTSESTree.TSModuleDeclaration;
		) asModuleDeclarationWithBody;

		// declared ambient modules with an `export =` statement will only export that one thing
		// all other statements are not automatically exported in this case
		if (
		moduleDecl.id.type === AST_NODE_TYPES.Literal &&
		checkModuleDeclForExportEquals(moduleDecl)
		) {
		if (checkForOverridingExportStatements(moduleDecl)) {
		return;
		}

		markDeclarationChildAsUsed(node);
		},

		// namespace handling in definition files
		[ambientDeclarationSelector('TSModuleDeclaration > TSModuleBlock')](
		node: DeclarationSelectorNode,
		): void {
		if (!isDefinitionFile(context.filename)) {
		return;
		}
		const moduleDecl = nullThrows(
		node.parent.parent,
		NullThrowsReasons.MissingParent,
		) as ModuleDeclarationWithBody;

		if (checkForOverridingExportStatements(moduleDecl)) {
		return;
		}

Expand DownExpand Up		@@ -670,21 +711,19 @@ export default createRule<Options, MessageIds>({
		},
		};

		functioncheckModuleDeclForExportEquals(
		node: TSESTree.TSModuleDeclaration,
		functioncheckForOverridingExportStatements(
		node:ModuleDeclarationWithBody \|TSESTree.Program,
		): boolean {
		const cached = MODULE_DECL_CACHE.get(node);
		if (cached != null) {
		return cached;
		}

		if (node.body) {
		for (const statement of node.body.body) {
		if (statement.type === AST_NODE_TYPES.TSExportAssignment) {
		MODULE_DECL_CACHE.set(node, true);
		return true;
		}
		}
		const body = getStatementsOfNode(node);

		if (hasOverridingExportStatement(body)) {
		MODULE_DECL_CACHE.set(node, true);
		return true;
		}

		MODULE_DECL_CACHE.set(node, false);
Expand All		@@ -700,10 +739,7 @@ export default createRule<Options, MessageIds>({
		\| TSESTree.TSModuleDeclaration
		\| TSESTree.TSTypeAliasDeclaration
		\| TSESTree.VariableDeclaration;
		function ambientDeclarationSelector(
		parent: string,
		childDeclare: boolean,
		): string {
		function ambientDeclarationSelector(parent: string): string {
		return [
		// Types are ambiently exported
		`${parent} > :matches(${[
Expand All		@@ -717,7 +753,7 @@ export default createRule<Options, MessageIds>({
		AST_NODE_TYPES.TSEnumDeclaration,
		AST_NODE_TYPES.TSModuleDeclaration,
		AST_NODE_TYPES.VariableDeclaration,
		].join(', ')})${childDeclare ? '[declare = true]' : ''}`,
		].join(', ')})`,
		].join(', ');
		}
		function markDeclarationChildAsUsed(node: DeclarationSelectorNode): void {
Expand DownExpand Up		@@ -774,6 +810,40 @@ export default createRule<Options, MessageIds>({
		},
		});

		function hasOverridingExportStatement(
		body: TSESTree.ProgramStatement[],
		): boolean {
		for (const statement of body) {
		if (
		(statement.type === AST_NODE_TYPES.ExportNamedDeclaration &&
		statement.declaration == null) \|\|
		statement.type === AST_NODE_TYPES.ExportAllDeclaration \|\|
		statement.type === AST_NODE_TYPES.TSExportAssignment
		) {
		return true;
		}

		if (
		statement.type === AST_NODE_TYPES.ExportDefaultDeclaration &&
		statement.declaration.type === AST_NODE_TYPES.Identifier
		) {
		return true;
		}
		}

		return false;
		}

		function getStatementsOfNode(
		block: ModuleDeclarationWithBody \| TSESTree.Program,
		): TSESTree.ProgramStatement[] {
		if (block.type === AST_NODE_TYPES.Program) {
		return block.body;
		}

		return block.body.body;
		}

		/*

		###### TODO ######
Expand Down