tests/test_docs_claims.py — Docs vs Code Checker

"""Synthetic command-line checks for Docs vs Code Checker.

By Zero Width Lab (zerowidthlab.com)
"""
from __future__ import annotations

import json
import os
import subprocess
import sys
import tempfile
import unittest
from unittest.mock import patch
import contextlib
import io
from pathlib import Path

__author__ = "Zero Width Lab"
ROOT = Path(__file__).resolve().parent.parent
SCRIPT = ROOT / "scripts" / "docs_claims.py"
FIXTURE = ROOT / "tests" / "fixtures" / "mini-repo"
sys.path.insert(0, str(ROOT / "scripts"))
import docs_claims as helper


class DocsClaimsTests(unittest.TestCase):
    def cli(self, *args: str) -> subprocess.CompletedProcess[str]:
        return subprocess.run([sys.executable, str(SCRIPT), *args], capture_output=True, text=True, check=False)

    def test_extract_candidates_and_lines(self) -> None:
        result = self.cli("extract", str(FIXTURE / "README.md"), "--json")
        self.assertEqual(result.returncode, 0, result.stderr)
        claims = json.loads(result.stdout)["claims"]
        self.assertEqual([item["line"] for item in claims], [3, 4, 5])
        self.assertIn("42 seconds", claims[1]["text"])

    def test_locate_and_inventory(self) -> None:
        result = self.cli("locate", "TIMEOUT_SECONDS", "--root", str(FIXTURE))
        self.assertEqual(result.returncode, 0, result.stderr)
        self.assertIn("app.py:9", result.stdout)
        result = self.cli("inventory", "--root", str(FIXTURE))
        self.assertEqual(result.returncode, 0, result.stderr)
        self.assertIn("flags --color app.py:8", result.stdout)
        self.assertIn("environment APP_MODE app.py:10", result.stdout)
        self.assertIn("versions 0.2.0 app.py:6", result.stdout)

    def test_all_text_names_binary_and_incomplete_walk(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            root = Path(temporary).resolve()
            (root / "Dockerfile").write_text("DOC_TOKEN\n", encoding="utf-8")
            (root / "settings.ini").write_text("--fresh\n", encoding="utf-8")
            (root / "image.bin").write_bytes(b"\0DOC_TOKEN")
            (root / "large.txt").write_text("x" * (1024 * 1024 + 1), encoding="utf-8")
            (root / "large.bin").write_bytes(b"\0" + b"x" * (1024 * 1024))
            (root / "broken.txt").write_bytes(b"\xff")
            (root / "node_modules").mkdir()
            (root / "node_modules" / "hidden.txt").write_text("DOC_TOKEN", encoding="utf-8")
            locate = self.cli("locate", "DOC_TOKEN", "--root", str(root), "--max", "1")
            self.assertEqual(locate.returncode, 2, locate.stderr)
            self.assertIn("Dockerfile:1", locate.stdout)
            self.assertIn("excluded_binary: 1", locate.stdout)
            self.assertNotIn("hidden.txt", locate.stdout)
            self.assertIn("large.txt", locate.stderr)
            self.assertIn("large.bin", locate.stderr)
            self.assertIn("broken.txt", locate.stderr)
            self.assertIn("incomplete: skipped", locate.stderr)
            partial = self.cli("locate", "DOC_TOKEN", "--root", str(root), "--allow-partial")
            self.assertEqual(partial.returncode, 0, partial.stderr)
            self.assertIn("incomplete: skipped", partial.stderr)
            inventory = self.cli("inventory", "--root", str(root))
            self.assertEqual(inventory.returncode, 2, inventory.stderr)
            self.assertIn("flags --fresh settings.ini:1", inventory.stdout)
            self.assertIn("excluded_binary: 1", inventory.stdout)
            self.assertEqual(self.cli("inventory", "--root", str(root), "--allow-partial").returncode, 0)

    def test_binary_exclusion_alone_is_complete(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            root = Path(temporary).resolve()
            (root / "blob.dat").write_bytes(b"\0--false")
            result = self.cli("inventory", "--root", str(root))
            self.assertEqual(result.returncode, 0, result.stderr)
            self.assertEqual(result.stdout.strip(), "excluded_binary: 1")
            self.assertEqual(result.stderr, "")

    def test_skipped_file_is_incomplete(self) -> None:
        result = self.cli("extract", str(FIXTURE / "absent.md"), "--json")
        self.assertEqual(result.returncode, 2)
        self.assertEqual(json.loads(result.stdout)["status"], "incomplete")
        self.assertIn("skipped", result.stderr)
        self.assertEqual(self.cli("extract", str(FIXTURE / "absent.md"), "--allow-partial").returncode, 0)

    def test_report_digest_create_only_and_escaping(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            base = Path(temporary).resolve()
            claims = base / "claims.json"
            verdicts = base / "verdicts.json"
            report = base / "report.md"
            claims.write_text(json.dumps([{"id": "C0001", "file": "README.md", "line": 3, "text": "bad|text" + chr(10) + "header"}]), encoding="utf-8")
            verdicts.write_text(json.dumps([{"id": "C0001", "verdict": "FALSE", "reason": "default is 30", "evidence": [{"file": "app.py", "line": 8}]}]), encoding="utf-8")
            args = ("report", "--claims", str(claims), "--verdicts", str(verdicts), "--out", str(report))
            preview = self.cli(*args, "--dry-run")
            self.assertEqual(preview.returncode, 0, preview.stderr)
            self.assertFalse(report.exists())
            digest = preview.stdout.split("approval digest: ")[1].strip()
            self.assertEqual(self.cli(*args).returncode, 1)
            self.assertEqual(self.cli(*args, "--approve", "0" * 64).returncode, 1)
            live = self.cli(*args, "--approve", digest)
            self.assertEqual(live.returncode, 0, live.stderr)
            content = report.read_text(encoding="utf-8")
            self.assertIn("bad\\|text\\u000aheader", content)
            self.assertIn("FALSE 1", content)
            self.assertEqual(self.cli(*args, "--approve", digest).returncode, 1)
            preview = self.cli(*args, "--dry-run")
            self.assertEqual(preview.returncode, 1)
            self.assertIn("already exists", preview.stderr)
            self.assertEqual(content.splitlines()[-1], "By Zero Width Lab (zerowidthlab.com)")

    def test_report_refuses_symlink_and_changed_content(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            base = Path(temporary).resolve()
            claims = base / "claims.json"
            verdicts = base / "verdicts.json"
            target = base / "target.md"
            target.write_text("preserve", encoding="utf-8")
            output = base / "report.md"
            output.symlink_to(target)
            claims.write_text('[{"id":"A","file":"doc","line":1,"text":"claim"}]', encoding="utf-8")
            verdicts.write_text('[{"id":"A","verdict":"UNVERIFIABLE","evidence":[]}]', encoding="utf-8")
            args = ("report", "--claims", str(claims), "--verdicts", str(verdicts), "--out", str(output))
            preview = self.cli(*args, "--dry-run")
            self.assertEqual(preview.returncode, 1)
            self.assertIn("already exists", preview.stderr)
            self.assertEqual(target.read_text(encoding="utf-8"), "preserve")
            output.unlink()
            digest = self.cli(*args, "--dry-run").stdout.split("approval digest: ")[1].strip()
            verdicts.write_text('[{"id":"A","verdict":"UNVERIFIABLE","reason":"changed","evidence":[]}]', encoding="utf-8")
            self.assertEqual(self.cli(*args, "--approve", digest).returncode, 1)

    def test_parent_swap_after_preview(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            base = Path(temporary).resolve()
            selected = base / "selected"
            selected.mkdir()
            other = base / "other"
            other.mkdir()
            out = selected / "report.md"
            expected = helper.destination_snapshot(out)
            digest = helper.approval_digest(out, "report", expected)
            selected.rename(base / "old")
            selected.symlink_to(other, target_is_directory=True)
            with self.assertRaisesRegex(ValueError, "physical path"):
                helper.create_only(out, "report", expected)
            self.assertFalse((other / "report.md").exists())
            selected.unlink()
            selected.mkdir()
            self.assertNotEqual(helper.approval_digest(out, "report"), digest)
            with self.assertRaisesRegex(ValueError, "changed"):
                helper.create_only(out, "report", expected)
            self.assertFalse(out.exists())

    def test_no_missing_output_ancestors_created(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            out = Path(temporary).resolve() / "absent" / "report.md"
            with self.assertRaises(OSError):
                helper.destination_snapshot(out)
            self.assertFalse(out.parent.exists())

    def test_traversal_rejected_and_root_reads_confined(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            base = Path(temporary).resolve()
            root = base / "root"
            root.mkdir()
            (base / "private.txt").write_text("OUTSIDE", encoding="utf-8")
            (root / "link.txt").symlink_to(base / "private.txt")
            (root / "alias").symlink_to(base, target_is_directory=True)
            self.assertEqual(helper.scan(root, "OUTSIDE", 10)[0], [])
            for value in (root / ".." / "private.txt", root / "%2e%2e" / "private.txt", root / "bad\\path", root / "%252e%252e"):
                with self.subTest(path=str(value)), self.assertRaises(ValueError):
                    helper.read_lines(value)
            fd = helper.open_directory(root)
            try:
                with self.assertRaisesRegex(ValueError, "physical path"):
                    helper.read_bytes(root / "alias" / "private.txt", root_fd=fd, root=root)
                with self.assertRaises(ValueError):
                    helper.read_bytes(base / "private.txt", root_fd=fd, root=root)
            finally:
                os.close(fd)

    def test_unsupported_platform_before_io(self) -> None:
        for platform in ("win32", "freebsd"):
            with patch.object(helper.sys, "platform", platform), patch.object(helper, "read_bytes", side_effect=AssertionError("read attempted")), contextlib.redirect_stderr(io.StringIO()) as errors:
                self.assertEqual(helper.main(["extract", "absent.md"]), 1)
                self.assertIn("supported platforms", errors.getvalue())

    def test_bounded_reads_and_malformed_json(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            base = Path(temporary).resolve()
            file = base / "input.json"
            file.write_bytes(b"x" * (helper.MAX_BYTES + 1))
            with self.assertRaisesRegex(ValueError, "exceeds 1 MiB"):
                helper.read_lines(file)
            for value in ('{}', '[null]', 'invalid', '[' * 2000 + '0' + ']' * 2000):
                file.write_text(value, encoding="utf-8")
                self.assertEqual(self.cli("report", "--claims", str(file), "--verdicts", str(file), "--out", str(base / "out.md"), "--dry-run").returncode, 1)
            claim = [{"id": "A", "file": "README.md", "line": 1, "text": "claim"}]
            for verdict in ([{"id": "A", "verdict": [], "evidence": []}], [{"id": "A", "verdict": "UNVERIFIABLE", "evidence": [], "reason": []}], [{"id": "A", "verdict": "TRUE", "evidence": [{"file": "app.py", "line": 0}]}]):
                with self.assertRaises(ValueError):
                    helper.make_report(claim, verdict)

    def test_deep_tree_walk_is_iterative(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            root = Path(temporary).resolve()
            root_fd = helper.open_directory(root)
            depth = 1100
            created = 0
            ancestors = []
            try:
                current = os.dup(root_fd)
                try:
                    for _ in range(depth):
                        os.mkdir("d", dir_fd=current)
                        created += 1
                        child = helper.open_child_directory("d", current)
                        ancestors.append(current)
                        current = child
                    file_fd = os.open("leaf.py", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=current)
                    with os.fdopen(file_fd, "w") as stream:
                        stream.write("--deep DEPTH_TOKEN")
                finally:
                    os.close(current)
                result, skipped, binary = helper.scan(root, "DEPTH_TOKEN", 1)
                self.assertEqual((len(result), skipped, binary), (1, [], 0))
                result, skipped, binary = helper.inventory(root)
                self.assertEqual((result["flags"][0]["value"], skipped, binary), ("--deep", [], 0))
            finally:
                leaf = helper.open_relative_directory(root_fd, ("d",) * created)
                try:
                    os.unlink("leaf.py", dir_fd=leaf)
                finally:
                    os.close(leaf)
                for parent in reversed(ancestors):
                    try:
                        os.rmdir("d", dir_fd=parent)
                    finally:
                        os.close(parent)
                os.close(root_fd)

    def test_repository_literal_percent_and_backslash_names(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            root = Path(temporary).resolve()
            for name in ("file%41.txt", "back\\slash.txt"):
                (root / name).write_text("--literal LOCAL_TOKEN", encoding="utf-8")
            for command in (("locate", "LOCAL_TOKEN"), ("inventory",)):
                result = self.cli(*command, "--root", str(root))
                self.assertEqual(result.returncode, 0, result.stderr)
                self.assertIn("file%41.txt", result.stdout)
                self.assertIn("back\\\\slash.txt", result.stdout)
            for name in ("..", ".", "bad/name", "bad" + chr(0)):
                with self.assertRaises(ValueError):
                    helper.validate_entry_name(name)

    def test_symlink_ancestor_has_physical_path_guidance(self) -> None:
        with tempfile.TemporaryDirectory() as temporary:
            root = Path(temporary).resolve()
            (root / "real").mkdir()
            (root / "alias").symlink_to(root / "real", target_is_directory=True)
            result = self.cli("inventory", "--root", str(root / "alias"))
            self.assertEqual(result.returncode, 1)
            self.assertIn("a path component is a symlink", result.stderr)
            self.assertIn("use the physical path", result.stderr)
            self.assertIn("/private/tmp", result.stderr)

    def test_bound_identity_documentation_is_exact(self) -> None:
        for relative in ("README.md", "SETUP.md", "SKILL.md", "references/method.md"):
            content = (ROOT / relative).read_text(encoding="utf-8")
            self.assertIn("verifies only the destination directory and its parent identities", content)

    def test_help_signature(self) -> None:
        for command in ((), ("extract",), ("locate",), ("inventory",), ("report",)):
            result = self.cli(*command, "--help")
            self.assertEqual(result.returncode, 0)
            self.assertEqual(result.stdout.strip().splitlines()[-1], "By Zero Width Lab (zerowidthlab.com)")


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

License: MIT (read it).

Back to the listing