If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kaleidawave/ezno shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 7w ago
• 18 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 60% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kaleidawave/ezno repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kaleidawave/ezno.

What it runs against: a local clone of kaleidawave/ezno — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kaleidawave/ezno | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 82 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kaleidawave/ezno. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kaleidawave/ezno.git
#   cd ezno
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kaleidawave/ezno and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kaleidawave/ezno(\\.git)?\\b" \\
  && ok "origin remote is kaleidawave/ezno" \\
  || miss "origin remote is not kaleidawave/ezno (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "checker/src/lib.rs" \\
  && ok "checker/src/lib.rs" \\
  || miss "missing critical file: checker/src/lib.rs"
test -f "checker/src/synthesis/mod.rs" \\
  && ok "checker/src/synthesis/mod.rs" \\
  || miss "missing critical file: checker/src/synthesis/mod.rs"
test -f "checker/src/context/mod.rs" \\
  && ok "checker/src/context/mod.rs" \\
  || miss "missing critical file: checker/src/context/mod.rs"
test -f "checker/src/types/calling.rs" \\
  && ok "checker/src/types/calling.rs" \\
  || miss "missing critical file: checker/src/types/calling.rs"
test -f "checker/src/features/mod.rs" \\
  && ok "checker/src/features/mod.rs" \\
  || miss "missing critical file: checker/src/features/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 82 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~52d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kaleidawave/ezno"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Ezno is a Rust-based TypeScript type checker and compiler designed for correctness and speed, written from scratch rather than as an extension of tsc. It performs imperative type system analysis that evaluates side effects and control flow like an interpreter, guaranteeing no runtime TypeErrors (when definitions are sound) and aiming for soundness over permissiveness—a fundamental departure from TypeScript's gradual typing approach. Monorepo with root Cargo.toml managing two core crates: parser/ (JavaScript/TypeScript parsing with derive macro, generator, visitable-derive) and checker/ (type checking logic with definitions, examples, fuzz tests, and internal serialization). Root src/lib.rs and src/main.rs expose the checker as both WASM library and CLI binary. Checker contains extensive documentation in checker/documentation/ covering architecture, inference, functions, and parameters.

TypeScript developers and language researchers who want stricter static analysis than tsc provides, and contributors interested in type system design and compiler optimization. Also targets projects willing to adopt a more conservative type checker that may reject valid-but-unsafe tsc programs.

Actively developed but deliberately experimental and incomplete. The README explicitly warns that Ezno 'does not currently support enough features to check existing projects' and links to blocking issues. CI is comprehensive (Rust, performance, fuzz testing, deployment workflows present). However, as v0.0.23 with a 1.6M LOC Rust codebase, it's a serious research project, not production-ready for general TypeScript codebases.

Single maintainer (kaleidawave, Ben) with 1.6M lines of Rust code to maintain. Breaking changes are likely given the 'active development' and experimental nature. Dependency risk is moderate—uses stable Rust crates like serde, codespan-reporting, and notify, but tight coupling to custom ezno-parser and ezno-checker packages. The WASM target (cdylib) adds platform-specific maintenance burden.

Core type checking logic is being extended (see checker/specification/to_implement.md and checker/specification/staging.md). The project has active GitHub workflows for performance benchmarking, continuous deployment to a playground, and fuzzing. LSP support is planned but not yet integrated (lsp/server is commented out in Cargo.toml). Binary serialization and caching features are being developed (see checker/binary-serialize-derive/).

git clone https://github.com/kaleidawave/ezno.git
cd ezno
cargo build --release
./target/release/ezno --help

For development, install Rust (1.70+), then cargo check and cargo test from the root directory.

Daily commands: For CLI: cargo run --release -- <file.ts> or direct ./target/release/ezno <file.ts>. For dev: cargo check or cargo test. For WASM playground (deployed via workflows): built and deployed automatically. Use bacon.toml for watch-mode: bacon check or bacon test.

