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.

test(contracts): ratchet the four remaining adoption populations

Juan Denis39a6e35d4244
diff --git a/backend/tests/ERROR_SHAPE_CEILING b/backend/tests/ERROR_SHAPE_CEILING
new file mode 100644
index 00000000..1b66bc15
--- /dev/null
+++ b/backend/tests/ERROR_SHAPE_CEILING
@@ -0,0 +1 @@
+1159
diff --git a/backend/tests/error_shape_census.py b/backend/tests/error_shape_census.py
new file mode 100644
index 00000000..6e0f1069
--- /dev/null
+++ b/backend/tests/error_shape_census.py
@@ -0,0 +1,125 @@
+"""Count hand-shaped API error bodies (plan 76, B).
+
+Milestone B's door is ``app/exceptions.py`` + the global handler: a route (or
+the service under it) raises a typed error and the handler owns the JSON body,
+the status code, and the ``X-Request-ID`` correlation. A hand-shaped
+
+ return jsonify({'error': 'App not found'}), 404
+
+answers with none of that — no ``code``, no ``request_id`` — and every one is
+a place where the error contract can drift (and has: the same failure returns
+400, 404, or 409 depending on which file answers it).
+
+This population is large and its conversion is "migrate when touched"
+(invariant 9 — no repo-wide rewrite). The census makes that policy
+enforceable: the count may only go down. New endpoints raise typed errors.
+
+A site is counted when a ``return`` in ``app/api`` yields an error-shaped
+mapping — a dict literal whose keys include ``'error'`` — either directly or
+through ``jsonify``. The door's own products are not counted: raising a typed
+error, or answering through ``app.error_reporting``.
+
+Usage (from ``backend/``)::
+
+ python tests/error_shape_census.py # print the count + report
+ python tests/error_shape_census.py --update # write the count as the ceiling
+"""
+
+import ast
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+BACKEND = os.path.dirname(HERE)
+API_DIR = os.path.join(BACKEND, 'app', 'api')
+CEILING_FILE = os.path.join(HERE, 'ERROR_SHAPE_CEILING')
+
+SKIP_DIRS = {'__pycache__'}
+
+
+def _rel(path):
+ return os.path.relpath(path, BACKEND).replace(os.sep, '/')
+
+
+def _is_error_dict(node):
+ return (isinstance(node, ast.Dict)
+ and any(isinstance(k, ast.Constant) and k.value == 'error'
+ for k in node.keys))
+
+
+def _error_shaped(value):
+ """The returned expression carries a hand-built {'error': ...} body."""
+ if _is_error_dict(value):
+ return True
+ if (isinstance(value, ast.Call) and isinstance(value.func, ast.Name)
+ and value.func.id == 'jsonify' and value.args
+ and _is_error_dict(value.args[0])):
+ return True
+ if isinstance(value, ast.Tuple) and value.elts:
+ return _error_shaped(value.elts[0])
+ return False
+
+
+def count_file(path):
+ """Return [(lineno, snippet)] of hand-shaped error returns in one file."""
+ try:
+ with open(path, encoding='utf-8') as f:
+ source = f.read()
+ tree = ast.parse(source)
+ except (SyntaxError, UnicodeDecodeError):
+ return []
+ lines = source.split('\n')
+ found = []
+ for node in ast.walk(tree):
+ if not (isinstance(node, ast.Return) and node.value is not None):
+ continue
+ if _error_shaped(node.value):
+ snippet = lines[node.lineno - 1].strip() if node.lineno <= len(lines) else ''
+ found.append((node.lineno, snippet[:100]))
+ return sorted(found)
+
+
+def census():
+ found = {}
+ for dirpath, dirnames, filenames in os.walk(API_DIR):
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+ for name in sorted(filenames):
+ if not name.endswith('.py'):
+ continue
+ path = os.path.join(dirpath, name)
+ hits = count_file(path)
+ if hits:
+ found[_rel(path)] = hits
+ return found
+
+
+def total(found=None):
+ if found is None:
+ found = census()
+ return sum(len(v) for v in found.values())
+
+
+def read_ceiling():
+ with open(CEILING_FILE, encoding='utf-8') as f:
+ return int(f.read().strip())
+
+
+def _write_ceiling(value):
+ with open(CEILING_FILE, 'w', encoding='utf-8') as f:
+ f.write('%d\n' % value)
+
+
+if __name__ == '__main__':
+ found = census()
+ count = total(found)
+ for rel in sorted(found, key=lambda p: (-len(found[p]), p))[:15]:
+ print('%-40s %d' % (rel, len(found[rel])))
+ print('\ntotal: %d' % count)
+ if '--update' in sys.argv:
+ _write_ceiling(count)
+ print('ceiling updated to %d' % count)
+ else:
+ try:
+ print('ceiling: %d' % read_ceiling())
+ except FileNotFoundError:
+ print('no ceiling file yet; run with --update')
diff --git a/backend/tests/test_error_shape_ratchet.py b/backend/tests/test_error_shape_ratchet.py
new file mode 100644
index 00000000..1e34b5c9
--- /dev/null
+++ b/backend/tests/test_error_shape_ratchet.py
@@ -0,0 +1,71 @@
+"""The hand-shaped-error-body ratchet (plan 76, milestone B closure).
+
+The conversion itself is migrate-when-touched (invariant 9); this ceiling is
+what makes that policy real — see ``error_shape_census.py`` for the contract.
+"""
+
+from error_shape_census import census, count_file, read_ceiling, total
+
+
+def test_the_count_is_at_or_below_the_ceiling():
+ found = census()
+ count = total(found)
+ ceiling = read_ceiling()
+ worst = sorted(found, key=lambda p: -len(found[p]))[:5]
+ assert count <= ceiling, (
+ f'{count} hand-shaped error bodies in app/api, ceiling is {ceiling}.\n'
+ f'Raise a typed error from app.exceptions instead — the global handler '
+ f'owns the body, the status, and the request id.\n'
+ f'Heaviest files: ' + ', '.join(f'{p} ({len(found[p])})' for p in worst)
+ )
+
+
+def test_the_ceiling_is_not_stale():
+ count, ceiling = total(), read_ceiling()
+ assert ceiling - count <= 25, (
+ f'ceiling {ceiling} is {ceiling - count} above the actual {count}; '
+ f'run `python tests/error_shape_census.py --update`'
+ )
+
+
+class TestTheCensusCountsTheRightThings:
+ """A miscounting ratchet is worse than none: it reads green either way."""
+
+ def _count(self, tmp_path, source):
+ path = tmp_path / 'sample.py'
+ path.write_text(source, encoding='utf-8')
+ return len(count_file(str(path)))
+
+ def test_counts_a_jsonified_error_body(self, tmp_path):
+ assert self._count(tmp_path, (
+ "def handler():\n"
+ " return jsonify({'error': 'nope'}), 404\n"
+ )) == 1
+
+ def test_counts_a_bare_dict_error_body(self, tmp_path):
+ assert self._count(tmp_path, (
+ "def handler():\n"
+ " return {'error': 'nope'}, 400\n"
+ )) == 1
+
+ def test_does_not_count_a_success_body(self, tmp_path):
+ assert self._count(tmp_path, (
+ "def handler():\n"
+ " return jsonify({'success': True, 'data': []}), 200\n"
+ )) == 0
+
+ def test_does_not_count_a_typed_raise(self, tmp_path):
+ """What the migration produces must not read as debt."""
+ assert self._count(tmp_path, (
+ "def handler():\n"
+ " raise NotFoundError('nope')\n"
+ )) == 0
+
+ def test_does_not_count_a_variable_body(self, tmp_path):
+ """`return body, status` where body was built elsewhere is out of
+ scope for a syntactic census — the recorder helpers return those."""
+ assert self._count(tmp_path, (
+ "def handler():\n"
+ " body, status = unexpected_response(exc)\n"
+ " return body, status\n"
+ )) == 0
diff --git a/frontend/scripts/check-frontend-boundaries.mjs b/frontend/scripts/check-frontend-boundaries.mjs
index aa707fae..4f46c765 100644
--- a/frontend/scripts/check-frontend-boundaries.mjs
+++ b/frontend/scripts/check-frontend-boundaries.mjs
@@ -217,6 +217,51 @@ for (const file of LEGACY_POLLERS.keys()) {
}
}
+// Adoption ceilings (plan 76, milestones E1/F2/C4-interim). These populations
+// are in the hundreds, so per-file baselines would be unmaintainable; a total
+// that may only go down is the honest ratchet. Each entry names the door the
+// sites should migrate to when their surface is next touched.
+const ADOPTION_CEILINGS = [
+ {
+ name: 'raw api.* calls in pages/ (E1: useServerQuery/useServerMutation)',
+ ceiling: 460,
+ include: (file) => file.startsWith('pages/'),
+ pattern: /\bapi\s*\.\s*\w+\s*\(/g,
+ },
+ {
+ name: 'per-page toast.error extractions in pages/ (E1: query-layer error presentation)',
+ ceiling: 264,
+ include: (file) => file.startsWith('pages/'),
+ pattern: /toast\s*\.\s*error\s*\(/g,
+ },
+ {
+ name: 'hand-rolled form-group blocks (F2: FormField/useForm)',
+ ceiling: 343,
+ include: (file) => file.startsWith('pages/') || file.startsWith('components/'),
+ pattern: /form-group/g,
+ },
+ {
+ name: 'unencoded ?k=${v} query interpolations in services/api (C4: buildQuery/encoding template)',
+ ceiling: 97,
+ include: (file) => file.startsWith('services/api/'),
+ pattern: /[?&][A-Za-z_]+=\$\{(?!encodeURIComponent)/g,
+ },
+];
+
+for (const rule of ADOPTION_CEILINGS) {
+ let totalCount = 0;
+ for (const path of files) {
+ const file = rel(path);
+ if (!rule.include(file)) continue;
+ totalCount += count(readFileSync(path, 'utf8'), rule.pattern);
+ }
+ if (totalCount > rule.ceiling) {
+ failures.push(`${rule.name}: ${totalCount} sites, ceiling ${rule.ceiling}. Migrate through the named door instead of adding another bypass.`);
+ } else if (rule.ceiling - totalCount > 25) {
+ failures.push(`${rule.name}: ceiling ${rule.ceiling} is ${rule.ceiling - totalCount} above the actual ${totalCount}; lower it in check-frontend-boundaries.mjs so the migration cannot silently regrow.`);
+ }
+}
+
// A @keyframes name is global and last-definition-wins, across every partial
// main.scss pulls in. Two partials defining the same name is therefore not
// duplication that merely wastes bytes: one of them is silently dead, and which