@shortlink-org/portolan 0.1.0

package/plugins/extract-rust/Cargo.lock

@@ -0,0 +1,133 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "indexmap"
+version = "2.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "portolan-extract-rust"
+version = "0.1.0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde",
+ "serde_json",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12df2e0110f65b775f769bb17ef989067a1d931b2eb822bd4346631eeada89f9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

package/plugins/extract-rust/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "portolan-extract-rust"
+version = "0.1.0"
+edition = "2024"
+description = "A Rust service in, a catalog fragment out: the Rust twin of extract-go and extract-ts, on the same protocol."
+publish = false
+
+[lib]
+name = "portolan_extract_rust"
+path = "src/lib.rs"
+
+[[bin]]
+name = "portolan-extract-rust"
+path = "src/main.rs"
+
+[dependencies]
+# The right parser for Rust is Rust's own; syn reads the whole language, and
+# proc-macro2's span-locations is what turns a node back into file:line.
+syn = { version = "3", features = ["full", "visit", "extra-traits"] }
+proc-macro2 = { version = "1", features = ["span-locations"] }
+quote = "1"
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1", features = ["preserve_order"] }

package/plugins/extract-rust/README.md

@@ -0,0 +1,204 @@
+# extract-rust
+
+A Rust service in, a catalog fragment out. The Rust twin of `extract-go` and
+`extract-ts`: it describes one service - its aggregates, what they publish,
+what runs when somebody calls in, what the service calls - by reading the
+tree, and it reads the tree by its layout. Nothing is annotated for the
+catalog; the layout is the claim.
+
+Written in Rust and run as a process plugin, `cargo run --quiet --manifest-path
+plugins/extract-rust/Cargo.toml`, because the right parser for Rust is Rust's
+own: `syn` reads the whole language, and `proc-macro2`'s span locations turn a
+node back into `file:line`. There is no type checker; everything is resolved
+by name and by `use` path, which is all a layout that is the claim needs.
+
+## The layout it reads
+
+```
+src/
+  domain/<aggregate>/
+    <aggregate>.rs        the root: a pub struct named like the directory, in PascalCase
+    *.rs                  entities: other pub structs in the directory's own files
+    vo/*.rs               value objects: pub structs under vo/
+    *.rs, vo/*.rs         enums: pub enums whose every variant is a bare name; `Error` is skipped
+    rules/*.rs            specifications; skipped, they are not shapes
+    event/*.rs            one pub struct per event, named by `fn name(&self) -> &'static str { "oms.OrderPlaced" }`
+                          in any impl of it, or by `pub const NAME: &str`
+    port.rs               traits a use case holds: repositories, publishers
+    status.rs             optional: `pub const TRANSITIONS: &[(&str, &[&str])] = &[("placed", &["confirmed"]), …]`
+    README.md             the aggregate's page, or the doc comment above the root
+  application/<aggregate>/usecases/<name>/
+    mod.rs                `pub struct UseCase` with a `handle(&self, …)` method; its fields are the ports
+    README.md             the operation's doc, or the doc comment above the struct
+  application/policy/*.rs   one pub struct per policy, `handle(&self, event)` reacting to one event
+  infrastructure/transport/grpc/<aggregate>/
+    proto/**/*.proto      the contract this service publishes: the service and its rpcs
+    *.rs                  `impl <Service> for <Handlers>`: a method per rpc, running use cases held as fields
+  infrastructure/<peer>/
+    proto/**/*.proto + gen/   a gRPC peer: the vendored contract and tonic's output
+    *.rs                  the adapter over the generated client, `impl <Port> for <Adapter>`
+  infrastructure/repository/<aggregate>/
+    *.rs                  `pub const TOPIC: &str` names the channel the aggregate's events leave on;
+    migrations/*.sql      read by extract-sql, with `repositories` pointed at the directory above
+```
+
+## What becomes what
+
+**Aggregate.** Every directory under `src/domain/` whose name has a root
+struct in it. The root is the pub struct whose name is the directory's in
+PascalCase (`order` → `Order`); a directory without one is reported and
+skipped. Its fields are the struct's fields with the type as written. Other
+pub structs in the directory's top-level files are entities; structs under
+`vo/` are value objects; `rules/` is skipped. The readme is `README.md` in the
+directory, or the doc comment above the root.
+
+**Enum.** A pub enum in the directory's own files or under `vo/` whose every
+variant is a bare name is a closed set of values, id
+`<aggregate>.<slug>`. A variant carrying data makes the enum a sum type, which
+is a shape rather than a set, and it is not read; `Error` is not read either,
+being what a command refuses with. A value's name is the string literal an
+inherent method answers for the variant - `as_str`, or any method whose body
+is a `match self` with a literal per arm - and the variant's own name when
+there is none; the doc is the variant's doc comment, and `#[deprecated]` on a
+variant or the enum is carried.
+
+**Event.** Each pub struct under `event/` whose name on the bus can be read -
+a `name` method returning a string literal in any of its impl blocks,
+inherent or of a trait, or a `NAME` constant - is an event of the aggregate,
+its id `<service>.<aggregate>.<Struct>`. Fields as for a root; doc from the
+doc comment; one version, `v1`; `consumers` empty, because a service does not
+know who listens. The channel is the `TOPIC` constant of the aggregate's
+repository module, the adapter that turns an event into a message.
+
+**Operation.** Each `application/<aggregate>/usecases/<name>/mod.rs`
+declaring a `pub struct UseCase` with a method `handle`. The id is the
+directory's name in PascalCase (`place_order` → `PlaceOrder`). It is a command
+when `handle` - or any other method of the struct - calls `save`, `delete`,
+`create`, `update`, `publish`, `remove`, `insert` or `upsert` on a port, else a
+query. The doc is the directory's `README.md` first paragraph, or the doc
+comment above the struct. `exposedBy` names the rpcs that run it, read from
+the handlers.
+
+**Port.** A field of `UseCase`, typed with a trait: `orders: Arc<dyn Orders>`,
+`orders: O` under `O: Orders`, in the generics or a `where` clause. A field
+typed with a function, `Box<dyn Fn() -> …>`, is a clock and no port. What the
+trait is decides what a call on it becomes:
+
+| the trait is | a call on it is |
+| --- | --- |
+| declared in `domain/<aggregate>/port.rs` | a `call` into the store lane, named by the method; an argument that holds an event is the event leaving for the bus |
+| declared in a use case's `mod.rs` and implemented by an adapter under `infrastructure/` | an `rpc` to the peer, read through the adapter's method to the client's call |
+| another use case's `UseCase` held outright, `place_order: Arc<PlaceOrder>` | a `call` to the service itself, and that use case's own steps, inlined two deep at most |
+
+A trait implemented more than once - the adapter over a real peer, a stand-in
+without - shows as the implementation that reaches a peer.
+
+**Lifecycle.** An aggregate whose directory declares a `TRANSITIONS` table -
+a slice of `(state, &[states it may become])` - gets a `lifecycle`: the states
+in the table's order, the first being where a new root starts, and one move
+per edge. The method of the root that assigns `self.status` is the mover;
+every public method that calls it with a literal - a string, or a variant of
+the status enum, `Status::Confirmed` read as `confirmed` - makes the edges
+into that state, and `emits` is the event its return type names. A status
+assigned anywhere else, a move into a state the table lacks, and an edge in
+the table no method makes are each reported. A state nothing leads out of is
+terminal; that is derived on the page, never written down.
+
+**Flow, from an endpoint.** Each rpc of the proto under
+`transport/grpc/<aggregate>/proto/` that a method of `impl <Service> for …`
+answers - `GetOrder` and `get_order` are one name - opens a flow: `client →
+service : rpc GetOrder`, then the steps of every use case the method runs
+through `self.<field>.handle(…)`, in the order it runs them. **Flow, from a
+policy.** Each pub struct under `application/policy/` with a `handle` opens a
+flow on the bus: `bus → service : event <ref>`, where the event is the type of
+`handle`'s event parameter, or failing that the name the body compares the
+message's against - `message.name != "…"`, a `match` arm. A type from under
+`src/domain` is the service's own; one from another module is another
+service's, and a line in the `events` option mapping that module to an
+aggregate id resolves it, without one the step names the type and is
+unresolved.
+
+**Inside a body.** Statements are read in source order. A call on a port is a
+hop; a call on `self.<method>` is followed into the method; `if`, `if let` and
+`match` become an `alt` when some arm holds a hop, an arm that ends in
+`return`, an `Err(…)` or a `bail!` is terminal; `for`, `while` and `loop`
+become a note on the steps inside; `?` and `.await` are transparent. Every
+step is `declared`: this reads code, and code is a claim about behaviour, not
+a record of it. A call whose peer the manifest does not name is `unresolved`.
+
+**What a name holds.** A value is followed back to its type by name: what an
+associated function on a domain struct, a method on a domain value or a port
+method hands back, as its return type is written - `Result<(Order,
+OrderPlaced), E>` binds both by position, through `Ok(…)`, `Some(…)` and a
+tuple pattern. `for order in idle` holds one of what `idle` holds;
+`events.push(x)` and `vec![x]` collect what `x` holds, and the list handed to
+a port is each event collected, once. An event handed to a domain port -
+`&placed`, `&[&placed]`, `&events` - is the event leaving for the bus; a field
+read off one is not.
+
+**gRPC peer.** An adapter implements a use case's port and holds tonic's
+generated client; a method call in the adapter's body whose name is an rpc of
+the proto vendored under `proto/` beside `gen/` is that rpc, in the proto's
+own case: `self.inner.authorize(…)` is `payments.v1.PaymentService/Authorize`.
+The peer is the manifest's `peers` entry for the proto package; without one
+the lane is `unknown` and the step unresolved, and the call is recorded on the
+service's `consumes` with the vendored proto as its source.
+
+## Options
+
+```json
+{
+  "context": "shop",
+  "contextName": "Shop",
+  "service": "oms",
+  "store": "pg",
+  "peers": { "payments.v1": "payments.ledger" },
+  "events": { "crate::infrastructure::cart": "shop.cart.basket" },
+  "source": "src",
+  "out": "domain.json"
+}
+```
+
+`source` is the directory the layout starts in, `src` unless said otherwise.
+`events` is keyed by the module path another service's events are decoded
+in. Everything else means what it means for `extract-go`.
+
+## Extraction limits
+
+These cases do not become facts in the fragment:
+
+- a domain directory with no root struct of its name;
+- a use case directory with no `UseCase`, or a `UseCase` with no `handle`;
+- a port whose trait is neither a domain port, a use case, nor implemented by
+  an adapter, whose calls are therefore left out;
+- an rpc in the proto with no method answering it;
+- a policy whose `handle` tests for no event, or for one the repository does
+  not declare and the manifest does not place;
+- an adapter with a `gen/` and no `proto/` beside it, whose calls cannot be named;
+- an event no flow reaches;
+- a proto package the manifest names no peer for.
+
+## Manifest
+
+```json
+{
+  "plugins": [{ "name": "rust-domain", "process": { "command": "cargo", "args": ["run", "--quiet", "--manifest-path", "plugins/extract-rust/Cargo.toml"] } }],
+  "extract": [
+    { "plugin": "rust-domain", "in": "examples/shop/oms", "out": "examples/shop/oms/portolan",
+      "options": { "context": "shop", "service": "oms", "store": "pg",
+                   "peers": { "payments.v1": "payments.ledger" },
+                   "events": { "crate::infrastructure::cart": "shop.cart.basket" }, "out": "domain.json" } }
+  ]
+}
+```
+
+`cargo run` builds the plugin the first time and reuses the build after; the
+target directory is not committed.
+
+## Tests
+
+The reader is held to a fixture under `testdata/oms`: a small service in the
+layout above, each shape it claims to read present once, and a golden
+fragment, `expected.json`. `cargo test --manifest-path
+plugins/extract-rust/Cargo.toml` runs it, and CI runs it beside the Go and
+TypeScript suites.

package/plugins/extract-rust/options.schema.json

@@ -0,0 +1,65 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context this service belongs to. A crate knows its name, not which context owns it. Defaults to the name of the input directory.",
+      "examples": ["shop"]
+    },
+    "contextName": {
+      "type": "string",
+      "description": "What the context is called on the page. Defaults to the slug, titled.",
+      "examples": ["Shop"]
+    },
+    "contextSummary": {
+      "type": "string",
+      "description": "A sentence or two on what the context is responsible for. Read on the context page and nowhere else."
+    },
+    "classification": {
+      "enum": ["core", "supporting", "generic"],
+      "description": "Whether the context is core to the business, supports it, or is generic and could be bought."
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service. Defaults to the name of the input directory.",
+      "examples": ["oms"]
+    },
+    "serviceName": {
+      "type": "string",
+      "description": "What the service is called on the page. Defaults to the title of its README, and failing that to the slug, titled."
+    },
+    "repo": {
+      "type": "string",
+      "description": "Where the source lives. Defaults to the repository in Cargo.toml.",
+      "examples": ["github.com/shortlink-org/portolan"]
+    },
+    "store": {
+      "type": "string",
+      "description": "Slug of the database this service keeps its state in, the same one the sql extractor is given. It is here for the flows: a call on a repository lands somewhere, and only the manifest knows where.",
+      "examples": ["pg"]
+    },
+    "peers": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which service answers for what this one calls, as the callee's proto package to its service id. The generated client names the package and the rpc; only the manifest knows whose it is. A package with no line here is called as unknown and its steps stay unresolved.",
+      "examples": [{ "payments.v1": "payments.ledger" }]
+    },
+    "events": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Where another service's events are decoded in this crate, as the module path to the aggregate id they belong to: a policy reacting to a type from that module reacts to that aggregate's event. Without a line the step is unresolved.",
+      "examples": [{ "crate::infrastructure::cart": "shop.cart.basket" }]
+    },
+    "source": {
+      "type": "string",
+      "description": "The directory the layout starts in, relative to the input root.",
+      "default": "src"
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory. One extractor writes one file, so that a fragment carries the provenance of the run that produced it.",
+      "default": "domain.json"
+    }
+  }
+}

package/plugins/extract-rust/rustfmt.toml

@@ -0,0 +1 @@
+max_width = 160