@ttsc/lint 0.13.0 → 0.14.0-dev.20260528

package/linthost/rules_ts_no_redundant_type_constituents.go

@@ -0,0 +1,113 @@
+// AST-only baseline of typescript-eslint's `no-redundant-type-constituents`.
+//
+// The rule reports type union/intersection constituents that the type
+// system would absorb — `string | any` collapses to `any`, `T & never`
+// collapses to `never`, `T & unknown` collapses to `T`, and repeated
+// constituents add nothing.
+//
+// Without the Checker the rule can only see what the type node declares,
+// so the baseline covers the cases where one operand is the literal
+// `any` / `unknown` / `never` keyword, plus duplicate operands matched
+// by textual identity. Subset relations such as `string | "foo"` and
+// generic alias resolution still need the type-aware path.
+// https://typescript-eslint.io/rules/no-redundant-type-constituents/
+package linthost
+
+import (
+	"strings"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type noRedundantTypeConstituents struct{}
+
+func (noRedundantTypeConstituents) Name() string {
+	return "typescript/no-redundant-type-constituents"
+}
+func (noRedundantTypeConstituents) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindUnionType, shimast.KindIntersectionType}
+}
+func (noRedundantTypeConstituents) Check(ctx *Context, node *shimast.Node) {
+	types := unionOrIntersectionTypes(node)
+	if len(types) < 2 {
+		return
+	}
+	isUnion := node.Kind == shimast.KindUnionType
+	hasAny := containsKeywordType(types, shimast.KindAnyKeyword)
+	hasUnknown := containsKeywordType(types, shimast.KindUnknownKeyword)
+	hasNever := containsKeywordType(types, shimast.KindNeverKeyword)
+	label := "intersection"
+	if isUnion {
+		label = "union"
+	}
+	seen := map[string]bool{}
+	for _, t := range types {
+		if t == nil {
+			continue
+		}
+		switch {
+		case isUnion && (hasAny || hasUnknown) && t.Kind != shimast.KindAnyKeyword && t.Kind != shimast.KindUnknownKeyword:
+			// `T | any` / `T | unknown` — every non-top constituent is
+			// absorbed. `any` takes precedence in the message because
+			// `any` also subsumes `unknown`.
+			absorbing := "unknown"
+			if hasAny {
+				absorbing = "any"
+			}
+			ctx.Report(t, "Constituent is overridden by `"+absorbing+"` in the surrounding union.")
+		case isUnion && hasNever && t.Kind == shimast.KindNeverKeyword:
+			ctx.Report(t, "`never` is absorbed by the surrounding union.")
+		case !isUnion && hasNever:
+			// `T & never` collapses to `never` for every constituent.
+			ctx.Report(t, "Intersection with `never` collapses to `never`.")
+		case !isUnion && hasUnknown && t.Kind == shimast.KindUnknownKeyword:
+			ctx.Report(t, "`unknown` is absorbed by the surrounding intersection.")
+		}
+		// Duplicate by textual identity — fire on the second occurrence
+		// so the first declaration stays unblamed.
+		key := strings.TrimSpace(nodeText(ctx.File, t))
+		if key == "" {
+			continue
+		}
+		if seen[key] {
+			ctx.Report(t, "Duplicate constituent in "+label+".")
+			continue
+		}
+		seen[key] = true
+	}
+}
+
+// unionOrIntersectionTypes returns the constituent type nodes of a union
+// or intersection type node, or nil for other shapes.
+func unionOrIntersectionTypes(node *shimast.Node) []*shimast.Node {
+	if node == nil {
+		return nil
+	}
+	switch node.Kind {
+	case shimast.KindUnionType:
+		if u := node.AsUnionTypeNode(); u != nil && u.Types != nil {
+			return u.Types.Nodes
+		}
+	case shimast.KindIntersectionType:
+		if i := node.AsIntersectionTypeNode(); i != nil && i.Types != nil {
+			return i.Types.Nodes
+		}
+	}
+	return nil
+}
+
+// containsKeywordType reports whether `types` contains a direct keyword
+// type node of `kind` — `any`, `unknown`, or `never` in type position
+// parse as bare keyword nodes rather than identifiers.
+func containsKeywordType(types []*shimast.Node, kind shimast.Kind) bool {
+	for _, t := range types {
+		if t != nil && t.Kind == kind {
+			return true
+		}
+	}
+	return false
+}
+
+func init() {
+	Register(noRedundantTypeConstituents{})
+}

package/linthost/rules_ts_no_restricted_types.go

