@stacks/rendezvous 0.7.4 → 0.9.0

package/README.md

@@ -56,6 +56,7 @@ npx rv <path-to-clarinet-project> <contract-name> <type>
 - `--path` – The path to use for the replay functionality.
 - `--runs` – The number of test iterations to use for exercising the contracts.
   (default: `100`)
+- `--bail` – Stop after the first failure.
 - `--dial` – The path to a JavaScript file containing custom pre- and
   post-execution functions (dialers).
 

package/dist/app.js

@@ -94,10 +94,12 @@ const helpMessage = `
     --seed - The seed to use for the replay functionality.
     --path - The path to use for the replay functionality.
     --runs - The runs to use for iterating over the tests. Default: 100.
+    --bail - Stop after the first failure.
     --dial – The path to a JavaScript file containing custom pre- and post-execution functions (dialers).
     --help - Show the help message.
   `;
-const parseOptionalArgument = (argName) => {
+const parseBooleanOption = (argName) => process.argv.slice(4).includes(`--${argName}`);
+const parseOption = (argName) => {
     var _a;
     return (_a = process.argv
         .find((arg, idx) => idx >= 4 && arg.toLowerCase().startsWith(`--${argName}`))) === null || _a === void 0 ? void 0 : _a.split("=")[1];
@@ -140,24 +142,28 @@ function main() {
         const manifestPath = (0, path_1.join)(manifestDir, (0, exports.getManifestFileName)(manifestDir, sutContractName));
         radio.emit("logMessage", `Using manifest path: ${manifestPath}`);
         radio.emit("logMessage", `Target contract: ${sutContractName}`);
-        const seed = parseInt(parseOptionalArgument("seed"), 10) || undefined;
+        const seed = parseInt(parseOption("seed"), 10) || undefined;
         if (seed !== undefined) {
             radio.emit("logMessage", `Using seed: ${seed}`);
         }
-        const path = parseOptionalArgument("path") || undefined;
+        const path = parseOption("path") || undefined;
         if (path !== undefined) {
             radio.emit("logMessage", `Using path: ${path}`);
         }
-        const runs = parseInt(parseOptionalArgument("runs"), 10) || undefined;
+        const runs = parseInt(parseOption("runs"), 10) || undefined;
         if (runs !== undefined) {
             radio.emit("logMessage", `Using runs: ${runs}`);
         }
+        const bail = parseBooleanOption("bail");
+        if (bail) {
+            radio.emit("logMessage", `Bailing on first failure.`);
+        }
         /**
          * The path to the dialer file. The dialer file allows the user to register
          * custom pre and post-execution JavaScript functions to be executed before
          * and after the public function calls during invariant testing.
          */
-        const dialPath = parseOptionalArgument("dial") || undefined;
+        const dialPath = parseOption("dial") || undefined;
         if (dialPath !== undefined) {
             radio.emit("logMessage", `Using dial path: ${dialPath}`);
         }
@@ -181,11 +187,11 @@ function main() {
         // If "test", call `checkProperties` for property-based testing.
         switch (type) {
             case "invariant": {
-                yield (0, invariant_1.checkInvariants)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, dialerRegistry, radio);
+                yield (0, invariant_1.checkInvariants)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, bail, dialerRegistry, radio);
                 break;
             }
             case "test": {
-                (0, property_1.checkProperties)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio);
+                (0, property_1.checkProperties)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, bail, radio);
                 break;
             }
         }

package/dist/heatstroke.js

@@ -20,7 +20,7 @@ const shared_1 = require("./shared");
  * @param type The type of test that failed: invariant or property.
  * @returns void
  */
