@stacks/rendezvous 0.2.0 → 0.4.0

package/README.md

@@ -56,6 +56,8 @@ 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`)
+- `--dial` – The path to a JavaScript file containing custom pre- and
+  post-execution functions (dialers).
 
 ---
 

package/dist/app.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getManifestFileName = void 0;
 exports.main = main;
 const path_1 = require("path");
 const events_1 = require("events");
@@ -19,13 +20,31 @@ const shared_1 = require("./shared");
 const citizen_1 = require("./citizen");
 const package_json_1 = require("./package.json");
 const ansicolor_1 = require("ansicolor");
+const fs_1 = require("fs");
+const dialer_1 = require("./dialer");
 const logger = (log, logLevel = "log") => {
     console[logLevel](log);
 };
+/**
+ * Gets the manifest file name for a Clarinet project.
+ * If a custom manifest exists (`Clarinet-<contract-name>.toml`), it is used.
+ * Otherwise, the default `Clarinet.toml` is returned.
+ * @param manifestDir The relative path to the Clarinet project directory.
+ * @param targetContractName The target contract name.
+ * @returns The manifest file name.
+ */
+const getManifestFileName = (manifestDir, targetContractName) => {
+    const isCustomManifest = (0, fs_1.existsSync)((0, path_1.resolve)(manifestDir, `Clarinet-${targetContractName}.toml`));
+    if (isCustomManifest) {
+        return `Clarinet-${targetContractName}.toml`;
+    }
+    return "Clarinet.toml";
+};
+exports.getManifestFileName = getManifestFileName;
 const helpMessage = `
   rv v${package_json_1.version}
   
-  Usage: rv <path-to-clarinet-project> <contract-name> <type> [--seed=<seed>] [--path=<path>] [--runs=<runs>]
+  Usage: rv <path-to-clarinet-project> <contract-name> <type> [--seed=<seed>] [--path=<path>] [--runs=<runs>] [--dial=<path-to-dialers-file>] [--help]
 
   Positional arguments:
     path-to-clarinet-project - The path to the Clarinet project.
