🥮 mooncakes.io

moonguard

MoonBit public API compatibility and SemVer guard

api
semver
compatibility
moonbit
ci
moon add 918154429/moonguard@0.2.0
Download zip
Author
Version
0.2.0
License
Apache-2.0
Repository
Last updated
last month
Downloads
10
README

#918154429/moonguard

MoonGuard is a MoonBit public API compatibility and SemVer guard.

///|
let report = @moonguard.diff_interfaces(
  "pub fn render(String) -> String", "pub fn render(String, Options) -> String",
)

See README.md for full project documentation.

#
AcceptedApiChange

source
pub struct AcceptedApiChange {
  change : ApiChange
  rule : ApiPolicyRule
} derive(Eq, 
Debug)

A change accepted by one policy rule.

#
ApiChange

source
pub struct ApiChange {
  kind : ChangeKind
  impact : Impact
  item_kind : String
  name : String
  old_signature : String?
  new_signature : String?
} derive(Eq, 
Debug)

#
ApiDiagnostic

source
pub struct ApiDiagnostic {
  severity : String
  code : String
  path : String
  message : String
} derive(Eq, 
Debug)

#
ApiFile

source
pub struct ApiFile {
  path : String
  text : String
} derive(Eq, 
Debug)

#
ApiIgnoreRule

source
pub struct ApiIgnoreRule {
  item_kind : String
  name : String
  reason : String
} derive(Eq, 
Debug)

#
ApiItem

source
pub struct ApiItem {
  kind : String
  name : String
  signature : String
} derive(Eq, 
Debug)

#
ApiKindCount

source
pub struct ApiKindCount {
  kind : String
  count : Int
} derive(Eq, 
Debug)

#
ApiPackageComparison

source
pub struct ApiPackageComparison {
  old_snapshot : ApiSnapshot
  new_snapshot : ApiSnapshot
  report : ApiReport
  diagnostics : Array[ApiDiagnostic]
  summary : ApiSummary
  diagnostic_summary : DiagnosticSummary
} derive(Eq, 
Debug)

#
ApiPolicyDiagnostic

source
pub struct ApiPolicyDiagnostic {
  severity : String
  code : String
  line : Int
  message : String
} derive(Eq, 
Debug)

A diagnostic emitted while evaluating compatibility policy.

#
ApiPolicyEvaluation

source
pub struct ApiPolicyEvaluation {
  original_report : ApiReport
  effective_report : ApiReport
  accepted_changes : Array[AcceptedApiChange]
  diagnostics : Array[ApiPolicyDiagnostic]
  summary : PolicySummary
} derive(Eq, 
Debug)

Original and effective reports together with their audit trail.

#
ApiPolicyRule

source
pub struct ApiPolicyRule {
  change_kind : String
  item_kind : String
  name : String
  until : String
  max_matches : Int
  reason : String
  line : Int
} derive(Eq, 
Debug)

One auditable compatibility exception.

#
ApiReport

source
pub struct ApiReport {
  changes : Array[ApiChange]
  recommendation : Impact
} derive(Eq, 
Debug)

#
ApiSnapshot

source
pub struct ApiSnapshot {
  items : Array[ApiItem]
  diagnostics : Array[ApiDiagnostic]
} derive(Eq, 
Debug)

#
ApiSummary

source
pub struct ApiSummary {
  total : Int
  major : Int
  minor : Int
  patch : Int
  added : Int
  removed : Int
  changed : Int
} derive(Eq, 
Debug)

#
ChangeKind

source
pub(all) enum ChangeKind {
  Added
  Removed
  Changed
} derive(Eq, 
Debug)

#
DiagnosticSummary

source
pub struct DiagnosticSummary {
  total : Int
  errors : Int
  warnings : Int
  infos : Int
} derive(Eq, 
Debug)

#
IgnoreParseResult

source
pub struct IgnoreParseResult {
  rules : Array[ApiIgnoreRule]
  errors : Array[String]
} derive(Eq, 
Debug)

#
Impact

source
pub(all) enum Impact {
  Patch
  Minor
  Major
} derive(Eq, 
Debug)

#
PolicyParseResult

source
pub struct PolicyParseResult {
  rules : Array[ApiPolicyRule]
  errors : Array[String]
} derive(Eq, 
Debug)

Result of parsing a policy file.

#
PolicyReleasePlan

source
pub struct PolicyReleasePlan {
  evaluation : ApiPolicyEvaluation
  plan : ReleasePlan
} derive(Eq, 
Debug)

A release plan evaluated against the effective compatibility report.

#
PolicySummary

