add "recommended" typeCheckingMode which sets the category to warning for less severe diagnostics, and failOnWarnings config option which is enabled by default in this mode

.github/workflows/docs.yaml

@@ -43,7 +43,7 @@ jobs:
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
       - name: install dependencies
-        run: ./pw pdm install --no-self
+        run: ./pw pdm install
       - name: validate docs
         run: ./pw pdm run mkdocs build --strict
       - name: deploy dev docs

.vscode/launch.json

@@ -1,6 +1,14 @@
 {
     "version": "0.2.0",
     "configurations": [
+        {
+            "name":"Python Current File (justMyCode=false)",
+            "type":"debugpy",
+            "request":"launch",
+            "program":"${file}",
+            "console":"integratedTerminal",
+            "justMyCode": false
+        },
         {
             "name": "Pyright current file",
             "type": "node",

.vscode/tasks.json

@@ -80,7 +80,7 @@
           "label": "install dependencies",
           "type": "shell",
           "command": "./pw",
-          "args": ["pdm", "sync", "--clean", "-G:all"],
+          "args": ["pdm", "sync", "--clean", "-G", "dev", "-G", "docstubs", "-G", "lochelper"],
           "presentation": {
             "clear": true
           },

based_build/docs_macros.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+from functools import partial
+from subprocess import run as stupid_run
+from typing import TYPE_CHECKING, Iterable
+
+if TYPE_CHECKING:
+    from mkdocs_macros.plugin import MacrosPlugin
+
+run = partial(stupid_run, check=True, capture_output=True)
+
+
+def define_env(env: MacrosPlugin):
+    env.macro(generate_diagnostic_rule_table)  # pyright:ignore[reportUnknownMemberType]
+
+
+def generate_diagnostic_rule_table() -> str:
+    """generates the table of `typeCheckingMode` defaults"""
+    _ = run(["npm", "run", "build:cli:dev"])
+    diagnostic_rulesets: list[dict[str, bool | str]] = json.loads(
+        run(["node", "packages/pyright/index.js", "--printdiagnosticrulesets"]).stdout
+    )
+    headers = diagnostic_rulesets[0].keys()
+    result: list[Iterable[str]] = [(f"**{header}**" for header in headers), (":-" for _ in headers)]
+    for row in diagnostic_rulesets:
+        diagnostic_rule, *values = row.values()
+        result.append([str(diagnostic_rule), *(json.dumps(value) for value in values)])
+    return "\n".join("|".join(row) for row in result)

docs/benefits-over-pyright/better-defaults.md

@@ -1,10 +1,13 @@
 # better defaults
 
-we believe that type checkers and linters should be as strict as possible by default, making the user aware of all the available rules so they can more easily make informed decisions about which rules they don't want enabled in their project. that's why the following defaults have been changed in basedpyright
+we believe that type checkers and linters should be as strict as possible by default. this ensures that the user aware of all the available rules so they can more easily make informed decisions about which rules they don't want enabled in their project. that's why the following defaults have been changed in basedpyright.
 
 ## `typeCheckingMode`
 
-used to be `basic`, but now defaults to `all`. while this may seem daunting at first, we support [baselining](./baseline.md) to allow for easy adoption of more strict rules in existing codebases.
+used to be `"basic"`, but now defaults to `"recommended"`, which enables all diagnostic rules by default. this may seem daunting at first, however we have some solutions to address some concerns users may have with this mode:
+
+-   less severe diagnostic rules are reported as warnings instead of errors. this reduces [alarm fatigue](https://en.wikipedia.org/wiki/Alarm_fatigue) while still ensuring that the user is made aware of all potentential issues that basedpyright can detect. `failOnWarnings` is also enabled by default in this mode, which causes the CLI to exit with a non-zero exit code if any warnings are detected. you disable this behavior by setting `failOnWarnings` to `false`.
+-   we support [baselining](./baseline.md) to allow for easy adoption of more strict rules in existing codebases.
 
 ## `pythonPlatform`
 

docs/configuration/config-files.md

@@ -1,6 +1,10 @@
 <!--
-this file is defined elsewhere and imported here because previous versions of basedpyright contain links to documentation for each diagnostic rule,
+most of this file is defined elsewhere and imported here because previous versions of basedpyright contain links to documentation for each diagnostic rule,
 eg. "https://github.com/microsoft/pyright/blob/main/docs/configuration.md#reportGeneralTypeIssues and we don't want to break those links for users
 who haven't yet updated to >=1.18.1
 -->
---8<-- "docs/configuration.md"
+--8<-- "docs/configuration.md:before-table"
+
+{{ generate_diagnostic_rule_table() }}
+
+--8<-- "docs/configuration.md:after-table"

docs/configuration/language-server-settings.md

@@ -69,7 +69,7 @@ however these settings are still suppored to maintain compatibility with pyright
 
 **basedpyright.analysis.stubPath** [path]: Path to directory containing custom type stub files.
 
-**basedpyright.analysis.typeCheckingMode** ["off", "basic", "standard", "strict", "all"]: Determines the default type-checking level used by pyright. This can be overridden in the configuration file. (Note: This setting used to be called "pyright.typeCheckingMode". The old name is deprecated but is still currently honored.)
+**basedpyright.analysis.typeCheckingMode** ["off", "basic", "standard", "strict", "recommended", "all"]: Determines the default type-checking level used by pyright. This can be overridden in the configuration file. (Note: This setting used to be called "basedpyright.typeCheckingMode". The old name is deprecated but is still currently honored.)
 
 **basedpyright.analysis.typeshedPaths** [array of paths]: Paths to look for typeshed modules. Pyright currently honors only the first path in the array.
 

docs/stylesheets/extra.css

@@ -1,3 +1,3 @@
 .md-grid {
-    max-width: 1500px;
+    max-width: 1600px;
 }

mkdocs.yml

@@ -50,6 +50,9 @@ plugins:
   - awesome-pages
   # https://github.com/wilhelmer/mkdocs-unused-files/issues/12
   # - unused_files
+  - macros:
+      module_name: based_build/docs_macros
+      on_undefined: strict
 nav:
   - index.md
   - ... | benefits-over-pyright/**/*.md

packages/pyright-internal/src/analyzer/service.ts

@@ -674,7 +674,7 @@ export class AnalyzerService {
                 throw e;
             }
         }
-        configOptions.initializeTypeCheckingMode('all');
+        configOptions.initializeTypeCheckingMode('recommended');
         if (configs && configs.length > 0) {
             // Then we apply the config file settings. This can update the
             // the typeCheckingMode.
@@ -694,15 +694,24 @@ export class AnalyzerService {
 
             // When not in language server mode, command line options override config file options.
             if (!commandLineOptions.fromLanguageServer) {
-                this._applyCommandLineOverrides(configOptions, commandLineOptions.configSettings, projectRoot, false);
+                errors.push(
+                    ...this._applyCommandLineOverrides(
+                        configOptions,
+                        commandLineOptions.configSettings,
+                        projectRoot,
+                        false
+                    )
+                );
             }
         } else {
             // If there are no config files, we can then directly apply the command line options.
-            this._applyCommandLineOverrides(
-                configOptions,
-                commandLineOptions.configSettings,
-                projectRoot,
-                commandLineOptions.fromLanguageServer
+            errors.push(
+                ...this._applyCommandLineOverrides(
+                    configOptions,
+                    commandLineOptions.configSettings,
+                    projectRoot,
+                    commandLineOptions.fromLanguageServer
+                )
             );
         }
 
@@ -922,10 +931,8 @@ export class AnalyzerService {
         commandLineOptions: CommandLineConfigOptions,
         projectRoot: Uri,
         fromLanguageServer: boolean
-    ) {
-        if (commandLineOptions.typeCheckingMode) {
-            configOptions.initializeTypeCheckingMode(commandLineOptions.typeCheckingMode);
-        }
+    ): string[] {
+        const errors = configOptions.initializeTypeCheckingModeFromString(commandLineOptions.typeCheckingMode);
 
         if (commandLineOptions.extraPaths) {
             configOptions.ensureDefaultExtraPaths(
@@ -1029,6 +1036,7 @@ export class AnalyzerService {
                 reportDuplicateSetting('stubPath', configOptions.stubPath.toUserVisibleString());
             }
         }
+        return errors;
     }
 
     // Loads the config JSON object from the specified config file along with any

packages/pyright-internal/src/common/commandLineOptions.ts

@@ -94,8 +94,7 @@ export class CommandLineConfigOptions {
     // when user has not explicitly defined execution environments.
     extraPaths?: string[] | undefined;
 
-    // Default type-checking rule set. Should be one of 'off',
-    // 'basic', 'standard', 'strict' or 'all'.
+    // Default type-checking rule set.
     typeCheckingMode?: string | undefined;
 
     // Indicates diagnostic severity overrides