Comonicon.jl AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Comonicon is a Julia CLI generator that transforms function definitions and docstrings into full-featured command-line interfaces with zero duplication, zero overhead, and zero dependencies. The two primary user-facing macros are @cast (mark a function/module as a CLI command) and @main (declare the CLI entry point).

Build & Test Commands

julia --project -e 'using Pkg; Pkg.instantiate()'   # Install dependencies
julia --project test/runtests.jl                     # Run all tests
julia --project -e 'using Pkg; Pkg.test()'           # Run tests via Pkg

To run a single testset:

julia --project -e 'using Test; include("test/runtests.jl")' # all
# Run a specific file directly (most test files are self-contained):
julia --project test/options.jl
julia --project test/frontend/cast.jl

Pre-commit Checklist

julia --project -e 'using JuliaFormatter; format("src")'  # Format (margin=102)
julia --project test/runtests.jl                           # Tests

JuliaFormatter config: always_for_in=true, margin=102.

Architecture

The pipeline is: Julia source → Frontend (parse) → AST → Codegen → executable CLI.

Modules

Module	Path	Role
Frontend	src/frontend/	@cast/@main macros; parse function signatures and markdown docstrings into CLI metadata
AST	src/ast/	Immutable command-tree types: Entry → NodeCommand/LeafCommand → Argument/Option/Flag
Codegen	src/codegen/	emit() converts Entry to Julia Expr; also generates bash/zsh completions
Builder	src/builder/	Compilation, installation, system image generation via PackageCompiler

Key Types (src/ast/types.jl)

Entry
  └─ root: Union{NodeCommand, LeafCommand}
       ├─ NodeCommand  — routing node; holds OrderedDict of subcommands
       └─ LeafCommand  — executable leaf; holds Vector[Argument], OrderedDict[Option/Flag]