@shortlink-org/portolan 0.1.0

package/plugins/extract-http-clients/main.go

@@ -0,0 +1,42 @@
+// Package main is portolan-extract-http-clients: outbound HTTP and SOAP calls
+// in a Go repository in, source-backed dependencies and flows out.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+type Options struct {
+	Context   string            `json:"context"`
+	Service   string            `json:"service"`
+	Peers     map[string]string `json:"peers,omitempty"`
+	Externals map[string]string `json:"externals,omitempty"`
+	Out       string            `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-http-clients:", err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	return plugin.Serve(stdin, stdout, descriptor(), func(req plugin.Request, opts Options) (plugin.Response, error) {
+		if req.Input.Root == "" {
+			return plugin.Response{}, fmt.Errorf("no input root: an extractor has nothing to read")
+		}
+		if opts.Context == "" {
+			opts.Context = slug(filepath.Base(req.Input.Root))
+		}
+		if opts.Service == "" {
+			opts.Service = slug(filepath.Base(req.Input.Root))
+		}
+		return extract(req.Input, opts)
+	})
+}

package/plugins/extract-http-clients/options.schema.json

@@ -0,0 +1,33 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the top-level group that owns the component. Defaults to the input directory name.",
+      "examples": ["avia"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the component making outbound calls. Defaults to the input directory name.",
+      "examples": ["billing"]
+    },
+    "peers": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Internal service answering an API, as API id to service id.",
+      "examples": [{ "auth.v1": "auth.auth" }]
+    },
+    "externals": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Override for the external system named by a vendored client contract, as API id to external id.",
+      "examples": [{ "gordian.v2": "gordian" }]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file inside the step output directory.",
+      "default": "http-clients.json"
+    }
+  }
+}

package/plugins/extract-java/README.md

@@ -0,0 +1,190 @@
+# extract-java
+
+A Java service in, a catalog fragment out. The fifth extractor, and the first
+that reads a language with a vocabulary for the model.
+
+Go, TypeScript, Rust and Python have no word for "aggregate root", so those
+extractors infer the role of a class from where it sits. Java does have one:
+[jMolecules](https://github.com/xmolecules/jmolecules) writes `@AggregateRoot`,
+`@Entity`, `@ValueObject`, `@Repository` and `@DomainEvent` into the source, and
+Spring Modulith writes `@ApplicationModuleListener`. So here the code *declares*
+its own model and this reads the declaration. Where the annotations are absent
+the layout answers instead, and that is said in a diagnostic — a guess and a
+claim should not read the same on the page.
+
+Written in Java, **JDK only**: no Gradle, no Maven, no third-party library. The
+parser is javac's own — `com.sun.source.util.JavacTask`, stopped after `parse()`
+— which is the same stance every other extractor takes (`syn` for Rust, `ast`
+for Python, oxc for TypeScript). Nothing is resolved and no classpath is
+assembled: the service's dependencies are not this plugin's to fetch, and what
+is read is what the author wrote. The protocol's JSON is read and written by
+`Json.java`, because the JDK ships no JSON API and pulling one in would need the
+build system this avoids.
+
+## The layout it reads
+
+```
+src/main/java/<package>/
+  domain/<aggregate>/
+    Payment.java              @AggregateRoot - the root; failing that, the class named after the package
+    Posting.java              @Entity
+    vo/Money.java             @ValueObject, usually a record
+    event/PaymentCaptured.java  @DomainEvent, with NAME and CHANNEL constants
+    PaymentRepository.java    @Repository - the port whose other end is the store
+    PaymentGateway.java       @SecondaryPort - a port to somebody else's system
+    PaymentStatus.java        the states, and TRANSITIONS beside them
+  application/<aggregate>/usecase/
+    AuthorizePayment.java     @Service, one public method - handle, execute, or the only one
+  application/policy/
+    VoidPaymentOnOrderCancelled.java   @ApplicationModuleListener, the event is the argument's type
+  infrastructure/transport/grpc/<aggregate>/
+    PaymentGrpcService.java   @GrpcService
+    proto/**/*.proto          the contract it answers, vendored
+  infrastructure/<peer>/
+    OrderClient.java          the adapter, @SecondaryAdapter or a class filling a port
+    proto/**/*.proto          the callee's contract, vendored narrow
+    openapi/openapi.yaml      or, for an HTTP peer, its document, vendored narrow
+  infrastructure/bus/Bus.java  how an event leaves
+```
+
+## What becomes what
+
+**Aggregate.** A package under `domain` is one. Its root is the class saying
+`@AggregateRoot`; without one, the class named after the package, and a
+diagnostic saying the role was read off the layout. Every `@Entity` beside it
+is an entity, the root included and first; every `@ValueObject` is a value
+object. Fields keep the type as written — `Association<Object, String>` stays
+that, because a typed reference to another aggregate is a fact worth seeing.
+A class that extends an exception is a sentinel - what a command refuses with
+- and a class under the aggregate's `services` package is a domain service;
+neither holds anything of the aggregate, so neither is a block of it. The doc
+of anything is its javadoc, first paragraph.
+
+**Enum.** Every top-level enum in an aggregate's package is a closed set of
+values, id `<aggregate>.<slug>`: its constants in declaration order, each
+with its javadoc, `@Deprecated` carried on a constant and on the type. A
+constant is a member whose type is the enum itself, so a `TRANSITIONS` table
+beside them is not one. jMolecules has no annotation for this, and none is
+needed: an enum in a domain package is a vocabulary whatever it is called. A
+status enum is read twice - here as the set, and by the lifecycle for its
+moves. Enums nested inside a class are not read.
+
+**Event.** A class saying `@DomainEvent`, or any class in the aggregate's
+`event` package. Its `NAME` constant is the name on the wire and `CHANNEL` is
+where it goes out; without a `NAME` the wire name is assumed from the service
+and that is reported. A record's components are the payload.
+
+**Operation.** A class saying `@Service` — jMolecules' one — or a class under
+`application/**/usecase`. Its entry is `handle`, `execute`, or the single public
+method it has. It is a command when it saves, deletes, publishes or sends, and
+a query when it does not. `exposedBy` names the rpcs that run it.
+
+**Endpoint.** A method of a `@GrpcService` whose name is an rpc of the contract
+vendored beside it — `getOrder` and `GetOrder` are one name. The endpoint's id
+is the proto's spelling, so what this says and what `extract-proto` puts in
+`provides` are the same string; an rpc the contract declares and no method
+answers is reported.
+
+**Lifecycle.** Read off the table the code keeps, never off the branches of the
+methods: a `TRANSITIONS` map beside the status enum, and the method of the root
+that assigns `this.status` is the mover. `emits` is the event the mover's return
+type names. An edge the table has and no method makes, a move into a state the
+enum lacks, and a status assigned to something the states do not name are each
+reported.
+
+**Ports, and the difference between them.** A port is an interface of the
+domain, and what a call on it means depends on which one it is. A `@Repository`
+(or a name ending in `Repository`) is the store: the call is a hop into the
+service's own database. Any other port is filled by an adapter under
+`infrastructure/<peer>/`, and the call goes wherever that adapter reaches — an
+rpc named by the contract vendored beside it, or, when there is no contract
+at all, the adapter's own method, recorded and left unresolved. A port nothing
+fills at all is reported. A port a use case declares for itself, under
+`application`, is filled the same way, by the adapter that implements it; and
+an adapter's method is the rpc it is named after or, when the port speaks the
+use case's words rather than the contract's, the rpc its body invokes on the
+stub. A port named for publishing - `Publisher`, `Bus`, or a name ending in
+`Events` - is the bus wherever it is declared, and a call on it is an event
+leaving.
+
+**HTTP peer.** Nothing in the code names the operation, so it is read the
+other way round: the method's body calls `http.post("/v1/payment_intents/" + id + "/capture", …)`,
+the verb and the route are in the call, and the OpenAPI document vendored
+beside the adapter says which operation answers there. Every non-literal part
+of the route stands in as a parameter, so that call lands on
+`/v1/payment_intents/{intent}/capture`, and the call is recorded as
+`stripe.v1/PostPaymentIntentsIntentCapture` - the api id the document goes by
+(its `x-portolan-api`, or its title and major version) and the operationId,
+spelled the way `extract-openapi` spells it. A route the document does not
+declare is reported and left out. The peer is then the manifest's `peers`
+entry for the api id when a service of ours answers, or its `externals` entry
+when the far end is outside the estate: the lane is `external`, the step is
+declared, and the catalog says where the call lands without pretending to own
+it. A method that makes two calls is the first one it makes.
+
+A call made inside the condition of an `if` is a hop before the branch it
+decides. **Flow, from an endpoint.** Each handler method opens one: `client → service :
+rpc <rpc>`, then the steps of every use case it runs, in order. **Flow, from a
+policy.** Each `@ApplicationModuleListener`, `@EventListener` or
+`@DomainEventHandler` method opens one on the bus: `bus → service
+: event <ref>`, where the event is the type of its argument — one of this
+service's own, or another service's placed by the manifest's `events`.
+
+**Inside a body.** Statements are read in source order, and a chain left to
+right. `if` becomes an alt when some arm holds a hop, and a branch ending in a
+return or a throw is terminal; a `for`, a `while` and a `catch` are a note on
+the steps inside them. A call into another use case is followed, two deep at
+most. Every step is `declared`.
+
+## What it does not read
+
+Named here rather than left to be discovered: **JPA mappings** (the schema is
+`extract-sql`'s to read, off the migrations), **Spring configuration**,
+**`@RestController` routes** (the class is read, the route is the OpenAPI
+document's business), **Axon's** event sourcing annotations, and **records of
+what ran** — every step here is a claim about behaviour, not a recording.
+
+## Options
+
+```json
+{
+  "context": "payments",
+  "service": "ledger",
+  "store": "pg",
+  "peers": { "shop.v1": "shop.oms" },
+  "externals": { "stripe.v1": "stripe" },
+  "events": { "org.portolan.payments.ledger.infrastructure.oms.event": "shop.oms.order" },
+  "source": "src/main/java",
+  "out": "domain.json"
+}
+```
+
+`peers` is keyed by the proto package, or the api id, of the contract vendored
+beside an adapter; `externals` by the api id of a document vendored from
+outside the estate, to the id the `openapi` extractor was given under
+`external` for the same copy; `events` by the package a listener reads a
+foreign event from. Everything else means what it means for `extract-ts`.
+
+## Building, and running it
+
+```bash
+javac --release 21 -d plugins/extract-java/build plugins/extract-java/src/org/portolan/extract/*.java
+java -cp plugins/extract-java/build org.portolan.extract.Main
+```
+
+The first line is in `plugins:build`, so `npm run schema` and `npm run gen`
+compile it before they ask it anything. Startup is a tenth of a second, which is
+why it is a jar-less class directory and not a Gradle run.
+
+## Tests
+
+```bash
+javac --release 21 -d plugins/extract-java/build -cp plugins/extract-java/build \
+    plugins/extract-java/test/org/portolan/extract/ExtractTest.java
+java -cp plugins/extract-java/build org.portolan.extract.ExtractTest
+```
+
+The reader is held to `testdata/ledger`: a service in the layout above with each
+shape it claims to read present once, against the golden `expected.json`, plus
+the claims named one at a time so a failure says which rule stopped being true.
+`UPDATE_GOLDEN=1` writes the golden again after a deliberate change.

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

@@ -0,0 +1,70 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context this service belongs to. Defaults to the name of the input directory.",
+      "examples": ["payments"]
+    },
+    "contextName": {
+      "type": "string",
+      "description": "What the context is called on the page. Defaults to the slug, titled."
+    },
+    "contextSummary": {
+      "type": "string",
+      "description": "A sentence or two on what the context is responsible for."
+    },
+    "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": ["ledger"]
+    },
+    "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 scm url in pom.xml.",
+      "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 port 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 contract vendored beside the adapter to the callee's service id: the proto package for a gRPC peer, the api id of the OpenAPI document (its x-portolan-api, or its title and major version) for an HTTP one. A package with no line here, and none under externals, is called as unknown and its steps stay unresolved.",
+      "examples": [{ "shop.v1": "shop.oms", "pricing.v1": "shop.pricing" }]
+    },
+    "externals": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which system outside the estate answers for what this one calls, as the api id of the document vendored beside the adapter to the external's id - the same bare name the openapi extractor is given under external. The calls land on the operations the copy declares and are declared, not unresolved; the lane says the far end is outside.",
+      "examples": [{ "stripe.v1": "stripe" }]
+    },
+    "events": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which aggregate another service's events belong to, as the package a listener reads them from to the aggregate id, so a policy reacting to a foreign event resolves.",
+      "examples": [{ "org.portolan.payments.ledger.infrastructure.oms.event": "shop.oms.order" }]
+    },
+    "source": {
+      "type": "string",
+      "description": "The directory the packages start in, relative to the input root.",
+      "default": "src/main/java"
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "domain.json"
+    }
+  }
+}

package/plugins/extract-openapi/describe.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	_ "embed"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+//go:embed options.schema.json
+var optionsSchema []byte
+
+func descriptor() plugin.Descriptor {
+	return plugin.Descriptor{
+		Name:    "extract-openapi",
+		Summary: "Reads an OpenAPI document and answers with the rpc services a service provides, one per tag - or, for a copy vendored from outside the estate, what a third party answers on.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}

package/plugins/extract-openapi/describe_test.go

@@ -0,0 +1,11 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/shortlink-org/portolan/plugin/schematest"
+)
+
+func TestOptionsSchemaMatchesStruct(t *testing.T) {
+	schematest.Check(t, optionsSchema, Options{})
+}