sass 1.72.0 → 1.74.1

package/sass.default.js

@@ -43,3 +43,5 @@ export const FALSE = _cliPkgExports.FALSE;
 export const NULL = _cliPkgExports.NULL;
 export const types = _cliPkgExports.types;
 export const NodePackageImporter = _cliPkgExports.NodePackageImporter;
+export const deprecations = _cliPkgExports.deprecations;
+export const Version = _cliPkgExports.Version;

package/sass.node.mjs

@@ -37,6 +37,8 @@ export const FALSE = cjs.FALSE;
 export const NULL = cjs.NULL;
 export const types = cjs.types;
 export const NodePackageImporter = cjs.NodePackageImporter;
+export const deprecations = cjs.deprecations;
+export const Version = cjs.Version;
 
 let printedDefaultExportDeprecation = false;
 function defaultExportDeprecation() {
@@ -196,4 +198,12 @@ export default {
     defaultExportDeprecation();
     return cjs.NodePackageImporter;
   },
+  get deprecations() {
+    defaultExportDeprecation();
+    return cjs.deprecations;
+  },
+  get Version() {
+    defaultExportDeprecation();
+    return cjs.Version;
+  },
 };

package/types/deprecations.d.ts

@@ -0,0 +1,209 @@
+/**
+ * All of the deprecation types currently used by Sass.
+ *
+ * Any of these IDs or the deprecation objects they point to can be passed to
+ * `fatalDeprecations`, `futureDeprecations`, or `silenceDeprecations`.
+ */
+export interface Deprecations {
+  /**
+   * Deprecation for passing a string to `call` instead of using `get-function`.
+   *
+   * This deprecation has been active in all versions of Dart Sass.
+   */
+  'call-string': Deprecation<'call-string'>;
+
+  /**
+   * Deprecation for `@elseif`.
+   *
+   * This deprecation became active in Dart Sass 1.3.2.
+   */
+  elseif: Deprecation<'elseif'>;
+
+  /**
+   * Deprecation for parsing `@-moz-document`.
+   *
+   * This deprecation became active in Dart Sass 1.7.2.
+   */
+  'moz-document': Deprecation<'moz-document'>;
+
+  /**
+   * Deprecation for imports using relative canonical URLs.
+   *
+   * This deprecation became active in Dart Sass 1.17.2.
+   */
+  'relative-canonical': Deprecation<'relative-canonical'>;
+
+  /**
+   * Deprecation for declaring new variables with `!global`.
+   *
+   * This deprecation became active in Dart Sass 1.17.2.
+   */
+  'new-global': Deprecation<'new-global'>;
+
+  /**
+   * Deprecation for using color module functions in place of plain CSS
+   * functions.
+   *
+   * This deprecation became active in Dart Sass 1.23.0.
+   */
+  'color-module-compat': Deprecation<'color-module-compat'>;
+
+  /**
+   * Deprecation for treating `/` as division.
+   *
+   * This deprecation became active in Dart Sass 1.33.0.
+   */
+  'slash-div': Deprecation<'slash-div'>;
+
+  /**
+   * Deprecation for leading, trailing, and repeated combinators.
+   *
+   * This deprecation became active in Dart Sass 1.54.0.
+   */
+  'bogus-combinators': Deprecation<'bogus-combinators'>;
+
+  /**
+   * Deprecation for ambiguous `+` and `-` operators.
+   *
+   * This deprecation became active in Dart Sass 1.55.0.
+   */
+  'strict-unary': Deprecation<'strict-unary'>;
+
+  /**
+   * Deprecation for passing invalid units to certain built-in functions.
+   *
+   * This deprecation became active in Dart Sass 1.56.0.
+   */
+  'function-units': Deprecation<'function-units'>;
+
+  /**
+   * Deprecation for using `!default` or `!global` multiple times for one
+   * variable.
+   *
+   * This deprecation became active in Dart Sass 1.62.0.
+   */
+  'duplicate-var-flags': Deprecation<'duplicate-var-flags'>;
+
+  /**
+   * Deprecation for passing null as alpha in the JS API.
+   *
+   * This deprecation became active in Dart Sass 1.62.3.
+   */
+  'null-alpha': Deprecation<'null-alpha'>;
+
+  /**
+   * Deprecation for passing percentages to the Sass `abs()` function.
+   *
+   * This deprecation became active in Dart Sass 1.65.0.
+   */
+  'abs-percent': Deprecation<'abs-percent'>;
+
+  /**
+   * Deprecation for using the current working directory as an implicit load
+   * path.
+   *
+   * This deprecation became active in Dart Sass 1.73.0.
+   */
+  'fs-importer-cwd': Deprecation<'fs-importer-cwd'>;
+
+  /**
+   * Deprecation for `@import` rules.
+   *
+   * This deprecation is not yet active, but will be soon.
+   */
+  import: Deprecation<'import'>;
+
+  /**
+   * Used for any user-emitted deprecation warnings.
+   */
+  'user-authored': Deprecation<'user-authored', 'user'>;
+}
+
+/**
+ * Either a deprecation or its ID, either of which can be passed to any of
+ * the relevant compiler options.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export type DeprecationOrId = Deprecation | keyof Deprecations;
+
+/**
+ * The possible statuses that each deprecation can have.
+ *
+ * "active" deprecations are currently emitting deprecation warnings.
+ * "future" deprecations are not yet active, but will be in the future.
+ * "obsolete" deprecations were once active, but no longer are.
+ *
+ * The only "user" deprecation is "user-authored", which is used for deprecation
+ * warnings coming from user code.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export type DeprecationStatus = 'active' | 'user' | 'future' | 'obsolete';
+
+/**
+ * A deprecated feature in the language.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export interface Deprecation<
+  id extends keyof Deprecations = keyof Deprecations,
+  status extends DeprecationStatus = DeprecationStatus
+> {
+  /** The unique ID of this deprecation. */
+  id: id;
+
+  /** The current status of this deprecation. */
+  status: status;
+
+  /** A human-readable description of this deprecation. */
+  description?: string;
+
+  /** The version this deprecation first became active in. */
+  deprecatedIn: status extends 'future' | 'user' ? null : Version;
+
+  /** The version this deprecation became obsolete in. */
+  obsoleteIn: status extends 'obsolete' ? Version : null;
+}
+
+/**
+ * A semantic version of the compiler.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export class Version {
+  /**
+   * Constructs a new version.
+   *
+   * All components must be non-negative integers.
+   *
+   * @param major - The major version.
+   * @param minor - The minor version.
+   * @param patch - The patch version.
+   */
+  constructor(major: number, minor: number, patch: number);
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+
+  /**
+   * Parses a version from a string.
+   *
+   * This throws an error if a valid version can't be parsed.
+   *
+   * @param version - A string in the form "major.minor.patch".
+   */
+  static parse(version: string): Version;
+}
+
+/**
+ * An object containing all deprecation types.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export const deprecations: Deprecations;

package/types/index.d.ts

@@ -13,6 +13,14 @@ export {
   initCompiler,
   initAsyncCompiler,
 } from './compile';
+export {
+  deprecations,
+  Deprecation,
+  Deprecations,
+  DeprecationOrId,
+  DeprecationStatus,
+  Version,
+} from './deprecations';
 export {Exception} from './exception';
 export {
   CanonicalizeContext,

package/types/logger/index.d.ts

@@ -1,3 +1,4 @@
+import {Deprecation} from '../deprecations';
 import {SourceSpan} from './source_span';
 
 export {SourceLocation} from './source_location';
@@ -43,17 +44,21 @@ export interface Logger {
    *
    * @param message - The warning message.
    * @param options.deprecation - Whether this is a deprecation warning.
+   * @param options.deprecationType - The type of deprecation this warning is
+   * for, if any.
    * @param options.span - The location in the Sass source code that generated this
    * warning.
    * @param options.stack - The Sass stack trace at the point the warning was issued.
    */
   warn?(
     message: string,
-    options: {
-      deprecation: boolean;
-      span?: SourceSpan;
-      stack?: string;
-    }
+    options: (
+      | {
+          deprecation: true;
+          deprecationType: Deprecation;
+        }
+      | {deprecation: false}
+    ) & {span?: SourceSpan; stack?: string}
   ): void;
 
   /**

package/types/options.d.ts

@@ -1,3 +1,4 @@
+import {DeprecationOrId, Version} from './deprecations';
 import {FileImporter, Importer, NodePackageImporter} from './importer';
 import {Logger} from './logger';
 import {Value} from './value';
@@ -122,6 +123,20 @@ export interface Options<sync extends 'sync' | 'async'> {
    */
   charset?: boolean;
 
