@ttsc/lint 0.19.3 → 0.20.0

package/rule/hint.go

@@ -0,0 +1,142 @@
+package rule
+
+import "encoding/json"
+
+// HintScope names the syntactic region a hint is offered in. It exists because
+// a line prefix alone cannot tell `@evidence` in a doc comment from
+// `@Injectable` above a class: both lines end in `@`, and a corpus that ignored
+// the difference would offer doc-comment tags in every decorator position.
+//
+// One value ships today. The field is present anyway: a hint with no scope
+// would mean "anywhere on any line", which is never what a rule meant, and
+// widening that default later would break every corpus already published.
+type HintScope string
+
+const (
+  // HintScopeJSDoc offers the hint inside a `/** */` documentation comment.
+  HintScopeJSDoc HintScope = "jsdoc"
+)
+
+// HintTrigger is the declarative answer to "does this hint apply at the
+// cursor?".
+//
+// It must be declarative because the rule that produced it is gone. The lint
+// engine is a separate process that reloads the Program on every invocation, so
+// nothing can ask a rule a question per keystroke. A Go predicate is the obvious
+// API and is exactly the one that cannot ship: it does not survive the process
+// boundary. Every editor-assistance system that lets a rule answer live does so
+// in-process on a shared AST; this host cannot, so the corpus travels instead of
+// the question.
+//
+// The host matches a trigger against the current line up to the cursor: the hint
+// applies when the cursor sits inside Scope and the line prefix contains After.
+// Text following the LAST occurrence of After is the filter the editor matches
+// against, and the range the completion replaces. Two consequences to design
+// around:
+//
+// After must end exactly where the completed token begins — `"@evidence "` with
+// its trailing space, not `"@evidence"` — or the token swallows the separator
+// and nothing filters.
+//
+// When several triggers match one line, the occurrence nearest the cursor wins.
+// At that occurrence, the longest After wins, and only hints with that same
+// trigger merge. That keeps a corpus layerable while preventing an earlier,
+// longer trigger from drowning a later one.
+type HintTrigger struct {
+  Scope HintScope `json:"scope"`
+  After string    `json:"after"`
+}
+
+// Hint is one completion an editor may offer.
+//
+// It is a value, not a behavior: the host serializes the corpus and hands it to
+// the LSP proxy, which answers from cache long after the lint process exited. A
+// closure, a channel, or an AST node cannot be carried here, and that constraint
+// is the whole shape of the type.
+type Hint struct {
+  // Insert is the text replacing the token being completed. Plain text,
+  // inserted verbatim: there is no snippet expansion, so `$` and tabs are
+  // literal.
+  Insert string `json:"insert"`
+
+  // Label is what the editor lists and filters on. Empty means Insert, which
+  // is the common case. Set it only when the two genuinely differ, and
+  // remember the filter is what the user typed AFTER the trigger: a Label
+  // repeating the trigger text will not prefix-match anything.
+  Label string `json:"label,omitempty"`
+
+  // Detail is a short annotation rendered beside Label. Use it for the fact
+  // distinguishing two similar entries — a heading's text, a count. It is not
+  // documentation: editors truncate it, so a sentence is wasted.
+  Detail string `json:"detail,omitempty"`
+
+  // Trigger is where this hint applies. A zero Trigger is dropped by the host
+  // rather than offered everywhere: a hint with no scope is one nobody asked
+  // for, surfacing in every decorator and every string literal.
+  Trigger HintTrigger `json:"trigger"`
+}
+
+// HintContext is the read-only handle the host passes to Hints.
+//
+// It carries State because a rule value is stateless: contributors register
+// `myRule{}`, not a pointer with fields, and the host owns everything Check
+// produced. Without State here, Hints could only ever return constants.
+type HintContext struct {
+  // Identity names the Program this corpus is built for, as during Check.
+  Identity ProjectIdentity
+
+  // State is the value the rule passed to ProjectContext.SetState.
+  // Type-assert it back, exactly as a file rule does with
+  // ProjectRuleResult.State. The host calls Hints only for a rule that passed
+  // and published, so a failed assertion means the rule published something
+  // other than it believes.
+  State any
+
+  // Severity and Options are the resolved configuration Check ran under,
+  // repeated so a rule shaping its corpus by option need not stash a decoded
+  // struct inside State.
+  Severity Severity
+  Options  json.RawMessage
+}
+
+// DecodeOptions unmarshals the configured options into out. A missing options
+// tuple leaves out unchanged and returns nil.
+func (c *HintContext) DecodeOptions(out interface{}) error {
+  if c == nil || len(c.Options) == 0 {
+    return nil
+  }
+  return json.Unmarshal(c.Options, out)
+}
+
+// HintRule is an optional marker a ProjectRule implements to publish editor
+// completions for the Program it just indexed.
+//
+// The host calls Hints at most once per Program, always after Check, and only
+// when a consumer asks for the corpus — never during `ttsc check`. It is not
+// called unless Check passed and published state, the same gate a file rule
+// writes by hand against ProjectRulePassed. A rule configured off is never
+// asked, so `off` means no hints with no code in the rule, and a rule's options
+// shape its corpus for free because the corpus is a projection of the state
+// Check built under them.
+//
+// Pull, not push. Report is push because a finding is discovered mid-walk and
+// belongs to the node under it. A corpus is the opposite: a projection of
+// FINISHED state. A rule pushing hints while building that state would publish
+// the anchors it had found so far rather than the ones the document has.
+//
+// The corpus outlives the process, so slice order is the only ranking channel
+// there is — the host preserves it and derives the editor's sort key from it.
+// Return what should be offered first, first. Nothing else about a Hint
+// influences ordering, by design: a sort key field would be a second, silently
+// conflicting answer to a question the slice already answers.
+//
+// This embeds ProjectRule rather than standing alone as OptionsRule does,
+// because a per-file corpus is not a coherent thing. File rules run in a
+// parallel walk, so their hints would arrive — and therefore rank —
+// nondeterministically, and a corpus keyed to one file cannot answer a keystroke
+// in another. A contributor wanting hints from file-level facts registers a
+// ProjectRule alongside, which is what those facts wanted anyway.
+type HintRule interface {
+  ProjectRule
+  Hints(ctx *HintContext) []Hint
+}