@@ -0,0 +1,62 @@
+// AST-only baseline of typescript-eslint's `no-restricted-types`.
+//
+// The upstream rule is fully configurable — users supply a map from
+// banned type name to a custom message and (optionally) a rewrite hint.
+// Without the rule-options plumbing, this baseline ships a fixed
+// default set that covers the five built-in wrapper / global types
+// that almost every team forbids: `Object`, `Function`, `Number`,
+// `String`, and `Boolean`. The dedicated `typescript/no-unsafe-function-type`
+// and `typescript/no-wrapper-object-types` rules also cover some of
+// these, but `no-restricted-types` is the documented umbrella users
+// reach for when they want a single "ban these names" knob.
+//
+// https://typescript-eslint.io/rules/no-restricted-types/
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type noRestrictedTypes struct{}
+
+// noRestrictedTypesDefault is the default set surfaced by the rule
+// when no config is supplied. Each entry pairs the banned identifier
+// with a short, actionable replacement hint.
+var noRestrictedTypesDefault = map[string]string{
+	"Object":   "Use `object` (any non-primitive) or a specific shape like `Record<string, unknown>` instead of `Object`.",
+	"Function": "Declare the specific call signature instead of the unsafe `Function` type.",
+	"Number":   "Use the lowercase primitive `number` instead of the wrapper type `Number`.",
+	"String":   "Use the lowercase primitive `string` instead of the wrapper type `String`.",
+	"Boolean":  "Use the lowercase primitive `boolean` instead of the wrapper type `Boolean`.",
+}
+
+func (noRestrictedTypes) Name() string { return "typescript/no-restricted-types" }
+func (noRestrictedTypes) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindTypeReference}
+}
+func (noRestrictedTypes) Check(ctx *Context, node *shimast.Node) {
+	ref := node.AsTypeReferenceNode()
+	if ref == nil || ref.TypeName == nil {
+		return
+	}
+	name := identifierText(ref.TypeName)
+	if name == "" {
+		return
+	}
+	message, banned := noRestrictedTypesDefault[name]
+	if !banned {
+		return
+	}
+	// Shadow guard: if the user has declared a same-named `type` /
+	// `interface` / `class` at file scope, their identifier is NOT the
+	// global wrapper. Re-use the wrapper-types helper so the two rules
+	// stay consistent about what counts as a shadow.
+	if fileShadowsWrapperName(ctx.File, name) {
+		return
+	}
+	ctx.Report(node, message)
+}
+
+func init() {
+	Register(noRestrictedTypes{})
+}

package/linthost/rules_ts_no_unnecessary_boolean_literal_compare.go

