Semantic compatibility analysis for MoonBit public interfaces

moonbit

api

compatibility

semver

mbti

moon add hmc11234/mooncompat@0.1.0

Download zip

Author

hmc11234

Version

0.1.0

License

Apache-2.0

Repository

github.com/hmc11234/123214

Last updated

4 hours ago

Downloads

README

#MoonCompat

MoonCompat is a MoonBit-native compatibility checker for public .mbti interfaces. It turns two interface versions into a semantic diff, explains why each change is compatible or breaking, and recommends the next Semantic Versioning release.

#Why MoonCompat?

Text diffs cannot distinguish a formatting change from a changed parameter type, and successful compilation of the new version says nothing about source compatibility for downstream packages. MoonCompat parses the public interface into functions, methods, types, fields, variants, and trait methods before applying MoonBit-specific compatibility rules.

The analyzer currently covers:

functions and methods, including labels, optional arguments, async and errors;
generic arity and trait constraints;
aliases, constants, public values and error payloads;
public struct fields, visibility and mutability;
enum variants and exhaustive-match risk;
trait methods and downstream implementation risk;
deprecation, documentation and interface-import changes;
terminal, JSON, Markdown and SARIF 2.1.0 output;
CI policies, ignored rules/symbols and SemVer recommendations.

#Quick start

Requirements: a current MoonBit toolchain and Node.js.

git clone https://github.com/hmc11234/123214.git
cd 123214
moon test --target js
moon run --target js cmd/mooncompat -- compare examples/v1.mbti examples/v2.mbti

The example intentionally contains breaking changes, so the CLI prints a report and exits with status 1. Use --fail-on none when exploring:

moon run --target js cmd/mooncompat -- compare \
  examples/v1.mbti examples/v2.mbti \
  --fail-on none --current-version 0.1.0

#CLI

mooncompat compare <OLD.mbti> <NEW.mbti> [OPTIONS]
mooncompat explain <RULE>
mooncompat rules

Important options:

Option	Purpose
--format terminal	Human-readable console report (default)
--format json	Stable machine-readable schema
--format markdown	Pull-request friendly report
--format sarif	SARIF 2.1.0 for code-scanning systems
--output FILE	Write output instead of printing it
--current-version X.Y.Z	Recommend the next release version
--fail-on breaking	Fail only on breaking changes (default)
--fail-on feature	Fail on breaking changes and additions
--fail-on none	Always return success after analysis
--ignore-rule ID	Suppress a stable rule identifier
--ignore-symbol PATTERN	Suppress a symbol; trailing * is supported
--no-info	Hide documentation and import-only changes

Generate a Markdown report:

moon run --target js cmd/mooncompat -- compare \
  examples/v1.mbti examples/v2.mbti \
  --format markdown --output api-report.md --fail-on none

Explain a result:

moon run --target js cmd/mooncompat -- explain MC401

#Obtaining .mbti files

MoonBit's build tool can emit package interfaces with moon info. Keep the released interface as a baseline, regenerate the current interface, then pass both files to MoonCompat. A CI job can store the baseline in the repository or download it from the last release artifact.

moon info
moon run --target js cmd/mooncompat -- compare baseline.mbti current.mbti

#Library API

The hmc11234/mooncompat/src package is portable and does not depend on Node.js. The command-line package contains the only host-specific filesystem bindings.

let report = @compat.compare_text(old_mbti, new_mbti)
println(@compat.render_terminal(report))
println(@compat.render_json(report))

Useful entry points:

parse_interface — recoverable .mbti parser;
compare_interfaces / compare_text — semantic comparison;
apply_policy / policy_failed — CI policy evaluation;
render_terminal, render_json, render_markdown, render_sarif;
parse_semver, next_version, recommend_version;
built_in_rules, find_rule, render_rule.

#Compatibility philosophy

MoonCompat is intentionally conservative. Adding a variant to a public enum is classified as breaking because downstream exhaustive matches may stop compiling. Adding a required field to a pub(all) struct is breaking because downstream struct literals must initialize it. Adding a required trait method is breaking for existing implementations.

The analyzer judges source-level interface compatibility. It cannot prove that unchanged signatures preserve runtime behavior, performance, security, or data format semantics. Those changes still require tests and human review.

#Project structure

src/
  lexer.mbt          .mbti tokenization with source spans
  parser.mbt         recoverable public-interface parser
  model.mbt          semantic API model
  diff.mbt           compatibility classification engine
  change_model.mbt   report and severity model
  policy.mbt         filtering and CI decisions
  report.mbt         terminal/JSON/Markdown/SARIF renderers
  semver.mbt         strict SemVer parsing and recommendations
  rules.mbt          documented stable rule catalog
cmd/mooncompat/
  main.mbt           Node.js command-line frontend
examples/
  v1.mbti, v2.mbti   executable comparison demonstration

#Development

moon fmt --check
moon check --target js
moon test --target js
moon build --target js

The test suite covers tokenization, parsing recovery, individual compatibility rules, report formats, policy filtering and version recommendations.

#Roadmap

compare Git tags by generating interfaces in temporary worktrees;
correlate API changes with MoonBit coverage data;
support package-set manifests for multi-package release reports;
publish the reusable parser and rule engine to mooncakes.io;
add editor diagnostics using the SARIF/source-span model.

#License

Apache-2.0. See LICENSE.

Site source Report issue Packages Build queue Skills Statistics