Skip to content

CLAUDE.md

Latest commit

 

History

History
92 lines (66 loc) · 3.11 KB

CLAUDE.md

File metadata and controls

92 lines (66 loc) · 3.11 KB

Claude Development Guide

Next Steps

To find the next test to work on, run:

go run ./cmd/next-test

This tool finds all tests with todo: true in their metadata and returns the one with the shortest query.sql file.

Workflow

  1. Run go run ./cmd/next-test to find the next test to implement
  2. Check the test's query.sql to understand what SQL needs parsing
  3. Check the test's ast.json to understand the expected output format
  4. Implement the necessary AST types in ast/
  5. Add parser logic in parser/parser.go
  6. Add JSON marshaling functions in parser/parser.go
  7. Run go test ./parser/... -check-todo -v to auto-enable passing todo tests
  8. Run go test ./parser/... to verify all enabled tests pass

Checking for Newly Passing Todo Tests

After implementing parser changes, run:

go test ./parser/... -check-todo -v

This runs todo tests and automatically updates metadata.json for any tests that now pass (removes the todo: true flag). Look for "ENABLED:" in the output to see which tests were updated.

Test Structure

Each test in parser/testdata/ contains:

  • metadata.json - {} for enabled tests, {"todo": true} for pending tests, or {"invalid_syntax": true} for tests with invalid SQL
  • query.sql - T-SQL to parse
  • ast.json - Expected AST output

Important Rules

  • NEVER modify ast.json files - These are golden files containing the expected output. If tests fail due to JSON mismatches, fix the Go code to match the expected output, not the other way around.

Generating ast.json with TsqlAstParser

The TsqlAstParser/ directory contains a C# tool that generates ast.json files using Microsoft's official T-SQL parser (ScriptDom).

Prerequisites

  1. Install .NET 8.0 SDK:

    curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 8.0 --install-dir ~/.dotnet

  2. Download the NuGet package (if packages/ directory is empty):

    mkdir -p packages
curl -L -o packages/microsoft.sqlserver.transactsql.scriptdom.170.128.0.nupkg \
  "https://api.nuget.org/v3-flatcontainer/microsoft.sqlserver.transactsql.scriptdom/170.128.0/microsoft.sqlserver.transactsql.scriptdom.170.128.0.nupkg"

  3. Build the tool:

    ~/.dotnet/dotnet build TsqlAstParser -c Release

Usage

Generate ast.json for a single test:

~/.dotnet/dotnet run --project TsqlAstParser -c Release -- parser/testdata/TestName/query.sql parser/testdata/TestName/ast.json

Generate ast.json for all tests missing it:

for dir in parser/testdata/*/; do
  if [ -f "$dir/query.sql" ] && [ ! -f "$dir/ast.json" ]; then
    ~/.dotnet/dotnet run --project TsqlAstParser -c Release -- "$dir/query.sql" "$dir/ast.json"
  fi
done

Limitations

TsqlAstParser uses TSql160Parser (SQL Server 2022) and cannot parse:

  • SQL Server 170+ features (VECTOR indexes, AI functions, JSON enhancements)
  • Fabric DW-specific syntax (CLONE TABLE, CLUSTER BY)
  • Deprecated syntax removed in newer versions
  • Intentionally invalid SQL (error test cases)

Tests for unsupported syntax will not have ast.json files generated.