package/rule/rule.go

@@ -112,6 +112,44 @@ type DeclarationFileRule interface {
   VisitsDeclarationFiles() bool
 }
 
+// DiagnosticTag classifies what a finding IS, orthogonally to how severe it is.
+// The values match the LSP DiagnosticTag enum, and an editor renders them
+// distinctively: unnecessary code is greyed out, deprecated code struck through.
+type DiagnosticTag int
+
+const (
+  // DiagnosticTagUnnecessary marks code that is safe to delete — an unused
+  // import, an unreachable branch. The editor fades it.
+  //
+  // This is a claim about what the code is, not how bad it is, and the
+  // distinction bites: "unnecessary" says "remove this." A finding that means
+  // "this is not done yet" is the opposite and must never carry it, or the
+  // editor tells the author to delete the work they have not finished. Tag by
+  // what deletion would mean, never by severity.
+  DiagnosticTagUnnecessary DiagnosticTag = 1
+  // DiagnosticTagDeprecated marks code that still works but should be migrated
+  // away from. The editor strikes it through.
+  DiagnosticTagDeprecated DiagnosticTag = 2
+)
+
+// TaggedRule is an optional marker a rule implements to classify its findings
+// with DiagnosticTags. Every finding the rule produces carries the returned
+// tags — the rule-level grain fits the rules that want this, since a rule that
+// flags unused code flags only unused code.
+//
+// It is separate from severity on purpose. Severity is how much a finding
+// matters and is the user's to configure; a tag is what the finding is and is
+// the rule's to state. A host that does not read tags loses the greying, not the
+// diagnostic — the same graceful degradation the other optional markers give.
+//
+// Return nil, or do not implement it, for a rule whose findings are neither
+// unnecessary nor deprecated. Most findings are neither, and guessing wrong is
+// worse than saying nothing: a spurious Unnecessary tells the author to delete
+// correct code.
+type TaggedRule interface {
+  DiagnosticTags() []DiagnosticTag
+}
+
 // TypeAwareRule is an optional marker contributors implement to declare
 // whether their rule reads `Context.Checker`. The host cannot infer a
 // third-party rule's shape, so a contributor that does not implement this
