Skip to content

Commit 602a8f7

Browse files
committed
feat(custom-rules): prototype versioned checker interchange
1 parent b3efd4e commit 602a8f7

10 files changed

Lines changed: 1126 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,9 @@ jobs:
110110
- name: Run tests
111111
run: make test-ci
112112

113+
- name: Test experimental custom-rule example
114+
run: RUMDL=target/debug/rumdl python3 -m unittest discover -s examples/custom-rules
115+
113116
- name: Check every non-ignored test belongs to a CI profile
114117
run: make check-test-selection
115118

‎docs/custom-rules.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
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+
```
Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
"""Example project policy for rumdl's experimental element interchange.
2+
3+
Static analysis only: this module never executes document content. It intentionally
4+
checks a small shell subset, not every possible way to launch a Python program.
5+
"""
6+
import json
7+
import re
8+
import shlex
9+
import sys
10+
11+
TOOLS = {"python", "python3", "pip", "pip3", "pytest"}
12+
SHELLS = {"bash", "sh", "shell", "zsh", "console", "shell-session"}
13+
INSTRUCTION = re.compile(r"\b(run|execute|invoke|install|start|test)\b", re.I)
14+
EXCEPTION = re.compile(r"mise-check:\s*(counterexample|bootstrap)\b")
15+
BOOTSTRAP = re.compile(r"\b(installing mise|install mise|bootstrapping mise)\b", re.I)
16+
17+
18+
def bare_python_command(line):
19+
"""Recognize command starts; quoted arguments are never executed or scanned."""
20+
try:
21+
lexer = shlex.shlex(line.lstrip().removeprefix("$ "), posix=True,
22+
punctuation_chars=";&|()")
23+
lexer.whitespace_split = True
24+
lexer.commenters = "#"
25+
tokens = list(lexer)
26+
except ValueError:
27+
return False # Incomplete shell syntax is outside this example's scope.
28+
command_start = True
29+
for token in tokens:
30+
if token and set(token) <= set(";&|()"):
31+
command_start = True
32+
elif command_start:
33+
if re.fullmatch(r"[A-Za-z_][A-Za-z_0-9]*=.*", token):
34+
continue
35+
if token in TOOLS:
36+
return True
37+
# Other commands, including mise, own the rest of this segment.
38+
command_start = False
39+
return False
40+
41+
42+
def check(document):
43+
if document.get("protocol") != "rumdl.elements" or document.get("protocol_version") != 1:
44+
raise ValueError("unsupported element protocol")
45+
source = document["source"].encode("utf-8")
46+
nodes = document["nodes"]
47+
48+
def text(node):
49+
start, end = node["range"]
50+
return source[start:end].decode("utf-8")
51+
52+
child_ranges = {}
53+
for candidate in nodes:
54+
child_ranges.setdefault(candidate["parent"], []).append(candidate["range"])
55+
prose_cache = {}
56+
57+
def prose(node):
58+
# Instruction words must come from this node's own prose, not code or
59+
# nested blocks whose instructions belong to a different context.
60+
if node["id"] not in prose_cache:
61+
start, end = node["range"]
62+
parts = []
63+
for begin, stop in child_ranges.get(node["id"], []):
64+
parts.append(source[start:begin])
65+
start = stop
66+
parts.append(source[start:end])
67+
prose_cache[node["id"]] = b" ".join(parts).decode("utf-8")
68+
return prose_cache[node["id"]]
69+
70+
def excepted(node):
71+
if any(BOOTSTRAP.search(text(nodes[i])) for i in node["heading_path"]):
72+
return True
73+
current = node
74+
while current is not None:
75+
previous = current["prev_sibling"]
76+
if previous is not None and nodes[previous]["kind"] == "html_block":
77+
if EXCEPTION.search(text(nodes[previous])):
78+
return True
79+
current = nodes[current["parent"]] if current["parent"] is not None else None
80+
return False
81+
82+
def code_lines(node):
83+
if node["kind"] == "code_span":
84+
start, end = node["content_ranges"][0]
85+
yield start, end, source[start:end].decode("utf-8").replace("\r\n", " ").replace("\n", " ")
86+
return
87+
buffer = bytearray()
88+
first = last = None
89+
for start, end in node["content_ranges"]:
90+
offset = start
91+
for chunk in source[start:end].splitlines(keepends=True):
92+
if first is None:
93+
first = offset
94+
buffer.extend(chunk)
95+
body = chunk.rstrip(b"\r\n")
96+
if body:
97+
last = offset + len(body)
98+
if chunk.endswith((b"\r", b"\n")):
99+
yield first, last if last is not None else first, buffer.decode("utf-8").rstrip("\r\n")
100+
buffer.clear()
101+
first = last = None
102+
offset += len(chunk)
103+
if buffer:
104+
yield first, last, buffer.decode("utf-8")
105+
106+
def commands(node):
107+
parts = []
108+
first = last = None
109+
for start, end, line in code_lines(node):
110+
if not parts:
111+
first = start
112+
last = end
113+
continued = not line.lstrip().startswith("#") and line.rstrip().endswith("\\")
114+
parts.append(line.rstrip()[:-1] if continued else line)
115+
if not continued:
116+
yield first, last, " ".join(parts)
117+
parts.clear()
118+
if parts:
119+
yield first, last, " ".join(parts)
120+
121+
diagnostics = []
122+
for node in nodes:
123+
kind = node["kind"]
124+
if kind not in {"code_span", "fenced_code", "indented_code"} or excepted(node):
125+
continue
126+
if kind == "fenced_code" and (node["language"] or "").lower() not in SHELLS:
127+
continue
128+
if kind in {"code_span", "indented_code"}:
129+
parent = nodes[node["parent"]] if node["parent"] is not None else None
130+
context = prose(parent) if parent else ""
131+
if not INSTRUCTION.search(context):
132+
if kind == "code_span" and re.search(r"\w", context):
133+
continue # Descriptive prose owns this span's context.
134+
previous = parent["prev_sibling"] if kind == "code_span" and parent else node["prev_sibling"]
135+
if previous is None or nodes[previous]["kind"] not in {"paragraph", "heading"} or not INSTRUCTION.search(prose(nodes[previous])):
136+
continue
137+
for start, end, line in commands(node):
138+
if (node["language"] or "").lower() in {"console", "shell-session"} and not line.lstrip().startswith("$ "):
139+
continue
140+
# A bare tool name in prose is a mention, not an instruction.
141+
if kind == "code_span" and line.strip() in TOOLS:
142+
continue
143+
if bare_python_command(line):
144+
diagnostics.append({
145+
"rule": "project/mise-command",
146+
"start_byte": start,
147+
"end_byte": end,
148+
"message": "Run Python tooling through mise exec --",
149+
})
150+
return {"protocol": "rumdl.diagnostics", "protocol_version": 1,
151+
"source_hash": document["source_hash"], "diagnostics": diagnostics}
152+
153+
154+
def main():
155+
try:
156+
result = check(json.load(sys.stdin))
157+
except (KeyError, IndexError, TypeError, ValueError) as error:
158+
print(f"mise checker: {error}", file=sys.stderr)
159+
return 2
160+
json.dump(result, sys.stdout)
161+
sys.stdout.write("\n")
162+
return 0 # Findings are data; report-diagnostics owns the lint exit code.
163+
164+
165+
if __name__ == "__main__":
166+
sys.exit(main())

0 commit comments

Comments
 (0)
⌂ 换网址