v0.2.0

v0.2.0 is an analysis architecture upgrade. It moves OmniScope from v0.1.8's rule-heavy, multi-pass heuristic FFI detection toward a context-aware framework built around semantic resolution, function surface classification, resource contracts, multi-language FFI passes, and a unified Issue Gate.

Change Size

• 697 files changed, 2,554,945 insertions(+), 762,475 deletions(-).
• VERSION is now 0.2.0.
• Main new areas:
  • src/pass/analysis/ffi/
  • src/pass/analysis/ptr_lifetime/
  • src/pass/analysis/noise/
  • src/pass/analysis/resource/
  • src/semantics/
  • src/resource/
  • src/lang/
  • src/ir/
  • test/, tests/, corpus/, docs/en, docs/zh

Major Updates

1. Adds the Semantic Resolution Tree and SemanticResolver so allocator, release, RAII, ownership-transfer, and interior-mutability evidence can be queried.
2. Adds a unified Issue Gate; diagnostics are checked against semantic evidence before they are emitted.
3. Adds SurfaceClassifier to classify functions as user_code, dependency, boundary, standard_library, compiler_generated, runtime, or unknown.
4. Adds SymbolGraph for per-symbol language, ABI, export-surface, and cross-language call-site detection.
5. Adds resource contracts: resource families, function summaries, ownership transfer, release-pair validation, and issue verification.
6. Adds or expands FFI checks for ABI, type mismatch, layout mismatch, string safety, unwind boundaries, callback lifecycle, GC safety, JNI leaks, and cross-language dataflow.
7. Adds language override and adapter support: --lang, --lang-prefix, --lang-suffix, --source-lang, and --default-lang.
8. Adds performance infrastructure: IRStore, InstCache, TraversalIndex, arenas, string interning, prefix trie, Aho-Corasick, and parallel pipeline scaffolding.
9. Expands tests and corpora: inline IR, cross-language fixtures, golden baselines, red-team corpus, real-world corpus, and CI workflow coverage.

Complete Architecture Diagram

flowchart TD
    subgraph Input["Input Layer"]
        CLI["CLI Args<br/>--config --lang --report-surfaces"]
        IR["LLVM IR<br/>.ll / .bc"]
        Config["JSON Config<br/>language overrides, filters, thresholds"]
    end

    subgraph Normalize["Load + Normalize"]
        Loader["IRLoader"]
        Module["LLVM Module + Debug Info"]
        IRStore["ModuleIRStore<br/>pre-categorized functions/instructions"]
        InstCache["InstCache<br/>opcode/operand/callee cache"]
        Traversal["TraversalIndex<br/>function/call/alloc/free indexes"]
    end

    subgraph Context["Context Building"]
        Lang["Language Detector + Overrides"]
        Adapter["Language Adapter Registry"]
        Surface["SurfaceClassifier"]
        Symbol["SymbolGraph<br/>language/ABI/export surfaces/cross-lang calls"]
        SRT["Semantic Resolution Tree"]
        Contracts["Resource Families + Function Summaries + FFI Contract DB"]
        Memory["MemoryGraph"]
    end

    subgraph Pipeline["Pass Pipeline"]
        PM["PassManager<br/>dependency resolution + profiling"]
        Foundation["CFG / DFG / Alias / CallGraph"]
        Classify["Surface / Semantic / Danger"]
        FFI["FFI Passes<br/>Boundary, ABI, Type, Layout, String, Unwind, GC, JNI, Callback"]
        Issue["Issue Passes<br/>Lifetime, Ownership, Free, Memory, Overflow"]
        Cross["Cross-lang Dataflow + Taint"]
    end

    subgraph Verify["Verification + Noise Control"]
        Candidate["Issue Candidate Builder"]
        Verifier["Issue Verifier"]
        Gate["Issue Gate<br/>query SRT, then allow/suppress"]
        Agg["DiagnosticAggregator<br/>dedup"]
        Filter["Surface Filter + Severity + Leak Threshold"]
    end

    subgraph Output["Output Layer"]
        Text["Text"]
        JSON["JSON<br/>optional export_surfaces"]
        SARIF["SARIF"]
        HTML["HTML Graph"]
    end

    CLI --> Config
    CLI --> Loader
    IR --> Loader
    Loader --> Module
    Module --> IRStore
    Module --> InstCache
    Module --> Traversal
    Module --> Lang
    Config --> Lang
    Lang --> Adapter
    IRStore --> Surface
    Traversal --> Surface
    Module --> Symbol
    Surface --> Symbol
    Adapter --> Memory
    Symbol --> PM
    SRT --> PM
    Contracts --> Memory
    Memory --> PM
    IRStore --> PM
    Traversal --> PM
    PM --> Foundation
    Foundation --> Classify
    Classify --> FFI
    FFI --> Issue
    Issue --> Cross
    Cross --> Candidate
    Candidate --> Verifier
    Verifier --> Gate
    Gate --> SRT
    Gate --> Agg
    Agg --> Filter
    Filter --> Text
    Filter --> JSON
    Filter --> SARIF
    Filter --> HTML

Data Flow Diagram

