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/facebook/hhvm 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.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 42+ active contributors
• Distributed ownership (top contributor 13% of recent commits)
• Other licensed
• Tests present
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

_{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 facebook/hhvm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/facebook/hhvm.

What it runs against: a local clone of facebook/hhvm — 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 facebook/hhvm | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of facebook/hhvm. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/facebook/hhvm.git
#   cd hhvm
#
# 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 facebook/hhvm and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "CMake/HPHPSetup.cmake" \\
  && ok "CMake/HPHPSetup.cmake" \\
  || miss "missing critical file: CMake/HPHPSetup.cmake"
test -f "CMake/HPHPFunctions.cmake" \\
  && ok "CMake/HPHPFunctions.cmake" \\
  || miss "missing critical file: CMake/HPHPFunctions.cmake"
test -f "CMake/Options.cmake" \\
  && ok "CMake/Options.cmake" \\
  || miss "missing critical file: CMake/Options.cmake"
test -f ".devcontainer/Dockerfile" \\
  && ok ".devcontainer/Dockerfile" \\
  || miss "missing critical file: .devcontainer/Dockerfile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/facebook/hhvm"
  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).

HHVM is a just-in-time (JIT) virtual machine that executes programs written in the Hack language, a statically-typed dialect of PHP. It compiles Hack code to native machine code at runtime to achieve near-C++ performance while preserving the flexibility of dynamic language development. HHVM can run standalone Hack scripts or power web applications via Proxygen (built-in webserver) or FastCGI adapters. Monorepo structure: hphp/hack contains the Hack typechecker and language implementation (OCaml, ~12M lines); hphp/runtime contains the HHVM runtime engine (C++, primary execution layer); hphp/hsl contains Hack Standard Library; CMake-based build system in /CMake with 60+ FindXXX modules for external deps; .devcontainer provides reproducible dev environment.

Developers writing Hack applications who need high-performance execution with static type safety; platform engineers deploying Hack-based web services; contributors to the Hack language ecosystem and runtime performance optimization.

Production-ready and actively maintained by Meta. The codebase is substantial (47M+ lines of C++, 31M lines of Hack, 12M lines of OCaml) with comprehensive build infrastructure (CMake, 60+ dependency finders), DevContainer support, and structured issue/PR templates. Actively receiving updates as evidenced by mature CI/CD setup and contributing guidelines.

High complexity due to JIT compiler implementation (C++, OCaml, LLVM integration) requiring deep systems knowledge; 60+ external dependencies (Boost, LLVM, libicu, etc.) create maintenance surface area. Single primary maintainer org (Meta/Facebook) means roadmap tied to corporate interests. Breaking changes possible across major versions given VM-level scope.

Active development of JIT compiler improvements, Hack language feature additions, and performance optimizations. Build infrastructure is modern (CMake, multi-language support, devcontainer.json). Contributing guide and issue templates suggest ongoing community engagement.

git clone https://github.com/facebook/hhvm.git
cd hhvm
# Build requires CMake 3.12+, C++ compiler, OCaml, and 60+ dependencies
# See CONTRIBUTING.md and devcontainer.json for detailed setup
cmake -B build
cmake --build build -j$(nproc)
./build/bin/hhvm example.hack

Daily commands:

# Standalone script execution
./build/bin/hhvm script.hack

# Web server mode (Proxygen)
./build/bin/hhvm -m server -p 8080

# FastCGI mode (nginx/Apache)
./build/bin/hhvm -m fastcgi -p 9000

• CMakeLists.txt — Root build configuration that orchestrates the entire HHVM compilation pipeline; essential for understanding how the project compiles and integrates all dependencies.
• CMake/HPHPSetup.cmake — Core CMake setup script defining compiler flags, platform detection, and build environment initialization that all modules depend on.
• CMake/HPHPFunctions.cmake — Shared CMake functions and macros used across the build system for adding libraries, executables, and running tests consistently.
• CMake/Options.cmake — Defines all build-time configuration options (JIT, extensions, features) that shape which components are included in the final HHVM binary.
• .devcontainer/Dockerfile — Containerized development environment specification; critical for understanding the supported build dependencies and development workflow.
• README.md — Project overview and quick-start guide that frames HHVM's purpose as a JIT-compiled Hack language VM and how to build/run it.
• CONTRIBUTING.md — Developer contribution guidelines and code standards that all pull requests must follow.

