"""仓库与顶层目录的整洁门槛。

检查顶层布局、工作树登记、私有产物和公开文档中的个人信息。
"""
import ast
import pathlib
import re
import socket
import subprocess
import tempfile
import tomllib
import unittest

import peach
from peach import appid
from scripts import test_runner

REPO = pathlib.Path(peach.__file__).resolve().parents[2]
DOCS = REPO / "docs"

#: ADR-0017 定义的四个运行时目录，加一个归置处。顶层只允许这五项。
TOP_LEVEL_ALLOWED = {"peach-app", "peach-data", "peach-sync", "peach-worktrees", "attic"}

#: 文件管理器自己写的缓存文件，按 casefold 比对（Windows 上大小写会变）。门槛拦的是人
#: 放上去的散落文档和产物；这几个不是人放的，macOS Finder 只要打开过那个文件夹就会写
#: `.DS_Store`，Windows 资源管理器写 `desktop.ini` 与 `Thumbs.db`，删掉照样再长出来。
#: 不豁免它们，这条门槛在任何有图形界面的开发机上都是红的，红得和布局无关。
TOP_LEVEL_GENERATED_FILES = frozenset({".ds_store", "desktop.ini", "thumbs.db"})

PRIVATE_CONTEXT_DOCUMENTS = frozenset({
    "HANDOFF.md", "STATUS.md", "PRODUCT_BACKLOG.md", "VERIFICATION_EFFICIENCY.md",
    "UI_REUSE_REVIEW.md", "SCRAPING_AUDIT.md",
})
PRIVATE_CONTEXT_PATHS = frozenset({
    "docs/reference-snapshots/tag-vocabulary-audit.md", "docs/scraping-audit.csv",
})
PRIVATE_ARTIFACT_ROOTS = frozenset({
    "peach-data", "peach-sync", "peach-worktrees", "secrets", "generated", "review", "attic", "build",
})
PRIVATE_RECORD_PATH = re.compile(r"(?:peach-data/(?:review|archive)/|attic/(?:evidence|reviews)/)(?![<*])[^`\s)]+")
COLLECTION_INVENTORY = re.compile(
    r"(?:本机|本库|真实馆藏|真实库|库里|馆里)[^。\n]{0,100}\d[\d,]*\s*"
    r"(?:条资产|行|部|作品|张头像|张封面|个文件|条来源|个题材|枚圆标|位缺头像)"
)


def _private_artifact(name: str) -> bool:
    path = pathlib.PurePosixPath(name)
    if path.parts[0].casefold() in PRIVATE_ARTIFACT_ROOTS:
        return True
    if name.startswith((".claude/worktrees/", ".codex/environments/")):
        return True
    if name in PRIVATE_CONTEXT_PATHS:
        return True
    if path.parent == pathlib.PurePosixPath("docs") and path.name in PRIVATE_CONTEXT_DOCUMENTS:
        return True
    if path.name == ".env" or path.name.startswith(".env.") and path.name != ".env.example":
        return True
    return bool(re.search(r"\.(?:db|sqlite\d*)(?:-(?:wal|shm))?$", path.name, re.I))


class PrivateArtifactTests(unittest.TestCase):
    """公开代码树拒收私有上下文、账本与运行产物。"""

    def test_private_artifact_paths_are_rejected_and_public_sources_are_allowed(self):
        for name in ("docs/HANDOFF.md", "docs/STATUS.md", "docs/PRODUCT_BACKLOG.md",
                     "peach-data/review/catalog.csv", "review/current-inventory.csv",
                     "attic/evidence/session.json", "secrets/access.json", ".env.local",
                     "database/ledger.db-wal", "database/history.sqlite3"):
            with self.subTest(path=name):
                self.assertTrue(_private_artifact(name))
        for name in ("docs/REUSE.md", "docs/OPERATIONS.md", "docs/TESTING.md",
                     "tests/test_job_status.py", "web/dist/peach-app.js", ".env.example",
                     "resources/seed/entities.json"):
            with self.subTest(path=name):
                self.assertFalse(_private_artifact(name))

    def test_tracked_files_exclude_private_artifacts(self):
        done = subprocess.run(["git", "ls-files", "-z"], cwd=REPO, capture_output=True, check=True)
        names = done.stdout.decode("utf-8").split("\0")
        offenders = [name for name in names if name and (REPO / name).is_file() and _private_artifact(name)]
        self.assertEqual(offenders, [], "私有记录与运行产物必须保存在代码仓库外")

    def test_git_ignores_private_context_and_runtime_directories(self):
        names = [f"docs/{name}" for name in sorted(PRIVATE_CONTEXT_DOCUMENTS)]
        names += sorted(PRIVATE_CONTEXT_PATHS)
        names += ["peach-data/review/catalog.csv", "secrets/access.json", "review/catalog.csv",
                  "attic/evidence/session.json"]
        public_sources = ["frontend/src/react/review/review-page.tsx", "resources/seed/entities.json"]
        done = subprocess.run(["git", "check-ignore", "--no-index", "-z", "--stdin"], cwd=REPO,
                              input=("\0".join([*names, *public_sources]) + "\0").encode("utf-8"),
                              capture_output=True, check=False)
        self.assertEqual(done.returncode, 0, done.stderr.decode("utf-8"))
        self.assertEqual(set(done.stdout.decode("utf-8").strip("\0").split("\0")), set(names))

    def test_private_inventory_and_record_references_are_distinguished_from_examples(self):
        self.assertIsNotNone(COLLECTION_INVENTORY.search("本机盘点有 1234 部作品"))
        self.assertIsNotNone(PRIVATE_RECORD_PATH.search("peach-data/review/current-catalog.csv"))
        self.assertIsNone(COLLECTION_INVENTORY.search("示例库包含 12 部合成视频"))
        self.assertIsNone(PRIVATE_RECORD_PATH.search("<Peach 数据目录>/review/<复核产物>"))


