Skip to content

README.md

Latest commit

 

History

History
94 lines (85 loc) · 5.07 KB

README.md

File metadata and controls

94 lines (85 loc) · 5.07 KB
Raw

generated/

Artifacts derived from a Rust source of truth — most are regenerated by mise run gen-specs. A handful of files in this tree are hand-maintained package metadata (package descriptions, dependency declarations, README copy). They live here because they sit next to the regenerated code, not because they're themselves generated.

mise run gen-specs-check runs the generators and diffs the result against the checked-in tree, so hand edits to a regenerated file will be reverted on the next regen.

Hand-maintained

These are committed under generated/ for proximity to the generated code they accompany, but the regeneration pipeline never writes to them. Edit them directly:

  • dart-ws/pubspec.yaml — Dart package metadata.
  • dart-ws/README.md
  • dart-rest/pubspec.yaml — Dart package metadata, version, deps (dio, retrofit, json_annotation + the swagger_parser / build_runner codegen dev-deps).
  • dart-rest/swagger_parser.yaml — generator config (schema path, serializer, client_postfix).
  • dart-rest/README.md
  • python-ws/pyproject.toml — Python package metadata, version, deps.
  • python-ws/README.md
  • python-ws/et_ws/__init__.py — Package exports / re-imports.
  • python-rest/pyproject.toml — Python package metadata, version, runtime deps (httpx, attrs). openapi-python-client is invoked with --meta none, so it only writes the source package and never touches this file.
  • rust-rest/Cargo.toml — Crate name, deps (inherited from [workspace.dependencies]), feature flags. progenitor (driven in-process by et-int-gen) only writes src/lib.rs, leaving this file untouched. The [lints] workspace = true table is intentionally omitted — progenitor's generated source contains patterns the workspace lint set flags (doc-comment shapes that trip rustdoc's invalid-code-block lint, etc.), so the lint-inheritance schema (config/taplo/require-lints-section.schema.json) exempts this Cargo.toml. The deps-inheritance schema does not.
  • zig-rest/build.zig.zon — Zig package manifest (name, version, fingerprint). Regen writes only src/et_rest_client.zig.
  • specs/wit/world.wit — The top-level et:ws-wasi@0.1.0 package (the ws and entry interfaces plus the runner/module worlds). Static content with no Rust-derived parts; edit directly. The companion specs/wit/deps/et-ws-messages/messages.wit is generated from the ClientMessage + ServerMessage schemas and lives in the next section.

Regenerated by mise run gen-specs

  • specs/ws.yaml — AsyncAPI 3.0 description of the WebSocket protocol. Source: edge_toolkit::ws::{ClientMessage, ServerMessage} annotated for asyncapi-rust, emitted by utilities/int-gen.
  • specs/rest.yaml — OpenAPI 3.0 description of the ws-server's REST surface. Source: #[utoipa::path] annotations on handlers in services/{ws-server,modules,storage}, aggregated by utilities/int-gen.
  • specs/wit/deps/et-ws-messages/messages.wit — Typed WIT mirror of ClientMessage + ServerMessage (records + two tagged unions). Built with wit-encoder in utilities/int-gen/src/wit/messages.rs.
  • dart-ws/lib/ws_messages.dart — Dart 3 sealed-class client for the WS protocol. Pipeline: ClientMessage + ServerMessage JSON Schemas → KDL (utilities/int-gen/src/kdl.rs) → dart-typegen → .dart.
  • python-ws/et_ws/messages.py — Pydantic v2 models for the WS protocol. Pipeline: ClientMessage + ServerMessage JSON Schemas → datamodel-code-generator → .py.
  • python-rest/et_rest_client/ — Typed Python (httpx-based) client for the REST surface. Pipeline: specs/rest.yaml → openapi-python-client → et_rest_client package.
  • rust-rest/src/lib.rs — Typed Rust client for the REST surface, generated by progenitor (driven in-process by et-int-gen) from specs/rest.yaml.
  • dart-rest/lib/ — Typed Dart (retrofit-on-dio) client for the REST surface. Pipeline: specs/rest.yaml → swagger_parser → build_runner. Two files are post-processed by gen:dart-rest after swagger_parser and are therefore not safe to hand-edit (regen overwrites): clients/ storage.dart (binary octet-stream body/response made browser-usable) and rest_client.dart (sub-client import paths corrected). The rest of lib/ is verbatim generator output.
  • zig-rest/src/et_rest_client.zig — Typed Zig client for the REST surface. Pipeline: et-int-gen writes target/int-gen/rest.json, invokes openapi2zig as a subprocess, then uses tree-sitter-zig to swap requestRaw's body for a single extern fn js_rest_request call (the JS host bridges that to fetch() via SharedArrayBuffer + Atomics). Zig's lazy compilation + DCE drops the remaining std.http/std.Io machinery automatically.

Fetched (upstream WIT)

specs/wit/deps/wasi-*/ — WASI interface packages pulled verbatim from upstream at pinned tags/SHAs by mise run fetch-wit-deps. Not regenerated by gen-specs; bump them by editing the version pins in utilities/int-gen/src/wit/upstream.rs and rerunning fetch-wit-deps.