moonbit

mustache

template

rendering

moon add bellesz0611/moon-mustache@0.2.0

Download zip

Author

bellesz0611

Version

0.2.0

License

MIT

Repository

github.com/bellesz0611/moon-mustache

Last updated

last month

Downloads

README

#Moon Mustache

Moon Mustache is a reusable Mustache template engine for MoonBit.

Moon Mustache 面向 MoonBit 生态提供一套轻量、稳定、可嵌入的模板渲染能力，重点服务于脚手架生成、配置文件拼装、静态内容渲染、邮件与通知模板、代码生成辅助等真实工程场景。

#Visual tour

#Judge quick look

latest GitHub workflows: library CI and playground smoke checks are green on the default branch
public repositories: GitHub + GitLink are synchronized
competition-relevant handwritten effective MoonBit LOC: about 8032, inside the suggested 4k-10k band
imported generated fixture asset: about 2149 effective LOC, reported separately from handwritten implementation
automated tests: 85 / 85 passing
imported core and optional mustache/spec fixtures: 194 / 194 passing, with zero skips
deterministic cross-implementation differential cases: 2048 / 2048 passing against mustache.js
measured core-library coverage: 81.5%, protected by an 80% CI gate with Cobertura output
public git history: well beyond the required 10-20 meaningful commits and still growing
key demos: CLI rendering, template scanning, bundle generation, scenario report, six consumer-style demos, and a Vue playground backed by the repository's own MoonBit engine
extra evidence: incident-response and developer-release downstream demos, benchmark snapshot, public static site, and SVG showcase assets

Fastest evaluator path:

moon test --deny-warn
moon run showcase
moon run official_spec_report
moon run cli --template "{{#user}}{{name}}{{/user}}{{> footer}}" --scan
cd playground && npm ci && npm run differential

#Repository

GitHub: https://github.com/bellesz0611/moon-mustache
GitLink: https://www.gitlink.org.cn/miemie0619/moon-mustache-mbt
MoonBit package: bellesz0611/moon-mustache
current release: bellesz0611/moon-mustache@0.2.0
mooncakes docs page: https://mooncakes.io/docs/bellesz0611/moon-mustache%400.2.0
online MoonBit playground: https://bellesz0611.github.io/moon-mustache/
workflow entrypoints: library CI and playground smoke workflow
verification artifacts: the default library CI uploads benchmarks, a coverage summary, and Cobertura XML from the wasm-gc lane
release-readiness workflow: artifact-oriented verification
Pages deployment workflow: browser playground deployment
evaluator artifact map: docs/ARTIFACT_INDEX.md
evaluator quick-look page: docs/JUDGE_QUICKLOOK.md
canonical generated metrics snapshot: docs/METRICS_SNAPSHOT.md

#Project positioning

MoonBit 已经具备出色的语言设计和统一工具链，但“把结构化数据可靠地转成文本输出”这类基础能力仍然比较稀缺。很多项目都会重复造一层简单模板系统，而 Mustache 恰好是一种边界清晰、跨语言生态广泛存在、适合作为通用基础库移植到 MoonBit 的方案。

Moon Mustache 选择以 Mustache 规范为核心，优先把最常用、最稳定、最容易复用的能力做好，而不是扩展成一个语法复杂的新模板语言。

#Independent value in MoonBit

MoonBit 生态中已经存在同类尝试，例如 ryota0624/mustache：

mooncakes: https://mooncakes.io/docs/ryota0624/mustache
GitHub: https://github.com/ryota0624/moonbit-mustache

Moon Mustache 不是对现有 MoonBit 同类仓库的简单重复实现，而是围绕“可验收、可复用、可工程化集成”的目标继续把这一方向做完整。当前仓库的独立新增价值主要体现在：

以 mustache/spec 为基准的系统兼容性证明，核心与可选规范 fixture 194 / 194 全部通过
在渲染核心之外补齐 CLI、文件渲染、bundle 校验、扫描分析和多文件生成工作流
提供 six consumer-style demos、Vue playground、静态展示站点和评审 artifact 索引
提供完整 CI、benchmark artifact、mooncakes 发布、治理文档和长期维护入口

因此，本项目更接近“MoonBit 模板基础设施的工程化补强”，而不是仅提供一个最小 Mustache 解释器。

#Current status

当前版本已经不是启动壳仓库，而是一个具备核心渲染能力、CLI 工具链、规范测试、基准、场景报告和多文件生成演示的可运行项目。

代码规模口径拆分如下：

