fix: update some docs (#1215)

docs/rules/guard_for_in.md

@@ -7,23 +7,23 @@ items in your for loop.
 ### Invalid:
 
 ```typescript
-for (key in obj) {
+for (const key in obj) {
   foo(obj, key);
 }
 ```
 
 ### Valid:
 
 ```typescript
-for (key in obj) {
+for (const key in obj) {
   if (Object.hasOwn(obj, key)) {
     foo(obj, key);
   }
 }
 ```
 
 ```typescript
-for (key in obj) {
+for (const key in obj) {
   if (!Object.hasOwn(obj, key)) {
     continue;
   }

docs/rules/no_console.md

@@ -1,5 +1,3 @@
-# no_console
-
 Disallows the use of the `console` global.
 
 Oftentimes, developers accidentally commit `console.log`/`console.error`

docs/rules/no_deprecated_deno_api.md

@@ -34,7 +34,7 @@ deprecated ones with alternatives from `std`. For more detail, see
 expression. See [deno#9294](https://github.com/denoland/deno/issues/9294) for
 more details.
 
-**File system API"
+**File system API**
 
 - `Deno.File`
 

docs/rules/no_import_assertions.md

@@ -1,6 +1,6 @@
 Disallows the `assert` keyword for import attributes
 
-ES import attributes (previously called import assetions) has been changed to
+ES import attributes (previously called import assertions) has been changed to
 use the `with` keyword. The old syntax using `assert` is still supported, but
 deprecated.
 

docs/rules/no_non_null_asserted_optional_chain.md

@@ -0,0 +1,19 @@
+Disallow non-null assertions after an optional chain expression
+
+`?.` optional chain expressions provide undefined if an object is `null` or
+`undefined`. Using a `!` non-null assertion to assert the result of an `?.`
+optional chain expression is non-nullable is likely wrong.
+
+### Invalid:
+
+```typescript
+foo?.bar!;
+foo?.bar()!;
+```
+
+### Valid:
+
+```typescript
+foo?.bar;
+foo?.bar();
+```

docs/rules/no_non_null_assertion.md

@@ -0,0 +1,29 @@
+Disallow non-null assertions using the `!` postfix operator
+
+TypeScript's `!` non-null assertion operator asserts to the type system that an
+expression is non-nullable, as in not `null` or `undefined`. Using assertions to
+tell the type system new information is often a sign that code is not fully
+type-safe. It's generally better to structure program logic so that TypeScript
+understands when values may be nullable.
+
+### Invalid:
+
+```typescript
+interface Example {
+  property?: string;
+}
+declare const example: Example;
+
+const includes = example.property!.includes("foo");
+```
+
+### Valid:
+
+```typescript
+interface Example {
+  property?: string;
+}
+declare const example: Example;
+
+const includes = example.property?.includes("foo") ?? false;
+```

docs/rules/no_throw_literal.md

@@ -0,0 +1,21 @@
+Disallow throwing literals as exceptions
+
+It is considered good practice to only `throw` the `Error` object itself or an
+object using the `Error` object as base objects for user-defined exceptions. The
+fundamental benefit of `Error` objects is that they automatically keep track of
+where they were built and originated.
+
+### Invalid:
+
+```typescript
+throw "error";
+throw 0;
+throw undefined;
+throw null;
+```
+
+### Valid:
+
+```typescript
+throw new Error("error");
+```

docs/rules/no_undef.md

@@ -0,0 +1,8 @@
+Disallow the use of undeclared variables
+
+### Invalid:
+
+```typescript
+const foo = someFunction();
+const bar = a + 1;
+```

docs/rules/single_var_declarator.md

@@ -0,0 +1,14 @@
+Disallows multiple variable definitions in the same declaration statement
+
+### Invalid:
+
+```typescript
+const foo = 1, bar = "2";
+```
+
+### Valid:
+
+```typescript
+const foo = 1;
+const bar = "2";
+```

docs/rules/triple_slash_reference.md

@@ -0,0 +1,21 @@
+Disallow certain triple slash directives in favor of ES6-style import
+declarations
+
+TypeScript's `///` triple-slash references are a way to indicate that types from
+another module are available in a file. Use of triple-slash reference type
+directives is generally discouraged in favor of ECMAScript Module imports. This
+rule reports on the use of `/// <reference path="..." />`,
+`/// <reference types="..." />`, or `/// <reference lib="..." />` directives.
+
+### Invalid:
+
+```typescript
+/// <reference types="foo" />
+import * as foo from "foo";
+```
+
+### Valid:
+
+```typescript
+import * as foo from "foo";
+```

src/rules/guard_for_in.rs

@@ -110,36 +110,36 @@ mod tests {
   fn guard_for_in_valid() {
     assert_lint_ok! {
       GuardForIn,
-      r#"for (key in obj);"#,
+      r#"for (const key in obj);"#,
       r#"
-for (key in obj)
+for (const key in obj)
   if (Object.hasOwn(obj, key)) {}
 "#,
       r#"
-for (key in obj) {
+for (const key in obj) {
   if (Object.hasOwn(obj, key)) {}
 }
 "#,
       r#"
-for (key in obj) {
+for (const key in obj) {
   if (!Object.hasOwn(obj, key)) continue;
 }
 "#,
       r#"
-for (key in obj) {
+for (const key in obj) {
   if (!Object.hasOwn(obj, key)) continue;
   foo(obj, key);
 }
 "#,
       r#"
-for (key in obj) {
+for (const key in obj) {
   if (!Object.hasOwn(obj, key)) {
     continue;
   }
 }
 "#,
       r#"
-for (key in obj) {
+for (const key in obj) {
   if (!Object.hasOwn(obj, key)) {
     continue;
   }
@@ -156,22 +156,22 @@ for (key in obj) {
       MESSAGE,
       HINT,
       r#"
-for (key in obj)
+for (const key in obj)
   foo(obj, key);
 "#: [{ line: 2, col: 0 }],
       r#"
-for (key in obj) {
+for (const key in obj) {
   foo(obj, key);
 }
 "#: [{ line: 2, col: 0 }],
       r#"
-for (key in obj) {
+for (const key in obj) {
   foo(obj, key);
   bar(obj, key);
 }
 "#: [{ line: 2, col: 0 }],
       r#"
-for (key in obj) {
+for (const key in obj) {
   if (!Object.hasOwn(obj, key)) {
     foo(obj, key);
     continue;

www/static/docs.json

@@ -108,7 +108,7 @@
   },
   {
     "code": "guard-for-in",
-    "docs": "Require `for-in` loops to include an `if` statement\n\nLooping over objects with a `for-in` loop will include properties that are\ninherited through the prototype chain. This behavior can lead to unexpected\nitems in your for loop.\n\n### Invalid:\n\n```typescript\nfor (key in obj) {\n  foo(obj, key);\n}\n```\n\n### Valid:\n\n```typescript\nfor (key in obj) {\n  if (Object.hasOwn(obj, key)) {\n    foo(obj, key);\n  }\n}\n```\n\n```typescript\nfor (key in obj) {\n  if (!Object.hasOwn(obj, key)) {\n    continue;\n  }\n  foo(obj, key);\n}\n```\n",
+    "docs": "Require `for-in` loops to include an `if` statement\n\nLooping over objects with a `for-in` loop will include properties that are\ninherited through the prototype chain. This behavior can lead to unexpected\nitems in your for loop.\n\n### Invalid:\n\n```typescript\nfor (const key in obj) {\n  foo(obj, key);\n}\n```\n\n### Valid:\n\n```typescript\nfor (const key in obj) {\n  if (Object.hasOwn(obj, key)) {\n    foo(obj, key);\n  }\n}\n```\n\n```typescript\nfor (const key in obj) {\n  if (!Object.hasOwn(obj, key)) {\n    continue;\n  }\n  foo(obj, key);\n}\n```\n",
     "tags": []
   },
   {
@@ -167,7 +167,7 @@
   },
   {
     "code": "no-console",
-    "docs": "# no_console\n\nDisallows the use of the `console` global.\n\nOftentimes, developers accidentally commit `console.log`/`console.error`\nstatements, left in particularly after debugging. Moreover, using these in code\nmay leak sensitive information to the output or clutter the console with\nunnecessary information. This rule helps maintain clean and secure code by\ndisallowing the use of `console`.\n\nThis rule is especially useful in libraries where you almost never want to\noutput to the console.\n\n### Invalid\n\n```typescript\nconsole.log(\"Debug message\");\nconsole.error(\"Debug message\");\nconsole.debug(obj);\n\nif (debug) console.log(\"Debugging\");\n\nfunction log() {\n  console.log(\"Log\");\n}\n```\n\n### Valid\n\nIt is recommended to explicitly enable the console via a `deno-lint-ignore`\ncomment for any calls where you actually want to use it.\n\n```typescript\nfunction logWarning(message: string) {\n  // deno-lint-ignore no-console\n  console.warn(message);\n}\n```\n",
+    "docs": "Disallows the use of the `console` global.\n\nOftentimes, developers accidentally commit `console.log`/`console.error`\nstatements, left in particularly after debugging. Moreover, using these in code\nmay leak sensitive information to the output or clutter the console with\nunnecessary information. This rule helps maintain clean and secure code by\ndisallowing the use of `console`.\n\nThis rule is especially useful in libraries where you almost never want to\noutput to the console.\n\n### Invalid\n\n```typescript\nconsole.log(\"Debug message\");\nconsole.error(\"Debug message\");\nconsole.debug(obj);\n\nif (debug) console.log(\"Debugging\");\n\nfunction log() {\n  console.log(\"Log\");\n}\n```\n\n### Valid\n\nIt is recommended to explicitly enable the console via a `deno-lint-ignore`\ncomment for any calls where you actually want to use it.\n\n```typescript\nfunction logWarning(message: string) {\n  // deno-lint-ignore no-console\n  console.warn(message);\n}\n```\n",
     "tags": []
   },
   {
@@ -205,7 +205,7 @@
   },
   {
     "code": "no-deprecated-deno-api",
-    "docs": "Warns the usage of the deprecated Deno APIs\n\nThe following APIs in `Deno` namespace are now marked as deprecated and will get\nremoved from the namespace in the future.\n\n**IO APIs**\n\n- `Deno.Buffer`\n- `Deno.copy`\n- `Deno.iter`\n- `Deno.iterSync`\n- `Deno.readAll`\n- `Deno.readAllSync`\n- `Deno.writeAll`\n- `Deno.writeAllSync`\n\nThe IO APIs are already available in `std/io` or `std/streams`, so replace these\ndeprecated ones with alternatives from `std`. For more detail, see\n[the tracking issue](https://github.com/denoland/deno/issues/9795).\n\n**Sub Process API**\n\n- `Deno.run`\n\n`Deno.run` was deprecated in favor of `Deno.Command`. See\n[deno#9435](https://github.com/denoland/deno/discussions/9435) for more details.\n\n**Custom Inspector API**\n\n- `Deno.customInspect`\n\n`Deno.customInspect` was deprecated in favor of\n`Symbol.for(\"Deno.customInspect\")`. Replace the usages with this symbol\nexpression. See [deno#9294](https://github.com/denoland/deno/issues/9294) for\nmore details.\n\n**File system API\"\n\n- `Deno.File`\n\n`Deno.File` was deprecated in favor of `Deno.FsFile`. Replace the usages with\nnew class name.\n\n### Invalid:\n\n```typescript\n// buffer\nconst a = Deno.Buffer();\n\n// read\nconst b = await Deno.readAll(reader);\nconst c = Deno.readAllSync(reader);\n\n// write\nawait Deno.writeAll(writer, data);\nDeno.writeAllSync(writer, data);\n\n// iter\nfor await (const x of Deno.iter(xs)) {}\nfor (const y of Deno.iterSync(ys)) {}\n\n// copy\nawait Deno.copy(reader, writer);\n\n// custom inspector\nclass A {\n  [Deno.customInspect]() {\n    return \"This is A\";\n  }\n}\n\nfunction foo(file: Deno.File) {\n  // ...\n}\n```\n\n### Valid:\n\n```typescript\n// buffer\nimport { Buffer } from \"https://deno.land/std/io/buffer.ts\";\nconst a = new Buffer();\n\n// read\nimport { readAll, readAllSync } from \"https://deno.land/std/io/util.ts\";\nconst b = await readAll(reader);\nconst c = readAllSync(reader);\n\n// write\nimport { writeAll, writeAllSync } from \"https://deno.land/std/io/util.ts\";\nawait writeAll(writer, data);\nwriteAllSync(writer, data);\n\n// iter\nimport { iter, iterSync } from \"https://deno.land/std/io/util.ts\";\nfor await (const x of iter(xs)) {}\nfor (const y of iterSync(ys)) {}\n\n// copy\nimport { copy } from \"https://deno.land/std/io/util.ts\";\nawait copy(reader, writer);\n\n// custom inspector\nclass A {\n  [Symbol.for(\"Deno.customInspect\")]() {\n    return \"This is A\";\n  }\n}\n\nfunction foo(file: Deno.FsFile) {\n  // ...\n}\n```\n",
+    "docs": "Warns the usage of the deprecated Deno APIs\n\nThe following APIs in `Deno` namespace are now marked as deprecated and will get\nremoved from the namespace in the future.\n\n**IO APIs**\n\n- `Deno.Buffer`\n- `Deno.copy`\n- `Deno.iter`\n- `Deno.iterSync`\n- `Deno.readAll`\n- `Deno.readAllSync`\n- `Deno.writeAll`\n- `Deno.writeAllSync`\n\nThe IO APIs are already available in `std/io` or `std/streams`, so replace these\ndeprecated ones with alternatives from `std`. For more detail, see\n[the tracking issue](https://github.com/denoland/deno/issues/9795).\n\n**Sub Process API**\n\n- `Deno.run`\n\n`Deno.run` was deprecated in favor of `Deno.Command`. See\n[deno#9435](https://github.com/denoland/deno/discussions/9435) for more details.\n\n**Custom Inspector API**\n\n- `Deno.customInspect`\n\n`Deno.customInspect` was deprecated in favor of\n`Symbol.for(\"Deno.customInspect\")`. Replace the usages with this symbol\nexpression. See [deno#9294](https://github.com/denoland/deno/issues/9294) for\nmore details.\n\n**File system API**\n\n- `Deno.File`\n\n`Deno.File` was deprecated in favor of `Deno.FsFile`. Replace the usages with\nnew class name.\n\n### Invalid:\n\n```typescript\n// buffer\nconst a = Deno.Buffer();\n\n// read\nconst b = await Deno.readAll(reader);\nconst c = Deno.readAllSync(reader);\n\n// write\nawait Deno.writeAll(writer, data);\nDeno.writeAllSync(writer, data);\n\n// iter\nfor await (const x of Deno.iter(xs)) {}\nfor (const y of Deno.iterSync(ys)) {}\n\n// copy\nawait Deno.copy(reader, writer);\n\n// custom inspector\nclass A {\n  [Deno.customInspect]() {\n    return \"This is A\";\n  }\n}\n\nfunction foo(file: Deno.File) {\n  // ...\n}\n```\n\n### Valid:\n\n```typescript\n// buffer\nimport { Buffer } from \"https://deno.land/std/io/buffer.ts\";\nconst a = new Buffer();\n\n// read\nimport { readAll, readAllSync } from \"https://deno.land/std/io/util.ts\";\nconst b = await readAll(reader);\nconst c = readAllSync(reader);\n\n// write\nimport { writeAll, writeAllSync } from \"https://deno.land/std/io/util.ts\";\nawait writeAll(writer, data);\nwriteAllSync(writer, data);\n\n// iter\nimport { iter, iterSync } from \"https://deno.land/std/io/util.ts\";\nfor await (const x of iter(xs)) {}\nfor (const y of iterSync(ys)) {}\n\n// copy\nimport { copy } from \"https://deno.land/std/io/util.ts\";\nawait copy(reader, writer);\n\n// custom inspector\nclass A {\n  [Symbol.for(\"Deno.customInspect\")]() {\n    return \"This is A\";\n  }\n}\n\nfunction foo(file: Deno.FsFile) {\n  // ...\n}\n```\n",
     "tags": [
       "recommended"
     ]
@@ -346,7 +346,7 @@
   },
   {
     "code": "no-import-assertions",
-    "docs": "Disallows the `assert` keyword for import attributes\n\nES import attributes (previously called import assetions) has been changed to\nuse the `with` keyword. The old syntax using `assert` is still supported, but\ndeprecated.\n\n### Invalid:\n\n```typescript\nimport obj from \"./obj.json\" assert { type: \"json\" };\nimport(\"./obj2.json\", { assert: { type: \"json\" } });\n```\n\n### Valid:\n\n```typescript\nimport obj from \"./obj.json\" with { type: \"json\" };\nimport(\"./obj2.json\", { with: { type: \"json\" } });\n```\n",
+    "docs": "Disallows the `assert` keyword for import attributes\n\nES import attributes (previously called import assertions) has been changed to\nuse the `with` keyword. The old syntax using `assert` is still supported, but\ndeprecated.\n\n### Invalid:\n\n```typescript\nimport obj from \"./obj.json\" assert { type: \"json\" };\nimport(\"./obj2.json\", { assert: { type: \"json\" } });\n```\n\n### Valid:\n\n```typescript\nimport obj from \"./obj.json\" with { type: \"json\" };\nimport(\"./obj2.json\", { with: { type: \"json\" } });\n```\n",
     "tags": [
       "recommended"
     ]
@@ -416,12 +416,12 @@
   },
   {
     "code": "no-non-null-asserted-optional-chain",
-    "docs": "",
+    "docs": "Disallow non-null assertions after an optional chain expression\n\n`?.` optional chain expressions provide undefined if an object is `null` or\n`undefined`. Using a `!` non-null assertion to assert the result of an `?.`\noptional chain expression is non-nullable is likely wrong.\n\n### Invalid:\n\n```typescript\nfoo?.bar!;\nfoo?.bar()!;\n```\n\n### Valid:\n\n```typescript\nfoo?.bar;\nfoo?.bar();\n```\n",
     "tags": []
   },
   {
     "code": "no-non-null-assertion",
-    "docs": "",
+    "docs": "Disallow non-null assertions using the `!` postfix operator\n\nTypeScript's `!` non-null assertion operator asserts to the type system that an\nexpression is non-nullable, as in not `null` or `undefined`. Using assertions to\ntell the type system new information is often a sign that code is not fully\ntype-safe. It's generally better to structure program logic so that TypeScript\nunderstands when values may be nullable.\n\n### Invalid:\n\n```typescript\ninterface Example {\n  property?: string;\n}\ndeclare const example: Example;\n\nconst includes = example.property!.includes(\"foo\");\n```\n\n### Valid:\n\n```typescript\ninterface Example {\n  property?: string;\n}\ndeclare const example: Example;\n\nconst includes = example.property?.includes(\"foo\") ?? false;\n```\n",
     "tags": []
   },
   {
@@ -506,7 +506,7 @@
   },
   {
     "code": "no-throw-literal",
-    "docs": "",
+    "docs": "Disallow throwing literals as exceptions\n\nIt is considered good practice to only `throw` the `Error` object itself or an\nobject using the `Error` object as base objects for user-defined exceptions. The\nfundamental benefit of `Error` objects is that they automatically keep track of\nwhere they were built and originated.\n\n### Invalid:\n\n```typescript\nthrow \"error\";\nthrow 0;\nthrow undefined;\nthrow null;\n```\n\n### Valid:\n\n```typescript\nthrow new Error(\"error\");\n```\n",
     "tags": []
   },
   {
@@ -516,7 +516,7 @@
   },
   {
     "code": "no-undef",
-    "docs": "",
+    "docs": "Disallow the use of undeclared variables\n\n### Invalid:\n\n```typescript\nconst foo = someFunction();\nconst bar = a + 1;\n```\n",
     "tags": []
   },
   {
@@ -622,12 +622,12 @@
   },
   {
     "code": "single-var-declarator",
-    "docs": "",
+    "docs": "Disallows multiple variable definitions in the same declaration statement\n\n### Invalid:\n\n```typescript\nconst foo = 1, bar = \"2\";\n```\n\n### Valid:\n\n```typescript\nconst foo = 1;\nconst bar = \"2\";\n```\n",
     "tags": []
   },
   {
     "code": "triple-slash-reference",
-    "docs": "",
+    "docs": "Disallow certain triple slash directives in favor of ES6-style import\ndeclarations\n\nTypeScript's `///` triple-slash references are a way to indicate that types from\nanother module are available in a file. Use of triple-slash reference type\ndirectives is generally discouraged in favor of ECMAScript Module imports. This\nrule reports on the use of `/// <reference path=\"...\" />`,\n`/// <reference types=\"...\" />`, or `/// <reference lib=\"...\" />` directives.\n\n### Invalid:\n\n```typescript\n/// <reference types=\"foo\" />\nimport * as foo from \"foo\";\n```\n\n### Valid:\n\n```typescript\nimport * as foo from \"foo\";\n```\n",
     "tags": []
   },
   {