storybook/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

Installing the LSP

To reinstall/update the Storybook LSP after making changes:

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:

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 main 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
- concept_comparison: 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

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