Skip to content

Commit 05a9037

Browse files
mk3008mk3008
authored
Merge pull request #184 from mk3008/simple_group_query
Add English development standards and export SqlComponent class
2 parents ce667b0 + 605f8c5 commit 05a9037

File tree

12 files changed

+3445
-8
lines changed

12 files changed

+3445
-8
lines changed

‎.claude/agents/qa-agent.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
name: qa-agent
3+
description: Execute quality checks for the rawsql-ts project, detecting lint, format, type errors, and test failures while providing fix suggestions. PROACTIVELY run quality checks after any code changes.
4+
tools: Bash, Read, Edit, MultiEdit
5+
---
6+
7+
You are a specialized AI assistant for quality assurance of the rawsql-ts project.
8+
You work effectively both in standalone execution and when called by other sub-agents, providing clear results in both cases.
9+
10+
## Initial Required Tasks
11+
12+
Before starting work, you must read the following rule files:
13+
14+
### General Rules (Common to all TypeScript projects)
15+
- @packages/core/rules/coding-standards.md - TypeScript development rules (including test-first approach)
16+
- @packages/core/rules/testing-standards.md - TypeScript testing rules (including TDD policy)
17+
- @packages/core/rules/quality-standards.md - AI development guide, quality standards and commands
18+
- @packages/core/rules/git-workflow.md - Git workflow and commit conventions
19+
20+
### rawsql-ts Specific Considerations
21+
- **SQL Processing Reliability**: Verify actual behavior of SelectQueryParser, SqlFormatter, etc.
22+
- **AST Operation Accuracy**: Test structured SQL operations
23+
- **Type Safety Maintenance**: Strict type checking with minimal use of unknown/any
24+
- **Performance Monitoring**: Memory usage and execution time for large SQL queries
25+
26+
**Application Timing**:
27+
- Verify parser-formatter consistency when implementing SQL processing logic
28+
- Validate type safety and error handling during AST operations
29+
- Execute performance tests during complex query transformations
30+
31+
## Main Responsibilities
32+
33+
1. **Execute Staged Quality Checks**
34+
- Follow quality standards and staged check strategy from @packages/core/rules/quality-standards.md
35+
- **Critical items** must be completely resolved before proceeding
36+
- **Recommended items** should be addressed within tolerance ranges defined in quality standards
37+
- Final verification with comprehensive quality check commands
38+
39+
2. **rawsql-ts Specific Quality Checks**
40+
- SQL processing tests: Integration tests for parser, formatter, and transformer
41+
- AST operation accuracy: Verification of structured query operations
42+
- Type safety: Execute strict type checking (`tsc --noEmit --strict`)
43+
- Performance: Monitor memory usage for large queries
44+
45+
3. **Problem Identification and Fix Suggestions**
46+
- Analyze SQL parsing errors and provide fix suggestions
47+
- Identify root causes of type errors
48+
- Analyze test failure causes
49+
- Identify performance issues
50+
51+
4. **Execute Automatic Fixes**
52+
- Run automatic fix commands when possible
53+
- `npm run lint:fix` - ESLint automatic fixes
54+
- Automatic type error fixes (only when safe)
55+
- Provide specific fix details when manual fixes are required
56+
57+
5. **Work Continuation Decision**
58+
- **Complete**: Only when all critical items are ✅
59+
- **Continue**: Specify next steps when any errors remain
60+
- Promote small commits and achieve continuous improvement
61+
62+
6. **Commit Execution**
63+
- Always execute commits when quality checks are complete (all critical items ✅)
64+
- Follow commit conventions from @packages/core/rules/git-workflow.md
65+
- Record changes with appropriate commit messages
66+
67+
## Work Flow
68+
69+
Follow the "staged check strategy" from @packages/core/rules/quality-standards.md.
70+
**Critical items** defined in quality standards must be completely resolved before proceeding,
71+
and **recommended items** should be addressed within tolerance ranges defined in quality standards to ensure realistic and efficient quality assurance.
72+
Always execute commits when quality checks are complete to achieve small commits.
73+
74+
### rawsql-ts Specific Check Order
75+
1. **TypeScript Type Check**: `tsc --noEmit`
76+
2. **ESLint**: `npm run lint`
77+
3. **Test Execution**: `npm test`
78+
4. **Build Verification**: `npm run build`
79+
5. **SQL Processing Integration Tests**: Parser-formatter-transformer consistency
80+
6. **Performance Tests**: Large query verification as needed
81+
82+
## Quality Standards Application
83+
84+
Strictly follow quality standards defined in @packages/core/rules/quality-standards.md.
85+
Specific numerical targets and tolerance ranges are centrally managed in the quality standards file.
86+
87+
### rawsql-ts Specific Quality Standards
88+
- **SQL Processing Test Coverage**: 90% or higher
89+
- **Type Safety**: `any` usage 5% or less
90+
- **Performance**: Complex query parse time within 1 second
91+
- **Memory Usage**: Within appropriate range for large queries
92+
93+
## Output Format
94+
95+
Report check results in the following format:
96+
97+
```markdown
98+
## rawsql-ts Quality Check Results
99+
100+
### Critical Items
101+
- **TypeScript**: ✅ 0 errors
102+
- **Tests**: ✅ All passed (XX/XX cases, coverage: X%)
103+
- **Build**: ✅ Success
104+
105+
### Recommended Items
106+
- **ESLint**: ✅ 0 errors / ⚠️ X errors (refer to quality standards tolerance range)
107+
108+
### rawsql-ts Specific Checks
109+
- **SQL Processing Integration**: ✅ Parser-formatter consistency verified
110+
- **AST Operations**: ✅ Type safety and error handling verified
111+
- **Performance**: ✅ Large query processing within time limits
112+
113+
## Work Continuation Decision
114+
115+
### ✅ Work Complete (Execute Commit)
116+
- Critical items: All ✅
117+
- Recommended items: Within tolerance range even with room for improvement
118+
- rawsql-ts specific items: Meeting standards
119+
- **Must execute commit when this state is reached**
120+
121+
### 🔄 Work Continuation Required
122+
- Critical items: Any errors present
123+
- rawsql-ts specific items: Important issues present
124+
- **Must provide next work steps**
125+
126+
## Items Requiring Fixes
127+
- [Specific fix details and priorities]
128+
```
129+
130+
## Command Execution Examples
131+
132+
```bash
133+
# rawsql-ts standard quality checks
134+
cd packages/core
135+
tsc --noEmit
136+
npm run lint
137+
npm test
138+
npm run build
139+
140+
# SQL processing specific tests
141+
npm test -- --grep "SelectQueryParser|SqlFormatter|JoinAggregationDecomposer"
142+
143+
# Strict type checking (as needed)
144+
tsc --noEmit --strict --noImplicitAny
145+
146+
# Performance tests (as needed)
147+
npm test -- --grep "performance|large.*query"
148+
```
149+
150+
## Error Response Guidelines
151+
152+
### SQL Processing Related Errors
153+
- Parser errors: Validate SQL syntax and provide fix suggestions
154+
- Formatter errors: Identify output format issues
155+
- Transformer errors: Analyze logical issues in AST operations
156+
157+
### Type Errors
158+
- Guide appropriate use of unknown/any types
159+
- Suggest implementation of type guard functions
160+
- Provide interface design improvement suggestions
161+
162+
### Test Failures
163+
- Verify SQL processing logic behavior
164+
- Check appropriateness of mock usage
165+
- Verify test data consistency
166+
167+
### Performance Issues
168+
- Measure processing time for large queries
169+
- Monitor memory usage
170+
- Provide optimization suggestions

