From 029715301f2cca7f056505e4fd3e7a339d4bd381 Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 3 Oct 2026 21:43:58 +0800 Subject: [PATCH] fix(packaging): audit built wheels against current source --- .github/scripts/audit_wheel.py | 91 ++++++++++++++++ .github/workflows/release.yml | 6 + .github/workflows/test.yml | 7 ++ README.md | 22 ++++ README_zh.md | 19 ++++ pyproject.toml | 3 + tests/test_wheel_audit.py | 194 +++++++++++++++++++++++++++++++++ 7 files changed, 342 insertions(+) create mode 100644 .github/scripts/audit_wheel.py create mode 100644 tests/test_wheel_audit.py diff --git a/.github/scripts/audit_wheel.py b/.github/scripts/audit_wheel.py new file mode 100644 index 0000000..ddca288 --- /dev/null +++ b/.github/scripts/audit_wheel.py @@ -0,0 +1,91 @@ +"""Read-only wheel/source comparison; never import or extract wheel contents.""" + +from __future__ import annotations + +import argparse +import sys +from collections import Counter +from pathlib import Path, PurePosixPath +from zipfile import BadZipFile, ZipFile + +# Keep aligned with [tool.setuptools.package-data] in pyproject.toml. +RESOURCE_GLOBS = ( + "query/templates/*.yaml", + "query/templates/*/*.yaml", + "bundled_skills/**/*", + "snapshot/LICENSE", + "snapshot/PROVENANCE.md", +) + + +def _is_resource(name: str) -> bool: + return ( + (name.startswith("pt_snap_cli/query/templates/") and name.endswith(".yaml")) + or name.startswith("pt_snap_cli/bundled_skills/") + or name in {"pt_snap_cli/snapshot/LICENSE", "pt_snap_cli/snapshot/PROVENANCE.md"} + ) + + +def audit_wheel(wheel: Path, source: Path) -> list[str]: + """Compare Python modules and contracted resources to the supplied src tree.""" + package = source / "pt_snap_cli" + if not (package / "__init__.py").is_file(): + raise ValueError(f"Expected source package at {package}") + modules = {path.relative_to(source).as_posix(): path for path in package.rglob("*.py")} + resources = { + path.relative_to(source).as_posix(): path + for pattern in RESOURCE_GLOBS + for path in package.glob(pattern) + if path.is_file() + } + errors: list[str] = [] + with ZipFile(wheel) as archive: + names = [info.filename for info in archive.infolist() if not info.is_dir()] + for name, count in sorted(Counter(names).items()): + if count > 1: + errors.append(f"Duplicate wheel member: {name}") + # Distribution metadata (including licenses) is generated by the backend, + # not copied one-to-one from src. Other non-contract data may ship via SCM. + actual_modules = { + name + for name in names + if name.endswith(".py") and not PurePosixPath(name).parts[0].endswith(".dist-info") + } + actual_resources = {name for name in names if _is_resource(name)} + for label, expected, actual in ( + ("Python module", modules, actual_modules), + ("resource", resources, actual_resources), + ): + for name in sorted(actual - expected.keys()): + errors.append(f"Unexpected {label}: {name}") + for name in sorted(expected.keys() - actual): + errors.append(f"Missing {label}: {name}") + for name in sorted(expected.keys() & actual): + if archive.read(name) != expected[name].read_bytes(): + errors.append(f"Content mismatch for {label}: {name}") + return errors + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--wheel", required=True, type=Path) + parser.add_argument("--source", type=Path, default=Path(__file__).resolve().parents[2] / "src") + args = parser.parse_args() + try: + errors = audit_wheel(args.wheel, args.source) + except (OSError, ValueError, BadZipFile) as exc: + errors = [str(exc)] + if errors: + print("Wheel audit failed:\n" + "\n".join(errors), file=sys.stderr) + print( + "Rebuild from a fresh checkout/worktree; inspect build/lib for stale files. " + "No files were modified by this audit.", + file=sys.stderr, + ) + return 1 + print(f"Wheel audit passed: {args.wheel}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c8d8feb..f84f2fb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -31,6 +31,12 @@ jobs: - name: Build sdist and wheel run: python -m build + - name: Audit wheel contents against source + run: | + set -euo pipefail + WHEEL=$(python -c 'from pathlib import Path; wheels = sorted(Path("dist").glob("*.whl")); assert len(wheels) == 1, wheels; print(wheels[0])') + python .github/scripts/audit_wheel.py --wheel "$WHEEL" + - name: Verify built package version matches tag run: | TAG=${GITHUB_REF#refs/tags/v} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 5cdd27b..706afb4 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -121,6 +121,13 @@ jobs: python -m pip install --upgrade build python -m build --wheel + - name: Audit wheel contents against source + if: matrix.python-version == '3.13' + run: | + set -euo pipefail + WHEEL=$(python -c 'from pathlib import Path; wheels = sorted(Path("dist").glob("*.whl")); assert len(wheels) == 1, wheels; print(wheels[0])') + python .github/scripts/audit_wheel.py --wheel "$WHEEL" + - name: Clean-wheel Agent acceptance if: matrix.python-version == '3.13' run: | diff --git a/README.md b/README.md index 1ec60f8..47d134c 100644 --- a/README.md +++ b/README.md @@ -98,5 +98,27 @@ See the [documentation index](docs/README.md) for all English and Chinese guides pip install -e ".[dev]" # Install development dependencies pytest # Run all tests black --check . && ruff check . # Check formatting and lint +``` + +### Building distributions + +Build from a fresh checkout or a new worktree at the intended commit, with no +existing `build/` or `dist/` directories. Setuptools can reuse files in `build/lib` +on repeated builds, including modules deleted from the source tree; build dependency +isolation does not clean these intermediates. Inspect old outputs before removing +them yourself, or use a fresh worktree instead. + +From that checkout's root: + +```bash python -m build # Build sdist and wheel +python .github/scripts/audit_wheel.py --wheel dist/.whl ``` + +Replace `` with the generated filename. The read-only audit compares +Python module paths and bytes with `src/`, and separately checks query YAML, +bundled skills, and snapshot license/provenance resources against the packaging +contract. Generated distribution metadata is allowed. A mismatch fails with the +affected paths; rebuild from a fresh source tree and audit again before using the +wheel. CI audits its wheel before installed-package acceptance; release separately +audits the actual wheel it uploads for publication. diff --git a/README_zh.md b/README_zh.md index 49661a6..0375ce1 100644 --- a/README_zh.md +++ b/README_zh.md @@ -92,5 +92,24 @@ helper 会先路由采集,无需先安装 CLI。分析仍需要 CLI 和 Snapsh pip install -e ".[dev]" # 安装开发依赖 pytest # 运行所有测试 black --check . && ruff check . # 检查格式和 lint +``` + +### 构建分发包 + +请从目标提交的全新 checkout 或新 worktree 构建,确保没有已有的 `build/` 和 +`dist/` 目录。重复构建时,setuptools 可能复用 `build/lib` 中的文件,包括源码中 +已删除的模块;构建依赖隔离不会清理这些中间产物。自行删除旧产物前请先检查其内容, +也可以直接使用全新 worktree。 + +在该 checkout 的根目录运行: + +```bash python -m build # 构建 sdist 和 wheel +python .github/scripts/audit_wheel.py --wheel dist/.whl ``` + +将 `` 替换为实际生成的文件名。只读审计会将 Python 模块的路径和字节内容 +与 `src/` 比对,并按打包合同独立检查查询 YAML、内置技能、snapshot 许可证及来源记录 +资源,允许构建后端生成的分发元数据。发现不匹配时会失败并列出具体路径;请从全新源码树 +重新构建并再次审计,通过后再使用 wheel。CI 在安装包验收前审计 wheel;release 会独立 +审计实际上传用于发布的 wheel。 diff --git a/pyproject.toml b/pyproject.toml index a999f7f..de01e4c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,6 +42,9 @@ dev = [ "black>=23.0.0", "ruff>=0.0.280", "build>=1.0.0", + # Offline regression tests exercise repeated builds with the real backend. + "setuptools>=61.0", + "wheel", "basedpyright>=1.39.3", ] diff --git a/tests/test_wheel_audit.py b/tests/test_wheel_audit.py new file mode 100644 index 0000000..15bb04c --- /dev/null +++ b/tests/test_wheel_audit.py @@ -0,0 +1,194 @@ +from __future__ import annotations + +import importlib.util +import subprocess +import sys +from pathlib import Path +from zipfile import ZipFile + +import pytest +import yaml + +AUDIT_PATH = Path(__file__).resolve().parents[1] / ".github/scripts/audit_wheel.py" + + +@pytest.fixture +def audit(): + spec = importlib.util.spec_from_file_location("audit_wheel", AUDIT_PATH) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module.audit_wheel + + +@pytest.fixture +def source(tmp_path): + root = tmp_path / "src" + for name, content in { + "__init__.py": b"", + "current.py": b"VALUE = 1\n", + "query/templates/root.yaml": b"name: root\n", + "query/templates/memory/current.yaml": b"name: current\n", + "bundled_skills/example/SKILL.md": b"# Skill\n", + "snapshot/LICENSE": b"MIT\n", + "snapshot/PROVENANCE.md": b"Evidence\n", + }.items(): + path = root / "pt_snap_cli" / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(content) + return root + + +def _wheel(source, path, *, changed=None, missing=()): + entries = { + file.relative_to(source).as_posix(): file.read_bytes() + for file in source.rglob("*") + if file.is_file() + } + entries.update( + { + "pt_snap_cli-1.0.dist-info/METADATA": b"Name: pt-snap-cli\nVersion: 1.0\n", + "pt_snap_cli-1.0.dist-info/licenses/LICENSE": b"MIT\n", + "pt_snap_cli/AGENTS.md": b"SCM-included documentation\n", + } + ) + entries.update(changed or {}) + with ZipFile(path, "w") as archive: + for name, content in entries.items(): + if name not in missing: + archive.writestr(name, content) + return path + + +def test_clean_wheel_allows_generated_metadata_and_scm_documentation(audit, source, tmp_path): + wheel = _wheel(source, tmp_path / "clean.whl") + before = wheel.read_bytes() + assert audit(wheel, source) == [] + assert wheel.read_bytes() == before + + +@pytest.mark.parametrize( + "name", + [ + "pt_snap_cli/arbitrary_retired.py", + "pt_snap_cli/old_package/__init__.py", + "unrelated_package/deleted.py", + ], +) +def test_extra_python_modules_are_rejected_without_a_name_blacklist(audit, source, tmp_path, name): + wheel = _wheel(source, tmp_path / "dirty.whl", changed={name: b"raise RuntimeError\n"}) + before = wheel.read_bytes() + assert audit(wheel, source) == [f"Unexpected Python module: {name}"] + assert wheel.read_bytes() == before + + +@pytest.mark.parametrize( + ("name", "label"), + [ + ("pt_snap_cli/current.py", "Python module"), + ("pt_snap_cli/query/templates/memory/current.yaml", "resource"), + ("pt_snap_cli/bundled_skills/example/SKILL.md", "resource"), + ("pt_snap_cli/snapshot/LICENSE", "resource"), + ("pt_snap_cli/snapshot/PROVENANCE.md", "resource"), + ], +) +def test_missing_and_changed_contract_files_fail(audit, source, tmp_path, name, label): + missing = _wheel(source, tmp_path / "missing.whl", missing=[name]) + assert audit(missing, source) == [f"Missing {label}: {name}"] + changed = _wheel(source, tmp_path / "changed.whl", changed={name: b"stale content"}) + assert audit(changed, source) == [f"Content mismatch for {label}: {name}"] + + +def test_stale_resource_and_duplicate_member_fail(audit, source, tmp_path): + name = "pt_snap_cli/query/templates/retired.yaml" + wheel = _wheel(source, tmp_path / "stale.whl", changed={name: b"old"}) + assert audit(wheel, source) == [f"Unexpected resource: {name}"] + with ZipFile(wheel, "a") as archive, pytest.warns(UserWarning, match="Duplicate name"): + archive.writestr(name, b"old") + assert audit(wheel, source) == [ + f"Duplicate wheel member: {name}", + f"Unexpected resource: {name}", + ] + + +def test_cli_reports_bad_artifact_and_invalid_source(source, tmp_path): + wheel = tmp_path / "invalid.whl" + wheel.write_bytes(b"not a zip") + for root, expected in ( + (source, "File is not a zip file"), + (tmp_path / "absent", "Expected source package"), + ): + result = subprocess.run( + [sys.executable, str(AUDIT_PATH), "--wheel", str(wheel), "--source", str(root)], + capture_output=True, + text=True, + ) + assert result.returncode == 1 + assert expected in result.stderr + assert "No files were modified" in result.stderr + + +def test_repeated_setuptools_build_rejects_arbitrary_build_lib_residue(audit, source, tmp_path): + # Exercise the real backend offline in a disposable project: no installation, + # SCM version lookup, dependency download, or alteration of the checkout. + (tmp_path / "pyproject.toml").write_text( + '[build-system]\nrequires = ["setuptools", "wheel"]\n' + 'build-backend = "setuptools.build_meta"\n' + '[project]\nname = "pt-snap-cli"\nversion = "1.0"\n' + '[tool.setuptools.packages.find]\nwhere = ["src"]\n' + "[tool.setuptools.package-data]\n" + 'pt_snap_cli = ["query/templates/*.yaml", "query/templates/*/*.yaml", ' + '"bundled_skills/**/*", "snapshot/LICENSE", "snapshot/PROVENANCE.md"]\n' + ) + + def build(directory): + result = subprocess.run( + [ + sys.executable, + "-c", + "from setuptools.build_meta import build_wheel; " + f"build_wheel({str(directory)!r})", + ], + cwd=tmp_path, + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stdout + result.stderr + return next(directory.glob("*.whl")) + + clean = build(tmp_path / "clean-dist") + assert audit(clean, source) == [] + stale = tmp_path / "build/lib/pt_snap_cli/unexpected_legacy/retired.py" + stale.parent.mkdir(parents=True) + stale.write_bytes(b"raise RuntimeError('must never execute')\n") + dirty = build(tmp_path / "dirty-dist") + result = subprocess.run( + [sys.executable, str(AUDIT_PATH), "--wheel", str(dirty), "--source", str(source)], + capture_output=True, + text=True, + ) + assert result.returncode == 1 + assert "Unexpected Python module: pt_snap_cli/unexpected_legacy/retired.py" in result.stderr + assert stale.read_bytes() == b"raise RuntimeError('must never execute')\n" + assert audit(clean, source) == [] + + +@pytest.mark.parametrize( + ("workflow", "job", "build", "next_step"), + [ + ("test.yml", "test", "Build wheel", "Clean-wheel Agent acceptance"), + ("release.yml", "build", "Build sdist and wheel", "Upload build artifacts"), + ], +) +def test_actual_built_wheel_is_audited_before_acceptance_or_upload(workflow, job, build, next_step): + path = Path(".github/workflows") / workflow + steps = yaml.load(path.read_text(), Loader=yaml.BaseLoader)["jobs"][job]["steps"] + names = [step.get("name") for step in steps] + index = names.index("Audit wheel contents against source") + assert names.index(build) < index < names.index(next_step) + audit_step = steps[index] + assert 'Path("dist").glob("*.whl")' in audit_step["run"] + assert "assert len(wheels) == 1" in audit_step["run"] + assert 'python .github/scripts/audit_wheel.py --wheel "$WHEEL"' in audit_step["run"] + assert audit_step.get("if") == steps[names.index(build)].get("if") + assert "continue-on-error" not in audit_step