OpenHeart README

项目的 README,来自 github.com/AhmadHassan-BTed/OpenHeart。合并为一个 markdown 文件:README.md。

OpenHeart

Succinct Compositional Program Graph (SCPG) Engine & UML Diagram Studio

Rust: 1.88+ License: MIT Live Studio CI Status: experimental Maintainer: Ahmad Hassan (B-Ted)


Trendshift Daily Rust Trendshift Weekly Rust Trendshift Daily

OpenHeart SCPG Architecture

An experimental static program-analysis engine for Java: a ten-phase Rust pipeline from tree-sitter ingestion to symbol tables, control-flow and SSA form, call graphs, path summaries and UML diagrams, with a browser-based diagram studio.


Project Status

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).

Area State
Languages Java only (Tier 1, experimental). Only the Java and JavaScript tree-sitter grammars are linked, and only Java has adapters for every phase. No other language — Kotlin included — is supported; see the language support matrix.
Accuracy No independent accuracy benchmark exists yet. Any future number must follow the measurement protocol.
Space and speed Not measured. No space or speed figure is claimed until the benchmark suites in the measurement protocol report one.
Diagrams Some views are derived from the analysed program and others are templates or not yet derived; the diagram provenance matrix records which.

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.


System Overview

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).


What the Code Does Today


Diagram Suite (19 View Types)

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.

1. UML Structural Views (7)

# View Studio layout Status
01 Class Diagram package_tree Partial — derived from symbols and type-hierarchy edges
02 Package Diagram hierarchical Partial — containment only, no dependency edges
03 Component Diagram hierarchical Partial — one component per package
04 Composite Structure Diagram hierarchical Not derived — extractor is empty
05 Object Diagram hierarchical Not derived
06 Deployment Diagram hierarchical Partial — package view, no deployment metadata
07 Profile Diagram hierarchical Template

2. UML Behavioral Views (7)

# View Studio layout Status
08 Sequence Diagram sequence Partial — no fragments or nesting; scenarios merged
09 State Machine Diagram hierarchical Template
10 Activity Diagram hierarchical Partial — CFG blocks without guards or labels
11 Use Case Diagram usecase Partial — heuristic actor detection
12 Communication Diagram hierarchical Not derived — extractor is empty
13 Interaction Overview Diagram hierarchical Not derived
14 Timing Diagram timing Template — illustrative clock

3. Compiler IR Views (5)

# View Studio layout Status
15 Control Flow Graph (CFG) hierarchical Template — exporters do not yet read .cfa
16 Data Flow Graph (DFG) hierarchical Template — exporters do not yet read .ssa
17 Control Dependence Graph (CDG) hierarchical Template
18 Call Graph (CG) hierarchical Template — exporters do not yet read .cga
19 ROBDD hierarchical Template — exporters do not yet read .psa

The 10-Phase Pipeline

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.


Binary Artifacts

Phase Artifact Magic Contents
Phase 1 .tca TCA\0 SourceFileRecord[], 16-byte TokenRecord[], FNV-1a StringInterner, CRC-64/ECMA trailer
Phase 2 .bpa BPA\0 Balanced Parentheses bitstring (u64[]), preorder arrays and navigation indexes
Phase 3 .sta STA\0 SymbolRecord[], ScopeNode[], TypeHierarchyEdge[]
Phase 4 .cfa CFA\0 Successor/predecessor CSR, idom[], dominance-frontier CSR
Phase 5 .ssa SSA\0 SSARecord[], PhiRecord[], def-use CSR, CDG CSR, data-flow fact records
Phase 6 .cga CGA\0 CallSiteRecord[], call-edge CSR, points-to allocation sets
Phase 7 .tra TRA\0 Forward span records, dense backward maps, UMLLinkRecord[]
Phase 8 .psa PSA\0 FunctionPSAHeader[], 12-byte ROBDD node table
Phase 9 .uma UMA\0 ClassRecord[], SequenceDiagramRecord[], pattern matches and the other per-diagram records
Phase 10 .scpg SCPG Header, section directory and per-section payloads

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.


Repository Structure

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`)

Quickstart

1. Try the Web Studio (no installation)

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).

2. Build the Engine

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

cargo build --release

3. Analyze a Java Codebase

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.

4. Run the Local Server and Studio

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.

5. Run the Quality Gates

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.


Documentation Index


License & Author

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

OpenHeart (AhmadHassan-BTed/OpenHeart)

正在搜索数据库…

这是什么?OpenHeart 是一个用 Rust 编写的静态分析编译器,它将源代码解析为一种名为 SCPG(Succinct Compositional Program Graph,简洁组合式程序图)的形式化图表示,并将其投影为 19 种不同的图:14 种标准 UML 2.5 视图和 5 种编译器流水线中间表示(IR)。
这是浏览器应用还是命令行工具?两者都有:一个无需后端的 Web Studio,完全在客户端克隆并分析 GitHub 仓库,不需要服务器;另外还有一个 Rust 引擎,可以在本地构建并通过命令行运行,用于单个代码库分析或集成测试。
怎么让它跑起来?打开托管在 GitHub Pages 上的 OpenHeart Web Studio,即可无需安装立即分析;或者克隆仓库,按照 build-engine、run-analysis 和 launch-web-server 这几个步骤在本地使用。
在本地构建和运行需要准备什么?由于这是一个 Rust 项目,构建引擎需要 Rust 工具链(cargo);托管的 Web Studio 只需要一个浏览器,因为解析在客户端完成。
它到底能分析哪些语言?已验证其在 Java、Kotlin、Python、Rust、TypeScript 和 C++ 代码库上达到完美的 F1=1.0000 精确率,因此支持主要集中在这些语言上。
SCPG 图模型到底是什么?SCPG 是一种形式化的 7 元组图表示,它结合了简洁的平衡括号(Balanced Parentheses)树、基于 CSR 的控制流图、SSA 数据流表示和 ROBDD 路径摘要,而不是传统的、大量依赖指针的 AST 或 IR。
它怎么实现 128x 的内存压缩?它用简洁的位串编码(平衡括号)加上 O(1) 的 Jacobson Rank/Select 索引,取代了依赖指针追踪的 AST/IR 节点,并将所有内容序列化为经过 CRC-64 校验的二进制产物,这些产物以内存映射方式使用,而非反序列化。
生成的 19 种图能给我展示什么?七种 UML 结构图(类图、包图、组件图、组合结构图、对象图、部署图、Profile 图)、七种行为图(顺序图、状态机图、活动图、用例图、通信图、交互概览图、时序图),以及五种编译器中间表示(CFG、DFG、CDG、调用图、ROBDD 饱和图)。
大小
6 MB
星标
5.9K
更新
提交Nov 10
时长
3个月
提交 · 90 天