feat(lints): Improved error reporting

src/detectors/builtin/divideBeforeMultiply.ts

@@ -18,7 +18,12 @@ import {
 import { Detector } from "../detector";
 import { CompilationUnit, Node, CFG } from "../../internals/ir";
 import { MistiContext } from "../../internals/context";
-import { createError, MistiTactError, Severity } from "../../internals/errors";
+import {
+  createError,
+  makeDocURL,
+  MistiTactError,
+  Severity,
+} from "../../internals/errors";
 import {
   forEachExpression,
   foldExpressions,
@@ -86,9 +91,14 @@ export class DivideBeforeMultiply extends Detector {
         }
         reportedDivIds.add(divId);
         const err = createError(
-          "Division operation before multiplication detected. Consider rearranging the operations.",
+          "Divide Before Multiply",
           Severity.HIGH,
           fact.data,
+          {
+            docURL: makeDocURL(this.id),
+            suggestion:
+              "Consider rearranging the operations: division should follow multiplication",
+          },
         );
         acc.push(err);
         return acc;

src/detectors/builtin/neverAccessedVariables.ts

@@ -131,9 +131,10 @@ export class NeverAccessedVariables extends Detector {
       new Set(
         [...definedFields].filter(([name, _ref]) => !usedFields.has(name)),
       ),
-    ).map(([name, ref]) =>
-      createError(`Field ${name} is never used`, Severity.MEDIUM, ref, {
+    ).map(([_name, ref]) =>
+      createError("Field is never used", Severity.MEDIUM, ref, {
         docURL: makeDocURL(this.id),
+        suggestion: "Consider removing the field",
       }),
     );
   }
@@ -170,8 +171,9 @@ export class NeverAccessedVariables extends Detector {
         ),
       ),
     ).map(([name, ref]) =>
-      createError(`Constant ${name} is never used`, Severity.MEDIUM, ref, {
+      createError("Constant is never used", Severity.MEDIUM, ref, {
         docURL: makeDocURL(this.id),
+        suggestion: "Consider removing the constant",
       }),
     );
   }
@@ -229,12 +231,17 @@ export class NeverAccessedVariables extends Detector {
       });
       Array.from(declaredVariables.keys()).forEach((name) => {
         if (!accessedVariables.has(name)) {
-          const msg = writtenVariables.has(name)
+          const isWritten = writtenVariables.has(name);
+          const msg = isWritten
             ? "Write-only variable"
             : "Variable is never accessed";
+          const suggestion = isWritten
+            ? "The variable value should be accessed"
+            : "Consider removing the variable";
           errors.push(
             createError(msg, Severity.MEDIUM, declaredVariables.get(name)!, {
               docURL: makeDocURL(this.id),
+              suggestion,
             }),
           );
         }

src/detectors/builtin/readOnlyVariables.ts

@@ -76,6 +76,7 @@ export class ReadOnlyVariables extends Detector {
       }
       return createError("Read-only variable", Severity.MEDIUM, fact.data, {
         docURL: makeDocURL(this.id),
+        suggestion: "Consider creating a constant instead",
       });
     });
 

src/detectors/builtin/unboundLoops.ts

@@ -76,12 +76,13 @@ export class UnboundLoops extends Detector {
       if (fact.data === undefined) {
         throw new Error(`AST position for fact ${fact} is not available`);
       }
-      return createError(
-        "Unbounded loop: the condition variable doesn't change within the loop",
-        Severity.MEDIUM,
-        fact.data,
-        { docURL: makeDocURL(this.id) },
-      );
+      return createError("Unbounded Loop", Severity.MEDIUM, fact.data, {
+        docURL: makeDocURL(this.id),
+        suggestion:
+          "Consider changing the variable within the loop to ensure it terminates",
+        extraDescription:
+          "The condition variable doesn't change within the loop",
+      });
     });
 
     return warnings;

src/detectors/builtin/zeroAddress.ts

@@ -22,8 +22,9 @@ function findZeroAddress(
       expr.args[1].value === 0n
     ) {
       acc.push(
-        createError("Using zero address", Severity.MEDIUM, expr.args[1].ref, {
+        createError("Using Zero Address", Severity.MEDIUM, expr.args[1].ref, {
           docURL: makeDocURL("zeroAddress"),
+          suggestion: "Consider changing code to avoid using it",
         }),
       );
     }

src/internals/errors.ts

@@ -88,11 +88,16 @@ export function createError(
         return `${relativeFilePath}:${lc.lineNum}:${lc.colNum}:\n${lcLines.join("\n")}`;
       })()
     : "";
-  const docURLStr = docURL === undefined ? "" : ` (see: ${docURL})`;
   const extraDescriptionStr =
-    extraDescription === undefined ? "" : `\n${extraDescription}`;
-  const suggestionStr =
-    suggestion === undefined ? "" : `\nSuggestion: ${suggestion}`;
-  const msg = `${pos}${description}${docURLStr}${extraDescriptionStr}${suggestionStr}`;
+    extraDescription === undefined ? "" : `: ${extraDescription}`;
+  const suggestionStr = suggestion === undefined ? "" : `\nHelp: ${suggestion}`;
+  const docURLStr = docURL === undefined ? "" : `\nSee: ${docURL})`;
+  const msg = [
+    pos,
+    description,
+    extraDescriptionStr,
+    suggestionStr,
+    docURLStr,
+  ].join("");
   return new MistiTactError(msg, ref, severity);
 }