def _loose_files(top: pathlib.Path) -> list[str]:
    """顶层的散落文件名，去掉文件管理器自己写的缓存。"""
    return sorted(child.name for child in top.iterdir() if child.is_file()
                  and child.name.casefold() not in TOP_LEVEL_GENERATED_FILES)


class TopLevelLayoutTests(unittest.TestCase):
    """顶层只放四个运行时目录加 attic/，且不放散落文件。

    在别的机器或 CI 上这个布局不成立（只 clone 了 peach-app），那里跳过——门槛要能在
    真实布局上拦住人，不能因为环境不同就把整套测试拖红。
    """

    def setUp(self):
        # 往上找真正的顶层，而不是 `REPO.parent`：测试几乎总是在隔离工作树里跑，那时
        # 上一级是 `peach-worktrees/`，判据不成立就会永远跳过——一个永远跳过的门槛
        # 等于没有，和它要防的失效是同一种。
        self.top = None
        for candidate in [REPO, *REPO.parents]:
            if all((candidate / name).is_dir()
                   for name in ("peach-app", "peach-data", "peach-worktrees")):
                self.top = candidate
                break
        if self.top is None:
            self.skipTest("不是双盘运行时布局（只 clone 了 peach-app），跳过")

    def test_only_the_runtime_directories_and_attic_live_at_the_top(self):
        extra = sorted(p.name for p in self.top.iterdir()
                       if p.is_dir() and p.name not in TOP_LEVEL_ALLOWED)
        self.assertEqual(
            extra, [],
            "顶层多了目录：`peach-` 前缀专属那四个运行时目录，别的东西进 attic/ 的"
            " builds／evidence／instances／tools／reviews，目录名写成 YYYYMMDD-主题",
        )

    def test_no_loose_files_at_the_top(self):
        self.assertEqual(_loose_files(self.top), [],
                         "顶层不放散落文件：文档进 attic/reviews/，产物进 attic/evidence/")


class LooseFileGuardTests(unittest.TestCase):
    """散落文件的判据本身。不依赖这台机器的布局，所以在哪儿都跑。"""

    def test_the_guard_exempts_only_the_file_manager_caches(self):
        """门槛自身也要能被证伪：缓存放行，人放上去的文件照旧算违规。"""
        with tempfile.TemporaryDirectory() as raw:
            sample = pathlib.Path(raw).resolve()
            for name in (".DS_Store", "desktop.ini", "Thumbs.db",
                         "REVIEW.md", "probe.json", "ds_store.md"):
                (sample / name).write_bytes(b"x")
            (sample / "peach-app").mkdir()
            self.assertEqual(_loose_files(sample),
                             ["REVIEW.md", "ds_store.md", "probe.json"])


class UnregisteredWorktreeTests(unittest.TestCase):
    """两个工作树落点里都不许留下未登记的目录。

    工作树被回收后目录可能留在原地，成了一份看不出区别的旧副本——在里面跑 git
    全部作用于主检出的 master。`peach-worktrees/` 是 `create` 的落点，也是智能体被告知
    要去干活的地方，所以它和 `.claude/worktrees/` 同一条判据。别的会话此刻可能正合法地
    占着一个工作树，所以判据是「有没有登记」而不是「有没有目录」，登记过的放行，
    本测试也从不删东西。
    """

    def _git(self, *args: str) -> str:
        done = subprocess.run(["git", *args], cwd=REPO, capture_output=True,
                              text=True, encoding="utf-8", errors="replace", check=False)
        if done.returncode != 0:
            self.skipTest(f"git 不可用或不是仓库：{done.stderr.strip()}")
        return done.stdout

    def test_no_unregistered_directory_lingers_in_either_worktree_root(self):
        # `--git-common-dir` 在工作树里指向主检出的 `.git`，在主检出里是相对路径，
        # 所以统一按 REPO 解析再取上一级。只 clone 了 peach-app 的机器上两个落点都可能
        # 不存在，不存在的那一个跳过。
        common = pathlib.Path(self._git("rev-parse", "--git-common-dir").strip())
        main = (REPO / common).resolve().parent
        registered = {
            pathlib.Path(line[len("worktree "):]).resolve()
            for line in self._git("worktree", "list", "--porcelain").splitlines()
            if line.startswith("worktree ")
        }
        for root in (main.parent / "peach-worktrees", main / ".claude" / "worktrees"):
            if not root.is_dir():
                continue
            residue = sorted(child.name for child in root.iterdir()
                             if child.is_dir() and child.resolve() not in registered)
            self.assertEqual(
                residue, [],
                f"{root} 下有未登记的工作树残留：`prune --apply` 扫空目录，"
                "里面还有文件的按它报的路径确认没人在用后手动删",
            )