• checker/src/lib.rs — Main library entry point; defines the public API for the type checker and orchestrates the analysis pipeline
• checker/src/synthesis/mod.rs — Core synthesis module that converts parsed AST into typed intermediate representation; handles statement and expression analysis
• checker/src/context/mod.rs — Environment and control-flow context management; tracks variable bindings, function scopes, and type narrowing state
• checker/src/types/calling.rs — Function call type resolution and argument checking; implements the calling convention for generic and overloaded functions
• checker/src/features/mod.rs — Feature modules dispatcher; coordinates language feature handling (assignments, conditionals, functions, modules, etc.)
• checker/src/context/environment.rs — Variable and binding resolution with scope chain; critical for type lookup and environment tracking during checking
• parser/src/lib.rs — Parser library entry; tokenizes and parses TypeScript/JavaScript into AST for consumption by the checker

Add a new language feature check

1. Create a new module in checker/src/features/ (e.g., features/async_await.rs) to handle the feature's type rules (checker/src/features/mod.rs)
2. Implement feature-specific synthesis logic by adding a function that takes a Context and AST node, returning a Type (checker/src/features/async_await.rs)
3. Wire the feature handler into the main synthesis dispatcher in checker/src/synthesis/statements_and_declarations.rs or checker/src/synthesis/expressions.rs (checker/src/synthesis/statements_and_declarations.rs)
4. Add diagnostic messages in checker/src/diagnostics.rs for type errors specific to the feature (checker/src/diagnostics.rs)
5. Write test cases in the specification or examples to document expected behavior (checker/specification/specification.md)

Extend type system with new built-in types or operations

1. Define the new type representation in checker/src/types/ (e.g., types/promise.rs for Promise types) (checker/src/types/functions.rs)
2. Implement subtyping rules in checker/src/types/disjoint.rs or a dedicated file to handle variance and assignability (checker/src/types/disjoint.rs)
3. Add operation handling in checker/src/features/operations/ (e.g., operations/async_operations.rs) for type-level operations (checker/src/features/operations/mod.rs)
4. Update type_mappings.rs to include mappings for the new type in built-in definitions (checker/src/type_mappings.rs)

Add support for a new standard library or type definitions

1. Create a new .d.ts definition file in checker/definitions/ (e.g., definitions/dom.d.ts) with type declarations (checker/definitions/simple.d.ts)
2. Register the definitions in the root context loading logic in checker/src/context/root.rs (checker/src/context/root.rs)
3. If type mappings are needed, add them to checker/src/type_mappings.rs to map runtime values to their types (checker/src/type_mappings.rs)
4. Test definition loading by creating examples in checker/examples/ to verify types are accessible (checker/examples/run_checker.rs)

Improve type narrowing and control-flow analysis

1. Extend control-flow tracking in checker/src/context/control_flow.rs to track new narrowing conditions (checker/src/context/control_flow.rs)
2. Update the narrowing feature in checker/src/features/narrowing.rs to apply type guards and refinements (checker/src/features/narrowing.rs)
3. Modify conditional feature handling in checker/src/features/conditional.rs to propagate narrowed types along branches (checker/src/features/conditional.rs)
4. Add tests in checker/specification/specification.md documenting the narrowing behavior (checker/specification/specification.md)

• Rust — Provides memory safety, zero-cost abstractions, and performance required for a high-speed type checker with guaranteed soundness guarantees
• Imperative type system with side-effect tracking — Enables sound type checking by evaluating control flow and function side effects similar to an interpreter, ensuring no runtime TypeErrors escape
• Binary serialization for type cache — Allows fast incremental checking by caching computed type information across invocations without re-parsing or re-checking unchanged files
• AST-based synthesis approach — Provides precise type-level information about source code structure for advanced features like control-flow narrowing and type guards

• No support for existing projects yet (experimental, blocking issues)

  • Why: Prioritizes correctness and soundness over feature completeness; allows iterative refinement of the type system and feature set
  • Consequence: Limited adoption and testing on real-world codebases; users must accept incomplete TypeScript/JavaScript support

• Imperative type system that simulates execution with types instead of values

  • Why: Enables sound, exhaustive type checking and detection of runtime errors at compile time
  • Consequence: Higher compilation overhead and complexity compared to traditional structural type checkers; some advanced patterns may be difficult to type

• Monolithic checker crate with feature-specific modules rather than plugin architecture

  • Why: Simplifies integration and allows tight control over soundness; no need for external plugin contracts
  • Consequence: Adding new features requires modifying core codebase; scaling to large number of features may become unwieldy

