@shortlink-org/portolan 0.2.4 → 0.4.0

package/plugins/extract-php-ddd/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "portolan-extract-php-ddd"
+version = "0.1.0"
+edition = "2024"
+description = "A PHP service laid out by bounded context, module and hexagonal layer in, a catalog fragment out: the PHP twin of extract-go and extract-rust, on the same protocol."
+publish = false
+
+[lib]
+name = "portolan_extract_php_ddd"
+path = "src/lib.rs"
+
+[[bin]]
+name = "portolan-extract-php-ddd"
+path = "src/main.rs"
+
+[dependencies]
+# The PHP tree as syntax, shared with extract-laravel.
+phpscan = { path = "../phpscan" }
+# Doctrine mappings are XML; roxmltree reads them without a build step.
+roxmltree = "0.21"
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1", features = ["preserve_order"] }

package/plugins/extract-php-ddd/README.md

@@ -0,0 +1,141 @@
+# extract-php-ddd
+
+A PHP tree laid out by bounded context, module and hexagonal layer in, a
+catalog fragment out - three, when the route files prove an HTTP contract
+and the Doctrine mappings a database. The PHP twin of `extract-go`,
+`extract-ts` and `extract-rust`: like them, this reads a layout rather than
+a framework, and the layout is the claim. Nothing is annotated for the
+catalog; the directory a class sits in and the base it extends say what it
+is.
+
+The layout is the one [CodelyTV's php-ddd-example](https://github.com/CodelyTV/php-ddd-example)
+made common in PHP - `src/<Context>/<Module>/{Domain,Application,Infrastructure}`
+with the deployables under `apps/<context>/<app>` - and it is that project the
+site ships as a profile, read by this extractor alone.
+
+Written in Rust and run as a process plugin, `cargo run --quiet
+--manifest-path plugins/extract-php-ddd/Cargo.toml`, on the same reader as
+`extract-laravel`: `plugins/phpscan`, over [Mago](https://github.com/carthage-software/mago)'s
+`mago-syntax`. **The application is never run.** No container, no `composer
+install`: everything is read from syntax, names are resolved by namespace and
+`use` line, and a file that does not parse is read as far as it parsed and
+reported.
+
+## The layout it reads
+
+```
+src/<Context>/<Module>/Domain          the model: root, entities, value objects, events, ports
+src/<Context>/<Module>/Application     the use cases: commands, queries, their handlers, subscribers
+src/<Context>/<Module>/Infrastructure  the adapters: repositories, *.orm.xml Doctrine mappings
+src/Shared, src/<Context>/Shared       the shared kernel: bases, ids; not a context, not a module
+apps/<context>/<app>/config/routes/*.yaml   the HTTP edge of one deployable
+apps/<context>/<app>/config/services*.yaml  which contexts' code the deployable loads
+apps/<context>/<app>/src/Controller         what answers a route
+```
+
+`source` and `apps` in the options rename `src/` and `apps/`. `tests/`,
+`vendor/` and everything under an application but `src/` are not read.
+
+## What becomes what
+
+**Context.** A directory under `src/` other than `Shared`, with its slug as
+id. `classification` in the options applies to every context the tree
+declares; nothing in the tree says which is core.
+
+**Service.** Each application under `apps/<context>/` is a service of that
+context - `mooc.backend`, `backoffice.frontend` - with the route files it
+carries as its HTTP interfaces, one per file, `mooc.backend.courses`. The
+context's model is filed under its `backend` application, or its first one
+when it has none of that name. A context with no application at all gets a
+service named after itself, `analytics.analytics`, and a warning: the code
+is there, nothing deploys it.
+
+**Aggregate.** A module whose `Domain/` has a class extending
+`AggregateRoot`. The root's constructor parameters are its fields, typed as
+written, `id: CourseId`; a class extending the root is an entity of it, the
+joined subclasses of an abstract `Step`. A value object is a class that wraps
+one value - it extends a `*ValueObject` base or `Uuid`, or answers `value()` -
+with its fields read up the base chain, so `CourseName extends
+StringValueObject` has the parent's `value: string`. Exceptions, collections
+and domain services are not shape and are skipped. A module with no root but
+with use cases - `Auth`, with a command and no aggregate - is a `model-group`
+aggregate; one with neither is a warning and nothing else.
+
+**Event.** A class extending `DomainEvent`. Its wire name is what
+`eventName()` answers, `course.created`; its fields are the keys of
+`toPrimitives()`, typed by the constructor parameter of the same name; its
+doc the class docblock. The id is the class name with `DomainEvent` taken
+off, `mooc.backend.courses.CourseCreated`. Every event's `wire.channel` is the
+RabbitMQ exchange, `exchange` in the options, because the code reads it from
+the environment.
+
+**Operation.** A class implementing `CommandHandler` or `QueryHandler`; the
+`__invoke` parameter names the message and the operation is the message
+without its suffix, `create-course` for `CreateCourseCommand`. The doc is the
+handler's, or the use case's it holds (`CourseCreator`), or the message's.
+Its `fields` are the message's constructor parameters, typed as written -
+what the caller hands in, and an empty list for a query that takes nothing;
+its `source` is the handler's `__invoke`. `exposedBy` names the routes of
+the operation's own service that dispatch or ask it; a route in another
+application is a call across contexts and lives in the flow instead. A
+class named `*CommandHandler` that implements neither interface is reported:
+the bus never reaches it.
+
+**Subscriber.** A class implementing `DomainEventSubscriber`; `subscribedTo()`
+says which events, and `DomainEvent::class` there means every one. Each
+subscriber is a consumer on the events it names, a flow from the bus in, and
+a channel of its own: the RabbitMQ queue `RabbitMqQueueNameFormatter` would
+name for it, `codelytv.mooc.courses_counter.increment_courses_counter_on_course_created`.
+A subscriber in a context no application's `services.yaml` loads is reported:
+declared, wired nowhere.
+
+**Store.** The tables the `*.orm.xml` mappings under a context declare, as
+one `mysql` store per context (`storeKind` in the options), owned by the
+context's service: `<id>`, `<field>` and `<embedded>` become columns, the
+embeddable's own mapping supplying the column names; a `JOINED` subclass gets
+its own table keyed to the parent's. Each table `persists` the aggregate its
+entity is the root or an entity of, and its columns `map` to the entity's
+fields. A `*Repository` interface under `Domain/` is a port; the adapter
+implementing it says what answers it - `Doctrine*`/`MySql*` the database,
+`Elasticsearch*` an index, kept as a second store of kind `other` with one
+table per index shaped like the root it keeps; `InMemory*` and `File*`
+nothing, and a warning. Every `$this->repository->save(...)` on a port is an
+access on the port's table, `write CourseRepository.save`, whether or not a
+flow reaches it.
+
+**Flow.** One per route whose controller the tree has: the request in, what
+the controller `dispatch`es or `ask`s, then what the handler does, followed
+through the classes it holds by their constructor types - `$this->creator->__invoke(...)`,
+`Course::create(...)`, `apply($this->incrementer, [...])`, a call on a local
+variable tried against the module's root. On the way, `record(new Event)`
+and `publish(new Event)` are event steps to the bus and a call on a port a
+step to its store. When a controller dispatches a command whose handler lives
+in another context - the backoffice front end creating a Mooc course - the
+flow crosses to that context's service with a `call` step and a note: in
+process, over an in-memory bus, but a boundary all the same. One flow per
+subscriber does the same from the queue in.
+
+**HTTP.** One OpenAPI 3.1 document per application with routes,
+`openapi.<context>-<app>.yaml` (`openapiOut` in the options, `{service}`
+where the name goes), one operation per route and verb, the path's `{id}`
+as parameters and the controller's docblock as the summary; a route to a
+controller not in the tree is kept and reported.
+
+## Options
+
+See `options.schema.json`. `repo` defaults to composer.json's
+`support.source` or `homepage`; `exchange` to `domain_events`; `storeKind`
+to `mysql`; `classification` to nothing.
+
+## Tests
+
+```bash
+cargo test --manifest-path plugins/extract-php-ddd/Cargo.toml
+```
+
+`testdata/mooc` is a small tree in the layout: three contexts with
+applications and two without, a joined-subclass aggregate, an Elasticsearch
+read model, a subscriber to every event, and a front end dispatching another
+context's command. `expected.json`, `expected-stores.json` and the
+`openapi.*.yaml` beside it are what the extractor writes for it; the fixture
+tests explain the rules, the goldens catch what nobody asserted.

package/plugins/extract-php-ddd/options.schema.json

@@ -0,0 +1,50 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "source": {
+      "type": "string",
+      "description": "The directory the bounded contexts are in, relative to the input root: one directory per context, one per module under it, `Domain`, `Application` and `Infrastructure` under that. A `Shared` directory at either level is the shared kernel and is not a context or a module.",
+      "default": "src"
+    },
+    "apps": {
+      "type": "string",
+      "description": "The directory the deployable applications are in, relative to the input root: `<apps>/<context>/<app>`, each with `config/routes/*.yaml` and `src/Controller/`. Each application is a service of its context; a context with none gets one service named after itself.",
+      "default": "apps"
+    },
+    "repo": {
+      "type": "string",
+      "description": "Where the source lives. Defaults to composer.json's support.source or homepage when either names a repository.",
+      "examples": ["github.com/CodelyTV/php-ddd-example"]
+    },
+    "exchange": {
+      "type": "string",
+      "description": "The RabbitMQ exchange domain events are published to. The code reads it from the environment, so the manifest says.",
+      "default": "domain_events"
+    },
+    "storeKind": {
+      "enum": ["postgres", "mysql", "sqlite", "other"],
+      "description": "What the Doctrine-mapped tables live in.",
+      "default": "mysql"
+    },
+    "classification": {
+      "enum": ["core", "supporting", "generic"],
+      "description": "Whether the contexts are core to the business, support it, or are generic and could be bought. One value for every context the tree declares."
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "domain.json"
+    },
+    "openapiOut": {
+      "type": "string",
+      "description": "Name of the inferred OpenAPI 3.1 document, inside the step's output directory. Written when the route files expose HTTP operations.",
+      "default": "openapi.inferred.yaml"
+    },
+    "storesOut": {
+      "type": "string",
+      "description": "Name of the store fragment, inside the step's output directory. Written when a Doctrine mapping or a repository adapter names a store.",
+      "default": "stores.json"
+    }
+  }
+}

