451 lines
22 KiB
Python
451 lines
22 KiB
Python
#!/usr/bin/env python3
|
|
"""Validate compatibility, shadow, and canonical project-first vault layouts."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import hashlib
|
|
import json
|
|
import os
|
|
from pathlib import Path
|
|
import re
|
|
import sys
|
|
from typing import Any, Iterable, Mapping
|
|
|
|
from contract_markdown import parse_frontmatter
|
|
|
|
|
|
DEFAULT_ROOT = Path(__file__).resolve().parents[2]
|
|
DEFAULT_MANIFEST = Path("harness/source/vault-layout.json")
|
|
CONTENT_ROOTS = ("raw", "wiki")
|
|
MODES = {"compatibility", "shadow", "canonical"}
|
|
HEX_SHA256 = re.compile(r"^[0-9a-f]{64}$")
|
|
WIKILINK = re.compile(r"\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]")
|
|
FENCE = re.compile(r"^[ \t]{0,3}(`{3,}|~{3,})")
|
|
INLINE_CODE = re.compile(r"(`+)(.*?)\1")
|
|
|
|
|
|
class LayoutContractError(ValueError):
|
|
def __init__(self, code: str, message: str, location: str = "") -> None:
|
|
self.code = code
|
|
self.location = location
|
|
super().__init__(message)
|
|
|
|
|
|
def _finding(code: str, path: str, detail: str = "") -> dict[str, str]:
|
|
item = {"code": code, "path": path}
|
|
if detail:
|
|
item["detail"] = detail
|
|
return item
|
|
|
|
|
|
def _lexical_absolute(path: Path) -> Path:
|
|
"""Return an absolute repository path without following redirects."""
|
|
|
|
return Path(os.path.abspath(path))
|
|
|
|
|
|
def _load_embedded_or_path(root: Path, value: Any, expected_schema: str, findings: list[dict[str, str]], location: str) -> Mapping[str, Any] | None:
|
|
document = value
|
|
if isinstance(value, str):
|
|
candidate = (root / value).resolve()
|
|
try:
|
|
candidate.relative_to(root)
|
|
document = json.loads(candidate.read_text(encoding="utf-8"))
|
|
except (ValueError, OSError, UnicodeError, json.JSONDecodeError) as exc:
|
|
findings.append(_finding("CUTOVER_SOURCE_ERROR", value, str(exc)))
|
|
return None
|
|
if not isinstance(document, dict) or document.get("schema_version") != expected_schema:
|
|
findings.append(_finding("INVALID_CUTOVER_SCHEMA", location, f"expected {expected_schema}"))
|
|
return None
|
|
return document
|
|
|
|
|
|
def _safe_repo_path(root: Path, value: Any, findings: list[dict[str, str]], location: str) -> Path | None:
|
|
if not isinstance(value, str) or not value or "\\" in value or Path(value).is_absolute():
|
|
findings.append(_finding("INVALID_MIGRATION_PATH", location, str(value)))
|
|
return None
|
|
resolved = _lexical_absolute(root / value)
|
|
try:
|
|
resolved.relative_to(root)
|
|
except ValueError:
|
|
findings.append(_finding("INVALID_MIGRATION_PATH", location, str(value)))
|
|
return None
|
|
if resolved.is_symlink():
|
|
try:
|
|
resolved.resolve().relative_to(root)
|
|
except ValueError:
|
|
findings.append(_finding("INVALID_MIGRATION_PATH", location, "symlink target escapes repository"))
|
|
return None
|
|
return resolved
|
|
|
|
|
|
def _content_files(root: Path, assignments: Mapping[str, str]) -> set[Path]:
|
|
files: set[Path] = set()
|
|
for source in assignments:
|
|
base = root / source
|
|
if base.is_dir():
|
|
files.update(
|
|
path for path in base.rglob("*")
|
|
if path.is_file() and path.name != ".gitkeep"
|
|
)
|
|
return files
|
|
|
|
|
|
def _migration_entries(
|
|
root: Path,
|
|
manifest: Mapping[str, Any],
|
|
findings: list[dict[str, str]],
|
|
) -> tuple[dict[Path, tuple[Path, str]], dict[Path, Path]]:
|
|
entries = manifest.get("entries")
|
|
if not isinstance(entries, list):
|
|
findings.append(_finding("INVALID_CUTOVER_SCHEMA", "migration_manifest.entries", "must be an array"))
|
|
return {}, {}
|
|
by_legacy: dict[Path, tuple[Path, str]] = {}
|
|
by_canonical: dict[Path, Path] = {}
|
|
for index, item in enumerate(entries):
|
|
location = f"migration_manifest.entries[{index}]"
|
|
if not isinstance(item, dict) or set(item) != {"legacy_path", "canonical_path", "sha256"}:
|
|
findings.append(_finding("INVALID_MIGRATION_ENTRY", location))
|
|
continue
|
|
legacy = _safe_repo_path(root, item.get("legacy_path"), findings, f"{location}.legacy_path")
|
|
canonical = _safe_repo_path(root, item.get("canonical_path"), findings, f"{location}.canonical_path")
|
|
digest = item.get("sha256")
|
|
if not isinstance(digest, str) or not HEX_SHA256.fullmatch(digest):
|
|
findings.append(_finding("INVALID_MIGRATION_HASH", location, str(digest)))
|
|
continue
|
|
if legacy is None or canonical is None:
|
|
continue
|
|
if legacy in by_legacy:
|
|
findings.append(_finding("DUPLICATE_LEGACY_OWNER", legacy.relative_to(root).as_posix()))
|
|
if canonical in by_canonical:
|
|
findings.append(_finding("DUPLICATE_CANONICAL_OWNER", canonical.relative_to(root).as_posix()))
|
|
by_legacy[legacy] = (canonical, digest)
|
|
by_canonical[canonical] = legacy
|
|
return by_legacy, by_canonical
|
|
|
|
|
|
def _validate_links(
|
|
root: Path,
|
|
files: Iterable[Path],
|
|
findings: list[dict[str, str]],
|
|
*,
|
|
namespace: Iterable[Path] | None = None,
|
|
) -> None:
|
|
namespace_items = list(namespace if namespace is not None else root.rglob("*"))
|
|
all_files = [path for path in namespace_items if path.is_file() and ".git" not in path.parts]
|
|
namespace_paths = {path.resolve() for path in all_files}
|
|
by_basename: dict[str, list[Path]] = {}
|
|
by_name: dict[str, list[Path]] = {}
|
|
for path in all_files:
|
|
by_basename.setdefault(path.stem, []).append(path)
|
|
by_name.setdefault(path.name, []).append(path)
|
|
for source in sorted(path for path in set(files) if path.suffix == ".md"):
|
|
lines: list[str] = []
|
|
fence_char = ""
|
|
fence_length = 0
|
|
for line in source.read_text(encoding="utf-8").splitlines():
|
|
if fence_char:
|
|
if re.fullmatch(rf"[ \t]{{0,3}}{re.escape(fence_char)}{{{fence_length},}}[ \t]*", line):
|
|
fence_char, fence_length = "", 0
|
|
continue
|
|
match = FENCE.match(line)
|
|
if match:
|
|
token = match.group(1)
|
|
if not fence_char:
|
|
fence_char, fence_length = token[0], len(token)
|
|
continue
|
|
lines.append(INLINE_CODE.sub("", line))
|
|
text = "\n".join(lines).replace(r"\|", "|")
|
|
for target_value in WIKILINK.findall(text):
|
|
target = target_value.strip()
|
|
if not target:
|
|
continue
|
|
if "/" not in target:
|
|
matches = (
|
|
by_name.get(Path(target).name, [])
|
|
if Path(target).suffix
|
|
else by_basename.get(Path(target).stem, [])
|
|
)
|
|
if not matches:
|
|
findings.append(_finding("BROKEN_LINK", source.relative_to(root).as_posix(), target))
|
|
elif len(matches) > 1:
|
|
findings.append(_finding("AMBIGUOUS_BASENAME_LINK", source.relative_to(root).as_posix(), target))
|
|
continue
|
|
candidate = root / target
|
|
if not candidate.is_file():
|
|
markdown_candidate = Path(str(candidate) + ".md")
|
|
if markdown_candidate.is_file():
|
|
candidate = markdown_candidate
|
|
if not candidate.is_file():
|
|
findings.append(_finding("BROKEN_LINK", source.relative_to(root).as_posix(), target))
|
|
elif namespace is not None and candidate.resolve() not in namespace_paths:
|
|
# STALE_AUTHORITY_LINK 은 "권한 밖 사본을 가리키는 링크"를 잡는다. shadow 모드
|
|
# (namespace=legacy|external)에서 canonical(vault/) 경로를 *미리* 가리키면 발화한다.
|
|
# canonical 모드(namespace=canonical|external)에서는 [[raw/…]]·[[wiki/…]] 레거시
|
|
# 경로가 호환 심링크를 통해 canonical 로 resolve() 되므로 여기 걸리지 않는다 —
|
|
# 이는 의도된 것이다(raw/·wiki/ 는 영구 호환 별칭). 회귀 방지:
|
|
# test_vault_migrate.test_canonical_symlink_preserves_escaped_alias_wikilink_without_stale_authority.
|
|
findings.append(_finding("STALE_AUTHORITY_LINK", source.relative_to(root).as_posix(), target))
|
|
|
|
|
|
def _validate_cutover(
|
|
root: Path,
|
|
mode: str,
|
|
vault_root: Path,
|
|
assignments: Mapping[str, str],
|
|
manifest: Mapping[str, Any],
|
|
findings: list[dict[str, str]],
|
|
) -> dict[str, int]:
|
|
migration = _load_embedded_or_path(root, manifest.get("migration_manifest"), "vault-migration/v1", findings, "migration_manifest")
|
|
rollback = _load_embedded_or_path(root, manifest.get("rollback_mapping"), "vault-rollback/v1", findings, "rollback_mapping")
|
|
if migration is None or rollback is None:
|
|
return {"migration_entries": 0, "canonical_files": 0}
|
|
by_legacy, by_canonical = _migration_entries(root, migration, findings)
|
|
legacy_files = _content_files(root, assignments)
|
|
canonical_files = {
|
|
path for path in vault_root.rglob("*")
|
|
if path.is_file() and path.name != ".gitkeep" and path != vault_root / "README.md"
|
|
}
|
|
if set(by_legacy) != legacy_files:
|
|
for path in sorted(legacy_files - set(by_legacy)):
|
|
findings.append(_finding("MIGRATION_ENTRY_MISSING", path.relative_to(root).as_posix()))
|
|
for path in sorted(set(by_legacy) - legacy_files):
|
|
findings.append(_finding("MIGRATION_LEGACY_EXTRA", path.relative_to(root).as_posix()))
|
|
if set(by_canonical) != canonical_files:
|
|
for path in sorted(canonical_files - set(by_canonical)):
|
|
findings.append(_finding("CANONICAL_OWNER_MISSING", path.relative_to(root).as_posix()))
|
|
for path in sorted(set(by_canonical) - canonical_files):
|
|
findings.append(_finding("MIGRATION_CANONICAL_MISSING", path.relative_to(root).as_posix()))
|
|
|
|
for legacy, (canonical, expected_hash) in sorted(by_legacy.items()):
|
|
if not canonical.is_file():
|
|
continue
|
|
if mode == "shadow":
|
|
# cutover 검증 단계에서만 콘텐츠 해시를 대조한다. 이 단계의 목적은
|
|
# "이관이 내용을 그대로 옮겼는가"를 증명하는 것이다.
|
|
observed_hash = hashlib.sha256(canonical.read_bytes()).hexdigest()
|
|
if observed_hash != expected_hash:
|
|
findings.append(_finding("MIGRATION_HASH_MISMATCH", canonical.relative_to(root).as_posix(), f"expected {expected_hash}, observed {observed_hash}"))
|
|
# canonical 모드에서는 문서가 계속 편집되는 것이 정상이므로 해시를 고정하지 않는다.
|
|
# 이 모드에서 manifest 는 legacy→canonical 매핑과 rollback 근거로만 쓰인다
|
|
# (매핑 완전성은 위 MIGRATION_ENTRY_MISSING / CANONICAL_OWNER_MISSING 이 검사한다).
|
|
#
|
|
# shadow 불변식: legacy·canonical 은 서로 *독립된 실파일* 바이트 동일 미러다.
|
|
# 둘 중 하나라도 심링크면 is_file()/read_bytes() 가 상대를 따라가 항상 '동일'로
|
|
# 읽혀 drift 를 못 잡는다(symlink-blind). 그래서 심링크를 먼저 loud 하게 잡는다.
|
|
if legacy.is_symlink() or canonical.is_symlink():
|
|
findings.append(_finding(
|
|
"SHADOW_MIRROR_SYMLINK", legacy.relative_to(root).as_posix(),
|
|
"shadow 미러는 독립 실파일이어야 함 — 심링크는 byte-identical 검사를 무력화한다"))
|
|
elif not legacy.is_file():
|
|
findings.append(_finding("SHADOW_SOURCE_MISSING", legacy.relative_to(root).as_posix()))
|
|
elif legacy.read_bytes() != canonical.read_bytes():
|
|
findings.append(_finding("SHADOW_MIRROR_DRIFT", canonical.relative_to(root).as_posix()))
|
|
elif mode == "canonical" and legacy.is_symlink():
|
|
expected_target = canonical.resolve()
|
|
observed_target = legacy.resolve()
|
|
if observed_target != expected_target:
|
|
findings.append(
|
|
_finding(
|
|
"INVALID_COMPATIBILITY_SYMLINK",
|
|
legacy.relative_to(root).as_posix(),
|
|
f"expected target {canonical.relative_to(root).as_posix()}",
|
|
)
|
|
)
|
|
elif mode == "canonical" and legacy.is_file():
|
|
if legacy.read_bytes() == canonical.read_bytes():
|
|
findings.append(_finding("OLD_NEW_FULL_CONTENT_DUPLICATE", legacy.relative_to(root).as_posix()))
|
|
if legacy.suffix == ".md":
|
|
canonical_value = parse_frontmatter(legacy.read_text(encoding="utf-8")).get("canonical_path")
|
|
expected_path = canonical.relative_to(root).as_posix()
|
|
if canonical_value != expected_path:
|
|
findings.append(_finding("INVALID_COMPATIBILITY_STUB", legacy.relative_to(root).as_posix(), f"canonical_path must be {expected_path}"))
|
|
else:
|
|
findings.append(
|
|
_finding(
|
|
"NON_MARKDOWN_LEGACY_REMAINS",
|
|
legacy.relative_to(root).as_posix(),
|
|
"canonical mode requires a symlink redirect for non-Markdown legacy assets",
|
|
)
|
|
)
|
|
|
|
rollback_entries = rollback.get("entries")
|
|
rollback_pairs: dict[Path, Path] = {}
|
|
if not isinstance(rollback_entries, list):
|
|
findings.append(_finding("INVALID_CUTOVER_SCHEMA", "rollback_mapping.entries", "must be an array"))
|
|
else:
|
|
for index, item in enumerate(rollback_entries):
|
|
location = f"rollback_mapping.entries[{index}]"
|
|
if not isinstance(item, dict) or set(item) != {"canonical_path", "legacy_path"}:
|
|
findings.append(_finding("INVALID_ROLLBACK_ENTRY", location))
|
|
continue
|
|
canonical = _safe_repo_path(root, item.get("canonical_path"), findings, f"{location}.canonical_path")
|
|
legacy = _safe_repo_path(root, item.get("legacy_path"), findings, f"{location}.legacy_path")
|
|
if canonical is not None and legacy is not None:
|
|
if canonical in rollback_pairs:
|
|
findings.append(_finding("DUPLICATE_ROLLBACK_MAPPING", canonical.relative_to(root).as_posix()))
|
|
rollback_pairs[canonical] = legacy
|
|
for canonical, legacy in by_canonical.items():
|
|
if rollback_pairs.get(canonical) != legacy:
|
|
findings.append(_finding("ROLLBACK_MAPPING_MISSING", canonical.relative_to(root).as_posix()))
|
|
for canonical in rollback_pairs.keys() - by_canonical.keys():
|
|
findings.append(_finding("ROLLBACK_MAPPING_EXTRA", canonical.relative_to(root).as_posix()))
|
|
|
|
all_repository_files = {
|
|
path for path in root.rglob("*")
|
|
if path.is_file() and ".git" not in path.parts
|
|
}
|
|
external_files = all_repository_files - legacy_files - canonical_files
|
|
link_namespace = (legacy_files if mode == "shadow" else canonical_files) | external_files
|
|
_validate_links(root, canonical_files, findings, namespace=link_namespace)
|
|
return {"migration_entries": len(by_legacy), "canonical_files": len(canonical_files)}
|
|
|
|
|
|
def resolve_authority(
|
|
root: Path,
|
|
manifest_path: Path = DEFAULT_MANIFEST,
|
|
*,
|
|
require_clean: bool = True,
|
|
) -> dict[str, Any]:
|
|
"""Resolve the active write authority and fail closed on invalid layout state."""
|
|
root = root.resolve(strict=True)
|
|
manifest_file = manifest_path if manifest_path.is_absolute() else root / manifest_path
|
|
try:
|
|
result = check_layout(root, manifest_path)
|
|
manifest_bytes = manifest_file.read_bytes()
|
|
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
|
|
raise LayoutContractError("LAYOUT_IO_ERROR", str(exc), str(manifest_path)) from exc
|
|
if require_clean and result.get("status") != "PASS":
|
|
codes = ",".join(sorted({item.get("code", "UNKNOWN") for item in result.get("findings", [])}))
|
|
raise LayoutContractError("LAYOUT_NOT_READY", codes or "layout validation failed", str(manifest_path))
|
|
mode = result.get("mode")
|
|
write_roots = result.get("write_roots")
|
|
if mode not in MODES or not isinstance(write_roots, list) or not write_roots:
|
|
raise LayoutContractError("INVALID_WRITE_AUTHORITY", "active mode has no valid write roots", str(manifest_path))
|
|
return {
|
|
"mode": mode,
|
|
"authority": result.get("authority"),
|
|
"write_roots": list(write_roots),
|
|
"manifest_path": manifest_file.relative_to(root).as_posix(),
|
|
"manifest_sha256": hashlib.sha256(manifest_bytes).hexdigest(),
|
|
}
|
|
|
|
|
|
def enforce_write_paths(root: Path, paths: Iterable[Path], authority: Mapping[str, Any]) -> None:
|
|
"""Require every repository write to live under the active authoritative roots."""
|
|
root = _lexical_absolute(root)
|
|
allowed = [_lexical_absolute(root / value) for value in authority.get("write_roots", [])]
|
|
for path in paths:
|
|
resolved = _lexical_absolute(path)
|
|
try:
|
|
resolved.relative_to(root)
|
|
except ValueError as exc:
|
|
raise LayoutContractError("WRITE_OUTSIDE_REPOSITORY", str(path), str(path)) from exc
|
|
if not any(resolved == prefix or prefix in resolved.parents for prefix in allowed):
|
|
relative = resolved.relative_to(root).as_posix()
|
|
raise LayoutContractError(
|
|
"WRITE_ROOT_VIOLATION",
|
|
f"{relative} is outside active write roots {authority.get('write_roots', [])}",
|
|
relative,
|
|
)
|
|
|
|
|
|
def check_layout(root: Path, manifest_path: Path = DEFAULT_MANIFEST) -> dict[str, Any]:
|
|
root = root.resolve()
|
|
manifest_file = manifest_path if manifest_path.is_absolute() else root / manifest_path
|
|
manifest = json.loads(manifest_file.read_text(encoding="utf-8"))
|
|
findings: list[dict[str, str]] = []
|
|
if manifest.get("schema_version") != "vault-layout/v1":
|
|
findings.append(_finding("INVALID_LAYOUT_SCHEMA", str(manifest_path)))
|
|
mode = manifest.get("mode")
|
|
if mode not in MODES:
|
|
findings.append(_finding("INVALID_LAYOUT_MODE", str(manifest_path)))
|
|
|
|
vault_root = root / str(manifest.get("vault_root", "vault"))
|
|
assignments: dict[str, str] = {}
|
|
areas = manifest.get("areas")
|
|
if not isinstance(areas, dict):
|
|
findings.append(_finding("INVALID_LAYOUT_SCHEMA", "areas"))
|
|
areas = {}
|
|
for area, sources in areas.items():
|
|
target = vault_root / area
|
|
if not target.is_dir():
|
|
findings.append(_finding("MISSING_VAULT_AREA", target.relative_to(root).as_posix()))
|
|
if not isinstance(sources, list):
|
|
findings.append(_finding("INVALID_LAYOUT_SCHEMA", f"areas.{area}"))
|
|
continue
|
|
for raw_source in sources:
|
|
source = Path(str(raw_source)).as_posix().rstrip("/")
|
|
if source in assignments:
|
|
findings.append(_finding("DUPLICATE_LAYOUT_OWNER", source, f"{assignments[source]},{area}"))
|
|
assignments[source] = area
|
|
if not (root / source).is_dir():
|
|
findings.append(_finding("MISSING_COMPATIBILITY_SOURCE", source))
|
|
if source == "harness" or source.startswith("harness/"):
|
|
findings.append(_finding("HARNESS_INSIDE_VAULT", source))
|
|
|
|
actual = {
|
|
path.relative_to(root).as_posix()
|
|
for content_root in CONTENT_ROOTS
|
|
if (root / content_root).is_dir()
|
|
for path in (root / content_root).iterdir()
|
|
if path.is_dir()
|
|
}
|
|
for path in sorted(actual - set(assignments)):
|
|
findings.append(_finding("UNASSIGNED_CONTENT_ROOT", path))
|
|
for required in ("harness/source", "harness/adapters", "harness/runtime", "harness/tests"):
|
|
if not (root / required).is_dir():
|
|
findings.append(_finding("MISSING_HARNESS_AREA", required))
|
|
|
|
write_roots = manifest.get("write_roots")
|
|
if not isinstance(write_roots, dict) or set(write_roots) != MODES:
|
|
findings.append(_finding("INVALID_WRITE_ROOTS", "write_roots", "all three modes are required"))
|
|
else:
|
|
expected = [Path(str(manifest.get("vault_root", "vault"))).as_posix()] if mode == "canonical" else ["raw", "wiki"]
|
|
observed = write_roots.get(mode)
|
|
if observed != expected:
|
|
findings.append(_finding("INVALID_AUTHORITATIVE_WRITE_ROOT", f"write_roots.{mode}", f"expected {expected}, observed {observed}"))
|
|
|
|
cutover_stats = {"migration_entries": 0, "canonical_files": 0}
|
|
if mode in {"shadow", "canonical"}:
|
|
cutover_stats = _validate_cutover(root, mode, vault_root, assignments, manifest, findings)
|
|
|
|
findings.sort(key=lambda item: (item["path"], item["code"], item.get("detail", "")))
|
|
return {
|
|
"schema_version": "layout-check-result/v2",
|
|
"status": "PASS" if not findings else "FAIL",
|
|
"mode": mode or "",
|
|
"authority": "vault" if mode == "canonical" else "legacy",
|
|
"write_roots": write_roots.get(mode, []) if isinstance(write_roots, dict) and mode in MODES else [],
|
|
"assigned_sources": len(assignments),
|
|
"discovered_content_roots": len(actual),
|
|
**cutover_stats,
|
|
"findings": findings,
|
|
}
|
|
|
|
|
|
def main(argv: list[str] | None = None) -> int:
|
|
parser = argparse.ArgumentParser(description=__doc__)
|
|
parser.add_argument("--root", type=Path, default=DEFAULT_ROOT)
|
|
parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
|
|
args = parser.parse_args(argv)
|
|
try:
|
|
result = check_layout(args.root.resolve(strict=True), args.manifest)
|
|
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
|
|
result = {
|
|
"schema_version": "layout-check-result/v2",
|
|
"status": "ERROR",
|
|
"findings": [_finding("LAYOUT_IO_ERROR", str(exc))],
|
|
}
|
|
exit_code = 2
|
|
else:
|
|
exit_code = 0 if result["status"] == "PASS" else 1
|
|
json.dump(result, sys.stdout, ensure_ascii=False, indent=2, sort_keys=True)
|
|
sys.stdout.write("\n")
|
|
return exit_code
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|