storybook/.claude/CLAUDE.md

# Storybook Project - Claude Code Instructions

## Commit Policy (CRITICAL - NEVER BYPASS)

These rules are **MANDATORY** for all commits:

1. **All tests must pass** - Run `cargo test` and verify 0 failures before every commit
2. **All new code must have tests** - No exceptions, no untested code allowed
3. **No unused variables or dead code** - Clean up unused code, don't suppress warnings with underscore prefixes
4. **Commit frequently** at logical milestones
5. **Never use `--no-verify`** flag to bypass pre-commit hooks

## Development Workflow

### Cleaning Build Artifacts

To clean all build artifacts across the entire workspace:

```bash
cargo xtask clean
```

This removes:
- Rust build artifacts (`target/`, `Cargo.lock`)
- tree-sitter node_modules and build output
- Zed extension build artifacts (`grammars/`, `extension.wasm`)
- mdbook build artifacts (`docs/book/`)

### Installing the LSP

To reinstall/update the Storybook LSP after making changes:

```bash
cargo install --path . --bin storybook-lsp --force
```

The LSP binary is installed to `~/.cargo/bin/storybook-lsp`. The Zed extension will automatically find it if `~/.cargo/bin` is in your PATH.

### Installing the Zed Extension

To rebuild and install the Zed extension after making changes:

```bash
cd zed-storybook
./build-extension.sh
```

Then in Zed:
1. `Cmd+Shift+P` → "zed: install dev extension"
2. Select: `/Users/sienna/Development/storybook/zed-storybook`

**Updating tree-sitter grammar:**
When the grammar changes, update `zed-storybook/extension.toml` and change the `rev` field under `[grammars.storybook]` to the new commit SHA or branch name.

## Git Workflow

Development happens directly on `mainline` until the language is stable. Releases are tagged with version numbers (e.g., `v0.2.0`). Branches are only used for external contributors or later development phases.

Pre-commit hooks check: trailing whitespace, rustfmt, clippy.

### Commit Message Guidelines

Keep commit messages clean and focused:

- **DO**: Use conventional commit format (e.g., `feat(lexer):`, `fix(parser):`, `docs:`)
- **DO**: Write clear, concise descriptions of what changed and why
- **DON'T**: Include attribution (no "Co-Authored-By")
- **DON'T**: Include test status (e.g., "all tests pass")
- **DON'T**: Include sprint/milestone markers
- **DON'T**: Include version markers (e.g., "Part of v0.3.0")

Example:
```
feat(lexer): add type system keywords

Added four keywords for new type system:
- concept: Base type definition
- sub_concept: Enum/record sub-type definition
- definition: Compile-time enum mapping
- any: Universal type for dynamic contexts
```

## Project Structure

- `src/` - Core Storybook compiler and runtime
- `tree-sitter-storybook/` - Tree-sitter grammar for Storybook DSL
- `zed-storybook/` - Zed editor extension
- `storybook-editor/` - LSP server implementation
- `docs/` - Specifications and documentation
  - `SBIR-v0.2.0-SPEC.md` - Storybook Intermediate Representation binary format
- `.claude/tmp` - Unlimited storage for temporary files. Use this for plans, reports, and other temporary data that is not part of the repository.

## Debugging Protocol

When debugging fails after 2 attempts, stop and enter plan mode. Explain your current hypothesis, what you've tried, and propose next steps before making more changes. Do not blame caching or environment without evidence.

## Project-Specific: Zed Extension

For Zed extension work: the compiled grammar is cached and `highlights.scm` must be bundled correctly. Never delete local query files assuming Zed will fall back to fetched ones. Always verify the extension builds and loads before declaring success.

## Testing Philosophy

- Every feature needs tests
- Every bug fix needs a regression test
- Tests must pass before commits
- Use `cargo test --lib` to run unit tests
- Use `cargo test` to run all tests including integration tests