• Type definitions in .d.ts and overrides files rather than automatic inference from JavaScript

  • Why: undefined
  • Consequence: undefined

No production support: Project explicitly states it doesn't handle existing TypeScript codebases. Single source of truth for types: the checker binary serialization format (internal.ts.d.bin) is custom and versioned; breaking it invalidates caches. WASM build requires target setup: rustup target add wasm32-unknown-unknown needed for browser builds. Definition files are critical: Ezno's 'soundness guarantee' depends entirely on definition files in checker/definitions/ being correct (see README caveat: 'as long as definitions are sound'). LSP not ready: Don't expect IDE integration yet. Fuzzing targets are in-tree: fuzz tests may catch regressions not in regular cargo test.

• Imperative Type Inference — Ezno's core differentiator: unlike declarative type systems, it evaluates type side effects and control flow like an interpreter, enabling soundness guarantees and better type narrowing that tsc cannot achieve
• Abstract Interpretation — The theoretical foundation for Ezno's approach: it tracks type values instead of concrete values, allowing the checker to reason about all possible executions without running code
• Soundness (Type Theory) — Ezno explicitly targets soundness (no undetected TypeErrors at runtime) over permissiveness; understanding this design goal is essential to predict which valid-tsc programs it may reject
• Type Narrowing & Control Flow Analysis — Critical feature documented in checker/documentation/checking.md; Ezno tracks how types change through conditionals and guards more precisely than tsc via imperative evaluation
• Binary Serialization for Type Caches — The binary-serialize-derive/ crate enables Ezno to serialize and reuse type information across runs; essential for performance on large codebases and incremental checking
• Visitor Pattern (AST Traversal) — Used throughout parser and checker (visitable-derive crate) for walking AST nodes; understanding this pattern is key to modifying type checking or parsing logic
• Event-Based Side Effect Representation — Instead of eager evaluation, Ezno represents side effects as events (documented in checker/documentation/events.md); this enables better analysis and potential future lower-level compilation targets

• microsoft/TypeScript — The reference implementation Ezno compares itself against; provides the language spec and comparison baseline at kaleidawave.github.io/ezno/comparison
• swc-rs/swc — Rust-based JavaScript/TypeScript transpiler with similar toolchain goals (speed, correctness) but focuses on compilation rather than type soundness guarantees
• denoland/deno — Runtime that integrates TypeScript checking; potential integration target for Ezno once feature parity improves
• rome/rome — Rust-based JavaScript toolchain (linter, formatter) with overlapping ecosystem goals of displacing Node.js tooling with faster alternatives
• kaleidawave/source-map — Companion utility by the same author; used for source map generation in Ezno's compiler output

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test suite for checker/src/features/modules.rs

The modules.rs file handles one of the most complex features (module resolution and imports), but there are no visible test files in checker/fuzz or checker/examples specifically targeting module system edge cases. This is critical for a type checker since incorrect module handling can silently pass wrong types across file boundaries. New contributors can add integration tests for: circular dependencies, re-exports, namespace imports, and type-only imports.

• [ ] Create checker/tests/modules/ directory with test structure
• [ ] Add test cases for circular module dependencies in checker/tests/modules/circular.rs
• [ ] Add test cases for re-export scenarios in checker/tests/modules/reexports.rs
• [ ] Add test cases for namespace and type-only imports in checker/tests/modules/import_variants.rs
• [ ] Wire tests into Cargo.toml and verify they run via cargo test in the checker workspace

Implement missing CI workflow for WASM target builds

The Cargo.toml shows cdylib/rlib crate-types for WASM support and wasm-bindgen dependencies, but there's no dedicated GitHub Actions workflow to verify WASM builds don't break. The existing workflows (rust.yml, publish.yml) don't include --target wasm32-unknown-unknown builds. This catches regressions early and ensures the playground deployment doesn't silently receive broken builds.

• [ ] Create .github/workflows/wasm-build.yml workflow file
• [ ] Add job to install wasm-pack target using rustup target add wasm32-unknown-unknown
• [ ] Add build step: cargo build --target wasm32-unknown-unknown --release from root and checker workspace
• [ ] Add optional wasm-pack build step to verify playground bundle compatibility
• [ ] Trigger on pull requests and main branch pushes to src/ and Cargo.toml changes

