🥮 mooncakes.io

    tradedocs

    MoonBit library for international trade document normalization, validation, and cross-document consistency checks

    international-trade
    trade-documents
    commercial-invoice
    cross-validation
    normalization
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    2 months ago
    Downloads
    28

    No dependencies

    #moonbit-tradedocs

    moonbit-tradedocs is a MoonBit library for turning international-trade documents into consistent, reviewable data. It combines domain types, field-level normalization, document validation, cross-document checks, structured diagnostics, and anonymized fixtures in a small, dependency-light module.

    #Why it is useful

    Trade-document workflows usually fail at the boundaries between systems: dates and units arrive in different spellings, commercial values drift between an invoice and a purchase order, and identifiers need to be checked before a document reaches a human reviewer. This project makes those boundaries explicit and produces diagnostics that can be rendered as text, Markdown, or JSON.

    The library is suitable for validation services, import pipelines, test fixtures, and MoonBit applications that need deterministic document checks.

    #Capabilities

    • Core models for commercial invoices, packing lists, purchase orders, bills of lading, origin declarations, customs declarations, and letters of credit.
    • Canonicalization of dates, country and currency codes, units, party text, descriptions, identifiers, and nested document collections.
    • Internal validation for required fields, amounts, weights, HS codes, container numbers, customs declarations, and SWIFT/BIC fields.
    • Cross-document checks for amounts, quantities, parties, weights, and HS codes, plus a deterministic trust score and risk tier.
    • Diagnostic reports with evidence, remediation suggestions, text/Markdown renderers, and escaped JSON output.
    • Deterministic anonymization for public or repeatable test fixtures.
    • Adapters for JSON, CSV, text key/value pairs, UN/EDIFACT, UBL XML, and ANSI X12 metadata.

    #Architecture

    adapters -> types -> normalizer -> pipeline
                         |          |
                         v          +--> single validators
                    canonical data  +--> cross-document checks
                                    +--> diagnostics / trust score
                                    +--> anonymized fixture summary

    The public orchestration entry point is lib/pipeline. Lower-level packages remain independently usable when an application needs only normalization, validation, or a format adapter.

    #Installation

    The module is published as zxwrrg/tradedocs in moon.mod and is designed to be consumed through MoonBit's normal module dependency workflow. For local development, clone the repository and use the Moon CLI from the project root.

    moon update
moon check --target all
moon test --target all

    #Library example

    let input = @pipeline.PipelineInput::new(
      documents=my_document_set,
      customs_declaration=Some(my_customs_declaration),
    )
    let result = @pipeline.run(input)

    println(result.report.to_json())
    if result.has_errors() {
      println(result.report.to_markdown())
    }

    For a lower-level flow, call @normalizer.normalize_document_set first and then use the validators in lib/validator/single or lib/validator/cross_check directly.

    #CLI demo

    The repository includes a runnable sample application:

    moon run cmd/main

    It constructs representative trade documents, runs validation, renders a diagnostic report, and shows JSON/anonymization output.

    #Quality checks

    Run the same checks locally that CI runs:

    moon version --all
moon fmt --check
moon info
moon check --target all --deny-warn
moon test --target all --deny-warn
moon bench lib/pipeline --target native --release

    The benchmark method and the latest local observation are documented in docs/benchmark.md.

    #Repository layout

    lib/types                  domain records, codes, units, and calculations
lib/normalizer             canonicalization and text/date/number cleanup
lib/validator/single        document-local validation rules
lib/validator/cross_check   consistency checks across a document set
lib/diagnostics             structured diagnostics and report renderers
lib/anonymizer              deterministic fixture anonymization
lib/adapters               JSON, CSV, EDIFACT, XML, and text adapters
lib/pipeline                end-to-end validation orchestration
cmd/main                    runnable demonstration program
docs                        benchmark documentation

    #Scope and limitations

    The adapters are deliberately lightweight and focus on predictable extraction and normalization rather than being full schema validators for every external standard. Exchange-rate conversion, cryptographic signatures, external sanctions data, and carrier-specific EDI profiles remain application concerns. Callers should validate required business context before relying on a trust score for an operational decision.

    #Contributing

    Keep MoonBit blocks separated with ///|, add regression tests for boundary behavior, and run moon info && moon fmt before opening a change. New public APIs should include a focused example or test and should preserve deterministic output where practical.

    #License

    Licensed under the Apache License 2.0.

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io