Jia Chen

This commit **updates the project documentation** by adding new guidelines to `AGENTS.md`. It introduces specific instructions for AI agents on how to write more effective and useful commit summaries, moving beyond simple change listings. The primary goal is to improve the **quality of AI-generated commit messages** by guiding them to provide higher-level context, such as the problem solved, the chosen solution, and its rationale. This **documentation update** aims to make future commit summaries more informative and valuable for readers.

This commit introduces a **performance optimization** to the **LSP server** by **suppressing redundant workspace diagnostic publishes**. It addresses an issue where the server would inefficiently republish diagnostics for non-open files after every recheck, leading to **UI lag** and excessive network traffic. The server, primarily within `pyrefly/lib/lsp/non_wasm/server.rs`, now tracks and deduplicates unversioned workspace diagnostics using fingerprints, only sending updates when the payload meaningfully changes or needs to clear previous diagnostics. This change significantly **reduces unnecessary notifications and log spam** without altering the visible diagnostic model or interfering with versioned open-file diagnostics and document open/close transitions, as verified by new and updated **tests**.

This commit **refactors** the **type inference system** by **unifying ParamSpec forwarding validation** into a single, dedicated method, `paramspec_forwarding`, within `pyrefly/lib/alt/callable.rs`. This new method centralizes checks for extra arguments both before and after `*P.args` or `**P.kwargs`, replacing previous inline and helper functions. It also improves the API by returning stripped argument slices, allowing callers in `callable_infer` and `callable_infer_params` to directly use the remaining arguments for subsequent matching. This change enhances the robustness and consistency of **ParamSpec handling**, ensuring correct validation across all dispatch paths, and is accompanied by **new test cases** to verify its correctness.

This commit delivers a **bug fix** to the **type resolution logic** within the `pyrefly` library, specifically addressing an issue with **`ParamSpec` forwarding** between generic helpers. Previously, the `var_to_rparams` closure in `pyrefly/lib/alt/callable.rs` would incorrectly raise an error when a `ParamSpec` variable was `Type::Quantified`, failing to properly bind forwarded arguments. The fix updates this closure to correctly recognize and permissively handle these quantified `ParamSpec` types, treating them as non-contributing to concrete parameters. This ensures **correct type checking** for complex generic helper patterns and is validated by new test cases added to `pyrefly/lib/test/paramspec.rs`.

