Docs are now online

Author: meowbmw

docs/rules/array-init-style.md

@@ -0,0 +1,25 @@
+# array-init-style
+
+> Enforce using Array constructor for empty array initialization
+
+## Rule Details
+
+In AssemblyScript, using the literal `[]` to create empty arrays creates a temporary object in the data section, which may lead to performance issues. This rule enforces using the `new Array<T>()` constructor to initialize empty arrays.
+
+## Rule Options
+
+This rule has no configuration options.
+
+## Examples
+
+### Incorrect
+
+```ts
+let arr: i32[] = []; // not recommended
+```
+
+### Correct
+
+```ts
+let arr: i32[] = new Array<i32>(); // recommended
+```

docs/rules/dont-omit-else.md

@@ -0,0 +1,47 @@
+# dont-omit-else
+
+> Enforce using else block when if branch doesn't contain control flow statement
+
+## Rule Details
+
+In AssemblyScript, it's recommended to explicitly handle all possible execution paths for better code clarity and safety. This rule enforces using an `else` block when the `if` branch doesn't contain a statement that alters the control flow, such as `return`, `throw`, `break`, or `continue`.
+
+## Rule Options
+
+This rule has no configuration options.
+
+## Examples
+
+### Incorrect
+
+```ts
+if (condition) {
+  doSomething();
+} // missing else
+```
+
+### Correct
+
+```ts
+// With else block
+if (condition) {
+  doSomething();
+} else {
+  doSomethingElse();
+}
+
+// Or with early exit in if branch
+if (condition) {
+  doSomething();
+  return; // Control flow statement makes else unnecessary
+}
+// Execution continues here only if condition is false
+```
+
+## When Not To Use
+
+You can disable this rule if you prefer a coding style that doesn't require explicit else blocks for all conditional statements.
+
+## Related Rules
+
+None

docs/rules/no-spread.md

@@ -0,0 +1,47 @@
+# no-spread
+
+> Disallow spread syntax which is not supported in AssemblyScript
+
+## Rule Details
+
+AssemblyScript does not support the spread syntax (`...var`) for function calls or array literals. This rule identifies and reports any use of spread syntax in your code.
+
+## Rule Options
+
+This rule has no configuration options.
+
+## Examples
+
+### Incorrect
+
+```ts
+// Using spread in function calls
+foo(1, ...bar);
+
+// Using spread in array literals
+const newArray = [...oldArray, 1, 2, 3];
+```
+
+### Correct
+
+```ts
+// Use direct arguments instead
+foo(1, bar);
+
+// Use array methods or explicit assignments
+const newArray = new Array<i32>(oldArray.length + 3);
+for (let i = 0; i < oldArray.length; i++) {
+  newArray[i] = oldArray[i];
+}
+newArray[oldArray.length] = 1;
+newArray[oldArray.length + 1] = 2;
+newArray[oldArray.length + 2] = 3;
+```
+
+## When Not To Use
+
+You should not disable this rule in AssemblyScript code, as using spread syntax will cause compilation errors.
+
+## Related Rules
+
+- [array-init-style](./array-init-style.md)

docs/rules/no-unsupported-keyword.md

@@ -0,0 +1,59 @@
+# no-unsupported-keyword
+
+> Disallow TypeScript keywords that are not supported in AssemblyScript
+
+## Rule Details
+
+AssemblyScript is a subset of TypeScript that compiles to WebAssembly, but it doesn't support all TypeScript features. This rule identifies and reports the use of TypeScript keywords that are not supported in AssemblyScript, specifically:
+
+- `never` type
+- `any` type
+- `undefined` type
+
+## Rule Options
+
+This rule has no configuration options.
+
+## Examples
+
+### Incorrect
+
+```ts
+// Using 'never' type
+function alwaysThrows(): never {
+  throw new Error('This function never returns');
+}
+
+// Using 'any' type
+function acceptsAnything(param: any) {
+  return param;
+}
+
+// Using 'undefined' type
+let maybeValue: string | undefined;
+```
+
+### Correct
+
+```ts
+// Use specific return types instead of 'never'
+function alwaysThrows(): void {
+  throw new Error('This function never returns');
+}
+
+// Use explicit types instead of 'any'
+function acceptsString(param: string): string {
+  return param;
+}
+
+// Use nullable types instead of undefined
+let maybeValue: string | null;
+```
+
+## When Not To Use
+
+You should not disable this rule in AssemblyScript code, as using these unsupported keywords will cause compilation errors.
+
+## Related Rules
+
+None

plugins/rules/array-init-style.ts

@@ -36,32 +36,26 @@ const arrayInitStyle: ESLintUtils.RuleModule<
         const typeAnnotation = node.id.typeAnnotation?.typeAnnotation;
         if (
           typeAnnotation?.type === "TSArrayType" &&
-          typeAnnotation.elementType?.type === "TSTypeReference"
+          typeAnnotation.elementType?.type === "TSTypeReference" &&
+          node.init?.type === "ArrayExpression" &&
+          node.init.elements.length === 0
         ) {
-          if (
-            node.init?.type === "ArrayExpression" &&
-            node.init.elements.length === 0
-          ) {
-            // Ensure node.init is not null before passing to fixer
-            const initNode = node.init;
-            const elementType = context.sourceCode.getText(
-              typeAnnotation.elementType.typeName
-            );
-            context.report({
-              node,
-              messageId: "preferArrayConstructor",
-              data: {
-                type: elementType,
-              },
-              fix(fixer) {
-                // initNode is guaranteed non-null here due to the outer check
-                return fixer.replaceText(
-                  initNode,
-                  `new Array<${elementType}>()`
-                );
-              },
-            });
-          }
+          // Ensure node.init is not null before passing to fixer
+          const initNode = node.init;
+          const elementType = context.sourceCode.getText(
+            typeAnnotation.elementType.typeName
+          );
+          context.report({
+            node,
+            messageId: "preferArrayConstructor",
+            data: {
+              type: elementType,
+            },
+            fix(fixer) {
+              // initNode is guaranteed non-null here due to the outer check
+              return fixer.replaceText(initNode, `new Array<${elementType}>()`);
+            },
+          });
         }
       },
     };

plugins/rules/dont-omit-else.ts

@@ -5,6 +5,10 @@ import createRule from "../utils/create-rule.js";
 /**
  * Rule: Dont Omit Else
  * Enforce using else block when if branch doesn't contain control flow statement.
+ * BAD
+ * if (x) { }
+ * GOOD
+ * if (x) { } else { }
  */
 const dontOmitElse: RuleModule<"omittedElse", [], unknown, RuleListener> =
   createRule({

plugins/rules/no-spread.ts

@@ -5,6 +5,10 @@ import createRule from "../utils/create-rule.js";
  * Rule: No Spread
  * Reject usages of ...var on call expressions, as spread syntax
  * is not supported in AssemblyScript.
+ * BAD:
+ * foo(1, ...bar)
+ * GOOD:
+ * foo(1, bar)
  */
 const noSpread: ESLintUtils.RuleModule<
   "noSpreadMsg",

plugins/rules/no-unsupported-keyword.ts

@@ -4,6 +4,11 @@ import createRule from "../utils/create-rule.js";
 /**
  * Rule: No Unsupported Keywords
  * Reject usage of TypeScript keywords that are not supported in AssemblyScript.
+ * BAD: 
+ * function foo(): never { throw new Error('never'); }
+ * function foo(a: any) {}
+ * GOOD:
+ * let foo: string;
  */
 const noUnsupportedKeyword: ESLintUtils.RuleModule<
   string,