DPX-OCaml is a static analysis and software design pattern detection engine designed for OCaml (OCaml 4.14, 5.0, 5.3+ / Multicore / Jane Street Core / Dune).
Built on Hexagonal Architecture (Ports and Adapters) and Domain-Driven Design (DDD) principles, DPX-OCaml identifies higher-order Functor parameterization, Abstract Data Type signatures (type t), First-Class Modules, GADT AST evaluators, Railway Monadic Bind error pipelines (let*, Result.bind), OCaml 5 Algebraic Effect Handlers (Effect.perform, try_with), Multicore Domains parallelism, and critical type safety / resilience hazards (unchecked failwith/raise, defensive with _ -> exception swallowing, and physical equality == bugs).
| Category | Pattern / Rule | Rule Code | Description |
|---|---|---|---|
| Module System | Functor Parametric Module | FUNCTOR_PARAMETRIC_MODULE |
Higher-order module parameterization (module Make (X : S) = struct ... end) for compile-time DI. |
| Module System | Abstract Data Type (ADT) | ABSTRACT_DATA_TYPE_INTERFACE |
Opaque type declarations (type t) in .mli interfaces with constructor/destructor operations. |
| Module System | First-Class Module | FIRST_CLASS_MODULE |
Packaging modules as runtime values ((module M : S)) for dynamic polymorphism. |
| Module System | Module Inclusion & Extension | MODULE_INCLUSION_EXTENDER |
Extending or overriding module signatures via include Module (e.g. Jane Street Core/Base). |
| Module System | Mutually Recursive Modules | RECURSIVE_MODULES |
Cross-module cyclic types and mutual definitions via module rec A : ... and B : .... |
| Functional Idiom | GADT Type-Safe Evaluator | GADTS_EXPRESSION_EVAL |
Generalized Algebraic Data Types (type _ expr = ...) ensuring compile-time type-safe evaluation. |
| Functional Idiom | Polymorphic Open Variants | POLYMORPHIC_VARIANTS |
Open tag polymorphism ([> Ok of 'a |
| Functional Idiom | Railway Monadic Error Pipeline | RAILWAY_MONADIC_BIND |
Monadic error composition via let*, let+, >>=, Result.bind, or Option.bind. |
| Functional Idiom | Pipeline Operator Transformation | PIPELINE_OPERATOR |
Pure functional data transformation chaining using ` |
| Functional Idiom | Continuation-Passing Style (CPS) | CPS_CONTINUATION_PASSING |
Tail-recursive calls passing explicit continuation callback k for stack-safety. |
| Behavioral | Curried Strategy Injection | CLOSURE_CURRYING_STRATEGY |
Dynamic strategy configuration through partial application, closures, and curried arguments. |
| Structural | Lazy Evaluation & Memoization | LAZY_MEMOIZATION |
Deferred on-demand evaluation and automatic result caching via lazy and Lazy.force. |
| Structural | Record Function VTable | RECORD_FUNCTION_VTABLE |
Structs / records containing function fields for explicit object-like virtual dispatch. |
| Multicore & Effects | Algebraic Effect Handlers | EFFECT_HANDLERS |
OCaml 5 direct-style algebraic effects (type _ Effect.t += ..., Effect.perform, try_with). |
| Multicore & Effects | Domains Multicore Parallelism | DOMAINS_PARALLELISM |
True shared-memory multicore parallelism in OCaml 5 via Domain.spawn / Domainslib. |
| Multicore & Effects | Lwt / Async Promise Concurrency | ASYNC_LWT_PROMISES |
Cooperative asynchronous concurrency using Lwt or Jane Street Async (Lwt.bind, let%bind). |
| Multicore & Effects | Actor Mailbox Process | ACTOR_MAILBOX_PROCESS |
Message-passing actor event loop processing concurrent message channels. |
| Type Safety | Unchecked Exception (failwith/raise) | UNCHECKED_EXCEPTION_RAISE |
Raising unhandled exceptions instead of typed Result.t or Option.t. |
| Resilience | Defensive Catch-All Exception | DEFENSIVE_CATCH_ALL_EXN |
Swallowing all exceptions (try ... with _ -> ...) hiding fatal bugs and corruption. |
| Quality & Principles | Mutable Reference Overuse | MUTABLE_REF_OVERUSE |
Excessive usage of ref or mutable fields violating functional immutability. |
| Type Safety | Physical Equality (==) Bug Risk | PHYSICAL_EQUALITY_SMELL |
Accidental pointer physical equality (== / !=) instead of structural equality (= / <>). |
| Quality & Principles | Single Responsibility (God Module) | GOD_MODULE_SRP |
Monolithic OCaml module defining excessive values and types (≥30 functions or ≥800 LOC). |
| Quality & Principles | KISS Complexity | CYCLOMATIC_COMPLEXITY_KISS |
Function with excessive pattern matching branches (≥12 branches). |
| Quality & Principles | Don't Repeat Yourself (DRY) | DUPLICATE_CODE_DRY |
Duplicated function implementations across modules. |
| Quality & Principles | Circular Module Dependency | CIRCULAR_MODULE_DEPENDENCY |
Cyclic cross-module dependencies without explicit module rec. |
git clone https://github.com/bivex/DPX-OCaml.git
cd DPX-OCaml
uv sync# Terminal scan with rich formatting
uv run dpx-ocaml scan /path/to/ocaml_project
# Generate interactive dark Semantic UI HTML dashboard
uv run dpx-ocaml scan /path/to/ocaml_project -H reports/dashboard.html
# Generate SARIF for GitHub Code Scanning
uv run dpx-ocaml scan /path/to/ocaml_project -S reports/security.sarif
# Export AI Context prompt for LLM refactoring
uv run dpx-ocaml scan /path/to/ocaml_project --llmZero-config architectural X-ray for Dune projects: builds the module dependency DAG, classifies modules into hexagonal layers, and reports cycles, layer inversions and Martin component metrics.
# Rich terminal report (default)
uv run dpx arch /path/to/ocaml_project
# Every format at once, written to ./arch_report/
uv run dpx arch /path/to/ocaml_project -f all -o ./arch_report
# Just the circular dependencies, as Mermaid
uv run dpx arch /path/to/ocaml_project -f mermaid --show-cycles-only| Option | Values | Default |
|---|---|---|
PATH |
project directory | . |
-f, --format |
terminal | mermaid | dot | html | json | all |
terminal |
--group-by |
dune-library | layer | directory |
dune-library |
--show-cycles-only |
only circular dependencies | off |
--metrics/--no-metrics |
Martin metrics matrix (Ca/Ce/I/A/D) | on |
-o, --out |
output directory for file formats | cwd |
What it detects:
- 🔁 Circular dependencies — Tarjan SCC over the module graph, with cross-library
cycles flagged separately (those cannot be broken with a local
module rec). ⚠️ Layer violations — dependency direction that breaks ports-and-adapters boundaries (e.g. Domain → Infrastructure).- ℹ️ Orphans & smells — isolated modules, god modules (>400 LOC), hub modules (>15 efferent deps), interface-bypass hotspots.
- 📊 Martin metrics — per-module Afferent/Efferent coupling, Instability, Abstractness and Main-Sequence distance, with zone of pain / zone of uselessness classification.
The pipeline reads dune/dune-project S-expressions (wrapped libraries,
(select ... from ...) dependencies, default_wrapped), extracts per-compilation-unit
facts (opens, includes, functor applications, qualified references, type t exports)
from .ml/.mli pairs, and falls back to pure filesystem grouping when no Dune
manifests exist. The html export is a single self-contained interactive file —
zoom, drag, click-to-highlight neighborhoods — with no CDN dependencies. Scans
500 modules in well under a second.
| # | Language | Repository | Ecosystem & Focus |
|---|---|---|---|
| 1 | Ada | bivex/DPX-Ada |
Ada 2012/2022, SPARK Contracts, Ravenscar Tasking, DO-178C Safety |
| 2 | Clojure | bivex/DPX |
Lisp S-Expressions, Protocols, Multimethods |
| 3 | C | bivex/DPX-C |
Memory Safety, Struct VTables, Idiomatic C11/C23 |
| 4 | Cairo | bivex/DPX-Cairo |
Starknet Smart Contracts, ZK-Rollup Invariants |
| 5 | C++ | bivex/DPX-Cpp |
RAII, CRTP, Concepts, Modern C++20/23 |
| 6 | C# | bivex/DPX-CSharp |
.NET 9, Roslyn AST, Linq, Records |
| 7 | Dart | bivex/DPX-Dart |
Dart 3.x, Flutter, BLoC, Riverpod, Isolates |
| 8 | Elixir | bivex/DPX-Elixir |
BEAM OTP, GenServer, Supervisors |
| 9 | Erlang | bivex/DPX-Erlang |
Fault Tolerance, Actor Model, OTP Behaviors |
| 10 | Gleam | bivex/DPX-Gleam |
Type-Safe BEAM, Actor Concurrency |
| 11 | Go | bivex/DPX-Go |
Goroutines, Channels, Composition, Interfaces |
| 12 | Haskell | bivex/DPX-Haskell |
Pure Functional, Monads, Typeclasses, Arrows |
| 13 | Huff | bivex/DPX-Huff |
Low-Level EVM Bytecode & Opcodes |
| 14 | Idris 2 | bivex/DPX-Idris2 |
Dependent Types, QTT Linear Protocols, Totality, Proofs |
| 15 | Java | bivex/DPX-Java |
Spring Boot, Enterprise Java, JVM Invariants |
| 16 | Julia | bivex/DPX-Julia |
Multiple Dispatch, Scientific Computing |
| 17 | Kotlin | bivex/DPX-Kotlin |
Coroutines, Multiplatform, Functional DSLs |
| 18 | Lua | bivex/DPX-Lua |
Metatables, Coroutines, LuaJIT, Neovim |
| 19 | Mojo | bivex/DPX-Mojo |
SIMD Hardware, Memory Lifetimes, AI Systems |
| 20 | Move | bivex/DPX-Move |
Aptos & Sui Resource Safety, Linear Types |
| 21 | OCaml | bivex/DPX-OCaml |
Algebraic Data Types, Functors, Polymorphism |
| 22 | PHP | bivex/DPX-Php |
Modern PHP 8.4, Attributes, Traits, Laravel |
| 23 | Prolog | bivex/DPX-Prolog |
ISO Prolog, SWI-Prolog, DCG, CLP(FD/R/Q), CHR, Meta-Interpreters |
| 24 | Puppet | bivex/DPX-Puppet |
Puppet DSL, Roles/Profiles, IaC Security, Hiera |
| 25 | Python | bivex/DPX-Py |
Metaprogramming, Protocols, Hexagonal DDD |
| 26 | Ruby | bivex/DPX-Ruby |
Ruby 3.x, Rails, Metaprogramming, Dry-RB, Security |
| 27 | Rust | bivex/DPX-Rust |
Zero-Cost Abstractions, Borrow Checker, Traits |
| 28 | Solidity | bivex/DPX-Solidity |
DeFi Security, Reentrancy, EVM Yul/Assembly |
| 29 | SQL | bivex/DPX-SQL |
PostgreSQL, MySQL, SQLite, T-SQL, PL/SQL |
| 30 | Swift | bivex/DPX-Swift |
Protocol-Oriented Programming, Actors |
| 31 | TypeScript | bivex/DPX-TypeScript |
Generics, Conditional Types, Clean Architecture |
| 32 | Yul | bivex/DPX-Yul |
EVM Intermediate Representation Optimization |
| 33 | Zig | bivex/DPX-Zig |
Comptime, Manual Memory Allocators, C ABI |
Distributed under the MIT License. See LICENSE for details.