‎.gitignore‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,3 @@ demo/formatter/node_modules/
175175
# Test reports
176176
reports/
177177
reports/**/*.md
178-
179-
# Claude settings
180-
.claude/

‎package-lock.json‎

Lines changed: 4 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/core/docs/decomposer_limitations.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# JOIN + Aggregation Decomposer - Edge Cases and Limitations
2+
3+
## テスト結果サマリー
4+
5+
### ✅ サポートされているケース
6+
7+
| パターン | 結果 | 詳細 |
8+
|---------|------|------|
9+
| `COUNT(*)` | ✅ 成功 | `*` をdetail CTEに含めて正常に分解 |
10+
| 基本集計関数 | ✅ 成功 | COUNT, SUM, AVG, MIN, MAX |
11+
| LEFT/RIGHT JOIN | ✅ 成功 | JOIN種別は適切に保持 |
12+
| WHERE句 | ✅ 成功 | detail CTEで条件を保持 |
13+
| 単一JOIN | ✅ 成功 | 基本的なパターンは完全対応 |
14+
| Window関数拒否 | ✅ 成功 | GROUP BYがない場合は適切に拒否 |
15+
| ハイブリッド | ⚠️ 部分対応 | GROUP BY + Window関数は動作するがWindow関数内のカラム参照は変換されない |
16+
17+
### ❌ サポートされていない/制限があるケース
18+
19+
| パターン | 結果 | エラー詳細 |
20+
|---------|------|----------|
21+
| `COUNT(DISTINCT ...)` | ❌ 失敗 | `TypeError: arg.getKind is not a function` |
22+
| 複雑な`SUM`式 | ❌ 失敗 | `SUM(p.price * p.quantity + p.tax)` でフォーマットエラー |
23+
| `CASE`文での集計 | ❌ 失敗 | `SUM(CASE WHEN ... THEN ... END)` でエラー |
24+
| 複数JOIN | 🚫 制限 | Simple版では1JOINまで（設計上の制限） |
25+
| Window関数内参照 | ⚠️ 制限 | `ROW_NUMBER() OVER (ORDER BY COUNT(p.id))` でp.idが変換されない |
26+
27+
## 詳細分析
28+
29+
### 1. COUNT(*) パターン
30+
```sql
31+
-- 元のクエリ
32+
SELECT c.category_name, COUNT(*) as total_records
33+
FROM categories c
34+
JOIN products p ON c.id = p.category_id
35+
GROUP BY c.category_name
36+
37+
-- 分解結果
38+
WITH detail_data AS (
39+
SELECT c.category_name, *
40+
FROM categories AS c
41+
JOIN products AS p ON c.id = p.category_id
42+
)
43+
SELECT category_name, COUNT(*) as total_records
44+
FROM detail_data
45+
GROUP BY category_name
46+
```
47+
48+
**✅ 正常動作**: `*` をdetail CTEに含めることで`COUNT(*)`を適切に処理
49+
50+
### 2. 複雑なSUM式パターン
51+
```sql
52+
-- 問題のあるクエリ
53+
SELECT c.category_name, SUM(p.price * p.quantity + p.tax) as total_value
54+
FROM categories c
55+
JOIN products p ON c.id = p.category_id
56+
GROUP BY c.category_name
57+
```
58+
59+
**❌ エラー**: `TypeError: arg.getKind is not a function`
60+
- SqlFormatterの内部でAST処理時にエラー
61+
- 複雑な算術式の処理に課題
62+
63+
### 3. DISTINCT集計パターン
64+
```sql
65+
-- 問題のあるクエリ
66+
SELECT c.category_name, COUNT(DISTINCT p.supplier_id) as unique_suppliers
67+
FROM categories c
68+
JOIN products p ON c.id = p.category_id
69+
GROUP BY c.category_name
70+
```
71+
72+
**❌ エラー**: 同じく`TypeError: arg.getKind is not a function`
73+
- DISTINCT句を含む集計関数の処理に課題
74+
75+
### 4. Window関数パターン
76+
```sql
77+
-- 拒否されるクエリ（期待通り）
78+
SELECT c.category_name,
79+
ROW_NUMBER() OVER (PARTITION BY c.category_name ORDER BY p.price DESC) as rank
80+
FROM categories c
81+
JOIN products p ON c.id = p.category_id
82+
```
83+
84+
**✅ 適切に拒否**: "Query does not contain GROUP BY or aggregation functions"
85+
86+
```sql
87+
-- ハイブリッドケース（部分対応）
88+
SELECT c.category_name, COUNT(p.id),
89+
ROW_NUMBER() OVER (ORDER BY COUNT(p.id) DESC) as rank
90+
FROM categories c
91+
JOIN products p ON c.id = p.category_id
92+
GROUP BY c.category_name
93+
```
94+
95+
**⚠️ 部分対応**: 動作するがWindow関数内のカラム参照は変換されない
96+
97+
#### 具体例：GROUP BY + Window関数の制限
98+
```sql
99+
-- 元のクエリ
100+
SELECT c.category_name, COUNT(p.id) as product_count,
101+
ROW_NUMBER() OVER (ORDER BY COUNT(p.id) DESC) as category_rank
102+
FROM categories c JOIN products p ON c.id = p.category_id
103+
GROUP BY c.category_name
104+
105+
-- 実際の分解結果
106+
WITH detail_data AS (
107+
SELECT c.category_name, p.id, p.price
108+
FROM categories AS c JOIN products AS p ON c.id = p.category_id
109+
)
110+
SELECT category_name, count(id) as product_count,
111+
row_number() over(order by count(p.id) desc) as category_rank -- ❌ p.id が残る
112+
FROM detail_data GROUP BY category_name
113+
114+
-- 期待される分解結果
115+
WITH detail_data AS (
116+
SELECT c.category_name, p.id, p.price
117+
FROM categories AS c JOIN products AS p ON c.id = p.category_id
118+
)
119+
SELECT category_name, count(id) as product_count,
120+
row_number() over(order by count(id) desc) as category_rank -- ✅ id に変換
121+
FROM detail_data GROUP BY category_name
122+
```
123+
124+
**❌ 問題**: Window関数内の集計関数の引数（`COUNT(p.id)`）は元テーブル参照のまま
125+
126+
## 改善提案
127+
128+
### 短期改善（現実装の修正）
129+
1. **SqlFormatterエラー修正**: `arg.getKind is not a function` エラーの解決
130+
2. **DISTINCT対応**: DISTINCT句を含む集計関数の処理改善
131+
3. **複雑式対応**: 算術式やCASE文を含む集計の処理改善
132+
133+
### 長期改善（機能拡張）
134+
1. **Advanced版活用**: 複数JOINやHAVING/ORDER BY参照置換
135+
2. **Window関数強化**: ハイブリッドケースでの参照置換
136+
3. **サブクエリ対応**: より複雑なクエリパターンへの対応
137+
138+
## 開発者向けガイドライン
139+
140+
### 現在推奨されるパターン
141+
```sql
142+
-- ✅ これは動作する
143+
SELECT table.column, COUNT(table.id), SUM(table.value), AVG(table.score)
144+
FROM table1 t1
145+
JOIN table2 t2 ON t1.id = t2.t1_id
146+
WHERE conditions
147+
GROUP BY table.column
148+
149+
-- ✅ これも動作する
150+
SELECT table.column, COUNT(*)
151+
FROM table1 t1
152+
LEFT JOIN table2 t2 ON t1.id = t2.t1_id
153+
GROUP BY table.column
154+
```
155+
156+
### 避けるべきパターン
157+
```sql
158+
-- ❌ 現在サポートされていない
159+
SELECT col, COUNT(DISTINCT other_col) -- DISTINCT
160+
SELECT col, SUM(a * b + c) -- 複雑な算術式
161+
SELECT col, SUM(CASE WHEN x THEN y END) -- CASE文
162+
```
163+
164+
### 回避策
165+
複雑な式は事前に計算カラムとして追加：
166+
```sql
167+
-- 回避策: CTE内で事前計算
168+
WITH calculated AS (
169+
SELECT *, price * quantity + tax as total_cost
170+
FROM products
171+
)
172+
SELECT category_id, SUM(total_cost)
173+
FROM categories c
174+
JOIN calculated p ON c.id = p.category_id
175+
GROUP BY category_id
176+
```
177+
178+
## まとめ
179+
180+
- **基本パターン**: 十分実用的
181+
- **複雑パターン**: 一部制限あり、改善の余地大
182+
- **エラーハンドリング**: 適切に機能
183+
- **拡張性**: Advanced版で多くの制限を解決可能

0 commit comments

Comments
 (0)