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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
test(contracts): ratchet the four remaining adoption populations
Juan Denis39a6e35d4244
diff --git a/backend/tests/ERROR_SHAPE_CEILING b/backend/tests/ERROR_SHAPE_CEILINGnew file mode 100644index 00000000..1b66bc15--- /dev/null+++ b/backend/tests/ERROR_SHAPE_CEILING@@ -0,0 +1 @@+1159diff --git a/backend/tests/error_shape_census.py b/backend/tests/error_shape_census.pynew file mode 100644index 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.pynew file mode 100644index 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"+ )) == 0diff --git a/frontend/scripts/check-frontend-boundaries.mjs b/frontend/scripts/check-frontend-boundaries.mjsindex 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