test/contracts/div-before-mul-1.expected.out

@@ -3,4 +3,6 @@ test/contracts/div-before-mul-1.tact:5:21:
 > 5 |   let result: Int = a / b * c; // error: Division before multiplication
                           ^
   6 |   return result;
-Division operation before multiplication detected. Consider rearranging the operations.
+Divide Before Multiply
+Help: Consider rearranging the operations: division should follow multiplication
+See: https://nowarp.github.io/docs/misti/docs/detectors/DivideBeforeMultiply)

test/contracts/div-before-mul-3.expected.out

@@ -3,4 +3,6 @@ test/contracts/div-before-mul-3.tact:2:16:
 > 2 |   let a: Int = 10 / 3; // Division operation
                      ^
   3 |   let c: Int = 2;
-Division operation before multiplication detected. Consider rearranging the operations.
+Divide Before Multiply
+Help: Consider rearranging the operations: division should follow multiplication
+See: https://nowarp.github.io/docs/misti/docs/detectors/DivideBeforeMultiply)

test/contracts/never-accessed-1.expected.out

@@ -3,4 +3,6 @@ test/contracts/never-accessed-1.tact:2:5:
 > 2 |     let a: Int = 20;
           ^
   3 |     if (true) { // error: write-only variable
-Write-only variable (see: https://nowarp.github.io/docs/misti/docs/detectors/NeverAccessedVariables)
+Write-only variable
+Help: The variable value should be accessed
+See: https://nowarp.github.io/docs/misti/docs/detectors/NeverAccessedVariables)

test/contracts/readonly-2.expected.out

@@ -3,11 +3,15 @@ test/contracts/readonly-2.tact:2:5:
 > 2 |     let a: Int = 20;
           ^
   3 |     let b: Int = 22;
-Read-only variable (see: https://nowarp.github.io/docs/misti/docs/detectors/ReadOnlyVariables)
+Read-only variable
+Help: Consider creating a constant instead
+See: https://nowarp.github.io/docs/misti/docs/detectors/ReadOnlyVariables)
 
 test/contracts/readonly-2.tact:2:5:
   1 | fun test1(): Int {
 > 2 |     let a: Int = 20;
           ^
   3 |     let b: Int = 22;
-Variable is never accessed (see: https://nowarp.github.io/docs/misti/docs/detectors/NeverAccessedVariables)
+Variable is never accessed
+Help: Consider removing the variable
+See: https://nowarp.github.io/docs/misti/docs/detectors/NeverAccessedVariables)

test/contracts/unbound-loop-1.expected.out

@@ -3,4 +3,6 @@ test/contracts/unbound-loop-1.tact:3:12:
 > 3 |     while (a > 10) { // error: a is not changing within the loop
                  ^
   4 |     }
-Unbounded loop: the condition variable doesn't change within the loop (see: https://nowarp.github.io/docs/misti/docs/detectors/UnboundLoops)
+Unbounded Loop: The condition variable doesn't change within the loop
+Help: Consider changing the variable within the loop to ensure it terminates
+See: https://nowarp.github.io/docs/misti/docs/detectors/UnboundLoops)

test/contracts/unbound-loop-2.expected.out

@@ -3,4 +3,6 @@ test/contracts/unbound-loop-2.tact:4:14:
 > 4 |     } until (a > 10);
                    ^
   5 |     return a;
-Unbounded loop: the condition variable doesn't change within the loop (see: https://nowarp.github.io/docs/misti/docs/detectors/UnboundLoops)
+Unbounded Loop: The condition variable doesn't change within the loop
+Help: Consider changing the variable within the loop to ensure it terminates
+See: https://nowarp.github.io/docs/misti/docs/detectors/UnboundLoops)

test/contracts/zero-address.expected.out

@@ -3,4 +3,6 @@ test/contracts/zero-address.tact:3:23:
 > 3 |         newAddress(1, 0x000000000000000000000000000000000000000000000000);
                             ^
   4 |     }
-Using zero address (see: https://nowarp.github.io/docs/misti/docs/detectors/zeroAddress)
+Using Zero Address
+Help: Consider changing code to avoid using it
+See: https://nowarp.github.io/docs/misti/docs/detectors/zeroAddress)