class BundledImageTests(unittest.TestCase):
    """图像二进制只许出现在 `resources/` 下。

    ADR-0024 的验收清单里一直有这一条，没有实现。ADR-0026 划出「法人实体标识」这条窄
    例外之后它更要有：例外一旦开口，下一张图进来时挡住它的只能是门槛，不是那份 ADR
    的措辞。`resources/` 之内由 `test_brand_marks` 逐条查判据，这里只管边界。
    """

    #: 判扩展名而不判字节：仓库里没有无扩展名的图，而读全部文件去嗅探要慢两个数量级。
    IMAGE_SUFFIXES = frozenset({
        ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".avif", ".ico", ".icns", ".tiff",
    })

    def test_images_live_only_under_resources(self):
        done = subprocess.run(["git", "ls-files", "-z"], cwd=REPO, capture_output=True,
                              text=True, encoding="utf-8", errors="replace", check=False)
        if done.returncode != 0:
            self.skipTest(f"git 不可用或不是仓库：{done.stderr.strip()}")
        stray = sorted(
            name for name in done.stdout.split("\0")
            if name and pathlib.PurePosixPath(name).suffix.lower() in self.IMAGE_SUFFIXES
            and not name.startswith("resources/")
        )
        self.assertEqual(
            stray, [],
            "图像二进制只进 resources/：应用自身品牌资产直接放 resources/，"
            "厂牌与站点标识走 scripts/sync_brand_marks.py 收进 resources/marks/（ADR-0026），"
            "其余图片是本机派生产物，留在 peach-data/generated/",
        )


class DocumentationMediaTests(unittest.TestCase):
    """`docs/assets/` 只放少量演示媒体，且每个文件都要小到能进 Git。

    README 的介绍视频住在这里，所以这一档不是「不许有字节」而是「有上限」：没有上限的话，
    下一段素材进来时挡住它的只剩人的自觉，而仓库一旦收下几十 MB 的二进制，clone 的人
    每次都得付这笔钱，删掉也只是从工作区消失，历史里照样躺着。
    """

    ASSETS = DOCS / "assets"
    #: 只认这几种容器：都是浏览器与 GitHub 直接播得动的格式，不需要额外转码说明。
    MEDIA_SUFFIXES = frozenset({".mp4", ".webm"})
    MAX_BYTES = 8 * 1024 * 1024

    def test_demo_media_stays_within_its_allowed_types_and_size(self):
        if not self.ASSETS.is_dir():
            self.skipTest("docs/assets 不存在")
        for path in sorted(self.ASSETS.rglob("*")):
            if not path.is_file():
                continue
            with self.subTest(asset=path.name):
                self.assertIn(
                    path.suffix.lower(), self.MEDIA_SUFFIXES,
                    "docs/assets 只收 mp4 与 webm 演示媒体；截图与图标走 resources/",
                )
                self.assertLessEqual(
                    path.stat().st_size, self.MAX_BYTES,
                    f"{path.name} 超过 {self.MAX_BYTES // (1024 * 1024)} MB："
                    "演示媒体要先压到这个上限以内，压不下去就别放进仓库",
                )




#: 家目录路径：`C:\Users\<名字>\…`、`/Users/<名字>/…`、`/home/<名字>/…`。名字段要以字母开头，
#: `<user>`、`<用户目录>` 这类占位由此放行；前面不许紧贴单词字符，`pixiv.net/users/…` 这种
#: URL 路径不算家目录。CI 靶机的 `runner`／`runneradmin`（含 8.3 短名 `RUNNER~1`）是文档里
#: 会正当提到的名字，放行。
_HOME_DIRECTORY = (r"(?<!\w)[\\/](?:Users|home)[\\/]"
                   r"(?!(?:runner|runneradmin)\b)[A-Za-z][\w.-]*")

#: mDNS 主机名 `<名字>.local`。只放行三个有文档意义的占位：默认名 `peach` 与讲双机布局用的
#: `peach-writer`／`peach-reader`。`self.local`／`this.local` 是属性名与后缀同形，不算主机名；
#: `threading.local()` 是标准库调用；同名主机地址仍按机器坐标检查。
#: `<mounts.local>` 是占位；`settings.local.json`、`_tcp.local.` 后面还有段，都不是主机名。
_MDNS_HOST = (r"(?<![\w<-])(?!(?:self|this|peach|peach-writer|peach-reader)\.local\b|threading\.local\s*\()"
              r"[a-z0-9-]+\.local\b(?![.\w])")