手写有效 MoonBit 代码约 8032 行
导入上游 fixture 后生成的测试资产约 2149 有效行，单独披露、不计入手写规模
所有参赛证明面合计约 10181 有效 MoonBit 行

也就是说，这个仓库不是靠“纯导入文件”撑规模；仅手写实现与演示部分已经进入赛事建议体量区间。精确当前数字以 docs/METRICS_SNAPSHOT.md 为准。当前重点能力包括：

模板扫描、Token 化与 AST 解析
模板变量/Partial 引用扫描
compile-once / render-many 的 prepared template API
HTML 转义变量与非转义变量
Section / Inverted Section
Comment
Partial
dynamic partial names
parent templates and block inheritance
interpolation and section lambdas
Delimiter change
standalone line trimming for section-like tags
dotted lookup
array iteration
{{.}} 当前上下文访问
JSON 上下文转换
RenderOptions 严格模式与缺失变量诊断
带稳定错误码、源码范围、行列号和片段的结构化诊断
模板/JSON/bundle lint 与非零 CLI 退出状态
输出长度、Section 迭代次数、渲染步骤和 Partial 深度资源限制
dotted assignment 上下文构造与上下文合并
多文件 bundle 渲染接口
prepared bundle 预编译与复用接口
bundle 输出路径模板渲染与安全校验
manifest profile 解析与批量模板工程生成
prepared manifest profile 预编译入口
bundle path normalization、validation 和 generation plan
bundle render report / scenario report 导出
CLI 文件输入与输出流程
spec compatibility report
official mustache/spec fixture import and report generation
独立 downstream consumer 包示例
benchmark 入口与真实脚手架 demo
incident response 与 developer release 两类新增下游 demo
85 个自动化测试、194 个官方 fixture 和 2048 个跨实现差异用例
覆盖 fmt / info / check / build / test / coverage / differential / demos / CLI 的 CI 工作流
wasm / wasm-gc / js / native 四后端矩阵和专门的 Windows Playground 回归任务
Vue playground 直接调用 MoonBit 编译的 ESM，不依赖在线后端
artifact index 与 CI benchmark artifact 输出

#Project surfaces

为了让项目不只是“库代码可运行”，Moon Mustache 现在同时提供几类不同层次的入口：

library API 供 MoonBit 包直接依赖和嵌入
CLI 供模板渲染、文件输入输出、bundle 校验和扫描分析使用
reports 供评审和使用者快速查看 spec 兼容性、场景报告和 bundle 计划
downstream consumer 证明该库可以被另一个 MoonBit 包复用，而不是只能在本仓库自测
adoption demo 证明该库还可以支撑第二类真实场景，这里是面向运维 rollout kit 的多文件生成流程
content pipeline demo 证明该库还能支撑文档、公告和 HTML 片段生成这一类内容生产工作流
starter repo demo 证明该库可以作为 MoonBit starter repository 生成器的核心渲染能力
incident response demo 证明该库可以支撑 incident runbook、status-page draft 和 escalation pack 这类运维应急场景
developer release demo 证明该库可以支撑 GitHub release、安装指引和 migration note 这类开发者发布场景
companion repo blueprint 证明该库已经可以被整理成接近“独立外部仓库”形态的消费方项目结构
Vue playground 供用户在浏览器里实时修改模板、JSON 和 partials，直接看到 MoonBit 引擎输出
deployed browser playground 供评审直接在线运行 MoonBit 引擎、浏览项目定位和关键指标，不依赖本地后端

#Community health

为了让这个仓库更接近长期维护的开源项目，而不只是一次性比赛提交，当前仓库也补齐了基础协作入口：

CONTRIBUTING.md
CODE_OF_CONDUCT.md
GOVERNANCE.md
SECURITY.md
SUPPORT.md
PROGRESS.md
GitHub issue templates for bugs and feature requests
GitHub pull request template
Dependabot configuration for GitHub Actions and the Vue playground dependencies

如果你想快速理解项目当前成熟度和功能落点，可以直接看：

#Quick start

Start here:

fastest first run: moon run cli
command cookbook: moon run cli --examples
copy the built-in demo template: moon run cli --print-default-template
inspect the sample bundle manifest: moon run cli --print-sample-manifest
detailed onboarding: docs/QUICKSTART.md

Prerequisites:

MoonBit toolchain
- recommended competition baseline: 0.10.3
Node.js when running file-based CLI flows on js target

Verify the repository:

moon check
moon test

Run the most direct demos:

