domaintrail 0.3.0 → 0.5.0

package/README.md

@@ -2,8 +2,9 @@
 
 A type-checkable domain modeling DSL shared by humans and AI.
 AI agents edit `.dt` files; humans watch the model update live in the browser and give feedback.
-The DSL is the single source of truth for domain **structure and contracts** — it generates TypeScript types and command
-contracts, never business logic.
+The DSL is the single source of truth for domain **structure and contracts** — it generates TypeScript types, command
+contracts, checks of the invariants and requirements it states, and contract tests for your implementation, never
+business logic.
 
 ## Setup
 
@@ -17,50 +18,82 @@ npx domaintrail <command>    # or run it without installing
 ## CLI
 
 ```bash
-dt guide                       # the guide: DSL, file layout, workflow, config, output and exit codes
+dt guide [topic]               # quick reference and topics; one topic (dt guide requires); --all for everything
+dt -r <root> fmt               # format .dt files in place in the canonical layout (--check for CI)
 dt -r <root> check             # validate syntax, references, types and DDD rules
 dt -r <root> generate ts       # generate TypeScript into <root>/generated/domain (--out to change)
 dt -r <root> view              # Live View at http://127.0.0.1:4321 (--port, --host); runs until Ctrl+C
+dt lsp                         # language server over stdio: dt check's diagnostics, definitions, references, hover
+dt -r <root> show <name>        # one element resolved: field sets, labels, commands' contracts, who uses it
 ```
 
 The package installs the same command under two names: `dt` for everyday use and `domaintrail`, its full name, for
 when `dt` clashes with another command or a script should spell it out (CI, for example).
 
-`<root>` defaults to the current directory; every `*.dt` file below it (except `node_modules`, `.git`, `.domaintrail`)
-belongs to the workspace. `dt --help` and `dt <command> --help` show the options with examples.
+`<root>` defaults to the current directory; every `*.dt` file below it (except in `node_modules`, `.git`, `.domaintrail`
+and what `.gitignore` ignores) belongs to the workspace, unless a `domaintrail.jsonc` says otherwise. `dt --help` and `dt <command> --help` show the options with examples.
 
-`check` prints diagnostics as `file:line:col - error M00X: message` and exits non-zero on errors.
+`check` prints diagnostics as `file:line:col - error M00X: message` (with a `hint:` line on what to change, when there is
+one) and exits non-zero on errors; `check --format json` prints them as one JSON document (`schema/diagnostics.schema.json`).
 `generate ts` runs `check` first and generates nothing if there are errors.
 