#: RFC 1918 私网地址；`10.` 段收尾要词边界，Windows 版本号 `10.0.26200.1234` 才不会被算进去。
#: 举例用 RFC 5737 的 192.0.2.0/24、198.51.100.0/24、203.0.113.0/24：它们不属于任何人，
#: 读者也不会照抄进自己的配置。
_PRIVATE_IPV4 = (r"\b192\.168\.\d{1,3}\.\d{1,3}"
                 r"|\b10\.\d{1,3}\.\d{1,3}\.\d{1,3}\b"
                 r"|\b172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}")

#: 只属于某一台机器的字面量。它们要么住在设置文件里，要么由用户在命令行给，
#: 不能编译进 `src/peach/`——否则第一个陌生用户跑起来就连着别人家的坐标（ADR-0023）。
#: 挂载点与项目位置只在源码里拦：说明文档要讲清双机布局，就得点出具体落点。
PERSONAL_LITERAL = re.compile("(?i)" + "|".join((
    r"Desktop[\\/]peach",                       # 某一台机器的项目位置
    _HOME_DIRECTORY,
    _MDNS_HOST,
    r"Volumes[\\/](?:peach-sync|RESOURCES)",    # macOS 上的具体挂载点
    r"[\\/]IMSL[\\/]",                          # CloudDrive 挂载目录
    _PRIVATE_IPV4,
)))

#: 全树一律不许出现的机器坐标：私网地址的具体一台、任何人的家目录、任何一台机器的 mDNS 名。
#: 仓库公开后它们既是别人家的坐标又是个人信息（ADR-0023 第四阶段）。判据写成形状而不是
#: 点名：门槛自己也进 Git，点名等于把要拦的坐标印在公开代码里。当前维护者的账号名与
#: 主机名由 `MachineCoordinateTests` 运行时取本机的值再扫一遍，对任何维护者都成立；
#: 那一遍先剔掉仓库自己的公开归属，判据见 `_this_machine_guard`。
#:
#: 判据是「只对某一台机器成立」，不是「像个名字」：仓库的 GitHub 归属与 LICENSE 的
#: 版权人本来就要公开署名，它们不在拦截范围内。
MACHINE_COORDINATE = re.compile("(?i)" + "|".join((_PRIVATE_IPV4, _HOME_DIRECTORY, _MDNS_HOST)))

#: 从 GitHub 的仓库 URL 里取归属名，`https://github.com/<owner>/<repo>` 与
#: `git@github.com:<owner>/<repo>` 两种写法都收。
_GITHUB_OWNER = re.compile(r"github\.com[:/]+([A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)/")

#: 门槛自身要写出它拦的形状，所以只有它自己豁免。
COORDINATE_EXEMPT_FILES = frozenset({"tests/test_repo_hygiene.py"})

#: 第三方代码与构建产物的措辞不由本仓库决定，压缩后的它们也没有可读的行。
#: 上游 README 快照逐字节锁在 `docs/reference-sources.json` 的 sha256 上，示例地址属于上游。
COORDINATE_EXEMPT_PREFIXES = ("web/vendor/", "web/dist/", "docs/reference-snapshots/upstream/")


def _live_strings(path: pathlib.Path) -> list[tuple[int, str]]:
    """源码里真正会被当值用的字符串常量，去掉文档串。

    文档串和注释留给解释：说明「哪一台机器是 writer」时提到具体名字是有信息量的，
    把它编译成默认值才是问题。判据因此是 AST 而不是 grep。
    """
    tree = ast.parse(path.read_text(encoding="utf-8"))
    docstrings = {
        id(node.body[0].value)
        for node in ast.walk(tree)
        if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef,
                             ast.AsyncFunctionDef))
        and node.body and isinstance(node.body[0], ast.Expr)
        and isinstance(node.body[0].value, ast.Constant)
        and isinstance(node.body[0].value.value, str)
    }
    return [(node.lineno, node.value) for node in ast.walk(tree)
            if isinstance(node, ast.Constant) and isinstance(node.value, str)
            and id(node) not in docstrings]


def _repository_identity(repo: pathlib.Path = REPO) -> frozenset[str]:
    """仓库自己的公开归属名，casefold 过。

    三个来源都取，取不到的静默跳过：`git remote` 的 URL、`pyproject.toml` 的项目 URL、
    `src/peach/appid.py` 的反向域名前缀。它们指的是同一个归属，多取一处是为了任一处
    缺失时判据仍然成立，而不是把名字写进这里——门槛自己也进 Git，点名等于把维护者的
    账号名印进公开代码，和形状判据不点名坐标是同一个理由。
    """
    names = set(appid.BUNDLE_PREFIX.split("."))
    urls: list[str] = []
    with (repo / "pyproject.toml").open("rb") as handle:
        urls += tomllib.load(handle)["project"].get("urls", {}).values()
    done = subprocess.run(["git", "remote", "-v"], cwd=repo, capture_output=True,
                          text=True, encoding="utf-8", errors="replace", check=False)
    if done.returncode == 0:
        urls += done.stdout.split()
    for url in urls:
        found = _GITHUB_OWNER.search(url)
        if found:
            names.add(found.group(1))
    return frozenset(name.casefold() for name in names if name)


