routecheck

    Dependency graph and subpackage boundary analyzer for WeChat Mini Programs, with WXML, JavaScript and WXSS parsers written in MoonBit

    wechat
    miniprogram
    wxml
    wxss
    linter
    static-analysis
    Download zip
    Version
    0.3.0
    License
    MIT
    Last updated
    13 hours ago
    Downloads
    11

    No dependencies

    #微信小程序路由体检(miniapp-routecheck)

    用 MoonBit 编写的微信小程序依赖图与分包边界分析器。它读取构建后的小程序目录,用自带的 WXML、JS、WXSS 解析器提取每个文件的引用,建立"页面 → 组件 → 脚本 / 模板 / 样式 / 图片"的完整依赖图。在此基础上,它检查分包边界、页面跳转、模板作用域、模块循环和包体积,并给出把主包文件挪进分包的瘦身建议。

    这些问题平时要到真机运行、上传代码或用户点击时才暴露。例如主包 require 了分包里的工具函数、navigateTo 打开了 tabBar 页面、独立分包悄悄依赖了主包的请求封装。本工具在提交前、在 CI 里一次性指出问题,每条诊断都带 文件:行:列。

    $ moon run cmd --target js -- --format text examples/shop-broken error pages/me/index.wxml:1:1 [wxml-syntax-error] <view> is never closed. warning packageGoods/detail/index.wxss:2:27 [local-wxss-resource] WXSS cannot load local file /images/logo.png on devices; ... error pages/index/index.wxml:3:3 [unknown-template] Template 'bannr' is not defined in this file or in a file it imports. warning pages/index/index.json $.usingComponents["coupon"] [unused-component] <coupon> is declared but never used ... error packageOrder/confirm/index.json $.usingComponents["thumb"] [cross-subpackage-reference] subpackage order cannot use packageGoods/components/thumb/index ... error pages/cart/index.js:1:26 [main-package-references-subpackage] The main package cannot use packageGoods/utils/sku.js ... error packageActivity/landing/index.js:1:29 [independent-subpackage-dependency] Independent subpackage activity must not depend on utils/request.js ... error pages/me/index.js:3:26 [navigate-to-tab-page] wx.navigateTo cannot open tabBar page pages/cart/index; use wx.switchTab. error pages/me/index.js:6:25 [switch-tab-to-non-tab-page] wx.switchTab can only open tabBar pages; ... error components/goods-card/index.js:5:28 [unknown-navigation-target] wx.navigateTo opens 'packageGoods/detial/index', which is not registered in app.json. warning utils/cache.js:1:23 [require-cycle] Modules require each other: utils/cache.js -> utils/store.js. ... info utils/legacy-share.js [unreferenced-file] Nothing references this file (36 bytes); ... info utils/chart.js [move-to-subpackage] Only subpackage goods uses this file; moving it under packageGoods/ would take 94 bytes out of the main package. Packages: main 3.8 KiB of 2048.0 KiB 35 files goods 0.8 KiB of 2048.0 KiB 10 files (0.1 KiB movable from main) order 0.4 KiB of 2048.0 KiB 3 files activity 0.1 KiB of 2048.0 KiB 2 files (independent) 8 errors, 3 warnings, 2 notes.

    #架构

    cmd/ CLI:参数、Node.js 文件枚举与按需读取、输出与退出码 │ ▼ routecheck 分析核心(纯 MoonBit,无 I/O,全部可用内存样例测试) audit.mbt / preload.mbt / tab_assets.mbt app.json 结构校验 graph.mbt 工作队列遍历 app → 页面 → 组件 → 源文件,生成带位置的类型化依赖边 resolve.mbt 模块解析:相对 / 根路径 / miniprogram_npm 逐级查找、扩展名与 index 补全 rules.mbt 模板作用域、未用组件、分包边界、跳转语义、Tarjan 循环检测、可达性、体积与迁移建议 report.mbt JSON / 文本 / SARIF 2.1.0 / Graphviz DOT │ ├── wxml/ WXML 解析器:元素树、严格闭合检查与错误恢复、{{ }} 感知、<wxs> 原文跳过 ├── jsscan/ JS 词法分析器(正则 / 除号判定、模板字符串嵌套、转义解码)+ 依赖与跳转提取 ├── wxss/ WXSS 扫描器:@import 与 url(),跳过注释和字符串 └── scan/ 共享游标:字符位置、行列号、BOM 处理

    三个解析器都是为这个工具从零写的,没有依赖第三方解析库。它们都会在出错后继续扫描,一个未闭合的字符串不会让后面的依赖丢失。核心分析不做任何 I/O:文件内容通过 Project 中的读取闭包按需提供,因此每条规则都能用内存中的小程序样例做单元测试。

    #在 MoonBit 生态中

    • 可复用的解析器包:wxml、jsscan、wxss、scan 是独立的 MoonBit 包,只依赖标准库,别的 MoonBit 项目(如小程序编辑器插件、代码生成器)可以单独引入。每个包都有 README.mbt.md,里面的用法示例是 moon test 会执行的文档测试:wxml、jsscan、wxss,分析核心见 analyze.mbt.md。
    • 多后端:分析核心不做 I/O,CI 在 JS、wasm-gc、native 三个后端上运行全部单元测试。CLI 通过 extern "js" 调用 Node.js 文件系统,目前只编译到 JS;核心可以直接编译成 Wasm,嵌入网页或编辑器扩展。
    • 用到的语言特性:enum 与模式匹配表达引用解析结果(Found / External / Missing / Escapes)和诊断级别;读取闭包让规则测试全部在内存中完成;#| 多行字符串直接内嵌小程序样例;moon fmt、moon check --deny-warn、moon info 与 .mbt.md 文档测试都在 CI 中把关。
    • 已发布到 mooncakes:模块名 jiabin777on-hue/routecheck。在其他 MoonBit 项目中引入:

      moon add jiabin777on-hue/routecheck

      然后在 moon.pkg 的 import 中加入需要的包,例如 "jiabin777on-hue/routecheck/wxml"。

    #运行

    需要 MoonBit 工具链和 Node.js 22.3 或更新版本。传入包含 app.json 的小程序目录,或包含 project.config.json 的项目目录(按 miniprogramRoot 查找源码)。

    moon run cmd --target js -- examples/shop # JSON 报告 moon run cmd --target js -- --format text examples/shop-broken # 终端阅读 moon run cmd --target js -- --format sarif <目录> > routecheck.sarif moon run cmd --target js -- --format dot <目录> | dot -Tsvg > deps.svg moon run cmd --target js -- --strict --max-package-kb 1800 <目录>

    选项说明
    --format json\|text\|sarif\|dot默认 json。sarif 可直接上传到 GitHub Code Scanning;dot 按包分簇输出依赖图,违规边标红,异步边为虚线。
    --strictwarning 也视为失败。
    --sarif-base <dir>SARIF 中的路径改为相对 <dir>(通常是仓库根目录),而不是小程序根目录,便于 Code Scanning 定位源码。
    --max-package-kb <n>单包上限,默认 2048。
    --max-total-kb <n>总体积上限,默认 20480。

    退出码:0 无 error;1 有 error(--strict 下含 warning);2 参数或文件系统错误。

    JSON 报告结构:

    { "summary": { "errors": 8, "warnings": 3, "infos": 2, "files": 51, "edges": 28 }, "packages": [{ "name": "goods", "root": "packageGoods", "independent": false, "files": 10, "bytes": 841, "movableBytes": 94 }], "findings": [{ "code": "main-package-references-subpackage", "severity": "error", "file": "pages/cart/index.js", "line": 1, "column": 26, "detail": "..." }], "moves": [{ "file": "utils/chart.js", "to": "packageGoods/utils/chart.js", "package": "goods", "bytes": 94, "conflict": false, "rewrites": [{ "file": "packageGoods/detail/index.js", "line": 3, "column": 27, "specifier": "../../utils/chart", "replacement": "../utils/chart" }] }] }

    moves 是 move-to-subpackage 建议的迁移清单:每个文件移到分包根目录下的同名路径,rewrites 列出移动后必须修改的每一处引用(文件:行:列,配置文件中为 JSON 路径)及修改前后的写法,text 格式在末尾以 “Moving files out of the main package” 列出同样内容。规则见 docs/rules.md。

    #GitHub Actions

    仓库自带组合 Action,在小程序仓库中加入下面的步骤即可把诊断上传到 Code Scanning,并在 Pull Request 的改动行上显示。输入、输出和私有仓库的注意事项见 docs/github-action.md。

    permissions: contents: read security-events: write steps: - uses: actions/checkout@v5 - uses: jiabin777on-hue/miniapp-routecheck@v0.3.0 with: path: .

    #检查范围

    完整规则、级别和依据见 docs/rules.md。概要:

    • 分包边界:主包引用分包、分包之间互相引用、独立分包依赖主包。覆盖 require / import、组件、WXML import·include、WXS、WXSS @import 和图片,识别 require.async 与 componentPlaceholder 两种合法的分包异步化写法。
    • 页面跳转:wx.navigateTo / redirectTo / reLaunch / switchTab 与 <navigator> 的目标是否已注册,tabBar 页面与普通页面是否用对了 API,相对路径按当前页面解析。
    • 引用解析:模块、组件(含 npm 构建产物)、模板、WXS、样式和图片是否存在。
    • 组件与模板:"component": true、组件文件完整性、声明却未使用的组件、<template is> 的作用域(import 不传递、include 继承包含方)。
    • 语法:WXML 标签闭合与错配、JS/WXS/WXSS 词法错误、WXSS 中真机不支持的本地背景图。
    • 模块循环:Tarjan 强连通分量(迭代实现,深链不会栈溢出)。
    • 体积:各包体积与限额,不被引用的文件,只被单个分包使用、可以移出主包的文件,以及移动这些文件时需要修改的每一处引用(迁移清单)。
    • 插件:主包与分包 plugins 的声明格式,plugin:// 组件与页面、requirePlugin 是否已声明,分包插件是否只在本分包使用,同一插件不能被多个分包声明。
    • Worker:workers 目录(字符串或 isSubpackage 对象形式)、Worker 代码不能引用目录外文件、目录只放 JS、wx.createWorker 入口是否存在。
    • app.json:页面与分包路径、重复与大小写冲突、entryPagePath、tabBar、图标、preloadRule 与 entranceDeclare。

    #验证

    moon test --target js # 64 个测试:三个解析器、解析器边界情况、每类规则(含插件、Worker)、迁移清单、Tarjan、4 个文档测试 moon test --target wasm-gc # 同一套测试在 wasm-gc 上运行(CI 还会跑 native) node --test test/cli.test.cjs # 13 个端到端测试:样例、SARIF(含 --sarif-base)、DOT、--strict、体积限额、编码、编译插件、参数

    examples/shop 是一个包含 3 个 tab 页、普通分包、独立分包、全局组件、WXS、模板和 npm 风格引用的商城小程序,预期零诊断。examples/shop-broken 在它的基础上为每类规则注入一个缺陷,端到端测试逐条核对诊断代码与行列号。examples/good 与 examples/broken 是早期的 app.json 配置样例。

    #真实项目验证

    在两个腾讯官方开源小程序上运行(2026-11-18 的默认分支):

    项目文件诊断说明
    Tencent/weui-wxss dist/3070 error,0 warning全部 126 条 info 为未被引用的样式文件(WeUI 按需引入的组件样式)。
    wechat-miniprogram/miniprogram-demo328350 error,30 warning官方示例,TypeScript + Less,11 个分包,含独立分包、Skyline 与 useExtendedLib。

    miniprogram-demo 中经人工核对的真实问题,例如:

    • packageAPI/pages/device/bluetooth/slave/slave.wxml 用 ../../../../common/head.wxml 引用模板,少了一级 ../,head、foot 两个模板因此都不可用。
    • packageCloud 中 wx.navigateTo 到 /page/cloud/pages/crud-detail/crud-detail,app.json 中没有注册这个路由(云开发页面现在位于 packageCloud/ 分包)。
    • packageExtend/pages/form/form/form.wxml 等页面的 ../images/*.jpg 指向不存在的目录(图片实际在 packageExtend/pages/images/)。
    • <image mode="center" ... mode='aspectFit'>、<slider value=... value=...> 这类重复属性。
    • 分包 packageAPI 的源文件体积为 2179 KiB,超过 2 MB 分包上限(以开发者工具上传结果为准)。
    • 其余 26 条 error 来自尚未"构建 npm"的依赖(如 threejs-miniprogram),在开发者工具中构建后即消失。

    验证过程中发现并修复的误报:useExtendedLib 扩展库组件、WeUI 的 url="" / javascript: 占位链接、openType 驼峰写法,以及 TypeScript / Less 项目(现按 useCompilerPlugins 分析源码,并像 tsc 一样忽略纯类型导入)。复现:

    git clone --depth 1 --recurse-submodules https://github.com/wechat-miniprogram/miniprogram-demo moon run cmd --target js -- --format text miniprogram-demo

    #已知局限

    JS 分析基于词法而非数据流,变量传入的 url 不检查。Taro、uni-app 等框架项目请传入编译输出目录;npm 依赖需先在开发者工具中构建。体积为源文件字节的近似值。详见 docs/rules.md。

    规则依据微信小程序全局配置、使用分包、独立分包与分包异步化。项目使用 AI 辅助设计、实现与测试,所有规则和测试由参赛者审核。

    Edge

    pub(all) struct Edge {
    from : String
    to : String
    kind : EdgeKind
    file : String
    location : String
    line : Int
    column : Int
    specifier : String
    } derive(Eq,
    Debug
    )

    A dependency between two graph nodes. Nodes are file paths, plus the base paths (without extension) of the app, pages and components. file/location/line/column say where the reference is written.

    EdgeKind

    pub(all) enum EdgeKind {
    PageFile
    Require
    RequireAsync
    EsImport
    Component
    AsyncComponent
    WxmlImport
    WxmlInclude
    Wxs
    WxssImport
    Asset
    } derive(Eq,
    Debug
    )

    EdgeKind::label

    fn EdgeKind::label(self : EdgeKind) -> String

    Finding

    pub(all) struct Finding {
    code : String
    severity : Severity
    file : String
    location : String
    line : Int
    column : Int
    detail : String
    } derive(Eq,
    Debug
    )

    One diagnostic. location is a JSON path for configuration files ($.pages[1]) and empty for source files, which use line/column instead. Both are 1-based; 0 means "not applicable".

    Finding::to_json

    Finding::where_

    fn Finding::where_(self : Finding) -> String

    file:line:column or file $.path, the way editors and terminals link to a location.

    Move

    pub(all) struct Move {
    file : String
    to : String
    package_name : String
    bytes : Int
    conflict : Bool
    rewrites : Array[Rewrite]
    } derive(Eq,
    Debug
    )

    A main-package file that only one subpackage uses, where to move it, and every reference that changes with the move.

    Options

    pub(all) struct Options {
    max_package_bytes : Int
    max_total_bytes : Int
    }

    Limits applied to the packaged size of each package and of the whole mini program. The defaults follow the published WeChat limits: 2 MB for the main package and for each subpackage, 20 MB in total.

    Options::default

    fn Options::default() -> Options

    PackageStats

    pub(all) struct PackageStats {
    name : String
    root : String
    independent : Bool
    files : Int
    bytes : Int
    movable_bytes : Int
    } derive(Eq,
    Debug
    )

    Size of one package as shipped.

    Project

    pub struct Project {
    sizes : Map[String, Int]
    reader : (String) -> String?
    sources : Map[String, String]
    outputs : Map[String, String]
    }

    The files of a mini program, keyed by /-separated path relative to the directory holding app.json, with their size in bytes. Contents are loaded on demand through reader, which returns None for files that cannot be read as UTF-8 text. Keeping I/O behind a closure lets the whole analysis run against in-memory fixtures in tests.

    Project::exists

    fn Project::exists(self : Project, path : String) -> Bool

    Project::from_sources

    fn Project::from_sources(sources : Array[(String, String)]) -> Project

    A project backed by a map of file contents; sizes are the UTF-8 length.

    Project::new

    fn Project::new(files : Array[(String, Int)], reader : (String) -> String?) -> Project

    Project::size

    fn Project::size(self : Project, path : String) -> Int

    Project::source_name

    fn Project::source_name(self : Project, path : String) -> String

    The file the developer wrote for path: the plugin source of a compiled file, otherwise path itself.

    Project::with_compiler_plugins

    fn Project::with_compiler_plugins(self : Project, plugins : Array[String]) -> Project

    The project as DevTools compiles it with the given compiler plugins (typescript, less, sass): each a.ts is analyzed as a.js and each a.less / a.scss / a.sass as a.wxss, unless the compiled file is already present. Findings name the source file again.

    Report

    pub struct Report {
    findings : Array[Finding]
    packages : Array[PackageStats]
    moves : Array[Move]
    edges : Array[Edge]
    files : Int
    }

    The result of analyzing one mini program.

    Report::count

    fn Report::count(self : Report, severity : Severity) -> Int

    Report::to_dot

    fn Report::to_dot(self : Report) -> String

    Graphviz DOT of pages, components and the files they depend on, with one cluster per package. Edges that break a package rule are red.

    Report::to_json

    Report::to_sarif

    fn Report::to_sarif(self : Report, root_uri? : String) ->
    Json

    SARIF 2.1.0, the format GitHub code scanning and most CI dashboards ingest. Paths are relative to the mini program root.

    Report::to_text

    fn Report::to_text(self : Report, options? : Options) -> String

    Human-readable report: one line per finding, then package sizes.

    Rewrite

    pub(all) struct Rewrite {
    file : String
    location : String
    line : Int
    column : Int
    specifier : String
    replacement : String
    } derive(Eq,
    Debug
    )

    One reference to update when files move into a subpackage. file and line/column (or location, a JSON path) say where it is written.

    Rewrite::where_

    fn Rewrite::where_(self : Rewrite) -> String

    Severity

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

    Severity::label

    fn Severity::label(self : Severity) -> String

    UnitKind

    pub(all) enum UnitKind {
    App
    Page
    Component
    } derive(Eq,
    Debug
    )

    analyze

    fn analyze(project : Project, options? : Options) -> Report

    Analyzes a mini program: validates app.json, builds the dependency graph of every page, component, script, template, style and asset, then applies the package boundary, navigation, template, cycle and size rules to it.

    audit_manifest

    fn audit_manifest(content : String, files : Array[String]) ->
    Json