domaintrail 0.4.0 → 0.5.0

package/README.md

@@ -30,19 +30,22 @@ dt -r <root> show <name>        # one element resolved: field sets, labels, comm
 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` (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
-(cd examples/shop && bun test)            # and passes the generated contract tests
+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
 ```
 
@@ -72,21 +75,25 @@ The sections, in the guide's order:
   [domain and technical fields](docs/guide.md#domain-fields-and-technical-fields),
   [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) and
-  [pure commands](docs/guide.md#pure-commands)
+  [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)), [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–M021, L001–L003
+- [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:
 
@@ -119,7 +126,9 @@ command transitions ([0014](docs/adr/0014-command-transitions.md)), handlers per
 ([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)) and more.
+([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
 
@@ -175,6 +184,8 @@ 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 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)
 ```