1panel-toolkit 0.3.0__py3-none-any.whl

p1toolkit/checks/structure.py

@@ -0,0 +1,140 @@
+"""Package structure: data.yml layout, required metadata, version dirs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .. import rules
+from ..model import Package
+from ..report import Report
+
+
+def run(package: Package, report: Report, strict: bool = False) -> None:
+    assets(package, report)
+    store = rules.store()
+    allowed = set(store.get("root_allowed_keys") or [])
+    warn_keys = set(store.get("root_warn_keys") or [])
+    required = list(store.get("root_required_additional") or [])
+    recommended = list(store.get("root_recommended_additional") or [])
+
+    root_keys = set(package.app)
+    for key in sorted(root_keys - allowed):
+        if key in warn_keys:
+            report.warn(
+                "P001",
+                f"root data.yml has non-standard top-level key {key!r}",
+                "data.yml",
+            )
+        else:
+            report.fail(
+                "P001",
+                f"root data.yml has unsupported top-level key {key!r}",
+                "data.yml",
+            )
+    for key in sorted(allowed - root_keys):
+        if key != "tags":
+            report.warn("P002", f"root data.yml is missing top-level {key!r}", "data.yml")
+
+    additional = package.additional
+    for key in required:
+        if key not in additional:
+            report.fail("P003", f"root additionalProperties.{key} is required", "data.yml")
+    for key in recommended:
+        if key not in additional:
+            report.warn(
+                "P004", f"root additionalProperties.{key} is recommended", "data.yml"
+            )
+
+    architectures = additional.get("architectures")
+    if architectures is not None and not (
+        isinstance(architectures, list) and architectures
+    ):
+        report.fail(
+            "P005",
+            "additionalProperties.architectures must be a non-empty list",
+            "data.yml",
+        )
+
+    tags = additional.get("tags")
+    if tags:
+        allowed_tags = rules.allowed_tags()
+        unknown = [t for t in tags if t not in allowed_tags]
+        if unknown:
+            report.warn(
+                "P006",
+                f"additionalProperties.tags not seen in the store survey: {unknown} "
+                "(allowed if intentional, but check for a typo or a localized value)",
+                "data.yml",
+            )
+
+    app_type = additional.get("type")
+    if app_type and str(app_type) not in set(store.get("app_types") or []):
+        report.warn(
+            "P007",
+            f"additionalProperties.type {app_type!r} is outside the documented set "
+            f"{store.get('app_types')}",
+            "data.yml",
+        )
+
+    if not package.versions:
+        report.fail(
+            "P010",
+            "no version directory found (expected e.g. 'latest/' with docker-compose.yml)",
+        )
+        return
+
+    version_allowed = set(store.get("version_allowed_keys") or [])
+    for version in package.versions:
+        label = f"{version.name}/data.yml"
+        if not version.dir.joinpath("data.yml").exists():
+            report.fail("P011", f"{version.name}/ is missing data.yml", label)
+        if not version.compose_text:
+            report.fail(
+                "P012", f"{version.name}/ is missing docker-compose.yml", label
+            )
+        extra = set(version.data) - version_allowed
+        if extra:
+            report.fail(
+                "P013",
+                f"{label} has unsupported top-level keys: {sorted(extra)}",
+                label,
+            )
+        if isinstance(version.data.get("formFields"), list):
+            report.fail(
+                "P014",
+                f"{label} declares formFields at the top level; it belongs under additionalProperties",
+                label,
+            )
+        if "architectures" in version.data or "architectures" in version.additional:
+            report.fail(
+                "P015",
+                f"{label} must not declare architectures (root data.yml owns it)",
+                label,
+            )
+        if not version.form_fields:
+            report.warn("P016", f"{label} declares no formFields", label)
+
+
+def assets(package: Package, report: Report) -> None:
+    """Logo check lives separately so tests can call it in isolation."""
+    logo = package.root / "logo.png"
+    if not logo.exists():
+        report.fail("P020", "logo.png is missing", "logo.png")
+        return
+    size = _png_size(logo)
+    if size is None:
+        report.warn("P021", "logo.png is not a readable PNG", "logo.png")
+        return
+    if size != (180, 180):
+        report.warn(
+            "P022",
+            f"logo.png is {size[0]}x{size[1]}; the store default is 180x180",
+            "logo.png",
+        )
+
+
+def _png_size(path: Path) -> tuple[int, int] | None:
+    raw = path.read_bytes()[:24]
+    if len(raw) < 24 or raw[:8] != b"\x89PNG\r\n\x1a\n":
+        return None
+    return int.from_bytes(raw[16:20], "big"), int.from_bytes(raw[20:24], "big")

p1toolkit/checks/substance.py

@@ -0,0 +1,55 @@
+"""Substance checks: does this package look adapted, or just reskinned?
+
+These are the cheap, corpus-free half of ``p1 depth``. They catch the package
+that was generated by filling a template and never thinking about the app.
+"""
+
+from __future__ import annotations
+
+from ..depth import profile_app
+from ..model import Package
+from ..report import Report
+
+
+def run(package: Package, report: Report, strict: bool = False) -> None:
+    profile = profile_app(package.root)
+    if profile is None:
+        return
+
+    if not profile.app_env_keys:
+        report.warn(
+            "S001",
+            "compose 里没有任何应用自有环境变量；官方语料里平均每个应用有 6 个，"
+            "确认这个应用是真的不需要配置，还是照模板填的",
+            "docker-compose.yml",
+        )
+    if not profile.mount_targets:
+        report.warn(
+            "S002",
+            "compose 里没有任何持久化挂载；除非应用确实无状态，否则卸载/升级会丢数据",
+            "docker-compose.yml",
+        )
+    # A package that ships source evidence had its ports traced back to an
+    # upstream file, so "looks like a template default" would be noise.
+    traced = (package.root / "source-evidence.json").exists()
+    if (
+        profile.port_pairs
+        and not traced
+        and not any(
+            port not in {"80", "8080", "3000", "8000", "5000"}
+            for port in profile.port_pairs
+        )
+    ):
+        report.warn(
+            "S003",
+            f"容器内端口是常见模板默认值 {profile.port_pairs}；"
+            "官方语料里这个维度有 359 种取值，请回到上游 EXPOSE / 官方 compose 核对",
+            "docker-compose.yml",
+        )
+    if profile.services == 1 and not profile.high_signal_keys:
+        report.info(
+            "S004",
+            "没有使用任何上游特有的运行时字段（security_opt / user / cap_add 等）；"
+            "87% 的单服务应用也确实如此，仅供参考",
+            "docker-compose.yml",
+        )