def _this_machine_guard(names, identity) -> re.Pattern[str] | None:
    """只在网址、挂载目录和账号/主机配置中匹配本机名字。

    仓库公开归属不属于个人坐标；用户目录与 mDNS 等坐标仍由 MACHINE_COORDINATE
    检查。无剩余名字时返回 None，避免空正则匹配全部内容。
    """
    remaining = sorted(name for name in names if name and name.casefold() not in identity)
    if not remaining:
        return None
    names_pattern = r"(?:" + "|".join(map(re.escape, remaining)) + r")"
    context = (r"(?:https?://|smb://|\\\\|/Volumes/|/mnt/|/media/)"
               r"|\b(?:username|user_name|hostname|smb_host|account)['\"]?\s*[:=]\s*['\"]?")
    return re.compile("(?:" + context + ")" + names_pattern + r"(?![\w.-])", re.IGNORECASE)


class PersonalLiteralTests(unittest.TestCase):
    """`src/peach/` 里不许留只对某一台机器成立的默认值。"""

    def test_common_machine_names_require_coordinate_context(self):
        guard = _this_machine_guard({"test", "desktop"}, frozenset())
        for text in ("test the desktop app", "https://example.invalid/test", "desktop-client", "accounting test"):
            self.assertIsNone(guard.search(text), text)
        for text in ("https://desktop/media", "smb://test/share", r"\\desktop\share",
                     "/Volumes/test/media", "hostname = 'desktop'", "username: test",
                     '{"hostname": "desktop"}', '{"username": "test"}'):
            self.assertIsNotNone(guard.search(text), text)

    def test_no_module_hardcodes_a_personal_coordinate(self):
        source = pathlib.Path(peach.__file__).parent
        offenders = []
        for path in sorted(source.rglob("*.py")):
            offenders += [
                f"{path.relative_to(source).as_posix()}:{line}：{text[:60]}"
                for line, text in _live_strings(path)
                if PERSONAL_LITERAL.search(text)
            ]
        self.assertEqual(offenders, [],
                         "把它搬进 <Peach 数据目录>/config.toml（peach init --from-existing 会生成），"
                         "或者做成命令行参数")

    def test_the_guard_catches_the_shape_it_describes(self):
        """门槛自身也要能被证伪，否则它可能只是一段永远为真的代码。"""
        for sample in (r"C:\Users\alice\Desktop\peach\peach-data", "~/Desktop/peach",
                       "/Users/alice/peach", "/home/alice/peach", "alice-mbp.local",
                       "/Volumes/peach-sync", "https://10.234.56.78",
                       "/Volumes/RESOURCES/media", "/Users/x/Desktop/IMSL/115"):
            self.assertTrue(PERSONAL_LITERAL.search(sample), sample)
        for allowed in ("127.0.0.1", "0.0.0.0", "peach.local", "224.0.0.251",
                        "192.0.2.1", r"R:\media", "peach-data", "peach-sync",
                        "Chrome/131.0.0.0", r"C:\Users\<user>\peach-data",
                        "https://www.pixiv.net/users/93812377", "self.local"):
            self.assertIsNone(PERSONAL_LITERAL.search(allowed), allowed)


class ReleaseFilesTests(unittest.TestCase):
    """公开发布必须齐备的治理文件（ADR-0023 第 4 阶段，名称与标识政策见 ADR-0129）。

    仓库一旦公开，许可证、名称政策、贡献说明、安全说明和 issue/PR 模板就是陌生人判断「能不能用、
    怎么报问题」的唯一依据。缺一份的后果不是报错而是沉默：使用者无从判断授权范围，
    漏洞只能开成公开 issue。它们又都是「一次写好、之后没人再看」的文件，正是重构和
    路径调整时最容易被顺手删掉的那一类，所以在这里钉住存在性。
    """

    #: 相对仓库根的路径。清单只增不减，删除任何一项都要先改 ADR-0023。
    REQUIRED = (
        "LICENSE",
        "docs/TRADEMARKS.md",
        "CONTRIBUTING.md",
        "SECURITY.md",
        "CHANGELOG.md",
        ".github/PULL_REQUEST_TEMPLATE.md",
        ".github/ISSUE_TEMPLATE/config.yml",
    )

    def test_every_release_file_exists_and_has_content(self):
        missing = [name for name in self.REQUIRED if not (REPO / name).is_file()]
        self.assertEqual(missing, [], "公开发布缺少治理文件")
        empty = [name for name in self.REQUIRED
                 if not (REPO / name).read_text(encoding="utf-8").strip()]
        self.assertEqual(empty, [], "治理文件存在但是空的，等于没有")

    def test_the_licence_is_the_agpl_v3(self):
        text = (REPO / "LICENSE").read_text(encoding="utf-8")
        for marker in ("GNU AFFERO GENERAL PUBLIC LICENSE", "Version 3"):
            self.assertIn(marker, text,
                          "许可证是 AGPL-3.0-or-later（ADR-0023 第 4 阶段），换许可证要先改 ADR")

    def test_pyproject_licence_expression_matches_the_licence_file(self):
        """pyproject 的 SPDX 表达式和 LICENSE 全文是同一份许可证的两种写法。"""
        with (REPO / "pyproject.toml").open("rb") as handle:
            project = tomllib.load(handle)["project"]
        self.assertEqual(
            project.get("license"), "AGPL-3.0-or-later",
            "pyproject.toml 的 SPDX 表达式必须与 LICENSE 全文和 ADR-0023 第 4 阶段一致；"
            "换许可证要 LICENSE、pyproject.toml、ADR-0023 三处同改",
        )