source
pub struct PolicySummary {
  rule_count : Int
  matched_rule_count : Int
  accepted_change_count : Int
  errors : Int
  warnings : Int
} derive(Eq, 
Debug)

Aggregate policy evaluation counters.

#
ReleasePlan

source
pub struct ReleasePlan {
  report : ApiReport
  diagnostics : Array[ApiDiagnostic]
  version_check : VersionCheck
  summary : ApiSummary
  diagnostic_summary : DiagnosticSummary
  status : String
  decision : String
  next_action : String
} derive(Eq, 
Debug)

#
Version

source
pub struct Version {
  major : Int
  minor : Int
  patch : Int
} derive(Eq, 
Debug)

#
VersionCheck

source
pub struct VersionCheck {
  ok : Bool
  required : Impact
  current : String
  next : String
  reason : String
} derive(Eq, 
Debug)

#
api_file

source
fn api_file(path : String, text : String) -> ApiFile

Create an interface file record for package-level snapshot APIs.

#
build_api_snapshot

source
fn build_api_snapshot(files : Array[ApiFile]) -> ApiSnapshot

Build a package-level API snapshot from named interface files.

#
check_interface_version_bump

source
fn check_interface_version_bump(old_text : String, new_text : String, current : String, next : String) -> VersionCheck

Diff two interface texts and check the proposed SemVer bump.

#
check_version_bump

source
fn check_version_bump(report : ApiReport, current : String, next : String) -> VersionCheck

Check whether next satisfies the SemVer bump required by a report.

#
compare_api_file_sets

source
fn compare_api_file_sets(old_files : Array[ApiFile], new_files : Array[ApiFile]) -> ApiPackageComparison

Build snapshots from file sets and compare them as one package.

#
compare_api_snapshots

source
fn compare_api_snapshots(old_snapshot : ApiSnapshot, new_snapshot : ApiSnapshot) -> ApiPackageComparison

Compare two package-level snapshots and keep diagnostics beside the report.

#
compare_versions

source
fn compare_versions(left : Version, right : Version) -> Int

Compare two parsed versions.

Returns -1 when left < right, 0 when equal, and 1 when left > right.

#
count_items_by_kind

source
fn count_items_by_kind(items : Array[ApiItem]) -> Array[ApiKindCount]

Count API items by kind for package-level diagnostics and reporting.

#
diagnostics_have_errors

source
fn diagnostics_have_errors(diagnostics : Array[ApiDiagnostic]) -> Bool

Return true when diagnostics include at least one error.

#
diff_api_snapshots

source
fn diff_api_snapshots(old_snapshot : ApiSnapshot, new_snapshot : ApiSnapshot) -> ApiReport

Diff two package-level snapshots.

#
diff_interfaces

source
fn diff_interfaces(old_text : String, new_text : String) -> ApiReport

Compare two MoonBit public API snapshots.

#
diff_items

source
fn diff_items(old_items : Array[ApiItem], new_items : Array[ApiItem]) -> ApiReport

Compare two normalized API lists.

#
evaluate_policy

source
fn evaluate_policy(report : ApiReport, rules : Array[ApiPolicyRule], target_version : String) -> ApiPolicyEvaluation

Evaluate parsed rules against a compatibility report.

A rule with an expired deadline or exceeded budget accepts no changes. When several valid rules match a change, the first rule owns its audit record.

#
evaluate_policy_text

source
fn evaluate_policy_text(report : ApiReport, rules_text : String, target_version : String) -> ApiPolicyEvaluation

Parse and evaluate policy text. Parse failures are preserved as policy diagnostics and never accept changes.

#
filter_report

source
fn filter_report(report : ApiReport, rules_text : String) -> ApiReport

Filter a report using textual ignore rules.

#
filter_report_with_rules

source
fn filter_report_with_rules(report : ApiReport, rules : Array[ApiIgnoreRule]) -> ApiReport

Filter a report using pre-parsed ignore rules.

#
make_policy_release_plan

source
fn make_policy_release_plan(evaluation : ApiPolicyEvaluation, diagnostics : Array[ApiDiagnostic], current : String, next : String) -> PolicyReleasePlan

Build a release plan using the effective report. Policy errors block the plan independently of interface snapshot diagnostics.

#
make_release_plan

source
fn make_release_plan(report : ApiReport, diagnostics : Array[ApiDiagnostic], current : String, next : String) -> ReleasePlan

Build a release-oriented decision from API, diagnostics, and SemVer data.

#
merge_diagnostics

source
fn merge_diagnostics(left : Array[ApiDiagnostic], right : Array[ApiDiagnostic]) -> Array[ApiDiagnostic]

