@ttsc/lint 0.14.0-dev.20260529.2 → 0.14.1

package/linthost/rules_unicorn_text_encoding_identifier_case.go

@@ -14,9 +14,9 @@
 package linthost
 
 import (
-	"strings"
+  "strings"
 
-	shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimast "github.com/microsoft/typescript-go/shim/ast"
 )
 
 type unicornTextEncodingIdentifierCase struct{}
@@ -25,48 +25,48 @@ type unicornTextEncodingIdentifierCase struct{}
 // spelling. Authors who already wrote the canonical form pass; anything
 // else with the same lowercased label fires.
 var unicornCanonicalTextEncodings = map[string]string{
-	"utf-8":        "utf-8",
-	"utf-16le":     "utf-16le",
-	"utf-16be":     "utf-16be",
-	"ascii":        "ascii",
-	"latin1":       "latin1",
-	"iso-8859-1":   "iso-8859-1",
-	"windows-1252": "windows-1252",
+  "utf-8":        "utf-8",
+  "utf-16le":     "utf-16le",
+  "utf-16be":     "utf-16be",
+  "ascii":        "ascii",
+  "latin1":       "latin1",
+  "iso-8859-1":   "iso-8859-1",
+  "windows-1252": "windows-1252",
 }
 
 func (unicornTextEncodingIdentifierCase) Name() string {
-	return "unicorn/text-encoding-identifier-case"
+  return "unicorn/text-encoding-identifier-case"
 }
 func (unicornTextEncodingIdentifierCase) Visits() []shimast.Kind {
-	return []shimast.Kind{shimast.KindStringLiteral, shimast.KindNoSubstitutionTemplateLiteral}
+  return []shimast.Kind{shimast.KindStringLiteral, shimast.KindNoSubstitutionTemplateLiteral}
 }
 func (unicornTextEncodingIdentifierCase) Check(ctx *Context, node *shimast.Node) {
-	text := stringLiteralText(node)
-	if text == "" {
-		return
-	}
-	lower := strings.ToLower(text)
-	canonical, ok := unicornCanonicalTextEncodings[lower]
-	if !ok {
-		// `utf8`/`UTF8` share a canonical form with `utf-8` but lowercase
-		// differently — handle the hyphen-stripped aliases explicitly.
-		switch lower {
-		case "utf8":
-			canonical = "utf-8"
-		case "utf16le":
-			canonical = "utf-16le"
-		case "utf16be":
-			canonical = "utf-16be"
-		default:
-			return
-		}
-	}
-	if text == canonical {
-		return
-	}
-	ctx.Report(node, "Use the canonical lowercase form for text-encoding identifiers (e.g. `utf-8`).")
+  text := stringLiteralText(node)
+  if text == "" {
+    return
+  }
+  lower := strings.ToLower(text)
+  canonical, ok := unicornCanonicalTextEncodings[lower]
+  if !ok {
+    // `utf8`/`UTF8` share a canonical form with `utf-8` but lowercase
+    // differently — handle the hyphen-stripped aliases explicitly.
+    switch lower {
+    case "utf8":
+      canonical = "utf-8"
+    case "utf16le":
+      canonical = "utf-16le"
+    case "utf16be":
+      canonical = "utf-16be"
+    default:
+      return
+    }
+  }
+  if text == canonical {
+    return
+  }
+  ctx.Report(node, "Use the canonical lowercase form for text-encoding identifiers (e.g. `utf-8`).")
 }
 
 func init() {
-	Register(unicornTextEncodingIdentifierCase{})
+  Register(unicornTextEncodingIdentifierCase{})
 }

package/linthost/rules_unicorn_throw_new_error.go