+  /**
+   * A set of deprecations to treat as fatal.
+   *
+   * If a deprecation warning of any provided type is encountered during
+   * compilation, the compiler will error instead.
+   *
+   * If a `Version` is provided, then all deprecations that were active in that
+   * compiler version will be treated as fatal.
+   *
+   * @category Messages
+   * @compatiblity dart: "1.74.0", node: false
+   */
+  fatalDeprecations?: (DeprecationOrId | Version)[];
+
   /**
    * Additional built-in Sass functions that are available in all stylesheets.
    * This option takes an object whose keys are Sass function signatures like
@@ -198,6 +213,17 @@ export interface Options<sync extends 'sync' | 'async'> {
    */
   functions?: Record<string, CustomFunction<sync>>;
 
+  /**
+   * A set of future deprecations to opt into early.
+   *
+   * Future deprecations passed here will be treated as active by the compiler,
+   * emitting warnings as necessary.
+   *
+   * @category Messages
+   * @compatiblity dart: "1.74.0", node: false
+   */
+  futureDeprecations?: DeprecationOrId[];
+
   /**
    * Custom importers that control how Sass resolves loads from rules like
    * [`@use`](https://sass-lang.com/documentation/at-rules/use) and
@@ -276,6 +302,20 @@ export interface Options<sync extends 'sync' | 'async'> {
    */
   quietDeps?: boolean;
 
+  /**
+   * A set of active deprecations to ignore.
+   *
+   * If a deprecation warning of any provided type is encountered during
+   * compilation, the compiler will ignore it instead.
+   *
+   * **Heads up!** The deprecated functionality you're depending on will
+   * eventually break.
+   *
+   * @category Messages
+   * @compatiblity dart: "1.74.0", node: false
+   */
+  silenceDeprecations?: DeprecationOrId[];
+
   /**
    * Whether or not Sass should generate a source map. If it does, the source
    * map will be available as {@link CompileResult.sourceMap}.