class MachineCoordinateTests(unittest.TestCase):
    """Git 跟踪的每个文本文件都不许写出某一台机器的坐标。

    只管源码的门槛拦不住这件事：真实 IP、用户名和账号名过去散在测试夹具、安装脚本、
    ADR、状态文档与技能里，它们都不是「默认值」，公开仓库后却一样把用户的网络布局
    和账号名交出去。所以判据是 `git ls-files` 的全部文本，不是某个目录。
    """

    def _tracked_text_files(self, exempt_files=COORDINATE_EXEMPT_FILES):
        done = subprocess.run(["git", "ls-files", "-z"], cwd=REPO,
                              capture_output=True, check=False)
        if done.returncode != 0:
            self.skipTest(f"git 不可用或不是仓库：{done.stderr.decode('utf-8', 'replace')}")
        for name in done.stdout.decode("utf-8").split("\0"):
            if not name or name in exempt_files:
                continue
            if name.startswith(COORDINATE_EXEMPT_PREFIXES):
                continue
            path = REPO / name
            if not path.is_file():
                continue
            raw = path.read_bytes()
            if b"\0" in raw:
                continue
            try:
                yield name, raw.decode("utf-8")
            except UnicodeDecodeError:
                continue

    def test_no_tracked_file_names_a_machine_coordinate(self):
        offenders = []
        for name, text in self._tracked_text_files():
            for number, line in enumerate(text.splitlines(), 1):
                found = MACHINE_COORDINATE.search(line)
                if found:
                    offenders.append(f"{name}:{number}：{found.group(0)}")
        self.assertEqual(
            offenders, [],
            "换成 RFC 5737 的文档地址（192.0.2.0/24、198.51.100.0/24、203.0.113.0/24）"
            "或中性的主机名、账号名、`<用户目录>` 这类占位",
        )

    def test_public_documents_exclude_collection_inventories_and_private_record_names(self):
        offenders = []
        for name, text in self._tracked_text_files():
            if not name.endswith(".md"):
                continue
            for number, line in enumerate(text.splitlines(), 1):
                if COLLECTION_INVENTORY.search(line) or PRIVATE_RECORD_PATH.search(line.replace("\\", "/")):
                    offenders.append(f"{name}:{number}")
        self.assertEqual(offenders, [], "馆藏盘点与私有记录名应保存在部署 Peach 数据目录，检查输出只列文件和行号")

    def test_no_tracked_file_names_this_machine(self):
        """本机的账号名与主机名对任何维护者都成立，正好不用在正则里点名。

        扫的是「剔掉仓库自身归属之后剩下的本机名字」，判据与剔除的理由见
        `_this_machine_guard`。本文件自己也扫：形状门槛豁免它是因为它要写出形状，
        可它没有理由写出这台机器。
        """
        hostname = socket.gethostname()
        names = {pathlib.Path.home().name, hostname, hostname.split(".", 1)[0]}
        this_machine = _this_machine_guard(names, _repository_identity())
        if this_machine is None:
            self.skipTest("本机的账号名与主机名都是仓库自己的公开归属，只剩形状门槛可扫")
        offenders = []
        for name, text in self._tracked_text_files(exempt_files=frozenset()):
            for number, line in enumerate(text.splitlines(), 1):
                found = this_machine.search(line)
                if found:
                    offenders.append(f"{name}:{number}：{found.group(0)}")
        self.assertEqual(offenders, [], "换成中性的账号名、主机名或 `<用户目录>` 这类占位")

    def test_the_whole_tree_guard_catches_the_shape_it_describes(self):
        """门槛自身也要能被证伪，否则它可能只是一段永远为真的代码。"""
        for sample in ("https://10.234.56.78", "PEACH_SHARED_SMB_HOST=192.168.1.9",
                       "review_writer_origin = 'https://10.0.0.5'", "172.31.112.1",
                       r"C:\Users\alice\Desktop\peach", "/Users/alice/Desktop/peach",
                       "/home/alice/peach", "smb://alice@alice-mbp.local/peach-sync",
                       "peach-two.local", "https://Alice-PC.local/", "https://threading.local/"):
            self.assertTrue(MACHINE_COORDINATE.search(sample), sample)
        for allowed in ("127.0.0.1", "0.0.0.0", "224.0.0.251", "198.18.0.1",
                        "192.0.2.2", "198.51.100.162", "203.0.113.1",
                        "peach.local", "peach-writer.local", "peach-reader.local",
                        "https://<writer>.local", "<mounts.local>/x",
                        ".claude/settings.local.json", "_https._tcp.local.",
                        "copy_database(self.shared, self.local)", "threading.local()", "peach-sync",
                        r"C:\Users\<user>\Desktop\peach", "~/Desktop/<用户目录>/peach",
                        r"C:\Users\RUNNER~1\AppData\Local\Temp", "/home/runner/work",
                        "https://www.pixiv.net/users/93812377",
                        "Chrome/131.0.0.0", "10.0.26200.1234", r"R:\media",
                        "https://github.com/peach-mitao/peach",
                        "Copyright (C) 2026 longmeidao"):
            self.assertIsNone(MACHINE_COORDINATE.search(allowed), allowed)

    def test_the_repository_identity_covers_its_own_github_owner(self):
        """归属名要真的从仓库元数据里解析出来，取不到就等于没剔除。"""
        with (REPO / "pyproject.toml").open("rb") as handle:
            urls = tomllib.load(handle)["project"]["urls"]
        owners = {found.group(1).casefold() for found in
                  (_GITHUB_OWNER.search(url) for url in urls.values()) if found}
        self.assertTrue(owners, "pyproject 的项目 URL 里应当写出仓库的 GitHub 归属")
        self.assertLessEqual(owners, _repository_identity(),
                             "仓库自己的 GitHub 归属没被认出来")

    def test_the_identity_exemption_does_not_hollow_out_the_this_machine_guard(self):
        """剔除只放行「光提到归属名」，同一个名字落进坐标形状照旧拦下。

        用合成的名字断言，这样判据本身不写出任何真实归属。
        """
        owner, other = "example-owner", "peach-two"
        guard = _this_machine_guard({owner, other}, frozenset({owner}))
        for allowed in (f"https://github.com/{owner}/peach",
                        f"io.github.{owner}.peach.tray",
                        f"Copyright (C) 2026 {owner}",
                        f"{owner}-peach", f"{owner}.Peach"):
            self.assertIsNone(guard.search(allowed), allowed)
        for blocked in (f"smb://{other}/peach-sync", f"/Volumes/{other}/media"):
            self.assertIsNotNone(guard.search(blocked), blocked)
        for blocked in (f"/Users/{owner}/Desktop/peach", f"/home/{owner}/peach",
                        rf"C:\Users\{owner}\peach-data",
                        f"smb://{owner}@{owner}-mbp.local/peach-sync"):
            self.assertIsNotNone(MACHINE_COORDINATE.search(blocked), blocked)
        self.assertIsNone(_this_machine_guard({owner}, frozenset({owner})),
                          "名字全被剔掉时不许返回会匹配任何位置的空正则")


