@lewin671/python-vm 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,3 @@
+{
+  "outputStyle": "default"
+}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/Agents.md

@@ -0,0 +1,66 @@
+# Python Compiler Architecture (TypeScript)
+
+## Overview
+
+This project is a Python compiler + interpreter written in TypeScript.
+It follows a classic 4-stage pipeline:
+
+**Lex → Parse → Compile → Execute**
+
+Goal: keep the system **modular, testable, and easy to extend.**
+
+## Architecture
+
+```
+Python Source
+     ↓
+Lexer        → Tokens
+     ↓
+Parser       → AST
+     ↓
+Compiler     → Bytecode
+     ↓
+VM           → Result
+```
+
+Each stage must:
+
+* Do one job only
+* Have clear input/output types
+* Avoid cross-stage coupling
+
+## Engineering Rules
+
+### 1. 500-Line Rule
+
+* **Hard limit:** No `.ts` file over **500 lines**
+* **Refactor early:** At **400 lines**, start splitting
+* **Why:**
+
+  * Easier to read and review
+  * Faster debugging
+  * Better AI/code-assist context
+
+### 2. Modularity
+
+* One file = one main responsibility
+* No “god files”
+* Shared logic goes into `utils/` or `common/`
+
+### 3. Stage Isolation
+
+* Lexer never touches AST
+* Parser never emits bytecode
+* Compiler never executes
+* VM never parses
+
+Each layer talks only through well-defined data structures.
+
+### 4. Test by Stage
+
+* Unit test each stage independently:
+
+  * Lexer → tokens
+  * Parser → AST
+  * Compiler → bytecode
+  * VM → runtime result

package/README.md

