redscript-mc 3.0.1 → 3.0.2

package/dist/src/parser/type-parser.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * TypeParser — parses type annotations and generic type arguments.
+ * Extends ParserBase to gain token navigation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeParser = void 0;
+const utils_1 = require("./utils");
+class TypeParser extends utils_1.ParserBase {
+    // -------------------------------------------------------------------------
+    // Type Parsing
+    // -------------------------------------------------------------------------
+    parseType() {
+        const token = this.peek();
+        let type;
+        if (token.kind === '(') {
+            // Disambiguate: tuple type `(T, T)` vs function type `(T) -> R`
+            const saved = this.pos;
+            this.advance(); // consume '('
+            const elements = [];
+            if (!this.check(')')) {
+                do {
+                    elements.push(this.parseType());
+                } while (this.match(','));
+            }
+            this.expect(')');
+            if (this.check('->')) {
+                this.pos = saved;
+                return this.parseFunctionType();
+            }
+            return { kind: 'tuple', elements };
+        }
+        if (token.kind === 'float') {
+            this.advance();
+            const filePart = this.filePath ? `${this.filePath}:` : '';
+            this.warnings.push(`[DeprecatedType] ${filePart}line ${token.line}, col ${token.col}: 'float' is deprecated, use 'fixed' instead (×10000 fixed-point)`);
+            type = { kind: 'named', name: 'float' };
+        }
+        else if (token.kind === 'int' || token.kind === 'bool' ||
+            token.kind === 'fixed' || token.kind === 'string' || token.kind === 'void' ||
+            token.kind === 'BlockPos') {
+            this.advance();
+            type = { kind: 'named', name: token.kind };
+        }
+        else if (token.kind === 'ident') {
+            this.advance();
+            if (token.value === 'selector' && this.check('<')) {
+                this.advance(); // consume <
+                const entityType = this.expect('ident').value;
+                this.expect('>');
+                type = { kind: 'selector', entityType };
+            }
+            else if (token.value === 'selector') {
+                type = { kind: 'selector' };
+            }
+            else if (token.value === 'Option' && this.check('<')) {
+                this.advance(); // consume <
+                const inner = this.parseType();
+                this.expect('>');
+                type = { kind: 'option', inner };
+            }
+            else if (token.value === 'double' || token.value === 'byte' ||
+                token.value === 'short' || token.value === 'long' ||
+                token.value === 'format_string') {
+                type = { kind: 'named', name: token.value };
+            }
+            else {
+                type = { kind: 'struct', name: token.value };
+            }
+        }
+        else {
+            this.error(`Expected type, got '${token.value || token.kind}'. Valid types: int, float, bool, string, void, or a struct/enum name`);
+        }
+        while (this.match('[')) {
+            this.expect(']');
+            type = { kind: 'array', elem: type };
+        }
+        return type;
+    }
+    parseFunctionType() {
+        this.expect('(');
+        const params = [];
+        if (!this.check(')')) {
+            do {
+                params.push(this.parseType());
+            } while (this.match(','));
+        }
+        this.expect(')');
+        this.expect('->');
+        const returnType = this.parseType();
+        return { kind: 'function_type', params, return: returnType };
+    }
+    /**
+     * Try to parse `<Type, ...>` as explicit generic type arguments.
+     * Returns the parsed type list if successful, null if this looks like a comparison.
+     * Does NOT consume any tokens if it returns null.
+     */
+    tryParseTypeArgs() {
+        const saved = this.pos;
+        this.advance(); // consume '<'
+        const typeArgs = [];
+        try {
+            do {
+                typeArgs.push(this.parseType());
+            } while (this.match(','));
+            if (!this.check('>')) {
+                this.pos = saved;
+                return null;
+            }
+            this.advance(); // consume '>'
+            return typeArgs;
+        }
+        catch {
+            this.pos = saved;
+            return null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Lambda lookahead helpers (needed by expr-parser)
+    // -------------------------------------------------------------------------
+    isLambdaStart() {
+        if (!this.check('('))
+            return false;
+        let offset = 1;
+        if (this.peek(offset).kind !== ')') {
+            while (true) {
+                if (this.peek(offset).kind !== 'ident') {
+                    return false;
+                }
+                offset += 1;
+                if (this.peek(offset).kind === ':') {
+                    offset += 1;
+                    const consumed = this.typeTokenLength(offset);
+                    if (consumed === 0) {
+                        return false;
+                    }
+                    offset += consumed;
+                }
+                if (this.peek(offset).kind === ',') {
+                    offset += 1;
+                    continue;
+                }
+                break;
+            }
+        }
+        if (this.peek(offset).kind !== ')') {
+            return false;
+        }
+        offset += 1;
+        if (this.peek(offset).kind === '=>') {
+            return true;
+        }
+        if (this.peek(offset).kind === '->') {
+            offset += 1;
+            const consumed = this.typeTokenLength(offset);
+            if (consumed === 0) {
+                return false;
+            }
+            offset += consumed;
+            return this.peek(offset).kind === '=>';
+        }
+        return false;
+    }
+    typeTokenLength(offset) {
+        const token = this.peek(offset);
+        if (token.kind === '(') {
+            let inner = offset + 1;
+            if (this.peek(inner).kind !== ')') {
+                while (true) {
+                    const consumed = this.typeTokenLength(inner);
+                    if (consumed === 0) {
+                        return 0;
+                    }
+                    inner += consumed;
+                    if (this.peek(inner).kind === ',') {
+                        inner += 1;
+                        continue;
+                    }
+                    break;
+                }
+            }
+            if (this.peek(inner).kind !== ')') {
+                return 0;
+            }
+            inner += 1;
+            if (this.peek(inner).kind !== '->') {
+                return 0;
+            }
+            inner += 1;
+            const returnLen = this.typeTokenLength(inner);
+            return returnLen === 0 ? 0 : inner + returnLen - offset;
+        }
+        const isNamedType = token.kind === 'int' ||
+            token.kind === 'bool' ||
+            token.kind === 'float' ||
+            token.kind === 'fixed' ||
+            token.kind === 'string' ||
+            token.kind === 'void' ||
+            token.kind === 'BlockPos' ||
+            token.kind === 'ident';
+        if (!isNamedType) {
+            return 0;
+        }
+        let length = 1;
+        while (this.peek(offset + length).kind === '[' && this.peek(offset + length + 1).kind === ']') {
+            length += 2;
+        }
+        return length;
+    }
+    // -------------------------------------------------------------------------
+    // Params parsing (used by decl-parser)
+    // -------------------------------------------------------------------------
+    parseParams(implTypeName) {
+        const params = [];
+        if (!this.check(')')) {
+            do {
+                const paramToken = this.expect('ident');
+                const name = paramToken.value;
+                let type;
+                if (implTypeName && params.length === 0 && name === 'self' && !this.check(':')) {
+                    type = { kind: 'struct', name: implTypeName };
+                }
+                else {
+                    this.expect(':');
+                    type = this.parseType();
+                }
+                let defaultValue;
+                if (this.match('=')) {
+                    defaultValue = this.parseExpr();
+                }
+                params.push(this.withLoc({ name, type, default: defaultValue }, paramToken));
+            } while (this.match(','));
+        }
+        return params;
+    }
+    parseInterfaceParams() {
+        const params = [];
+        if (!this.check(')')) {
+            do {
+                const paramToken = this.expect('ident');
+                const paramName = paramToken.value;
+                let type;
+                if (params.length === 0 && paramName === 'self' && !this.check(':')) {
+                    type = { kind: 'named', name: 'void' };
+                }
+                else {
+                    this.expect(':');
+                    type = this.parseType();
+                }
+                params.push(this.withLoc({ name: paramName, type }, paramToken));
+            } while (this.match(','));
+        }
+        return params;
+    }
+}
+exports.TypeParser = TypeParser;
+//# sourceMappingURL=type-parser.js.map

package/dist/src/parser/utils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parser utilities — base class with token navigation, error handling,
+ * and shared constants used by all sub-parsers.
+ */
+import { Lexer, type Token, type TokenKind } from '../lexer';
+import { DiagnosticError } from '../diagnostics';
+export declare const PRECEDENCE: Record<string, number>;
+export declare const BINARY_OPS: Set<string>;
+export type { Lexer };
+export declare class ParserBase {
+    protected tokens: Token[];
+    protected pos: number;
+    protected sourceLines: string[];
+    protected filePath?: string;
+    /** Set to true once `module library;` is seen. */
+    protected inLibraryMode: boolean;
+    /** Warnings accumulated during parsing (e.g. deprecated keyword usage). */
+    readonly warnings: string[];
+    /** Parse errors collected during error-recovery mode. */
+    readonly parseErrors: DiagnosticError[];
+    constructor(tokens: Token[], source?: string, filePath?: string);
+    peek(offset?: number): Token;
+    advance(): Token;
+    check(kind: TokenKind): boolean;
+    match(...kinds: TokenKind[]): boolean;
+    expect(kind: TokenKind): Token;
+    error(message: string): never;
+    withLoc<T extends object>(node: T, token: Token): T;
+    getLocToken(node: object): Token | null;
+    checkIdent(value: string): boolean;
+    syncToNextDecl(): void;
+    syncToNextStmt(): void;
+    protected makeSubParser(source: string): ParserBase;
+}

package/dist/src/parser/utils.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Parser utilities — base class with token navigation, error handling,
+ * and shared constants used by all sub-parsers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParserBase = exports.BINARY_OPS = exports.PRECEDENCE = void 0;
+const lexer_1 = require("../lexer");
+const diagnostics_1 = require("../diagnostics");
+// ---------------------------------------------------------------------------
+// Operator Precedence (higher = binds tighter)
+// ---------------------------------------------------------------------------
+exports.PRECEDENCE = {
+    '||': 1,
+    '&&': 2,
+    '==': 3, '!=': 3,
+    '<': 4, '<=': 4, '>': 4, '>=': 4, 'is': 4,
+    '+': 5, '-': 5,
+    '*': 6, '/': 6, '%': 6,
+};
+exports.BINARY_OPS = new Set(['||', '&&', '==', '!=', '<', '<=', '>', '>=', 'is', '+', '-', '*', '/', '%']);
+// ---------------------------------------------------------------------------
+// ParserBase — token navigation, error reporting, span attachment
+// ---------------------------------------------------------------------------
+class ParserBase {
+    constructor(tokens, source, filePath) {
+        this.pos = 0;
+        /** Set to true once `module library;` is seen. */
+        this.inLibraryMode = false;
+        /** Warnings accumulated during parsing (e.g. deprecated keyword usage). */
+        this.warnings = [];
+        /** Parse errors collected during error-recovery mode. */
+        this.parseErrors = [];
+        this.tokens = tokens;
+        this.sourceLines = source?.split('\n') ?? [];
+        this.filePath = filePath;
+    }
+    // -------------------------------------------------------------------------
+    // Token navigation
+    // -------------------------------------------------------------------------
+    peek(offset = 0) {
+        const idx = this.pos + offset;
+        if (idx >= this.tokens.length) {
+            return this.tokens[this.tokens.length - 1]; // eof
+        }
+        return this.tokens[idx];
+    }
+    advance() {
+        const token = this.tokens[this.pos];
+        if (token.kind !== 'eof')
+            this.pos++;
+        return token;
+    }
+    check(kind) {
+        return this.peek().kind === kind;
+    }
+    match(...kinds) {
+        for (const kind of kinds) {
+            if (this.check(kind)) {
+                this.advance();
+                return true;
+            }
+        }
+        return false;
+    }
+    expect(kind) {
+        const token = this.peek();
+        if (token.kind !== kind) {
+            throw new diagnostics_1.DiagnosticError('ParseError', `Expected '${kind}' but got '${token.kind}'`, { file: this.filePath, line: token.line, col: token.col }, this.sourceLines);
+        }
+        return this.advance();
+    }
+    error(message) {
+        const token = this.peek();
+        throw new diagnostics_1.DiagnosticError('ParseError', message, { file: this.filePath, line: token.line, col: token.col }, this.sourceLines);
+    }
+    withLoc(node, token) {
+        const span = { line: token.line, col: token.col };
+        Object.defineProperty(node, 'span', {
+            value: span,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+        return node;
+    }
+    getLocToken(node) {
+        const span = node.span;
+        if (!span) {
+            return null;
+        }
+        return { kind: 'eof', value: '', line: span.line, col: span.col };
+    }
+    checkIdent(value) {
+        return this.check('ident') && this.peek().value === value;
+    }
+    // -------------------------------------------------------------------------
+    // Error Recovery
+    // -------------------------------------------------------------------------
+    syncToNextDecl() {
+        const TOP_LEVEL_KEYWORDS = new Set([
+            'fn', 'struct', 'impl', 'enum', 'const', 'let', 'export', 'declare', 'import', 'namespace', 'module'
+        ]);
+        while (!this.check('eof')) {
+            const kind = this.peek().kind;
+            if (kind === '}') {
+                this.advance();
+                return;
+            }
+            if (TOP_LEVEL_KEYWORDS.has(kind)) {
+                return;
+            }
+            if (kind === 'ident' && this.peek().value === 'import') {
+                return;
+            }
+            this.advance();
+        }
+    }
+    syncToNextStmt() {
+        while (!this.check('eof')) {
+            const kind = this.peek().kind;
+            if (kind === ';') {
+                this.advance();
+                return;
+            }
+            if (kind === '}') {
+                return;
+            }
+            this.advance();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Sub-parser helper (used by string interpolation)
+    // -------------------------------------------------------------------------
+    makeSubParser(source) {
+        const tokens = new lexer_1.Lexer(source, this.filePath).tokenize();
+        return new ParserBase(tokens, source, this.filePath);
+    }
+}
+exports.ParserBase = ParserBase;
+//# sourceMappingURL=utils.js.map

package/docs/dev/README-mc-integration-tests.md

@@ -0,0 +1,141 @@
+# MC Integration Tests — 操作手册
+
+RedScript 有两层测试：
+
+1. **单元/e2e 测试**：纯编译器，不需要 MC 服务器，直接 `npm test`
+2. **MC 联动测试**：需要 Paper 服务器 + TestHarness 插件，测试生成的 mcfunction 在真实 MC 里是否正确执行
+
+---
+
+## 快速跑法
+
+```bash
+# 1. 确认服务器在跑
+curl http://localhost:25561/status
+
+# 2. 跑所有 MC 联动测试
+cd ~/projects/redscript
+MC_SERVER_DIR=~/mc-test-server MC_PORT=25561 npx jest src/__tests__/mc-integration/ --testTimeout=120000 --no-coverage --forceExit
+
+# 3. 跑单个测试文件
+MC_SERVER_DIR=~/mc-test-server MC_PORT=25561 npx jest say-fstring --testTimeout=60000 --forceExit
+```
+
+服务器不在线时，测试会自动跳过（不报错），只有编译时测试会跑。
+
+---
+
+## 启动 Paper 服务器
+
+Java 装在 Homebrew（不在系统 PATH）：
+
+```bash
+export JAVA_HOME="/opt/homebrew/opt/openjdk@21"
+export PATH="$JAVA_HOME/bin:$PATH"
+
+cd ~/mc-test-server
+java -Xmx2G -Xms512M -jar paper.jar --nogui
+```
+
+服务器起来后 TestHarness 插件自动在 **端口 25561** 上开 HTTP API。
+
+验证：
+```bash
+curl http://localhost:25561/status
+# → {"online":true,"tps_1m":20.0,...}
+```
+
+---
+
+## 关键注意事项
+
+### 1. 只能有一个 redscript-test datapack
+
+`~/mc-test-server/world/datapacks/` 里**只留 `redscript-test/`**，其他旧 datapack 全删掉。  
+多个 datapack 有相同 namespace 会导致 MC 用旧版本，测试结果不对。
+
+```bash
+# 清理旧 datapack（只留 redscript-test）
+ls ~/mc-test-server/world/datapacks/
+trash ~/mc-test-server/world/datapacks/<旧的>
+```
+
+### 2. Reload 用 TestHarness API
+
+不要用 `/reload` 命令（需要 `/reload confirm`，Paper 1.21+ 要求）。  
+测试代码里用 `mc.reload()`，它调用的是 `POST /reload`。
+
+### 3. Java 路径
+
+系统 `java` 命令指向一个壳，实际没装。用：
+```bash
+/opt/homebrew/opt/openjdk@21/bin/java -version
+# openjdk version "21.0.10"
+```
+
+---
+
+## 测试文件结构
+
+```
+src/__tests__/mc-integration/
+├── syntax-coverage.test.ts     # 语法特性：for-each、match、Option、impl、struct、array
+├── say-fstring.test.ts         # say() + f-string macro 编译和运行时测试
+├── stdlib-coverage.test.ts     # stdlib 覆盖（数学、物理等）
+├── stdlib-coverage-2~8.test.ts # stdlib 覆盖续集
+└── item-entity-events.test.ts  # 实体/物品/事件
+```
+
+### 写新 test case 的模式
+
+```typescript
+import { compile } from '../../compile'
+import { MCTestClient } from '../../mc-test/client'
+
+const NS = 'my_test_ns'  // 每个文件用唯一 namespace
+let serverOnline = false
+let mc: MCTestClient
+
+beforeAll(async () => {
+  mc = new MCTestClient(process.env.MC_HOST ?? 'localhost', parseInt(process.env.MC_PORT ?? '25561'))
+  try {
+    serverOnline = await mc.isOnline()
+  } catch { serverOnline = false }
+  if (!serverOnline) return
+
+  // 编译 + 写入 datapack
+  writeFixture(`...redscript code...`, NS)
+  await mc.reload()
+  await mc.ticks(5)
+}, 30_000)
+
+test('runtime: xxx', async () => {
+  if (!serverOnline) return  // 服务器不在线就跳过
+
+  await mc.command(`/function ${NS}:fn_name`)
+  await mc.ticks(5)
+  const score = await mc.scoreboard('#result', 'objective')
+  expect(score).toBe(42)
+}, 20_000)
+```
+
+### 可用的 TestHarness API（via MCTestClient）
+
+| 方法 | 说明 |
+|------|------|
+| `mc.isOnline()` | 检查服务器是否在线 |
+| `mc.reload()` | Reload datapacks（正确方式） |
+| `mc.ticks(n)` | 等待 n 个游戏 tick（50ms 各） |
+| `mc.command('/xxx')` | 执行 MC 命令 |
+| `mc.scoreboard(player, obj)` | 读取 scoreboard 值 |
+| `mc.chat(since)` | 读取聊天日志 |
+| `mc.assertChatContains(str)` | 断言聊天包含字符串 |
+| `mc.reset()` | 清空聊天和事件日志 |
+| `mc.fullReset(...)` | 完整重置（清空区域、实体、scoreboard） |
+
+---
+
+## 已知问题
+
+- `impl Counter` 测试（syntax-coverage）：runtime 失败，`#impl_out` 读到 0 而不是 3。这是预存在的 impl 方法运行时 bug，与 f-string/say macro 无关。
+- `repl-server-extra.test.ts`：端口 3001 占用导致 10 个测试失败，与代码无关。