Skip to content

Enhance sourceMapIncludeSources option #2713

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ntkme wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Enhance sourceMapIncludeSources option #2713

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
656fd94
Use the canonical URL instead of a data: URL for sourceMapUrl fallback
ntkme Dec 26, 2025
8919079
Enhance sourceMapIncludeSources option
ntkme Dec 27, 2025
290c3d5
Emit deprecation
ntkme Jan 29, 2026
fb7157d
Add sourceMapUrlOrNull
ntkme Feb 12, 2026
83af137
Add comments
ntkme May 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions lib/sass.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import 'src/import_cache.dart';
import 'src/importer.dart';
import 'src/importer/utils.dart';
import 'src/logger.dart';
import 'src/source_map_include_sources.dart';
import 'src/syntax.dart';
import 'src/util/nullable.dart';
import 'src/visitor/serialize.dart';
Expand All @@ -26,6 +27,7 @@ export 'src/deprecation.dart';
export 'src/exception.dart' show SassException;
export 'src/importer.dart';
export 'src/logger.dart' show Logger;
export 'src/source_map_include_sources.dart';
export 'src/syntax.dart';
export 'src/value.dart'
hide
Expand Down Expand Up @@ -90,6 +92,9 @@ export 'src/evaluation_context.dart' show warn;
///
/// [`source_maps`]: https://pub.dartlang.org/packages/source_maps
///
/// The [sourceMapIncludeSources] parameter controls the ways in which the
/// compiler can choose to include source contents in the source map.
///
/// If [charset] is `true`, this will include a `@charset` declaration or a
/// UTF-8 [byte-order mark][] if the stylesheet contains any non-ASCII
/// characters. Otherwise, it will never include a `@charset` declaration or a
Expand All @@ -112,6 +117,8 @@ CompileResult compileToResult(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.always,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand All @@ -130,6 +137,7 @@ CompileResult compileToResult(
quietDeps: quietDeps,
verbose: verbose,
sourceMap: sourceMap,
sourceMapIncludeSources: sourceMapIncludeSources,
charset: charset,
silenceDeprecations: silenceDeprecations,
fatalDeprecations: fatalDeprecations,
Expand Down Expand Up @@ -199,6 +207,9 @@ CompileResult compileToResult(
///
/// [`source_maps`]: https://pub.dartlang.org/packages/source_maps
///
/// The [sourceMapIncludeSources] parameter controls the ways in which the
/// compiler can choose to include source contents in the source map.
///
/// If [charset] is `true`, this will include a `@charset` declaration or a
/// UTF-8 [byte-order mark][] if the stylesheet contains any non-ASCII
/// characters. Otherwise, it will never include a `@charset` declaration or a
Expand All @@ -224,6 +235,8 @@ CompileResult compileStringToResult(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.always,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand All @@ -245,6 +258,7 @@ CompileResult compileStringToResult(
quietDeps: quietDeps,
verbose: verbose,
sourceMap: sourceMap,
sourceMapIncludeSources: sourceMapIncludeSources,
charset: charset,
silenceDeprecations: silenceDeprecations,
fatalDeprecations: fatalDeprecations,
Expand All @@ -268,6 +282,8 @@ Future<CompileResult> compileToResultAsync(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.always,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand All @@ -286,6 +302,7 @@ Future<CompileResult> compileToResultAsync(
quietDeps: quietDeps,
verbose: verbose,
sourceMap: sourceMap,
sourceMapIncludeSources: sourceMapIncludeSources,
charset: charset,
silenceDeprecations: silenceDeprecations,
fatalDeprecations: fatalDeprecations,
Expand Down Expand Up @@ -314,6 +331,8 @@ Future<CompileResult> compileStringToResultAsync(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.always,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand All @@ -335,6 +354,7 @@ Future<CompileResult> compileStringToResultAsync(
quietDeps: quietDeps,
verbose: verbose,
sourceMap: sourceMap,
sourceMapIncludeSources: sourceMapIncludeSources,
charset: charset,
silenceDeprecations: silenceDeprecations,
fatalDeprecations: fatalDeprecations,
Expand Down
55 changes: 42 additions & 13 deletions lib/src/async_compile.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
// MIT-style license that can be found in the LICENSE file or at
// https://opensource.org/licenses/MIT.

import 'dart:convert';

import 'package:cli_pkg/js.dart';
import 'package:path/path.dart' as p;

Expand All @@ -18,8 +16,8 @@ import 'importer/no_op.dart';
import 'io.dart';
import 'logger.dart';
import 'logger/deprecation_processing.dart';
import 'source_map_include_sources.dart';
import 'syntax.dart';
import 'utils.dart';
import 'visitor/async_evaluate.dart';
import 'visitor/serialize.dart';

Expand All @@ -42,6 +40,8 @@ Future<CompileResult> compileAsync(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.auto,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand Down Expand Up @@ -88,6 +88,7 @@ Future<CompileResult> compileAsync(
lineFeed,
quietDeps,
sourceMap,
sourceMapIncludeSources,
charset,
);

Expand Down Expand Up @@ -117,6 +118,8 @@ Future<CompileResult> compileStringAsync(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.auto,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand Down Expand Up @@ -156,6 +159,7 @@ Future<CompileResult> compileStringAsync(
lineFeed,
quietDeps,
sourceMap,
sourceMapIncludeSources,
charset,
);

Expand All @@ -179,6 +183,7 @@ Future<CompileResult> _compileStylesheet(
LineFeed? lineFeed,
bool quietDeps,
bool sourceMap,
SourceMapIncludeSources sourceMapIncludeSources,
bool charset,
) async {
if (nodeImporter != null) {
Expand All @@ -188,6 +193,23 @@ Future<CompileResult> _compileStylesheet(
'Dart Sass 2.0.0.\n\n'
'More info: https://sass-lang.com/d/legacy-js-api',
);
} else {
if (sourceMapIncludeSources == SourceMapIncludeSources.true_ ||
sourceMapIncludeSources == SourceMapIncludeSources.false_) {
var boolean = sourceMapIncludeSources == SourceMapIncludeSources.true_;
var suggestion = boolean ? 'always' : 'never';
logger?.warnForDeprecation(
Deprecation.sourceMapIncludeSourcesBoolean,
'Passing a boolean value for Options.sourceMapIncludeSources is '
'deprecated and will be removed in Dart Sass 2.0.0.\n'
"Please use '$suggestion' instead of $boolean.\n\n"
'More info: https://sass-lang.com/d/source-map-include-sources-boolean',
);
Comment on lines +201 to +207

@nex3 nex3 Feb 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be handled at the JS level.

@ntkme ntkme Feb 12, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The logger object isn’t available at JS level. Also throwing it here allow us to only need to throw in a single code path, instead of need to duplicate it in multiple code paths.

@ntkme ntkme Feb 12, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In fact, if you just look at a few lines above, the legacy JS API warning is done here, instead of in the JS API code, I think for exactly same reason...

@nex3 nex3 Feb 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's probably something we'll need to fix sooner or later anyway as APIs evolve over time. The DeprecationProcessingLogger initialization isn't that complex; we should be able to copy it into the JS code and then check if the logger that's passed in to compile*Async is already deprecation-processing and avoid rewrapping if so.

Either way, we shouldn't expose immediately-deprecated enum fields in a new Dart API. If we had to handle that, we should either make this parameter Object or have two separate enums.

@ntkme ntkme May 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with the general principle here, but I don't really want to spend the effort chasing it when it's for a temporary piece code that will be soon removed in 2.0.0 anyways.

sourceMapIncludeSources =
sourceMapIncludeSources == SourceMapIncludeSources.true_
? SourceMapIncludeSources.always
: SourceMapIncludeSources.never;
}
}
var evaluateResult = await evaluateAsync(
stylesheet,
Expand All @@ -211,17 +233,24 @@ Future<CompileResult> _compileStylesheet(
charset: charset,
);

// Postprocess the sourceMap to remove unwanted source contents.
var resultSourceMap = serializeResult.sourceMap;
if (resultSourceMap != null && importCache != null) {
mapInPlace(
resultSourceMap.urls,
(url) => url == ''
? Uri.dataFromString(
stylesheet.span.file.getText(0),
encoding: utf8,
).toString()
: importCache.sourceMapUrl(Uri.parse(url)).toString(),
);
if (resultSourceMap != null) {
if (importCache != null) {
for (var i = 0, length = resultSourceMap.urls.length; i < length; i++) {
var canonicalUrl = Uri.parse(resultSourceMap.urls[i]);
var sourceMapUrl = importCache.sourceMapUrlOrNull(canonicalUrl);
if (sourceMapUrl != null) {
resultSourceMap.urls[i] = sourceMapUrl.toString();
if (sourceMapIncludeSources == SourceMapIncludeSources.auto) {
resultSourceMap.files[i] = null;
}
}
}
}
if (sourceMapIncludeSources == SourceMapIncludeSources.never) {
resultSourceMap.files.fillRange(0, resultSourceMap.files.length, null);
}
}

return CompileResult(evaluateResult, serializeResult);
Expand Down
7 changes: 7 additions & 0 deletions lib/src/async_import_cache.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -371,9 +371,16 @@ final class AsyncImportCache {
/// Returns the URL to use in the source map to refer to [canonicalUrl].
///
/// Returns [canonicalUrl] as-is if it hasn't been loaded by this cache.
@Deprecated('Use sourceMapUrlOrNull instead.')
Uri sourceMapUrl(Uri canonicalUrl) =>
_resultsCache[canonicalUrl]?.sourceMapUrl ?? canonicalUrl;

/// Returns the URL to use in the source map to refer to [canonicalUrl].
///
/// Returns `null` if it hasn't been loaded by this cache.
Uri? sourceMapUrlOrNull(Uri canonicalUrl) =>
_resultsCache[canonicalUrl]?.sourceMapUrl;

/// Returns the most recent time the stylesheet at [canonicalUrl] was loaded
/// from its importer, or `null` if it has never been loaded.
@internal
Expand Down
57 changes: 43 additions & 14 deletions lib/src/compile.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,12 @@
// DO NOT EDIT. This file was generated from async_compile.dart.
// See tool/grind/synchronize.dart for details.
//
// Checksum: aa378886d9a3d697d466ac916f7902cbc1b282ee
// Checksum: 24489ae0ff07c9b2febb57a82f59fafc525178d5
//
// ignore_for_file: unused_import

export 'async_compile.dart';

import 'dart:convert';

import 'package:cli_pkg/js.dart';
import 'package:path/path.dart' as p;

Expand All @@ -27,8 +25,8 @@ import 'importer/no_op.dart';
import 'io.dart';
import 'logger.dart';
import 'logger/deprecation_processing.dart';
import 'source_map_include_sources.dart';
import 'syntax.dart';
import 'utils.dart';
import 'visitor/evaluate.dart';
import 'visitor/serialize.dart';

Expand All @@ -51,6 +49,8 @@ CompileResult compile(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.auto,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand Down Expand Up @@ -97,6 +97,7 @@ CompileResult compile(
lineFeed,
quietDeps,
sourceMap,
sourceMapIncludeSources,
charset,
);

Expand Down Expand Up @@ -126,6 +127,8 @@ CompileResult compileString(
bool quietDeps = false,
bool verbose = false,
bool sourceMap = false,
SourceMapIncludeSources sourceMapIncludeSources =
SourceMapIncludeSources.auto,
bool charset = true,
Iterable<Deprecation>? silenceDeprecations,
Iterable<Deprecation>? fatalDeprecations,
Expand Down Expand Up @@ -165,6 +168,7 @@ CompileResult compileString(
lineFeed,
quietDeps,
sourceMap,
sourceMapIncludeSources,
charset,
);

Expand All @@ -188,6 +192,7 @@ CompileResult _compileStylesheet(
LineFeed? lineFeed,
bool quietDeps,
bool sourceMap,
SourceMapIncludeSources sourceMapIncludeSources,
bool charset,
) {
if (nodeImporter != null) {
Expand All @@ -197,6 +202,23 @@ CompileResult _compileStylesheet(
'Dart Sass 2.0.0.\n\n'
'More info: https://sass-lang.com/d/legacy-js-api',
);
} else {
if (sourceMapIncludeSources == SourceMapIncludeSources.true_ ||
sourceMapIncludeSources == SourceMapIncludeSources.false_) {
var boolean = sourceMapIncludeSources == SourceMapIncludeSources.true_;
var suggestion = boolean ? 'always' : 'never';
logger?.warnForDeprecation(
Deprecation.sourceMapIncludeSourcesBoolean,
'Passing a boolean value for Options.sourceMapIncludeSources is '
'deprecated and will be removed in Dart Sass 2.0.0.\n'
"Please use '$suggestion' instead of $boolean.\n\n"
'More info: https://sass-lang.com/d/source-map-include-sources-boolean',
);
sourceMapIncludeSources =
sourceMapIncludeSources == SourceMapIncludeSources.true_
? SourceMapIncludeSources.always
: SourceMapIncludeSources.never;
}
}
var evaluateResult = evaluate(
stylesheet,
Expand All @@ -220,17 +242,24 @@ CompileResult _compileStylesheet(
charset: charset,
);

// Postprocess the sourceMap to remove unwanted source contents.
var resultSourceMap = serializeResult.sourceMap;
if (resultSourceMap != null && importCache != null) {
mapInPlace(
resultSourceMap.urls,
(url) => url == ''
? Uri.dataFromString(
stylesheet.span.file.getText(0),
encoding: utf8,
).toString()
: importCache.sourceMapUrl(Uri.parse(url)).toString(),
);
if (resultSourceMap != null) {
if (importCache != null) {
for (var i = 0, length = resultSourceMap.urls.length; i < length; i++) {
var canonicalUrl = Uri.parse(resultSourceMap.urls[i]);
var sourceMapUrl = importCache.sourceMapUrlOrNull(canonicalUrl);
if (sourceMapUrl != null) {
resultSourceMap.urls[i] = sourceMapUrl.toString();
if (sourceMapIncludeSources == SourceMapIncludeSources.auto) {
resultSourceMap.files[i] = null;
}
}
}
}
if (sourceMapIncludeSources == SourceMapIncludeSources.never) {
resultSourceMap.files.fillRange(0, resultSourceMap.files.length, null);
}
}

return CompileResult(evaluateResult, serializeResult);
Expand Down
8 changes: 7 additions & 1 deletion lib/src/deprecation.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ enum Deprecation {
// DO NOT EDIT. This section was generated from the language repo.
// See tool/grind/generate_deprecations.dart for details.
//
// Checksum: 1e05e728d95255e2e9fadbe9696baf751fc7ef66
// Checksum: 3fc6d58768aadb9d257e4e8ea3d282f99ee4857e

/// Deprecation for passing a string directly to meta.call().
callString('call-string',
Expand Down Expand Up @@ -161,6 +161,12 @@ enum Deprecation {
deprecatedIn: '1.100.0',
description: 'Adjacent compound selectors like `[class]a`.'),

/// Deprecation for passing a boolean value to as Options.sourceMapIncludeSources.
sourceMapIncludeSourcesBoolean('source-map-include-sources-boolean',
deprecatedIn: '1.101.0',
description:
'Passing a boolean value to as Options.sourceMapIncludeSources.'),

// END AUTOGENERATED CODE

/// Used for deprecations coming from user-authored code.
Expand Down
Loading
Loading