Warn on module level type ignore with error code (#13512)

Per-module error codes were added in #13502, let's recommend using them.

The existing type ignore behaviour is pretty unintuitive; I think most
people actually want `# mypy: ignore-errors`. There are probably people
depending on the current behaviour though.

Fixes #13435, fixes #12076, fixes #11999, fixes #11027, fixes #9318,
fixes #7839

docs/source/common_issues.rst

@@ -187,7 +187,13 @@ Ignoring a whole file
 ---------------------
 
 A ``# type: ignore`` comment at the top of a module (before any statements,
-including imports or docstrings) has the effect of ignoring the *entire* module.
+including imports or docstrings) has the effect of ignoring the entire contents of the module.
+
+To only ignore errors, use a top-level ``# mypy: ignore-errors`` comment instead.
+To only ignore errors with a specific error code, use a top-level
+``# mypy: disable-error-code=...`` comment.
+To replace the contents of the module with ``Any``, use a per-module ``follow_imports = skip``.
+See :ref:`Following imports <follow-imports>` for details.
 
 .. code-block:: python
 

mypy/fastparse.py

@@ -483,6 +483,16 @@ def translate_stmt_list(
             and self.type_ignores
             and min(self.type_ignores) < self.get_lineno(stmts[0])
         ):
+            if self.type_ignores[min(self.type_ignores)]:
+                self.fail(
+                    (
+                        "type ignore with error code is not supported for modules; "
+                        "use `# mypy: disable-error-code=...`"
+                    ),
+                    line=min(self.type_ignores),
+                    column=0,
+                    blocker=False,
+                )
             self.errors.used_ignored_lines[self.errors.file][min(self.type_ignores)].append(
                 codes.FILE.code
             )

test-data/unit/check-errorcodes.test

@@ -920,3 +920,8 @@ def f(d: D, s: str) -> None:
     d[s]  # type: ignore[literal-required]
 [builtins fixtures/dict.pyi]
 [typing fixtures/typing-typeddict.pyi]
+
+
+[case testRecommendErrorCode]
+# type: ignore[whatever]  # E: type ignore with error code is not supported for modules; use `# mypy: disable-error-code=...`  [syntax]
+1 + "asdf"