[BREAKING] Convert to a module. Drops support for Ember < 3.28, requires manual initialization

.github/workflows/ci.yml

@@ -62,21 +62,20 @@ jobs:
       matrix:
         try-scenario:
           [
-            ember-lts-2.12,
-            ember-lts-2.18,
-            ember-lts-3.16,
-            ember-lts-3.20,
-            ember-lts-3.24,
             ember-lts-3.28,
             ember-lts-4.4,
             ember-lts-4.8,
             ember-lts-4.12,
+            ember-lts-5.4,
             ember-release,
             ember-beta,
             ember-canary,
             ember-3.28-with-jquery,
             ember-3.28-classic,
           ]
+        include:
+          - ember-try-scenario: ember-canary
+            allow-failure: true
 
     steps:
       - name: Checkout

README.md

@@ -23,6 +23,12 @@ addressing a single deprecation at a time, and prevents backsliding
 
 ### Compatibility
 
+3.x
+
+- Ember.js 3.28 until at least 5.4
+- Ember CLI 4.12 or above
+- Node.js 16 or above
+
 2.x
 
 - Ember.js 2.12 until at least 4.12
@@ -37,13 +43,27 @@ addressing a single deprecation at a time, and prevents backsliding
 
 ### Getting started
 
-The initial steps needed to get started:
-
 1. Install the ember-cli-deprecation-workflow addon (`ember install ember-cli-deprecation-workflow`).
-2. Run your test suite\* with `ember test --server`.
-3. Navigate to your tests (default: http://localhost:7357/)
-4. Run `deprecationWorkflow.flushDeprecations()` from your browsers console.
-5. Copy the string output into `config/deprecation-workflow.js` in your project.
+2. Create an `app/deprecation-workflow.js` file with the following content:
+
+    ```js
+    import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow';
+
+    setupDeprecationWorkflow();
+    ```
+
+3. In your `app/app.js`, do: 
+
+    ```js
+    import './deprecation-workflow';
+    ```
+
+4. Run your test suite\* with `ember test --server`.
+5. Navigate to your tests (default: http://localhost:7357/)
+6. Run `deprecationWorkflow.flushDeprecations()` in your browsers console.
+7. Copy the string output and overwrite the content of `app/deprecation-workflow.js`.
+
+    In Chrome, use right click → "Copy string contents" to avoid escape characters.
 
 Once this initial setup is completed the "deprecation spew" should be largely
 "fixed". Only unhandled deprecations will be displayed in your console.

addon/index.js

@@ -0,0 +1,114 @@
+import { registerDeprecationHandler } from '@ember/debug';
+
+const LOG_LIMIT = 100;
+
+export default function setupDeprecationWorkflow(config) {
+  self.deprecationWorkflow = self.deprecationWorkflow || {};
+  self.deprecationWorkflow.deprecationLog = {
+    messages: {},
+  };
+
+  registerDeprecationHandler((message, options, next) =>
+    handleDeprecationWorkflow(config, message, options, next),
+  );
+
+  registerDeprecationHandler(deprecationCollector);
+
+  self.deprecationWorkflow.flushDeprecations = flushDeprecations;
+}
+
+let preamble = `import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow';
+
+setupDeprecationWorkflow({
+  workflow: [
+`;
+
+let postamble = `  ]
+});`;
+
+export function detectWorkflow(config, message, options) {
+  if (!config || !config.workflow) {
+    return;
+  }
+
+  let i, workflow, matcher, idMatcher;
+  for (i = 0; i < config.workflow.length; i++) {
+    workflow = config.workflow[i];
+    matcher = workflow.matchMessage;
+    idMatcher = workflow.matchId;
+
+    if (typeof idMatcher === 'string' && options && idMatcher === options.id) {
+      return workflow;
+    } else if (typeof matcher === 'string' && matcher === message) {
+      return workflow;
+    } else if (matcher instanceof RegExp && matcher.exec(message)) {
+      return workflow;
+    }
+  }
+}
+
+export function flushDeprecations() {
+  let messages = self.deprecationWorkflow.deprecationLog.messages;
+  let logs = [];
+
+  for (let message in messages) {
+    logs.push(messages[message]);
+  }
+
+  let deprecations = logs.join(',\n') + '\n';
+
+  return preamble + deprecations + postamble;
+}
+
+export function handleDeprecationWorkflow(config, message, options, next) {
+  let matchingWorkflow = detectWorkflow(config, message, options);
+  if (!matchingWorkflow) {
+    if (config && config.throwOnUnhandled) {
+      throw new Error(message);
+    } else {
+      next(message, options);
+    }
+  } else {
+    switch (matchingWorkflow.handler) {
+      case 'silence':
+        // no-op
+        break;
+      case 'log': {
+        let key = (options && options.id) || message;
+
+        if (!self.deprecationWorkflow.logCounts) {
+          self.deprecationWorkflow.logCounts = {};
+        }
+
+        let count = self.deprecationWorkflow.logCounts[key] || 0;
+        self.deprecationWorkflow.logCounts[key] = ++count;
+
+        if (count <= LOG_LIMIT) {
+          console.warn('DEPRECATION: ' + message);
+          if (count === LOG_LIMIT) {
+            console.warn(
+              'To avoid console overflow, this deprecation will not be logged any more in this run.',
+            );
+          }
+        }
+
+        break;
+      }
+      case 'throw':
+        throw new Error(message);
+      default:
+        next(message, options);
+        break;
+    }
+  }
+}
+
+export function deprecationCollector(message, options, next) {
+  let key = (options && options.id) || message;
+  let matchKey = options && key === options.id ? 'matchId' : 'matchMessage';
+
+  self.deprecationWorkflow.deprecationLog.messages[key] =
+    '    { handler: "silence", ' + matchKey + ': ' + JSON.stringify(key) + ' }';
+
+  next(message, options);
+}