codedash-schemas

Stable public schema types for codedash code metrics output.

Overview

This crate provides the external contract for codedash's analysis JSON output. Internal domain model changes in codedash are absorbed by an Anti-Corruption Layer (ACL), so this schema remains stable for downstream consumers.

                          codedash (binary/lib)
                         ┌──────────────────────────────────┐
                         │  domain/ast.rs                    │
                         │  (internal model — may change)    │
                         │              │                    │
                         │              ▼                    │
                         │  port/schema.rs  (ACL: From impls)│
                         │              │                    │
                         └──────────────┼────────────────────┘
                                        ▼
                         ┌──────────────────────────────────┐
                         │  codedash-schemas                 │
                         │  (public contract — stable)       │
                         └──────────────────────────────────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    ▼                   ▼                   ▼
              Rust consumers      JSON consumers      GUI (egui-cha etc.)
              (serde deser)       (JSON Schema)       (Rust SDK)

Design: Anti-Corruption Layer (ACL)

codedash follows DDD's Anti-Corruption Layer pattern to decouple the public schema from the internal domain model:

• domain/ast.rs (codedash internal) — Internal types optimized for parsing and enrichment logic. May change freely across codedash versions.
• port/schema.rs (codedash internal) — The ACL boundary. From trait implementations map domain types to schema types. This is the only place where the two models touch.
• codedash-schemas (this crate) — Stable public types. Versioned independently. Breaking changes follow semver.

This separation ensures:

1. codedash can refactor its internals without breaking consumers
2. The JSON output format has an explicit, documented contract
3. Schema types carry minimal dependencies (serde only, no tree-sitter/git2/mlua)

Usage

Rust consumers

Add to Cargo.toml:

[dependencies]
codedash-schemas = "0.1"
serde_json = "1"

Deserialize codedash's JSON output:

use codedash_schemas::AstData;

let json = std::fs::read_to_string("analysis.json")?;
let data: AstData = serde_json::from_str(&json)?;

for file in &data.files {
    for node in &file.nodes {
        if let Some(cc) = node.cyclomatic {
            println!("{}/{}: cyclomatic={}", file.name, node.name, cc);
        }
    }
}

JSON Schema (non-Rust consumers)

A pre-generated JSON Schema file is available at:

codedash-schemas/schema/ast-data.schema.json

Non-Rust consumers (TypeScript, Python, Go, etc.) can use this file for validation or type generation:

• TypeScript: generate interfaces via json-schema-to-typescript
• Python: generate Pydantic models via datamodel-code-generator
• Go: generate structs via go-jsonschema

The schema file is kept up-to-date by CI. When a PR touches codedash-schemas/, GitHub Actions regenerates the JSON Schema and auto-commits any diff.

Generating from Rust

Enable the schema feature to derive schemars::JsonSchema on all types.

[dependencies]
codedash-schemas = { version = "0.1", features = ["schema"] }
schemars = "1"

let schema = schemars::schema_for!(codedash_schemas::AstData);
let json = serde_json::to_string_pretty(&schema).unwrap();
std::fs::write("ast-data.schema.json", json).unwrap();

To regenerate locally, run the bundled example:

cargo run -p codedash-schemas --example generate_schema --features schema \
  > codedash-schemas/schema/ast-data.schema.json

Types

Optional features

Minimum Supported Rust Version

1.80

License

MIT