redscript-mc 3.0.1 → 3.0.2

package/docs/lint-rules.md

@@ -0,0 +1,162 @@
+# RedScript Lint Rules
+
+The lint engine runs after HIR lowering and reports warnings before code generation.
+
+## Existing Rules
+
+### `unused-variable`
+Warns when a `let` binding is declared but never read.
+
+```redscript
+fn foo(): void {
+  let x: int = 5;  // warning: "x" is declared but never used
+}
+```
+
+### `unused-import`
+Warns when an imported symbol is never called in the module.
+
+```redscript
+import mylib::helper;  // warning: "helper" is never used
+
+fn main(): void {
+  say("hello");
+}
+```
+
+### `magic-number`
+Warns when a literal number with absolute value greater than 1 is used directly outside a `const` declaration.
+
+```redscript
+fn foo(): void {
+  let x: int = 1000;  // warning: avoid magic number 1000
+}
+
+const MAX: int = 1000;  // OK — const declarations are exempt
+```
+
+### `dead-branch`
+Warns when an `if` condition is a compile-time constant (always true or always false).
+
+```redscript
+fn foo(): void {
+  if 1 == 2 {  // warning: condition is always false
+    say("never");
+  }
+}
+```
+
+### `function-too-long`
+Warns when a function body exceeds the line limit (default: 50 lines). Configurable via `LintOptions.maxFunctionLines`.
+
+---
+
+## New Rules
+
+### `no-dead-assignment`
+Warns when a variable is assigned a value that is immediately overwritten before being read. The initial write is "dead" — it has no effect on program behavior.
+
+```redscript
+fn foo(): void {
+  let x: int = 0;  // warning: assignment to "x" is never read before being overwritten
+  x = 42;
+  say("done");
+}
+```
+
+No warning when each assigned value is read:
+
+```redscript
+fn foo(): int {
+  let x: int = 5;
+  let y: int = x;  // reads x — clears pending write
+  x = 10;
+  return x + y;    // reads x again
+}
+```
+
+### `prefer-match-exhaustive`
+Warns when a `match` expression uses Option patterns (`Some`/`None`) but is missing one of the arms and has no wildcard `_` catch-all.
+
+```redscript
+fn foo(x: Option<int>): void {
+  match x {
+    Some(v) => { say("got value"); }
+    // warning: match on Option is missing a None arm
+  }
+}
+```
+
+No warning when both arms are present, or when a wildcard covers the rest:
+
+```redscript
+fn foo(x: Option<int>): void {
+  match x {
+    Some(v) => { say("got value"); }
+    None    => { say("nothing"); }
+  }
+}
+```
+
+### `no-empty-catch`
+Warns about silent failure patterns — specifically:
+- An `if let Some` with an empty `else {}` block (silently ignores the None case)
+- A `match` arm with an empty body
+
+```redscript
+fn foo(x: Option<int>): void {
+  if let Some(v) = x {
+    say("ok");
+  } else {}  // warning: None case is silently ignored
+}
+
+fn bar(x: Option<int>): void {
+  match x {
+    Some(v) => { say("ok"); }
+    None    => {}  // warning: empty match arm body
+  }
+}
+```
+
+### `naming-convention`
+Enforces naming conventions:
+- Variables (let bindings, foreach bindings, if-let / while-let bindings) must use **camelCase**
+- Struct and enum type names must use **PascalCase**
+
+A leading underscore is allowed (e.g. `_unused` is valid camelCase).
+
+```redscript
+fn foo(): void {
+  let my_var: int = 5;  // warning: "my_var" should use camelCase — use myVar
+}
+
+struct myPoint { x: int, y: int }  // warning: "myPoint" should use PascalCase — use MyPoint
+```
+
+No warning for:
+
+```redscript
+fn foo(): void {
+  let myVar: int = 5;
+  let _ignored: int = 0;
+}
+
+struct MyPoint { x: int, y: int }
+```
+
+### `no-magic-numbers`
+Similar to `magic-number` but checks against a configurable allow-list (default: `[0, 1]`) instead of a threshold. Numbers outside the allow-list that appear in expressions outside `const` declarations are flagged.
+
+```redscript
+fn foo(): void {
+  let x: int = 42;  // warning: Magic number 42 — extract to a named const
+}
+
+const ANSWER: int = 42;  // OK — const declarations are exempt
+```
+
+Configurable via `LintOptions.allowedNumbers`:
+
+```typescript
+lintString(source, file, ns, { allowedNumbers: [0, 1, 42, 100] })
+```

package/docs/stdlib/bigint.md

@@ -2,6 +2,8 @@
 
 Import: `import bigint;`
 
+> **Attribution:** Parts of this module's multi-precision arithmetic approach were inspired by [kaer-3058/large_number](https://github.com/kaer-3058/large_number).
+
 Arbitrary-precision integers represented as base-10000 (万進制) `int` arrays in NBT storage. Arrays are big-endian (index 0 = most significant chunk). Provides 3-chunk (96-bit) helpers and arbitrary-length operations for addition, subtraction, multiplication, division, comparison, and utility functions. Full bigint×bigint multiplication and squaring included.
 
 ## Functions