class ArchitectureDriftTests(unittest.TestCase):
    """架构文档点名的模块必须真的存在。

    它逼不出「架构变了要重写描述」，但能逼出「模块改名或删掉之后文档还在指它」——
    那种失真最难发现，因为文档读起来一切正常。
    """

    def test_every_module_the_document_names_still_exists(self):
        text = (DOCS / "ARCHITECTURE.md").read_text(encoding="utf-8")
        source = pathlib.Path(peach.__file__).parent
        missing = sorted({
            name for name in re.findall(r"`src/peach/(\w+)\.py`", text)
            if not (source / f"{name}.py").is_file()
        })
        self.assertEqual(missing, [],
                         "架构文档还在指已经不存在的模块，改名或删除时请一起改")


#: `` `docs/HANDOFF.md`「数据安全」「身份、来源与标识采集」 `` 这种写法：一个路径后面跟一个或多个节名。
SECTION_REFERENCE = re.compile(r"`([\w./-]+\.md)`((?:「[^」]+」)+)")


def _headings(path: pathlib.Path) -> list[str]:
    return [line.lstrip("#").strip() for line in path.read_text(encoding="utf-8").splitlines()
            if line.startswith("#")]


class SectionReferenceTests(unittest.TestCase):
    """入口文件、技能与文档指向的「某文件某一节」必须真的有那一节。

    2026-09-13 盘点时四个技能引用的 `docs/HANDOFF.md` 节名已经改掉了，技能读起来一切
    正常，照着去找的人才发现找不到。节名跟着文件走，改标题的人看不见谁在引用它。
    """

    def test_every_referenced_section_exists(self):
        sources = [REPO / "AGENTS.md", REPO / "CLAUDE.md", REPO / "README.md",
                   *sorted((REPO / ".claude" / "skills").glob("*/SKILL.md")),
                   *sorted(DOCS.glob("*.md"))]
        broken = []
        for source in sources:
            for target, names in SECTION_REFERENCE.findall(source.read_text(encoding="utf-8")):
                # 只写文件名的引用在 `docs/` 下找唯一同名文件（技能里引用参考快照就是这么写的）。
                candidates = [REPO / target, source.parent / target,
                              *(sorted(DOCS.rglob(target)) if "/" not in target else [])]
                found = next((path for path in candidates if path.is_file()), None)
                if found is None:
                    broken.append(f"{source.relative_to(REPO).as_posix()} -> {target}（文件不存在）")
                    continue
                headings = _headings(found)
                for name in re.findall(r"「([^」]+)」", names):
                    if not any(heading == name or heading.startswith(name) for heading in headings):
                        broken.append(f"{source.relative_to(REPO).as_posix()} -> {target}「{name}」")
        self.assertEqual(broken, [],
                         "这些引用指向的节已经不存在，改标题时请一起改引用：\n  " + "\n  ".join(broken))


