#moonsize

moon add BigSaltyMan/moonsize@0.5.1

#Building

moon build --target native --release
./_build/native/release/build/cmd/main/main.exe app.wasm

#Data segment encodings

moonsize app.wasm --data-segments --top 20
moonsize app.wasm --data-json new-data.json
moonsize app.wasm --html new-report.html --data-json new-data.json

#Visual report development

npm run dev

#Usage

usage: moonsize <file.wasm> [--top <n>] [--retained] [--dead-code]
                 [--compress] [--strict] [--call-graph <path>] [--html <path>]
                 [--max-size <size>] [--baseline <path.wasm>] [--diff-functions]
                 [--data-segments] [--diff-data] [--data-json <new-path.json>]
                 [--budget <config.json>] [--budget-json <path.json>] [--budget-md <path.md>]
                 [--experiment <report.html|report.json>] [--experiment-context <context.json>]
       moonsize <file.wasm> --why-index <n> [--why-root <n>] [--why-json <path.json>] [--strict]

Report the section table of a WebAssembly binary, rank its heaviest
functions, roll the bytes up by module, and follow the call graph to
identify candidates for investigation.

  --top <n>            how many functions to rank (default 10)
  --retained           dominated function bytes in the current graph model
  --dead-code          functions no root can reach
  --compress           whole-file gzip and independent section gzip sizes
  --data-segments      append data-entry file bytes (payload-ranked by --top)
  --data-json <path>   enable details and write all entries to a new .json file
                       offset expressions are recorded, not evaluated
  --diff-data          compare exact payload content groups; requires --baseline
                       --data-json then writes the data comparison format
  --strict             refuse to report when the call graph is incomplete,
                       instead of reporting it with a warning
  --call-graph <path>  write a new .dot or .json call graph; refuses existing paths
  --html <path>        write a new self-contained HTML report; refuses existing paths
                       --data-segments or --data-json adds current-input data details
  --max-size <size>    fail with exit code 3 above this size, where size is
                       bytes or a KB/MB/GB count such as 10KB or 1.5MB
  --budget <path>      validated multi-metric byte budgets; growth needs --baseline
  --budget-json <path> write budget JSON; requires --budget, refuses existing paths
  --budget-md <path>   write CI Markdown summary; requires --budget, refuses existing paths
  --baseline <path>    compare against another module and print the change;
                       --max-size then bounds the growth, not the file
  --diff-functions     append function and package changes; requires --baseline
  --experiment <path>  write measured before/after results; requires --baseline
                       refuses to overwrite an existing path
  --experiment-context <path>  attach declared build settings and validation
  --why-index <n>      explain a shortest model reference path to function n
  --why-root <n>       search from one actual model root (requires --why-index)
  --why-json <path>    write path JSON; refuses existing paths
                       query mode allows only these flags and --strict
                       element functions are conservative roots; paths are
                       not execution traces or predictions of savings

All report outputs refuse existing files, directories and link aliases.
Targets are checked together; each file is created exclusively. Output errors use exit 1.
Multiple files are not a transaction; a later failure may leave earlier new outputs.

Exit codes: 0 completed, 1 input/query/output/unavailable measurement, 2 bad arguments/config,
            3 over budget, incomplete strict graph, or path search limited.

moonsize app.wasm --retained --dead-code        # the full text report
moonsize app.wasm --html report.html            # charts, opens in a browser
moonsize app.wasm --call-graph graph.dot        # for Graphviz

#Optimization experiments

moonsize after.wasm --baseline before.wasm --experiment experiment.html \
  --experiment-context context.json --top 20

#Multi-metric budgets and CI summaries

moonsize after.wasm --baseline before.wasm --budget moonsize-budget.json \
  --budget-json budget-result.json --budget-md budget-summary.md

node scripts/demo-budget.mjs _build/native/release/build/cmd/main/main.exe
_build/native/release/build/cmd/main/main.exe _build/budget-demo/after.wasm \
  --baseline _build/budget-demo/before.wasm --budget examples/budget.json

#Explaining a function's reference path

moonsize app.wasm --why-index 47
moonsize app.wasm --why-index 47 --why-root 0
moonsize app.wasm --why-index 47 --why-json function-path.json --strict

