Orkuncakilkaya
42f955fd22
game/module -> program, main -> entry, component -> property, archetype -> model, system -> handler. Done via a transitional self-hosting bootstrap: parser accepts both -> reseed -> compiler source moved to new keywords + parser tightened to new-only -> reseed (fixpoint holds). Old keywords now rejected. Token-safe corpus migration (tools/ludic-tools/rename_kw.c) leaves the LLVM @main/entry: labels in emit strings untouched; goldens byte-identical. Editor vocab (header/JetBrains/TextMate/emacs), check-docs wrapper, and doc fences updated; error string 'unknown component' -> 'unknown property'. test.sh 14/14, test-tools 28/0, check-vocabulary green. (Doc prose pass to follow.) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
78 lines
3.4 KiB
Python
Executable file
78 lines
3.4 KiB
Python
Executable file
#!/usr/bin/env python3
|
|
"""check-docs.py — every ```ludic fence in the docs is checked against the
|
|
compiler, so documentation cannot drift away from the language.
|
|
|
|
A fence declares its own intent with an in-fence comment (`#` is a Ludic
|
|
comment, so the marker is valid code and visible to a reader):
|
|
|
|
# doc-check: skip illustrative or pseudo-syntax; not checked
|
|
# doc-check: expect-error must FAIL to compile (error demonstrations)
|
|
|
|
Anything else must PARSE. The gate is `ludicc --fmt`, not a full build: it runs
|
|
lex + parse, which is what catches syntax drift, but does not resolve
|
|
identifiers — so an excerpt may reference components and registers that live in
|
|
the surrounding program it was lifted from, and still be checked.
|
|
|
|
A bare fragment is wrapped first: a declaration list goes inside
|
|
`game DocCheck { ... }`, loose statements inside a Start system.
|
|
"""
|
|
import re, subprocess, sys, os, tempfile
|
|
|
|
LC = './build/ludicc'
|
|
DECL = ('program','property','model','handler','enum','fn',
|
|
'extern','const','var','ui','struct','import')
|
|
|
|
def classify(body):
|
|
first = next((l.strip() for l in body.split('\n')
|
|
if l.strip() and not l.strip().startswith('#')), '')
|
|
head = first.split('(')[0].split()[0] if first else ''
|
|
if head == 'program': return 'whole'
|
|
return 'decls' if head in DECL else 'stmts'
|
|
|
|
def wraps(body, kind):
|
|
"""Candidate framings, best guess first. An excerpt often mixes declarations
|
|
with loose statements, so both are tried and either parsing counts."""
|
|
if kind == 'whole': return [body]
|
|
as_decls = 'program DocCheck {\n' + body + '\n}\n'
|
|
as_stmts = 'program DocCheck {\n handler DocS phase Start {\n' + body + '\n }\n}\n'
|
|
return [as_decls, as_stmts] if kind == 'decls' else [as_stmts, as_decls]
|
|
|
|
def fences(path):
|
|
t = open(path).read()
|
|
for m in re.finditer(r'^```ludic\n(.*?)^```', t, re.S | re.M):
|
|
yield t[:m.start()].count('\n') + 1, m.group(1)
|
|
|
|
def main(argv):
|
|
report = '--report' in argv
|
|
docs = [p for p in argv if p.endswith('.md')]
|
|
ok = bad = skipped = 0
|
|
failures = []
|
|
for path in docs:
|
|
for line, body in fences(path):
|
|
if '# doc-check: skip' in body:
|
|
skipped += 1; continue
|
|
expect_error = '# doc-check: expect-error' in body
|
|
kind = classify(body)
|
|
parsed, first_err = False, None
|
|
for src in wraps(body, kind):
|
|
with tempfile.NamedTemporaryFile('w', suffix='.ludic', delete=False) as f:
|
|
f.write(src); tmp = f.name
|
|
# bytes, not text: a diagnostic may echo a partial multibyte char
|
|
r = subprocess.run([LC, tmp, '--fmt'], capture_output=True)
|
|
os.unlink(tmp)
|
|
if r.returncode == 0: parsed = True; break
|
|
# keep the best-guess framing's error; later ones are fallbacks
|
|
if first_err is None: first_err = r.stderr
|
|
if parsed != (not expect_error):
|
|
bad += 1
|
|
want = 'be rejected' if expect_error else 'parse'
|
|
err = (first_err or b'').decode('utf-8','replace').strip().split('\n')[0]
|
|
failures.append(f"{path}:{line} expected to {want}: {err[:90]}")
|
|
else:
|
|
ok += 1
|
|
print(f" doc fences: {ok} as documented, {bad} drifted, {skipped} skipped")
|
|
for f in failures: print(f" {f}")
|
|
if report: return 0
|
|
return 1 if bad else 0
|
|
|
|
sys.exit(main(sys.argv[1:]))
|