Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

fix(census): measure only tracked files — the instruments count what ships

Juan Denisc803ee50120e
diff --git a/backend/app/jobs/thread_ownership.py b/backend/app/jobs/thread_ownership.py
index 3c7f27f2..17a70880 100644
--- a/backend/app/jobs/thread_ownership.py
+++ b/backend/app/jobs/thread_ownership.py
@@ -52,11 +52,8 @@ THREAD_OWNERSHIP = {
'lifecycle': LIFECYCLE_PROCESS_LOOP,
'rationale': 'Long-lived consumer for already-persisted notification messages.',
},
- 'app/plugins/serverkit-analytics/ingest_service.py:ensure_flush_thread:_flush_loop': {
- 'owner': 'analytics extension ingest',
- 'lifecycle': LIFECYCLE_PROCESS_LOOP,
- 'rationale': 'Flushes an in-memory analytics batch owned by this process.',
- },
+ # Installed (untracked) extension copies are not classified here: the
+ # guard scans tracked files only, and extension repos own their threads.
'app/queue_bus/consumers/webhook_consumer.py:start:self._run': {
'owner': 'webhook queue',
'lifecycle': LIFECYCLE_PROCESS_LOOP,
diff --git a/backend/tests/RAW_SUBPROCESS_CEILING b/backend/tests/RAW_SUBPROCESS_CEILING
index 9902f178..a45fd52c 100644
--- a/backend/tests/RAW_SUBPROCESS_CEILING
+++ b/backend/tests/RAW_SUBPROCESS_CEILING
@@ -1 +1 @@
-28
+24
diff --git a/backend/tests/raw_subprocess_census.py b/backend/tests/raw_subprocess_census.py
index ab12077c..67755140 100644
--- a/backend/tests/raw_subprocess_census.py
+++ b/backend/tests/raw_subprocess_census.py
@@ -36,10 +36,15 @@ SKIP_DIRS = {'__pycache__', 'node_modules', '.venv', 'venv'}
def _iter_py_files(root):
+ # Only git-tracked files: a dev box's app/plugins/ also carries installed
+ # extension copies a clean checkout never sees, and counting those gives
+ # the ceiling invisible slack on CI (28 measured here vs 24 there).
+ from tracked_files import is_tracked, tracked_py_files
+ tracked = tracked_py_files(BACKEND)
for dirpath, dirnames, filenames in os.walk(root):
dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
for name in sorted(filenames):
- if name.endswith('.py'):
+ if name.endswith('.py') and is_tracked(os.path.join(dirpath, name), tracked):
yield os.path.join(dirpath, name)
diff --git a/backend/tests/test_raw_subprocess_ratchet.py b/backend/tests/test_raw_subprocess_ratchet.py
index 2c43084d..d4618874 100644
--- a/backend/tests/test_raw_subprocess_ratchet.py
+++ b/backend/tests/test_raw_subprocess_ratchet.py
@@ -105,3 +105,22 @@ def test_the_doors_are_where_the_raw_calls_are_allowed_to_be():
change that accidentally stopped scanning app/ would not read as a win."""
found = census()
assert found.get('app/utils/system.py'), 'census stopped seeing the helpers'
+
+
+def test_untracked_files_are_not_counted():
+ """The census measures what ships, not what this machine has installed.
+
+ A dev box's app/plugins/ also holds installed extension copies that git
+ does not track; counting their call sites once gave the ceiling four
+ sites of invisible slack on CI's clean checkout (28 here, 24 there).
+ """
+ import os
+ from raw_subprocess_census import APP_DIR, census
+
+ probe = os.path.join(APP_DIR, '_untracked_census_probe.py')
+ with open(probe, 'w', encoding='utf-8') as f:
+ f.write("import subprocess\nsubprocess.run(['true'])\n")
+ try:
+ assert 'app/_untracked_census_probe.py' not in census()
+ finally:
+ os.remove(probe)
diff --git a/backend/tests/test_thread_ownership.py b/backend/tests/test_thread_ownership.py
index d7df7de5..4d5c227f 100644
--- a/backend/tests/test_thread_ownership.py
+++ b/backend/tests/test_thread_ownership.py
@@ -18,8 +18,15 @@ BACKEND_ROOT = APP_ROOT.parent
def _raw_thread_sites():
+ # Tracked files only: installed extension copies under app/plugins/ exist
+ # on dev boxes but not in a clean checkout, and a classification entry for
+ # one reads as stale on CI (extension repos own their own threads).
+ from tracked_files import is_tracked, tracked_py_files
+ tracked = tracked_py_files(str(BACKEND_ROOT))
sites = set()
for path in APP_ROOT.rglob('*.py'):
+ if not is_tracked(str(path), tracked):
+ continue
tree = ast.parse(path.read_text(encoding='utf-8'), filename=str(path))
parents = {}
for node in ast.walk(tree):
diff --git a/backend/tests/tracked_files.py b/backend/tests/tracked_files.py
new file mode 100644
index 00000000..07cb12d4
--- /dev/null
+++ b/backend/tests/tracked_files.py
@@ -0,0 +1,44 @@
+"""Scope tree-measuring instruments to the files that ship with the repo.
+
+The censuses and structural guards measure ``backend/app`` by walking the
+filesystem — but a dev box's ``app/plugins/`` also holds *installed* extension
+copies that are not tracked in git (only the builtin extensions are). A walk
+that counts those measures the machine, not the product: the raw-subprocess
+ceiling picked up 4 call sites from locally-installed extensions that CI's
+clean checkout can never see, which is exactly the silent-slack failure mode
+the ceilings exist to prevent.
+
+``tracked_py_files()`` returns the set of git-tracked ``.py`` paths under a
+root, so an instrument can skip everything else. When git is unavailable it
+returns ``None`` and callers fall back to walking everything — measuring too
+much is recoverable; measuring nothing is not.
+"""
+
+import os
+import subprocess
+
+
+def tracked_py_files(root):
+ """Absolute, ``os.path.normcase``-normalised paths of git-tracked ``.py``
+ files under *root*, or ``None`` when git cannot answer."""
+ try:
+ proc = subprocess.run(
+ ['git', 'ls-files', '-z', '--', '.'],
+ cwd=root, capture_output=True, text=True, timeout=30,
+ )
+ except (OSError, subprocess.TimeoutExpired):
+ return None
+ if proc.returncode != 0:
+ return None
+ return {
+ os.path.normcase(os.path.abspath(os.path.join(root, rel)))
+ for rel in proc.stdout.split('\0')
+ if rel.endswith('.py')
+ }
+
+
+def is_tracked(path, tracked):
+ """True when *path* is in *tracked*, or when there is no filter."""
+ if tracked is None:
+ return True
+ return os.path.normcase(os.path.abspath(path)) in tracked
diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.md
index 58b6cfc4..fa78ccdf 100644
--- a/docs/MIGRATION_INVENTORY.md
+++ b/docs/MIGRATION_INVENTORY.md
@@ -17,7 +17,7 @@ debt. Regenerate with `python scripts/generate-migration-inventory.py`.
| HTTP statuses chosen by sniffing error text | typed errors from app.exceptions | 0 | 0 | INVARIANT at 0 - migration completed 2026-08-19 |
| API crashes swallowed without recording | app.error_reporting | 0 | 0 | INVARIANT at 0 |
| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 1159 | 1159 | migrate when touched; new endpoints raise |
-| Raw subprocess calls outside the runners | app/utils/system.py runners | 28 | 28 | migrate when touched |
+| Raw subprocess calls outside the runners | app/utils/system.py runners | 24 | 24 | migrate when touched |
| Controller-boundary violations (routes doing service work) | service layer extraction | 510 | 510 | migrate when touched (first-wave ratchet) |
| raw api.* calls in pages/ | E1: useServerQuery/useServerMutation | 460 | 460 | migrate when touched |
| per-page toast.error extractions in pages/ | E1: query-layer error presentation | 264 | 264 | migrate when touched |