-Try it with the example in this repository (see [Development](#development)):
+Try it with the example in this repository (see [Development](#development)). [examples/shop](examples/shop/README.md)
+is a complete one: the model, the generated code, and the code an AI agent writes against it — the domain
+implementations and a small application layer.
 
 ```bash
 bun run dt -r examples/shop check
-bun run dt -r examples/shop generate ts   # then examples/shop/src/order-commands.ts type-checks against it
+bun run dt -r examples/shop generate ts      # then examples/shop/src type-checks against it
+(cd examples/shop && bun test)               # passes the generated contract tests and the application's tests
+(cd examples/shop && bun src/demo.ts)        # a walk through the shop: orders, an invoice, a refund request
 bun run build && bun run dt -r examples/shop view
 ```
 
 ## Guide
 
-**[docs/guide.md](docs/guide.md)** is the reference for writing models and using the CLI, and `dt guide` prints the
-same text, so people and AI agents get it without leaving the terminal:
+**[docs/guide.md](docs/guide.md)** is the reference for writing models and using the CLI. It starts with a
+[quick reference](docs/guide.md#quick-reference) (the workflow, the DSL at a glance, the commands), and its sections are
+**topics** that the CLI prints one at a time, so people and AI agents read only what they need without leaving the
+terminal:
 
-- [Workflow](docs/guide.md#workflow): `check` → `generate ts` → type-check your own code (`tsc --noEmit`)
-- [Output and exit codes](docs/guide.md#output-and-exit-codes)
-- [Configuration](docs/guide.md#configuration): `domaintrail.jsonc` (`sources`, `generate.ts.out` /
-  `generate.ts.contexts`, `view.port` / `view.host`; JSON Schema in `schema/domaintrail.schema.json`)
+```bash
+dt guide                       # the quick reference and the list of topics (about one screen)
+dt guide requires              # one topic: a ## section with its ### sections, or one ### section
+dt guide M010                  # one rule and the topics that explain it
+dt guide --all                 # the whole guide, the same text as docs/guide.md
+```
+
+The sections, in the guide's order:
+
+- [Workflow](docs/guide.md#workflow): `fmt` → `check` → `generate ts` → implement with `decide` → type-check your own
+  code (`tsc --noEmit`) → run the generated contract tests
 - [File layout (recommended)](docs/guide.md#file-layout-recommended): `<context>/<aggregate>.dt` and
   `<context>/context.dt` (see [ADR 0009](docs/adr/0009-file-layout.md))
 - [DSL](docs/guide.md#dsl): contexts, aggregates, entities, values, states, commands, events, errors,
   [domain primitives](docs/guide.md#domain-primitives), [unions](docs/guide.md#unions),
   [shared contexts](docs/guide.md#shared-contexts), [field sets](docs/guide.md#field-sets),
   [domain and technical fields](docs/guide.md#domain-fields-and-technical-fields),
-  [names (表示名)](docs/guide.md#names-labels-and-descriptions)
-  and [invariant expressions](docs/guide.md#invariant-expressions)
-- [Rules](docs/guide.md#rules) (M001–M017, L001–L003) and [Generated TypeScript](docs/guide.md#generated-typescript):
+  [names (表示名)](docs/guide.md#names-labels-and-descriptions),
+  [invariant expressions](docs/guide.md#invariant-expressions), [command requirements](docs/guide.md#command-requirements),
+  [command changes](docs/guide.md#command-changes), [command events](docs/guide.md#command-events),
+  [pure commands](docs/guide.md#pure-commands), [verified types](docs/guide.md#verified-types) (the evidence of a
+  check outside the aggregate, as a command's parameter) and [reactions to events](docs/guide.md#reactions-to-events-policies)
+  (policies: when an event happens, a command eventually runs; see [ADR 0022](docs/adr/0022-policy-declarations.md))
+- [Generated TypeScript](docs/guide.md#generated-typescript): [decisions and `decide`](docs/guide.md#decisions-and-decide),
   [what is generated and what you write](docs/guide.md#generated-code-and-your-code) (see
-  [ADR 0011](docs/adr/0011-generated-code-boundary.md)), [output directories](docs/guide.md#output-directories) and
+  [ADR 0011](docs/adr/0011-generated-code-boundary.md)), [generated checks](docs/guide.md#generated-checks) and
+  [generated tests](docs/guide.md#generated-tests) (see [ADR 0020](docs/adr/0020-generated-checks-and-contract-tests.md)),
   [technical metadata](docs/guide.md#technical-metadata) (see [ADR 0013](docs/adr/0013-field-sets-and-technical-metadata.md))
+  and [output directories](docs/guide.md#output-directories)
+- [Rules](docs/guide.md#rules): M001–M024, L001–L003
+- [Looking up one element](docs/guide.md#looking-up-one-element): `dt show`, as text or JSON
+- [Formatting](docs/guide.md#formatting): `dt fmt`, the one canonical layout of `.dt` files
+- [Output and exit codes](docs/guide.md#output-and-exit-codes): text, or JSON with `--format json`
+- [Configuration](docs/guide.md#configuration): `domaintrail.jsonc` (`sources`, `generate.ts.out` /
+  `generate.ts.contexts` / `generate.ts.tests`, `view.port` / `view.host`; JSON Schema in `schema/domaintrail.schema.json`)
+- [Language server](docs/guide.md#language-server): `dt lsp`, and how to use it from an editor or Claude Code
+- [Editors](docs/guide.md#editors): the Zed extension in `editors/zed` (tree-sitter highlighting, outline, `dt lsp`),
+  other editors through `dt lsp` and the tree-sitter grammar in `tree-sitter-domaintrail`
 
 A taste of the DSL:
 
@@ -70,18 +103,32 @@ context Sales "販売" {
   aggregate Order "注文" {
     id: OrderId
     state Draft
-    state Confirmed { confirmedAt: Timestamp }
-    create command place() -> Draft
-    command confirm(at: Timestamp) Draft -> Confirmed emits OrderConfirmed
+    state Confirmed {
+      confirmedAt: Timestamp
+    }
+    create command place(id: OrderId) -> Draft
+    command confirm(at: Timestamp)
+      Draft -> Confirmed
+      emits OrderConfirmed
+  }
+  persistent event OrderConfirmed {
+    orderId: OrderId
+    confirmedAt: Timestamp
   }
-  persistent event OrderConfirmed { orderId: OrderId confirmedAt: Timestamp }
 }
 ```
 
 The design decisions behind the DSL are in [docs/adr](docs/adr): shared contexts ([0004](docs/adr/0004-shared-contexts.md)),
 unions ([0005](docs/adr/0005-unions.md)), persistent events ([0008](docs/adr/0008-persistent-events.md)),
 command transitions ([0014](docs/adr/0014-command-transitions.md)), handlers per state
-([0015](docs/adr/0015-handlers-per-state.md)) and more.
+([0015](docs/adr/0015-handlers-per-state.md), superseded), collection constraints and declared invariants
+([0016](docs/adr/0016-collection-constraints-and-declared-invariants.md)), command requirements
+([0017](docs/adr/0017-command-requirements.md)), command events as an exact contract
+([0018](docs/adr/0018-command-events-contract.md)), the fields a command changes and decisions
+([0019](docs/adr/0019-command-changes-and-decisions.md)), generated checks and contract tests
+([0020](docs/adr/0020-generated-checks-and-contract-tests.md)), event and error fields named after their source
+([0021](docs/adr/0021-payload-field-names.md)), policy declarations ([0022](docs/adr/0022-policy-declarations.md)),
+verified types ([0023](docs/adr/0023-verified-types.md)) and more.
 
 ## Live View
 
@@ -137,7 +184,9 @@ Requires [Bun](https://bun.sh) (version pinned in `mise.toml`). `bun run dt` run
 bun install
 bun run langium:generate   # after editing src/language/domain.langium
 bun run typecheck
-bun test
+bun run lint               # oxlint --type-aware, no narrowing casts without a reason (after `bun run dt -r examples/shop generate ts`)
+bun run fmt                # oxfmt (`fmt:check` in CI); the .dt files are formatted by `dt fmt`
+bun test                   # the repository's tests (bunfig.toml: test/ only)
 bun run build              # dist/: the CLI bundled for Node and the Live View page (needed by `view` and the tests)
 ```
 
@@ -152,7 +201,7 @@ See [docs/releasing.md](docs/releasing.md).
 | `src/language` | Langium grammar, generated parser/AST, scoping |
 | `src/core` | analyzer, diagnostics, validation rules (`checker/`) |
 | `src/model` | Typed Model (serializable, resolved) |
-| `src/generator` | TypeScript generator and naming |
+| `src/generator` | TypeScript generator and naming, generated checks (`checks.ts`) and contract tests (`tests.ts`, `testing/`) |
 | `src/graph`, `src/layout` | Graph IR, diff, ELK layout |
 | `src/server`, `web` | Live View server and React + tldraw client |