diff --git a/server/CLAUDE.md b/server/CLAUDE.md index ad56e4487..dd5c62066 100644 --- a/server/CLAUDE.md +++ b/server/CLAUDE.md @@ -29,7 +29,7 @@ npm run db:call-graph -- --sync --tx [--domains nest/days,…] # sync DB-touchi npm run lint:size # no file in src/ or scripts/ past 1000 lines, none in tests/ past 2000, longer ones only shrink (CI gate) npm run lint:boundaries # import cycles and cross-domain reach-ins may only shrink (CI gate) npm run lint:dialect # SQLite-only SQL spellings under src/ may only shrink (CI gate) -npm run lint:engine-dispatch # isSqlite(/isPostgres(/platform instanceof outside src/db/dialect/ and src/db/engine/ may only shrink (CI gate) +npm run lint:engine-dispatch # engine checks (isSqlite(/isPostgres(, instanceof or a comparison on a driver or platform class, a comparison with or case on 'sqlite'/'postgres') outside src/db/dialect/ and src/db/engine/ may only shrink (CI gate) npm run probe:pg # dialect helpers + the repository statements it reaches against Postgres (CI job server-postgres; needs TREK_PG_PROBE_URL) npm run test:pg # the Postgres lane (CI job server-postgres, on 14 and 18; needs TREK_TEST_DB_URL) npm run lint:tx # methods writing more than once outside one transaction may only shrink (CI gate) diff --git a/server/scripts/engine-dispatch-ratchet.mjs b/server/scripts/engine-dispatch-ratchet.mjs index 29e4ca0cb..5eca224ab 100644 --- a/server/scripts/engine-dispatch-ratchet.mjs +++ b/server/scripts/engine-dispatch-ratchet.mjs @@ -6,24 +6,39 @@ * What differs between SQLite and Postgres has two homes: the SQL helpers in * src/db/dialect/ and the engine implementations in src/db/engine/ (the * driver, the schema bootstrap, maintenance, backups). Anywhere else, an - * `isSqlite(`/`isPostgres(` check, an `instanceof` on a platform class or a - * comparison on the engine's name (`readEnv().db.engine === 'postgres'`) is a - * branch a third engine would have to find by searching, so each file is held - * to its entry in scripts/engine-dispatch-baseline.json and a file without one - * holds none (scripts/lib/count-ratchet.mjs has the rules). Comments do not - * count. + * `isSqlite(`/`isPostgres(` check, an `instanceof` on a driver or platform + * class, a comparison with a driver class (`config.driver !== + * SharedSqliteDriver`), and any comparison with or `case` on an engine's name + * (`db.engine === 'postgres'`, `engine !== 'sqlite'`, `case 'postgres':`) is + * a branch a third engine would have to find by searching, so each file is + * held to its entry in scripts/engine-dispatch-baseline.json and a file + * without one holds none (scripts/lib/count-ratchet.mjs has the rules). + * Comments do not count. * * npm run lint:engine-dispatch check against the baseline (CI) * npm run lint:engine-dispatch -- --update lower the counts; never raises or adds an entry */ import { cliMain, stripComments } from './lib/count-ratchet.mjs'; +/** An engine's name as a string literal. */ +const ENGINE_NAME = String.raw`['"\x60](?:sqlite|postgres)['"\x60]`; + +/** A driver or platform class of either engine: MikroORM's (PostgreSqlPlatform) and ours (SharedSqliteDriver). */ +const ENGINE_CLASS = String.raw`\b\w*(?:Sqlite|PostgreSql)\w*(?:Driver|Platform)\b`; + const DISPATCH = new RegExp( [ - /\bis(?:Sqlite|Postgres)\s*\(/.source, - /\binstanceof\s+(?:Sqlite|BasePostgreSql|PostgreSql)Platform\b/.source, - // A comparison on the engine's name: `db.engine === 'postgres'`, `engine.id !== 'sqlite'`. - /\.(?:engine|id)\s*[!=]==?\s*['"](?:sqlite|postgres)['"]/.source, + String.raw`\bis(?:Sqlite|Postgres)\s*\(`, + String.raw`\binstanceof\s+` + ENGINE_CLASS, + // A comparison with an engine's name, whatever stands on the other side + // (`db.engine === 'postgres'`, `engine !== 'sqlite'`, `'postgres' == kind`), + // and a switch over it. + String.raw`[!=]==?\s*` + ENGINE_NAME, + ENGINE_NAME + String.raw`\s*[!=]==?`, + String.raw`\bcase\s+` + ENGINE_NAME + String.raw`\s*:`, + // A comparison with a driver or platform class. + String.raw`[!=]==?\s*` + ENGINE_CLASS, + ENGINE_CLASS + String.raw`\s*[!=]==?`, ].join('|'), 'g', ); @@ -42,7 +57,9 @@ export const check = { root: 'src', baseline: 'scripts/engine-dispatch-baseline.json', unit: 'engine check(s)', - advice: 'Dispatch through a helper in src/db/dialect/ or the DatabaseEngine in src/db/engine/ instead.', + advice: + 'Move the check into src/db/dialect/ (SQL that differs per engine) or the DatabaseEngine in src/db/engine/ ' + + '(anything else, such as a guard that refuses an engine), and call that helper here instead.', include: (file) => file.endsWith('.ts') && !ENGINE_HOMES.some((home) => file.startsWith(home)), count: (text) => countEngineDispatch(text), }; diff --git a/server/src/db/engine/index.ts b/server/src/db/engine/index.ts index f4d685ea8..a5d9a8efe 100644 --- a/server/src/db/engine/index.ts +++ b/server/src/db/engine/index.ts @@ -2,6 +2,7 @@ import { readEnv } from '../../app-config'; import type { DbEngineSettings } from '../../app-config/db-settings'; import type { DbSettings } from '../../app-config/derive'; import { ALL_ENTITIES } from '../entities'; +import { SharedSqliteDriver } from '../orm-driver'; import type { DatabaseEngine } from './engine'; import { PostgresEngine } from './postgres/postgres-engine'; import { SqliteEngine } from './sqlite/sqlite-engine'; @@ -34,6 +35,17 @@ export function postgresTarget(db: DbSettings): { url: string; binDir: string | return { url: db.url, binDir: db.pgBinDir, poolMax: db.poolMax }; } +/** + * Refuses an ORM config that does not run on the SQLite engine, with + * `refusal` as the error. For the code that exists only for SQLite (the test + * schema snapshot), which must say so instead of starting a SQLite ORM on + * another engine's options; the check on the driver stays here, in the + * engine port, like every other question about the engine. + */ +export function assertSqliteOrmConfig(config: Options, refusal: string): void { + if (config.driver !== SharedSqliteDriver) throw new Error(refusal); +} + /** * The MikroORM config for `engine`: what every engine shares (entities, * migrations, seeders) and what the engine adds. `src/mikro-orm.config.ts` diff --git a/server/src/db/standalone-orm.ts b/server/src/db/standalone-orm.ts index f300bfff2..e7a830c7c 100644 --- a/server/src/db/standalone-orm.ts +++ b/server/src/db/standalone-orm.ts @@ -1,6 +1,6 @@ import mikroOrmConfig from '../mikro-orm.config'; +import { assertSqliteOrmConfig } from './engine'; import type { AnyOrm } from './orm'; -import { SharedSqliteDriver } from './orm-driver'; import { MikroORM as SqliteMikroORM } from '@mikro-orm/sqlite'; /** @@ -12,9 +12,10 @@ import { MikroORM as SqliteMikroORM } from '@mikro-orm/sqlite'; * SQLite driver's, so a config that names another engine is refused. */ export function createStandaloneOrm(): Promise { - if (mikroOrmConfig.driver !== SharedSqliteDriver) { - throw new Error('createStandaloneOrm builds the SQLite schema snapshot; unset TREK_DB_URL to run it.'); - } + assertSqliteOrmConfig( + mikroOrmConfig, + 'createStandaloneOrm builds the SQLite schema snapshot; unset TREK_DB_URL to run it.', + ); return SqliteMikroORM.init({ ...mikroOrmConfig, // Entity discovery is skipped deliberately. Migrations and seeders are raw diff --git a/server/tests/unit/scripts/engine-dispatch-ratchet.test.ts b/server/tests/unit/scripts/engine-dispatch-ratchet.test.ts index a63cec84a..da2198fc7 100644 --- a/server/tests/unit/scripts/engine-dispatch-ratchet.test.ts +++ b/server/tests/unit/scripts/engine-dispatch-ratchet.test.ts @@ -63,6 +63,26 @@ describe('lint:engine-dispatch', () => { expect(countEngineDispatch(`// ${IS_SQLITE}\n/* ${INSTANCE} */\nconst ok = 1;`)).toBe(0); }); + it.each([ + ['a destructured name', ["const { engine } = readEnv().db; if (engine === 'post", "gres') a();"].join('')], + ['the literal on the left', ["if ('sql", "ite' !== kind) a();"].join('')], + ['a switch', ["switch (readEnv().db.engine) { case 'post", "gres': a(); }"].join('')], + ['instanceof on a driver', ['if (em.getDriver() instanceof PostgreSql', 'Driver) a();'].join('')], + ['instanceof on our own driver', ['if (d instanceof TrekPostgreSql', 'Driver) a();'].join('')], + ['a comparison with a driver class', ['if (config.driver !== SharedSqlite', 'Driver) a();'].join('')], + ])('ENGDISP-005: counts an engine check spelled as %s', (_what, code) => { + expect(countEngineDispatch(code)).toBe(1); + const domain = run(serverRoot({ 'src/nest/trips/trips.service.ts': `${code}\n` })); + expect(domain.status).toBe(1); + expect(domain.out).toContain('src/nest/trips/trips.service.ts'); + expect(domain.out).toContain('src/db/engine/'); + }); + + it('ENGDISP-006: leaves names that only look like an engine alone', () => { + expect(countEngineDispatch("if (format === 'sqlite3') a(); const label = 'postgres';")).toBe(0); + expect(countEngineDispatch('if (driver === LocalDriver) a(); if (x instanceof S3Driver) b();')).toBe(0); + }); + it('ENGDISP-002: the dialect layer and the engine port may dispatch, any other file may not', () => { const text = `export const x = ${IS_SQLITE};\n`; expect(run(serverRoot({ 'src/db/dialect/a.ts': text, 'src/db/engine/sqlite/b.ts': text })).status).toBe(0);