@shortlink-org/portolan 0.2.4 → 0.4.0

package/plugins/phpscan/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "phpscan"
+version = "0.1.0"
+edition = "2024"
+description = "A PHP tree as syntax, for every PHP extractor: files parsed once with Mago, classes and the call chains their code makes, names resolved by namespace and use line."
+publish = false
+
+[lib]
+path = "src/lib.rs"
+
+[dependencies]
+# Mago is the PHP toolchain written in Rust; its syntax crate is the one
+# maintained PHP parser in this language that keeps up with the language, and
+# the arena it parses into is dropped once a file has been read into the
+# extractor's own shapes.
+mago-syntax = "1.48.1"
+mago-database = "1.48.1"
+mago-allocator = "1.48.1"
+mago-span = "1.48.1"

package/plugins/phpscan/rustfmt.toml

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

package/plugins/pyplugin/catalog.py

@@ -13,10 +13,33 @@ DECLARED = "declared"
 UNRESOLVED = "unresolved"
 
 
-def field(name: str, type_: str, doc: str = "", ref: str = "") -> Dict[str, Any]:
+def field(
+    name: str,
+    type_: str,
+    doc: str = "",
+    ref: str = "",
+    required: bool = False,
+    rules: Optional[List[Dict[str, str]]] = None,
+) -> Dict[str, Any]:
+    """A field. `required` is written only when true and `rules` only when
+    there are any: a source that says nothing about a value leaves nothing."""
     out = {"name": name, "type": type_, "doc": doc}
     if ref:
         out["ref"] = ref
+    if required:
+        out["required"] = True
+    if rules:
+        out["rules"] = rules
+    return out
+
+
+def rule(name: str, value: str = "") -> Dict[str, str]:
+    """One rule on a value, in the catalog's vocabulary (portolan.0015):
+    `min_len`, `pattern`, `in`, `format`, `gte`... The value is text, as the
+    source wrote it; a bare flag such as `unique` has none."""
+    out = {"name": name}
+    if value:
+        out["value"] = value
     return out
 
 

package/plugins/pyplugin/protocol.py

@@ -17,12 +17,10 @@ from typing import Any, Dict, List
 
 @dataclass
 class Input:
-    """Where the source is, and the stamp the host put on this run."""
+    """Where the source is."""
 
     root: str = ""
     output: str = ""
-    commit: str = ""
-    generated_at: str = ""
 
     @staticmethod
     def of(raw: Any) -> "Input":
@@ -30,8 +28,6 @@ class Input:
         return Input(
             root=raw.get("root", ""),
             output=raw.get("output", ""),
-            commit=raw.get("commit", ""),
-            generated_at=raw.get("generatedAt", ""),
         )
 
 

package/plugins/verify-otel/options.schema.json

@@ -22,6 +22,18 @@
       "description": "Which catalog event a wire name belongs to, for an estate where the event does not declare its wire name and the last segment of the event.name attribute is not the event's name in the model.",
       "examples": [{ "auth.PasswordChanged": "auth.auth.PasswordChanged" }]
     },
+    "routes": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which operation a route a server span answers on belongs to - the verb and the http.route, to the operation's name in the service's interface - for an estate where the two do not line up: a prefix a gateway adds, a path the document spells another way. Without a line here a route is matched by verb and path shape.",
+      "examples": [{ "POST /api/v1/sessions": "login" }]
+    },
+    "examples": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "How many recordings a flow keeps as examples of itself running: the ones that show the most of it, earliest first. Five when unset; zero keeps none.",
+      "examples": [3]
+    },
     "out": {
       "type": "string",
       "description": "Name of the fragment file, inside the step's output directory."

package/portolan.json

@@ -19,10 +19,32 @@
         "examples/*/*/portolan/*.json",
         "examples/*/*/*/portolan/*.json",
         "vendor/repos/*/*/git.repo.json",
-        "vendor/repos/**/portolan/*.json"
+        "vendor/repos/**/portolan/*.json",
+        "examples/argocd/argocd.apps.json"
       ],
       "contexts": ["auth", "shop", "delivery", "payments", "storefront"],
       "projects": ["auth", "shop-cart", "shop-billing", "shop-pricing", "delivery-core", "payments-ledger", "shop-oms"]