@@ -36,6 +55,7 @@ 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.
+    --dial – The path to a JavaScript file containing custom pre- and post-execution functions (dialers).
     --help - Show the help message.
   `;
 const parseOptionalArgument = (argName) => {
@@ -74,8 +94,11 @@ function main() {
             radio.emit("logMessage", helpMessage);
             return;
         }
-        /** The relative path to `Clarinet.toml`. */
-        const manifestPath = (0, path_1.join)(manifestDir, "Clarinet.toml");
+        /**
+         * The relative path to the manifest file, either `Clarinet.toml` or
+         * `Clarinet-<contract-name>.toml`. If the latter exists, it is used.
+         */
+        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;
@@ -90,7 +113,24 @@ function main() {
         if (runs !== undefined) {
             radio.emit("logMessage", `Using runs: ${runs}`);
         }
-        const simnet = yield (0, citizen_1.issueFirstClassCitizenship)(manifestDir, sutContractName);
+        /**
+         * 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;
+        if (dialPath !== undefined) {
+            radio.emit("logMessage", `Using dial path: ${dialPath}`);
+        }
+        /**
+         * The dialer registry, which is used to keep track of all the custom dialers
+         * registered by the user using the `--dial` flag.
+         */
+        const dialerRegistry = dialPath !== undefined ? new dialer_1.DialerRegistry(dialPath) : undefined;
+        if (dialerRegistry !== undefined) {
+            dialerRegistry.registerDialers();
+        }
+        const simnet = yield (0, citizen_1.issueFirstClassCitizenship)(manifestDir, manifestPath, sutContractName);
         /**
          * The list of contract IDs for the SUT contract names, as per the simnet.
          */
@@ -101,7 +141,7 @@ function main() {
         // If "test", call `checkProperties` for property-based testing.
         switch (type) {
             case "invariant": {
-                (0, invariant_1.checkInvariants)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio);
+                yield (0, invariant_1.checkInvariants)(simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, dialerRegistry, radio);
                 break;
             }
             case "test": {

package/dist/citizen.js

@@ -19,20 +19,20 @@ const path_1 = require("path");
 const yaml_1 = __importDefault(require("yaml"));
 const clarinet_sdk_1 = require("@hirosystems/clarinet-sdk");
 /**
- * Prepares the simnet environment and assures the target contract is treated
- * as a first-class citizen, by combining it with its tests. This function
- * handles:
+ * Prepares the simnet instance and assures the target contract's corresponding
+ * test contract is treated as a first-class citizen, relying on their
+ * concatenation. This function handles:
  * - Contract sorting by epoch based on the deployment plan.
  * - Combining the target contract with its tests and deploying all contracts
  *   to the simnet.
  *
- * @param manifestDir - The relative path to the manifest directory.
- * @param sutContractName - The target contract name.
+ * @param manifestDir The relative path to the manifest directory.
+ * @param manifestPath The absolute path to the manifest file.
+ * @param sutContractName The target contract name.
  * @returns The initialized simnet instance with all contracts deployed, with
- * the target contract treated as a first-class citizen.
+ * the test contract treated as a first-class citizen of the target contract.
  */
-const issueFirstClassCitizenship = (manifestDir, sutContractName) => __awaiter(void 0, void 0, void 0, function* () {
-    const manifestPath = (0, path_1.join)(manifestDir, "Clarinet.toml");
+const issueFirstClassCitizenship = (manifestDir, manifestPath, sutContractName) => __awaiter(void 0, void 0, void 0, function* () {
     // Initialize the simnet, to generate the simnet plan and instance. The empty
     // session will be set up, and contracts will be deployed in the correct
     // order based on the simnet plan a few lines below.
@@ -43,8 +43,8 @@ const issueFirstClassCitizenship = (manifestDir, sutContractName) => __awaiter(v
     const sortedContractsByEpoch = (0, exports.groupContractsByEpochFromSimnetPlan)(simnetPlan);
     yield simnet.initEmptySession();
     // Combine the target contract with its tests into a single contract. The
-    // resulting contract will replace the target contract in the simnet. This
-    // map stores the contract name and its corresponding source code.
+    // resulting contract will replace the target contract in the simnet.
+    /** The contract names mapped to the concatenated source code. */
     const rendezvousSources = new Map([sutContractName]
         .map((contractName) => (0, exports.buildRendezvousData)(simnetPlan, contractName, manifestDir))
         .map((rendezvousContractData) => [
@@ -58,7 +58,7 @@ const issueFirstClassCitizenship = (manifestDir, sutContractName) => __awaiter(v
 exports.issueFirstClassCitizenship = issueFirstClassCitizenship;
 /**
  * Groups contracts by epoch from the simnet plan.
- * @param simnetPlan - The simnet plan.
+ * @param simnetPlan The simnet plan.
  * @returns A record of contracts grouped by epoch. The record key is the epoch
  * string, and the value is an array of contracts. Each contract is represented
  * as a record with the contract name as the key and a record containing the
@@ -86,10 +86,10 @@ const groupContractsByEpochFromSimnetPlan = (simnetPlan) => {
 };
 exports.groupContractsByEpochFromSimnetPlan = groupContractsByEpochFromSimnetPlan;
 /**
- * Deploy the contracts to the simnet in the correct order.
+ * Deploys the contracts to the simnet in the correct order.
  * @param simnet The simnet instance.
- * @param contractsByEpoch - The record of contracts by epoch.
- * @param getContractSourceFn - The function to retrieve the contract source.
+ * @param contractsByEpoch The record of contracts by epoch.
+ * @param getContractSourceFn The function to retrieve the contract source.
  */
 const deployContracts = (simnet, contractsByEpoch, getContractSourceFn) => __awaiter(void 0, void 0, void 0, function* () {
     for (const [epoch, contracts] of Object.entries(contractsByEpoch)) {
@@ -109,18 +109,19 @@ const deployContracts = (simnet, contractsByEpoch, getContractSourceFn) => __awa
     }
 });
 /**
- * Conditionally retrieve the contract source based on whether the contract is
+ * Conditionally retrieves the contract source based on whether the contract is
  * a SUT contract or not.
- * @param sutContractNames - The list of SUT contract names.
- * @param rendezvousMap - The rendezvous map.
- * @param contractName - The contract name.
- * @param contractProps - The contract properties.
- * @param manifestDir - The relative path to the manifest directory.
- * @returns The contract source.
+ * @param targetContractNames The list of target contract names.
+ * @param rendezvousSourcesMap The contract names mapped to the concatenated
+ * source code.
+ * @param contractName The contract name.
+ * @param contractProps The contract deployment properties.
+ * @param manifestDir The relative path to the manifest directory.
+ * @returns The contract source code.
  */
-const getContractSource = (sutContractNames, rendezvousMap, contractName, contractProps, manifestDir) => {
-    if (sutContractNames.includes(contractName)) {
-        const contractSource = rendezvousMap.get(contractName);
+const getContractSource = (targetContractNames, rendezvousSourcesMap, contractName, contractProps, manifestDir) => {
+    if (targetContractNames.includes(contractName)) {
+        const contractSource = rendezvousSourcesMap.get(contractName);
         if (!contractSource) {
             throw new Error(`Contract source not found for ${contractName}`);
         }
@@ -134,11 +135,11 @@ const getContractSource = (sutContractNames, rendezvousMap, contractName, contra
 };
 exports.getContractSource = getContractSource;
 /**
- * Build the Rendezvous data.
+ * Builds the Rendezvous data.
  * @param simnetPlan The parsed simnet plan.
  * @param contractName The contract name.
  * @param manifestDir The relative path to the manifest directory.
- * @returns The Rendezvous data representing an object. The returned object
+ * @returns The Rendezvous data representing a record. The returned record
  * contains the Rendezvous source code and the Rendezvous contract name.
  */
 const buildRendezvousData = (simnetPlan, contractName, manifestDir) => {
@@ -151,13 +152,13 @@ const buildRendezvousData = (simnetPlan, contractName, manifestDir) => {
             rendezvousContractName: contractName,
         };
     }
-    catch (e) {
-        throw new Error(`Error processing "${contractName}" contract: ${e.message}`);
+    catch (error) {
+        throw new Error(`Error processing "${contractName}" contract: ${error.message}`);
     }
 };
 exports.buildRendezvousData = buildRendezvousData;
 /**
- * Get the contract source code from the simnet plan.
+ * Retrieves the contract source code using the simnet plan.
  * @param simnetPlan The parsed simnet plan.
  * @param manifestDir The relative path to the manifest directory.
  * @param sutContractName The target contract name.
@@ -179,7 +180,7 @@ const getSimnetPlanContractSource = (simnetPlan, manifestDir, sutContractName) =
     }).toString();
 };
 /**
- * Get the test contract source code.
+ * Retrieves the test contract source code.
  * @param simnetPlan The parsed simnet plan.
  * @param sutContractName The target contract name.
  * @param manifestDir The relative path to the manifest directory.
@@ -203,19 +204,19 @@ const getTestContractSource = (simnetPlan, sutContractName, manifestDir) => {
             encoding: "utf-8",
         }).toString();
     }
-    catch (e) {
-        throw new Error(`Error retrieving the corresponding test contract for the "${sutContractName}" contract. ${e.message}`);
+    catch (error) {
+        throw new Error(`Error retrieving the corresponding test contract for the "${sutContractName}" contract. ${error.message}`);
     }
 };
 exports.getTestContractSource = getTestContractSource;
 /**
- * Schedule a Rendezvous between the System Under Test (`SUT`) and the
- * invariants.
- * @param sutContractSource The SUT contract source code.
- * @param invariants The invariants contract source code.
+ * Schedules a Rendezvous between the System Under Test (`SUT`) and the test
+ * contract.
+ * @param targetContractSource The target contract source code.
+ * @param tests The corresponding test contract source code.
  * @returns The Rendezvous source code.
  */
-function scheduleRendezvous(sutContractSource, invariants) {
+function scheduleRendezvous(targetContractSource, tests) {
     /**
      * The `context` map tracks how many times each function has been called.
      * This data can be useful for invariant tests to check behavior over time.
@@ -227,5 +228,5 @@ function scheduleRendezvous(sutContractSource, invariants) {
 
   (define-public (update-context (function-name (string-ascii 100)) (called uint))
     (ok (map-set context function-name {called: called})))`;
-    return `${sutContractSource}\n\n${context}\n\n${invariants}`;
+    return `${targetContractSource}\n\n${context}\n\n${tests}`;
 }

package/dist/dialer.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostDialerError = exports.PreDialerError = exports.DialerRegistry = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// In telephony, a registry is used for maintaining a known set of handlers,
+// devices, or processes. This aligns with this class's purpose. Dialers are
+// loaded/stored and run in a structured way, so "registry" fits both telephony
+// and DI semantics.
+class DialerRegistry {
+    constructor(dialPath) {
+        this.preDialers = [];
+        this.postDialers = [];
+        this.dialPath = dialPath;
+    }
+    registerPreDialer(dialer) {
+        this.preDialers.push(dialer);
+    }
+    registerPostDialer(dialer) {
+        this.postDialers.push(dialer);
+    }
+    registerDialers() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const resolvedDialPath = (0, path_1.resolve)(this.dialPath);
+            if (!(0, fs_1.existsSync)(resolvedDialPath)) {
+                console.error(`Error: Dialer file not found: ${resolvedDialPath}`);
+                process.exit(1);
+            }
+            try {
+                const userModule = yield Promise.resolve(`${resolvedDialPath}`).then(s => __importStar(require(s)));
+                Object.entries(userModule).forEach(([key, fn]) => {
+                    if (typeof fn === "function") {
+                        if (key.startsWith("pre")) {
+                            this.registerPreDialer(fn);
+                        }
+                        else if (key.startsWith("post")) {
+                            this.registerPostDialer(fn);
+                        }
+                    }
+                });
+            }
+            catch (error) {
+                console.error(`Failed to load dialers:`, error);
+                process.exit(1);
+            }
+        });
+    }
+    executePreDialers(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.preDialers.length === 0) {
+                return;
+            }
+            for (const dial of this.preDialers) {
+                yield dial(context);
+            }
+        });
+    }
+    executePostDialers(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.postDialers.length === 0) {
+                return;
+            }
+            for (const dial of this.postDialers) {
+                yield dial(context);
+            }
+        });
+    }
+}
+exports.DialerRegistry = DialerRegistry;
+class PreDialerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "Pre-dialer error";
+    }
+}
+exports.PreDialerError = PreDialerError;
+class PostDialerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "Post-dialer error";
+    }
+}
+exports.PostDialerError = PostDialerError;

