MoonDocCheck

    A MoonBit documentation quality checker for open-source packages and contest submissions.

    moonbit
    documentation
    quality
    checker
    ci
    Download zip
    Author
    Version
    0.1.0
    License
    MIT
    Last updated
    2 months ago
    Downloads
    15

    Dependencies

    #MoonDocCheck

    #目录

    #Demo 展示

    Markdown 和终端 Demo 受限于截图长度,仅展示报告开头。

    #中文

    #项目简介

    MoonDocCheck 关注的是 MoonBit 项目的“文档准备度”:当一个陌生开发者打开仓库时,他能不能快速理解项目价值、找到使用入口,并判断这个项目是否值得信任。

    它不会替代 moon check、moon test 或 MoonBit 官方文档工具,而是补充检查那些常常被忽略的文档信号:公开 API 是否有说明、README 是否像项目门面、示例是否可检查、元数据是否完整、接口摘要是否生成、CI 是否体现基础验证。

    #为什么值得使用

    很多项目的代码已经能运行,但对外展示还不够完整。评审者或使用者通常不会先读完整源码,而是先看 README、API 注释、示例和项目元数据。

    MoonDocCheck 把这些信号整合成一份报告,帮助维护者在发布、参赛、课程提交、社区评审或团队交接前快速发现短板。

    它尤其适合:

    • MoonBit 开源项目发布前自检。
    • 比赛、课程或社区项目评审。
    • 为已有项目补全文档。
    • 快速了解陌生 MoonBit 仓库的文档成熟度。
    • 团队内部统一文档质量标准。

    #核心能力

    • 检查公开 MoonBit API 是否缺少 /// 文档注释。
    • 识别 TODO、FIXME 等弱文档。
    • 按项目和文件统计 API 文档覆盖率。
    • 找出缺文档最集中的文件。
    • 检查 README 是否包含项目介绍、文档入口和许可证信息。
    • 统计 Markdown 中的 MoonBit 示例,识别 mbt check / mbt nocheck。
    • 检查 moon.mod 元数据,并识别旧版 moon.mod.json。
    • 检查 pkg.generated.mbti 是否存在。
    • 检查 GitHub Actions 或脚本式验证信号。
    • 支持扫描本地目录和公开 GitHub 仓库 URL。
    • 支持文本、HTML、Markdown、JSON 四种报告格式。

    #基础使用

    以下命令需要在 MoonDocCheck 仓库根目录中运行。扫描与 MoonDocCheck 并列存放的其他 MoonBit 项目:

    moon run cmd/main -- scan ../my_moonbit_project

    生成适合人工评审的 HTML 报告:

    moon run cmd/main -- scan ../my_moonbit_project --format html --output report.html

    扫描公开 GitHub 仓库:

    moon run cmd/main -- scan https://github.com/user/project.git

    更完整的参数、配置文件、报告解读和排除规则请查看 用户指南。

    MoonDocCheck 会生成包含摘要、总体评价、文件覆盖率、问题清单和下一步建议的报告。Markdown 报告适合作为临时评审材料,JSON 报告适合接入其他工具链。生成的报告文件通常是本地评审产物,默认不建议提交到仓库。

    #中文文档

    #English

    #Overview

    MoonDocCheck is a documentation quality checker for MoonBit projects.

    It focuses on documentation readiness: when a new developer opens a repository, can they understand what the project is, find the right entry points, and trust the project enough to start using it?

    MoonDocCheck does not replace moon check, moon test, or official MoonBit documentation tools. It complements them by checking documentation-facing signals that matter during publishing, review, handoff, and open-source evaluation.

    #Why It Matters

    A project can compile and still be difficult to adopt. Reviewers and users usually look at the README, API docs, examples, metadata, and CI signals before reading the full source code.

    MoonDocCheck gathers those signals into one report so maintainers can quickly find documentation gaps before release or review.

    It is useful for:

    • Pre-release checks for MoonBit open-source packages.
    • Course, contest, or community project review.
    • Improving documentation for existing repositories.
    • Understanding the documentation maturity of an unfamiliar MoonBit project.
    • Keeping documentation quality consistent across a team.

    #Core Features

    • Detect missing /// comments on public MoonBit APIs.
    • Detect weak placeholder documentation such as TODO and FIXME.
    • Summarize API documentation coverage by project and file.
    • Highlight files with the most missing API docs.
    • Check whether README has a project overview, documentation entry, and license signal.
    • Count MoonBit examples in Markdown and recognize mbt check / mbt nocheck.
    • Inspect moon.mod metadata and recognize legacy moon.mod.json.
    • Check whether pkg.generated.mbti exists.
    • Inspect GitHub Actions and script-based validation signals.
    • Scan local directories and public GitHub repository URLs.
    • Render text, HTML, Markdown, and JSON reports.

    #Basic Usage

    Run the following commands from the MoonDocCheck repository root. To scan another MoonBit project stored next to MoonDocCheck:

    moon run cmd/main -- scan ../my_moonbit_project

    Generate an HTML report for human review:

    moon run cmd/main -- scan ../my_moonbit_project --format html --output report.html

    Scan a public GitHub repository:

    moon run cmd/main -- scan https://github.com/user/project.git

    For full options, configuration, report interpretation, and exclusion rules, see the User Guide.

    MoonDocCheck reports include a summary, overall assessment, file coverage, issue list, and issue-specific next steps. Markdown reports are useful as temporary review artifacts, and JSON reports are useful for tool integration. Generated reports are local artifacts by default and are usually not committed.

    #Documentation

    #指导手册

    #License

    This project is licensed under the MIT License.

    ApiItem

    pub(all) struct ApiItem {
    name : String
    kind : String
    file : String
    line : Int
    documented : Bool
    weak_doc : Bool
    } derive(Eq, ToJson,
    Debug
    )

    A public API item discovered in a MoonBit source file.

    CiStats

    pub(all) struct CiStats {
    workflow_files : Int
    has_moon_check : Bool
    has_moon_test : Bool
    has_moon_fmt : Bool
    has_moon_info : Bool
    has_moon_run : Bool
    has_script_validation : Bool
    } derive(Eq, ToJson,
    Debug
    )

    Summary of CI workflow readiness signals.

    CoverageConfig

    pub(all) struct CoverageConfig {
    min_public_api_coverage : Int?
    } derive(Eq, ToJson,
    Debug
    )

    Coverage thresholds loaded from moondoccheck.toml.

    DocIssue

    pub(all) struct DocIssue {
    severity : Severity
    file : String
    line : Int?
    message : String
    } derive(Eq, ToJson,
    Debug
    )

    A single issue found while scanning a MoonBit project.

    FileCoverage

    pub(all) struct FileCoverage {
    file : String
    public_api_total : Int
    public_api_documented : Int
    public_api_missing_docs : Int
    documentation_coverage : Int
    } derive(Eq, ToJson,
    Debug
    )

    Documentation coverage summary for one source file.

    MarkdownStats

    pub(all) struct MarkdownStats {
    files : Int
    code_blocks : Int
    mbt_check_blocks : Int
    mbt_nocheck_blocks : Int
    moonbit_blocks : Int
    } derive(Eq, ToJson,
    Debug
    )

    Summary of Markdown code examples found in project documentation.

    MoonModStats

    pub(all) struct MoonModStats {
    found : Bool
    legacy_json_found : Bool
    has_name : Bool
    has_version : Bool
    has_readme : Bool
    has_repository : Bool
    has_license : Bool
    has_keywords : Bool
    has_description : Bool
    } derive(Eq, ToJson,
    Debug
    )

    Summary of MoonBit module metadata found in moon.mod.

    ProjectReport

    pub(all) struct ProjectReport {
    project_name : String
    project_root : String
    files_scanned : Int
    moonbit_source_files : Int
    public_api_total : Int
    public_api_documented : Int
    public_api_missing_docs : Int
    documentation_coverage : Int
    api_items : Array[ApiItem]
    file_coverage : Array[FileCoverage]
    markdown : MarkdownStats
    readme : ReadmeStats
    moon_mod : MoonModStats
    ci : CiStats
    has_generated_mbti : Bool
    issues : Array[DocIssue]
    } derive(Eq, ToJson,
    Debug
    )

    Full scan report for a MoonBit repository.

    ReadmeStats

    pub(all) struct ReadmeStats {
    found : Bool
    has_overview : Bool
    has_usage : Bool
    has_code_example : Bool
    has_development_commands : Bool
    has_license_mention : Bool
    } derive(Eq, ToJson,
    Debug
    )

    Summary of README-related signals.

    RuleConfig

    pub(all) struct RuleConfig {
    check_readme : Bool
    check_moon_mod : Bool
    check_ci : Bool
    check_generated_mbti : Bool
    } derive(Eq, ToJson,
    Debug
    )

    Rule switches loaded from moondoccheck.toml.

    ScanConfig

    pub(all) struct ScanConfig {
    exclusions : Array[String]
    rules : RuleConfig
    coverage : CoverageConfig
    } derive(Eq, ToJson,
    Debug
    )

    Project-level configuration used to customize scan behavior.

    ScanOptions

    pub(all) struct ScanOptions {
    exclusions : Array[String]
    } derive(Eq, ToJson,
    Debug
    )

    User-configurable options for a project scan.

    Severity

    pub(all) enum Severity {
    Error
    Warning
    Suggestion
    } derive(Eq, ToJson,
    Debug
    )

    Severity of a documentation or project readiness issue.

    apply_scan_config

    fn apply_scan_config(config : ScanConfig, options : ScanOptions) -> ScanOptions

    Merge configuration-file exclusions with command-line scan options.

    build_file_coverage

    fn build_file_coverage(items : Array[ApiItem]) -> Array[FileCoverage]

    Build per-file documentation coverage from scanned public API items.

    default_scan_config

    fn default_scan_config() -> ScanConfig

    Build default scan configuration.

    default_scan_options

    fn default_scan_options() -> ScanOptions

    Build default scan options.

    is_github_workflow_file

    fn is_github_workflow_file(path : String) -> Bool

    Classify GitHub Actions workflow files.

    is_markdown_file

    fn is_markdown_file(path : String) -> Bool

    Classify whether a file path points to Markdown documentation.

    is_moonbit_source_file

    fn is_moonbit_source_file(path : String) -> Bool

    Classify whether a file path points to a MoonBit source file.

    is_readme_file

    fn is_readme_file(path : String) -> Bool

    Classify README files accepted by MoonDocCheck.

    matches_exclusion

    fn matches_exclusion(path : String, pattern : String) -> Bool

    Return true when a path matches a user-provided exclusion pattern.

    parse_scan_config

    fn parse_scan_config(source : String) -> ScanConfig

    Parse the supported moondoccheck.toml configuration subset.

    project_name

    fn project_name() -> String

    Return the project display name.

    project_readiness_issues

    fn project_readiness_issues(report : ProjectReport, config : ScanConfig) -> Array[DocIssue]

    Build project-readiness issues from scan facts and configured rules.

    render_html

    fn render_html(report : ProjectReport, all_issues? : Bool, lang? : String) -> String

    Render a project report as a standalone HTML preview.

    render_json

    fn render_json(report : ProjectReport, indent? : Int) -> String

    Render a project report as machine-readable JSON.

    render_markdown

    fn render_markdown(report : ProjectReport, all_issues? : Bool, lang? : String) -> String

    Render a project report as Markdown.

    render_text

    fn render_text(report : ProjectReport, all_issues? : Bool, lang? : String) -> String

    Render a project report as terminal-friendly text.

    report_from_api_items

    fn report_from_api_items(project_name : String, items : Array[ApiItem]) -> ProjectReport

    Build a minimal report from source-level scan results.

    scan_ci_text

    fn scan_ci_text(source : String) -> CiStats

    Scan workflow text for common MoonBit validation commands.

    scan_markdown_text

    fn scan_markdown_text(source : String) -> MarkdownStats

    Scan Markdown text and count MoonBit-related code examples.

    scan_moon_mod_json_text

    fn scan_moon_mod_json_text(source : String) -> MoonModStats

    Scan a legacy moon.mod.json file for package metadata.

    scan_moon_mod_text

    fn scan_moon_mod_text(source : String) -> MoonModStats

    Scan a moon.mod file for package metadata used by MoonBit package reviewers.

    scan_moon_source

    fn scan_moon_source(file : String, source : String) -> Array[ApiItem]

    Scan a MoonBit source text and return public API items found in it.

    scan_project

    fn scan_project(path : String) -> ProjectReport raise

    Scan a MoonBit project directory and build a documentation quality report.

    scan_project_with_options

    fn scan_project_with_options(path : String, options : ScanOptions) -> ProjectReport raise

    Scan a MoonBit project directory with explicit scan options.

    scan_readme_text

    fn scan_readme_text(source : String) -> ReadmeStats

    Scan README content for common open-source project sections.

    should_ignore_path

    fn should_ignore_path(path : String) -> Bool

    Return true when a path should be ignored during project scanning.

    should_ignore_path_with_exclusions

    fn should_ignore_path_with_exclusions(path : String, exclusions : Array[String]) -> Bool

    Return true when a path should be ignored by default rules or custom exclusions.

    version

    fn version() -> String

    Return the current package version.