@ttsc/lint 0.18.4 → 0.19.0

package/src/structures/rules/ITtscLintTypeScriptRuleOptions.ts

@@ -0,0 +1,248 @@
+/**
+ * Options shapes for the configurable rules in {@link ITtscLintTypeScriptRules}.
+ *
+ * @reference https://typescript-eslint.io/rules/
+ */
+
+/** Identifies a type or value declared in a project file. */
+export interface ITtscLintFileTypeOrValueSpecifier {
+  /** Select project-file declarations. */
+  from: "file";
+  /** Match one or more declared names. */
+  name: string | readonly string[];
+  /** Restrict the match to this project-relative declaration file. */
+  path?: string;
+}
+
+/** Identifies a type or value declared by TypeScript's default libraries. */
+export interface ITtscLintLibTypeOrValueSpecifier {
+  /** Select TypeScript default-library declarations. */
+  from: "lib";
+  /** Match one or more declared names. */
+  name: string | readonly string[];
+}
+
+/** Identifies a type or value declared by an installed package. */
+export interface ITtscLintPackageTypeOrValueSpecifier {
+  /** Select package declarations. */
+  from: "package";
+  /** Match one or more declared names. */
+  name: string | readonly string[];
+  /** Require declarations from this package or ambient module. */
+  package: string;
+}
+
+/** Identifies a type or value by name and, preferably, declaration source. */
+export type TtscLintTypeOrValueSpecifier =
+  | string
+  | ITtscLintFileTypeOrValueSpecifier
+  | ITtscLintLibTypeOrValueSpecifier
+  | ITtscLintPackageTypeOrValueSpecifier;
+
+/** One structured replacement policy in `typescript/no-restricted-types`. */
+export interface ITtscLintTypeScriptNoRestrictedTypesTypeConfig {
+  /** Custom text appended to the standard diagnostic. */
+  message: string;
+  /** Replacement applied automatically by `ttsc fix`. */
+  fixWith?: string;
+  /** Replacement choices exposed as opt-in editor suggestions. */
+  suggest?: readonly string[];
+}
+
+/** Policy value for one normalized type spelling. */
+export type TtscLintTypeScriptNoRestrictedTypesTypeValue =
+  | boolean
+  | string
+  | ITtscLintTypeScriptNoRestrictedTypesTypeConfig
+  | null;
+
+/** Options for `typescript/no-restricted-types`. */
+export interface ITtscLintTypeScriptNoRestrictedTypesRuleOptions {
+  /**
+   * Type spellings to reject. Whitespace is ignored in both keys and source
+   * spellings; `false` and `null` entries explicitly disable a key.
+   */
+  types?: Readonly<
+    Record<string, TtscLintTypeScriptNoRestrictedTypesTypeValue>
+  >;
+}
+
+/** Options for `typescript/no-floating-promises`. */
+export interface ITtscLintTypeScriptNoFloatingPromisesRuleOptions {
+  /** Functions whose returned Promises may be discarded safely. */
+  allowForKnownSafeCalls?: readonly TtscLintTypeOrValueSpecifier[];
+  /** Promise types whose values may be discarded safely. */
+  allowForKnownSafePromises?: readonly TtscLintTypeOrValueSpecifier[];
+  /** Also inspect catchable structural thenables. Defaults to `false`. */
+  checkThenables?: boolean;
+  /**
+   * Ignore immediately invoked function-expression results. Defaults to
+   * `false`.
+   */
+  ignoreIIFE?: boolean;
+  /** Treat `void` as an explicit discard marker. Defaults to `true`. */
+  ignoreVoid?: boolean;
+}
+
+/**
+ * Policy for one `@ts-<directive>` comment kind in `typescript/ban-ts-comment`.
+ *
+ * - `true` — report every use of the directive.
+ * - `false` — allow the directive unconditionally.
+ * - `"allow-with-description"` — allow the directive when it is followed by a
+ *   description of at least `minimumDescriptionLength` characters.
+ * - `{ descriptionFormat }` — additionally require the description to match the
+ *   given regular expression (evaluated with Go's RE2 `regexp` syntax, which
+ *   covers the usual patterns such as `"^: TS\\d+ because .+$"`).
+ */
+export type TtscLintTypeScriptBanTsCommentDirectiveConfig =
+  | boolean
+  | "allow-with-description"
+  | {
+      /**
+       * Regular expression the directive description must match. Matched
+       * against the raw text following the directive, including its leading
+       * whitespace, so anchored patterns usually start with `^: `.
+       */
+      descriptionFormat: string;
+    };
+
+/**
+ * `typescript/ban-ts-comment` rule options.
+ *
+ * Absent directive keys keep the upstream recommended defaults: `@ts-check` is
+ * allowed, `@ts-expect-error` is allowed with a description, and `@ts-ignore` /
+ * `@ts-nocheck` are reported.
+ */
+export interface ITtscLintTypeScriptBanTsCommentRuleOptions {
+  /**
+   * Minimum description length (counted in Unicode 16.0 extended grapheme
+   * clusters, so one emoji is one character) for directives configured as
+   * `"allow-with-description"` or `{ descriptionFormat }`.
+   *
+   * @default 3
+   */
+  minimumDescriptionLength?: number;
+
+  /**
+   * Policy for `@ts-check` pragma comments.
+   *
+   * @default false
+   */
+  "ts-check"?: TtscLintTypeScriptBanTsCommentDirectiveConfig;
+
+  /**
+   * Policy for `@ts-expect-error` directive comments.
+   *
+   * @default "allow-with-description"
+   */
+  "ts-expect-error"?: TtscLintTypeScriptBanTsCommentDirectiveConfig;
+
+  /**
+   * Policy for `@ts-ignore` directive comments.
+   *
+   * @default true
+   */
+  "ts-ignore"?: TtscLintTypeScriptBanTsCommentDirectiveConfig;
+
+  /**
+   * Policy for `@ts-nocheck` pragma comments.
+   *
+   * @default true
+   */
+  "ts-nocheck"?: TtscLintTypeScriptBanTsCommentDirectiveConfig;
+}
+
+/**
+ * Positions governed by `checksVoidReturn` in `typescript/no-misused-promises`.
+ *
+ * Omitted keys default to `true`.
+ */
+export interface ITtscLintTypeScriptNoMisusedPromisesChecksVoidReturnOptions {
+  /** Check Promise-returning callbacks passed as call/construct arguments. */
+  arguments?: boolean;
+
+  /** Check Promise-returning JSX attribute expressions. */
+  attributes?: boolean;
+
+  /** Check Promise-returning methods against extended/implemented types. */
+  inheritedMethods?: boolean;
+
+  /** Check Promise-returning functions in contextually typed properties. */
+  properties?: boolean;
+
+  /** Check Promise-returning functions returned from void-function factories. */
+  returns?: boolean;
+
+  /** Check Promise-returning functions assigned to variables. */
+  variables?: boolean;
+}
+
+/** `typescript/no-misused-promises` rule options. */
+export interface ITtscLintTypeScriptNoMisusedPromisesRuleOptions {
+  /**
+   * Check thenables used in boolean condition and predicate positions.
+   *
+   * @default true
+   */
+  checksConditionals?: boolean;
+
+  /**
+   * Check thenables spread into object literals.
+   *
+   * @default true
+   */
+  checksSpreads?: boolean;
+
+  /**
+   * Check Promise-returning functions where a void return is expected.
+   *
+   * @default true
+   */
+  checksVoidReturn?:
+    | boolean
+    | ITtscLintTypeScriptNoMisusedPromisesChecksVoidReturnOptions;
+}
+
+/**
+ * `typescript/switch-exhaustiveness-check` rule options.
+ *
+ * The defaults require every enumerable union member to have an explicit
+ * `case`, allow a redundant `default` on an already exhaustive switch, and do
+ * not require a `default` for open types such as `string` or `number`.
+ *
+ * @reference https://typescript-eslint.io/rules/switch-exhaustiveness-check
+ */
+export interface ITtscLintTypeScriptSwitchExhaustivenessCheckRuleOptions {
+  /**
+   * Allow a `default` clause on a switch whose finite members are already
+   * covered explicitly.
+   *
+   * @default true
+   */
+  allowDefaultCaseForExhaustiveSwitch?: boolean;
+
+  /**
+   * Treat a real `default` clause or matching trailing comment as coverage for
+   * otherwise missing finite members.
+   *
+   * @default false
+   */
+  considerDefaultExhaustiveForUnions?: boolean;
+
+  /**
+   * Regular expression matched against the trimmed body of the last comment
+   * after the final `case`. The default marker is `/^no default$/iu`.
+   *
+   * Custom patterns use Go's RE2 `regexp` syntax.
+   */
+  defaultCaseCommentPattern?: string;
+
+  /**
+   * Require a real `default` clause or matching trailing comment when the
+   * discriminant contains an open, non-literal type.
+   *
+   * @default false
+   */
+  requireDefaultForNonUnion?: boolean;
+}

