Emit deprecation warnings for legacy JS API

lib/src/compiler/async.ts

@@ -17,6 +17,7 @@ import {
   newCompileStringRequest,
 } from './utils';
 import {compilerCommand} from '../compiler-path';
+import {activeDeprecationOptions} from '../deprecations';
 import {FunctionRegistry} from '../function-registry';
 import {ImporterRegistry} from '../importer-registry';
 import {MessageTransformer} from '../message-transformer';
@@ -102,38 +103,44 @@ export class AsyncCompiler {
     importers: ImporterRegistry<'async'>,
     options?: OptionsWithLegacy<'async'> & {legacy?: boolean}
   ): Promise<CompileResult> {
-    const functions = new FunctionRegistry(options?.functions);
-
-    const dispatcher = createDispatcher<'async'>(
-      this.compilationId++,
-      this.messageTransformer,
-      {
-        handleImportRequest: request => importers.import(request),
-        handleFileImportRequest: request => importers.fileImport(request),
-        handleCanonicalizeRequest: request => importers.canonicalize(request),
-        handleFunctionCallRequest: request => functions.call(request),
-      }
-    );
-    dispatcher.logEvents$.subscribe(event => handleLogEvent(options, event));
-
-    const compilation = new Promise<proto.OutboundMessage_CompileResponse>(
-      (resolve, reject) =>
-        dispatcher.sendCompileRequest(request, (err, response) => {
-          this.compilations.delete(compilation);
-          // Reset the compilation ID when the compiler goes idle (no active
-          // compilations) to avoid overflowing it.
-          // https://github.com/sass/embedded-host-node/pull/261#discussion_r1429266794
-          if (this.compilations.size === 0) this.compilationId = 1;
-          if (err) {
-            reject(err);
-          } else {
-            resolve(response!);
-          }
-        })
-    );
-    this.compilations.add(compilation);
+    const optionsKey = Symbol();
+    activeDeprecationOptions.set(optionsKey, options ?? {});
+    try {
+      const functions = new FunctionRegistry(options?.functions);
+
+      const dispatcher = createDispatcher<'async'>(
+        this.compilationId++,
+        this.messageTransformer,
+        {
+          handleImportRequest: request => importers.import(request),
+          handleFileImportRequest: request => importers.fileImport(request),
+          handleCanonicalizeRequest: request => importers.canonicalize(request),
+          handleFunctionCallRequest: request => functions.call(request),
+        }
+      );
+      dispatcher.logEvents$.subscribe(event => handleLogEvent(options, event));
+
+      const compilation = new Promise<proto.OutboundMessage_CompileResponse>(
+        (resolve, reject) =>
+          dispatcher.sendCompileRequest(request, (err, response) => {
+            this.compilations.delete(compilation);
+            // Reset the compilation ID when the compiler goes idle (no active
+            // compilations) to avoid overflowing it.
+            // https://github.com/sass/embedded-host-node/pull/261#discussion_r1429266794
+            if (this.compilations.size === 0) this.compilationId = 1;
+            if (err) {
+              reject(err);
+            } else {
+              resolve(response!);
+            }
+          })
+      );
+      this.compilations.add(compilation);
 
-    return handleCompileResponse(await compilation);
+      return handleCompileResponse(await compilation);
+    } finally {
+      activeDeprecationOptions.delete(optionsKey);
+    }
   }
 
   /** Initialize resources shared across compilations. */

lib/src/compiler/sync.ts

@@ -14,6 +14,7 @@ import {
   newCompileStringRequest,
 } from './utils';
 import {compilerCommand} from '../compiler-path';
+import {activeDeprecationOptions} from '../deprecations';
 import {Dispatcher} from '../dispatcher';
 import {FunctionRegistry} from '../function-registry';
 import {ImporterRegistry} from '../importer-registry';
