Skip to content

Latest commit

 

History

History
56 lines (36 loc) · 1.86 KB

CLAUDE.md

File metadata and controls

56 lines (36 loc) · 1.86 KB

Claude Development Guide

Next Steps

To find the next explain test to work on (fewest pending statements first), run:

go run ./cmd/next-test

This finds tests with explain_todo entries in their metadata.

Running Tests

Always run parser tests with a 30 second timeout:

go test ./parser/... -timeout 30s

The tests are fast but some test files have many statements. If a test is timing out, it may indicate a bug (likely an infinite loop in the parser).

Checking for Newly Passing Explain Tests

IMPORTANT: After implementing parser/explain changes, ALWAYS run check-explain to update metadata files:

go test ./parser/... -check-explain -v 2>&1 | grep "EXPLAIN PASSES NOW"

This command:

  1. Runs all explain tests including those in explain_todo
  2. Automatically updates metadata.json files to remove passing statements from explain_todo
  3. Reports which tests now pass

You must run this after every change to parser or explain code, then commit the updated metadata.json files along with your code changes.

Test Structure

Each test in parser/testdata/ contains:

  • metadata.json - {} for enabled tests
  • query.sql - ClickHouse SQL to parse
  • explain.txt - Expected EXPLAIN AST output (matches ClickHouse's format)
  • explain_N.txt - Expected EXPLAIN AST output for Nth statement (N >= 2)

Metadata Options

  • explain_todo: {"stmt2": true} - Skip specific statement subtests
  • skip: true - Skip test entirely (e.g., causes infinite loop)
  • explain: false - Skip test (e.g., ClickHouse couldn't parse it)
  • parse_error: true - Query is intentionally invalid SQL

Important Rules

NEVER modify explain.txt files - These are golden files containing the expected output from ClickHouse. If tests fail due to output mismatches, fix the Go code to match the expected output, not the other way around.