From 21f4f7d5de7d8f4d237ec1caba5c7dc79ef16fda Mon Sep 17 00:00:00 2001 From: Maurice Date: Wed, 18 Nov 2026 13:20:09 +0100 Subject: [PATCH] docs(server): plain wording in the comments and test titles this change added Comments and test titles added on this branch cited review labels and planning documents that do not exist in the repository, and some used dashes as separators. They now say what the code does and why in plain sentences, and the Postgres lane's suites share one header format. Test ids stay as they were. --- Dockerfile | 2 +- server/scripts/generate-entities.ts | 2 +- server/src/bootstrap.ts | 2 +- server/src/nest/reservations/reservation-rows.ts | 2 +- server/src/nest/reservations/reservations.service.ts | 2 +- server/tests/integration/places-nul.test.ts | 5 ++--- server/tests/integration/vacay.test.ts | 2 +- server/tests/postgres/result-semantics.test.ts | 2 +- server/tests/postgres/schema-parity.test.ts | 2 +- server/tests/postgres/semantics.test.ts | 2 +- server/tests/postgres/server-checks.test.ts | 2 +- wiki/Environment-Variables.md | 2 +- 12 files changed, 13 insertions(+), 14 deletions(-) diff --git a/Dockerfile b/Dockerfile index 0b6bb7742..8aad504d3 100644 --- a/Dockerfile +++ b/Dockerfile @@ -120,7 +120,7 @@ COPY --chown=node:node wiki ./wiki # tsconfig-paths/register reads this at runtime to resolve MCP SDK paths. COPY --chown=node:node server/tsconfig.json ./server/ # Encryption-key rotation is run on demand via tsx (a prod dep) straight from the -# raw .ts source (the command and its stores module) — they never enter dist, so they must be copied in explicitly or +# raw .ts source (the command and its stores module). They never enter dist, so they must be copied in explicitly or # `node --import tsx scripts/migrate-encryption.ts` fails with module-not-found. COPY --chown=node:node server/scripts/migrate-encryption.ts server/scripts/migrate-encryption-stores.ts ./server/scripts/ # Admin recovery script (node server/reset-admin.js) for locked-out installs. diff --git a/server/scripts/generate-entities.ts b/server/scripts/generate-entities.ts index 49dc954f3..7dcd0a34f 100644 --- a/server/scripts/generate-entities.ts +++ b/server/scripts/generate-entities.ts @@ -1221,7 +1221,7 @@ export interface RuleFixups { jsonColumns: JsonColumnFixup[]; /** Rule 1c's flags, whose class field `fixFlagClassFieldTypes` turns back into a plain boolean. */ flags: RetypedScalarFixup[]; - /** Rule 1's + Rule 1b's + Rule 1c's + Rule 2's retyped scalars together — all need the same `.columnType()` strip (see `stripRedundantColumnType`). */ + /** Rule 1's + Rule 1b's + Rule 1c's + Rule 2's retyped scalars together, which all need the same `.columnType()` strip (see `stripRedundantColumnType`). */ retypedScalars: RetypedScalarFixup[]; /** Rule 10's repository-type markers — one per entity class. */ repositoryMarkers: RepositoryTypeMarkerFixup[]; diff --git a/server/src/bootstrap.ts b/server/src/bootstrap.ts index 80ba2100e..fced714a6 100644 --- a/server/src/bootstrap.ts +++ b/server/src/bootstrap.ts @@ -50,7 +50,7 @@ import nodeHttp from 'node:http'; * 4b. setupApiDocs — Swagger UI/spec at /api/docs* when TREK_API_DOCS_ENABLED. * 4c. the named body-parser wrappers — the global 100kb JSON/urlencoded * parsers, exempting /mcp so the MCP SDK reads the raw stream. - * 4d. nulFreeRequest — drops NUL from the path, query, body and cookies. + * 4d. nulFreeRequest, which drops NUL from the path, query, body and cookies. * 5. app.init() — every domain controller, including the transport surface * that used to live pre-init: /api/health (FeaturesController), OAuth * discovery documents (DiscoveryController), the /oauth/consent COOP diff --git a/server/src/nest/reservations/reservation-rows.ts b/server/src/nest/reservations/reservation-rows.ts index dbe4efe93..090fc192f 100644 --- a/server/src/nest/reservations/reservation-rows.ts +++ b/server/src/nest/reservations/reservation-rows.ts @@ -18,7 +18,7 @@ export interface ReservationTraveler { is_guest?: number | null; } -/** A reservation row as the joined list/get queries return it (open record — +/** A reservation row as the joined list/get queries return it (an open record: * the legacy queries selected `r.*` and callers pass the row through; the * named fields are the columns consumers read in a typed position). */ export type ReservationRow = Record & { diff --git a/server/src/nest/reservations/reservations.service.ts b/server/src/nest/reservations/reservations.service.ts index f9f82ce0b..9d54b59e4 100644 --- a/server/src/nest/reservations/reservations.service.ts +++ b/server/src/nest/reservations/reservations.service.ts @@ -613,7 +613,7 @@ export class ReservationsService { // the two together would bend one of them out of shape. The day stop is the // part that must not exist twice, so it comes from AccommodationsService. // The payload's accommodation_id is untrusted input and goes through - // `toRowId` the way update() reads it (L2): a `'0x1'` or an `'abc'` used to + // `toRowId` the way update() reads it: a `'0x1'` or an `'abc'` used to // be stored as `'0x1.0'`, which Postgres cannot cast back for the join. let resolvedAccommodationId: number | null = toRowId(accommodation_id) || null; if (type === 'hotel' && !resolvedAccommodationId && create_accommodation) { diff --git a/server/tests/integration/places-nul.test.ts b/server/tests/integration/places-nul.test.ts index ba72d6d03..343d393e7 100644 --- a/server/tests/integration/places-nul.test.ts +++ b/server/tests/integration/places-nul.test.ts @@ -5,9 +5,8 @@ * answer a 500 there while SQLite stored it. TREK stores no NUL on either * engine now (src/db/nul-free.ts): every string a statement carries loses it, * so the same request answers the same status and leaves the same row on both - * engines (M1 / program rule 22 first made it a 201 on SQLite). The control - * characters 0x01-0x1F, which both engines store, are swept in - * places.test.ts. + * engines. The control characters 0x01-0x1F, which both engines store, are + * swept in places.test.ts. */ import { buildApp } from '../../src/bootstrap'; import { Places } from '../../src/db/entities/Places.entity'; diff --git a/server/tests/integration/vacay.test.ts b/server/tests/integration/vacay.test.ts index 1f6e51d76..ee40f9614 100644 --- a/server/tests/integration/vacay.test.ts +++ b/server/tests/integration/vacay.test.ts @@ -202,7 +202,7 @@ describe('Vacay entries', () => { }); describe('Vacay carry-over', () => { - it('VACAY-046 — a half day left over carries as a half day into the next year, on every engine', async () => { + it('VACAY-046: a half day left over carries as a half day into the next year, on every engine', async () => { const { user } = await makeUser(orm); const cookie = authCookie(user.id); await request(app).get('/api/addons/vacay/plan').set('Cookie', cookie); diff --git a/server/tests/postgres/result-semantics.test.ts b/server/tests/postgres/result-semantics.test.ts index e4c47da82..413ef6159 100644 --- a/server/tests/postgres/result-semantics.test.ts +++ b/server/tests/postgres/result-semantics.test.ts @@ -1,5 +1,5 @@ /** - * PGSEM-101..105 — answers that differ by engine although every statement is + * PGSEM-101..105: answers that differ by engine although every statement is * accepted, so the probe cannot see them; checked here against the real app * on the lane's Postgres database: * a booking linked to a stay as '14.0' still shows the stay in the public diff --git a/server/tests/postgres/schema-parity.test.ts b/server/tests/postgres/schema-parity.test.ts index 917098976..982b9fa08 100644 --- a/server/tests/postgres/schema-parity.test.ts +++ b/server/tests/postgres/schema-parity.test.ts @@ -1,5 +1,5 @@ /** - * PARITY-PG — the schema a Postgres database ends with after its bootstrap + * PARITY-PG-001: the schema a Postgres database ends with after its bootstrap * (the baseline, then every migration after its cut) is the schema the * entities describe, as scripts/generate-pg-baseline.ts writes it for * Postgres (src/db/engine/postgres/schema-adjust.ts). MikroORM's comparator diff --git a/server/tests/postgres/semantics.test.ts b/server/tests/postgres/semantics.test.ts index f97094627..5476bbd89 100644 --- a/server/tests/postgres/semantics.test.ts +++ b/server/tests/postgres/semantics.test.ts @@ -1,5 +1,5 @@ /** - * PGSEM-001..002 — what SQLite gives for free and Postgres only through the + * PGSEM-001..002: what SQLite gives for free and Postgres only through the * engine, against the real app on the lane's Postgres database: * writes in a UnitOfWork run one at a time, as on SQLite's single writer, so * a read-then-insert never races; counts come back as numbers; and a search diff --git a/server/tests/postgres/server-checks.test.ts b/server/tests/postgres/server-checks.test.ts index e03fdb5e6..fb339047e 100644 --- a/server/tests/postgres/server-checks.test.ts +++ b/server/tests/postgres/server-checks.test.ts @@ -1,5 +1,5 @@ /** - * PGROLE-001..006 — the check that refuses a restore (and warns at boot) for a + * PGROLE-001..006: the check that refuses a restore (and warns at boot) for a * role that could reach the database host from SQL * (src/db/engine/postgres/server-checks.ts), evaluated by the real server as * each kind of role. Roles belong to the whole server, so this suite creates diff --git a/wiki/Environment-Variables.md b/wiki/Environment-Variables.md index 31d0a74af..1a227d9a5 100644 --- a/wiki/Environment-Variables.md +++ b/wiki/Environment-Variables.md @@ -537,7 +537,7 @@ from the next boot onward. The startup log prints what is actually in effect: [DB] journal_mode=DELETE, synchronous=FULL ``` -The maintenance tools that open the same file (on SQLite; with `TREK_DB_URL` they work on the Postgres database and never open a file) — `reset-admin.js` and `scripts/migrate-encryption.ts` — read the same two +The maintenance tools that open the same file on SQLite, `reset-admin.js` and `scripts/migrate-encryption.ts`, read the same two variables, so run them with the same environment (`docker exec` into the container does this for you). Otherwise the next key rotation or admin reset would quietly switch the file back to WAL.