av
b411d4edb8
Слияние ничего из идей не тронуло, но сделало дешёвым дом для правила, натянутого между скиллами. Заведён shared/axes.md — дом перечня, а не значений: девять осей, их адреса и чего каждая не решает. Механика остаётся у владельца. Целиком сюда переехали две оси, у которых владельца не было. Коды выхода объявлялись общим словарём в одиннадцати местах, и каждое объявление называло свой набор соседей; машина их не сверяла, потому что copies.py смотрит markdown, а перечни лежали в docstring'ах. Теперь дом один, скрипты держат указатель, а три SKILL.md — помеченную копию, потому что на кодах они ветвятся. Режим прогона (с меткой, без метки) был размазан по четырём файлам и осью назван не был, хотя в уставе review-basics задаёт саму возможность запуска. Разведены два значения слова «стадия»: ступени 1-5 внутри прогона кода, стадии дизайна и кода снаружи. Карта нашла ошибку в себе: клетка «категория документа × метка» пустой не была — review-basics приёмник проектных тем при любой метке. Пустой оказалась соседняя: на прогоне без метки план фиксирован, и своих тем проекта в нём нет вовсе. Обе оставшиеся пустоты названы вслух, а не заполнены наугад.
235 lines
12 KiB
Python
235 lines
12 KiB
Python
#!/usr/bin/env python3
|
||
"""Проверка mermaid-диаграмм в markdown этого репозитория.
|
||
|
||
Диаграммы заведены там, где структура — граф или автомат: порядок проходов
|
||
ревью, жизненный цикл записи по индексам, исходы задачи в спринте, храповик
|
||
промоута, счётчик калибровки, граф вызовов между скиллами.
|
||
|
||
Проверка нужна по одной причине: **синтаксическая ошибка в блоке не видна при
|
||
чтении**. Текст диаграммы выглядит правдоподобно, `git diff` показывает разумную
|
||
строку, ревью её пропускает — а отрендерить не удаётся, и читатель видит вместо
|
||
схемы полотно исходника либо сообщение об ошибке. Первый раз это ловилось тем,
|
||
что автор не забыл прогнать рендер руками; на «не забыл» проверки не строятся.
|
||
|
||
Чего проверка **не** ловит: расхождение диаграммы с прозой вокруг неё. Это
|
||
второй дом для одного факта, и удержать его в синхроне может только правило
|
||
старшинства, записанное рядом с каждой диаграммой (в конвейере ревью старший —
|
||
граф, он и есть алгоритм; в остальных местах старшая — проза, диаграмма там
|
||
сводка). Механической сверки для этого нет: между текстом и графом нет
|
||
дословного соответствия, которое можно было бы сличить, — в отличие от копий
|
||
правил, где оно есть и где его сверяет copies.py.
|
||
|
||
Рендерит `mermaid-cli`: бинарь `mmdc`, если он на PATH, иначе
|
||
`npx --yes @mermaid-js/mermaid-cli`. Ни того ни другого нет — это код 3, а не
|
||
молчаливый успех: проверка, отчитавшаяся «диаграммы в порядке», ничего не
|
||
отрендерив, хуже отсутствующей.
|
||
|
||
Chromium запускается с `--no-sandbox`: на современных дистрибутивах
|
||
непривилегированные user namespaces выключены, и без флага рендер падает на
|
||
«No usable sandbox». Содержимое здесь своё и локальное, так что песочница ничего
|
||
не защищает — она только мешает запуску.
|
||
|
||
Дорого здесь не чтение markdown, а рендер: каждый блок — отдельный запуск
|
||
mermaid-cli со своим chromium, секунда с лишним. Отсюда два рычага, и оба нужны
|
||
гейту коммита:
|
||
|
||
- **блоки собираются все сразу, а рендерятся параллельно.** Сбор — обход файлов,
|
||
он же и определяет порядок вывода; рендер ждёт подпроцесс и потому пускается
|
||
пулом потоков. Порядок находок от этого не плывёт: он берётся из порядка
|
||
сбора, а не из порядка ответов;
|
||
- **проверять можно не весь репозиторий, а названные файлы.** `diagrams.py
|
||
путь.md …` смотрит только их — так гейт платит за диаграммы ровно того файла,
|
||
который правят. Без аргументов обходится весь репозиторий, как и раньше.
|
||
|
||
Коды выхода — общий словарь скриптов av-dev; дом словаря и разбор «дрейф
|
||
против окружения» — av-dev/shared/axes.md. Значения — в константах ниже.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import json
|
||
import os
|
||
import re
|
||
import shutil
|
||
import subprocess
|
||
import sys
|
||
import tempfile
|
||
from concurrent.futures import ThreadPoolExecutor
|
||
from pathlib import Path
|
||
|
||
OK, DRIFT, USAGE, ENV, INTERNAL = 0, 1, 2, 3, 4
|
||
|
||
# Потолок параллели. Каждый рендер — свой chromium, а он стоит сотни мегабайт:
|
||
# на машине с 24 ядрами упереться в память дешевле, чем в процессор. Восемь
|
||
# снимают почти весь выигрыш и не рискуют ничем.
|
||
MAX_WORKERS = 8
|
||
|
||
FENCE_OPEN = re.compile(r"^\s*```mermaid\s*$")
|
||
FENCE_CLOSE = re.compile(r"^\s*```\s*$")
|
||
|
||
# Каталоги, где markdown не наш: клоны, окружения, временное.
|
||
SKIP = {".git", ".venv", "node_modules", "tmp", ".ruff_cache"}
|
||
|
||
# Стек вызовов puppeteer/mermaid полезного не несёт — режем по первой его строке.
|
||
NOISE = re.compile(r"^(Parser\.|\s+at )")
|
||
# Строки хода работы: не ошибка, а прогресс рендера.
|
||
PROGRESS = re.compile(r"^(Generating|Found \d+ mermaid)")
|
||
|
||
|
||
class Block:
|
||
"""Один блок ```mermaid: где начался и что внутри."""
|
||
|
||
def __init__(self, path: Path, line: int, text: str, root: Path) -> None:
|
||
self.path = path
|
||
self.line = line
|
||
self.text = text
|
||
self.where = f"{path.relative_to(root).as_posix()}:{line}"
|
||
|
||
|
||
def markdown(root: Path, named: list[Path]) -> list[Path]:
|
||
"""Какие файлы смотреть: названные или весь репозиторий.
|
||
|
||
Названные фильтруются теми же правилами, что и обход: только `*.md`, только
|
||
внутри корня, без пропускаемых каталогов. Гейт передаёт сюда staged-файлы
|
||
списком, в котором есть и скрипты, и удалённое, — отбор его дело, а не
|
||
вызывающего.
|
||
"""
|
||
if not named:
|
||
return sorted(root.rglob("*.md"))
|
||
out = []
|
||
for path in named:
|
||
full = (path if path.is_absolute() else root / path).resolve()
|
||
if full.suffix == ".md" and full.is_file() and full.is_relative_to(root):
|
||
out.append(full)
|
||
return sorted(set(out))
|
||
|
||
|
||
def collect(root: Path, named: list[Path]) -> list[Block]:
|
||
"""Все mermaid-блоки, в порядке обхода. Порядок вывода берётся отсюда."""
|
||
found: list[Block] = []
|
||
for path in markdown(root, named):
|
||
if any(part in SKIP for part in path.relative_to(root).parts):
|
||
continue
|
||
lines = path.read_text(encoding="utf-8").splitlines()
|
||
start: int | None = None
|
||
body: list[str] = []
|
||
for i, line in enumerate(lines, start=1):
|
||
if start is None:
|
||
if FENCE_OPEN.match(line):
|
||
start, body = i, []
|
||
continue
|
||
if FENCE_CLOSE.match(line):
|
||
found.append(Block(path, start, "\n".join(body) + "\n", root))
|
||
start = None
|
||
continue
|
||
body.append(line)
|
||
if start is not None:
|
||
found.append(Block(path, start, "\n".join(body) + "\n", root))
|
||
return found
|
||
|
||
|
||
def renderer() -> list[str] | None:
|
||
"""Команда рендера или None, если mermaid-cli недоступен."""
|
||
mmdc = shutil.which("mmdc")
|
||
if mmdc:
|
||
return [mmdc]
|
||
if shutil.which("npx"):
|
||
return ["npx", "--yes", "@mermaid-js/mermaid-cli"]
|
||
return None
|
||
|
||
|
||
def render(cmd: list[str], block: Block, workdir: Path, config: Path,
|
||
slot: int) -> str | None:
|
||
"""Отрендерить блок. None — получилось, иначе сообщение об ошибке.
|
||
|
||
`slot` разводит временные файлы: рендеры идут параллельно, и одно имя на
|
||
всех означало бы, что блоки затирают исходники друг друга — с находками,
|
||
которые не воспроизводятся поодиночке.
|
||
"""
|
||
src = workdir / f"d{slot}.mmd"
|
||
src.write_text(block.text, encoding="utf-8")
|
||
out = workdir / f"d{slot}.svg"
|
||
done = subprocess.run(
|
||
[*cmd, "-p", str(config), "-i", str(src), "-o", str(out)],
|
||
capture_output=True,
|
||
text=True,
|
||
check=False,
|
||
)
|
||
if done.returncode == 0 and out.exists():
|
||
out.unlink()
|
||
return None
|
||
noise = f"{done.stdout}\n{done.stderr}"
|
||
useful = []
|
||
for line in noise.splitlines():
|
||
if NOISE.match(line):
|
||
break
|
||
if line.strip() and not PROGRESS.match(line.strip()):
|
||
useful.append(line.strip())
|
||
return "\n ".join(useful[:8]) or f"код {done.returncode} без сообщения"
|
||
|
||
|
||
def main() -> int:
|
||
ap = argparse.ArgumentParser(description="Проверка mermaid-диаграмм.")
|
||
ap.add_argument("paths", nargs="*", type=Path,
|
||
help="какие файлы смотреть; без них — весь репозиторий")
|
||
ap.add_argument("--dir", default=".", help="корень репозитория")
|
||
args = ap.parse_args()
|
||
|
||
root = Path(args.dir).resolve()
|
||
if not (root / ".claude-plugin").is_dir():
|
||
print(f"окружение: {root} не похож на корень репозитория"
|
||
f" (нет .claude-plugin)", file=sys.stderr)
|
||
return ENV
|
||
|
||
blocks = collect(root, args.paths)
|
||
if not blocks:
|
||
print("диаграмм нет" if not args.paths
|
||
else "диаграмм нет в названных файлах")
|
||
return OK
|
||
|
||
cmd = renderer()
|
||
if cmd is None:
|
||
print("окружение: нет ни mmdc, ни npx — рендер невозможен."
|
||
" Поставь mermaid-cli (npm i -g @mermaid-js/mermaid-cli)"
|
||
" или запусти проверку там, где есть npx.", file=sys.stderr)
|
||
return ENV
|
||
|
||
with tempfile.TemporaryDirectory(prefix="diagrams-") as tmp:
|
||
workdir = Path(tmp)
|
||
config = workdir / "puppeteer.json"
|
||
config.write_text(json.dumps({"args": ["--no-sandbox"]}), encoding="utf-8")
|
||
workers = max(1, min(MAX_WORKERS, len(blocks), os.cpu_count() or 1))
|
||
with ThreadPoolExecutor(max_workers=workers) as pool:
|
||
# Потоки, а не процессы: работа целиком в ожидании подпроцесса,
|
||
# своего интерпретатора ей не надо. `map` сохраняет порядок блоков,
|
||
# поэтому вывод не зависит от того, кто ответил первым.
|
||
errors = list(pool.map(
|
||
lambda pair: render(cmd, pair[1], workdir, config, pair[0]),
|
||
enumerate(blocks)))
|
||
broken = [(b, e) for b, e in zip(blocks, errors, strict=True) if e is not None]
|
||
|
||
files = len({b.path for b in blocks})
|
||
print(f"диаграмм {len(blocks)} в {files} файлах")
|
||
if broken:
|
||
print()
|
||
for block, error in broken:
|
||
print(f"НЕ РЕНДЕРИТСЯ {block.where}\n {error}")
|
||
print(f"\nИтог: не рендерятся {len(broken)}."
|
||
f" Блок правится в самом markdown — картинок в репозитории нет"
|
||
f" и не заводится, диаграмма живёт исходником рядом с текстом.")
|
||
return DRIFT
|
||
|
||
print("все рендерятся")
|
||
return OK
|
||
|
||
|
||
if __name__ == "__main__":
|
||
try:
|
||
sys.exit(main())
|
||
except KeyboardInterrupt:
|
||
sys.exit(INTERNAL)
|
||
except Exception as e: # noqa: BLE001 — последний рубеж, код 4 по словарю
|
||
print(f"внутренний сбой ({type(e).__name__}): {e}", file=sys.stderr)
|
||
sys.exit(INTERNAL)
|