chore(template): document traditional helper - #347
Merged
mk3008 merged 2 commits intoDec 30, 2025
Merged
Conversation
📝 WalkthroughWalkthroughAdds a "traditional" Postgres execution mode to the testkit client (alongside ZTD), with schema-based isolation, DDL/SQL application, fixture seeding, and configurable cleanup; updates docs, templates, tsconfigs, and tests, and extends public types and createTestkitClient options to select execution mode. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Developer
participant Client as testkit-client
participant Files as DDL / Fixture Files
participant DB as Postgres
Developer->>Client: createTestkitClient(fixtures, {mode: 'traditional'})
Client->>DB: CONNECT
alt isolation: 'schema'
Client->>DB: CREATE SCHEMA "schema_xxx"
Client->>DB: SET search_path = "schema_xxx"
end
Client->>Files: Read DDL/.sql files (if present)
Files-->>Client: DDL statements
Client->>DB: Execute DDL statements
Client->>DB: INSERT fixture rows (seed)
Developer->>Client: Run tests (queries)
Client->>DB: Execute queries (profile/log per-query)
Developer->>Client: Tests complete
alt cleanup: 'drop_schema'
Client->>DB: DROP SCHEMA "schema_xxx"
else cleanup: 'custom_sql'
Client->>DB: Execute cleanupSql statements
else cleanup: 'none'
Note over Client,DB: No cleanup executed
end
Client->>DB: CLOSE
Client-->>Developer: ZtdPlaygroundClient finished
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly Related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
playgrounds/ztd-playground/tests/support/testkit-client.test.ts (1)
42-44: Consider resetting module-level state between tests.The
afterEachonly cleansprocess.env.DATABASE_URL, but thetestkit-clientmodule maintainssharedPgClientandsharedQueryablestate. If one test pollutes this state, subsequent tests may behave unexpectedly. Consider resetting module state or usingvi.resetModules()between tests.🔎 Suggested enhancement
afterEach(() => { delete process.env.DATABASE_URL; + vi.resetModules(); }); + +beforeAll(async () => { + // Re-import after resetModules in afterEach +});Alternatively, since you're dynamically importing in
beforeAll, you could move it tobeforeEachto get a fresh module per test.packages/ztd-cli/templates/tests/support/testkit-client.ts (2)
649-671: SQL file execution order is non-deterministic.
readdirdoes not guarantee ordering, so DDL files may execute in different orders across runs. If schema dependencies exist between files (e.g.,01_tables.sqlbefore02_constraints.sql), this could cause failures. Consider sorting entries by name.🔎 Proposed fix for deterministic file ordering
const entries = await fsPromises.readdir(directory, { withFileTypes: true }); - for (const entry of entries) { + const sqlFiles = entries + .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.sql')) + .sort((a, b) => a.name.localeCompare(b.name)); + for (const entry of sqlFiles) { - if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.sql')) { - continue; - } const filePath = path.join(directory, entry.name);
673-695: Row-by-row inserts may be slow for large fixtures.Each fixture row triggers a separate
INSERTstatement. For large fixtures, this could significantly slow down test setup. Consider batching inserts using multi-valueVALUESclauses.🔎 Example batch insert approach
// Batch multiple rows into single INSERT for better performance const BATCH_SIZE = 100; for (let i = 0; i < fixture.rows.length; i += BATCH_SIZE) { const batch = fixture.rows.slice(i, i + BATCH_SIZE); const allValues: unknown[] = []; const rowPlaceholders = batch.map((row, rowIdx) => { const values = columnNames.map((col) => Object.prototype.hasOwnProperty.call(row, col) ? row[col] : null ); allValues.push(...values); const offset = rowIdx * columnNames.length; return `(${columnNames.map((_, j) => `$${offset + j + 1}`).join(', ')})`; }); await client.query( `INSERT INTO ${tableIdentifier} (${columnsSql}) VALUES ${rowPlaceholders.join(', ')}`, allValues ); }playgrounds/ztd-playground/tests/support/testkit-client.ts (2)
155-157: Consider guarding against empty string for schemaName.If
config?.schemaNameis an empty string, it will be used instead of generating a unique name, which could cause conflicts or invalid SQL.🔎 Proposed fix to ensure non-empty schemaName
- const schemaName = isolation === 'schema' ? config?.schemaName ?? generateSchemaName() : undefined; + const schemaName = isolation === 'schema' + ? (config?.schemaName?.trim() || generateSchemaName()) + : undefined;
295-309: Add type guards to prevent runtime errors from invalid fixture schemas.The type assertions at lines 297 and 301 could throw if
fixture.schema.columnsdoesn't match the expected shape. Consider adding validation or try-catch blocks.🔎 Proposed fix with safer type checking
function getColumnNamesFromFixture(fixture: TableFixture): string[] { if (fixture.schema && Array.isArray((fixture.schema as { columns?: unknown }).columns)) { - return (fixture.schema as { columns: { name: string }[] }).columns.map((column) => column.name); + const columns = (fixture.schema as { columns: unknown[] }).columns; + return columns + .filter((col): col is { name: string } => typeof col === 'object' && col !== null && 'name' in col) + .map((col) => col.name); } if (fixture.schema && 'columns' in fixture.schema && typeof fixture.schema.columns === 'object') { - return Object.keys(fixture.schema.columns); + return Object.keys(fixture.schema.columns ?? {}); } if (fixture.rows.length > 0) { return Object.keys(fixture.rows[0]); } return []; }
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdpackages/ztd-cli/templates/README.mdpackages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/tsconfig.jsonplaygrounds/ztd-playground/AGENTS.mdplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Remove console debugging before committing.
Files:
playgrounds/ztd-playground/tests/support/testkit-client.test.tspackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
playgrounds/ztd-playground/tests/**/*.test.{ts,tsx}
📄 CodeRabbit inference engine (playgrounds/ztd-playground/AGENTS.md)
playgrounds/ztd-playground/tests/**/*.test.{ts,tsx}: Always wire Postgres execution throughtests/support/testkit-client.tswhich opens apg.Clientand passes it into@rawsql-ts/pg-testkit
Never issue DDL statements against Postgres from the playground; all CRUD operations must flow through pg-testkit so they resolve to fixture-backedSELECTqueries
ImportZtdConfig,ZtdRowShapes,ZtdTableName, andtableFixture()fromtests/generated/ztd-row-map.generated.tsand trust the generated helpers for row shapes instead of duplicating row interfaces
Provide explicit fixtures for each test usingtableFixture('schema.table', [{ ... }])pattern
Do not reuse shared mutable data between tests; do not insert, update, or delete data directly; rely on the rewrite helper instead
Files:
playgrounds/ztd-playground/tests/support/testkit-client.test.ts
playgrounds/ztd-playground/**/*.{ts,tsx,sql,md,json,yml,yaml,js}
📄 CodeRabbit inference engine (playgrounds/ztd-playground/AGENTS.md)
Use
pnpm formatto normalize TypeScript, SQL, Markdown, and config files; do not hand-edit whitespace or indentation
Files:
playgrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
playgrounds/ztd-playground/**/*.{ts,tsx,js}
📄 CodeRabbit inference engine (playgrounds/ztd-playground/AGENTS.md)
Run
pnpm lintregularly andpnpm lint:fixwhen ESLint reports autofixable issues; these scripts are the single source of truth for formatting/linting
Files:
playgrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
packages/ztd-cli/templates/tests/**/*.{ts,tsx}
📄 CodeRabbit inference engine (packages/ztd-cli/templates/AGENTS.md)
packages/ztd-cli/templates/tests/**/*.{ts,tsx}: Always import table types fromtests/generated/ztd-row-map.generated.tswhen constructing test scenarios and rerunnpx ztd ztd-configwhenever schema changes
In ZTD tests, do not assert auto-generated ID values (sequence/identity); assert only that an ID exists with correct type or differs from known IDs, or assert specific ID values only when the ID is a business rule (not infrastructure)
ZTD tests must be safe to run in parallel against a single Postgres instance; use one shared instance with multiple connections and do not create per-test databases or schemas
Files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
🧠 Learnings (53)
📓 Common learnings
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/src/**/*.{ts,tsx} : Do not add fallbacks or alternative logic paths in `src/` to accommodate ZTD/testkit tooling limitations; instead, report the issue with exact SQL, error message, minimal reproduction, and expected behavior
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Always wire Postgres execution through `tests/support/testkit-client.ts` which opens a `pg.Client` and passes it into `rawsql-ts/pg-testkit`
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: ZTD tests should be safe to run in parallel against a single Postgres instance because no physical tables are created or mutated; do not start multiple Postgres instances per test file/worker
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/**/*.{ts,tsx} : ZTD tests must be safe to run in parallel against a single Postgres instance; use one shared instance with multiple connections and do not create per-test databases or schemas
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/tests/**/*.{test,spec}.{ts,tsx} : Add test coverage for fixture resolution paths, CRUD rewrite transformations, CTE + multi-statement handling, fallback logic, identifier casing rules, and error diagnostics in testkit-core
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to {packages/pg-testkit,packages/sqlite-testkit}/**/*.test.{ts,tsx} : Do not treat the backing DB as a migration target. The DB engine is only for planning/type-checking. Never execute `CREATE TABLE`, `ALTER TABLE`, or seed `INSERT`s over a pg-testkit connection.
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: All CRUD operations (INSERT, UPDATE, DELETE, RETURNING) must be rewritten by testkit-core before reaching pg-testkit; the driver must execute only rewritten SELECT queries against fixtures
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Never issue DDL statements against Postgres from the playground; all CRUD operations must flow through pg-testkit so they resolve to fixture-backed `SELECT` queries
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to ztd.config.json : Application SQL can omit schema qualifiers (e.g., `SELECT ... FROM users`). pg-testkit maps those references to canonical `schema.table` keys by consulting the `ddl.defaultSchema` / `ddl.searchPath` block in `ztd.config.json` before looking up fixtures or DDL metadata.
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Do not mock QueryResult in pg-testkit; use real PostgreSQL execution results
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Support full parallel test execution by ensuring each query sees an isolated fixture universe with no shared state
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/src/**/*.{ts,tsx} : Do not add fallbacks or alternative logic paths in `src/` to accommodate ZTD/testkit tooling limitations; instead, report the issue with exact SQL, error message, minimal reproduction, and expected behavior
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/README.mdpackages/ztd-cli/templates/tsconfig.jsonplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/tests/**/*.{test,spec}.{ts,tsx} : Add test coverage for fixture resolution paths, CRUD rewrite transformations, CTE + multi-statement handling, fallback logic, identifier casing rules, and error diagnostics in testkit-core
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdpackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/**/*.{ts,tsx} : Always import table types from `tests/generated/ztd-row-map.generated.ts` when constructing test scenarios and rerun `npx ztd ztd-config` whenever schema changes
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/tsconfig.jsonplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/**/*.{ts,tsx} : ZTD tests must be safe to run in parallel against a single Postgres instance; use one shared instance with multiple connections and do not create per-test databases or schemas
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/ztd/{AGENTS.md,README.md} : Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction; these are guidance documents for AI and repository maintainers
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdpackages/ztd-cli/templates/README.md
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Always wire Postgres execution through `tests/support/testkit-client.ts` which opens a `pg.Client` and passes it into `rawsql-ts/pg-testkit`
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : In rawsql-ts/testkit-core, remain DBMS-agnostic with no Postgres/SQLite conditionals or behavior
Applied to files:
.changeset/traditional-cli-guidance.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Never issue DDL statements against Postgres from the playground; all CRUD operations must flow through pg-testkit so they resolve to fixture-backed `SELECT` queries
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to {packages/pg-testkit,packages/sqlite-testkit}/**/*.test.{ts,tsx} : Do not treat the backing DB as a migration target. The DB engine is only for planning/type-checking. Never execute `CREATE TABLE`, `ALTER TABLE`, or seed `INSERT`s over a pg-testkit connection.
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.md
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx,js} : All SQL must flow through the testkit-core AST rewriter before execution; new rewrite behavior must be added to testkit-core first, then threaded into sqlite-testkit
Applied to files:
.changeset/traditional-cli-guidance.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tspackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to {packages/pg-testkit,packages/sqlite-testkit}/**/*.test.{ts,tsx} : Do not hand-construct `QueryResult` or mock `Client#query`. All tests must flow through the rewrite pipeline + fixtures.
Applied to files:
.changeset/traditional-cli-guidance.mdpackages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: ZTD tests should be safe to run in parallel against a single Postgres instance because no physical tables are created or mutated; do not start multiple Postgres instances per test file/worker
Applied to files:
packages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/README.md
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Document any deviations from the standard formatting workflow in AGENTS so AI contributors understand that formatting is owned by the scripts, not by hand edits.
Applied to files:
packages/ztd-cli/templates/AGENTS.md
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Include actionable hints (table/column names) in error messages from pg-testkit to aid debugging
Applied to files:
packages/ztd-cli/templates/AGENTS.md
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.{ts,tsx,js} : All new features added to pg-testkit must have corresponding tests in the tests/ directory
Applied to files:
packages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tspackages/ztd-cli/templates/tsconfig.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/**/*.{ts,tsx} : In ZTD tests, do not assert auto-generated ID values (sequence/identity); assert only that an ID exists with correct type or differs from known IDs, or assert specific ID values only when the ID is a business rule (not infrastructure)
Applied to files:
packages/ztd-cli/templates/AGENTS.mdpackages/ztd-cli/templates/tsconfig.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not rely on real table state between queries even for in-memory databases; all perceived state must originate from fixtures supplied to the driver
Applied to files:
packages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Do not reuse shared mutable data between tests; do not insert, update, or delete data directly; rely on the rewrite helper instead
Applied to files:
packages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to packages/pg-testkit/src/**/*.{ts,tsx} : Application SQL may freely use normal CRUD (`INSERT`, `UPDATE`, `DELETE`). pg-testkit will automatically rewrite them into `SELECT` queries. Library code must never bypass the rewriter.
Applied to files:
packages/ztd-cli/templates/AGENTS.mdplaygrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Validate fixtures at construction time to keep per-query interception fast; respect passthrough tables and wildcard overrides driven by testkit-core
Applied to files:
playgrounds/ztd-playground/tests/support/testkit-client.test.tspackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : warn and passthrough modes in testkit-core must behave predictably and never silently rewrite incorrect SQL
Applied to files:
playgrounds/ztd-playground/tests/support/testkit-client.test.tspackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: The core role of rawsql-ts/testkit-core is to rewrite all CRUD SQL into fixture-backed SELECT queries without creating, reading, or mutating physical tables
Applied to files:
playgrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.mdpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Do not mock QueryResult in pg-testkit; use real PostgreSQL execution results
Applied to files:
playgrounds/ztd-playground/tests/support/testkit-client.test.tsplaygrounds/ztd-playground/README.md
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/{ztd/ddl/**/*.sql,ztd/enums/**/*.md,ztd/domain-specs/**/*.md} : Keep every table definition inside `ztd/ddl/<schema>.sql`, enums under `ztd/enums/*.md`, and executable specs inside `ztd/domain-specs/*.md`
Applied to files:
playgrounds/ztd-playground/README.mdpackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/generated/ztd-row-map.generated.ts : `tests/generated/ztd-row-map.generated.ts` is the canonical source for typed fixtures and is generated by `pnpm --filter ztd-playground exec ztd ztd-config`
Applied to files:
playgrounds/ztd-playground/README.mdplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/generated/** : Never commit auto-generated files in `tests/generated/` directory; run `npx ztd ztd-config` after cloning or in clean environments if TypeScript reports missing modules
Applied to files:
packages/ztd-cli/templates/tsconfig.jsonpackages/ztd-cli/templates/README.md
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/src/**/*.{ts,tsx} : Keep production code in `src/` decoupled from the generated row map (`tests/generated/ztd-row-map.generated.ts`); operate only on row interfaces and use repositories to return application-facing DTOs
Applied to files:
packages/ztd-cli/templates/tsconfig.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:04.844Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/ztd/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:04.844Z
Learning: If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-02T22:57:21.022Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.022Z
Learning: Applies to packages/core/tsconfig.browser.json : Browser bundles depend on tsconfig.browser.json
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/**/*.{ts,tsx,sql,md,json,yml,yaml,js} : Use `pnpm format` to normalize TypeScript, SQL, Markdown, and config files; do not hand-edit whitespace or indentation
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx,js} : No stray console.log or temp files outside ./tmp/ directory
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Import `ZtdConfig`, `ZtdRowShapes`, `ZtdTableName`, and `tableFixture()` from `tests/generated/ztd-row-map.generated.ts` and trust the generated helpers for row shapes instead of duplicating row interfaces
Applied to files:
packages/ztd-cli/templates/tsconfig.jsonplaygrounds/ztd-playground/AGENTS.mdpackages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:21.022Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.022Z
Learning: Applies to packages/core/src/**/*.ts : Ensure TypeScript errors stay at zero before running tests
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-02T22:57:21.022Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.022Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Add or update tests whenever adding features or fixing bugs
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.test.{ts,tsx} : Use Vitest for both unit and integration-level coverage; integration tests should exercise real better-sqlite3 connections
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-02T22:57:21.022Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.022Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Follow TDD cycle: Red (failing test) → Compile (fix TypeScript errors) → Green (minimum implementation) → Refactor (clean code) → Verify (intentionally break test)
Applied to files:
packages/ztd-cli/templates/tsconfig.json
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Do not use hand-written QueryResult-like objects in testkit-core; use database engine execution for final SELECT results
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/generated/** : Never edit files under `tests/generated/`; regenerate them with `pnpm --filter ztd-playground exec ztd ztd-config`
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Humans own schema definitions in `ztd/ddl/`, domain semantics in `ztd/domain-specs/`, enumerations in `ztd/enums/`, and repository interfaces; AI assists with SQL generation, fixture updates, and TypeScript structures while ensuring adherence to these definitions
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Provide explicit fixtures for each test using `tableFixture('schema.table', [{ ... }])` pattern
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : INSERT rewrites should convert to SELECT ... FROM (VALUES fixture_rows) with correct RETURNING projection
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: All CRUD operations (INSERT, UPDATE, DELETE, RETURNING) must be rewritten by testkit-core before reaching pg-testkit; the driver must execute only rewritten SELECT queries against fixtures
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : UPDATE rewrites should apply updates to fixture snapshot and project updated rows via SELECT
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : DELETE rewrites should remove matching rows in fixture snapshot and return deleted rows via SELECT
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : withFixtures() must return a shallow copy of the driver, inherit base configuration, and layer additional fixtures/scenario-specific data on top
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.tsplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Load DDL-based fixtures from canonical schema files (tests/generated/ztd-row-map.generated.ts, ztd/ddl/, or legacy ddl/ directory) rather than reverse-engineering the database structure
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.tspackages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:04.844Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/ztd/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:04.844Z
Learning: Applies to packages/ztd-cli/templates/ztd/**/ztd/enums/**/*.md : Do not modify or append new enums in specification files unless explicitly instructed by a human
Applied to files:
packages/ztd-cli/templates/README.md
📚 Learning: 2025-12-13T04:10:04.844Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/ztd/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:04.844Z
Learning: Applies to packages/ztd-cli/templates/ztd/**/ztd/domain-specs/**/*.md : Only the first top-level SELECT block in domain-specs files should be considered executable logic
Applied to files:
packages/ztd-cli/templates/README.md
📚 Learning: 2025-12-13T04:10:04.844Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/ztd/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:04.844Z
Learning: Applies to packages/ztd-cli/templates/ztd/**/ztd/domain-specs/**/*.md : Do not reorder or optimize SQL in domain-specs files unless explicitly instructed; preserve the semantic meaning as given
Applied to files:
packages/ztd-cli/templates/README.md
📚 Learning: 2025-12-13T04:10:04.844Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/ztd/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:04.844Z
Learning: Applies to packages/ztd-cli/templates/ztd/**/ztd/domain-specs/**/*.md : Never ignore the human-written description above the SQL block in domain-specs files
Applied to files:
packages/ztd-cli/templates/README.md
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/src/**/*repository*.{ts,tsx} : Do not explicitly assign values to sequence/identity columns in INSERT statements unless explicitly instructed; omit them from repository method inputs by default
Applied to files:
packages/ztd-cli/templates/README.md
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to ztd.config.json : Application SQL can omit schema qualifiers (e.g., `SELECT ... FROM users`). pg-testkit maps those references to canonical `schema.table` keys by consulting the `ddl.defaultSchema` / `ddl.searchPath` block in `ztd.config.json` before looking up fixtures or DDL metadata.
Applied to files:
packages/ztd-cli/templates/README.mdplaygrounds/ztd-playground/tests/support/testkit-client.ts
🧬 Code graph analysis (1)
packages/ztd-cli/templates/tests/support/testkit-client.ts (1)
packages/testkit-core/src/types/index.ts (1)
TableFixture(29-31)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build-and-test (20.x)
🔇 Additional comments (23)
packages/ztd-cli/templates/README.md (1)
212-216: Documentation clearly explains the new traditional execution mode.The guidance on when to use traditional mode (for locks, isolation, constraints) is helpful. The explanation of cleanup strategies and the
isolation: 'none'option for pre-existing schemas is clear.packages/ztd-cli/templates/AGENTS.md (1)
59-61: Good addition of traditional mode guidance for ZTD tests.The documentation clearly explains the
createTestkitClient()options and cleanup strategies. The guidance onisolation: 'none'for existing schemas is appropriate..changeset/traditional-cli-guidance.md (1)
1-5: Changeset is appropriate for this documentation and test update.The patch version bump correctly reflects the nature of changes (documentation and test additions without breaking changes).
playgrounds/ztd-playground/AGENTS.md (1)
22-22: Traditional mode documentation is consistent with templates.The guidance mirrors the template AGENTS.md and correctly describes the traditional execution workflow.
playgrounds/ztd-playground/README.md (1)
47-47: Comprehensive documentation for traditional mode in playground context.The guidance clearly explains when and how to use traditional mode, including the
schemaNameoption for referencing existing schemas.playgrounds/ztd-playground/tests/support/testkit-client.test.ts (2)
51-80: Test validates the complete traditional execution lifecycle.Good coverage of schema creation,
search_pathsetup, fixture seeding, and cleanup ordering. The assertion thatDROP SCHEMAoccurs after the user query ensures proper teardown sequencing.
82-104: Custom cleanup SQL test correctly verifies the alternative cleanup path.The test properly validates that
custom_sqlcleanup executes the provided SQL instead of dropping the schema.packages/ztd-cli/templates/tests/support/testkit-client.ts (3)
30-50: Well-designed type definitions for traditional execution configuration.The types are clear and provide good flexibility for different isolation and cleanup strategies.
200-206: Clean mode dispatch logic.The separation between ZTD and traditional client creation is clear and maintainable.
723-726:quoteIdentifierimplementation is correct for Postgres.Properly escapes embedded double quotes by doubling them.
packages/ztd-cli/templates/tsconfig.json (1)
8-8: Addsrc/**/*.tsto theincludearray.The template has production code in
src/db/sql-client.tsthat should be compiled, but the current configuration only includes test files."include": ["tests/**/*.ts", "src/**/*.ts"]playgrounds/ztd-playground/tests/support/testkit-client.ts (12)
1-10: LGTM! Imports support both execution modes.The addition of
fsandpathimports enables DDL file processing for traditional mode while maintaining existing ZTD dependencies.
11-27: LGTM! Type definitions are clear and well-structured.The type hierarchy properly models the traditional execution configuration options with appropriate optionality.
113-123: LGTM! Clean routing between execution modes.The mode-based dispatch maintains backward compatibility while enabling traditional execution when configured.
125-144: LGTM! ZTD client extraction maintains existing behavior.The refactor to a separate function preserves the original ZTD workflow without changes.
162-187: LGTM! Initialization is properly idempotent and secured.The cached promise ensures setup runs once, and SQL injection is prevented through consistent use of
quoteIdentifierand parameterized queries.
189-210: LGTM! Cleanup logic is properly guarded and secured.The cleanup strategies are correctly implemented with run-once protection and SQL injection safeguards.
212-229: LGTM! Query and close methods handle lifecycle correctly.The initialization guard in
query()and the comprehensive error handling inclose()ensure proper resource management.
231-238: LGTM! Mode resolution follows clear precedence.The fallback chain (parameter → environment → default) is intuitive and correctly implemented.
240-244: LGTM! Schema name generation provides sufficient uniqueness.The combination of timestamp and random suffix should prevent collisions in parallel test execution.
270-293: LGTM! Fixture seeding is secure and handles edge cases.Parameterized queries prevent SQL injection, and the null handling for missing columns is appropriate.
311-319: LGTM! Table identifier construction correctly handles qualified names.The logic properly parses schema-qualified table names and applies the isolation schema when configured.
321-324: LGTM! PostgreSQL identifier quoting is correctly implemented.The double-quote escaping follows PostgreSQL standards.
Comment on lines
+246
to
+268
| async function applySqlFiles(client: Client, directories: string[]): Promise<void> { | ||
| // Execute each .sql script so the physical schema matches the ZTD DDL definition. | ||
| for (const directory of directories) { | ||
| if (!existsSync(directory)) { | ||
| continue; | ||
| } | ||
|
|
||
| const entries = await fsPromises.readdir(directory, { withFileTypes: true }); | ||
| for (const entry of entries) { | ||
| if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.sql')) { | ||
| continue; | ||
| } | ||
|
|
||
| const filePath = path.join(directory, entry.name); | ||
| const sql = await fsPromises.readFile(filePath, 'utf8'); | ||
| if (!sql.trim()) { | ||
| continue; | ||
| } | ||
|
|
||
| await client.query(sql); | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Sort SQL files before execution to ensure deterministic DDL application.
The readdir() order is not guaranteed to be consistent across systems. If DDL files have dependencies (e.g., foreign keys, views), random execution order could cause failures.
🔎 Proposed fix to sort files alphabetically
const entries = await fsPromises.readdir(directory, { withFileTypes: true });
+ const sqlFiles = entries
+ .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.sql'))
+ .sort((a, b) => a.name.localeCompare(b.name));
+
- for (const entry of entries) {
- if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.sql')) {
- continue;
- }
+ for (const entry of sqlFiles) {
const filePath = path.join(directory, entry.name);
const sql = await fsPromises.readFile(filePath, 'utf8');
if (!sql.trim()) {
continue;
}
await client.query(sql);
}🤖 Prompt for AI Agents
In playgrounds/ztd-playground/tests/support/testkit-client.ts around lines 246
to 268, the function applySqlFiles iterates filesystem entries in
nondeterministic order; sort the SQL files before executing them to ensure
deterministic DDL application. After reading entries (and/or after filtering to
files ending with .sql), sort the list by entry.name (use a stable comparison
like entry.name.localeCompare(other.name, undefined, { sensitivity: 'base' }) or
simple string compare) and then iterate the sorted list to read and execute each
SQL file.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
packages/ztd-cli/templates/tests/support/testkit-client.ts (2)
665-687: Consider adding error context for SQL file execution failures.If a DDL file fails to execute, the current implementation propagates the raw database error. Consider wrapping execution errors with the file path for easier debugging.
🔎 Proposed enhancement
const filePath = path.join(directory, entry.name); const sql = await fsPromises.readFile(filePath, 'utf8'); if (!sql.trim()) { continue; } - await client.query(sql); + try { + await client.query(sql); + } catch (error) { + throw new Error(`Failed to execute DDL file ${filePath}: ${error}`); + } } } }
659-663: Schema name collision risk is low but possible.The timestamp + random approach provides adequate uniqueness for most test suites. However, high-parallelism environments or rapid test execution could encounter collisions. Consider using a UUID or adding retry logic if collision failures occur in practice.
🔎 Alternative using crypto.randomUUID()
+import { randomUUID } from 'node:crypto'; + function generateSchemaName(): string { - const timestamp = Date.now().toString(36); - const random = Math.random().toString(36).slice(2, 7); - return `ztd_traditional_${timestamp}_${random}`; + const uuid = randomUUID().replace(/-/g, ''); + return `ztd_traditional_${uuid}`; }
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.changeset/calm-mice-close.mdpackages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
✅ Files skipped from review due to trivial changes (1)
- .changeset/calm-mice-close.md
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Remove console debugging before committing.
Files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
packages/ztd-cli/templates/tests/**/*.{ts,tsx}
📄 CodeRabbit inference engine (packages/ztd-cli/templates/AGENTS.md)
packages/ztd-cli/templates/tests/**/*.{ts,tsx}: Always import table types fromtests/generated/ztd-row-map.generated.tswhen constructing test scenarios and rerunnpx ztd ztd-configwhenever schema changes
In ZTD tests, do not assert auto-generated ID values (sequence/identity); assert only that an ID exists with correct type or differs from known IDs, or assert specific ID values only when the ID is a business rule (not infrastructure)
ZTD tests must be safe to run in parallel against a single Postgres instance; use one shared instance with multiple connections and do not create per-test databases or schemas
Files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
🧠 Learnings (43)
📓 Common learnings
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/src/**/*.{ts,tsx} : Do not add fallbacks or alternative logic paths in `src/` to accommodate ZTD/testkit tooling limitations; instead, report the issue with exact SQL, error message, minimal reproduction, and expected behavior
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Always wire Postgres execution through `tests/support/testkit-client.ts` which opens a `pg.Client` and passes it into `rawsql-ts/pg-testkit`
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to {packages/pg-testkit,packages/sqlite-testkit}/**/*.test.{ts,tsx} : Do not treat the backing DB as a migration target. The DB engine is only for planning/type-checking. Never execute `CREATE TABLE`, `ALTER TABLE`, or seed `INSERT`s over a pg-testkit connection.
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/tests/**/*.{test,spec}.{ts,tsx} : Add test coverage for fixture resolution paths, CRUD rewrite transformations, CTE + multi-statement handling, fallback logic, identifier casing rules, and error diagnostics in testkit-core
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Never issue DDL statements against Postgres from the playground; all CRUD operations must flow through pg-testkit so they resolve to fixture-backed `SELECT` queries
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/**/*.{ts,tsx} : ZTD tests must be safe to run in parallel against a single Postgres instance; use one shared instance with multiple connections and do not create per-test databases or schemas
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: All CRUD operations (INSERT, UPDATE, DELETE, RETURNING) must be rewritten by testkit-core before reaching pg-testkit; the driver must execute only rewritten SELECT queries against fixtures
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to {packages/pg-testkit,packages/sqlite-testkit}/**/*.test.{ts,tsx} : Do not hand-construct `QueryResult` or mock `Client#query`. All tests must flow through the rewrite pipeline + fixtures.
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: ZTD tests should be safe to run in parallel against a single Postgres instance because no physical tables are created or mutated; do not start multiple Postgres instances per test file/worker
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to ztd.config.json : Application SQL can omit schema qualifiers (e.g., `SELECT ... FROM users`). pg-testkit maps those references to canonical `schema.table` keys by consulting the `ddl.defaultSchema` / `ddl.searchPath` block in `ztd.config.json` before looking up fixtures or DDL metadata.
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : In rawsql-ts/testkit-core, remain DBMS-agnostic with no Postgres/SQLite conditionals or behavior
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/tests/**/*.{test,spec}.{ts,tsx} : Add test coverage for fixture resolution paths, CRUD rewrite transformations, CTE + multi-statement handling, fallback logic, identifier casing rules, and error diagnostics in testkit-core
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : In rawsql-ts/testkit-core, remain DBMS-agnostic with no Postgres/SQLite conditionals or behavior
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx,js} : All SQL must flow through the testkit-core AST rewriter before execution; new rewrite behavior must be added to testkit-core first, then threaded into sqlite-testkit
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : No code path bypasses testkit-core's rewrite pipeline
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.{ts,tsx,js} : All new features added to pg-testkit must have corresponding tests in the tests/ directory
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Intercept prepare, all, get, and run APIs to apply AST-based rewrite from testkit-core and execute the resulting SELECT against better-sqlite3
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to {packages/pg-testkit,packages/sqlite-testkit}/**/*.test.{ts,tsx} : Do not treat the backing DB as a migration target. The DB engine is only for planning/type-checking. Never execute `CREATE TABLE`, `ALTER TABLE`, or seed `INSERT`s over a pg-testkit connection.
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Do not use DBMS branching (if postgres, if sqlite, etc.) in testkit-core implementation
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not create cross-test global state or singleton fixtures in sqlite-testkit
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Do not rewrite SQL by string concatenation without AST in testkit-core
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:57:21.022Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.022Z
Learning: Applies to packages/core/src/**/*.ts : Prefer import { ... } from 'rawsql-ts' over deep relative paths
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Do not re-parse SQL after rewrite in testkit-core
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx,js} : No stray console.log or temp files outside ./tmp/ directory
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Ensure `packages/core/dist` outputs stay synchronized with the pnpm store copy that CLI tests consume. Run `pnpm --filter rawsql-ts build` which executes `scripts/sync-rawsql-dist.js` as a `postbuild` step.
Applied to files:
packages/drivers/pg-testkit/tsconfig.build.jsonpackages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not mock or hand-craft better-sqlite3 result shapes to bypass the rewrite pipeline
Applied to files:
packages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not add physical table management (CREATE TABLE, ALTER TABLE, migrations) through the wrapped driver
Applied to files:
packages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.test.{ts,tsx} : Ensure tests remain deterministic regardless of file-backed vs. memory-backed SQLite configurations
Applied to files:
packages/drivers/sqlite-testkit/tsconfig.build.json
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : withFixtures() must return a shallow copy of the driver, inherit base configuration, and layer additional fixtures/scenario-specific data on top
Applied to files:
packages/drivers/sqlite-testkit/tsconfig.build.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Validate fixtures at construction time to keep per-query interception fast; respect passthrough tables and wildcard overrides driven by testkit-core
Applied to files:
packages/drivers/sqlite-testkit/tsconfig.build.jsonpackages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/src/**/*.{ts,tsx} : Do not add fallbacks or alternative logic paths in `src/` to accommodate ZTD/testkit tooling limitations; instead, report the issue with exact SQL, error message, minimal reproduction, and expected behavior
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/**/*.{ts,tsx} : Always import table types from `tests/generated/ztd-row-map.generated.ts` when constructing test scenarios and rerun `npx ztd ztd-config` whenever schema changes
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : warn and passthrough modes in testkit-core must behave predictably and never silently rewrite incorrect SQL
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/tests/**/*.{ts,tsx} : ZTD tests must be safe to run in parallel against a single Postgres instance; use one shared instance with multiple connections and do not create per-test databases or schemas
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Always wire Postgres execution through `tests/support/testkit-client.ts` which opens a `pg.Client` and passes it into `rawsql-ts/pg-testkit`
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Import `ZtdConfig`, `ZtdRowShapes`, `ZtdTableName`, and `tableFixture()` from `tests/generated/ztd-row-map.generated.ts` and trust the generated helpers for row shapes instead of duplicating row interfaces
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Do not use hand-written QueryResult-like objects in testkit-core; use database engine execution for final SELECT results
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Applies to packages/ztd-cli/templates/src/**/*.{ts,tsx} : Keep production code in `src/` decoupled from the generated row map (`tests/generated/ztd-row-map.generated.ts`); operate only on row interfaces and use repositories to return application-facing DTOs
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Connection lifecycle: driver.close() must close the wrapped database handle and multiple close() calls must be idempotent for test ergonomics
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/generated/ztd-row-map.generated.ts : `tests/generated/ztd-row-map.generated.ts` is the canonical source for typed fixtures and is generated by `pnpm --filter ztd-playground exec ztd ztd-config`
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Never issue DDL statements against Postgres from the playground; all CRUD operations must flow through pg-testkit so they resolve to fixture-backed `SELECT` queries
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/generated/** : Never edit files under `tests/generated/`; regenerate them with `pnpm --filter ztd-playground exec ztd ztd-config`
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-25T10:57:16.522Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/ztd-cli/templates/AGENTS.md:0-0
Timestamp: 2025-12-25T10:57:16.522Z
Learning: Humans own schema definitions in `ztd/ddl/`, domain semantics in `ztd/domain-specs/`, enumerations in `ztd/enums/`, and repository interfaces; AI assists with SQL generation, fixture updates, and TypeScript structures while ensuring adherence to these definitions
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:10:16.411Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: playgrounds/ztd-playground/AGENTS.md:0-0
Timestamp: 2025-12-13T04:10:16.411Z
Learning: Applies to playgrounds/ztd-playground/tests/**/*.test.{ts,tsx} : Provide explicit fixtures for each test using `tableFixture('schema.table', [{ ... }])` pattern
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to {packages/pg-testkit,packages/sqlite-testkit}/**/*.test.{ts,tsx} : Do not hand-construct `QueryResult` or mock `Client#query`. All tests must flow through the rewrite pipeline + fixtures.
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: The core role of rawsql-ts/testkit-core is to rewrite all CRUD SQL into fixture-backed SELECT queries without creating, reading, or mutating physical tables
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : INSERT rewrites should convert to SELECT ... FROM (VALUES fixture_rows) with correct RETURNING projection
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:57:55.637Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.637Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not rely on real table state between queries even for in-memory databases; all perceived state must originate from fixtures supplied to the driver
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: All CRUD operations (INSERT, UPDATE, DELETE, RETURNING) must be rewritten by testkit-core before reaching pg-testkit; the driver must execute only rewritten SELECT queries against fixtures
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : UPDATE rewrites should apply updates to fixture snapshot and project updated rows via SELECT
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-02T22:58:15.347Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.347Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : DELETE rewrites should remove matching rows in fixture snapshot and return deleted rows via SELECT
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-08T14:13:45.136Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T14:13:45.136Z
Learning: Applies to packages/pg-testkit/src/**/*.{ts,tsx} : Application SQL may freely use normal CRUD (`INSERT`, `UPDATE`, `DELETE`). pg-testkit will automatically rewrite them into `SELECT` queries. Library code must never bypass the rewriter.
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
📚 Learning: 2025-12-13T04:09:30.398Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-13T04:09:30.398Z
Learning: Load DDL-based fixtures from canonical schema files (tests/generated/ztd-row-map.generated.ts, ztd/ddl/, or legacy ddl/ directory) rather than reverse-engineering the database structure
Applied to files:
packages/ztd-cli/templates/tests/support/testkit-client.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build-and-test (20.x)
🔇 Additional comments (7)
packages/drivers/sqlite-testkit/tsconfig.build.json (1)
6-8: LGTM! Consistent with pg-testkit.The path mapping is identical to the one added in
pg-testkit/tsconfig.build.json, correctly aliasing@rawsql-ts/testkit-coreto the local dist output for both driver packages.packages/drivers/pg-testkit/tsconfig.build.json (1)
6-8: LGTM! Path mapping correctly configured for monorepo builds.The path mapping correctly aliases
@rawsql-ts/testkit-coreto the local dist output. Verification confirms:
testkit-coreis configured to build todist/index.jsanddist/index.d.ts- pnpm workspace dependency (
workspace:*) ensurestestkit-corebuilds beforepg-testkitpackages/ztd-cli/templates/tests/support/testkit-client.ts (5)
30-50: LGTM! Well-designed API surface.The new execution mode types and configuration options provide a clear, flexible interface for both ZTD and traditional execution modes.
196-206: LGTM! Clean mode-based routing.The dispatcher correctly routes to mode-specific client creators based on resolved execution mode.
386-604: Traditional mode implementation is correct and intentional.The traditional execution mode creates dedicated connections, applies DDL, and seeds real tables—an intentional departure from the ZTD fixture-backed approach. Schema-based isolation ensures parallel safety. The error handling in
close()correctly captures cleanup errors and ensuresclient.end()runs in the finally block.
689-742: LGTM! Helper functions are well-implemented.The utility functions correctly handle:
- Parameterized queries in
seedFixtureRows(SQL injection safe)- Flexible schema formats in
getColumnNamesFromFixture- Qualified and unqualified identifiers in
buildTableIdentifier- Proper SQL escaping in
quoteIdentifier
263-263: Fix type signature mismatch: third parameter should be required, not optional.The
onExecutecallback signature at line 263 marksfixturesAppliedas non-optional (fixturesApplied: string[]), but the pg-testkit API definition declares it as optional (fixtures?: string[]inCreatePgTestkitClientOptions). The implementation always passes the third parameter, so the type definition should be corrected to require it rather than having the callback use a stricter signature than the API allows.
mk3008
deleted the
346-add-traditional-execution-mode-to-ztd-connection-wrapper
branch
December 30, 2025 00:45
This was referenced Mar 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
New Features
Documentation
Bug Fixes
Tests
✏️ Tip: You can customize this high-level summary in your review settings.