🥮 mooncakes.io

harborcheck

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

docs
examples
provenance
license
mooncakes
moon add NBB2006/harborcheck@0.1.2
Download zip
Author
Version
0.1.2
License
MIT
Repository
Last updated
4 hours ago
Downloads
2
README

#HarborCheck

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

#解决什么问题

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

#项目边界

HarborCheck 现在主打两个能力：

  • 文档示例证明：提取 README / docs 中的 fenced code block，识别 MoonBit 示例是否具备可运行形态；
  • 来源证明：记录自有代码、第三方代码、数据集、素材和生成文本的来源、许可证和说明，输出合规风险。

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

#安装方式

moon add NBB2006/harborcheck

Mooncakes 包名：NBB2006/harborcheck

#最小使用示例

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 证明报告；
  • 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 示例可运行形态识别；
  • 自有代码、第三方代码、数据集、素材、生成文本的来源证明建模；
  • 许可证信号检查，支持常见 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/NBB2006/harborcheck
https://mooncakes.io/api/v0/manifest/NBB2006/harborcheck

#维护资料

  • 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)

#
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)

#
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

#
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 issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io