@@ -0,0 +1,93 @@
+# @lewin671/python-vm
+
+A Python compiler and interpreter implemented in TypeScript. The compiler currently packages the AST into a bytecode container that the VM executes.
+
+[简体中文](README_zh-CN.md)
+
+## Features
+
+- [x] CLI entry point for running `.py` files
+- [x] Lexer with indentation handling, numbers, strings (including f-strings), keywords, and operators
+- [x] Parser that builds ASTs for statements and expressions (functions, classes, loops, comprehensions, exceptions, and more)
+- [x] Bytecode compiler scaffold that passes ASTs to the VM
+- [x] AST-based virtual machine with scopes, control flow, functions, classes, generators, context managers, and exceptions
+- [x] Python data structures including lists, tuples, dicts, sets, slicing, and comprehensions
+- [x] Built-ins:
+  - Type/conversion: int, float, str, bool, list, tuple, set, type, isinstance
+  - Iteration: range, enumerate, zip, sorted, reversed, map, filter, next
+  - Math/util: abs, round, sum, min, max
+  - I/O: print, open
+- [x] Example scripts and Vitest suite that compare output against system Python
+
+## Getting Started
+
+### Requirements
+
+- Node.js 18+
+- npm
+- Python 3 available on your PATH for tests (set `PYTHON=python3` if needed)
+
+### Install
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+```
+
+If the tests cannot find Python, set the environment variable before running them, for example: `export PYTHON=python3`.
+
+### Run
+
+```bash
+npm run build
+npm start -- examples/hello.py
+```
+
+Or run directly:
+
+```bash
+node dist/index.js examples/hello.py
+```
+
+### Use in TypeScript
+
+After `npm run build`, you can call the compiler from TypeScript. When consuming the package, import from `@lewin671/python-vm`. For local development in this repo, import from `./dist` instead.
+
+```ts
+import { PythonCompiler } from '@lewin671/python-vm';
+
+const compiler = new PythonCompiler();
+const result = compiler.run('print("Hello from TypeScript")');
+
+console.log(result);
+```
+
+## Project Structure
+
+```
+@lewin671/python-vm/
+├── dist/                # Compiled output
+├── examples/            # Sample Python programs used by tests
+├── src/
+│   ├── compiler.ts      # Public PythonCompiler API
+│   ├── compiler_module/ # Bytecode compiler scaffold
+│   ├── index.ts         # CLI entry + exports
+│   ├── lexer/           # Tokenizer
+│   ├── parser/          # AST parser
+│   ├── types/           # Tokens, AST, bytecode types
+│   └── vm/              # AST interpreter (virtual machine)
+├── tests/               # Vitest suites comparing against CPython
+├── package.json
+└── tsconfig.json
+```

package/README_zh-CN.md

@@ -0,0 +1,93 @@
+# @lewin671/python-vm
+
+一个使用 TypeScript 实现的 Python 编译器与解释器。目前编译器会将 AST 打包到字节码容器中，由虚拟机执行。
+
+[English](README.md)
+
+## 功能特性
+
+- [x] CLI 入口，用于运行 `.py` 文件
+- [x] 具备缩进处理、数字/字符串（含 f-string）、关键字与运算符的词法分析器
+- [x] 语法分析器生成 AST，覆盖函数、类、循环、推导式、异常等语句与表达式
+- [x] 字节码编译器框架，将 AST 交给虚拟机执行
+- [x] 基于 AST 的虚拟机，支持作用域、控制流、函数、类、生成器、上下文管理器与异常
+- [x] Python 数据结构支持：list、tuple、dict、set、切片与推导式
+- [x] 内置函数：
+  - 类型/转换：int、float、str、bool、list、tuple、set、type、isinstance
+  - 迭代相关：range、enumerate、zip、sorted、reversed、map、filter、next
+  - 数值/工具：abs、round、sum、min、max
+  - 输入输出：print、open
+- [x] 示例脚本与 Vitest 测试，输出对比系统 Python
+
+## 快速开始
+
+### 环境要求
+
+- Node.js 18+
+- npm
+- Python 3（运行测试需要，确保在 PATH 中；必要时设置 `PYTHON=python3`）
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 测试
+
+```bash
+npm test
+```
+
+如果测试无法找到 Python，可先设置环境变量，例如：`export PYTHON=python3`。
+
+### 运行
+
+```bash
+npm run build
+npm start -- examples/hello.py
+```
+
+或直接运行：
+
+```bash
+node dist/index.js examples/hello.py
+```
+
+### 在 TypeScript 中调用
+
+运行 `npm run build` 后，可以在 TypeScript 中这样调用。作为依赖使用时请从 `@lewin671/python-vm` 导入，本仓库本地开发时则从 `./dist` 导入。
+
+```ts
+import { PythonCompiler } from '@lewin671/python-vm';
+
+const compiler = new PythonCompiler();
+const result = compiler.run('print("Hello from TypeScript")');
+
+console.log(result);
+```
+
+## 项目结构
+
+```
+@lewin671/python-vm/
+├── dist/                # 编译输出
+├── examples/            # 测试用 Python 示例
+├── src/
+│   ├── compiler.ts      # PythonCompiler 公共 API
+│   ├── compiler_module/ # 字节码编译器框架
+│   ├── index.ts         # CLI 入口 + 导出
+│   ├── lexer/           # 词法分析器
+│   ├── parser/          # 语法分析器
+│   ├── types/           # Token/AST/字节码类型
+│   └── vm/              # AST 解释执行器
+├── tests/               # 与 CPython 对比的 Vitest 测试
+├── package.json
+└── tsconfig.json
+```

package/SETUP.md

@@ -0,0 +1,171 @@
+# 项目设置和测试说明
+
+## 项目概览
+
+这是一个用 TypeScript 实现的 Python 编译器项目。目前编译器核心功能尚未完全实现，使用方法壳来定义接口。
+
+## 当前状态
+
+### ✅ 已完成
+- 项目结构搭建
+- 配置文件（TypeScript, Jest, ESLint, Prettier）
+- 编译器接口定义（方法壳）
+- 完整的测试用例
+- Python 示例脚本（可在 shell 中正常运行）
+
+### 🚧 待实现
+- 词法分析器（Tokenizer）
+- 语法分析器（Parser）
+- 编译器（Compiler）
+- 虚拟机（VM）
+
+## 快速开始
+
+### 安装依赖
+```bash
+npm install
+```
+
+### 编译项目
+```bash
+npm run build
+```
+
+### 运行测试
+```bash
+npm test
+```
+
+**注意：** 测试预期会失败，因为编译器核心功能尚未实现。所有 24 个测试都会报错：
+```
+Error: Tokenizer not implemented yet
+```
+
+这是正常的！这表明：
+1. 测试框架正常工作
+2. 测试用例正确配置
+3. 编译器接口定义完整
+4. 现在可以开始实现各个模块
+
+## 验证 Python 脚本
+
+所有示例 Python 脚本都可以在 shell 中正常运行：
+
+```bash
+# Hello World
+python3 examples/hello.py
+
+# 数学运算
+python3 examples/math.py
+
+# 斐波那契数列
+python3 examples/fibonacci.py
+
+# 条件语句
+python3 examples/conditions.py
+
+# 循环
+python3 examples/loops.py
+```
+
+## 项目结构
+
+```
+python-compiler-ts/
+├── src/
+│   ├── compiler.ts       # 编译器主类（方法壳）
+│   └── index.ts          # CLI 入口
+├── tests/
+│   └── compiler.test.ts  # 24 个测试用例
+├── examples/             # Python 示例脚本
+│   ├── hello.py         # Hello World
+│   ├── math.py          # 数学运算
+│   ├── fibonacci.py     # 递归函数
+│   ├── conditions.py    # 条件语句
+│   └── loops.py         # 循环语句
+├── dist/                # 编译输出（npm run build）
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+└── README.md
+```
+
+## 测试覆盖范围
+
+测试用例涵盖以下 Python 特性：
+
+1. **Hello World** (2 tests)
+   - 简单的 print 语句
+   - 运行 hello.py 文件
+
+2. **变量和算术运算** (3 tests)
+   - 变量赋值
+   - 基本算术运算
+   - 运行 math.py 文件
+
+3. **函数** (4 tests)
+   - 函数定义
+   - 函数调用
+   - 递归函数
+   - 运行 fibonacci.py 文件
+
+4. **控制流** (3 tests)
+   - if 语句
+   - if-elif-else 语句
+   - 运行 conditions.py 文件
+
+5. **循环** (4 tests)
+   - for 循环（range）
+   - while 循环
+   - 列表迭代
+   - 运行 loops.py 文件
+
+6. **数据类型** (5 tests)
+   - 整数
+   - 浮点数
+   - 字符串
+   - 布尔值
+   - 列表
+
+7. **运算符** (3 tests)
+   - 算术运算符（+, -, *, /, %, **）
+   - 比较运算符（==, !=, <, >, <=, >=）
+   - 逻辑运算符（and, or, not）
+
+**总计：24 个测试用例，全部预期失败**
+
+## 下一步
+
+1. 实现 `tokenize()` 方法 - 词法分析
+2. 实现 `parse()` 方法 - 语法分析
+3. 实现 `compile()` 方法 - 编译到字节码
+4. 实现 `execute()` 方法 - 虚拟机执行
+5. 逐步通过测试用例
+
+## 开发命令
+
+```bash
+# 开发模式（监听文件变化）
+npm run dev
+
+# 运行测试（监听模式）
+npm run test:watch
+
+# 测试覆盖率
+npm run test:coverage
+
+# 代码检查
+npm run lint
+
+# 代码格式化
+npm run format
+```
+
+## 贡献指南
+
+1. 从简单的功能开始实现（如：整数字面量、变量赋值）
+2. 确保每次实现后运行测试
+3. 逐步增加复杂度
+4. 保持代码整洁和文档更新
+
+祝你编码愉快！🚀

package/dist/compiler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Python Compiler - 主入口
+ * 用于编译和执行 Python 代码
+ */
+export declare class PythonCompiler {
+    /**
+     * 编译并运行 Python 代码
+     * @param code Python 源代码
+     * @returns 执行结果
+     */
+    run(code: string): any;
+    /**
+     * 运行 Python 文件
+     * @param filePath 文件路径
+     * @returns 执行结果
+     */
+    runFile(filePath: string): any;
+}
+export * from './types';
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Python Compiler - 主入口
+ * 用于编译和执行 Python 代码
+ */
+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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonCompiler = void 0;
+const lexer_1 = require("./lexer");
+const parser_1 = require("./parser");
+const compiler_module_1 = require("./compiler_module");
+const vm_1 = require("./vm");
+const path = __importStar(require("path"));
+class PythonCompiler {
+    /**
+     * 编译并运行 Python 代码
+     * @param code Python 源代码
+     * @returns 执行结果
+     */
+    run(code) {
+        // 1. 词法分析
+        const lexer = new lexer_1.Lexer(code);
+        const tokens = lexer.tokenize();
+        // 2. 语法分析
+        const parser = new parser_1.Parser(tokens);
+        const ast = parser.parse();
+        // 3. 编译到字节码
+        const compiler = new compiler_module_1.Compiler();
+        const bytecode = compiler.compile(ast);
+        // 4. 执行字节码
+        const vm = new vm_1.VirtualMachine([process.cwd()]);
+        const result = vm.execute(bytecode);
+        return result;
+    }
+    /**
+     * 运行 Python 文件
+     * @param filePath 文件路径
+     * @returns 执行结果
+     */
+    runFile(filePath) {
+        const fs = require('fs');
+        const code = fs.readFileSync(filePath, 'utf-8');
+        const lexer = new lexer_1.Lexer(code);
+        const tokens = lexer.tokenize();
+        const parser = new parser_1.Parser(tokens);
+        const ast = parser.parse();
+        const compiler = new compiler_module_1.Compiler();
+        const bytecode = compiler.compile(ast);
+        const vm = new vm_1.VirtualMachine([path.dirname(filePath), process.cwd()]);
+        return vm.execute(bytecode);
+    }
+}
+exports.PythonCompiler = PythonCompiler;
+// 重新导出类型，供外部使用
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=compiler.js.map

package/dist/compiler_module/compiler.d.ts

@@ -0,0 +1,8 @@
+import { ASTNode, ByteCode } from '../types';
+/**
+ * 编译器 - 将 AST 编译为字节码
+ */
+export declare class Compiler {
+    compile(ast: ASTNode): ByteCode;
+}
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler_module/compiler.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Compiler = void 0;
+const types_1 = require("../types");
+/**
+ * 编译器 - 将 AST 编译为字节码
+ */
+class Compiler {
+    compile(ast) {
+        if (ast.type !== types_1.ASTNodeType.PROGRAM) {
+            throw new Error(`Expected Program node, got ${ast.type}`);
+        }
+        return {
+            instructions: [],
+            constants: [],
+            names: [],
+            ast
+        };
+    }
+}
+exports.Compiler = Compiler;
+//# sourceMappingURL=compiler.js.map

package/dist/compiler_module/index.d.ts

@@ -0,0 +1,2 @@
+export { Compiler } from './compiler';
+//# sourceMappingURL=index.d.ts.map

package/dist/compiler_module/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Compiler = void 0;
+var compiler_1 = require("./compiler");
+Object.defineProperty(exports, "Compiler", { enumerable: true, get: function () { return compiler_1.Compiler; } });
+//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { PythonCompiler } from './compiler';
+export { PythonCompiler };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+"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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonCompiler = void 0;
+const compiler_1 = require("./compiler");
+Object.defineProperty(exports, "PythonCompiler", { enumerable: true, get: function () { return compiler_1.PythonCompiler; } });
+const fs = __importStar(require("fs"));
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.error('Usage: PyVM <file.py>');
+        process.exit(1);
+    }
+    const filePath = args[0];
+    if (!fs.existsSync(filePath)) {
+        console.error(`Error: File '${filePath}' not found`);
+        process.exit(1);
+    }
+    const compiler = new compiler_1.PythonCompiler();
+    try {
+        const result = compiler.runFile(filePath);
+        if (result !== undefined) {
+            console.log(result);
+        }
+    }
+    catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+if (require.main === module) {
+    main();
+}
+//# sourceMappingURL=index.js.map

package/dist/lexer/index.d.ts

@@ -0,0 +1,2 @@
+export { Lexer } from './lexer';
+//# sourceMappingURL=index.d.ts.map

package/dist/lexer/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lexer = void 0;
+var lexer_1 = require("./lexer");
+Object.defineProperty(exports, "Lexer", { enumerable: true, get: function () { return lexer_1.Lexer; } });
+//# sourceMappingURL=index.js.map

package/dist/lexer/lexer.d.ts

@@ -0,0 +1,16 @@
+import { Token } from '../types';
+/**
+ * 词法分析器 - 将源代码转换为 token 流
+ */
+export declare class Lexer {
+    private code;
+    private pos;
+    private line;
+    private column;
+    private tokens;
+    private indentStack;
+    private atLineStart;
+    constructor(code: string);
+    tokenize(): Token[];
+}
+//# sourceMappingURL=lexer.d.ts.map