|
| 1 | +# Experimental custom checks |
| 2 | + |
| 3 | +The custom-checker prototype tests a language-neutral JSON contract using |
| 4 | +rumdl's parser and source positions. It is experimental, report-only, and limited |
| 5 | +to one standard/GFM Markdown document at a time. It does not run a checker for |
| 6 | +you, execute document commands, load lint configuration, cache diagnostics, or |
| 7 | +integrate with the language server. Compatibility is not guaranteed yet. |
| 8 | + |
| 9 | +An example project policy (Python 3.9 or newer) checks that instructional Python commands use |
| 10 | +`mise exec --`. Run each stage explicitly, or use a shell with pipeline failure |
| 11 | +propagation enabled: |
| 12 | + |
| 13 | +```bash |
| 14 | +set -o pipefail |
| 15 | +rumdl experimental export-elements docs/setup.md \ |
| 16 | + | python3 examples/custom-rules/mise_command.py \ |
| 17 | + | rumdl experimental report-diagnostics docs/setup.md |
| 18 | +``` |
| 19 | + |
| 20 | +The example checker always exits 0 when it produces valid diagnostic data. |
| 21 | +`report-diagnostics` exits 0 for a clean result, 1 for findings, or 2 for a protocol |
| 22 | +or input error. Shell pipeline failure propagation is needed to preserve failures |
| 23 | +from earlier stages. No commands are spawned by these rumdl subcommands. |
| 24 | + |
| 25 | +## Element payload |
| 26 | + |
| 27 | +`export-elements FILE` produces a JSON object with: |
| 28 | + |
| 29 | +- `protocol`: `rumdl.elements`. |
| 30 | +- `protocol_version`: `1`. |
| 31 | +- `path` and `source`: the supplied path and exact UTF-8 source. |
| 32 | +- `source_hash`: the BLAKE3 hash of the source bytes. |
| 33 | +- `nodes`: selected elements and their context, in source order. |
| 34 | + |
| 35 | +The selected node kinds are `code_span`, `fenced_code`, `indented_code`, `heading`, |
| 36 | +`paragraph`, `list_item`, `blockquote`, `html_block`, `table`, `table_row`, |
| 37 | +`table_cell`, `footnote_definition`, and `definition_body`. Node `id` is its array |
| 38 | +index. `parent` names the nearest exported ancestor; `prev_sibling` names the |
| 39 | +previous exported node with that parent. Either can be null. `heading_path` |
| 40 | +names the current heading hierarchy, including an enclosing heading when code |
| 41 | +appears inside one. Headings inside blockquotes, list items, footnotes, and |
| 42 | +definition bodies stop affecting the outline when that container ends. `info` |
| 43 | +and `language` describe fenced code; otherwise they are null. Info is the |
| 44 | +parser-decoded value, including entity and escape handling. |
| 45 | +Language is its first whitespace-delimited word. |
| 46 | + |
| 47 | +Every `range` is a half-open `[start_byte, end_byte]` into the original UTF-8 |
| 48 | +source. It includes code delimiters. `content_ranges` contains original source |
| 49 | +slices without code delimiters. Code-block content slices omit container prefixes; |
| 50 | +multiline inline-code interiors can retain continuation-line prefixes. Code-block slices |
| 51 | +come from parser text-event ranges; join them in order to read the raw code. |
| 52 | +They can be smaller than lines, especially with CRLF input. Inline code retains |
| 53 | +its original interior spaces and line endings. These are raw slices, not cooked |
| 54 | +CommonMark text: escapes, tabs, and whitespace have not been normalized. |
| 55 | +Non-code nodes have an empty `content_ranges` array. Frontmatter is not exported |
| 56 | +as nodes; it remains available in `source`. |
| 57 | + |
| 58 | +Python checkers must slice bytes, not Python character indices: |
| 59 | + |
| 60 | +```python |
| 61 | +raw = payload["source"].encode("utf-8") |
| 62 | +text = raw[start_byte:end_byte].decode("utf-8") |
| 63 | +``` |
| 64 | + |
| 65 | +For PR text or another in-memory document, use: |
| 66 | + |
| 67 | +```bash |
| 68 | +rumdl experimental export-elements --stdin --stdin-filename pr.md |
| 69 | +``` |
| 70 | + |
| 71 | +Export accepts at most 4 MiB of UTF-8 source and 100,000 nodes. The report stage |
| 72 | +currently reads a source file, so save the identical bytes when exporting stdin |
| 73 | +if you want to validate returned findings with rumdl. |
| 74 | + |
| 75 | +## Diagnostic payload |
| 76 | + |
| 77 | +A checker returns one JSON object, not log text or a JSON Lines stream: |
| 78 | + |
| 79 | +```json |
| 80 | +{ |
| 81 | + "protocol": "rumdl.diagnostics", |
| 82 | + "protocol_version": 1, |
| 83 | + "source_hash": "the unchanged source_hash from the element payload", |
| 84 | + "diagnostics": [ |
| 85 | + { |
| 86 | + "rule": "project/mise-command", |
| 87 | + "start_byte": 10, |
| 88 | + "end_byte": 16, |
| 89 | + "message": "Run Python tooling through mise exec --" |
| 90 | + } |
| 91 | + ] |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +`report-diagnostics FILE` reads this JSON from stdin. It validates the whole |
| 96 | +response before reporting findings. It rejects a stale hash, unknown protocol |
| 97 | +or version, invalid ranges or UTF-8 boundaries, malformed rule IDs, empty or |
| 98 | +oversized messages, control or bidi override/isolate characters, more than 10,000 findings, and responses |
| 99 | +larger than 1 MiB. Rule IDs use lowercase letters, digits, and hyphens in two |
| 100 | +nonempty parts separated by `/`. Unknown fields are ignored. Empty ranges at a |
| 101 | +valid source boundary are allowed. Columns in rumdl's output count characters; |
| 102 | +the interchange ranges count bytes. Findings never carry fixes. |
| 103 | + |
| 104 | +## Example policy and limits |
| 105 | + |
| 106 | +The Python example is static analysis. It checks shell fences for `python`, |
| 107 | +`python3`, `pip`, `pip3`, and `pytest` at simple shell command starts, including |
| 108 | +after `&&`, `||`, `;`, and pipes. Backslash line continuations stay together. It accepts commands wrapped by `mise exec --` |
| 109 | +or `mise x --`. Any other leading command also owns its arguments, so wrappers |
| 110 | +such as `env python` are not inspected. It checks inline and indented code when |
| 111 | +nearby text reads as an instruction. Bare tool names in prose, comments, and Python-language fences are |
| 112 | +not reported. Console and shell-session blocks check only `"$ "` prompt lines; |
| 113 | +fence languages are matched without case sensitivity, and untagged fences are |
| 114 | +skipped. This is a small example policy, not a complete shell analyzer. |
| 115 | +Heredoc bodies can be mistaken for commands. Shell substitutions, aliases, |
| 116 | +wrappers such as `sudo`, shell keywords, versioned executable names, and |
| 117 | +template-generated commands require a more capable checker. |
| 118 | + |
| 119 | +Mark an intentional counterexample or bootstrap step explicitly: |
| 120 | + |
| 121 | +```markdown |
| 122 | +<!-- mise-check: counterexample --> |
| 123 | + |
| 124 | +~~~bash |
| 125 | +python intentionally-unwrapped.py |
| 126 | +~~~ |
| 127 | +``` |
| 128 | + |
| 129 | +A marker applies to the following exported block or its descendants. Before a |
| 130 | +list it applies to the first item and its descendants, not later sibling items. |
| 131 | +Headings such as "Installing mise" exempt their section. These explicit exceptions avoid |
| 132 | +assuming that all mentions of an incorrect command are instructions to run it. |
| 133 | + |
| 134 | +The prototype does not honor `rumdl-disable` comments, per-file ignores, severity |
| 135 | +configuration, or custom lint configuration. All configuration flags are rejected. |
| 136 | +Flavor-specific constructs such as MkDocs admonitions are outside this first |
| 137 | +contract. Before integrating subprocess execution or declaring a stable plugin |
| 138 | +API, validate the contract against the requesting project's documentation and |
| 139 | +settle rule configuration and disable semantics. |
| 140 | + |
| 141 | +Run the example's end-to-end tests after building rumdl: |
| 142 | + |
| 143 | +```bash |
| 144 | +RUMDL=target/debug/rumdl python3 -m unittest discover -s examples/custom-rules |
| 145 | +``` |
0 commit comments