@ttsc/lint 0.15.2 → 0.15.4

package/README.md

@@ -1132,6 +1132,8 @@ export default {
 
 Contributor rules emit autofixes the same way built-ins do, call `ctx.ReportFix(node, message, edits...)` or `ctx.ReportRangeFix(pos, end, message, edits...)`. The `rule/astutil` package re-exports the byte-range helpers built-ins use (`NodeText`, `KeywordStart`, `FindKeyword`, `TokenRange`). See the [contributor autofix path](https://ttsc.dev/docs/development/walkthroughs/lint#the-contributor-autofix-path) section for the full contract and an example.
 
+Contributor rules run on declaration files (`.d.ts`) by default. The engine skips its own value-level rules there — executable grammar cannot appear in a declaration file — but it cannot infer a third-party rule's shape, so contributors keep the conservative default. A rule that only inspects executable code can implement the optional `rule.DeclarationFileRule` marker (`VisitsDeclarationFiles() bool { return false }`) to get the same skip and save the dispatch on declaration-heavy projects.
+
 ## Sponsors
 
 [![Sponsors](https://raw.githubusercontent.com/samchon/sponsor-images/refs/heads/master/public/circle.svg)](https://github.com/sponsors/samchon)

package/linthost/contrib_adapter.go

@@ -75,6 +75,18 @@ func (a contributorAdapter) NeedsTypeChecker() bool {
   return true
 }
 
+// VisitsDeclarationFiles keeps contributor rules running on declaration
+// files unless the contributor opts out through the public
+// `rule.DeclarationFileRule` marker. Same conservative-default reasoning
+// as NeedsTypeChecker: the host cannot infer a third-party rule's grammar
+// shape, and a wrong skip silently loses findings.
+func (a contributorAdapter) VisitsDeclarationFiles() bool {
+  if dr, ok := a.inner.(rule.DeclarationFileRule); ok {
+    return dr.VisitsDeclarationFiles()
+  }
+  return true
+}
+
 // formatContributorAdapter is the FormatRule-tagged variant of
 // contributorAdapter. Wrapping the lint-only adapter (rather than
 // duplicating its method set) keeps the marker addition trivial and

package/linthost/declaration_rules.go

@@ -0,0 +1,173 @@
+// Declaration-file dispatch policy.
+//
+// The engine skips rules on `.d.ts` (and other declaration) sources unless
+// the rule is known to produce legitimate findings there. Declaration files
+// carry no executable code, so most value-level rules can never fire on one;
+// walking them anyway is pure dispatch overhead on declaration-heavy
+// projects (see issue #177).
+//
+// Three ways a rule participates in declaration files:
+//
+//   - FormatRule markers: every format rule visits declaration files —
+//     `ttsc format` / `ttsc fix` must keep formatting hand-written `.d.ts`
+//     on the same boundary as other sources.
+//   - declarationFileRule: the optional interface a rule (built-in or
+//     contributor adapter) implements to answer for itself.
+//   - declarationFileRuleNames: the curated allowlist below for built-in
+//     rules, kept in one place so the whole audit stays reviewable.
+//
+// Audit principle for the allowlist: a rule is listed when its grammar
+// shape occurs in declaration files under normal usage — type syntax,
+// signatures, import/export forms, enums and their constant initializers,
+// comments/JSDoc, identifier naming, or per-file metrics. Rules that need
+// executable statements, expressions outside ambient-legal constant
+// expressions, or runtime semantics (promises, DOM, JSX, test frameworks)
+// are deliberately absent. When in doubt the rule is listed: a wrongly
+// listed rule only costs dispatch time, while a wrongly skipped rule
+// silently loses findings.
+package linthost
+
+// declarationFileRule marks rules that want to fire on declaration-file
+// (`.d.ts`, `.d.mts`, `.d.cts`) inputs. Rules that neither implement this
+// interface (returning true) nor appear in declarationFileRuleNames nor
+// carry the FormatRule marker are skipped on every
+// `file.IsDeclarationFile == true` source.
+type declarationFileRule interface {
+  VisitsDeclarationFiles() bool
+}
+
+// ruleVisitsDeclarationFiles reports whether the engine dispatches `r` on
+// declaration-file sources.
+func ruleVisitsDeclarationFiles(r Rule) bool {
+  if isFormatRule(r) {
+    return true
+  }
+  if dr, ok := r.(declarationFileRule); ok {
+    return dr.VisitsDeclarationFiles()
+  }
+  return declarationFileRuleNames[r.Name()]
+}
+
+// declarationFileRuleNames is the audited allowlist of built-in rules whose
+// grammar shapes occur in declaration files. Grouped by namespace; each
+// group states the shape that justifies it. A name listed here must exist
+// in the registry — the registry-parity test pins that.
+var declarationFileRuleNames = map[string]bool{
+  // JSDoc lives on declarations; declaration files are its prime habitat.
+  "jsdoc/check-tag-names":              true,
+  "jsdoc/check-values":                 true,
+  "jsdoc/empty-tags":                   true,
+  "jsdoc/no-types":                     true,
+  "jsdoc/reject-any-type":              true,
+  "jsdoc/reject-function-type":         true,
+  "jsdoc/require-description":          true,
+  "jsdoc/require-param-description":    true,
+  "jsdoc/require-param-name":           true,
+  "jsdoc/require-property-description": true,
+  "jsdoc/require-property-name":        true,
+  "jsdoc/require-returns-description":  true,
+  "jsdoc/tsdoc-syntax":                 true,
+
+  // Import-graph boundaries: declaration files import and re-export, and
+  // an architectural boundary holds for hand-written `.d.ts` too.
+  "boundaries/dependencies":  true,
+  "boundaries/element-types": true,
+  "boundaries/entry-point":   true,
+  "boundaries/external":      true,
+  "boundaries/no-private":    true,
+  "boundaries/no-unknown":    true,
+
+  // Core rules over shapes a declaration file contains: identifier
+  // naming, import/export forms, accessor and class-member signatures,
+  // per-file metrics, user-configured selectors, and the constant
+  // expressions enum initializers allow (bitwise flags, numeric
+  // literals).
+  "camelcase":                 true,
+  "grouped-accessor-pairs":    true,
+  "id-length":                 true,
+  "max-classes-per-file":      true,
+  "max-lines":                 true,
+  "max-params":                true,
+  "no-bitwise":                true,
+  "no-dupe-class-members":     true,
+  "no-duplicate-imports":      true,
+  "no-empty-named-blocks":     true,
+  "no-irregular-whitespace":   true,
+  "no-loss-of-precision":      true,
+  "no-magic-numbers":          true,
+  "no-mixed-operators":        true,
+  "no-redeclare":              true,
+  "no-restricted-imports":     true,
+  "no-restricted-syntax":      true,
+  "no-shadow":                 true,
+  "no-shadow-restricted-names": true,
+  "no-useless-computed-key":   true,
+  "no-useless-rename":         true,
+  "sort-imports":              true,
+
+  // typescript/* rules over type syntax, signatures, enums, import/export
+  // type forms, comments, and declaration merging.
+  "typescript/adjacent-overload-signatures":      true,
+  "typescript/array-type":                        true,
+  "typescript/ban-ts-comment":                    true,
+  "typescript/ban-tslint-comment":                true,
+  "typescript/class-literal-property-style":      true,
+  "typescript/consistent-indexed-object-style":   true,
+  "typescript/consistent-type-definitions":       true,
+  "typescript/consistent-type-exports":           true,
+  "typescript/consistent-type-imports":           true,
+  "typescript/explicit-function-return-type":     true,
+  "typescript/explicit-member-accessibility":     true,
+  "typescript/method-signature-style":            true,
+  "typescript/no-deprecated":                     true,
+  "typescript/no-duplicate-enum-values":          true,
+  "typescript/no-empty-interface":                true,
+  "typescript/no-empty-object-type":              true,
+  "typescript/no-explicit-any":                   true,
+  "typescript/no-extraneous-class":               true,
+  "typescript/no-import-type-side-effects":       true,
+  "typescript/no-invalid-void-type":              true,
+  "typescript/no-magic-numbers":                  true,
+  "typescript/no-misused-new":                    true,
+  "typescript/no-mixed-enums":                    true,
+  "typescript/no-redundant-type-constituents":    true,
+  "typescript/no-require-imports":                true,
+  "typescript/no-restricted-types":               true,
+  "typescript/no-unnecessary-qualifier":          true,
+  "typescript/no-unnecessary-template-expression": true,
+  "typescript/no-unnecessary-type-arguments":     true,
+  "typescript/no-unnecessary-type-constraint":    true,
+  "typescript/no-unsafe-declaration-merging":     true,
+  "typescript/no-unsafe-function-type":           true,
+  "typescript/no-wrapper-object-types":           true,
+  "typescript/prefer-enum-initializers":          true,
+  "typescript/prefer-function-type":              true,
+  "typescript/prefer-literal-enum-member":        true,
+  "typescript/prefer-namespace-keyword":          true,
+  "typescript/prefer-return-this-type":           true,
+  "typescript/related-getter-setter-pairs":       true,
+  "typescript/sort-type-constituents":            true,
+  "typescript/triple-slash-reference":            true,
+
+  // functional/* rules that police type shapes (not statements).
+  "functional/no-mixed-types":               true,
+  "functional/no-return-void":               true,
+  "functional/prefer-immutable-types":       true,
+  "functional/prefer-property-signatures":   true,
+  "functional/prefer-readonly-type":         true,
+  "functional/readonly-type":                true,
+  "functional/type-declaration-immutability": true,
+
+  // unicorn/* rules over file names, comments, identifier naming, and
+  // the numeric literals that appear in enum initializers and literal
+  // types.
+  "unicorn/empty-brace-spaces":          true,
+  "unicorn/expiring-todo-comments":      true,
+  "unicorn/filename-case":               true,
+  "unicorn/no-abusive-eslint-disable":   true,
+  "unicorn/no-empty-file":               true,
+  "unicorn/no-keyword-prefix":           true,
+  "unicorn/number-literal-case":         true,
+  "unicorn/numeric-separators-style":    true,
+  "unicorn/prevent-abbreviations":       true,
+}

package/linthost/engine.go

@@ -534,6 +534,12 @@ func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker)
   // Context for every (node, rule) pair, which on a large program meant
   // millions of short-lived heap allocations and the GC pressure they
   // carry. Rules never mutate their Context, so reuse is safe.
+  //
+  // Declaration files only bind rules that opt into them (see
+  // declaration_rules.go): value-level rules can never fire on a `.d.ts`,
+  // so dispatching to them is pure overhead on declaration-heavy trees.
+  declarationFile := file.IsDeclarationFile
+  bound := 0
   byKind := make([][]boundRule, len(e.rules))
   ctxByRule := make(map[string]*Context, len(e.enabled))
   for kind, rules := range e.rules {
@@ -541,6 +547,9 @@ func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker)
       continue
     }
     for _, rule := range rules {
+      if declarationFile && !ruleVisitsDeclarationFiles(rule) {
+        continue
+      }
       name := rule.Name()
       ctx, built := ctxByRule[name]
       if !built {
@@ -563,6 +572,7 @@ func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker)
         continue
       }
       byKind[kind] = append(byKind[kind], boundRule{rule: rule, ctx: ctx})
+      bound++
     }
   }
 