@@ -0,0 +1,129 @@
+// typescript/no-unnecessary-boolean-literal-compare: comparing a value
+// already typed as `boolean` against `true` / `false` adds noise without
+// changing the result — `x === true` evaluates to `x`, `x === false`
+// evaluates to `!x`. The rule narrows to direct comparisons because once
+// the operand carries `null` / `undefined` the literal compare actually
+// strips nullability and is no longer redundant. typescript-eslint:
+// https://typescript-eslint.io/rules/no-unnecessary-boolean-literal-compare/
+//
+// Type-aware. Without a Checker we cannot prove the non-literal side is
+// pure boolean, so Context.Checker == nil short-circuits the rule the
+// same way `no-misused-promises` and `strict-boolean-expressions` do.
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+type noUnnecessaryBooleanLiteralCompare struct{}
+
+func (noUnnecessaryBooleanLiteralCompare) Name() string {
+	return "typescript/no-unnecessary-boolean-literal-compare"
+}
+func (noUnnecessaryBooleanLiteralCompare) NeedsTypeChecker() bool {
+	return true
+}
+func (noUnnecessaryBooleanLiteralCompare) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindBinaryExpression}
+}
+func (noUnnecessaryBooleanLiteralCompare) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	bin := node.AsBinaryExpression()
+	if bin == nil || bin.OperatorToken == nil || bin.Left == nil || bin.Right == nil {
+		return
+	}
+	// Only equality / inequality operators are subject to the rewrite —
+	// `<`, `>`, `&&`, etc. against `true` / `false` are not the same shape.
+	switch bin.OperatorToken.Kind {
+	case shimast.KindEqualsEqualsToken,
+		shimast.KindEqualsEqualsEqualsToken,
+		shimast.KindExclamationEqualsToken,
+		shimast.KindExclamationEqualsEqualsToken:
+	default:
+		return
+	}
+	left := stripParens(bin.Left)
+	right := stripParens(bin.Right)
+	if left == nil || right == nil {
+		return
+	}
+	// Identify which side is the literal and which side is the value.
+	// `true === x` and `x === true` are both reported.
+	var value *shimast.Node
+	switch {
+	case noUnnecessaryBooleanLiteralCompareIsBoolLiteral(left):
+		value = right
+	case noUnnecessaryBooleanLiteralCompareIsBoolLiteral(right):
+		value = left
+	default:
+		return
+	}
+	// Skip when both sides are literals — that's a different code smell
+	// (e.g. `true === false`) that other rules cover.
+	if noUnnecessaryBooleanLiteralCompareIsBoolLiteral(value) {
+		return
+	}
+	t := ctx.Checker.GetTypeAtLocation(value)
+	if t == nil {
+		return
+	}
+	// Only fire when the value side is pure boolean. A `boolean | null`
+	// operand uses the literal compare to strip nullability — leaving
+	// that intact is the explicit carve-out the rule documentation calls
+	// out, so we refuse to flag it.
+	if !noUnnecessaryBooleanLiteralCompareIsPureBoolean(t) {
+		return
+	}
+	ctx.Report(node, "This comparison against a boolean literal is unnecessary; use the value (or its negation) directly.")
+}
+
+// noUnnecessaryBooleanLiteralCompareIsBoolLiteral reports whether node is
+// the literal `true` or `false` keyword.
+func noUnnecessaryBooleanLiteralCompareIsBoolLiteral(node *shimast.Node) bool {
+	if node == nil {
+		return false
+	}
+	return node.Kind == shimast.KindTrueKeyword || node.Kind == shimast.KindFalseKeyword
+}
+
+// noUnnecessaryBooleanLiteralCompareIsPureBoolean reports whether t is a
+// pure boolean type — `boolean`, `true`, `false`, or a union strictly of
+// these. `boolean | null`, `boolean | undefined`, and `any` / `unknown`
+// are explicitly excluded so the literal compare stays in place when it
+// is also stripping nullability or escaping an opaque value.
+func noUnnecessaryBooleanLiteralCompareIsPureBoolean(t *shimchecker.Type) bool {
+	if t == nil {
+		return false
+	}
+	flags := t.Flags()
+	if flags&(shimchecker.TypeFlagsAny|shimchecker.TypeFlagsUnknown|shimchecker.TypeFlagsNever) != 0 {
+		return false
+	}
+	if flags&shimchecker.TypeFlagsUnion != 0 {
+		parts := t.Types()
+		if len(parts) == 0 {
+			return false
+		}
+		for _, part := range parts {
+			if part == nil {
+				return false
+			}
+			pf := part.Flags()
+			if pf&(shimchecker.TypeFlagsNull|shimchecker.TypeFlagsUndefined) != 0 {
+				return false
+			}
+			if pf&shimchecker.TypeFlagsBooleanLike == 0 {
+				return false
+			}
+		}
+		return true
+	}
+	return flags&shimchecker.TypeFlagsBooleanLike != 0
+}
+
+func init() {
+	Register(noUnnecessaryBooleanLiteralCompare{})
+}

package/linthost/rules_ts_no_unnecessary_condition.go

