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.

feat(conformance): generated remaining-migration inventory (H closure)

Juan Denis395309052629
diff --git a/backend/tests/test_migration_inventory.py b/backend/tests/test_migration_inventory.py
new file mode 100644
index 00000000..e366ad8d
--- /dev/null
+++ b/backend/tests/test_migration_inventory.py
@@ -0,0 +1,46 @@
+"""The committed migration inventory must match the measured state (plan 76, H).
+
+``docs/MIGRATION_INVENTORY.md`` is generated from the same censuses and checks
+that enforce each ratchet, so the plan cannot claim a migration is further
+along (or a door more adopted) than the code measures. This test is the
+freshness half of that closure: whenever a migration commit moves a number,
+regenerating the document is part of the commit::
+
+ python scripts/generate-migration-inventory.py
+
+Skipped when node is unavailable — the generator shells out to the frontend
+boundary checker for its half of the rows.
+"""
+
+import importlib.util
+import os
+import shutil
+import subprocess
+import sys
+
+import pytest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(os.path.dirname(HERE))
+GENERATOR = os.path.join(REPO, 'scripts', 'generate-migration-inventory.py')
+DOC = os.path.join(REPO, 'docs', 'MIGRATION_INVENTORY.md')
+
+
+def test_the_committed_inventory_matches_the_measured_state():
+ if shutil.which('node') is None:
+ pytest.skip('node is not available to run the frontend half')
+ assert os.path.exists(DOC), (
+ 'docs/MIGRATION_INVENTORY.md is missing; run '
+ 'python scripts/generate-migration-inventory.py')
+
+ spec = importlib.util.spec_from_file_location('_mig_inventory', GENERATOR)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+
+ expected = mod.render()
+ with open(DOC, encoding='utf-8') as f:
+ committed = f.read()
+ assert committed == expected, (
+ 'docs/MIGRATION_INVENTORY.md is stale — a ratchet number moved without '
+ 'regenerating it. Run: python scripts/generate-migration-inventory.py'
+ )
diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.md
new file mode 100644
index 00000000..58b6cfc4
--- /dev/null
+++ b/docs/MIGRATION_INVENTORY.md
@@ -0,0 +1,30 @@
+# Remaining-migration inventory
+
+<!-- GENERATED by scripts/generate-migration-inventory.py - do not edit.
+ Every number is measured by the census/check that enforces it. -->
+
+Plan 76 closure artifact (milestone H). Each row is a cross-cutting
+concern whose door exists and is guarded by an executable ratchet; the
+"remaining" column is the measured legacy population that has not yet
+walked through it. A row at 0 is a completed migration held as an
+invariant. Rows marked REGISTERED EXCEPTION are deliberate policy, not
+debt. Regenerate with `python scripts/generate-migration-inventory.py`.
+
+| Concern | Door | Remaining | Ceiling | Policy |
+|---|---|---:|---:|---|
+| Identity lookups outside rbac.get_current_user() | rbac.get_current_user() | 69 | 69 | JWT-only routes; the API-key-capable population is held at 0 by a companion assertion |
+| Routes on bare @jwt_required() | auth_required() / role decorators | 605 | 605 | REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision |
+| 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 |
+| 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 |
+| hand-rolled form-group blocks | F2: FormField/useForm | 343 | 343 | migrate when touched |
+| unencoded ?k=${v} query interpolations in services/api | C4: buildQuery/encoding template | 97 | 97 | migrate when touched |
+| raw setInterval pollers | E2: usePolling/refetchInterval | 11 | 11 | DELIBERATE RESIDUE: clock ticks, socket-fallback hooks, and sibling-repo extension timers - each listed per file |
+| direct navigator.clipboard call sites | F3: copyToClipboard | 0 | 0 | INVARIANT at 0 |
+| hex colour literals outside token files | G: var(--token) | 151 | 151 | migrate when touched |
+| SCSS class names defined in multiple files | single-owner partials | 114 | 114 | needs eyes on pages (no byte-identical proof available) |
+
diff --git a/frontend/scripts/check-frontend-boundaries.mjs b/frontend/scripts/check-frontend-boundaries.mjs
index 4f46c765..ed7a67ee 100644
--- a/frontend/scripts/check-frontend-boundaries.mjs
+++ b/frontend/scripts/check-frontend-boundaries.mjs
@@ -248,6 +248,7 @@ const ADOPTION_CEILINGS = [
},
];
+const adoptionActuals = new Map();
for (const rule of ADOPTION_CEILINGS) {
let totalCount = 0;
for (const path of files) {
@@ -255,6 +256,7 @@ for (const rule of ADOPTION_CEILINGS) {
if (!rule.include(file)) continue;
totalCount += count(readFileSync(path, 'utf8'), rule.pattern);
}
+ adoptionActuals.set(rule.name, totalCount);
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) {
@@ -330,6 +332,24 @@ for (const ownership of EXTENSION_OWNED_STYLES) {
}
}
+// Machine-readable ratchet report for the plan-76 H-closure inventory
+// generator (scripts/generate-migration-inventory.py at the repo root).
+if (process.argv.includes('--inventory')) {
+ const inventory = [];
+ for (const rule of ADOPTION_CEILINGS) {
+ inventory.push({ name: rule.name, actual: adoptionActuals.get(rule.name), ceiling: rule.ceiling });
+ }
+ const sum = (m) => [...m.values()].reduce((a, b) => a + b, 0);
+ inventory.push({ name: 'raw setInterval pollers (E2: usePolling/refetchInterval)',
+ actual: sum(LEGACY_POLLERS), ceiling: sum(LEGACY_POLLERS) });
+ inventory.push({ name: 'direct navigator.clipboard call sites (F3: copyToClipboard)',
+ actual: sum(LEGACY_CLIPBOARD), ceiling: 0 });
+ inventory.push({ name: 'hex colour literals outside token files (G: var(--token))',
+ actual: sum(LEGACY_COLOR_LITERALS), ceiling: sum(LEGACY_COLOR_LITERALS) });
+ console.log(JSON.stringify({ ok: failures.length === 0, failures, inventory }, null, 2));
+ process.exit(failures.length ? 1 : 0);
+}
+
if (failures.length) {
console.error('\nFrontend boundary check failed:\n');
failures.forEach((failure) => console.error(` - ${failure}`));
diff --git a/scripts/generate-migration-inventory.py b/scripts/generate-migration-inventory.py
new file mode 100644
index 00000000..1ee80f0f
--- /dev/null
+++ b/scripts/generate-migration-inventory.py
@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Generate docs/MIGRATION_INVENTORY.md from the executable ratchets (plan 76, H).
+
+Milestone H requires "a remaining-migration inventory generated from the same
+checks, so the plan cannot claim completion while known legacy doors remain."
+This script IS that closure: every number below comes from running the actual
+census/check that enforces it — nothing is typed in by hand, so the document
+cannot drift from what the ratchets hold.
+
+Run from the repo root::
+
+ python scripts/generate-migration-inventory.py
+
+Regenerate whenever a migration commit changes a ceiling;
+``backend/tests/test_migration_inventory.py`` fails if the committed document
+no longer matches the measured state.
+"""
+
+import importlib
+import io
+import json
+import os
+import subprocess
+import sys
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BACKEND_TESTS = os.path.join(REPO, 'backend', 'tests')
+OUT = os.path.join(REPO, 'docs', 'MIGRATION_INVENTORY.md')
+
+sys.path.insert(0, BACKEND_TESTS)
+
+
+def _backend_rows():
+ rows = []
+ specs = [
+ ('identity_door_census', 'Identity lookups outside rbac.get_current_user()',
+ 'rbac.get_current_user()',
+ 'JWT-only routes; the API-key-capable population is held at 0 by a companion assertion'),
+ ('jwt_only_census', 'Routes on bare @jwt_required()',
+ 'auth_required() / role decorators',
+ 'REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision'),
+ ('status_sniffing_census', 'HTTP statuses chosen by sniffing error text',
+ 'typed errors from app.exceptions',
+ 'INVARIANT at 0 - migration completed 2026-08-19'),
+ ('unreported_crash_census', 'API crashes swallowed without recording',
+ 'app.error_reporting',
+ 'INVARIANT at 0'),
+ ('error_shape_census', "Hand-shaped {'error': ...} bodies in app/api",
+ 'typed errors + the global handler',
+ 'migrate when touched; new endpoints raise'),
+ ('raw_subprocess_census', 'Raw subprocess calls outside the runners',
+ 'app/utils/system.py runners',
+ 'migrate when touched'),
+ ]
+ for module_name, concern, door, policy in specs:
+ mod = importlib.import_module(module_name)
+ rows.append((concern, door, mod.total(), mod.read_ceiling(), policy))
+ return rows
+
+
+def _controller_boundary_row():
+ path = os.path.join(BACKEND_TESTS, 'api_controller_boundary_baseline.json')
+ data = json.load(io.open(path, encoding='utf-8'))
+ n = data['violations'] if isinstance(data['violations'], int) else len(data['violations'])
+ return ('Controller-boundary violations (routes doing service work)',
+ 'service layer extraction', n, n, 'migrate when touched (first-wave ratchet)')
+
+
+def _frontend_rows():
+ result = subprocess.run(
+ ['node', os.path.join('frontend', 'scripts', 'check-frontend-boundaries.mjs'),
+ '--inventory'],
+ capture_output=True, text=True, cwd=REPO)
+ if result.returncode != 0:
+ raise SystemExit('frontend boundary check failed:\n' + result.stdout + result.stderr)
+ payload = json.loads(result.stdout)
+ rows = []
+ for item in payload['inventory']:
+ name = item['name']
+ door = name[name.index('(') + 1:name.rindex(')')] if '(' in name else ''
+ concern = name[:name.index('(')].strip() if '(' in name else name
+ if item['ceiling'] == 0:
+ policy = 'INVARIANT at 0'
+ elif 'setInterval' in name:
+ policy = ('DELIBERATE RESIDUE: clock ticks, socket-fallback hooks, '
+ 'and sibling-repo extension timers - each listed per file')
+ else:
+ policy = 'migrate when touched'
+ rows.append((concern, door, item['actual'], item['ceiling'], policy))
+ return rows
+
+
+def _style_ownership_row():
+ path = os.path.join(REPO, 'frontend', 'scripts', 'STYLE_OWNERSHIP_CEILING')
+ n = int(io.open(path, encoding='utf-8').read().strip())
+ return ('SCSS class names defined in multiple files', 'single-owner partials',
+ n, n, 'needs eyes on pages (no byte-identical proof available)')
+
+
+def render():
+ rows = (_backend_rows() + [_controller_boundary_row()]
+ + _frontend_rows() + [_style_ownership_row()])
+
+ lines = [
+ '# Remaining-migration inventory',
+ '',
+ '<!-- GENERATED by scripts/generate-migration-inventory.py - do not edit.',
+ ' Every number is measured by the census/check that enforces it. -->',
+ '',
+ 'Plan 76 closure artifact (milestone H). Each row is a cross-cutting',
+ 'concern whose door exists and is guarded by an executable ratchet; the',
+ '"remaining" column is the measured legacy population that has not yet',
+ 'walked through it. A row at 0 is a completed migration held as an',
+ 'invariant. Rows marked REGISTERED EXCEPTION are deliberate policy, not',
+ 'debt. Regenerate with `python scripts/generate-migration-inventory.py`.',
+ '',
+ '| Concern | Door | Remaining | Ceiling | Policy |',
+ '|---|---|---:|---:|---|',
+ ]
+ for concern, door, actual, ceiling, policy in rows:
+ lines.append(f'| {concern} | {door} | {actual} | {ceiling} | {policy} |')
+ lines.append('')
+ return '\n'.join(lines) + '\n'
+
+
+if __name__ == '__main__':
+ content = render()
+ io.open(OUT, 'w', encoding='utf-8', newline='\n').write(content)
+ print(f'wrote {os.path.relpath(OUT, REPO)}')