+    },
+    {
+      "id": "bagisto",
+      "title": "Bagisto",
+      "sources": ["vendor/repos/bagisto/bagisto/git.repo.json", "vendor/repos/bagisto/bagisto/catalog/*.json"],
+      "contexts": ["commerce"],
+      "projects": []
+    },
+    {
+      "id": "codely",
+      "title": "CodelyTV php-ddd-example",
+      "sources": ["vendor/repos/CodelyTV/php-ddd-example/git.repo.json", "vendor/repos/CodelyTV/php-ddd-example/catalog/*.json"],
+      "contexts": ["mooc", "backoffice", "analytics", "retention"],
+      "projects": []
+    },
+    {
+      "id": "modular-monolith",
+      "title": "Modular Monolith with DDD",
+      "sources": ["vendor/repos/kgrzybek/modular-monolith-with-ddd/git.repo.json", "vendor/repos/kgrzybek/modular-monolith-with-ddd/catalog/*.json"],
+      "contexts": ["administration", "meetings", "payments", "registrations", "user-access"],
+      "projects": []
     }
   ],
   "projects": [
@@ -90,7 +112,8 @@
     "examples/*/*/portolan/*.json",
     "examples/*/*/*/portolan/*.json",
     "vendor/repos/*/*/git.repo.json",
-    "vendor/repos/**/portolan/*.json"
+    "vendor/repos/**/portolan/*.json",
+    "examples/argocd/argocd.apps.json"
   ],
   "plugins": [
     {
@@ -125,6 +148,27 @@
         "args": ["run", "--quiet", "--manifest-path", "plugins/extract-rust/Cargo.toml"]
       }
     },
+    {
+      "name": "laravel-domain",
+      "process": {
+        "command": "cargo",
+        "args": ["run", "--quiet", "--manifest-path", "plugins/extract-laravel/Cargo.toml"]
+      }
+    },
+    {
+      "name": "php-ddd",
+      "process": {
+        "command": "cargo",
+        "args": ["run", "--quiet", "--manifest-path", "plugins/extract-php-ddd/Cargo.toml"]
+      }
+    },
+    {
+      "name": "csharp-ddd",
+      "process": {
+        "command": "dotnet",
+        "args": ["plugins/extract-csharp-ddd/bin/portolan-extract-csharp-ddd.dll"]
+      }
+    },
     {
       "name": "java-domain",
       "process": {
@@ -167,8 +211,9 @@
     },
     {
       "name": "http-clients",
-      "wasm": {
-        "url": "file://plugins/portolan-go.wasm"
+      "process": {
+        "command": "go",
+        "args": ["run", "-mod=mod", "./plugins/cmd/portolan-http-clients"]
       }
     },
     {
@@ -195,6 +240,30 @@
         "url": "file://plugins/portolan-go.wasm"
       }
     },
+    {
+      "name": "go-sqs",
+      "wasm": {
+        "url": "file://plugins/portolan-go.wasm"
+      }
+    },
+    {
+      "name": "terraform",
+      "wasm": {
+        "url": "file://plugins/portolan-go.wasm"
+      }
+    },
+    {
+      "name": "k8s",
+      "wasm": {
+        "url": "file://plugins/portolan-go.wasm"
+      }
+    },
+    {
+      "name": "argocd-gitops",
+      "wasm": {
+        "url": "file://plugins/portolan-go.wasm"
+      }
+    },
     {
       "name": "asyncapi",
       "wasm": {
@@ -273,6 +342,14 @@
       "name": "csr",
       "host": "fetch-csr"
     },
+    {
+      "name": "k8s-cluster",
+      "host": "fetch-k8s"
+    },
+    {
+      "name": "argocd",
+      "host": "fetch-argocd"
+    },
     {
       "name": "csr-schemas",
       "wasm": {
@@ -444,6 +521,17 @@
         "out": "commands.json"
       }
     },
+    {
+      "plugin": "k8s",
+      "in": "examples/shop/cart",
+      "out": "examples/shop/cart/portolan",
+      "options": {
+        "context": "shop",
+        "service": "cart",
+        "paths": ["deploy/k8s"],
+        "out": "k8s.json"
+      }
+    },
     {
       "plugin": "ts-domain",
       "in": "examples/shop/cart",
@@ -615,6 +703,17 @@
         "out": "commands.json"
       }
     },
+    {
+      "plugin": "k8s",
+      "in": "examples/shop/pricing",
+      "out": "examples/shop/pricing/portolan",
+      "options": {
+        "context": "shop",
+        "service": "pricing",
+        "paths": ["deploy/k8s"],
+        "out": "k8s.json"
+      }
+    },
     {
       "plugin": "go-nats",
       "in": "examples/shop/pricing",
@@ -813,6 +912,26 @@
         ]
       }
     },
