Skip to content

: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.

chore(hogli): make backend/checks.py the home for product system checks (#129835)

Rafael Audibert24909d2ee925
diff --git a/products/README.md b/products/README.md
index f4b47a45b2bf..3950585fbd61 100644
--- a/products/README.md
+++ b/products/README.md
@@ -22,6 +22,7 @@ products/
backend/ # Django app
__init__.py
apps.py
+ checks.py # optional: Django system checks, imported from apps.py ready()
models.py
logic.py # business logic
routes.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 str
This 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.py
index 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 annotations
import re
+import ast
import json
import shlex
import tomllib
@@ -17,7 +18,7 @@ from collections.abc import Iterator
from dataclasses import dataclass, field
from pathlib import Path
-from .ast_helpers import module_import_targets
+from .ast_helpers import ast_parse_safe, module_import_targets
from .crossings import driven_wiring_locations, facade_shape_use, facade_wiring_use, recorded_facade_shape_rows
from .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.py
index 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):
+ continue
file_path = product_dir / path
if 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):
+ continue
file_path = product_dir / "backend" / path
label = 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.yaml
index 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: true
can_be_folder: true
diff --git a/tools/hogli-commands/hogli_commands/tests/test_checks.py b/tools/hogli-commands/hogli_commands/tests/test_checks.py
index 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 issue
diff --git a/tools/hogli-commands/hogli_commands/tests/test_scaffold.py b/tools/hogli-commands/hogli_commands/tests/test_scaffold.py
index 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 annotations
from pathlib import Path
+from hogli_commands.product.checks import CheckContext, SystemChecksCheck
from hogli_commands.product.isolation import MODEL_SURFACE_PREFIXES, has_narrowed_turbo_inputs, unwatched_model_surface
from hogli_commands.product.paths import load_structure
from 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):
+ continue
file_path = product_dir / path
file_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):
+ continue
file_path = product_dir / "backend" / path
file_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 == []