Add documentation for checker/src/context/control_flow.rs architecture

Control flow analysis is critical for type narrowing (e.g., type guards, exhaustiveness checking), but checker/documentation/ lacks a dedicated file explaining how control_flow.rs works. The existing documentation has inference.md, functions.md, and checking.md but no control_flow_analysis.md. This is a barrier for contributors wanting to improve narrowing or add new control flow features.

• [ ] Create checker/documentation/control-flow.md explaining the data structures in context/control_flow.rs
• [ ] Document the purpose of control flow graph representation with at least 2 code examples showing type narrowing
• [ ] Explain how control_flow.rs integrates with environment.rs for variable type tracking
• [ ] Add a section on limitations and TODOs (reference specification/staging.md for in-progress features)
• [ ] Link the new file from checker/documentation/getting-started.md and README.md

• Add type checking support for the async keyword in function parameters and return types. See checker/specification/staging.md to confirm it's listed as TODO, then add test cases to checker/examples/run_checker.rs and implement inference in checker/src/context/. Look at how Promise<T> is already handled for patterns.
• Expand the definitions in checker/definitions/overrides.d.ts to include missing standard library type stubs (e.g., Array.prototype methods like .flatMap, .at). Cross-reference against the specification at checker/specification/specification.md to see what's not yet typed, then add stubs following the existing pattern.
• Write a new fuzzing target in checker/fuzz/fuzz_targets/ that generates random but valid TypeScript and checks that the checker doesn't panic. Use the existing check_project_naive.rs as a template. This improves robustness without requiring deep type system knowledge and is marked as a 'good-first-issue' in the GitHub repo.

The Ezno TypeScript type checker codebase demonstrates reasonable security practices as a compiler/type-checker project. Primary concerns are around dependency management and the planning for future LSP server functionality. No hardcoded credentials, SQL injection, or XSS vulnerabilities are evident in the visible structure. The project is Rust-based, which provides memory safety benefits. Key recommendations include: (1) Implementing automated dependency scanning via cargo-audit in CI/CD, (2) Completing the WASM dependency specification, (3) Creating a security policy, and (4) Pre-planning security controls for the upcoming LSP server feature. The relatively small external dependency footprint is a positive indicator.

• Medium · Outdated Dependencies with Known Vulnerabilities — Cargo.toml, [dependencies] section. The codebase uses several dependencies that may have known security vulnerabilities. Specifically: base64 0.22, serde_json 1.0, and other older versions. While these are not inherently vulnerable, the lack of a comprehensive dependency audit and update strategy increases risk. The notify crate (8.x) and notify-debouncer-full (0.5.x) are also relatively old. Fix: Regularly run 'cargo audit' to identify known vulnerabilities. Update dependencies to their latest secure versions. Implement automated dependency scanning in CI/CD pipelines (e.g., via GitHub Dependabot).
• Medium · Incomplete WASM Dependency Configuration — Cargo.toml, [target.'cfg(target_family = "wasm")'.dependencies] section. The wasm-bindgen dependency in the WASM target configuration is incomplete (missing version specification). This could lead to unpredictable builds and potential security issues if an unexpected version is pulled. Fix: Complete the wasm-bindgen dependency specification with an explicit version constraint, e.g., 'wasm-bindgen = "0.2"'.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file is visible in the repository structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting responsible disclosure procedures and security contact information.
• Low · Commented-out LSP Server Code — Cargo.toml, workspace members. The Cargo.toml contains a commented-out LSP server member ('# "lsp/server"'). While currently disabled, this suggests future network-facing functionality that will require careful security review, especially around input validation and authorization. Fix: When enabling LSP server functionality, implement comprehensive security controls including input validation, authentication/authorization, and secure communication protocols (e.g., TLS).
• Low · Binary Self-Update Feature — Cargo.toml, release-downloader dependency. The release-downloader dependency with 'self-update' feature enables automatic binary updates. This could be exploited if the update mechanism lacks proper signature verification or uses insecure channels. Fix: Verify that the release-downloader crate implements cryptographic signature verification for downloaded binaries. Ensure updates are fetched over HTTPS with certificate pinning if possible. Document the update security model clearly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.