@@ -572,23 +582,30 @@ func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker)
   // the heap on every invocation; converting to a method value with a
   // cached function field removes that allocation from the hot path —
   // ~38 % of pre-Opt-4 CPU was in the inner ForEachChild closure.
-  w := &lintFileWalker{byKind: byKind, collect: collect}
-  w.childCB = w.visitChild
-
-  // SourceFile dispatches into its statement list directly; we walk
-  // statements explicitly so the file node itself can be inspected by
-  // rules (e.g., `ban-ts-comment` reads CommentDirectives off the
-  // SourceFile).
-  if k := int(shimast.KindSourceFile); k >= 0 && k < len(byKind) {
-    for _, bound := range byKind[k] {
-      runRuleCheck(bound.rule, bound.ctx, file.AsNode(), collect)
+  //
+  // With no bound rules at all (every active rule was filtered out, e.g.
+  // a declaration file where nothing opted in) the walk cannot produce a
+  // finding, so it is skipped entirely; inline directives are still
+  // parsed below so unknown-directive warnings stay file-complete.
+  if bound != 0 {
+    w := &lintFileWalker{byKind: byKind, collect: collect}
+    w.childCB = w.visitChild
+
+    // SourceFile dispatches into its statement list directly; we walk
+    // statements explicitly so the file node itself can be inspected by
+    // rules (e.g., `ban-ts-comment` reads CommentDirectives off the
+    // SourceFile).
+    if k := int(shimast.KindSourceFile); k >= 0 && k < len(byKind) {
+      for _, bound := range byKind[k] {
+        runRuleCheck(bound.rule, bound.ctx, file.AsNode(), collect)
+      }
     }
-  }
 
-  statements := file.Statements
-  if statements != nil {
-    for _, stmt := range statements.Nodes {
-      w.walk(stmt)
+    statements := file.Statements
+    if statements != nil {
+      for _, stmt := range statements.Nodes {
+        w.walk(stmt)
+      }
     }
   }
   directives := parseLintInlineDirectives(file)

package/linthost/lsp.go

@@ -502,8 +502,11 @@ func lspFormatBuffer(content string, opts *lspCommandOptions) (*lspWorkspaceEdit
 
   text := content
   converged := false
+  // The tsgo parser asserts on normalized (forward-slash) absolute paths;
+  // `target` comes from filepath.Abs and carries backslashes on Windows.
+  parseName := filepath.ToSlash(target)
   for pass := 0; pass < maxFormatPasses; pass++ {
-    file := shimparser.ParseSourceFile(shimast.SourceFileParseOptions{FileName: target}, text, scriptKind)
+    file := shimparser.ParseSourceFile(shimast.SourceFileParseOptions{FileName: parseName}, text, scriptKind)
     if file == nil {
       // Match the disk path: a buffer we can't parse is a benign no-op, not a
       // hard error — don't fight the editor's own diagnostics on a dirty buffer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/lint",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "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.20260421.2",
+    "@typescript/native-preview": "7.0.0-dev.20260615.1",
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
-    "ttsc": "0.15.2"
+    "ttsc": "0.15.4"
   },
   "repository": {
     "type": "git",

package/rule/rule.go

@@ -97,6 +97,21 @@ type FormatRule interface {
   IsFormat() bool
 }
 
+// DeclarationFileRule is an optional marker contributors implement to
+// control whether their rule runs on declaration-file inputs (`.d.ts`,
+// `.d.mts`, `.d.cts`). The engine skips most built-in rules on declaration
+// files because value-level grammar cannot appear there; contributor rules
+// keep the conservative default — they DO run on declaration files — since
+// the host cannot infer a third-party rule's shape (mirror of the implicit
+// checker default). A contributor whose rule inspects executable code only
+// can implement this with `return false` to skip declaration files and
+// save the dispatch on declaration-heavy projects; returning `true` is
+// equivalent to not implementing the interface at all.
+type DeclarationFileRule interface {
+  Rule
+  VisitsDeclarationFiles() bool
+}
+
 // Reporter is the engine-supplied callback that records a finding. The
 // host implements this and passes it to `NewContext` when invoking a
 // contributor rule.