Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
15 changes: 1 addition & 14 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,22 +52,9 @@ jobs:
- name: Validate test-evidence boundaries and consumers
if: matrix.node-version == '20.x'
run: |
pnpm -r --if-present --filter @rawsql-ts/test-evidence-core --filter @rawsql-ts/test-evidence-renderer-md --filter @rawsql-ts/shared-binder --filter @rawsql-ts/testkit-core --filter @rawsql-ts/testkit-postgres --filter @rawsql-ts/testkit-sqlite --filter @rawsql-ts/adapter-node-pg --filter @rawsql-ts/ztd-cli run build
pnpm -r --if-present --filter @rawsql-ts/test-evidence-core --filter @rawsql-ts/test-evidence-renderer-md --filter @rawsql-ts/shared-binder --filter @rawsql-ts/testkit-core --filter @rawsql-ts/testkit-postgres --filter @rawsql-ts/testkit-sqlite --filter @rawsql-ts/adapter-node-pg run build
pnpm -r --if-present --filter @rawsql-ts/test-evidence-core --filter @rawsql-ts/test-evidence-renderer-md --filter @rawsql-ts/testkit-core --filter @rawsql-ts/testkit-postgres --filter @rawsql-ts/testkit-sqlite --filter @rawsql-ts/adapter-node-pg run test
pnpm --filter @rawsql-ts/shared-binder run test:consumer-validation
pnpm --filter @rawsql-ts/ztd-cli run test:consumer-validation

- name: Build ztd-cli for generated mapper drift
if: matrix.node-version == '20.x'
run: pnpm --filter @rawsql-ts/ztd-cli run build

- name: Check generated mapper drift
if: matrix.node-version == '20.x'
run: pnpm verify:generated-mapper-drift

- name: Test generated mapper scaffold and drift commands
if: matrix.node-version == '20.x'
run: pnpm --filter @rawsql-ts/ztd-cli run test:generated-mapper

customer-consumer-guard:
runs-on: ${{ matrix.os }}
Expand Down
1 change: 0 additions & 1 deletion .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,6 @@ jobs:
run: |
pnpm --filter rawsql-ts run build
pnpm --filter @rawsql-ts/testkit-core run build
pnpm --filter @rawsql-ts/ztd-cli run build

- name: Verify transfer docs and metadata drift
run: pnpm run verify:transfer-docs
Expand Down
92 changes: 0 additions & 92 deletions .github/workflows/pr-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,51 +49,6 @@ jobs:
- name: Run unit tests (core)
run: pnpm --filter "./packages/core" run test

- name: Detect playground-impacting changes
id: playground_changes
shell: bash
run: |
base_sha="${{ github.event.pull_request.base.sha }}"
head_sha="${{ github.event.pull_request.head.sha }}"
changed_files=$(git diff --name-only "$base_sha...$head_sha")
printf '%s\n' "$changed_files"

if printf '%s\n' "$changed_files" | grep -Eq '^(packages/ztd-cli/|packages/test-evidence-core/|packages/test-evidence-renderer-md/|packages/testkit-core/|playgrounds/ztd-playground/|\.github/workflows/pr-check\.yml$)'; then
echo "run=true" >> "$GITHUB_OUTPUT"
else
echo "run=false" >> "$GITHUB_OUTPUT"
fi

- name: Detect scaffold-layout changes
id: generated_project_changes
shell: bash
run: |
base_sha="${{ github.event.pull_request.base.sha }}"
head_sha="${{ github.event.pull_request.head.sha }}"
changed_files=$(git diff --name-only "$base_sha...$head_sha")
printf '%s\n' "$changed_files"

if printf '%s\n' "$changed_files" | grep -Eq '^(package\.json|scripts/verify-generated-project-mode\.mjs|packages/ztd-cli/package\.json|packages/ztd-cli/(README\.md|src/commands/(feature|init)\.ts|templates/|tests/(cliCommands|featureScaffold\.unit|init\.command)\.test\.ts)|docs/guide/(generated-project-verification|ztd-local-source-dogfooding|sql-first-end-to-end-tutorial)\.md|\.github/workflows/pr-check\.yml$)'; then
echo "run=true" >> "$GITHUB_OUTPUT"
else
echo "run=false" >> "$GITHUB_OUTPUT"
fi