Add a new CMake dependency/library

1. Create a Find module in CMake/ that locates and configures the library (CMake/FindNewLibrary.cmake)
2. In CMake/HPHPFunctions.cmake, add helper functions to link the library if needed (CMake/HPHPFunctions.cmake)
3. Update CMakeLists.txt to call find_package() and conditionally include the dependency (CMakeLists.txt)
4. Document the dependency and its build flags in CONTRIBUTING.md (CONTRIBUTING.md)

Enable or disable a build feature

1. Add an OPTION() declaration in CMake/Options.cmake with a meaningful default and help text (CMake/Options.cmake)
2. In CMakeLists.txt or relevant module CMakeLists.txt, use if(OPTION_NAME) ... endif() to conditionally add source files or link libraries (CMakeLists.txt)
3. Update README.md or CONTRIBUTING.md to document the new feature flag and how to enable it (CONTRIBUTING.md)

Add a third-party extension or optional module

1. Create a Find module in CMake/ to locate the extension library (CMake/FindNewExtension.cmake)
2. Reference CMake/HHVMExtensionConfig.cmake to understand extension discovery and registration (CMake/HHVMExtensionConfig.cmake)
3. Add an option in CMake/Options.cmake to enable/disable the extension with ENABLE_EXT_NEWEXT (CMake/Options.cmake)
4. Update CMakeLists.txt to conditionally find, link, and integrate the extension (CMakeLists.txt)

Set up a development environment

1. Use the provided Dockerfile to build a container with all dependencies (.devcontainer/Dockerfile)
2. Open the repository in VS Code with 'Dev Containers' extension and click 'Reopen in Container' (.devcontainer/devcontainer.json)
3. Run CMake configure and build as documented in CONTRIBUTING.md (CONTRIBUTING.md)

• CMake — Cross-platform build configuration language that abstracts compiler and platform differences; essential for supporting Linux, macOS, Windows, and FreeBSD targets.
• C++ — Core HHVM virtual machine implementation requires high performance and low-level control; C++ provides both while remaining reasonably portable.
• Boost, Folly, Thrift — Facebook's internal libraries (Folly for baseline abstractions, Thrift for serialization, Boost for utilities) provide proven, high-performance building blocks.
• JIT Compilation — Converts Hack bytecode to native machine code at runtime, enabling performance approaching compiled languages while maintaining interpreter flexibility.
• Docker/Dev Containers — Standardizes development environment across contributors, reducing 'works on my machine' issues and simplifying CI.

• JIT-based execution model vs. pure interpretation or static compilation

  • Why: Provides a middle ground: fast execution (near compiled-code speeds) with dynamic language flexibility (no pre-compilation required).
  • Consequence: Startup overhead (~100ms) and memory footprint higher than static compilation, but much faster long-running server performance than pure interpretation.

• Monolithic CMake configuration vs. modular sub-projects

  • Why: Simpler to maintain a single source of truth for compiler flags, dependencies, and feature selection across the entire VM.
  • Consequence: Configuration changes can affect the entire codebase; large CMakeLists.txt files that require careful review.

• Tight coupling to Facebook internal libraries (Folly, Thrift)

  • Why: Leverages proven, high-performance libraries developed within Facebook and optimized for large-scale services.
  • Consequence: Requires building/maintaining these dependencies; less independent from the broader Facebook ecosystem.

• Support multiple platforms (Linux, macOS, Windows, FreeBSD) with one codebase

  • Why: Maximizes user base and deployment flexibility across development and production environments.
  • Consequence: Platform-specific code paths and Find modules increase complexity; CI/testing burden grows.

• JavaScript or Python compatibility — HHVM is designed exclusively for Hack, not to run other languages.
• Real-time constraint satisfaction — HHVM is optimized for throughput (web servers, batch processing), not hard real-time systems.
• Embedded systems support — The VM and its dependencies are too heavy for embedded or IoT devices.
• Static type checking at compile time — Hack uses dynamic typing with optional type hints; full static verification is not a goal.
• Cross-compilation turnkey support — Compiling for a different target than the build machine is not a primary focus.
• Windows first-class support — While some Windows support exists, the primary targets are Linux and macOS servers.

