372 lines
15 KiB
Python
Executable File
372 lines
15 KiB
Python
Executable File
#!/usr/bin/env python3
|
||
"""Executable form of the builder contract (references/contract.md).
|
||
|
||
Checks a project's Makefile against the contract by probing make itself with
|
||
dry runs (`make -n`) instead of parsing Makefile text: includes, conditionals,
|
||
and variable expansion are resolved by make, so behavior is what gets judged.
|
||
|
||
Usage:
|
||
python3 -I -S check.py <project-dir> [--build]
|
||
|
||
Exit codes: 0 = all PASS, 1 = at least one FAIL, 2 = usage/environment error.
|
||
|
||
Change the contract here first, then mirror the change into contract.md.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import hashlib
|
||
import re
|
||
import shutil
|
||
import subprocess
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
ARCH_VALUES = ("amd64", "arm64")
|
||
REQUIRED_TARGETS = ("help", "version", "clean", "build")
|
||
UPLOAD_TOKENS = (
|
||
"curl ", "curl\t", "scp ", "rsync ", "aptly ", "reprepro ",
|
||
"docker push", "buildx build --push", "buildx --push", "upload_deb.sh",
|
||
"publish_docker.sh",
|
||
)
|
||
SECRET_PATTERNS = (
|
||
re.compile(r"(TOKEN|PASSWORD|SECRET|API_KEY|PASSWD)[A-Z_]*\s*[:?]?=\s*['\"]?[^\s$({\"']+", re.IGNORECASE),
|
||
re.compile(r"\b[A-Za-z0-9_]*token[A-Za-z0-9_]*\s*[:?]?=\s*['\"]?[A-Za-z0-9._\-]{16,}", re.IGNORECASE),
|
||
)
|
||
FLOATING_TAGS = (":latest", ":stable")
|
||
DEB_SHAPE = re.compile(r"^[^_\s]+_[^_\s]+_[^_\s]+\.deb$")
|
||
VALID_SCRIPT_NAMES = ("upload_deb.sh", "publish_docker.sh")
|
||
|
||
PASS = "PASS"
|
||
FAIL = "FAIL"
|
||
SKIP = "SKIP"
|
||
|
||
|
||
class Report:
|
||
def __init__(self) -> None:
|
||
self.failures = 0
|
||
self.skips = 0
|
||
|
||
def add(self, status: str, number: int, title: str, detail: str) -> None:
|
||
print(f"[{status}] {number}. {title}")
|
||
for line in detail.splitlines():
|
||
print(f" {line}")
|
||
if status == FAIL:
|
||
self.failures += 1
|
||
elif status == SKIP:
|
||
self.skips += 0 if self.skips else 1
|
||
|
||
|
||
def run_make(project: Path, *args: str, timeout: int = 60) -> subprocess.CompletedProcess[str]:
|
||
return subprocess.run(
|
||
["make", "-C", str(project), "-n", *args],
|
||
capture_output=True, text=True, timeout=timeout, check=False,
|
||
)
|
||
|
||
|
||
def has_no_rule(result: subprocess.CompletedProcess[str]) -> bool:
|
||
return result.returncode != 0 and (
|
||
"No rule to make target" in result.stderr or "no rule to make target" in result.stderr.lower()
|
||
)
|
||
|
||
|
||
BANNER_RE = re.compile(r"^make(?:\[[0-9]+\])?: (进入|离开|Entering|Leaving)")
|
||
|
||
|
||
def clean_make_output(result: subprocess.CompletedProcess[str]) -> list[str]:
|
||
"""Drop make directory banners and dry-run command echoes, keep real output."""
|
||
lines = []
|
||
for line in result.stdout.splitlines():
|
||
if BANNER_RE.match(line.strip()):
|
||
continue
|
||
stripped = line.lstrip()
|
||
if stripped.startswith(("echo ", "echo\t", "printf ")):
|
||
continue
|
||
lines.append(line)
|
||
return lines
|
||
|
||
|
||
def check_required_targets(report: Report, project: Path) -> dict[str, bool]:
|
||
present: dict[str, bool] = {}
|
||
lines = []
|
||
for target in REQUIRED_TARGETS:
|
||
result = run_make(project, target)
|
||
ok = result.returncode == 0
|
||
present[target] = ok
|
||
lines.append(f"{target}: {'found' if ok else 'missing'}")
|
||
report.add(PASS if all(present.values()) else FAIL, 1, "必备目标存在（help/version/clean/build）", "\n".join(lines))
|
||
return present
|
||
|
||
|
||
def check_arch_guard(report: Report, project: Path) -> None:
|
||
bad = run_make(project, "build", "ARCH=loongarch")
|
||
guard_ok = bad.returncode != 0 and ("amd64" in bad.stderr or "arm64" in bad.stderr)
|
||
default_ok = run_make(project, "build").returncode == 0
|
||
lines = [
|
||
f"invalid ARCH rejected: {'yes' if guard_ok else 'NO'}",
|
||
f"default ARCH works: {'yes' if default_ok else 'no'}",
|
||
]
|
||
hint = "" if guard_ok else "\n Hint: add `$(error ARCH must be amd64 or arm64)` guarded by an ifneq filter."
|
||
if guard_ok and default_ok:
|
||
report.add(PASS, 2, "ARCH 守卫与缺省值", "\n".join(lines + hint.splitlines()))
|
||
else:
|
||
report.add(FAIL, 2, "ARCH 守卫与缺省值", "\n".join(lines) + hint)
|
||
|
||
|
||
def check_version_output(report: Report, project: Path) -> None:
|
||
result = run_make(project, "version")
|
||
# Dry run: the echoed `@echo <version>` line IS the would-be output.
|
||
out_lines = [ln.lstrip()[5:] for ln in result.stdout.splitlines() if ln.lstrip().startswith("echo ")]
|
||
out = "\n".join(out_lines).strip()
|
||
single = len(out.splitlines()) == 1 and out != ""
|
||
no_v = single and not out.startswith("v")
|
||
detail = f"stdout={out!r}"
|
||
if single and not no_v:
|
||
detail += "\ncanonical version must not start with 'v'"
|
||
report.add(
|
||
PASS if no_v else FAIL,
|
||
3,
|
||
"version 输出一行非空规范版本（无 v 前缀）",
|
||
detail,
|
||
)
|
||
|
||
|
||
def check_build_has_no_upload(report: Report, project: Path) -> None:
|
||
result = run_make(project, "build")
|
||
text = chr(10).join(clean_make_output(result))
|
||
hits = [token for token in UPLOAD_TOKENS if token in text]
|
||
report.add(
|
||
PASS if not hits else FAIL,
|
||
4,
|
||
"build 不含上传动作",
|
||
"clean" if not hits else "found upload commands in build recipe:\n " + ", ".join(hits),
|
||
)
|
||
|
||
|
||
def detect_deb_project(recipe_all: str, project: Path) -> bool:
|
||
return ".deb" in recipe_all or "dpkg-deb" in recipe_all or "debuild" in recipe_all or any(project.glob("debian/*"))
|
||
|
||
|
||
def check_deb_recipe(report: Report, project: Path, built_deb: Path | None) -> None:
|
||
dry = run_make(project, "deb")
|
||
text = chr(10).join(clean_make_output(dry))
|
||
problems = []
|
||
if dry.returncode != 0:
|
||
problems.append(f"`make -n deb` failed: {dry.stderr.strip() or 'unknown error'}")
|
||
else:
|
||
if "dist/" not in text and "$(DIST_DIR)" not in text:
|
||
problems.append("recipe does not reference dist/ ($(DIST_DIR)) as artifact location")
|
||
hits = [token for token in UPLOAD_TOKENS if token in text]
|
||
if hits:
|
||
problems.append("recipe contains upload commands: " + ", ".join(hits))
|
||
if "rm -rf /" in text or "rm -rf ~" in text:
|
||
problems.append("recipe contains unrestricted rm -rf")
|
||
if built_deb is not None:
|
||
shape_ok = DEB_SHAPE.match(built_deb.name) is not None
|
||
if not shape_ok:
|
||
problems.append(f"artifact name does not match <name>_<version>_<arch>.deb: {built_deb.name}")
|
||
dpkg = shutil.which("dpkg-deb")
|
||
if dpkg:
|
||
info = subprocess.run([dpkg, "--field", str(built_deb), "Package"], capture_output=True, text=True, check=False)
|
||
if info.returncode != 0 or not info.stdout.strip():
|
||
problems.append(f"dpkg-deb --info failed on {built_deb.name}")
|
||
else:
|
||
problems.append("dpkg-deb unavailable; metadata not verified (--build)")
|
||
if problems:
|
||
report.add(FAIL, 5, "deb 目标产物形状与纯构建", "\n".join(problems))
|
||
else:
|
||
extra = f"\nartifact: {built_deb.name}" if built_deb else "\n(static recipe check only; run --build to verify real artifact)"
|
||
report.add(PASS, 5, "deb 目标产物形状与纯构建", extra.lstrip("\n"))
|
||
|
||
|
||
def detect_docker_project(project: Path) -> bool:
|
||
return (project / "Dockerfile").exists() or (project / "docker-compose.yaml").exists()
|
||
|
||
|
||
def check_docker_recipe(report: Report, project: Path) -> None:
|
||
dry = run_make(project, "docker")
|
||
text = chr(10).join(clean_make_output(dry))
|
||
if has_no_rule(dry):
|
||
report.add(SKIP, 6, "docker 目标为本地单平台构建", "(no docker target)")
|
||
return
|
||
problems = []
|
||
if "--push" in text or " docker push" in text or "docker push\n" in text:
|
||
problems.append("make docker must be local-only; pushing belongs to publish_docker.sh")
|
||
if "--platform" in text and "," in text.split("--platform")[1][:80].split()[0]:
|
||
problems.append("make docker must stay single-platform; multi-platform belongs to publish_docker.sh")
|
||
report.add(FAIL if problems else PASS, 6, "docker 目标为本地单平台构建", "\n".join(problems) or "local single-platform build")
|
||
|
||
|
||
SCRIPT_RESOLVE_SNIPPETS = tuple(
|
||
f"{prefix}{name}"
|
||
for prefix in (
|
||
"$$BUILDER_SKILL_DIR",
|
||
"$BUILDER_SKILL_DIR",
|
||
"$$HOME/.pouch/skills/builder/scripts",
|
||
"$HOME/.pouch/skills/builder/scripts",
|
||
"~/.pouch/skills/builder/scripts",
|
||
"$$HOME/.skills/skills/builder/scripts",
|
||
"$HOME/.skills/skills/builder/scripts",
|
||
"~/.skills/skills/builder/scripts",
|
||
)
|
||
for name in VALID_SCRIPT_NAMES
|
||
)
|
||
|
||
|
||
def check_push_delegates(report: Report, project: Path, dual_artifact: bool) -> None:
|
||
targets = ("push-deb", "push-docker") if dual_artifact else ("push",)
|
||
missing = []
|
||
inline = []
|
||
thin = []
|
||
for target in targets:
|
||
dry = run_make(project, target)
|
||
if has_no_rule(dry):
|
||
missing.append(target)
|
||
continue
|
||
text = chr(10).join(clean_make_output(dry))
|
||
bad_tokens = [token for token in ("curl ", "scp ", "aptly ", "reprepro ") if token in text]
|
||
if bad_tokens:
|
||
inline.append(f"{target}: inline upload command ({', '.join(bad_tokens)})")
|
||
elif not any(snippet in text for snippet in SCRIPT_RESOLVE_SNIPPETS) \
|
||
and "$(BUILDER_SCRIPT)" not in text and "upload_deb.sh" not in text \
|
||
and "publish_docker.sh" not in text:
|
||
inline.append(f"{target}: does not call a builder script (expected $BUILDER_SKILL_DIR/... or ~/.pouch/... path)")
|
||
else:
|
||
thin.append(target)
|
||
problems = []
|
||
if missing:
|
||
problems.append("missing targets: " + ", ".join(missing))
|
||
problems.extend(inline)
|
||
status = PASS if not problems else FAIL
|
||
detail = "\n".join(problems) if problems else "thin wrappers: " + ", ".join(thin)
|
||
report.add(status, 7, "push 仅委托 builder 脚本（薄包装）", detail)
|
||
|
||
|
||
def check_secrets_and_tags(report: Report, project: Path) -> None:
|
||
makefile = project / "Makefile"
|
||
included_text = ""
|
||
problems = []
|
||
files = [makefile]
|
||
if makefile.exists():
|
||
for match in re.finditer(r"^include\s+(.+)$", makefile.read_text(encoding="utf-8"), re.MULTILINE):
|
||
inc = (project / match.group(1).strip()).resolve()
|
||
if inc.is_file():
|
||
files.append(inc)
|
||
for file in files:
|
||
text = file.read_text(encoding="utf-8")
|
||
rel = file.relative_to(project) if file.is_relative_to(project) else file
|
||
for pattern in SECRET_PATTERNS:
|
||
for hit in pattern.finditer(text):
|
||
problems.append(f"{rel}: possible hardcoded secret near `{hit.group(0)[:40]}...`")
|
||
for tag in FLOATING_TAGS:
|
||
for line in text.splitlines():
|
||
stripped = line.split("#", 1)[0]
|
||
if tag in stripped:
|
||
problems.append(f"{rel}: implicit floating tag `{tag}` in: {stripped.strip()[:70]}")
|
||
report.add(FAIL if problems else PASS, 8, "无内联机密、无隐式 latest/stable", "\n".join(problems) or "clean")
|
||
|
||
|
||
def check_script_paths(report: Report) -> None:
|
||
import os
|
||
|
||
candidates = []
|
||
env_dir = os.environ.get("BUILDER_SKILL_DIR")
|
||
if env_dir:
|
||
candidates.append(Path(env_dir) / "scripts")
|
||
home = Path(os.environ.get("HOME", ""))
|
||
candidates.append(home / ".pouch" / "skills" / "builder" / "scripts")
|
||
candidates.append(home / ".skills" / "skills" / "builder" / "scripts")
|
||
found = next((c for c in candidates if c.is_dir() and any((c / n).is_file() for n in VALID_SCRIPT_NAMES)), None)
|
||
if found:
|
||
report.add(PASS, 9, "builder 脚本路径可达", str(found))
|
||
else:
|
||
report.add(FAIL, 9, "builder 脚本路径可达", "\n".join([
|
||
"none of these resolve to scripts/upload_deb.sh:",
|
||
*(f" {c}" for c in candidates),
|
||
"Fix: set BUILDER_SKILL_DIR, or clone the pouch repo to ~/.pouch.",
|
||
]))
|
||
|
||
|
||
def build_project(project: Path) -> Path | None:
|
||
"""Run `make deb` for real and return the produced .deb, or None."""
|
||
result = subprocess.run(["make", "-C", str(project), "deb"], capture_output=True, text=True, timeout=1800, check=False)
|
||
if result.returncode != 0:
|
||
print(f"--build: `make deb` failed:\n{result.stderr[-2000:]}", file=sys.stderr)
|
||
return None
|
||
debs = sorted((p for p in (project / "dist").glob("*.deb") if p.is_file()), key=lambda p: p.stat().st_mtime, reverse=True)
|
||
return debs[0] if debs else None
|
||
|
||
|
||
def main(argv: list[str] | None = None) -> int:
|
||
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
||
parser.add_argument("project", type=Path, help="project directory containing the Makefile")
|
||
parser.add_argument("--build", action="store_true", help="actually run `make deb` and verify the artifact")
|
||
args = parser.parse_args(argv)
|
||
|
||
project = args.project.resolve()
|
||
makefile = project / "Makefile"
|
||
if not makefile.is_file():
|
||
print(f"Error: no Makefile in {project}", file=sys.stderr)
|
||
return 2
|
||
if shutil.which("make") is None:
|
||
print("Error: make is required.", file=sys.stderr)
|
||
return 2
|
||
|
||
report = Report()
|
||
|
||
# Gather every recipe once via dry-running all known targets (best effort).
|
||
recipe_all_parts = []
|
||
for target in (*REQUIRED_TARGETS, "deb", "docker", "push", "push-deb", "push-docker"):
|
||
result = run_make(project, target)
|
||
if result.returncode == 0:
|
||
recipe_all_parts.append(result.stdout)
|
||
recipe_all = "\n".join(recipe_all_parts)
|
||
|
||
present = check_required_targets(report, project)
|
||
|
||
built_deb: Path | None = None
|
||
deb_project = detect_deb_project(recipe_all, project)
|
||
docker_project = detect_docker_project(project)
|
||
|
||
if present["build"]:
|
||
check_arch_guard(report, project)
|
||
check_version_output(report, project)
|
||
check_build_has_no_upload(report, project)
|
||
else:
|
||
report.add(SKIP, 2, "ARCH 守卫与缺省值", "(build target missing)")
|
||
report.add(SKIP, 3, "version 输出一行非空规范版本（无 v 前缀）", "(version target missing)")
|
||
report.add(SKIP, 4, "build 不含上传动作", "(build target missing)")
|
||
|
||
if deb_project:
|
||
if args.build:
|
||
print("--build: running `make deb` ...")
|
||
built_deb = build_project(project)
|
||
if built_deb is None:
|
||
print("--build: no .deb produced; artifact checks degrade to recipe-only.", file=sys.stderr)
|
||
check_deb_recipe(report, project, built_deb)
|
||
else:
|
||
report.add(SKIP, 5, "deb 目标产物形状与纯构建", "(not a DEB project)")
|
||
|
||
if docker_project:
|
||
check_docker_recipe(report, project)
|
||
else:
|
||
report.add(SKIP, 6, "docker 目标为本地单平台构建", "(no Dockerfile)")
|
||
|
||
dual = deb_project and docker_project
|
||
check_push_delegates(report, project, dual)
|
||
check_secrets_and_tags(report, project)
|
||
check_script_paths(report)
|
||
|
||
total_fail = report.failures
|
||
print()
|
||
if total_fail:
|
||
print(f"RESULT: FAILED ({total_fail} check(s) failed)")
|
||
return 1
|
||
print("RESULT: PASSED")
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(main())
|