Comprehensive OCaml development toolkit with project setup, build migration, testing, RFC integration, opam publishing, and code style assistance

version
1.6.0
GitHub stars
40

Install

/plugin install ocaml-dev@ocaml-claude-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add avsm/ocaml-claude-marketplace.

Contents

Discovered from source

Skills 22

Role

You are an expert OCaml and cmdliner practitioner who designs and implements command-line interfaces following established CLI design principles: clarity, predictability, orthogonality, discoverability, composability, and precise semantics.

When asked to design or modify a CLI using cmdliner, you:

  • Focus on semantically clear commands and options.
  • Aim for consistent, orthogonal flags across subcommands.
  • Produce excellent --help output and error messages.
  • Provide minimal but complete examples that can be pasted into a project.

Always use British spelling.

When to Use This Skill

Use this skill whenever the user wants to:

  1. Design the structure of a new CLI for an OCaml project (commands, subcommands, flags, arguments).
  2. Implement the CLI using cmdliner terms, combinators, and Cmd.v / Term.t values.
  3. Refactor an existing cmdliner-based CLI for clarity, orthogonality, or better help text.
  4. Integrate the CLI in a dune project (executables, libraries, test commands).
  5. Add logging, configuration, or environment-variable support around a cmdliner interface.

Core Design Principles

  1. Economy of commands and extensibility
    • Prefer extending existing commands rather than adding new ones when the domain permits.
    • Keep each command designed for future growth through well-considered flags, sub-modes, or argument structures.
    • Avoid unnecessary expansion of the command namespace; new commands should appear only when they introduce a genuinely distinct operational domain.

When designing or reviewing a CLI, explicitly apply the following principles and refer to them in explanations:

  1. Clarity and explicitness

    • Each command and option has a single, clearly stated purpose.
    • Avoid ambiguous shorthand; prefer explicit names and well-phrased docs.
    • Make defaults explicit in documentation and error messages.
  2. Predictable structure

    • Related operations are grouped into subcommands (e.g. mytool build, mytool check, mytool format).
    • Options with similar names behave the same way across all commands.
    • Positional arguments appear in a stable, predictable order.
  3. Orthogonality

    • Each flag controls one independent aspect of behaviour.
    • Avoid flags that silently alter multiple concerns.
    • Avoid pairs of flags that only make sense in certain hidden combinations.
  4. Discoverability

    • --help output is concise but complete: usage, description, arguments, options, environment, examples.
    • Default values and accepted ranges or enumerations are documented.
    • Errors help the user discover the correct usage instead of merely rejecting input.
  5. Composability and shell-friendliness

    • Design for Unix-style pipelines: standard input/output, exit codes, and simple text or structured output.
    • Avoid implicit file I/O if explicit paths or -o flags are possible.
    • Offer machine-friendly output formats where relevant (e.g. JSON) and document them.
  6. Precise failure modes

    • Error messages state what is wrong and how to fix it.
    • Ambiguous or partial input is rejected with clear guidance.
    • Exit codes are chosen deliberately (e.g. 0 success, 1 user error, 2 internal failure).

Good and Bad Examples

Option Naming

Bad: Ambiguous or inconsistent names

(* Unclear what -f does without reading docs *)
let file = Arg.(value & opt (some string) None & info ["f"])

(* Inconsistent: some commands use --verbose, others use --debug *)
let verbose = Arg.(value & flag & info ["v"; "verbose"])
let debug = Arg.(value & flag & info ["d"; "debug"])  (* same thing? *)

Good: Clear, explicit names with consistent patterns

(* Self-documenting option name *)
let config_file =
  Arg.(value & opt (some file) None &
       info ["c"; "config"] ~docv:"FILE"
         ~doc:"Configuration file path.")

(* Use Logs_cli for verbosity - integrates with Logs library *)
let setup_log =
  Term.(const Logs_fmt.setup $ Fmt_cli.style_renderer () $ Logs_cli.level ())
(* Provides -v, -v -v, --verbosity=debug, etc. *)

Subcommand Design

Bad: Flat command namespace with overlapping concerns

(* Explosion of top-level commands *)
let cmds = [
  create_user_cmd; delete_user_cmd; list_users_cmd;
  create_group_cmd; delete_group_cmd; list_groups_cmd;
  create_role_cmd; delete_role_cmd; list_roles_cmd;
]

Good: Hierarchical grouping with consistent verbs

(* Grouped by resource, consistent verbs *)
let create_cmd = Cmd.v (Cmd.info "create") create_user_term
let delete_cmd = Cmd.v (Cmd.info "delete") delete_user_term
let list_cmd = Cmd.v (Cmd.info "list") list_users_term

let user_cmd =
  let info = Cmd.info "user" ~doc:"Manage users" in
  Cmd.group info ~default:list_users_term [create_cmd; delete_cmd; list_cmd]

let main_cmd =
  let info = Cmd.info "mytool" ~version:"1.0" in
  Cmd.group info [user_cmd; group_cmd; role_cmd]

Error Messages

Bad: Unhelpful error that doesn't guide the user

let validate_port p =
  if p < 0 || p > 65535 then `Error (false, "invalid port")
  else `Ok p

Good: Error explains what's wrong and how to fix it

let validate_port p =
  if p < 0 || p > 65535 then
    `Error (false, Printf.sprintf
      "port %d is out of range (must be 0-65535)" p)
  else `Ok p

Separating Parsing from Logic

Bad: Business logic mixed with cmdliner parsing

let run_term =
  let open Term in
  const (fun config_file ->
    (* Business logic embedded in term *)
    let config = read_config config_file in
    let db = connect_db config in
    run_server db)
  $ config_file_arg

Good: Terms only parse; separate function does the work

(* Pure business logic function *)
let run ~config_file =
  let config = read_config config_file in
  let db = connect_db config in
  run_server db

(* Term just wires up arguments *)
let run_term = Term.(const run $ config_file_arg)

Flag Orthogonality

Bad: Flags with hidden interactions

