[ty] Generate and add rules table (#17953)

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ exclude: |
     .github/workflows/release.yml|
     crates/ty_vendored/vendor/.*|
     crates/ty_project/resources/.*|
+    crates/ty/docs/rules.md|
     crates/ruff_benchmark/resources/.*|
     crates/ruff_linter/resources/.*|
     crates/ruff_linter/src/rules/.*/snapshots/.*|

Cargo.lock

@@ -2726,6 +2726,7 @@ dependencies = [
  "tracing-indicatif",
  "tracing-subscriber",
  "ty_project",
+ "url",
 ]
 
 [[package]]

crates/ruff_dev/Cargo.toml

@@ -44,6 +44,7 @@ toml = { workspace = true, features = ["parse"] }
 tracing = { workspace = true }
 tracing-indicatif = { workspace = true }
 tracing-subscriber = { workspace = true, features = ["env-filter"] }
+url = { workspace = true }
 
 [dev-dependencies]
 indoc = { workspace = true }

crates/ruff_dev/src/generate_all.rs

@@ -2,7 +2,9 @@
 
 use anyhow::Result;
 
-use crate::{generate_cli_help, generate_docs, generate_json_schema, generate_ty_schema};
+use crate::{
+    generate_cli_help, generate_docs, generate_json_schema, generate_ty_rules, generate_ty_schema,
+};
 
 pub(crate) const REGENERATE_ALL_COMMAND: &str = "cargo dev generate-all";
 
@@ -38,5 +40,6 @@ pub(crate) fn main(args: &Args) -> Result<()> {
     generate_docs::main(&generate_docs::Args {
         dry_run: args.mode.is_dry_run(),
     })?;
+    generate_ty_rules::main(&generate_ty_rules::Args { mode: args.mode })?;
     Ok(())
 }

crates/ruff_dev/src/generate_ty_rules.rs

@@ -0,0 +1,144 @@
+//! Generates the rules table for ty
+#![allow(clippy::print_stdout, clippy::print_stderr)]
+
+use std::borrow::Cow;
+use std::fmt::Write as _;
+use std::fs;
+use std::path::PathBuf;
+
+use anyhow::{bail, Result};
+use itertools::Itertools as _;
+use pretty_assertions::StrComparison;
+
+use crate::generate_all::{Mode, REGENERATE_ALL_COMMAND};
+use crate::ROOT_DIR;
+
+#[derive(clap::Args)]
+pub(crate) struct Args {
+    /// Write the generated table to stdout (rather than to `ty.schema.json`).
+    #[arg(long, default_value_t, value_enum)]
+    pub(crate) mode: Mode,
+}
+
+pub(crate) fn main(args: &Args) -> Result<()> {
+    let markdown = generate_markdown();
+    let filename = "crates/ty/docs/rules.md";
+    let schema_path = PathBuf::from(ROOT_DIR).join(filename);
+
+    match args.mode {
+        Mode::DryRun => {
+            println!("{markdown}");
+        }
+        Mode::Check => {
+            let current = fs::read_to_string(schema_path)?;
+            if current == markdown {
+                println!("Up-to-date: {filename}");
+            } else {
+                let comparison = StrComparison::new(&current, &markdown);
+                bail!("{filename} changed, please run `{REGENERATE_ALL_COMMAND}`:\n{comparison}");
+            }
+        }
+        Mode::Write => {
+            let current = fs::read_to_string(&schema_path)?;
+            if current == markdown {
+                println!("Up-to-date: {filename}");
+            } else {
+                println!("Updating: {filename}");
+                fs::write(schema_path, markdown.as_bytes())?;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn generate_markdown() -> String {
+    let registry = &*ty_project::DEFAULT_LINT_REGISTRY;
+
+    let mut output = String::new();
+
+    let _ = writeln!(&mut output, "# Rules\n");
+
+    let mut lints: Vec<_> = registry.lints().iter().collect();
+    lints.sort_by(|a, b| {
+        a.default_level()
+            .cmp(&b.default_level())
+            .reverse()
+            .then_with(|| a.name().cmp(&b.name()))
+    });
+
+    for lint in lints {
+        let _ = writeln!(&mut output, "## `{rule_name}`\n", rule_name = lint.name());
+
+        // Increase the header-level by one
+        let documentation = lint
+            .documentation_lines()
+            .map(|line| {
+                if line.starts_with('#') {
+                    Cow::Owned(format!("#{line}"))
+                } else {
+                    Cow::Borrowed(line)
+                }
+            })
+            .join("\n");
+
+        let _ = writeln!(
+            &mut output,
+            r#"**Default level**: {level}
+
+<details>
+<summary>{summary}</summary>
+
+{documentation}
+
+### Links
+* [Related issues](https://github.com/astral-sh/ty/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20{encoded_name})
+* [View source](https://github.com/astral-sh/ruff/blob/main/{file}#L{line})
+</details>
+"#,
+            level = lint.default_level(),
+            // GitHub doesn't support markdown in `summary` headers
+            summary = replace_inline_code(lint.summary()),
+            encoded_name = url::form_urlencoded::byte_serialize(lint.name().as_str().as_bytes())
+                .collect::<String>(),
+            file = url::form_urlencoded::byte_serialize(lint.file().replace('\\', "/").as_bytes())
+                .collect::<String>(),
+            line = lint.line(),
+        );
+    }
+
+    output
+}
+
+/// Replaces inline code blocks (`code`) with `<code>code</code>`
+fn replace_inline_code(input: &str) -> String {
+    let mut output = String::new();
+    let mut parts = input.split('`');
+
+    while let Some(before) = parts.next() {
+        if let Some(between) = parts.next() {
+            output.push_str(before);
+            output.push_str("<code>");
+            output.push_str(between);
+            output.push_str("</code>");
+        } else {
+            output.push_str(before);
+        }
+    }
+
+    output
+}
+
+#[cfg(test)]
+mod tests {
+    use anyhow::Result;
+
+    use crate::generate_all::Mode;
+
+    use super::{main, Args};
+
+    #[test]
+    fn ty_rules_up_to_date() -> Result<()> {
+        main(&Args { mode: Mode::Check })
+    }
+}

crates/ruff_dev/src/main.rs

@@ -15,6 +15,7 @@ mod generate_docs;
 mod generate_json_schema;
 mod generate_options;
 mod generate_rules_table;
+mod generate_ty_rules;
 mod generate_ty_schema;
 mod print_ast;
 mod print_cst;
@@ -44,6 +45,7 @@ enum Command {
     GenerateTySchema(generate_ty_schema::Args),
     /// Generate a Markdown-compatible table of supported lint rules.
     GenerateRulesTable,
+    GenerateTyRules(generate_ty_rules::Args),
     /// Generate a Markdown-compatible listing of configuration options.
     GenerateOptions,
     /// Generate CLI help.
@@ -88,6 +90,7 @@ fn main() -> Result<ExitCode> {
         Command::GenerateJSONSchema(args) => generate_json_schema::main(&args)?,
         Command::GenerateTySchema(args) => generate_ty_schema::main(&args)?,
         Command::GenerateRulesTable => println!("{}", generate_rules_table::generate()),
+        Command::GenerateTyRules(args) => generate_ty_rules::main(&args)?,
         Command::GenerateOptions => println!("{}", generate_options::generate()),
         Command::GenerateCliHelp(args) => generate_cli_help::main(&args)?,
         Command::GenerateDocs(args) => generate_docs::main(&args)?,

crates/ty_python_semantic/src/types/diagnostic.rs

@@ -646,7 +646,7 @@ declare_lint! {
     /// must be assigned the value `False` at runtime; the type checker will consider its value to
     /// be `True`. If annotated, it must be annotated as a type that can accept `bool` values.
     pub(crate) static INVALID_TYPE_CHECKING_CONSTANT = {
-        summary: "detects invalid TYPE_CHECKING constant assignments",
+        summary: "detects invalid `TYPE_CHECKING` constant assignments",
         status: LintStatus::preview("1.0.0"),
         default_level: Level::Error,
     }

ty.schema.json

@@ -551,7 +551,7 @@
           ]
         },
         "invalid-type-checking-constant": {
-          "title": "detects invalid TYPE_CHECKING constant assignments",
+          "title": "detects invalid `TYPE_CHECKING` constant assignments",
           "description": "## What it does\nChecks for a value other than `False` assigned to the `TYPE_CHECKING` variable, or an\nannotation not assignable from `bool`.\n\n## Why is this bad?\nThe name `TYPE_CHECKING` is reserved for a flag that can be used to provide conditional\ncode seen only by the type checker, and not at runtime. Normally this flag is imported from\n`typing` or `typing_extensions`, but it can also be defined locally. If defined locally, it\nmust be assigned the value `False` at runtime; the type checker will consider its value to\nbe `True`. If annotated, it must be annotated as a type that can accept `bool` values.",
           "default": "error",
           "oneOf": [