lanternspec 0.1.0__py3-none-any.whl

lanternspec/check/githooks.py

@@ -0,0 +1,284 @@
+"""git hooks — 구조 실수는 막고(block), 내용 실수는 경고(warn) (C-09 · C-10 · I-03).
+
+commit-msg  H-1  작업 ID가 있나 · 할 일 여러 개를 섞었나
+pre-commit  구조  docs/.git · .gitignore · .ignore · 코드 커밋에 docs/ 섞임   (항상 막음)
+            H-2  스키마 변경에 기록이 있나
+            H-3  바뀐 문서에 lantern check
+pre-push    R6   docs-local 브랜치 push 막기 (허용한 개인 원격만 통과)
+
+Shell shims call `lantern hook git-…`; an existing non-LanternSpec hook is kept as `<name>.local`
+and still runs first.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+import sys
+from pathlib import Path
+
+from ..core.project import Project, git_out, nfc
+
+MARK = "# lanternspec hook"
+HOOKS = {"commit-msg": "git-commit-msg", "pre-commit": "git-pre-commit", "pre-push": "git-pre-push"}
+DOCS_BRANCH = "docs-local"
+ID_RE = re.compile(r"\b(?:IDEA|W|ADR|D)-\d{3,}(?:-T\d{2,})?\b")
+TASK_RE = re.compile(r"\bW-\d{3,}-T\d{2,}\b")
+SKIP_MSG = re.compile(r"^(Merge |Revert |fixup! |squash! |amend! )|\[lantern\]")
+
+SHIM = """#!/bin/sh
+{mark} — `lantern hooks uninstall`로 지운다. 고치지 말 것.
+HOOK_DIR=$(cd "$(dirname "$0")" && pwd)
+{prelude}if [ -x "$HOOK_DIR/{name}.local" ]; then
+  {local_call} || exit $?
+fi
+if command -v lantern >/dev/null 2>&1; then
+  {feed}lantern hook {handler} "$@"
+  exit $?
+elif python3 -c "import lanternspec" >/dev/null 2>&1; then
+  {feed}python3 -m lanternspec hook {handler} "$@"
+  exit $?
+fi
+echo "lanternspec: lantern 명령을 찾지 못해 검사를 건너뜁니다" >&2
+exit 0
+"""
+
+
+def hooks_dir(project: Project) -> Path:
+    custom = git_out(["config", "--get", "core.hooksPath"], project.root)
+    if custom:
+        p = Path(custom)
+        return p if p.is_absolute() else project.root / p
+    common = git_out(["rev-parse", "--path-format=absolute", "--git-common-dir"], project.root)
+    if not common:
+        raise RuntimeError("git 저장소가 아닙니다")
+    return Path(common) / "hooks"
+
+
+def _shim(name: str) -> str:
+    if name == "pre-push":  # stdin must reach both the local hook and ours
+        return SHIM.format(
+            mark=MARK,
+            name=name,
+            handler=HOOKS[name],
+            prelude="INPUT=$(cat)\n",
+            local_call=f'printf "%s\\n" "$INPUT" | "$HOOK_DIR/{name}.local" "$@"',
+            feed='printf "%s\\n" "$INPUT" | ',
+        )
+    return SHIM.format(mark=MARK, name=name, handler=HOOKS[name], prelude="", local_call=f'"$HOOK_DIR/{name}.local" "$@"', feed="")
+
+
+def install(project: Project) -> list[str]:
+    d = hooks_dir(project)
+    d.mkdir(parents=True, exist_ok=True)
+    msgs = []
+    for name in HOOKS:
+        p = d / name
+        if p.exists() and MARK not in p.read_text(encoding="utf-8", errors="replace"):
+            local = d / f"{name}.local"
+            if not local.exists():
+                p.rename(local)
+                msgs.append(f"• 기존 {name} hook을 {name}.local로 보존 (먼저 실행됨)")
+        p.write_text(_shim(name), encoding="utf-8")
+        p.chmod(p.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    msgs.append(f"✔ git hook 설치: {', '.join(HOOKS)} ({d})")
+    return msgs
+
+
+def uninstall(project: Project) -> list[str]:
+    d = hooks_dir(project)
+    msgs = []
+    for name in HOOKS:
+        p = d / name
+        if p.exists() and MARK in p.read_text(encoding="utf-8", errors="replace"):
+            p.unlink()
+            local = d / f"{name}.local"
+            if local.exists():
+                local.rename(p)
+                msgs.append(f"• {name}.local을 원래 이름으로 되돌림")
+            msgs.append(f"✔ {name} 제거")
+    return msgs or ["설치된 LanternSpec hook이 없습니다"]
+
+
+def status(project: Project) -> list[tuple[str, bool]]:
+    try:
+        d = hooks_dir(project)
+    except RuntimeError:
+        return [(n, False) for n in HOOKS]
+    return [(n, (d / n).exists() and MARK in (d / n).read_text(encoding="utf-8", errors="replace")) for n in HOOKS]
+
+
+# --------------------------------------------------------------------------- handlers
+
+
+def _skip() -> bool:
+    return os.environ.get("LANTERN_SKIP_HOOKS") == "1"
+
+
+def _mode(project: Project) -> str:
+    return str(project.profile.get("git.hooks") or "warn")
+
+
+def _say(lines: list[str]) -> None:
+    for line in lines:
+        print(line, file=sys.stderr)
+
+
+def _toplevel() -> Path:
+    return Path(git_out(["rev-parse", "--show-toplevel"], Path.cwd()) or Path.cwd())
+
+
+def _branch(cwd: Path) -> str:
+    b = git_out(["symbolic-ref", "--short", "-q", "HEAD"], cwd)
+    return b or git_out(["rev-parse", "--abbrev-ref", "HEAD"], cwd)
+
+
+def _staged(cwd: Path) -> list[str]:
+    out = git_out(["diff", "--cached", "--name-only", "--diff-filter=ACMRD"], cwd)
+    return [nfc(x) for x in out.splitlines() if x.strip()]
+
+
+def _content_result(project: Project, problems: list[str], label: str) -> int:
+    if not problems:
+        return 0
+    block = _mode(project) == "block"
+    _say([f"{'✖' if block else '⚠'} LanternSpec {label}"] + [f"   {p}" for p in problems])
+    if block:
+        _say(["   (git.hooks: block — 고친 뒤 다시 커밋. 급하면 git commit --no-verify)"])
+        return 1
+    _say(["   (경고만 — 커밋은 진행됩니다. 막으려면 lantern.yaml git.hooks: block)"])
+    return 0
+
+
+def commit_msg(project: Project, msg_file: str) -> int:
+    if _skip():
+        return 0
+    text = Path(msg_file).read_text(encoding="utf-8", errors="replace")
+    msg = "\n".join(l for l in text.split("\n") if not l.startswith("#")).strip()
+    if not msg or SKIP_MSG.search(msg):
+        return 0
+    top = _toplevel()
+    branch = _branch(top)
+    docs_branch = branch == DOCS_BRANCH
+    staged = _staged(top)
+    from ..report.scan import is_doc_path
+
+    code = staged if docs_branch else [f for f in staged if not is_doc_path(project, f)]
+    problems: list[str] = []
+    if code and not ID_RE.search(msg):
+        where = "문서 브랜치" if docs_branch else "코드 커밋"
+        problems.append(f"H-1 {where} 메시지에 작업 ID가 없습니다 — 끝에 [W-012-T03] 처럼 붙이세요")
+    tasks = sorted(set(TASK_RE.findall(msg)))
+    if len(tasks) > 1:
+        problems.append(f"H-1 할 일 여러 개가 한 커밋에 섞였습니다 ({', '.join(tasks)}) — 할 일 하나 = 커밋 하나 (BU-01)")
+    return _content_result(project, problems, "커밋 메시지 검사")
+
+
+def structure_problems(project: Project, cwd: Path | None = None, staged: list[str] | None = None) -> list[str]:
+    """C-10 rules. Always blocking. Also used by `lantern doctor`."""
+    cwd = cwd or project.root
+    branch = _branch(cwd)
+    docs = project.docs
+    pattern = project.profile.docs_root.rstrip("/") + "/"
+    gi = project.root / ".gitignore"
+    ig = project.root / ".ignore"
+    gi_has = gi.exists() and any(
+        l.strip() in (pattern, "/" + pattern, pattern.rstrip("/")) for l in gi.read_text(encoding="utf-8").split("\n")
+    )
+    ig_has = ig.exists() and any(l.strip() in ("!" + pattern, "!/" + pattern) for l in ig.read_text(encoding="utf-8").split("\n"))
+    out: list[str] = []
+    if project.profile.remote == "shared":
+        if (docs / ".git").exists():
+            out.append("docs/ 안에 .git이 있습니다 (shared 방식에서는 없어야 함) — lantern doctor")
+        if gi_has:
+            out.append(".gitignore가 docs/를 무시합니다 (shared 방식이면 지워야 함)")
+    else:
+        g = docs / ".git"
+        if g.is_dir():
+            out.append("docs/.git이 폴더입니다 — docs-local 브랜치를 가리키는 표지판 파일이어야 합니다 (lantern docs-mode)")
+        elif not g.exists():
+            out.append("docs/가 docs-local worktree가 아닙니다 — lantern docs-mode local 로 만드세요")
+        if not gi_has:
+            out.append(".gitignore에 docs/가 없습니다 (R1)")
+        if not ig_has:
+            out.append(".ignore에 !docs/가 없습니다 — AI 검색이 문서를 못 찾습니다 (R2)")
+        if branch != DOCS_BRANCH and staged is not None:
+            mixed = [f for f in staged if f.startswith(pattern)]
+            if mixed:
+                out.append(f"코드 커밋에 docs/ 파일이 섞였습니다: {', '.join(mixed[:3])} — 문서는 docs-local에 따로 커밋")
+    return out
+
+
+def pre_commit(project: Project) -> int:
+    if _skip():
+        return 0
+    top = _toplevel()
+    branch = _branch(top)
+    staged = _staged(top)
+    docs_branch = branch == DOCS_BRANCH
+    structural = structure_problems(project, cwd=top, staged=staged)
+    if structural:
+        _say(["✖ LanternSpec 구조 검사 — 커밋을 막았습니다 (구조 실수는 항상 막음)"] + [f"   {p}" for p in structural])
+        return 1
+    problems: list[str] = []
+    # H-2 schema change without a record
+    from ..report.scan import is_doc_path, schema_files
+
+    if not docs_branch:
+        sfiles = schema_files(project, staged)
+        if sfiles:
+            if project.profile.remote == "shared":
+                recorded = any(nfc(f).endswith("기록.md") for f in staged)
+            else:
+                docs_status = git_out(["status", "--porcelain"], project.docs) if project.docs.exists() else ""
+                recent = git_out(["log", "--since=1.day", "--name-only", "--format="], project.docs) if project.docs.exists() else ""
+                recorded = "기록.md" in nfc(docs_status) or "기록.md" in nfc(recent)
+            if not recorded:
+                problems.append(
+                    f"H-2 스키마 파일이 바뀌었는데 기록.md 변경이 없습니다: {', '.join(sfiles[:3])}"
+                    " — 작업 기록.md '## 스키마 변경'에 남기세요"
+                )
+    # H-3 lantern check on the documents in this commit
+    from . import check_docs
+
+    if docs_branch:
+        doc_paths = [top / f for f in staged if f.endswith(".md")]
+    else:
+        doc_paths = [
+            project.root / f
+            for f in staged
+            if f.endswith(".md") and is_doc_path(project, f) and f.startswith(project.profile.docs_root.rstrip("/") + "/")
+        ]
+    doc_paths = [p for p in doc_paths if p.exists()]
+    if doc_paths:
+        rep = check_docs.run(project, doc_paths)
+        bad = [f for f in rep.findings if f.level == "error"]
+        warn = [f for f in rep.findings if f.level == "warn"]
+        for f in bad:
+            problems.append(f"H-3 {f.path}: {f.message}")
+        if warn and not bad:
+            _say([f"⚠ LanternSpec H-3 참고: {f.path}: {f.message}" for f in warn[:5]])
+    return _content_result(project, problems, "커밋 전 검사")
+
+
+def pre_push(project: Project, remote: str, url: str, stdin_text: str) -> int:
+    if _skip():
+        return 0
+    allowed = git_out(["config", "--get-all", "lantern.allowDocsRemote"], project.root).split()
+    for line in stdin_text.splitlines():
+        parts = line.split()
+        if len(parts) < 4:
+            continue
+        local_ref, remote_ref = parts[0], parts[2]
+        if f"refs/heads/{DOCS_BRANCH}" in (local_ref, remote_ref):
+            if remote in allowed:
+                return 0
+            _say(
+                [
+                    f"✖ LanternSpec: {DOCS_BRANCH} 브랜치는 원격({remote})에 올리지 않습니다 (docs.remote: local)",
+                    f"   개인 원격을 허용하려면: git config --add lantern.allowDocsRemote {remote}",
+                ]
+            )
+            return 1
+    return 0

lanternspec/check/legacy.py

@@ -0,0 +1,116 @@
+"""브라운필드 기존 문서 (I-02): 원본은 `5. 기존 문서/`에 그대로, 지도와 TODO 후보는 스크립트가."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+from ..core.profile import FOLDERS, MOC_FILE
+from ..core.project import Project, git, git_out, nfc, read, write
+
+TODO_RE = re.compile(r"(TODO|FIXME|나중에|추후|언젠가|해야 할|할 것|아이디어|개선 필요|- \[ \])", re.I)
+
+
+def _ours(project: Project) -> set:
+    tops = {nfc(v.split("/")[0]) for v in FOLDERS.values()}
+    return tops | {nfc(MOC_FILE), ".git", ".obsidian"}
+
+
+def _move(project: Project, src: Path, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tracked = bool(git_out(["ls-files", "--", str(src)], project.root))
+    if tracked:
+        r = git(["mv", str(src), str(dest)], project.root)
+        if r.returncode == 0:
+            return
+    shutil.move(str(src), str(dest))
+
+
+def adopt(project: Project, source: Path | None = None) -> list[str]:
+    """Move existing documents into docs/5. 기존 문서/ (git mv keeps their history)."""
+    legacy = project.folder("legacy")
+    moved: list[str] = []
+    if source is None:
+        if not project.docs.exists():
+            return []
+        ours = _ours(project)
+        for item in sorted(project.docs.iterdir()):
+            if nfc(item.name) in ours or item.name.startswith("."):
+                continue
+            dest = legacy / item.name
+            _move(project, item, dest)
+            moved.append(project.rel(dest))
+    else:
+        src = source if source.is_absolute() else project.root / source
+        if not src.exists():
+            raise FileNotFoundError(f"없습니다: {source}")
+        dest = legacy / src.name
+        _move(project, src, dest)
+        moved.append(project.rel(dest))
+    legacy.mkdir(parents=True, exist_ok=True)
+    add_map_rows(project)
+    return moved
+
+
+def legacy_files(project: Project) -> list[Path]:
+    legacy = project.folder("legacy")
+    if not legacy.exists():
+        return []
+    return sorted(
+        p
+        for p in legacy.rglob("*")
+        if p.is_file() and nfc(p.name) != "기존 문서 지도.md" and not any(x.startswith(".") for x in p.relative_to(legacy).parts)
+    )
+
+
+def map_rows(project: Project, files: list[Path]) -> str:
+    rows = []
+    for p in files:
+        rel = project.docs_rel(p)
+        target = rel[:-3] if rel.endswith(".md") else rel
+        rows.append(
+            f"| [[{target}\\|{nfc(p.stem)}]] | {{{{무슨 내용}}}} | {{{{아직 맞나}}}} | {{{{흡수 · 보관 · 옮기기}}}} | {{{{새 위치}}}} |"
+        )
+    return "\n".join(rows) or "| {{문서}} | {{무슨 내용}} | {{아직 맞나}} | {{흡수 · 보관 · 옮기기}} | {{새 위치}} |"
+
+
+def add_map_rows(project: Project) -> Path | None:
+    """Add a row for every legacy file the map does not mention yet."""
+    m = project.folder("legacy") / "기존 문서 지도.md"
+    if not m.exists():
+        return None
+    text = read(m)
+    missing = [p for p in legacy_files(project) if project.docs_rel(p).rsplit(".", 1)[0] not in text]
+    if not missing:
+        return m
+    rows = map_rows(project, missing)
+    lines = text.split("\n")
+    # drop the template's blank example row once real rows exist
+    lines = [l for l in lines if l.strip() != "| {{문서}} | {{무슨 내용}} | {{아직 맞나}} | {{흡수 · 보관 · 옮기기}} | {{새 위치}} |"]
+    try:
+        start = next(i for i, l in enumerate(lines) if l.strip() == "## 문서")
+    except StopIteration:
+        write(m, text.rstrip() + "\n\n## 문서\n| 문서 | 무슨 내용 | 아직 맞나 | 갈래 | 새 위치 |\n|---|---|---|---|---|\n" + rows + "\n")
+        return m
+    last = start
+    for i in range(start + 1, len(lines)):
+        if lines[i].startswith("|"):
+            last = i
+        elif lines[i].startswith("## "):
+            break
+    lines[last + 1 : last + 1] = rows.split("\n")
+    write(m, "\n".join(lines))
+    return m
+
+
+def todos(project: Project) -> list[dict[str, str]]:
+    out = []
+    for p in legacy_files(project):
+        if p.suffix.lower() not in (".md", ".txt", ".markdown"):
+            continue
+        for i, line in enumerate(read(p).split("\n"), start=1):
+            s = line.strip()
+            if s and TODO_RE.search(s) and not s.startswith("- [x]"):
+                out.append({"file": project.docs_rel(p), "line": str(i), "text": s[:160]})
+    return out