moon-wipe

    Recursively find and optionally wipe MoonBit build directories

    cli
    cleanup
    disk-usage
    moonbit
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    4 days ago
    Downloads
    34

    #moon-wipe

    Recursively find and optionally wipe MoonBit build directories.

    moon clean only cleans the module you are standing in. moon-wipe walks a whole tree, reports what it found and how much space it occupies, and deletes it only when you ask.

    #Install

    #moon-binstall

    moon binstall f4ah6o/moon-wipe

    Prebuilt binaries are published to GitHub Releases for linux-x86_64, linux-aarch64 and darwin-aarch64. Linux binaries need glibc 2.34 or newer; moon-binstall.json declares that floor, so an older host stops with a build-from-source hint instead of a loader error.

    The same assets are reachable through the Mooncakes coordinate once the module is published there:

    moon binstall f4ah6o/moon-wipe/cmd/moon-wipe

    #From source

    moon install --path ./cmd/moon-wipe # => ~/.moon/bin/moon-wipe

    The installed binary is named after the main package directory, which is why the package lives in cmd/moon-wipe rather than cmd/main.

    #Usage

    moon-wipe [TARGET] [OPTIONS]

    TARGET is one of:

    TargetLooks forMarker
    moon (default)_build.moon_db
    mooncakes.mooncakes.moon-lock
    allboth of the above
    cache$MOON_HOME/cache, $MOON_HOME/registry

    A directory is only reported when it carries the marker, so a directory that merely shares the name is left alone.

    The default is a dry run:

    $ moon-wipe moon-wipe 0.1.0 Searching for MoonBit build directories in /home/you/code /home/you/code/a/_build 1.2 GiB 1,234 files /home/you/code/b/_build 340.5 MiB 567 files Found 2 directories, 1.5 GiB, 1,801 files Dry run: re-run with -w to delete

    Add -w to delete:

    $ moon-wipe -w ... Wiped 2 directories, freed 1.5 GiB

    #Options

    FlagMeaning
    -w, --wipeDelete what was found
    -i, --ignore <PATH>Skip this path; repeatable
    --root <PATH>Start searching here (default: current directory)
    --min-size <SIZE>Only report directories at least this large
    --older-than <DAYS>Only report directories untouched for this many days
    --jsonEmit machine-readable JSON
    -h, --helpPrint help
    -V, --versionPrint the version

    Sizes accept binary units and decimals: 100, 512K, 1.5G, 2GiB.

    #Why the walk prunes

    A _build directory contains a copy of the dependency sources:

    _build/native/debug/build/.mooncakes/...

    So the walk never descends into a directory whose name is a MoonBit artifact, whatever the current target is looking for. Without that rule, moon-wipemooncakes would report the same dependency tree once per build profile.

    #Library

    The scanner is usable on its own.

    ///|
    test {
    let options = @moon-wipe.Options::new()
    inspect(options.target.name(), content="moon")
    inspect(options.wipe, content="false")
    }

    ///|
    test {
    inspect(@moon-wipe.format_bytes(1536), content="1.5 KiB")
    inspect(@moon-wipe.group_digits(1234567), content="1,234,567")
    }

    ///|
    test {
    debug_inspect(
    @moon-wipe.cache_dirs_from("/home/u/.moon", None, None),
    content="[\"/home/u/.moon/cache\", \"/home/u/.moon/registry\"]",
    )
    }

    #Development

    moon check moon test moon fmt

    #Releasing

    Bump version in moon.mod and push to main. The release workflow reads the version with scripts/version.mbtx, compares it against the previous moon.mod, and only builds when the version actually moved. It then tags v<version> and attaches moon-wipe-<target> for each target.

    Pushing a v<version> tag by hand works too, as long as the tag matches moon.mod; a mismatch fails the run before anything is built.

    CliError

    pub(all) suberror CliError {
    CliError(String)
    }

    A command line that could not be understood.

    ScanError

    pub(all) suberror ScanError {
    ScanError(String)
    }

    A problem that stops the run before anything can be reported.

    Command

    pub(all) enum Command {
    Run(Options)
    Help
    Version
    }

    What the command line asked for.

    DirStats

    pub(all) struct DirStats {
    bytes : Int64
    files : Int
    newest : Int64
    } derive(
    Debug
    )

    What a directory occupies and when it was last touched.

    DirStats::to_repr

    Entry

    pub(all) struct Entry {
    path : String
    size : Int64
    files : Int
    ignored : Bool
    error : String?
    } derive(
    Debug
    )

    One directory that matched, with the space it occupies.

    Entry::new

    fn Entry::new(path : String, size : Int64, files : Int) -> Entry

    A freshly measured entry that has not been filtered or deleted yet.

    Entry::to_repr

    Options

    pub(all) struct Options {
    root : String
    target : Target
    wipe : Bool
    ignores : Array[String]
    min_size : Int64
    older_than_days : Int?
    json : Bool
    }

    Search and deletion settings.

    Options::new

    fn Options::new() -> Options

    Settings used when no flag is given: search for _build under the current directory and report without deleting anything.

    Rule

    pub(all) struct Rule {
    dir_name : String
    marker : String
    } derive(Eq,
    Debug
    )

    A directory name to look for, plus the marker file that proves the directory really belongs to MoonBit.

    Rule::equal

    fn Rule::equal(Rule, Rule) -> Bool

    Rule::not_equal

    fn Rule::not_equal(x : Rule, y : Rule) -> Bool

    Rule::to_repr

    ScanResult

    pub(all) struct ScanResult {
    root : String
    entries : Array[Entry]
    } derive(
    Debug
    )

    The outcome of a search.

    Target

    pub(all) enum Target {
    Moon
    Mooncakes
    All
    Cache
    } derive(Eq,
    Debug
    )

    What kind of directory to look for.

    Target::equal

    fn Target::equal(Target, Target) -> Bool

    Target::name

    fn Target::name(self : Target) -> String

    The name accepted on the command line.

    Example

    test {
    inspect(@moon-wipe.Target::Moon.name(), content="moon")
    inspect(@moon-wipe.Target::Mooncakes.name(), content="mooncakes")
    inspect(@moon-wipe.Target::All.name(), content="all")
    inspect(@moon-wipe.Target::Cache.name(), content="cache")
    }

    Target::not_equal

    fn Target::not_equal(x : Target, y : Target) -> Bool

    Target::parse

    fn Target::parse(text : StringView) -> Target raise CliError

    Parse a target name as accepted on the command line.

    Example

    test {
    debug_inspect(@moon-wipe.Target::parse("moon"), content="Moon")
    debug_inspect(@moon-wipe.Target::parse(" mooncakes "), content="Mooncakes")
    debug_inspect(@moon-wipe.Target::parse("all"), content="All")
    debug_inspect(@moon-wipe.Target::parse("cache"), content="Cache")
    }

    Target::rules

    fn Target::rules(self : Target) -> Array[Rule]

    The rules a target expands to.

    Example

    test {
    debug_inspect(
    @moon-wipe.Target::Moon.rules(),
    content="[{ dir_name: \"_build\", marker: \".moon_db\" }]",
    )
    debug_inspect(@moon-wipe.Target::All.rules().length(), content="2")
    debug_inspect(@moon-wipe.Target::Cache.rules().length(), content="0")
    }

    Target::to_repr

    VERSION

    let VERSION : String

    Version reported by --version and in the report header.

    cache_dirs_from

    fn cache_dirs_from(home : StringView, dep_cache : String?, registry_cache : String?) -> Array[String]

    Resolve the cache directories from an explicit home and overrides.

    Example

    test {
    debug_inspect(
    @moon-wipe.cache_dirs_from("/home/u/.moon", None, None),
    content="[\"/home/u/.moon/cache\", \"/home/u/.moon/registry\"]",
    )
    debug_inspect(
    @moon-wipe.cache_dirs_from("/home/u/.moon", Some("/d"), Some("/r")),
    content="[\"/d\", \"/r\"]",
    )
    }

    dir_size

    async fn dir_size(path : StringView) -> (Int64, Int)

    Total bytes and file count under path.

    dir_stats

    async fn dir_stats(path : StringView) -> DirStats

    Measure path without following symlinks.

    A link cycle cannot hang the walk and a linked tree is not counted twice. Unreadable subdirectories are skipped rather than aborting the measurement.

    format_bytes

    fn format_bytes(bytes : Int64) -> String

    Format a byte count with binary units.

    Example

    test {
    inspect(@moon-wipe.format_bytes(0), content="0 B")
    inspect(@moon-wipe.format_bytes(512), content="512 B")
    inspect(@moon-wipe.format_bytes(1024), content="1.0 KiB")
    inspect(@moon-wipe.format_bytes(1536), content="1.5 KiB")
    inspect(@moon-wipe.format_bytes(1048576), content="1.0 MiB")
    inspect(@moon-wipe.format_bytes(1099511627776), content="1.0 TiB")
    }

    group_digits

    fn group_digits(value : Int64) -> String

    Insert thousands separators into a non-negative integer.

    Example

    test {
    inspect(@moon-wipe.group_digits(0), content="0")
    inspect(@moon-wipe.group_digits(999), content="999")
    inspect(@moon-wipe.group_digits(1000), content="1,000")
    inspect(@moon-wipe.group_digits(1234567), content="1,234,567")
    }

    help_text

    fn help_text() -> String

    Usage text printed by --help.

    join

    fn join(dir : StringView, name : StringView) -> String

    Join a directory and a child name with exactly one separator.

    Example

    test {
    inspect(@moon-wipe.join("/a", "b"), content="/a/b")
    inspect(@moon-wipe.join("/a/", "b"), content="/a/b")
    inspect(@moon-wipe.join("/", "b"), content="/b")
    }

    measure_caches

    async fn measure_caches(dirs : Array[String], root : String, options : Options) -> ScanResult

    Measure the given cache directories, skipping the ones that do not exist.

    parse_args

    fn parse_args(args : ArrayView[String]) -> Command raise CliError

    Parse the arguments that follow the program name.

    Example

    test {
    let command = @moon-wipe.parse_args(["-w", "mooncakes"])
    guard command is Run(options) else { fail("expected Run") }
    inspect(options.wipe, content="true")
    debug_inspect(options.target, content="Mooncakes")
    }

    parse_size

    fn parse_size(text : StringView) -> Int64 raise CliError

    Parse a byte count such as 100, 512K, 1.5G, or 2GiB.

    Units are binary: K is 1024 bytes. A bare number is taken as bytes.

    Example

    test {
    inspect(@moon-wipe.parse_size("100"), content="100")
    inspect(@moon-wipe.parse_size("1K"), content="1024")
    inspect(@moon-wipe.parse_size("1.5M"), content="1572864")
    inspect(@moon-wipe.parse_size("2GiB"), content="2147483648")
    }

    render_json

    fn render_json(result : ScanResult, options : Options) -> String

    Render the machine-readable report.

    The shape is stable: root, target, wiped, entries, and total. error is null for entries that were measured or removed cleanly.

    render_report

    fn render_report(result : ScanResult, options : Options) -> String

    Render the report shown to the user.

    The result has no trailing newline so callers can decide how to emit it.

    scan

    async fn scan(options : Options) -> ScanResult

    Find every directory that matches the target.

    Moon, Mooncakes, and All walk options.root. Cache looks at the global caches instead, which live outside any project.

    strip_trailing_slash

    fn strip_trailing_slash(path : StringView) -> String

    Drop trailing separators, keeping a lone / intact.

    Example

    test {
    inspect(@moon-wipe.strip_trailing_slash("/a/b/"), content="/a/b")
    inspect(@moon-wipe.strip_trailing_slash("/a/b///"), content="/a/b")
    inspect(@moon-wipe.strip_trailing_slash("/"), content="/")
    inspect(@moon-wipe.strip_trailing_slash("/a/b"), content="/a/b")
    }

    wipe

    async fn wipe(entries : Array[Entry]) -> Array[Entry]

    Delete every entry that is not ignored and return the updated entries.

    Failures are recorded on the returned entry instead of aborting, so one directory that cannot be removed does not stop the rest of the run.