moonbit-spec-test-development

name	moonbit-spec-test-development
description	Create formal spec-driven MoonBit APIs and test suites. Use when asked to set up a spec.mbt, spec-driven tests, or a formal contract-first workflow (e.g., "set up a formal spec & test suite for Yaml in MoonBit"), including moon.mod.json/moon.pkg.json scaffolding and guidance to implement in separate files.

MoonBit Spec & Test Development

Overview

Define a formal API contract in <pkg>_spec.mbt, write type-checked tests against it, and scaffold a minimal MoonBit module so moon check passes before implementation work begins.

Workflow

Confirm API surface (if needed)

• Infer the package name from context; only ask if ambiguous.
• Confirm the API surface: core types, entry points, error types, and any versioning needs.

Scaffold the module using moon new (preferred for new projects)

• If you didn't use moon new, fall back to the moon.mod.json and moon.pkg.json templates.

Write the formal spec (<pkg>_spec.mbt)

• Use #declaration_only for all types/functions that will be implemented later.
• Functions with #declaration_only must still have a body: { ... }.
• Keep the spec as the contract: treat it as read-only after creation; implementation goes in new files under the same package.
• Use pub(all) for types you need to construct in tests; keep pub for opaque types.

Write spec-driven tests

• Create <pkg>_easy_test.mbt, <pkg>_mid_test.mbt, and <pkg>_difficult_test.mbt (or similar) in the same package.
• Prefer black-box tests using public APIs; use @json.inspect(...) for complex values.
• Try to make the tests rich enough to validate the spec surface.

Validate

• Run moon check to confirm the spec + tests type-check.
• Run moon test only after some implementations exist

Templates

• See references/templates.md for scaffolding and file templates.