sequenceDiagram
    participant U as User/CLI
    participant L as IRLoader
    participant M as LLVM Module
    participant I as IRStore/TraversalIndex
    participant C as Language/Surface/SymbolGraph
    participant S as SRT/Contracts/MemoryGraph
    participant P as PassManager
    participant A as Analysis Passes
    participant G as IssueVerifier/IssueGate
    participant O as Formatter

    U->>L: .ll/.bc input + flags/config
    L->>M: parse LLVM module/debug info
    M->>I: collect functions, instructions, calls, alloc/free sites
    M->>C: detect languages, apply overrides, classify surfaces
    C->>S: provide boundary, origin, and symbol evidence
    S->>P: expose semantics, resources, ownership, memory graph
    I->>P: expose shared IR indexes
    P->>A: run passes in dependency order
    A->>G: submit candidate issue + evidence
    G->>S: query SRT and resource evidence
    G->>O: emit allowed issues
    O->>U: text/json/sarif/html

New Pass Functions And Responsibilities

The list below follows the full pipeline registered in src/pipeline_registration.zig. Some passes existed before but were reorganized or wired into new v0.2.0 context; they are included because their responsibilities changed in the new architecture.

flowchart LR
    CFG[cfg] --> DFG[dfg]
    CFG --> Alias[alias]
    DFG --> Alias
    Call[call-graph] --> PF[pointer-flow]
    Call --> Life[ptr-lifetime]
    Life --> Danger[danger-surface]
    Danger --> Boundary[ffi-boundary]
    Boundary --> Own[pointer-ownership]
    Boundary --> Unsafe[ffi-unsafe / ffi-body-check]
    Boundary --> ABI[abi-compat-checker]
    Boundary --> GC[gc-safety]
    Boundary --> CB[callback-lifecycle]
    Boundary --> Err[error-propagation-tracer]
    PF --> FFI[ffi-detector / ownership-violation]
    PF --> XDF[cross-lang-dataflow]
    Boundary --> XDF
    Sem[SemanticResolver] --> Rust[rust-ffi-filter]
    Life --> Mem[memory-safety / free-validation]
    Danger --> Mem
    Layout[layout_mismatch] --> Reports[Issue reports]
    String[string_safety_ffi] --> Reports
    Unwind[unwind-boundary] --> Reports
    Mem --> Reports
    XDF --> Reports
    Rust --> Reports

Context And Foundation Passes

These passes mainly produce shared evidence rather than diagnostics. Much of v0.2.0's accuracy improvement comes from this layer: later passes reuse a common CFG/DFG/call graph/surface/semantic view instead of rebuilding local guesses.

FFI Boundary And Cross-Language Passes

Important responsibility split:

• ffi-boundary is the boundary fact producer for downstream FFI passes.
• ffi-type-mismatch, abi-compat-checker, and layout_mismatch separate type, ABI, and layout concerns so reports can point to narrower causes.
• cross-lang-dataflow connects boundary evidence with pointer-flow and is the main path for cross-language ownership/leak reasoning.

New v0.2.0 FFI-Specific Passes

Note: layout_mismatch, string_safety_ffi, and unwind-boundary currently declare empty deps. Conceptually they rely on FFI context, but that dependency is not fully explicit in metadata yet. Check registration order and helper use before moving them.

Lifetime, Ownership, And Memory-Safety Passes

Responsibility split:

• ptr-lifetime gathers lifetime facts.
• danger-surface decides whether facts are relevant enough to report.
• memory-safety and free-validation are the main reporters.
• pointer-ownership and the resource model explain cross-language ownership transfer; they are not equivalent to reporting.

Language And Runtime-Specific Passes

How v0.2.0 Reduces Noise And Improves Accuracy

1. SurfaceClassifier: first decide whether the function should be analyzed

Implemented in src/semantics/surface_classifier/surface_classifier.zig:

• boundary has the highest priority, so FFI boundaries are not accidentally removed by stdlib/runtime suppression.
• standard_library, compiler_generated, and runtime are skipped by default, reducing Rust drop glue, C++ ABI internal, and runtime-helper noise.
• unknown is kept for analysis, which protects recall when classification is incomplete.

2. Issue Gate: every issue goes through the same semantic gate

Implemented in src/pass/filter/issue_gate.zig:

• borrow_escape can be explained by heap_provenance, global_provenance, or mutable_param.
• write_to_immutable can be explained by mutable_param or interior_mutability.
• use_after_free can be explained by raii_drop_release.
• cross_language_free/leak can be explained by into_raw_transfer, non-memory syscalls, or library releases.
• The enhanced gate uses a 0.85 confidence threshold. Conflicting or low-confidence evidence is allowed through instead of hidden.

3. Resource Contracts: from “saw a free” to “release pair is correct”

Implemented in src/resource/ffi_contract_db.zig:

• OwnershipModel.gc, callee, and borrowed suppress leaks that the caller does not own.
• caller and custom are reported conservatively.
• isValidRelease() validates allocation/release pairing, for example SSL_new should match SSL_free, not any free-like function.

4. SymbolGraph: module-level language detection becomes symbol-level detection

Implemented in src/ffi/symbol_graph.zig:

• per-symbol language
• ABI class
• export surface
• cross-language call site

This reduces misclassification caused by treating a mixed LLVM module as a single language, especially in C shims, Rust/C++ mangling, JNI, and Python C API cases.

5. IRStore/InstCache/TraversalIndex: shared indexes reduce repeated traversal

New infrastructure:

• src/ir/ir_store.zig
• src/ir/inst_cache.zig
• src/pipeline/traversal_index.zig

Benefits:

• Passes share function, instruction, call, alloc, and free indexes.
• Hot-path O(n) instruction lookup becomes O(1).
• Repeated LLVM C API calls are reduced, which improves stability and performance on large IR corpora.

v0.1.8 vs v0.2.0

One-Line Summary

v0.2.0 upgrades OmniScope from “find suspicious patterns” to “understand language boundaries, resource ownership, and semantic context before reporting suspicious issues.”