Initial commit

Hyper: a Python framework for hypermedia-driven applications.
Write templates in .hyper syntax, compile to type-safe Python.

Author: scriptogre

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: rust
+      - name: Format
+        run: cd rust && cargo fmt --check
+      - name: Lint
+        run: cd rust && cargo clippy -- -D warnings
+      - name: Test
+        run: cd rust && cargo test

.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+
+# Virtual/generated files
+*.virtual.py
+playground/templates/**/*.py
+rust/playground/
+
+# Generated .py files in test directories (only .expected.py should be tracked)
+rust/transpiler/tests/**/*.py
+!rust/transpiler/tests/**/*.expected.py
+
+# Rust build artifacts
+rust/target/
+
+# IDE
+.idea/
+*.iml
+.vscode/
+.claude/
+
+# JetBrains plugin build artifacts
+editors/jetbrains-plugin/.intellijPlatform/
+editors/jetbrains-plugin/.gradle/
+editors/jetbrains-plugin/.sandbox/
+editors/jetbrains-plugin/build/
+editors/jetbrains-plugin/src/main/gen/
+
+# Worktrees
+.worktrees/
+
+# Temp files
+*.log
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/doublify/pre-commit-rust
+    rev: v1.0
+    hooks:
+      - id: fmt

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Rust transpiler compiling `.hyper` templates to type-safe Python
+- Component model with props, slots, and `@html` decorator
+- Full Python control flow (`if`, `for`, `while`, `match`, `try`, `with`, `async`)
+- Streaming generator output
+- Content collections with Markdown, JSON, YAML, TOML support
+- JetBrains IDE plugin with Python code intelligence
+- TextMate syntax bundle

CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Hyper is a Python template framework. Write templates in `.hyper` syntax, compile to type-safe Python code.
+
+Monorepo with 3 components:
+- **Rust transpiler** (`rust/transpiler/`) — Compiles `.hyper` → `.py`
+- **Python runtime** (`python/`) — Runtime helpers, CLI, optional content collections
+- **JetBrains plugin** (`editors/jetbrains-plugin/`) — IDE support via language injection
+
+## Build and Test Commands
+
+```bash
+# Transpiler
+just build transpiler          # Release build
+just test transpiler           # Run all tests (or: cd rust && cargo test)
+just compile <files-or-dirs>   # Build + run in one step (debug, suppresses warnings)
+just test-accept               # Regenerate all .expected.* files from current output
+just test-accept basic         # Regenerate only files matching "basic"
+
+# Plugin
+just build plugin              # Build transpiler + bundle binary + build plugin
+just run plugin                # Launch sandbox IDE
+just test plugin               # Run plugin tests
+
+# Python
+uv sync                        # Setup workspace
+pytest                         # Run Python tests
+
+# Generate .py from .hyper (uses release binary)
+just generate <files>
+```
+
+The `compile` recipe accepts directories — it walks them for `.hyper` files.
+
+## Transpiler Architecture
+
+Three-stage pipeline in `rust/transpiler/src/lib.rs`:
+
+1. **Parser** (`parser/`) — `tokenizer.rs` lexes into tokens, `tree_builder.rs` builds AST. Line-based tokenizer with `after_structural` flag for comment detection, `is_control_flow()` requiring trailing `:` to distinguish Python keywords from content text.
+
+2. **Transformer** (`transform/`) — Visitor-pattern plugins (`HelperDetectionPlugin`, `AsyncDetectionPlugin`, `SlotDetectionPlugin`) analyze the AST and produce `TransformMetadata`.
+
+3. **Generator** (`generate/`) — `python.rs` combines consecutive text/expression/element nodes into single f-strings, emits control flow as separate statements. `injection_analyzer.rs` produces IDE language injection ranges. `output.rs` tracks source positions with UTF-16 mapping.
+
+### Compile-time HTML validation (`html.rs` + `tree_builder.rs`)
+
+The parser validates HTML at parse time:
+- **Void elements** — `<br>`, `<img>`, etc. cannot have children or closing tags
+- **Duplicate attributes** — Same attribute name twice on one element
+- **Invalid nesting** — Block elements inside `<p>`, nested interactive elements (`<a>` inside `<button>`)
+
+Validation uses an `element_stack` in `TreeBuilder` for parent context.
+
+### Error system (`error.rs`)
+
+`ParseError` renders with ANSI colors when stderr is a TTY:
+- `render()` — plain text (for piped output, tests)
+- `render_color()` — colored (red errors, blue line numbers, cyan related spans, yellow help)
+- `Display` impl outputs just the message (no redundant kind prefix)
+- Errors support `related_span` with custom `related_label` and multiline `help` text
+
+## Testing
+
+**Expected output tests** (`rust/transpiler/tests/expected_tests.rs`):
+- Test files: `rust/transpiler/tests/<category>/<name>.hyper`
+- Expected output: `<name>.expected.py` (compiled Python), `<name>.expected.json` (injection ranges/injections), `<name>.expected.err` (error messages)
+- Error tests live in `tests/errors/` and are auto-detected
+
+**Expected output workflow:**
+```bash
+cargo test                              # Run tests, see failures
+cargo run --bin accept_expected         # Regenerate all .expected.* files from current compiler output
+cargo run --bin accept_expected basic   # Regenerate only files matching "basic"
+```
+
+**IMPORTANT — expected output review:** `cargo run --bin accept_expected` blindly stamps the compiler's current output as correct. Never run it after a change without manually reviewing the diffs (`git diff`) to confirm the new output is actually what you expect. A bug in the compiler will silently become the blessed expected output otherwise. When changing parser or codegen logic, always spot-check at least the directly affected `.expected.py` and `.expected.json` files before considering the change done.
+
+**CRITICAL — injection range validation:** Every Python injection range `source[start:end]` must extract to meaningful text from the source file (not mid-word garbage). After accepting expected output, verify that source positions in `.expected.json` files map to the correct source text. The test suite includes semantic validation (range text extraction checks) — if these fail, the ranges are wrong, do NOT blindly accept. Common mistakes: off-by-one in span calculations, stale expected files accepted without review, substring-matching tests that pass accidentally.
+
+**Invariant tests** (`rust/transpiler/tests/invariants/`):
+- Property-based checks that run across ALL `.hyper` test files automatically
+- Each module validates one structural invariant (roundtrip, monotonicity, bounds, html_completeness, etc.)
+- New invariants go in their own module file under `invariants/`
+- Adding a new `.hyper` test file automatically gets invariant coverage with zero extra work
+
+**Kitchen sink smoke test** (`tests/basic/kitchen_sink.hyper`):
+- Exercises every syntax construct in one file (elements, components, slots, control flow, decorators, attributes, expressions, comments)
+- After any injection change, open this file in JetBrains and visually verify highlighting
+- All 8 invariants run against it automatically
+
+## CLI Modes (`main.rs`)
+
+- `hyper generate <files|dirs>` — Compile to `.py` files, walks directories
+- `hyper generate --stdin` — Read from stdin, write to stdout
+- `hyper generate --json` — JSON output with source mappings
+- `hyper generate --daemon` — Length-prefixed JSON protocol for IDE integration
+
+## Gotchas
+
+- Transpiler binary must be rebuilt and re-bundled for plugin changes: `just build`
+- Plugin requires JDK 17+
+- Expected output files (`.expected.py`, `.expected.json`, `.expected.err`) are managed by `cargo run --bin accept_expected` — never edit them by hand
+- The tokenizer is line-based; multiline Python expressions (paren/bracket spanning lines) are a known limitation
+- `is_control_flow()` uses trailing `:` heuristic — content text that starts with a Python keyword and ends with `:` inside an element is an edge case
+
+## Bug Fix Workflow
+
+When the user reports a bug, visual issue, or incorrect behavior — especially phrases like "not highlighted", "looks wrong", "should be X but is Y", "missing", "broken" — invoke the `/red-green-fix` skill before making any code changes. Never fix a bug without first writing a failing test that captures the expected behavior.
+

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+## Prerequisites
+
+- [Rust toolchain](https://rustup.rs/)
+- [uv](https://docs.astral.sh/uv/)
+- [just](https://github.com/casey/just)
+- JDK 17+ (only for JetBrains plugin work)
+
+## Setup
+
+```bash
+git clone https://github.com/scriptogre/hyper.git
+cd hyper
+uv sync
+just build transpiler
+```
+
+## Running Tests
+
+```bash
+just test transpiler    # Rust transpiler tests
+pytest                  # Python runtime tests
+just test plugin        # JetBrains plugin tests
+```
+
+## Linting
+
+```bash
+cd rust && cargo fmt --check
+cd rust && cargo clippy -- -D warnings
+```

Justfile

@@ -0,0 +1,119 @@
+# Default: build transpiler, bundle it in plugin, and build plugin
+default: build
+
+# Build transpiler
+build-transpiler:
+    cd {{justfile_directory()}}/rust && cargo build --release
+
+# Build plugin (always rebuilds + bundles transpiler first)
+build-plugin: build-transpiler _bundle
+    #!/usr/bin/env bash
+    set -e
+    ROOT="{{justfile_directory()}}"
+    echo "Building JetBrains plugin..."
+    cd "$ROOT/editors/jetbrains-plugin" && ./gradlew clean buildPlugin
+    cp "$ROOT/editors/jetbrains-plugin/build/distributions"/*.zip "$ROOT/editors/jetbrains-plugin/hyper-plugin.zip"
+    echo ""
+    echo "✅ Plugin built!"
+    echo "📦 Install: editors/jetbrains-plugin/hyper-plugin.zip"
+
+# Build everything (or a specific target)
+build target="":
+    #!/usr/bin/env bash
+    set -e
+    case "{{target}}" in
+        transpiler) just build-transpiler ;;
+        plugin)     just build-plugin ;;
+        "")         just build-transpiler && just _bundle && just build-plugin ;;
+        *)          echo "Usage: just build [transpiler|plugin]"; exit 1 ;;
+    esac
+
+# Run transpiler or plugin
+run target *args:
+    #!/usr/bin/env bash
+    set -e
+    ROOT="{{justfile_directory()}}"
+
+    case "{{target}}" in
+        transpiler)
+            "$ROOT/rust/target/release/hyper" {{args}}
+            ;;
+        plugin)
+            just build-plugin
+            cd "$ROOT/editors/jetbrains-plugin" && ./gradlew runIde
+            ;;
+        *)
+            echo "Usage: just run [transpiler|plugin] [args...]"
+            exit 1
+            ;;
+    esac
+
+# Test transpiler or plugin
+test target:
+    #!/usr/bin/env bash
+    set -e
+    ROOT="{{justfile_directory()}}"
+
+    case "{{target}}" in
+        transpiler)
+            cd "$ROOT/rust" && cargo test
+            ;;
+        plugin)
+            echo "Building transpiler (debug)..."
+            cd "$ROOT/rust" && cargo build -q
+            cd "$ROOT/editors/jetbrains-plugin" && ./gradlew test
+            ;;
+        *)
+            echo "Usage: just test [transpiler|plugin]"
+            exit 1
+            ;;
+    esac
+
+# Update all expected test files from current transpiler output
+test-accept *filter:
+    cd {{justfile_directory()}}/rust/transpiler && cargo run --example accept_expected -- {{filter}}
+
+# Show diff between expected and actual transpiler output
+test-diff *filter:
+    #!/usr/bin/env bash
+    cd "{{justfile_directory()}}/rust" && cargo test --test expected_tests 2>&1 | head -100
+
+# Run expected tests only (faster than full test suite)
+test-expected:
+    cd {{justfile_directory()}}/rust && cargo test --test expected_tests
+
+# Bundle transpiler binary into plugin resources (internal helper)
+_bundle:
+    #!/usr/bin/env bash
+    set -e
+    ROOT="{{justfile_directory()}}"
+
+    # Detect platform
+    OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+    ARCH=$(uname -m)
+    case "$OS" in
+        darwin) OS_NAME="darwin" ;;
+        linux)  OS_NAME="linux" ;;
+        *)      OS_NAME="$OS" ;;
+    esac
+    case "$ARCH" in
+        arm64|aarch64) ARCH_NAME="arm64" ;;
+        x86_64|amd64)  ARCH_NAME="x64" ;;
+        *)             ARCH_NAME="$ARCH" ;;
+    esac
+
+    BINARY_NAME="hyper-${OS_NAME}-${ARCH_NAME}"
+    SRC="$ROOT/rust/target/release/hyper"
+    DEST="$ROOT/editors/jetbrains-plugin/src/main/resources/bin/${BINARY_NAME}"
+
+    mkdir -p "$(dirname "$DEST")"
+    cp "$SRC" "$DEST"
+    echo "✓ Bundled: $DEST"
+
+# Generate Python from .hyper files
+generate *files:
+    {{justfile_directory()}}/rust/target/release/hyper generate {{files}}
+
+# Compile .hyper file(s) (build + run, for quick iteration)
+compile *files:
+    cd {{justfile_directory()}}/rust && RUSTFLAGS="-Awarnings" cargo run -q -- generate {{files}}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hyper contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.