Merge diagnostics from two snapshots.

#
parse_ignore_rules

source
fn parse_ignore_rules(text : String) -> IgnoreParseResult

Parse ignore rules used to filter accepted or experimental API changes.

Supported rule syntax:

ignore KIND NAME [reason...]

KIND and NAME may be *; NAME may also use a single * prefix, suffix, or infix wildcard.

#
parse_interface

source
fn parse_interface(text : String) -> Array[ApiItem]

Parse a MoonBit interface file into a normalized public API list.

#
parse_interface_with_namespace

source
fn parse_interface_with_namespace(text : String, scope : String) -> Array[ApiItem]

Parse a MoonBit interface file and namespace every public API name.

#
parse_policy_rules

source
fn parse_policy_rules(text : String) -> PolicyParseResult

Parse auditable compatibility rules.

Syntax: allow CHANGE_KIND ITEM_KIND NAME [until VERSION][max_matches N] reason TEXT....

#
parse_version

source
fn parse_version(text : String) -> Version?

Parse a strict major.minor.patch SemVer core version.

#
policy_diagnostics_have_errors

source
fn policy_diagnostics_have_errors(diagnostics : Array[ApiPolicyDiagnostic]) -> Bool

Return true when policy diagnostics contain at least one error.

#
render_json_check_result

source
fn render_json_check_result(report : ApiReport, check : VersionCheck) -> String

Render a combined JSON object for API diff and version-check output.

#
render_json_package_check_result

source
fn render_json_package_check_result(report : ApiReport, diagnostics : Array[ApiDiagnostic], check : VersionCheck) -> String

Render a package-level JSON report with diagnostics and a SemVer check.

#
render_json_package_report

source
fn render_json_package_report(report : ApiReport, diagnostics : Array[ApiDiagnostic]) -> String

Render a package-level JSON report with diagnostics.

#
render_json_policy_evaluation

source
fn render_json_policy_evaluation(evaluation : ApiPolicyEvaluation) -> String

Render an audited compatibility evaluation as JSON.

#
render_json_policy_release_plan

source
fn render_json_policy_release_plan(plan : PolicyReleasePlan) -> String

Render a policy-aware release plan as JSON.

#
render_json_release_plan

source
fn render_json_release_plan(plan : ReleasePlan) -> String

Render a release-oriented JSON report for CI and dashboards.

#
render_json_report

source
fn render_json_report(report : ApiReport) -> String

Render a machine-readable JSON compatibility report.

#
render_json_snapshot_inventory

source
fn render_json_snapshot_inventory(snapshot : ApiSnapshot) -> String

Render a JSON inventory for one package API snapshot.

#
render_markdown_package_check_result

source
fn render_markdown_package_check_result(report : ApiReport, diagnostics : Array[ApiDiagnostic], check : VersionCheck) -> String

Render a package-level Markdown report with a SemVer check section.

#
render_markdown_package_report

source
fn render_markdown_package_report(report : ApiReport, diagnostics : Array[ApiDiagnostic]) -> String

Render a package-level Markdown report with summary and diagnostics.

#
render_markdown_policy_evaluation

source
fn render_markdown_policy_evaluation(evaluation : ApiPolicyEvaluation) -> String

Render an audited compatibility evaluation as Markdown.

#
render_markdown_policy_release_plan

source
fn render_markdown_policy_release_plan(plan : PolicyReleasePlan) -> String

Render a policy-aware release plan as Markdown.

#
render_markdown_release_plan

source
fn render_markdown_release_plan(plan : ReleasePlan) -> String

Render a release-oriented Markdown report for maintainers and PR comments.

#
render_markdown_report

source
fn render_markdown_report(report : ApiReport) -> String

Render a Markdown compatibility report for PR comments or release notes.

#
render_markdown_snapshot_inventory

source
fn render_markdown_snapshot_inventory(snapshot : ApiSnapshot) -> String

Render a Markdown inventory for one package API snapshot.

#
render_version_check_markdown

source
fn render_version_check_markdown(check : VersionCheck) -> String

Render a Markdown summary for a SemVer check result.

#
semver_recommendation

source
fn semver_recommendation(old_text : String, new_text : String) -> String

#
summarize_diagnostics

source
fn summarize_diagnostics(diagnostics : Array[ApiDiagnostic]) -> DiagnosticSummary

Count diagnostics by severity.

#
summarize_report

source
fn summarize_report(report : ApiReport) -> ApiSummary

Count change kinds and impact levels in a report.

#
version_to_string

source
fn version_to_string(version : Version) -> String

Convert a parsed version back to its canonical major.minor.patch form.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io