From 8890e86da179305d327f4a8b011fbe4ba02312f4 Mon Sep 17 00:00:00 2001 From: huyplb Date: Sat, 31 Oct 2026 13:04:18 -0600 Subject: [PATCH] docs(feature-map): add SQL Tracer, fold #563's hand edits into the sources, fail on a stale page #563 edited docs/feature-map.html by hand after #567 moved its sources into docs/feature-map/, so the next `npm run docs:feature-map` would have dropped those edits, and the page's diagrams were already behind FEATURE_MAP.md. - data.js: utilities.trace (SQL Tracer, #564); No password for Redis/MongoDB; Compare 2,000 rows and the shared migrate cap; force-migrate and compare-window e2e; routes, unit-test and e2e-group counts re-measured on main b12bcd5607 (158 routes, 18 server modules, 57 specs in 35 groups). - template.html and FEATURE_MAP.md: the same counts; 34 features. - docs/feature-map.html rebuilt, so it also takes the newer diagrams. - feature-map-build.test.ts: fails while the committed page differs from the build (A/B: a one-character hand edit fails it, a rebuild passes). Co-Authored-By: Claude Opus 5.5 --- docs/FEATURE_MAP.md | 15 +++--- docs/feature-map.html | 52 +++++++++++-------- docs/feature-map/data.js | 23 ++++---- docs/feature-map/template.html | 14 ++--- packages/shared/src/feature-map-build.test.ts | 11 +++- 5 files changed, 70 insertions(+), 45 deletions(-) diff --git a/docs/FEATURE_MAP.md b/docs/FEATURE_MAP.md index a434916ce..4aee6aba1 100644 --- a/docs/FEATURE_MAP.md +++ b/docs/FEATURE_MAP.md @@ -12,10 +12,11 @@ an interactive page (open it in a browser), and [the test and fix plan](plans/2026-10-25-feature-and-dialect-test-plan.md) sets the order every feature and dialect is tested in. -Measured on `main` at `100fb679` (2026-10-26): 17 server feature modules, -155 HTTP routes (pinned by `packages/server/src/api/http-contract.test.ts`), -14 frontend features, 16 database engines, 28 metadata tables (31 migrations), -56 e2e specs, ~600 unit-test files. Re-measure with the commands in +Measured on `main` at `b12bcd5607` (2026-10-31): 34 features, 18 server +feature modules, 158 HTTP routes (pinned by +`packages/server/src/api/http-contract.test.ts`), 14 frontend features, +16 database engines, 28 metadata tables (31 migrations), 57 e2e specs in 35 +groups, ~550 unit-test files. Re-measure with the commands in [Keeping this page true](#keeping-this-page-true). - [System](#system) @@ -37,7 +38,7 @@ flowchart LR end subgraph server["Fox server — packages/server (Fastify)"] PLAT["platform
identity · RBAC · workspaces
connections · guards"] - FEAT["17 feature modules
153 routes"] + FEAT["18 feature modules
158 routes"] end WFS["Workflow server :8081
apps/workflow-server
+ packages/workflow-engine"] META[("Metadata store
SQLite · 28 tables")] @@ -625,7 +626,9 @@ tables in the schema diagram. The interactive page, [feature-map.html](feature-map.html), is generated. Edit its inventory in `docs/feature-map/data.js` (its layout in `template.html`, its -script in `app.js`; the diagrams come from this page), then rebuild it: +script in `app.js`; the diagrams come from this page), then rebuild it. Never +edit the page itself: `feature-map-build.test.ts` fails while it differs from +the build. ```bash npm run docs:feature-map diff --git a/docs/feature-map.html b/docs/feature-map.html index f2c9f608d..1219927b7 100644 --- a/docs/feature-map.html +++ b/docs/feature-map.html @@ -238,17 +238,17 @@

Fox Feature Map

-
Measured on main · 100fb679 · 2026-10-26 · mirrors docs/FEATURE_MAP.md
+
Measured on main · b12bcd5607 · 2026-10-31 · mirrors docs/FEATURE_MAP.md
    -
  • 33 features
    • -
  • 155 HTTP routes
    • -
  • 17 server modules
    • +
  • 34 features
    • +
  • 158 HTTP routes
    • +
  • 18 server modules
  • 14 web features
  • 16 engines
  • 28 metadata tables
    • -
  • 56 e2e specs
    • -
  • ~600 unit-test files
    • +
  • 57 e2e specs
    • +
  • ~550 unit-test files
flowchart LR
-  R[Request] --> O["Origin policy<br/>+ rate limit"] --> S["Session guard<br/>(auth.guard)"] --> W["Workspace scope<br/>(resolveWorkspace)"]
+  R[Request] --> O["Origin policy<br/>+ rate limit"] --> S["Session guard<br/>(auth.guard)"] --> RO["app.write or GET / reads"]
+  RO --> W["Workspace scope<br/>(resolveWorkspace)"]
   W --> P["Permission guard<br/>requirePermissions()"] --> H["Feature route<br/>→ service"]
   H --> C["Connection resolver<br/>(decrypts the saved connection)"] --> D["Driver<br/>packages/db"]
   H --> M[("Metadata store")]

Every request passes origin, session, workspace and permission checks before a feature runs.

@@ -383,13 +384,15 @@

Workflows

Data compare → data migrate

flowchart LR
   A[Same SELECT on ≥2 destinations] --> B[Side by side + Compare data]
-  B --> C[align rows by key columns]
-  C --> D[add / edit / delete per target<br/>Sync column picks rows]
+  B --> W["Compare 2,000 rows<br/>both sides in key order"]
+  B --> C[or align the pages already loaded]
+  W --> D[add / edit / delete per target<br/>Sync column picks rows]
+  C --> D
   D --> E[Preview SQL]
   E --> F{Safe mode}
   F -- confirm --> G[POST /api/data-migrations/start]
   G --> H[backup snapshot of affected rows]
-  H --> I[POST /api/data-migrate/execute<br/>Transaction only where it can roll back<br/>stop or continue on error]
+  H --> I["POST /api/data-migrate/execute<br/>≤ 2,000 ops, one shared cap<br/>Transaction only where it can roll back"]
   I --> J[POST /api/data-migrations/:id/finish<br/>data_migrate_runs]
   J --> K[History: restore from snapshot]

Snapshots — capture, compare, revert

flowchart LR
@@ -650,7 +653,7 @@ 
Coverage

End-to-end suites

-

56 Playwright specs in 37 groups, run with npm run test:e2e:all. Dialect suites need their Docker container and a fresh seed.

+

57 Playwright specs in 35 groups, run with npm run test:e2e:all. Dialect suites need their Docker container and a fresh seed.

@@ -663,7 +666,7 @@

End-to-end suites

'; @@ -29,4 +30,12 @@ describe('feature map build', () => { expect(page).toContain('T\n\n\n\n
'); expect(page).toContain('mermaid@11.4.1'); }); + + // The page is generated: an edit made to it by hand is lost on the next build. + // Edit docs/feature-map/ or FEATURE_MAP.md, then run `npm run docs:feature-map`. + it('docs/feature-map.html is what the build writes', () => { + const built = buildStaticPage(buildBoardPage(readSources())); + const committed = readFileSync(new URL('../../../docs/feature-map.html', import.meta.url), 'utf8'); + expect(committed === built, 'docs/feature-map.html is stale: run npm run docs:feature-map').toBe(true); + }); });