#: ADR 文件名 `NNNN-主题.md` 与首行标题 `# ADR-NNNN：…`。
_ADR_FILE = re.compile(r"^(\d{4})-[^/\\]+\.md$")
_ADR_TITLE = re.compile(r"^# ADR-(\d{4})(?!\d)")


def _adr_numbering_problems(adr_dir: pathlib.Path) -> list[str]:
    """`docs/adr/` 里编号不唯一、文件名与标题编号不符的文件，一条一行。"""
    problems: list[str] = []
    by_number: dict[str, list[str]] = {}
    for path in sorted(adr_dir.glob("*.md")):
        named = _ADR_FILE.match(path.name)
        if named is None:
            problems.append(f"{path.name}：文件名不是 NNNN-主题.md")
            continue
        number = named.group(1)
        by_number.setdefault(number, []).append(path.name)
        first = next(iter(path.read_text(encoding="utf-8").splitlines()), "")
        titled = _ADR_TITLE.match(first)
        if titled is None or titled.group(1) != number:
            problems.append(f"{path.name}：首行标题应以 `# ADR-{number}` 开头，实际是 {first[:40]!r}")
    for number, names in sorted(by_number.items()):
        if len(names) > 1:
            problems.append(f"ADR-{number} 重号：{'、'.join(names)}")
    return problems


class AdrNumberingTests(unittest.TestCase):
    """ADR 编号全树唯一，文件名编号与首行标题编号一致。

    编号由新建 ADR 的人自己取「当前最大号加一」，两个并行工作树各取一次就会撞号，
    而没有任何门槛看编号，ready 与 integrate 两边都放行：2026-09-23 两份 ADR-0044
    就是这样先后合进 master 的。编号是别处引用 ADR 的唯一钥匙，撞号后「见 ADR-0044」
    指向哪一份说不清。后合入的一方 ready 前必须纳入 master 重跑选测，本门槛就在那一步拦住。
    """

    ADR_DIR = DOCS / "adr"

    def test_every_adr_number_is_unique_and_matches_its_title(self):
        problems = _adr_numbering_problems(self.ADR_DIR)
        self.assertEqual(
            problems, [],
            "ADR 编号有冲突：后合入的那份改用当前最大号加一，文件名与首行标题一起改，"
            "再全树搜旧编号的引用：\n  " + "\n  ".join(problems),
        )

    def test_the_guard_catches_the_shape_it_describes(self):
        """门槛自身也要能被证伪：重号、标题错号、文件名不合形状都要报出来。"""
        with tempfile.TemporaryDirectory() as raw:
            sample = pathlib.Path(raw)
            for name, title in (("0044-scraping.md", "# ADR-0044：甲"),
                                ("0044-booru.md", "# ADR-0044：乙"),
                                ("0045-packs.md", "# ADR-0046：丙"),
                                ("0046-bursts.md", "# ADR-00460：丁"),
                                ("0047-fine.md", "# ADR-0047：戊"),
                                ("notes.md", "# 笔记")):
                (sample / name).write_text(title + "\n正文\n", encoding="utf-8")
            problems = _adr_numbering_problems(sample)
        self.assertEqual(problems, [
            "0045-packs.md：首行标题应以 `# ADR-0045` 开头，实际是 '# ADR-0046：丙'",
            "0046-bursts.md：首行标题应以 `# ADR-0046` 开头，实际是 '# ADR-00460：丁'",
            "notes.md：文件名不是 NNNN-主题.md",
            "ADR-0044 重号：0044-booru.md、0044-scraping.md",
        ])

    def test_adding_an_adr_selects_this_guard(self):
        """新建 ADR 的分支按改动选测时必须跑到本门槛，否则撞号照样能过 ready。"""
        scopes, _ = test_runner.scopes_for_changes(["docs/adr/0099-example.md"])
        self.assertTrue(
            any("test_repo_hygiene.py" in test_runner.SCOPES.get(scope, ()) for scope in scopes),
            f"改 docs/adr/ 选到的域 {scopes} 都没有登记 test_repo_hygiene.py",
        )


if __name__ == "__main__":
    unittest.main()