🥮 mooncakes.io

    docproof-harbor

    MoonBit-native README example verifier and open-source provenance proof toolkit

    docs
    examples
    provenance
    license
    mooncakes
    Download zip
    Author
    Version
    0.1.2
    License
    MIT
    Repository
    Last updated
    2 months ago
    Downloads
    33

    No dependencies

    #HarborCheck

    HarborCheck 是一个 MoonBit 原生的 README 示例验证与开源来源证明工具包。它把文档里的 MoonBit 代码块、可运行示例、第三方来源记录、许可证说明和项目快照整理成可测试的数据模型，帮助维护者证明“文档能复现、来源可追踪、许可证说得清楚”。

    #解决什么问题

    很多 MoonBit 项目的风险不是只有构建失败，还包括 README 示例无法复现、文档中的命令和源码状态不一致、测试数据或素材来源没有说明、许可证边界不清楚。HarborCheck 的重点是把这些证据变成 MoonBit 可检查的报告，而不是替代发布平台或自动发布工具。

    #项目边界

    HarborCheck 现在主打三个能力：

    • 文档示例证明：提取 README / docs 中的 fenced code block，识别 MoonBit 示例是否具备可运行形态；
    • 来源证明：记录自有代码、第三方代码、数据集、素材和生成文本的来源、许可证和说明，输出合规风险；
    • 身份一致性证明：检查申报书、GitHub 仓库、moon.mod、Mooncakes 包名和 git 提交身份是否使用同一套申请人信息。

    项目仍保留 audit 快照检查，作为附属的提交材料清单能力，用来确认 README、CI、测试、示例、许可证和 Mooncakes 元数据是否完整。

    #安装方式

    moon add WB-ai-nb/docproof-harbor

    Mooncakes 包名：WB-ai-nb/docproof-harbor

    #最小使用示例

    test {
      let markdown =
        #|# Usage
        #|
        #|```moonbit
        #|fn main {
        #|  println("verified")
        #|}
        #|```
        #|
      let report = @harborcheck.doc_proof(
        markdown,
        [
          @harborcheck.SourceEvidence(
            name="HarborCheck source",
            kind=@harborcheck.OwnedCode,
            license="MIT",
            note="Original MoonBit implementation by the project applicant",
          ),
        ],
      )
      inspect(report.verdict, content="ready")
    }

    完整示例位于 examples/basic：

    moon run examples/basic

    CLI smoke 入口位于 cmd/main：

    moon run cmd/main

    #本地运行方式

    moon check
moon build
moon test
moon run examples/basic
moon run cmd/main
moon publish --dry-run

    #API 与核心功能

    • extract_doc_snippets(markdown)：提取 Markdown 代码块并标注语言、序号和可运行信号；
    • SourceEvidence(...)：记录自有代码、第三方代码、数据、素材或生成文本的来源证明；
    • doc_proof(markdown, sources)：生成文档示例与来源证明报告；
    • doc_proof_markdown(markdown, sources) / DocProofReport::to_markdown()：导出 Markdown 证明报告；
    • SubmissionIdentity(...)：定义申报材料、GitHub 和 Mooncakes 应统一使用的身份；
    • acceptance_identity_report(identity, snapshot, submission_text)：生成身份一致性报告；
    • acceptance_identity_markdown(identity, snapshot, submission_text)：导出身份一致性 Markdown 证明；
    • ProjectSnapshot(...)：描述一个项目的提交材料快照；
    • parse_manifest(text)：从 moon.mod 文本中提取包名、版本、仓库、许可证和描述；
    • snapshot_from_bundle(text)：解析 --- file: path 分隔的仓库快照文本；
    • audit(snapshot)：对 README、CI、测试、示例、许可证和 Mooncakes 元数据做附属清单检查；
    • audit_markdown(snapshot) / audit_json(snapshot)：导出提交材料检查报告；
    • release_checklist(snapshot)：导出阻塞项和修复步骤。

    #支持范围

    • README / docs 中 Markdown 代码块提取；
    • MoonBit 示例可运行形态识别；
    • 自有代码、第三方代码、数据集、素材、生成文本的来源证明建模；
    • 申报身份、仓库 owner、模块 namespace、Mooncakes owner、包名和 git 提交身份一致性检查；
    • 许可证信号检查，支持常见 OSI 许可证和开放素材许可证；
    • MoonBit 包配置字段检查：name、version、readme、repository、license、description；
    • CI、测试、示例、维护记录和 Mooncakes 发布元数据清单检查；
    • Markdown 和 JSON 风格的报告导出。

    #暂不支持范围

    • 不直接联网访问 GitHub、Mooncakes 或本地文件系统；
    • 不替代 moon check、moon build、moon test 的真实执行结果；
    • 不自动执行 README 里的任意命令；
    • 不执行 moon login 或 moon publish；
    • 不做通用 Markdown 语法解析，只处理开源证明所需的 fenced code block 和证据字段。

    #测试与验收命令

    当前项目包含黑盒测试、白盒测试、README 示例证明测试、来源证明风险测试、示例 smoke 和 CLI smoke。验收前建议执行：

    moon check --deny-warn
