spice

Build the Spice compiler (`spice`) and/or the test runner (`spicetest`) with CMake/Ninja. Use when the user wants to compile/rebuild the project, build a specific target, produce a release/debug build, or set up the CMake build directory before running or testing.

Guidelines for contributing changes to the Spice GitHub repository — branch naming conventions, commit message format, PR workflow, no-push-to-main rule, and quality gates. Use when preparing a branch for review, writing a commit, opening a PR, or checking that a contribution is ready to merge.

Profile and benchmark the Spice compiler (the host C++ `spice` program) and the native binaries it emits from `.spice` files — using the built-in per-stage timers, the dedicated CMake profiling build options, and external tools (perf, valgrind/callgrind, flamegraph, hyperfine). Covers the preferred build/compile settings for representative profiling of each layer. Use when the user wants to find where compile time or runtime is spent, benchmark a change, or chase a performance regression.

Find, diagnose, and fix bugs in the Spice compiler or in a compiled Spice program using GDB, objdump, sanitizers (for both the host C++ compiler and the emitted Spice program via the built-in `--sanitizer` flag), the compiler dump flags, and valgrind. Use when investigating a crash, miscompilation, memory error, or undefined behavior, or when triaging a failing test. Whenever a bug is fixed, this skill also requires extending or adding a test that covers the problematic code path and any related uncovered paths.

Add a reference/integration test case under test/test-files for the Spice compiler. Covers the directory layout (flat vs grouped suites), the exact reference filenames the runner compares against, control/skip marker files, platform-specific variants, and the --update-refs workflow to generate expected output. Use when adding or modifying compiler test cases.

Orientation map of the Spice compiler codebase — the compilation pipeline (lexer → parser → CST → AST → import collector → symbol table → type checker → IR generator → optimizer → object emitter → linker), the key class/file for each stage, and the SourceFile orchestration sequence. Use when navigating the compiler, deciding where a change belongs, or understanding how a stage feeds the next.

Locate or add a Spice compiler diagnostic — errors (semantic, parser, lexer, compiler-internal, linker, CLI) and warnings. Covers the exception classes in src/exception, the message tables, how to throw a diagnostic from a pass, the warning mechanism, and the matching test convention (exception.out / warning.out). Use when adding a new error/warning or tracking down where a message comes from.

End-to-end recipe for adding or changing a Spice language construct — edit the ANTLR grammar (Spice.g4), rebuild to regenerate the parser, add/extend an AST node and its visitor method, then thread the construct through ASTBuilder, SymbolTableBuilder, TypeChecker and IRGenerator, and add tests. Use when implementing new syntax/semantics in the compiler.

Dump compiler intermediate output (LLVM IR, assembly, AST, CST, symbol table, types) for a Spice source or test-input file using the `spice` CLI dump flags. Use when the user wants to inspect what the compiler generates for a `.spice` file, debug codegen, or regenerate reference dumps.

Compile and/or run a Spice program with the `spice` CLI — build to an executable, run a file directly, run with a sanitizer, run its enclosed tests, or cross-compile. Use when the user wants to execute a `.spice` file or produce a binary from one.

Run the Spice `spicetest` suite (GoogleTest-based integration + unit tests). Use when the user wants to run all tests, a specific suite or case, update reference files, check for memory leaks with valgrind, or debug a failing test.