Reglace — Code Transformation Runtime

EN: A language-neutral code transformation runtime with source-mapping capability. 中文: 一个带源码回映能力的、语言相对中立的、可预览和可追踪的代码变换运行时。

It is NOT a programming language, nor a full compiler. 它不是编程语言，也不是完整编译器。

Core Capabilities / 核心能力

English	中文
Rule validation for `.reglace.json` and `.reglace.js`	验证规则文件
Stable execution order (priority + declaration order)	稳定执行顺序（priority 排序 + 声明顺序）
Match tracking (original interval, replacement, output interval)	匹配追踪（原始区间、替换文本、输出区间）
Conflict detection for overlapping matches	冲突检测（重叠匹配告警）
Dry-run / preview (read-only, no writes)	Dry-run / 预览（只看不写）
Multi-round fixpoint with loop and growth guards	多轮执行（fixpoint 收敛 + 死循环+增长保护）
Machine-readable JSON reports for CI/Agent	JSON 机器可读报告（供 CI/Agent 消费）
MCP protocol support for LLM Agent integration	MCP 协议支持（LLM Agent 可直接调用）

Install / 安装

npm install
npm run compile        # Build everything / 编译全部

Quick Start / 快速开始

1. Create a rule file / 写规则文件 `transform.reglace.json`

[
    {
        "name": "for_var_to_auto",
        "rule": {
            "search": "(^|[\\s\\n\\r])for(\\s*)\\((\\s*)var([\\s\\n\\r])",
            "replace": "$1for$2($3auto$4"
        }
    }
]

2. Create a build config / 写构建配置 `regmake.json`

[{
    "rules": ["transform"],
    "replace": [{ "src": "src/*.mate", "out": "build/{name}.cpp" }]
}]

EN: "transform" has no extension — it automatically loads transform.reglace.json + transform.reglace.js. 中文: "transform" 无扩展名，自动加载 transform.reglace.json + transform.reglace.js。

3. Run / 运行