package/src/structures/rules/ITtscLintTypeScriptRules.ts

@@ -1,4 +1,14 @@
-import type { TtscLintRuleSetting } from "../TtscLintRuleSetting";
+import type {
+  TtscLintRuleOptionsSetting,
+  TtscLintRuleSetting,
+} from "../TtscLintRuleSetting";
+import type {
+  ITtscLintTypeScriptBanTsCommentRuleOptions,
+  ITtscLintTypeScriptNoFloatingPromisesRuleOptions,
+  ITtscLintTypeScriptNoMisusedPromisesRuleOptions,
+  ITtscLintTypeScriptNoRestrictedTypesRuleOptions,
+  ITtscLintTypeScriptSwitchExhaustivenessCheckRuleOptions,
+} from "./ITtscLintTypeScriptRuleOptions";
 
 /**
  * TypeScript-only rules and `@typescript-eslint` plugin equivalents, exposed
@@ -41,25 +51,34 @@ export interface ITtscLintTypeScriptRules {
   "typescript/array-type"?: TtscLintRuleSetting;
 
   /**
-   * Reject `await` on operands that are not thenable.
+   * Reject non-awaitable ordinary `await` operands and native Promise
+   * aggregator members.
    *
-   * Type-aware — the Checker decides whether the awaited expression has a
-   * `then` method. Autofixable: drops the `await`.
+   * Also reject sync-only `for await...of` and `await using` constructs.
+   *
+   * Type-aware. The Checker resolves Promise and well-known-symbol protocols,
+   * including each Promise aggregator input's synchronous iterator yield type.
+   * Ordinary `await` findings offer an opt-in editor suggestion, while
+   * automatic fix and fix-all paths leave the source unchanged.
    *
    * @reference https://typescript-eslint.io/rules/await-thenable
    */
   "typescript/await-thenable"?: TtscLintRuleSetting;
 
   /**
-   * Reject `@ts-ignore` and `@ts-expect-error` comments.
+   * Reject `@ts-<directive>` comments, or require them to carry a description.
    *
-   * The rule flags both directives unconditionally. There is no
-   * description-based allowance, and the `@typescript-eslint` options are not
-   * implemented.
+   * With the upstream recommended defaults, `@ts-ignore` and `@ts-nocheck` are
+   * reported, `@ts-check` is allowed, and `@ts-expect-error` is allowed when
+   * followed by a description of at least three characters. Each directive is
+   * individually configurable as `boolean`, `"allow-with-description"`, or `{
+   * descriptionFormat }`, with `minimumDescriptionLength` governing the
+   * description-required forms. Banned `@ts-ignore` findings offer replacement
+   * with `@ts-expect-error` only as an opt-in editor suggestion.
    *
    * @reference https://typescript-eslint.io/rules/ban-ts-comment
    */
