pyrefly 0.25.1__tar.gz → 0.26.0__tar.gz

{pyrefly-0.25.1 → pyrefly-0.26.0}/Cargo.lock

@@ -2029,7 +2029,7 @@ dependencies = [
 
 [[package]]
 name = "pyrefly"
-version = "0.25.1"
+version = "0.26.0"
 dependencies = [
  "anstream",
  "anyhow",
@@ -2076,7 +2076,7 @@ dependencies = [
 
 [[package]]
 name = "pyrefly_bundled"
-version = "0.25.1"
+version = "0.26.0"
 dependencies = [
  "anyhow",
  "starlark_map",
@@ -2086,7 +2086,7 @@ dependencies = [
 
 [[package]]
 name = "pyrefly_config"
-version = "0.25.1"
+version = "0.26.0"
 dependencies = [
  "anyhow",
  "clap",
@@ -2119,7 +2119,7 @@ dependencies = [
 
 [[package]]
 name = "pyrefly_derive"
-version = "0.25.1"
+version = "0.26.0"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2128,7 +2128,7 @@ dependencies = [
 
 [[package]]
 name = "pyrefly_python"
-version = "0.25.1"
+version = "0.26.0"
 dependencies = [
  "anyhow",
  "dupe",
@@ -2150,8 +2150,9 @@ dependencies = [
 
 [[package]]
 name = "pyrefly_types"
-version = "0.25.1"
+version = "0.26.0"
 dependencies = [
+ "compact_str 0.8.0",
  "dupe",
  "itertools 0.14.0",
  "num-bigint",
@@ -2169,13 +2170,14 @@ dependencies = [
 
 [[package]]
 name = "pyrefly_util"
-version = "0.25.1"
+version = "0.26.0"
 dependencies = [
  "anstream",
  "anyhow",
  "append-only-vec",
  "argfile",
  "bstr",
+ "compact_str 0.8.0",
  "const-str",
  "dupe",
  "equivalent",

{pyrefly-0.25.1 → pyrefly-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrefly
-Version: 0.25.1
+Version: 0.26.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -12,8 +12,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development
 Summary: A fast Python type checker written in Rust
 Keywords: typechecker,typechecking
-Author: Meta
-License: MIT
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: homepage, https://pyrefly.org

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_bundled/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyrefly_bundled"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Meta"]
 edition = "2024"
 repository = "https://github.com/facebook/pyrefly"

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_config/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyrefly_config"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Meta"]
 edition = "2024"
 repository = "https://github.com/facebook/pyrefly"

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_config/src/config.rs

@@ -48,9 +48,8 @@ pub struct SubConfig {
 }
 
 impl SubConfig {
-    fn rewrite_with_path_to_config(&mut self, config_root: &Path) -> anyhow::Result<()> {
-        self.matches = self.matches.clone().from_root(config_root)?;
-        Ok(())
+    fn rewrite_with_path_to_config(&mut self, config_root: &Path) {
+        self.matches = self.matches.clone().from_root(config_root);
     }
 }
 
@@ -85,29 +84,43 @@ pub enum ProjectLayout {
     Flat,
     /// Python packages live in a src/ subdirectory
     Src,
+    /// The parent directory of the project root is the import root
+    /// (this is how pandas is set up for some reason)
+    Parent,
 }
 
 impl ProjectLayout {
     pub fn new(project_root: &Path) -> Self {
+        let error = |path: PathBuf, error| {
+            debug!(
+                "Error checking for existence of path {}: {}",
+                path.display(),
+                error
+            );
+            Self::default()
+        };
         let src_subdir = project_root.join("src");
         match src_subdir.try_exists() {
-            Ok(true) => Self::Src,
-            Ok(false) => Self::Flat,
-            Err(e) => {
-                debug!(
-                    "Error checking for existence of path {}: {}",
-                    src_subdir.display(),
-                    e
-                );
-                Self::default()
+            Ok(true) => return Self::Src,
+            Ok(false) => (),
+            Err(e) => return error(src_subdir, e),
+        }
+        for suffix in ["py", "pyi"] {
+            let init_file = project_root.join(format!("__init__.{suffix}"));
+            match init_file.try_exists() {
+                Ok(true) => return Self::Parent,
+                Ok(false) => (),
+                Err(e) => return error(init_file, e),
             }
         }
+        Self::Flat
     }
 
     fn get_import_root(&self, project_root: &Path) -> PathBuf {
         match self {
             Self::Flat => project_root.to_path_buf(),
             Self::Src => project_root.join("src"),
+            Self::Parent => project_root.parent().unwrap_or(project_root).to_path_buf(),
         }
     }
 }
@@ -323,14 +336,13 @@ impl ConfigFile {
         let mut result = Self {
             project_includes: Self::default_project_includes(),
             project_excludes: Self::default_project_excludes(),
-            // Note that rewrite_with_path_to_config() converts "" to the config file's containing directory.
-            import_root: Some(layout.get_import_root(Path::new(""))),
+            import_root: Some(layout.get_import_root(root)),
             ..Default::default()
         };
         // ignore failures rewriting path to config, since we're trying to construct
         // an ephemeral config for the user, and it's not fatal (but things might be
         // a little weird)
-        let _ = result.rewrite_with_path_to_config(root);
+        result.rewrite_with_path_to_config(root);
         result
     }
 
@@ -611,9 +623,9 @@ impl ConfigFile {
     /// We do this as a step separate from `configure()` because CLI args may override some of these
     /// values, but CLI args will always be relative to CWD, whereas config values should be relative
     /// to the config root.
-    fn rewrite_with_path_to_config(&mut self, config_root: &Path) -> anyhow::Result<()> {
-        self.project_includes = self.project_includes.clone().from_root(config_root)?;
-        self.project_excludes = self.project_excludes.clone().from_root(config_root)?;
+    fn rewrite_with_path_to_config(&mut self, config_root: &Path) {
+        self.project_includes = self.project_includes.clone().from_root(config_root);
+        self.project_excludes = self.project_excludes.clone().from_root(config_root);
         self.search_path_from_file
             .iter_mut()
             .for_each(|search_root| {
@@ -637,8 +649,7 @@ impl ConfigFile {
             .map(|s| s.map(|i| i.absolutize_from(config_root)));
         self.sub_configs
             .iter_mut()
-            .try_for_each(|c| c.rewrite_with_path_to_config(config_root))?;
-        Ok(())
+            .for_each(|c| c.rewrite_with_path_to_config(config_root));
     }
 
     pub fn from_file(config_path: &Path) -> (ConfigFile, Vec<ConfigError>) {
@@ -670,10 +681,7 @@ impl ConfigFile {
                 Some(config_root) => {
                     let layout = ProjectLayout::new(config_root);
                     if let Some(mut config) = maybe_config {
-                        let rewrite_error = config.rewrite_with_path_to_config(config_root);
-                        if let Err(error) = rewrite_error {
-                            errors.push(ConfigError::error(error));
-                        }
+                        config.rewrite_with_path_to_config(config_root);
                         config.import_root = Some(layout.get_import_root(config_root));
                         config
                     } else {
@@ -1128,7 +1136,7 @@ mod tests {
         )
         .unwrap();
 
-        config.rewrite_with_path_to_config(&test_path).unwrap();
+        config.rewrite_with_path_to_config(&test_path);
 
         let expected_config = ConfigFile {
             source: ConfigSource::Synthetic,

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_derive/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyrefly_derive"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Meta"]
 edition = "2024"
 repository = "https://github.com/facebook/pyrefly"

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_python/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyrefly_python"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Meta"]
 edition = "2024"
 repository = "https://github.com/facebook/pyrefly"

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_types/Cargo.toml

@@ -2,17 +2,18 @@
 
 [package]
 name = "pyrefly_types"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Meta"]
 edition = "2024"
 repository = "https://github.com/facebook/pyrefly"
 license = "MIT"
 
 [dependencies]
+compact_str = "0.8.0"
 dupe = "0.9.1"
 itertools = "0.14.0"
-num-bigint = { version = "0.4.4", features = ["rand"] }
-num-traits = { version = "0.2.18", default-features = false }
+num-bigint = { version = "0.4.6", features = ["rand"] }
+num-traits = { version = "0.2.19", default-features = false }
 parse-display = "0.8.2"
 pyrefly_derive = { path = "../pyrefly_derive" }
 pyrefly_python = { path = "../pyrefly_python" }

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_types/src/callable.rs

@@ -15,7 +15,7 @@ use pyrefly_derive::VisitMut;
 use pyrefly_python::dunder;
 use pyrefly_python::module_name::ModuleName;
 use pyrefly_util::display::commas_iter;
-use pyrefly_util::prelude::SliceExt;
+use pyrefly_util::prelude::VecExt;
 use ruff_python_ast::Keyword;
 use ruff_python_ast::name::Name;
 
@@ -46,8 +46,8 @@ impl ParamList {
     }
 
     /// Create a new ParamList from a list of types, as required position-only parameters.
-    pub fn new_types(xs: &[Type]) -> Self {
-        Self(xs.map(|t| Param::PosOnly(None, t.clone(), Required::Required)))
+    pub fn new_types(xs: Vec<Type>) -> Self {
+        Self(xs.into_map(|t| Param::PosOnly(None, t, Required::Required)))
     }
 
     /// Prepend some required position-only parameters.
@@ -200,7 +200,9 @@ pub struct FuncFlags {
     /// A `foo.setter` function, where `foo` is some `@property`-decorated function.
     /// When used to decorate a function, turns the decorated function into a property setter.
     pub is_property_setter_decorator: bool,
-    /// A function decorated with `@foo.setter`, where `foo` is some `@property`-decorated function.
+    /// If None, this is a function decorated with `@foo.setter`, where `foo` is
+    /// a property (i.e. a function decoratoed with `@property`)
+    ///
     /// The stored type is `foo` (the getter).
     pub is_property_setter_with_getter: Option<Type>,
     pub has_enum_member_decoration: bool,

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_types/src/display.rs

@@ -81,6 +81,8 @@ impl QNameInfo {
 #[derive(Debug, Default)]
 pub struct TypeDisplayContext<'a> {
     qnames: SmallMap<&'a Name, QNameInfo>,
+    /// Should we display for IDE Hover? This makes type names more readable but less precise.
+    hover: bool,
 }
 
 impl<'a> TypeDisplayContext<'a> {
@@ -118,6 +120,11 @@ impl<'a> TypeDisplayContext<'a> {
         }
     }
 
+    /// Set the context to display for hover. This makes type names more readable but less precise.
+    pub fn set_display_mode_to_hover(&mut self) {
+        self.hover = true;
+    }
+
     pub fn display(&'a self, t: &'a Type) -> impl Display + 'a {
         Fmt(|f| self.fmt(t, f))
     }
@@ -257,12 +264,16 @@ impl<'a> TypeDisplayContext<'a> {
                 write!(f, "]")
             }
             Type::BoundMethod(box BoundMethod { obj, func }) => {
-                write!(
-                    f,
-                    "BoundMethod[{}, {}]",
-                    self.display(obj),
-                    self.display(&func.as_type())
-                )
+                if self.hover {
+                    write!(f, "{}", self.display(&func.clone().as_type()))
+                } else {
+                    write!(
+                        f,
+                        "BoundMethod[{}, {}]",
+                        self.display(obj),
+                        self.display(&func.clone().as_type())
+                    )
+                }
             }
             Type::Never(NeverStyle::NoReturn) => write!(f, "NoReturn"),
             Type::Never(NeverStyle::Never) => write!(f, "Never"),
@@ -397,6 +408,7 @@ pub mod tests {
 
     use super::*;
     use crate::callable::Callable;
+    use crate::callable::FuncMetadata;
     use crate::callable::Param;
     use crate::callable::ParamList;
     use crate::callable::Required;
@@ -412,6 +424,7 @@ pub mod tests {
     use crate::type_var::Restriction;
     use crate::type_var::TypeVar;
     use crate::typed_dict::TypedDict;
+    use crate::types::BoundMethodType;
     use crate::types::TParam;
     use crate::types::TParams;
 
@@ -465,6 +478,30 @@ pub mod tests {
         )
     }
 
+    fn fake_bound_method(method_name: &str, class_name: &str, module_name_str: &str) -> Type {
+        let module_name = ModuleName::from_str(module_name_str);
+        let class = fake_class(class_name, module_name_str, 10);
+        let method = Callable::list(
+            ParamList::new(vec![Param::Pos(
+                Name::new_static("self"),
+                Type::any_explicit(),
+                Required::Required,
+            )]),
+            Type::None,
+        );
+        Type::BoundMethod(Box::new(BoundMethod {
+            obj: Type::ClassDef(class),
+            func: BoundMethodType::Function(Function {
+                signature: method,
+                metadata: FuncMetadata::def(
+                    module_name,
+                    Name::new(class_name),
+                    Name::new(method_name),
+                ),
+            }),
+        }))
+    }
+
     #[test]
     fn test_display() {
         let uniques = UniqueFactory::new();
@@ -726,4 +763,20 @@ pub mod tests {
         let td = TypedDict::new(cls, targs);
         assert_eq!(Type::TypedDict(td).to_string(), "TypedDict[C[None]]");
     }
+
+    #[test]
+    fn test_display_bound_method_for_hover() {
+        let bound_method = fake_bound_method("foo", "MyClass", "my.module");
+        let mut ctx = TypeDisplayContext::new(&[&bound_method]);
+
+        assert_eq!(
+            ctx.display(&bound_method).to_string(),
+            "BoundMethod[type[MyClass], (self: Any) -> None]"
+        );
+        ctx.set_display_mode_to_hover();
+        assert_eq!(
+            ctx.display(&bound_method).to_string(),
+            "(self: Any) -> None"
+        );
+    }
 }

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_types/src/equality.rs

@@ -8,6 +8,7 @@
 use std::hash::Hash;
 use std::sync::Arc;
 
+use compact_str::CompactString;
 use dupe::Dupe;
 use pyrefly_python::module_name::ModuleName;
 use pyrefly_util::uniques::Unique;
@@ -134,6 +135,7 @@ impl TypeEq for u64 {}
 impl TypeEq for u128 {}
 impl TypeEq for usize {}
 impl TypeEq for String {}
+impl TypeEq for CompactString {}
 impl TypeEq for str {}
 
 impl TypeEq for Name {}

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_types/src/literal.rs

@@ -9,6 +9,7 @@ use std::char;
 use std::fmt;
 use std::fmt::Display;
 
+use compact_str::CompactString;
 use pyrefly_derive::TypeEq;
 use pyrefly_derive::Visit;
 use pyrefly_derive::VisitMut;
@@ -33,7 +34,7 @@ assert_words!(Lit, 3);
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[derive(Visit, VisitMut, TypeEq)]
 pub enum Lit {
-    Str(Box<str>),
+    Str(CompactString),
     Int(LitInt),
     Bool(bool),
     Bytes(Box<[u8]>),
@@ -131,7 +132,7 @@ impl Lit {
                 }
             }
         }
-        Some(Lit::Str(collected_literals.join("").into_boxed_str()))
+        Some(Lit::Str(collected_literals.join("").into()))
     }
 
     pub fn from_int(x: &Int) -> Self {

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_types/src/types.rs

@@ -364,10 +364,13 @@ pub struct BoundMethod {
 
 impl BoundMethod {
     pub fn drop_self(&self) -> Option<Type> {
-        self.as_function().drop_first_param_of_unbound_callable()
+        self.func
+            .clone()
+            .as_type()
+            .drop_first_param_of_unbound_callable()
     }
 
-    pub fn as_function(&self) -> Type {
+    pub fn as_function(self) -> Type {
         self.func.as_type()
     }
 }
@@ -381,13 +384,11 @@ pub enum BoundMethodType {
 }
 
 impl BoundMethodType {
-    pub fn as_type(&self) -> Type {
+    pub fn as_type(self) -> Type {
         match self {
-            Self::Function(func) => Type::Function(Box::new(func.clone())),
-            Self::Forall(forall) => {
-                Forallable::Function(forall.body.clone()).forall(forall.tparams.clone())
-            }
-            Self::Overload(overload) => Type::Overload(overload.clone()),
+            Self::Function(func) => Type::Function(Box::new(func)),
+            Self::Forall(forall) => Forallable::Function(forall.body).forall(forall.tparams),
+            Self::Overload(overload) => Type::Overload(overload),
         }
     }
 

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_util/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyrefly_util"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Meta"]
 edition = "2024"
 repository = "https://github.com/facebook/pyrefly"
@@ -14,6 +14,7 @@ anyhow = "1.0.98"
 append-only-vec = "0.1.2"
 argfile = "0.2.1"
 bstr = { version = "1.10.0", features = ["serde", "std", "unicode"] }
+compact_str = "0.8.0"
 const-str = "0.4.3"
 dupe = "0.9.1"
 equivalent = "1.0"

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_util/src/globs.rs

@@ -58,13 +58,13 @@ impl Glob {
     /// Create a new `Glob`, with the pattern relative to `root`.
     /// `root` should be an absolute path.
     pub fn new_with_root(root: &Path, pattern: String) -> anyhow::Result<Self> {
-        Self::new(pattern)?.from_root(root)
+        Ok(Self::new(pattern)?.from_root(root))
     }
 
     /// Rewrite the current `Glob` relative to `root`.
     /// `root` should be an absolute path.
-    pub fn from_root(self, root: &Path) -> anyhow::Result<Self> {
-        Ok(Self(Self::pattern_relative_to_root(root, &self.0)?))
+    pub fn from_root(self, root: &Path) -> Self {
+        Self(Self::pattern_relative_to_root(root, &self.0))
     }
 
     fn contains_glob_char(part: &OsStr) -> bool {
@@ -72,10 +72,13 @@ impl Glob {
         bytes.contains(&b'*') || bytes.contains(&b'?') || bytes.contains(&b'[')
     }
 
-    fn pattern_relative_to_root(root: &Path, pattern: &Pattern) -> anyhow::Result<Pattern> {
+    fn pattern_relative_to_root(root: &Path, pattern: &Pattern) -> Pattern {
         let from_root = Path::new(pattern.as_str())
             .absolutize_from(Path::new(&Pattern::escape(root.to_string_lossy().as_ref())));
-        Ok(Pattern::new(&from_root.to_string_lossy())?)
+        // the unwrap is okay because the previous `pattern` worked already
+        // and the escaped `root` shouldn't realistically fail
+        Pattern::new(&from_root.to_string_lossy())
+            .with_context(|| "Got invalid Glob pattern relative to root that was assumed to be safe. Please report this to the Pyrefly maintainers on our GitHub.").unwrap()
     }
 
     fn get_glob_root(&self) -> PathBuf {
@@ -295,18 +298,19 @@ impl Globs {
     /// Create a new `Globs`, rewriting all patterns to be relative to `root`.
     /// `root` should be an absolute path.
     pub fn new_with_root(root: &Path, patterns: Vec<String>) -> anyhow::Result<Self> {
-        Self::rewrite_with_root(root, patterns.into_try_map(Glob::new)?)
+        Ok(Self::rewrite_with_root(
+            root,
+            patterns.into_try_map(Glob::new)?,
+        ))
     }
 
-    fn rewrite_with_root(root: &Path, patterns: Vec<Glob>) -> anyhow::Result<Self> {
-        Ok(Self(
-            patterns.into_try_map(|pattern| pattern.from_root(root))?,
-        ))
+    fn rewrite_with_root(root: &Path, patterns: Vec<Glob>) -> Self {
+        Self(patterns.into_map(|pattern| pattern.from_root(root)))
     }
 
     /// Rewrite the existing `Globs` to be relative to `root`.
     /// `root` should be an absolute path.
-    pub fn from_root(self, root: &Path) -> anyhow::Result<Self> {
+    pub fn from_root(self, root: &Path) -> Self {
         // TODO(connernilsen): store root as part of globs to make it easier to rewrite later on
         Self::rewrite_with_root(root, self.0)
     }

{pyrefly-0.25.1 → pyrefly-0.26.0}/crates/pyrefly_util/src/visit.rs

@@ -11,6 +11,7 @@
 use std::any;
 use std::any::Any;
 
+use compact_str::CompactString;
 use const_str;
 use ruff_python_ast::name::Name;
 use ruff_text_size::TextRange;
@@ -139,6 +140,8 @@ visit_nothing!(i64);
 visit_nothing!(i128);
 visit_nothing!(isize);
 visit_nothing!(());
+visit_nothing!(String);
+visit_nothing!(CompactString);
 
 // We can't visit `str` on its own, so this is atomic.
 visit_nothing!(Box<str>);

{pyrefly-0.25.1 → pyrefly-0.26.0}/pyrefly/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyrefly"
-version = "0.25.1"
+version = "0.26.0"
 authors = ["Meta"]
 edition = "2024"
 repository = "https://github.com/facebook/pyrefly"
@@ -28,7 +28,7 @@ indicatif = { version = "0.17.6", features = ["futures", "improved_unicode", "ra
 itertools = "0.14.0"
 lsp-server = "0.7.2"
 lsp-types = "0.94.1"
-num-traits = { version = "0.2.18", default-features = false }
+num-traits = { version = "0.2.19", default-features = false }
 parse-display = "0.8.2"
 paste = "1.0.14"
 pyrefly_bundled = { path = "../crates/pyrefly_bundled" }

{pyrefly-0.25.1 → pyrefly-0.26.0}/pyrefly/lib/alt/answers_solver.rs

@@ -616,7 +616,10 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
         SolutionsTable: TableKeyed<K, Value = SolutionsEntry<K>>,
     {
         if module == self.module().name() && path.is_none_or(|path| path == self.module().path()) {
-            Some(self.get(k))
+            // We are working in our own module, so don't have to go back to the `LookupAnswer` trait.
+            // But even though we are looking at our own module, we might be using our own type via an import
+            // from a mutually recursive module, so have to deal with key_to_idx finding nothing due to incremental.
+            Some(self.get_idx(self.bindings().key_to_idx_hashed_opt(Hashed::new(k))?))
         } else {
             self.answers.get(module, path, k, self.thread_state)
         }

{pyrefly-0.25.1 → pyrefly-0.26.0}/pyrefly/lib/alt/attr.rs

@@ -1469,9 +1469,17 @@ impl<'a, Ans: LookupAnswer> AnswersSolver<'a, Ans> {
             AttributeBase::Never => LookupResult::found_type(Type::never()),
             AttributeBase::Property(mut getter) => {
                 if attr_name == "setter" {
-                    // Get the property's `setter` method, which, when called with a function, returns
-                    // a copy of the property with the passed-in function as its setter. We hack this
-                    // by updating the getter's metadata to mark it as a setter method.
+                    // When given a decorator `@some_property.setter`, instead of modeling the setter
+                    // directly at the type level we just return the getter (the raw `some_property`)
+                    // but with the function metadata marked to indicate this is a setter invocation.
+                    //
+                    // This doesn't accurately model the runtime semantics (the setter function is
+                    // not at all the same type), but makes it easy for us to use function metadata
+                    // to track both the getter and setter in a way that class field can use.
+                    //
+                    // See also the function decorator and class field code to
+                    // understand how all this works end-to-end.
+                    //
                     // TODO(stroxler): it is probably possible to synthesize a forall type here
                     // that uses a type var to propagate the setter. Investigate this option later.
                     getter.transform_toplevel_func_metadata(|meta: &mut FuncMetadata| {