moon build
moon test --deny-warn
moon fmt --check
moon run examples/basic
moon run cmd/main
moon publish --dry-run

    #开源许可证和第三方说明

    HarborCheck 使用 MIT License。项目为原创 MoonBit 实现，不移植第三方源码，不包含外部图片、音频、字体或私有素材。运行时仅依赖 MoonBit 标准核心库。

    #Mooncakes 发布

    发布命令：

    moon login
moon publish --dry-run
moon publish

    发布后检查：

    https://mooncakes.io/docs/WB-ai-nb/docproof-harbor
https://mooncakes.io/api/v0/manifest/WB-ai-nb/docproof-harbor

    #维护资料

    • CHANGELOG.md：版本发布记录；
    • SUBMISSION.md：项目申报书；
    • docs/API.md：API 说明；
    • docs/design.md：设计说明；
    • docs/research.md：选题调研与差异化；
    • docs/issues.md：Issue 记录；
    • docs/test-record.md：测试记录；
    • docs/release-checklist.md：发布检查清单。
    • FINAL_ACCEPTANCE.md：最终验收链接、Dashboard 账号说明和验收证据。

    AuditMetrics

    source
    pub(all) struct AuditMetrics {
      pass_count : Int
      warn_count : Int
      fail_count : Int
      command_count : Int
      test_fixture_count : Int
      example_count : Int
    } derive(Eq, 
    Debug    )

    AuditReport

    source
    pub(all) struct AuditReport {
      project_name : String
      score : Int
      max_score : Int
      verdict : String
      package_name : String
      repository : String
      findings : Array[Finding]
      metrics : AuditMetrics
    } derive(Eq, 
    Debug    )

    AuditReport::has_blockers

    source
    fn AuditReport::has_blockers(self : AuditReport) -> Bool

    AuditReport::repair_steps

    source
    fn AuditReport::repair_steps(self : AuditReport) -> Array[RepairStep]

    AuditReport::to_json

    source
    fn AuditReport::to_json(self : AuditReport) -> String

    AuditReport::to_markdown

    source
    fn AuditReport::to_markdown(self : AuditReport) -> String

    AuditReport::to_release_checklist

    source
    fn AuditReport::to_release_checklist(self : AuditReport) -> String

    CheckKind

    source
    pub(all) enum CheckKind {
      PackageConfig
      Readme
      ContinuousIntegration
      Tests
      Examples
      Build
      Mooncakes
      GitTrace
      License
      Boundary
      DocProof
    } derive(Eq, 
    Debug    )

    DocProofReport

    source
    pub(all) struct DocProofReport {
      snippet_count : Int
      runnable_snippet_count : Int
      source_count : Int
      unclear_source_count : Int
      license_issue_count : Int
      verdict : String
      snippets : Array[DocSnippet]
      sources : Array[SourceEvidence]
    } derive(Eq, 
    Debug    )

    DocProofReport::to_markdown

    source
    fn DocProofReport::to_markdown(self : DocProofReport) -> String

    DocSnippet

    source
    pub(all) struct DocSnippet {
      index : Int
      language : String
      body : String
      runnable : Bool
      label : String
    } derive(Eq, 
    Debug    )

    Finding

    source
    pub(all) struct Finding {
      id : String
      kind : CheckKind
      severity : Severity
      title : String
      detail : String
      repair : String
      evidence : String
      penalty : Int
    } derive(Eq, 
    Debug    )

    IdentityEvidence

    source
    pub(all) struct IdentityEvidence {
      key : String
      value : String
      source : String
      note : String
    } derive(Eq, 
    Debug    )

    IdentityEvidence::IdentityEvidence

    source
    fn IdentityEvidence::IdentityEvidence(key? : String, value? : String, source? : String, note? : String) -> IdentityEvidence

    IdentityFinding

    source
    pub(all) struct IdentityFinding {
      id : String
      severity : Severity
      title : String
      expected : String
      actual : String
      source : String
      detail : String
    } derive(Eq, 
    Debug    )

    IdentityReport

    source
    pub(all) struct IdentityReport {
      canonical : SubmissionIdentity
      evidence : Array[IdentityEvidence]
      findings : Array[IdentityFinding]
      score : Int
      verdict : String
    } derive(Eq, 
    Debug    )

    IdentityReport::has_mismatch

    source
    fn IdentityReport::has_mismatch(self : IdentityReport) -> Bool

    IdentityReport::to_json

    source
    fn IdentityReport::to_json(self : IdentityReport) -> String

    IdentityReport::to_markdown

    source
    fn IdentityReport::to_markdown(self : IdentityReport) -> String

    NamedFile

    source
    pub(all) struct NamedFile {
      path : String
      content : String
    } derive(Eq, 
    Debug    )

    PackageManifest

    source
    pub(all) struct PackageManifest {
      module_name : String
      version : String
      readme : String
      repository : String
      license : String
      description : String
      owner : String
      package_name : String
      has_valid_name : Bool
      has_semver : Bool
    } derive(Eq, 
    Debug    )

    ProjectSnapshot

    source
    pub(all) struct ProjectSnapshot {
      name : String
      moon_mod : String
      readme : String
      ci_workflow : String
      license_text : String
      examples : Array[String]
      tests : Array[String]
      commands : Array[String]
      changelog : String
      design_notes : String
      issue_notes : String
      commit_count : Int
      repository_public : Bool
      mooncakes_published : Bool
      mooncakes_owner : String
      mooncakes_package : String
    } derive(Eq, 
    Debug    )

    ProjectSnapshot::ProjectSnapshot

    source
    fn ProjectSnapshot::ProjectSnapshot(name? : String, moon_mod? : String, readme? : String, ci_workflow? : String, license_text? : String, examples? : Array[String], tests? : Array[String], commands? : Array[String], changelog? : String, design_notes? : String, issue_notes? : String, commit_count? : Int, repository_public? : Bool, mooncakes_published? : Bool, mooncakes_owner? : String, mooncakes_package? : String) -> ProjectSnapshot

    RepairStep

    source
    pub(all) struct RepairStep {
      id : String
      kind : CheckKind
      severity : Severity
      title : String
      action : String
      blocking : Bool
    } derive(Eq, 
    Debug    )

    RuleSpec

    source
    pub(all) struct RuleSpec {
      id : String
      kind : CheckKind
      default_severity : Severity
      title : String
      evidence_hint : String
      repair_hint : String
      penalty : Int
    } derive(Eq, 
    Debug    )

    Severity

    source
    pub(all) enum Severity {
      Pass
      Warn
      Fail
    } derive(Eq, 
    Debug    )

    SourceEvidence

    source
    pub(all) struct SourceEvidence {
      name : String
      kind : SourceKind
      source_url : String
      license : String
      note : String
    } derive(Eq, 
    Debug    )

    SourceEvidence::SourceEvidence

    source
    fn SourceEvidence::SourceEvidence(name? : String, kind? : SourceKind, source_url? : String, license? : String, note? : String) -> SourceEvidence

    SourceKind

    source
    pub(all) enum SourceKind {
      OwnedCode
      ThirdPartyCode
      Dataset
      Asset
      GeneratedText
    } derive(Eq, 
    Debug    )

    SubmissionIdentity

    source
    pub(all) struct SubmissionIdentity {
      applicant_name : String
      phone : String
      email : String
      github_owner : String
      repository_name : String
      mooncakes_owner : String
      package_name : String
    } derive(Eq, 
    Debug    )

    SubmissionIdentity::SubmissionIdentity

    source
    fn SubmissionIdentity::SubmissionIdentity(applicant_name? : String, phone? : String, email? : String, github_owner? : String, repository_name? : String, mooncakes_owner? : String, package_name? : String) -> SubmissionIdentity

    acceptance_identity_markdown

    source
    fn acceptance_identity_markdown(canonical : SubmissionIdentity, snapshot : ProjectSnapshot, submission_text : String, git_user_name? : String, git_user_email? : String, git_remote? : String) -> String

    Check whether applicant, repository, git and Mooncakes identities agree.

    acceptance_identity_report

    source
    fn acceptance_identity_report(canonical : SubmissionIdentity, snapshot : ProjectSnapshot, submission_text : String, git_user_name? : String, git_user_email? : String, git_remote? : String) -> IdentityReport

    audit

    source
    fn audit(snapshot : ProjectSnapshot) -> AuditReport

    Run the default HarborCheck audit over a project snapshot.

    audit_json

    source
    fn audit_json(snapshot : ProjectSnapshot) -> String

    Build a compact JSON summary for integrations that need machine-readable output.

    audit_markdown

    source
    fn audit_markdown(snapshot : ProjectSnapshot) -> String

    Build a compact Markdown report for a project snapshot.

    catalog_size

    source
    fn catalog_size() -> Int

    doc_proof

    source
    fn doc_proof(markdown : String, sources : Array[SourceEvidence]) -> DocProofReport

    doc_proof_markdown

    source
    fn doc_proof_markdown(markdown : String, sources : Array[SourceEvidence]) -> String

    example_snapshot

    source
    fn example_snapshot() -> ProjectSnapshot

    Return a runnable fixture that demonstrates a release-ready MoonBit package.

    extract_doc_snippets

    source
    fn extract_doc_snippets(markdown : String) -> Array[DocSnippet]

    find_rule

    source
    fn find_rule(id : String) -> RuleSpec?

    harborcheck_example_snapshot

    source
    fn harborcheck_example_snapshot() -> ProjectSnapshot

    identity_consistency

    source
    fn identity_consistency(canonical : SubmissionIdentity, evidence : Array[IdentityEvidence]) -> IdentityReport

    identity_json

    source
    fn identity_json(report : IdentityReport) -> String

    identity_markdown

    source
    fn identity_markdown(report : IdentityReport) -> String

    parse_manifest

    source
    fn parse_manifest(moon_mod : String) -> PackageManifest

    parse_snapshot_bundle

    source
    fn parse_snapshot_bundle(bundle : String) -> Array[NamedFile]

    release_checklist

    source
    fn release_checklist(snapshot : ProjectSnapshot) -> String

    Build an actionable checklist from the audit result.

    rule_catalog

    source
    fn rule_catalog() -> Array[RuleSpec]

    rule_catalog_markdown

    source
    fn rule_catalog_markdown() -> String

    rules_for_kind

    source
    fn rules_for_kind(kind : CheckKind) -> Array[RuleSpec]

    rules_markdown

    source
    fn rules_markdown() -> String

    Return the built-in rule catalog in Markdown form.

    snapshot_from_bundle

    source
    fn snapshot_from_bundle(bundle : String, project_name? : String, commit_count? : Int, repository_public? : Bool, mooncakes_published? : Bool, mooncakes_owner? : String, mooncakes_package? : String) -> ProjectSnapshot

    snapshot_from_files

    source
    fn snapshot_from_files(files : Array[NamedFile], project_name? : String, commit_count? : Int, repository_public? : Bool, mooncakes_published? : Bool, mooncakes_owner? : String, mooncakes_package? : String) -> ProjectSnapshot

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io