@ls-stack/fast-lint 0.5.0 → 0.7.0

package/README.md

@@ -467,6 +467,19 @@ Comments starting with `INFO:`, `TODO:`, `DOCS:`, `FIX:`, `FIXME:`, `HACK:`, `NO
 `ISSUE:`, `TEMP:`, `TEMPORARY:`, `XXX:`, `REVIEW:`, `eslint`, `cspell:` or `spell-checker:` are allowed. The rule is
 heuristic: it can miss commented code.
 
+Explanation comments required by other rules (`require-type-guard-explanation`'s `type-guard-safety:` by default) are
+prose, so a line comment starting with one of `explanationPrefixes`, plus the `//` lines right below it, is never
+reported.
+
+```ts
+type Options = [
+  {
+    /** Prefixes of explanation comment blocks to skip (default: `['type-guard-safety:']`; replaces the default) */
+    explanationPrefixes?: string[]
+  },
+]
+```
+
 ### `react-single-export`
 
 In React component files (by default `*.tsx`), a file that exports a component (a PascalCase function, arrow,
@@ -810,9 +823,13 @@ safe and why TS inference or an alternative can't be used.
 - the comment goes right before the function or before the statement, `export`, class member or object property
   holding it; consecutive `//` lines form one block, and block/JSDoc comments count too
 - an explicit predicate TypeScript (5.5+) would infer identically is reported even with a comment, with a suggestion
-  to remove the annotation (`inferablePredicate`); only null/undefined and `typeof` checks it is sure about are
-  reported
+  to remove the annotation (`inferablePredicate`); it is conservative and only reports `===`/`!==` checks against
+  `null`, `undefined` and string/number literals, `typeof` checks and `instanceof` (non-generic classes), combined with
+  `||`/`&&`, that it is sure TypeScript infers identically
 - body-less signatures (overloads, `declare function`, interface members, function types) and `asserts x` are ignored
+- `alternativeMsgs` appends a project-specific hint to the `missingExplanation` message, e.g. pointing to a schema
+  validator or a `filterAndMap` helper; the most specific one wins: `inArrayFind`/`inArrayFilter` for guards passed
+  directly to `.find()`/`.filter()`, then `unknownInput` for guards narrowing an `unknown` parameter, then `default`
 
 ```ts
 // Error: missingExplanation
@@ -840,6 +857,17 @@ type Options = [
     commentPrefix?: string
     /** Minimum characters of explanation after the prefix (default: 20) */
     minLength?: number
+    /** Extra hints appended to the `missingExplanation` message, the most specific one wins */
+    alternativeMsgs?: {
+      /** Every guard */
+      default?: string
+      /** Guards narrowing an `unknown` parameter (falls back to `default`) */
+      unknownInput?: string
+      /** Guards passed directly to `.find()` */
+      inArrayFind?: string
+      /** Guards passed directly to `.filter()` */
+      inArrayFilter?: string
+    }
   },
 ]
 ```

package/lib/index.d.ts

@@ -217,9 +217,19 @@ export type NoRestrictedCommentsOptions = {
   }[]
 }
 
+export type NoCommentedOutCodeOptions = {
+  explanationPrefixes?: string[]
+}
+
 export type RequireTypeGuardExplanationOptions = {
   commentPrefix?: string
   minLength?: number
+  alternativeMsgs?: {
+    default?: string
+    unknownInput?: string
+    inArrayFind?: string
+    inArrayFilter?: string
+  }
 }
 
 export type RequireUsageExplanationOptions = {
@@ -257,7 +267,7 @@ type RuleOptions = {
   'no-unnecessary-iife': Record<string, never>
   'require-description': RequireDescriptionOptions
   'no-write-only-ref': Record<string, never>
-  'no-commented-out-code': Record<string, never>
+  'no-commented-out-code': NoCommentedOutCodeOptions
   'react-single-export': ReactSingleExportOptions
   'no-unused-optional-args': NoUnusedOptionalArgsOptions
   'no-unused-type-props-in-args': NoUnusedTypePropsInArgsOptions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ls-stack/fast-lint",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "license": "MIT",
   "description": "Fast type-aware lint rules for TypeScript and React, running natively on tsrs, the Rust port of the TypeScript checker",
   "type": "module",