OCaml dependency: The typechecker is written in OCaml (12M+ lines), requiring opam/dune toolchain separate from C++ build—many developers overlook this dual-language requirement. CMake complexity: 60+ custom FindXXX modules in /CMake for obscure deps (libWatchmanClient, libAfdt, Oniguruma)—missing system packages silently disable features. LLVM version pinning: JIT compilation requires specific LLVM version; mismatches cause subtle codegen bugs. Proxygen threading: Built-in webserver uses async I/O model—blocking C++ extensions cause hangs. Hack vs PHP incompatibility: Not all PHP code runs unmodified; static typing and strict semantics break legacy patterns.

• Just-In-Time (JIT) Compilation — HHVM's entire performance model depends on runtime code generation—understanding how bytecode gets compiled to native instructions is essential to optimizing or debugging hot paths
• Bytecode Interpreter Pattern — HHVM first compiles Hack to an intermediate bytecode format (hphp/runtime/vm/bytecode.h) before JIT; understanding this two-stage compilation clarifies where type information flows
• Type Erasure & Type Specialization — Hack's static types are erased at runtime but the JIT uses them to generate specialized code paths; this tension between compile-time types and runtime specialization is central to HHVM's design
• LLVM Intermediate Representation (IR) — HHVM's JIT generates LLVM IR rather than direct native code, enabling portability and leveraging LLVM's optimizer; familiarity with LLVM IR is required for JIT debugging
• Incremental Type Checking — The Hack typechecker (hphp/hack/src) uses incremental checking to avoid re-analyzing unchanged files; understanding dependency tracking clarifies edit-time IDE responsiveness
• Copy-On-Write (CoW) Arrays — HHVM's array implementation uses CoW semantics for performance; understanding this clarifies memory behavior and why array copies are cheap until modification
• FastCGI Protocol — HHVM can run as a FastCGI server integrating with nginx/Apache; understanding the protocol clarifies deployment modes beyond the built-in Proxygen webserver

• php/php-src — HHVM's predecessor language; understanding PHP's implementation clarifies HHVM's design decisions and compatibility layer
• llvm/llvm-project — HHVM's JIT backend—code generation and optimization passes depend on LLVM API; changes there impact HHVM's codegen
• facebook/proxygen — Standalone webserver library that HHVM embeds; understanding its architecture clarifies HHVM's -m server mode
• rust-lang/rust — Some HHVM build tooling is Rust-based; ecosystem for performance-critical tools that HHVM may adopt or integrate
• hacklang/hack-mode — Editor tooling and LSP implementation for Hack; users of HHVM will interact with typechecker via these clients

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 CMake dependency resolution tests for missing FindXXX.cmake modules

The CMake/ directory contains 40+ Find*.cmake modules for external dependencies (Boost, ICU, LibEvent, etc.), but there's no test suite validating that these modules correctly detect missing dependencies, handle version mismatches, or provide helpful error messages. This is critical because build failures from misconfigured dependencies are a major pain point for contributors. Adding pytest-based CMake integration tests would catch regressions early.

• [ ] Create tests/cmake/ directory with pytest infrastructure for CMake module validation
• [ ] Add tests for critical modules: CMake/FindBoost.cmake, CMake/FindICU.cmake, CMake/FindLibEvent.cmake
• [ ] Test failure modes: missing dependencies, incompatible versions, and error message clarity
• [ ] Integrate into CI via GitHub Actions to run on dependency changes
• [ ] Document in CONTRIBUTING.md how to add tests for new CMake modules

Create GitHub Action workflow for cross-platform build validation on PRs

The repo has .devcontainer/Dockerfile and CMakeLists.txt but no automated CI that validates builds across Linux, macOS, and Windows on every PR. Given the complexity of HHVM's 40+ external dependencies (tracked in CMake/Find*.cmake), PRs frequently break builds in environments contributors haven't tested. A GitHub Actions matrix build workflow would catch these early.

• [ ] Create .github/workflows/build-matrix.yml with jobs for Ubuntu 20.04, Ubuntu 22.04, and macOS latest
• [ ] Configure CMake flags for each OS (reference CMake/Options.cmake for available toggles)
• [ ] Cache dependencies between runs using .github/workflows/cache action
• [ ] Add step to validate all CMake/Find*.cmake modules resolve correctly
• [ ] Document build instructions in .github/workflows/BUILD.md

Add integration tests for CMake configuration options in CMake/Options.cmake

