Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions .github/scripts/audit_wheel.py
Original file line number Diff line number Diff line change
@@ -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())
6 changes: 6 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
7 changes: 7 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand Down
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<built-wheel>.whl
```

Replace `<built-wheel>` 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.
19 changes: 19 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<built-wheel>.whl
```

将 `<built-wheel>` 替换为实际生成的文件名。只读审计会将 Python 模块的路径和字节内容
与 `src/` 比对,并按打包合同独立检查查询 YAML、内置技能、snapshot 许可证及来源记录
资源,允许构建后端生成的分发元数据。发现不匹配时会失败并列出具体路径;请从全新源码树
重新构建并再次审计,通过后再使用 wheel。CI 在安装包验收前审计 wheel;release 会独立
审计实际上传用于发布的 wheel。
3 changes: 3 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]

Expand Down
194 changes: 194 additions & 0 deletions tests/test_wheel_audit.py
Original file line number Diff line number Diff line change
@@ -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
Loading