Feature Request: Typestate / Self-Type Refinement for Method Calls

Chưa có ai nhận issue này.

## Problem

Lua is a highly dynamic language, and many real-world Lua frameworks mutate object capabilities at runtime.

This pattern is especially common in:

* game engines
* UI frameworks
* ECS architectures
* builder APIs
* runtime mixin systems
* userdata bindings from native engines

Currently, LuaLS/LuaCats cannot properly express:

> "after calling this method, `self` now has additional capabilities/methods"

This becomes a major DX limitation for frameworks that dynamically extend objects.

---

## Real-world Example

Consider a UI framework where all elements start as a generic `UIElement`.

```lua
---@class UIElement
local UIElement = {}
```

Calling:

```lua
element:setupUIImage()
```

injects image-related functionality into the element at runtime:

```lua
element:setImage(...)
```

However, LuaLS still sees `element` as only `UIElement`.

The only current workaround is manual casting:

```lua
element:setupUIImage()

---@cast element UIImage
element:setImage(material)
```

This works technically, but becomes repetitive and hurts DX significantly in large codebases.

---

## Comparison to TypeScript

TypeScript supports type refinement after method calls through assertion signatures such as:

```ts
asserts this is SomeType
```

This allows APIs to safely refine object types after capability-changing methods.

A good real-world example is `discord.js`, where `Interaction` objects can be refined into subtypes through methods like:

```ts
interaction.isButton()
interaction.isChatInputCommand()
```

After refinement, TypeScript understands the new subtype automatically.

Lua frameworks often use similar runtime patterns, but LuaLS currently cannot model them.

---

## Proposed Solution

Introduce a LuaCats annotation for self-type refinement / capability injection.

Possible syntax examples:

```lua
---@injects UIImage
function UIElement:setupUIImage() end
```

or:

```lua
---@mutates self UIImage
function UIElement:setupUIImage() end
```

or:

```lua
---@becomes UIImage
function UIElement:setupUIImage() end
```

---

## Expected Behavior

After:

```lua
element:setupUIImage()
```

LuaLS would understand:

```lua
element :: UIElement & UIImage
```

allowing:

```lua
element:setImage(...)
```

without requiring manual casts.

---

## Why This Matters

This would greatly improve support for:

* dynamic Lua architectures
* runtime capability injection
* engine bindings
* UI frameworks
* builder APIs
* fluent APIs
* mixin systems

while keeping Lua's dynamic nature intact.

This feature would also reduce:

* repetitive `---@cast`
* noisy annotations
* inaccurate supersets in base classes
* degraded autocomplete quality

---

## Additional Notes

This feature does not need to become full typestate analysis or advanced dependent typing.

Even a pragmatic flow-sensitive refinement system limited to:

* direct method calls
* current scope
* explicit annotations only

would already provide massive DX improvements.

---

## Example Use Case

```lua
---@class UIImage
---@field setImage fun(self: UIImage, material: string)

---@class UIElement

---@injects UIImage
function UIElement:setupUIImage() end

local element = UIElement.new()

element:setupUIImage()

element:setImage("icon")
```

Expected:

* autocomplete works
* diagnostics recognize `setImage`
* no manual cast required

---

Thanks for all the amazing work on LuaLS and LuaCats.
This would significantly improve tooling support for dynamic Lua patterns commonly used in real-world frameworks and game engines.

Issue không nêu tên các tệp triển khai hoặc các bài kiểm thử. Hãy bắt đầu bằng cách xem xét cách LuaLS hiện đang xử lý `---@cast` tường minh và các lời gọi phương thức, sau đó đánh giá phạm vi tinh chỉnh được đề xuất: các lời gọi trực tiếp, phạm vi hiện tại và các chú thích tường minh. Được coi là hoàn tất khi đã thống nhất một thiết kế chú thích, với khả năng tinh chỉnh capability theo luồng, tính năng tự động hoàn thành và chẩn đoán hoạt động mà không cần cast thủ công.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.