Model Builder

Name#

litespec model checks the project model, formats record files, renders generated outputs, and answers record queries.

Synopsis#

litespec model check [--root <consumer>] [--format json] [--release] [--since <ref>] [--all]
litespec model format [--root <consumer>] [--check]
litespec model render [--root <consumer>]
litespec model query [--root <consumer>] <id>

Description#

The model builder reads the written records, the code marks, the routes, the tests, and the latest test run into one model. The model holds every record, each with its identifier and its qualified identifier, and its resolved links. It names the code, screens, tests, and test runs it read. It adds the computed implements, calls, and proves links and the computed implemented, verified, stale, and reachable state of each record. Computed states are never written on a record; the book shows them. The model also lists each unmarked Domain constituent type under the aggregate whose folder holds it, or under kernel, in constituents.

Each screen lists its operations, its useCases, and its calls, where each call pairs one operation with the use case it reaches. The calls links carry one link per such pair, so a use case reached through two operations gets two links, and a use case whose operation is unknown carries an empty operation.

A proof goes stale when its scenario changes after the proof passed. .litespec/proof/proofs.json is committed: for each scenario it holds the scenario hash and its test body's hash at the last passing run. On every later build, a scenario whose hash or test body differs from the recorded one has a stale proof, and a stale proof verifies nothing until a newer passing run is read. A test that both passed and failed within the runs read reports proof-invalid. Run the model check after the test run, in the same job, so the hash is recorded before a record changes.

The .NET stack reader links each code element to its record through its mark, in the style marks declares: a handler, an event handler, a job host, a port, an adapter, an endpoint, an aggregate root and its state-changing methods, a domain event, a refusal type, and a test. A folder or a type name is never the link. A marked refusal type declares the code of the refusal result its rule names.

The four subcommands share one reader:

• check builds the model in memory and reports every finding with its level, code, message, path, and line. It runs only the findings of the conformance level the project claims in conformance, in both the model checks and the consumer pass, as the finding table below states per code. It runs the consumer pass over the project file, the record pages, the glossary, and the controlled UI, and reports those findings in the same shape, so one command and one CI step hold the whole consumer. In text it lists every open blocking finding in full, then one line per finding code with its level and count ordered by level (G, then S, then A) and then by count, such as record-invalid G 3, and the totals line. By default the level A findings are summarized in those counts and not listed one by one; --all lists them. With --format json it writes every finding with its severity beside its level: error for G, warning for S and note for A. With --release the release-readiness findings block: use-case-unverified. With --since <ref> only the findings about records and code changed since <ref> block, and the rest report; it also reports every client-breaking contract change since <ref>: a removed result, a removed refusal code, and a changed integration event: each as a contract-break finding of level S, which always blocks at the level that runs it.
• format rewrites every record file under the record roots, and the glossary file, into canonical form. With --check it writes nothing and lists each file that would change.
• render rewrites the fenced generated regions in explanation files and documents, touching no text outside the fences, and writes litespec-records.ts into each React and Svelte frontend frame.
• query prints one record with its links in both directions, showing both its identifier and its qualified identifier. Agents use it to load a record's context.

A finding that an exception covers is reported as known and exits zero, as the model page states under The Model Builder. An exception on a use case also covers the findings about the scenarios and results it holds. An expired exception fails the check.

Every check has a level. G reads records only and always blocks. S reads code through a stack reader: it blocks where the reader that produced the finding is qualified, and reports otherwise. A stack reader is the reader a stack selects to read its code, screens or tests. Qualification is per reader: a reader is qualified when it ran and its handshake matched; the golden corpus is a test contract for the reader bundle and does not gate a consumer run. The .NET (Roslyn) reader, including Blazor and Android screens, stays qualified. A finding no reader produced, a record finding, is qualified. A is advisory: it reports and never blocks. A structural parent is any link or containment the Parents table and the Identifiers table on the model page name as a record's parent; a missing structural parent is level G. Every other required link is level G.

Every finding code also has a conformance level: the lowest claimed level that runs it, from what its check reads. A check that reads records alone runs at records. A check that reads code, screens, tests, test runs or measure results through a stack reader runs at traced. A check that reads LiteSpec's code layout, operations files, the bill of materials or the controlled UI runs at full. At records no stack reader runs. At traced the readers run and the layout group does not: the layout group is code-placement-drift and mark-folder-drift, the findings about LiteSpec's own code layout, each running only at full. A code with no row runs at full. The finding codes are:

The render subcommand writes these generated regions, each fenced by <!-- generated:<name> --> and <!-- /generated:<name> -->: alert-inventory, runbook-index, and operations-log. It also writes litespec-records.ts into every React and Svelte frontend frame: the use-case and screen ids of that frontend's own entry points with the proves helper browser tests annotate with.

Arguments#

Options#

Exit Codes#

Examples#

Check the model and read the findings from another program:

litespec model check --root ../consumer --format json

Render the generated outputs after a record change:

litespec model render --root ../consumer

Rewrite every record file into canonical form:

litespec model format --root ../consumer

List the files that would change, without writing:

litespec model format --root ../consumer --check

Print one record with its links:

litespec model query --root ../consumer use-case/orders.cancel-order

Print one record by its qualified identifier:

litespec model query --root ../consumer finance/problem/organizers-wait-for-ticket-money

Check for release, with the release-readiness findings blocking:

litespec model check --root ../consumer --release

Block only on the findings changed since the main branch, and report every breaking contract change since it:

litespec model check --root ../consumer --since main

Underneath#

A web frontend is read by a TypeScript reader that ships with the tool as one bundled script: the tool runs it with Node once per command run that builds the model, sends one versioned JSON request on standard input, and reads one versioned JSON facts document back, so a consumer installs nothing beyond Node itself. The reader opens with a handshake naming the protocol version, the reader, and the TypeScript and Svelte versions; a version mismatch, an absent Node, or a reader failure produces the single reader-missing finding for that frontend instead of passing silently. A finding records the reader that produced its facts, and its level takes that reader's qualification: a reader qualifies when its handshake matches; the golden corpus is a test contract for the reader bundle and does not gate a consumer run. The .NET (Roslyn) reader, which reads Blazor and Android frontends, stays qualified. A finding no reader produced, a record finding, is qualified.

The builder reads paths, shape, and stacks from the consumer's .litespec/project.json. It reads shared provisions from the release the tool carries and the test run from TRX or JUnit XML files under paths.testResults. A JUnit testcase proves a Behavior scenario directly by carrying the scenario id in a litespec.proves property, one property per scenario or several ids separated by commas in one value: <properties><property name="litespec.proves" value="scenario/borrow-copy.borrowing-an-available-copy-succeeds" /></properties>. The case proves each id it names with the same rules as a proves mark on a test method, so a runner whose steps carry no mark, or a stack with no code reader, still proves its scenarios. A check --since base is read through an archive into a temporary folder, which is removed after the check. Nothing beneath it is separately runnable.