@@ -108,44 +109,50 @@ export class Compiler {
     importers: ImporterRegistry<'sync'>,
     options?: OptionsWithLegacy<'sync'>
   ): CompileResult {
-    const functions = new FunctionRegistry(options?.functions);
-
-    const dispatcher = createDispatcher<'sync'>(
-      this.compilationId++,
-      this.messageTransformer,
-      {
-        handleImportRequest: request => importers.import(request),
-        handleFileImportRequest: request => importers.fileImport(request),
-        handleCanonicalizeRequest: request => importers.canonicalize(request),
-        handleFunctionCallRequest: request => functions.call(request),
-      }
-    );
-    this.dispatchers.add(dispatcher);
-
-    dispatcher.logEvents$.subscribe(event => handleLogEvent(options, event));
-
-    let error: unknown;
-    let response: proto.OutboundMessage_CompileResponse | undefined;
-    dispatcher.sendCompileRequest(request, (error_, response_) => {
-      this.dispatchers.delete(dispatcher);
-      // Reset the compilation ID when the compiler goes idle (no active
-      // dispatchers) to avoid overflowing it.
-      // https://github.com/sass/embedded-host-node/pull/261#discussion_r1429266794
-      if (this.dispatchers.size === 0) this.compilationId = 1;
-      if (error_) {
-        error = error_;
-      } else {
-        response = response_;
-      }
-    });
-
-    for (;;) {
-      if (!this.yield()) {
-        throw utils.compilerError('Embedded compiler exited unexpectedly.');
+    const optionsKey = Symbol();
+    activeDeprecationOptions.set(optionsKey, options ?? {});
+    try {
+      const functions = new FunctionRegistry(options?.functions);
+
+      const dispatcher = createDispatcher<'sync'>(
+        this.compilationId++,
+        this.messageTransformer,
+        {
+          handleImportRequest: request => importers.import(request),
+          handleFileImportRequest: request => importers.fileImport(request),
+          handleCanonicalizeRequest: request => importers.canonicalize(request),
+          handleFunctionCallRequest: request => functions.call(request),
+        }
+      );
+      this.dispatchers.add(dispatcher);
+
+      dispatcher.logEvents$.subscribe(event => handleLogEvent(options, event));
+
+      let error: unknown;
+      let response: proto.OutboundMessage_CompileResponse | undefined;
+      dispatcher.sendCompileRequest(request, (error_, response_) => {
+        this.dispatchers.delete(dispatcher);
+        // Reset the compilation ID when the compiler goes idle (no active
+        // dispatchers) to avoid overflowing it.
+        // https://github.com/sass/embedded-host-node/pull/261#discussion_r1429266794
+        if (this.dispatchers.size === 0) this.compilationId = 1;
+        if (error_) {
+          error = error_;
+        } else {
+          response = response_;
+        }
+      });
+
+      for (;;) {
+        if (!this.yield()) {
+          throw utils.compilerError('Embedded compiler exited unexpectedly.');
+        }
+
+        if (error) throw error;
+        if (response) return handleCompileResponse(response);
       }
-
-      if (error) throw error;
-      if (response) return handleCompileResponse(response);
+    } finally {
+      activeDeprecationOptions.delete(optionsKey);
     }
   }
 

lib/src/deprecations.ts

@@ -2,7 +2,7 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
-import {DeprecationOrId} from './vendor/sass';
+import {Deprecation, DeprecationOrId, Options} from './vendor/sass';
 import {Version} from './version';
 
 export {deprecations} from './vendor/deprecations';
@@ -15,12 +15,132 @@ export {Deprecation, DeprecationOrId, DeprecationStatus} from './vendor/sass';
 export function getDeprecationIds(
   arr: (DeprecationOrId | Version)[]
 ): string[] {
-  return arr.flatMap(item => {
+  return arr.map(item => {
     if (item instanceof Version) {
-      return arr.map(item => item.toString());
+      return item.toString();
     } else if (typeof item === 'string') {
       return item;
     }
     return item.id;
   });
 }
+
+/**
+ * Map between active compilations and the deprecation options they use.
+ *
+ * This is used to determine which options to use when handling host-side
+ * deprecation warnings that aren't explicitly tied to a particular compilation.
+ */
+export const activeDeprecationOptions: Map<Object, DeprecationOptions> =
+  new Map();
+
+/**
+ * Shorthand for the subset of options related to deprecations.
+ */
+export type DeprecationOptions = Pick<
+  Options<'sync'>,
+  'fatalDeprecations' | 'futureDeprecations' | 'silenceDeprecations'
+>;
+
+/**
+ * Handles a host-side deprecation warning, either emitting a warning, throwing
+ * an error, or doing nothing depending on the deprecation options used.
+ *
+ * If no specific deprecation options are passed here, then options will be
+ * determined based on the options of the active compilations.
+ */
+export function warnForHostSideDeprecation(
+  message: string,
+  deprecation: Deprecation,
+  options?: DeprecationOptions
+): void {
+  if (
+    deprecation.status === 'future' &&
+    !isEnabledFuture(deprecation, options)
+  ) {
+    return;
+  }
+  const fullMessage = `Deprecation [${deprecation.id}]: ${message}`;
+  if (isFatal(deprecation, options)) {
+    throw Error(fullMessage);
+  }
+  if (!isSilent(deprecation, options)) {
+    console.warn(fullMessage);
+  }
+}
+
+/**
+ * Checks whether the given deprecation is included in the given list of silent
+ * deprecations or is silenced by at least one active compilation.
+ */
+function isSilent(
+  deprecation: Deprecation,
+  options?: DeprecationOptions
+): boolean {
+  if (!options) {
+    for (const potentialOptions of activeDeprecationOptions.values()) {
+      if (isSilent(deprecation, potentialOptions)) return true;
+    }
+    return false;
+  }
+  return getDeprecationIds(options?.silenceDeprecations ?? []).includes(
+    deprecation.id
+  );
+}
+
+/**
+ * Checks whether the given deprecation is included in the given list of future
+ * deprecations that should be enabled or is enabled in all active compilations.
+ */
+function isEnabledFuture(
+  deprecation: Deprecation,
+  options?: DeprecationOptions
+): boolean {
+  if (!options) {
+    for (const potentialOptions of activeDeprecationOptions.values()) {
+      if (!isEnabledFuture(deprecation, potentialOptions)) return false;
+    }
+    return activeDeprecationOptions.size > 0;
+  }
+  return getDeprecationIds(options?.futureDeprecations ?? []).includes(
+    deprecation.id
+  );
+}
+
+/**
+ * Checks whether the given deprecation is included in the given list of
+ * fatal deprecations or is marked as fatal in all active compilations.
+ */
+function isFatal(
+  deprecation: Deprecation,
+  options?: DeprecationOptions
+): boolean {
+  if (!options) {
+    for (const potentialOptions of activeDeprecationOptions.values()) {
+      if (!isFatal(deprecation, potentialOptions)) return false;
+    }
+    return activeDeprecationOptions.size > 0;
+  }
+  const versionNumber =
+    deprecation.deprecatedIn === null
+      ? null
+      : deprecation.deprecatedIn.major * 1000000 +
+        deprecation.deprecatedIn.minor * 1000 +
+        deprecation.deprecatedIn.patch;
+  for (const fatal of options?.fatalDeprecations ?? []) {
+    if (fatal instanceof Version) {
+      if (versionNumber === null) continue;
+      if (
+        versionNumber <=
+        fatal.major * 1000000 + fatal.minor * 1000 + fatal.patch
+      ) {
+        return true;
+      }
+    } else if (typeof fatal === 'string') {
+      if (fatal === deprecation.id) return true;
+    } else {
+      if ((fatal as Deprecation).id === deprecation.id) return true;
+    }
+  }
+  return false;
+}

lib/src/legacy/index.ts

@@ -14,6 +14,7 @@ import {
   compileString,
   compileStringAsync,
 } from '../compile';
+import {deprecations, warnForHostSideDeprecation} from '../deprecations';
 import {
   SyncBoolean,
   fileUrlToPathCrossPlatform,
@@ -50,6 +51,11 @@ export function render(
     options = adjustOptions(options);
 
     const start = Date.now();
+    warnForHostSideDeprecation(
+      'The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.',
+      deprecations['legacy-js-api'],
+      options
+    );
     const compileSass = isStringOptions(options)
       ? compileStringAsync(options.data, convertStringOptions(options, false))
       : compileAsync(options.file, convertOptions(options, false));
@@ -68,6 +74,11 @@ export function renderSync(options: LegacyOptions<'sync'>): LegacyResult {
   const start = Date.now();
   try {
     options = adjustOptions(options);
+    warnForHostSideDeprecation(
+      'The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.',
+      deprecations['legacy-js-api'],
+      options
+    );
     const result = isStringOptions(options)
       ? compileString(options.data, convertStringOptions(options, true))
       : compile(options.file, convertOptions(options, true));