-  "typescript/ban-ts-comment"?: TtscLintRuleSetting;
+  "typescript/ban-ts-comment"?: TtscLintRuleOptionsSetting<ITtscLintTypeScriptBanTsCommentRuleOptions>;
 
   /**
    * Reject `// tslint:disable` and related TSLint directive comments left
@@ -307,12 +326,13 @@ export interface ITtscLintTypeScriptRules {
    *
    * Type-aware via the Checker. A floating promise loses its rejection channel
    * and runs out of order with surrounding code. Acceptable sinks are `await`,
-   * `.catch(...)`, `.then(_, onRejected)`, `.finally(...)`, assignment, the
-   * `void` operator, and `return`.
+   * callable rejection handlers, assignment, the `void` operator by default,
+   * and `return`. A `.finally(...)` call is clean only when its receiver was
+   * already handled.
    *
    * @reference https://typescript-eslint.io/rules/no-floating-promises
    */
-  "typescript/no-floating-promises"?: TtscLintRuleSetting;
+  "typescript/no-floating-promises"?: TtscLintRuleOptionsSetting<ITtscLintTypeScriptNoFloatingPromisesRuleOptions>;
 
   /**
    * Reject `for (const k in arr)` where `arr` is statically typed as an array
@@ -392,15 +412,13 @@ export interface ITtscLintTypeScriptRules {
   /**
    * Reject Promise values supplied where a non-Promise was expected.
    *
-   * Covers conditional positions (`if (promise)`, `while`, `for`, ternary,
-   * `&&`, `||`, `??`) where the Promise is truthy by reference, and `async`
-   * callbacks passed to APIs that expect a void-returning function (e.g.
-   * `Array#forEach`, JSX event handlers), where the returned Promise is
-   * silently dropped.
+   * Covers conditional and predicate positions, Promise object spreads,
+   * synchronous disposal, and Promise-returning functions in void-return
+   * argument, JSX, inherited-method, property, return, and variable contexts.
    *
    * @reference https://typescript-eslint.io/rules/no-misused-promises
    */