- name: Detect ztd-cli essential-gate changes
id: ztd_cli_gates
shell: bash
run: |
base_sha="${{ github.event.pull_request.base.sha }}"
head_sha="${{ github.event.pull_request.head.sha }}"
changed_files=$(git diff --name-only "$base_sha...$head_sha")
printf '%s\n' "$changed_files"

if printf '%s\n' "$changed_files" | grep -Eq '^(\.husky/pre-commit|\.github/pull_request_template\.md|\.github/workflows/pr-check\.yml|\.github/workflows/ztd-cli-soft-gates\.yml|scripts/(check-pr-readiness|run-ztd-cli-quality-gates|ztd-cli-quality-gates)\.js|docs/guide/(release-readiness|ztd-cli-quality-gates)\.md|packages/ztd-cli/|docs/guide/ztd-cli-)'; then
echo "run=true" >> "$GITHUB_OUTPUT"
else
echo "run=false" >> "$GITHUB_OUTPUT"
fi

- name: Detect transfer DDL metadata changes
id: transfer_ddl_metadata
shell: bash
Expand All @@ -109,53 +64,6 @@ jobs:
echo "run=false" >> "$GITHUB_OUTPUT"
fi

- name: Build ZTD CLI dependencies
if: steps.playground_changes.outputs.run == 'true'
run: |
pnpm --filter rawsql-ts run build
pnpm --filter @rawsql-ts/test-evidence-core run build
pnpm --filter @rawsql-ts/test-evidence-renderer-md run build
pnpm --filter @rawsql-ts/testkit-core run build
pnpm --filter @rawsql-ts/ztd-cli run build

- name: Detect deprecated playground
id: playground
if: steps.playground_changes.outputs.run == 'true'
run: |
if [ -d "./playgrounds/ztd-playground" ]; then
echo "exists=true" >> "$GITHUB_OUTPUT"
else
echo "exists=false" >> "$GITHUB_OUTPUT"
echo "playgrounds/ztd-playground is removed; skipping playground artifact generation."
fi

# Playground artifact generation stays in PR checks, but only when relevant packages or the workflow changed.
- name: Generate ZTD artifacts (playground)
if: steps.playground_changes.outputs.run == 'true' && steps.playground.outputs.exists == 'true'
working-directory: ./playgrounds/ztd-playground
run: node ../../packages/ztd-cli/dist/index.js ztd-config

- name: Verify working tree is clean after generation
if: steps.playground_changes.outputs.run == 'true' && steps.playground.outputs.exists == 'true'
run: git diff --exit-code

- name: Run generated-project verification lane
if: steps.generated_project_changes.outputs.run == 'true'
run: pnpm verify:generated-project-mode

- name: Build ztd-cli gate dependencies
if: steps.ztd_cli_gates.outputs.run == 'true'
run: |
pnpm --filter rawsql-ts run build
pnpm --filter @rawsql-ts/sql-grep-core run build
pnpm --filter @rawsql-ts/test-evidence-core run build
pnpm --filter @rawsql-ts/test-evidence-renderer-md run build
pnpm --filter @rawsql-ts/testkit-core run build

- name: Run ztd-cli essential gates
if: steps.ztd_cli_gates.outputs.run == 'true'
run: node scripts/run-ztd-cli-quality-gates.js pr

- name: Check transfer docs and metadata drift
if: steps.transfer_ddl_metadata.outputs.run == 'true'
run: pnpm verify:transfer-docs
Expand Down
3 changes: 0 additions & 3 deletions .github/workflows/refresh-demo-bundle.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,6 @@ jobs:
- name: Build testkit-core package
run: pnpm --filter @rawsql-ts/testkit-core build

- name: Build ztd-cli package
run: pnpm --filter @rawsql-ts/ztd-cli build

- name: Build rawsql-ts browser output
run: pnpm --filter rawsql-ts build:browser

