:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
chore(hogli): make backend/checks.py the home for product system checks (#129835)
Rafael Audibert24909d2ee925
diff --git a/products/README.md b/products/README.mdindex f4b47a45b2bf..3950585fbd61 100644--- a/products/README.md+++ b/products/README.md@@ -22,6 +22,7 @@ products/backend/ # Django app__init__.pyapps.py+ checks.py # optional: Django system checks, imported from apps.py ready()models.pylogic.py # business logicroutes.py # API routes: register_routes(routers) + api_urlpatterns/webhook_urlpatterns, auto-discovered@@ -92,6 +93,15 @@ Use `bin/hogli product:bootstrap <name>` to scaffold a new product with this strThis avoids circular imports and keeps migrations/app labels stable.+- Put the product's Django system checks in `backend/checks.py`.+ A system check catches a wrong setting at startup instead of in user traffic.+ `hogli product:lint` enforces three rules:+ - `apps.py` `ready()` imports `backend/checks.py`. Django never runs a check whose module nobody imported.+ - No other product module registers a check.+ - Every check ID starts with `posthog.<product>.`, for example `posthog.canvas.E001`.++ Register each check with `register_check` from `posthog/checks.py`, which documents the ID scheme. `product:bootstrap` does not create the file.+## Frontend conventions- Each `frontend/` directory contains the frontend app for the product.diff --git a/tools/hogli-commands/hogli_commands/product/checks.py b/tools/hogli-commands/hogli_commands/product/checks.pyindex 4c2785430e09..a83647627423 100644--- a/tools/hogli-commands/hogli_commands/product/checks.py+++ b/tools/hogli-commands/hogli_commands/product/checks.py@@ -9,6 +9,7 @@ Progress/maturity scoring lives in maturity.py instead.from __future__ import annotationsimport re+import astimport jsonimport shleximport tomllib@@ -17,7 +18,7 @@ from collections.abc import Iteratorfrom dataclasses import dataclass, fieldfrom pathlib import Path-from .ast_helpers import module_import_targets+from .ast_helpers import ast_parse_safe, module_import_targetsfrom .crossings import driven_wiring_locations, facade_shape_use, facade_wiring_use, recorded_facade_shape_rowsfrom .isolation import (GARAGE_PREFIXES,@@ -1384,6 +1385,171 @@ class WatchedChannelsCheck(ProductCheck):return result+# A string shaped like a Django system check ID: dotted words, then a level letter and three digits.+_SYSTEM_CHECK_ID_RE = re.compile(r"^[A-Za-z_][\w.]*\.[A-Z]\d{3}$")+# Each module that registers system checks, mapped to its register function.+_REGISTER_FUNCTIONS = {"django.core.checks": "register", "posthog.checks": "register_check"}+++def _register_bindings(tree: ast.Module) -> tuple[set[str], dict[str, str]]:+ """Local names bound to a register function, and local module names mapped to their register function."""+ register_names: set[str] = set()+ module_names: dict[str, str] = {}+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom) and node.module:+ for alias in node.names:+ bound = alias.asname or alias.name+ if _REGISTER_FUNCTIONS.get(node.module) == alias.name:+ register_names.add(bound)+ elif (module := f"{node.module}.{alias.name}") in _REGISTER_FUNCTIONS:+ module_names[bound] = _REGISTER_FUNCTIONS[module]+ elif isinstance(node, ast.Import):+ for alias in node.names:+ if alias.name in _REGISTER_FUNCTIONS:+ module_names[alias.asname or alias.name] = _REGISTER_FUNCTIONS[alias.name]+ return register_names, module_names+++def _registers_system_check(tree: ast.Module) -> bool:+ """Whether the module registers a Django system check, through Django or posthog.checks."""+ register_names, module_names = _register_bindings(tree)++ def _is_register(func: ast.expr) -> bool:+ if isinstance(func, ast.Name):+ return func.id in register_names+ return isinstance(func, ast.Attribute) and module_names.get(ast.unparse(func.value)) == func.attr++ return any(+ (isinstance(node, ast.Call) and _is_register(node.func))+ or (+ isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)+ and any(_is_register(decorator) for decorator in node.decorator_list)+ )+ for node in ast.walk(tree)+ )+++def _system_check_ids(tree: ast.Module) -> list[str]:+ return sorted(+ {+ node.value+ for node in ast.walk(tree)+ if isinstance(node, ast.Constant) and isinstance(node.value, str) and _SYSTEM_CHECK_ID_RE.match(node.value)+ }+ )+++def _is_type_checking(test: ast.expr) -> bool:+ return (isinstance(test, ast.Name) and test.id == "TYPE_CHECKING") or (+ isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"+ )+++def _runtime_imports(statements: list[ast.stmt]) -> Iterator[ast.Import | ast.ImportFrom]:+ """Imports that run when the statements run: not in a nested def or class, or a type-checking-only branch."""+ for stmt in statements:+ if isinstance(stmt, ast.Import | ast.ImportFrom):+ yield stmt+ elif isinstance(stmt, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):+ continue+ elif isinstance(stmt, ast.If) and _is_type_checking(stmt.test):+ yield from _runtime_imports(stmt.orelse)+ elif (+ isinstance(stmt, ast.If)+ and isinstance(stmt.test, ast.UnaryOp)+ and isinstance(stmt.test.op, ast.Not)+ and _is_type_checking(stmt.test.operand)+ ):+ yield from _runtime_imports(stmt.body)+ else:+ for nested in ("body", "orelse", "finalbody"):+ yield from _runtime_imports(getattr(stmt, nested, []))+ for handler in getattr(stmt, "handlers", []):+ yield from _runtime_imports(handler.body)+++def _imports_checks_module(node: ast.Import | ast.ImportFrom, backend: str) -> bool:+ if isinstance(node, ast.Import):+ return any(alias.name == f"{backend}.checks" for alias in node.names)+ names = {alias.name for alias in node.names}+ if node.level == 0:+ return node.module == f"{backend}.checks" or (node.module == backend and "checks" in names)+ return node.level == 1 and (node.module == "checks" or (node.module is None and "checks" in names))+++def _ready_imports_checks(apps_path: Path, product: str) -> bool:+ """Whether an AppConfig.ready() in apps.py imports the product's backend/checks.py when it runs."""+ tree = ast_parse_safe(apps_path) if apps_path.exists() else None+ if tree is None:+ return False+ backend = f"products.{product}.backend"+ return any(+ _imports_checks_module(node, backend)+ for class_node in tree.body+ if isinstance(class_node, ast.ClassDef)+ for ready in class_node.body+ if isinstance(ready, ast.FunctionDef) and ready.name == "ready"+ for node in _runtime_imports(ready.body)+ )+++class SystemChecksCheck(ProductCheck):+ """A product's Django system checks live in backend/checks.py, which apps.py ready() imports.++ Django only runs a check whose module has been imported, so a check anywhere else, or a+ checks.py that ready() never imports, is silently never run. IDs follow the scheme in+ posthog/checks.py, with the product name as the area.+ """++ label = "system checks"++ @staticmethod+ def _misplaced_registrations(backend_dir: Path) -> list[str]:+ problems: list[str] = []+ for path in sorted(backend_dir.rglob("*.py")):+ rel = path.relative_to(backend_dir)+ if rel == Path("checks.py") or {"__pycache__", "test", "tests"}.intersection(rel.parts):+ continue+ if path.name.startswith("test_") or path.name.endswith("_test.py"):+ continue+ tree = ast_parse_safe(path)+ if tree is not None and _registers_system_check(tree):+ problems.append(+ f"backend/{rel.as_posix()} registers a Django system check: move it to backend/checks.py"+ )+ return problems++ @staticmethod+ def _checks_module_problems(ctx: CheckContext) -> list[str]:+ tree = ast_parse_safe(ctx.backend_dir / "checks.py")+ prefix = f"posthog.{ctx.name}."+ problems = [+ f"backend/checks.py uses check ID {check_id!r}, which must start with {prefix!r}"+ for check_id in (_system_check_ids(tree) if tree is not None else [])+ if not check_id.startswith(prefix)+ ]+ if not _ready_imports_checks(ctx.backend_dir / "apps.py", ctx.name):+ problems.append(+ "backend/checks.py is never imported by apps.py ready(), so Django never registers its checks"+ )+ return problems++ def run(self, ctx: CheckContext) -> CheckResult:+ if not ctx.backend_dir.exists():+ return CheckResult(skip=True)++ problems = self._misplaced_registrations(ctx.backend_dir)+ if (ctx.backend_dir / "checks.py").exists():+ problems.extend(self._checks_module_problems(ctx))++ if problems:+ return CheckResult(+ lines=[f"✗ {len(problems)} problem(s)"] + [f" → {p}" for p in problems],+ issues=problems,+ )+ return CheckResult(lines=["✓ ok"])++CHECKS: list[ProductCheck] = [ProductYamlCheck(),RequiredRootFilesCheck(),@@ -1398,4 +1564,5 @@ CHECKS: list[ProductCheck] = [WiringInterfaceCheck(),WatchedChannelsCheck(),OrphanedTestFilesCheck(),+ SystemChecksCheck(),]diff --git a/tools/hogli-commands/hogli_commands/product/scaffold.py b/tools/hogli-commands/hogli_commands/product/scaffold.pyindex e1ec9c7dff27..7b5b6b58fafa 100644--- a/tools/hogli-commands/hogli_commands/product/scaffold.py+++ b/tools/hogli-commands/hogli_commands/product/scaffold.py@@ -241,6 +241,8 @@ def bootstrap_product(skipped: list[str] = []for path, config in flatten_structure(structure.get("root_files", {})).items():+ if not config.get("scaffold", True):+ continuefile_path = product_dir / pathif dry_run:(skipped if (file_path.exists() and not force) else created).append(path)@@ -253,6 +255,8 @@ def bootstrap_product(created.append(path)for path, config in flatten_structure(structure.get("backend_files", {})).items():+ if not config.get("scaffold", True):+ continuefile_path = product_dir / "backend" / pathlabel = f"backend/{path}"if dry_run:diff --git a/tools/hogli-commands/hogli_commands/product_structure.yaml b/tools/hogli-commands/hogli_commands/product_structure.yamlindex 1913c2b0eeee..edcbe1a5f7e0 100644--- a/tools/hogli-commands/hogli_commands/product_structure.yaml+++ b/tools/hogli-commands/hogli_commands/product_structure.yaml@@ -6,6 +6,7 @@# required_lenient: bool - whether lint should warn if missing (in lenient mode)# can_be_folder: bool - whether file.py can also be file/ directory# template: str - content template with {product} and {Product} placeholders+# scaffold: bool - whether product:bootstrap creates the file (default true)## Modes:# strict: product has backend/facade/contracts.py (isolated architecture)@@ -118,6 +119,13 @@ backend_files:name = "products.{product}.backend"label = "{product}"+ # Django system checks for the product. Optional, and not scaffolded: add it when the product+ # has a setting worth validating at startup. product:lint requires that apps.py ready()+ # imports it and that its IDs start with posthog.{product}. (see posthog/checks.py).+ checks.py:+ required: false+ scaffold: false+models.py:required: truecan_be_folder: truediff --git a/tools/hogli-commands/hogli_commands/tests/test_checks.py b/tools/hogli-commands/hogli_commands/tests/test_checks.pyindex 8c53567e2034..b6161d0f4393 100644--- a/tools/hogli-commands/hogli_commands/tests/test_checks.py+++ b/tools/hogli-commands/hogli_commands/tests/test_checks.py@@ -23,6 +23,7 @@ from hogli_commands.product.checks import (PackageJsonScriptsCheck,ProductYamlCheck,ProductYamlOwnersCheck,+ SystemChecksCheck,WiringInterfaceCheck,_has_test_files,_is_noop_script,@@ -3164,3 +3165,139 @@ class TestFacadeShapeBaseline:recorded = FacadeShapeCheck().run(ctx)assert recorded.issues == []assert recorded.lines == ["⚠ facade shape debt: 1 rows"]+++# ---------------------------------------------------------------------------+# SystemChecksCheck — Django system checks live in backend/checks.py+# ---------------------------------------------------------------------------++_READY_IMPORTS_CHECKS = """+from django.apps import AppConfig+++class PConfig(AppConfig):+ name = "products.p.backend"++ def ready(self):+ from products.p.backend import checks # noqa: F401+"""++_READY_WITHOUT_CHECKS = """+from django.apps import AppConfig+++class PConfig(AppConfig):+ name = "products.p.backend"+"""++_CHECKS_MODULE = """+from posthog.checks import register_check++P_CHECK = "{check_id}"+++@register_check(P_CHECK)+def check_p(app_configs, **kwargs):+ return []+"""++_DJANGO_REGISTER_ELSEWHERE = """+from django.core import checks+++def check_p(app_configs, **kwargs):+ return []+"""+++def _system_checks_ctx(tmp_path: Path, files: dict[str, str]) -> CheckContext:+ product_dir = tmp_path / "p"+ backend = product_dir / "backend"+ backend.mkdir(parents=True)+ for rel, content in files.items():+ (backend / rel).parent.mkdir(parents=True, exist_ok=True)+ (backend / rel).write_text(content)+ return CheckContext(+ name="p",+ product_dir=product_dir,+ backend_dir=backend,+ has_facade_contracts=False,+ structure={},+ detailed=False,+ )+++class TestSystemChecksCheck:+ @pytest.mark.parametrize(+ "files, expected",+ [+ ({"apps.py": _READY_WITHOUT_CHECKS}, []),+ (+ {"apps.py": _READY_IMPORTS_CHECKS, "checks.py": _CHECKS_MODULE.format(check_id="posthog.p.E001")},+ [],+ ),+ (+ {+ "apps.py": _READY_IMPORTS_CHECKS.replace(+ "from products.p.backend import checks", "from . import checks"+ ),+ "checks.py": _CHECKS_MODULE.format(check_id="posthog.p.W001"),+ },+ [],+ ),+ (+ {"apps.py": _READY_WITHOUT_CHECKS, "logic/settings_guard.py": _DJANGO_REGISTER_ELSEWHERE},+ ["backend/logic/settings_guard.py registers a Django system check"],+ ),+ (+ {"apps.py": _READY_IMPORTS_CHECKS, "checks.py": _CHECKS_MODULE.format(check_id="p.E001")},+ ["check ID 'p.E001'"],+ ),+ (+ {"apps.py": _READY_IMPORTS_CHECKS, "checks.py": _CHECKS_MODULE.format(check_id="posthog.other.E001")},+ ["check ID 'posthog.other.E001'"],+ ),+ (+ {"apps.py": _READY_WITHOUT_CHECKS, "checks.py": _CHECKS_MODULE.format(check_id="posthog.p.E001")},+ ["never imported by apps.py ready()"],+ ),+ (+ {+ "apps.py": _READY_WITHOUT_CHECKS,+ "logic/guard.py": "import posthog.checks as checks\n\n\[email protected]_check('posthog.p.W001')\n"+ "def check_p(app_configs, **kwargs):\n return []\n",+ },+ ["backend/logic/guard.py registers a Django system check"],+ ),+ (+ {+ "apps.py": _READY_IMPORTS_CHECKS.replace(+ " from products.p.backend import checks",+ " from typing import TYPE_CHECKING\n\n if TYPE_CHECKING:\n"+ " from products.p.backend import checks",+ ),+ "checks.py": _CHECKS_MODULE.format(check_id="posthog.p.E001"),+ },+ ["never imported by apps.py ready()"],+ ),+ (+ {+ "apps.py": _READY_IMPORTS_CHECKS.replace(+ " from products.p.backend import checks",+ " import typing\n\n if not typing.TYPE_CHECKING:\n"+ " from products.p.backend import checks",+ ),+ "checks.py": _CHECKS_MODULE.format(check_id="posthog.p.E001"),+ },+ [],+ ),+ ],+ )+ def test_system_check_placement_ids_and_registration(+ self, tmp_path: Path, files: dict[str, str], expected: list[str]+ ) -> None:+ issues = SystemChecksCheck().run(_system_checks_ctx(tmp_path, files)).issues+ assert len(issues) == len(expected), issues+ for fragment, issue in zip(expected, issues):+ assert fragment in issuediff --git a/tools/hogli-commands/hogli_commands/tests/test_scaffold.py b/tools/hogli-commands/hogli_commands/tests/test_scaffold.pyindex 776c2c178c1e..c1b6833d6984 100644--- a/tools/hogli-commands/hogli_commands/tests/test_scaffold.py+++ b/tools/hogli-commands/hogli_commands/tests/test_scaffold.py@@ -2,6 +2,7 @@ from __future__ import annotationsfrom pathlib import Path+from hogli_commands.product.checks import CheckContext, SystemChecksCheckfrom hogli_commands.product.isolation import MODEL_SURFACE_PREFIXES, has_narrowed_turbo_inputs, unwatched_model_surfacefrom hogli_commands.product.paths import load_structurefrom hogli_commands.product.scaffold import _render_template, flatten_structure@@ -12,10 +13,14 @@ def _write_scaffold(product_dir: Path) -> None:# (tach.toml, settings, db routing) that must not run inside a test.structure = load_structure()for path, config in flatten_structure(structure.get("root_files", {})).items():+ if not config.get("scaffold", True):+ continuefile_path = product_dir / pathfile_path.parent.mkdir(parents=True, exist_ok=True)file_path.write_text(_render_template(config.get("template", ""), "my_product", separate_db=True))for path, config in flatten_structure(structure.get("backend_files", {})).items():+ if not config.get("scaffold", True):+ continuefile_path = product_dir / "backend" / pathfile_path.parent.mkdir(parents=True, exist_ok=True)file_path.write_text(_render_template(config.get("template", ""), "my_product", separate_db=True))@@ -34,3 +39,16 @@ class TestScaffoldPassesIsolationGates:product_dir = tmp_path / "my_product"_write_scaffold(product_dir)assert has_narrowed_turbo_inputs(product_dir, model_surface=MODEL_SURFACE_PREFIXES) is True++ def test_scaffold_passes_the_system_checks_lint(self, tmp_path: Path) -> None:+ product_dir = tmp_path / "my_product"+ _write_scaffold(product_dir)+ ctx = CheckContext(+ name="my_product",+ product_dir=product_dir,+ backend_dir=product_dir / "backend",+ has_facade_contracts=True,+ structure=load_structure(),+ detailed=False,+ )+ assert SystemChecksCheck().run(ctx).issues == []