# Language & Compiler — ModelHike

A language for WHAT. Blueprints for HOW.

ModelHike is a typed application modeling language and compiler. Lightweight, Markdown-inspired syntax defines application structures and supported behavior. The compiler validates models and turns supported declarations into conventional source code through framework-specific blueprints.

Readable enough to discuss. Precise enough to compile.

## Syntax at a glance

```
===
Billing APIs   #blueprint(api-nestjs-monorepo)
====
+ Billing

=== Billing ===

Subscription
============
** _id: String
*  plan: Plan
*  owner: Customer
*  startDate: Date
-  cancelledAt: Date
~  cancel(): void
~  renew(months): Subscription
```

- `**` identity · `*` required · `-` optional · `~` method signature
- `===` containers and modules · `+` declares a module
- `#blueprint(…)` assigns the generation target

(Syntax excerpt — Plan and Customer definitions omitted. A runnable model defines every referenced type.)

## Workflow
01 Define — describe application concepts and supported behaviors.
02 Validate — structural and semantic rules with compiler diagnostics.
03 Inspect — entities, operations, dependencies, generated artifacts.
04 Compile — transform definitions into source via blueprints.
05 Extend — conventional code for algorithms.

## Pipeline
Discover → Load → Hydrate → Validate → Render → Persist

## CLI
Non-interactive Smart CLI: human-readable by default, `--format json` for structured output, stdin via `--input -`, no prompts.

```
modelhike validate --input -
modelhike dry-run --input model.modelhike --blueprint api-nestjs-monorepo --container APIs
modelhike generate --input model.modelhike --blueprint api-nestjs-monorepo --container APIs --output ./generated
modelhike explain --input model.modelhike --format human
modelhike what-depends-on Payment --input model.modelhike
modelhike fix --input model.modelhike --codes W301
modelhike preflight --input model.modelhike --blueprint api-nestjs-monorepo
```

Exit codes: 0 success · 1 warnings · 2 errors · 3 parse failure · 4 generation failure.
Diagnosing an unresolved type (documented example): `W301 — Type 'CustomerProfile' referenced by property 'owner' in 'Subscription' not found.`
With `--blueprint`, also pass a target (`--container` or `--system-view`). Default output: `./modelhike-output`.

## MCP (stdio)
`modelhike/validate` · `generate` · `dry-run` · `inline-generate` · `explain` · `inspect` · `what-depends-on` · `list-types` · `fix` · `preflight` · `list-blueprints` · `dsl-schema-in-markdown` — structured JSON tools for Cursor, Windsurf, Claude Code.

```json
{ "mcpServers": { "modelhike": { "command": "/path/to/.build/debug/modelhike-mcp", "transportType": "stdio" } } }
```

## Blueprints
- `api-nestjs-monorepo` — NestJS + TypeScript monorepo: REST, CQRS (`@nestjs/cqrs`), MongoDB, Yup, soft delete + audit, pagination, PlantUML
- `api-springboot-monorepo` — Spring Boot 3.x + Java: GraphQL, reactive WebFlux, MongoDB
- Custom blueprints: `--blueprints <path>` or `MODELHIKE_BLUEPRINTS`. Blueprints differ in capability and surface.

## Why compile a spec
Spec-driven development is an important step forward. But a specification interpreted by an AI and a specification understood by a compiler are not the same thing. Interpreted specs leave implementation open; probabilistic generation varies; every change re-opens review.

## Fix the source. Not the symptoms.
Spec-driven AI: Update spec → AI interpretation → Generated changes → Review and correct.
ModelHike: Update supported Source Model → Validate → Compile → Verify.
AI still finds the right change. Once a decision is in a blueprint, nobody reinvents it.

## Prompts propose. Compilers enforce their rules.
AI drafts → validate → diagnose → fix → explain → approve → generate.
Deterministic = repeatable output from fixed model, blueprint, toolchain, configuration. Not a correctness guarantee.
Use intelligence where judgment is needed. Use determinism where the rules are known.

## Roadmap (direction, not shipped)
From modeling structure to modeling outcomes: a payment authorized, an order fulfilled, a refund within limits — without prescribing every algorithm. Also: packaged CLI, VS Code extension, plugin system.

Links: [GitHub](https://github.com/modelhike/modelhike) · [Docs](https://github.com/modelhike/modelhike/tree/main/docs) · [FAQ](/faq.html)