+    {
+      "plugin": "argocd-gitops",
+      "in": "examples/gitops",
+      "out": "examples/gitops/portolan",
+      "options": {
+        "repo": "github.com/shortlink-org/portolan",
+        "paths": ["bootstrap", "appsets"],
+        "out": "argocd.json"
+      }
+    },
+    {
+      "plugin": "argocd",
+      "in": "examples",
+      "out": "examples/argocd",
+      "options": {
+        "server": "argocd.example.com",
+        "projects": ["shop", "platform"],
+        "cache": "examples/argocd"
+      }
+    },
     {
       "plugin": "proto",
       "in": "examples/shop/oms",
@@ -956,6 +1075,15 @@
         "context": "storefront",
         "out": "glossary.json"
       }
+    },
+    {
+      "plugin": "k8s-cluster",
+      "in": ".",
+      "out": "data",
+      "options": {
+        "cache": "data",
+        "out": "k8s-cluster.json"
+      }
     }
   ],
   "verify": [

package/rules/builtin.json

@@ -0,0 +1,218 @@
+[
+  {
+    "id": "rpc",
+    "over": "call",
+    "severity": "error",
+    "title": "Call resolves to nothing",
+    "note": "the provider of this call is not in the catalog",
+    "description": "A service calls a method, by interface and name, and no service in the catalog declares that interface. The chart draws an arrow into open water.",
+    "action": "Add the provider's contract to the catalog, or map the peer under externals, then regenerate.",
+    "when": "!call.resolved",
+    "message": "call.note",
+    "peer": "call.peer"
+  },
+  {
+    "id": "consumer",
+    "over": "consumer",
+    "severity": "error",
+    "title": "Consumer is not in the catalog",
+    "note": "this consumer of the event is not in the catalog",
+    "description": "An event names a consuming service that no source in the catalog declares. Either the consumer's repository has not been read, or the name is spelled differently on the two sides.",
+    "action": "Point an extractor at the consuming service, or correct the consumer's name where the event declares it.",
+    "when": "!consumer.resolved",
+    "message": "consumer.note",
+    "peer": "consumer.consumer"
+  },
+  {
+    "id": "cross-service-fk",
+    "over": "column",
+    "severity": "error",
+    "title": "Foreign key across a service boundary",
+    "note": "foreign key across a service boundary",
+    "description": "A column references a table another service owns. The database enforces a relation the services' contracts do not know about, and one migration can break the other service.",
+    "action": "Carry the reference as a plain id and resolve it through the owning service's contract, or move the two tables under one owner.",
+    "when": "column.fkOwner != '' && column.fkOwner != column.owner",
+    "message": "column.owner + ' holds a foreign key into a table owned by ' + column.fkOwner + '; neither service can migrate that table alone.'",
+    "peer": "column.fk"
+  },
+  {
+    "id": "cross-service-lineage",
+    "over": "column",
+    "severity": "warning",
+    "title": "Value copied from another service's schema",
+    "note": "a value copied from another service's schema",
+    "description": "A column is computed from a column in a store another service owns. The copy follows the source's schema without a contract saying so, and nothing on the other side records that the copy exists.",
+    "action": "Feed the projection from the owning service's events, or document the read as an accepted coupling.",
+    "when": "size(column.foreignFrom) > 0",
+    "message": "column.owner + ' copies this value from ' + column.foreignFrom.join(', ') + ', which ' + column.foreignOwners.join(', ') + ' owns; nothing on that side records that the copy exists.'",
+    "peer": "column.foreignFrom[0]"
+  },
+  {
+    "id": "cross-service-view",
+    "over": "table",
+    "severity": "warning",
+    "title": "View defined over another service's relation",
+    "note": "a view over another service's table",
+    "description": "A view reads a table or view in a store another service owns. A rename over there breaks this view with no error until it is read.",
+    "action": "Build the view over a local projection fed by the owner's events, or document the read as an accepted coupling.",
+    "when": "table.kind == 'view' && size(table.foreignReads) > 0",
+    "message": "table.id + ' is defined over ' + table.foreignReads.join(', ') + ', which another service owns; a rename over there breaks this view with no error until it is read.'",
+    "peer": "table.foreignReads[0]"
+  },
+  {
+    "id": "shared-store",
+    "over": "table",
+    "severity": "error",
+    "title": "Second writer on a database",
+    "note": "a second service writes this database",
+    "description": "A table in one service's store holds an aggregate another service writes. Two services now share one schema, and neither can change it alone. A projection is a copy maintained from the owner's events and is not this.",
+    "action": "Move the write behind the owner's API or events, or give the table to the service that writes it.",
+    "when": "table.kind == 'table' && table.role != 'projection' && table.aggregateOwner != '' && table.aggregateOwner != table.owner",
+    "message": "table.store + ' is owned by ' + table.owner + ', but this table holds ' + table.aggregate + ', which ' + table.aggregateOwner + ' writes.'",
+    "peer": "table.aggregateOwner"
+  },
+  {
+    "id": "persistence-drift",
+    "over": "table",
+    "severity": "warning",
+    "title": "Table no longer holds the aggregate it claims",
+    "note": "this table no longer carries the aggregate it claims",
+    "description": "A table says it persists an aggregate, and no column of it maps to a field the aggregate declares any more. The table was relabelled and the columns were not, or the aggregate moved on without it.",
+    "action": "Point the table at the aggregate that replaced it, map its columns again, or drop the persists claim.",
+    "when": "table.kind == 'table' && table.role != 'projection' && table.role != 'outbox' && table.aggregate != '' && table.aggregateFields > 0 && table.mappedColumns == 0",
+    "message": "table.claimedColumns == 0 ? 'no column of ' + table.name + ' maps to a field of ' + table.aggregate : string(table.claimedColumns) + ' column(s) of ' + table.name + ' map to fields ' + table.aggregate + ' no longer declares'",
+    "peer": "table.aggregate"
+  },
+  {
+    "id": "column-type",
+    "over": "column",
+    "severity": "warning",
+    "title": "Column type and domain type disagree",
+    "note": "column type and domain type disagree",
+    "description": "A column is mapped to a domain field, and the database type is not one the field's type is stored as. One side has changed without the other.",
+    "action": "Align the migration with the field's type, or correct the mapping if the column holds something else.",
+    "when": "column.kind == 'table' && column.maps != '' && column.fieldType != '' && !column.typeMatches",
+    "message": "'column is ' + column.type + ', ' + column.maps + ' is ' + column.fieldType",
+    "peer": "column.maps"
+  },
+  {
+    "id": "outbox-payload",
+    "over": "table",
+    "severity": "warning",
+    "title": "Outbox without a payload column",
+    "note": "an outbox with no payload column",
+    "description": "A table plays the outbox role and has no json column that could carry a message body. The whole point of the pattern is that the event body is committed with the state change, so this is either not an outbox or not finished.",
+    "action": "Add a payload column to the outbox table, or clear its role if it is not an outbox.",
+    "when": "table.role == 'outbox' && !table.hasPayload",
+    "message": "'an outbox carries the event body in the same transaction as the state change; this table declares no json column to hold one'",
+    "peer": "table.store"
+  },
+  {
+    "id": "proto-missing",
+    "over": "call",
+    "severity": "error",
+    "title": "Provider answers on no such method",
+    "note": "the provider is in the catalog but answers on no such method",
+    "description": "A call names a service the catalog knows and a method that service's interfaces do not declare. The caller's vendored copy is ahead of, or behind, the provider, and the call will fail.",
+    "action": "Regenerate the caller's vendored proto from the provider's module, or add the method on the provider.",
+    "when": "call.resolved && call.peerKnown && !call.methodDeclared",
+    "message": "call.note",
+    "peer": "call.peer"
+  },
+  {
+    "id": "proto-drift",
+    "over": "copy",
+    "severity": "warning",
+    "title": "Vendored proto and provider schema disagree",
+    "note": "the vendored proto and provider schema disagree",
+    "description": "The copy of an interface a caller compiled against differs from the interface the provider publishes: a message, a field or an enum value is not the same on both sides.",
+    "action": "Pin the caller to the provider's published module version and regenerate the copy.",
+    "when": "copy.provider != '' && size(copy.differences) > 0",
+    "message": "'Vendored copy differs from ' + copy.provider + ': ' + copy.differences.join('; ') + '.'",
+    "peer": "copy.provider"
+  },
+  {
+    "id": "shared-channel",
+    "over": "channel",
+    "severity": "error",
+    "title": "Second publisher on a channel",
+    "note": "a second service publishes on this channel",
+    "description": "Two services publish on one channel, by an event that names it or a document that declares a send on it. A subscriber dispatches on the event's name and cannot tell whose message arrived, until one it cannot parse does.",
+    "action": "Give each publisher its own channel, named after the aggregate whose events travel on it.",
+    "when": "channel.publishes && size(channel.otherPublishers) > 0",
+    "message": "channel.service + ' publishes on ' + channel.address + ', and so does ' + channel.otherPublishers.join(', ') + ': ' + channel.otherClaims.join('; ') + '. A subscriber reads both without being told.'",
+    "peer": "channel.otherPublishers[0]"
+  },
+  {
+    "id": "channel-undeclared",
+    "over": "event",
+    "severity": "warning",
+    "title": "Event leaves on an undeclared channel",
+    "note": "this event goes out on a channel the service does not declare",
+    "description": "The code publishes an event on a channel the service's AsyncAPI document does not list among its sends. The document is behind the code. A service whose document declares no sends says nothing here.",
+    "action": "Declare the channel and its messages in the service's AsyncAPI document.",
+    "when": "event.channel != '' && size(event.declaredChannels) > 0 && !(event.channel in event.declaredChannels)",
+    "message": "event.name + ' goes out on ' + event.channel + ', which ' + event.service + ' does not declare it sends on. A subscriber reading the document does not know this message exists.'",
+    "peer": "event.channel"
+  },
+  {
+    "id": "channel-unpublished",
+    "over": "channel",
+    "severity": "warning",
+    "title": "Declared channel nothing publishes on",
+    "note": "a declared channel no event of this service names",
+    "description": "The service's document declares it sends domain events on a channel, and no event of the service names that channel as its wire. The code is behind the document, or the channel is dead.",
+    "action": "Remove the channel from the document, or wire the event that should leave on it.",
+    "when": "channel.declared && channel.kind == 'event' && size(channel.sends) > 0 && size(channel.events) == 0",
+    "message": "channel.service + ' declares it sends on ' + channel.address + ', and no event of it names that channel: ' + channel.sends.join(', ') + '.'",
+    "peer": "channel.address"
+  },
+  {
+    "id": "message-encoding",
+    "over": "subscription",
+    "severity": "error",
+    "title": "Publisher and subscriber encode differently",
+    "note": "publisher and subscriber use different payload encodings",
+    "description": "Both sides of a message have named a payload encoding, and the two names differ. The subscriber will not read what the publisher writes.",
+    "action": "Agree one encoding in both AsyncAPI documents.",
+    "when": "subscription.encoding != '' && size(subscription.mismatched) > 0",
+    "message": "subscription.service + ' expects ' + subscription.name + ' on ' + subscription.channel + ' as ' + subscription.encoding + ', but ' + subscription.mismatched[0] + ' sends it as ' + subscription.mismatchedEncodings[0] + '.'",
+    "peer": "subscription.mismatched[0]"
+  },
+  {
+    "id": "subscription-unresolved",
+    "over": "subscription",
+    "severity": "warning",
+    "title": "Subscription nothing publishes",
+    "note": "nothing in the catalog publishes what this service listens for",
+    "description": "A service declares it receives a message, and no event of the estate goes by that name on the wire and no document declares a send of it. The publisher is outside the estate, or the name has drifted.",
+    "action": "Read the publisher's repository into the catalog, or remove the subscription.",
+    "when": "!subscription.published",
+    "message": "subscription.service + ' listens on ' + subscription.channel + ' for ' + subscription.name + ', and nothing in the catalog publishes it. Either the publisher is outside the estate, or the name has drifted.'",
+    "peer": "subscription.name"
+  },
+  {
+    "id": "deployment-unclaimed",
+    "over": "deployment",
+    "severity": "warning",
+    "title": "Deployed from nowhere the catalog knows",
+    "note": "the deployer runs this from a repository and directory no service in the catalog lives at",
+    "description": "The deployer runs an Application from a repository and path, or with labels, that match no service. It is a service nobody has read yet, a path spelled differently, or infrastructure that is not a service at all.",
+    "action": "Read the service into the catalog, align its path with where its manifests live, or switch this rule off for infrastructure with a reason.",
+    "when": "!deployment.claimed",
+    "message": "deployment.name + ' runs in ' + deployment.runsIn + (deployment.namespace != '' ? ', namespace ' + deployment.namespace : '') + '; ' + (deployment.labelled != '' ? 'its labels name ' + deployment.labelled + ', which is no service of the estate' : 'if it is a service of the estate, its `path` should be a directory the Application\\'s path is under, or the Application should carry app.kubernetes.io/part-of and app.kubernetes.io/name') + '. ' + deployment.url",
+    "peer": "deployment.from"
+  },
+  {
+    "id": "deployment-drift",
+    "over": "deployment",
+    "severity": "warning",
+    "title": "GitOps tree and deployer disagree",
+    "note": "the GitOps tree and the deployer disagree about this Application",
+    "description": "What the GitOps tree says should run and what the deployer reports is running differ on a project, cluster, namespace, path, revision or image.",
+    "action": "Sync the Application, or commit to the tree what was changed on the cluster.",
+    "when": "deployment.drifted",
+    "message": "deployment.drift + '. ' + deployment.url",
+    "peer": "deployment.environment"
+  }
+]