Replace the Strong/Emph/List/Quote mapping in place with the single @exec/@knowledge heading-mode model, unified payload carriers and keyword control flow. - add the authoritative RFC, ADR-0052 and a historical ADR index - rewrite spec/mapping.md and spec/expression.ebnf as the normative mapping/statement grammar; update evaluation, references, math, foreign, package-format, plugin-abi, security and schema notes - rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking language change; update the architecture index/overview and active docs - mark superseded planning docs, compute RFCs, evidence and syntax-role ADRs as historical/superseded without rewriting their decisions - add migration guide, per-file inventory and dev-only audit scripts The frontend/stdlib migration is completed in the following commits; this commit contains documentation only.
158 lines
6.0 KiB
Python
158 lines
6.0 KiB
Python
#!/usr/bin/env python3
|
|
"""Review aid for the RFC-LANG-0002 migration (NOT a parser).
|
|
|
|
Checks migrated `.mq.md` files for common mistakes:
|
|
* unclosed/unmatched if/else/while/end inside an executable segment;
|
|
* `if`/`while`/`return` without an expression; `else`/`end` with trailing text;
|
|
* semicolon-separated statements in one payload;
|
|
* unknown `sem.*` codes in negative expected JSON.
|
|
|
|
It intentionally ignores Knowledge sections and does not try to be a
|
|
normative validator; the Rust frontend migration must provide the real
|
|
validation. Usage: python3 tools/dev-only/check-mq-syntax.py <dir>...
|
|
"""
|
|
from __future__ import annotations
|
|
import json
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
KNOWN_SEM = {
|
|
"sem.invalid_mode_marker", "sem.empty_unit_name", "sem.duplicate_unit_name", "sem.exec_without_function",
|
|
"sem.payload_nested", "sem.empty_payload", "sem.syntax", "sem.unmatched_else",
|
|
"sem.duplicate_else", "sem.unmatched_end", "sem.unclosed_control",
|
|
"sem.signature_position", "sem.unsupported_version_directive",
|
|
"sem.no_entry_function", "sem.inferred_signature",
|
|
}
|
|
HEADING = re.compile(r"^(#{1,6})\s+(.*)$")
|
|
MODE = re.compile(r"^@(exec|knowledge)\b\s*(.*)$")
|
|
|
|
|
|
def payload_of(line: str):
|
|
s = line.strip()
|
|
while True:
|
|
n = re.sub(r"^(?:>|[-+*]\s+|\d+[.)]\s+)", "", s).strip()
|
|
if n == s:
|
|
break
|
|
s = n
|
|
if len(s) >= 4 and s.startswith("**") and s.endswith("**") and "**" not in s[2:-2]:
|
|
return s[2:-2]
|
|
if len(s) >= 2 and s.startswith("*") and s.endswith("*") and not s.startswith("**") and "*" not in s[1:-1]:
|
|
return s[1:-1]
|
|
m = re.match(r"^(`+)(.*)\1$", s, re.S)
|
|
if m:
|
|
return m.group(2)
|
|
return None
|
|
|
|
|
|
def check(path: Path) -> list[str]:
|
|
errors: list[str] = []
|
|
stack: list[tuple[str, int]] = []
|
|
headings: list[tuple[int, str | None, int]] = [] # level, explicit mode
|
|
segment = "root"
|
|
|
|
def effective(level: int) -> str:
|
|
for hl, mode, _ln in reversed(headings):
|
|
if hl < level:
|
|
if mode:
|
|
return mode
|
|
# continue to a higher explicit ancestor
|
|
return "knowledge"
|
|
|
|
def close_segment(line: int) -> None:
|
|
nonlocal stack
|
|
if stack:
|
|
kind, op = stack[-1]
|
|
errors.append(f"{path}:{line}: unclosed {kind} from line {op} in {segment}")
|
|
stack = []
|
|
|
|
for i, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
|
|
m = HEADING.match(raw)
|
|
if m:
|
|
close_segment(i)
|
|
level, body = len(m.group(1)), m.group(2)
|
|
mm = MODE.match(body)
|
|
mode = mm.group(1) if mm else None
|
|
name = mm.group(2).strip() if mm else body.strip()
|
|
if mm and not name:
|
|
errors.append(f"{path}:{i}: mode without heading name")
|
|
if not mm and re.match(r"^@[A-Za-z]", name):
|
|
errors.append(f"{path}:{i}: unknown mode marker {name.split()[0]}")
|
|
while headings and headings[-1][0] >= level:
|
|
headings.pop()
|
|
headings.append((level, mode, i))
|
|
segment = f"H{level} {name}"
|
|
continue
|
|
text = payload_of(raw)
|
|
if text is None:
|
|
continue
|
|
text = text.strip()
|
|
if not text:
|
|
errors.append(f"{path}:{i}: empty executable payload")
|
|
continue
|
|
owning = False
|
|
for hl, _mode, _ln in reversed(headings):
|
|
if hl == 2:
|
|
owning = effective(2) == "exec"
|
|
break
|
|
if not owning:
|
|
continue
|
|
if ";" in text:
|
|
errors.append(f"{path}:{i}: semicolon in one payload: {text!r}")
|
|
first = text.split(None, 1)[0]
|
|
if first in ("if", "while"):
|
|
if len(text.split()) == 1:
|
|
errors.append(f"{path}:{i}: {first} without expression")
|
|
stack.append((first, i))
|
|
elif first == "else":
|
|
if text != "else":
|
|
errors.append(f"{path}:{i}: else with trailing tokens")
|
|
if not stack or not stack[-1][0].startswith("if"):
|
|
errors.append(f"{path}:{i}: unmatched else")
|
|
elif stack[-1][0] == "if_else":
|
|
errors.append(f"{path}:{i}: duplicate else")
|
|
else:
|
|
stack[-1] = ("if_else", stack[-1][1])
|
|
elif first == "end":
|
|
if text != "end":
|
|
errors.append(f"{path}:{i}: end with trailing tokens")
|
|
if not stack:
|
|
errors.append(f"{path}:{i}: unmatched end")
|
|
else:
|
|
stack.pop()
|
|
elif first == "return" and len(text.split()) == 1:
|
|
errors.append(f"{path}:{i}: return without expression")
|
|
elif first == "params" and not re.match(r"^params\s*\(.*\)$", text, re.S):
|
|
errors.append(f"{path}:{i}: malformed params")
|
|
close_segment(len(headings) + 1)
|
|
return errors
|
|
|
|
|
|
def main(argv: list[str]) -> int:
|
|
roots = [Path(a) for a in argv] or [Path("tests"), Path("examples")]
|
|
failures: list[str] = []
|
|
count = 0
|
|
for root in roots:
|
|
paths = [root] if root.is_file() else sorted(root.rglob("*"))
|
|
for path in paths:
|
|
if path.name.endswith(".mq.md"):
|
|
count += 1
|
|
failures.extend(check(path))
|
|
elif path.suffix == ".json" and "negative" in path.as_posix():
|
|
try:
|
|
data = json.loads(path.read_text(encoding="utf-8"))
|
|
except Exception as error: # noqa: BLE001 - review aid
|
|
failures.append(f"{path}: invalid JSON: {error}")
|
|
continue
|
|
for code in data.get("codes", []):
|
|
if code.startswith("sem.") and code not in KNOWN_SEM:
|
|
failures.append(f"{path}: unknown sem code {code}")
|
|
for failure in failures:
|
|
print(failure)
|
|
print(f"checked {count} .mq.md files, {len(failures)} issue(s)")
|
|
return 1 if failures else 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main(sys.argv[1:]))
|