OpenHeart is experimental research software. The pipeline runs end to end on Java sources, but several analyses are partial, and several diagram views are still templates whose content does not depend on the analysed program. Before relying on any output, read Implementation Status, Support Matrix & Claims Ledger. That page is the source of truth for what the code does, and it records every earlier headline claim that has been withdrawn (including "128× memory compression", "F1 = 1.0000 across six languages", "zero-copy memory mapping", IFDS, Andersen points-to and Rudell sifting).

Status tables in this README and in docs/status.md record the code as audited at commit fc218cd. An entry changes only in the change that fixes it, with links to the module and to a test that asserts an expected result.

OpenHeart is built around a design called the Succinct Compositional Program Graph (SCPG), a 7-tuple graph model

$$\mathcal{G} = (V, E, \nu, \varepsilon, \tau, \rho, \Sigma_\Phi)$$

that layers lexical tokens, a Balanced Parentheses (BP) AST, Compressed Sparse Row (CSR) control-flow graphs, Static Single-Assignment (SSA) data flow, call graphs and Reduced Ordered Binary Decision Diagram (ROBDD) path summaries over one monotonic token_id traceability anchor. The formal model, its intended complexity bounds and the research paper describe the design target; docs/status.md describes how far the reference implementation has reached it.

Designed, created, and maintained by Ahmad Hassan (B-Ted).

• Java ingestion with tree-sitter and tree-sitter-java: monotonic 32-bit token_id anchors, an FNV-1a string interner and 16-byte token records in a .tca artifact with a CRC-64/ECMA trailer.
• BP-encoded AST (.bpa) with rank/select-based navigation indexes.
• Symbol table and type hierarchy (.sta) built in five passes over the AST.
• Per-function CFGs in CSR form with Cooper et al. dominators and dominance frontiers (.cfa), and SSA construction modules (.ssa).
• Call graph (.cga) from call sites with Class Hierarchy Analysis dispatch.
• Traceability index (.tra): O(1) entity-to-source lookups through dense backward arrays, and sorted span records for source-to-entity queries.
• ROBDD path summaries (.psa). Check the phase capability ledger before relying on path counts: at the audited baseline they overstated the number of paths of branching functions.
• Diagram export to PlantUML, Mermaid and JSON for the 19 view types listed below.
• Declarative studio manifest: web/diagrams/manifest.json defines the 3 categories, 19 diagram types, 16 relationship kinds and 24 node kinds that the web studio renders.
• Web studio on GitHub Pages. It does not run the Rust engine: it uses a JavaScript heuristic extractor over a sample of a repository's files. Full analysis requires the native engine (openheart server).

Each view type has an exporter. The Status column states whether its content was computed from the analysed program at the audited baseline; the full matrix with reasons is in docs/status.md §5.

Phase 1 ──────────────► Phase 2 ──────────────► Phase 3 ──────────────► Phase 4 ──────────────► Phase 5
Lexical Ingestion       BP AST Encoding         Symbol Table &          CFG CSR &               SSA Form & CDG
& Token Corpus (.tca)   (.bpa)                  Type Hierarchy (.sta)   Dominators (.cfa)       (.ssa)

        │
        ▼
Phase 6 ──────────────► Phase 7 ──────────────► Phase 8 ──────────────► Phase 9 ──────────────► Phase 10
Call Graph (.cga)       Traceability Index      ROBDD Path              UML Metadata            SCPG Container
                        (.tra)                  Summaries (.psa)        (.uma)                  (.scpg)

Every phase runs and writes its artifact. What each phase computes, and how it deviates from its design document, is recorded in the phase capability ledger.

What each artifact actually contained at the audited baseline — for example that the .scpg sections other than the string table held only element counts, and that no artifact was mapped zero-copy — is recorded in the phase capability ledger.

OpenHeart/
├── src/                          # Rust engine (10 pipeline phases)
│   ├── adapters/                 # HTTP server and git-clone ingestion adapter
│   ├── ast/                      # Phase 2: BP AST and its navigation indexes
│   ├── cfg/                      # Phase 4: CSR control-flow graphs and Cooper dominators
│   ├── cg/                       # Phase 6: call graph, CHA dispatch, points-to sets
│   ├── core/                     # Core types, binary I/O primitives and logger
│   ├── ingestion/                # Phase 1: tree-sitter ingestion and token corpus (.tca)
│   ├── psa/                      # Phase 8: ROBDD library and path summaries (.psa)
│   ├── scpg/                     # Phase 10: .scpg container, query engine and diagram exporters
│   │   └── diagram/              # Exporters (JSON, PlantUML, Mermaid, XMI)
│   ├── ssa/                      # Phase 5: SSA form, CDG and data-flow facts (.ssa)
│   ├── symbol/                   # Phase 3: symbol table and scope graph (.sta)
│   ├── tra/                      # Phase 7: traceability index (.tra) and UMLLinks
│   ├── uma/                      # Phase 9: UML metadata (.uma) and pattern detectors
│   ├── lib.rs                    # Library crate root
│   └── main.rs                   # CLI entry point
│
├── web/                          # Web studio (static site, deployed to GitHub Pages)
│   ├── diagrams/                 # manifest.json and the bundled sample diagram set
│   ├── js/                       # ES modules: layout, renderer, canvas, editor, file tree,
│   │                             # and the heuristic in-browser extractor (github-engine.js)
│   ├── index.html                # Single-page studio
│   └── style.css                 # Styles and light/dark themes
│
├── examples/                     # Small Java fixture codebases (see examples/README.md)
├── tests/                        # Integration tests (unit tests live beside the code in src/)
├── scripts/                      # Diagram generators, CI checker and experimental harness scripts
├── docs/                         # Design documents, phase plans, status ledger and research paper
├── Cargo.toml / Cargo.lock       # Rust manifest (rust-version = 1.88)
└── Makefile                      # Build, quality-gate and release targets (`make help`)

Open the OpenHeart Web Studio on GitHub Pages. Pasting a repository URL there runs the heuristic in-browser extractor on a sample of files, not the Rust engine (see Project Status).

Requires Rust 1.88 or newer (the rust-version declared in Cargo.toml).

cargo build --release

target/release/openheart analyze ./my_project ./output_dir

The CLI collects source files recursively; only Java is supported (see the language support matrix). It writes the ten phase artifacts and the exported diagrams into output_dir.

target/release/openheart server 8080

Then visit http://localhost:8080. The subcommand is server [PORT]. The server is a development server for local use; do not expose it to untrusted networks.

make ci          # rustfmt check, cargo check, clippy -D warnings, tests, doctests, rustdoc
cargo test --all-targets

make help lists every target, including msrv, miri, deny and coverage.

• Implementation Status & Claims Ledger: What the code does today, the language and diagram support matrices, withdrawn claims and the measurement protocol.
• System Overview: The SCPG formal model and design goals.
• System Architecture: 10-phase pipeline design and the 19 diagram mappings.
• Codebase Guide: Repository layout, module structure and developer reference.
• Getting Started: Workspace setup, Web Studio usage and command-line execution.
• Succinct Structures: BP trees, CSR graphs and ROBDDs, with the gap between design and implementation.
• UML Derivation: Derivation rules for structural, behavioral and compiler-IR views, with per-view status.
• Architectural Roadmap: Phase status and planned work.

Authored, created, and maintained by Ahmad Hassan (B-Ted) under the MIT License. Contributions are welcome; see docs/contributing.md.