package/dist/dialer.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/heatstroke.js

@@ -1,38 +1,29 @@
 "use strict";
-/**
- * Heatstrokes Reporter
- *
- * This reporter integrates with `fast-check` to provide detailed and formatted
- * outputs for failed property-based tests. It captures key information such as
- * the contract, functions, arguments, outputs, and the specific invariant that
- * failed, enabling quick identification of issues.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reporter = reporter;
+const ansicolor_1 = require("ansicolor");
+const shared_1 = require("./shared");
 /**
- * Reports the details of a failed property-based test run.
- *
- * This function provides a detailed report when a fuzzing test fails including
- * the contract, functions, arguments, outputs, and the specific invariant that
- * failed.
+ * Heatstrokes Reporter
  *
- * @param runDetails - The details of the test run provided by fast-check.
- * @property runDetails.failed - Indicates if the property test failed.
- * @property runDetails.counterexample - The input that caused the failure.
- * @property runDetails.numRuns - The number of test cases that were run.
- * @property runDetails.seed - The seed used to generate the test cases.
- * @property runDetails.path - The path to reproduce the failing test.
- * @property runDetails.error - The error thrown during the test.
+ * Provides a detailed report when a test run test ends. In case of failure,
+ * includes the contract, functions, arguments, outputs, and the specific
+ * invariant or property test that failed.
+ * @param runDetails The details of the test run provided by fast-check.
+ * @property `runDetails.failed`: Indicates if the test run failed.
+ * @property `runDetails.counterexample`: The input that caused the failure.
+ * @property `runDetails.numRuns`: The number of test cases that were run.
+ * @property `runDetails.seed`: The replay seed for reproducing the failure.
+ * @property `runDetails.path`: The replay path for reproducing the failure.
+ * @property `runDetails.error`: The error thrown during the test.
+ * @param radio The event emitter to log messages.
+ * @param type The type of test that failed: invariant or property.
+ * @returns void
  */
