@appland/scanner 1.84.0 → 1.85.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@appland/scanner-v1.85.0](https://github.com/getappmap/appmap-js/compare/@appland/scanner-v1.84.1...@appland/scanner-v1.85.0) (2023-12-28)
+
+
+### Features
+
+* Scanner rule for unfulfilled promises ([df6afe8](https://github.com/getappmap/appmap-js/commit/df6afe8e2cbc1f677ad1313309fb365971806204)), closes [#1477](https://github.com/getappmap/appmap-js/issues/1477)
+
+# [@appland/scanner-v1.84.1](https://github.com/getappmap/appmap-js/compare/@appland/scanner-v1.84.0...@appland/scanner-v1.84.1) (2023-11-08)
+
+
+### Bug Fixes
+
+* Catch and report errors that occur in the matcher function ([b558170](https://github.com/getappmap/appmap-js/commit/b558170aa49c3b874c5b46f504a1db1a0120bacb))
+
 # [@appland/scanner-v1.84.0](https://github.com/getappmap/appmap-js/compare/@appland/scanner-v1.83.1...@appland/scanner-v1.84.0) (2023-11-07)
 
 

package/LICENSE.txt

@@ -12,7 +12,7 @@ Software: @appland/scanner
 
 License: MIT License
 
-Copyright 2022, AppLand Inc
+Copyright 2023, AppLand Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,

package/built/ruleChecker.js

@@ -231,7 +231,13 @@ class RuleChecker {
             });
             if (this.progress)
                 yield this.progress.matchEvent(event, appMapIndex);
-            const matchResult = yield checkInstance.ruleLogic.matcher(event, appMapIndex, checkInstance.filterEvent.bind(checkInstance));
+            let matchResult;
+            try {
+                matchResult = yield checkInstance.ruleLogic.matcher(event, appMapIndex, checkInstance.filterEvent.bind(checkInstance));
+            }
+            catch (e) {
+                (0, console_1.warn)(e);
+            }
             if (this.progress)
                 yield this.progress.matchResult(event, matchResult);
             const numFindings = findings.length;

package/built/rules/unfulfilledPromise.d.ts

@@ -0,0 +1,3 @@
+import type RuleInstance from '../ruleInstance';
+declare const RULE: RuleInstance;
+export default RULE;

package/built/rules/unfulfilledPromise.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const parseRuleDescription_1 = __importDefault(require("./lib/parseRuleDescription"));
+const id = 'unfulfilled-promise';
+const RULE = {
+    id,
+    title: 'Unfulfilled Promise',
+    description: (0, parseRuleDescription_1.default)(id),
+    enumerateScope: true,
+    build: () => ({ matcher: (e) => { var _a; return ((_a = e.returnValue) === null || _a === void 0 ? void 0 : _a.value) === 'Promise { <pending> }'; } }),
+};
+exports.default = RULE;

package/doc/rules/unfulfilled-promise.md

@@ -0,0 +1,48 @@
+---
+rule: unfulfilled-promise
+name: Unfulfilled promise
+title: Unfulfilled Promise
+---
+
+Finds promises which have been created during the recording but have remained unfulfilled at the
+end.
+
+### Rule logic
+
+The rule simply looks for return events with value of `Promise { <pending> }` without a subsequent
+update.
+
+### Notes
+
+`Promise { <pending> }` is a special value used by the appmap-node agent to represent promises that
+haven't been fulfilled yet. Normally, once the promise is fulfilled, an event update is added to the
+AppMap with the resolved value and total elapsed run time.
+
+However, if a promise remains unfulfilled when the recording ends (for example when a HTTP response
+is sent or a test case finishes) this pending state is never updated.
+
+Most of the time it means some asynchronous computation has been started and its results not awaited
+for and therefore not collected; such computations should be removed or the results awaited.
+
+In some cases this is an intended behaviour; for example, a background book-keeping or cleanup
+process might be started which doesn't directly impact the results of the operation that triggered
+it. Note that during testing such processes should still run to completion before a test case
+finishes (or else be suppressed altogether); otherwise there might be unintended interference
+between test cases leading to brittle tests. Each test case should start from a known, clean and
+quiescent environment.
+
+### Resolution
+
+Identify where the promise is created and make sure to `await` on it. Even when the result is void,
+some other part of the program might assume the asynchronous computation has completed. Without
+awaiting it at that point a race condition can result, leading to intermittent stability issues.
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: unfulfilledPromise
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appland/scanner",
-  "version": "1.84.0",
+  "version": "1.85.0",
   "description": "Analyze AppMaps for code flaws",
   "bin": "built/cli.js",
   "main": "built/index.js",