-function reporter(runDetails, radio, type) {
+function reporter(runDetails, radio, type, statistics) {
     var _a, _b;
     if (runDetails.failed) {
         // Report general run data.
@@ -79,4 +79,115 @@ function reporter(runDetails, radio, type) {
     else {
         radio.emit("logMessage", (0, ansicolor_1.green)(`\nOK, ${type === "invariant" ? "invariants" : "properties"} passed after ${runDetails.numRuns} runs.\n`));
     }
+    reportStatistics(statistics, type, radio);
+    radio.emit("logMessage", "\n");
 }
+const ARROW = "->";
+const SUCCESS_SYMBOL = "+";
+const FAIL_SYMBOL = "-";
+const WARN_SYMBOL = "!";
+/**
+ * Reports execution statistics in a tree-like format.
+ * @param statistics The statistics object containing test execution data.
+ * @param type The type of test being reported.
+ * @param radio The event emitter for logging messages.
+ */
+function reportStatistics(statistics, type, radio) {
+    if ((type === "invariant" && (!statistics.invariant || !statistics.sut)) ||
+        (type === "test" && !statistics.test)) {
+        radio.emit("logMessage", "No statistics available for this run");
+        return;
+    }
+    radio.emit("logMessage", `\nEXECUTION STATISTICS\n`);
+    switch (type) {
+        case "invariant": {
+            radio.emit("logMessage", "│ PUBLIC FUNCTION CALLS");
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", `├─ ${SUCCESS_SYMBOL} SUCCESSFUL`);
+            logAsTree(Object.fromEntries(statistics.sut.successful), radio);
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", `├─ ${FAIL_SYMBOL} IGNORED`);
+            logAsTree(Object.fromEntries(statistics.sut.failed), radio);
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", "│ INVARIANT CHECKS");
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", `├─ ${SUCCESS_SYMBOL} PASSED`);
+            logAsTree(Object.fromEntries(statistics.invariant.successful), radio);
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", `└─ ${FAIL_SYMBOL} FAILED`);
+            logAsTree(Object.fromEntries(statistics.invariant.failed), radio, {
+                isLastSection: true,
+            });
+            radio.emit("logMessage", "\nLEGEND:\n");
+            radio.emit("logMessage", "  SUCCESSFUL calls executed and advanced the test");
+            radio.emit("logMessage", "  IGNORED    calls failed but did not affect the test");
+            radio.emit("logMessage", "  PASSED     invariants maintained system integrity");
+            radio.emit("logMessage", "  FAILED     invariants indicate contract vulnerabilities");
+            if (computeTotalCount(statistics.invariant.failed) > 0) {
+                radio.emit("logFailure", "\n! FAILED invariants require immediate attention as they indicate that your contract can enter an invalid state under certain conditions.");
+            }
+            break;
+        }
+        case "test": {
+            radio.emit("logMessage", "│ PROPERTY TEST CALLS");
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", `├─ ${SUCCESS_SYMBOL} PASSED`);
+            logAsTree(Object.fromEntries(statistics.test.successful), radio);
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", `├─ ${WARN_SYMBOL} DISCARDED`);
+            logAsTree(Object.fromEntries(statistics.test.discarded), radio);
+            radio.emit("logMessage", "│");
+            radio.emit("logMessage", `└─ ${FAIL_SYMBOL} FAILED`);
+            logAsTree(Object.fromEntries(statistics.test.failed), radio, {
+                isLastSection: true,
+            });
+            radio.emit("logMessage", "\nLEGEND:\n");
+            radio.emit("logMessage", "  PASSED    properties verified for given inputs");
+            radio.emit("logMessage", "  DISCARDED skipped due to invalid preconditions");
+            radio.emit("logMessage", "  FAILED    property violations or unexpected behavior");
+            if (computeTotalCount(statistics.test.failed) > 0) {
+                radio.emit("logFailure", "\n! FAILED tests indicate that your function properties don't hold for all inputs. Review the counterexamples above for debugging.");
+            }
+            break;
+        }
+    }
+}
+/**
+ * Displays a tree structure of data.
+ * @param tree The object to display as a tree.
+ * @param radio The event emitter for logging messages.
+ * @param options Configuration options for tree display.
+ */
+function logAsTree(tree, radio, options = {}) {
+    const { isLastSection = false, baseIndent = "   " } = options;
+    const printTree = (node, indent = baseIndent, isLastParent = true, radio) => {
+        const keys = Object.keys(node);
+        keys.forEach((key, index) => {
+            const isLast = index === keys.length - 1;
+            const connector = isLast ? "└─" : "├─";
+            const nextIndent = indent + (isLastParent ? "   " : "│  ");
+            const leadingChar = isLastSection ? " " : "│";
+            if (typeof node[key] === "object" && node[key] !== null) {
+                radio.emit("logMessage", `${leadingChar} ${indent}${connector} ${ARROW} ${key}`);
+                printTree(node[key], nextIndent, isLast, radio);
+            }
+            else {
+                const count = node[key];
+                radio.emit("logMessage", `${leadingChar} ${indent}${connector} ${key}: x${count}`);
+            }
+        });
+    };
+    printTree(tree, baseIndent, true, radio);
+}
+/**
+ * Computes the total number of failures from a failure map.
+ * @param failedMap Map containing failure counts by test name
+ * @returns The sum of all failure counts
+ */
+const computeTotalCount = (failedMap) => {
+    let totalFailures = 0;
+    for (const count of failedMap.values()) {
+        totalFailures += count;
+    }
+    return totalFailures;
+};

package/dist/invariant.js

@@ -31,22 +31,42 @@ const dialer_1 = require("./dialer");
  * @param seed The seed for reproducible invariant testing.
  * @param path The path for reproducible invariant testing.
  * @param runs The number of test runs.
+ * @param bail Stop execution after the first failure and prevent further
+ * shrinking.
  * @param dialerRegistry The custom dialer registry.
  * @param radio The custom logging event emitter.
  * @returns void
  */
-const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, dialerRegistry, radio) => __awaiter(void 0, void 0, void 0, function* () {
+const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, bail, dialerRegistry, radio) => __awaiter(void 0, void 0, void 0, function* () {
+    const statistics = {
+        sut: {
+            successful: new Map(),
+            failed: new Map(),
+        },
+        invariant: {
+            successful: new Map(),
+            failed: new Map(),
+        },
+    };
     // A map where the keys are the Rendezvous identifiers and the values are
     // arrays of their SUT (System Under Test) functions. This map will be used
     // to access the SUT functions for each Rendezvous contract afterwards.
     const rendezvousSutFunctions = filterSutFunctions(rendezvousAllFunctions);
+    // The Rendezvous identifier is the first one in the list. Only one contract
+    // can be fuzzed at a time.
+    const rendezvousContractId = rendezvousList[0];
+    for (const functionInterface of rendezvousSutFunctions.get(rendezvousContractId)) {
+        statistics.sut.successful.set(functionInterface.name, 0);
+        statistics.sut.failed.set(functionInterface.name, 0);
+    }
     // A map where the keys are the Rendezvous identifiers and the values are
     // arrays of their invariant functions. This map will be used to access the
     // invariant functions for each Rendezvous contract afterwards.
     const rendezvousInvariantFunctions = filterInvariantFunctions(rendezvousAllFunctions);
-    // The Rendezvous identifier is the first one in the list. Only one contract
-    // can be fuzzed at a time.
-    const rendezvousContractId = rendezvousList[0];
+    for (const functionInterface of rendezvousInvariantFunctions.get(rendezvousContractId)) {
+        statistics.invariant.successful.set(functionInterface.name, 0);
+        statistics.invariant.failed.set(functionInterface.name, 0);
+    }
     const traitReferenceSutFunctions = rendezvousSutFunctions
         .get(rendezvousContractId)
         .filter((fn) => (0, traits_1.isTraitReferenceFunction)(fn));
@@ -93,7 +113,7 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
         return;
     }
     const radioReporter = (runDetails) => {
-        (0, heatstroke_1.reporter)(runDetails, radio, "invariant");
+        (0, heatstroke_1.reporter)(runDetails, radio, "invariant", statistics);
     };
     yield fast_check_1.default.assert(fast_check_1.default.asyncProperty(fast_check_1.default
         .record({
@@ -176,6 +196,7 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
                 // call during the run.
                 const selectedFunctionClarityResult = (0, transactions_1.cvToString)(functionCall.result);
                 if (functionCallResultJson.success) {
+                    statistics.sut.successful.set(selectedFunction.name, statistics.sut.successful.get(selectedFunction.name) + 1);
                     localContext[r.rendezvousContractId][selectedFunction.name]++;
                     simnet.callPublicFn(r.rendezvousContractId, "update-context", [
                         transactions_1.Cl.stringAscii(selectedFunction.name),
@@ -204,6 +225,7 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
                 }
                 else {
                     // Function call failed.
+                    statistics.sut.failed.set(selectedFunction.name, statistics.sut.failed.get(selectedFunction.name) + 1);
                     radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
                         `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                         `${sutCallerWallet}        ` +
@@ -255,6 +277,8 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
             const invariantCallResultJson = (0, transactions_1.cvToJSON)(invariantCallResult);
             const invariantCallClarityResult = (0, transactions_1.cvToString)(invariantCallResult);
             if (invariantCallResultJson.value === true) {
+                statistics.invariant.successful.set(r.selectedInvariant.name, statistics.invariant.successful.get(r.selectedInvariant.name) +
+                    1);
                 radio.emit("logMessage", `₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
                     `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                     `${(0, ansicolor_1.dim)(invariantCallerWallet)} ` +
@@ -265,6 +289,7 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
                     (0, ansicolor_1.green)(invariantCallClarityResult));
             }
             else {
+                statistics.invariant.failed.set(r.selectedInvariant.name, statistics.invariant.failed.get(r.selectedInvariant.name) + 1);
                 radio.emit("logMessage", (0, ansicolor_1.red)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
                     `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                     `${invariantCallerWallet} ` +
@@ -298,11 +323,12 @@ const checkInvariants = (simnet, targetContractName, rendezvousList, rendezvousA
             simnet.mineEmptyBurnBlocks(r.burnBlocks);
         }
     })), {
-        verbose: true,
+        endOnFailure: bail,
+        numRuns: runs,
+        path: path,
         reporter: radioReporter,
         seed: seed,
-        path: path,
-        numRuns: runs,
+        verbose: true,
     });
 });
 exports.checkInvariants = checkInvariants;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stacks/rendezvous",
-    "version": "0.7.4",
+    "version": "0.9.0",
     "description": "Meet your contract's vulnerabilities head-on.",
     "main": "app.js",
     "bin": {

package/dist/property.js

@@ -21,15 +21,29 @@ const traits_1 = require("./traits");
  * @param seed The seed for reproducible property-based tests.
  * @param path The path for reproducible property-based tests.
  * @param runs The number of test runs.
+ * @param bail Stop execution after the first failure and prevent further
+ * shrinking.
  * @param radio The custom logging event emitter.
  * @returns void
  */
-const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio) => {
+const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, bail, radio) => {
+    const statistics = {
+        test: {
+            successful: new Map(),
+            discarded: new Map(),
+            failed: new Map(),
+        },
+    };
     const testContractId = rendezvousList[0];
     // A map where the keys are the test contract identifiers and the values are
     // arrays of their test functions. This map will be used to access the test
     // functions for each test contract in the property-based testing routine.
     const testContractsTestFunctions = filterTestFunctions(rendezvousAllFunctions);
+    for (const functionInterface of testContractsTestFunctions.get(testContractId)) {
+        statistics.test.successful.set(functionInterface.name, 0);
+        statistics.test.discarded.set(functionInterface.name, 0);
+        statistics.test.failed.set(functionInterface.name, 0);
+    }
     const traitReferenceFunctions = testContractsTestFunctions
         .get(testContractId)
         .filter((fn) => (0, traits_1.isTraitReferenceFunction)(fn));
@@ -79,7 +93,7 @@ const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousA
         return;
     }
     const radioReporter = (runDetails) => {
-        (0, heatstroke_1.reporter)(runDetails, radio, "test");
+        (0, heatstroke_1.reporter)(runDetails, radio, "test", statistics);
     };
     fast_check_1.default.assert(fast_check_1.default.property(fast_check_1.default
         .record({
@@ -132,6 +146,7 @@ const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousA
             .get(r.selectedTestFunction.name);
         const discarded = isTestDiscarded(discardFunctionName, selectedTestFunctionArgs, r.testContractId, simnet, testCallerAddress);
         if (discarded) {
+            statistics.test.discarded.set(r.selectedTestFunction.name, statistics.test.discarded.get(r.selectedTestFunction.name) + 1);
             radio.emit("logMessage", `₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
                 `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                 `${(0, ansicolor_1.dim)(testCallerWallet)} ` +
@@ -149,6 +164,7 @@ const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousA
                 const discardedInPlace = (0, exports.isTestDiscardedInPlace)(testFunctionCallResultJson);
                 const testFunctionCallClarityResult = (0, transactions_1.cvToString)(testFunctionCallResult);
                 if (discardedInPlace) {
+                    statistics.test.discarded.set(r.selectedTestFunction.name, statistics.test.discarded.get(r.selectedTestFunction.name) + 1);
                     radio.emit("logMessage", `₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
                         `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                         `${(0, ansicolor_1.dim)(testCallerWallet)} ` +
@@ -161,6 +177,8 @@ const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousA
                 else if (!discardedInPlace &&
                     testFunctionCallResultJson.success &&
                     testFunctionCallResultJson.value.value === true) {
+                    statistics.test.successful.set(r.selectedTestFunction.name, statistics.test.successful.get(r.selectedTestFunction.name) +
+                        1);
                     radio.emit("logMessage", `₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
                         `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                         `${(0, ansicolor_1.dim)(testCallerWallet)} ` +
@@ -174,6 +192,7 @@ const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousA
                     }
                 }
                 else {
+                    statistics.test.failed.set(r.selectedTestFunction.name, statistics.test.failed.get(r.selectedTestFunction.name) + 1);
                     // The function call did not result in (ok true) or (ok false).
                     // Either the test failed or the test function returned an
                     // unexpected value i.e. `(ok 1)`.
@@ -202,11 +221,12 @@ const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousA
             }
         }
     }), {
-        verbose: true,
+        endOnFailure: bail,
+        numRuns: runs,
+        path: path,
         reporter: radioReporter,
         seed: seed,
-        path: path,
-        numRuns: runs,
+        verbose: true,
     });
 };
 exports.checkProperties = checkProperties;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacks/rendezvous",
-  "version": "0.7.4",
+  "version": "0.9.0",
   "description": "Meet your contract's vulnerabilities head-on.",
   "main": "app.js",
   "bin": {