# MoonJinja 0.2 兼容矩阵

MoonJinja 以 Jinja/MiniJinja 的常用运行时语义为参照，不承诺完整复刻 Jinja 的
Python 对象模型。下表对应 `src/environment_test.mbt` 中的黑盒回归。

| 能力 | 0.2 状态 | 正例 | 反例/边界 |
| --- | --- | --- | --- |
| `ToJson` 上下文 | 支持 | 对象、数组、整数、浮点、布尔、null | 非对象根值映射到 `value` |
| 变量/路径/索引 | 支持 | `user.name`、`xs[0]`、`map["k"]` | 越界在严格模式报 undefined |
| 表达式 | 支持 | 真除法、floor/mod、`**`、`~`、比较链、行内 if、值语义逻辑、`in`、`is` | 除零、非法类型操作报错 |
| `if` | 支持 | `elif`、`else` | 未闭合标签报解析错误 |
| `for` | 支持 | `else`、loop 元数据、break/continue | 循环外 break/continue 在解析期拒绝 |
| include | 支持 | 默认带 context、`without context` | 名称越界和 include 循环拒绝 |
| scope | 支持 | `with`、loop、macro 局部 scope | include 内 `set` 不泄漏给调用者 |
| macro | 支持 | 默认参数、keyword 参数、call/caller | 缺参、多参、重复或未知参数报错 |
| import | 支持 | 命名空间 import、from-import | 只导入模板顶层宏 |
| 继承 | 支持 | 多级 extends、super、self.block | 继承循环拒绝 |
| autoescape | 支持 | HTML named entities、SafeStr | `safe` 只适合可信内容 |
| 空白控制 | 支持 | `-` 标记、raw trim、trim/lstrip 配置 | 不实现 Jinja 的 `+` 禁用标记 |
| raw/comment | 支持 | raw 原样输出、comment 丢弃 | 未闭合时返回带行列的 lexer error |
| 扩展 registry | 支持 | filter/function/test、context、keyword args | 回调值深拷贝，业务错误返回 `Result` |
| 缓存/限制 | 支持 | 有界/禁用缓存、版本化自动刷新、fuel、解析/渲染/include、UTF-8 字节和 range 上限 | 超限立即失败 |
| 诊断 | 支持 | stage、模板名、行列、UTF-8 byte span、模板 trace | 所有失败保持类型化 |
| 流式输出 | 支持 | `render_to` / `render_json_to` | sink 为同步回调 |
| sandbox | 支持 | 强制转义、禁用 safe、扩展 allowlist | loader/获准回调仍是可信宿主代码 |

## 刻意不兼容

- 不暴露 Python/Jinja 的任意对象属性、方法调用或动态反射；输入统一经过 `ToJson`。
- 不实现可变参数、tuple unpacking、切片、递归 loop、async、Jinja extension tags
  和 Python 运算符的全部细节。
- `include`、macro 和 loop 使用隔离 scope，模板不能修改调用者传入的数据。
- 模板 loader 使用逻辑名称，不提供核心文件系统访问；应用自行决定名称如何映射到存储。
- 资源限制是解释器边界。自定义回调属于可信代码，其 CPU、内存和副作用由应用负责。

## 回归策略

- valid/invalid golden 场景由公开 API 黑盒测试覆盖。
- 四个后端执行相同测试集。
- 多组完整模板的每个截断前缀和 512 组可复现生成输入都必须成功或返回类型化错误，不能数组越界。
- `tools/minijinja-oracle` 在 CI 中运行 MiniJinja 2.21 差分夹具。
- Jinja 共有语义的期望值按 Jinja/MiniJinja 文档固定；刻意差异记录在本文件中。