JSDoc tag for getting around "Object literals are open-ended"

还没有人认领这个 Issue。

### 🔍 Search Terms

label:"Domain: JSDoc" open-ended
label:"Domain: JSDoc" literal
label:checkJs open-ended
label:checkJs literal

### ✅ Viability Checklist

- [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
- [x] This wouldn't change the runtime behavior of existing JavaScript code
- [x] This could be implemented without emitting different JS based on the types of the expressions
- [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- [x] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [x] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

### ⭐ Suggestion

According to [the documentation](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#object-literals-are-open-ended), TypeScript treats inferred object literals in checked `.js` files as open-ended by default. This is good and makes sense, but is annoying for the times when it isn't the desired functionality.

I'd like for a new tag to be introduced. I'll be using `@closed` as an example, but I'm fine with whatever wording, really. The new tag would be used on an object definition in order to opt out of this open-ended behavior for that specific object literal declaration.

Ideally, this would be done recursively through the object's definition (i.e. I shouldn't have to define `@closed` for each sub-object), but I understand if that's too broad-reaching. I'd be fine with having that limitation.

This is obviously very similar to [Exact Types (#12936)](https://github.com/microsoft/TypeScript/issues/12936), but it concerns general exact object types and structural compatibility, whereas this request is limited to a JSDoc opt-in for inferred object literals in checked JavaScript. I therefore believe this warrants its own feature request.

### 📃 Motivating Example

I use JSDoc quite extensively in my hobby work. I often run into issues like this:
```js
class CustomFooBarElement extends HTMLElement {
_elements = {
/** @type {HTMLSpanElement|null} */
foo: null,
};

constructor() {
super();
this._elements.bar = document.createElement("span");
// ^ currently doesn't report an error
}
}
```

Now, you can easily work around this by adding a full object typing to the `_elements` object:
```js
class CustomFooBarElement extends HTMLElement {
/** @type {{foo: HTMLSpanElement|null}} */
_elements = {
foo: null,
};
```
which would cause the `.bar` access to fail. However, maintaining such a declaration can quickly grow cumbersome when the `_elements` object grows in size and complexity:
```js
class CustomFooBarElement extends HTMLElement {
/**
* @type {{
* foo: HTMLSpanElement | null,
* buttons: {
* primary: {
* a: HTMLButtonElement | null,
* b: HTMLButtonElement | null,
* },
* },
* images: {
* a: HTMLImageElement | null,
* b: HTMLImageElement | null,
* },
* }}
*/
_elements = {
foo: null,
buttons: {
primary: {
a: null,
b: null,
},
},
images: {
a: null,
b: null,
},
};
```
A silly example, but I think you get the point. Not to mention the fact that you've completely decoupled the type definition from the definition of the variable itself.

Now, if I instead could do something like this:
```js
class CustomFooBarElement extends HTMLElement {
/** @closed */
_elements = {
/** @type {HTMLSpanElement|null} */
foo: null,
buttons: {
primary: {
/** @type {HTMLButtonElement|null} */
a: null,
/** @type {HTMLButtonElement|null} */
b: null,
},
},
images: {
/** @type {HTMLImageElement|null} */
a: null,
/** @type {HTMLImageElement|null} */
b: null,
},
};
```
It's much easier to handle, and would lead to the desired result:
```js
this._elements.bar = document.createElement("span");
// ^^^ error: Property 'bar' does not exist

this._elements.buttons.primary.c = document.createElement("button");
// ^ error: Property 'c' does not exist
```

### 💻 Use Cases

1. What do you want to use this for?

Typing fixed-shape objects. See the examples above.

2. What shortcomings exist with current approaches?

The object-declaration-level `@type` requires essentially repeating the entire structure of the object. It also decouples the type of the actual leaf property from its definition.

3. What workarounds are you using in the meantime?

I started with the object-declaration-level `@type`, but at this point I just use the leaf-level `@type` and hope I don't run into any spelling mistakes or such.

先阅读 handbook 中的“Object literals are open-ended”章节和链接的 Exact Types issue (#12936)，然后调查示例中描述的 checked-JavaScript JSDoc 行为。完成标准是提供一个有文档说明的 JSDoc opt-in，用于固定形状的推断对象字面量，包括针对嵌套对象约定的范围，并拒绝示例中的额外属性赋值。

由索引模型根据 Issue 内容生成。