-const ansicolor_1 = require("ansicolor");
-const shared_1 = require("./shared");
-function reporter(
-//@ts-ignore
-runDetails, radio, type) {
+function reporter(runDetails, radio, type) {
     var _a, _b;
     if (runDetails.failed) {
         // Report general run data.
-        const r = runDetails.counterexample[0];
         radio.emit("logFailure", `\nError: Property failed after ${runDetails.numRuns} tests.`);
         radio.emit("logFailure", `Seed : ${runDetails.seed}`);
         if (runDetails.path) {
@@ -40,15 +31,26 @@ runDetails, radio, type) {
         }
         switch (type) {
             case "invariant": {
+                const r = runDetails.counterexample[0];
                 // Report specific run data for the invariant testing type.
                 radio.emit("logFailure", `\nCounterexample:`);
                 radio.emit("logFailure", `- Contract : ${(0, shared_1.getContractNameFromContractId)(r.rendezvousContractId)}`);
-                radio.emit("logFailure", `- Function : ${r.selectedFunction.name} (${r.selectedFunction.access})`);
-                radio.emit("logFailure", `- Arguments: ${JSON.stringify(r.functionArgsArb)}`);
-                radio.emit("logFailure", `- Caller   : ${r.sutCaller[0]}`);
-                radio.emit("logFailure", `- Outputs  : ${JSON.stringify(r.selectedFunction.outputs)}`);
+                radio.emit("logFailure", `- Functions: ${r.selectedFunctions
+                    .map((selectedFunction) => selectedFunction.name)
+                    .join(", ")} (${r.selectedFunctions
+                    .map((selectedFunction) => selectedFunction.access)
+                    .join(", ")})`);
+                radio.emit("logFailure", `- Arguments: ${r.selectedFunctionsArgsList
+                    .map((selectedFunctionArgs) => JSON.stringify(selectedFunctionArgs))
+                    .join(", ")}`);
+                radio.emit("logFailure", `- Callers  : ${r.sutCallers
+                    .map((sutCaller) => sutCaller[0])
+                    .join(", ")}`);
+                radio.emit("logFailure", `- Outputs  : ${r.selectedFunctions
+                    .map((selectedFunction) => JSON.stringify(selectedFunction.outputs))
+                    .join(", ")}`);
                 radio.emit("logFailure", `- Invariant: ${r.selectedInvariant.name} (${r.selectedInvariant.access})`);
-                radio.emit("logFailure", `- Arguments: ${JSON.stringify(r.invariantArgsArb)}`);
+                radio.emit("logFailure", `- Arguments: ${JSON.stringify(r.invariantArgs)}`);
                 radio.emit("logFailure", `- Caller   : ${r.invariantCaller[0]}`);
                 radio.emit("logFailure", `\nWhat happened? Rendezvous went on a rampage and found a weak spot:\n`);
                 const formattedError = `The invariant "${r.selectedInvariant.name}" returned:\n\n${(_a = runDetails.error) === null || _a === void 0 ? void 0 : _a.toString().split("\n").map((line) => "    " + line).join("\n")}\n`;
@@ -56,11 +58,12 @@ runDetails, radio, type) {
                 break;
             }
             case "test": {
+                const r = runDetails.counterexample[0];
                 // Report specific run data for the property testing type.
                 radio.emit("logFailure", `\nCounterexample:`);
                 radio.emit("logFailure", `- Test Contract : ${(0, shared_1.getContractNameFromContractId)(r.testContractId)}`);
                 radio.emit("logFailure", `- Test Function : ${r.selectedTestFunction.name} (${r.selectedTestFunction.access})`);
-                radio.emit("logFailure", `- Arguments     : ${JSON.stringify(r.functionArgsArb)}`);
+                radio.emit("logFailure", `- Arguments     : ${JSON.stringify(r.functionArgs)}`);
                 radio.emit("logFailure", `- Caller        : ${r.testCaller[0]}`);
                 radio.emit("logFailure", `- Outputs       : ${JSON.stringify(r.selectedTestFunction.outputs)}`);
                 radio.emit("logFailure", `\nWhat happened? Rendezvous went on a rampage and found a weak spot:\n`);

package/dist/heatstroke.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/invariant.js

@@ -1,4 +1,13 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -10,7 +19,23 @@ const heatstroke_1 = require("./heatstroke");
 const fast_check_1 = __importDefault(require("fast-check"));
 const ansicolor_1 = require("ansicolor");
 const traits_1 = require("./traits");
-const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio) => {
+const dialer_1 = require("./dialer");
+/**
+ * Runs invariant testing on the target contract and logs the progress. Reports
+ * the test results through a custom reporter.
+ * @param simnet The Simnet instance.
+ * @param targetContractName The name of the target contract.
+ * @param rendezvousList The list of contract IDs for each target contract.
+ * @param rendezvousAllFunctions The map of all function interfaces for each
+ * target contract.
+ * @param seed The seed for reproducible invariant testing.
+ * @param path The path for reproducible invariant testing.
+ * @param runs The number of test runs.
+ * @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* () {
     // 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.
@@ -44,52 +69,57 @@ const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllF
         return;
     }
     const enrichedSutFunctionsInterfaces = traitReferenceSutFunctions.length > 0
-        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(sutContractName), (0, traits_1.buildTraitReferenceMap)(rendezvousSutFunctions.get(rendezvousContractId)), rendezvousSutFunctions.get(rendezvousContractId), rendezvousContractId)
+        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(targetContractName), (0, traits_1.buildTraitReferenceMap)(rendezvousSutFunctions.get(rendezvousContractId)), rendezvousSutFunctions.get(rendezvousContractId), rendezvousContractId)
         : rendezvousSutFunctions;
     const enrichedInvariantFunctionsInterfaces = traitReferenceInvariantFunctions.length > 0
-        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(sutContractName), (0, traits_1.buildTraitReferenceMap)(rendezvousInvariantFunctions.get(rendezvousContractId)), rendezvousInvariantFunctions.get(rendezvousContractId), rendezvousContractId)
+        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(targetContractName), (0, traits_1.buildTraitReferenceMap)(rendezvousInvariantFunctions.get(rendezvousContractId)), rendezvousInvariantFunctions.get(rendezvousContractId), rendezvousContractId)
         : rendezvousInvariantFunctions;
     // Set up local context to track SUT function call counts.
     const localContext = (0, exports.initializeLocalContext)(enrichedSutFunctionsInterfaces);
     // Set up context in simnet by initializing state for SUT.
     (0, exports.initializeClarityContext)(simnet, enrichedSutFunctionsInterfaces);
-    radio.emit("logMessage", `\nStarting invariant testing type for the ${sutContractName} contract...\n`);
+    radio.emit("logMessage", `\nStarting invariant testing type for the ${targetContractName} contract...\n`);
     const simnetAccounts = simnet.getAccounts();
     const eligibleAccounts = new Map([...simnetAccounts].filter(([key]) => key !== "faucet"));
     const simnetAddresses = Array.from(simnetAccounts.values());
     const functions = (0, shared_1.getFunctionsListForContract)(enrichedSutFunctionsInterfaces, rendezvousContractId);
     const invariants = (0, shared_1.getFunctionsListForContract)(enrichedInvariantFunctionsInterfaces, rendezvousContractId);
     if ((functions === null || functions === void 0 ? void 0 : functions.length) === 0) {
-        radio.emit("logMessage", (0, ansicolor_1.red)(`No public functions found for the "${sutContractName}" contract. Without public functions, no state transitions can happen inside the contract, and the invariant test is not meaningful.\n`));
+        radio.emit("logMessage", (0, ansicolor_1.red)(`No public functions found for the "${targetContractName}" contract. Without public functions, no state transitions can happen inside the contract, and the invariant test is not meaningful.\n`));
         return;
     }
     if ((invariants === null || invariants === void 0 ? void 0 : invariants.length) === 0) {
-        radio.emit("logMessage", (0, ansicolor_1.red)(`No invariant functions found for the "${sutContractName}" contract. Beware, for your contract may be exposed to unforeseen issues.\n`));
+        radio.emit("logMessage", (0, ansicolor_1.red)(`No invariant functions found for the "${targetContractName}" contract. Beware, for your contract may be exposed to unforeseen issues.\n`));
         return;
     }
     const radioReporter = (runDetails) => {
         (0, heatstroke_1.reporter)(runDetails, radio, "invariant");
     };
-    fast_check_1.default.assert(fast_check_1.default.property(fast_check_1.default
+    yield fast_check_1.default.assert(fast_check_1.default.asyncProperty(fast_check_1.default
         .record({
         // The target contract identifier. It is a constant value equal
         // to the first contract in the list. The arbitrary is still needed,
         // being used for reporting purposes in `heatstroke.ts`.
         rendezvousContractId: fast_check_1.default.constant(rendezvousContractId),
-        sutCaller: fast_check_1.default.constantFrom(...eligibleAccounts.entries()),
         invariantCaller: fast_check_1.default.constantFrom(...eligibleAccounts.entries()),
         canMineBlocks: fast_check_1.default.boolean(),
     })
         .chain((r) => fast_check_1.default
         .record({
-        selectedFunction: fast_check_1.default.constantFrom(...functions),
+        selectedFunctions: fast_check_1.default.array(fast_check_1.default.constantFrom(...functions), {
+            minLength: 1, // At least one function must be selected.
+        }),
         selectedInvariant: fast_check_1.default.constantFrom(...invariants),
     })
         .map((selectedFunctions) => (Object.assign(Object.assign({}, r), selectedFunctions))))
         .chain((r) => fast_check_1.default
         .record({
-        functionArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedFunction, simnetAddresses, projectTraitImplementations)),
-        invariantArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedInvariant, simnetAddresses, projectTraitImplementations)),
+        sutCallers: fast_check_1.default.array(fast_check_1.default.constantFrom(...eligibleAccounts.entries()), {
+            minLength: r.selectedFunctions.length,
+            maxLength: r.selectedFunctions.length,
+        }),
+        selectedFunctionsArgsList: fast_check_1.default.tuple(...r.selectedFunctions.map((selectedFunction) => fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(selectedFunction, simnetAddresses, projectTraitImplementations)))),
+        invariantArgs: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedInvariant, simnetAddresses, projectTraitImplementations)),
     })
         .map((args) => (Object.assign(Object.assign({}, r), args))))
         .chain((r) => fast_check_1.default
@@ -107,59 +137,91 @@ const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllF
                 })
             : fast_check_1.default.constant(0),
     })
-        .map((burnBlocks) => (Object.assign(Object.assign({}, r), burnBlocks)))), (r) => {
-        const selectedFunctionArgs = (0, shared_1.argsToCV)(r.selectedFunction, r.functionArgsArb);
-        const selectedInvariantArgs = (0, shared_1.argsToCV)(r.selectedInvariant, r.invariantArgsArb);
-        const printedFunctionArgs = r.functionArgsArb
-            .map((arg) => {
+        .map((burnBlocks) => (Object.assign(Object.assign({}, r), burnBlocks)))), (r) => __awaiter(void 0, void 0, void 0, function* () {
+        const selectedFunctionsArgsCV = r.selectedFunctions.map((selectedFunction, index) => (0, shared_1.argsToCV)(selectedFunction, r.selectedFunctionsArgsList[index]));
+        const selectedInvariantArgsCV = (0, shared_1.argsToCV)(r.selectedInvariant, r.invariantArgs);
+        for (const [index, selectedFunction] of r.selectedFunctions.entries()) {
+            const [sutCallerWallet, sutCallerAddress] = r.sutCallers[index];
+            const printedFunctionArgs = r.selectedFunctionsArgsList[index]
+                .map((arg) => {
+                try {
+                    return typeof arg === "object"
+                        ? JSON.stringify(arg)
+                        : arg.toString();
+                }
+                catch (_a) {
+                    return "[Circular]";
+                }
+            })
+                .join(" ");
             try {
-                return typeof arg === "object"
-                    ? JSON.stringify(arg)
-                    : arg.toString();
+                if (dialerRegistry !== undefined) {
+                    yield dialerRegistry.executePreDialers({
+                        selectedFunction: selectedFunction,
+                        functionCall: undefined,
+                        clarityValueArguments: selectedFunctionsArgsCV[index],
+                    });
+                }
             }
-            catch (_a) {
-                return "[Circular]";
+            catch (error) {
+                throw new dialer_1.PreDialerError(error.message);
             }
-        })
-            .join(" ");
-        const [sutCallerWallet, sutCallerAddress] = r.sutCaller;
-        try {
-            const { result: functionCallResult } = simnet.callPublicFn(r.rendezvousContractId, r.selectedFunction.name, selectedFunctionArgs, sutCallerAddress);
-            const functionCallResultJson = (0, transactions_1.cvToJSON)(functionCallResult);
-            if (functionCallResultJson.success) {
-                localContext[r.rendezvousContractId][r.selectedFunction.name]++;
-                simnet.callPublicFn(r.rendezvousContractId, "update-context", [
-                    transactions_1.Cl.stringAscii(r.selectedFunction.name),
-                    transactions_1.Cl.uint(localContext[r.rendezvousContractId][r.selectedFunction.name]),
-                ], simnet.deployer);
-                radio.emit("logMessage", `₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
-                    `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
-                    (0, ansicolor_1.dim)(`${sutCallerWallet}        `) +
-                    `${sutContractName} ` +
-                    `${(0, ansicolor_1.underline)(r.selectedFunction.name)} ` +
-                    printedFunctionArgs);
+            try {
+                const functionCall = simnet.callPublicFn(r.rendezvousContractId, selectedFunction.name, selectedFunctionsArgsCV[index], sutCallerAddress);
+                const functionCallResultJson = (0, transactions_1.cvToJSON)(functionCall.result);
+                if (functionCallResultJson.success) {
+                    localContext[r.rendezvousContractId][selectedFunction.name]++;
+                    simnet.callPublicFn(r.rendezvousContractId, "update-context", [
+                        transactions_1.Cl.stringAscii(selectedFunction.name),
+                        transactions_1.Cl.uint(localContext[r.rendezvousContractId][selectedFunction.name]),
+                    ], simnet.deployer);
+                    radio.emit("logMessage", `₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
+                        `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
+                        (0, ansicolor_1.dim)(`${sutCallerWallet}        `) +
+                        `${targetContractName} ` +
+                        `${(0, ansicolor_1.underline)(selectedFunction.name)} ` +
+                        printedFunctionArgs);
+                    try {
+                        if (dialerRegistry !== undefined) {
+                            yield dialerRegistry.executePostDialers({
+                                selectedFunction: selectedFunction,
+                                functionCall: functionCall,
+                                clarityValueArguments: selectedFunctionsArgsCV[index],
+                            });
+                        }
+                    }
+                    catch (error) {
+                        throw new dialer_1.PostDialerError(error.message);
+                    }
+                }
+                else {
+                    radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
+                        `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
+                        `${sutCallerWallet}        ` +
+                        `${targetContractName} ` +
+                        `${(0, ansicolor_1.underline)(selectedFunction.name)} ` +
+                        printedFunctionArgs));
+                }
             }
-            else {
-                radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
-                    `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
-                    `${sutCallerWallet}        ` +
-                    `${sutContractName} ` +
-                    `${(0, ansicolor_1.underline)(r.selectedFunction.name)} ` +
-                    printedFunctionArgs));
+            catch (error) {
+                if (error instanceof dialer_1.PreDialerError ||
+                    error instanceof dialer_1.PostDialerError) {
+                    throw error;
+                }
+                else {
+                    // If the function call fails with a runtime error, log a dimmed
+                    // message. Since the public function result is ignored, there's
+                    // no need to throw an error.
+                    radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
+                        `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
+                        `${sutCallerWallet}        ` +
+                        `${targetContractName} ` +
+                        `${(0, ansicolor_1.underline)(selectedFunction.name)} ` +
+                        printedFunctionArgs));
+                }
             }
         }
-        catch (error) {
-            // If the function call fails with a runtime error, log a dimmed
-            // message. Since the public function result is ignored, there's
-            // no need to throw an error.
-            radio.emit("logMessage", (0, ansicolor_1.dim)(`₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
-                `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
-                `${sutCallerWallet}        ` +
-                `${sutContractName} ` +
-                `${(0, ansicolor_1.underline)(r.selectedFunction.name)} ` +
-                printedFunctionArgs));
-        }
-        const printedInvariantArgs = r.invariantArgsArb
+        const printedInvariantArgs = r.invariantArgs
             .map((arg) => {
             try {
                 return typeof arg === "object"
@@ -173,19 +235,19 @@ const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllF
             .join(" ");
         const [invariantCallerWallet, invariantCallerAddress] = r.invariantCaller;
         try {
-            const { result: invariantCallResult } = simnet.callReadOnlyFn(r.rendezvousContractId, r.selectedInvariant.name, selectedInvariantArgs, invariantCallerAddress);
+            const { result: invariantCallResult } = simnet.callReadOnlyFn(r.rendezvousContractId, r.selectedInvariant.name, selectedInvariantArgsCV, invariantCallerAddress);
             const invariantCallResultJson = (0, transactions_1.cvToJSON)(invariantCallResult);
             if (invariantCallResultJson.value === true) {
                 radio.emit("logMessage", `₿ ${simnet.burnBlockHeight.toString().padStart(8)} ` +
                     `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                     `${(0, ansicolor_1.dim)(invariantCallerWallet)} ` +
                     `${(0, ansicolor_1.green)("[PASS]")} ` +
-                    `${sutContractName} ` +
+                    `${targetContractName} ` +
                     `${(0, ansicolor_1.underline)(r.selectedInvariant.name)} ` +
                     printedInvariantArgs);
             }
             if (!invariantCallResultJson.value) {
-                throw new Error(`Invariant failed for ${sutContractName} contract: "${r.selectedInvariant.name}" returned ${invariantCallResultJson.value}`);
+                throw new Error(`Invariant failed for ${targetContractName} contract: "${r.selectedInvariant.name}" returned ${invariantCallResultJson.value}`);
             }
         }
         catch (error) {
@@ -196,7 +258,7 @@ const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllF
                 `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                 `${invariantCallerWallet} ` +
                 `[FAIL] ` +
-                `${sutContractName} ` +
+                `${targetContractName} ` +
                 `${(0, ansicolor_1.underline)(r.selectedInvariant.name)} ` +
                 printedInvariantArgs));
             // Re-throw the error for fast-check to catch and process.
@@ -205,17 +267,17 @@ const checkInvariants = (simnet, sutContractName, rendezvousList, rendezvousAllF
         if (r.canMineBlocks) {
             simnet.mineEmptyBurnBlocks(r.burnBlocks);
         }
-    }), {
+    })), {
         verbose: true,
         reporter: radioReporter,
         seed: seed,
         path: path,
         numRuns: runs,
     });
-};
+});
 exports.checkInvariants = checkInvariants;
 /**
- * Initialize the local context, setting the number of times each function
+ * Initializes the local context, setting the number of times each function
  * has been called to zero.
  * @param rendezvousSutFunctions The Rendezvous functions.
  * @returns The initialized local context.
@@ -236,14 +298,15 @@ const initializeClarityContext = (simnet, rendezvousSutFunctions) => rendezvousS
 });
 exports.initializeClarityContext = initializeClarityContext;
 /**
- * Filter the System Under Test (`SUT`) functions from the map of all
- * contract functions.
+ * Filter the System Under Test (`SUT`) functions from the map of all contract
+ * functions.
  *
  * The SUT functions are the ones that have `public` access since they are
  * capable of changing the contract state, and they are not test functions.
  * @param allFunctionsMap The map containing all the functions for each
+ * Rendezvous contract.
+ * @returns A map containing the filtered SUT functions for each Rendezvous
  * contract.
- * @returns A map containing only the SUT functions for each contract.
  */
 const filterSutFunctions = (allFunctionsMap) => new Map(Array.from(allFunctionsMap, ([contractId, functions]) => [
     contractId,

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stacks/rendezvous",
-    "version": "0.2.0",
+    "version": "0.4.0",
     "description": "Meet your contract's vulnerabilities head-on.",
     "main": "app.js",
     "bin": {
@@ -25,6 +25,10 @@
         "README.md",
         "LICENSE"
     ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/stacks-network/rendezvous.git"
+    },
     "dependencies": {
         "@hirosystems/clarinet-sdk": "2.12.0",
         "@stacks/transactions": "^6.16.1",
@@ -36,7 +40,7 @@
         "@hirosystems/clarinet-sdk-wasm": "2.12.0",
         "@types/jest": "^29.5.12",
         "jest": "^29.7.0",
-        "ts-jest": "^29.2.3",
+        "ts-jest": "^29.2.5",
         "typescript": "^5.5.4"
     }
 }

package/dist/property.js

@@ -10,7 +10,21 @@ const heatstroke_1 = require("./heatstroke");
 const shared_1 = require("./shared");
 const ansicolor_1 = require("ansicolor");
 const traits_1 = require("./traits");
-const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio) => {
+/**
+ * Runs property-based tests on the target contract and logs the progress.
+ * Reports the test results through a custom reporter.
+ * @param simnet The simnet instance.
+ * @param targetContractName The name of the target contract.
+ * @param rendezvousList The list of contract IDs for each target contract.
+ * @param rendezvousAllFunctions A map of all target contract IDs to their
+ * function interfaces.
+ * @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 radio The custom logging event emitter.
+ * @returns void
+ */
+const checkProperties = (simnet, targetContractName, rendezvousList, rendezvousAllFunctions, seed, path, runs, radio) => {
     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
@@ -28,9 +42,9 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
         return;
     }
     const enrichedTestFunctionsInterfaces = traitReferenceFunctions.length > 0
-        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(sutContractName), (0, traits_1.buildTraitReferenceMap)(testContractsTestFunctions.get(testContractId)), testContractsTestFunctions.get(testContractId), testContractId)
+        ? (0, traits_1.enrichInterfaceWithTraitData)(simnet.getContractAST(targetContractName), (0, traits_1.buildTraitReferenceMap)(testContractsTestFunctions.get(testContractId)), testContractsTestFunctions.get(testContractId), testContractId)
         : testContractsTestFunctions;
-    radio.emit("logMessage", `\nStarting property testing type for the ${sutContractName} contract...\n`);
+    radio.emit("logMessage", `\nStarting property testing type for the ${targetContractName} contract...\n`);
     // Search for discard functions, for each test function. This map will
     // be used to pair the test functions with their corresponding discard
     // functions.
@@ -61,7 +75,7 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
     const simnetAddresses = Array.from(simnetAccounts.values());
     const testFunctions = (0, shared_1.getFunctionsListForContract)(enrichedTestFunctionsInterfaces, testContractId);
     if ((testFunctions === null || testFunctions === void 0 ? void 0 : testFunctions.length) === 0) {
-        radio.emit("logMessage", (0, ansicolor_1.red)(`No test functions found for the "${sutContractName}" contract.\n`));
+        radio.emit("logMessage", (0, ansicolor_1.red)(`No test functions found for the "${targetContractName}" contract.\n`));
         return;
     }
     const radioReporter = (runDetails) => {
@@ -80,7 +94,7 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
         .map((selectedTestFunction) => (Object.assign(Object.assign({}, r), selectedTestFunction))))
         .chain((r) => fast_check_1.default
         .record({
-        functionArgsArb: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedTestFunction, simnetAddresses, projectTraitImplementations)),
+        functionArgs: fast_check_1.default.tuple(...(0, shared_1.functionToArbitrary)(r.selectedTestFunction, simnetAddresses, projectTraitImplementations)),
     })
         .map((args) => (Object.assign(Object.assign({}, r), args))))
         .chain((r) => fast_check_1.default
@@ -99,8 +113,8 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
             : fast_check_1.default.constant(0),
     })
         .map((burnBlocks) => (Object.assign(Object.assign({}, r), burnBlocks)))), (r) => {
-        const selectedTestFunctionArgs = (0, shared_1.argsToCV)(r.selectedTestFunction, r.functionArgsArb);
-        const printedTestFunctionArgs = r.functionArgsArb
+        const selectedTestFunctionArgs = (0, shared_1.argsToCV)(r.selectedTestFunction, r.functionArgs);
+        const printedTestFunctionArgs = r.functionArgs
             .map((arg) => {
             try {
                 return typeof arg === "object"
@@ -122,7 +136,7 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
                 `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                 `${(0, ansicolor_1.dim)(testCallerWallet)} ` +
                 `${(0, ansicolor_1.yellow)("[WARN]")} ` +
-                `${sutContractName} ` +
+                `${targetContractName} ` +
                 `${(0, ansicolor_1.underline)(r.selectedTestFunction.name)} ` +
                 (0, ansicolor_1.dim)(printedTestFunctionArgs));
         }
@@ -138,7 +152,7 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
                         `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                         `${(0, ansicolor_1.dim)(testCallerWallet)} ` +
                         `${(0, ansicolor_1.yellow)("[WARN]")} ` +
-                        `${sutContractName} ` +
+                        `${targetContractName} ` +
                         `${(0, ansicolor_1.underline)(r.selectedTestFunction.name)} ` +
                         (0, ansicolor_1.dim)(printedTestFunctionArgs));
                 }
@@ -149,7 +163,7 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
                         `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                         `${(0, ansicolor_1.dim)(testCallerWallet)} ` +
                         `${(0, ansicolor_1.green)("[PASS]")} ` +
-                        `${sutContractName} ` +
+                        `${targetContractName} ` +
                         `${(0, ansicolor_1.underline)(r.selectedTestFunction.name)} ` +
                         printedTestFunctionArgs);
                     if (r.canMineBlocks) {
@@ -157,7 +171,7 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
                     }
                 }
                 else {
-                    throw new Error(`Test failed for ${sutContractName} contract: "${r.selectedTestFunction.name}" returned ${testFunctionCallResultJson.value.value}`);
+                    throw new Error(`Test failed for ${targetContractName} contract: "${r.selectedTestFunction.name}" returned ${testFunctionCallResultJson.value.value}`);
                 }
             }
             catch (error) {
@@ -166,7 +180,7 @@ const checkProperties = (simnet, sutContractName, rendezvousList, rendezvousAllF
                     `Ӿ ${simnet.blockHeight.toString().padStart(8)}   ` +
                     `${testCallerWallet} ` +
                     `[FAIL] ` +
-                    `${sutContractName} ` +
+                    `${targetContractName} ` +
                     `${(0, ansicolor_1.underline)(r.selectedTestFunction.name)} ` +
                     printedTestFunctionArgs));
                 // Re-throw the error for fast-check to catch and process.
@@ -190,12 +204,12 @@ const isTestDiscardedInPlace = (testFunctionCallResultJson) => testFunctionCallR
     testFunctionCallResultJson.value.value === false;
 exports.isTestDiscardedInPlace = isTestDiscardedInPlace;
 /**
- * Check if the test function has to be discarded.
+ * Checks if the test function has to be discarded.
  * @param discardFunctionName The discard function name.
  * @param selectedTestFunctionArgs The generated test function arguments.
  * @param contractId The contract identifier.
  * @param simnet The simnet instance.
- * @param selectedCaller The selected caller.
+ * @param selectedCaller The selected caller address.
  * @returns A boolean indicating if the test function has to be discarded.
  */
 const isTestDiscarded = (discardFunctionName, selectedTestFunctionArgs, contractId, simnet, selectedCaller) => {
@@ -206,7 +220,7 @@ const isTestDiscarded = (discardFunctionName, selectedTestFunctionArgs, contract
     return jsonDiscardFunctionCallResult.value === false;
 };
 /**
- * Validate the discard function, ensuring that its parameters match the test
+ * Validates a discard function, ensuring that its parameters match the test
  * function's parameters and that its return type is boolean.
  * @param contractId The contract identifier.
  * @param discardFunctionName The discard function name.
@@ -235,23 +249,23 @@ const validateDiscardFunction = (contractId, discardFunctionName, testFunctionNa
     return true;
 };
 /**
- * Verify if the test function parameters match the discard function
+ * Checks if the test function parameters match the discard function
  * parameters.
- * @param testFunction The test function's interface.
- * @param discardFunction The discard function's interface.
+ * @param testFunctionInterface The test function's interface.
+ * @param discardFunctionInterface The discard function's interface.
  * @returns A boolean indicating if the parameters match.
  */
-const isParamsMatch = (testFunction, discardFunction) => {
-    const sortedTestFunctionArgs = [...testFunction.args].sort((a, b) => a.name.localeCompare(b.name));
-    const sortedDiscardFunctionArgs = [...discardFunction.args].sort((a, b) => a.name.localeCompare(b.name));
+const isParamsMatch = (testFunctionInterface, discardFunctionInterface) => {
+    const sortedTestFunctionArgs = [...testFunctionInterface.args].sort((a, b) => a.name.localeCompare(b.name));
+    const sortedDiscardFunctionArgs = [...discardFunctionInterface.args].sort((a, b) => a.name.localeCompare(b.name));
     return (JSON.stringify(sortedTestFunctionArgs) ===
         JSON.stringify(sortedDiscardFunctionArgs));
 };
 exports.isParamsMatch = isParamsMatch;
 /**
- * Verify if the discard function's return type is boolean.
- * @param discardFunction The discard function's interface.
+ * Checks if the discard function's return type is boolean.
+ * @param discardFunctionInterface The discard function's interface.
  * @returns A boolean indicating if the return type is boolean.
  */
-const isReturnTypeBoolean = (discardFunction) => discardFunction.outputs.type === "bool";
+const isReturnTypeBoolean = (discardFunctionInterface) => discardFunctionInterface.outputs.type === "bool";
 exports.isReturnTypeBoolean = isReturnTypeBoolean;

package/dist/shared.js

@@ -8,35 +8,42 @@ const fast_check_1 = __importDefault(require("fast-check"));
 const transactions_1 = require("@stacks/transactions");
 const traits_1 = require("./traits");
 /**
- * Get the interfaces of contracts deployed by the specified deployer from the
- * simnet.
+ * Retrieves the contract interfaces of the contracts deployed by a specific
+ * deployer from the simnet instance.
  * @param simnet The simnet instance.
- * @param deployer The deployer address.
- * @returns The contracts interfaces.
+ * @returns The contract IDs mapped to their interfaces.
  */
 const getSimnetDeployerContractsInterfaces = (simnet) => new Map(Array.from(simnet.getContractsInterfaces()).filter(([key]) => key.split(".")[0] === simnet.deployer));
 exports.getSimnetDeployerContractsInterfaces = getSimnetDeployerContractsInterfaces;
 /**
- * Get the functions from the smart contract interfaces.
- * @param contractsInterfaces The smart contract interfaces map.
- * @returns A map containing the contracts functions.
+ * Retrieves the function interfaces from the contract interfaces. Filters out
+ * other contract interface data such as data maps, variables, and constants.
+ * @param contractInterfaces The smart contract interfaces map.
+ * @returns The contract IDs mapped to their function interfaces.
  */
-const getFunctionsFromContractInterfaces = (contractsInterfaces) => new Map(Array.from(contractsInterfaces, ([contractId, contractInterface]) => [
+const getFunctionsFromContractInterfaces = (contractInterfaces) => new Map(Array.from(contractInterfaces, ([contractId, contractInterface]) => [
     contractId,
     contractInterface.functions,
 ]));
 exports.getFunctionsFromContractInterfaces = getFunctionsFromContractInterfaces;
 const getFunctionsListForContract = (functionsMap, contractId) => functionsMap.get(contractId) || [];
 exports.getFunctionsListForContract = getFunctionsListForContract;
-/** For a given function, dynamically generate fast-check arbitraries.
- * @param fn The function interface.
+/** Dynamically generates fast-check arbitraries for a given function
+ * interface.
+ * @param functionInterface The "enriched" function interface.
+ * @param addresses The array of addresses to use for principal types.
+ * @param projectTraitImplementations The contract IDs mapped to the traits
+ * they implement.
  * @returns Array of fast-check arbitraries.
  */
-const functionToArbitrary = (fn, addresses, projectTraitImplementations) => fn.args.map((arg) => parameterTypeToArbitrary(arg.type, addresses, projectTraitImplementations));
+const functionToArbitrary = (functionInterface, addresses, projectTraitImplementations) => functionInterface.args.map((arg) => parameterTypeToArbitrary(arg.type, addresses, projectTraitImplementations));
 exports.functionToArbitrary = functionToArbitrary;
 /**
- * For a given type, generate a fast-check arbitrary.
- * @param type The parameter type.
+ * Generates a fast-check arbitrary for a given parameter type.
+ * @param type The "enriched" parameter type.
+ * @param addresses The array of addresses to use for principal types.
+ * @param projectTraitImplementations The contract IDs mapped to the traits
+ * they implement.
  * @returns Fast-check arbitrary.
  */
 const parameterTypeToArbitrary = (type, addresses, projectTraitImplementations) => {
@@ -129,8 +136,8 @@ const complexTypesToArbitrary = {
 };
 /**
  * Custom hexadecimal string generator. The `hexaString` generator from
- * fast-check has been deprecated. This generator is implemented to precisely
- * match the behavior of the deprecated generator.
+ * fast-check has been deprecated. This generator is implemented to match the
+ * behavior of the deprecated generator.
  *
  * @param constraints Fast-check string constraints.
  * @returns Fast-check arbitrary for hexadecimal strings.
@@ -150,31 +157,31 @@ exports.hexaString = hexaString;
 /** The character set used for generating ASCII strings.*/
 const charSet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~";
 /**
- * Convert function arguments to Clarity values.
- * @param fn The function interface.
- * @param args Array of arguments.
+ * Converts JavaScript generated function arguments to Clarity values.
+ * @param functionInterface The function interface.
+ * @param generatedArguments Array of generated arguments.
  * @returns Array of Clarity values.
  */
-const argsToCV = (fn, args) => fn.args.map((arg, i) => argToCV(args[i], arg.type));
+const argsToCV = (functionInterface, generatedArguments) => functionInterface.args.map((arg, i) => argToCV(generatedArguments[i], arg.type));
 exports.argsToCV = argsToCV;
 /**
- * Convert a function argument to a Clarity value.
- * @param arg Generated argument.
+ * Converts a JavaScript generated function argument to a Clarity value.
+ * @param generatedArgument Generated argument.
  * @param type Argument type (base or complex).
  * @returns Clarity value.
  */
-const argToCV = (arg, type) => {
+const argToCV = (generatedArgument, type) => {
     if (isBaseType(type)) {
         // Base type.
         switch (type) {
             case "int128":
-                return baseTypesToCV.int128(arg);
+                return baseTypesToCV.int128(generatedArgument);
             case "uint128":
-                return baseTypesToCV.uint128(arg);
+                return baseTypesToCV.uint128(generatedArgument);
             case "bool":
-                return baseTypesToCV.bool(arg);
+                return baseTypesToCV.bool(generatedArgument);
             case "principal":
-                return baseTypesToCV.principal(arg);
+                return baseTypesToCV.principal(generatedArgument);
             default:
                 throw new Error(`Unsupported base parameter type: ${type}`);
         }
@@ -182,36 +189,38 @@ const argToCV = (arg, type) => {
     else {
         // Complex type.
         if ("buffer" in type) {
-            return complexTypesToCV.buffer(arg);
+            return complexTypesToCV.buffer(generatedArgument);
         }
         else if ("string-ascii" in type) {
-            return complexTypesToCV["string-ascii"](arg);
+            return complexTypesToCV["string-ascii"](generatedArgument);
         }
         else if ("string-utf8" in type) {
-            return complexTypesToCV["string-utf8"](arg);
+            return complexTypesToCV["string-utf8"](generatedArgument);
         }
         else if ("list" in type) {
-            const listItems = arg.map((item) => argToCV(item, type.list.type));
+            const listItems = generatedArgument.map((item) => argToCV(item, type.list.type));
             return complexTypesToCV.list(listItems);
         }
         else if ("tuple" in type) {
             const tupleData = {};
             type.tuple.forEach((field) => {
-                tupleData[field.name] = argToCV(arg[field.name], field.type);
+                tupleData[field.name] = argToCV(generatedArgument[field.name], field.type);
             });
             return complexTypesToCV.tuple(tupleData);
         }
         else if ("optional" in type) {
-            return (0, transactions_1.optionalCVOf)(arg ? argToCV(arg, type.optional) : undefined);
+            return (0, transactions_1.optionalCVOf)(generatedArgument
+                ? argToCV(generatedArgument, type.optional)
+                : undefined);
         }
         else if ("response" in type) {
-            const status = arg.status;
+            const status = generatedArgument.status;
             const branchType = type.response[status];
-            const responseValue = argToCV(arg.value, branchType);
+            const responseValue = argToCV(generatedArgument.value, branchType);
             return complexTypesToCV.response(status, responseValue);
         }
         else if ("trait_reference" in type) {
-            return complexTypesToCV.trait_reference(arg);
+            return complexTypesToCV.trait_reference(generatedArgument);
         }
         else {
             throw new Error(`Unsupported complex parameter type: ${JSON.stringify(type)}`);

package/dist/traits.js

@@ -2,16 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractProjectTraitImplementations = exports.isTraitReferenceFunction = exports.getContractIdsImplementingTrait = exports.buildTraitReferenceMap = exports.getTraitReferenceData = exports.enrichInterfaceWithTraitData = void 0;
 /**
- * Enriches contract interface with trait reference data. Before enrichment,
+ * Enriches a contract interface with trait reference data. Before enrichment,
  * the contract interface lacks trait reference data for parameters. This
  * function constructs a copy of the contract interface with trait reference
  * data for parameters that are trait references.
  * @param ast The contract AST.
- * @param traitReferenceMap The map of function names to trait reference paths.
+ * @param traitReferenceMap The function names mapped to their trait reference
+ * parameter paths.
  * @param functionInterfaceList The list of function interfaces for a contract.
  * @param targetContractId The contract ID to enrich with trait reference data.
- * @returns A map of contract IDs to a list of enriched contract interface
- * functions.
+ * @returns The contract IDs mapped to a list of enriched function interfaces.
  */
 const enrichInterfaceWithTraitData = (ast, traitReferenceMap, functionInterfaceList, targetContractId) => {
     const enriched = new Map();
@@ -233,9 +233,10 @@ const getTraitReferenceData = (ast, functionName, parameterPath) => {
 exports.getTraitReferenceData = getTraitReferenceData;
 /**
  * Builds a map of function names to trait reference paths. The trait reference
- * path is the path to the trait reference in the function parameter list.
+ * path is the nesting path of the trait reference in the function parameter
+ * list.
  * @param functionInterfaces The list of function interfaces for a contract.
- * @returns A map of function names to trait reference paths.
+ * @returns The function names mapped to their trait reference parameter paths.
  */
 const buildTraitReferenceMap = (functionInterfaces) => {
     const traitReferenceMap = new Map();
@@ -363,7 +364,7 @@ exports.isTraitReferenceFunction = isTraitReferenceFunction;
  * Iterates over all project contracts's ASTs excluding the boot ones and
  * extracts a record of contract IDs to their implemented traits.
  * @param simnet The Simnet instance.
- * @returns A record of contract IDs to their implemented traits.
+ * @returns The contract IDs mapped to their implemented traits.
  */
 const extractProjectTraitImplementations = (simnet) => {
     const allProjectContracts = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacks/rendezvous",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Meet your contract's vulnerabilities head-on.",
   "main": "app.js",
   "bin": {
@@ -25,6 +25,10 @@
     "README.md",
     "LICENSE"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stacks-network/rendezvous.git"
+  },
   "dependencies": {
     "@hirosystems/clarinet-sdk": "2.12.0",
     "@stacks/transactions": "^6.16.1",
@@ -36,7 +40,7 @@
     "@hirosystems/clarinet-sdk-wasm": "2.12.0",
     "@types/jest": "^29.5.12",
     "jest": "^29.7.0",
-    "ts-jest": "^29.2.3",
+    "ts-jest": "^29.2.5",
     "typescript": "^5.5.4"
   }
 }