(* --json silently disables --color, user doesn't know *)
let output_format json color =
  if json then Json else if color then Colored else Plain

Good: Orthogonal flags, explicit conflicts

(* Either format flag, not both *)
let output_format =
  Arg.(value & vflag Plain [
    Json, info ["json"] ~doc:"Output as JSON.";
    Colored, info ["color"] ~doc:"Output with ANSI colors.";
  ])

Cmdliner-Specific Guidance

When writing or revising cmdliner code, follow these patterns:

  • Use Cmd.v with a Term.t and Cmd.info for each command or subcommand.
  • Keep parsing logic inside cmdliner terms and keep business logic in plain OCaml functions that receive already-parsed values.
  • Use Arg.info documentation strings that are short, concrete, and consistent across commands.
  • Prefer labelled arguments and records in the implementation to keep term assembly readable.
  • Ensure each CLI example you give compiles on recent OCaml and cmdliner versions.

Typical Structure

When the user asks for a new CLI, aim to provide:

  1. A command tree sketch (top-level command, subcommands, options, arguments).
  2. Example Cmd.t and Term.t definitions.
  3. Example dune stanzas required to build the executable.
  4. Example usage snippets showing common workflows.

Response Format

Unless the user requests otherwise, structure your responses as:

  1. Overview – brief description of the CLI design or change.
  2. Command layout – a tree-like view of commands, subcommands, and key options.
  3. Cmdliner implementation – OCaml snippets with open Cmdliner (or fully qualified names if clearer).
  4. Help and examples – sample --help output and real-world usage examples.
  5. Rationale – short notes linking the design back to the principles (clarity, orthogonality, etc.).

Keep explanations concrete and focused on practical trade-offs (naming, grouping of options, error behaviour, and output formats).

CLI Output Design Guidelines

A good CLI is both useful and beautiful. Follow these guidelines for consistent, professional output.

Core Libraries

LibraryPurpose
fmtStyled terminal output (colors, bold, etc.)
progressProgress bars and spinners
logs + logs-cliStructured logging with verbosity levels
nottyFull terminal UI (tables, boxes) - for complex tools

Output Modes

Every CLI should support at least two output modes:

type output_format = Human | Json

let output_format =
  let doc = "Output format: $(b,human) for terminal, $(b,json) for scripts." in
  Arg.(value & opt (enum ["human", Human; "json", Json]) Human &
       info ["o"; "output"] ~doc ~docv:"FORMAT")

Human mode: Colors, progress bars, tables, emoji status indicators JSON mode: Machine-parseable, no ANSI codes, newline-delimited for streaming

Color Scheme

Use consistent semantic colors across all tools:

(* Standard semantic styles *)
let success = Fmt.(styled `Green string)      (* ✓ Success, OK *)
let error = Fmt.(styled `Red string)          (* ✗ Error, Failed *)
let warning = Fmt.(styled `Yellow string)     (* ⚠ Warning *)
let info = Fmt.(styled `Cyan string)          (* ℹ Info, hints *)
let dimmed = Fmt.(styled `Faint string)       (* Secondary info *)
let bold = Fmt.(styled `Bold string)          (* Emphasis, headers *)
let code = Fmt.(styled `Cyan string)          (* Code, paths, values *)

(* Status indicators with icons *)
let pp_status ppf = function
  | `Ok -> Fmt.pf ppf "%a" Fmt.(styled `Green string) "✓"
  | `Error -> Fmt.pf ppf "%a" Fmt.(styled `Red string) "✗"
  | `Warning -> Fmt.pf ppf "%a" Fmt.(styled `Yellow string) "⚠"
  | `Info -> Fmt.pf ppf "%a" Fmt.(styled `Cyan string) "ℹ"
  | `Pending -> Fmt.pf ppf "%a" Fmt.(styled `Blue string) "○"

Progress Bars

Use the progress library for long-running operations:

open Progress

(* Simple progress bar *)
let with_progress ~total f =
  let bar =
    Line.(list [
      spinner ();
      bar ~style:`UTF8 ~width:(`Fixed 40) total;
      count_to total;
      elapsed ();
    ])
  in
  Progress.with_reporter bar f

(* Example usage *)
let process_files files =
  let total = List.length files in
  with_progress ~total (fun report ->
    List.iteri (fun i file ->
      process_file file;
      report i
    ) files)

For indeterminate operations, use spinners:

let with_spinner ~message f =
  let line = Line.(list [spinner (); const message]) in
  Progress.with_reporter line (fun _report -> f ())

Tables

For tabular data, use aligned columns:

(* Simple table with Fmt *)
let pp_table ppf rows =
  let widths = compute_column_widths rows in
  List.iter (fun row ->
    List.iteri (fun i cell ->
      let width = List.nth widths i in
      Fmt.pf ppf "%-*s  " width cell
    ) row;
    Fmt.pf ppf "@."
  ) rows

(* With header styling *)
let pp_table_with_header ppf ~headers rows =
  (* Header row in bold *)
  List.iter (fun h -> Fmt.pf ppf "%a  " bold h) headers;
  Fmt.pf ppf "@.";
  (* Separator *)
  List.iter (fun h -> Fmt.pf ppf "%s  " (String.make (String.length h) '─')) headers;
  Fmt.pf ppf "@.";
  (* Data rows *)
  List.iter (fun row ->
    List.iter (fun cell -> Fmt.pf ppf "%s  " cell) row;
    Fmt.pf ppf "@."
  ) rows

Error Output

Errors should be clear, actionable, and visually distinct:

let pp_error ppf ~context ~message ~hint =
  Fmt.pf ppf "@[<v>%a %a@,%a@,%a %a@]@."
    Fmt.(styled `Red string) "error:"
    Fmt.(styled `Bold string) message
    dimmed (Printf.sprintf "  in %s" context)
    Fmt.(styled `Cyan string) "hint:"
    Fmt.string hint

(* Example output:
   error: Invalid port number '70000'
     in --port argument
   hint: Port must be between 0 and 65535
*)

Summary Output

For commands that process multiple items:

let pp_summary ppf ~processed ~succeeded ~failed ~skipped =
  Fmt.pf ppf "@.%a@."
    Fmt.(styled `Bold string) "Summary:";
  Fmt.pf ppf "  %a %d processed@."
    (Fmt.styled `Cyan string) "•" processed;
  if succeeded > 0 then
    Fmt.pf ppf "  %a %d succeeded@."
      (Fmt.styled `Green string) "✓" succeeded;
  if failed > 0 then
    Fmt.pf ppf "  %a %d failed@."
      (Fmt.styled `Red string) "✗" failed;
  if skipped > 0 then
    Fmt.pf ppf "  %a %d skipped@."
      (Fmt.styled `Yellow string) "○" skipped

(* Example output:
   Summary:
     • 42 processed
     ✓ 40 succeeded
     ✗ 2 failed
*)

TTY Detection

Always check if stdout is a terminal before using colors/progress:

let setup_formatter () =
  let style_renderer =
    if Unix.isatty Unix.stdout then `Ansi_tty else `None
  in
  Fmt.set_style_renderer Fmt.stdout style_renderer

(* Or use Fmt_cli for cmdliner integration *)
let setup_term =
  Term.(const Fmt_tty.setup_std_outputs $ Fmt_cli.style_renderer ())

Verbosity Levels

Integrate with Logs for consistent verbosity:

(* In main.ml *)
let setup_log style_renderer level =
  Fmt_tty.setup_std_outputs ?style_renderer ();
  Logs.set_level level;
  Logs.set_reporter (Logs_fmt.reporter ())

let setup_log_term =
  Term.(const setup_log $ Fmt_cli.style_renderer () $ Logs_cli.level ())

(* In code, use appropriate log levels *)
Logs.debug (fun m -> m "Processing file %s" path);
Logs.info (fun m -> m "Converted %d records" count);
Logs.warn (fun m -> m "Deprecated format, consider upgrading");
Logs.err (fun m -> m "Failed to parse: %s" reason);

Example: Complete CLI with Good Output

open Cmdliner

(* Styled output helpers *)
let success fmt = Fmt.pf Fmt.stdout ("%a " ^^ fmt ^^ "@.")
  Fmt.(styled `Green string) "✓"
let error fmt = Fmt.pf Fmt.stderr ("%a " ^^ fmt ^^ "@.")
  Fmt.(styled `Red string) "✗"
let info fmt = Fmt.pf Fmt.stdout ("%a " ^^ fmt ^^ "@.")
  Fmt.(styled `Cyan string) "ℹ"

(* Command implementation *)
let convert ~input ~output ~format =
  info "Converting %a to %s format"
    Fmt.(styled `Bold string) input
    format;
  match do_convert input output format with
  | Ok bytes ->
      success "Wrote %d bytes to %a" bytes
        Fmt.(styled `Cyan string) output;
      `Ok ()
  | Error msg ->
      error "Conversion failed: %s" msg;
      `Error (false, msg)

(* Term with proper setup *)
let term =
  let open Term in
  const convert
  $ input_arg
  $ output_arg
  $ format_arg

let cmd =
  let info = Cmd.info "convert"
    ~doc:"Convert between formats"
    ~man:[`S "EXAMPLES"; `P "$(iname) input.json -o output.cbor"]
  in
  Cmd.v info Term.(ret (const setup $ setup_log_term $ term))

Checklist for New CLIs

  • Supports --output=json for machine-readable output
  • Uses semantic colors (green=success, red=error, etc.)
  • Progress bars for operations > 1 second
  • Clear error messages with hints
  • Summary output for batch operations
  • TTY detection (no colors when piped)
  • Verbosity via -v / --verbosity (Logs_cli)
  • Consistent with project conventions

OCaml Code Style

Core Philosophy

  1. Interface-First: Design .mli first. Clean interface > clever implementation.
  2. Modularity: Small, focused modules. Compose for larger systems.
  3. Simplicity (KISS): Clarity over conciseness. Avoid obscure constructs.
  4. Explicitness: Explicit control flow and error handling. No exceptions for recoverable errors.
  5. Purity: Prefer pure functions. Isolate side-effects at edges.
  6. NEVER use Obj.magic: Breaks type safety. Always a better solution.

Naming Conventions

ElementConventionExample
Fileslowercase_underscoresuser_profile.ml
ModulesSnake_caseUser_profile
Typessnake_case, primary type is ttype user_profile, type t
Valuessnake_casefind_user, create_channel
VariantsSnake_caseWaiting_for_input, Processing_data

Function naming:

  • find_* returns option (may not exist)
  • get_* returns value directly (must exist)

Avoid: Long names with many underscores (get_user_profile_data_from_database_by_id).

Refactoring Patterns

Option/Result Combinators

(* Before *)
match get_value () with Some x -> Some (x + 1) | None -> None

(* After *)
Option.map (fun x -> x + 1) (get_value ())

Prefer: Option.map, Option.bind, Option.value, Result.map, Result.bind

Monadic Syntax (let*/let+)

(* Before - nested matches *)
match fetch_user id with
| Ok user -> (match fetch_perms user with Ok p -> Ok (user, p) | Error e -> Error e)
| Error e -> Error e

(* After *)
let open Result.Syntax in
let* user = fetch_user id in
let+ perms = fetch_perms user in
(user, perms)

Pattern Matching Over Conditionals

(* Before *)
if x > 0 then if x < 10 then "small" else "large" else "negative"

(* After *)
match x with
| x when x < 0 -> "negative"
| x when x < 10 -> "small"
| _ -> "large"

Function Design

Keep functions small: Under 50 lines. One purpose per function.

Avoid deep nesting: Max 4 levels of match/if. Extract helpers.

High complexity signal: Many branches = split into focused helpers.

(* Bad - high complexity *)
let check x y z =
  if x > 0 then if y > 0 then if z > 0 then ... else ... else ... else ...

(* Good - factored *)
let all_positive x y z = x > 0 && y > 0 && z > 0
let check x y z = if not (all_positive x y z) then "invalid" else ...

Error Handling

Use result for recoverable errors. Exceptions only for programming errors.

Never catch-all:

(* Bad *)
try f () with _ -> default

(* Good *)
try f () with Failure _ -> default

Don't silence warnings: Fix the issue, don't use [@warning "-nn"].

Library Preferences

Instead ofUseWhy
StrReBetter API, no global state
PrintfFmtComposable, type-safe
yojson (manual)jsontType-safe codecs

Module Hygiene

Abstract types: Keep type t abstract. Expose smart constructors.

(* Good - .mli *)
type t
val create : name:string -> t
val name : t -> string
val pp : t Fmt.t

Avoid generic names: Not Util, Helpers. Use String_ext, Json_codec.

API Design

Avoid boolean blindness:

(* Bad *)
let create_widget visible bordered = ...
let w = create_widget true false  (* What does this mean? *)

(* Good *)
type visibility = Visible | Hidden
let create_widget ~visibility ~border = ...

Comments and Documentation

Documentation is written in the voice of a POSIX manual page. Implementations carry no comments where the code speaks for itself. Load the doc-style skill before writing or rewording any comment. It is the full standard and the list below is only its summary.

The short form:

  • A function's doc opens [f x y] is ..., on the line after the val.
  • Full sentences ending in a full stop. No fragments.
  • No colons or em dashes joining clauses. Use separate sentences.
  • Nothing about the implementation. Only what the caller can observe.
  • No This function, Note that, simply, helper for, internally.
  • Every optional argument states its default.
  • Delete implementation comments that restate the code, section banners, and commented-out code.
  • Documentation lives in the .mli. An .ml with an .mli carries no (** ... *) comments.
(* Bad *)
(** Parses the string: splits on commas and builds the record — fast. *)
val parse : string -> t

(* Good *)
val parse : string -> t
(** [parse s] is the record encoded in [s]. Parsing is linear in the length of
    [s]. *)

Red Flags

  • Match that just rewraps: Some v -> Some (f v) | None -> None
  • Nested Result/Option matches → use let*/let+
  • Deep if/then/else → pattern matching
  • Missing pp function on types
  • Unlabeled boolean parameters
  • Obj.magic anywhere
  • Doc comments that describe the implementation rather than the behaviour
  • Comments inside an implementation that restate the code
  • A colon or em dash joining clauses in a doc comment
  • An exported value with no doc comment

OCaml Comment and Documentation Style

Write ocamldoc the way a POSIX manual page is written. State what a thing is and what it does, in full sentences, and stop.

Implementations carry no comments at all unless the code cannot speak for itself.

This skill covers what to write. For odoc reference syntax, cross-package links and build warnings, see the ocaml-docs skill.

The Six Rules

  1. Full sentences. Every doc comment is one or more complete sentences, each ending in a full stop. No fragments, no bullet-point shorthand, no trailing "...".
  2. Manpage voice. Terse, declarative, present tense, third person. No "we", no "you", no "this function", no enthusiasm.
  3. No extraneous detail. Document what a caller must know to call it. History, rationale, benchmarks, future plans and implementation trivia do not appear.
  4. No connectives. No colons and no em dashes joining clauses. Split into separate sentences instead. Semicolons only inside a genuine list.
  5. User-facing, not internal. Describe observable behaviour. Mention an internal only when the caller can observe it, such as time complexity, allocation behaviour, evaluation order or thread safety.
  6. [f x y] is .... A function's documentation opens with the function applied to its arguments in brackets, followed by is.

Function Documentation

The doc comment follows the val declaration. Name the arguments in the bracketed application and refer to them with [x] thereafter.

val length : t -> int
(** [length t] is the number of elements in [t]. *)

val find : string -> t -> element option
(** [find name t] is the element of [t] called [name], or [None] if [t] has
    no such element. *)

val is_bot : t -> bool
(** [is_bot u] is [true] if [u] is a bot user. *)

Use is whenever the function has a meaningful result. Reserve an active verb for functions that exist for their effect.

val flush : out_channel -> unit
(** [flush oc] writes the buffered bytes of [oc] to its underlying file. *)

val set : t -> key:string -> value:string -> unit
(** [set t ~key ~value] binds [key] to [value] in [t]. Any previous binding of
    [key] is dropped. *)

Effectful constructors are still is.

val create : unit -> t
(** [create ()] is a new empty table. *)

val of_file : Fpath.t -> (t, Error.t) result
(** [of_file file] is the configuration parsed from [file]. The error holds a
    human readable message suitable for a command line tool. *)

Document optional arguments in their own sentence, and give the default.

val sub : ?start:int -> ?len:int -> string -> string
(** [sub ~start ~len s] is the substring of [s] of length [len] starting at
    [start]. [start] defaults to [0]. [len] defaults to the remainder of [s]
    after [start]. *)

Failure conditions go last, as tags.

val get : t -> string -> element
(** [get t name] is the element of [t] called [name].

    @raise Not_found if [t] has no element called [name]. *)

Prefer naming arguments in the bracketed application over @param tags. @param restates the signature and reads nothing like a manual page.

Type and Value Documentation

A type is documented by what its values represent, not by its representation.

type t
(** The type for users. *)

type id = string
(** The type for user identifiers. An identifier is unique within a workspace
    and stable across renames. *)

type level = Debug | Info | Warning | Error
(** The type for message severities, in increasing order of severity. *)

Constructors and record fields take a doc comment only when the name is not enough.

type t = {
  name : string;  (** The display name. It is not unique. *)
  id : id;
  created : Ptime.t;  (** The creation time, in UTC. *)
}

Module Documentation

The first line of an .mli is a synopsis in the shape of a manpage NAME line. A blank line follows, then the description.

(** User accounts and profiles.

    Users are workspace members. A user is identified by an {!type:id} that is
    stable for the lifetime of the account. Profile fields are populated
    lazily and may be absent on users who have never signed in. *)

Keep the description to what a caller needs before reading the values below it. Use {1 Section} headings once the interface is long enough to need them, and name the sections after what they hold, such as {1 Users} or {1 Predicates and comparisons}.

Rewrites

Instead ofWrite
(** Returns the length of the buffer *)(** [length b] is the number of bytes in [b]. *)
(** [parse s] parses [s]: it splits on commas and builds a record. *)(** [parse s] is the record encoded in [s]. *)
(** [send t msg] sends a message — note this blocks. *)(** [send t msg] sends [msg] on [t]. It blocks until [msg] has been written. *)
(** This function is used internally by the scheduler to requeue fibers. *)Delete it, or make the value private.
(** Fast lookup (uses a hashtable). *)(** [find t k] is the value bound to [k] in [t]. Lookup is constant time. *)
(** TODO: document *)Write the sentence.

Banned Words and Shapes

Delete these on sight.

  • This function, This value, This module as an opener. Name the thing.
  • Basically, simply, just, obviously, of course.
  • Note that, Please note, Be aware. State the fact as a sentence.
  • Internally, under the hood, behind the scenes.
  • Helper for, Wrapper around, Convenience function.
  • A colon or em dash introducing an explanatory clause.
  • A parenthetical that repeats the type signature.
  • Author names, dates, ticket numbers and changelog entries.

Comments in Implementations

Default is no comment. If a reader who knows OCaml can see what the code does, the code says it already. Naming a value is better than commenting it.

Delete on sight:

  • Comments that restate the code, such as (* increment i *).
  • Section banners and boxes, such as (* ---- Helpers ---- *).
  • Commented-out code. Version control keeps it.
  • Narration of obvious control flow, such as (* loop over the list *).
  • Attribution, dates and changelog entries.
  • Doc comments in an .ml that has an .mli. The documentation belongs in the interface, and a second copy will drift.

Write a comment only for something the code cannot state:

  • A citation for behaviour mandated elsewhere, such as (* RFC 8259 §7. *).
  • An invariant a reader cannot check locally, such as (* [buf] is never empty here, see [refill]. *).
  • A deliberate deviation or workaround, with the reason it exists.
  • A justification for an unsafe or unusual operation.
  • Why the obvious approach was rejected, when someone would otherwise reinstate it.

Kept comments are full sentences in (* ... *), placed on the line above the code they explain.

(* Bad. *)
let decode s =
  (* get the length *)
  let n = String.length s in
  (* loop over the characters *)
  let b = Buffer.create n in
  ...

(* Good. *)
let decode s =
  let b = Buffer.create (String.length s) in
  ...

(* Good. The comment states what the code cannot. *)
let decode s =
  (* RFC 4648 §3.2 requires padding to be rejected in strict mode. *)
  if strict && String.length s mod 4 <> 0 then invalid_arg "decode";
  ...

Checklist

Before committing documentation:

  • Every exported value has a doc comment.
  • Every function doc opens with [f x y] is or an active verb for an effect.
  • Every argument named in the brackets is referred to in the prose.
  • Every optional argument has its default stated.
  • Every sentence is complete and ends in a full stop.
  • No colons or em dashes join clauses.
  • No sentence describes the implementation.
  • No banned word from the list above survives.
  • The .ml has no comment that the code already says.
  • dune build @doc is clean.

OCaml Build System Migration

When to Use This Skill

Invoke this skill when:

  • Converting a project from ocamlbuild to dune
  • Discussing _tags, .mllib, or pkg.ml files
  • Migrating from topkg to dune
  • Understanding ocamlbuild artifacts

Process Overview

1. Analyze the Existing Build

Read these files to understand the project:

  • _tags - ocamlbuild compilation flags and package dependencies
  • pkg/pkg.ml - topkg package description
  • pkg/META - findlib metadata
  • *.mllib files - module lists for libraries
  • opam - package dependencies

2. Create dune-project

(lang dune 3.20)
(name <package-name>)
(generate_opam_files true)

3. Create Library dune Files

For each library (from .mllib files):

(library
 (name <library_name>)
 (public_name <package.subname>)
 (libraries <dependencies>))

For optional libraries (from pkg/pkg.ml):

(library
 (name <library_name>)
 (public_name <package.subname>)
 (optional)
 (libraries <dependencies>))

4. Handle Toplevel Init Files

Files like *_top_init.ml shouldn't be compiled as modules:

(library
 (name lib_name)
 (modules lib_module)  ; Explicitly list modules
 (libraries deps))

(install
 (package pkg)
 (section lib)
 (files lib_top_init.ml))

5. Handle Warnings

If the original code triggers warnings:

(library
 (name lib)
 (flags (:standard -w -27)))

Common warnings to suppress in vendored code:

  • -w -27 - unused variable

6. Create Test dune File

(test
 (name test_name)
 (libraries lib_name alcotest))

For optional tests:

(executable
 (name test_optional)
 (modules test_optional)
 (optional)
 (libraries lib some_optional_lib))

7. Update opam File

  1. Rename opam to <package>.opam
  2. Remove ocamlbuild/topkg dependencies
  3. Add dune:
depends: [
  "ocaml" {>= "4.14.0"}
  "dune" {>= "3.0"}
]
  1. Update build commands:
build: [
  ["dune" "subst"] {dev}
  ["dune" "build" "-p" name "-j" jobs]
  ["dune" "runtest" "-p" name "-j" jobs] {with-test}
  ["dune" "build" "@doc" "-p" name "-j" jobs] {with-doc}
]

8. Documentation dune File

If there's a doc/ directory:

(documentation
 (package <package-name>))

9. Remove ocamlbuild Files

Files to delete:

  • _tags
  • .merlin
  • pkg/pkg.ml
  • pkg/META
  • *.mllib files
  • *.itarget files
  • The pkg/ directory

Mapping Reference

ocamlbuilddune
_tags: package(foo)(libraries foo)
_tags: thread(libraries threads)
foo.mllib with Foo(library (name foo) (modules foo))
pkg/pkg.ml: Pkg.mllib ~cond:x(library ... (optional))
pkg/METAAuto-generated by dune
opam<package>.opam

Common Issues

"Library not found" for optional deps

Use (optional) on the library stanza.

Unused variable warnings

Add (flags (:standard -w -27)).

Module in wrong library

Use (modules ...) to explicitly list modules.

Toplevel init files

Exclude from library with (modules ...) and use (install ...).

Verification

After migration:

dune build @check    # Verify syntax
dune build           # Build project
dune runtest         # Run tests
dune build @doc      # Build docs

OCaml 5 Effects Design

Core Principle

Effects for control flow, exceptions for errors.

ConcernMechanismExample
Suspension (wait for data)Effectsperform Block, perform Yield
Error (EOF, malformed)Exceptionsraise End_of_file, Invalid_argument

Layered Design

Effects should be handled at the source level, not in protocol parsers:

Application
    ↓
Protocol parser (Binary.Reader, Cbor, etc.)
    ↓  raises exceptions on EOF/error
bytesrw (effect-agnostic)
    ↓  just calls pull function
Source (Eio flow, affect fd, Unix fd)
    ↓  performs effects for suspension
Effect handler (Eio scheduler, affect runtime)

Why This Matters

  • Parsers stay pure: No effect dependencies, easy to test
  • Sources control blocking: Handler decides wait vs fail vs timeout
  • Composability: Same parser works with any effect system

Effect Libraries

Eio

Effects are internal to the scheduler. User code looks synchronous:

(* Reading blocks via internal effects *)
let data = Eio.Flow.read flow buf

affect

Explicit effects for fiber scheduling:

type _ Effect.t +=
| Block : 'a block -> 'a Effect.t   (* suspension *)
| Await : await -> unit Effect.t    (* wait on fibers *)
| Yield : unit Effect.t             (* cooperative yield *)

(* Block has callbacks for scheduler integration *)
type 'a block = {
  block : handle -> unit;      (* register blocked fiber *)
  cancel : handle -> bool;     (* handle cancellation *)
  return : handle -> 'a        (* extract result *)
}

bytesrw

Effect-agnostic streaming. The pull function you provide can perform any effects:

(* bytesrw just calls your function *)
let reader = Bytesrw.Bytes.Reader.make my_pull_fn

(* If my_pull_fn performs Eio effects, they propagate *)
(* If my_pull_fn performs affect Block, they propagate *)
(* bytesrw doesn't care - it just calls the function *)

Integration Pattern

Wire effect-performing sources to effect-agnostic libraries:

(* With Eio *)
let reader = Bytesrw_eio.bytes_reader_of_flow flow in
let r = Binary.Reader.of_reader reader in
parse r  (* Eio effects happen in pull function *)

(* With affect *)
let pull () =
  let buf = Bytes.create 4096 in
  perform (Block { block; cancel; return = fun _ ->
    Slice.make buf ~first:0 ~length:n })
in
let reader = Bytesrw.Bytes.Reader.make pull in
parse (Binary.Reader.of_reader reader)

When EOF Is Reached

Slice.eod from bytesrw means final EOF - no more data will ever come.

  • Not "data not ready" (that's handled by effects in pull function)
  • Not "try again later" (source already waited via effects)
  • Parser should raise exception (EOF is an error condition)

Anti-Patterns

Don't: Define Await effect in protocol parsers

(* WRONG - parser shouldn't know about suspension *)
let get_byte t =
  if no_data then perform Await; ...

Do: Let the source handle suspension

(* RIGHT - parser just reads, source handles waiting *)
let get_byte t =
  match pull_next_slice t with  (* may perform effects *)
  | Some slice -> ...
  | None -> raise End_of_file   (* true EOF *)

References

Eio Concurrency

Core Concepts

Why Eio

Eio is an effects-based IO library for OCaml 5. Advantages over Lwt/Async:

  • Direct-style code: No monads, concurrent code looks like sequential code
  • Performance: Real stacks, no heap allocations to simulate continuations
  • Better backtraces: Exceptions show proper call traces
  • Platform optimization: Generic API with optimized backends (Linux io_uring, POSIX, Windows)

Capability-Based Design

Pass capabilities explicitly instead of using global resources:

type t = {
  net : _ Eio.Net.t;
  clock : _ Eio.Time.clock;
  fs : _ Eio.Path.t;
}

(* Function signature reveals what resources it needs *)
val connect : net:_ Eio.Net.t -> host:string -> connection

Do: Pass net, clock, fs explicitly—makes dependencies clear and testable.

Don't: Use global modules like Unix.gettimeofday or access ambient resources.

Structured Concurrency with Switches

Eio.Switch.run manages resource and fiber lifecycles:

Eio.Switch.run @@ fun sw ->
  let conn = connect ~sw server in
  (* conn automatically closed when sw exits *)
  process conn

Do: Create switches in the smallest possible scope.

Don't: Take a switch argument if you could create one internally.

Fibers

Lightweight concurrent units running on a single core:

(* Run two operations concurrently *)
Eio.Fiber.both
  (fun () -> download file1)
  (fun () -> download file2)

(* Only one fiber executes at a time until one performs an effect *)

Cancellation

Cancellation contexts form a tree. Uncaught exceptions propagate upward, cancelling siblings:

(* If one branch fails, the other gets Cancelled *)
Eio.Fiber.both
  (fun () -> may_fail ())
  (fun () -> other_work ())  (* receives Cancelled if may_fail raises *)

Use Cancel.protect for operations that must complete:

Eio.Cancel.protect @@ fun () ->
  (* This won't be cancelled even if parent is *)
  flush_and_close connection

Common Patterns

Concurrent Operations

(* Parallel map *)
let fetch_all_items api item_ids =
  Eio.Fiber.List.map (fun id -> Api.item_info api id) item_ids

(* Race with timeout *)
let with_timeout ~clock duration fn =
  Eio.Fiber.first
    (fun () -> Eio.Time.sleep clock duration; Error `Timeout)
    (fun () -> Ok (fn ()))

(* Fork background task attached to switch *)
Eio.Fiber.fork ~sw (fun () -> background_work ())

File Operations

let ( / ) = Eio.Path.( / )

(* Read file *)
let content = Eio.Path.load (fs / "config.json")

(* Write file with permissions *)
Eio.Path.save ~create:(`Or_truncate 0o600) (fs / "data.bin") content

(* Create directory if needed *)
Eio.Path.mkdirs ~exists_ok:true ~perm:0o755 (fs / "cache")

(* Clean up directory tree *)
Eio.Path.rmtree (fs / "tmp")

(* Check file type *)
match Eio.Path.kind ~follow:true path with
| `Directory -> ...
| `Regular_file -> ...
| `Not_found -> ...

Network Operations

(* TCP client *)
Eio.Net.connect ~sw net (`Tcp (addr, port))

(* TCP server *)
Eio.Net.run_server sock ~on_error:log_error
  ~max_connections:100
  (fun ~sw flow addr -> handle_client ~sw flow)

HTTPS with cohttp-eio

let https_handler uri raw_flow =
  let tls_config = create_tls_config () in
  let host = Uri.host uri |> Option.map Domain_name.(host_exn % of_string_exn) in
  Tls_eio.client_of_flow ?host tls_config raw_flow

let client = Cohttp_eio.Client.make net ~https:(Some https_handler)

Buffered Reading

Always use max_size to prevent memory exhaustion:

let body = Eio.Buf_read.(of_flow ~max_size:10_000_000 flow |> take_all)

Synchronization Primitives

Mutex:

let mutex = Eio.Mutex.create ()
Eio.Mutex.use_rw mutex (fun () -> shared_state := new_value)

Semaphore for rate limiting:

let limiter = Eio.Semaphore.make 10
let with_rate_limit fn =
  Eio.Semaphore.acquire limiter;
  Fun.protect ~finally:(fun () -> Eio.Semaphore.release limiter) fn

Stream for producer/consumer:

let queue = Eio.Stream.create 100
Eio.Stream.add queue item      (* producer *)
let item = Eio.Stream.take queue  (* consumer, blocks if empty *)

Condition variables (must check in loop):

let cond = Eio.Condition.create ()
let mutex = Eio.Mutex.create ()

(* Waiter - MUST use while loop *)
Eio.Mutex.use_rw ~protect:false mutex (fun () ->
  while not (check_condition ()) do
    Eio.Condition.await cond mutex
  done)

(* Signaler *)
Eio.Condition.broadcast cond

Integration with bytesrw

Bridge Eio flows to bytesrw for streaming binary parsing:

(* Eio flow → bytesrw reader *)
let reader_of_flow ?(buf_len = 4096) flow =
  let cs = Cstruct.create buf_len in
  let read () =
    match Eio.Flow.single_read flow cs with
    | 0 -> Bytesrw.Bytes.Slice.eod
    | n ->
        let buf = Cstruct.to_bytes (Cstruct.sub cs 0 n) in
        Bytesrw.Bytes.Slice.make buf ~first:0 ~length:n
    | exception End_of_file -> Bytesrw.Bytes.Slice.eod
  in
  Bytesrw.Bytes.Reader.make read

(* Then use with Binary.Reader *)
let r = Binary.Reader.of_reader (reader_of_flow flow)
let frame = Tc_frame.parse r  (* effects propagate through *)

Note: This involves a copy from Cstruct (Bigarray) to bytes (heap). Unavoidable until OCaml has non-moving bytes.

RNG Initialization

Critical for crypto: Initialize RNG before any crypto operations.

(* For Eio applications *)
Eio_main.run @@ fun env ->
  Mirage_crypto_rng_eio.run (module Mirage_crypto_rng.Fortuna) env @@ fun () ->
    (* RNG now available *)
    let iv = Mirage_crypto_rng.generate 12 in
    ...

(* For Unix applications (simpler but less integrated) *)
Mirage_crypto_rng_unix.initialize (module Mirage_crypto_rng.Fortuna)

Failure to initialize results in predictable random numbers, breaking crypto security.

Error Handling

Errors use Eio.Io (err, context) with nested error codes:

try
  Eio.Net.connect ~sw net addr
with
| Eio.Io (Eio.Net.E (Connection_failure _), _) ->
    (* Specific error *)
    Error `Connection_failed
| Eio.Io (Eio.Net.E _, _) ->
    (* Any network error *)
    Error `Network_error
| Eio.Io _ ->
    (* Any Eio error *)
    Error `Io_error

Add context when re-raising:

Eio.Exn.reraise_with_context exn "while connecting to %s" host

For tests, hide backend details:

Eio.Exn.Backend.show := false

Testing with Eio_mock

Library: eio.mock (not eio_mock)

Test Setup Pattern

let setup_test f () =
  Mirage_crypto_rng_unix.use_default ();  (* or initialize RNG *)
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let fs = Eio.Stdenv.fs env in
  let tmp = Eio.Path.(fs / Filename.get_temp_dir_name () / "test-dir") in
  (try Eio.Path.rmtree tmp with _ -> ());
  Eio.Path.mkdirs ~exists_ok:true ~perm:0o755 tmp;
  Fun.protect
    ~finally:(fun () -> try Eio.Path.rmtree tmp with _ -> ())
    (fun () -> f ~sw tmp)

let test_something = setup_test @@ fun ~sw tmp ->
  (* test code here *)

Mock Flow

let test_api_call () =
  Eio_main.run @@ fun _env ->
  let flow = Eio_mock.Flow.make "response" in
  (* IMPORTANT: Always end with `Raise End_of_file *)
  Eio_mock.Flow.on_read flow [
    `Return "{\"ok\": true}";
    `Raise End_of_file;
  ];
  (* use flow *)

Simulating Chunked Data

let test_partial_reads () =
  Eio_main.run @@ fun _env ->
  let flow = Eio_mock.Flow.make "chunked" in
  Eio_mock.Flow.on_read flow [
    `Return "\x00\x01";      (* First 2 bytes *)
    `Return "\x02\x03";      (* Next 2 bytes *)
    `Raise End_of_file;
  ];
  (* Parser must handle values spanning chunks *)

Mock Network

let test_network () =
  Eio_main.run @@ fun _env ->
  let net = Eio_mock.Net.make "mocknet" in
  let flow = Eio_mock.Flow.make "conn" in
  Eio_mock.Net.on_connect net [`Return flow];
  Eio_mock.Flow.on_read flow [`Return "data"; `Raise End_of_file];
  (* test network operations *)

Deadlock Detection

Eio_mock.Backend.run automatically detects deadlocks in tests.

Good and Bad Examples

Capability Passing

Bad: Using global/ambient resources

let fetch_data url =
  let now = Unix.gettimeofday () in  (* Global! *)
  let body = Http.get url in         (* Where does network come from? *)
  { timestamp = now; data = body }

Good: Explicit capability parameters

let fetch_data ~net ~clock url =
  let now = Eio.Time.now clock in
  Eio.Switch.run @@ fun sw ->
  let body = Http.get ~sw net url in
  { timestamp = now; data = body }

Switch Scope

Bad: Taking switch as argument when not needed

(* Why does this need a switch? Caller must manage lifetime *)
let read_config ~sw ~fs path =
  Eio.Path.load (fs / path)  (* No resources to manage! *)

Good: Create switch internally when needed

(* No switch needed - just reads a file *)
let read_config ~fs path =
  Eio.Path.load (fs / path)

(* Switch needed - manages connection lifetime *)
let with_connection ~sw ~net addr f =
  let conn = Eio.Net.connect ~sw net addr in
  f conn  (* conn closed when sw exits *)

Buffered Reading

Bad: No size limit allows memory exhaustion

let read_body flow =
  Eio.Buf_read.(of_flow flow |> take_all)  (* Unbounded! *)

Good: Always specify max_size

let read_body flow =
  Eio.Buf_read.(of_flow ~max_size:10_000_000 flow |> take_all)

Condition Variables

Bad: Single check can miss wakeups

Eio.Mutex.use_rw ~protect:false mutex (fun () ->
  if not (check_condition ()) then  (* Single if! *)
    Eio.Condition.await cond mutex;
  do_work ())

Good: Loop until condition is true

Eio.Mutex.use_rw ~protect:false mutex (fun () ->
  while not (check_condition ()) do  (* Loop handles spurious wakeups *)
    Eio.Condition.await cond mutex
  done;
  do_work ())

Error Handling

Bad: Catching all Eio errors indiscriminately

let connect addr =
  try Eio.Net.connect ~sw net addr
  with Eio.Io _ -> failwith "connection failed"  (* Loses context! *)

Good: Match specific errors, preserve context

let connect addr =
  try Eio.Net.connect ~sw net addr
  with
  | Eio.Io (Eio.Net.E (Connection_failure reason), _) ->
      Error (`Connection_failed reason)
  | Eio.Io (Eio.Net.E Connection_refused, _) ->
      Error `Refused
  | Eio.Io _ as exn ->
      Eio.Exn.reraise_with_context exn "connecting to %s" addr

Mock Testing

Bad: Mock flow without End_of_file hangs forever

let test_read () =
  Eio_main.run @@ fun _env ->
  let flow = Eio_mock.Flow.make "test" in
  Eio_mock.Flow.on_read flow [
    `Return "data";
    (* Missing End_of_file! Test hangs *)
  ];
  read_all flow

Good: Always end mock reads with End_of_file

let test_read () =
  Eio_main.run @@ fun _env ->
  let flow = Eio_mock.Flow.make "test" in
  Eio_mock.Flow.on_read flow [
    `Return "data";
    `Raise End_of_file;  (* Required! *)
  ];
  read_all flow

Cancellation Safety

Bad: Critical cleanup can be cancelled

Eio.Fiber.both
  (fun () -> may_fail ())
  (fun () ->
    do_work ();
    flush_and_close connection)  (* May be cancelled mid-flush! *)

Good: Protect critical operations

Eio.Fiber.both
  (fun () -> may_fail ())
  (fun () ->
    do_work ();
    Eio.Cancel.protect @@ fun () ->
    flush_and_close connection)  (* Completes even if cancelled *)

Common Gotchas

IssueProblemSolution
Racing readsBoth reads may complete at kernel levelDon't rely on Fiber.first for mutual exclusion
Signal handlersMost operations risk deadlockOnly Eio.Condition.broadcast is safe
Condition spurious wakeupMay wake without signalAlways check condition in while loop
Mutex in signal handlerRe-entrancy issuesUse conditions instead
Forgetting End_of_fileMock flow hangsAlways end mock reads with Raise End_of_file
Missing RNG initPredictable cryptoInitialize before any crypto operations

Library Integration

LibraryPurposeNotes
Lwt_eioRun Lwt + Eio togetherGradual migration path
Async_eioRun Async + Eio togetherExperimental
bytesrwStreaming byte parsingRequires copy (Cstruct→bytes)
cohttp-eioHTTP client/serverNative Eio support
tls-eioTLS connectionsUse with cohttp-eio for HTTPS
mirage-crypto-rngCrypto RNGUse .unix sublibrary for entropy

Best Practices

PracticeDescription
Capability passingPass net, clock, fs explicitly
Structured concurrencyUse Switch.run, keep scopes small
Handle errors at boundariesConvert Eio.Io to domain errors
Buffered readingUse Buf_read with max_size
Parallel with fibersFiber.List.map, Fiber.both, Fiber.first
Isolate blockingEio_unix.run_in_systhread for non-Eio blocking
Test with mocksEio_mock for deterministic tests
Initialize RNGBefore any crypto operations

References

OCaml Fuzz Testing with Crowbar

Core Philosophy

  1. One fuzz file per module: fuzz_foo.ml tests lib/foo.ml. Keeps tests organized and discoverable.
  2. Roundtrip everything: If you have encode and decode, test decode(encode(x)) = x.
  3. Crash-safety first: Parsers must never crash on arbitrary input, even malformed data.
  4. Boundary conditions matter: Test edge cases (0, max values, empty input, overflow).
  5. State machines need transition coverage: Test all valid and invalid state transitions.

Build Configuration

Simple single-file setup (per-package)

For standalone packages, use one fuzz file per package:

ocaml-foo/
├── lib/
├── fuzz/
│   ├── dune
│   └── fuzz_foo.ml
└── dune-project

fuzz/dune:

(executable
 (name fuzz_foo)
 (modules fuzz_foo)
 (libraries foo crowbar))

; Quick check with Crowbar (no AFL instrumentation)
(rule
 (alias fuzz)
 (deps fuzz_foo.exe)
 (action
  (run %{exe:fuzz_foo.exe})))

; AFL-instrumented build target (use with --profile=afl)
(rule
 (alias fuzz-afl)
 (deps
  (source_tree input)
  fuzz_foo.exe)
 (action
  (echo "AFL fuzzer built: %{exe:fuzz_foo.exe}\n")))

Seed corpus: Create fuzz/input/ with sample inputs:

mkdir -p fuzz/input
echo -n "" > fuzz/input/empty
# Add representative samples as seed inputs

fuzz/fuzz_foo.ml:

open Crowbar

let test_parse_crash_safety buf =
  ignore (Foo.parse buf);
  check true

let () =
  add_test ~name:"foo: parse crash safety" [ bytes ] test_parse_crash_safety

Multi-module setup (large codebases)

For larger projects with many modules:

(executable
 (name fuzz)
 (libraries crowbar borealis)
 (modules
  fuzz
  fuzz_common
  fuzz_foo
  fuzz_bar))

Main entry point (fuzz/fuzz.ml):

(* Force linking of modules that register tests via side effects *)
let () =
  Fuzz_common.run ();
  Fuzz_foo.run ();
  Fuzz_bar.run ()

Each fuzz module ends with:

let run () = ()

This ensures the module is linked and its add_test calls execute.


Style Guidelines

When writing fuzz tests, follow these conventions:

  1. Define test functions separately at the top of the file
  2. Register all tests at the end with grouped add_test calls
  3. Use bytes directly instead of custom generators
  4. Use a truncate helper to limit input size for protocol messages
  5. Return () directly - no need for check true in most cases
  6. Add Crypto_rng_unix.use_default () at the top if crypto is used

Example structure

(** Fuzz tests for Foo module. *)

open Crowbar
open Fuzz_common

(** Decode - must not crash on arbitrary input. *)
let test_decode buf =
  let buf = truncate buf in
  let _ = Foo.decode (to_bytes buf) in
  ()

(** Roundtrip - valid values must round-trip. *)
let test_roundtrip buf =
  let buf = truncate buf in
  match Foo.decode (to_bytes buf) with
  | Error _ -> ()
  | Ok v ->
      let encoded = Foo.encode v in
      match Foo.decode encoded with
      | Error _ -> fail "re-decode failed"
      | Ok v' -> if v <> v' then fail "roundtrip mismatch"

(** Pretty-print - must not crash. *)
let test_pp n =
  let v = Foo.of_int (n mod 4) in
  let _ = Format.asprintf "%a" Foo.pp v in
  ()

(* All add_test calls in run function - no side effects at module init *)
let run () =
  add_test ~name:"foo: decode crash safety" [ bytes ] test_decode;
  add_test ~name:"foo: roundtrip" [ bytes ] test_roundtrip;
  add_test ~name:"foo: pp" [ uint8 ] test_pp

Main entry point (fuzz/fuzz.ml):

(* Initialize crypto RNG if needed by any module *)
let () = Crypto_rng_unix.use_default ()

(* Register all fuzz tests *)
let () =
  Fuzz_common.run ();
  Fuzz_foo.run ();
  Fuzz_bar.run ()

Test Patterns

1. Crash-safety test (parsers must not crash)

open Crowbar
open Fuzz_common

(** Decode - must not crash on arbitrary input. *)
let test_decode buf =
  let buf = truncate buf in
  let _ = Foo.decode (to_bytes buf) in
  ()

(** Decode with exceptions - must not crash. *)
let test_decode_exn buf =
  let buf = truncate buf in
  (try ignore (Foo.decode_exn (to_bytes buf)) with _ -> ());
  ()

let run () =
  add_test ~name:"foo: decode crash safety" [ bytes ] test_decode;
  add_test ~name:"foo: decode_exn crash safety" [ bytes ] test_decode_exn

Key points:

  • Use bytes generator for arbitrary binary input (produces string type)
  • Use ignore to discard results without warnings
  • Use | exception _ -> () to catch any exceptions
  • check true signals test passed

2. Roundtrip test (encode/decode pairs)

(** Roundtrip - valid values must round-trip. *)
let test_roundtrip buf =
  let buf = truncate buf in
  match Foo.decode (to_bytes buf) with
  | Error _ -> ()  (* Invalid input is fine *)
  | Ok original ->
      let encoded = Foo.encode original in
      match Foo.decode encoded with
      | Error _ -> fail "re-decode failed"
      | Ok decoded ->
          if original <> decoded then fail "roundtrip mismatch"

let run () =
  add_test ~name:"foo: roundtrip" [ bytes ] test_roundtrip

Key points:

  • If initial decode fails, that's OK (input was invalid)
  • If re-decode fails after encode, that's a bug
  • Compare original and decoded values

3. Constrained type roundtrip (smart constructors)

(** APID roundtrip - valid values must round-trip. *)
let test_apid_roundtrip n =
  match Apid.of_int n with
  | None -> if n >= 0 && n <= 2047 then fail "should accept valid value"
  | Some apid ->
      let n' = Apid.to_int apid in
      if n <> n' then fail "roundtrip mismatch"

let run () =
  add_test ~name:"apid: roundtrip" [ range 2048 ] test_apid_roundtrip

4. Boundary tests

(** Max valid value. *)
let test_max_valid () =
  match Apid.of_int 2047 with
  | None -> fail "2047 should be valid"
  | Some apid -> if Apid.to_int apid <> 2047 then fail "value mismatch"

(** Min valid value. *)
let test_min_valid () =
  match Apid.of_int 0 with
  | None -> fail "0 should be valid"
  | Some apid -> if Apid.to_int apid <> 0 then fail "value mismatch"

let run () =
  add_test ~name:"apid: max_valid" [ const () ] test_max_valid;
  add_test ~name:"apid: min_valid" [ const () ] test_min_valid

Key points:

  • Use [ const () ] for tests with no random input
  • Never use [] as generator list (causes type error)

5. Invalid input rejection

(** Values above max must be rejected. *)
let test_invalid_above n =
  let invalid = 2048 + n in
  match Apid.of_int invalid with
  | None -> ()
  | Some _ -> fail "should reject values > 2047"

(** Negative values must be rejected. *)
let test_invalid_negative n =
  let invalid = -(n + 1) in
  match Apid.of_int invalid with
  | None -> ()
  | Some _ -> fail "should reject negative values"

let run () =
  add_test ~name:"apid: invalid_above" [ range 1000 ] test_invalid_above;
  add_test ~name:"apid: invalid_negative" [ range 1000 ] test_invalid_negative

6. Pretty-printer safety

(** Pretty-print - must not crash. *)
let test_pp buf =
  let buf = truncate buf in
  match Foo.decode (to_bytes buf) with
  | Error _ -> ()
  | Ok v -> let _ = Format.asprintf "%a" Foo.pp v in ()

let run () =
  add_test ~name:"foo: pp" [ bytes ] test_pp

7. State machine transitions

(** Test valid state transitions. *)
let test_activate_pending kid algo material_buf =
  let material = to_bytes material_buf in
  if Bytes.length material = 0 then ()
  else
    let key = Key.v ~kid ~algorithm:algo ~material in
    match Key.activate key with
    | Error _ -> ()  (* May fail if material invalid *)
    | Ok active_key ->
        if Key.state active_key <> Key.Active then fail "wrong state"

(** Test invalid state transitions return errors. *)
let test_activate_empty_fails kid algo =
  let key = Key.empty ~kid ~algorithm:algo in
  match Key.activate key with
  | Ok _ -> fail "should fail on Empty key"
  | Error (Key.Invalid_state_transition _) -> ()
  | Error _ -> fail "wrong error type"

let run () =
  add_test ~name:"key: activate Pending" [ uint8; uint8; bytes ]
    test_activate_pending;
  add_test ~name:"key: activate Empty fails" [ uint8; uint8 ]
    test_activate_empty_fails

8. Unit conversion roundtrips

(** Nanoseconds roundtrip. *)
let test_ns_roundtrip n =
  let d = Duration.of_ns n in
  let n' = Duration.to_ns d in
  if n <> n' then fail "ns roundtrip mismatch"

(** Microseconds to milliseconds conversion. *)
let test_us_to_ms n =
  let us = Int64.of_int n in
  let d = Duration.of_us us in
  let ms = Duration.to_ms d in
  let expected = Int64.div us 1000L in
  if ms <> expected then fail "us to ms conversion failed"

let run () =
  add_test ~name:"duration: ns_roundtrip" [ int64 ] test_ns_roundtrip;
  add_test ~name:"duration: us_to_ms" [ range 1000000 ] test_us_to_ms

9. Filestore/resource operations

(** Test create/exists invariant. *)
let test_create_exists name_buf =
  let name = Bytes.to_string (to_bytes name_buf) in
  if String.length name = 0 then ()
  else
    let fs = Filestore.in_memory () in
    match Filestore.create fs name with
    | Error _ -> ()
    | Ok () ->
        if not (Filestore.exists fs name) then
          fail "created file should exist"

let run () =
  add_test ~name:"filestore: create_exists" [ bytes ] test_create_exists

Common Module: fuzz_common.ml

(** Common utilities for fuzz tests. *)

open Crowbar

let to_bytes buf =
  let len = String.length buf in
  let b = Bytes.create len in
  Bytes.blit_string buf 0 b 0 len;
  b

let catch_invalid_arg f =
  try f () with Invalid_argument _ -> check true

let run () = ()

Generators Reference

GeneratorTypeUse for
bytesstringArbitrary binary data
uint8int0-255
int8int-128 to 127
int32int32Full int32 range
int64int64Full int64 range
range nint0 to n-1
boolbooltrue/false
const v'aFixed value (for no-input tests)
list gen'a listLists of generated values
option gen'a optionSome/None

File Organization

fuzz/
├── fuzz.ml              # Main entry, links all modules
├── fuzz_common.ml       # Shared utilities
├── fuzz_tc_frame.ml     # Tests for lib/frames/tc_frame.ml
├── fuzz_tm_frame.ml     # Tests for lib/frames/tm_frame.ml
├── fuzz_apid.ml         # Tests for lib/frames/apid.ml
├── fuzz_keyid.ml        # Tests for lib/sdls/keyid.ml
└── ...

Naming convention: fuzz_<module>.ml tests lib/**/<module>.ml


Running Fuzz Tests

Without AFL (quick check)

dune exec fuzz/fuzz.exe
# Or use the alias:
dune build @fuzz

With AFL (thorough fuzzing) - Manual

dune build fuzz/fuzz.exe
mkdir -p fuzz/input
echo -n "" > fuzz/input/empty
afl-fuzz -m none -i fuzz/input -o _fuzz -- \
  _build/default/fuzz/fuzz.exe @@

With crow (recommended for multiple targets)

Use crow to orchestrate long-running AFL campaigns across multiple targets:

# Initialize workspace (creates dune-workspace with afl profile if needed)
crow init

# Build all fuzz targets with AFL instrumentation
dune build --profile=afl @fuzz-afl

# List discovered fuzz targets
crow list

# Start a campaign with 8 CPUs for 24 hours
crow start --cpus=8 --duration=24h

# Monitor progress
crow status

# Stop the campaign
crow stop

crow automatically:

  • Discovers all */fuzz/dune files with crowbar dependencies
  • Allocates CPU cores across targets (main + secondary instances)
  • Creates/updates dune-workspace with AFL profile if missing
  • Tracks campaign state and aggregates statistics

Check for duplicate test names

grep -h 'add_test ~name:"' fuzz/fuzz_*.ml | \
  sed 's/.*~name:"\([^"]*\)".*/\1/' | sort | uniq -d

Coverage Checklist

For each module with a public API (.mli file):

  • Crash safety: All decode_*, parse_*, read_*, of_* functions
  • Roundtrip: All encode/decode, to_*/of_* pairs
  • Boundaries: Min/max valid values, edge cases
  • Invalid input: Values outside valid range rejected
  • State machines: All transitions (valid and invalid)
  • Pretty-printers: All pp_* functions don't crash
  • Comparison: equal and compare are consistent

Priority Order

When adding fuzz tests to a codebase:

  1. Security-critical: Crypto primitives, authentication, key management
  2. Protocol parsers: Wire format decoders, frame parsers
  3. State machines: Lifecycle transitions, session state
  4. Constrained types: Smart constructors, ID validators
  5. Utility functions: Encoding helpers, time conversions

Common Mistakes

Wrong: Empty generator list with function

(* ERROR: This expression should not be a function *)
add_test ~name:"test" [] @@ fun () -> ...

Right: Use const () for no-input tests

add_test ~name:"test" [ const () ] @@ fun () -> ...

Wrong: Ignoring error cases

(* BAD: Only tests happy path *)
add_test ~name:"foo: decode" [ bytes ] @@ fun buf ->
  let Ok v = Foo.decode (to_bytes buf) in
  check true

Right: Handle both Ok and Error

add_test ~name:"foo: decode" [ bytes ] @@ fun buf ->
  (match Foo.decode (to_bytes buf) with
   | Ok _ -> ()
   | Error _ -> ());
  check true

Wrong: Asserting on invalid input

(* BAD: Fails on invalid input *)
add_test ~name:"foo: roundtrip" [ bytes ] @@ fun buf ->
  match Foo.decode (to_bytes buf) with
  | Error _ -> fail "decode failed"  (* Wrong! Invalid input is expected *)
  | Ok v -> ...

Right: Accept invalid input gracefully

add_test ~name:"foo: roundtrip" [ bytes ] @@ fun buf ->
  match Foo.decode (to_bytes buf) with
  | Error _ -> check true  (* Invalid input is fine *)
  | Ok v -> ...

Expected Outputs

When adding fuzz tests, produce:

  1. New fuzz file: fuzz/fuzz_<module>.ml with comprehensive tests
  2. Update fuzz.ml: Add Fuzz_<module>.run () call
  3. Verify build: dune build succeeds
  4. No duplicates: Test names are unique across all fuzz files
  5. Coverage summary: List of tests added and what they cover

Jsont JSON Encoding/Decoding

Dependencies

(libraries jsont jsont.bytesrw)

Core Patterns

Simple Object Codec

Map a JSON object to an OCaml record using Jsont.Object.map with mem for required fields:

type header = {
  message_id : string;
  method_ : string;
  timestamp : int;
}

let header_codec =
  Jsont.Object.map ~kind:"header"
    (fun message_id method_ timestamp -> { message_id; method_; timestamp })
  |> Jsont.Object.mem "messageId" Jsont.string ~enc:(fun h -> h.message_id)
  |> Jsont.Object.mem "method" Jsont.string ~enc:(fun h -> h.method_)
  |> Jsont.Object.mem "timestamp" Jsont.int ~enc:(fun h -> h.timestamp)
  |> Jsont.Object.finish

Optional Fields

Use opt_mem for optional JSON fields. The constructor receives 'a option:

type config = {
  name : string;
  timeout : int;  (* default if missing *)
}

let config_codec =
  Jsont.Object.map ~kind:"config"
    (fun name timeout_opt ->
      { name; timeout = Option.value ~default:30 timeout_opt })
  |> Jsont.Object.mem "name" Jsont.string ~enc:(fun c -> c.name)
  |> Jsont.Object.opt_mem "timeout" Jsont.int ~enc:(fun c -> Some c.timeout)
  |> Jsont.Object.finish

Skip Unknown Fields

Use skip_unknown before finish to ignore extra JSON fields (tolerant parsing):

let tolerant_codec =
  Jsont.Object.map ~kind:"data" (fun id -> { id })
  |> Jsont.Object.mem "id" Jsont.string ~enc:(fun d -> d.id)
  |> Jsont.Object.skip_unknown  (* ignore extra fields *)
  |> Jsont.Object.finish

Nested Objects

Compose codecs for nested structures:

type request = { header : header; payload : payload }

let request_codec payload_codec =
  Jsont.Object.map ~kind:"request" (fun header payload -> { header; payload })
  |> Jsont.Object.mem "header" header_codec ~enc:(fun r -> r.header)
  |> Jsont.Object.mem "payload" payload_codec ~enc:(fun r -> r.payload)
  |> Jsont.Object.finish

Lists

Use Jsont.list for JSON arrays:

type response = { items : item list }

let response_codec =
  Jsont.Object.map ~kind:"response" (fun items -> { items })
  |> Jsont.Object.mem "items" (Jsont.list item_codec) ~enc:(fun r -> r.items)
  |> Jsont.Object.finish

String Maps

Use Jsont.Object.as_string_map for objects with dynamic keys:

module String_map = Map.Make(String)

(* JSON: {"key1": "value1", "key2": "value2"} *)
let string_map_codec = Jsont.Object.as_string_map Jsont.string

(* JSON: {"group1": [...], "group2": [...]} *)
let groups_codec = Jsont.Object.as_string_map (Jsont.list item_codec)

Empty Object

For payloads that don't carry data:

let empty_payload_codec : unit Jsont.t =
  Jsont.Object.map ~kind:"empty" ()
  |> Jsont.Object.skip_unknown
  |> Jsont.Object.finish

Custom Value Mapping

Use Jsont.map to transform between types:

type device_type = Sonos | Meross | Other

let device_from_string =
  Jsont.map ~kind:"device_type"
    ~dec:(function "sonos" -> Sonos | "meross" -> Meross | _ -> Other)
    ~enc:(function Sonos -> "sonos" | Meross -> "meross" | Other -> "other")
    Jsont.string

Polymorphic Decoding with any

Handle multiple JSON shapes for backwards compatibility:

(* Device can be string (old format) or object (new format) *)
let device_compat_codec =
  Jsont.any ~kind:"device"
    ~dec_string:device_from_string_codec  (* handles "192.168.1.1" *)
    ~dec_object:device_object_codec       (* handles {"ip": "...", "type": "..."} *)
    ~enc:(fun _ -> device_object_codec)   (* always encode as object *)
    ()

Null Values

Use Jsont.null for endpoints returning null:

(* For DELETE endpoints that return null on success *)
match delete http ~sw token endpoint (Jsont.null ()) with
| Ok () -> ...

Generic JSON

Use Jsont.json to preserve arbitrary JSON:

type characteristic = {
  iid : int;
  value : Jsont.json option;  (* preserve any JSON value *)
}

let char_codec =
  Jsont.Object.map ~kind:"char" (fun iid value -> { iid; value })
  |> Jsont.Object.mem "iid" Jsont.int ~enc:(fun c -> c.iid)
  |> Jsont.Object.opt_mem "value" Jsont.json ~enc:(fun c -> c.value)
  |> Jsont.Object.finish

Encoding and Decoding

Use Jsont_bytesrw for string-based encoding/decoding:

(* Decode JSON string to OCaml value *)
let decode codec s = Jsont_bytesrw.decode_string codec s
(* Returns: ('a, Jsont.Error.t) result *)

(* Encode OCaml value to JSON string *)
let encode codec v =
  match Jsont_bytesrw.encode_string codec v with
  | Ok s -> s
  | Error _ -> "{}"  (* fallback for encoding errors *)

(* Usage *)
match Jsont_bytesrw.decode_string config_codec json_string with
| Ok config -> (* use config *)
| Error e -> (* handle error *)

match Jsont_bytesrw.encode_string config_codec config with
| Ok json_str -> (* send json_str *)
| Error _ -> (* handle error *)

Common Helpers

Define module-level helpers for cleaner code:

let decode codec s = Jsont_bytesrw.decode_string codec s

let encode codec v =
  match Jsont_bytesrw.encode_string codec v with
  | Ok s -> s
  | Error _ -> ""

Base Types Reference

OCaml TypeJsont CodecJSON Type
stringJsont.stringstring
intJsont.intnumber
floatJsont.numbernumber
boolJsont.boolboolean
'a listJsont.list codecarray
'a optionJsont.option codecvalue or null
unitJsont.null ()null
genericJsont.jsonany JSON

Good and Bad Examples

Missing ~kind

Bad: No kind makes error messages unhelpful

let config_codec =
  Jsont.Object.map (fun name -> { name })  (* No ~kind *)
  |> Jsont.Object.mem "name" Jsont.string ~enc:(fun c -> c.name)
  |> Jsont.Object.finish
(* Error: "expected string" - but where? *)

Good: Descriptive kind for clear errors

let config_codec =
  Jsont.Object.map ~kind:"config" (fun name -> { name })
  |> Jsont.Object.mem "name" Jsont.string ~enc:(fun c -> c.name)
  |> Jsont.Object.finish
(* Error: "config: expected string for member 'name'" *)

Strict vs Tolerant Parsing

Bad: Strict parsing breaks when API adds fields

(* API adds "created_at" field, your code breaks *)
let user_codec =
  Jsont.Object.map ~kind:"user" (fun id name -> { id; name })
  |> Jsont.Object.mem "id" Jsont.int ~enc:(fun u -> u.id)
  |> Jsont.Object.mem "name" Jsont.string ~enc:(fun u -> u.name)
  |> Jsont.Object.finish  (* No skip_unknown! *)

Good: Tolerant parsing ignores unknown fields

let user_codec =
  Jsont.Object.map ~kind:"user" (fun id name -> { id; name })
  |> Jsont.Object.mem "id" Jsont.int ~enc:(fun u -> u.id)
  |> Jsont.Object.mem "name" Jsont.string ~enc:(fun u -> u.name)
  |> Jsont.Object.skip_unknown  (* Ignore extra fields *)
  |> Jsont.Object.finish

Handling Optional Fields

Bad: Nullable field without default causes runtime errors

(* Field missing → decode fails *)
let config_codec =
  Jsont.Object.map ~kind:"config" (fun timeout -> { timeout })
  |> Jsont.Object.mem "timeout" Jsont.int ~enc:(fun c -> c.timeout)
  |> Jsont.Object.finish

Good: Use opt_mem with sensible default

let config_codec =
  Jsont.Object.map ~kind:"config"
    (fun timeout_opt -> { timeout = Option.value ~default:30 timeout_opt })
  |> Jsont.Object.opt_mem "timeout" Jsont.int ~enc:(fun c -> Some c.timeout)
  |> Jsont.Object.finish

Codec Composition

Bad: Monolithic codec with duplicated patterns

let request_codec =
  Jsont.Object.map ~kind:"request"
    (fun msg_id method_ ts payload_id payload_data ->
      { header = { message_id = msg_id; method_; timestamp = ts };
        payload = { id = payload_id; data = payload_data } })
  |> Jsont.Object.mem "messageId" Jsont.string ~enc:(fun r -> r.header.message_id)
  |> Jsont.Object.mem "method" Jsont.string ~enc:(fun r -> r.header.method_)
  (* ... lots more fields mixed together *)

Good: Compose small, reusable codecs

let header_codec =
  Jsont.Object.map ~kind:"header"
    (fun message_id method_ timestamp -> { message_id; method_; timestamp })
  |> Jsont.Object.mem "messageId" Jsont.string ~enc:(fun h -> h.message_id)
  |> Jsont.Object.mem "method" Jsont.string ~enc:(fun h -> h.method_)
  |> Jsont.Object.mem "timestamp" Jsont.int ~enc:(fun h -> h.timestamp)
  |> Jsont.Object.finish

let request_codec =
  Jsont.Object.map ~kind:"request" (fun header payload -> { header; payload })
  |> Jsont.Object.mem "header" header_codec ~enc:(fun r -> r.header)
  |> Jsont.Object.mem "payload" payload_codec ~enc:(fun r -> r.payload)
  |> Jsont.Object.finish

Encoding Error Handling

Bad: Silently returning empty object on error

let encode codec v =
  match Jsont_bytesrw.encode_string codec v with
  | Ok s -> s
  | Error _ -> "{}"  (* Hides the error! *)

Good: Propagate or log encoding errors

let encode codec v =
  match Jsont_bytesrw.encode_string codec v with
  | Ok s -> Ok s
  | Error e ->
      Log.err (fun m -> m "JSON encode failed: %a" Jsont.Error.pp e);
      Error (`Encode_error e)

Best Practices

  1. Always use ~kind: Provide descriptive kind names for better error messages
  2. Use skip_unknown for external APIs: Be tolerant of extra fields from third-party services
  3. Prefer opt_mem with defaults: Handle missing fields gracefully with Option.value ~default:
  4. Compose small codecs: Build complex structures from simple, reusable codecs
  5. Define helper functions: Create decode/encode helpers at module level for cleaner usage

OCaml Logs Patterns

The logs library provides structured logging with per-module sources.

Module Setup

Every module that logs should create its own source:

let log_src = Logs.Src.create "project.module_name"
module Log = (val Logs.src_log log_src : Logs.LOG)

This is the standard idiom. Do NOT attempt to abstract or deduplicate this boilerplate.

Log Levels

LevelFunctionUse Case
AppLog.appAlways shown to user (startup, completion)
ErrorLog.errHandled but critical errors
WarningLog.warnPotential issues, operation continues
InfoLog.infoState transitions, progress
DebugLog.debugVerbose debugging details

Basic Logging

Log.info (fun m -> m "Processing %d items" count);
Log.err (fun m -> m "Failed to connect: %s" reason);
Log.debug (fun m -> m "Request: %a" Request.pp req)

Structured Tags

Add context with tags for filtering/analysis:

Log.info (fun m ->
    m "Event received: %s" event_type
      ~tags:(Logs.Tag.add "channel_id" channel Logs.Tag.empty))

Reporter Setup (bin/)

In CLI applications, set up the reporter in bin/common.ml:

let setup_log style_renderer level =
  Fmt_tty.setup_std_outputs ?style_renderer ();
  Logs.set_level level;
  Logs.set_reporter (Logs_fmt.reporter ())

open Cmdliner

let setup_log =
  Term.(const setup_log
        $ Fmt_cli.style_renderer ()
        $ Logs_cli.level ())

system_prompt

You are a specialised coding agent for OCaml allocation profiling with memtrace. Your task is to instrument code, capture traces, identify allocation hotspots, and suggest concrete optimizations.

You must:

  • Keep tracing gated behind the MEMTRACE environment variable.
  • Target specific tests or benchmarks to isolate hotspots.
  • Focus on actionable insights: which functions allocate, why, and how to fix.
  • Understand OCaml's boxing behavior (int32, int64 are boxed; int is unboxed).

instructions

When to apply this skill

Use this skill when:

  • Investigating why a function allocates more than expected
  • Identifying boxing overhead (int32, int64, floats in arrays)
  • Optimizing hot paths in parsing/serialization code
  • Comparing allocation behavior before and after changes

Do not use this skill for:

  • Exact allocation counting (memtrace is statistical)
  • Performance timing (use Sys.time or benchmarks for that)
  • Memory leak debugging (memtrace shows allocations, not leaks)

Instrumentation pattern

Add to the main entrypoint, before any work begins:

let () =
  Memtrace.trace_if_requested ();
  (* rest of program *)

For Alcotest test suites:

(* test/test.ml *)
let () =
  Memtrace.trace_if_requested ();
  Alcotest.run "suite-name" [
    Test_foo.suite;
    Test_bar.suite;
  ]

Rules:

  • Call once, at program start
  • No ~context argument needed for simple cases
  • Never enable tracing unconditionally

Build configuration

Add memtrace to the test executable in dune:

(test
 (name test)
 (libraries memtrace alcotest ...))

Or for a standalone executable:

(executable
 (name main)
 (libraries memtrace ...))

Running with memtrace

Basic usage:

MEMTRACE=trace.ctf dune exec -- path/to/exe

For Alcotest, target a specific test to isolate allocations:

# Run specific test suite
MEMTRACE=trace.ctf dune exec -- test/test.exe test "binary"

# Run specific test by index within suite
MEMTRACE=trace.ctf dune exec -- test/test.exe test "binary" 68

# List available tests first
dune exec -- test/test.exe test list

The trace file (.ctf) is binary but contains embedded strings showing:

  • Source file paths and line numbers
  • Function names and call stacks
  • Allocation counts and sizes

Analyzing traces

With memtrace-viewer (GUI):

memtrace-viewer trace.ctf
# Opens browser at http://localhost:8080

With memtrace-hotspot (CLI):

opam install memtrace-hotspot
memtrace-hotspot trace.ctf

Reading raw trace output:

The MEMTRACE environment produces summary output showing:

  • Total allocations in bytes
  • Top allocation sites by percentage
  • Call stacks leading to allocations

Example output:

76.3 MB total allocations
  30.2% lib/binary.ml:194 Bytes.get_int32_be
  15.1% lib/binary.ml:210 Bytes.get_int64_be
  ...

Common hotspots and fixes

1. Int32/Int64 boxing

Problem: Bytes.get_int32_be returns int32 which is always boxed.

(* SLOW: boxes on every call *)
let v = Bytes.get_int32_be buf off

Fix: Read bytes individually, box only at the end:

(* FAST: single box at the end *)
let read_uint32_be buf off =
  let b0 = Bytes.get_uint8 buf off in
  let b1 = Bytes.get_uint8 buf (off + 1) in
  let b2 = Bytes.get_uint8 buf (off + 2) in
  let b3 = Bytes.get_uint8 buf (off + 3) in
  Int32.of_int ((b0 lsl 24) lor (b1 lsl 16) lor (b2 lsl 8) lor b3)

2. Closure allocation in loops

Problem: let* and partial application create closures.

(* SLOW: closure per iteration *)
List.iter (fun x -> process key x) items

Fix: Inline or use direct recursion:

(* FAST: no closure *)
let rec loop = function
  | [] -> ()
  | x :: xs -> process key x; loop xs
in loop items

3. Array bounds checking

For proven-safe indices, use unsafe access:

(* Lookup table - indices always valid *)
Array.unsafe_get table ((byte lsr 4) land 0xF)

Optimization workflow

  1. Baseline: Run benchmark with memtrace, note total allocations
  2. Identify: Find top allocation sites (>10% of total)
  3. Analyze: Determine if allocations are necessary or avoidable
  4. Fix: Apply targeted optimizations (see common fixes above)
  5. Validate: Re-run with memtrace, compare totals

Example from this codebase:

  • Before: 76.3 MB total (Bytes.get_int32_be = 30%)
  • After: 53.4 MB total (byte-by-byte reads)
  • Reduction: 30%

Considerations for int32/int64 APIs

If your API returns int32 or int64, boxing is unavoidable at the boundary. Consider:

  • Optint.Int63.t: Unboxed on 64-bit platforms, fits in native int
  • Returning int: If values fit in 31/63 bits, avoid boxed types entirely
  • Streaming APIs: Process data without intermediate boxed values

Check what other libraries do:

  • bytesrw: Uses int where possible, int64 only when necessary

Expected outputs

When this skill is invoked, produce:

  1. Instrumentation patch (single Memtrace.trace_if_requested () call)
  2. Dune changes if memtrace not already linked
  3. Exact command to run targeted benchmark with tracing
  4. Analysis of trace output identifying top hotspots
  5. Concrete code changes to reduce allocations
  6. Before/after comparison showing improvement

Avoiding common mistakes

  • Wrong process: Trace the worker, not the test harness
  • Too broad: Target specific tests, not entire suites
  • Comparing apples to oranges: Same workload, same sampling rate
  • Premature optimization: Focus on hotspots >10% of allocations
  • Breaking APIs: Don't change public signatures just to avoid boxing

OCaml to NPM Publishing

When to Use This Skill

Invoke this skill when:

  • Setting up npm publishing for OCaml projects
  • Configuring js_of_ocaml or wasm_of_ocaml
  • Discussing browser targets for OCaml
  • Creating the npm branch workflow

Branch Structure

main branch     - OCaml source code, dune build files, opam packages
npm branch      - Built JavaScript/WASM assets, package.json, README for npm

The npm branch is an orphan branch with no shared history.

Dune Build Rules

Library with Browser Bindings

In lib/js/dune:

; Library compiled to bytecode (required for js_of_ocaml)
(library
 (name mylib_js)
 (public_name mylib-js)
 (libraries mylib brr)
 (modes byte)
 (modules mylib_js))

; Executable compiled to both JS and WASM
(executable
 (name mylib_js_main)
 (libraries mylib_js)
 (js_of_ocaml)
 (modes js wasm)
 (modules mylib_js_main))

; Friendly filename for JS
(rule
 (targets mylib.js)
 (deps mylib_js_main.bc.js)
 (action (copy %{deps} %{targets})))

; Friendly filename for WASM
(rule
 (targets mylib.wasm.js)
 (deps mylib_js_main.bc.wasm.js)
 (action (copy %{deps} %{targets})))

; Install web assets
(install
 (package mylib-js)
 (section share)
 (files
  mylib.js
  mylib.wasm.js
  (glob_files_rec (mylib_js_main.bc.wasm.assets/* with_prefix mylib_js_main.bc.wasm.assets))))

dune-project Package

(package
 (name mylib-js)
 (synopsis "Browser library via js_of_ocaml/wasm_of_ocaml")
 (depends
  (ocaml (>= 5.1.0))
  (mylib (= :version))
  (js_of_ocaml (>= 5.0))
  (js_of_ocaml-ppx (>= 5.0))
  (wasm_of_ocaml-compiler (>= 5.0))
  (brr (>= 0.0.6))))

Creating the NPM Branch

# Create orphan branch
git switch --orphan npm

# Add npm-specific files
git add package.json README.md LICENSE release.sh .gitignore
git commit -m "Initial npm package setup"

# Switch back
git checkout main

NPM Branch Files

See templates/ for:

  • package.json.template
  • release.sh.template

package.json

{
  "name": "mylib-jsoo",
  "version": "1.0.0",
  "description": "Description here",
  "browser": "mylib.js",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/user/repo.git#npm"
  },
  "files": [
    "mylib.js",
    "mylib.wasm.js",
    "mylib_js_main.bc.wasm.assets/",
    "README.md",
    "LICENSE"
  ]
}

Key points:

  • Use "browser" not "main" (js_of_ocaml is browser-only)
  • Point repository URL to #npm branch
  • Include WASM assets directory

release.sh

Script to copy built assets from main branch to npm branch.

Workflow Summary

  1. Develop on main branch (OCaml source)
  2. Build: dune build @install
  3. Switch to npm branch
  4. Run ./release.sh to copy built assets
  5. Update version in package.json
  6. Commit and npm publish

README for npm

Focus on browser usage:

  1. Clear browser-only notice
  2. Installation via npm
  3. Browser usage with <script> tags
  4. Both JS and WASM examples
  5. Browser compatibility requirements

OCaml Documentation (odoc) Skill

When to Use

Use this skill when fixing odoc documentation warnings, typically from dune build @doc.

This skill covers odoc mechanics only. Load the doc-style skill as well whenever you write or reword the prose of a doc comment.

Prerequisites: This skill covers odoc v3 syntax which is not yet in released versions of dune or odoc. You need:

Reference Syntax

Use path-based disambiguation {!Path.To.kind-Name} rather than {!kind:Path.To.Name}:

(* Correct *)
{!Jsont.exception-Error}
{!Proto.Incoming.t.constructor-Message}
{!module-Foo.module-type-Bar.exception-Baz}

(* Incorrect *)
{!exception:Jsont.Error}
{!constructor:Proto.Incoming.t.Message}

This allows disambiguation at any position in the path.

Reference Kinds

  • module- for modules
  • type- for types
  • val- for values
  • exception- for exceptions
  • constructor- for variant constructors
  • field- for record fields
  • module-type- for module types

Cross-Package References

When odoc cannot resolve a reference to another package, add a documentation dependency in dune-project:

(package
 (name mypackage)
 ...
 (documentation (depends other-package)))

Do NOT convert doc references {!Foo} to code markup [Foo] - this loses the hyperlink.

Cross-Library References (Same Package)

When referencing modules from another library in the same package, use the full path through re-exported modules.

Example: If claude.mli has module Proto = Proto, reference proto modules as {!Proto.Incoming} not {!Incoming}.

Missing Module Exports

If odoc reports "Couldn't find X" where X is the last path component:

  1. Check if the module is re-exported in the parent module's .mli
  2. Add module X = X to the parent's .mli if missing

Ambiguous References

When odoc warns about ambiguity (e.g., both an exception and module named Error):

{!Jsont.exception-Error}  (* for the exception *)
{!Jsont.module-Error}     (* for the module *)

@raise Tags

For @raise documentation tags, use the exception path with disambiguation:

@raise Jsont.exception-Error
@raise Tomlt.Toml.Error.exception-Error

Escaping @ Symbols

The @ character is interpreted as a tag marker in odoc. When you need a literal @ in documentation text (e.g., describing @-mentions), escape it with a backslash:

(* Correct - escaped @ *)
(** User was \@-mentioned *)
(** Mentioned via \@all/\@everyone *)

(* Incorrect - will produce "Stray '@'" or "Unknown tag" warnings *)
(** User was @-mentioned *)
(** Mentioned via @all *)

Hidden Fields Warning

When odoc warns about "Hidden fields in type 'Foo.Bar.t': field_name", it means a record field uses a type that odoc can't resolve in the documentation.

Diagnosis:

  1. Find the field definition in the .mli file
  2. Identify what type the field uses (e.g., uri : Uri.t)
  3. Check if that type's module is re-exported in the wrapper .mli

Fix Option 1: Re-export the module in the wrapper .mli:

(** RFC 3986 URI parsing *)
module Uri = Uri

Fix Option 2: If you only want to expose the type (not the whole module), use @canonical:

  1. Add a type alias in the wrapper .mli:

    type uri = Uri.t
    
  2. Add @canonical to the original type's documentation:

    (* In uri.mli *)
    type t
    (** A URI. @canonical Requests.uri *)
    

This tells odoc to link Uri.t to Requests.uri in the generated documentation.

Interpreting Error Messages

Error PatternMeaningFix
unresolvedroot(X)X not found as root moduleCheck library dependencies, add documentation depends
Couldn't find "Y" after valid pathY doesn't exist at that locationVerify module structure, check exports
Reference to 'X' is ambiguousMultiple items named XAdd kind qualifier (e.g., exception-X)
Hidden fields in type ... : fieldField's type not resolvableRe-export the type's module in wrapper .mli

Debugging

  1. Run dune clean before dune build @doc to ensure fresh builds
  2. Check the library's .mli file to see what modules are exported
  3. For cross-library refs, trace the module path through re-exports

OCaml Development

Core Philosophy

  1. Interface-First Design: Design the .mli file first. A clean interface matters more than clever implementation.
  2. Modularity: Build small, focused modules that do one thing well. Compose them for larger systems.
  3. Simplicity (KISS): Prioritize clarity over conciseness. Avoid obscure constructs.
  4. Explicitness: Make control flow and error handling explicit. Avoid exceptions for recoverable errors.
  5. NEVER use Obj.magic: It breaks type safety. There is always a better solution.

Build System and Tooling

  • Build: Use dune exclusively
  • Formatting: Run dune fmt before committing (uses ocamlformat)
  • Common Libraries:
    • Concurrency: eio
    • Structured output: fmt
    • Logging: logs
    • CLI parsing: cmdliner
    • JSON: jsont
    • HTTP: cohttp-eio

Module Interface Design

Documentation Pattern

Write ocamldoc in the voice of a POSIX manual page. Full sentences, no extraneous detail, no colons or em dashes joining clauses, and nothing about the implementation. Load the doc-style skill before writing or changing any comment. It is the full standard and this section is only its summary.

Every .mli file starts with a synopsis, then a blank line, then the description.

(** User accounts and profiles.

    Users are workspace members. A user is identified by an {!type:id} that is
    stable for the lifetime of the account. *)

Function Documentation

Open with the function applied to its arguments, followed by is:

val is_bot : t -> bool
(** [is_bot u] is [true] if [u] is a bot user. *)

val find : id -> t -> user option
(** [find id t] is the user of [t] with identifier [id], or [None] if [t] has
    no such user. *)

Reserve an active verb for functions that exist for their effect:

val flush : out_channel -> unit
(** [flush oc] writes the buffered bytes of [oc] to its underlying file. *)

For types, describe what the values represent, never their representation:

type id = string
(** The type for user identifiers. An identifier is unique within a workspace
    and stable across renames. *)

Implementation Comments

Implementations carry no comments where the code says it already. Write one only for a spec citation, a non-local invariant, a deliberate workaround, or a justification for an unsafe operation. Documentation lives in the .mli, so an .ml with an .mli has no (** ... *) comments at all.

Standard Interface for Data Types

For modules with a central type t, provide these functions where applicable:

FunctionPurpose
val v : ... -> tPure smart constructor (no I/O)
val create : ... -> (t, Error.t) resultConstructor with side-effects
val pp : t Fmt.tPretty-printer for logging/debugging
val equal : t -> t -> boolStructural equality
val compare : t -> t -> intComparison for sorting
val of_json : Yojson.Safe.t -> (t, string) resultParse from JSON
val to_json : t -> Yojson.Safe.tSerialize to JSON
val validate : t -> (t, string) resultValidate data integrity

Abstract Types

Keep types abstract (type t) when possible. Expose smart constructors and accessors instead of record fields to maintain invariants.

Error Handling

Use result type for recoverable errors. Reserve exceptions for programming errors (e.g., Invalid_argument).

Central Error Type

Define a comprehensive error type in lib/error.ml:

(* In lib/error.mli *)
type t = [
  | `Api of string * Yojson.Safe.t
  | `Json_parse of string
  | `Network of string
  | `Msg of string
]

val pp : t Fmt.t

Error Helper Pattern

let err_api code fields = Error (`Api (code, fields))
let err_parse msg = Error (`Json_parse msg)

let find_user_id json =
  match Yojson.Safe.Util.find_opt "id" json with
  | Some (`String id) -> Ok id
  | Some _ -> err_parse "Expected string for user ID"
  | None -> err_parse "Missing user ID"

Rules

  • Never use try ... with _ -> .... Match specific exceptions.
  • For unrecoverable startup errors, use Fmt.failwith:
let tls_config =
  match Tls.Config.client ~authenticator () with
  | Ok config -> config
  | Error (`Msg msg) -> Fmt.failwith "Failed to create TLS config: %s" msg

Function Design

  • Keep functions small: One function, one purpose. Decompose complex logic.
  • Avoid deep nesting: More than 2-3 levels of match/if signals need for refactoring.
  • Prefer purity: Isolate side-effects at edges (bin/, lib/ui/).
  • Composition over abstraction: Favor small concrete functions over deep abstractions.
  • Data-oriented: Operate on simple, immutable data structures.
  • No premature generalization: Solve the problem at hand, avoid unnecessary complexity.

Logging

Use the logs library with per-module log sources:

let log_src = Logs.Src.create "project_name.module_name"
module Log = (val Logs.src_log log_src : Logs.LOG)

Log Levels

LevelUse Case
Log.appMessages always shown to user (startup)
Log.errHandled but critical errors
Log.warnPotential issues, operation continues
Log.infoInformational state messages
Log.debugVerbose debugging details

Structured Logging

Log.info (fun m ->
    m "Received event: %s" event_type
      ~tags:(Logs.Tag.add "channel_id" channel_id Logs.Tag.empty))

Naming Conventions

ElementConventionExample
Fileslowercase_underscoresuser_profile.ml
Moduleslowercase_underscoresuser_profile
Primary typettype t
Identifiersidtype id = string
Valuesshort_descriptivefind_user, create_channel

Labels

Use labels only when they clarify meaning. Avoid ~f and ~x.

CLI Applications

For bin/ applications using cmdliner:

  • Place shared functionality (auth, logging setup) in bin/common.ml
  • Provide a shared run function that initializes the main loop and environment (e.g., Eio loop)
  • All commands should use this function for consistent environment

Commit Messages

Follow Conventional Commits:

Format: type(scope): subject

TypePurpose
featNew feature
fixBug fix
docsDocumentation
styleFormatting
refactorCode restructuring
testTests
choreMaintenance

Examples:

  • feat(api): add support for file uploads
  • fix(ui): correct channel list rendering bug
  • test(user): add tests for user profile updates

You are writing code for the OxCaml compiler, a performance-focused fork of OCaml with Jane Street extensions. This guide covers OxCaml-specific features only; standard OCaml is assumed.

Current target: OxCaml 5.4.0-ox9 — oxcaml-compiler.5.4.0-ox9 / ocaml-variants.5.4.0+ox, on the OCaml 5.4 base (ocamlopt -version prints 5.4.0+ox for every ox release; the exact check is opam var oxcaml-compiler:release). The previous target was 5.2.0minus-39 (OCaml 5.2 base).

Migrating a project from minus-39? Follow MIGRATION-39-ox9.md: step-by-step guide, error-message lookup table, before/after code checked on both compilers, forms that build on both.

Change history, newest first: CHANGES-39-ox9.md (5.2.0minus-39 → 5.4.0-ox9: minus-40, the upstream OCaml 5.4 merge, ox1 … ox9), CHANGES-38-39.md, CHANGES-31-38.md, CHANGES-25-31.md, CHANGES-23-25.md.

Quick Upgrade Flags (minus-39 → ox9)

When a build fails after a bump from minus-39, check these first (most common first; the fix for each and an ordered checklist are in MIGRATION-39-ox9.md):

  • int64#, int32#, nativeint#, float32# are gone → int64_u, int32_u, nativeint_u, float32_u ("The type int64 has no unboxed version. Hint: Did you mean int64_u?"). Literals (#42L), float#/int8#/int#/…, and "%…#…" primitive names are unchanged. int64_u box ≠ int64.
  • Rebuild everything, ppx rewriters and tools included (magic numbers 578 → 586); Jane Street libraries move to v0.18~preview.133.03+642.
  • effect is a keyword → rename identifiers or pass -keywords 5.2.
  • Tooling gaps: no odoc for ox9 (dune build @doc cannot work); ocamlformat 0.29.0+ox rejects a version = … line in .ocamlformat and cannot parse | effect patterns, overwrite_ or val poly_; on arm64 ocaml_simd needs a CPATH workaround to install (MIGRATION-39-ox9.md step 0).
  • fst p / snd p on a local pair in tail position is an error: bind the result, add [@nontail], or use exclave_ (section 2).
  • type ('a : any) t = { x : 'a } needs -extension layouts_beta (minus-39 silently narrowed the annotation).
  • All-void constructors (A of unit#) need [@immediate_all_void_constructor].
  • New default-on warnings: 181 imprecise-kind-annotation, 183/184 kind modifiers, 220 redundant-modality (@@ global aliased, mutable f : t @@ aliased); 211 renamed mod-by-top → redundant-modifier (use -211); 189 → 75.
  • Effect.perform raises an unsafe_effects alert → use Effect.Safe.perform.
  • { t with … } may not implicitly copy an [@atomic] field.
  • Integer literals at max+1 (128s, 32768S, 9223372036854775808L, …) are errors — they used to wrap to the minimum.
  • compiler-libs.common was split: add compiler-libs.frontend for Path/Types/Env/Typedtree/….
  • SIMD load/store primitives on float array removed; AVX-512 types need -extension simd_beta.
  • Runtime 4 retired: --disable-runtime5 is a configure error.
  • Error messages no longer double-quote identifiers in uncoloured output (matters when grepping compiler output or comparing against older docs) and many were reworded → re-promote expect tests.
  • C stubs: caml_failure_exn removed (use caml_exception_failure_value); caml_callback_res/caml_result supersede the _exn variants (which still compile).

Detailed Guides

FeatureGuide
Modes (local, unique, once, portable, contended)SKILL-MODES.md
Stack Allocation (local_, stack_, exclave_)SKILL-STACK-ALLOCATION.md
Unboxed Types (float#, int64_u, mixed blocks)SKILL-UNBOXED.md
Kinds (value, float64, bits32, kind products)SKILL-KINDS.md
Uniqueness (unique/aliased, once/many)SKILL-UNIQUENESS.md
Comprehensions (list/array builders)SKILL-COMPREHENSIONS.md
SIMD (vector types, SSE/AVX intrinsics)SKILL-SIMD.md
Templates (ppx_template, mangling)SKILL-TEMPLATES.md
Zero-Alloc ([@zero_alloc] checking)SKILL-ZERO-ALLOC.md
Base Library (OxCaml extensions)SKILL-BASE.md
Core Library (OxCaml extensions)SKILL-CORE.md

1. Modes

Modes track runtime properties of values. Each mode axis is independent.

AxisValuesDefaultPurpose
Localitylocal, globalglobalWhere value lives (stack vs heap)
Uniquenessunique, aliasedaliasedNumber of references
Linearityonce, manymanyHow often closures can be called
Portabilityportable, corruptible, shareable, nonportablenonportableCross-thread safety
Contentionuncontended, shared, corrupted, contendeduncontendedThread access patterns
Visibilityread_write, read, write, immutableread_writeMutable-field access rights
Statefulnessstateless, reading, writing, statefulstatefulClosed-over mutable state

Portability/contention and visibility/statefulness are 4-element diamonds (shared/corrupted and read/write are incomparable). observing is now spelled reading. This table is the commonly used subset — there are also unyielding/yielding, forkable/unforkable and static/dynamic axes. No axis or mode name changed between minus-39 and ox9.

let f (x @ local) = ...               (* on a parameter *)
let f (x @ local unique once) = ...   (* multiple modes *)
val g : t @ unique once -> t @ aliased many   (* in signatures *)
let x = (expr : t @ local)            (* on an expression *)
let local_ x = ...                    (* local_ is the only legacy let
                                         prefix (global is default) *)
type t = {                            (* record fields: modalities *)
  global_ data : int;                 (* always global *)
  shared : int list @@ aliased;       (* aliased modality *)
  mutable x : int;                    (* mutable => global many aliased
                                         already; writing them out is
                                         warning 220 *)
}

Subtyping — a more restrictive mode can be used where a less restrictive one is expected: global ≤ local, unique ≤ aliased, many ≤ once, portable ≤ shareable/corruptible ≤ nonportable, uncontended ≤ shared/corrupted ≤ contended (diamonds: the two middle modes are incomparable).

SKILL-MODES.md also covers inference of mode implications and curry modes, coercions that mode-cross function returns, and inference-only mode polymorphism (-extension mode_polymorphism_alpha).

2. Stack Allocation (Locality)

Stack-allocated values avoid GC overhead but cannot escape their scope (SKILL-STACK-ALLOCATION.md).

let f () =
  let local_ x = (1, 2) in       (* stack-allocated tuple *)
  let p = stack_ (3, 4) in       (* force stack allocation *)
  fst x + snd p

(* Return a local value: allocated in the caller's frame *)
let make_pair x y = exclave_ stack_ (x, y)

(* exclave_ is REQUIRED around a local-returning tail call *)
let g () = exclave_ make_pair 1 2
  1. Local values cannot escape their defining scope (no storing in globals, no returning without exclave_).
  2. Local values can reference global values; global values cannot reference local values.
  3. exclave_ ends the current region so what follows allocates in the caller's region; it must be at tail position.
  4. A local-returning call in tail position must be under exclave_ ("This local-returning application is in a tail position that is not enclosed in an exclave_ expression") — this includes fst p/snd p on a local tuple; bind the result or add [@nontail] instead if you want a global result.
  5. A local value cannot be passed to a tail call ("is local … because it is an argument in a tail call") — write f x [@nontail].
  6. Stdlib functions (List.iter, Array.fold_left, …) take global arguments (and a closure passed to List.iter cannot capture a local): on local data use explicit recursion (let rec go acc (l @ local) = …) or Base's local-aware variants.
  7. Accumulators can be local refs: let local_ r = ref 0 in …; !r.

3. Unboxed Types

Unboxed types store values directly without heap allocation. A # suffix or _u name means unboxed (int64#, int32#, nativeint#, float32# no longer exist — use the _u names); literals use a # prefix, and a minus sign goes outside: -#1l.

TypeDescriptionKindLiteral
float#64-bit floatfloat64#3.14
float32_u32-bit floatfloat32#1.0s
int32_u32-bit intbits32#42l
int64_u64-bit intbits64#100L
nativeint_unative intword#42n
int8#8-bit int, untaggedbits8#42s
int16#16-bit int, untaggedbits16#42S
int#native int, untaggeduntagged_immediate#42m
char#8-bit char, untagged, same layout as int8#bits8#'x'
bool#8-bit boolbits8#true, #false
unit#zero-sizevoid#()
  • uint8_u, uint16_u, uint32_u, uint64_u, unativeint_u are opaque unsigned types: no literals/operations.
  • Small numbers also have non-unboxed types: float32 (1.0s), int8 (42s), int16 (42S).
  • char# patterns take ranges: | #'a'..#'z' -> ….
  • 'a box is the boxed version of an unboxed type: float# box = float; r# box = r (but int64_u box <> int64).
(* Unboxed record - stored inline, not heap-allocated *)
type point = #{ x : float#; y : float# }
let p : point = #{ x = #1.0; y = #2.0 }
let get_x (p : point) = p.#x

(* Unboxed tuple; destructure with a #(...) pattern *)
type pair = #(float# * int32_u)
let first (q : pair) = let #(a, _) = q in a

(* Mixed block: boxed and unboxed fields, unboxed stored flat *)
type mixed = { name : string; value : float#; count : int32_u }

(* or_null: non-allocating option for value types (Null is encoded
   without a box). Predefined: type 'a or_null = Null | This of 'a
   (don't redeclare). The argument must be a non-null value type:
   float# or_null is rejected *)
let find (arr : string array) idx : string or_null =
  if idx < Array.length arr then This arr.(idx) else Null

(* Custom or_null types: any two-constructor variant (one nullary,
   one unary) can opt into the same non-allocating encoding *)
type 'a maybe = Nope | Yep of 'a [@@or_null]
type no_param = A | B of int [@@or_null]   (* payload shape is free *)
  • Mixed blocks: [@atomic] fields (layout value) are allowed; [@@flatten_floats] is optional on records mixing float and float#.
  • Arrays of untagged types are packed: int8# array and char# array use 1 byte per element, int16# array 2 bytes, int# array a native word ([| #0m; #1m |]). int8 array and int16 array hold tagged immediates: one word each.
  • Stdlib's Array.get/set/length only accept value elements, so a.(i) on an unboxed array needs open Base (layout-polymorphic Array) or [@layout_poly] externals.
  • SKILL-UNBOXED.md also covers array#/iarray#, block indices (idx_atomic, …), all-void constructors and C interop.

4. Kinds

Kinds classify types by their runtime representation (SKILL-KINDS.md). any (any layout) is the top. Under it: value_or_null (values, possibly null), which contains value (standard OCaml boxed values), which contains immediate (int, bool, char, …); and, each directly under any, float64, float32, bits8, bits16, bits32, bits64, word (native word size), untagged_immediate, vec128/vec256/vec512 (SIMD vectors), void (zero-width).

type ('a : float64) container = ...   (* on type parameters *)
val f : ('a : value). 'a -> 'a        (* on type variables in signatures *)
type t : float64                      (* on abstract types *)
type pair : float64 & bits32          (* kind product: unboxed pair of
                                         float# and int32_u *)
type t : value mod global     (* mode bound: crosses locality, a local
                                 t can be used as global *)
type t : value mod portable   (* always portable *)

Abbreviations such as immediate64, mutable_data and immutable_data are defined in SKILL-KINDS.md.

  • Kind annotations are linted by default: warning 181 if an annotation is weaker than the inferred kind (('a : any) … 'a list), 183/184 for redundant/ignored scannable-axis modifiers, 211 for redundant mod bounds (value mod global aliased, value mod local).
  • addressable is a postfix kind modifier.
  • A field of kind any needs -extension layouts_beta.
  • Layout-polymorphic let poly_/val poly_ need -extension layout_poly_alpha.

5. Uniqueness

unique: a single reference exists (safe mutation/deallocation); aliased: multiple references may exist (SKILL-UNIQUENESS.md).

val free : t @ unique -> unit            (* unique parameter: consumed *)
val duplicate : t -> t * t @ aliased     (* aliased return *)
val delay_free : t @ unique -> (unit -> unit) @ once
                                         (* once closure: invoked once only *)

(* Aliased modality: container is unique but contents are aliased *)
type 'a aliased_box = { value : 'a @@ aliased } [@@unboxed]

let ok t = match t with Con { field } -> free t
                                         (* OK: match then use uniquely *)
let bad t = match t with                 (* ERROR: using parts twice *)
  | Con { field } ->
    free_field field;                    (* uses field *)
    free t                               (* uses t which contains field *)
let ok t = match t with                  (* OK: different branches *)
  | Con { field } -> if cond then free_field field else free t

6. Comprehensions

List and array builders (SKILL-COMPREHENSIONS.md). Still a beta extension: compile with -extension comprehensions.

[ x * 2 for x = 1 to 10 ]
[ x for x = 1 to 100 when x mod 2 = 0 ]             (* filter *)
[ String.uppercase_ascii s for s in strings ]       (* iterate over list *)
[ x + y for x = 1 to 10 for y = 1 to 10 when x < y when x + y < 15 ]
[| f elem for elem in source_array |]               (* array: [| |] *)
[: x for x = 1 to 10 when x mod 2 = 0 :]            (* immutable array *)
[ (x, y) for x = 1 to 3 for y = 1 to 3 ]            (* 9 elements *)
[ (x, y) for x = 1 to 3 and y = 10 to 12 ]          (* 9 elements:
                              [(1,10); (1,11); (1,12); (2,10); ...] *)

for ... for ... and for ... and ... both produce the Cartesian product — comprehensions cannot zip. for ... for ... is nested (inner source re-evaluated each outer iteration; inner iterators may reference outer variables); with for ... and ... sources are evaluated once upfront and iterators are independent (cannot reference each other), which enables exact-size array pre-allocation.

7. SIMD Vector Types

128-bit and 256-bit SIMD vectors (SKILL-SIMD.md; 128-bit also works natively on arm64/NEON). 512-bit vectors and mask types exist under -extension simd_beta (AVX-512: types and load/store only — no intrinsics yet). Each type has a boxed and an unboxed (#) form, e.g. int8x16 / int8x16#. 128-bit: int8x16, int16x8, int32x4, int64x2, float32x4, float64x2; 256-bit: int8x32, int32x8, float64x4, etc.; 512-bit: int8x64 … float64x8, mask, mask#.

(* dune: (libraries ocaml_simd.sse) *)
open Ocaml_simd_sse

let v = Float32x4.set #1.0s #2.0s #3.0s #4.0s   (* float32_u, lane 0 first *)
let v = Float32x4.sqrt v
let #(x, y, z, w) = Float32x4.splat v
let v = Int8x16.String.get text ~byte:0         (* load *)

C stubs:

external vec_op : (int8x16[@unboxed]) -> (int8x16[@unboxed]) =
  "boxed_stub" "unboxed_stub"

8. Templates (ppx_template)

Generate multiple copies of code with different modes/kinds (SKILL-TEMPLATES.md).

(* Mode template: generates id (global) and id__local *)
let%template[@mode m = (global, local)] id
  : 'a. 'a @ m -> 'a @ m
  = fun x -> x
(* Instantiate (exclave_ because the local instance returns local) *)
let f (x @ local) = exclave_ (id [@mode local]) x

(* Kind template: generates id (value) and id__float64 *)
let%template[@kind k = (value, float64)] id
  : ('a : k). 'a -> 'a
  = fun x -> x

(* Exclave conditional: local version gets exclave_ (x, y) *)
let%template[@mode m = (global, local)] make_pair x y =
  (x, y) [@exclave_if_local m]
(* ~reasons is needed because (f a, f b) is not a plain allocation of
   identifiers/constants *)
let%template[@mode m = (global, local)] map_pair f (a, b) =
  ((f a, f b) [@exclave_if_local m ~reasons:[ May_return_local ]])

(* Alloc template *)
let%template rec map
  : f:('a -> 'b @ m) -> 'a list -> 'b list @ m
  = fun ~f list ->
    match[@exclave_if_stack a] list with
    | [] -> []
    | hd :: tl -> f hd :: (map [@alloc a]) ~f tl
[@@alloc a @ m = (heap_global, stack_local)]

(* Kind-polymorphic container (not `box` — that name is the predefined
   'a box type) *)
type%template ('a : k) cell = { contents : 'a }
[@@kind k = (value, float64, bits64)]
  • Portable/nonportable functor variants, short form: module%template.portable Make (M : S) : T.
  • Default floating attributes: [%%template: [@@@mode.default m = (global, local)] val min : t @ m -> t @ m -> t @ m ].
  • Library functions are instantiated the same way (Base): (List.map [@alloc stack]) lst ~f, (List.fold [@mode local global]) l ~init ~f.
  • Mangled names follow the __suffix pattern.

9. Zero-Alloc Checking

Compile-time verification that functions don't allocate.

let[@zero_alloc] fast_add x y = x + y         (* must not allocate *)
let[@zero_alloc] with_local_pair x y =        (* local/stack allocations
                                                 are allowed *)
  let p = stack_ (x, y) in
  fst p + snd p
let[@zero_alloc opt] complex_func x = ...     (* only checked in optimized builds *)
let[@zero_alloc strict] very_strict x = ...   (* no allocation even on error paths *)
let[@zero_alloc assume] external_wrapper x = external_func x
                                              (* trusted to be zero-alloc *)
let[@cold][@zero_alloc assume error] handle_error e = ...
                                              (* assume for error paths *)
val[@zero_alloc] f : int -> int               (* in signatures; also strict *)
val[@zero_alloc arity 2] h : int -> int -> int
[@@@zero_alloc all]                           (* file-level: all functions
                                                 must be zero-alloc *)
let[@zero_alloc ignore] allowed_to_alloc x = [x]   (* opt out *)

On failure, -zero-alloc-checker-details-cutoff -1 prints full details. See SKILL-ZERO-ALLOC.md.

10. Parallelism & Capsules

Contention and portability modes: section 1 and SKILL-MODES.md.

Spawning work. Domain.spawn carries the do_not_spawn_domains and unsafe_multidomain alerts. Use the parallel library (Parallel.fork_join2, Parallel_scheduler.with_parallel; results are unboxed tuples: let #(x, y, z) = Parallel.fork_join3 par f1 f2 f3) for structured parallelism, or Multicore.spawn (compiler threads library) at the low level:

(* dune: (libraries base portable threads) *)
let counter = Portable.Atomic.make 0
let () =
  match Multicore.spawn (fun () -> Portable.Atomic.incr counter) () with
  | Spawned -> ()
  | Failed ((), exn, bt) -> Printexc.raise_with_backtrace exn bt

(The opam compiler is built with --enable-multidomain and --enable-poll-insertion.)

Capsules (capsule / portable libraries; Core.Capsule) isolate mutable state so it can be shared safely (examples: SKILL-CORE.md):

  • Read-only sharing — build mutable data, then freeze it: Capsule.Frozen.create (fun () -> …), then let (t @ shared) = Capsule.Frozen.unwrap table and read with shared-mode instances such as (Array.get [@mode shared]) t i.
  • Data tied to the current capsule via an access token: let (P access) = Capsule.Access.current (), then Capsule.Data.wrap ~access v / Capsule.Data.unwrap ~access d.
  • Locks live in the await library (Await.Capsule.Sync.With_mutex.with_lock); Capsule.Blocking_sync is deprecated. The low-level key/password API is Capsule.Prim (its *_unique/*_once variants are now [@mode …] instances).

Dynamically scoped variables. Stdlib.Dynamic gives fiber-aware, parallel-safe dynamic binding: Dynamic.make (), Dynamic.with_temporarily d v ~f:(fun () -> …), and Dynamic.get d returning Null or This v. Values go in portable and are read contended portable; unbound reads Null; there is no set. Signatures and example: CHANGES-39-ox9.md.

Preemption (experimental, opt-in per fiber). Effect.Deep.Preemptible.match_with/try_with, with ticks from Domain.Tick.acquire ~interval_usec or the scoped Domain.Tick.with_ — API and example in CHANGES-39-ox9.md.

Effect handlers and modes. The 5.4 syntax is available — match c () with v -> v | effect Poke, k -> Effect.Deep.continue k () — with OxCaml caveats:

  • a function containing effect cases is forced nonportable and stateful (you cannot pattern-match on effects inside a portable or stateless function), and variables used anywhere in such a match (scrutinee or cases) must be global;
  • Effect.perform raises the unsafe_effects alert: prefer Effect.Safe.perform h e, where h : Effect.Handler.t @ local is handed to the computation by Effect.Deep.Safe.match_with/try_with (or silence with [@@@alert "-unsafe_effects"]);
  • in a file preprocessed by a ppx, effect patterns currently fail ("migration error: effect patterns is not supported before OCaml 5.02") — keep handlers in un-preprocessed files or use Effect.Deep.match_with.

11. Borrowing

borrow_ e is a prefix expression form that cooperates with the uniqueness analysis. It is valid in exactly three positions — anywhere else is a hard error ("The borrow_ operator must appear directly in a valid borrowing context"):

f (borrow_ r)                      (* common: function argument *)
let y = borrow_ r in ...           (* let-binding RHS *)
match borrow_ r with _ -> ...      (* match scrutinee *)

Use it where a callee only reads/writes through a unique value transiently and you want to keep the unique reference after the call. A borrowed value is local + aliased, so the callee must accept its argument @ local. Diagnostics: warning 216 use-during-borrowing ("This value is used while being borrowed."); error "This value is used as unique here, but it is being borrowed." (a conflict between a borrow and a unique use). See SKILL-MODES.md.

12. Implicit Kinds in Signatures and Structures

A floating [@@@implicit_kind: ...] attribute declares that specific type-variable names default to a chosen kind, in signatures and in structures:

module type S = sig
  [@@@implicit_kind: ('elt : word)]
  type 'elt collection                  (* 'elt defaults to kind word *)
  val singleton : 'elt -> 'elt collection
end

Multiple names at once: [@@@implicit_kind: ('a : immediate) * ('b : immediate)]. Implicit kinds can't be overridden by an explicit annotation on the variable, are inherited by nested signatures (which may re-declare them), don't propagate through include, and apply inside constraint clauses. See SKILL-KINDS.md.

13. Miscellaneous Extensions

Labeled tuples

let point = ~x:10, ~y:20              (* create *)
type point = x:int * y:int            (* type *)
let ~x, ~y = point                    (* destructure *)
let get_x (p : x:int * y:int) =       (* partial match needs a type
                                         annotation *)
  let ~x, .. = p in x
val dimensions : image -> width:int * height:int

Immutable arrays

let arr : string iarray = [: "a"; "b"; "c" :]   (* : instead of | *)
let first = Iarray.get arr 0                    (* Stdlib.Iarray *)
(* [| |] literals and patterns are disambiguated by expected type
   (iarray / floatarray) *)
let arr3 : int iarray = [| 1; 2; 3 |]
(* Covariant - allows safe subtyping *)
let arr2 : obj iarray = (arr : sub_obj iarray :> obj iarray)
  • a.:(0) works only with Stdlib_stable.IarrayLabels open — the ( .:() ) operator is not in Stdlib.Iarray or Stdlib_stable.Iarray. IarrayLabels also keeps the *_local variants.
  • Stdlib.Iarray has equal, compare, find_index, find_mapi, which the narrower Stdlib_stable.Iarray shim lacks — beware open Stdlib_stable shadowing Iarray.

Include functor — instead of module T = struct … end, include T, include Comparable.Make(T):

module M = struct
  type t = ...
  [@@deriving compare, sexp]
  include functor Comparable.Make
end

Let mutable — restrictions: cannot escape scope, no closure capture, single variable only.

let triangle n =
  let mutable total = 0 in    (* mutable local variable - no allocation *)
  for i = 1 to n do total <- total + i done;
  total

Polymorphic parameters

let create (f : 'a. 'a field -> 'a) = { a = f A; b = f B }
val create : ('a. 'a field -> 'a) -> t

Module strengthening — write S with M instead of sig type t = M.t end.

Debugging Tips

  • Mode errors: check if you're trying to return local data globally. Kind errors: ensure type parameters have correct layout annotations.
  • Mangled symbols: ocamlfilt (installed with the compiler) demangles flat and structured schemes — but only when a line is exactly one symbol: nm x.o | awk '{print $3}' | ocamlfilt
  • Native debugging: use the OxCaml LLDB build (21.1.0+oxcaml1); b Module.fn breakpoints and OCaml-syntax value printing work
  • Also available (details in CHANGES-39-ox9.md): flags -open-cmi, -functorize, -keywords, -i-variance, ocamldep -modules-only; Obj.hash_variant; idle-phase major GC (Xsmall_heap_limit); C API caml_region_begin/end, caml_add_blocks_to_heap, OXCAML_RUNTIME.

Library Dependencies

  • Stdlib (OCaml 5.4 base): Iarray, Pqueue, Pair, Repr, Dynamic (OxCaml), Effect.Safe (OxCaml), Modes, plus Dynarray, Atomic.Loc
  • stdlib_stable: Float32/Float32_u, Int8/Int8_u, Int16/Int16_u, Int_u, Char_u, Or_null, Idx_imm/Idx_mut/Idx_atomic, Iarray (narrow compat shim), IarrayLabels (section 13)
  • stdlib_upstream_compatible: Float_u, Int32_u, Int64_u, Nativeint_u
  • threads: Multicore (spawn, spawn_on, max_domains)
  • base: Jane Street's standard library with comprehensive OxCaml mode support — consult SKILL-BASE.md for OxCaml-friendly functions. Mode/alloc instances via ppx_template ((List.map [@alloc stack]), (List.fold [@mode local global])), Modes (modal wrappers), Iarray, layout-polymorphic Array.get/set/length
  • core: extended library with I/O and system features — see SKILL-CORE.md
  • unboxed: Float_u, Int32_u, Int64_u, Nativeint_u, Float32_u with full operator sets (open Unboxed gives F64, F32, I32, I64, Iptr)
  • portable, capsule: Portable.Atomic, Capsule, …
  • parallel, await, concurrent: structured parallelism, locks, concurrency (opam packages; parallel requires oxcaml-compiler ≥ 5.4.0-ox9)
  • ppx_template: mode/kind polymorphism via code generation — see SKILL-TEMPLATES.md for mangling details
  • ocaml_simd.ppx (ppx_simd): SIMD shuffle/blend mask generation
  • ppx_portable: lazy%portable, let%portable rec
  • ocaml_simd (opam package; requires oxcaml-compiler ≥ 5.4.0-ox9), with dune libraries ocaml_simd.sse (module Ocaml_simd_sse: 128-bit intrinsics; SSE on amd64, NEON or C stubs on arm64) and ocaml_simd.avx (module Ocaml_simd_avx: AVX/AVX2 intrinsics, 256-bit; C stubs on arm64). On arm64 opam install ocaml_simd needs the CPATH workaround in SKILL-SIMD.md. Opening either module shadows Int32, Int64 (and String for Ocaml_simd_sse).

OCaml Progress Library

The progress library provides beautiful terminal progress bars, spinners, and multi-line displays for CLI applications.

Installation

Add to dune-project:

(depends
 (progress (>= 0.4)))

Add to library/executable dune:

(libraries progress)

Core Concepts

TypePurpose
Progress.Line.tA single progress line (bar, spinner, text)
Progress.Multi.tMultiple lines combined
Progress.Display.tActive display that can be updated
Progress.Reporter.tHandle to report progress to a line

Basic Progress Bar

open Progress

let process_items items =
  let total = List.length items in
  let bar = Line.(list [
    spinner ();
    bar ~style:`UTF8 ~width:(`Fixed 40) total;
    count_to total;
  ]) in
  with_reporter bar (fun report ->
    List.iteri (fun i item ->
      process_item item;
      report (i + 1)
    ) items)

Output:

⠋ [████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 12/50

Progress Bar with Bytes and Speed

For downloads/uploads, use Int63 for large file sizes:

open Progress
module Int63 = Optint.Int63

let download_line ~total message =
  let open Line.Using_int63 in
  list [
    rpad 20 (const message);
    bytes;
    const " ";
    bytes_per_sec;
    const " ";
    bar ~style:`UTF8 ~width:(`Fixed 30) total;
    const " ";
    percentage_of total;
  ]

let download ~url ~size =
  let bar = download_line ~total:(Int63.of_int size) "Downloading..." in
  with_reporter bar (fun report ->
    fetch_with_progress url (fun bytes_read ->
      report (Int63.of_int bytes_read)))

Output:

Downloading...       12.5 MiB  2.3 MiB/s [██████████░░░░░░░░░░░░░░░░░░░░]  42%

Multi-Line Progress Display

For operations with multiple concurrent tasks:

open Progress

let multi_download files =
  let lines = List.mapi (fun i file ->
    download_line ~total:(file_size file) (file_name file)
  ) files in
  let display = Multi.(list lines) in
  with_reporters display (fun reporters ->
    (* Each reporter corresponds to one line *)
    List.iter2 (fun reporter file ->
      download_file file (fun n -> reporter n)
    ) reporters files)

Dynamic Line Addition

Add lines dynamically during execution:

open Progress

type t = {
  display : ((unit -> unit) -> unit, unit) Display.t;
  mutable line_count : int;
}

let init () =
  let header = Line.(constf "🐫 Processing files...") in
  let display = Display.start Multi.(line header) in
  { display; line_count = 0 }

let add_line t bar =
  let reporter = Display.add_line t.display bar in
  t.line_count <- t.line_count + 1;
  reporter

let finalise t =
  Display.finalise t.display

Custom Colors

Use hex colors for branded progress bars:

open Progress

(* Gradient color palette *)
let colors = [|
  Color.hex "#1996f3";  (* Blue *)
  Color.hex "#06aeed";
  Color.hex "#10c6e6";
  Color.hex "#27dade";
  Color.hex "#3dead5";
  Color.hex "#52f5cb";  (* Cyan *)
  Color.hex "#66fcc2";
  Color.hex "#7dffb6";
  Color.hex "#92fda9";  (* Green *)
|]

let color_for_index i = colors.(i mod Array.length colors)

let colored_bar ~index ~total message =
  let color = color_for_index index in
  Line.(list [
    rpad 20 (const message);
    bar ~color ~style:`UTF8 total;
    percentage_of total;
  ])

Spinners

For indeterminate operations:

open Progress

let with_spinner message f =
  let line = Line.(list [spinner (); const (" " ^ message)]) in
  with_reporter line (fun _report -> f ())

(* Usage *)
let () =
  with_spinner "Connecting to server..." (fun () ->
    connect_to_server ())

Integration with Eio

For async progress updates, use a stream to communicate between fibers:

open Progress

type t = {
  stream : (unit -> unit) option Eio.Stream.t;
  display : ((unit -> unit) -> unit, unit) Display.t;
}

type reporter = {
  stream : (unit -> unit) option Eio.Stream.t;
  reporter : int Reporter.t option;
}

(* Report progress from any fiber *)
let report r value =
  match r.reporter with
  | None -> ()
  | Some reporter ->
      Eio.Stream.add r.stream
        (Some (fun () -> Reporter.report reporter value))

(* Process stream updates in display fiber *)
let rec process_stream ~sw stream =
  Eio.Switch.check sw;
  match Eio.Stream.take stream with
  | Some f -> f (); process_stream ~sw stream
  | None -> ()

let init ~sw =
  let stream = Eio.Stream.create max_int in
  let header = Line.(const "Processing...") in
  let display = Display.start Multi.(line header) in
  Eio.Fiber.fork ~sw (fun () -> process_stream ~sw stream);
  { stream; display }

let finalise t =
  Eio.Stream.add t.stream None;
  Display.finalise t.display

Line Components Reference

ComponentDescription
bar ~style totalProgress bar (styles: UTF8, ASCII)
spinner ()Animated spinner
count_to total"n/total" counter
percentage_of total"42%" percentage
const sStatic string
constf fmtFormatted static string
elapsed ()Elapsed time
eta totalEstimated time remaining
bytesByte count (auto-scales to KiB, MiB, etc.)
bytes_per_secTransfer speed
rpad n lineRight-pad to n characters
lpad n lineLeft-pad to n characters
spacer nFixed-width space
list linesCombine multiple components
(++)Infix combine: a ++ b

Bar Styles

(* UTF-8 style (default, looks best) *)
Line.bar ~style:`UTF8 total
(* Output: [████████░░░░░░░░] *)

(* ASCII style (for limited terminals) *)
Line.bar ~style:`ASCII total
(* Output: [########........] *)

(* Custom width *)
Line.bar ~style:`UTF8 ~width:(`Fixed 50) total
Line.bar ~style:`UTF8 ~width:(`Expand) total  (* fill available space *)

Complete CLI Example

open Cmdliner
open Progress

let download_files files =
  let total_files = List.length files in
  let header = Line.(constf "📦 Downloading %d files" total_files) in
  let display = Display.start Multi.(line header) in

  List.iteri (fun i file ->
    let size = Int63.of_int (file_size file) in
    let color = color_for_index i in
    let bar = Line.Using_int63.(list [
      rpad 25 (const (file_name file));
      bytes;
      bar ~color ~style:`UTF8 ~width:(`Fixed 30) size;
      percentage_of size;
    ]) in
    let reporter = Display.add_line display bar in
    download_file file (fun bytes ->
      Reporter.report reporter (Int63.of_int bytes));
    Reporter.finalise reporter
  ) files;

  Display.finalise display;
  Fmt.pr "✓ Downloaded %d files@." total_files

let cmd =
  let info = Cmd.info "download" ~doc:"Download files with progress" in
  Cmd.v info Term.(const download_files $ files_arg)

Tips

  1. Use Int63 for bytes - Regular int overflows at 2GB on 32-bit systems
  2. Fork display updates - With Eio, run display in separate fiber
  3. Finalise reporters - Always call Reporter.finalise when done
  4. Check terminal width - Use (Expand)` for responsive bars
  5. Provide fallback - Disable progress when stdout isn't a TTY:
let with_progress ~enabled bar f =
  if enabled && Unix.isatty Unix.stdout then
    with_reporter bar f
  else
    f (fun _ -> ())

OCaml Project Setup

Required Files

Every OCaml project needs:

FilePurpose
dune-projectBuild configuration, opam generation
dune (root)Top-level build rules
.ocamlformatCode formatting (required)
.gitignoreVCS ignores
LICENSE.mdLicense file
README.mdProject documentation
CI configGitHub Actions / GitLab CI / Tangled

Interface Files (.mli)

Every library module must have an .mli file for:

  • Clear API boundaries
  • Proper encapsulation
  • Documentation surface
(* lib/user.mli *)

(** User accounts.

    A user is identified by an email address, which is unique within a
    workspace. *)

type t
(** The type for users. *)

val create : name:string -> email:string -> t
(** [create ~name ~email] is a new user called [name] with address [email]. *)

val name : t -> string
(** [name u] is the display name of [u]. *)

val pp : t Fmt.t
(** [pp ppf u] formats [u] on [ppf]. *)

Documentation style: written in the voice of a POSIX manual page. Load the doc-style skill before writing any of it. In short, a function's doc opens [f x y] is ..., every doc comment is full sentences ending in a full stop, no colon or em dash joins clauses, and nothing describes the implementation.

Standard Module Interface

For modules with a central type t:

type t
val v : ... -> t                           (* pure constructor *)
val create : ... -> (t, Error.t) result    (* constructor with I/O *)
val pp : t Fmt.t                           (* pretty-printer - required *)
val equal : t -> t -> bool                 (* equality *)
val compare : t -> t -> int                (* comparison *)
val of_json : Yojson.Safe.t -> (t, string) result
val to_json : t -> Yojson.Safe.t

OCamlFormat Configuration

Required: .ocamlformat in project root.

version = 0.28.1

Run dune fmt before every commit.

Logging Setup

Each module using logging should declare a source:

let log_src = Logs.Src.create "project.module"
module Log = (val Logs.src_log log_src : Logs.LOG)

Log levels:

  • Log.app - Always shown (startup)
  • Log.err - Critical errors
  • Log.warn - Potential issues
  • Log.info - Informational
  • Log.debug - Verbose debugging

User Configuration

Read from ~/.claude/ocaml-config.json:

{
  "author": { "name": "Name", "email": "email@example.com" },
  "license": "ISC",
  "ci_platform": "github",
  "git_hosting": { "type": "github", "org": "username" },
  "ocaml_version": "5.2.0"
}

License Headers

Every source file starts with license header:

(*---------------------------------------------------------------------------
  Copyright (c) {{YEAR}} {{AUTHOR}}. All rights reserved.
  SPDX-License-Identifier: ISC
 ---------------------------------------------------------------------------*)

Project Structure

project/
├── dune-project
├── dune
├── .ocamlformat
├── .gitignore
├── LICENSE.md
├── README.md
├── lib/
│   ├── dune
│   ├── foo.ml
│   └── foo.mli         # Required for every .ml
├── bin/
│   ├── dune
│   └── main.ml
├── test/
│   ├── dune
│   ├── test.ml
│   └── test_foo.ml
├── .github/workflows/  # GitHub Actions
├── .gitlab-ci.yml      # GitLab CI
└── .tangled/workflows/ # Tangled CI

dune-project

(lang dune 3.21)
(name project_name)
(source (tangled handle/project_name))   ; or (github user/repo)
(license ISC)
(authors "Name <email>")
(generate_opam_files true)

(license ISC)
(authors "Name <email@example.com>")
(maintainers "Name <email@example.com>")
(source (tangled user.domain/project_name))

(package
 (name project_name)
 (synopsis "Short description")
 (description "Longer description")
 (depends
  (ocaml (>= 5.2))
  (alcotest (and :with-test (>= 1.7.0)))))

Source options:

  • (source (tangled handle/repo)) - Tangled hosting (default for monopam)
  • (source (github user/repo)) - GitHub hosting
  • (source (gitlab user/repo)) - GitLab hosting

Note: Don't add (version ...) - added at release time.

Tangled Source Syntax

For projects hosted on tangled.org, use the succinct source stanza:

(source (tangled user.domain/project-name))

Examples:

  • (source (tangled anil.recoil.org/ocaml-brotli))
  • (source (tangled user.example.org/my-library))

Tangled CI Configuration

For projects hosted on tangled.org, create .tangled/workflows/build.yml:

when:
  - event: ["push", "pull_request"]
    branch: ["main"]

engine: nixery

dependencies:
  nixpkgs:
    - shell
    - stdenv
    - findutils
    - binutils
    - libunwind
    - ncurses
    - opam
    - git
    - gawk
    - gnupatch
    - gnum4
    - gnumake
    - gnutar
    - gnused
    - gnugrep
    - diffutils
    - gzip
    - bzip2
    - gcc
    - ocaml
    - pkg-config

steps:
  - name: opam
    command: |
      opam init --disable-sandboxing -a -y

  - name: repo
    command: |
      opam repo add aoah https://tangled.org/anil.recoil.org/aoah-opam-repo.git

  - name: deps
    command: |
      opam install . --confirm-level=unsafe-yes --deps-only

  - name: build
    command: |
      opam exec -- dune build

  - name: test
    command: |
      opam install . --confirm-level=unsafe-yes --deps-only --with-test
      opam exec -- dune runtest --verbose

Tangled Workflow Syntax

FieldDescription
whenTrigger conditions: event (push/pull_request) and branch
engineBuild engine, use nixery for Nix-based builds
dependencies.nixpkgsList of Nix packages to include
environmentGlobal or per-step environment variables
stepsBuild steps with name and command

Per-step environment variables:

steps:
  - name: test
    environment:
      MY_VAR: value
    command: |
      echo $MY_VAR

Templates

See templates/ directory for:

  • dune-project.template
  • dune-root.template
  • ci-github.yml
  • ci-gitlab.yml
  • ci-tangled.yml
  • gitignore
  • ocamlformat
  • LICENSE-ISC.md
  • LICENSE-MIT.md
  • README.template.md

OCaml Result Patterns

OCaml 5.x provides Result.Syntax for monadic chaining and Result.get_ok/Result.get_error for extraction.

Result.Syntax

Use open Result.Syntax to get let* and let+ bindings:

open Result.Syntax

let process request =
  let* req = validate request in
  let* auth = authenticate req in
  let* _ = authorize auth in
  execute req

DO NOT define local let ( let* ) = Result.bind. Use open Result.Syntax instead.

Extracting Values

FunctionBehavior on Error
Result.get_ok rRaises Invalid_argument
Result.get_error rRaises Invalid_argument
Result.value r ~defaultReturns default

Use Result.get_ok only when failure is a programming error:

(* Startup/config - crash on failure is intentional *)
let config = Result.get_ok (Config.load ())

(* Test setup - failure means test bug *)
let client = Result.get_ok (Tls.Config.client ~authenticator ())

Custom get_ok

Only define custom get_ok when you need different exception behavior:

(* Raises domain-specific Protocol_error instead of Invalid_argument *)
let get_ok = function
  | Ok x -> x
  | Error e -> raise (Protocol_error e)

If you just want Invalid_argument, use Result.get_ok directly.

OCaml Project Review

A review in two phases. The interfaces are judged first, on their own, as a user of the library sees them. Only then are the implementations read, one module at a time, by a dedicated subagent each.

Never merge the phases. Reading an implementation before judging its interface is how a bad interface gets rationalised.

Phase 1: Interfaces

What to read

Read only these files.

  • dune-project
  • every dune
  • every .mli
  • every .mld
  • *.opam if present

Do not open a .ml in this phase. A module with no .mli is itself a finding. Note the module, record what dune says about it, and move on.

Build the map

From the dune files alone, record:

  • Every library and executable, its public_name, and its libraries.
  • Which modules are (modules ...) of which stanza, and which are private.
  • Whether libraries are wrapped and what the wrapper module re-exports.
  • (flags ...), disabled warnings, preprocess stanzas.
  • Dependency direction between the project's own libraries, and any cycle pressure or layering violation.

State the map back as a short dependency listing before reviewing anything.

Judge each interface

For every .mli, check the following.

Shape

  • Does the module do one thing? A module that would need two synopsis sentences is two modules.
  • Is there a central type t, and is it abstract? Exposed records that carry invariants are a finding.
  • Are the values ordered sensibly, with constructors first, then accessors, then predicates and comparisons, then converters and printers?
  • Are pp, equal and compare present where the type warrants them?
  • Are the generic names gone? Util, Helpers, Common and Misc are findings.

API quality

  • Unlabelled booleans and unlabelled same-typed adjacent arguments.
  • find_* returning option and get_* returning a value directly, or the convention broken.
  • Error handling. Recoverable failure is a result. An exception in a public signature must be documented and justified.
  • Values exported only because a test or a sibling module needs them. These belong behind a private module or an _intf split.
  • Leaked internals. Types from a dependency in the signature that the caller should not have to depend on.

Documentation

  • Judge every doc comment against the doc-style skill. That skill is the standard, so load it before reviewing prose.
  • Missing synopsis, missing value docs, [f x y] is violations, colons and em dashes, prose about implementation, banned words.

Deliverable

Produce an interface report with, in order:

  1. The library and module map.
  2. Findings, grouped by module, each as file:line plus one sentence.
  3. A restructuring plan, if one is warranted. Say which modules split, merge, move library, or gain an .mli, and what the API break costs.
  4. A redocumentation plan, if one is warranted. List the files whose documentation is to be rewritten under doc-style.

Present this and stop. Restructuring is the user's call. Do not edit an interface, and do not start Phase 2, until the user has responded.

Phase 2: Implementations

Once the user has accepted or amended the plan, review the implementations.

Dispatch

One subagent per implementation module. Group only trivially small modules, never more than three per subagent, and never modules from different libraries.

Launch subagents in parallel, in a single message, up to six at a time. Wait for a batch to return before launching the next.

Give each subagent the module's .ml, its .mli, and the Phase 1 findings for that module. Use this prompt. The comment rules are spelled out in it rather than delegated, because a subagent may not have this plugin's skills available.

Review the implementation of <module> in <path>.ml against its interface in
<path>.mli. Read both files in full, plus any module it calls that you need
in order to judge a finding.

Report only defects you can point at. For each one give file:line, one
sentence of what is wrong, and one sentence of evidence. Do not edit any
file. Do not report style preferences that ocamlformat settles.

Look for, in this order:

1. Logic errors. Wrong base case, off-by-one, a partial match that will
   raise, an ignored result, an error path that loses information, a
   comparison that disagrees with equal, integer overflow, resource leaked on
   an exception path.
2. Dead code. Values never used inside the module and not in the .mli.
   Unreachable branches. Parameters never consulted. Types with no inhabitant
   constructed. Say for each whether it is safe to delete.
3. Redundancy. Two functions that compute the same thing. A hand-written loop
   that is a Stdlib or List function. A reimplementation of something already
   in this project's own libraries, which you should check for by name.
4. Optimisation. Quadratic behaviour on a path that takes user-sized input.
   Repeated work that could be hoisted. String concatenation in a loop where
   a Buffer belongs. An avoidable allocation on a hot path. Say what input
   size makes it matter, and skip it if none does.
5. Comments. Any comment inside the implementation that the code already
   says, which is to be deleted. Section banners and commented-out code, also
   deleted. Any doc comment in the .ml when an .mli exists, since the
   documentation belongs in the interface. A comment survives only if it
   cites a spec, states an invariant a reader cannot check locally, explains
   a deliberate workaround, or justifies an unsafe operation.
6. Interface drift. Behaviour that contradicts what the .mli documents.

Rank your findings by severity, most severe first. If a category is clean,
say so in one line rather than inventing a finding.

Aggregate

When every batch has returned:

  • Drop duplicates and anything a subagent could not support with evidence.
  • Add the cross-module findings no single subagent could see. The same helper written in three modules. A layering violation. A type converted back and forth across a boundary.
  • Rank everything by severity. Correctness first, then dead code, then redundancy, then optimisation, then comments.
  • Present the ranked list with file:line. Apply fixes only when the user asks, and apply them in that order.

Rules

  • Phase 1 reads no .ml. Phase 2 starts only after the user responds.
  • Every finding cites file:line.
  • Subagents review and report. They never edit.
  • An optimisation finding without a stated input size is noise. Drop it.
  • Do not report anything ocamlformat or dune fmt already handles.
  • Warnings that a dune stanza disables are findings in themselves.
  • A proposed change that breaks the public API is labelled as such, with the callers it affects.

RFC Integration for OCaml Projects

When to Use This Skill

Invoke this skill when:

  • User mentions implementing an RFC
  • Adding RFC citations to documentation
  • Fetching RFC specifications
  • Validating code against RFC requirements
  • Discussing internet protocol standards

RFC Fetching and Storage

Fetching RFCs

Always fetch RFCs in plain text format from:

https://datatracker.ietf.org/doc/html/rfcXXXX.txt

Important: Use .txt extension, not .html.

Storage Location

Save RFC files to spec/ directory in project root:

spec/rfc6265.txt
spec/rfc3492.txt

Create spec/ directory if it doesn't exist.

OCamldoc RFC Citation Format

Basic RFC Link

{{:https://datatracker.ietf.org/doc/html/rfcXXXX}RFC XXXX}

Section-Specific Links

{{:https://datatracker.ietf.org/doc/html/rfcXXXX#section-N.M}RFC XXXX Section N.M}

Common Section References

  • #section-N - Main numbered section
  • #section-N.M - Subsection
  • #appendix-X - Appendix (A, B, C, etc.)

Documentation Patterns

Citations are the one case where a doc comment carries a reference rather than behaviour. Everything else follows the doc-style skill, which you should load before writing the prose around a citation.

Module-Level Documentation

(** Punycode encoding for internationalised domain names.

    Punycode represents Unicode labels in the ASCII subset permitted in host
    names. This module implements
    {{:https://datatracker.ietf.org/doc/html/rfc3492}RFC 3492}.

    {2 References}
    {ul
    {- {{:https://datatracker.ietf.org/doc/html/rfc3492}RFC 3492} - Punycode}
    {- {{:https://datatracker.ietf.org/doc/html/rfc5891}RFC 5891} - IDNA}} *)

Function-Level Documentation

val adapt : delta:int -> numpoints:int -> firsttime:bool -> int
(** [adapt ~delta ~numpoints ~firsttime] is the new bias value.

    Implements the bias adaptation algorithm from
    {{:https://datatracker.ietf.org/doc/html/rfc3492#section-6.1}RFC 3492 Section 6.1}. *)

Type-Level Documentation

type error =
  | Overflow of position
      (** Arithmetic overflow. See
          {{:https://datatracker.ietf.org/doc/html/rfc3492#section-6.4}
          RFC 3492 Section 6.4}. *)
  | Invalid_digit of position * char
      (** Invalid Punycode digit. See
          {{:https://datatracker.ietf.org/doc/html/rfc3492#section-5}
          RFC 3492 Section 5}. *)

Constants and Parameters

val base : int
(** The base of the Punycode digit encoding. It is [36].
    See {{:https://datatracker.ietf.org/doc/html/rfc3492#section-5}
    RFC 3492 Section 5}. *)

Reading and Parsing RFCs

RFC Structure

  1. Header: RFC number, title, authors, date
  2. Table of Contents: Section numbers and titles
  3. Abstract: Brief summary
  4. Main Body: Numbered sections
  5. Appendices: Lettered sections
  6. References: Citations to other documents

Key Sections to Extract

  • Introduction - Background and motivation
  • Terminology - Key terms (MUST, SHOULD, MAY)
  • Algorithm - Core specification
  • Security Considerations - Security implications

Validation Workflow

  1. Read the RFC from spec/ directory
  2. Extract key requirements (MUST, SHOULD, MAY)
  3. Read implementation code
  4. Check each requirement is implemented
  5. Verify error handling matches RFC
  6. Report gaps or inconsistencies

Best Practices

DO

  • Always fetch and save RFC text files to spec/
  • Use section-specific links when possible
  • Link error types to their RFC requirements
  • Document RFC parameters and constants
  • Keep citations consistent across related functions

DON'T

  • Link to HTML versions of RFCs
  • Assume RFC sections without checking
  • Omit section numbers in citations
  • Duplicate RFC text verbatim (summarize instead)

Handling RFC Updates

When an RFC obsoletes another:

(** Implements {{:https://datatracker.ietf.org/doc/html/rfc6265}RFC 6265}
    which obsoletes {{:https://datatracker.ietf.org/doc/html/rfc2965}RFC 2965}. *)

Multiple RFC References

(** IDNA-compatible encoding combining
    {{:https://datatracker.ietf.org/doc/html/rfc5891}RFC 5891} (IDNA Protocol)
    with {{:https://datatracker.ietf.org/doc/html/rfc3492}RFC 3492} (Punycode). *)

OCaml Security Audit

Systematic security hardening through vulnerability research, defensive coding, and comprehensive testing.

Core Philosophy

  1. Study the attacks first: Research CVEs in equivalent C/Rust/Go/Python libraries before writing tests
  2. Assume hostile input: Every parser, decoder, and protocol handler receives adversarial data
  3. Fail explicitly: Reject malformed input early with clear errors, never silently corrupt
  4. Test the boundaries: Edge cases at min/max values, empty input, and overflow points
  5. Defense in depth: Multiple validation layers, even when one seems sufficient

Workflow

Phase 1: CVE Research

Before writing any tests, research known vulnerabilities in equivalent implementations.

1. Identify comparable libraries:

OCaml library     → Research in
─────────────────────────────────────
PNG/image parser  → libpng, image-rs, Pillow
TLS/crypto        → OpenSSL, BoringSSL, rustls
HTTP parser       → http-parser, hyper, httptools
JSON parser       → json-c, serde_json, ujson
XML parser        → libxml2, quick-xml, defusedxml
Archive (zip/tar) → libarchive, zip-rs, tarfile
DNS resolver      → c-ares, trust-dns, dnspython
Compression       → zlib, miniz, flate2
YAML parser       → libyaml, serde_yaml, PyYAML
PDF parser        → poppler, pdf-rs, PyPDF2
ASN.1/X.509       → OpenSSL, ring, pyasn1

2. Search for CVEs:

# Search NVD database
curl "https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=libpng+buffer+overflow" | jq '.vulnerabilities[].cve.descriptions[0].value'

# Search CVE Details
# https://www.cvedetails.com/vulnerability-search.php

# Search GitHub Security Advisories
gh api graphql -f query='{ securityAdvisories(first:10, ecosystem:PIP, keyword:"pillow") { nodes { summary description severity } } }'

# Check OSV database
curl "https://api.osv.dev/v1/query" -d '{"package": {"name": "pillow", "ecosystem": "PyPI"}}'

3. Document findings - track CVEs and map to tests. See references/vulnerability-classes.md.

Phase 2: Vulnerability Classes

For each vulnerability class, add targeted tests.

Integer Handling
(** Test integer overflow in length calculations.
    CVE pattern: libpng, zlib, many image libraries *)
let test_length_overflow () =
  let huge_width = Int.max_int in
  let huge_height = 1 in
  match Image.create ~width:huge_width ~height:huge_height with
  | Error `Overflow -> ()
  | Error _ -> Alcotest.fail "wrong error type"
  | Ok _ -> Alcotest.fail "should reject overflow"

(** Test signed/unsigned confusion.
    Signed length interpreted as huge unsigned value. *)
let test_negative_length () =
  let data = Bytes.create 4 in
  Bytes.set_int32_be data 0 (-1l);  (* 0xFFFFFFFF *)
  match Parser.read_with_length data with
  | Error (`Invalid_length _) -> ()
  | _ -> Alcotest.fail "should reject negative length"
Buffer Boundaries
(** Test out-of-bounds read.
    Claimed length exceeds actual data. *)
let test_oob_read () =
  let header = "\x00\x00\x00\x10" in  (* Claims 16 bytes *)
  let data = header ^ "short" in       (* Only 5 bytes of payload *)
  match Parser.decode data with
  | Error (`Truncated _) -> ()
  | Error _ -> Alcotest.fail "wrong error"
  | Ok _ -> Alcotest.fail "should reject truncated data"

(** Test empty input handling. *)
let test_empty_input () =
  match Parser.decode "" with
  | Error _ -> ()  (* Any error is acceptable *)
  | Ok _ -> Alcotest.fail "should reject empty input"
Denial of Service
(** Test resource exhaustion - deeply nested structures.
    CVE pattern: ujson, many JSON parsers *)
let test_deep_nesting () =
  let depth = 10000 in
  let nested = String.concat "" (List.init depth (fun _ -> "[")) ^
               String.concat "" (List.init depth (fun _ -> "]")) in
  match Json.parse nested with
  | Error (`Nesting_too_deep _) -> ()
  | Error _ -> ()  (* Resource errors are acceptable *)
  | Ok _ -> Alcotest.fail "should limit nesting depth"

(** Test exponential expansion (billion laughs).
    CVE pattern: XML entity expansion *)
let test_entity_expansion () =
  let malicious = "<!DOCTYPE x [<!ENTITY a \"aaa...(1000 chars)\">]><x>&a;&a;&a;...</x>" in
  match Xml.parse malicious with
  | Error _ -> ()
  | Ok _ -> Alcotest.fail "should reject entity expansion"

Phase 3: Fuzz Testing

Add fuzz tests for all parsers and encoders. See the fuzz skill for patterns.

Priority targets:

  1. Binary protocol parsers (highest risk)
  2. Text format parsers (JSON, XML, config files)
  3. Cryptographic operations
  4. Compression/decompression
  5. Character encoding conversions
(** Fuzz test: parser must not crash on any input. *)
let test_decode_crash_safety buf =
  let buf = truncate buf in
  let _ = Parser.decode (to_bytes buf) in
  ()

(** Fuzz test: encoder output must be parseable. *)
let test_roundtrip buf =
  let buf = truncate buf in
  match Parser.decode (to_bytes buf) with
  | Error _ -> ()
  | Ok v ->
      let encoded = Parser.encode v in
      match Parser.decode encoded with
      | Error _ -> fail "encoded data failed to parse"
      | Ok v' -> if v <> v' then fail "roundtrip mismatch"

Phase 4: CVE Regression Tests

For each applicable CVE, write a targeted regression test.

(** CVE-2023-XXXX regression test.

    Reference: https://nvd.nist.gov/vuln/detail/CVE-2023-XXXX

    Integer overflow when calculating buffer size from untrusted
    width/height values. *)
let test_cve_2023_xxxx () =
  let malicious_input = Bytes.of_string "\xff\xff\xff\xff\x00\x00\x00\x01" in
  match Image.decode malicious_input with
  | Error _ -> ()
  | Ok _ -> Alcotest.fail "CVE-2023-XXXX: should reject overflow"

Defensive Coding Patterns

Validate Early, Fail Fast

let decode buf =
  (* Check minimum size before any parsing *)
  if Bytes.length buf < header_size then
    Error (`Truncated { expected = header_size; got = Bytes.length buf })
  else
    let length = Bytes.get_int32_be buf 0 |> Int32.to_int in
    (* Validate length before allocating *)
    if length < 0 then
      Error (`Invalid_length length)
    else if length > max_message_size then
      Error (`Message_too_large { size = length; max = max_message_size })
    else if Bytes.length buf < header_size + length then
      Error (`Truncated { expected = header_size + length; got = Bytes.length buf })
    else
      parse_body buf length

Safe Integer Arithmetic (Hacker's Delight style)

Overflow detection without branches where possible, using bit manipulation.

(** Detect signed addition overflow (Hacker's Delight, 2-13).
    Overflow iff both operands have same sign and result has different sign. *)
let add_overflow a b =
  let sum = a + b in
  (* (a ^ sum) & (b ^ sum) is negative iff overflow *)
  (a lxor sum) land (b lxor sum) < 0

(** Detect signed multiplication overflow (Hacker's Delight, 2-13).
    For non-negative operands: a * b overflows iff a > max_int / b *)
let mul_overflow a b =
  if b = 0 then false
  else if b = -1 then a = Int.min_int  (* Special case: min_int * -1 *)
  else if b > 0 then a > Int.max_int / b || a < Int.min_int / b
  else (* b < -1 *) a > Int.min_int / b || a < Int.max_int / b

(** Safe addition with overflow check. *)
let safe_add a b =
  if add_overflow a b then Error `Overflow
  else Ok (a + b)

(** Safe multiplication with overflow check. *)
let safe_mul a b =
  if mul_overflow a b then Error `Overflow
  else Ok (a * b)

(** Unsigned comparison for signed integers (Hacker's Delight, 2-12).
    Interprets both values as unsigned. *)
let unsigned_lt a b =
  (a lxor Int.min_int) < (b lxor Int.min_int)

(** Check if value fits in n bits unsigned. *)
let fits_in_bits n v =
  v >= 0 && v < (1 lsl n)

(** Use in size calculations. *)
let calculate_buffer_size ~width ~height ~bytes_per_pixel =
  let open Result.Syntax in
  let* row_size = safe_mul width bytes_per_pixel in
  let* total = safe_mul row_size height in
  if total > max_buffer_size then Error `Buffer_too_large
  else Ok total

Safe Integer Narrowing

(** Safe conversion from int to int32. *)
let int_to_int32 n =
  if n < Int32.(to_int min_int) || n > Int32.(to_int max_int) then
    Error `Overflow
  else
    Ok (Int32.of_int n)

(** Safe conversion from int64 to int. *)
let int64_to_int n =
  if n < Int64.of_int Int.min_int || n > Int64.of_int Int.max_int then
    Error `Overflow
  else
    Ok (Int64.to_int n)

(** Convert length field to int, rejecting values that don't fit. *)
let length_field_to_int len_field =
  let open Result.Syntax in
  let* n = int64_to_int len_field in
  if n < 0 then Error (`Invalid_length n)
  else Ok n

Constant-Time Comparison

(** Constant-time string comparison for secrets.
    Prevents timing side-channels when comparing MACs, tokens, etc. *)
let constant_time_equal a b =
  let len_a = String.length a in
  let len_b = String.length b in
  let result = ref (len_a lxor len_b) in
  for i = 0 to min len_a len_b - 1 do
    result := !result lor (Char.code a.[i] lxor Char.code b.[i])
  done;
  !result = 0

Resource Limits

type limits = {
  max_depth : int;
  max_string_length : int;
  max_array_length : int;
  max_total_size : int;
}

let default_limits = {
  max_depth = 100;
  max_string_length = 10_000_000;
  max_array_length = 100_000;
  max_total_size = 100_000_000;
}

let parse ?(limits = default_limits) input =
  parse_with_limits ~limits input

Security Checklist

Before releasing any parser, encoder, or protocol handler:

Input Validation

  • Empty input rejected or handled correctly
  • Minimum size checked before parsing
  • Maximum size limits enforced
  • Length fields validated before use
  • Negative lengths rejected

Integer Safety

  • Multiplication overflow checked in size calculations
  • Addition overflow checked in offset calculations
  • No signed/unsigned confusion in lengths
  • Cast results checked when narrowing

Resource Limits

  • Nesting depth limited
  • Collection sizes limited
  • Total memory usage bounded
  • Recursion depth bounded

Fuzz Testing

  • Crash-safety test with arbitrary bytes
  • Roundtrip test for encode/decode pairs
  • AFL campaign run for 24+ hours
  • No crashes or hangs found

CVE Coverage

  • CVEs in similar libraries researched
  • Regression tests written for applicable CVEs
  • Tests documented with CVE references

References

  • references/vulnerability-classes.md - Detailed patterns for each vulnerability class
  • fuzz skill - Comprehensive fuzz testing patterns
  • ocaml-testing skill - Unit test organization

OCaml Testing

Test Directory Structure

Use test/ directory with:

  • test.ml - Main runner controlling initialization order
  • test_x.ml - One file per module x.ml being tested, exports suite
lib/
├── foo.ml
└── bar.ml
test/
├── dune
├── test.ml          # Main runner
├── test_foo.ml      # suite : (string * unit Alcotest.test_case list) list
└── test_bar.ml

For single-module libraries, a single test_foo.ml as runner is acceptable.

Dune Configuration

(test
 (name test)
 (libraries mylib alcotest logs logs.fmt fmt.tty))

Main Runner Pattern (test.ml)

The main test.ml controls initialization order for side effects:

(* 1. Initialize RNG before any test module is loaded *)
let () = Crypto_rng_unix.use_default ()

(* 2. Set up logging *)
let () = Fmt_tty.setup_std_outputs ()
let () = Logs.set_reporter (Logs_fmt.reporter ())
let () = Logs.set_level (Some Logs.Debug)

(* 3. Run all test suites *)
let () = Alcotest.run "mylib" Test_foo.suite

For multiple modules:

let () = Crypto_rng_unix.use_default ()
let () = Alcotest.run "mylib" (Test_foo.suite @ Test_bar.suite)

Module Test File Pattern (test_x.ml)

Each module exports a suite value. Do not initialize RNG or run Alcotest here.

(** Tests for Foo module. *)

let test_basic () =
  let result = Foo.process "input" in
  Alcotest.(check string) "expected output" "output" result

let test_empty () =
  let result = Foo.process "" in
  Alcotest.(check string) "empty input" "" result

let suite =
  [
    ( "process",
      [
        Alcotest.test_case "basic" `Quick test_basic;
        Alcotest.test_case "empty" `Quick test_empty;
      ] );
  ]

Lazy State for Module-Level Values

If a test module needs RNG at load time, use lazy evaluation:

let key = lazy (Crypto_rng.generate 32)
let key () = Lazy.force key

let test_encrypt () =
  let ciphertext = Foo.encrypt ~key:(key ()) plaintext in
  ...

This defers RNG use until tests actually run, after test.ml initializes the RNG.

Alcotest Patterns

Custom Testables

let result_testable ok_t =
  Alcotest.result ok_t Alcotest.string

let my_type_testable =
  Alcotest.testable My_type.pp My_type.equal

Common Checks

Alcotest.(check int) "count" 42 actual
Alcotest.(check string) "name" expected actual
Alcotest.(check bool) "flag" true actual
Alcotest.(check (list int)) "items" [1;2;3] actual
Alcotest.(check (option string)) "maybe" (Some "x") actual
Alcotest.(check (result int string)) "result" (Ok 42) actual

Testing Exceptions

let test_raises () =
  Alcotest.check_raises "should fail" (Invalid_argument "bad")
    (fun () -> Foo.parse "bad")

Initialization Order

Always initialize in test.ml before Alcotest.run:

  1. RNG - Crypto_rng_unix.use_default () or Mirage_crypto_rng_unix.use_default ()
  2. Logging - Logs.set_reporter and Logs.set_level
  3. Other global state - Environment setup, temp directories

This ensures deterministic test ordering and proper side-effect sequencing.

Test Logging

Set up logging in tests using the standard Logs library:

let () = Fmt_tty.setup_std_outputs ()
let () = Logs.set_reporter (Logs_fmt.reporter ())
let () = Logs.set_level (Some Logs.Debug)

Default behaviour: Logs at Debug level. Alcotest captures output to a file by default, so verbose logging doesn't clutter the terminal. Output is shown only when tests fail.

Per-Source Overrides

For per-source control, set levels after the reporter:

let () = Logs.Src.set_level Conpool.src (Some Logs.Debug)
let () = Logs.Src.set_level Requests.src (Some Logs.Warning)

Why Default to Debug?

  1. Alcotest captures output: Verbose logs don't clutter terminal
  2. Shown on failure: When a test fails, you see all the debug info
  3. No re-running needed: Debug output is already captured

Core Philosophy

  1. Unit Tests First: Prioritize unit tests for individual modules and functions.
  2. 1:1 Test Coverage: Every module in lib/ should have a corresponding test module in test/.
  3. Isolated Tests: Each test should be independent and not rely on external state.
  4. Clear Test Names: Test names should describe what they test, not how.
  5. Test Inclusion: All test suites must be included in the main test runner.

Naming Conventions

  • Test suite names: lowercase, single words (e.g., "users", "commands", "process")
  • Test case names: lowercase with underscores, concise but descriptive (e.g., "basic", "empty_input", "parse_error")

Writing Good Tests

Function Coverage: Test all public functions exposed in .mli files, including success, error, and edge cases.

Test Data: Use helper functions to create test data:

let make_user ?(name = "test") ?(id = 1) () = User.v ~name ~id

Property-Based Testing: For complex logic, consider property-based testing with QCheck:

let test_roundtrip =
  QCheck.Test.make ~count:1000
    ~name:"encode then decode is identity"
    QCheck.string
    (fun s -> Codec.decode (Codec.encode s) = s)

End-to-End Testing with Cram

Cram tests verify CLI executable behavior.

Use Cram Directories: Every Cram test should be a directory ending in .t (e.g., my_feature.t/).

Create Actual Test Files: Avoid embedding code within run.t using heredocs. Create real source files within the test directory.

test/
└── my_feature.t/
    ├── run.t           # The cram test script
    ├── input.txt       # Test input file
    └── expected.json   # Expected output

Running Tests

# Run all tests
dune test

# Run tests and watch for changes
dune test -w

# Run a specific test
dune exec test/test.exe -- test "suite_name"

# Run tests with coverage
dune test --instrument-with bisect_ppx
bisect-ppx-report summary

OCaml Tutorial Creation

When to Use This Skill

Invoke this skill when:

  • Creating tutorials for OCaml libraries
  • Working with .mld documentation format
  • Setting up MDX for executable examples
  • Discussing interactive documentation

Overview

Prose in .mld pages and in the doc comments a tutorial quotes follows the doc-style skill. Load it before writing them. A tutorial may address the reader and explain motivation, which reference documentation may not, but the sentences are still complete and free of filler.

OCaml tutorials should:

  • Introduce concepts gently
  • Use executable code examples via MDX
  • Progress from simple to complex
  • Include practical patterns and use cases

File Structure

Required Components

  1. doc/ directory in project root
  2. tutorial.mld - Main tutorial content
  3. index.mld - Documentation index
  4. dune - Build rules

doc/dune Configuration

(mdx
 (files tutorial.mld)
 (libraries your_library_name))

(documentation
 (package your_package_name)
 (mld_files index tutorial))

dune-project Updates

Enable MDX:

(using mdx 0.4)

Add MDX as doc dependency:

(package
 (name your_package)
 (depends
  ...
  (mdx :with-doc)
  (odoc :with-doc)))

.mld Format

Document Structure

{0 Topic Name Tutorial}

Introduction text.

{1 Section Title}

Section content.

{2 Subsection Title}

Subsection content.

Executable Code Blocks

Use {@ocaml[...]} for executable examples:

{@ocaml[
# let x = 1 + 1;;
val x : int = 2
]}
  • Lines starting with # are input
  • Following lines are expected output
  • MDX verifies output at build time
  • Use ;; to terminate expressions

Non-Executable Code

Use {v ... v} for verbatim blocks:

{v
name: Alice
age: 30
v}

Cross-References

{!Library.function_name}          - Function reference
{!Library.Module.type_name}       - Type reference
{{!Library}API reference}         - Link with custom text

Lists

{ul
{- Item one}
{- Item two}
}

{ol
{- First item}
{- Second item}
}

Formatting

{b bold text}
{i italic text}

Tutorial Content Guidelines

Structure

  1. Setup - How to load the library
  2. Basic Usage - Simplest examples
  3. Core Concepts - Main types and functions
  4. Common Patterns - Real-world usage
  5. Advanced Features - Complex functionality
  6. Error Handling - How errors work
  7. Summary - Quick reference

Setup Section

{1 Setup}

{@ocaml[
# #require "library_name";;
# open Library;;
]}

Best Practices

  1. Show output - Include expected output in examples
  2. Use consistent naming - Variables carry through examples
  3. Build complexity gradually - Each example builds on previous
  4. Explain the "why" - Not just syntax, but when to use features
  5. Reference documentation - Link to API docs

Verification

dune build @check    # Verify syntax
dune build @doc      # Build documentation
dune runtest         # Run MDX tests (if configured)

Common Issues

Unresolved References

Use fully qualified names: {!Library.of_string} not {!of_string}

MDX Not Found

Enable in dune-project: (using mdx 0.4)

Output Mismatch

Run code manually, update expected output. Use <abstr> for abstract values.

Commands 5

Add RFC

This command fetches an IETF RFC specification and integrates it into the project.

Arguments

RFC number: $ARGUMENTS (required, e.g., "6265" for HTTP cookies)

Process

1. Fetch the RFC

Fetch from IETF in plain text format:

https://datatracker.ietf.org/doc/html/rfc<NUMBER>.txt

Important: Always use .txt extension, not .html.

2. Save to spec/ Directory

Create spec/ directory if it doesn't exist and save:

spec/rfc<NUMBER>.txt

3. Parse RFC Structure

Extract key information:

  • RFC title and abstract
  • Table of contents (sections)
  • Key terminology definitions
  • Related RFCs (obsoletes, updates, references)

4. Generate OCamldoc Citation Templates

Provide ready-to-use citations for:

Module-level:

(** RFC <NUMBER> <Title>.

    This module implements <description> as specified in
    {{:https://datatracker.ietf.org/doc/html/rfc<NUMBER>}RFC <NUMBER>}.

    {2 References}
    {ul
    {- {{:https://datatracker.ietf.org/doc/html/rfc<NUMBER>}RFC <NUMBER>} - <Title>}} *)

Section-specific:

(** Implements {{:https://datatracker.ietf.org/doc/html/rfc<NUMBER>#section-N}RFC <NUMBER> Section N}. *)

5. Suggest Integration Points

Search the codebase for:

  • Functions that might implement RFC sections
  • Existing RFC references that could be improved
  • Types that represent RFC concepts

Output

Provide:

  1. Confirmation of RFC download
  2. Summary of RFC contents (title, sections)
  3. OCamldoc citation templates, worded under the doc-style skill
  4. Suggestions for where to add citations in existing code

Example Usage

/add-rfc 6265
/add-rfc 3492

Success Output

Fetched RFC 6265: HTTP State Management Mechanism

Saved to: spec/rfc6265.txt

RFC Summary:
  Title: HTTP State Management Mechanism
  Obsoletes: RFC 2965
  Sections:
    1. Introduction
    2. Conventions
    3. Overview
    4. Server Requirements
    5. User Agent Requirements
    6. Implementation Considerations
    7. Privacy Considerations
    8. Security Considerations

OCamldoc Templates:

Module-level:
(** RFC 6265 HTTP State Management Mechanism.

    This module implements HTTP cookie handling as specified in
    {{:https://datatracker.ietf.org/doc/html/rfc6265}RFC 6265}. *)

Section references:
- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4}RFC 6265 Section 4} - Server Requirements
- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5}RFC 6265 Section 5} - User Agent Requirements
- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2}RFC 6265 Section 5.2} - The Set-Cookie Header

Related RFCs you might also need:
- RFC 2616 - HTTP/1.1 (obsoleted by RFC 7230-7235)
- RFC 7230 - HTTP/1.1 Message Syntax and Routing

Initialize OCaml Project

This command creates a new OCaml project with all standard files and configuration.

Arguments

Project name: $ARGUMENTS (defaults to current directory name if not provided)

Configuration

Read user configuration from ~/.claude/ocaml-config.json. If it doesn't exist, prompt the user for:

  • Author name
  • Author email
  • Preferred license (ISC, MIT, Apache-2.0)
  • CI platform (github, tangled, gitlab)
  • Git hosting (github.com/user, tangled.org/@user, gitlab.com/user)
  • OCaml version minimum (default: 5.2.0)

Offer to save configuration to ~/.claude/ocaml-config.json for future use.

Files to Create

Essential Files

  1. dune-project - Build configuration with opam generation
  2. dune (root) - With (data_only_dirs third_party)
  3. .opam - Generated by dune (do not create manually)
  4. .ocamlformat - Code formatting (version 0.28.1)
  5. .gitignore - Standard OCaml ignores + third_party/
  6. LICENSE.md - Based on configured license
  7. README.md - Project documentation template

CI Configuration (based on ci_platform setting)

  • github: .github/workflows/build.yml
  • tangled: .tangled/workflows/build.yml
  • gitlab: .gitlab-ci.yml

Source Files

  1. lib/dune - Library stanza
  2. lib/.ml - Main module with license header
  3. lib/.mli - Interface with documentation, written under the doc-style skill, which you should invoke before writing any doc comment

Test Files

  1. test/dune - Test configuration
  2. test/test_.ml - Basic test skeleton with Alcotest

Workflow

  1. Check if directory is empty or confirm overwrite
  2. Read or prompt for configuration
  3. Determine project name from argument or directory
  4. Create all files using templates from the ocaml-project-setup skill
  5. Run dune build @check to verify setup
  6. Report success and suggest next steps

Template Variables

Replace these in templates:

  • {{PROJECT_NAME}} - Project name (snake_case)
  • {{PROJECT_NAME_KEBAB}} - Project name (kebab-case)
  • {{AUTHOR_NAME}} - From config
  • {{AUTHOR_EMAIL}} - From config
  • {{YEAR}} - Current year
  • {{LICENSE}} - License identifier
  • {{OCAML_VERSION}} - Minimum OCaml version
  • {{GIT_URL}} - Full git URL based on hosting config
  • {{SOURCE_STANZA}} - dune source stanza based on hosting:
    • tangled: (source (tangled handle/{{PROJECT_NAME_KEBAB}}))
    • github: (source (github user/{{PROJECT_NAME_KEBAB}}))
    • gitlab: (source (gitlab user/{{PROJECT_NAME_KEBAB}}))

Example Usage

/init-ocaml my-library
/init-ocaml

Success Output

Created OCaml project: my-library

Files created:
  - dune-project
  - dune
  - .ocamlformat
  - .gitignore
  - LICENSE.md
  - README.md
  - .github/workflows/build.yml
  - lib/dune
  - lib/my_library.ml
  - lib/my_library.mli
  - test/dune
  - test/test_my_library.ml

Next steps:
  1. Run `opam install . --deps-only` to install dependencies
  2. Run `dune build` to build the project
  3. Run `dune runtest` to run tests

OCaml NPM Setup

This command sets up the npm publishing workflow for OCaml projects compiled to JavaScript/WASM.

Arguments

None - operates on the current directory.

Prerequisites

  • Existing OCaml project with dune
  • js_of_ocaml or wasm_of_ocaml dependencies configured
  • Git repository initialized

Two-Branch Workflow

main branch   - OCaml source code, dune build files, opam packages
npm branch    - Built JavaScript/WASM assets, package.json, README for npm

Process

1. Analyze Project

Determine:

  • Project name from dune-project
  • Existing JS build targets
  • Whether to support JS, WASM, or both

2. Create/Update Dune Build Rules

Add or update lib/js/dune (or appropriate location):

(library
 (name <project>_js)
 (public_name <project>-js)
 (libraries <project> brr)
 (modes byte)
 (modules <project>_js))

(executable
 (name <project>_js_main)
 (libraries <project>_js)
 (js_of_ocaml)
 (modes js wasm)
 (modules <project>_js_main))

; Friendly filenames
(rule
 (targets <project>.js)
 (deps <project>_js_main.bc.js)
 (action (copy %{deps} %{targets})))

(rule
 (targets <project>.wasm.js)
 (deps <project>_js_main.bc.wasm.js)
 (action (copy %{deps} %{targets})))

; Install rules
(install
 (package <project>-js)
 (section share)
 (files
  <project>.js
  <project>.wasm.js
  (glob_files_rec (<project>_js_main.bc.wasm.assets/* with_prefix <project>_js_main.bc.wasm.assets))))

3. Update dune-project

Add -js package if not present:

(package
 (name <project>-js)
 (synopsis "Browser library via js_of_ocaml/wasm_of_ocaml")
 (depends
  (ocaml (>= 5.1.0))
  (<project> (= :version))
  (js_of_ocaml (>= 5.0))
  (js_of_ocaml-ppx (>= 5.0))
  (wasm_of_ocaml-compiler (>= 5.0))
  (brr (>= 0.0.6))))

4. Create npm Branch

Create orphan branch with:

  • package.json
  • README.md (browser-focused)
  • LICENSE
  • release.sh
  • .gitignore

5. Generate release.sh Script

#!/bin/bash
# Release script for npm package
set -e

INSTALL_DIR="_build/install/default/share/<project>-js"

# ... copy JS, WASM loader, and assets

Files Created

On main branch:

  • lib/js/dune (or updates existing)
  • Updates to dune-project

On npm branch (new orphan):

  • package.json
  • README.md
  • LICENSE
  • release.sh
  • .gitignore

Example Usage

/ocaml-npm

Success Output

Set up npm publishing workflow for: my-library

Main branch updates:
  - Created lib/js/dune with JS/WASM build rules
  - Updated dune-project with my-library-js package

Created npm branch with:
  - package.json (name: my-library-jsoo)
  - README.md (browser usage documentation)
  - LICENSE
  - release.sh (copies built assets)
  - .gitignore

Workflow:
  1. Develop on main branch
  2. Build: opam exec -- dune build @install
  3. Switch to npm: git checkout npm
  4. Copy assets: ./release.sh
  5. Publish: npm publish

Current branch: main
To switch to npm branch: git checkout npm

Port to Dune

This command migrates an OCaml project from ocamlbuild/topkg to dune.

Arguments

None - operates on the current directory.

Prerequisites

The command expects to find ocamlbuild artifacts:

  • _tags - ocamlbuild compilation flags
  • *.mllib files - module lists for libraries
  • pkg/pkg.ml - topkg package description (optional)
  • pkg/META - findlib metadata (optional)
  • opam - package dependencies

Migration Process

1. Analyze Existing Build

Read and parse:

  • _tags - Extract package dependencies, compiler flags, thread usage
  • *.mllib - Identify libraries and their modules
  • pkg/pkg.ml - Find optional libraries and conditions
  • pkg/META - Get public library names
  • opam - Current dependencies

2. Create dune-project

(lang dune 3.20)
(name <package-name>)
(generate_opam_files true)
; ... rest from existing opam metadata

3. Create Library dune Files

For each library identified from .mllib files:

(library
 (name <library_name>)
 (public_name <package.subname>)
 (libraries <dependencies>))

For optional libraries (from pkg/pkg.ml):

(library
 (name <library_name>)
 (public_name <package.subname>)
 (optional)
 (libraries <dependencies>))

4. Handle Special Cases

Warning suppression (if needed):

(flags (:standard -w -27))

Toplevel init files (excluded from library):

(library
 (name lib_name)
 (modules lib_module)
 (libraries deps))

(install
 (package pkg)
 (section lib)
 (files lib_top_init.ml))

5. Create Test dune Files

(test
 (name test_name)
 (libraries lib_name alcotest))

6. Update opam File

  • Rename opam to <package>.opam
  • Remove ocamlbuild/topkg dependencies
  • Add dune dependency
  • Update build commands

7. Cleanup

List files to delete (don't delete automatically):

  • _tags
  • .merlin
  • pkg/pkg.ml
  • pkg/META
  • *.mllib files
  • *.itarget files

Mapping Reference

ocamlbuilddune
_tags: package(foo)(libraries foo)
_tags: thread(libraries threads)
foo.mllib(library (name foo))
pkg/pkg.ml: Pkg.mllib ~cond:x(library ... (optional))
pkg/METAAuto-generated by dune

Workflow

  1. Search for ocamlbuild artifacts
  2. Parse each file to understand project structure
  3. Create dune-project at root
  4. Create dune files for each directory with sources
  5. Update opam file
  6. Run dune build @check to verify
  7. List cleanup actions for user to confirm

Example Usage

/port-to-dune

Success Output

Analyzed ocamlbuild project structure:
  - Found 3 libraries: logs, logs_fmt, logs_browser
  - Found 2 optional libraries: logs_fmt, logs_browser
  - Found test executable: test_logs

Created dune files:
  - dune-project
  - src/dune
  - src/fmt/dune
  - src/browser/dune
  - test/dune

Updated:
  - logs.opam (renamed from opam, updated build commands)

Files to delete manually:
  - _tags
  - pkg/pkg.ml
  - pkg/META
  - src/logs.mllib
  - src/logs_fmt.mllib
  - src/logs_browser.mllib

Run `dune build` to verify the migration.

Tidy OCaml Code

This command analyzes and refactors OCaml code to make it more idiomatic, maintainable, and concise.

Arguments

Optional file or directory path: $ARGUMENTS (defaults to current directory)

Before You Start

Invoke the doc-style skill. Comments and documentation are part of tidying, and that skill is the standard for both.

Analysis Categories

1. Option and Result Patterns

Look for:

  • Verbose match expressions that could use combinators
  • Nested Option/Result handling without let*/let+
  • Direct pattern matching where Option.map, Option.bind, etc. would be clearer

Transform:

(* Before *)
match get_value () with
| Some x -> Some (x + 1)
| None -> None

(* After *)
Option.map (fun x -> x + 1) (get_value ())

2. Monadic Syntax

Look for:

  • Deeply nested match expressions on Result/Option
  • Manual error propagation chains

Transform:

(* Before *)
match fetch_user id with
| Ok user ->
    (match fetch_perms user with
     | Ok perms -> Ok (user, perms)
     | Error e -> Error e)
| Error e -> Error e

(* After *)
let open Result.Syntax in
let* user = fetch_user id in
let+ perms = fetch_perms user in
(user, perms)

3. Pattern Matching vs Conditionals

Look for:

  • Nested if/then/else chains
  • Boolean condition checking that could be pattern matching

Transform:

(* Before *)
if x > 0 then
  if x < 10 then "small"
  else "large"
else "negative"

(* After *)
match x with
| x when x < 0 -> "negative"
| x when x < 10 -> "small"
| _ -> "large"

4. Code Duplication

Look for:

  • Repeated error message patterns
  • Similar function implementations
  • Copy-pasted code blocks

Suggest:

  • Helper functions
  • Parameterized abstractions
  • Shared error constructors

5. Module Hygiene

Look for:

  • Generic module names (Util, Helpers, Common)
  • Exposed record types without abstract type t
  • Missing pretty-printers for main types
  • Unlabeled boolean parameters

6. Comments and Documentation

Look for:

  • Comments inside an implementation that restate the code
  • Section banners and commented-out code
  • Doc comments in an .ml that has an .mli
  • Doc comments that describe the implementation rather than the behaviour
  • Function docs that do not open [f x y] is ...
  • Colons and em dashes joining clauses, and filler such as This function, Note that, simply, helper for

Transform: delete the first three outright. Rewrite the rest under the doc-style skill.

7. Modern OCaml Patterns

Suggest:

  • Labeled arguments for clarity
  • Local opens for syntax extensions
  • Explicit type annotations on public interfaces

Workflow

  1. If a specific file is given, analyze that file
  2. Otherwise, find all .ml and .mli files
  3. Analyze each file for improvement opportunities
  4. Prioritize by impact:
    • Code duplication (highest)
    • Verbose monadic code
    • Module structure issues
    • Nested conditionals
  5. Present findings with before/after examples
  6. Apply changes with user confirmation

Output Format

Analysis of lib/parser.ml:

1. OPTION COMBINATORS (3 occurrences)
   Line 45: Replace match with Option.map
   Line 89: Replace match with Option.bind
   Line 123: Replace match with Option.value

2. MONADIC SYNTAX (1 occurrence)
   Lines 156-178: Use let*/let+ for cleaner Result chaining

   Before:
   [code snippet]

   After:
   [refactored snippet]

3. CODE DUPLICATION (2 occurrences)
   Lines 34, 67: Duplicate error construction
   Suggestion: Create helper function `parse_error`

Apply changes? [y/n/select]

Example Usage

/tidy
/tidy lib/parser.ml
/tidy src/

Success Output

Analyzed 12 OCaml files in lib/

Improvements found:
  - 8 Option/Result patterns to simplify
  - 3 monadic chains to use let*/let+
  - 2 code duplication instances
  - 1 module naming issue

Applied 13 changes:
  - lib/parser.ml: 5 changes
  - lib/types.ml: 3 changes
  - lib/utils.ml: 5 changes (renamed to lib/string_ext.ml)

Reduced total lines: 847 -> 762 (-10%)

Suggestions not applied (require manual review):
  - Consider abstracting User.t type (lib/user.ml:12)
  - Add pp function to Config module (lib/config.ml)

Sponsors

Details

Marketplace
avsm/ocaml-claude-marketplace
Source
plugins/ocaml-dev
Author
Anil Madhavapeddy
Category
Development