This commit introduces **strict validation** for `ParamSpec` forwarding patterns within the **PyreFly type inference engine**, specifically addressing the deferred resolution of `ParamSpec Var` instances during `callable_infer_params`. It ensures that arguments passed to a `ParamSpec` strictly follow the `*P.args` and `**P.kwargs` forwarding syntax, preventing incorrect argument usage from being permissively accepted. This **bug fix** (for issue #823) enhances the **type soundness** and consistency of `ParamSpec` handling, mirroring existing validation logic. The new `check_paramspec_forwarding` helper function in `pyrefly/lib/alt/callable.rs` centralizes this validation, and new test cases have been added to verify its correctness.

This commit **fixes a bug** in the **type checker** by **removing an incorrect validation check** for **abstract `async def` methods** that declare an **`AsyncIterator`** as their return type. Previously, these valid Python patterns, which represent coroutines returning an `AsyncIterator` when awaited, were erroneously flagged with `bad-function-definition` errors. This change prevents **false positive errors** in the `pyrefly/lib/alt/function.rs` module and correctly allows the type checker to identify **`bad-override` errors** when these coroutine-returning abstract methods are improperly overridden by incompatible async generators.

This commit introduces a **bug fix and enhancement** to Pyrefly's **type checking for generic metaclasses**, specifically addressing scenarios where metaclasses are parameterized with unbound type variables. Previously, the system failed to detect PEP 695 type parameters (`Quantified`) in generic metaclass arguments, leading to silent propagation of bare type variables and subsequent confusing "object has no attribute" errors during attribute lookups. The fix, primarily in `pyrefly/lib/alt/class/class_metadata.rs`, extends the detection mechanism to cover all type variable forms, consistently emitting an error, and then **gracefully resolves these unbound type variables** within the metaclass's type arguments by replacing them with their gradual types (defaults or `Any`), preserving structural type information. This **improves type inference accuracy and robustness** for complex generic class definitions, preventing cascading errors and ensuring more reliable type safety.

This commit **fixes a bug** in **LSP diagnostics** where warning-level diagnostics would persist indefinitely on files closed in **workspace mode**. Previously, the system failed to re-publish diagnostics for closed files, causing stale warnings to remain visible and violating the invariant that only error-severity diagnostics should appear for non-open files. The fix involves explicitly **re-publishing diagnostics** for a closed file after the `InvalidateOnClose` task completes its transaction, leveraging existing logic to correctly filter out non-error severities. This ensures that **LSP clients** accurately reflect the diagnostic state, showing only error-level issues for closed files in `pyrefly/lib/lsp/non_wasm/server.rs`. The **test suite** in `pyrefly/lib/test/lsp/lsp_interaction/workspace_diagnostics.rs` has been extended to verify this correct open-close diagnostic lifecycle.

This commit **adds opt-in Scuba logging for typing errors** encountered during **`pyrefly check` runs**. This **new capability** involves **refactoring** the **`pyrefly check` command** within `pyrefly/lib/commands/check.rs` to return a `CheckResult` struct, which is then propagated for telemetry. The `run` method in `pyrefly/lib/commands/all.rs` is updated to handle and propagate this result, enabling **enhanced telemetry** for type checking outcomes. Related commands like `pyrefly/lib/commands/init.rs` and `pyrefly/lib/commands/suppress.rs` were adjusted to handle the updated return types from the check command's `run_once` method.

This commit **fixes a bug** in the **LSP server's workspace diagnostics** where closing a file could result in false "memory path not found" errors in the Problems panel. The fix involves adding an `is_memory` check to `ModulePath` and modifying the `publish_workspace_diagnostics` function in `pyrefly/lib/lsp/non_wasm/server.rs` to **filter out stale in-memory handles**. This prevents misleading diagnostic messages for files that are no longer open, as workspace diagnostics for such files should rely on `FileSystem` handles. Ultimately, this improves the accuracy and user experience of **workspace mode** diagnostics by ensuring only valid file states are reported.

This commit **refactors the decorator application logic** within the **`pyrefly/lib/alt/function.rs` module**. It **restructures the `apply_function_decorator` function** by explicitly splitting its internal logic into four distinct phases: preparation, raw decorator call, callable metadata reconstruction, and decoratee generic restoration. This **behavior-preserving refactoring** introduces new helper methods like `prepare_decorator_application`, `decorate_returned_callable`, `restore_decoratee_generics`, and a `PreparedDecoratorApplication` struct. The primary goal is to **improve code clarity and maintainability** by making the data flow more explicit, which will facilitate future development and reviews of the decorator system.

This commit **updates the user-facing documentation** to reflect recent changes in diagnostic severity handling. It adds comprehensive details for the new `min-severity` configuration option and `--min-severity` CLI flag to the `website/docs/configuration.mdx` file. Furthermore, the `website/docs/error-kinds.mdx` page is updated to clarify how `min-severity` affects diagnostic display, specifically noting that **warnings no longer cause a non-zero exit by default** and that sub-error diagnostics are now limited to open files in the IDE. This **documentation update** ensures users have accurate information regarding diagnostic behavior and exit codes.

This commit **fixes** an issue in the **`pyrefly` CLI tool** where the `check --suppress-errors` flag and `suppress` command would only suppress diagnostics with `Severity::Warn` or higher, inadvertently excluding Info-level messages. It **removes a hard-coded severity filter** within `pyrefly/lib/commands/suppress.rs` that previously prevented the suppression of lower-severity, yet user-visible, diagnostics. This **enhancement** ensures that the suppression mechanism now operates on *all* diagnostics presented to the user, providing a consistent "what-you-see-is-what-we-suppress" experience. Users can now effectively suppress any visible diagnostic, regardless of its severity level.

This commit introduces a **new capability** to configure the minimum severity level for reported issues directly within project configuration files like `pyrefly.toml` or `pyproject.toml`. It enhances the **configuration system** by adding a `min_severity` field to the `ConfigFile` struct and updates the **CLI commands** in `pyrefly/lib/commands/check.rs` and `pyrefly/lib/commands/buck_check.rs` to load this value. The `--min-severity` CLI flag retains precedence over the config file, and both default to `Error` if unset, ensuring consistent behavior. Furthermore, **watch mode** now dynamically re-reads the configuration to pick up changes to the `min-severity` setting, improving developer workflow. This **configuration enhancement** allows users to define a project-wide minimum severity threshold, streamlining issue reporting across the codebase.

This commit introduces a **new feature** to the **Language Server Protocol (LSP) implementation** within `pyrefly`, specifically modifying the **diagnostics publishing mechanism**. It now **restricts the publication of diagnostics** with severity below `Error` (such as warnings and info messages) to only files that are currently open in the user's editor. For files not actively open, the LSP server, primarily through `pyrefly/lib/lsp/non_wasm/server.rs`, will only publish `Error`-level diagnostics. This **enhancement** significantly **reduces noise** and improves the developer experience by focusing attention on critical issues in the active workspace, while still providing comprehensive diagnostics for files being edited.

This commit introduces a **new capability** by adding a `--min-severity` CLI flag to the `pyrefly check` and `buck-check` commands. This flag allows users to control the minimum severity level of diagnostics displayed, defaulting to `Error` to hide warnings and info-level messages. To support this, the `Severity` enum in `crates/pyrefly_config/src/error_kind.rs` now derives `ValueEnum` for CLI parsing. This change improves the user experience by reducing diagnostic output noise and aligns `pyrefly`'s behavior with Flow's diagnostic filtering.

This commit introduces a significant **refactoring** of the type checker's error handling pipeline to treat `reveal_type()` output as an explicit **user directive** rather than a standard diagnostic. This **feature enhancement** ensures that `reveal_type` messages are no longer affected by suppression, baselining, or `min-severity` thresholds, guaranteeing they are always displayed by default. The change primarily impacts the **error collection**, **suppression**, and **reporting** subsystems, including command-line tools like `buck_check` and `check`, as well as LSP integration. By separating directives from ordinary errors during processing and merging them only for final display, the system provides a more predictable and intuitive experience for users leveraging `reveal_type` for type introspection. This also simplifies internal logic by focusing baseline and suppression mechanisms solely on actual diagnostics.

This commit performs a **maintenance** task by **removing an unused import** statement that was triggering a **compiler warning** on the trunk branch. This action improves the overall **code quality** and build cleanliness, ensuring that the codebase adheres to best practices and reduces unnecessary build-time noise. The change has a positive impact on the developer experience by eliminating a spurious warning.

This commit performs a **refactoring** and **performance optimization** within the **binding analysis** module. It consolidates the previously separate `outer_capture_value_idx` and `outer_capture_narrow_idx` methods into a single `outer_capture_info` method in `pyrefly/lib/binding/scope.rs`. This change eliminates redundant scope chain traversals when analyzing **captured variables** in closures, as the `seed_captured_variables` function in `pyrefly/lib/binding/bindings.rs` now retrieves both value and narrow information in a single pass. The refactoring maintains the correct semantic behavior, including the module-scope asymmetry for value and narrow propagation, ensuring efficient and accurate **closure analysis**.

This commit **enhances `namedtuple` type inference** within `pyrefly` by preserving explicitly defined fields even when a starred unpacking expression is used in the field list (e.g., `namedtuple("Ext", [*Base._fields, "extra"])`). Previously, all fields were discarded for type checking in such cases, but now `extra` and `comment` would be recognized. The **type solver** now synthesizes `__new__` methods for dynamic `namedtuple`s using `*args, **kwargs`, allowing the constructor to accept additional arguments beyond just the known fields. This **improves static analysis** and **LSP completion**, ensuring that tools correctly recognize and suggest these known fields. This **feature enhancement** aligns `pyrefly`'s `namedtuple` behavior with how `pyright` and `mypy` handle these dynamic field definitions.