@@ -17,45 +17,45 @@ package linthost
 import shimast "github.com/microsoft/typescript-go/shim/ast"
 
 var unicornThrowNewErrorBuiltinNames = map[string]struct{}{
-	"Error":          {},
-	"TypeError":      {},
-	"RangeError":     {},
-	"SyntaxError":    {},
-	"ReferenceError": {},
-	"EvalError":      {},
-	"URIError":       {},
-	"AggregateError": {},
+  "Error":          {},
+  "TypeError":      {},
+  "RangeError":     {},
+  "SyntaxError":    {},
+  "ReferenceError": {},
+  "EvalError":      {},
+  "URIError":       {},
+  "AggregateError": {},
 }
 
 type unicornThrowNewError struct{}
 
 func (unicornThrowNewError) Name() string { return "unicorn/throw-new-error" }
 func (unicornThrowNewError) Visits() []shimast.Kind {
-	return []shimast.Kind{shimast.KindThrowStatement}
+  return []shimast.Kind{shimast.KindThrowStatement}
 }
 func (unicornThrowNewError) Check(ctx *Context, node *shimast.Node) {
-	throw := node.AsThrowStatement()
-	if throw == nil {
-		return
-	}
-	expr := stripParens(throw.Expression)
-	if expr == nil || expr.Kind != shimast.KindCallExpression {
-		return
-	}
-	call := expr.AsCallExpression()
-	if call == nil {
-		return
-	}
-	name := identifierText(call.Expression)
-	if name == "" {
-		return
-	}
-	if _, ok := unicornThrowNewErrorBuiltinNames[name]; !ok {
-		return
-	}
-	ctx.Report(expr, "Use `new` when throwing an error.")
+  throw := node.AsThrowStatement()
+  if throw == nil {
+    return
+  }
+  expr := stripParens(throw.Expression)
+  if expr == nil || expr.Kind != shimast.KindCallExpression {
+    return
+  }
+  call := expr.AsCallExpression()
+  if call == nil {
+    return
+  }
+  name := identifierText(call.Expression)
+  if name == "" {
+    return
+  }
+  if _, ok := unicornThrowNewErrorBuiltinNames[name]; !ok {
+    return
+  }
+  ctx.Report(expr, "Use `new` when throwing an error.")
 }
 
 func init() {
-	Register(unicornThrowNewError{})
+  Register(unicornThrowNewError{})
 }

package/linthost/rules_var.go

@@ -20,20 +20,272 @@ func (noVar) Check(ctx *Context, node *shimast.Node) {
     return
   }
   if shimast.IsVar(stmt.DeclarationList) {
+    const message = "Unexpected var, use let or const instead."
     start := keywordStart(ctx.File, stmt.DeclarationList, "var")
-    if start >= 0 {
+    if start >= 0 && isNoVarAutoFixSafe(ctx, node) {
       ctx.ReportRangeFix(
         start,
         start+len("var"),
-        "Unexpected var, use let or const instead.",
+        message,
         TextEdit{Pos: start, End: start + len("var"), Text: "let"},
       )
       return
     }
-    ctx.Report(node, "Unexpected var, use let or const instead.")
+    ctx.Report(node, message)
   }
 }
 