package/editors/vscode/README.md

@@ -1,47 +1,67 @@
 # RedScript VSCode Extension
 
-Syntax highlighting and snippets for [RedScript](https://github.com/bkmashiro/redscript) — a compiler targeting Minecraft Java Edition datapacks.
+> Version 1.3.80 | [RedScript 3.0](https://github.com/bkmashiro/redscript)
+
+Full language support for [RedScript](https://github.com/bkmashiro/redscript) — a compiler targeting Minecraft Java Edition datapacks.
 
 ## Features
 
-- **RedScript syntax highlighting** (`.rs` files)
-  - Keywords: `fn`, `let`, `struct`, `if`, `while`, `for`, `foreach`, `as`, `at`
-  - Entity selectors: `@a`, `@e[type=zombie, distance=..5]`, etc.
+### Syntax Highlighting
+
+- **RedScript** (`.mcrs`, `.rs` files)
+  - Keywords, types, decorators, operators
+  - Entity selectors: `@a`, `@e[type=zombie, distance=..5]`
   - Range literals: `..5`, `1..`, `1..10`
-  - Decorators: `@tick`, `@tick(rate=20)`, `@on_trigger("name")`
-  - Built-in functions: `say`, `kill`, `give`, `effect`, `raw`, `random`, `spawn_object`
-  - Types: `int`, `float`, `bool`, `string`, `void`
-
-- **mcfunction syntax highlighting** (`.mcfunction` files)
-  - Full command syntax from [MinecraftCommands/syntax-mcfunction](https://github.com/MinecraftCommands/syntax-mcfunction)
-  - Entity selectors, NBT, coordinates, resource locations
-
-- **Code snippets**
-  - `fn` → function declaration
-  - `tickfn` → `@tick` function
-  - `tickratefn` → `@tick(rate=N)` function
-  - `trigfn` → `@on_trigger` handler
-  - `foreach` → entity foreach loop
-  - `struct` → struct declaration
-  - `for` → C-style for loop
-  - `spawn` → spawn_object call
-  - And more...
+  - Format strings: `f"Hello {name}!"`
+  - All 50 stdlib modules
+
+- **mcfunction** (`.mcfunction` files)
+  - Full command syntax highlighting
+  - Entity selectors, NBT, coordinates
+
+### Language Server (LSP)
+
+- **Diagnostics** — Real-time error checking
+- **Hover** — Type info and `///` doc comments
+- **Go to Definition** — Jump to function/struct declarations
+- **Auto-complete** — Functions, types, stdlib modules
+- **Lint warnings** — 5 built-in lint rules
+
+### Code Snippets
+
+| Trigger | Result |
+|---------|--------|
+| `fn` | Function declaration |
+| `tickfn` | `@tick` function |
+| `struct` | Struct declaration |
+| `match` | Match expression |
+| `foreach` | Entity foreach loop |
+| `result` | Result<T> handling |
 
 ## Install
 
-### From VSIX (manual)
+### VS Code Marketplace
+
+Search for "RedScript" in the Extensions panel, or:
+```
+ext install bkmashiro.redscript-vscode
+```
+
+### Manual (VSIX)
 
 ```bash
 cd editors/vscode
 npm install -g @vscode/vsce
 vsce package
-code --install-extension redscript-vscode-0.1.0.vsix
+code --install-extension redscript-vscode-1.3.80.vsix
 ```
 
-### Note on `.rs` extension
+## File Extensions
 
-RedScript uses `.rs` files, same as Rust. If you have the Rust extension installed, you may need to associate `.rs` files with RedScript manually:
+- `.mcrs` — Recommended (no conflict with Rust)
+- `.rs` — Supported, but may conflict with Rust extension
 
+To force `.rs` as RedScript:
 ```json
 // settings.json
 {
@@ -51,28 +71,30 @@ RedScript uses `.rs` files, same as Rust. If you have the Rust extension install
 }
 ```
 
-Or use `.mcrs` extension (we may switch to this in future).
-
 ## Usage
 
-Write RedScript code with full syntax highlighting:
+```redscript
+import math;
+import player;
 
-```
 @tick(rate=20)
-fn check_zombies() {
-    foreach (z in @e[type=zombie, distance=..10]) {
-        kill(z);
+fn gravity_check() {
+    foreach (p in @a[tag=flying]) {
+        let y = player::get_y(p);
+        if y > 100 {
+            effect::give(p, "slow_falling", 5);
+        }
     }
 }
-
-@on_trigger("claim_reward")
-fn handle_claim() {
-    give(@s, "minecraft:diamond", 1);
-}
 ```
 
-Compile with the CLI:
-
+Compile:
 ```bash
-redscript compile src/main.rs -o dist/mypack/
+redscript build src/ -o dist/mypack/
 ```
+
+## Links
+
+- [RedScript Documentation](https://redscript-docs.pages.dev)
+- [Online Playground](https://redscript.pages.dev)
+- [GitHub](https://github.com/bkmashiro/redscript)