CMake/Options.cmake likely contains many feature flags (ENABLE_, WITH_, etc.) but there's no test suite verifying that combinations of these options produce valid builds or that incompatible options provide clear error messages. This prevents subtle configuration bugs that only appear when users toggle specific features.

• [ ] Audit CMake/Options.cmake to document all configuration variables and their constraints
• [ ] Create tests/cmake/options_test.py to validate: valid option combinations, invalid combinations with helpful errors, and option interaction side effects
• [ ] Test at least 10 common configuration matrices (e.g., -DENABLE_ZEND_COMPAT=ON with various dependency versions)
• [ ] Add to CI to run on CMake/Options.cmake changes
• [ ] Document in CONTRIBUTING.md which option combinations are officially supported

• Add missing error recovery tests in hphp/test/slow/parse_errors for new Hack syntax features—many syntax additions lack comprehensive test coverage for edge cases.
• Document CMake options in CONTRIBUTING.md—the 60+ FindXXX modules in /CMake are undocumented; a guide mapping feature flags to required deps would help new builders.
• Implement stdlib type stubs for undocumented HSL functions in hphp/hsl/src—cross-reference actual implementations with their .hhi type definitions to find mismatches or missing docs.

The HHVM repository demonstrates a reasonable security posture with responsible disclosure guidelines in place. However, there are several areas for improvement: lack of visible automated security scanning in the CI/CD pipeline, incomplete dependency management transparency, and missing detailed security documentation. The project would benefit from implementing SAST/DAST scanning, comprehensive dependency pinning and auditing, and more explicit security requirements in contribution guidelines. The codebase size and complexity (virtual machine with JIT compilation) warrant enhanced security testing and code review processes. No critical vulnerabilities were identified based on the file structure analysis, but proactive security measures should be strengthened.

• Medium · Potential Dependency Supply Chain Risk — build/deps/, CMake/Find*.cmake files. The repository contains multiple external dependencies referenced through CMake find modules and build configuration files. Without visibility into the full dependency list and their versions, there is a risk of using outdated or compromised dependencies. The build/deps directory structure suggests external dependencies are fetched, potentially with mutable references. Fix: Implement dependency pinning with specific versions and checksums. Use lock files for all external dependencies. Regularly audit dependencies for known vulnerabilities using tools like OWASP Dependency-Check or Snyk. Consider using signed commits and integrity verification for dependency sources.
• Medium · Lack of Explicit Security Policy in Repository — .github/, SECURITY.md, CMakeLists.txt. While SECURITY.md exists with responsible disclosure guidance, there is no clear security baseline documentation, security testing requirements, or vulnerability management process visible in the repository structure. No evidence of automated security scanning in CI/CD pipeline configuration files. Fix: Add comprehensive security documentation including: security testing procedures, SAST/DAST scanning in CI/CD, dependency scanning configuration, security code review process. Create a SECURITY_BASELINE.md documenting required security practices.
• Medium · Potential Information Disclosure in Build Configuration — CMake/ directory, CMakeLists.txt, build/fbcode_builder/. The extensive CMake configuration and multiple Find*.cmake modules could potentially expose sensitive information about the build environment, dependency paths, and system configuration through verbose logging or error messages. Fix: Review CMake output verbosity settings. Sanitize build logs to prevent exposure of system paths and configuration details. Implement log redaction for sensitive information in CI/CD pipelines. Use secure defaults for CMake configurations.
• Low · Missing CONTRIBUTING.md Security Guidelines — CONTRIBUTING.md. While CONTRIBUTING.md exists, there is no visible emphasis on security-focused contribution guidelines, secure coding practices, or security review requirements for pull requests. Fix: Enhance CONTRIBUTING.md with a 'Security' section covering: secure coding practices for Hack language, common vulnerability patterns to avoid, security testing requirements before PR submission, and reference to security code review process.
• Low · Devcontainer Security Configuration — .devcontainer/Dockerfile. The .devcontainer/Dockerfile is present but its content is not visible. Dockerfiles used for development containers may have security misconfigurations such as running as root, missing security updates, or excessive privileges. Fix: Review and apply Docker security best practices: use minimal base images, implement multi-stage builds, run containers as non-root user, scan images for vulnerabilities with tools like Trivy or Grype, and implement layer caching best practices.

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.