-  "typescript/no-misused-promises"?: TtscLintRuleSetting;
+  "typescript/no-misused-promises"?: TtscLintRuleOptionsSetting<ITtscLintTypeScriptNoMisusedPromisesRuleOptions>;
 
   /**
    * Reject spread expressions whose operand is syntactically wrong for the
@@ -479,19 +497,13 @@ export interface ITtscLintTypeScriptRules {
   "typescript/no-redundant-type-constituents"?: TtscLintRuleSetting;
 
   /**
-   * Reject specific type-reference names that are almost always a mistake — by
-   * default the global wrapper types `Object`, `Function`, `Number`, `String`,
-   * and `Boolean`. The lowercase primitives (`number`, `string`, `boolean`) and
-   * explicit call signatures convey the intended type without the
-   * runtime-boxing semantics that the wrapper names imply.
-   *
-   * AST-only baseline: shadow guard reuses the same file-scope check as
-   * `no-wrapper-object-types` so a user-declared `interface String {}` is not
-   * flagged as the global wrapper.
+   * Reject the exact type spellings configured in the `types` map. The rule is
+   * a no-op without options. Entries can carry a custom message, an automatic
+   * replacement, and editor-only replacement suggestions.
    *
    * @reference https://typescript-eslint.io/rules/no-restricted-types
    */
-  "typescript/no-restricted-types"?: TtscLintRuleSetting;
+  "typescript/no-restricted-types"?: TtscLintRuleOptionsSetting<ITtscLintTypeScriptNoRestrictedTypesRuleOptions>;
 
   /**
    * Reject `require(...)` calls and `import x = require(...)` declarations.
@@ -614,7 +626,8 @@ export interface ITtscLintTypeScriptRules {
 
   /**
    * Reject `<T extends unknown>` and similar constraints that match everything.
-   * Autofixable: drops the constraint.
+   * Autofixable: drops the constraint while retaining the disambiguating comma
+   * required by single-parameter generic arrows in TSX, MTS, and CTS files.
    *
    * @reference https://typescript-eslint.io/rules/no-unnecessary-type-constraint
    */
@@ -632,11 +645,14 @@ export interface ITtscLintTypeScriptRules {
   "typescript/no-unsafe-argument"?: TtscLintRuleSetting;
 
   /**
-   * Reject assigning an `any`-typed value into a concretely typed location —
-   * variable initializer with an explicit annotation, or a reassignment whose
-   * left-hand side has a static type.
+   * Reject direct and nested `any` values escaping through assignment
+   * boundaries. Covers annotated and inferred variables, reassignments,
+   * defaults, class members, contextual properties, spreads, and
+   * destructuring.
    *
-   * Type-aware via the Checker. `unknown` is not flagged.
+   * Type-aware via the Checker. Matching generic references are compared
+   * recursively with cycle protection. `any` may flow into `unknown`, including
+   * a corresponding nested generic argument. The rule has no options.
    *
    * @reference https://typescript-eslint.io/rules/no-unsafe-assignment
    */
@@ -795,7 +811,12 @@ export interface ITtscLintTypeScriptRules {
   "typescript/parameter-properties"?: TtscLintRuleSetting;
 
   /**
-   * Prefer `as const` over `as "literal"` assertions. Autofixable.
+   * Prefer `as const` over literal type assertions (`as "literal"`,
+   * `<"literal">`) and matching literal type annotations on variable and
+   * class-property declarations. Literals are compared by raw source spelling.
+   * Assertions are autofixable. Annotation findings expose an editor quick fix
+   * that removes the annotation and appends `as const`; `ttsc fix` never
+   * applies that suggestion automatically.
    *
    * @reference https://typescript-eslint.io/rules/prefer-as-const
    */
@@ -1117,18 +1138,19 @@ export interface ITtscLintTypeScriptRules {
   "typescript/strict-boolean-expressions"?: TtscLintRuleSetting;
 
   /**
-   * Require every member of a union or `enum` discriminant to be covered by an
-   * explicit `case`, unless a `default` clause is present.
+   * Require every enumerable member of a discriminant to be covered by an
+   * explicit `case`.
    *
-   * Type-aware via the Checker. The rule resolves the discriminant type, walks
-   * each constituent of the union (or each member of the enum), matches it
-   * against the `case` expressions in the body, and flags the switch when at
-   * least one constituent is uncovered and no `default` clause is present. A
-   * `default` clause covers the remaining shape and silences the rule.
+   * Type-aware via the Checker. Singleton literals, literal unions, enums,
+   * nullish members, bigint and boolean literals, unique symbols, constrained
+   * generics, and literal pieces of intersections are enumerable. Open
+   * primitive pieces remain unenumerated without hiding adjacent finite
+   * members. Under the default options, a `default` clause does not replace
+   * explicit finite-member coverage.
    *
    * @reference https://typescript-eslint.io/rules/switch-exhaustiveness-check
    */
-  "typescript/switch-exhaustiveness-check"?: TtscLintRuleSetting;
+  "typescript/switch-exhaustiveness-check"?: TtscLintRuleOptionsSetting<ITtscLintTypeScriptSwitchExhaustivenessCheckRuleOptions>;
 
   /**
    * Reject `/// <reference path="..." />`, `/// <reference types="" />`, and