Expand Down
31 changes: 0 additions & 31 deletions .github/workflows/ztd-cli-soft-gates.yml

This file was deleted.

40 changes: 11 additions & 29 deletions .husky/pre-commit
Original file line number Diff line number Diff line change
Expand Up @@ -16,34 +16,16 @@ node scripts/precommit-enforcement.js
# Do not let tests that create temporary Git repositories inherit the hook index.
unset GIT_INDEX_FILE

ZTD_ONLY=true
for file in $STAGED_FILES
do
case "$file" in
.github/workflows/*|.husky/pre-commit|packages/ztd-cli/*|docs/guide/ztd-cli-*|scripts/run-ztd-cli-quality-gates.js|scripts/ztd-cli-quality-gates.js|.changeset/*|README.md)
;;
*)
ZTD_ONLY=false
break
;;
esac
done

if [ "$ZTD_ONLY" = true ]; then
echo "[pre-commit] Detected ztd-cli scoped changes."
node scripts/run-ztd-cli-quality-gates.js pre-commit
else
echo "[pre-commit] Running workspace typecheck..."
pnpm typecheck

echo "[pre-commit] Running workspace tests..."
pnpm test

echo "[pre-commit] Building workspace..."
pnpm build

echo "[pre-commit] Running workspace lint..."
pnpm lint
fi
echo "[pre-commit] Running workspace typecheck..."
pnpm typecheck

echo "[pre-commit] Running workspace tests..."
pnpm test

echo "[pre-commit] Building workspace..."
pnpm build

echo "[pre-commit] Running workspace lint..."
pnpm lint

echo "[pre-commit] All checks passed."
1 change: 0 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,6 @@ Deeper `AGENTS.md` files take precedence when they add stricter or narrower rule
- Development has two completion stages: first prove the feature and regression tests, then run a separate finishing review pass before PR handoff.
- The finishing review pass must use the available self-review workflow or repo-local review skill, and it must look for cross-mode regressions such as direct command versus PR/worktree command behavior.
- The finishing review pass must include a concept boundary review when the change touches package behavior, generated scaffold output, generated runtime code, docs, or PR wording. Read the owning package concept, package scope, technology policy, or Concept Spec when one exists.
- For `@rawsql-ts/ztd-cli`, the concept boundary review must check that the standard generated runtime path remains runtime-free: no dependency on `ztd-cli`, `rawsql-ts`, runtime mapper libraries, runtime validator libraries, SQL JSON result shaping, or hidden business SQL rewriting. Test support and driver adapters may exist only within their stated non-ORM, driver/test roles.
- Final PR text and final implementation reports must pass self-review before human review.
- Before creating or editing a PR, read `.github/pull_request_template.md` and use `.agents/skills/pr-readiness/SKILL.md` when present.
- Before claiming a PR is ready, run the repository PR readiness script locally when `scripts/check-pr-readiness.js` exists, or explicitly state why it could not be run.
Expand Down
58 changes: 10 additions & 48 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,9 @@

A monorepo for **rawsql-ts**: a SQL-first toolkit for parsing, testing, inspecting, and evolving database applications while keeping raw SQL as a first-class asset.

By parsing SQL into abstract syntax trees, rawsql-ts enables type-safe query building, static validation, and transparent result mapping — all while preserving the expressiveness and control of handwritten SQL. AST-based rewriting also powers Zero Table Dependency (ZTD) testing, which transforms application queries to run against in-memory fixtures instead of physical tables, enabling deterministic unit tests without database setup overhead. The repo additionally covers AST-based impact analysis, deterministic test evidence, schema documentation, and `ztd-cli` workflows for inspection and SQL artifact generation.
By parsing SQL into abstract syntax trees, rawsql-ts enables type-safe query building, static validation, fixture-backed testing, and transparent result mapping while preserving the expressiveness and control of handwritten SQL. AST-based rewriting also powers Zero Table Dependency (ZTD) testkits, which transform application queries to run against in-memory fixtures instead of physical tables.

The `ztd init` scaffold now starts from a feature-first layout under `src/features/<feature>/` and includes `src/features/smoke/` as the removable teaching feature.
Shared feature seams live under `src/features/_shared/`, driver-neutral runtime contracts under `src/libraries/`, driver or sink bindings under `src/adapters/<tech>/`, shared verification seams under `tests/support/`, and tool-managed assets under `.ztd/`.
`src/catalog` may still exist as internal support, but it is no longer the user-facing standard location.
The former `@rawsql-ts/ztd-cli` package has moved to the Ashiba project as `@ashiba-ts/cli`. Use [mk3008/ashiba](https://github.com/mk3008/ashiba) for SQL-first scaffolding, command-line inspection, optional-condition maintenance, and project lifecycle workflows.

> [!Note]
> This project is currently in beta. APIs may change until the v1.0 release.
Expand All @@ -28,20 +26,18 @@ Use this section as the shortest repo-level map. It is intentionally brief: pack
| ZTD fixture rewriting and testkits | `@rawsql-ts/testkit-*` | [packages/testkit-core](./packages/testkit-core) |
| Test evidence storage and rendering | `@rawsql-ts/test-evidence-*` | [packages/test-evidence-core](./packages/test-evidence-core) |
| Schema documentation generation | `@rawsql-ts/ddl-docs-*` | [packages/ddl-docs-cli](./packages/ddl-docs-cli) |
| ZTD project scaffolding and SQL lifecycle tooling | `@rawsql-ts/ztd-cli` | [packages/ztd-cli/README.md](./packages/ztd-cli/README.md) |
| Ashiba CLI workflows | `@ashiba-ts/cli` | [mk3008/ashiba](https://github.com/mk3008/ashiba) |

### Workflow Surfaces

These capabilities are important at the repo level even though they are mostly exposed through `ztd-cli` commands rather than standalone packages.
These workflows are now owned by Ashiba. rawsql-ts keeps the reusable parser, formatter, testkit, binder, SQL grep, and documentation packages that Ashiba can consume.

| Workflow | Entry point | Why it matters |
|----------|-------------|----------------|
| SQL pipeline planning and dry-run optimization analysis | `ztd query plan`, `ztd perf run --dry-run` | Explains how SQL may be decomposed into stages before execution. |
| SQL impact analysis before schema changes | `ztd query uses` | Supports rename/type-change investigations using AST-based usage analysis. |
| SQL-first optional filter authoring | `ztd query sssql scaffold`, `ztd query sssql refresh` | Keeps optional filters visible in SQL while runtime pruning stays explicit. Runtime no longer injects new filter predicates. |
| SQL debug and recovery for long CTE queries | `ztd query outline`, `ztd query lint`, `ztd query slice`, `ztd query patch apply` | Helps isolate and repair problematic query shapes; `ztd query lint --rules join-direction` adds a FK-aware JOIN readability guard. |
| Explicit-target schema inspection and migration-prep workflow | `ztd ddl diff`, `ztd ddl pull` | Supports safe inspection against explicit target databases and generation of diff / patch SQL artifacts. Applying generated SQL is intentionally out of scope. |
| Machine-readable CLI automation and telemetry | `ztd --output json`, `ztd describe`, telemetry export modes | Supports AI/tooling integration and timing investigation. |
| SQL impact analysis before schema changes | `@rawsql-ts/sql-grep-core` / Ashiba query commands | Supports rename/type-change investigations using AST-based usage analysis. |
| SQL-first optional filter authoring | `rawsql-ts` SSSQL APIs / Ashiba query commands | Keeps optional filters visible in SQL while runtime pruning stays explicit. Runtime no longer injects new filter predicates. |
| Fixture-backed SQL unit testing | `@rawsql-ts/testkit-*` | Runs SQL against deterministic fixtures without a production database dependency. |
| Schema documentation generation | `@rawsql-ts/ddl-docs-*` | Generates reviewable Markdown schema documentation from DDL assets. |

## Packages

Expand Down Expand Up @@ -96,14 +92,6 @@ The planned rename path is to add a non-breaking alias such as `@rawsql-ts/testk
| [@rawsql-ts/ddl-docs-cli](./packages/ddl-docs-cli) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ddl-docs-cli) | CLI that generates Markdown table definition docs from DDL files. |
| [@rawsql-ts/ddl-docs-vitepress](./packages/ddl-docs-vitepress) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ddl-docs-vitepress) | Scaffold generator for VitePress-based database schema documentation sites. |

### CLI

| Package | Version | Description |
|---------|---------|-------------|
| [@rawsql-ts/ztd-cli](./packages/ztd-cli) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ztd-cli) | SQL-first CLI for ZTD workflows, schema inspection, and migration SQL artifact generation. |

For the machine-readable CLI surface, see [ztd-cli Agent Interface](./docs/guide/ztd-cli-agent-interface.md) and [ztd-cli Describe Schema](./docs/guide/ztd-cli-describe-schema.md).

## Architecture

```text
Expand All @@ -117,8 +105,7 @@ rawsql-ts (core)
│ └─ @rawsql-ts/testkit-sqlite
├─ @rawsql-ts/ddl-docs-cli
│ └─ @rawsql-ts/ddl-docs-vitepress
└─ @rawsql-ts/ztd-cli
└─ uses @rawsql-ts/sql-grep-core for `query uses`
└─ consumed by Ashiba for CLI workflows
```

## Quick Start
Expand All @@ -127,12 +114,7 @@ rawsql-ts (core)
npm install rawsql-ts
```

See the [Core Package Documentation](./packages/core/README.md) for usage examples and API reference. For reusable AST-based impact analysis, see [@rawsql-ts/sql-grep-core](./packages/sql-grep-core). For repo-level SQL lifecycle workflows, inspection commands, and ZTD project guidance, see [@rawsql-ts/ztd-cli](./packages/ztd-cli/README.md). Deterministic dogfooding spec: [docs/dogfooding/DOGFOODING.md](./docs/dogfooding/DOGFOODING.md).

## Tutorials

- [SQL-first End-to-End Tutorial](./docs/guide/sql-first-end-to-end-tutorial.md) - Walk from DDL to `ztd-config`, `model-gen`, repository wiring, and the first passing smoke test in one focused path.
- [Migration Repair Loop](./docs/dogfooding/ztd-migration-lifecycle.md) - Repair DDL, SQL, DTO, and migration artifacts with AI after the starter flow is green.
See the [Core Package Documentation](./packages/core/README.md) for usage examples and API reference. For reusable AST-based impact analysis, see [@rawsql-ts/sql-grep-core](./packages/sql-grep-core). For CLI scaffolding and SQL lifecycle workflows, use [Ashiba](https://github.com/mk3008/ashiba).

## Intent and Procedure

Expand Down Expand Up @@ -173,26 +155,6 @@ volumes:

Then run `docker compose up -d` and point `ZTD_DB_URL` at that database for the fixture-backed rewrite path.

## CLI Tool Routing Happy Paths

- SQL pipeline / debug → `ztd query plan <sql-file>`
- Impact analysis → `ztd query uses <target>`
- SQL-first optional filters → `ztd query sssql scaffold <sql-file>` / `ztd query sssql refresh <sql-file>`
- Schema inspection → `ztd ddl diff --url <target>`

For the full routing guide and decision table, see [SQL Tool Happy Paths](./docs/guide/sql-tool-happy-paths.md).

## Database Boundary at a Glance

For repo-level workflows, keep this boundary in mind:

* `.env` is the source of truth for the fixture-backed ZTD runtime inputs, and `ZTD_DB_URL` is the implicit database input used by `ztd-cli`
* `DATABASE_URL` is typically an application/runtime/deployment concern and is not read automatically by `ztd-cli`
* any non-ZTD database target must be supplied explicitly via `--url` or `--db-*`
* migration SQL artifacts may be generated by `ztd-cli`, but apply / deployment execution remains outside its ownership

This boundary exists for both AI-driven and human-driven workflows. It keeps test, inspection, and deployment concerns from silently collapsing into a single default database model.

## Online Demo

[Try rawsql-ts in your browser](https://mk3008.github.io/rawsql-ts/)
Expand Down
Loading
Loading