moon run showcase
moon run scenario_report
moon run official_spec_report

Run the Vue playground locally:

cd playground
npm install
npm run dev

Use the file-oriented CLI flow:

moon run --target js cli --template-file "examples/files/template.mustache" --json-file "examples/files/context.json" --partials-json-file "examples/files/partials.json"

If you are deciding between library embedding and CLI usage, read docs/QUICKSTART.md.

#Target support

core parsing and rendering library: wasm-gc and js
scenario, report, and benchmark entrypoints: validated in CI
file-backed CLI workflows: currently rely on the js target through the Node.js bridge
the Vue playground uses a local Node render bridge that calls the repository's own MoonBit engine

#Supported syntax

Syntax	Meaning	Status
{{name}}	escaped variable	supported
{{{name}}} / {{& name}}	unescaped variable	supported
{{#items}}...{{/items}}	section	supported
{{^empty}}...{{/empty}}	inverted section	supported
{{! note }}	comment	supported
{{> card}}	partial	supported
{{=<% %>=}}	delimiter change	supported
standalone section/comment/partial lines	whitespace trimming	supported
{{user.name}}	dotted lookup	supported
{{.}}	current context	supported

#Example

Template:

{{#users}}
- {{name}} <{{email}}>
{{/users}}
{{^users}}
No users found.
{{/users}}
{{> footer}}

Context:

{
  "users": [
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob", "email": "bob@example.com" }
  ]
}

Partials:

{
  "footer": "Generated by Moon Mustache."
}

Output:

- Alice <alice@example.com>
- Bob <bob@example.com>
Generated by Moon Mustache.

#Public API

当前接口分成两层，避免把“稳定核心库能力”和“比赛展示/工作流辅助能力”混在一起理解。

Core library API:

parse(template)
render(template, context)
render_with_partials(template, context, partials)
render_checked(template, context)
render_with_partials_checked(template, context, partials)
render_checked_with_options(template, context, options)
render_with_partials_checked_with_options(template, context, partials, options)
parse_json_context(json)
scan_template_variables(template)
scan_template_references(template)
scan_template_partials(template)
render_json(...) / render_json_checked(...)
render_json_checked_with_options(...)
parse_json_partials_checked(json)
render_json_bundle_checked(template, context_json, partials_json)
render_json_bundle_checked_with_options(...)
object_from_string_entries(entries) / merge_values(base, incoming)
render_template_bundle_checked(bundle, context, options)
render_template_bundle_json_checked(bundle, context_json, options)
parse_bundle_manifest_json(json)
resolve_bundle_manifest_profile(manifest, runtime_context, profile_name)
render_bundle_manifest_checked(...)
validate_template_bundle(bundle) / validate_bundle_manifest(manifest)
build_bundle_plan(bundle_name, render_result, validation_result)

Companion workflow/report helpers:

format_bundle_result_markdown(...) / format_bundle_result_json(...)
format_validation_report_markdown(...)
format_bundle_plan_markdown(...)
run_official_spec_report() / format_official_spec_report_markdown(...)
run_scenario_report() / format_scenario_report_markdown(...)

这种设计更适合作为其他 MoonBit 工具链和应用层库的基础依赖，而不会把上层项目绑死在一个过重的模板框架里。

#Compatibility direction

项目当前同时维护两层兼容性验证：

仓库内 hand-written spec-style suite，用于快速回归和行为补充
从官方 mustache/spec 直接导入的 fixture，用于上游语义对齐

当前 spec-style suite 覆盖：

interpolation
comments
sections
inverted sections
partials
delimiters
standalone lines
whitespace-sensitive cases
diagnostics cases

当前共有：

47 个仓库内 spec-style case，分布在 9 个 suite 中，全部通过
194 个核心及可选官方 fixture，全部通过且零跳过
最新 GitHub CI 为绿色，能直接复现 fmt / info / check / test 与 demo smoke paths
上游 fixture 的原始 JSON 与许可证已归档在 third_party/mustache-spec/

这让仓库的测试不只是“我们自己觉得对”，而是能直接对照上游 Mustache 规范资产。

#CLI demo

仓库内提供了一个轻量 CLI，用于快速演示模板渲染能力。

Run the built-in demo:

moon run cli

Render an inline template:

moon run cli --template "Hello {{name}}" --var name=MoonBit

Render with partials:

moon run cli --template "{{> card}}" --partial "card={{name}} builds tooling." --var name=MoonBit

Render with dotted variables and typed values:

moon run cli --template "{{user.name}}/{{enabled}}/{{count}}" --var user.name=Alice --var enabled=true --var count=3

Render with strict diagnostics:

moon run cli --template "A{{> missing}}B" --strict

Print a short cookbook of common commands:

moon run cli --examples

Scan referenced data names and partials:

moon run cli --template "{{#user}}{{name}}{{/user}}{{> footer}}" --scan

Front-end playground:

playground/ provides a Vue + Vite demo surface for judges and users
it renders through a dedicated playground_bridge MoonBit entrypoint instead of a third-party Mustache implementation

Track missing variables as diagnostics:

moon run cli --template "Hello {{name}}" --strict --strict-missing

Render a bundle manifest into an output directory:

moon run --target js cli --bundle-manifest-file "examples/bundle/manifest.json" --json-file "examples/bundle/context.json" --bundle-output-dir "out_bundle_demo"

Render a profile-specific bundle and emit a JSON report:

moon run --target js cli --bundle-manifest-file "examples/bundle/manifest.json" --bundle-profile prod --json-file "examples/bundle/context.json" --bundle-output-dir "out_bundle_demo" --bundle-report-file "out_bundle_demo/report.json" --bundle-report-format json

Validate and plan a bundle without writing generated files:

moon run --target js cli --bundle-manifest-file "examples/bundle/manifest.json" --bundle-profile dev --json-file "examples/bundle/context.json" --bundle-check-only --bundle-validation-file "out_bundle_check/validation.md" --bundle-plan-file "out_bundle_check/plan.md"

Render with JSON context:

moon run cli --json "{\"name\":\"MoonBit\",\"role\":\"renderer\"}" --template "Hello {{name}}, core={{role}}"

PowerShell-friendly JSON input:

$json='{"name":"MoonBit","role":"renderer"}'
$encoded=[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($json))
moon run cli --json-base64 $encoded --template "Hello {{name}}, core={{role}}"

Render from files:

moon run --target js cli --template-file "examples/files/template.mustache" --json-file "examples/files/context.json" --partials-json-file "examples/files/partials.json"

Write output to a file:

moon run --target js cli --template-file "examples/files/template.mustache" --json-file "examples/files/context.json" --partials-json-file "examples/files/partials.json" --output "rendered.txt"

说明：

默认 moon run cli 适合直接传字符串参数的演示场景
文件读写能力当前通过 Node.js 文件桥接提供，因此请使用 moon run --target js cli ...

#Demo entrypoints

Quick project demos shipped in the repo:

moon run showcase 展示配置生成、邮件模板、HTML 片段和项目摘要四类场景。
moon run scaffold_demo 展示多文件脚手架生成，输出 .env、compose.yaml、README.generated.md。
moon run spec_report 输出 Markdown 兼容性报告。
moon run official_spec_report 输出基于官方 mustache/spec 导入 fixture 的兼容性报告。
moon run scenario_report 输出“真实工作流是否跑通”的场景报告，适合展示项目落地性。
moon run benchmarks 输出核心渲染路径的 benchmark 摘要。
moon run --target js cli --bundle-check-only ... 可直接作为 bundle manifest 的校验和生成计划入口，适合接 CI。
moon run downstream_consumer 运行独立 downstream consumer 包，证明公开 API 可以被其他 MoonBit 包直接复用。

#Repository layout

src/: core scanner, parser, context, renderer, bundle APIs, spec suites, and tests
cli/: demo command-line renderer
showcase/: quick scenario-oriented demos
scaffold_demo/: multi-file project generation demo
spec_report/: compatibility report entrypoint
official_spec_report/: upstream fixture compatibility report entrypoint
scenario_report/: workflow-style scenario report entrypoint
downstream_consumer/: separate package proving public API reuse
benchmarks/: performance smoke benchmarks
playground/: Vue playground for interactive template rendering demos
playground_bridge/: MoonBit JSON bridge used by the playground API
examples/: sample templates and expected output
third_party/mustache-spec/: imported upstream official spec fixtures
THIRD_PARTY_NOTICES.md: source and license notes for imported third-party assets
docs/: architecture notes, roadmap, and competition materials
docs/EVALUATION_SUMMARY.md: concise evaluator-facing project strengths
docs/QUICKSTART.md: user-oriented onboarding guide
docs/STABILITY.md: API stability tiers and versioning direction
docs/BENCHMARKS.md: benchmark interpretation and next steps
docs/FINAL_ACCEPTANCE_REPORT.md: final acceptance readiness summary
.github/workflows/: CI configuration