Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

[heft-sass-plugin] Emit declaration source maps so "go to definition" resolves to the stylesheet

オープン
  • 何か問題がありますか？
#5,908 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
45/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
静か
技術スタック
sass, typescript
領域
build-system, tooling

調査の方向性

Start in the heft-sass-plugin's SassProcessor, where the plugin composes and writes its .d.ts, and review how postcss-modules and the Sass source map can provide class positions. Consider the relationship to typings-generator's serializeDeclarationMap from #5907 and the proposed opt-in behavior. Done means tsserver navigation reaches the declaring rule, including classes in partials and @media blocks.

索引モデルが issue の本文から書いたものです。

説明

Summary

Typings generated by @rushstack/heft-sass-plugin are written into a folder that is merged back
into the source tree via the TypeScript rootDirs compiler option, so the language service only
ever sees the generated .d.ts. The stylesheet that actually declares the class is invisible to it.

The effect is that "go to definition" on a CSS module class, or on the import specifier, navigates
to the generated declaration rather than to the file the developer can edit:

import * as styles from './HeaderBar.module.scss';

styles.headerBar; // -> temp/sass-ts/HeaderBar.module.scss.d.ts, not src/HeaderBar.module.scss

Because the generated file is a build artifact, landing there is a dead end.

This is the same underlying problem as #5906, which covers localization typings, but the Sass plugin
does not share the code path: it composes and writes its own .d.ts in SassProcessor rather than
going through @rushstack/typings-generator.

Repro steps

  1. Configure a project that uses @rushstack/heft-sass-plugin to emit typings into a folder listed
    in rootDirs.
  2. Import a .module.scss from a .ts file and reference one of its classes.
  3. Alt-click (or F12) the class, or the import specifier.

Expected result: the editor opens the .scss at the rule that declares the class.

Actual result: the editor opens the generated .module.scss.d.ts.

Details

TypeScript already solves this generally with declaration source maps (.d.ts.map): when a .d.ts
has a corresponding map pointing at real source, tsserver transparently redirects "go to
definition" there. The Sass plugin does not emit one, so there is nothing to redirect with.

The interesting part is obtaining accurate positions. Searching the stylesheet text for the class
name is unreliable in two common cases:

  • A class declared in an @imported partial does not appear in the entry file at all.
  • A class restated inside a @media or theme block can be matched instead of its primary rule.

Both are avoidable, because Sass can produce a source map for the compilation. A PostCSS plugin
registered before postcss-modules (which rewrites class names) can record where each class
selector appears in the compiled CSS, and that position maps back through the Sass source map to the
original stylesheet. Because the lookup is done in compiled-CSS order, the top-level rule is
naturally preferred over a later restatement, and classes from partials resolve into the partial.

I have prototyped this and confirmed with a live tsserver that navigation resolves to the correct
rule, including the partial and @media cases.

Two design points I would like guidance on before sending a PR:

  1. Where the shared pieces should live. #5907 adds serializeDeclarationMap to
    @rushstack/typings-generator. The Sass plugin additionally needs to decode a source map to do
    the position lookup. Putting the decoder alongside the encoder in typings-generator would keep
    one implementation, but heft-sass-plugin does not currently depend on that package.
  2. Whether the Sass-specific helpers should be exported. Other Sass typings generators exist
    outside this repo that would otherwise reimplement the same PostCSS-plus-source-map chain.
    Exporting them would let those consumers reuse this rather than duplicate it.

Requesting the Sass source map has a cost, so the feature would be opt-in and off by default.

Standard questions

Question Answer
Package name: @rushstack/heft-sass-plugin
Package version? 0.15.24
Operating system? Linux (also reproduced on Mac)
Would you consider contributing a PR? Yes
Node.js version (node -v)? 22.16.0
主要言語
TypeScript
スター
6.5k
フォーク
708
平均マージ
4日 7時間
マージ済み PR（30日）
61

環境構築

このプロジェクトの環境構築ファイルはまだ確認していません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

microsoft/rushstack のほかの issue

microsoft/rushstack の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。