+// isNoVarAutoFixSafe reports whether rewriting a `var` statement's keyword to
+// `let` is safe using only AST-local information (no scope/data-flow engine).
+// It mirrors the conservative posture of isEqeqeqAutoFixSafe: over-declining
+// is fine, corrupting source is not. Blindly turning every `var` into `let`
+// breaks two real shapes that `var` hoisting tolerates but `let` does not:
+//   - redeclaration (`var x=1; var x=2;`) → two `let x` is a SyntaxError;
+//   - use-before-declaration (a binding referenced above its own line) →
+//     `let` makes that reference a TDZ ReferenceError.
+//
+// Five corruption holes were patched piecemeal here before (var-vs-var,
+// for-header var, function/class redeclaration, mixed destructuring sibling,
+// object-literal shorthand, use-before-declaration). That whack-a-mole is
+// replaced by one conservative rule with two preconditions; the fix is
+// emitted only if BOTH hold:
+//
+//  1. Single binding in the whole file. The declared name is introduced by
+//     EXACTLY ONE binding position anywhere in the source — counting every
+//     binding-introducing slot of that identifier: variable declarations and
+//     destructuring leaves, function/class/enum/module declarations,
+//     parameters and catch bindings, and import bindings. More than one such
+//     position → decline. This single count subsumes every prior
+//     redeclaration arm (var-vs-var, var-vs-param, var-vs-function, mixed
+//     destructure siblings, for-header var, …). It over-declines harmless
+//     cross-scope same-name bindings, which never corrupts.
+//  2. No use-before-declaration / TDZ. The declared name is not referenced as
+//     a VALUE before the statement's Pos(). A non-reference occurrence of the
+//     same text — a member name (`o.x`), an object-literal key (`{x:1}`), a
+//     statement label (`x:`), or a type reference (`: x`) — binds no value and
+//     must not force a decline; isValueReferenceIdentifier classifies these.
+//
+// The var statement being fixed must itself be a single plain identifier
+// declarator so the keyword rewrite has a simple `let x` rename target; a
+// destructuring var (`var {a}=o`) or a multi-binding list is declined here
+// even though its names might each bind only once.
+func isNoVarAutoFixSafe(ctx *Context, node *shimast.Node) bool {
+  if ctx == nil || ctx.File == nil {
+    return false
+  }
+  // Precondition: the var being fixed is a single plain identifier declarator.
+  // variableStatementBindingNames returns plain identifier names only, so a
+  // destructuring declarator yields zero names; requiring exactly one name AND
+  // exactly one VariableDeclaration node rejects both multi-binding lists and
+  // any destructured (or destructured-sibling) declarator.
+  names := variableStatementBindingNames(node)
+  if len(names) != 1 {
+    return false
+  }
+  if list := node.AsVariableStatement().DeclarationList.AsVariableDeclarationList(); list == nil ||
+    list.Declarations == nil || len(list.Declarations.Nodes) != 1 {
+    return false
+  }
+  target := names[0]
+
+  declPos := node.Pos()
+  // The single declarator's initializer subtree. A value reference to `target`
+  // inside this range is a self-reference that runs while `target` is still in
+  // its temporal dead zone under `let` (`var x = typeof x;`, `var x = x;`,
+  // `var x = (() => x)();`), so it must also force a decline even though its
+  // Pos() is AFTER the statement's start. initStart/initEnd are -1 when the
+  // declarator has no initializer, which disables the range check.
+  initStart, initEnd := -1, -1
+  if list := node.AsVariableStatement().DeclarationList.AsVariableDeclarationList(); list != nil &&
+    list.Declarations != nil && len(list.Declarations.Nodes) == 1 {
+    if decl := list.Declarations.Nodes[0].AsVariableDeclaration(); decl != nil && decl.Initializer != nil {
+      initStart, initEnd = decl.Initializer.Pos(), decl.Initializer.End()
+    }
+  }
+  bindingCount := 0
+  referencedBefore := false
+  walkDescendants(ctx.File.AsNode(), func(child *shimast.Node) {
+    // Binding count: every position that introduces the name `target` as a
+    // binding (a declaration), not a value reference. Two or more positions
+    // anywhere in the file decline the fix.
+    for _, name := range bindingNamesIntroducedBy(child) {
+      if name == target {
+        bindingCount++
+      }
+    }
+    // TDZ: a value reference to `target` turns into a ReferenceError under
+    // `let` when it executes while `target` is still in its temporal dead
+    // zone. Two cases decline:
+    //   - a reference BEFORE the var's own position (`log(x); var x = 1;`);
+    //   - a self-reference WITHIN the declarator's own initializer range
+    //     (`var x = typeof x;`). Conservatively, any value reference inside
+    //     the initializer declines — including a deferred read in a nested
+    //     closure (`var f = () => f;`) that is actually safe — because the
+    //     AST-local gate does not track whether that closure runs during
+    //     initialization. Over-declining never corrupts source.
+    if child.Kind == shimast.KindIdentifier && identifierText(child) == target &&
+      isValueReferenceIdentifier(child) {
+      pos := child.Pos()
+      if pos < declPos || (initStart >= 0 && pos >= initStart && pos < initEnd) {
+        referencedBefore = true
+      }
+    }
+  })
+  if referencedBefore {
+    return false
+  }
+  return bindingCount == 1
+}
+
+// bindingNamesIntroducedBy returns every plain identifier name that `node`
+// introduces as a binding in its OWN slot — never the names bound by its
+// descendants, which the file-wide walk visits independently. The classifier
+// is by AST kind and slot so a value reference, member name, object-literal
+// key, label, or type reference of the same text is excluded; only genuine
+// declarations contribute.
+//
+// A destructuring declarator (`var { a } = o`, `function f([a]) {}`) is NOT
+// flattened here: its leaf names belong to the BindingElement descendants,
+// which the walk visits on their own, so each leaf is counted exactly once at
+// its own position. Declaration nodes therefore contribute only when their
+// own name slot is a plain identifier.
+//
+// Returns nil for any node that introduces no binding in its own slot. Type
+// aliases and interfaces are intentionally absent: they live in the type
+// namespace and merge with a same-name value binding without a `let`
+// duplicate-declaration error.
+func bindingNamesIntroducedBy(node *shimast.Node) []string {
+  if node == nil {
+    return nil
+  }
+  switch node.Kind {
+  case shimast.KindVariableDeclaration:
+    if decl := node.AsVariableDeclaration(); decl != nil {
+      if name := identifierText(decl.Name()); name != "" {
+        return []string{name}
+      }
+    }
+  case shimast.KindParameter:
+    if decl := node.AsParameterDeclaration(); decl != nil {
+      if name := identifierText(decl.Name()); name != "" {
+        return []string{name}
+      }
+    }
+  case shimast.KindBindingElement:
+    // A leaf of a destructuring pattern (`{ a }`, `[a]`, `{ k: a }`,
+    // `...rest`). Only the element's own bound name counts; nested patterns
+    // are their own BindingElement descendants, and the default-value
+    // initializer is a value reference, not a binding.
+    if elem := node.AsBindingElement(); elem != nil {
+      if name := identifierText(elem.Name()); name != "" {
+        return []string{name}
+      }
+    }
+  case shimast.KindFunctionDeclaration:
+    if decl := node.AsFunctionDeclaration(); decl != nil && decl.Body != nil {
+      if name := identifierText(decl.Name()); name != "" {
+        return []string{name}
+      }
+    }
+  case shimast.KindClassDeclaration:
+    if name := identifierText(node.Name()); name != "" {
+      return []string{name}
+    }
+  case shimast.KindEnumDeclaration, shimast.KindModuleDeclaration:
+    if name := identifierText(node.Name()); name != "" {
+      return []string{name}
+    }
+  case shimast.KindCatchClause:
+    // `catch (e)` — the catch binding. A destructured catch binding
+    // (`catch ({ e })`) has its leaves counted via the BindingElement
+    // descendants, so only a plain identifier binding counts here.
+    if catch := node.AsCatchClause(); catch != nil && catch.VariableDeclaration != nil {
+      if name := identifierText(catch.VariableDeclaration.Name()); name != "" {
+        return []string{name}
+      }
+    }
+  case shimast.KindImportClause:
+    // `import foo from "m"` — the default import binding. Named and
+    // namespace bindings are their own ImportSpecifier / NamespaceImport
+    // descendants, visited separately.
+    if name := identifierText(node.Name()); name != "" {
+      return []string{name}
+    }
+  case shimast.KindNamespaceImport:
+    // `import * as ns from "m"`.
+    if name := identifierText(node.Name()); name != "" {
+      return []string{name}
+    }
+  case shimast.KindImportSpecifier:
+    // `import { a } from "m"` / `import { a as b } from "m"` — the local
+    // binding is the specifier's Name(), not the PropertyName.
+    if name := identifierText(node.Name()); name != "" {
+      return []string{name}
+    }
+  case shimast.KindImportEqualsDeclaration:
+    // `import x = require("m")` / `import x = A.B`.
+    if name := identifierText(node.Name()); name != "" {
+      return []string{name}
+    }
+  }
+  return nil
+}
+
+// isValueReferenceIdentifier reports whether an Identifier node occupies a
+// value-reference position rather than a non-reference role that merely
+// reuses the same text. The use-before-declaration gate in
+// isNoVarAutoFixSafe matches identifiers by text alone, so it would
+// otherwise decline on positions that bind no value:
+//
+//   - the `name` of a property access (`o.x`) or qualified name (`A.x`);
+//   - an object-literal property key (`{ x: 1 }`) or shorthand key;
+//   - a statement label (`x:` / `break x`);
+//   - a type reference (`: x`) whose `TypeName` is the identifier.
+//
+// Classification is by the identifier's parent node kind and slot, never
+// by text. Any unrecognized parent is treated as a value reference
+// (safety first: an unclassified position keeps declining).
+func isValueReferenceIdentifier(node *shimast.Node) bool {
+  parent := node.Parent
+  if parent == nil {
+    return true
+  }
+  switch parent.Kind {
+  case shimast.KindPropertyAccessExpression:
+    // `o.x`: only the object expression is a reference; the member name
+    // is a property, not a binding.
+    access := parent.AsPropertyAccessExpression()
+    return access == nil || access.Name() != node
+  case shimast.KindQualifiedName:
+    // `A.x` in type position: the right side is a property name.
+    qn := parent.AsQualifiedName()
+    return qn == nil || qn.Right != node
+  case shimast.KindPropertyAssignment:
+    // `{ x: target }`: the key is not a reference; the value is.
+    assign := parent.AsPropertyAssignment()
+    return assign == nil || assign.Name() != node
+  // `{ x }`: an object-literal shorthand is a VALUE READ of binding `x`
+  // (object destructuring parses as KindBindingElement and is handled
+  // elsewhere). It falls through to the default `true` so the
+  // use-before-declaration gate sees the forward reference and declines.
+  case shimast.KindLabeledStatement:
+    // `x:` label — a statement label shares no namespace with values.
+    lbl := parent.AsLabeledStatement()
+    return lbl == nil || lbl.Label != node
+  case shimast.KindBreakStatement:
+    brk := parent.AsBreakStatement()
+    return brk == nil || brk.Label != node
+  case shimast.KindContinueStatement:
+    cont := parent.AsContinueStatement()
+    return cont == nil || cont.Label != node
+  case shimast.KindTypeReference:
+    // `: x` — a type reference lives in the type namespace.
+    ref := parent.AsTypeReferenceNode()
+    return ref == nil || ref.TypeName != node
+  }
+  return true
+}
+
 // preferConst: flag `let` declarations whose binding is never reassigned.
 // This follows ESLint's core rule for the common AST-local cases. It is
 // intentionally conservative: destructuring and declaration-only `let`