node scripts/test-function-path.mjs _build/native/release/build/cmd/main/main.exe
node scripts/demo-function-path.mjs _build/native/release/build/cmd/main/main.exe

#Using the library

fn main {
  let bytes : Bytes = read("app.wasm")
  match @moonsize.parse_module(bytes) {
    Ok(parsed) =>
      match @moonsize.analyze(bytes, parsed) {
        Ok(analysis) => {
          let options = @moonsize.Options::default("app.wasm")
          // What the five heaviest functions cost, as text or as numbers:
          // `analysis.stats` and `analysis.retained` are there to be read.
          println(@moonsize.render_top_functions(analysis.stats, analysis.data.length(), 5))
          println(@moonsize.render_graph_warning(analysis.graph))
          println(@moonsize.render_dead_code(analysis, 5))
          println(@moonsize.render_retained(analysis, 5))
          println(@moonsize.render_html(analysis, options.path))
        }
        Err(error) => println(@moonsize.describe_error(error))
      }
    Err(error) => println(@moonsize.describe_error(error))
  }
}

#Analysis

#Symbol names

• a symbol is _M0<kind> and then a path: F a function, M a method, I a trait implementation;
• the package is B for the builtin package, C for moonbitlang/core, or P and an index — which runs into the first component's own length, so P55probe is index 5 followed by 5probe;
• a component is its length and then its name, and the length counts the mangled name;
• anything that cannot appear in an identifier is escaped as _ and the byte in hex, and a literal underscore is doubled: to__string_2einner is to_string.inner, _24default__impl is $default_impl, and a non-ASCII character is escaped one byte at a time, so 中 is _e4_b8_ad;
• a generic instantiation carries G...E with one code per argument, where a builtin is a single letter, a tuple is U...E, and a named type is R and a path;
• a closure is either an environment named __moonbit_<fn> or a body carrying C<id>l<line>, the id of the closure and the line it was written on;
• a trait implementation names two packages, its type's and its trait's.

#The call graph

• call x and return_call x — precise edges to x;
• ref.func x — a reference, which counts as reachable because the function may run later as a closure;
• call_indirect and return_call_indirect — conservative edges to static element candidates in the selected table;
• call_ref and return_call_ref — recognised call sites with an UnmodeledReferenceCall diagnostic. Target analysis is not implemented, including when ref.func immediately precedes the call. No target is guessed.

WARNING: the call graph has 1 analysis gap.
  function 0, offset 42: call_ref: reference-call target analysis is not implemented.

Dead-code and retained-size results may be inaccurate; do not use them as proof that a function can be removed.

#Parser bounds and Reader API

#Diagnostic API and export migration

#Retained size

• RETAINED == SIZE — the model attributes no other function's encoded bytes to this dominator; an actual source change may affect other sections and callers.
• RETAINED ≫ SIZE with a high DIES — investigate the corresponding dependency branch, then rebuild to measure the actual effect.
• IND — the function can be reached through a call_indirect, so removing it requires checking every dependent table entry and indirect call before removal.

#Dead code

#Compressed size

COMPRESSED SIZE
  raw   10675 B
  gzip   5207 B  (48.7% of raw, ratio 2.05x)

  BY SECTION — INDEPENDENT GZIP STREAMS

  SECTION              RAW  GZIP  RATIO
  code                5166  2712  1.90x
  custom (name)       4975  1983  2.50x
  data                 252   174  1.44x
  custom (producers)    71    95  0.74x
  type                  59    66  0.89x
  function              50    63  0.79x
  import                37    61  0.60x
  export                21    45  0.46x
  global                13    34  0.38x
  element                8    32  0.25x
  table                  7    31  0.22x
  memory                 5    29  0.17x
  datacount              3    27  0.11x

  Section gzip sizes are measured independently and are not additive.
  They do not represent shares of the whole-file gzip size.

#Judging what can be deleted

1. Check graph diagnostics, root assumptions and the runtime integration contract. --dead-code lists functions unreachable in this model; it is not a safe-deletion list.
2. Then look at --retained for large RETAINED values with DIES above zero. These identify modelled dependency branches to investigate, not promised savings.
3. Treat IND rows with care: an indirect candidate can only be removed when the table entry and the call sites go with it.