@@ -128,8 +166,12 @@ type DeclarationFileRule interface {
 // preserving the engine's parallel file walk. Returning `true` is equivalent
 // to not implementing the interface at all. A rule that returns `false` must
 // not read `Context.Checker`: the host is free to leave it nil.
+//
+// The method name is domain-specific so an unrelated generic method on an
+// existing contributor cannot opt out by accident. ProjectRule implementations
+// may use the same marker; the serial walk it governs is engine-wide, so one
+// type-aware project rule serializes every file rule in the run.
 type TypeAwareRule interface {
-  Rule
   NeedsTypeChecker() bool
 }
 
@@ -176,6 +218,43 @@ type FixReporter interface {
   ReportRangeFix(pos, end int, message string, edits ...TextEdit)
 }
 
+// RelatedReporter is the optional extension a host implements to receive a
+// finding's related source locations. Like FixReporter, the public
+// `rule.Context` type-asserts against this shape, so any host whose reporter
+// exposes both methods opts into related locations without depending on a
+// private interface name. A host that does not implement it loses the related
+// locations, not the diagnostic — the same graceful degradation the other
+// optional reporter extensions give.
+//
+// Rule production code does NOT touch RelatedReporter directly — call
+// `ctx.ReportRelated` / `ctx.ReportRangeRelated`, and the host's reporter
+// receives the locations. The only place a contributor sees this interface is in
+// test code that fakes the reporter: such a fake must implement BOTH `Reporter`
+// AND `RelatedReporter` to observe the locations, because Go interface
+// satisfaction is all-or-nothing. Declaring `var _ rule.RelatedReporter =
+// &myFake{}` compile-checks the fake covers the related surface.
+type RelatedReporter interface {
+  ReportRelated(node *shimast.Node, message string, related ...RelatedInformation)
+  ReportRangeRelated(pos, end int, message string, related ...RelatedInformation)
+}
+
+// RelatedInformation is a secondary source location a finding points at, paired
+// with a message naming the connection. LSP renders each as its own clickable
+// line beneath the diagnostic, so "'x' is already defined." can lead the reader
+// to the first definition instead of only naming it.
+//
+// Pos/End are byte offsets into the CURRENT file — the same offsets a shim AST
+// node exposes and `ReportRange` consumes — so a related location lives in the
+// file the finding is in, and the host fills in that file's URI. A location in
+// ANOTHER file would need a URI this API does not yet carry, and is a separate
+// extension left deliberately out of scope so the same-file case ships without
+// waiting on it.
+type RelatedInformation struct {
+  Pos     int
+  End     int
+  Message string
+}
+
 // TextEdit is one byte-range replacement offered by an autofixable finding.
 // Positions use the same byte offsets as shim AST nodes and must point inside
 // the current source file. An empty `Text` deletes the range; positions are
@@ -198,6 +277,42 @@ type TextEdit struct {
   Text string
 }
 
+// Suggestion is one of several candidate fixes offered for a finding, each with
+// its own title. It exists for the case `ReportFix` cannot serve: when a rule
+// knows more than one valid repair and cannot pick among them for the author.
+//
+// The distinction is the same one the built-in rules already draw and, until
+// now, kept to themselves. A fix is imposed; a suggestion is chosen. A rule that
+// found three valid renames must either impose one arbitrarily through
+// `ReportFix` or describe the three in prose and offer none — both worse than
+// letting the editor present the choice, which is what the built-ins do through
+// this shape and contributors could not reach.
+//
+// Edits within one Suggestion follow the same non-overlap policy as `TextEdit`
+// in a `ReportFix` call.
+type Suggestion struct {
+  // Title is what the editor shows for this choice, e.g. "Rename to `frames`".
+  Title string
+  // Edits apply this suggestion. Empty means the suggestion is a label with no
+  // edit — a "did you mean" the author acts on by hand.
+  Edits []TextEdit
+}
+
+// SuggestionReporter is the optional half of the reporter a host implements to
+// carry suggestions. A host that does not implement it still receives the
+// finding through `Reporter`, without the choices — the same graceful
+// degradation `FixReporter` gives autofixes.
+//
+// It is separate from `FixReporter` rather than folded into it because the two
+// answer different questions: `ReportFix` offers the one right rewrite, this
+// offers a choice among several. A rule reaches it through
+// `Context.ReportSuggestion` / `ReportRangeSuggestion`; it is not called
+// directly.
+type SuggestionReporter interface {
+  ReportSuggestion(node *shimast.Node, message string, suggestions ...Suggestion)
+  ReportRangeSuggestion(pos, end int, message string, suggestions ...Suggestion)
+}
+
 // Context is the per-(file, rule) handle the engine passes to `Check`.
 // The `Reporter` is supplied by the host when constructing the context;
 // contributors call `ctx.Report` / `ctx.ReportRange` directly through
@@ -342,6 +457,87 @@ func (c *Context) ReportRangeFix(pos, end int, message string, edits ...TextEdit
   fixer.ReportRangeFix(pos, end, message, edits...)
 }
 
+// ReportSuggestion records a finding at the node's range with a choice of
+// candidate fixes. A host that does not implement `SuggestionReporter` receives
+// the diagnostic without the choices, so design the rule so the message alone is
+// useful — the same best-effort contract as `ReportFix`.
+//
+// Use this over `ReportFix` only when there genuinely is a choice. One correct
+// rewrite is a fix; imposing it is the right thing. Several valid rewrites is a
+// suggestion; imposing one arbitrarily is not.
+func (c *Context) ReportSuggestion(node *shimast.Node, message string, suggestions ...Suggestion) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
+    return
+  }
+  if len(suggestions) == 0 {
+    c.reporter.Report(node, message)
+    return
+  }
+  suggester, ok := c.reporter.(SuggestionReporter)
+  if !ok {
+    c.reporter.Report(node, message)
+    return
+  }
+  suggester.ReportSuggestion(node, message, suggestions...)
+}
+
+// ReportRangeSuggestion records a finding at an explicit byte range with a
+// choice of candidate fixes. See `ReportSuggestion`.
+func (c *Context) ReportRangeSuggestion(pos, end int, message string, suggestions ...Suggestion) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff {
+    return
+  }
+  if len(suggestions) == 0 {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  suggester, ok := c.reporter.(SuggestionReporter)
+  if !ok {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  suggester.ReportRangeSuggestion(pos, end, message, suggestions...)
+}
+
+// ReportRelated records a finding at the given node's source range with related
+// source locations. Older hosts that do not implement RelatedReporter receive
+// the diagnostic without them, so design the rule to read well from the message
+// alone. With no related locations it is exactly `Report`.
+func (c *Context) ReportRelated(node *shimast.Node, message string, related ...RelatedInformation) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
+    return
+  }
+  if len(related) == 0 {
+    c.reporter.Report(node, message)
+    return
+  }
+  reporter, ok := c.reporter.(RelatedReporter)
+  if !ok {
+    c.reporter.Report(node, message)
+    return
+  }
+  reporter.ReportRelated(node, message, related...)
+}
+
+// ReportRangeRelated records a finding at an explicit byte range with related
+// source locations. Falls back to a plain range finding on a host without
+// RelatedReporter, and equals `ReportRange` when no related locations are given.
+func (c *Context) ReportRangeRelated(pos, end int, message string, related ...RelatedInformation) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff {
+    return
+  }
+  if len(related) == 0 {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  reporter, ok := c.reporter.(RelatedReporter)
+  if !ok {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  reporter.ReportRangeRelated(pos, end, message, related...)
+}
+
 var registry []Rule
 
 // Register adds a contributor rule to the global registry. Called from a

package/src/index.ts

@@ -223,10 +223,10 @@ function resolveConfigFileContributors(
   if (!configPath || !fs.existsSync(configPath)) return [];
 
   const entries = readConfigPluginEntries(configPath, context);
-  // Dedup on the Go-subpackage form (post hyphen→underscore transform)
-  // so two namespaces that collapse to the same Go identifier surface
-  // here instead of as the contributor validator's opaque
-  // `duplicate name "a_b"` error.
+  assertContributorNamespacesDoNotCollide(entries, configPath);
+  // Dedup exact repeated namespaces on the Go-subpackage form. Config-array
+  // folding can surface the same namespace more than once; that existing
+  // behavior stays intact after distinct namespaces are rejected above.
   const occupied = new Set<string>();
   const out: TtscPluginContributor[] = [];
   for (const entry of entries) {
@@ -238,6 +238,37 @@ function resolveConfigFileContributors(
   return out;
 }
 
+function assertContributorNamespacesDoNotCollide(
+  entries: ConfigPluginEntry[],
+  configPath: string,
+): void {
+  const namespacesByGoName = new Map<string, Set<string>>();
+  for (const entry of entries) {
+    const goName = goSubpackageName(entry.namespace);
+    let namespaces = namespacesByGoName.get(goName);
+    if (namespaces === undefined) {
+      namespaces = new Set<string>();
+      namespacesByGoName.set(goName, namespaces);
+    }
+    namespaces.add(entry.namespace);
+  }
+  const collisions = [...namespacesByGoName]
+    .map(([goName, namespaces]) => [goName, [...namespaces].sort()] as const)
+    .filter(([, namespaces]) => namespaces.length > 1)
+    .sort(([left], [right]) => left.localeCompare(right));
+  if (collisions.length === 0) return;
+
+  const details = collisions
+    .map(
+      ([goName, namespaces]) =>
+        `${namespaces.map((namespace) => JSON.stringify(namespace)).join(", ")} all normalize to ${JSON.stringify(goName)}`,
+    )
+    .join("; ");
+  throw new Error(
+    `@ttsc/lint: lint config ${configPath} contributor namespaces collide after Go normalization: ${details}`,
+  );
+}
+
 /**
  * Rejects any tsconfig plugin-entry key that is neither a host framework key
  * nor the single lint-specific `configFile` key. Rule, format, and plugin

package/src/structures/format/ITtscLintFormat.ts

@@ -61,28 +61,32 @@ export interface ITtscLintFormat {
    * Pad the inside of single-line braces with one space. Mirrors Prettier's
    * `bracketSpacing`. `true` (the default) gives `{ x: 1 }`, `import { foo }`;
    * `false` gives `{x: 1}`, `import {foo}`. Applies to object literals, object
-   * destructuring patterns, named imports/exports, and type literals; block,
-   * class, interface, and enum braces are unaffected.
+   * destructuring patterns, named imports/exports, type literals, mapped types,
+   * and import attributes; block, class, interface, and enum braces are
+   * unaffected.
    *
    * @default true
    */
   bracketSpacing?: boolean;
 
   /**
-   * Quoting policy for object-literal property keys. Mirrors Prettier's
-   * `quoteProps`. `"as-needed"` (the default) removes quotes from a key that is
-   * a valid identifier (`{ "foo": 1 }` becomes `{ foo: 1 }`), keeping them on
-   * non-identifier or numeric keys (`"bar-baz"`, `"123"`). `"consistent"` keeps
-   * every key quoted when any one of them requires quotes. `"preserve"` never
-   * changes quoting.
+   * Quoting policy for object-literal keys plus class-method and type-member
+   * names. Mirrors Prettier's `quoteProps`. `"as-needed"` (the default) removes
+   * quotes from a key that is a valid identifier (`{ "foo": 1 }` becomes `{
+   * foo: 1 }`), keeping them on non-identifier or numeric keys (`"bar-baz"`,
+   * `"123"`). `"consistent"` quotes every object-literal identifier key when a
+   * sibling requires quotes. `"preserve"` never changes quoting. ttsc keeps
+   * `"__proto__"` and non-ASCII identifier keys quoted because unquoting can
+   * change runtime semantics or exceed its conservative identifier policy.
    *
    * @default "as-needed"
    */
   quoteProps?: "as-needed" | "consistent" | "preserve";
 
   /**
-   * Trailing-comma policy. Mirrors Prettier's `trailingComma`. The `"none"`
-   * mode disables the rule's edits.
+   * Trailing-comma policy. Mirrors Prettier's `trailingComma`. `"none"` removes
+   * an existing governed trailing comma, `"es5"` keeps it on ES5-level lists,
+   * and `"all"` also keeps it on calls and parameter lists.
    *
    * @default "all"
    */

package/src/structures/rules/ITtscLintRegexpRules.ts

@@ -103,7 +103,8 @@ export interface ITtscLintRegexpRules {
   /**
    * Reject regex flags that the literal does not exercise — `i` on a pattern
    * with no case-variable character, `m` on a pattern with no `^`/`$`
-   * assertion.
+   * assertion. Autofixable: the diagnostic names the dead flags and the fix
+   * deletes exactly those, leaving the live ones in place.
    *
    * Cleans up flag combos that suggest behavior the pattern can never trigger.
    * A character is case-variable wherever it sits, so `/[a-z]/i` keeps its flag
@@ -121,12 +122,18 @@ export interface ITtscLintRegexpRules {
    * (`/a{1}/`), `?` on patterns already matching the empty string
    * (`/(?:a+|b*)?/`), and quantifiers on non-consuming atoms (`/(?:\b)+/`).
    *
+   * Autofixable for the constant-one count, except where the next character
+   * would change the meaning of the deletion: a lazy marker (`/a{1}?/` is
+   * "exactly one", not optional) or a digit (`/\1{1}2/` would fuse into
+   * backreference twelve).
+   *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-useless-quantifier.html
    */
   "regexp/no-useless-quantifier"?: TtscLintRuleSetting;
 
   /**
    * Reject equal min/max quantifiers (`/a{2,2}/`) in favor of `/a{2}/`.
+   * Autofixable.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-useless-two-nums-quantifier.html
    */
@@ -136,42 +143,45 @@ export interface ITtscLintRegexpRules {
    * Reject zero-repeat quantifiers (`/a{0}/`, `/a{0,0}/`) — the atom never
    * matches, so the quantifier is either dead code or a typo for `{1,…}`.
    *
-   * The fix is normally to delete the atom or correct the upper bound.
+   * Diagnostic-only: the correction is to delete the atom or repair the bound,
+   * and which one was meant is not recoverable from the source.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-zero-quantifier.html
    */
   "regexp/no-zero-quantifier"?: TtscLintRuleSetting;
 
   /**
-   * Prefer `\d` over `[0-9]` in regex literals.
+   * Prefer `\d` over `[0-9]` in regex literals. Autofixable.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/prefer-d.html
    */
   "regexp/prefer-d"?: TtscLintRuleSetting;
 
   /**
-   * Prefer `+` over `{1,}` in regex literals.
+   * Prefer `+` over `{1,}` in regex literals. Autofixable.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/prefer-plus-quantifier.html
    */
   "regexp/prefer-plus-quantifier"?: TtscLintRuleSetting;
 
   /**
-   * Prefer `?` over `{0,1}` in regex literals.
+   * Prefer `?` over `{0,1}` in regex literals. Autofixable; a lazy `{0,1}`
+   * correctly becomes `??`.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/prefer-question-quantifier.html
    */
   "regexp/prefer-question-quantifier"?: TtscLintRuleSetting;
 
   /**
-   * Prefer `*` over `{0,}` in regex literals.
+   * Prefer `*` over `{0,}` in regex literals. Autofixable.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/prefer-star-quantifier.html
    */
   "regexp/prefer-star-quantifier"?: TtscLintRuleSetting;
 
   /**
-   * Prefer `\w` over `[A-Za-z0-9_]` in regex literals.
+   * Prefer `\w` over `[A-Za-z0-9_]` in regex literals. Autofixable for both
+   * accepted spellings.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/prefer-w.html
    */
@@ -181,6 +191,9 @@ export interface ITtscLintRegexpRules {
    * Require regex literals to use the `u` or `v` flag, so Unicode-property
    * escapes and surrogate-pair handling stay predictable.
    *
+   * Offers `u` and `v` as editor suggestions rather than an automatic fix: both
+   * satisfy the rule, and both change what the pattern matches.
+   *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/require-unicode-regexp.html
    */
   "regexp/require-unicode-regexp"?: TtscLintRuleSetting;
@@ -191,7 +204,8 @@ export interface ITtscLintRegexpRules {
    * stricter escape rules on top of `u`.
    *
    * Choose this over `require-unicode-regexp` only on engines that ship
-   * ES2024-era regex.
+   * ES2024-era regex. Offers one editor suggestion, which replaces an existing
+   * `u` because the two flags are mutually exclusive.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/require-unicode-sets-regexp.html
    */
@@ -201,7 +215,8 @@ export interface ITtscLintRegexpRules {
    * Require regex flags to appear in canonical alphabetical order (`dgimsuvy`).
    *
    * Stable ordering keeps diffs small and lets readers compare flag sets at a
-   * glance.
+   * glance. Autofixable: a permutation of a flag run cannot change what the
+   * literal matches.
    *
    * @reference https://ota-meshi.github.io/eslint-plugin-regexp/rules/sort-flags.html
    */

package/src/structures/rules/ITtscLintSecurityRules.ts

@@ -67,6 +67,13 @@ export interface ITtscLintSecurityRules {
    * Detect `new Buffer(input)` constructions with non-literal input —
    * historical source of allocation-disclosure bugs.
    *
+   * The three successors — `Buffer.from`, `Buffer.alloc`, `Buffer.allocUnsafe`
+   * — are offered as editor suggestions and none is applied automatically:
+   * which one is correct depends on the argument, which this rule fires
+   * precisely because it cannot read. The rule stays untagged because its
+   * upstream-compatible name match also admits a user-defined constructor named
+   * `Buffer`.
+   *
    * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-new-buffer.md
    */
   "security/detect-new-buffer"?: TtscLintRuleSetting;
@@ -138,6 +145,17 @@ export interface ITtscLintSecurityRules {
    * Tokens, session ids, and key material must use `crypto.randomBytes` (or Web
    * Crypto's `getRandomValues`) instead.
    *
+   * Type-aware via the Checker, which resolves the object at the use site so an
+   * automatic rewrite is never applied to a shadowed binding. Enabling this
+   * rule therefore puts the whole run on the checker path. The diagnostic
+   * itself stays name-based, so it still reports without one.
+   *
+   * The member name alone is rewritten to `randomBytes`. The edit is automatic
+   * when the object is proven to be an import or require of Node `crypto`, and
+   * an editor suggestion otherwise, because a local application object can also
+   * be named `crypto`. That name-based diagnostic surface also keeps the rule
+   * untagged.
+   *
    * @reference https://github.com/eslint-community/eslint-plugin-security/blob/main/docs/rules/detect-pseudoRandomBytes.md
    */
   "security/detect-pseudoRandomBytes"?: TtscLintRuleSetting;

package/src/structures/rules/ITtscLintSolidRules.ts

@@ -31,8 +31,14 @@ export interface ITtscLintSolidRules {
 
   /**
    * Route each Solid export to the correct entry point (`solid-js`,
-   * `solid-js/web`, or `solid-js/store`) and merge duplicate imports from the
-   * same entry.
+   * `solid-js/web`, or `solid-js/store`) and relocate a misrouted one to where
+   * it belongs, joining an existing import from that entry when the file
+   * already has one. The diagnostic names the symbol and its entry point.
+   *
+   * Autofixable. A specifier that stands alone has its declaration's module
+   * specifier rewritten; one with siblings, or one beside a default binding, is
+   * cut out and relocated. A type-only declaration relocates into a type-only
+   * one, never into a value import.
    *
    * @reference https://github.com/solidjs-community/eslint-plugin-solid/blob/main/packages/eslint-plugin-solid/docs/imports.md
    */
@@ -103,6 +109,15 @@ export interface ITtscLintSolidRules {
    * Reject React-style dependency arrays in Solid tracked scopes
    * (`createEffect(() => ..., [deps])`).
    *
+   * Type-aware via the Checker. The tag below claims the array is dead, so the
+   * callee has to be the Solid primitive itself rather than a same-named local
+   * or a shadowing parameter, and only symbol resolution can say that. Enabling
+   * this rule therefore puts the whole run on the checker path.
+   *
+   * Tagged `Unnecessary`: the reported range is the array literal alone, and
+   * Solid tracks dependencies automatically, so deleting it is the whole
+   * resolution and an editor greys it out.
+   *
    * @reference https://github.com/solidjs-community/eslint-plugin-solid/blob/main/packages/eslint-plugin-solid/docs/no-react-deps.md
    */
   "solid/no-react-deps"?: TtscLintRuleSetting;
@@ -111,6 +126,11 @@ export interface ITtscLintSolidRules {
    * Reject React-specific JSX props such as `className` and `htmlFor` — Solid
    * uses `class` and `for`.
    *
+   * The two renames are autofixed by rewriting the name token alone, so the
+   * value survives untouched. The `key` arm stays diagnostic-only: a Solid DOM
+   * element does not consume `key`, so its resolution is a deletion that has to
+   * take the surrounding whitespace with it.
+   *
    * @reference https://github.com/solidjs-community/eslint-plugin-solid/blob/main/packages/eslint-plugin-solid/docs/no-react-specific-props.md
    */
   "solid/no-react-specific-props"?: TtscLintRuleSetting;