заведён канон общих конвенций для личных проектов
- 13 конвенций по осям arch / lang / stack / common; репозитории берут оттуда копии в свой docs/conventions/ и коммитят их у себя - conv — синхронизация копий: add / status / diff / pull / push, локальные регионы исключены из сравнения, поэтому расхождение не даёт шума
This commit is contained in:
@@ -0,0 +1,515 @@
|
||||
#!/usr/bin/env python3
|
||||
"""conv — синхронизация конвенций между каноном и репозиторием.
|
||||
|
||||
Канон — эта директория. Репозиторий держит закоммиченные копии нужных
|
||||
конвенций в docs/conventions/, повторяя структуру канона. Копия — источник
|
||||
правды для репозитория; канон — лавка, из которой берут.
|
||||
|
||||
Служебная разметка копии:
|
||||
|
||||
---
|
||||
origin: arch/time.md # откуда взято
|
||||
origin_hash: a1b2c3d4 # отпечаток канона на момент синхронизации
|
||||
synced: 2026-07-25
|
||||
local: нет # или текст: чем и почему разошлись
|
||||
---
|
||||
|
||||
Прочие ключи шапки (status, extends) — часть документа: они сравниваются
|
||||
наравне с телом и приезжают из канона.
|
||||
|
||||
Локальные регионы — куски, которые по определению принадлежат репозиторию
|
||||
(механизация, отступления, «здесь решили так»). Из сравнения исключаются:
|
||||
|
||||
<!-- local:механизировано -->
|
||||
...
|
||||
<!-- /local -->
|
||||
|
||||
Имя региона обязательно: перенос при pull идёт по именам.
|
||||
|
||||
Команды:
|
||||
conv list что есть в каноне
|
||||
conv add arch/time.md [...] взять конвенцию в репозиторий
|
||||
conv status состояние копий репозитория
|
||||
conv diff [arch/time.md] чем копия отличается от канона
|
||||
conv pull arch/time.md забрать обновление канона
|
||||
conv push arch/time.md вернуть локальное улучшение в канон
|
||||
conv push --new lang/go/x.md завести в каноне новую конвенцию
|
||||
|
||||
Везде можно указать --repo <path> (по умолчанию — текущая директория)
|
||||
и --dir <subpath> (по умолчанию docs/conventions), до или после команды.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime
|
||||
import difflib
|
||||
import hashlib
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import NoReturn
|
||||
|
||||
CANON = Path(__file__).resolve().parent
|
||||
CANON_TREES = ("common", "arch", "lang", "stack")
|
||||
SERVICE_KEYS = ("origin", "origin_hash", "synced", "local")
|
||||
DEFAULT_DIR = "docs/conventions"
|
||||
ENC = "utf-8"
|
||||
|
||||
# Маркеры распознаются только в начале строки: так пример разметки внутри
|
||||
# текста конвенции не превращается в настоящий регион.
|
||||
REGION_RE = re.compile(
|
||||
r"^<!--[ \t]*local(?::[ \t]*([^>]*?))?[ \t]*-->(.*?)^<!--[ \t]*/local[ \t]*-->",
|
||||
re.DOTALL | re.MULTILINE,
|
||||
)
|
||||
OPEN_RE = re.compile(r"^<!--[ \t]*local", re.MULTILINE)
|
||||
CLOSE_RE = re.compile(r"^<!--[ \t]*/local", re.MULTILINE)
|
||||
|
||||
|
||||
def die(message: str) -> NoReturn:
|
||||
print(f"conv: {message}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
# --- разметка --------------------------------------------------------------
|
||||
|
||||
|
||||
def read(path: Path) -> str:
|
||||
return path.read_text(encoding=ENC)
|
||||
|
||||
|
||||
def write(path: Path, text: str) -> None:
|
||||
path.write_text(text, encoding=ENC)
|
||||
|
||||
|
||||
def split_front(text: str) -> tuple[dict[str, str], str]:
|
||||
"""Отделяет YAML-шапку (плоский key: value) от тела."""
|
||||
if not text.startswith("---\n"):
|
||||
return {}, text
|
||||
end = text.find("\n---\n", 4)
|
||||
if end == -1:
|
||||
return {}, text
|
||||
meta: dict[str, str] = {}
|
||||
for line in text[4:end].splitlines():
|
||||
if ":" in line:
|
||||
key, value = line.split(":", 1)
|
||||
meta[key.strip()] = value.strip()
|
||||
return meta, text[end + 5 :]
|
||||
|
||||
|
||||
def join_front(meta: dict[str, str], body: str) -> str:
|
||||
if not meta:
|
||||
return body
|
||||
lines = "\n".join(f"{k}:{' ' + v if v else ''}" for k, v in meta.items())
|
||||
return f"---\n{lines}\n---\n{body}"
|
||||
|
||||
|
||||
def doc_keys(meta: dict[str, str]) -> dict[str, str]:
|
||||
return {k: v for k, v in meta.items() if k not in SERVICE_KEYS}
|
||||
|
||||
|
||||
def regions(body: str) -> dict[str, str]:
|
||||
"""Содержимое локальных регионов по имени.
|
||||
|
||||
Поднимает ValueError на разметке, из-за которой регион молча превратился
|
||||
бы в обычный текст и потерялся при pull.
|
||||
"""
|
||||
matched = len(REGION_RE.findall(body))
|
||||
if len(OPEN_RE.findall(body)) != matched or len(CLOSE_RE.findall(body)) != matched:
|
||||
raise ValueError("непарный или нераспознанный маркер локального региона")
|
||||
found: dict[str, str] = {}
|
||||
for match in REGION_RE.finditer(body):
|
||||
name = (match.group(1) or "").strip()
|
||||
content = match.group(2)
|
||||
if not name:
|
||||
if content.strip():
|
||||
raise ValueError(
|
||||
"безымянный локальный регион с содержимым — дай ему имя"
|
||||
)
|
||||
continue
|
||||
if name in found:
|
||||
raise ValueError(f"локальный регион '{name}' встречается дважды")
|
||||
found[name] = content
|
||||
return found
|
||||
|
||||
|
||||
def checked_regions(body: str, where: str) -> dict[str, str]:
|
||||
try:
|
||||
return regions(body)
|
||||
except ValueError as exc:
|
||||
die(f"{where}: {exc}")
|
||||
|
||||
|
||||
def blank_regions(body: str) -> str:
|
||||
"""Тело с опустошёнными локальными регионами — то, что сравнивается."""
|
||||
|
||||
def repl(match: re.Match[str]) -> str:
|
||||
raw = (match.group(1) or "").strip()
|
||||
head = f"<!-- local:{raw} -->" if raw else "<!-- local -->"
|
||||
return f"{head}\n<!-- /local -->"
|
||||
|
||||
return REGION_RE.sub(repl, body)
|
||||
|
||||
|
||||
def fill_regions(body: str, values: dict[str, str]) -> tuple[str, list[str]]:
|
||||
"""Вставляет содержимое регионов по имени. Возвращает тело и имена,
|
||||
которым не нашлось места."""
|
||||
used: set[str] = set()
|
||||
|
||||
def repl(match: re.Match[str]) -> str:
|
||||
raw = (match.group(1) or "").strip()
|
||||
head = f"<!-- local:{raw} -->" if raw else "<!-- local -->"
|
||||
if raw in values:
|
||||
used.add(raw)
|
||||
return f"{head}{values[raw]}<!-- /local -->"
|
||||
return match.group(0)
|
||||
|
||||
filled = REGION_RE.sub(repl, body)
|
||||
lost = [n for n, v in values.items() if n not in used and v.strip()]
|
||||
return filled, lost
|
||||
|
||||
|
||||
def fingerprint(meta: dict[str, str], body: str) -> str:
|
||||
"""Отпечаток документа: ключи шапки плюс тело без локальных регионов."""
|
||||
head = "\n".join(f"{k}={v}" for k, v in sorted(doc_keys(meta).items()))
|
||||
return hashlib.sha256(f"{head}\n\n{blank_regions(body)}".encode(ENC)).hexdigest()[
|
||||
:8
|
||||
]
|
||||
|
||||
|
||||
def today() -> str:
|
||||
return datetime.date.today().isoformat()
|
||||
|
||||
|
||||
# --- канон и репозиторий ---------------------------------------------------
|
||||
|
||||
|
||||
def canon_list() -> list[str]:
|
||||
out: list[str] = []
|
||||
for tree in CANON_TREES:
|
||||
root = CANON / tree
|
||||
if root.is_dir():
|
||||
out += [str(p.relative_to(CANON)) for p in sorted(root.rglob("*.md"))]
|
||||
return out
|
||||
|
||||
|
||||
def canon_read(origin: str) -> tuple[dict[str, str], str]:
|
||||
path = CANON / origin
|
||||
if not path.is_file():
|
||||
die(f"в каноне нет {origin}")
|
||||
return split_front(read(path))
|
||||
|
||||
|
||||
def normalize_origin(name: str, *, must_exist: bool = True) -> str:
|
||||
"""Принимает 'arch/time.md', 'arch/time' и однозначный хвост вроде 'time'."""
|
||||
name = name.strip("/")
|
||||
if not name.endswith(".md"):
|
||||
name += ".md"
|
||||
candidate = (CANON / name).resolve()
|
||||
if candidate.is_relative_to(CANON):
|
||||
rel = str(candidate.relative_to(CANON))
|
||||
if rel.split("/")[0] in CANON_TREES and (not must_exist or candidate.is_file()):
|
||||
return rel
|
||||
matches = [c for c in canon_list() if c == name or c.endswith("/" + name)]
|
||||
if len(matches) == 1:
|
||||
return matches[0]
|
||||
if not matches:
|
||||
die(f"в каноне нет {name} (путь должен начинаться с {'/'.join(CANON_TREES)})")
|
||||
die(f"неоднозначно: {name} → {', '.join(matches)}")
|
||||
|
||||
|
||||
def repo_dir(args: argparse.Namespace) -> Path:
|
||||
return (Path(str(args.repo)) / str(args.dir)).resolve()
|
||||
|
||||
|
||||
def repo_copies(base: Path) -> tuple[dict[str, Path], list[Path], list[str]]:
|
||||
"""origin → копия; плюс .md без шапки и сообщения о нечитаемых файлах."""
|
||||
found: dict[str, Path] = {}
|
||||
untracked: list[Path] = []
|
||||
problems: list[str] = []
|
||||
if not base.is_dir():
|
||||
return found, untracked, problems
|
||||
for path in sorted(base.rglob("*.md")):
|
||||
try:
|
||||
meta, _ = split_front(read(path))
|
||||
except (OSError, UnicodeDecodeError) as exc:
|
||||
problems.append(f"{path.name}: не читается ({type(exc).__name__})")
|
||||
continue
|
||||
origin = meta.get("origin")
|
||||
if not origin:
|
||||
if path.name != "README.md":
|
||||
untracked.append(path)
|
||||
continue
|
||||
if origin in found:
|
||||
problems.append(
|
||||
f"{origin}: две копии ({found[origin]}, {path}) — вторая скрыта"
|
||||
)
|
||||
continue
|
||||
found[origin] = path
|
||||
return found, untracked, problems
|
||||
|
||||
|
||||
def locate(args: argparse.Namespace, origin: str) -> Path:
|
||||
"""Путь копии: по шапке, если она лежит не по канонному пути."""
|
||||
base = repo_dir(args)
|
||||
copies, _, _ = repo_copies(base)
|
||||
return copies.get(origin, base / origin)
|
||||
|
||||
|
||||
# --- состояние -------------------------------------------------------------
|
||||
|
||||
|
||||
def state(
|
||||
meta: dict[str, str], body: str, canon_meta: dict[str, str], canon_body: str
|
||||
) -> str:
|
||||
copy_fp = fingerprint(meta, body)
|
||||
canon_fp = fingerprint(canon_meta, canon_body)
|
||||
if copy_fp == canon_fp:
|
||||
return "ok"
|
||||
base = meta.get("origin_hash")
|
||||
if not base:
|
||||
return "нет origin_hash в шапке"
|
||||
if base == canon_fp:
|
||||
return "изменено локально"
|
||||
if base == copy_fp:
|
||||
return "канон обновился"
|
||||
return "разошлись"
|
||||
|
||||
|
||||
# --- команды ---------------------------------------------------------------
|
||||
|
||||
|
||||
def cmd_list(args: argparse.Namespace) -> int:
|
||||
for origin in canon_list():
|
||||
meta, _ = canon_read(origin)
|
||||
marks = []
|
||||
if "extends" in meta:
|
||||
marks.append(f"расширяет {meta['extends']}")
|
||||
if "status" in meta:
|
||||
marks.append(meta["status"])
|
||||
tail = f" ({'; '.join(marks)})" if marks else ""
|
||||
print(f"{origin}{tail}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_add(args: argparse.Namespace) -> int:
|
||||
base = repo_dir(args)
|
||||
added = False
|
||||
for raw in args.names:
|
||||
origin = normalize_origin(raw)
|
||||
target = base / origin
|
||||
if target.exists():
|
||||
print(f"{origin}: уже есть ({target}), пропускаю")
|
||||
continue
|
||||
canon_meta, canon_body = canon_read(origin)
|
||||
checked_regions(canon_body, f"канон/{origin}")
|
||||
meta: dict[str, str] = {
|
||||
"origin": origin,
|
||||
"origin_hash": fingerprint(canon_meta, canon_body),
|
||||
"synced": today(),
|
||||
"local": "нет",
|
||||
}
|
||||
meta.update(doc_keys(canon_meta))
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
write(target, join_front(meta, canon_body))
|
||||
added = True
|
||||
print(f"{origin} → {target}")
|
||||
if "extends" in canon_meta:
|
||||
print(f" расширяет {canon_meta['extends']} — возможно, нужна и она")
|
||||
if added:
|
||||
print("не забудь строку в docs/conventions/README.md")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_status(args: argparse.Namespace) -> int:
|
||||
base = repo_dir(args)
|
||||
copies, untracked, problems = repo_copies(base)
|
||||
if not copies and not untracked and not problems:
|
||||
print(f"в {base} нет копий конвенций")
|
||||
return 0
|
||||
width = max((len(o) for o in copies), default=0)
|
||||
for origin, path in copies.items():
|
||||
try:
|
||||
meta, body = split_front(read(path))
|
||||
except (OSError, UnicodeDecodeError) as exc:
|
||||
print(f"{origin:<{width}} не читается ({type(exc).__name__})")
|
||||
continue
|
||||
if not (CANON / origin).is_file():
|
||||
print(f"{origin:<{width}} нет в каноне")
|
||||
continue
|
||||
canon_meta, canon_body = canon_read(origin)
|
||||
try:
|
||||
regions(body)
|
||||
except ValueError as exc:
|
||||
print(f"{origin:<{width}} разметка: {exc}")
|
||||
continue
|
||||
local = meta.get("local", "нет")
|
||||
note = "" if local == "нет" else f" [{local}]"
|
||||
print(f"{origin:<{width}} {state(meta, body, canon_meta, canon_body)}{note}")
|
||||
for path in untracked:
|
||||
print(f"{path.name}: без шапки origin — не отслеживается")
|
||||
for problem in problems:
|
||||
print(problem)
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_diff(args: argparse.Namespace) -> int:
|
||||
base = repo_dir(args)
|
||||
copies, _, _ = repo_copies(base)
|
||||
targets = [normalize_origin(args.name)] if args.name else list(copies)
|
||||
for origin in targets:
|
||||
path = copies.get(origin)
|
||||
if path is None:
|
||||
print(f"{origin}: нет копии в репозитории")
|
||||
continue
|
||||
if not (CANON / origin).is_file():
|
||||
print(f"{origin}: нет в каноне")
|
||||
continue
|
||||
meta, body = split_front(read(path))
|
||||
canon_meta, canon_body = canon_read(origin)
|
||||
if fingerprint(meta, body) == fingerprint(canon_meta, canon_body):
|
||||
continue
|
||||
sys.stdout.writelines(
|
||||
difflib.unified_diff(
|
||||
join_front(doc_keys(canon_meta), blank_regions(canon_body)).splitlines(
|
||||
keepends=True
|
||||
),
|
||||
join_front(doc_keys(meta), blank_regions(body)).splitlines(
|
||||
keepends=True
|
||||
),
|
||||
fromfile=f"канон/{origin}",
|
||||
tofile=f"репо/{origin}",
|
||||
)
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_pull(args: argparse.Namespace) -> int:
|
||||
origin = normalize_origin(args.name)
|
||||
path = locate(args, origin)
|
||||
if not path.is_file():
|
||||
die(f"нет копии {origin} — сначала conv add {origin}")
|
||||
meta, body = split_front(read(path))
|
||||
canon_meta, canon_body = canon_read(origin)
|
||||
checked_regions(canon_body, f"канон/{origin}")
|
||||
local = checked_regions(body, f"репо/{origin}")
|
||||
st = state(meta, body, canon_meta, canon_body)
|
||||
if st == "ok":
|
||||
fresh = fingerprint(canon_meta, canon_body)
|
||||
if meta.get("origin_hash") != fresh:
|
||||
meta["origin_hash"] = fresh
|
||||
meta["synced"] = today()
|
||||
write(path, join_front(meta, body))
|
||||
print(f"{origin}: тексты совпадают, отпечаток освежён")
|
||||
else:
|
||||
print(f"{origin}: уже совпадает")
|
||||
return 0
|
||||
if st in ("изменено локально", "разошлись") and not args.force:
|
||||
die(
|
||||
f"{origin}: {st} — правки вне локальных регионов будут потеряны.\n"
|
||||
f" посмотри conv diff {origin}, затем conv pull --force "
|
||||
f"или conv push {origin}"
|
||||
)
|
||||
merged, lost = fill_regions(canon_body, local)
|
||||
if lost and not args.force:
|
||||
die(
|
||||
f"{origin}: в каноне нет регионов {', '.join(lost)} — их содержимое "
|
||||
f"пропадёт.\n перенеси вручную или conv pull --force"
|
||||
)
|
||||
for name in lost:
|
||||
print(f" потерян локальный регион {name}")
|
||||
new_meta = {k: meta[k] for k in SERVICE_KEYS if k in meta}
|
||||
new_meta["origin_hash"] = fingerprint(canon_meta, canon_body)
|
||||
new_meta["synced"] = today()
|
||||
new_meta.update(doc_keys(canon_meta))
|
||||
write(path, join_front(new_meta, merged))
|
||||
print(f"{origin}: обновлено из канона — перечитай глазами, регионы могли устареть")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_push(args: argparse.Namespace) -> int:
|
||||
origin = normalize_origin(args.name, must_exist=not args.new)
|
||||
path = locate(args, origin)
|
||||
if not path.is_file():
|
||||
die(f"нет копии {origin}")
|
||||
meta, body = split_front(read(path))
|
||||
checked_regions(body, f"репо/{origin}")
|
||||
target = CANON / origin
|
||||
if not target.is_file():
|
||||
if not args.new:
|
||||
die(f"в каноне нет {origin} — заведи новую конвенцию через conv push --new")
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
write(target, join_front(doc_keys(meta), blank_regions(body)))
|
||||
meta["origin_hash"] = fingerprint(doc_keys(meta), blank_regions(body))
|
||||
meta["synced"] = today()
|
||||
write(path, join_front(meta, body))
|
||||
print(f"{origin}: заведена в каноне")
|
||||
return 0
|
||||
canon_meta, canon_body = canon_read(origin)
|
||||
st = state(meta, body, canon_meta, canon_body)
|
||||
if st == "ok":
|
||||
print(f"{origin}: канон уже такой")
|
||||
return 0
|
||||
if st == "канон обновился":
|
||||
die(
|
||||
f"{origin}: копия не менялась, а канон ушёл вперёд — пушить нечего, нужен pull"
|
||||
)
|
||||
if st == "разошлись" and not args.force:
|
||||
die(
|
||||
f"{origin}: разошлись — канон менялся после синхронизации, "
|
||||
f"его правки затрутся.\n посмотри conv diff {origin}, "
|
||||
f"затем conv push --force"
|
||||
)
|
||||
write(target, join_front(doc_keys(meta), blank_regions(body)))
|
||||
meta["origin_hash"] = fingerprint(doc_keys(meta), blank_regions(body))
|
||||
meta["synced"] = today()
|
||||
write(path, join_front(meta, body))
|
||||
print(f"{origin}: канон обновлён из репозитория")
|
||||
return 0
|
||||
|
||||
|
||||
def main() -> int:
|
||||
common = argparse.ArgumentParser(add_help=False)
|
||||
common.add_argument("--repo", default=".", help="корень репозитория")
|
||||
common.add_argument("--dir", default=DEFAULT_DIR, help="где лежат конвенции")
|
||||
|
||||
parser = argparse.ArgumentParser(prog="conv", parents=[common], description=__doc__)
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
|
||||
sub.add_parser("list", parents=[common], help="что есть в каноне").set_defaults(
|
||||
fn=cmd_list
|
||||
)
|
||||
|
||||
p_add = sub.add_parser(
|
||||
"add", parents=[common], help="взять конвенцию в репозиторий"
|
||||
)
|
||||
p_add.add_argument("names", nargs="+")
|
||||
p_add.set_defaults(fn=cmd_add)
|
||||
|
||||
sub.add_parser("status", parents=[common], help="состояние копий").set_defaults(
|
||||
fn=cmd_status
|
||||
)
|
||||
|
||||
p_diff = sub.add_parser(
|
||||
"diff", parents=[common], help="чем копия отличается от канона"
|
||||
)
|
||||
p_diff.add_argument("name", nargs="?")
|
||||
p_diff.set_defaults(fn=cmd_diff)
|
||||
|
||||
p_pull = sub.add_parser("pull", parents=[common], help="забрать обновление канона")
|
||||
p_pull.add_argument("name")
|
||||
p_pull.add_argument("--force", action="store_true")
|
||||
p_pull.set_defaults(fn=cmd_pull)
|
||||
|
||||
p_push = sub.add_parser("push", parents=[common], help="вернуть улучшение в канон")
|
||||
p_push.add_argument("name")
|
||||
p_push.add_argument("--force", action="store_true")
|
||||
p_push.add_argument("--new", action="store_true", help="завести новый файл канона")
|
||||
p_push.set_defaults(fn=cmd_push)
|
||||
|
||||
args = parser.parse_args()
|
||||
return int(args.fn(args))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in New Issue
Block a user