#Example output

Retained size

    #  INDEX  SIZE  RETAINED  DIES    SHARE  IND  FUNCTION
    1     47   158      5162    46    48.3%       ____moonbit__main
    2     39   301      1773    10    16.6%       int::Int::to__string_2einner
    3     37    24       887     8     8.3%       println
    4     34     9       819     5     7.6%       moonbit.println
    5     33   206       810     4     7.5%       moonbit.fprintln
    6     28    49       717     7     6.7%       moonbit.decref
    7     29   409       668     6     6.2%       moonbit.gc.free
    8     43   633       633     0     5.9%       int__to__string__dec

  DIES counts the other functions that become unreachable with this one.
  IND marks a function an indirect call could reach.

Dead code

  0 of 47 functions are unreachable from the roots
  0 bytes (0.0% of file)

  every function is reachable

#HTML report

moonsize examples/fib.wasm --html new-report.html

#CI integration

moonsize app.wasm --max-size 100KB                     # a ceiling on the file
moonsize app.wasm --baseline main.wasm --max-size 5KB  # at most 5 KB of growth

SIZE COMPARISON

                      baseline  current  delta
  total                  10675    11039  +364  (+3.4%)
  code                    5166     5299  +133  (+2.5%)
  custom (name)           4975     5205  +230  (+4.6%)
  data                     252      252  0  (0.0%)
  custom (producers)        71       71  0  (0.0%)
  ...

              baseline  current  delta
  custom (x)        10       13  +3  (+30.0%)

#Function and package changes

moonsize current.wasm --baseline previous.wasm --diff-functions --top 20

package encoded-byte sums = local function total_size sums
code section = function encoding + code overhead (header/count encoding)
function delta = matched delta + added bytes - removed bytes
               + unmatched current bytes - unmatched baseline bytes

moon build --target native --release
bash scripts/demo-function-diff.sh _build/native/release/build/cmd/main/main.exe

- uses: ./.github/actions/setup-moonbit
- name: Build the example and CLI
  run: |
    moon build --target wasm
    moon build --target native --release
- name: The example stays inside its budget
  env:
    EXAMPLE: _build/wasm/debug/build/examples/examples.wasm
    CLI: _build/native/release/build/cmd/main/main.exe
  run: |
    test -s "$EXAMPLE"
    printf 'budget input: %s\nbytes: %s\n' "$EXAMPLE" "$(wc -c < "$EXAMPLE")"
    sha256sum "$EXAMPLE"
    "$CLI" "$EXAMPLE" --max-size 100KB

- name: Setup MoonBit
  run: |
    curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash -s '0.10.13+cbb11c36f'
    echo "$HOME/.moon/bin" >> "$GITHUB_PATH"
- run: moon update
- run: moon build --target wasm --release
- name: Size budget
  run: moonsize _build/wasm/release/build/app/app.wasm --max-size 250KB

- name: Build the base branch
  run: |
    git worktree add "$RUNNER_TEMP/base" "origin/${{ github.base_ref }}"
    (cd "$RUNNER_TEMP/base" && moon build --target wasm --release)
- name: Size budget
  run: |
    moonsize _build/wasm/release/build/app/app.wasm \
      --baseline "$RUNNER_TEMP/base/_build/wasm/release/build/app/app.wasm" \
      --max-size 5KB

#Development

moon check --target native --deny-warn
moon test
moon build --target native --release
bash scripts/test-tail-calls.sh _build/native/release/build/cmd/main/main.exe
bash scripts/test-graph-diagnostics.sh _build/native/release/build/cmd/main/main.exe
bash scripts/test-parser-boundaries.sh _build/native/release/build/cmd/main/main.exe

#Regenerating the example

moon build --target wasm

stage=$(mktemp -d examples/report-update.XXXXXX)
cp _build/wasm/debug/build/examples/examples.wasm "$stage/fib.wasm"

moon run cmd/main -- \
  --html "$stage/report.html" \
  "$stage/fib.wasm"

sha256sum _build/wasm/debug/build/examples/examples.wasm "$stage/fib.wasm"

cp "$stage/fib.wasm" examples/fib.wasm
cp "$stage/report.html" examples/report.html