fix Support for runtime enforcement of required version in pyrefly.toml #3314

crates/pyrefly_config/Cargo.toml

@@ -18,6 +18,7 @@ dupe = "0.9.1"
 enum-iterator = "2.3.0"
 itertools = "0.15.0"
 parse-display = "0.8.2"
+pep440_rs = "0.7.3"
 pyrefly_build = { path = "../pyrefly_build" }
 pyrefly_python = { path = "../pyrefly_python" }
 pyrefly_util = { path = "../pyrefly_util" }

crates/pyrefly_config/src/config.rs

@@ -23,6 +23,8 @@ use clap::ValueEnum;
 use derivative::Derivative;
 use dupe::Dupe as _;
 use itertools::Itertools;
+use pep440_rs::Version;
+use pep440_rs::VersionSpecifiers;
 use pyrefly_build::BuildSystem;
 use pyrefly_build::handle::Handle;
 use pyrefly_build::source_db::SourceDatabase;
@@ -518,6 +520,9 @@ pub struct ConfigFile {
     #[serde(skip)]
     pub source: ConfigSource,
 
+    /// The PEP 440 version requirement that the running Pyrefly must satisfy.
+    pub required_version: Option<String>,
+
     /// Files that should be counted as sources (e.g. user-space code).
     /// NOTE: unlike other args, this is never replaced with CLI arg overrides
     /// in this config, but may be overridden by CLI args where used.
@@ -683,6 +688,7 @@ impl Default for ConfigFile {
     fn default() -> Self {
         ConfigFile {
             source: ConfigSource::Synthetic,
+            required_version: None,
             project_includes: Default::default(),
             project_excludes: Default::default(),
             interpreters: Interpreters {
@@ -1659,6 +1665,25 @@ impl ConfigFile {
             };
             config.source = config_source;
 
+            if let Some(required_version) = &config.required_version {
+                match required_version.parse::<VersionSpecifiers>() {
+                    Ok(specifiers) => {
+                        let running_version = env!("CARGO_PKG_VERSION");
+                        let parsed_running_version = running_version
+                            .parse::<Version>()
+                            .expect("Pyrefly's package version must be PEP 440 compatible");
+                        if !specifiers.contains(&parsed_running_version) {
+                            errors.push(ConfigError::error(anyhow!(
+                                "Pyrefly {running_version} does not satisfy `required-version = \"{required_version}\"`"
+                            )));
+                        }
+                    }
+                    Err(error) => errors.push(ConfigError::error(anyhow!(
+                        "Invalid `required-version` `{required_version}`: {error}"
+                    ))),
+                }
+            }
+
             if !config.root.extras.0.is_empty() {
                 let extra_keys = config.root.extras.0.keys().join(", ");
                 errors.push(ConfigError::warn(anyhow!(
@@ -1911,6 +1936,7 @@ mod tests {
             config,
             ConfigFile {
                 source: ConfigSource::Synthetic,
+                required_version: None,
                 project_includes: Globs::new(vec![
                     "tests".to_owned(),
                     "./implementation".to_owned()
@@ -2297,6 +2323,7 @@ mod tests {
         let interpreter = "venv/bin/python3".to_owned();
         let mut config = ConfigFile {
             source: ConfigSource::Synthetic,
+            required_version: None,
             project_includes: Globs::new(vec!["path1/**".to_owned(), "path2/path3".to_owned()])
                 .unwrap(),
             project_excludes: Globs::new(vec!["tests/untyped/**".to_owned()]).unwrap(),
@@ -2371,6 +2398,7 @@ mod tests {
 
         let expected_config = ConfigFile {
             source: ConfigSource::Synthetic,
+            required_version: None,
             project_includes: Globs::new(project_includes_vec).unwrap(),
             project_excludes: Globs::new(project_excludes_vec).unwrap(),
             interpreters: Interpreters {
@@ -3825,6 +3853,30 @@ output-format = "omit-errors"
         assert_eq!(config.source.root(), Some(root.path()));
     }
 
+    #[test]
+    fn test_required_version() {
+        let root = TempDir::new().unwrap();
+        let path = root.path().join(ConfigFile::PYREFLY_FILE_NAME);
+        for (required_version, expect_error) in [
+            (format!("=={}", env!("CARGO_PKG_VERSION")), false),
+            ("<0".to_owned(), true),
+            ("not a specifier".to_owned(), true),
+        ] {
+            fs::write(&path, format!("required-version = {required_version:?}")).unwrap();
+            let (config, errors) = ConfigFile::from_file(&path);
+            assert_eq!(
+                config.required_version.as_deref(),
+                Some(required_version.as_str())
+            );
+            if expect_error {
+                assert_eq!(errors.len(), 1);
+                assert_eq!(errors[0].severity(), Severity::Error);
+            } else {
+                assert!(errors.is_empty());
+            }
+        }
+    }
+
     #[test]
     fn test_explicit_search_path_wins_over_site_packages() {
         // An explicit search path should take priority over a site-package

schemas/pyrefly.json

@@ -105,6 +105,11 @@
     {
       "type": "object",
       "properties": {
+        "required-version": {
+          "description": "A PEP 440 version specifier that the running version of Pyrefly must satisfy.",
+          "type": "string",
+          "examples": [">=1.2.0", ">=1.2.0,<2.0.0", "==1.2.0"]
+        },
         "preset": {
           "description": "Named preset that provides default error severities and behavior settings. User-specified settings override the preset.",
           "type": "string",

schemas/test-pyproject.toml

@@ -5,6 +5,9 @@ name = "example-project"
 version = "0.1.0"
 
 [tool.pyrefly]
+# Runtime version requirement
+required-version = ">=0.0.0.dev0"
+
 # Basic project configuration
 project-includes = ["src", "tests"]
 project-excludes = ["**/node_modules", "**/__pycache__"]

schemas/test-pyrefly.toml

@@ -4,6 +4,9 @@
 # Preset (named collection of defaults applied as the base config)
 preset = "legacy"
 
+# Runtime version requirement
+required-version = ">=0.0.0.dev0"
+
 # Basic project configuration
 project-includes = ["src", "tests"]
 project-excludes = ["**/node_modules", "**/__pycache__"]

website/docs/configuration.mdx

@@ -546,6 +546,30 @@ set on the CLI.
     - `"junit-xml"` emits a JUnit XML `<testsuites>` report suitable for CI
       dashboards (Jenkins, GitLab MR widgets, CircleCI, Azure DevOps, etc.).
 
+### `required-version`
+
+Enforces a requirement on the version of Pyrefly at runtime. Pyrefly reports a
+configuration error if its version does not satisfy the requirement. This can
+keep local CLI runs, editor integrations, and CI on compatible versions.
+
+```toml
+# pyrefly.toml
+required-version = ">=1.2.0,<2.0.0"
+```
+
+```toml
+# pyproject.toml
+[tool.pyrefly]
+required-version = ">=1.2.0,<2.0.0"
+```
+
+- Type: string containing a [PEP 440 version specifier](https://peps.python.org/pep-0440/#version-specifiers)
+- Default: none
+- Flag equivalent: none
+- Notes:
+    - `required-version` is a **project-level setting** and cannot be overridden
+      in [`sub-config`](#sub-configs) sections.
+
 ### `preset`
 
 A named collection of error severities and behavior settings that serves as the base configuration.