feat: introduce @rawsql-ts/cli with init, ddl, and ztd-config commands, alongside new core and testkit packages.
#269
Conversation
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
… commands, alongside new core and testkit packages.
WalkthroughThis PR restructures the CLI tooling by removing the original Changes
Sequence DiagramsequenceDiagram
participant User
participant CLI as ZTD CLI
participant ConfigLoader as Config Loader
participant Generator as Code Generator
participant Watcher as File Watcher
participant Disk as Filesystem
User->>CLI: ztd-config --ddl-dir=ddl --watch
CLI->>ConfigLoader: loadZtdProjectConfig()
ConfigLoader->>Disk: Read ztd.config.json
Disk-->>ConfigLoader: Config (or defaults)
ConfigLoader-->>CLI: ZtdProjectConfig
CLI->>Generator: runGenerateZtdConfig(options)
Generator->>Disk: Read SQL files from ddl/
Disk-->>Generator: SQL sources
Generator->>Generator: snapshotTableMetadata()
Generator->>Disk: Write ztd-config.ts (TestRowMap)
Disk-->>Generator: Success
Generator-->>CLI: Generation complete
alt Watch Enabled
CLI->>Watcher: watchZtdConfig(ddlDirs, extensions)
Watcher->>Disk: Monitor files (add/change/unlink)
loop File Changes
Disk-->>Watcher: Event (debounce 150ms)
Watcher->>Generator: runGenerateZtdConfig()
Generator->>Disk: Update ztd-config.ts
Disk-->>Watcher: Written
Watcher-->>User: Log: "Regenerated..."
end
User->>User: Press Ctrl+C
CLI->>Watcher: Cleanup (SIGINT)
Watcher->>Disk: Close watchers
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes
Possibly related issues
Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (12)
packages/core/package.json (1)
18-18: Inconsistent package manager usage in release script.The release script mixes
npm runfor build/test/lint steps withpnpm publishfor the final publish. Per the learnings, the repository is moving toward pnpm as the primary package manager for validation workflows.Consider aligning all commands to use
pnpm runconsistently if the repository is fully migrating to pnpm:- "release": "npm run build:all && npm pack --dry-run && pnpm publish", + "release": "pnpm run build:all && pnpm pack --dry-run && pnpm publish",Alternatively, if
npm runis intentionally retained for legacy compatibility, document the rationale and verify this pattern is applied consistently across all packages.packages/drivers/pg-testkit/package.json (1)
12-12: Inconsistent package manager usage in release script.Similar to packages/core, this release script mixes
npm runcommands withpnpm publish. For consistency with the repository's shift to pnpm (as indicated by learnings and the PR's coordinated updates across packages), align all commands:- "release": "npm run lint && npm run test && npm run build && npm pack --dry-run && pnpm publish --access public" + "release": "pnpm run lint && pnpm run test && pnpm run build && pnpm pack --dry-run && pnpm publish --access public"Verify this pattern across all updated packages and document if mixed usage is intentional.
packages/testkit-core/package.json (1)
12-12: Align package manager usage in release script.This file exhibits the same mixed
npm run/pnpm publishpattern. For consistency with the repository's pnpm migration, update to:- "release": "npm run lint && npm run test && npm run build && npm pack --dry-run && pnpm publish --access public" + "release": "pnpm run lint && pnpm run test && pnpm run build && pnpm pack --dry-run && pnpm publish --access public"This is the third package with this inconsistency; verify the approach across all packages to ensure uniformity.
packages/drivers/sqlite-testkit/package.json (1)
14-14: Standardize package manager in release script (fourth instance).This is the fourth package showing mixed
npm run/pnpm publishusage. Coordinate updates across all packages to use pnpm consistently:- "release": "npm run lint && npm run test && npm run build && npm pack --dry-run && pnpm publish --access public" + "release": "pnpm run lint && pnpm run test && pnpm run build && pnpm pack --dry-run && pnpm publish --access public"packages/cli/package.json (1)
13-13: Consider using consistent package manager commands in the release script.The script mixes
npm runcommands withpnpm publish. For consistency within a pnpm workspace, consider usingpnpm runthroughout:-"release": "npm run lint && npm run test && npm run build && pnpm publish --access public" +"release": "pnpm run lint && pnpm run test && pnpm run build && pnpm publish --access public"packages/cli/src/commands/ztdConfigCommand.ts (1)
10-38: Add JSDoc documentation to the exported function.As per coding guidelines, all exported functions in
src/should include clear English JSDoc documentation.+/** + * Registers the `ztd-config` CLI command on the provided Commander program. + * The command parses DDL sources and generates a TypeScript file containing + * test row type definitions for ZTD (Zero Table Dependency) testing. + * + * @param program - The Commander program instance to register the command on. + */ export function registerZtdConfigCommand(program: Command): void {packages/cli/src/commands/options.ts (2)
1-7: Add JSDoc documentation for exported constants and functions.Per coding guidelines, all exported classes and types in
src/must include clear English JSDoc documentation. The exportedDEFAULT_EXTENSIONS,DEFAULT_DDL_DIRECTORY, andcollectDirectorieslack JSDoc comments.+/** + * Default file extensions to scan for SQL files. + */ export const DEFAULT_EXTENSIONS = ['.sql']; + +/** + * Default directory name for DDL files. + */ export const DEFAULT_DDL_DIRECTORY = 'ddl'; const EXTENSION_TOKEN_PATTERN = /^[A-Za-z0-9_]+$/; +/** + * Accumulator callback for Commander's repeatable directory options. + * @param value - The directory path provided by the user. + * @param previous - Previously collected directory paths. + * @returns Updated array including the new directory. + */ export function collectDirectories(value: string, previous: string[]): string[] { return [...previous, value]; }
9-22: Add JSDoc forparseExtensions.This exported function should have JSDoc describing its purpose, parameters, and return value.
+/** + * Parses and normalizes file extension tokens. + * Accepts a comma-separated string or an array, trims whitespace, validates + * characters, lowercases, and returns a deduplicated, sorted array of + * dot-prefixed extensions (e.g., ['.sql']). + * @param value - Comma-separated extension string or array of extensions. + * @returns Normalized, deduplicated, and sorted array of extensions. + */ export function parseExtensions(value: string | string[]): string[] {packages/cli/src/commands/ddl.ts (1)
32-44: Fix inconsistent indentation on the closing brace.The closing
});on line 44 has inconsistent indentation compared to the.action()chain starting at line 32.await runDiffSchema({ directories, extensions, url: options.url, out: options.out, pgDumpPath: options.pgDumpPath as string | undefined }); - }); + }); }packages/cli/src/commands/ztdConfig.ts (3)
13-17: Add JSDoc for exported interface.Per coding guidelines, exported types should include JSDoc documentation.
+/** + * Options for generating ZTD test-row configuration from DDL files. + */ export interface ZtdConfigGenerationOptions { + /** Directories containing DDL SQL files to scan. */ directories: string[]; + /** File extensions to include (e.g., ['.sql']). */ extensions: string[]; + /** Output path for the generated ztd-config.ts file. */ out: string; }
31-46: Add JSDoc for the exported function.This public function should have JSDoc documentation describing its purpose and behavior.
+/** + * Generates a ZTD test-row configuration file from DDL SQL sources. + * Scans the specified directories for SQL files, extracts CREATE TABLE + * statements, and writes TypeScript interfaces to the output path. + * @param options - Generation options including directories, extensions, and output path. + * @throws Error if no SQL files are found or no CREATE TABLE statements exist. + */ export function runGenerateZtdConfig(options: ZtdConfigGenerationOptions): void {
60-68: Consider logging or collecting parse errors instead of silently swallowing them.The
catchblock silently continues on parse errors. While this is reasonable for non-CREATE statements, actual parsing failures in DDL files might go unnoticed during development.Consider at minimum tracking failed files for optional verbose output:
try { const parsed = SqlParser.parse(query.sql); if (parsed instanceof CreateTableQuery) { ast = parsed; } - } catch (_error) { + } catch (error) { + // Non-CREATE statements or unsupported syntax; skip silently. + // Future: optionally surface in verbose mode. continue; }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (5)
packages/cli/tests/__snapshots__/cliCommands.test.ts.snapis excluded by!**/*.snappackages/cli/tests/__snapshots__/genEntities.unit.test.ts.snapis excluded by!**/*.snappackages/cli/tests/__snapshots__/init.command.test.ts.snapis excluded by!**/*.snappackages/cli/tests/__snapshots__/ztdConfig.unit.test.ts.snapis excluded by!**/*.snappnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (15)
packages/cli/README.md(6 hunks)packages/cli/package.json(2 hunks)packages/cli/src/commands/ddl.ts(3 hunks)packages/cli/src/commands/init.ts(8 hunks)packages/cli/src/commands/options.ts(1 hunks)packages/cli/src/commands/ztdConfig.ts(8 hunks)packages/cli/src/commands/ztdConfigCommand.ts(1 hunks)packages/cli/src/index.ts(1 hunks)packages/cli/tests/cliCommands.test.ts(2 hunks)packages/cli/tests/init.command.test.ts(2 hunks)packages/cli/tests/ztdConfig.unit.test.ts(3 hunks)packages/core/package.json(1 hunks)packages/drivers/pg-testkit/package.json(1 hunks)packages/drivers/sqlite-testkit/package.json(1 hunks)packages/testkit-core/package.json(1 hunks)
🧰 Additional context used
📓 Path-based instructions (4)
**/*.{ts,tsx,js,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
All identifiers, comments, and documentation remain in English
Files:
packages/testkit-core/package.jsonpackages/cli/src/commands/options.tspackages/cli/tests/cliCommands.test.tspackages/cli/src/commands/ztdConfigCommand.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/drivers/pg-testkit/package.jsonpackages/cli/package.jsonpackages/cli/src/index.tspackages/core/package.jsonpackages/drivers/sqlite-testkit/package.jsonpackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
packages/**/src/**/*.{ts,tsx,js}
📄 CodeRabbit inference engine (AGENTS.md)
Remove console debugging before committing
Files:
packages/cli/src/commands/options.tspackages/cli/src/commands/ztdConfigCommand.tspackages/cli/src/index.tspackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
packages/**/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
All exported classes and types must include clear English JSDoc documentation in src/
Files:
packages/cli/src/commands/options.tspackages/cli/src/commands/ztdConfigCommand.tspackages/cli/src/index.tspackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
packages/cli/**/*.ts
📄 CodeRabbit inference engine (packages/cli/AGENTS.md)
Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Files:
packages/cli/src/commands/options.tspackages/cli/tests/cliCommands.test.tspackages/cli/src/commands/ztdConfigCommand.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/src/index.tspackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
🧠 Learnings (69)
📓 Common learnings
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : In rawsql-ts/testkit-core, remain DBMS-agnostic with no Postgres/SQLite conditionals or behavior
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Implement DDL-based fixtures by parsing CREATE TABLE and INSERT statements from .sql schema files, producing fixture schema and baseline rows
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{core,testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : All SQL rewrites must rely on rawsql-ts AST utilities (parser, analyzer, splitQueries); regex-based rewrites are allowed only as guarded fallbacks with comments explaining why
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Repository and application SQL may use normal CRUD (INSERT, UPDATE, DELETE) operations; pg-testkit will automatically rewrite them into SELECT queries
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: Applies to packages/cli/**/*.ts : Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: CLI scaffolding templates must be compatible with rawsql-ts/testkit-core, rawsql-ts/pg-testkit, and rawsql-ts/sqlite-testkit
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Support CREATE TEMP TABLE ... AS SELECT as the only allowed temporary table DDL pattern in pg-testkit
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.test.{ts,tsx,js} : Provide test-specific fixture rows via tableRows or withFixtures() rather than embedding them in schema files
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : UPDATE rewrites should apply updates to fixture snapshot and project updated rows via SELECT
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Run pnpm lint, pnpm test (or pnpm --filter <pkg> test), and pnpm build as part of the validation checklist
Applied to files:
packages/testkit-core/package.jsonpackages/drivers/pg-testkit/package.jsonpackages/cli/package.jsonpackages/core/package.jsonpackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Run pnpm --filter rawsql-ts test && pnpm --filter rawsql-ts build && pnpm --filter rawsql-ts lint before committing
Applied to files:
packages/testkit-core/package.jsonpackages/drivers/pg-testkit/package.jsonpackages/cli/package.jsonpackages/core/package.jsonpackages/drivers/sqlite-testkit/package.jsonpackages/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: After formatter export changes, run pnpm --filter rawsql-ts build:browser
Applied to files:
packages/testkit-core/package.jsonpackages/cli/package.jsonpackages/core/package.jsonpackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/testkit-core/package.jsonpackages/cli/tests/ztdConfig.unit.test.tspackages/drivers/pg-testkit/package.jsonpackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/testkit-core/package.jsonpackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Supported runtime is Node 20+; optional features must degrade gracefully on other platforms or Node versions
Applied to files:
packages/testkit-core/package.jsonpackages/cli/package.jsonpackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/testkit-core/package.jsonpackages/cli/tests/cliCommands.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/package.jsonpackages/drivers/sqlite-testkit/package.jsonpackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Repository and application SQL may use normal CRUD (INSERT, UPDATE, DELETE) operations; pg-testkit will automatically rewrite them into SELECT queries
Applied to files:
packages/testkit-core/package.jsonpackages/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/drivers/pg-testkit/package.jsonpackages/cli/package.jsonpackages/drivers/sqlite-testkit/package.jsonpackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/scripts/install-better-sqlite3.cjs : Keep scripts/install-better-sqlite3.cjs up to date so CI and local installs stay reliable; better-sqlite3 requires native compilation
Applied to files:
packages/testkit-core/package.jsonpackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/testkit-core/package.jsonpackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : No code path bypasses testkit-core's rewrite pipeline
Applied to files:
packages/testkit-core/package.jsonpackages/cli/tests/cliCommands.test.tspackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: Applies to packages/cli/**/*.ts : Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Applied to files:
packages/cli/src/commands/options.tspackages/cli/src/index.tspackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/ddl.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/README.mdpackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Tests act as specifications - never update expectations without intent and alignment
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/drivers/sqlite-testkit/package.jsonpackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Do not hand-construct QueryResult or mock Client#query; all tests must flow through the rewrite pipeline and fixtures
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Do not mutate fixtures as global state in testkit-core; keep fixture mutations scoped
Applied to files:
packages/cli/tests/cliCommands.test.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/package.jsonpackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/tests/cliCommands.test.tspackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Implement DDL-based fixtures by parsing CREATE TABLE and INSERT statements from .sql schema files, producing fixture schema and baseline rows
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/src/commands/ztdConfigCommand.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/drivers/pg-testkit/package.jsonpackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : In tests, no physical tables are created, migrated, or mutated; all schema information and seed rows must come from DDL files and fixtures, with pg-testkit rewriting CRUD statements into fixture-backed SELECT queries
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: CLI scaffolding templates must be compatible with rawsql-ts/testkit-core, rawsql-ts/pg-testkit, and rawsql-ts/sqlite-testkit
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/package.jsonpackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: No runtime dependency on rawsql-ts/cli in production code. All generated CLI outputs must be plain TypeScript/SQL that can be committed and maintained without the tool.
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/src/commands/ztdConfigCommand.tspackages/cli/package.jsonpackages/cli/src/index.tspackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/ddl.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Support CREATE TEMP TABLE ... AS SELECT as the only allowed temporary table DDL pattern in pg-testkit
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/README.mdpackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : FixtureStore.describeColumns must surface table names, available columns, and suggested hints for error diagnostics
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/README.mdpackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.test.{ts,tsx,js} : Provide test-specific fixture rows via tableRows or withFixtures() rather than embedding them in schema files
Applied to files:
packages/cli/tests/cliCommands.test.tspackages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/pg-testkit/src/**/*.{ts,tsx} : Do not execute CREATE TABLE, ALTER TABLE, or seed INSERTs over a pg-testkit connection; the DB engine is only for planning and type-checking
Applied to files:
packages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/drivers/pg-testkit/package.jsonpackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Never mock QueryResult; use real PostgreSQL query results with fixture-backed data
Applied to files:
packages/cli/tests/init.command.test.tspackages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : pg-testkit must never bypass rewrite logic or attempt any real migration
Applied to files:
packages/cli/tests/init.command.test.tspackages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Throw descriptive fail-fast errors for missing fixtures, unknown tables/columns, ambiguous columns, and unsupported constructs (e.g., INSERT … ON CONFLICT, mutating CTEs)
Applied to files:
packages/cli/tests/init.command.test.tspackages/cli/tests/ztdConfig.unit.test.tspackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Never create or write to physical tables using CREATE TABLE, ALTER TABLE, INSERT, UPDATE, or DELETE statements in pg-testkit
Applied to files:
packages/cli/tests/init.command.test.tspackages/drivers/pg-testkit/package.jsonpackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : RETURNING clauses should be rendered solely as SELECT projection in testkit-core rewrites
Applied to files:
packages/cli/tests/ztdConfig.unit.test.tspackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/tests/ztdConfig.unit.test.tspackages/cli/package.jsonpackages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/tests/ztdConfig.unit.test.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/tests/ztdConfig.unit.test.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/tests/ztdConfig.unit.test.tspackages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Provide helper functions: createPgTestkitClient, createPgTestkitPool, wrapPgClient, and .withFixtures() overlay method
Applied to files:
packages/drivers/pg-testkit/package.jsonpackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Convert insert defaults involving nextval(...) into deterministic expressions like row_number() over () to ensure consistent behavior without real sequences
Applied to files:
packages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Ensure result types follow PostgreSQL casting rules to maintain parity with real-world applications
Applied to files:
packages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Emit debug traces when fallback paths trigger, analyzer limitations appear, or fixture mismatches surface
Applied to files:
packages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : All CRUD operations (INSERT, UPDATE, DELETE) must be rewritten into fixture-backed SELECT queries before execution in pg-testkit
Applied to files:
packages/drivers/pg-testkit/package.jsonpackages/cli/README.mdpackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Never throw due to missing logger fields; use logger hooks from testkit-core with safe fallbacks
Applied to files:
packages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.test.{ts,tsx,js} : Use real PostgreSQL Testcontainers instance for testing pg-testkit; support full parallel test execution with isolated fixture universes
Applied to files:
packages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Normalize $1, $2, ... placeholders before rewrite and restore them before PostgreSQL execution
Applied to files:
packages/drivers/pg-testkit/package.json
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Rebuild the browser bundle when parser or formatter changes: pnpm --filter rawsql-ts build:browser, then re-bundle for docs demo using esbuild, and commit updated docs/public/demo/vendor/rawsql.browser.js
Applied to files:
packages/cli/package.jsonpackages/core/package.json
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: When code is not updating, confirm imports use built rawsql-ts vs live ../../core/src paths, clear caches with rm -rf dist node_modules && pnpm --filter rawsql-ts build
Applied to files:
packages/cli/package.json
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{core,testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : All SQL rewrites must rely on rawsql-ts AST utilities (parser, analyzer, splitQueries); regex-based rewrites are allowed only as guarded fallbacks with comments explaining why
Applied to files:
packages/cli/package.jsonpackages/cli/README.mdpackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Prefer import { ... } from 'rawsql-ts' over deep relative paths
Applied to files:
packages/cli/package.jsonpackages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/package.json
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/tsconfig.browser.json : Browser bundles depend on tsconfig.browser.json
Applied to files:
packages/core/package.json
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/build.*.js : Use esbuild with --minify-syntax --minify-whitespace for bundling; avoid --minify-identifiers as it breaks comment bookkeeping and named exports
Applied to files:
packages/core/package.json
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not use regex-based SQL parsing inside sqlite-testkit; if temporary regex-based merge is absolutely required, add TODO and inline comment, emit logger.debug notice, and file an issue in testkit-core
Applied to files:
packages/drivers/sqlite-testkit/package.json
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Enforce fixture precedence: DDL fixtures (schema + shared seed) → Manual fixtures (tableDefinitions, tableRows) → Scoped fixtures (client.withFixtures())
Applied to files:
packages/cli/README.mdpackages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.sql : Do not put per-test seeds inside DDL schema files; use only for true shared baseline data via INSERT statements
Applied to files:
packages/cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Make DDL loader behavior deterministic and parse files only once per client/pool instance
Applied to files:
packages/cli/README.mdpackages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/ddl.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Refactor for clarity and document public APIs before running the validation pipeline
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/src/commands/init.tspackages/cli/src/commands/ddl.ts
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Always prefer AST helpers (SelectQueryParser, SelectAnalyzer, splitQueries, formatter APIs) for SQL parsing
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Surface clear, typed errors from the driver layer using error classes like MissingFixtureError and SchemaValidationError with descriptive messages including table/column hints
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Include actionable hints in error messages that reference specific table and column names
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Never consult PostgreSQL for schema or row data; only use fixture-derived CTEs
Applied to files:
packages/cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/src/commands/init.ts
🧬 Code graph analysis (4)
packages/cli/tests/ztdConfig.unit.test.ts (2)
packages/cli/tests/utils/normalize.ts (1)
normalizeLineEndings(1-1)packages/cli/src/commands/ztdConfig.ts (1)
renderZtdConfigFile(129-160)
packages/cli/src/commands/ztdConfig.ts (2)
packages/cli/src/utils/fs.ts (1)
ensureDirectory(3-10)packages/cli/src/utils/collectSqlFiles.ts (1)
SqlSource(4-7)
packages/cli/src/commands/init.ts (1)
packages/cli/src/commands/ztdConfig.ts (1)
ZtdConfigGenerationOptions(13-17)
packages/cli/src/commands/ddl.ts (1)
packages/cli/src/commands/options.ts (1)
DEFAULT_DDL_DIRECTORY(2-2)
🪛 markdownlint-cli2 (0.18.1)
packages/cli/README.md
68-68: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
74-74: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (18)
packages/cli/README.md (1)
107-126: Documentation aligns well with the new TestRowMap contract.The example clearly demonstrates the generated structure, warnings, and test-only nature of the output. The header comments effectively communicate that this file should not be imported from
src/.packages/cli/src/index.ts (1)
6-14: LGTM!The
ztd-configcommand is cleanly wired into the CLI startup sequence. The registration order (init → ztd-config → ddl) is logical and maintains a sensible command hierarchy.packages/cli/tests/cliCommands.test.ts (1)
72-100: LGTM!The test correctly targets the renamed
ztd-configcommand and validates the expected output artifact (ztd-config.ts). The test structure remains clean and the snapshot comparison ensures output stability.packages/cli/tests/ztdConfig.unit.test.ts (2)
1-34: LGTM!The test correctly imports and invokes
renderZtdConfigFilefrom the renamed module. Test descriptions align with the new ZTD row map terminology, and the snapshot-based validation ensures output stability.
36-105: Comprehensive test coverage for multi-source and cross-schema scenarios.The test validates composite primary keys, cross-schema references, and nullability preservation across multiple DDL sources. This provides good coverage for the ZTD config generation.
packages/cli/tests/init.command.test.ts (2)
59-72: LGTM!The test correctly validates that the init wizard generates
tests/ztd-config.tswith theTestRowMapinterface. The assertions align with the new ZTD config workflow.
74-102: DB workflow test correctly updated.The test for the database-connected init workflow now validates the presence of
TestRowMapin the generated config file, maintaining consistency with the DDL-first workflow test.packages/cli/src/commands/ztdConfigCommand.ts (3)
40-69: Well-implemented debounce logic for file watching.The debounce implementation correctly buffers rapid file events to avoid redundant regenerations. The 150ms debounce window is reasonable for multi-step editor saves.
71-83: Good error handling in the reload function.Errors during regeneration are caught and logged without crashing the watcher, which is the correct behavior for a long-running watch process.
90-109: Clean shutdown handling on SIGINT.The cleanup logic properly removes event listeners, clears timers, closes the watcher, and resolves the promise. Using
process.onceprevents multiple handler registrations.packages/cli/src/commands/ddl.ts (1)
47-47: LGTM!The re-export pattern maintains a clean public API surface while centralizing implementation in
options.ts.packages/cli/src/commands/ztdConfig.ts (2)
3-8: Good use of AST-driven analysis.The imports from
rawsql-tsfor SQL parsing (SqlParser,CreateTableQuery,MultiQuerySplitter,createTableDefinitionFromCreateTableQuery) align with the coding guideline to use AST-driven analysis instead of regex-based string manipulation. Based on learnings.
108-127: LGTM!The helper correctly handles schema-qualified names, Pascal-casing, and ensures valid TypeScript identifiers by stripping leading digits and adding underscore prefix when needed.
packages/cli/src/commands/init.ts (5)
8-8: LGTM!The import correctly references the renamed
runGenerateZtdConfigfunction andZtdConfigGenerationOptionstype from./ztdConfig.
83-83: LGTM!The
FileKeytype correctly includes'ztdConfig'replacing the former'entities'key.
115-156: Well-written documentation content.The updated README, guide content, and next steps clearly explain the ZTD workflow, test-row mappings, and the relationship between DDL files and generated configuration. The terminology is consistent with the renamed
ztd-configworkflow.
244-264: LGTM!The ZTD config generation flow correctly:
- Checks for existing file and prompts for overwrite consent
- Calls
runGenerateZtdConfigwith proper options derived from schema path- Logs appropriate skip message when preserving existing config
- Records correct outcome in summary
362-380: LGTM!The
orderedKeysarray correctly includes'ztdConfig'to maintain consistent output ordering in the summary.
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/cli/src/commands/ztdConfig.ts (1)
13-17: Add JSDoc to exported options type and generator entrypointPer repo guidelines, exported types should have clear English JSDoc. Adding brief doc comments here will also help downstream callers understand how to wire directories/extensions/out:
+/** + * Options for generating the test-only ZTD row map (tests/ztd-config.ts) from DDL sources. + * + * - `directories`: one or more root directories containing .sql DDL files. + * - `extensions`: file extensions to include (for example, ['.sql']). + * - `out`: path to the generated TypeScript file, typically under tests/. + */ export interface ZtdConfigGenerationOptions { directories: string[]; extensions: string[]; out: string; } @@ -export function runGenerateZtdConfig(options: ZtdConfigGenerationOptions): void { +/** + * Parse the configured DDL sources and write a synchronized ZTD test-row config + * file to `options.out`. Throws if no SQL files or CREATE TABLE statements are found. + */ +export function runGenerateZtdConfig(options: ZtdConfigGenerationOptions): void {Also applies to: 31-46
🧹 Nitpick comments (1)
packages/cli/src/commands/ztdConfig.ts (1)
48-106: Consider surfacing richer diagnostics when parsing or metadata resolution fails
snapshotTableMetadatais nicely AST-driven and keeps one entry per table name, but a couple of failure paths are silent or low-context:
SqlParser.parseerrors are swallowed (the loop justcontinues), so a malformedCREATE TABLEcan be dropped without any indication as long as at least one other table parses.- The
Missing metadata for ${column.name.name} in ${definition.name}error does not include source file information, even thoughsourceis available in the outer scope.To make debugging DDL issues easier, consider:
- Logging or aggregating parse failures with
source.pathand the failing statement (maybe behind a verbose flag), or rethrowing a more descriptive error when the statement appears to be aCREATE TABLE.- Extending the missing-metadata error to include the originating file, e.g.:
- throw new Error(`Missing metadata for ${column.name.name} in ${definition.name}`); + throw new Error( + `Missing metadata for ${column.name.name} in ${definition.name} (source: ${source.path})` + );This keeps the AST flow intact while giving users clearer feedback when their DDL isn’t compatible with the generator.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (3)
packages/cli/tests/__snapshots__/cliCommands.test.ts.snapis excluded by!**/*.snappackages/cli/tests/__snapshots__/ztdConfig.unit.test.ts.snapis excluded by!**/*.snappnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (4)
packages/cli/README.md(6 hunks)packages/cli/package.json(2 hunks)packages/cli/src/commands/ztdConfig.ts(8 hunks)packages/cli/src/commands/ztdConfigCommand.ts(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- packages/cli/src/commands/ztdConfigCommand.ts
- packages/cli/package.json
🧰 Additional context used
📓 Path-based instructions (4)
**/*.{ts,tsx,js,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
All identifiers, comments, and documentation remain in English
Files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
packages/**/src/**/*.{ts,tsx,js}
📄 CodeRabbit inference engine (AGENTS.md)
Remove console debugging before committing
Files:
packages/cli/src/commands/ztdConfig.ts
packages/**/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
All exported classes and types must include clear English JSDoc documentation in src/
Files:
packages/cli/src/commands/ztdConfig.ts
packages/cli/**/*.ts
📄 CodeRabbit inference engine (packages/cli/AGENTS.md)
Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Files:
packages/cli/src/commands/ztdConfig.ts
🧠 Learnings (40)
📓 Common learnings
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : In rawsql-ts/testkit-core, remain DBMS-agnostic with no Postgres/SQLite conditionals or behavior
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Implement DDL-based fixtures by parsing CREATE TABLE and INSERT statements from .sql schema files, producing fixture schema and baseline rows
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{core,testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : All SQL rewrites must rely on rawsql-ts AST utilities (parser, analyzer, splitQueries); regex-based rewrites are allowed only as guarded fallbacks with comments explaining why
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Repository and application SQL may use normal CRUD (INSERT, UPDATE, DELETE) operations; pg-testkit will automatically rewrite them into SELECT queries
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: Applies to packages/cli/**/*.ts : Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: CLI scaffolding templates must be compatible with rawsql-ts/testkit-core, rawsql-ts/pg-testkit, and rawsql-ts/sqlite-testkit
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Support CREATE TEMP TABLE ... AS SELECT as the only allowed temporary table DDL pattern in pg-testkit
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.test.{ts,tsx,js} : Provide test-specific fixture rows via tableRows or withFixtures() rather than embedding them in schema files
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : UPDATE rewrites should apply updates to fixture snapshot and project updated rows via SELECT
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Refactor for clarity and document public APIs before running the validation pipeline
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.test.{ts,tsx,js} : Provide test-specific fixture rows via tableRows or withFixtures() rather than embedding them in schema files
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : FixtureStore.describeColumns must surface table names, available columns, and suggested hints for error diagnostics
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Use convertModelDrivenMapping when mapping.typeInfo && mapping.structure exist; legacy mode expects mapping.rootName && mapping.rootEntity
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Implement DDL-based fixtures by parsing CREATE TABLE and INSERT statements from .sql schema files, producing fixture schema and baseline rows
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Regression testing for complex SQL should achieve ≥95% comment preservation, no token splits like table. /* comment */ column, and CASE expression comments preserved in evaluation order
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Keep all comments and identifiers in English
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not use regex-based SQL parsing inside sqlite-testkit; if temporary regex-based merge is absolutely required, add TODO and inline comment, emit logger.debug notice, and file an issue in testkit-core
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Include actionable hints in error messages that reference specific table and column names
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to **/*.{ts,tsx,js,json,md} : All identifiers, comments, and documentation remain in English
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: No runtime dependency on rawsql-ts/cli in production code. All generated CLI outputs must be plain TypeScript/SQL that can be committed and maintained without the tool.
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: Applies to packages/cli/**/*.ts : Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{core,testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : All SQL rewrites must rely on rawsql-ts AST utilities (parser, analyzer, splitQueries); regex-based rewrites are allowed only as guarded fallbacks with comments explaining why
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Always prefer AST helpers (SelectQueryParser, SelectAnalyzer, splitQueries, formatter APIs) for SQL parsing
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: CLI scaffolding templates must be compatible with rawsql-ts/testkit-core, rawsql-ts/pg-testkit, and rawsql-ts/sqlite-testkit
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Prefer import { ... } from 'rawsql-ts' over deep relative paths
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/pg-testkit/src/**/*.{ts,tsx} : Do not execute CREATE TABLE, ALTER TABLE, or seed INSERTs over a pg-testkit connection; the DB engine is only for planning and type-checking
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Repository and application SQL may use normal CRUD (INSERT, UPDATE, DELETE) operations; pg-testkit will automatically rewrite them into SELECT queries
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : In tests, no physical tables are created, migrated, or mutated; all schema information and seed rows must come from DDL files and fixtures, with pg-testkit rewriting CRUD statements into fixture-backed SELECT queries
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Support CREATE TEMP TABLE ... AS SELECT as the only allowed temporary table DDL pattern in pg-testkit
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Make DDL loader behavior deterministic and parse files only once per client/pool instance
Applied to files:
packages/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Surface clear, typed errors from the driver layer using error classes like MissingFixtureError and SchemaValidationError with descriptive messages including table/column hints
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Throw descriptive fail-fast errors for missing fixtures, unknown tables/columns, ambiguous columns, and unsupported constructs (e.g., INSERT … ON CONFLICT, mutating CTEs)
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/src/commands/ztdConfig.tspackages/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : RETURNING clauses should be rendered solely as SELECT projection in testkit-core rewrites
Applied to files:
packages/cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : All CRUD operations (INSERT, UPDATE, DELETE) must be rewritten into fixture-backed SELECT queries before execution in pg-testkit
Applied to files:
packages/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Always use SelectQueryParser, SelectAnalyzer, and splitQueries for rewriting SQL; use regex only as a fallback with a comment explaining the need, a link to a tracking issue, and a description of AST migration
Applied to files:
packages/cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Enforce fixture precedence: DDL fixtures (schema + shared seed) → Manual fixtures (tableDefinitions, tableRows) → Scoped fixtures (client.withFixtures())
Applied to files:
packages/cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.sql : Do not put per-test seeds inside DDL schema files; use only for true shared baseline data via INSERT statements
Applied to files:
packages/cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Run pnpm --filter rawsql-ts test && pnpm --filter rawsql-ts build && pnpm --filter rawsql-ts lint before committing
Applied to files:
packages/cli/README.md
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/cli/README.md
🔇 Additional comments (4)
packages/cli/README.md (2)
44-57: Init artifacts + ZTD config description look coherentThe
initartifacts list and the explanations fortests/ztd-config.tsand ZTD guides are consistent with the new TestRowMap‑centric workflow; no issues from my side here.
204-205: AI-contract + troubleshooting section reads wellThe new guidance that AI should consume both
ddl/andtests/ztd-config.ts, plus the ZTD troubleshooting cases, is clear and matches the intended contract between schema, row map, fixtures, andsrc/. Once the CLI name tweaks are applied above, this section looks solid.Also applies to: 206-218, 226-226
packages/cli/src/commands/ztdConfig.ts (2)
108-127: Test-row interface name generation looks robust
buildTestRowInterfaceName’s approach (schema/table segmentation, PascalCase, stripping leading digits, and the_/Tablefallbacks) should produce stable, valid TypeScript identifiers even for odd table names, while preserving uniqueness across schemas. No changes needed here.
129-160: ZTD config file rendering and header fix look goodThe new
renderZtdConfigFile:
- Prepends a clear, ASCII‑only header marking the file as auto‑generated and test‑only (fixing the earlier encoding glitch).
- Emits a
TestRowMapkeyed by table SQL name →testRowInterfaceName.- Renders per-table interfaces using
mapSqlTypeToTsand column nullability, preserving column order.This matches the README’s description of the artifact (once the header example is updated) and satisfies the “plain TypeScript output” requirement.
packages/cli/README.md
Outdated
Comment on lines
79
to
80
| Keeping `rawsql ztd-config --watch` running keeps the row map in lockstep with the DDL while you edit. | ||
|
|
There was a problem hiding this comment.
Use rawsql-ts consistently in CLI examples
Several examples still show rawsql ztd-config instead of the actual rawsql-ts binary, which could confuse users:
- Line 79: backticked command in the watch sentence
- Line 160: parenthetical watch reference
- Line 190: “How It Works” step 2
- Line 214: troubleshooting Case B action text
- Line 218: troubleshooting Case C action text
Recommend normalizing all of these to rawsql-ts ztd-config (and rawsql-ts ztd-config --watch):
- Keeping `rawsql ztd-config --watch` running keeps the row map in lockstep with the DDL while you edit.
+ Keeping `rawsql-ts ztd-config --watch` running keeps the row map in lockstep with the DDL while you edit.
@@
- Update DDL -> regenerate the row map -> rerun tests (or keep `rawsql ztd-config --watch` running while editing DDL).
+ Update DDL -> regenerate the row map -> rerun tests (or keep `rawsql-ts ztd-config --watch` running while editing DDL).
@@
- `rawsql ztd-config` converts SQL types into TypeScript while preserving nullability and primary-key semantics, and it prepends warnings so the output stays test-only.
+ `rawsql-ts ztd-config` converts SQL types into TypeScript while preserving nullability and primary-key semantics, and it prepends warnings so the output stays test-only.
@@
- **Action:** Rerun `rawsql ztd-config` to refresh the row map (or rely on `rawsql ztd-config --watch`), update the fixtures, then rerun the tests to observe failing columns.
+ **Action:** Rerun `rawsql-ts ztd-config` to refresh the row map (or rely on `rawsql-ts ztd-config --watch`), update the fixtures, then rerun the tests to observe failing columns.
@@
- **Action:** 1. Regenerate `tests/ztd-config.ts` via `rawsql ztd-config`. 2. Update fixtures to match the new columns. 3. Adjust the domain model in `src/` if business rules changed. 4. Run `ddl diff` and apply migrations if necessary.
+ **Action:** 1. Regenerate `tests/ztd-config.ts` via `rawsql-ts ztd-config`. 2. Update fixtures to match the new columns. 3. Adjust the domain model in `src/` if business rules changed. 4. Run `ddl diff` and apply migrations if necessary.Also applies to: 160-160, 190-190, 214-214, 218-218
🤖 Prompt for AI Agents
packages/cli/README.md lines 79-80, 160-160, 190-190, 214-214, 218-218: several
CLI examples use the incorrect binary name `rawsql` or `rawsql ztd-config`;
replace each occurrence with the correct `rawsql-ts` form (use `rawsql-ts
ztd-config` and `rawsql-ts ztd-config --watch` where the watch variant is
referenced) so all examples consistently show the `rawsql-ts` binary.
packages/cli/README.md
Outdated
Comment on lines
107
to
121
| ## Example Generated Test Row Map | ||
|
|
||
| After running `ddl gen-entities`, `tests/entities.ts` exports every table interface and an `Entities` map that AI assistants can inspect to learn row shapes: | ||
| After running `rawsql-ts ztd-config`, `tests/ztd-config.ts` emits every table interface and a `TestRowMap` that AI assistants can inspect to learn row shapes. The file starts with strong warnings to prevent production imports: | ||
|
|
||
| ```ts | ||
| export interface Entities { | ||
| 'public.users': PublicUsersEntity; | ||
| // ZTD TEST ROW TYPES ? AUTO GENERATED | ||
| // DO NOT import this file from src. | ||
| // Test-only. Not domain entities. | ||
| // Synchronized with DDL via ztd-config generator. | ||
|
|
||
| export interface TestRowMap { | ||
| 'public.users': PublicUsersTestRow; | ||
| } | ||
|
|
||
| export interface PublicUsersEntity { | ||
| export interface PublicUsersTestRow { |
There was a problem hiding this comment.
Align example header comment with generated output
In the “Example Generated Test Row Map” section, the first header line shows:
// ZTD TEST ROW TYPES ? AUTO GENERATEDGiven that the generator now emits:
// ZTD TEST ROW TYPES - AUTO GENERATEDand the “?” likely came from an encoding hiccup, it would be clearer and less confusing to update the example to match the real header:
-// ZTD TEST ROW TYPES ? AUTO GENERATED
+// ZTD TEST ROW TYPES - AUTO GENERATED🤖 Prompt for AI Agents
packages/cli/README.md around lines 107 to 121: the example header comment shows
"// ZTD TEST ROW TYPES ? AUTO GENERATED" but the generator actually emits "//
ZTD TEST ROW TYPES - AUTO GENERATED"; update the README example to replace the
question mark with a hyphen so the displayed header exactly matches the
generated output.
packages/cli/README.md
Outdated
Comment on lines
137
to
140
| ### Step 2. Generate the ZTD row map | ||
| ```bash | ||
| rawsql-ts ddl gen-entities --ddl-dir ddl --out tests/entities.ts | ||
| rawsql-ts ztd-config --ddl-dir ddl --out tests/ztd-config.ts | ||
| ``` |
There was a problem hiding this comment.
Update “entity” wording to TestRow/TestRowMap terminology
A few Scenario A/B descriptions still talk about “entity interfaces/definitions” even though the documented workflow is now centered on the generated TestRowMap and test‑row interfaces:
- Line 154: “AI uses entity interfaces to build validation-safe ZTD tests.”
- Line 173: “Provide DDL + entities so the AI can generate repositories and domain logic.”
- Line 176: “AI uses entity definitions to understand fixtures + expected row shapes.”
To avoid mixing old and new concepts, suggest rephrasing to point at the row map and test-row types, for example:
- AI uses entity interfaces to build validation-safe ZTD tests.
+ AI uses the generated test-row interfaces (from `tests/ztd-config.ts`) to build validation-safe ZTD tests.
@@
- Provide DDL + entities so the AI can generate repositories and domain logic.
+ Provide DDL + the ZTD row map (`tests/ztd-config.ts`) so the AI can generate repositories and domain logic.
@@
- AI uses entity definitions to understand fixtures + expected row shapes.
+ AI uses the test-row interfaces to understand fixtures and expected row shapes.Also applies to: 153-154, 171-176
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (11)
packages/ztd-cli/package.json (1)
13-13: Align release script to use pnpm consistently.The release script mixes
npm runcommands withpnpm publish. Per the AI summary, release scripts are being updated to use pnpm across packages. For consistency, consider using pnpm for the entire script.- "release": "npm run lint && npm run test && npm run build && pnpm publish --access public" + "release": "pnpm lint && pnpm test && pnpm build && pnpm publish --access public"packages/ztd-cli/README.md (1)
54-59: Optionally add a concreteztd-configCLI example.The behavior of
ztd ztd-configis well-described, but a short usage snippet (e.g.npx ztd ztd-config --ddl-dir ddl --out tests/ztd-config.ts) would make the workflow immediately copy-pastable and keep parity with the “README section with usage examples” guidance for new commands.Based on learnings, this would better satisfy the CLI README expectations for new commands.
packages/ztd-cli/src/commands/genEntities.ts (1)
8-29: Add JSDoc forGenerateEntitiesOptionsandrunGenerateEntities.The generation flow and error handling look good, and reusing
snapshotTableMetadatakeeps this AST‑driven. To match the repo’s “exported classes and types must include clear English JSDoc” guideline and clarify the CLI surface, consider documenting the options and generator behavior:-export interface GenerateEntitiesOptions { +/** Options for generating TypeScript entity helpers from DDL sources. */ +export interface GenerateEntitiesOptions { directories: string[]; extensions: string[]; out: string; } -export function runGenerateEntities(options: GenerateEntitiesOptions): void { +/** + * Generate entity interfaces from the given DDL directories and write them + * to the configured output file. Throws if no SQL files or CREATE TABLE + * statements are discovered. + */ +export function runGenerateEntities(options: GenerateEntitiesOptions): void {You might also add a brief JSDoc summary above
renderEntitiesFileto explain the TestRow→Entity naming convention.As per coding guidelines, exported types should carry JSDoc in src/.
Also applies to: 31-55
packages/ztd-cli/src/commands/ztdConfig.ts (2)
13-31: Document ZTD config types and generator with JSDoc.The generator and emitted
TestRowMaplook solid, and the earlier header encoding issue is fixed. To line up with project standards and clarify the external contract, I’d add brief JSDoc on the exported interfaces and functions, e.g.:-export interface ZtdConfigGenerationOptions { +/** Inputs controlling how ztd-config scans DDL and where it writes ztd-config.ts. */ +export interface ZtdConfigGenerationOptions { directories: string[]; extensions: string[]; out: string; } -export interface ColumnMetadata { +/** Column metadata derived from CREATE TABLE definitions and constraints. */ +export interface ColumnMetadata { name: string; typeName?: string; isNullable: boolean; } -export interface TableMetadata { +/** Table metadata used to build the TestRowMap and per-table TestRow interfaces. */ +export interface TableMetadata { name: string; testRowInterfaceName: string; columns: ColumnMetadata[]; } -export function runGenerateZtdConfig(options: ZtdConfigGenerationOptions): void { +/** + * Generate `tests/ztd-config.ts` from the provided DDL sources. + * Throws if no SQL files or CREATE TABLE statements are discovered. + */ +export function runGenerateZtdConfig(options: ZtdConfigGenerationOptions): void { @@ -export function renderZtdConfigFile(tables: TableMetadata[]): string { +/** Render the ZTD TestRowMap and table-specific TestRow interfaces from table metadata. */ +export function renderZtdConfigFile(tables: TableMetadata[]): string {This keeps the public API self-describing for downstream tooling and contributors.
As per coding guidelines, exported types in src/ should be documented.
Also applies to: 129-163
80-85: Make the “missing metadata” error include the source file path.The
Missing metadata for ...error is a good fail‑fast, but without the originating.sqlpath it can be hard to track down the offending DDL in larger projects. SincesnapshotTableMetadataiteratessources, you could threadsource.pathinto the message:- if (!columnMeta) { - throw new Error(`Missing metadata for ${column.name.name} in ${definition.name}`); - } + if (!columnMeta) { + throw new Error( + `Missing metadata for ${column.name.name} in ${definition.name} (source: ${source.path})` + ); + }This matches the broader goal of emitting actionable diagnostics that reference specific tables/columns.
Based on learnings, errors should include table/column hints and be actionable.
packages/ztd-cli/src/utils/agents.ts (1)
5-29: Template copy logic is sound; confirm template is shipped beside compiled CLIThe
copyAgentsTemplateflow (skip when template or targets are missing, avoid overwrites, ensure directory, then return first created target) is well-structured and idempotent. The only follow-up is to ensureAGENTS_ZTD.mdis actually emitted to the same relative location in the built package (../../AGENTS_ZTD.mdfrom this module) so the helper works both under ts-node and from the compiled CLI.packages/ztd-cli/src/commands/ztdConfigCommand.ts (1)
18-45: ztd-config command and watcher wiring look solid; consider minor cleanup in watcherThe command setup (config-driven defaults, directory/extension normalization, and default
tests/ztd-config.tsoutput) is consistent with the shared options layer and looks correct.In
watchZtdConfig:
executeReloadis declaredasyncbut only performs synchronous work; it is invoked fromsetTimeoutwithoutawait/void. Either removeasyncor explicitlyvoid executeReload(...)to avoid accidental unhandled promises ifrunGenerateZtdConfigbecomes async later.- Because
process.once('SIGINT', ...)already unregisters the handler after the first signal, the explicitprocess.off('SIGINT', stop)instopis redundant and currently references a different function than the one registered.These are minor nits and don’t affect current behavior but would simplify reasoning about the watcher.
Also applies to: 48-111
packages/ztd-cli/src/commands/init.ts (4)
81-107: New dependency interface is consistent but missing JSDoc for an exported typeThe introduction of
FileKeyentries forconfig,ztdConfig, andagentsplus theZtdConfigWriterDependenciesinterface cleanly matches all downstream usage (defaults, helpers, andrunInitCommand). However,ZtdConfigWriterDependenciesis an exported type without JSDoc, which goes against the repo guideline for exported types insrc/.Consider adding a short doc comment to clarify its role:
- export interface ZtdConfigWriterDependencies { + /** + * Abstraction for filesystem, logging, and generation primitives used by the `ztd init` flow. + * Allows tests and consumers to override IO behavior while keeping the CLI logic pure. + */ + export interface ZtdConfigWriterDependencies {
115-140: ZTD docs and next steps are clear; consider deriving paths from config defaultsThe updated
README_CONTENT,SRC_GUIDE_CONTENT,TESTS_GUIDE_CONTENT, andNEXT_STEPSdo a good job of explaining the ZTD workflow (DDL inddl/, types fromtests/ztd-config.ts, runningnpx ztd ztd-config, using pg-testkit, etc.) and align with the project’s testkit story.To avoid future drift if
DEFAULT_ZTD_CONFIG.ddlDirortestsDirever change, you might consider building the hard-coded path fragments (ddl/schema.sql,tests/ztd-config.ts) fromDEFAULT_ZTD_CONFIGinstead of embedding raw strings, but this is optional.
227-238: Config seeding behavior is correct; IO bypasses injected dependenciesSeeding
ztd.config.jsonviawriteFileWithConsentandwriteZtdProjectConfig(rootDir)is correct and ensures the config exists beforeztd-configgeneration. One design nit:writeZtdProjectConfigwrites directly using its own IO instead of going throughZtdConfigWriterDependencies, which slightly weakens testability and the “all side effects behind dependencies” pattern you use elsewhere.If you want full control in tests, consider threading
writeZtdProjectConfigthrough the dependency bag as well, but it’s not strictly required for correctness.
384-407: Summary builder ordering and wording are good; small naming nitThe updated
buildSummaryLines:
- Includes the new
config,ztdConfig, andagentskeys in a sensible order.- Distinguishes
created,overwritten, andunchangedwith clear notes.Two tiny nits:
- The header
"Created:"now also lists preserved files; something like"Files:"or"Project files:"might be slightly more accurate.- The
summariesargument is cast toRecord<FileKey, FileSummary>even though it is built as a partial; you could tighten the type toRecord<FileKey, FileSummary | undefined>to avoid theaswithout changing runtime behavior.Both are minor and can be addressed opportunistically.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (5)
packages/ztd-cli/tests/__snapshots__/cliCommands.test.ts.snapis excluded by!**/*.snappackages/ztd-cli/tests/__snapshots__/diff.unit.test.ts.snapis excluded by!**/*.snappackages/ztd-cli/tests/__snapshots__/init.command.test.ts.snapis excluded by!**/*.snappackages/ztd-cli/tests/__snapshots__/ztdConfig.unit.test.ts.snapis excluded by!**/*.snappnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (23)
AGENTS.md(1 hunks)packages/cli/AGENTS.md(0 hunks)packages/cli/README.md(0 hunks)packages/cli/src/commands/ddl.ts(0 hunks)packages/cli/tests/options.unit.test.ts(0 hunks)packages/drivers/pg-testkit/AGENTS.md(1 hunks)packages/ztd-cli/AGENTS_ZTD.md(1 hunks)packages/ztd-cli/README.md(1 hunks)packages/ztd-cli/package.json(3 hunks)packages/ztd-cli/src/commands/ddl.ts(1 hunks)packages/ztd-cli/src/commands/genEntities.ts(1 hunks)packages/ztd-cli/src/commands/init.ts(10 hunks)packages/ztd-cli/src/commands/options.ts(1 hunks)packages/ztd-cli/src/commands/ztdConfig.ts(7 hunks)packages/ztd-cli/src/commands/ztdConfigCommand.ts(1 hunks)packages/ztd-cli/src/index.ts(1 hunks)packages/ztd-cli/src/utils/agents.ts(1 hunks)packages/ztd-cli/src/utils/ztdProjectConfig.ts(1 hunks)packages/ztd-cli/tests/cliCommands.test.ts(2 hunks)packages/ztd-cli/tests/init.command.test.ts(5 hunks)packages/ztd-cli/tests/options.unit.test.ts(1 hunks)packages/ztd-cli/tests/utils/agents.test.ts(1 hunks)packages/ztd-cli/tests/ztdConfig.unit.test.ts(3 hunks)
💤 Files with no reviewable changes (4)
- packages/cli/AGENTS.md
- packages/cli/src/commands/ddl.ts
- packages/cli/README.md
- packages/cli/tests/options.unit.test.ts
✅ Files skipped from review due to trivial changes (1)
- AGENTS.md
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{ts,tsx,js,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
All identifiers, comments, and documentation remain in English
Files:
packages/ztd-cli/src/utils/agents.tspackages/ztd-cli/tests/utils/agents.test.tspackages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/src/index.tspackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.jsonpackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/tests/options.unit.test.tspackages/ztd-cli/src/commands/ztdConfigCommand.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/src/commands/init.tspackages/ztd-cli/AGENTS_ZTD.mdpackages/ztd-cli/README.md
packages/**/src/**/*.{ts,tsx,js}
📄 CodeRabbit inference engine (AGENTS.md)
Remove console debugging before committing
Files:
packages/ztd-cli/src/utils/agents.tspackages/ztd-cli/src/index.tspackages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/src/commands/ztdConfigCommand.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/src/commands/init.ts
packages/**/src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
All exported classes and types must include clear English JSDoc documentation in src/
Files:
packages/ztd-cli/src/utils/agents.tspackages/ztd-cli/src/index.tspackages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/src/commands/ztdConfigCommand.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/src/commands/init.ts
🧠 Learnings (66)
📓 Common learnings
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : In rawsql-ts/testkit-core, remain DBMS-agnostic with no Postgres/SQLite conditionals or behavior
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Implement DDL-based fixtures by parsing CREATE TABLE and INSERT statements from .sql schema files, producing fixture schema and baseline rows
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{core,testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : All SQL rewrites must rely on rawsql-ts AST utilities (parser, analyzer, splitQueries); regex-based rewrites are allowed only as guarded fallbacks with comments explaining why
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Repository and application SQL may use normal CRUD (INSERT, UPDATE, DELETE) operations; pg-testkit will automatically rewrite them into SELECT queries
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: Applies to packages/cli/**/*.ts : Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: CLI scaffolding templates must be compatible with rawsql-ts/testkit-core, rawsql-ts/pg-testkit, and rawsql-ts/sqlite-testkit
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Support CREATE TEMP TABLE ... AS SELECT as the only allowed temporary table DDL pattern in pg-testkit
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: No runtime dependency on rawsql-ts/cli in production code. All generated CLI outputs must be plain TypeScript/SQL that can be committed and maintained without the tool.
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Run pnpm --filter rawsql-ts test && pnpm --filter rawsql-ts build && pnpm --filter rawsql-ts lint before committing
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: After formatter export changes, run pnpm --filter rawsql-ts build:browser
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Add or update tests whenever adding features or fixing bugs
Applied to files:
packages/ztd-cli/tests/utils/agents.test.tspackages/ztd-cli/tests/options.unit.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/tests/utils/agents.test.tspackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.jsonpackages/ztd-cli/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/ztd-cli/tests/utils/agents.test.tspackages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.jsonpackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/tests/options.unit.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/ztd-cli/tests/utils/agents.test.tspackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/tests/options.unit.test.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Support CREATE TEMP TABLE ... AS SELECT as the only allowed temporary table DDL pattern in pg-testkit
Applied to files:
packages/ztd-cli/tests/utils/agents.test.tspackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Do not mutate fixtures as global state in testkit-core; keep fixture mutations scoped
Applied to files:
packages/ztd-cli/tests/utils/agents.test.ts
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Tests act as specifications - never update expectations without intent and alignment
Applied to files:
packages/ztd-cli/tests/utils/agents.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/options.unit.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/ztd-cli/tests/utils/agents.test.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.test.{ts,tsx,js} : Provide test-specific fixture rows via tableRows or withFixtures() rather than embedding them in schema files
Applied to files:
packages/ztd-cli/tests/utils/agents.test.tspackages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/ztd-cli/tests/utils/agents.test.tspackages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Implement DDL-based fixtures by parsing CREATE TABLE and INSERT statements from .sql schema files, producing fixture schema and baseline rows
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/src/index.tspackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.jsonpackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/tests/options.unit.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/src/commands/init.tspackages/ztd-cli/AGENTS_ZTD.mdpackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Never consult PostgreSQL for schema or row data; only use fixture-derived CTEs
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : In tests, no physical tables are created, migrated, or mutated; all schema information and seed rows must come from DDL files and fixtures, with pg-testkit rewriting CRUD statements into fixture-backed SELECT queries
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/tests/options.unit.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/src/commands/init.tspackages/ztd-cli/AGENTS_ZTD.mdpackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Convert insert defaults involving nextval(...) into deterministic expressions like row_number() over () to ensure consistent behavior without real sequences
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/AGENTS_ZTD.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Provide helper functions: createPgTestkitClient, createPgTestkitPool, wrapPgClient, and .withFixtures() overlay method
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/init.command.test.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : All CRUD operations (INSERT, UPDATE, DELETE) must be rewritten into fixture-backed SELECT queries before execution in pg-testkit
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/AGENTS_ZTD.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Never create or write to physical tables using CREATE TABLE, ALTER TABLE, INSERT, UPDATE, or DELETE statements in pg-testkit
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/AGENTS_ZTD.mdpackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Enforce fixture precedence: DDL fixtures (schema + shared seed) → Manual fixtures (tableDefinitions, tableRows) → Scoped fixtures (client.withFixtures())
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : pg-testkit must never bypass rewrite logic or attempt any real migration
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/AGENTS_ZTD.md
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Keep rewrite logic exclusively in testkit-core; pg-testkit driver must only adapt rewrite results and execute queries
Applied to files:
packages/drivers/pg-testkit/AGENTS.md
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/pg-testkit/src/**/*.{ts,tsx} : Do not execute CREATE TABLE, ALTER TABLE, or seed INSERTs over a pg-testkit connection; the DB engine is only for planning and type-checking
Applied to files:
packages/drivers/pg-testkit/AGENTS.mdpackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/AGENTS_ZTD.md
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: Applies to packages/cli/**/*.ts : Use AST-driven analysis from rawsql-ts/core for SQL inspection and transformation instead of regex-based string manipulation
Applied to files:
packages/ztd-cli/src/index.tspackages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/package.jsonpackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: No runtime dependency on rawsql-ts/cli in production code. All generated CLI outputs must be plain TypeScript/SQL that can be committed and maintained without the tool.
Applied to files:
packages/ztd-cli/src/index.tspackages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/package.jsonpackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/src/commands/init.tspackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/tests/cliCommands.test.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/AGENTS_ZTD.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Do not hand-construct QueryResult or mock Client#query; all tests must flow through the rewrite pipeline and fixtures
Applied to files:
packages/ztd-cli/tests/cliCommands.test.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/tests/cliCommands.test.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: CLI scaffolding templates must be compatible with rawsql-ts/testkit-core, rawsql-ts/pg-testkit, and rawsql-ts/sqlite-testkit
Applied to files:
packages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.jsonpackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/AGENTS_ZTD.mdpackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Repository and application SQL may use normal CRUD (INSERT, UPDATE, DELETE) operations; pg-testkit will automatically rewrite them into SELECT queries
Applied to files:
packages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.jsonpackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/AGENTS_ZTD.mdpackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : FixtureStore.describeColumns must surface table names, available columns, and suggested hints for error diagnostics
Applied to files:
packages/ztd-cli/tests/cliCommands.test.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Refactor for clarity and document public APIs before running the validation pipeline
Applied to files:
packages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/src/commands/init.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Add metadata to SelectAnalyzer instead of re-parsing or creating ad-hoc regex logic when extending rewrite capability in testkit-core
Applied to files:
packages/ztd-cli/src/commands/options.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{core,testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : Block contributions introducing regex parsing when an AST alternative exists
Applied to files:
packages/ztd-cli/src/commands/options.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Always canonicalize identifiers via normalizeIdentifier; never trust caller casing or quoting
Applied to files:
packages/ztd-cli/src/commands/options.tspackages/ztd-cli/tests/options.unit.test.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Include actionable hints in error messages that reference specific table and column names
Applied to files:
packages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/src/utils/ztdProjectConfig.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.jsonpackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/AGENTS_ZTD.mdpackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : Throw descriptive fail-fast errors for missing fixtures, unknown tables/columns, ambiguous columns, and unsupported constructs (e.g., INSERT … ON CONFLICT, mutating CTEs)
Applied to files:
packages/ztd-cli/src/commands/genEntities.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/tests/init.command.test.tspackages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/tests/options.unit.test.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Make DDL loader behavior deterministic and parse files only once per client/pool instance
Applied to files:
packages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/src/commands/ddl.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/tests/**/*.test.{ts,tsx,js} : Use real PostgreSQL Testcontainers instance for testing pg-testkit; support full parallel test execution with isolated fixture universes
Applied to files:
packages/ztd-cli/tests/init.command.test.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Never mock QueryResult; use real PostgreSQL query results with fixture-backed data
Applied to files:
packages/ztd-cli/tests/init.command.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : No code path bypasses testkit-core's rewrite pipeline
Applied to files:
packages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/package.json
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: After formatter export changes, run pnpm --filter rawsql-ts build:browser
Applied to files:
packages/ztd-cli/package.json
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Run pnpm --filter rawsql-ts test && pnpm --filter rawsql-ts build && pnpm --filter rawsql-ts lint before committing
Applied to files:
packages/ztd-cli/package.json
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Rebuild the browser bundle when parser or formatter changes: pnpm --filter rawsql-ts build:browser, then re-bundle for docs demo using esbuild, and commit updated docs/public/demo/vendor/rawsql.browser.js
Applied to files:
packages/ztd-cli/package.json
📚 Learning: 2025-12-02T22:56:43.151Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:43.151Z
Learning: Applies to packages/{core,testkit-core,pg-testkit,sqlite-testkit}/src/**/*.{ts,tsx} : All SQL rewrites must rely on rawsql-ts AST utilities (parser, analyzer, splitQueries); regex-based rewrites are allowed only as guarded fallbacks with comments explaining why
Applied to files:
packages/ztd-cli/package.jsonpackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/AGENTS_ZTD.md
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Supported runtime is Node 20+; optional features must degrade gracefully on other platforms or Node versions
Applied to files:
packages/ztd-cli/package.json
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Prefer import { ... } from 'rawsql-ts' over deep relative paths
Applied to files:
packages/ztd-cli/package.json
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/package.jsonpackages/ztd-cli/src/commands/ztdConfig.tspackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
Learning: Applies to packages/testkit-core/src/**/*.{ts,tsx} : RETURNING clauses should be rendered solely as SELECT projection in testkit-core rewrites
Applied to files:
packages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Use SQL normalization via SqlFormatter when comparing SQL in tests instead of hand-written comparisons
Applied to files:
packages/ztd-cli/tests/ztdConfig.unit.test.tspackages/ztd-cli/tests/options.unit.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/ztd-cli/tests/ztdConfig.unit.test.ts
📚 Learning: 2025-12-02T22:56:53.135Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/cli/AGENTS.md:0-0
Timestamp: 2025-12-02T22:56:53.135Z
Learning: All new CLI commands must include a README section with usage examples and tests for the command's main code path
Applied to files:
packages/ztd-cli/tests/options.unit.test.tspackages/ztd-cli/README.md
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/**/*.{test,spec}.ts : Regression testing for complex SQL should achieve ≥95% comment preservation, no token splits like table. /* comment */ column, and CASE expression comments preserved in evaluation order
Applied to files:
packages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:21.011Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:21.011Z
Learning: Applies to packages/core/src/**/*.ts : Keep all comments and identifiers in English
Applied to files:
packages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Do not use regex-based SQL parsing inside sqlite-testkit; if temporary regex-based merge is absolutely required, add TODO and inline comment, emit logger.debug notice, and file an issue in testkit-core
Applied to files:
packages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:58:15.329Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/testkit-core/AGENTS.md:0-0
Timestamp: 2025-12-02T22:58:15.329Z
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/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
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/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/src/**/*.{ts,tsx} : Surface clear, typed errors from the driver layer using error classes like MissingFixtureError and SchemaValidationError with descriptive messages including table/column hints
Applied to files:
packages/ztd-cli/src/commands/ztdConfig.ts
📚 Learning: 2025-12-02T22:57:36.031Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/pg-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:36.031Z
Learning: Applies to packages/drivers/pg-testkit/**/*.{ts,tsx,js} : Ensure result types follow PostgreSQL casting rules to maintain parity with real-world applications
Applied to files:
packages/ztd-cli/AGENTS_ZTD.md
📚 Learning: 2025-12-02T22:57:55.626Z
Learnt from: CR
Repo: mk3008/rawsql-ts PR: 0
File: packages/drivers/sqlite-testkit/AGENTS.md:0-0
Timestamp: 2025-12-02T22:57:55.626Z
Learning: Applies to packages/drivers/sqlite-testkit/**/README.md : Adapters must be documented in README.md with realistic fixture-based examples
Applied to files:
packages/ztd-cli/README.md
🧬 Code graph analysis (7)
packages/ztd-cli/tests/utils/agents.test.ts (1)
packages/ztd-cli/src/utils/agents.ts (1)
copyAgentsTemplate(8-29)
packages/ztd-cli/src/index.ts (2)
packages/ztd-cli/src/commands/init.ts (1)
registerInitCommand(413-425)packages/ztd-cli/src/commands/ztdConfigCommand.ts (1)
registerZtdConfigCommand(18-46)
packages/ztd-cli/tests/init.command.test.ts (1)
packages/ztd-cli/src/commands/init.ts (1)
ZtdConfigWriterDependencies(93-102)
packages/ztd-cli/tests/options.unit.test.ts (1)
packages/ztd-cli/src/commands/options.ts (5)
normalizeDirectoryList(10-15)DEFAULT_DDL_DIRECTORY(2-2)parseExtensions(17-29)resolveExtensions(31-35)DEFAULT_EXTENSIONS(1-1)
packages/ztd-cli/src/commands/ztdConfigCommand.ts (3)
packages/ztd-cli/src/commands/options.ts (7)
collectDirectories(6-8)parseExtensions(17-29)DEFAULT_EXTENSIONS(1-1)normalizeDirectoryList(10-15)DEFAULT_DDL_DIRECTORY(2-2)resolveExtensions(31-35)DEFAULT_TESTS_DIRECTORY(3-3)packages/ztd-cli/src/utils/ztdProjectConfig.ts (1)
loadZtdProjectConfig(22-40)packages/ztd-cli/src/commands/ztdConfig.ts (2)
ZtdConfigGenerationOptions(13-17)runGenerateZtdConfig(31-46)
packages/ztd-cli/src/commands/ddl.ts (4)
packages/ztd-cli/src/commands/options.ts (6)
DEFAULT_DDL_DIRECTORY(2-2)collectDirectories(6-8)parseExtensions(17-29)DEFAULT_EXTENSIONS(1-1)normalizeDirectoryList(10-15)resolveExtensions(31-35)packages/ztd-cli/src/commands/pull.ts (1)
runPullSchema(12-22)packages/ztd-cli/src/commands/genEntities.ts (1)
runGenerateEntities(14-29)packages/ztd-cli/src/commands/diff.ts (1)
runDiffSchema(16-38)
packages/ztd-cli/src/commands/ztdConfig.ts (2)
packages/ztd-cli/src/utils/fs.ts (1)
ensureDirectory(3-10)packages/ztd-cli/src/utils/collectSqlFiles.ts (1)
SqlSource(4-7)
🪛 LanguageTool
packages/ztd-cli/AGENTS_ZTD.md
[style] ~8-~8: This phrase is redundant. Consider using “outside”.
Context: ...efinitions or re-derive schema metadata outside of tests/ztd-config.ts. If a table or co...
(OUTSIDE_OF)
packages/ztd-cli/README.md
[grammar] ~79-~79: Ensure spelling is correct
Context: ...ventions for AI agents, including which testkit to use, how to treat `tests/ztd-config....
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
Comment on lines
+239
to
265
| const ztdConfigTarget = await confirmOverwriteIfExists( | ||
| absolutePaths.ztdConfig, | ||
| relativePath('ztdConfig'), | ||
| dependencies, | ||
| prompter | ||
| ); | ||
|
|
||
| if (entitiesNeeded.write) { | ||
| await dependencies.runGenerateEntities({ | ||
| if (ztdConfigTarget.write) { | ||
| // Regenerate tests/ztd-config.ts so TestRowMap reflects the DDL snapshot. | ||
| dependencies.ensureDirectory(path.dirname(absolutePaths.ztdConfig)); | ||
| dependencies.runGenerateZtdConfig({ | ||
| directories: [path.resolve(path.dirname(absolutePaths.schema))], | ||
| extensions: ['.sql'], | ||
| out: absolutePaths.entities | ||
| extensions: DEFAULT_EXTENSIONS, | ||
| out: absolutePaths.ztdConfig | ||
| }); | ||
| } else { | ||
| dependencies.log('Skipping entity generation; existing tests/entities.ts preserved.'); | ||
| dependencies.log('Skipping ZTD config generation; existing tests/ztd-config.ts preserved.'); | ||
| } | ||
|
|
||
| summaries.entities = { | ||
| relativePath: relativePath('entities'), | ||
| outcome: entitiesNeeded.existed ? (entitiesNeeded.write ? 'overwritten' : 'unchanged') : 'created' | ||
| summaries.ztdConfig = { | ||
| relativePath: relativePath('ztdConfig'), | ||
| outcome: ztdConfigTarget.existed | ||
| ? ztdConfigTarget.write | ||
| ? 'overwritten' | ||
| : 'unchanged' | ||
| : 'created' | ||
| }; |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find the definition of runGenerateZtdConfig and ZtdConfigWriterDependencies
rg -n "runGenerateZtdConfig" -B2 -A5 packages/ztd-cli/srcRepository: mk3008/rawsql-ts
Length of output: 5618
🏁 Script executed:
#!/bin/bash
# Find the ZtdConfigWriterDependencies interface definition
rg -n "ZtdConfigWriterDependencies" -B2 -A15 packages/ztd-cli/srcRepository: mk3008/rawsql-ts
Length of output: 10510
🏁 Script executed:
#!/bin/bash
# Check the entire init.ts file structure to understand the dependencies object
head -100 packages/ztd-cli/src/commands/init.tsRepository: mk3008/rawsql-ts
Length of output: 3343
🏁 Script executed:
#!/bin/bash
# Check if there are test files that inject async implementations
find packages/ztd-cli -name "*.test.ts" -o -name "*.spec.ts" | head -20Repository: mk3008/rawsql-ts
Length of output: 321
🏁 Script executed:
#!/bin/bash
# Look at the actual function signature in ztdConfig.ts more carefully
cat -n packages/ztd-cli/src/commands/ztdConfig.ts | head -50Repository: mk3008/rawsql-ts
Length of output: 1994
🏁 Script executed:
#!/bin/bash
# Check the context around line 249 in init.ts to see the full function
sed -n '240,270p' packages/ztd-cli/src/commands/init.tsRepository: mk3008/rawsql-ts
Length of output: 1028
🏁 Script executed:
#!/bin/bash
# Check the test file to see if async implementations are injected
cat -n packages/ztd-cli/tests/init.command.test.ts | head -200Repository: mk3008/rawsql-ts
Length of output: 6447
🏁 Script executed:
#!/bin/bash
# Check how runPullSchema is called to see the pattern for handling Promise<void> | void
grep -n "runPullSchema" packages/ztd-cli/src/commands/init.ts -B2 -A2Repository: mk3008/rawsql-ts
Length of output: 1151
🏁 Script executed:
#!/bin/bash
# Check the full context around runPullSchema and runGenerateZtdConfig calls in init.ts
sed -n '200,265p' packages/ztd-cli/src/commands/init.tsRepository: mk3008/rawsql-ts
Length of output: 2005
Add await to runGenerateZtdConfig call to match the pattern used for runPullSchema.
runGenerateZtdConfig is typed identically to runPullSchema as (options: ZtdConfigGenerationOptions) => Promise<void> | void in the ZtdConfigWriterDependencies interface. However, at line 249, runGenerateZtdConfig is invoked without await, whereas runPullSchema is properly awaited at line 203. This inconsistency could cause issues if the implementation becomes async or if an async mock is injected in tests—the command would complete before file generation finishes.
Change line 249 to:
await dependencies.runGenerateZtdConfig({This ensures the CLI lifecycle remains deterministic and aligns with how runPullSchema is handled in the same function.
🤖 Prompt for AI Agents
In packages/ztd-cli/src/commands/init.ts around lines 239 to 265, the call to
dependencies.runGenerateZtdConfig is not awaited while similar calls (e.g.,
runPullSchema) are awaited; update the invocation to await
dependencies.runGenerateZtdConfig(...) so the CLI waits for generation to finish
(keeping the surrounding async function signature and error propagation as-is).
Comment on lines
+4
to
+16
| export interface ZtdProjectConfig { | ||
| dialect: string; | ||
| ddlDir: string; | ||
| testsDir: string; | ||
| } | ||
|
|
||
| const CONFIG_NAME = 'ztd.config.json'; | ||
|
|
||
| export const DEFAULT_ZTD_CONFIG: ZtdProjectConfig = { | ||
| dialect: 'postgres', | ||
| ddlDir: 'ddl', | ||
| testsDir: 'tests' | ||
| }; |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Config load/write behavior is robust; add JSDoc for the exported config type
The ZTD project config utilities correctly handle missing and partial configs, validate fields, and emit a stable JSON representation. This is a solid foundation for CLI behavior.
To align with the repo’s guideline that all exported types be documented, please add concise JSDoc to ZtdProjectConfig (and optionally to DEFAULT_ZTD_CONFIG) describing the purpose of each field (dialect, ddlDir, testsDir) and how consumers should use them.
Also applies to: 22-40, 42-52
🤖 Prompt for AI Agents
In packages/ztd-cli/src/utils/ztdProjectConfig.ts around lines 4-16 (and also
apply at 22-40 and 42-52), the exported ZtdProjectConfig type lacks JSDoc; add
concise JSDoc above the exported interface describing the purpose of the
interface and each field (dialect: SQL dialect name, ddlDir: directory for DDL
files, testsDir: directory for tests) and how callers should use/override them,
and optionally add a short JSDoc above DEFAULT_ZTD_CONFIG describing that it
provides sensible defaults and may be used when no user config is present; keep
comments short, one or two sentences per item.
mk3008
deleted the
268-ztd-row-type-overhaul-rename-test-rows-introduce-ztd-config-and-add-ddl-watch-sync
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.