donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: 가상화 문서들 추가

Browse Source
This commit is contained in:
DongHyeonka
2026-09-10 08:54:05 +09:00
parent e9f6a93327
commit 43e1aadef0
695 changed files with 153404 additions and 12754 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/verify-project-layout.py
+96 -26
View File
@@ -10,8 +10,7 @@ CLAUDE.md 「문서 위치」가 같은 것을 말로 적은 것이다.
├── analysis/ · notes/ · checkpoints/
├── final/ SSOT
│ ├── document.md
│ ├── assets/<이름>/ 그림 하나가 폴더 하나
│ ├── assets/tech-log-studio/ Studio 에 올릴 표현물
│ ├── assets/<이름>/ 그림 하나가 폴더 하나. 기록의 assets: file: 도 여기를 가리킨다
│ ├── .techviz/<이름>/ 그림의 정본
│ └── evidence/{raw,meta,rendered,browser}
└── tech-log-studio/
@@ -25,6 +24,8 @@ from __future__ import annotations
import argparse
import glob
import hashlib
import importlib.util
import json
import os
import re
@@ -41,19 +42,49 @@ EVIDENCE_DIRS = {"raw", "meta", "rendered", "browser"}
WORKING_MATERIAL = ("analysis", "notes", "checkpoints", "state.json", "source-index.md")
# 밖에서 가져올 때만 있는 재료. final/ 이 그 내용을 담으면 원본은 사본이 된다
IMPORT_MATERIAL = "source"
# Studio 에 올릴 표현물이 사는 곳. 여기 SVG 는 그림의 정본을 따로 갖지 않는다
STUDIO_ASSETS = "tech-log-studio"
def _svg_stems(assets: str) -> list[tuple[str, str]]:
"""(stem, 상대경로). assets/tech-log-studio/ 아래는 표현물이라 뺀다."""
out = []
for path in sorted(glob.glob(os.path.join(assets, "**", "*.svg"), recursive=True)):
rel = os.path.relpath(path, assets)
if rel.split(os.sep)[0] == STUDIO_ASSETS:
continue
out.append((os.path.basename(path)[:-4], rel))
return out
"""(stem, 상대경로). 그림은 한 곳에만 산다 — 사본을 두는 폴더를 따로 두지 않는다."""
return [(os.path.basename(path)[:-4], os.path.relpath(path, assets))
for path in sorted(glob.glob(os.path.join(assets, "**", "*.svg"), recursive=True))]
def _load_overlap():
"""`check-figure-overlap.py` 의 검사 함수. 없으면 None."""
path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
"check-figure-overlap.py")
if not os.path.exists(path):
return None
spec = importlib.util.spec_from_file_location("check_figure_overlap", path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module.check
def _context_sha(path: str) -> str | None:
"""`techviz prepare` 가 context 에 적는 것과 같은 해시.
**원본 바이트가 아니다.** prepare 는 문서의 관리 블록(`techviz:begin … end`)을 접은
정규화본을 해싱한다. 원본으로 비교하면 관리 블록이 있는 프로젝트는 그림을 방금 다시
만들어도 영영 「SSOT 가 바뀌었다」로 남는다. 도구가 없으면 대조하지 않는다.
"""
try:
raw = open(path, encoding="utf-8").read()
except OSError:
return None
home = os.environ.get("TECHVIZ_HOME",
"/home/donghyeon/workspace/ai-tool/technical-visualization-haness")
src = os.path.join(home, "src")
if not os.path.isdir(os.path.join(src, "techviz")):
return None
if src not in sys.path:
sys.path.insert(0, src)
try:
from techviz.document import canonicalize_document # noqa: PLC0415
except ImportError:
return None
return hashlib.sha256(canonicalize_document(raw).encode("utf-8")).hexdigest()
def verify(project: str) -> Report:
@@ -119,24 +150,64 @@ def verify(project: str) -> Report:
f"raw {counts['raw']}건 — command·cwd·executedAt·exitCode·revision 이 없다")
# ── 그림 ───────────────────────────────────────────────────────
ssot_sha = _context_sha(os.path.join(final, "document.md"))
assets = os.path.join(final, "assets")
techviz = os.path.join(final, ".techviz")
# 정본은 그림 이름 폴더다. .techviz 에 놓인 파일은 정본이 아니다
techviz_sources = {n for n in os.listdir(techviz)
if os.path.isdir(os.path.join(techviz, n))} \
if os.path.isdir(techviz) else set()
if os.path.isdir(assets):
# 정본은 그림 이름 폴더다. .techviz 에 놓인 파일은 정본이 아니다
sources = {n for n in os.listdir(techviz)
if os.path.isdir(os.path.join(techviz, n))} \
if os.path.isdir(techviz) else set()
sources = techviz_sources
svgs = _svg_stems(assets)
rep.facts["diagrams"] = {"svg": len(svgs), "techviz": len(sources)}
overlap = _load_overlap()
for stem, rel in svgs:
if stem not in sources:
rep.warn("techviz 정본이 없는 그림", f"final/assets/{rel}")
# lint 는 좌표를 안 본다. 상자와 라벨이 서로를 덮는 것은 여기서만 걸린다
if overlap is not None:
for hit in overlap(os.path.join(assets, rel)):
rep.error("그림 안에서 상자와 라벨이 겹친다", f"final/assets/{rel} — {hit}")
if os.path.dirname(rel) in ("", "diagrams"):
rep.warn("그림이 이름 폴더로 묶여 있지 않다", f"final/assets/{rel}")
stems = {s for s, _ in svgs}
for name in sorted(sources - stems):
rep.warn("정본만 있고 그림이 없다", f"final/.techviz/{name}")
# 관계선이 없고 항목마다 같은 수의 details 를 늘어놓았으면 그것은 표다.
# 표는 값을 비교하고 그림은 포함·순서·경계처럼 자리로만 보이는 것을 맡는다
for name in sorted(sources):
spec_path = os.path.join(techviz, name, "spec.json")
if not os.path.exists(spec_path):
continue
try:
spec = json.load(open(spec_path, encoding="utf-8"))
except (ValueError, OSError):
continue
# 그림의 근거는 SSOT 다. 기록은 SSOT 의 인용이라 줄 번호가 근거가 되지 못하는데,
# techviz prepare 는 기록 .md 를 받아도 에러 없이 돈다. 여기서 잡는다
ctx = spec.get("source_context") or {}
doc = os.path.basename(str(ctx.get("document") or ""))
if doc and doc != "document.md":
rep.error("그림의 근거가 SSOT 가 아니다",
f"final/.techviz/{name} — source_context.document = {doc}")
elif ssot_sha and ctx.get("document_sha256") and \
ctx["document_sha256"] != ssot_sha:
rep.warn("SSOT 가 바뀐 뒤 그림을 다시 보지 않았다",
f"final/.techviz/{name}")
elif ssot_sha is None and ctx.get("document_sha256"):
rep.warn("그림이 어느 SSOT 를 보고 만들어졌는지 대조하지 못했다",
f"final/.techviz/{name} — techviz 도구가 없다")
nodes = spec.get("nodes") or []
if spec.get("edges") or len(nodes) < 2:
continue
counts = [len(n.get("details") or []) for n in nodes]
if all(counts) and len(set(counts)) == 1:
rep.warn("표로 되는 그림", f"final/.techviz/{name} — 관계선이 없고 "
f"{len(nodes)}항목이 같은 {counts[0]}줄을 늘어놓는다")
# ── 기록이 가리키는 그림 ───────────────────────────────────────
if os.path.isdir(studio):
wrong = 0
@@ -151,24 +222,23 @@ def verify(project: str) -> Report:
text = open(path, encoding="utf-8").read()
for m in re.finditer(r"^ file: (\S+)$", text, re.M):
target = os.path.normpath(os.path.join(os.path.dirname(path), m.group(1)))
# 이름이 같으면 같은 그림이다. tech-log-studio/ 사본도 SSOT 원본을 쓴 것으로 센다
cited_figures.add(os.path.basename(target)[:-4]
if target.endswith(".svg") else os.path.basename(target))
stem = (os.path.basename(target)[:-4] if target.endswith(".svg")
else os.path.basename(target))
cited_figures.add(stem)
if not os.path.exists(target):
broken += 1
if broken <= 5:
rep.error("기록이 가리키는 그림이 없다",
f"{os.path.relpath(path, base)} — {m.group(1)}")
continue
if f"assets{os.sep}{STUDIO_ASSETS}{os.sep}" not in target:
# 기록이 가리키는 그림도 다시 만들 수 있어야 한다. 사본을 따로 두면 정본이 둘이 된다
if stem not in techviz_sources:
wrong += 1
rep.warn("기록이 가리키는 그림에 techviz 정본이 없다",
f"{os.path.relpath(path, base)} — {os.path.basename(target)}")
for m in re.finditer(r"^ - (\.\./\S*final/evidence/\S+)$", text, re.M):
cited_evidence.add(
os.path.normpath(os.path.join(os.path.dirname(path), m.group(1))))
if wrong:
rep.warn("Studio 자산이 assets/tech-log-studio/ 밖에 있다",
f"{wrong}건 — 다른 프로젝트는 전부 그 폴더를 쓴다")
# ── SSOT 가 만들어 둔 것을 기록이 쓰고 있나 ────────────────────
# 기록이 하나도 없는 프로젝트는 아직 안 쓴 것이지 안 쓰기로 한 것이 아니다
if records: