# mooncram CLI behavior specification [中文版本](CLI_SPEC_CN.md) This document describes the CLI behavior of the `0.0.7` module. It covers the command line, Markdown input format, process execution, matching, reporting, and updates. The English and Chinese versions have the same section structure and should be maintained together. Examples containing `mooncram` fences are enclosed in larger Markdown example fences so that this specification does not itself introduce executable cases. Paths such as `./hello.mbtx` in those examples are illustrative. ## 1. Invocation and command-line parsing ```text mooncram [global-options] check [paths...] [global-options] mooncram [global-options] test [paths...] [global-options] mooncram [global-options] update [paths...] [global-options] [--dry-run] mooncram (-h | --help) mooncram (-V | --version) mooncram help [check|test|update] mooncram check (-h | --help) mooncram test (-h | --help) mooncram update (-h | --help) ``` From the repository checkout, the executable can be launched with: ```text moon run . -- check README.md moon run . -- test README.md moon run . -- update examples --dry-run ``` The `--` in these examples separates `moon` arguments from mooncram arguments. A later `--` can terminate mooncram's own option parsing. | Command | Behavior | | --- | --- | | `check` | Validate documents and resolve local targets without building or executing cases. | | `test` | Execute cases and compare routed output and exit status with the expectations. | | `update` | Execute cases, then update and normalize their expectations from observed results, including passing cases. | | `update --dry-run` | Execute cases and print proposed document changes without writing them. | | `help`, `-h`, `--help` | Print the relevant help to stdout and exit with `0`, without discovering or executing cases. | | `-V`, `--version` | At the top level, print the executable's version string followed by a newline to stdout and exit with `0`. | A subcommand is required unless a help or version request is handled. An empty command line is an argument error, not an implicit `test`. Version flags are not available after `check`, `test`, or `update`; for example, `mooncram test --version` is an argument error. ### 1.1 Options and defaults | Option | Scope | Default | Accepted values and effect | | --- | --- | --- | --- | | `--target VALUE` | Global, `test`/`update` only | `wasm` | Exactly `wasm` or `native`; default backend for local package cases. | | `--timeout-ms N` | Global, `test`/`update` only | `60000` | Positive signed 32-bit integer in milliseconds; one deadline for each case's build and execution. | | `--color VALUE` | Global | `auto` | Exactly `auto`, `always`, or `never`; controls mooncram's report coloring. | | `--dry-run` | `update` only | Off | Print proposed document diffs instead of replacing documents. Takes no value. | Global options can appear before the subcommand, before paths, between paths, or after paths. Both `--target native` and `--target=native` forms are accepted; the other value options also accept `--name=value`. These options have no short aliases. Each global value option may be supplied only once, including across both sides of the subcommand; repeated occurrences are errors rather than overrides. Repeating `--dry-run` keeps it enabled. `--dry-run` must occur after `update`. It is invalid at the top level and for `check` or `test`. `check` also rejects explicit `--target` and `--timeout-ms`, even when they equal the defaults or appear before the subcommand. All three commands accept `--color`. Unknown commands/options, missing option values, and invalid values produce exit status `2`. For `--timeout-ms`, only ASCII decimal digits are accepted, with value in `1..2147483647`. Leading zeroes are allowed. Signs, spaces, fractions, zero, and overflow are rejected. Validation after argument parsing checks target, then timeout, then color. `paths` accepts zero or more values. With no paths, it becomes `.`. After the subcommand, `--` makes all remaining arguments paths, including names starting with `-`: ```text mooncram --target native test docs README.md --color never mooncram update docs --timeout-ms=120000 --dry-run mooncram test -- -example.md ``` Mooncram does not expand path globs itself. Expansion by the shell launching mooncram happens before the CLI receives its arguments. A fence can declare its module; target and timeout are controlled by the CLI options. ### 1.2 Check without execution `check` shares file discovery, Markdown parsing, command and expectation validation, and document-level module/directory validation with `test` and `update`. Configuration-only fences are validated too. It then resolves each pipeline segment against the current filesystem, checking script existence, full executable package names, module boundaries, and exact remote coordinates. It reads local files and configuration without building, downloading dependencies, starting subprocesses, or modifying Markdown. A document parse or declaration-validation failure counts as one error and prevents checking its cases. A target-resolution failure counts as one error for that case, skips its remaining segments, and continues with later cases and files. The summary is `N cases, E errors`; a run with no cases and no other errors uses the no-cases error described in section 2. Command parsing does not query the environment. Arguments and assignment values remain literal after quoting and escaping. Check results depend on the current filesystem. A target generated by an earlier case may be reported missing by `check`; `test` and `update` resolve targets at execution time and support this pattern. `check` does not verify source compilation, backend build support, remote-coordinate existence, or program assertions. It has no per-case execution timeout. ## 2. File discovery and ordering Discovery completes before any document is read or any case is executed. 1. Resolve each supplied path against mooncram's invocation directory. 2. Recurse into actual directories. During enumeration, skip entries beginning with `.`, entries hidden according to the filesystem API, and entries named exactly `_build` or `target`. This includes Windows hidden attributes. 3. Select regular files whose encountered path ends in the case-sensitive suffix `.md`. A directly supplied regular file with another suffix is ignored. 4. For a file symlink with an encountered `.md` suffix, include its target if it is a regular file. Do not traverse directory symlinks. 5. Resolve selected files to canonical absolute paths, deduplicate those paths, and sort them lexicographically. The skip rules apply to directory entries during traversal. An explicitly supplied hidden file, hidden directory, `_build`, or `target` is not rejected just because of its name; its contents still follow the normal discovery rules. Deduplication uses canonical paths, not file contents or inode identity. The suffix test is on the encountered path, so an `alias.md` symlink can select a regular target whose own name has another suffix. A missing input or a filesystem error during discovery aborts the entire run with status `2`; already discovered files are not executed. Symlinks ending in `.md` whose targets cannot be inspected can also produce discovery errors. Documents run in sorted canonical-path order, independently of argument order. Cases run serially in document order. Segments of the same pipeline run concurrently. Filesystem side effects from earlier cases remain visible to later cases. Each process starts in the block's working directory (the canonical document's parent by default) and inherits mooncram's environment, overridden by the segment's temporary assignments. A document without cases is allowed when other documents contain cases. If there are no attempted cases (checked or executed) and no recorded errors, the CLI reports `ERROR no mooncram cases found` and exits with `2` without a summary. ## 3. Markdown recognition and case boundaries Documents are read as UTF-8; decoding failures are document errors. Markdown is parsed structurally with `cmark`, with source locations and layout retained. Fenced code blocks with a backtick opening fence and the exact, case-sensitive language `mooncram` contain tests. The info string accepts optional whitespace and a single module name, such as `mooncram user/foo`. The declaration is scoped to that fence; ordinary fences have no module name. Multiple words or invalid module names are document parsing errors at the opening line. Module/package names use nonempty slash-separated components with ASCII letters, digits, `_`, `-`, or `.`; `.` and `..` components are prohibited. Valid longer backtick fences work as well as triple backticks. Other languages, indented code blocks, tilde fences, and apparent fences inside larger code examples are silently ignored. Cases inside block quotes and lists are supported; the Markdown container prefix is not part of the command or output. Normal Markdown indentation rules apply before parsing lines. An eligible fence must have a closing fence and at least one command or working directory declaration. An unclosed or empty eligible fence is a document parsing error. Ignored fences do not produce mooncram parsing errors. ````markdown ```mooncram user/foo $ moonx ./hello.mbtx "Moon Bit" Hello, Moon Bit! $ moonx user/foo/cmd/main --version my-cli * (glob) ``` ```` Within the parsed code block: - A line beginning exactly with `#cwd(` starts a working directory declaration and ends any preceding expectation span. It must be the first nonempty line. - A line beginning exactly with `$ ` starts a command and a case. A line consisting only of `$` is also treated as a command start, then rejected as an empty command. - Before the first command, only completely empty lines and a valid directory declaration are accepted. Any other line is an error. `$` followed only by a tab is not the `$ ` command prefix. - Every following line up to the next command, directory declaration or closing fence is an expectation line, except completely empty lines at the end of that span. - Trailing empty lines are separators and are excluded from expectations. Empty lines inside the remaining expectation span are real output lines; whitespace-only lines are not empty separators. - Commands occupy one source line. There is no multiline command continuation, comment syntax, or separate setup/teardown syntax inside a test block. A line of output that would look like a command or begin with `#cwd(` must use a JSON string with `(escaped)`. The whole document, including all commands and expectations, is parsed before executing any case in that document. A parsing error prevents every case in that document from running, even cases before the error. Later documents are still processed. Reported source line numbers are one-based positions in the original Markdown document. ### 3.1 Remote package coordinates Use `$ moonx user/module[/package]@version ` directly in a test fence. Coordinates require at least two nonempty path components, following the module/package name rules above. Versions must be exact SemVer `MAJOR.MINOR.PATCH`, optionally followed by `-prerelease` and `+build`. Core numbers and numeric prerelease identifiers have no leading zeros; build identifiers may have them. Identifiers contain ASCII letters, digits and hyphens, separated by dots, with no empty identifiers. `latest`, ranges, wildcards and malformed versions are rejected during target resolution. Unversioned targets are local and require a matching module declaration. Remote coordinates are independent of fence module declarations; `check` does not verify their registry existence. ````markdown ```mooncram $ moonx moonbit-community/moongrep@0.3.5 --version * (glob) ``` ```` ## 4. Command tokenization and executable selection The text after the leading `$` is tokenized directly into an array of pipeline segments. It is not passed to a shell. The command parser returns `Array[PipelineSegment]`. Optional `case_insensitive : Bool = false` normalizes temporary assignment names to ASCII uppercase when enabled; the document parser enables it on Windows. Returned arguments and assignment values have quotes and escapes processed, with variable-like text kept literal. `PipelineSegment` has `argv : Array[String]` and `extra_env : Map[String, String]`, with `Debug` and `Eq`. `argv` includes `moonx`, the target and program arguments. `Case.pipeline` stores these segments. Segment `extra_env` contains temporary assignments, which override inherited variables for that segment's build and run. The original command text is retained for reports, update and dry-run. | Syntax | Meaning | | --- | --- | | Unquoted, unescaped `\|` | Separate pipeline segments, even without surrounding spaces. | | Unquoted space or tab | Separate arguments; consecutive separators are ignored. | | `'text'` | Literal text until the next single quote; backslashes are literal. | | `"text"` | Text until the next unescaped double quote. | | Backslash outside single quotes | Quote exactly the next character, including inside double quotes. | | `''` or `""` | An empty argument, which is preserved. | | Adjacent quoted/unquoted fragments | Concatenated into the same argument; `a"b"c` becomes `abc`. | | `${NAME}` or `$NAME` | Ordinary text, using the same splitting, quoting and escaping rules as other text. | Backslash does not interpret C/JSON escape sequences: `\n` contributes `n`, not a newline, unless the backslash is inside single quotes. A trailing backslash or an unclosed quote is a parsing error. The underlying command parser rejects NUL, CR and LF. Raw NUL characters in Markdown are first replaced by cmark with `U+FFFD` (`�`), so they do not trigger the NUL check. Empty pipeline segments, including leading/trailing `|` and `||`, are parsing errors. Quoted or escaped `|` is an ordinary argument character. For example: ```text $ moonx ./producer.mbtx|moonx user/foo/cmd/filter|moonx ./consumer.mbtx ``` Unquoted, unescaped `&`, `;`, `<`, `>`, backticks, `(` and `)` are rejected wherever they occur in a word. Output redirection, including `2>&1` and `1>/dev/null`, is unsupported in every pipeline segment. Quoting or escaping operators passes them literally: `'2>&1'`, `2\>\&1` and `1\>/dev/null` are ordinary arguments. There is no wildcard or tilde expansion or command substitution. For example, `'$HOME'`, `*`, `~` and `'$(cmd)'` are literal arguments; unquoted `$(cmd)` is rejected because of its parentheses. Errors retain the document filename and command line number. `#cwd(path)` declares one working directory for the current fence. The Markdown block parser recognizes a whole logical line starting exactly with `#cwd(` and ending with `)`. It takes all text between the opening prefix and the final `)` as the nonempty path, without trimming, tokenization, escaping, variable expansion or parenthesis matching. Spaces, backslashes, quotes, parentheses, Chinese text and `${NAME}` remain literal. For example, `#cwd(../fixtures with spaces)` needs no quotes; `#cwd("foo")` includes the double quotes in its path, and `#cwd(a)b(c))` stores `a)b(c)`. Each block permits at most one declaration on its first nonempty logical line; leading empty lines are allowed. Empty paths, missing final `)`, duplicates and declarations after a test command are parsing errors with source locations. A declaration accepts no expected output or exit code. It is not a case; configuration-only fences are legal, with the usual no-cases rule for a whole run. Output beginning with `#cwd(` must use a JSON string with `(escaped)`, even when it would be a malformed declaration. The updater automatically escapes such output so generated documents parse again and a second update is unchanged. Updates preserve the declaration's original text and Markdown layout. The parser does not inspect the filesystem. `WorkingDirectoryDeclaration` contains `directory : String` and its one-based `line : Int`. `Case.working_directory` is optional; `Document.working_directory_declarations` retains every declaration, including those in fences without cases. Configuration resets at each fence. After parsing and module validation, before any case or build in that document, `validate_document_working_directories` checks every declaration. Relative paths resolve against the canonical Markdown file's parent, never another block's cwd; absolute paths are accepted. Targets must already be directories, including symlink targets, and are resolved to real absolute paths. Earlier cases cannot create these directories. The returned `Map[Int, String]` maps declaration lines to validated directories. The CLI selects each case's directory from that map, using the document directory when no declaration applies. Validation failures are one document error, located at the directive and showing the resolved path: zero cases execute and no update occurs in that document, while later documents continue. A directory removed after validation follows the normal execution-error rules. Local modules resolve from startup cwd and package builds use `moon -C `; their subprocess cwd is the configured block directory. Environment variable expansion is not supported. `${NAME}`, `$NAME`, `${}`, `${A-B}` and `${UNCLOSED` are ordinary text and do not trigger environment lookup or reference validation. Normal splitting, quoting and escaping still apply: `${A B}` is two arguments, while `"${A B}"` is one literal argument. Assignment values follow the same rules. Expected output is literal too. The whole document must parse before any case runs. `$ NAME=value OTHER="${NAME}" moonx ./program.mbtx` sets temporary variables for one pipeline segment and its build. Only consecutive assignments before the executable are recognized, with an unquoted, unescaped name and `=`; names must match `[A-Za-z_][A-Za-z0-9_]*`. Values follow the command quoting and escaping rules, including empty values and additional `=`. Assignments after the executable are ordinary arguments. Words with invalid variable names, such as `9A=x` and `A-B=x`, are not recognized as temporary assignments. They are ordinary words; before `moonx` they cause a missing-moonx parsing error, and after the target they remain program arguments. Temporary values override the parent environment, including with an empty string. Values and arguments remain literal: `A=new B="${A}" moonx ./program.mbtx "${B}"` sets `B` to `${A}` and passes `${B}` as its argument. Repeated names keep the last value. Each pipeline segment has its own temporary environment, and later commands inherit the parent environment. Windows names are normalized to ASCII uppercase and matched case-insensitively; Linux and macOS names remain case-sensitive. Assignments without a command are parsing errors. After temporary assignments, every executable segment must begin with `moonx` and a nonempty target. Missing prefixes, bare targets and empty targets are parsing errors. No moonx options are accepted before the target. Target paths, working directories and file arguments keep variable-like text literal. An `export` executable is rejected with `command must start with moonx: export`. A target ending in `.mbtx` is a local script, relative to the block's working directory or absolute. This includes script filenames containing `@`. Otherwise a target containing `@` must be a valid remote coordinate with exact SemVer, even if its package name matches the declared local module. Before processing any case, all module declarations must exactly match `name` in the `moon.mod` directly in mooncram's startup cwd, including configuration-only fences. Missing/invalid configuration or mismatches are document errors at the opening fence. There is no parent-directory search. `Case.module_name` stores the optional name; `Document.module_declarations` stores names and opening lines. Unversioned package targets require a module-declared fence and the full package name. For module `user/foo`, `user/foo` selects the root package and `user/foo/cmd/boo` selects that subpackage. `foo`, `cmd/boo`, other module names and paths such as `./foo` are rejected. Missing, empty or null `source` means the module root; otherwise the source root must remain inside the module. Full names are mapped relative to this source root. Packages must declare `pkgtype(kind: "executable")` or `options("is-main": true)`. Compilation and backend errors propagate. Traversal, empty path components, nested `moon.mod` boundaries and symlink escapes are prohibited. `moon.pkg` is parsed with `moonbitlang/moon_config@0.4.2`; invalid configurations are errors. Arbitrary binaries, shell commands and `.mbt` files are not targets, and user targets are not searched through `PATH`. Every argument after the target, including `--`, `--version` and `--target`, is forwarded unchanged to the program. `Case.command` retains the original source command. ## 5. Build, execution, capture, and timeout Mooncram uses external MoonBit tools. `moon` must be available to build cases; scripts and remote packages also require `moonx`, Wasm packages require `moonrun`, and native package builds require the corresponding native toolchain. The backend used to run mooncram itself is separate from the backend selected for a test case. The following argument vectors use resolved absolute paths. Angle-bracket items are placeholders, not shell syntax: | Case kind | Build preflight | Program invocation | | --- | --- | --- | | `.mbtx` script | `moon run --build-only --target wasm