Skip to main content

koyu check

Checks that what is written holds together as data. It is the gate to pass after every edit, and it is what you put in CI.

Arguments​

koyu check <entry.muro> [--json] [--strict]

Takes one entry path. For a building split with import, pass the base layer's file.

Flags​

FlagEffect
--jsonWrites the diagnostics to stdout as Diagnostic[] JSON. This is the only time the codes appear
--strictMakes the exit code 1 even when there are only warnings

They combine. --json --strict writes the JSON and still returns 1 for warnings alone.

Output​

With no errors you get the green line, plus a line saying what that green means.

npx tsx src/cli.ts check examples/two-rooms.muro
✔ Consistent — 3 spaces / 3 boundaries
  Structural consistency only — architectural validity is what koyu validate says, separately

The boundaries counted are the boundaries after derivation. The default between touching spaces is a wall, so boundaries appear even when you wrote no boundary line at all. For the count on the written side, use koyu json.

Warnings keep the green line and add a count; each warning comes out first, marked ⚠.

npx tsx src/cli.ts check warn.muro
⚠ <absolute path>/warn.muro:line 6: Level L1 has no slab:, so not one floor is generated on this storey
✔ Consistent — 3 spaces / 2 boundaries (1 warning)
  Structural consistency only — architectural validity is what koyu validate says, separately

With errors only the ✖ lines appear; the green line does not. The position prefixes the body as <resolved absolute path>:line <n>:.

npx tsx src/cli.ts check bad.muro
✖ <absolute path>/bad.muro:line 6: The spaces do not touch, so no boundary can be derived: /L1/a | /L1/b

Codes never appear in the human output. To look one up, add --json.

The shape of --json​

With no diagnostics it is an empty array.

npx tsx src/cli.ts check examples/two-rooms.muro --json
[]

Otherwise it is one object per diagnostic. message carries the body only; the position is carried separately by line and file, and file is the resolved absolute path.

npx tsx src/cli.ts check bad.muro --json
[
 {
  "code": "BND04",
  "severity": "error",
  "message": "The spaces do not touch, so no boundary can be derived: /L1/a | /L1/b",
  "line": 6,
  "file": "<absolute path>/bad.muro",
  "path": [
   "/L1/a",
   "/L1/b"
  ]
 }
]

code, severity and message are always present; line, file, path and related appear only when the diagnostic has them.

severity is a property of the code. The same code is never an error one time and a warning another. There are 65 codes in all.

A file that never composed into a model — a syntax or composition error — still returns valid JSON under --json. It is copied into a single SYN01.

npx tsx src/cli.ts check broken.muro --json
[
 {
  "code": "SYN01",
  "severity": "error",
  "message": "Undefined grid line name: Y1",
  "line": 2,
  "file": "<absolute path>/broken.muro"
 }
]

An unreadable file takes the same path. There is no position, so neither line nor file appears.

[
 {
  "code": "SYN01",
  "severity": "error",
  "message": "Cannot read file: <absolute path>/nope.muro"
 }
]

Without --json the same file produces a single ✖ line instead of JSON. Either way the exit code is 1.

Exit codes​

Exit codeMeaning
0No errors (and, under --strict, no warnings either)
1There are errors / there are warnings under --strict / it could not be read because of a syntax or composition error
2No file path was given (usage is printed)

--json does not change the exit code. It writes the diagnostics as JSON and still returns 0 or 1 on the same test.

What check does not say​

What check guarantees stops at "what is written holds together as data". It says nothing whatsoever about whether the building is usable.

The default between touching spaces is a wall, and a wall is impassable without a door. So a building with no doors at all comes out green while perfectly sealed. The same goes for windows: none at all is still green.

koyu 1.0
name 密封
unit mm
grid X 0 3600 7200
grid Y 0 4500
level L1 0 h:2400 slab:150
space /L1/a room X1..X2 Y1..Y2 name:居室A daylight:1
space /L1/b room X2..X3 Y1..Y2 name:居室B
space /out exterior name:外部
npx tsx src/cli.ts check sealed.muro
✔ Consistent — 3 spaces / 1 boundary
  Structural consistency only — architectural validity is what koyu validate says, separately

Hand the same file to koyu validate and three violations come out. Never claim it works on the strength of the green.

See also​