@@ -100,6 +352,24 @@ func (preferConst) Check(ctx *Context, node *shimast.Node) {
           assigned[name] = true
         }
       }
+    case shimast.KindForOfStatement, shimast.KindForInStatement:
+      // `for (x of …)` / `for (x in …)` reassigns the existing binding `x`
+      // on every iteration. When the initializer IS a
+      // VariableDeclarationList (`for (const y of …)`) it declares a fresh
+      // binding instead, so only a non-declaration initializer counts as a
+      // reassignment target. Missing this lets a pre-existing `let` be
+      // rewritten to `const` that the loop then assigns to — a TS error and
+      // runtime TypeError.
+      stmt := child.AsForInOrOfStatement()
+      if stmt == nil || stmt.Initializer == nil {
+        return
+      }
+      if stmt.Initializer.Kind == shimast.KindVariableDeclarationList {
+        return
+      }
+      for _, name := range assignmentTargetNames(stmt.Initializer) {
+        assigned[name] = true
+      }
     }
   })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/lint",
-  "version": "0.14.0-dev.20260529.2",
+  "version": "0.14.1",
   "description": "Reference ttsc plugin: ESLint-style lint rules hosted in the same Program/Checker as the type-check pass.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -33,10 +33,10 @@
     "src"
   ],
   "devDependencies": {
-    "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "@typescript/native-preview": "7.0.0-dev.20260519.1",
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
-    "ttsc": "0.14.0-dev.20260529.2"
+    "ttsc": "0.14.1"
   },
   "repository": {
     "type": "git",

package/src/defaultFormat.ts

@@ -1,14 +1,15 @@
-import type { ITtscLintFormat } from "./structures/ITtscLintFormat";
+import type { ITtscLintFormat } from "./structures/format/ITtscLintFormat";
 
 /**
  * Documented defaults for the `format` block's _always-on_ rules
- * (`format/semi`, `format/quotes`, `format/trailing-comma`,
+ * (`format/semi`, `format/quotes`, `format/arrow-parens`,
+ * `format/bracket-spacing`, `format/quote-props`, `format/trailing-comma`,
  * `format/print-width`).
  *
  * Exported so users can spread defaults next to overrides:
  *
  * ```ts
- * import { defaultFormat, type ITtscLintConfig } from "@ttsc/lint";
+ * import { type ITtscLintConfig, defaultFormat } from "@ttsc/lint";
  *
  * export default {
  *   format: { ...defaultFormat, printWidth: 100 },
@@ -18,15 +19,18 @@ import type { ITtscLintFormat } from "./structures/ITtscLintFormat";
  * The values mirror Prettier 1:1 except for the documented `endOfLine`
  * narrowing (no `"cr"` / `"auto"`).
  *
- * Notably absent: `importOrder` and `jsdoc`. `format/sort-imports` and
- * `format/jsdoc` are opt-in by setting their corresponding fields; this
- * const documents only the rules that turn on unconditionally with a
- * non-empty `format` block — the Go host owns runtime activation.
+ * Notably absent: `sortImports`. Import sorting is opt-in by setting
+ * `sortImports`; JSDoc normalization is always on (set `jsDoc: false` to opt
+ * out). This const documents only the keys that turn on unconditionally with a
+ * non-empty `format` block; the Go host owns runtime activation.
  */
 export const defaultFormat = Object.freeze({
   severity: "off",
   semi: true,
   singleQuote: false,
+  arrowParens: "always",
+  bracketSpacing: true,
+  quoteProps: "as-needed",
   trailingComma: "all",
   printWidth: 80,
   tabWidth: 2,

package/src/structures/ITtscLintConfig.ts

@@ -1,5 +1,5 @@
-import type { ITtscLintFormat } from "./ITtscLintFormat";
 import type { ITtscLintPlugin } from "./ITtscLintPlugin";
+import type { ITtscLintFormat } from "./format/ITtscLintFormat";
 import type { ITtscLintRules } from "./rules/ITtscLintRules";
 
 /**
@@ -22,8 +22,8 @@ export interface ITtscLintConfig {
    */
   extends?: string;
 
-  /** Contributor plugin objects keyed by namespace. */
-  plugins?: Record<string, ITtscLintPlugin>;
+  /** Prettier-style flat configuration for the format rules. */
+  format?: ITtscLintFormat;
 
   /**
    * Kebab-case built-in rule severities plus namespaced contributor rules.
@@ -34,6 +34,6 @@ export interface ITtscLintConfig {
    */
   rules?: ITtscLintRules;
 
-  /** Prettier-style flat configuration for the format rules. */
-  format?: ITtscLintFormat;
+  /** Contributor plugin objects keyed by namespace. */
+  plugins?: Record<string, ITtscLintPlugin>;
 }

package/src/structures/TtscLintRuleSetting.ts

@@ -6,12 +6,12 @@ import type { TtscLintSeverity } from "./TtscLintSeverity";
  *
  * A rule may be configured either as a bare severity string (`"error"`,
  * `"warning"`, `"off"`) or as a single-element tuple containing the same
- * severity. Both forms are equivalent at runtime; the tuple form exists so
- * that severity-only rules and options-bearing rules look uniform when read
+ * severity. Both forms are equivalent at runtime; the tuple form exists so that
+ * severity-only rules and options-bearing rules look uniform when read
  * top-to-bottom in a `ttsc.lint.config.ts` file.
  *
- * Use {@link TtscLintRuleOptionsSetting} when the rule accepts a typed
- * options object.
+ * Use {@link TtscLintRuleOptionsSetting} when the rule accepts a typed options
+ * object.
  *
  * @example
  *   const config: ITtscLintConfig = {
@@ -30,25 +30,25 @@ export type TtscLintRuleSetting =
  * Per-rule severity-plus-options setting for rules that accept a typed options
  * object.
  *
- * This is the tuple form ESLint users know — `[severity, options]` —
- * kept strongly typed by way of the rule's dedicated options interface
- * (see `TtscLintRuleOptions.ts`). The bare {@link TtscLintRuleSetting}
- * forms remain accepted; omitting the options object means "use the
- * rule's default options".
- *
- * @typeParam TOptions - The rule's options shape. Each rule supplies its
- *   own interface from `TtscLintRuleOptions.ts` (for example
- *   `ITtscLintBoundariesElementTypesRuleOptions`).
+ * This is the tuple form ESLint users know — `[severity, options]` — kept
+ * strongly typed by way of the rule's dedicated options interface (see
+ * `TtscLintRuleOptions.ts`). The bare {@link TtscLintRuleSetting} forms remain
+ * accepted; omitting the options object means "use the rule's default
+ * options".
  *
  * @example
  *   const config: ITtscLintConfig = {
- *     rules: {
- *       "boundaries/element-types": [
- *         "error",
- *         { default: "disallow", rules: [...] },
- *       ],
- *     },
+ *   rules: {
+ *   "boundaries/element-types": [
+ *   "error",
+ *   { default: "disallow", rules: [...] },
+ *   ],
+ *   },
  *   };
+ *
+ * @typeParam TOptions - The rule's options shape. Each rule supplies its own
+ *   interface from `TtscLintRuleOptions.ts` (for example
+ *   `ITtscLintBoundariesElementTypesRuleOptions`).
  */
 export type TtscLintRuleOptionsSetting<TOptions> =
   | TtscLintRuleSetting