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

[mikedelgaudio]

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. [typings-generator] Emit declaration source maps for generated typings #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