@@ -0,0 +1,250 @@
+// typescript/no-unnecessary-condition: a conditional whose test expression
+// has a type that can only ever evaluate to one truthiness — `if ({})`,
+// `if (null)`, `while ("")` — branches that never run (or always run) and
+// almost always reflect a logic error. The runtime takes the static
+// answer that the type system already had, so naming the constant intent
+// explicitly (`if (true)`, deleting the dead arm, or widening the type)
+// is the fix. typescript-eslint:
+// https://typescript-eslint.io/rules/no-unnecessary-condition/
+//
+// Type-aware. Without a Checker the rule cannot tell `null` apart from
+// `string | null`, so Context.Checker == nil short-circuits each Check to
+// a no-op the way `strict-boolean-expressions` and `no-misused-promises`
+// do.
+package linthost
+
+import (
+	"strings"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+// truthState is the lattice value the rule tracks for each constituent of
+// the test expression's static type.
+//
+//   - truthStateUnknowable — `any` / `unknown` / `never`, or any other
+//     constituent we cannot prove either truthy or falsy. Treated as
+//     "abandon the analysis" — if any constituent is unknowable the
+//     overall result is unknowable and the rule does not fire.
+//   - truthStateAlwaysTruthy / truthStateAlwaysFalsy — a constituent
+//     whose runtime truthiness is fixed.
+//   - truthStateMixed — a constituent that could be either (plain
+//     `string`, plain `number`, plain `boolean`, enum, etc.). Reaching
+//     "mixed" disqualifies the whole expression from the rule.
+type truthState int
+
+const (
+	truthStateUnknowable truthState = iota
+	truthStateAlwaysTruthy
+	truthStateAlwaysFalsy
+	truthStateMixed
+)
+
+type noUnnecessaryCondition struct{}
+
+func (noUnnecessaryCondition) Name() string { return "typescript/no-unnecessary-condition" }
+func (noUnnecessaryCondition) NeedsTypeChecker() bool {
+	return true
+}
+func (noUnnecessaryCondition) Visits() []shimast.Kind {
+	return []shimast.Kind{
+		shimast.KindIfStatement,
+		shimast.KindWhileStatement,
+		shimast.KindDoStatement,
+		shimast.KindForStatement,
+		shimast.KindConditionalExpression,
+		shimast.KindBinaryExpression,
+		shimast.KindPrefixUnaryExpression,
+	}
+}
+func (noUnnecessaryCondition) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	switch node.Kind {
+	case shimast.KindIfStatement:
+		if stmt := node.AsIfStatement(); stmt != nil {
+			noUnnecessaryConditionReport(ctx, stmt.Expression)
+		}
+	case shimast.KindWhileStatement:
+		if stmt := node.AsWhileStatement(); stmt != nil {
+			noUnnecessaryConditionReport(ctx, stmt.Expression)
+		}
+	case shimast.KindDoStatement:
+		if stmt := node.AsDoStatement(); stmt != nil {
+			noUnnecessaryConditionReport(ctx, stmt.Expression)
+		}
+	case shimast.KindForStatement:
+		if stmt := node.AsForStatement(); stmt != nil {
+			noUnnecessaryConditionReport(ctx, stmt.Condition)
+		}
+	case shimast.KindConditionalExpression:
+		if expr := node.AsConditionalExpression(); expr != nil {
+			noUnnecessaryConditionReport(ctx, expr.Condition)
+		}
+	case shimast.KindPrefixUnaryExpression:
+		expr := node.AsPrefixUnaryExpression()
+		if expr != nil && expr.Operator == shimast.KindExclamationToken {
+			noUnnecessaryConditionReport(ctx, expr.Operand)
+		}
+	case shimast.KindBinaryExpression:
+		bin := node.AsBinaryExpression()
+		if bin == nil || bin.OperatorToken == nil {
+			return
+		}
+		// Only `&&` / `||` test their left operand for truthiness. `??`
+		// short-circuits on nullish, not on falsy, and is intentionally
+		// out of scope — its dedicated rule
+		// `no-unnecessary-nullish-coalescing` covers that pattern.
+		switch bin.OperatorToken.Kind {
+		case shimast.KindAmpersandAmpersandToken, shimast.KindBarBarToken:
+			noUnnecessaryConditionReport(ctx, bin.Left)
+		}
+	}
+}
+
+// noUnnecessaryConditionReport flags `expr` when its static type proves
+// the runtime truthiness is fixed. The descent through `&&` / `||`
+// mirrors `strict-boolean-expressions`: the outer BinaryExpression visit
+// only checks Left, so the recursion here picks up Right too. Wrapping
+// parens are skipped via stripParens.
+func noUnnecessaryConditionReport(ctx *Context, expr *shimast.Node) {
+	if expr == nil {
+		return
+	}
+	expr = stripParens(expr)
+	if expr == nil {
+		return
+	}
+	if expr.Kind == shimast.KindBinaryExpression {
+		bin := expr.AsBinaryExpression()
+		if bin != nil && bin.OperatorToken != nil {
+			switch bin.OperatorToken.Kind {
+			case shimast.KindAmpersandAmpersandToken, shimast.KindBarBarToken:
+				noUnnecessaryConditionReport(ctx, bin.Left)
+				noUnnecessaryConditionReport(ctx, bin.Right)
+				return
+			}
+		}
+	}
+	t := ctx.Checker.GetTypeAtLocation(expr)
+	if t == nil {
+		return
+	}
+	switch noUnnecessaryConditionEvaluate(ctx.Checker, t) {
+	case truthStateAlwaysTruthy:
+		ctx.Report(expr, "Unnecessary conditional, value is always truthy.")
+	case truthStateAlwaysFalsy:
+		ctx.Report(expr, "Unnecessary conditional, value is always falsy.")
+	}
+}
+
+// noUnnecessaryConditionEvaluate folds a type into a single truthState by
+// combining each constituent's state under union semantics: any
+// unknowable constituent forces unknowable, otherwise the combined state
+// is the unique truthy / falsy / mixed reading of every constituent.
+// Intersections are not analyzed structurally — they bail to unknowable
+// because the Checker may resolve them into shapes (e.g. branded
+// primitives) the rule cannot reason about safely.
+func noUnnecessaryConditionEvaluate(checker *shimchecker.Checker, t *shimchecker.Type) truthState {
+	if checker == nil || t == nil {
+		return truthStateUnknowable
+	}
+	flags := t.Flags()
+	if flags&(shimchecker.TypeFlagsAny|shimchecker.TypeFlagsUnknown|shimchecker.TypeFlagsNever) != 0 {
+		return truthStateUnknowable
+	}
+	if flags&shimchecker.TypeFlagsIntersection != 0 {
+		// Intersections such as `Foo & { brand: "x" }` carry semantics the
+		// rule cannot prove without a deeper Checker walk, so we keep the
+		// conservative bail.
+		return truthStateUnknowable
+	}
+	if flags&shimchecker.TypeFlagsUnion != 0 {
+		parts := t.Types()
+		if len(parts) == 0 {
+			return truthStateUnknowable
+		}
+		combined := truthState(-1)
+		for _, part := range parts {
+			if part == nil {
+				return truthStateUnknowable
+			}
+			state := noUnnecessaryConditionEvaluate(checker, part)
+			if state == truthStateUnknowable || state == truthStateMixed {
+				// A union with even one constituent we can't pin breaks the
+				// "always X" guarantee — bail.
+				return state
+			}
+			if combined == truthState(-1) {
+				combined = state
+				continue
+			}
+			if combined != state {
+				// `string | null` has both a falsy ("") and a always-falsy
+				// (null) outcome that disagree across constituents — fall
+				// back to mixed so the rule stays silent.
+				return truthStateMixed
+			}
+		}
+		if combined == truthState(-1) {
+			return truthStateUnknowable
+		}
+		return combined
+	}
+	// Atomic types.
+	if flags&(shimchecker.TypeFlagsNull|shimchecker.TypeFlagsUndefined|shimchecker.TypeFlagsVoid) != 0 {
+		return truthStateAlwaysFalsy
+	}
+	if flags&shimchecker.TypeFlagsBooleanLiteral != 0 {
+		text := checker.TypeToString(t)
+		if strings.TrimSpace(text) == "false" {
+			return truthStateAlwaysFalsy
+		}
+		if strings.TrimSpace(text) == "true" {
+			return truthStateAlwaysTruthy
+		}
+		return truthStateUnknowable
+	}
+	if flags&shimchecker.TypeFlagsStringLiteral != 0 {
+		text := strings.TrimSpace(checker.TypeToString(t))
+		if text == `""` || text == `''` {
+			return truthStateAlwaysFalsy
+		}
+		return truthStateAlwaysTruthy
+	}
+	if flags&shimchecker.TypeFlagsNumberLiteral != 0 {
+		text := strings.TrimSpace(checker.TypeToString(t))
+		// `0`, `0.0`, `-0` all stringify as `0`; everything else is truthy.
+		// `NaN` is not representable as a literal type, so it cannot reach
+		// this branch.
+		if text == "0" {
+			return truthStateAlwaysFalsy
+		}
+		return truthStateAlwaysTruthy
+	}
+	if flags&shimchecker.TypeFlagsBigIntLiteral != 0 {
+		text := strings.TrimSpace(checker.TypeToString(t))
+		if text == "0n" {
+			return truthStateAlwaysFalsy
+		}
+		return truthStateAlwaysTruthy
+	}
+	if flags&shimchecker.TypeFlagsObject != 0 {
+		// A non-nullable object value is always truthy. `{}`, arrays,
+		// class instances, functions, and structural records all share
+		// this contract; only `null` / `undefined` make an object position
+		// falsy and those flags route to the always-falsy branch above.
+		return truthStateAlwaysTruthy
+	}
+	// Plain `string` / `number` / `boolean` / `bigint` / enum / symbol /
+	// type parameter / index / template literal — every one of these can
+	// hold both truthy and falsy values (or escapes static reasoning), so
+	// the rule must stay silent.
+	return truthStateMixed
+}
+
+func init() {
+	Register(noUnnecessaryCondition{})
+}