package/plugins/extract-php-ddd/rustfmt.toml

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

package/plugins/extract-python-kafka/extract.py

@@ -62,8 +62,6 @@ def extract(input_: Input, opts: Options, b: Builder, cwd: str = "") -> None:
     flows.sort(key=lambda flow: flow["slug"])
 
     fragment: Dict[str, Any] = {
-        "generatedAt": input_.generated_at,
-        "commit": input_.commit,
         "contexts": [
             {
                 "id": context,

package/plugins/extract-python-kafka/extract_test.py

@@ -23,7 +23,7 @@ class PythonKafka(unittest.TestCase):
         fixture = os.path.join(HERE, "testdata", "service")
         builder = Builder()
         extract(
-            Input(root=os.path.relpath(fixture, ROOT), commit="abc1234", generated_at="2026-09-08T00:00:00Z"),
+            Input(root=os.path.relpath(fixture, ROOT)),
             Options.of({"context": "shop", "service": "orders", "settings": "config.settings"}),
             builder,
             cwd=ROOT,

package/plugins/extract-python-kafka/main.py

@@ -18,6 +18,7 @@ HERE = os.path.dirname(os.path.abspath(__file__))
 DESCRIPTOR = {
     "name": "extract-python-kafka",
     "summary": "Reads confluent-kafka, kafka-python and aiokafka producers and consumers into message channels and source-backed flows.",
+    "category": "messaging",
     "phases": ["extract"],
 }
 

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

@@ -0,0 +1,26 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context the module deploys into. Defaults to the name of the input directory.",
+      "examples": ["shop"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service the module sits beside. Queues, topics and stores nothing in the module claims are listed on it, and it owns every store. A Lambda function whose name slugs to this becomes the service itself; any other becomes a component of kind function in the same context. Defaults to the name of the input directory.",
+      "examples": ["fulfillment"]
+    },
+    "dir": {
+      "type": "string",
+      "description": "Directory of *.tf files to read, relative to the input root. Left out, the root is read when it holds *.tf files, and otherwise the one directory under it that does - when there are several, the first by name, and the rest are named in a warning. Local modules (source = ./...) are followed from wherever they are called; registry modules are not read.",
+      "examples": ["deploy/terraform"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "terraform.json"
+    }
+  }
+}

package/plugins/extract-ts/extract.test.ts

@@ -8,7 +8,7 @@ const ROOT = "plugins/extract-ts/testdata/cart";
 const options = { context: "shop", service: "cart", store: "pg", peers: { "auth.v1": "auth.auth", "shop.v1": "shop.pricing" } };
 
 function run() {
-  return extract({ root: ROOT, commit: "abc1234", generatedAt: "2026-09-04T00:00:00Z" }, options);
+  return extract({ root: ROOT }, options);
 }
 
 function fragment() {
@@ -200,7 +200,7 @@ describe("the JavaScript twin", () => {
     );
 
   it("reads to the fragment the TypeScript tree reads to", () => {
-    const twin = extract({ root: JS, commit: "abc1234", generatedAt: "2026-09-04T00:00:00Z" }, options);
+    const twin = extract({ root: JS }, options);
     const golden = JSON.parse(readFileSync(`${ROOT}/expected.json`, "utf8"));
     expect(sameShape(JSON.parse(twin.files[0]!.contents))).toEqual(sameShape(golden));
     expect(twin.warnings.map((d) => d.ref)).toEqual(["getBasket"]);

package/plugins/extract-ts/extract.ts

@@ -5,6 +5,9 @@
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
 import type { Catalog, Service } from "../../src/catalog.ts";
+
+/** What an extractor writes: a catalog less the stamps, which are the history's to give (portolan.0010). */
+type Fragment = Omit<Catalog, "generatedAt" | "commit">;
 import { readAggregates, type WarningSink } from "./domain.ts";
 import { operationOf, readUseCases } from "./operations.ts";
 import { readBindings } from "./wiring.ts";
@@ -39,8 +42,6 @@ export interface Options {
 export interface Input {
   root: string;
   output?: string;
-  commit: string;
-  generatedAt: string;
 }
 
 export interface Warning {
@@ -151,9 +152,7 @@ export function extract(input: Input, opts: Options, cwd = process.cwd()): Respo
     for (const e of source.errors) b.warn(rel(source.path), `${rel(e.at)}: ${e.message}; the file is read only up to here`);
   }
 
-  const fragment: Catalog = {
-    generatedAt: input.generatedAt,
-    commit: input.commit,
+  const fragment: Fragment = {
     contexts: [
       {
         id: context,

package/plugins/extract-ts/graphql.test.ts

@@ -13,7 +13,7 @@ const ROOT = "plugins/extract-ts/testdata/storefront";
 const options = { context: "storefront", service: "bff", graphql: "src/schema", peers: { "auth.v1": "auth.auth" } };
 
 function run() {
-  return extract({ root: ROOT, commit: "abc1234", generatedAt: "2026-09-05T00:00:00Z" }, options);
+  return extract({ root: ROOT }, options);
 }
 
 function fragment() {

package/plugins/extract-ts/main.ts

@@ -11,6 +11,7 @@ const schema = JSON.parse(readFileSync(new URL("./options.schema.json", import.m
 export const descriptor = {
   name: "extract-ts",
   summary: "Reads a TypeScript service by its layout - aggregates, events, use cases, endpoints, policies, clients - into a catalog fragment.",
+  category: "code",
   phases: ["extract"],
   options: schema,
 };

package/plugins/openapi/ids.go

@@ -0,0 +1,261 @@
+// Package openapi is what two extractors agree on about an OpenAPI document:
+// how its interfaces are named in the catalog, and which operation answers on
+// which route. The server side reads the document to say what a service
+// provides; the client side reads the copy vendored beside a generated client
+// to say what a service calls. Both have to spell `auth.v1.Sessions/login` the
+// same way, or the call would never resolve to the method, and one place is
+// how they do.
+package openapi
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// APIID is the document's title and major version: `auth` 1.0.0 gives
+// `auth.v1`. It prefixes every interface the document declares.
+func APIID(title, version string) string {
+	name := title
+	if name == "" {
+		name = "api"
+	}
+	name = strings.ReplaceAll(strings.ToLower(name), " ", "-")
+
+	if major, _, ok := strings.Cut(version, "."); ok && major != "" {
+		return name + ".v" + major
+	}
+
+	return name
+}
+
+// DocumentAPIID is the id a document says it goes by in the estate, or the one
+// built from its title and version when it says nothing.
+//
+// `x-portolan-api` in `info` is for a copy vendored from outside the estate:
+// Stripe's document is titled "Stripe API" and versioned "2026-08-26.dahlia",
+// and `stripe-api.v2026-08-26` on every arrow would be the document's words
+// where the estate wants its own. The copy is the consumer's translation
+// boundary already, so it is the one place the estate's name may be written,
+// and both sides of a call read it from there rather than from two manifests.
+func DocumentAPIID(declared, title, version string) string {
+	if declared = strings.TrimSpace(declared); declared != "" {
+		return declared
+	}
+
+	return APIID(title, version)
+}
+
+// ExternalID is the id a system outside the estate goes by when nothing but
+// its own document names it: the document's title as a slug, with a trailing
+// "API" dropped because the system is the thing, not its interface. "Gordian
+// Flights & Ancillaries API" is gordian-flights-ancillaries; "Stripe API" is
+// stripe. Both sides of a call - the extractor that reads the vendored copy
+// for what the system answers on, and the one that reads the client beside it
+// for what this service calls - derive it here, so neither needs the manifest
+// to say it.
+func ExternalID(title string) string {
+	var b strings.Builder
+	dash := false
+	for _, r := range strings.ToLower(strings.TrimSpace(title)) {
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
+			b.WriteRune(r)
+			dash = false
+		case !dash && b.Len() > 0:
+			b.WriteByte('-')
+			dash = true
+		}
+	}
+	id := strings.TrimRight(b.String(), "-")
+	if trimmed := strings.TrimSuffix(id, "-api"); trimmed != "" {
+		id = trimmed
+	}
+
+	return id
+}
+
+// Title is the human form of a tag: users becomes Users, price_list becomes
+// PriceList, because it sits in an id beside a proto-shaped service name.
+func Title(name string) string {
+	var b strings.Builder
+	for _, word := range strings.FieldsFunc(name, func(r rune) bool { return r == '_' || r == '-' || r == ' ' }) {
+		runes := []rune(word)
+		if runes[0] >= 'a' && runes[0] <= 'z' {
+			runes[0] = runes[0] - 'a' + 'A'
+		}
+		b.WriteString(string(runes))
+	}
+
+	return b.String()
+}
+
+// InterfaceID is the contract declared by the OpenAPI document. Tags organise
+// operations inside that contract; they do not create separate interfaces.
+func InterfaceID(api, _ string) string { return api }
+
+// Verbs, in the order the paths object lists them by convention.
+var Verbs = []string{"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+
+// Operation is one route of the document and the name it goes by.
+type Operation struct {
+	// ID is the operationId, or `VERB /path` when the document has none.
+	ID string
+	// Tag is the first tag, retained as document metadata. It does not change
+	// the identity of the contract.
+	Tag string
+	// Verb is upper case: POST.
+	Verb string
+	// Path is the template as written: /v1/users/{userId}.
+	Path string
+}
+
+// Interface is the id of the interface the operation belongs to.
+func (o Operation) Interface(api string) string { return InterfaceID(api, o.Tag) }
+
+// CallID is what a call to this operation is known by in the catalog.
+func (o Operation) CallID(api string) string { return o.Interface(api) + "/" + o.ID }
+
+// Spec is the part of a document these extractors read.
+type Spec struct {
+	API        string
+	Operations []Operation
+
+	// Title, Description and DocsURL are what the document says about the
+	// system it describes, for naming that system when the manifest does not.
+	Title       string
+	Description string
+	DocsURL     string
+}
+
+// Read loads a document and lists its operations. The api id may be
+// overridden by whoever calls, since the manifest may name one.
+func Read(path string) (*Spec, error) {
+	contents, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var root yaml.Node
+	if err := yaml.Unmarshal(contents, &root); err != nil {
+		return nil, fmt.Errorf("%s: %w", path, err)
+	}
+	node := &root
+	if node.Kind == yaml.DocumentNode && len(node.Content) > 0 {
+		node = node.Content[0]
+	}
+
+	info := child(node, "info")
+	spec := &Spec{
+		API:         DocumentAPIID(text(child(info, "x-portolan-api")), text(child(info, "title")), text(child(info, "version"))),
+		Title:       text(child(info, "title")),
+		Description: text(child(info, "description")),
+		DocsURL:     text(child(node, "externalDocs", "url")),
+	}
+	for _, p := range entries(child(node, "paths")) {
+		for _, verb := range Verbs {
+			operation := child(p.value, verb)
+			if operation == nil {
+				continue
+			}
+			id := text(child(operation, "operationId"))
+			if id == "" {
+				id = strings.ToUpper(verb) + " " + p.key
+			}
+			tags := list(child(operation, "tags"))
+			tag := ""
+			if len(tags) > 0 {
+				tag = tags[0]
+			}
+			spec.Operations = append(spec.Operations, Operation{ID: id, Tag: tag, Verb: strings.ToUpper(verb), Path: p.key})
+		}
+	}
+
+	return spec, nil
+}
+
+// Find looks up an operation by verb and route. Both sides may spell a path
+// parameter differently - `{userId}` in the document, `%s` in a generated
+// client - so parameters are compared by position, not by name.
+func (s *Spec) Find(verb, path string) (Operation, bool) {
+	want := strings.ToUpper(verb) + " " + shape(path)
+	for _, op := range s.Operations {
+		if op.Verb+" "+shape(op.Path) == want {
+			return op, true
+		}
+	}
+
+	return Operation{}, false
+}
+
+// shape replaces every parameter, however spelled, with one marker.
+func shape(path string) string {
+	var b strings.Builder
+	for _, segment := range strings.Split(strings.TrimSuffix(path, "/"), "/") {
+		if strings.HasPrefix(segment, "{") || segment == "%s" || segment == "%v" || segment == "%d" {
+			b.WriteString("/*")
+
+			continue
+		}
+		b.WriteString("/" + segment)
+	}
+
+	return b.String()
+}
+
+type entry struct {
+	key   string
+	value *yaml.Node
+}
+
+func entries(node *yaml.Node) []entry {
+	if node == nil || node.Kind != yaml.MappingNode {
+		return nil
+	}
+	var out []entry
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		out = append(out, entry{key: node.Content[i].Value, value: node.Content[i+1]})
+	}
+
+	return out
+}
+
+func child(node *yaml.Node, keys ...string) *yaml.Node {
+	for _, key := range keys {
+		if node == nil || node.Kind != yaml.MappingNode {
+			return nil
+		}
+		var next *yaml.Node
+		for i := 0; i+1 < len(node.Content); i += 2 {
+			if node.Content[i].Value == key {
+				next = node.Content[i+1]
+
+				break
+			}
+		}
+		node = next
+	}
+
+	return node
+}
+
+func text(node *yaml.Node) string {
+	if node == nil || node.Kind != yaml.ScalarNode {
+		return ""
+	}
+
+	return strings.TrimSpace(node.Value)
+}
+
+func list(node *yaml.Node) []string {
+	if node == nil || node.Kind != yaml.SequenceNode {
+		return nil
+	}
+	var out []string
+	for _, item := range node.Content {
+		out = append(out, text(item))
+	}
+
+	return out
+}