Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Hare
|
3c3edf4c6f | ||
|
Hare
|
1cbe03b49e | ||
|
Hare
|
26cba3398f |
@@ -4,6 +4,19 @@ All notable changes to the published WIP Rust crates are documented here.
|
||||
|
||||
## Unreleased
|
||||
|
||||
## 0.2.0
|
||||
|
||||
- Adds public Text View `Token`/`TokenKind`, `tokenize_object`,
|
||||
`tokenize_interface`, and delimiter-free `to_plain_text`. Direct rendering uses
|
||||
the same token generation path; HTML and terminal-color renderers are not included.
|
||||
- Makes Client Interface caches scope-lifetime-aware, invalidates observations on
|
||||
confirmed binding loss, and retains immutable contexts for in-flight calls.
|
||||
|
||||
- Adds `wip-text-view`, an independent single-entity Object/Interface signature
|
||||
library with Protocol validation, typed errors, full ordered declarations,
|
||||
documentation summaries and safe Text View quoting/escapes. No path, lookup,
|
||||
cache, UI, network or Protocol wire-schema changes are required.
|
||||
|
||||
- Breaking Protocol/HTTP migration from opaque Interface reference strings to
|
||||
exact `(scope, name)` records in Objects, fetches and calls, with optional
|
||||
opaque `scope_ref` metadata. Adds shape and placement-aware scope validation
|
||||
|
||||
Generated
+16
-9
@@ -1235,7 +1235,7 @@ checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
|
||||
|
||||
[[package]]
|
||||
name = "wip-client"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"wip-http",
|
||||
"wip-protocol",
|
||||
@@ -1243,7 +1243,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wip-fs-server"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"http",
|
||||
"rustix 1.1.5",
|
||||
@@ -1256,7 +1256,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wip-host"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"trybuild",
|
||||
"wip-interface",
|
||||
@@ -1265,7 +1265,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wip-http"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"base64 0.22.1",
|
||||
"http",
|
||||
@@ -1277,7 +1277,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wip-interface"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"trybuild",
|
||||
"wip-interface-macros",
|
||||
@@ -1286,7 +1286,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wip-interface-macros"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
@@ -1295,11 +1295,11 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "wip-protocol"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
|
||||
[[package]]
|
||||
name = "wip-public-api-example"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"wip-client",
|
||||
"wip-host",
|
||||
@@ -1308,9 +1308,16 @@ dependencies = [
|
||||
"wip-protocol",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wip-text-view"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"wip-protocol",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wip-tui"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
dependencies = [
|
||||
"base64 0.22.1",
|
||||
"crossterm",
|
||||
|
||||
+9
-8
@@ -3,17 +3,18 @@ members = ["crates/*"]
|
||||
resolver = "3"
|
||||
|
||||
[workspace.package]
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
edition = "2024"
|
||||
rust-version = "1.88"
|
||||
license = "MIT OR Apache-2.0"
|
||||
repository = "https://gitea.hareworks.net/Hare/wip-rs"
|
||||
|
||||
[workspace.dependencies]
|
||||
wip-client = { version = "0.1.0", path = "crates/wip-client" }
|
||||
wip-fs-server = { version = "0.1.0", path = "crates/wip-fs-server" }
|
||||
wip-host = { version = "0.1.0", path = "crates/wip-host" }
|
||||
wip-http = { version = "0.1.0", path = "crates/wip-http" }
|
||||
wip-interface = { version = "0.1.0", path = "crates/wip-interface" }
|
||||
wip-interface-macros = { version = "0.1.0", path = "crates/wip-interface-macros" }
|
||||
wip-protocol = { version = "0.1.0", path = "crates/wip-protocol" }
|
||||
wip-client = { version = "0.2.0", path = "crates/wip-client" }
|
||||
wip-fs-server = { version = "0.2.0", path = "crates/wip-fs-server" }
|
||||
wip-host = { version = "0.2.0", path = "crates/wip-host" }
|
||||
wip-http = { version = "0.2.0", path = "crates/wip-http" }
|
||||
wip-interface = { version = "0.2.0", path = "crates/wip-interface" }
|
||||
wip-interface-macros = { version = "0.2.0", path = "crates/wip-interface-macros" }
|
||||
wip-protocol = { version = "0.2.0", path = "crates/wip-protocol" }
|
||||
wip-text-view = { version = "0.2.0", path = "crates/wip-text-view" }
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# Structured Interface reference and scope publication migration
|
||||
|
||||
This unreleased API/wire change follows `wip-reference` canonical Core Model,
|
||||
The 0.2.0 API/wire change follows `wip-reference` canonical Core Model,
|
||||
Protocol and WIP over HTTP at `6086f3c5ef10aa1464ce9c824750d7f667217bfd`.
|
||||
It replaces the earlier opaque Interface reference contract; HTTP routes and
|
||||
error codes have **not** changed. Peers must upgrade together: the codec does
|
||||
|
||||
@@ -7,7 +7,8 @@ under `crates/*`. It provides a transport-independent protocol model, the
|
||||
standard framework-independent WIP over HTTP v1 binding, a stateful
|
||||
presentation-independent client runtime, a Rust interface-authoring facade, a
|
||||
request-scoped host runtime, a bounded Linux filesystem projection server, an
|
||||
interactive terminal client, and a private public-API conformance consumer. The
|
||||
interactive terminal client, a standalone Text View signature library, and a
|
||||
private public-API conformance consumer. The
|
||||
repository root is not itself a package.
|
||||
|
||||
## Crate graph and responsibilities
|
||||
@@ -15,6 +16,9 @@ repository root is not itself a package.
|
||||
```text
|
||||
Published libraries
|
||||
|
||||
wip-text-view
|
||||
└── wip-protocol
|
||||
|
||||
wip-client
|
||||
├── wip-http
|
||||
│ └── wip-protocol
|
||||
@@ -47,19 +51,20 @@ wip-public-api-example
|
||||
|
||||
| Crate | Responsibility | Does not own |
|
||||
| --- | --- | --- |
|
||||
| `wip-text-view` | Standalone, validated single-Object and single-Interface Text View signatures with full declarations, summaries and safe escapes. | Retrieval, cache, placement context, wire schema, UI layout, parsing or call-target reconstruction. |
|
||||
| `wip-protocol` | Transport-independent descriptors, object/call/result types, logical `Value`s, validation, and stable protocol error categories. | Application DTOs, implementations, persistence, or wire encoding. |
|
||||
| `wip-http` | Standard WIP over HTTP v1 endpoint/route derivation, UTF-8 JSON codecs, direct success bodies, and error/status classification. | HTTP I/O, URL scheme or TLS policy, authentication schemes, server frameworks, filesystem projection, or client presentation/cache policy. |
|
||||
| `wip-client` | Endpoint/security-context-isolated Known Space, normalized object and interface observations, intent-driven object and descriptor coverage with bounded request deduplication, immutable operation call contexts, stale transitions, and bounded histories. | HTTP I/O, credentials, persistent cache, automatic operation retries, or presentation widgets/events. |
|
||||
| `wip-tui` | Keyboard-only interactive Worldspace tree, selected Entry and qualified operation panes, descriptor-driven argument editing, bounded result/diagnostic rendering, terminal lifecycle, and HTTP I/O workers over `wip-client`. | Independent cache/validator semantics, automatic operation retries, Host internals, backend paths, or persistent state. |
|
||||
| `wip-interface` | The public `WipType`/`interface` authoring API, Rust-to-protocol codecs, generated descriptors, and typed implementation dispatch. | Object publication, backend lifetime, or transport policy. |
|
||||
| `wip-interface-macros` | Procedural-macro expansion used by `wip-interface`. It is not an application dependency. | A supported direct user API. |
|
||||
| `wip-host` | Opaque interface registration, explicit object membership, validator checks, interface-qualified dispatch against one host-owned instance, and descriptor-guided argument decoding inside that same resolution boundary. | Backend atomicity, global object lookup, or network serving. |
|
||||
| `wip-host` | Scoped interface registration and publication lifetimes, explicit object membership, validator checks, interface-qualified dispatch against one host-owned instance, and descriptor-guided argument decoding inside that same resolution boundary. | Backend atomicity, global object lookup, or network serving. |
|
||||
| `wip-fs-server` | Linux directory-handle-confined request-time projection, complete depth-bounded observations and bounded file operations, standard `wip-http` dispatch, and a loopback HTTP binary. | A new wire profile, implicit symlink following, non-loopback cleartext, authentication policy, TLS termination, or filesystem-wide preregistration. |
|
||||
| `wip-public-api-example` | An independently compiled consumer of the protocol, authoring, and host public crates. Its DTOs and traits are application-owned; its implementation and backend handle remain host-private. | Reusable library API or a production server. |
|
||||
|
||||
## Published crates
|
||||
|
||||
The `0.1.0` release consists of these six crates:
|
||||
The `0.2.0` release consists of these seven crates:
|
||||
|
||||
- `wip-protocol`
|
||||
- `wip-interface-macros` — implementation dependency re-exported by `wip-interface`
|
||||
@@ -67,6 +72,13 @@ The `0.1.0` release consists of these six crates:
|
||||
- `wip-host`
|
||||
- `wip-http`
|
||||
- `wip-client`
|
||||
- `wip-text-view`
|
||||
|
||||
The [`wip-text-view`](crates/wip-text-view/README.md) library's
|
||||
`render_object(&Object)` API needs no path;
|
||||
`render_interface(&Interface)` takes one borrowed entity pairing the complete
|
||||
structured reference with its descriptor, without changing Protocol wire fields.
|
||||
Both return one complete plain-text signature or a typed error.
|
||||
|
||||
The filesystem server, terminal client, and public-API example are workspace-only packages and set `publish = false`. All workspace packages require Rust 1.88 or newer and are licensed under either Apache-2.0 or MIT at your option.
|
||||
|
||||
@@ -81,7 +93,7 @@ or application traits.
|
||||
|
||||
## Structured Interface references
|
||||
|
||||
The unreleased Protocol/HTTP API uses explicit `InterfaceReference { scope,
|
||||
The 0.2.0 Protocol/HTTP API uses explicit `InterfaceReference { scope,
|
||||
name }` records and optional `scope_ref` observation/precondition metadata.
|
||||
Legacy opaque-string wire references are rejected. See [MIGRATION.md](MIGRATION.md)
|
||||
for construction examples, validation boundaries and downstream migration status.
|
||||
|
||||
+8
-5
@@ -1,12 +1,12 @@
|
||||
# Releasing
|
||||
|
||||
The six crates published from this workspace use one version and must be released in dependency order. The filesystem server, terminal client, and public-API example set `publish = false` and are never uploaded.
|
||||
The seven public crates in the current workspace (including `wip-text-view`) use one version and must be released in dependency order. The filesystem server, terminal client, and public-API example set `publish = false` and are never uploaded.
|
||||
|
||||
## Preconditions
|
||||
|
||||
1. Work from a clean `master` whose `HEAD` matches `origin/master`.
|
||||
2. Confirm the intended version in `[workspace.package]` and every internal requirement in `[workspace.dependencies]`.
|
||||
3. Confirm ownership of all six names on crates.io.
|
||||
3. Confirm ownership of all seven names on crates.io.
|
||||
4. Run the complete repository validation suite:
|
||||
|
||||
```console
|
||||
@@ -44,6 +44,9 @@ cargo publish --package wip-interface-macros
|
||||
Wait until both versions are available from the crates.io index, then continue:
|
||||
|
||||
```console
|
||||
cargo publish --dry-run --package wip-text-view
|
||||
cargo publish --package wip-text-view
|
||||
|
||||
cargo publish --dry-run --package wip-interface
|
||||
cargo publish --package wip-interface
|
||||
|
||||
@@ -65,11 +68,11 @@ Registry propagation can take time. A dependent dry-run reporting that a WIP cra
|
||||
|
||||
## Tag
|
||||
|
||||
After all six uploads resolve successfully, tag the exact published commit and push the tag:
|
||||
After all seven uploads resolve successfully, tag the exact published commit and push the tag:
|
||||
|
||||
```console
|
||||
git tag -a v0.1.0 -m "release: 0.1.0"
|
||||
git push origin v0.1.0
|
||||
git tag -a v0.2.0 -m "chore: release 0.2.0"
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
Do not move or recreate a published version or its tag. Prepare a new version for any subsequent correction.
|
||||
|
||||
@@ -6,7 +6,7 @@ Presentation-independent stateful runtime for Web Interface Protocol (WIP) clien
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
wip-client = "0.1.0"
|
||||
wip-client = "0.2.0"
|
||||
```
|
||||
|
||||
Applications provide the HTTP adapter and presentation layer, send each prepared request exactly as owned by the runtime, then return the corresponding response for completion.
|
||||
|
||||
@@ -6,11 +6,11 @@ Framework-independent Host publication and operation dispatch for the Web Interf
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
wip-host = "0.1.0"
|
||||
wip-interface = "0.1.0"
|
||||
wip-host = "0.2.0"
|
||||
wip-interface = "0.2.0"
|
||||
```
|
||||
|
||||
Protocol publication and dispatch use `wip_protocol::InterfaceReference { scope, name }` and compare both fields exactly. The legacy `InterfaceRef` registration token remains Host-private: `protocol_reference()` maps its opaque string verbatim to the name at root scope `/`, without parsing it. Registry lookup and fetch accept structured references; non-root references do not resolve legacy registrations. Legacy responses omit `scope_ref`.
|
||||
Protocol publication and dispatch use `wip_protocol::InterfaceReference { scope, name }` and compare both fields exactly. Registration takes an explicit `Scope` and local name; `InterfaceRef::protocol_reference()` preserves those coordinates without parsing display text. Providers attach a current `ScopeObservation` inside the coherent backend boundary, and fetch returns its optional Object ref as `scope_ref`. Calls check a supplied `scope_ref` against that current binding; omission adds no identity precondition. Retire a Scope on Object deletion, replacement or movement; retained registry artifacts alone do not establish publication.
|
||||
|
||||
Malformed interface-reference shapes fail calls as `InvalidRequest` before object resolution. A well-shaped reference outside the target path's ancestor-or-self scope fails at the membership check as `InterfaceMismatch`.
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ The crate maps the three WIP Core interactions to fixed HTTP routes and strict U
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
wip-http = "0.1.0"
|
||||
wip-http = "0.2.0"
|
||||
```
|
||||
|
||||
```rust
|
||||
|
||||
@@ -6,7 +6,7 @@ The crate re-exports `#[interface]` and `#[derive(WipType)]`, generates Interfac
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
wip-interface = "0.1.0"
|
||||
wip-interface = "0.2.0"
|
||||
```
|
||||
|
||||
```rust
|
||||
|
||||
@@ -6,7 +6,7 @@ This crate defines the canonical Object and Interface Descriptor models, the thr
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
wip-protocol = "0.1.0"
|
||||
wip-protocol = "0.2.0"
|
||||
```
|
||||
|
||||
Interface identity is an exact `InterfaceReference { scope, name }` pair.
|
||||
@@ -16,7 +16,7 @@ and Object/interaction validation at response boundaries. Fetching needs no
|
||||
target Object path. Fetch responses and interface call targets carry optional
|
||||
opaque string `scope_ref` metadata, not a third identity field. Descriptors do
|
||||
not embed identity. See the repository's [migration guide](../../MIGRATION.md)
|
||||
for the breaking Rust and HTTP wire changes and deferred consumer semantics.
|
||||
for the breaking Rust and HTTP wire changes and consumer migration guidance.
|
||||
|
||||
See the [API documentation](https://docs.rs/wip-protocol) for the complete model and validation rules.
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
[package]
|
||||
name = "wip-text-view"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
rust-version.workspace = true
|
||||
description = "Standalone Object and Interface Text View signatures for WIP"
|
||||
license.workspace = true
|
||||
repository.workspace = true
|
||||
readme = "README.md"
|
||||
documentation = "https://docs.rs/wip-text-view"
|
||||
|
||||
[dependencies]
|
||||
wip-protocol.workspace = true
|
||||
@@ -0,0 +1,193 @@
|
||||
# wip-text-view
|
||||
|
||||
Standalone Object and Interface signature rendering for WIP Text View, following
|
||||
`4.2-text-view.md` at reference revision `6086f3c` and the Protocol semantics in
|
||||
`3-protocol.md`. Only `wip-protocol` and the Rust standard library are dependencies.
|
||||
No Client, Host, HTTP I/O, cache, UI framework or retrieval service is required.
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
wip-text-view = "0.2.0"
|
||||
wip-protocol = "0.2.0"
|
||||
```
|
||||
|
||||
## Single-entity API
|
||||
|
||||
```rust
|
||||
use wip_protocol::{Object, InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
|
||||
use wip_text_view::{Interface, render_object, render_interface};
|
||||
|
||||
let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
|
||||
let object = Object {
|
||||
name: "item".into(), description: None, interfaces: vec![reference.clone()],
|
||||
r#ref: None, validator: None,
|
||||
};
|
||||
let object_signature = render_object(&object)?;
|
||||
assert_eq!(object_signature,
|
||||
"object {\n name: \"item\";\n interfaces: [\"/::example\"];\n}\n");
|
||||
|
||||
let descriptor = InterfaceDescriptor {
|
||||
format: INTERFACE_FORMAT_V1.into(), documentation: None,
|
||||
types: vec![], operations: vec![],
|
||||
};
|
||||
let interface = Interface { reference: &reference, descriptor: &descriptor };
|
||||
let interface_signature = render_interface(&interface)?;
|
||||
assert_eq!(interface_signature, "interface \"/::example\" {\n}\n");
|
||||
# Ok::<(), wip_text_view::RenderError>(())
|
||||
```
|
||||
|
||||
`Interface<'a>` is one borrowed SDK input entity containing a complete structured
|
||||
reference and its corresponding descriptor, not a wire schema extension. The
|
||||
caller pairs them from a coherent observation or publication. The descriptor has
|
||||
no identity, so a renderer cannot prove the pairing's provenance or freshness.
|
||||
For example, a caller with a validated `FetchInterfaceResponse` can borrow its
|
||||
`interface` and `descriptor`; it does not pass `scope_ref` or validators.
|
||||
|
||||
An Object has no placement path. This API always emits `object { ... }`, never
|
||||
requests a path and never infers one from name or ref. It requires no descriptor.
|
||||
An Interface needs no Object, separate name/scope/context arguments or lookup.
|
||||
There is no document aggregator, configuration or details selector.
|
||||
|
||||
## Typed display tokens
|
||||
|
||||
```rust
|
||||
use wip_protocol::{Object, InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
|
||||
use wip_text_view::{
|
||||
Interface, TokenKind, tokenize_object, tokenize_interface, to_plain_text,
|
||||
render_object, render_interface,
|
||||
};
|
||||
|
||||
let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
|
||||
let object = Object {
|
||||
name: "item".into(), description: None, interfaces: vec![reference.clone()],
|
||||
r#ref: None, validator: None,
|
||||
};
|
||||
let object_tokens = tokenize_object(&object)?;
|
||||
assert_eq!(object_tokens[0].kind(), TokenKind::Keyword);
|
||||
assert_eq!(object_tokens[0].text(), "object");
|
||||
assert_eq!(to_plain_text(&object_tokens), render_object(&object)?);
|
||||
|
||||
let descriptor = InterfaceDescriptor {
|
||||
format: INTERFACE_FORMAT_V1.into(), documentation: None,
|
||||
types: vec![], operations: vec![],
|
||||
};
|
||||
let input = Interface { reference: &reference, descriptor: &descriptor };
|
||||
let tokens = tokenize_interface(&input)?;
|
||||
for token in &tokens {
|
||||
// Custom renderers can select presentation by role without reparsing text.
|
||||
if token.kind() == TokenKind::Reference {
|
||||
assert_eq!(token.text(), "\"/::example\"");
|
||||
}
|
||||
}
|
||||
let joined: String = tokens.iter().map(|token| token.text()).collect();
|
||||
assert_eq!(to_plain_text(&tokens), joined);
|
||||
assert_eq!(to_plain_text(&tokens), render_interface(&input)?);
|
||||
# Ok::<(), wip_text_view::RenderError>(())
|
||||
```
|
||||
|
||||
`tokenize_object` / `tokenize_interface` return `Result<Vec<Token>, RenderError>`.
|
||||
They generate **directly from the input structure**, not by lexing a completed
|
||||
Text View string. Each token owns its text (and can outlive the input) and exposes
|
||||
`kind()` / `text()`. Existing render APIs use the same token generation followed
|
||||
by `to_plain_text(&[Token])`; there is no second grammar/escape/layout engine.
|
||||
|
||||
### Kind and splitting contract
|
||||
|
||||
| Kind | One token contains |
|
||||
| --- | --- |
|
||||
| `Keyword` | One grammar keyword, Object property label, or primitive type keyword |
|
||||
| `TypeName` | One type declaration name or Named type reference |
|
||||
| `OperationName` | One Operation declaration name |
|
||||
| `ParameterName` / `FieldName` | One parameter / record field name |
|
||||
| `CaseName` | One enum or union case name |
|
||||
| `String` | One complete quoted Object name or description |
|
||||
| `Reference` | One complete quoted absolute Interface reference, with both quoting layers |
|
||||
| `Documentation` | Entire `/// "summary"` content, including marker and internal space, excluding indentation/LF |
|
||||
| `Symbol` | One punctuation mark, except the indivisible two-character `->` arrow |
|
||||
| `Whitespace` | One inter-token ASCII space |
|
||||
| `Newline` | One LF, including the final LF |
|
||||
| `Indentation` | All leading spaces of a non-root line, two spaces per depth level |
|
||||
|
||||
Quoted identifiers retain their semantic role even when named like keywords.
|
||||
Quotes, backticks and all WIP escapes are part of the data token, never separate
|
||||
symbols. Host spaces inside quoted data remain in that token. Adjacent symbols
|
||||
are separate; no empty tokens or zero-depth indentation tokens are emitted.
|
||||
`TokenKind` is non-exhaustive so consumers should handle future roles with a
|
||||
fallback. The API does not distinguish type declaration names from Named uses,
|
||||
or enum cases from union cases; both share the documented role.
|
||||
|
||||
All layout is included. Concatenate token text **without separators**, not with
|
||||
`join(" ")`. `to_plain_text` is only that concatenation: no interpretation,
|
||||
validation, quoting, escaping or layout completion. An empty slice yields `""`;
|
||||
a filtered/reordered slice is allowed but need not be a complete signature.
|
||||
|
||||
Token text is escaped for **WIP Text View**, not for HTML or other destinations.
|
||||
Custom renderers must escape for their destination and treat Host text as data,
|
||||
not markup or instructions. This crate supplies no HTML, ANSI, color or theme
|
||||
renderer/adapter and no external text lexer/parser or AST.
|
||||
|
||||
## Output and validation
|
||||
|
||||
- UTF-8 plain text with LF, two-space indentation and a final LF, without ANSI,
|
||||
Markdown fences, syntax highlighting or provider envelopes. Nonempty composites
|
||||
and parameter lists use multiple lines; layout is deterministic here, but not a
|
||||
byte-canonical protocol format.
|
||||
- All Object references remain in Host order. All types, then all operations,
|
||||
fields, parameters and cases remain in declaration order, without elision.
|
||||
- Missing vs empty description/documentation, optional vs unit, no payload vs
|
||||
unit payload, and empty record/enum/union/declaration sets remain distinct.
|
||||
- Full absolute references use component quoting **and** outer JSON-string quoting.
|
||||
Identifiers use keywords/backtick rules. All Host strings use standard JSON
|
||||
escapes plus DEL/C1, Unicode line/paragraph separator and bidi-control escapes.
|
||||
No normalization, case conversion, URL encoding or input mutation occurs.
|
||||
- Documentation summaries are displayed in their prescribed positions, including
|
||||
return documentation between `)` and `->`. Details are not displayed. Host text
|
||||
is data, not renderer instructions or markup; quoting alone is not a prompt
|
||||
injection defense. AI adapters must preserve the trust boundary.
|
||||
- Object ref/validator, children, domain data and Interface scope_ref/validator
|
||||
are not signature content. No annotations are inferred from operation names.
|
||||
|
||||
The render functions return `Result<String, RenderError>`; token generation
|
||||
returns `Result<Vec<Token>, RenderError>`. Neither returns partial signatures. Resource checks happen first, followed by existing Protocol validators:
|
||||
Object shape and reference uniqueness, or Interface reference shape plus descriptor
|
||||
structure, duplicate names, unknown Named references and cycles. Descriptor format
|
||||
is checked after semantics: valid but unsupported formats return
|
||||
`UnsupportedDescriptorFormat`, distinct from `InvalidDescriptor`. Supported format
|
||||
is exactly `wip-interface/1`. Other validation errors preserve the Protocol's typed
|
||||
`ValidationError` (also exposed as the error source).
|
||||
|
||||
Bounded input limits are **1 MiB** of total string/opaque byte data, **16,384**
|
||||
declarations/fields/parameters/cases/type expressions/references, **256** named type
|
||||
declarations, and **64** TypeExpr nesting levels. Details and Object runtime
|
||||
metadata count toward input bytes even though they are not rendered. A limit
|
||||
returns `RenderError::ResourceLimit`, never truncates or supplies `...`. Counts
|
||||
bound allocation and recursive validation before those validators run; these are
|
||||
library safety limits, not Protocol restrictions.
|
||||
|
||||
Without path/context, this library cannot attest Object scope ancestry, placement,
|
||||
observation consistency, identity, membership, authorization or currentness.
|
||||
Callers validate those at their observation boundary. Callers also own retrieval,
|
||||
resolution, cache, selection, multiple-signature arrangement and AI/UI adaptation.
|
||||
Text is display-only, not serialization, a digest, identity/cache key or call
|
||||
target. No parser or round-trip API is supplied.
|
||||
|
||||
## Validation
|
||||
|
||||
`tests/signatures.rs` is an external consumer of the public APIs. Goldens cover
|
||||
the spec's Object, issue.read, CloseResult, search/return documentation and
|
||||
identifier examples (with permitted multiline layout), plus nested documentation.
|
||||
The suite checks all TypeExpr variants/positions, ordering and empty distinctions,
|
||||
keyword and Unicode names, both reference quoting layers, all required control
|
||||
escapes, input immutability, metadata exclusion and typed rejection cases. Every
|
||||
existing case compares the render result (including exact errors) with token
|
||||
text concatenation and `to_plain_text`. Additional tests assert complete Object
|
||||
token splitting, all semantic roles, keyword collisions, atomic escaped data,
|
||||
all documentation positions, layout tokens and ownership beyond input lifetime.
|
||||
Input budgets bound token counts per node, indentation depth and escape expansion;
|
||||
token generation checks them before any rendering/validation traversal.
|
||||
|
||||
```console
|
||||
cargo test -p wip-text-view
|
||||
cargo clippy -p wip-text-view --all-targets -- -D warnings
|
||||
RUSTDOCFLAGS='-D warnings' cargo doc -p wip-text-view --no-deps
|
||||
```
|
||||
@@ -0,0 +1,221 @@
|
||||
//! Standalone, single-entity WIP Text View signatures.
|
||||
//!
|
||||
//! [`render_object`] accepts just an [`Object`], and [`render_interface`] accepts
|
||||
//! just an [`Interface`] (a reference paired with its corresponding descriptor).
|
||||
//! No Client, Host, HTTP, UI, retrieval, cache, path or display context is needed.
|
||||
//! The caller supplies a coherent observation; descriptor identity cannot be
|
||||
//! inferred from descriptor contents. No protocol wire fields are added.
|
||||
//!
|
||||
//! Output follows WIP `4.2-text-view.md` (reference revision `6086f3c`): UTF-8
|
||||
//! plain text, LF, two-space indentation, all declarations in original order,
|
||||
//! and documentation summaries only. There is no truncation or details setting.
|
||||
//! Object paths are neither requested nor guessed: output uses `object { ... }`.
|
||||
//! Runtime metadata is never rendered. Host documentation is untrusted data,
|
||||
//! not markup or instructions; quoting does not by itself prevent prompt injection.
|
||||
//!
|
||||
//! Each call checks resource limits, then Protocol shape/semantic validation.
|
||||
//! Interface rendering additionally requires [`wip_protocol::INTERFACE_FORMAT_V1`].
|
||||
//! Limits reject the entire input, never produce partial text: at most 1 MiB of
|
||||
//! input string/byte data, 16,384 declarations/fields/cases/type expressions or
|
||||
//! references, 256 named type declarations (bounding validator graph recursion),
|
||||
//! and 64 nested TypeExpr levels. These are implementation limits, not new
|
||||
//! Protocol semantics. An Object without placement context can only be checked
|
||||
//! for name/reference shape and duplicate references; the caller must validate
|
||||
//! scope ancestry and observation consistency at its observation boundary.
|
||||
//!
|
||||
//! Signatures are display-only: no parser, round-trip, identity comparison,
|
||||
//! cache key or call-target reconstruction is provided. The caller owns fetching,
|
||||
//! freshness, authorization, selection and arrangement of multiple signatures.
|
||||
//!
|
||||
//! ```
|
||||
//! use wip_protocol::{Object, InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
|
||||
//! use wip_text_view::{Interface, render_object, render_interface};
|
||||
//! let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
|
||||
//! let object = Object {
|
||||
//! name: "item".into(), description: None, interfaces: vec![reference.clone()],
|
||||
//! r#ref: Some("not a path".into()), validator: Some(vec![1]),
|
||||
//! };
|
||||
//! assert_eq!(render_object(&object)?,
|
||||
//! "object {\n name: \"item\";\n interfaces: [\"/::example\"];\n}\n");
|
||||
//! let descriptor = InterfaceDescriptor {
|
||||
//! format: INTERFACE_FORMAT_V1.into(), documentation: None,
|
||||
//! types: vec![], operations: vec![],
|
||||
//! };
|
||||
//! let interface = Interface { reference: &reference, descriptor: &descriptor };
|
||||
//! assert_eq!(render_interface(&interface)?, "interface \"/::example\" {\n}\n");
|
||||
//! # Ok::<(), wip_text_view::RenderError>(())
|
||||
//! ```
|
||||
//!
|
||||
//! # Typed display tokens
|
||||
//!
|
||||
//! [`tokenize_object`] and [`tokenize_interface`] traverse the input structure
|
||||
//! directly and return owned [`Token`] sequences, including all layout. Existing
|
||||
//! render APIs use this same generation path followed by [`to_plain_text`]. The
|
||||
//! input limits above also bound token allocation: tokens per node, indentation
|
||||
//! depth and escape expansion are bounded; no partial signature is returned.
|
||||
//! Token text is WIP-escaped, **not HTML-escaped** or escaped for other destinations.
|
||||
//! See [`Token`] for the semantic splitting contract; no renderer/theme is supplied.
|
||||
//!
|
||||
//! ```
|
||||
//! use wip_protocol::{InterfaceReference, InterfaceDescriptor, INTERFACE_FORMAT_V1};
|
||||
//! use wip_text_view::{Interface, TokenKind, tokenize_interface, to_plain_text, render_interface};
|
||||
//! let reference = InterfaceReference { scope: "/".into(), name: "example".into() };
|
||||
//! let descriptor = InterfaceDescriptor {
|
||||
//! format: INTERFACE_FORMAT_V1.into(), documentation: None,
|
||||
//! types: vec![], operations: vec![],
|
||||
//! };
|
||||
//! let input = Interface { reference: &reference, descriptor: &descriptor };
|
||||
//! let tokens = tokenize_interface(&input)?;
|
||||
//! assert_eq!(tokens[0].kind(), TokenKind::Keyword);
|
||||
//! assert_eq!(tokens[0].text(), "interface");
|
||||
//! let concatenated: String = tokens.iter().map(|token| token.text()).collect();
|
||||
//! assert_eq!(to_plain_text(&tokens), concatenated);
|
||||
//! assert_eq!(to_plain_text(&tokens), render_interface(&input)?);
|
||||
//! # Ok::<(), wip_text_view::RenderError>(())
|
||||
//! ```
|
||||
|
||||
#![deny(missing_docs)]
|
||||
|
||||
mod limits;
|
||||
mod render;
|
||||
mod token;
|
||||
|
||||
pub use token::{Token, TokenKind, to_plain_text};
|
||||
|
||||
use std::{error::Error, fmt};
|
||||
use wip_protocol::{
|
||||
INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceReference, Object, ValidationError,
|
||||
};
|
||||
|
||||
/// One Interface input entity, borrowing its identity and corresponding data.
|
||||
///
|
||||
/// The caller pairs values from the same observation/publication. The descriptor
|
||||
/// itself has no identity, so rendering cannot verify provenance or freshness.
|
||||
/// This is an SDK display input, not a replacement wire schema or a document.
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
pub struct Interface<'a> {
|
||||
/// Complete, absolute, Client-facing Interface reference.
|
||||
pub reference: &'a InterfaceReference,
|
||||
/// Descriptor corresponding to `reference`.
|
||||
pub descriptor: &'a InterfaceDescriptor,
|
||||
}
|
||||
|
||||
/// Failure to render a complete, validated signature. No partial text is returned.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum RenderError {
|
||||
/// Object-independent Protocol validation failed.
|
||||
InvalidObject(ValidationError),
|
||||
/// The Interface's structured reference is malformed.
|
||||
InvalidReference(ValidationError),
|
||||
/// Descriptor structure or semantics failed Protocol validation.
|
||||
InvalidDescriptor(ValidationError),
|
||||
/// A semantically valid descriptor uses a format this renderer cannot interpret.
|
||||
UnsupportedDescriptorFormat {
|
||||
/// Exact unsupported format identifier.
|
||||
format: String,
|
||||
},
|
||||
/// Input exceeds an implementation safety limit, without truncation.
|
||||
ResourceLimit {
|
||||
/// Limit that was exceeded.
|
||||
limit: ResourceLimit,
|
||||
},
|
||||
}
|
||||
|
||||
/// Bounded input dimensions checked before recursive Protocol validation.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum ResourceLimit {
|
||||
/// Total input string and opaque byte length exceeds 1 MiB.
|
||||
InputBytes,
|
||||
/// Total declarations, fields, parameters, cases, expressions or references exceeds 16,384.
|
||||
Nodes,
|
||||
/// More than 256 named type declarations.
|
||||
TypeDeclarations,
|
||||
/// More than 64 nested TypeExpr levels (outer expression is level one).
|
||||
TypeDepth,
|
||||
}
|
||||
|
||||
impl fmt::Display for RenderError {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
match self {
|
||||
Self::InvalidObject(e) => write!(f, "invalid Object: {e}"),
|
||||
Self::InvalidReference(e) => write!(f, "invalid Interface reference: {e}"),
|
||||
Self::InvalidDescriptor(e) => write!(f, "invalid Interface descriptor: {e}"),
|
||||
Self::UnsupportedDescriptorFormat { format } => {
|
||||
write!(f, "unsupported descriptor format: {format:?}")
|
||||
}
|
||||
Self::ResourceLimit { limit } => write!(f, "Text View input exceeds {limit:?} limit"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Error for RenderError {
|
||||
fn source(&self) -> Option<&(dyn Error + 'static)> {
|
||||
match self {
|
||||
Self::InvalidObject(e) | Self::InvalidReference(e) | Self::InvalidDescriptor(e) => {
|
||||
Some(e)
|
||||
}
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Renders one complete Object signature, with no placement path or inferred data.
|
||||
///
|
||||
/// Validates shape and ordered-set uniqueness, but cannot validate ancestry or
|
||||
/// root/non-root placement without context. Missing and empty descriptions remain
|
||||
/// distinct; ref and validator bytes are ignored for display. Input is unmodified.
|
||||
/// See [crate documentation](crate) for limits and caller responsibilities.
|
||||
pub fn render_object(object: &Object) -> Result<String, RenderError> {
|
||||
tokenize_object(object).map(|tokens| to_plain_text(&tokens))
|
||||
}
|
||||
|
||||
/// Generates the complete owned display token sequence for one Object signature.
|
||||
///
|
||||
/// Uses the same validation, limits, metadata exclusion and caller responsibilities
|
||||
/// as [`render_object`]. No partial sequence is returned on error. Input is not
|
||||
/// modified. See [`Token`] and [`TokenKind`] for semantic roles and splitting.
|
||||
pub fn tokenize_object(object: &Object) -> Result<Vec<Token>, RenderError> {
|
||||
limits::object(object)?;
|
||||
object.validate().map_err(RenderError::InvalidObject)?;
|
||||
Ok(render::object(object))
|
||||
}
|
||||
|
||||
/// Renders one complete Interface signature from one paired input entity.
|
||||
///
|
||||
/// Validates reference shape and all descriptor declarations/named references,
|
||||
/// including cycles, before checking format support. No lookup or Object is
|
||||
/// needed. All types precede all operations, with original member order; only
|
||||
/// documentation summaries are shown, without interpreting Host text.
|
||||
/// Input is unmodified. See [crate documentation](crate) for safety limits.
|
||||
pub fn render_interface(interface: &Interface<'_>) -> Result<String, RenderError> {
|
||||
tokenize_interface(interface).map(|tokens| to_plain_text(&tokens))
|
||||
}
|
||||
|
||||
/// Generates the complete owned display token sequence for one Interface signature.
|
||||
///
|
||||
/// Uses the same validation, limits, format support and summary-only documentation
|
||||
/// as [`render_interface`]. No partial sequence is returned on error. Input is not
|
||||
/// modified. See [`Token`] and [`TokenKind`] for semantic roles and splitting.
|
||||
/// This traverses structured declarations directly, not a rendered-text lexer.
|
||||
pub fn tokenize_interface(interface: &Interface<'_>) -> Result<Vec<Token>, RenderError> {
|
||||
limits::interface(interface)?;
|
||||
interface
|
||||
.reference
|
||||
.validate()
|
||||
.map_err(RenderError::InvalidReference)?;
|
||||
interface
|
||||
.descriptor
|
||||
.validate()
|
||||
.map_err(RenderError::InvalidDescriptor)?;
|
||||
if interface.descriptor.format != INTERFACE_FORMAT_V1 {
|
||||
return Err(RenderError::UnsupportedDescriptorFormat {
|
||||
format: interface.descriptor.format.clone(),
|
||||
});
|
||||
}
|
||||
Ok(render::interface(interface))
|
||||
}
|
||||
|
||||
// Keep both README examples executable as external-consumer doctests.
|
||||
#[cfg(doctest)]
|
||||
#[doc = include_str!("../README.md")]
|
||||
mod readme {}
|
||||
@@ -0,0 +1,125 @@
|
||||
use wip_protocol::{Documentation, InterfaceReference, Object, TypeExpr};
|
||||
|
||||
use crate::{Interface, RenderError, ResourceLimit};
|
||||
|
||||
#[derive(Default)]
|
||||
struct Budget {
|
||||
bytes: usize,
|
||||
nodes: usize,
|
||||
}
|
||||
|
||||
fn check(value: usize, max: usize, limit: ResourceLimit) -> Result<(), RenderError> {
|
||||
if value > max {
|
||||
Err(RenderError::ResourceLimit { limit })
|
||||
} else {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
impl Budget {
|
||||
fn bytes(&mut self, len: usize) -> Result<(), RenderError> {
|
||||
self.bytes = self.bytes.saturating_add(len);
|
||||
check(self.bytes, 1024 * 1024, ResourceLimit::InputBytes)
|
||||
}
|
||||
|
||||
fn nodes(&mut self, len: usize) -> Result<(), RenderError> {
|
||||
self.nodes = self.nodes.saturating_add(len);
|
||||
check(self.nodes, 16_384, ResourceLimit::Nodes)
|
||||
}
|
||||
|
||||
fn reference(&mut self, reference: &InterfaceReference) -> Result<(), RenderError> {
|
||||
self.nodes(1)?;
|
||||
self.bytes(reference.scope.len())?;
|
||||
self.bytes(reference.name.len())
|
||||
}
|
||||
|
||||
fn doc(&mut self, doc: &Option<Documentation>) -> Result<(), RenderError> {
|
||||
if let Some(doc) = doc {
|
||||
self.bytes(doc.summary.len())?;
|
||||
self.bytes(doc.details.as_ref().map_or(0, String::len))?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn declaration(&mut self, name: &str, doc: &Option<Documentation>) -> Result<(), RenderError> {
|
||||
self.nodes(1)?;
|
||||
self.bytes(name.len())?;
|
||||
self.doc(doc)
|
||||
}
|
||||
|
||||
fn expr(&mut self, expr: &TypeExpr, depth: usize) -> Result<(), RenderError> {
|
||||
check(depth, 64, ResourceLimit::TypeDepth)?;
|
||||
self.nodes(1)?;
|
||||
match expr {
|
||||
TypeExpr::Named { name } => self.bytes(name.len())?,
|
||||
TypeExpr::List { items } => self.expr(items, depth + 1)?,
|
||||
TypeExpr::Record { fields } => {
|
||||
self.nodes(fields.len())?;
|
||||
for field in fields {
|
||||
self.bytes(field.name.len())?;
|
||||
self.doc(&field.documentation)?;
|
||||
self.expr(&field.r#type, depth + 1)?;
|
||||
}
|
||||
}
|
||||
TypeExpr::Enum { cases } => {
|
||||
self.nodes(cases.len())?;
|
||||
for case in cases {
|
||||
self.bytes(case.name.len())?;
|
||||
self.doc(&case.documentation)?;
|
||||
}
|
||||
}
|
||||
TypeExpr::Union { cases } => {
|
||||
self.nodes(cases.len())?;
|
||||
for case in cases {
|
||||
self.bytes(case.name.len())?;
|
||||
self.doc(&case.documentation)?;
|
||||
if let Some(payload) = &case.payload {
|
||||
self.expr(payload, depth + 1)?;
|
||||
}
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
pub(crate) fn object(object: &Object) -> Result<(), RenderError> {
|
||||
let mut budget = Budget::default();
|
||||
budget.bytes(object.name.len())?;
|
||||
budget.bytes(object.description.as_ref().map_or(0, String::len))?;
|
||||
budget.bytes(object.r#ref.as_ref().map_or(0, String::len))?;
|
||||
budget.bytes(object.validator.as_ref().map_or(0, Vec::len))?;
|
||||
check(object.interfaces.len(), 16_384, ResourceLimit::Nodes)?;
|
||||
for reference in &object.interfaces {
|
||||
budget.reference(reference)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub(crate) fn interface(interface: &Interface<'_>) -> Result<(), RenderError> {
|
||||
let mut budget = Budget::default();
|
||||
let descriptor = interface.descriptor;
|
||||
budget.reference(interface.reference)?;
|
||||
budget.bytes(descriptor.format.len())?;
|
||||
budget.doc(&descriptor.documentation)?;
|
||||
check(descriptor.types.len(), 256, ResourceLimit::TypeDeclarations)?;
|
||||
// Check collection counts before traversing even empty names/expressions.
|
||||
check(descriptor.operations.len(), 16_384, ResourceLimit::Nodes)?;
|
||||
for ty in &descriptor.types {
|
||||
budget.declaration(&ty.name, &ty.documentation)?;
|
||||
budget.expr(&ty.definition, 1)?;
|
||||
}
|
||||
for operation in &descriptor.operations {
|
||||
budget.declaration(&operation.name, &operation.documentation)?;
|
||||
check(operation.parameters.len(), 16_384, ResourceLimit::Nodes)?;
|
||||
for parameter in &operation.parameters {
|
||||
budget.declaration(¶meter.name, ¶meter.documentation)?;
|
||||
budget.expr(¶meter.r#type, 1)?;
|
||||
}
|
||||
budget.nodes(1)?; // Return declaration.
|
||||
budget.doc(&operation.returns.documentation)?;
|
||||
budget.expr(&operation.returns.r#type, 1)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
@@ -0,0 +1,334 @@
|
||||
use std::fmt::Write as _;
|
||||
use wip_protocol::{Documentation, InterfaceReference, Object, OperationDeclaration, TypeExpr};
|
||||
|
||||
use crate::{Interface, Token, TokenKind};
|
||||
use TokenKind::{
|
||||
CaseName, FieldName, Indentation, Keyword, Newline, OperationName, ParameterName, Reference,
|
||||
Symbol, TypeName, Whitespace,
|
||||
};
|
||||
|
||||
// Quoting a component and quoting the complete reference are separate layers.
|
||||
fn reference(reference: &InterfaceReference) -> String {
|
||||
format!(
|
||||
"{}::{}",
|
||||
component(&reference.scope, true),
|
||||
component(&reference.name, false)
|
||||
)
|
||||
}
|
||||
|
||||
fn component(value: &str, scope: bool) -> String {
|
||||
if !value.is_empty()
|
||||
&& value
|
||||
.bytes()
|
||||
.all(|b| b.is_ascii_alphanumeric() || b"_.-".contains(&b) || (scope && b == b'/'))
|
||||
{
|
||||
value.into()
|
||||
} else {
|
||||
quote(value, '"')
|
||||
}
|
||||
}
|
||||
|
||||
fn identifier(value: &str) -> String {
|
||||
const KEYWORDS: &[&str] = &[
|
||||
"object",
|
||||
"at",
|
||||
"name",
|
||||
"description",
|
||||
"interfaces",
|
||||
"interface",
|
||||
"type",
|
||||
"operation",
|
||||
"enum",
|
||||
"union",
|
||||
"unit",
|
||||
"boolean",
|
||||
"integer",
|
||||
"number",
|
||||
"string",
|
||||
"bytes",
|
||||
"json",
|
||||
"entry",
|
||||
];
|
||||
if value
|
||||
.bytes()
|
||||
.next()
|
||||
.is_some_and(|b| b.is_ascii_alphabetic() || b == b'_')
|
||||
&& value
|
||||
.bytes()
|
||||
.all(|b| b.is_ascii_alphanumeric() || b == b'_')
|
||||
&& !KEYWORDS.contains(&value)
|
||||
{
|
||||
value.into()
|
||||
} else {
|
||||
quote(value, '`')
|
||||
}
|
||||
}
|
||||
|
||||
fn quote(value: &str, delimiter: char) -> String {
|
||||
let mut output = String::new();
|
||||
output.push(delimiter);
|
||||
for ch in value.chars() {
|
||||
match ch {
|
||||
'`' if delimiter == '`' => output.push_str("\\`"),
|
||||
'\\' => output.push_str("\\\\"),
|
||||
'"' => output.push_str("\\\""),
|
||||
'\u{08}' => output.push_str("\\b"),
|
||||
'\u{0c}' => output.push_str("\\f"),
|
||||
'\n' => output.push_str("\\n"),
|
||||
'\r' => output.push_str("\\r"),
|
||||
'\t' => output.push_str("\\t"),
|
||||
'\u{00}'..='\u{1f}'
|
||||
| '\u{7f}'..='\u{9f}'
|
||||
| '\u{2028}'
|
||||
| '\u{2029}'
|
||||
| '\u{061c}'
|
||||
| '\u{200e}'..='\u{200f}'
|
||||
| '\u{202a}'..='\u{202e}'
|
||||
| '\u{2066}'..='\u{2069}' => {
|
||||
write!(output, "\\u{:04x}", ch as u32).expect("String write");
|
||||
}
|
||||
_ => output.push(ch),
|
||||
}
|
||||
}
|
||||
output.push(delimiter);
|
||||
output
|
||||
}
|
||||
|
||||
pub(crate) fn object(object: &Object) -> Vec<Token> {
|
||||
let mut writer = Writer(Vec::new());
|
||||
writer.word(Keyword, "object");
|
||||
writer.space();
|
||||
writer.symbol("{");
|
||||
writer.newline();
|
||||
writer.indent(1);
|
||||
writer.word(Keyword, "name");
|
||||
writer.symbol(":");
|
||||
writer.space();
|
||||
writer.word(TokenKind::String, quote(&object.name, '"'));
|
||||
writer.symbol(";");
|
||||
writer.newline();
|
||||
if let Some(description) = &object.description {
|
||||
writer.indent(1);
|
||||
writer.word(Keyword, "description");
|
||||
writer.symbol(":");
|
||||
writer.space();
|
||||
writer.word(TokenKind::String, quote(description, '"'));
|
||||
writer.symbol(";");
|
||||
writer.newline();
|
||||
}
|
||||
writer.indent(1);
|
||||
writer.word(Keyword, "interfaces");
|
||||
writer.symbol(":");
|
||||
writer.space();
|
||||
writer.symbol("[");
|
||||
for (index, interface) in object.interfaces.iter().enumerate() {
|
||||
if index > 0 {
|
||||
writer.symbol(",");
|
||||
writer.space();
|
||||
}
|
||||
writer.word(Reference, quote(&reference(interface), '"'));
|
||||
}
|
||||
writer.symbol("]");
|
||||
writer.symbol(";");
|
||||
writer.newline();
|
||||
writer.symbol("}");
|
||||
writer.newline();
|
||||
writer.0
|
||||
}
|
||||
|
||||
pub(crate) fn interface(interface: &Interface<'_>) -> Vec<Token> {
|
||||
let mut writer = Writer(Vec::new());
|
||||
writer.doc(&interface.descriptor.documentation, 0);
|
||||
writer.word(Keyword, "interface");
|
||||
writer.space();
|
||||
writer.word(Reference, quote(&reference(interface.reference), '"'));
|
||||
writer.space();
|
||||
writer.symbol("{");
|
||||
writer.newline();
|
||||
for declaration in &interface.descriptor.types {
|
||||
writer.doc(&declaration.documentation, 1);
|
||||
writer.indent(1);
|
||||
writer.word(Keyword, "type");
|
||||
writer.space();
|
||||
writer.word(TypeName, identifier(&declaration.name));
|
||||
writer.space();
|
||||
writer.symbol("=");
|
||||
writer.space();
|
||||
writer.expr(&declaration.definition, 1);
|
||||
writer.symbol(";");
|
||||
writer.newline();
|
||||
}
|
||||
for operation in &interface.descriptor.operations {
|
||||
writer.operation(operation);
|
||||
}
|
||||
writer.symbol("}");
|
||||
writer.newline();
|
||||
writer.0
|
||||
}
|
||||
|
||||
struct Writer(Vec<Token>);
|
||||
|
||||
impl Writer {
|
||||
fn word(&mut self, kind: TokenKind, text: impl Into<String>) {
|
||||
self.0.push(Token {
|
||||
kind,
|
||||
text: text.into(),
|
||||
});
|
||||
}
|
||||
|
||||
fn symbol(&mut self, text: &str) {
|
||||
self.word(Symbol, text);
|
||||
}
|
||||
|
||||
fn space(&mut self) {
|
||||
self.word(Whitespace, " ");
|
||||
}
|
||||
|
||||
fn newline(&mut self) {
|
||||
self.word(Newline, "\n");
|
||||
}
|
||||
|
||||
fn indent(&mut self, depth: usize) {
|
||||
if depth > 0 {
|
||||
self.word(Indentation, " ".repeat(depth));
|
||||
}
|
||||
}
|
||||
|
||||
fn doc(&mut self, doc: &Option<Documentation>, depth: usize) {
|
||||
if let Some(doc) = doc {
|
||||
self.indent(depth);
|
||||
self.word(
|
||||
TokenKind::Documentation,
|
||||
format!("/// {}", quote(&doc.summary, '"')),
|
||||
);
|
||||
self.newline();
|
||||
}
|
||||
}
|
||||
|
||||
fn member(&mut self, kind: TokenKind, name: &str, required: bool, ty: &TypeExpr, depth: usize) {
|
||||
self.indent(depth);
|
||||
self.word(kind, identifier(name));
|
||||
if !required {
|
||||
self.symbol("?");
|
||||
}
|
||||
self.symbol(":");
|
||||
self.space();
|
||||
self.expr(ty, depth);
|
||||
self.symbol(",");
|
||||
self.newline();
|
||||
}
|
||||
|
||||
fn operation(&mut self, operation: &OperationDeclaration) {
|
||||
self.doc(&operation.documentation, 1);
|
||||
self.indent(1);
|
||||
self.word(Keyword, "operation");
|
||||
self.space();
|
||||
self.word(OperationName, identifier(&operation.name));
|
||||
self.symbol("(");
|
||||
if !operation.parameters.is_empty() {
|
||||
self.newline();
|
||||
for parameter in &operation.parameters {
|
||||
self.doc(¶meter.documentation, 2);
|
||||
self.member(
|
||||
ParameterName,
|
||||
¶meter.name,
|
||||
parameter.required,
|
||||
¶meter.r#type,
|
||||
2,
|
||||
);
|
||||
}
|
||||
self.indent(1);
|
||||
}
|
||||
self.symbol(")");
|
||||
if operation.returns.documentation.is_some() {
|
||||
self.newline();
|
||||
self.doc(&operation.returns.documentation, 1);
|
||||
self.indent(1);
|
||||
} else {
|
||||
self.space();
|
||||
}
|
||||
self.symbol("->");
|
||||
self.space();
|
||||
self.expr(&operation.returns.r#type, 1);
|
||||
self.symbol(";");
|
||||
self.newline();
|
||||
}
|
||||
|
||||
// Starts at the current cursor. Composite closing braces align with the
|
||||
// declaration/field/parameter containing this expression, not its width.
|
||||
fn expr(&mut self, expr: &TypeExpr, depth: usize) {
|
||||
match expr {
|
||||
TypeExpr::Unit => self.word(Keyword, "unit"),
|
||||
TypeExpr::Boolean => self.word(Keyword, "boolean"),
|
||||
TypeExpr::Integer => self.word(Keyword, "integer"),
|
||||
TypeExpr::Number => self.word(Keyword, "number"),
|
||||
TypeExpr::String => self.word(Keyword, "string"),
|
||||
TypeExpr::Bytes => self.word(Keyword, "bytes"),
|
||||
TypeExpr::Json => self.word(Keyword, "json"),
|
||||
TypeExpr::Entry => self.word(Keyword, "entry"),
|
||||
TypeExpr::Named { name } => self.word(TypeName, identifier(name)),
|
||||
TypeExpr::List { items } => {
|
||||
self.symbol("[");
|
||||
self.expr(items, depth);
|
||||
self.symbol("]");
|
||||
}
|
||||
TypeExpr::Record { fields } => {
|
||||
self.symbol("{");
|
||||
if !fields.is_empty() {
|
||||
self.newline();
|
||||
for field in fields {
|
||||
self.doc(&field.documentation, depth + 1);
|
||||
self.member(
|
||||
FieldName,
|
||||
&field.name,
|
||||
field.required,
|
||||
&field.r#type,
|
||||
depth + 1,
|
||||
);
|
||||
}
|
||||
self.indent(depth);
|
||||
}
|
||||
self.symbol("}");
|
||||
}
|
||||
TypeExpr::Enum { cases } => {
|
||||
self.word(Keyword, "enum");
|
||||
self.space();
|
||||
self.symbol("{");
|
||||
if !cases.is_empty() {
|
||||
self.newline();
|
||||
for case in cases {
|
||||
self.doc(&case.documentation, depth + 1);
|
||||
self.indent(depth + 1);
|
||||
self.word(CaseName, identifier(&case.name));
|
||||
self.symbol(",");
|
||||
self.newline();
|
||||
}
|
||||
self.indent(depth);
|
||||
}
|
||||
self.symbol("}");
|
||||
}
|
||||
TypeExpr::Union { cases } => {
|
||||
self.word(Keyword, "union");
|
||||
self.space();
|
||||
self.symbol("{");
|
||||
if !cases.is_empty() {
|
||||
self.newline();
|
||||
for case in cases {
|
||||
self.doc(&case.documentation, depth + 1);
|
||||
self.indent(depth + 1);
|
||||
self.word(CaseName, identifier(&case.name));
|
||||
if let Some(payload) = &case.payload {
|
||||
self.symbol("(");
|
||||
self.expr(payload, depth + 1);
|
||||
self.symbol(")");
|
||||
}
|
||||
self.symbol(",");
|
||||
self.newline();
|
||||
}
|
||||
self.indent(depth);
|
||||
}
|
||||
self.symbol("}");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
//! Owned display data, independent of the Protocol wire model.
|
||||
|
||||
/// Semantic display role assigned from the input structure, not from text parsing.
|
||||
///
|
||||
/// Identifiers retain their role even when quoted or identical to a keyword.
|
||||
/// Type declarations and Named expressions both use [`Self::TypeName`]. Enum and
|
||||
/// union cases both use [`Self::CaseName`]. See [`Token`] for splitting rules.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
||||
#[non_exhaustive]
|
||||
pub enum TokenKind {
|
||||
/// Grammar keyword, including Object property labels and primitive types.
|
||||
Keyword,
|
||||
/// Named type declaration or reference within the same Interface.
|
||||
TypeName,
|
||||
/// Operation declaration name (not an invocation target).
|
||||
OperationName,
|
||||
/// Operation parameter name.
|
||||
ParameterName,
|
||||
/// Record field name.
|
||||
FieldName,
|
||||
/// Enum or union case name.
|
||||
CaseName,
|
||||
/// Quoted Object name or description.
|
||||
String,
|
||||
/// Entire quoted absolute Interface reference, including both quoting layers.
|
||||
Reference,
|
||||
/// Entire `/// "summary"` line content, excluding indentation and LF.
|
||||
Documentation,
|
||||
/// One punctuation mark, or the complete two-character return arrow `->`.
|
||||
Symbol,
|
||||
/// One inter-token ASCII space, never indentation or text inside quotes.
|
||||
Whitespace,
|
||||
/// One LF (`\n`), including the final signature LF.
|
||||
Newline,
|
||||
/// All leading spaces on a non-root line: two ASCII spaces per depth level.
|
||||
Indentation,
|
||||
}
|
||||
|
||||
/// One owned, already escaped fragment of a Text View signature.
|
||||
///
|
||||
/// Each keyword, identifier, quoted string and complete quoted reference is one
|
||||
/// token, including its delimiters and escapes. Documentation is one token for
|
||||
/// the `///` marker, space and quoted summary together. Symbols are individual
|
||||
/// punctuation marks except `->`, which is indivisible. Spaces between tokens,
|
||||
/// each LF, and each nonzero line indentation have separate tokens. No empty
|
||||
/// tokens are emitted; an empty value still has its quotes. Adjacent symbols are
|
||||
/// not merged. Host whitespace inside quoted data stays inside that data token.
|
||||
///
|
||||
/// The generation APIs emit all layout: concatenating [`Self::text`] in order,
|
||||
/// without separators, produces exactly the existing plain-text signature.
|
||||
/// Tokens own their text and can outlive the input; they are display data, not
|
||||
/// an AST, lexer output, Protocol serialization or identity/call-target data.
|
||||
///
|
||||
/// Text is escaped for **WIP Text View**, not for HTML or any other destination.
|
||||
/// Custom renderers must apply destination-specific escaping and must not treat
|
||||
/// Host documentation as markup or instructions.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct Token {
|
||||
pub(crate) kind: TokenKind,
|
||||
pub(crate) text: String,
|
||||
}
|
||||
|
||||
impl Token {
|
||||
/// Returns the semantic display role, without reparsing the output text.
|
||||
pub fn kind(&self) -> TokenKind {
|
||||
self.kind
|
||||
}
|
||||
|
||||
/// Returns the exact output fragment, with WIP quoting and escapes applied.
|
||||
pub fn text(&self) -> &str {
|
||||
&self.text
|
||||
}
|
||||
}
|
||||
|
||||
/// Concatenates token text in order, with no separators or further processing.
|
||||
///
|
||||
/// This performs no grammar interpretation, validation, quoting, escaping or
|
||||
/// layout completion. An empty slice yields an empty string. Filtering or
|
||||
/// reordering tokens is allowed, but need not produce a complete signature.
|
||||
/// Object/Interface generation limits are checked by [`crate::tokenize_object`]
|
||||
/// and [`crate::tokenize_interface`], not by this concatenation function.
|
||||
pub fn to_plain_text(tokens: &[Token]) -> String {
|
||||
tokens.iter().map(Token::text).collect()
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
interface "/::example" {
|
||||
type `string` = {
|
||||
`表示名`: string,
|
||||
};
|
||||
operation `find-item`(
|
||||
`search term`: string,
|
||||
) -> `string`;
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
/// "Issueの内容と関連項目を読む。"
|
||||
interface "/::issue.read" {
|
||||
type Relation = enum {
|
||||
parent,
|
||||
sibling,
|
||||
related,
|
||||
};
|
||||
type RelatedItems = {
|
||||
/// "同じWorldspace内の関連項目。"
|
||||
items: [entry],
|
||||
next_cursor?: string,
|
||||
};
|
||||
/// "本文を取得する。"
|
||||
operation read_body() -> {
|
||||
body: string,
|
||||
};
|
||||
/// "関係を指定して関連項目を取得する。"
|
||||
operation get_related_items(
|
||||
relation: Relation,
|
||||
limit?: integer,
|
||||
) -> RelatedItems;
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
interface "/::example" {
|
||||
/// "type summary"
|
||||
type Z = {
|
||||
/// "field summary"
|
||||
z?: unit,
|
||||
a: [union {
|
||||
/// "case summary"
|
||||
z,
|
||||
/// ""
|
||||
a(unit),
|
||||
nested(enum {
|
||||
/// "enum summary"
|
||||
z,
|
||||
a,
|
||||
}),
|
||||
}],
|
||||
};
|
||||
operation z(
|
||||
z: unit,
|
||||
a?: unit,
|
||||
) -> unit;
|
||||
operation a()
|
||||
/// "no params result"
|
||||
-> unit;
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
object {
|
||||
name: "123";
|
||||
description: "Issue 123の公開操作。本文はOperationで取得する。";
|
||||
interfaces: ["/::issue.read", "/::issue.lifecycle"];
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
interface "/::example" {
|
||||
type CloseResult = union {
|
||||
closed,
|
||||
blocked({
|
||||
dependencies: [entry],
|
||||
}),
|
||||
};
|
||||
operation refresh() -> unit;
|
||||
/// "対象を検索する。"
|
||||
operation search(
|
||||
/// "検索語。"
|
||||
query: string,
|
||||
)
|
||||
/// "条件に一致する項目。"
|
||||
-> {
|
||||
items: [entry],
|
||||
};
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user