package/linthost/rules_ts_no_unnecessary_qualifier.go

@@ -0,0 +1,118 @@
+// typescript/no-unnecessary-qualifier: a qualified reference like
+// `Foo.Bar` written inside `namespace Foo { ... }` (or `enum Foo { ...,
+// X = Foo.Y, ... }`) names the same scope the reference is already in.
+// The qualifier adds no information; dropping `Foo.` leaves the
+// identical binding lookup. typescript-eslint:
+// https://typescript-eslint.io/rules/no-unnecessary-qualifier/
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// noUnnecessaryQualifier inspects every two-segment qualified reference
+// whose head is a plain identifier — `QualifiedName` shows up in type
+// position (`Foo.Bar` inside a type annotation) and
+// `PropertyAccessExpression` shows up in value position. The check is
+// AST-only: it walks the ancestor chain for an enclosing `namespace
+// <head> { ... }` or `enum <head> { ... }` declaration and reports when
+// one is found. The rule deliberately does not consult the Checker
+// because the upstream rule operates on lexical scope identity, which
+// the AST already encodes via declaration ancestry.
+type noUnnecessaryQualifier struct{}
+
+func (noUnnecessaryQualifier) Name() string {
+	return "typescript/no-unnecessary-qualifier"
+}
+func (noUnnecessaryQualifier) Visits() []shimast.Kind {
+	return []shimast.Kind{
+		shimast.KindQualifiedName,
+		shimast.KindPropertyAccessExpression,
+	}
+}
+func (noUnnecessaryQualifier) Check(ctx *Context, node *shimast.Node) {
+	head := noUnnecessaryQualifierHead(node)
+	if head == "" {
+		return
+	}
+	if !noUnnecessaryQualifierHasEnclosingScope(node, head) {
+		return
+	}
+	ctx.Report(node, "Qualifier `"+head+"` is the enclosing namespace or enum — drop the qualifier.")
+}
+
+// noUnnecessaryQualifierHead returns the LHS identifier text when the
+// node is a two-segment qualified reference (`A.B`) whose head is a
+// plain identifier. Returns "" for nested chains (`A.B.C`), computed
+// accesses, or non-identifier heads — those shapes don't match the
+// "qualifier names the enclosing scope" pattern.
+func noUnnecessaryQualifierHead(node *shimast.Node) string {
+	if node == nil {
+		return ""
+	}
+	switch node.Kind {
+	case shimast.KindQualifiedName:
+		qn := node.AsQualifiedName()
+		if qn == nil || qn.Left == nil {
+			return ""
+		}
+		if qn.Left.Kind != shimast.KindIdentifier {
+			return ""
+		}
+		return identifierText(qn.Left)
+	case shimast.KindPropertyAccessExpression:
+		pa := node.AsPropertyAccessExpression()
+		if pa == nil || pa.Expression == nil || pa.Name() == nil {
+			return ""
+		}
+		// Optional chains (`Foo?.Bar`) aren't redundant in the same
+		// sense — the `?.` changes runtime behavior, so leave them be.
+		if pa.QuestionDotToken != nil {
+			return ""
+		}
+		if pa.Expression.Kind != shimast.KindIdentifier {
+			return ""
+		}
+		return identifierText(pa.Expression)
+	}
+	return ""
+}
+
+// noUnnecessaryQualifierHasEnclosingScope reports whether `node`
+// appears inside a `namespace <head> { ... }` or `enum <head> { ... }`
+// declaration body. The walk climbs `Parent` links until it finds a
+// matching block or hits the SourceFile root.
+func noUnnecessaryQualifierHasEnclosingScope(node *shimast.Node, head string) bool {
+	for cur := node.Parent; cur != nil; cur = cur.Parent {
+		switch cur.Kind {
+		case shimast.KindModuleDeclaration:
+			decl := cur.AsModuleDeclaration()
+			if decl == nil || decl.Name() == nil {
+				continue
+			}
+			// `declare module "fs"` carries a string-literal name and
+			// does not bind an identifier in the surrounding scope —
+			// skip those entirely. The rule only fires when the head
+			// matches the enclosing namespace's identifier name.
+			if decl.Name().Kind != shimast.KindIdentifier {
+				continue
+			}
+			if identifierText(decl.Name()) == head {
+				return true
+			}
+		case shimast.KindEnumDeclaration:
+			decl := cur.AsEnumDeclaration()
+			if decl == nil || decl.Name() == nil {
+				continue
+			}
+			if identifierText(decl.Name()) == head {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func init() {
+	Register(noUnnecessaryQualifier{})
+}