reglace validate transform.reglace.json              # Validate rules / 验证规则
reglace preview transform.reglace.json src/*.mate     # Preview (dry-run) / 预览
reglace apply transform.reglace.json src/*.mate       # Apply / 应用
reglace build regmake.json                            # Build / 构建

Rule Format / 规则格式

JSON Rules / JSON 规则（`.reglace.json`）

[{
    "name": "rule_name",
    "rule": {
        "search": "regex_pattern",
        "replace": "replacement_string"
    },
    "priority": 0,
    "scope": "!comment"
}]

Field / 字段	Type / 类型	Description / 说明
`name`	string	Rule name for match tracking / 规则名称
`rule.search`	string	JavaScript regex pattern
`rule.replace`	string	Replacement, supports `$1` `$&` / 替换串
`rule.flags`	string	Regex flags, default `g`
`priority`	number	Higher runs first / 越大越先执行
`scope`	string	Scope restriction / 匹配范围限制

Scope / 范围限制

Value / 值	Meaning / 含义
`"string"`	Inside string literals / 字符串内
`"!string"`	Outside string literals / 字符串外
`"comment"` / `"!comment"`	Inside/outside comments / 注释内/外
`"code"`	Outside strings and comments / 代码区
`"bracket{}"` / `"bracket()"` / `"bracket[]"`	Inside balanced brackets / 括号内
`"range:10-20"`	Line range / 行区间
`"region:name"`	User-defined region / 用户定义区域
`"define:name"`	Define reusable pattern / 定义可复用模式

Pattern References / 模式引用 `{{name}}`

Use {{name}} within search to reference defined patterns, and {{generator('arg')}} to call generators:

{
    "search": "call_{{balanced('(', ')')}}",
    "replace": "new_call$1"
}

Standard Library / 标准库

packages/core/lib/ ships with paired library files / 包含配对的标准库文件：

lib/
├── base.reglace.json    ← Static pattern definitions / 静态模式定义
└── base.reglace.js      ← Parameterized generators / 参数化生成器

Built-in Generators / 内置生成器

Generator / 生成器	Example / 示例	Generates / 生成结果
`{{balanced('(', ')')}}`	Balanced pairs	`$[^()](?:\([^()]$[^()])\)`
`{{string("'")}}`	String literal	`'(?:[^'\\]\|\\.)*'`
`{{line_comment('//')}}`	Line comment	`//[^\n]*`

Users can add custom generators by creating .reglace.js files in lib/. 用户可以在 lib/ 下创建自己的 .reglace.js 文件添加生成器。

Build System (Regmake) / 构建系统

regmake.json is a project-level build config, similar to a Makefile / 项目的构建配置文件：

[{
    "$id": "my-build",
    "rules": ["transform"],
    "exclude": ["**/test/**"],
    "replace": [
        { "src": "src/**/*.mate", "out": "build/{name}.cpp", "exclude": ["**/generated/**"] }
    ]
}, {
    "$ref": "my-build",
    "replace": [{ "src": "extra/*.mate", "out": "build/{name}.cpp" }]
}]

Feature / 特性	Description / 说明
`$id` / `$ref`	Deduplicate rules / 避免重复写规则
Glob in `src`	Expanded via picomatch
`{name}` `{ext}` in `out`	Path templates / 路径模板
`exclude`	File exclusion (entry-level + target-level)
Extensionless rule names	`"transform"` loads `.reglace.json` + `.reglace.js`

CLI Commands / CLI 命令

reglace validate <rules-file>                     # Validate rules / 验证规则
reglace preview <rules> <paths>                   # Preview (dry-run) / 预览
reglace apply <rules> <paths>                     # Apply and write / 应用
reglace build <regmake.json>                      # Build / 构建
reglace build <regmake.json> --json               # Machine-readable JSON / 机器可读
reglace preview <rules> <paths> --include "*.mate" --exclude "*.h"

VS Code Extension / VS Code 扩展

Features / 特性

English	中文
Edit `.mate` source files, auto-generate target files (e.g. `.cpp`)	编辑源文件，自动生成目标文件
Hover to see corresponding generated code side-by-side	悬停查看对应生成代码
Compiler diagnostics mirrored back to source files	编译器诊断镜像回源文件
Mapping cache in `*.reglace.json` for fast lookup	映射缓存加速查找

Settings / 配置

Setting / 设置	Description / 说明
`reglace.runOnSave`	Auto-run on save / 保存时自动执行
`reglace.mirrorDiagnosticsMode`	Diagnostic mirroring mode / 诊断镜像模式
`reglace.debugMappings`	Debug logging / 调试日志
`reglace.autoApplyMateLanguage`	Auto-apply target language mode / 自动切换语言模式

Commands / 命令

Command / 命令	EN	中文
`reglace.openGenerated`	Open Generated File	打开生成文件
`reglace.openSource`	Open Source File	打开源文件
`reglace.showDiff`	Show Diff	显示对比
`reglace.applyMateLanguage`	Apply Mate Language	应用目标语言模式
`reglace.toggleHighlight`	Toggle Highlight	切换高亮

Workflow / 工作流

Create regmake.json in your project root / 在工作目录创建 regmake.json
Create rule files (.reglace.json + .reglace.js) / 创建规则文件
Edit source files (.mate), auto-generate on save / 编辑源文件，保存时自动生成
Use Reglace: Open Generated to see full LSP support / 打开生成文件查看 LSP
Generated diagnostics are mirrored back to source / 诊断自动回映

Engineering Constraints / 工程约束

Core (@reglace/core) has zero vscode dependency — pure Node.js built-ins
Deterministic: same input + rules + version → same output / 确定性的
JSON rules first: canonical format; JS rules are optional extensions
JSON output: CLI --json is designed for MCP/Agent adapters
No LLM integration in core or CLI. LLM is a user / 不包含 LLM
Backward compatible: old .reglace and .js files still work / 兼容旧格式

reglace

LiXiaYu