Skip to content

feat: validate map-to-tileset references #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jasoncavinder merged 5 commits into from
Aug 10, 2026
Merged

feat: validate map-to-tileset references #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2762523
feat: add experimental tileset catalog
jasoncavinder Aug 9, 2026
6e064f2
docs: accept ADR 0012
jasoncavinder Aug 9, 2026
2952d0d
feat: validate map tileset references
jasoncavinder Aug 9, 2026
1bd08d8
docs: accept ADRs 0012 and 0013
jasoncavinder Aug 9, 2026
f33822e
Merge dev into map-tileset validation
jasoncavinder Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ not a current support claim.
> order, and parent relationships into a typed catalog. It can also summarize
> one catalog-selected map's basic metadata and opaque event count, selected
> project-level system settings, tileset IDs and editor-facing names, and
> map-scoped event IDs, names, coordinates, and opaque page counts. Its first
> contextual validator checks only the stored player start. It does not yet
> provide broader semantic understanding, project validity, or modification.
> Do not rely on it for valuable workflows.
> map-scoped event IDs, names, coordinates, and opaque page counts. Its bounded
> contextual validators check only the stored player start and map-to-tileset
> references. It does not yet provide broader semantic understanding, project
> validity, or modification. Do not rely on it for valuable workflows.

## What Tilewright aims to provide

Expand Down Expand Up @@ -58,8 +58,8 @@ for the distinction between planned and supported behavior.

| Package | Role | Current state |
| --- | --- | --- |
| [`tilewright`](crates/tilewright/README.md) | Format-aware domain library and primary public API | Experimental discovery, inventory, strict lossless JSON syntax, raw snapshot loading, typed map, tileset, and event catalogs, selected-map and system summaries, and player-start validation |
| [`tilewright-cli`](crates/tilewright-cli/README.md) | Human- and script-facing adapter; installs the `tilewright` executable | Experimental discovery, inventory, raw snapshot, typed map/tileset/event projections, player-start validation, and JSON inspection adapter |
| [`tilewright`](crates/tilewright/README.md) | Format-aware domain library and primary public API | Experimental discovery, inventory, strict lossless JSON syntax, raw snapshot loading, typed map, tileset, and event catalogs, selected-map and system summaries, and bounded player-start and map-to-tileset validation |
| [`tilewright-cli`](crates/tilewright-cli/README.md) | Human- and script-facing adapter; installs the `tilewright` executable | Experimental discovery, inventory, raw snapshot, typed map/tileset/event projections, bounded player-start and map-to-tileset validation, and JSON inspection adapter |
| [`tilewright-mcp`](crates/tilewright-mcp/README.md) | Thin MCP adapter over the library | Scaffold |

The dependency direction is inward:
Expand Down Expand Up @@ -120,6 +120,7 @@ cargo run -p tilewright-cli -- map path/to/project 1
cargo run -p tilewright-cli -- events path/to/project 1
cargo run -p tilewright-cli -- system path/to/project
cargo run -p tilewright-cli -- validate path/to/project
cargo run -p tilewright-cli -- validate-tilesets path/to/project
cargo run -p tilewright-cli -- inspect-json path/to/file.json
```

Expand All @@ -139,6 +140,7 @@ tilewright map path/to/project 1
tilewright events path/to/project 1
tilewright system path/to/project
tilewright validate path/to/project
tilewright validate-tilesets path/to/project
tilewright inspect-json path/to/file.json
```

Expand All @@ -148,12 +150,13 @@ for update and uninstall details.

The CLI currently exposes experimental candidate discovery, project inventory,
bounded raw snapshot loading, typed map-catalog inspection, selected-map
summaries, tileset identity/name catalogs, selected system-setting summaries,
summaries, tileset identity/name catalogs, selected-map event catalogs,
selected system-setting summaries, bounded player-start validation, and strict
lossless JSON syntax inspection. The tileset command leaves modes, images,
flags, and notes opaque; the event command leaves page bodies and commands
opaque. The validation
command covers only the stored player start; it does not establish general
selected system-setting summaries, bounded player-start and map-to-tileset
validation, and strict lossless JSON syntax inspection. The tileset command
leaves modes, images, flags, and notes opaque; the event command leaves page
bodies and commands opaque. The validation commands cover only the stored
player start and map-to-tileset references; they do not establish general
project validity or editor compatibility. No command establishes MZ-version
compatibility, round-trip behavior, or write support. Contributors should use
the full verification process described in
Expand Down
34 changes: 27 additions & 7 deletions crates/tilewright-cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,13 @@

This crate is experimental. It provides help and version output plus read-only
`discover`, `inventory`, `snapshot`, `maps`, `tilesets`, `map`, `events`,
`system`, `validate`, and `inspect-json` commands over the core library's
`system`, `validate`, `validate-tilesets`, and `inspect-json` commands over the
core library's
experimental RPG Maker MZ candidate-discovery, capability-relative project
inventory, raw snapshot loader, typed map, tileset, and selected-map event
catalogs, selected-map and system summaries, player-start validation, and
strict lossless JSON syntax APIs. It does not provide general project
understanding, project validity, editor compatibility, or modification.
catalogs, selected-map and system summaries, player-start and map-to-tileset
validation, and strict lossless JSON syntax APIs. It does not provide general
project understanding, project validity, editor compatibility, or modification.

## Install from a checkout

Expand Down Expand Up @@ -85,6 +86,10 @@ cargo run -p tilewright-cli -- system path/to/project --format json
cargo run -p tilewright-cli -- validate path/to/project
cargo run -p tilewright-cli -- validate path/to/project --format json

# Validate every cataloged map's tileset reference.
cargo run -p tilewright-cli -- validate-tilesets path/to/project
cargo run -p tilewright-cli -- validate-tilesets path/to/project --format json

# Inspect a file for strict lossless JSON syntax.
cargo run -p tilewright-cli -- inspect-json path/to/file.json
cargo run -p tilewright-cli -- inspect-json path/to/file.json --format json
Expand Down Expand Up @@ -195,15 +200,30 @@ passability, event placement, or runtime success. The command does not emit raw
documents or unprojected fields, and the snapshot resource-limit options are
available on `validate`.

The `validate-tilesets` command loads the same bounded snapshot and delegates a
project-wide map-to-tileset reference check to the core library. It reports a
finding when a cataloged map's positive tileset ID has no matching tileset
record. Findings are completed validation results and exit with code 0.
Acquisition, loading, and structural map-catalog, tileset-catalog, or selected
map failures exit with code 1.

A finding-free result means only that this relationship check found no missing
catalog record. It does not establish project validity, editor acceptance,
asset existence, tile behavior, runtime success, compatibility, mutation
safety, or write support. The command does not emit raw documents or
unprojected fields, and the snapshot resource-limit options are available on
`validate-tilesets`.

JSON paths include an exact `utf8` value when one exists and a lossy `display`
value for presentation. Callers must not treat `display` as an exact encoding of
a non-UTF-8 path.

Note: While descendant symlink entries are reported without traversal, the
initial `open_ambient_dir` acquisition used by `inventory`, `snapshot`, `maps`,
`tilesets`, `map`, `events`, `system`, and `validate` may resolve root or
ancestor symlinks and does not prove root identity. The `inspect-json` command
explicitly opens the provided path and makes no project-containment claim.
`tilesets`, `map`, `events`, `system`, `validate`, and `validate-tilesets` may
resolve root or ancestor symlinks and does not prove root identity. The
`inspect-json` command explicitly opens the provided path and makes no
project-containment claim.

## Responsibilities

Expand Down
Loading