@shortlink-org/portolan 0.3.0 → 0.4.0

package/plugins/README.md

@@ -18,7 +18,7 @@ the plugin itself rather than its work:
 → { "portolanVersion": "0.1.0", "kind": "describe" }
 ← { "files": [],
     "describe": { "name": "extract-go", "summary": "...",
-                  "phases": ["extract"],
+                  "category": "code", "phases": ["extract"],
                   "options": { "type": "object", "additionalProperties": false,
                                "properties": { "context": { ... } } } } }
 ```
@@ -31,6 +31,16 @@ is what makes that worth having: `encoding/json` drops a field it does not
 recognise, so before this a misspelled option was no option at all and nothing
 said so.
 
+`category` is what the plugin reads or makes, one of `code`, `contracts`,
+`messaging`, `data`, `infrastructure`, `repository`, `documents`, `evidence`,
+`sources` and `exports` (the constants in `plugin/describe.go`). A phase says
+where in a run a plugin goes; the category says what kind of fact it is after,
+which is how the site's `/plugins` page groups it. `npm run schema` also writes
+`src/lib/plugin-index.json` - every declared plugin as it describes itself,
+with how the manifest runs it - and that page and the landing page's list of
+inputs are rendered from it, so a plugin added to `portolan.json` appears on
+both without being written down twice.
+
 A descriptor may also carry `needs`: what the host must put in the request
 beyond the tree, because a sandboxed module cannot reach it. The one need so
 far is `history` (portolan.0007) - when each file under the root was first
@@ -154,7 +164,14 @@ a value's name is the constant's literal, because that is what the wire
 carries, and the constant's own name only for an iota. A `Deprecated:`
 paragraph in the doc marks the value. In Rust it is a `pub enum` whose every
 variant is a bare name, the literal an `as_str` answers standing in for the
-variant. In Java it is a top-level enum in the aggregate's package. In proto,
+variant. In Java it is a top-level enum in the aggregate's package. In PHP it
+is a backed `enum` anywhere in the module, and on an Eloquent model the
+constants that share a prefix - `STATUS_PENDING = 'pending'` beside
+`STATUS_CLOSED = 'closed'` - with `@deprecated` in a constant's docblock
+marking the value; see `extract-laravel/README.md`. In a PHP tree laid out
+by bounded context (`extract-php-ddd`) it is a backed `enum` under a module's
+`Domain/`. In a .NET modular monolith (`extract-csharp-ddd`) it is a C# `enum`
+in the aggregate's directory, `[Obsolete]` marking a value. In proto,
 the enums the messages reach through their fields sit on the interface as
 `enums`, with the numbers the wire uses.
 
@@ -248,6 +265,61 @@ channel's doc. A subject read off a database row is a warning at the call,
 not a channel. Consumer configs give the filter subject and the durable name;
 streams, wildcard subjects and work-queue retention are not read yet.
 
+`extract-go-sqs` is its twin for Amazon SQS through aws-sdk-go-v2. A call is
+known by being made on `*sqs.Client` - `SendMessage`, `SendMessageBatch`,
+`ReceiveMessage` - and the queue is the `QueueUrl` of the input struct,
+written inline or built into a local first. `aws.String` and `aws.ToString`
+are taken off, and the `QueueUrl` of a `GetQueueUrl` result is read as the
+`QueueName` that was asked for. The queue is then followed like a subject: to
+a literal, a constant, a config default, or a parameter up to two hops through
+the callers, and when it sits in a field of the receiver, to the constructor
+that filled the field and on to that constructor's callers - the worker's
+shape, where the queue comes in at `New` and is read at `Run`. A URL becomes
+the queue's name, its last path segment. Channels are `message` streams, not
+domain events: a queue is point to point, and the event model is not asked to
+match it. A port that takes exactly one other string beside the queue names
+the message; a direct call names none. `DeleteMessage`, visibility changes and
+`CreateQueue` say nothing about direction and are not read; SNS is not read.
+
+`extract-terraform` reads the other half: the infrastructure the code runs
+on, from the `*.tf` files of the directory given as `dir` - or the root, or
+the one directory under it that holds any. Nothing is evaluated; the files
+are read as syntax with `hashicorp/hcl`, and a name is followed the way a
+subject is - to a literal, a variable's default, a local, the argument a
+calling `module` block passed in, or a child module's output - and left out
+with a warning when none of those reaches it, never taken from the label.
+Local modules (`source = "./..."`) are read where they are called. A registry
+module the reader knows - `terraform-aws-modules/lambda`, `sqs`, `sns`,
+`s3-bucket` with its `notification` submodule, `dynamodb-table`, whether
+named through the registry or as the git repository behind it with a ref -
+is read as the resource it wraps: its inputs are that resource's attributes
+under the module's names (`environment_variables`, `attributes = [...]`,
+`event_source_mapping = {...}`, `subscriptions = {...}`, `create_dlq`), and
+its outputs (`lambda_function_arn`, `queue_arn` or `sqs_queue_arn`,
+`dead_letter_queue_arn`, `dynamodb_table_stream_arn`) are references to it,
+so `module.queue` reads as `aws_sqs_queue` would; the dead-letter queue the
+queue module makes beside itself is `module.queue.dlq`, and a layer the
+lambda module makes is not a function. Any other registry module is noted
+and skipped. A reference from one resource to another
+(`aws_sqs_queue.orders.arn`) is the edge itself and needs no value. What
+comes out: an `aws_sqs_queue` is a `message` channel and an `aws_sns_topic`
+an `event` channel, each with `messages: []` and the facts in the doc - FIFO,
+the dead-letter queue and its receive count from `redrive_policy`, the SNS
+subscription that fills a queue, the S3 notification that fills either; an
+`aws_lambda_function` is a component of kind `function` in the same context,
+its runtime among its technologies - or the service itself when its name
+slugs to the `service` option; an `aws_lambda_event_source_mapping` puts the
+queue on the function as received, and a topic reaching the function through
+a subscribed queue is listed on it too; a value in the function's
+`environment` that reaches a queue, topic, table or bucket lists that on the
+function with the variable's name, and without a direction, because
+Terraform does not know one. `aws_s3_bucket`, `aws_dynamodb_table` (keys and
+secondary indexes as the table), `aws_db_instance` and `aws_rds_cluster`
+(kind from `engine`) are stores at the root, owned by the `service` option;
+a queue or topic nothing in the module touches is listed on that service as
+well, and says so. Kinesis, EventBridge, API Gateway, Step Functions,
+ElastiCache, MSK and ECS resources are named once as not read yet.
+
 `extract-python-kafka` is the framework-independent Kafka enrichment for
 Python. It recognizes confluent-kafka, kafka-python and aiokafka by their
 imported client types, follows literal topics through constants, environment
@@ -654,6 +726,178 @@ line with its description, and as entity links of type `command`, each
 leading to the line of the runner file it was read from, when `sourceBaseUrl`
 says where the repository is.
 
+## Where it answers, what it dials: the manifests, and the cluster
+
+A catalog that knows what a service provides and what it consumes still has
+holes where the two do not meet by route alone: two services answer
+`POST /foo`, and the caller's code says only that it posts to `$LEDGER_URL`.
+What that variable holds is not in the code. It is in the Deployment, the
+ConfigMap it reads, and the Service and Ingress objects that give the far end
+a name. Two plugins read those - `extract-k8s` from the manifests in a
+repository, `fetch-k8s` from a live cluster - and put two lists on the
+service:
+
+- **Hosts** - the names it answers on: a Kubernetes Service's name in its
+  short, namespaced, `svc` and fully qualified forms, and the hosts of the
+  Ingress or Gateway API HTTPRoute in front of it, from a rule whose backend
+  is that Service.
+- **Dials** - the in-cluster names its workload is configured to reach, cut
+  out of its containers' `env` and the ConfigMaps they read.
+
+The merge then has both facts in one place. A call that names a host, or a
+caller whose manifests dial one, resolves against the providers of its route
+when exactly one of them answers on that name, and the evidence says
+`kubernetes-host` as the basis. A host only ever decides between providers of
+the route; it never conjures a provider that does not have it.
+
+### What is never written
+
+A manifest holds configuration, and configuration is where the passwords are.
+The rule that keeps them out is a rule of shape, not a list of words:
+
+- A `Secret`, a `SealedSecret`, an `ExternalSecret`, or any document with
+  `stringData` is passed over at its `kind`, before its body is decoded. A
+  `secretKeyRef` or `secretRef` is not followed.
+- A value from `env` or a ConfigMap is reduced to the host it names, or to
+  nothing. A URL gives up its hostname and keeps nothing else - not the
+  scheme, the port, the path, the query, nor the user and password in front
+  of the host. A bare `host[:port]` gives up the port. `info`, `true`, a
+  token, a DSN written as `key=value` pairs: none of these is a host, and
+  none passes.
+- What is left qualifies only when the cluster resolves it: a form the tree's
+  own Services answer to, or `<name>.<namespace>.svc[.cluster.local]`, the
+  one shape no name outside a cluster has. A bare `cart` from another
+  repository's manifests is not taken, because nothing distinguishes it from
+  a word.
+- Warnings name files and directories, never values, because the build
+  report is committed.
+
+The fragment carries the variable's name no more than its value: the
+`environmentVariable` the HTTP client extractor records stays what it was, and
+no value is attached to it.
+
+### The manifests: extract-k8s
+
+Every `*.yaml` and `*.yml` under the root, or under the `paths` named in the
+options; anything without `apiVersion` and `kind` - a compose file, a
+workflow - is passed over silently. Multi-document files are split. A file
+holding `{{` is a template and not YAML until rendered, so a directory of
+Helm templates is passed over with one warning for the directory; render the
+chart into the tree, or point `paths` at plain manifests, to have it read.
+Kustomize is read without running it: the base and the overlays are all under
+the root, and two documents of one kind and name - a Deployment and the patch
+laid over it - fold into one, their env and labels unioned. `namespace`
+narrows the read to one namespace; an object naming none is read either way.
+
+The workload the step is about is the Deployment, StatefulSet, DaemonSet,
+ReplicaSet, Job or CronJob named like the service, or labelled so with
+`app.kubernetes.io/name` or `app`, or the only one in the tree. A Job or
+CronJob makes the service's kind `job`; a Deployment says nothing about kind,
+because a webapp and a worker both deploy that way. Several workloads and
+none named is a warning, not a guess.
+
+### The cluster: fetch-k8s
+
+The manifests say what should run; the cluster says what does, and for an
+estate deployed by Helm or Argo the rendered objects are in no repository at
+all. `fetch-k8s` asks `kubectl` for the workloads, Services, Ingresses,
+Gateway API routes and ConfigMaps of the namespaces named - never for a
+Secret - and answers with one fragment for every workload it saw, placed
+into contexts and services by label. It runs in the host (portolan.0008)
+because it needs the binary, the socket and kubectl's own credential, which
+comes from the kubeconfig and is never in the manifest.
+
+```json
+{ "name": "k8s-cluster", "host": "fetch-k8s" }
+
+{
+  "plugin": "k8s-cluster",
+  "in": ".",
+  "out": "data",
+  "options": {
+    "kubeContext": "prod-eu",
+    "namespaces": ["shop", "auth", "payments"],
+    "labels": { "context": "app.kubernetes.io/part-of", "service": "app.kubernetes.io/name" },
+    "namespaceContexts": { "shop-jobs": "shop" },
+    "cache": "data",
+    "out": "k8s-cluster.json"
+  }
+}
+```
+
+The context is the value of the `app.kubernetes.io/part-of` label and the
+service the value of `app.kubernetes.io/name`; an estate that labels
+differently names its own keys under `labels`. A workload without the
+context label falls back to `namespaceContexts`; one with neither is counted
+in a warning for its namespace and left out, not guessed at. A workload
+without the service label is named after itself. Several workloads landing
+on one service - a Deployment and the CronJob beside it - fold into one; a
+service that is only jobs is a `job`, one with a Deployment beside them is
+whatever its code says.
+
+The same offline rule as fetch-git: with `PORTOLAN_OFFLINE` set, or in CI,
+the fragment committed at `cache` is used unchanged; when the cluster cannot
+be reached it is used with a warning that names the failed command and its
+exit status, not the server; with no committed copy, that is an error and
+not a short answer. What kubectl itself said on stderr goes to the terminal,
+where the person at the keyboard can read the connection error, and not into
+the build report, which is committed. Nothing but the fragment is written to
+disk: the objects live in the process for the length of one call.
+
+portolan.0011 records why both readers keep names and nothing else.
+
+## Where it runs: the GitOps tree, and the deployer
+
+A service's manifests say what it is; what deploys them says where it
+stands - which environment, cluster and namespace, from which directory of
+which repository, tracking which revision. Two plugins read that, and the
+merge lays one under the other (portolan.0012, portolan.0013):
+
+- **extract-argocd** reads the Argo CD `Application` and `ApplicationSet`
+  objects in a GitOps tree, as wasm over the workspace, and answers with
+  what *should* run: one deployment per Application, basis `manifest`. An
+  ApplicationSet is expanded as far as a tree allows - `list` generators
+  whole, `git` directories and files by walking this repository, `matrix`
+  over those, the template rendered as Go `text/template` or fasttemplate
+  as it declared. A `clusters`, `pullRequest`, `scmProvider`, `merge` or
+  `plugin` generator, or a `git` one pointing at another repository, is a
+  warning naming the ApplicationSet and no rows. When the source path holds
+  a `kustomization.yaml`, the tool is kustomize and the images the overlay
+  pins are the declared images.
+- **fetch-argocd** asks the Argo CD API for what *does* run - the revision
+  synced, the images running, the link - and commits it as a snapshot
+  beside a lock, basis `api` (see the fetchers above).
+
+```json
+{ "name": "argocd-gitops", "wasm": { "url": "file://plugins/portolan-go.wasm" } }
+
+{
+  "plugin": "argocd-gitops",
+  "in": "examples/gitops",
+  "out": "examples/gitops/portolan",
+  "options": {
+    "repo": "github.com/shortlink-org/portolan",
+    "paths": ["bootstrap", "appsets"],
+    "labels": { "context": "app.kubernetes.io/part-of", "service": "app.kubernetes.io/name" },
+    "out": "argocd.json"
+  }
+}
+```
+
+An Application is placed on a service by the labels it carries -
+`app.kubernetes.io/part-of` and `app.kubernetes.io/name`, the same pair
+fetch-k8s reads off a workload, or whichever the manifest names under
+`labels` - and, without them, by deploying from the service's repository
+inside the service's directory. One that matches neither way is listed on
+the Problems page as unclaimed rather than guessed at.
+
+Where both plugins spoke for one Application the merge folds the two into
+one row, basis `both`: the deployer's shape, the tree filling what the
+deployer did not say, and the fields the two disagree on kept as the tree's
+word under `drift` - a `deployment-drift` problem, and a chip on the
+service page that says the difference in words. A row only the tree spoke
+for wears `declared`.
+
 ## Outside the estate: an external with a contract
 
 A service calls things nobody here builds - a card network, a tax API, a
@@ -777,13 +1021,60 @@ called" - and `unresolved` is never raised, because a trace does not put the
 far end in the catalog. A consumer span inside a trace opens a flow of its own
 and is matched the same way, so one password change verifies both the
 request's flow and the policy's. A root no flow opens is written down as
-`observed-<service>-<route>`, once per shape, with a summary saying how many
+`observed-<service>-<route>`, once per opening, with a summary saying how many
 traces showed it.
 
+Every recording that opened a flow is laid over it. A declared step carries
+`seen: { traces }`, how many recordings showed it. An rpc or an event a
+recording showed that the code does not declare is put into the flow after
+the declared step it followed, as a step with an id the code never gave
+(`seen1`, `seen2`) and a note saying in how many recordings; a lane such a
+hop needed is added after the declared ones. A store call is never added -
+the code's word on which repository method ran is the better one - and a
+consumer met on the way belongs to the flow it opens.
+
+Where recordings part, the flow says so. What every recording showed after
+a step is a run of plain steps; where they went different ways is an `alt`
+(`seen-alt1`, or `alt1` in an observed flow) with a branch for each way,
+titled by the hop it starts with and counting the recordings that went it,
+each branch laid over the same way inside; what they all showed again
+after parting comes after the frame, once. A recording that went no
+further where others went on is the branch titled `otherwise`, with no
+steps and its count, so that a reader sees the hop is not always taken.
+Two observed recordings that open the same way are one flow built this
+way, so a happy path and a refusal read as one sequence that parts. The
+merge takes all of this from a second declaration of a flow because it
+says where it came from: `seen` on a step the first declaration does not
+have, or a frame whose every step and branch carries it.
+
+A recording is also kept as an example of each flow it showed, under
+`examples` on the flow: the recording and trace it came from, when it ran,
+how long it took, and for each step the span's name, its length and an
+allowlist of its attributes - `http.route`, `http.request.method`,
+`http.response.status_code`, `rpc.service`, `rpc.method`, `db.operation.name`,
+`db.collection.name`, `messaging.destination.name`, `event.name`,
+`server.address` and a few more of that kind. A query text, a header, a full
+URL or a path with an id in it is somebody's data and is never carried; the
+list is closed in `examples.go`, and a new attribute is added there with the
+argument for it. `examples` in the options says how many recordings a flow
+keeps, the ones that show the most of it first: five when unset, zero for
+none.
+
+A recording added from the page lands under the project's
+`telemetry/recordings/` and widens (or adds) the project's `otel` verify step
+to read that directory, so every run after reads it too; the page runs the
+generator over a copy of the workspace first and shows which flows the
+recording showed before anything is written (portolan.0014).
+
 `service.name` is matched to the one service whose slug it is, `event.name` to
 the one event whose `wire.name` it is, or failing that to the one event of the
 publisher's with that last segment; `services` and `events` in the options say
-otherwise where an estate's names differ. A publish span whose
+otherwise where an estate's names differ. A server span's route is matched to
+the operation whose `http` verb and path template it fits; `routes` in the
+options names an operation for a route the estate spells another way - a
+prefix a gateway adds, a path the document writes differently - as
+`{ "POST /api/v1/sessions": "login" }`, and the name has to be one the
+service's interface declares. A publish span whose
 `messaging.destination.name` is not the event's `wire.channel` is a warning:
 the event went out, but not where the code says it does.
 
@@ -863,7 +1154,7 @@ trusted not to write the tree it reads, the same trust a process plugin has
 today; a `sha256` pins that trust to a build.
 
 `process` is the escape hatch for a plugin that needs a toolchain: the typed Go
-HTTP client analyzer and the Rust, Java, Python and TypeScript extractors run in
+HTTP client analyzer and the Rust, Java, Python, PHP and TypeScript extractors run in
 their own runtimes. It gets the same protocol
 and none of the sandbox, which is the trade being made and the reason it is
 not the default. It declares `command` and an `args` array; the host never

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

@@ -0,0 +1,44 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "repo": {
+      "type": "string",
+      "description": "The repository this tree is, spelled the way `Service.repo` spells it. A git generator pointing at another repository cannot be walked and is passed over with a warning; left out, every git generator is taken to mean this tree.",
+      "examples": ["github.com/acme/gitops"]
+    },
+    "paths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Directories under the input root that hold the Applications and ApplicationSets, so overlays and charts beside them are not read for Argo CD objects. Left out, the whole root is walked.",
+      "examples": [["bootstrap", "appsets"]]
+    },
+    "environmentLabel": {
+      "type": "string",
+      "default": "env",
+      "description": "The Application label that names the environment. An Application without it is placed by the cluster it deploys to."
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Which Application labels name the service it deploys. The defaults are the Kubernetes recommended labels, the same ones fetch-argocd and fetch-k8s read.",
+      "properties": {
+        "context": {
+          "type": "string",
+          "description": "The label whose value is the bounded context's slug.",
+          "default": "app.kubernetes.io/part-of"
+        },
+        "service": {
+          "type": "string",
+          "description": "The label whose value is the service's slug.",
+          "default": "app.kubernetes.io/name"
+        }
+      }
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "argocd.json"
+    }
+  }
+}

package/plugins/extract-celery/main.py

@@ -25,6 +25,7 @@ HERE = os.path.dirname(os.path.abspath(__file__))
 DESCRIPTOR = {
     "name": "extract-celery",
     "summary": "Reads Celery task declarations, the calls that enqueue them and the routes that place them into work queues and source-backed job flows.",
+    "category": "messaging",
     "phases": ["extract"],
 }
 

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

@@ -0,0 +1,213 @@
+# extract-csharp-ddd
+
+A C# tree laid out by module and layer in, a catalog fragment out - three
+kinds, when the API host proves an HTTP contract and the database project a
+schema. The .NET twin of `extract-php-ddd`: like it, 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 [kgrzybek's modular-monolith-with-ddd](https://github.com/kgrzybek/modular-monolith-with-ddd)
+made common in .NET - `src/Modules/<Module>/{Domain,Application,Infrastructure,IntegrationEvents}`
+with one API host under `src/API` and one SQL Server database project under
+`src/Database` - and it is that project the site ships as a profile, read by
+this extractor alone.
+
+Written in C# and run as a process plugin, `dotnet plugins/extract-csharp-ddd/bin/portolan-extract-csharp-ddd.dll`,
+built by `npm run plugins:build` with the .NET SDK (8 or later). The parser
+is Roslyn, the compiler's own, and the one dependency; every `.cs` under the
+root goes into one `Compilation`, so a partial class is one type, a base
+chain is followed across files and modules, and the type of `new X(...)` or
+of a variable is a fact rather than a guess. **The application is never
+built or run, and none of its packages is restored.** What comes from NuGet
+- MediatR's `INotificationHandler`, EF's `IEntityTypeConfiguration`,
+ASP.NET's `ControllerBase` - is an error type with a name, and every rule
+that touches one goes by the name as written on the base list. Only the
+runtime's own assemblies are referenced, so that `Guid`, `string` and
+`List<T>` read as themselves.
+
+## The layout it reads
+
+```
+src/Modules/<Module>/Domain/<Aggregate>/      the model: root, entities, value objects, events, ports
+src/Modules/<Module>/Application/<Group>/     the use cases: commands, queries, their handlers, notification handlers
+src/Modules/<Module>/Infrastructure/          the adapters: repositories, EF configurations, the bus subscriptions
+src/Modules/<Module>/IntegrationEvents/       what the module tells the other modules
+src/API/**/Modules/<Module>/*Controller.cs    the HTTP edge of that module
+src/Database/**/Structure/<schema>/Tables/    the tables, one file each, T-SQL
+src/Database/**/Structure/<schema>/Views/     the views over them
+src/BuildingBlocks/                           the bases: Entity, ValueObject, DomainEventBase, IntegrationEvent
+```
+
+`modules`, `api` and `database` in the options rename the three roots. A
+directory named `Tests`, or ending in `Tests`, is not read; neither is `bin/`
+or `obj/`.
+
+## What becomes what
+
+**Context.** A directory under `src/Modules` with `Domain` or `Application`
+under it, with its slug as id - `user-access` for `UserAccess`.
+`classification` in the options applies to every module the tree declares;
+nothing in the tree says which is core.
+
+**Service.** One per module, `<module>.module` - `meetings.module` - because
+a module here has its own schema, its own outbox, its own composition root
+and its own slice of the API. There is one deployable, and the catalog says
+so where it matters: a call from one module to another is drawn as a `call`
+step with a note that it is in process. The controllers filed under the
+module's directory of the API host are its HTTP interfaces, one per
+controller, `meetings.module.meetings`.
+
+**Aggregate.** A directory under `Domain/` whose own files declare a root: a
+class implementing `IAggregateRoot` or extending a class named
+`AggregateRoot` (the event-sourced base Payments keeps in its `SeedWork`).
+Subdirectories with no root of their own fold in - `Events/`, `Rules/` - and
+one with a root is an aggregate in its own right, `Members/MemberSubscriptions`.
+`SharedKernel`, `SeedWork`, `Shared`, `Rules`, `Events` and `Exceptions` at
+the top of `Domain/` are not aggregates. A directory with types and no root
+is a group the application layer may claim as a `model-group`; unclaimed, it
+is reported.
+
+The root and every class extending `Entity` are the entities, the root first.
+Their fields are the public properties inherited from a base that is not the
+framework's, then their own members in source order, a private `_title`
+read as `title`, the `_domainEvents` list left out. A value object is a
+class extending `ValueObject`, `TypedIdValueBase` or `AggregateId<T>`, with
+its public properties read up the base chain, so `MeetingId` has the base's
+`value: Guid`; one with no fields is reported and not written. A C# `enum` in
+the directory is a closed set with its members, `[Obsolete]` carried as
+deprecated. Rules, exceptions, domain services and `I*Context` interfaces are
+not shape and are skipped.
+
+**Domain event.** A class extending `DomainEventBase` or implementing
+`IDomainEvent`, in the aggregate's directory. Its fields are its own public
+properties - `Id` and `OccurredOn` are the envelope. It has no wire: a
+domain event here is a MediatR notification in the same transaction, and a
+notification replayed from the outbox after it. Its consumers are the
+module's `INotificationHandler<TheEvent>` classes, and its
+`INotificationHandler<TheNotification>` classes where the notification
+extends `DomainNotificationBase<TheEvent>`, each `declared` with the
+handler's name. The id keeps the class name whole,
+`meetings.module.meetings.MeetingCreatedDomainEvent`, because the
+integration event that follows it is a different fact with the same stem.
+
+**Integration event.** A class extending `IntegrationEvent` under the
+module's `IntegrationEvents/`. Its publisher is the module whose application
+layer calls `IEventsBus.Publish(new X(...))`, and its aggregate is the one
+whose domain event the publishing handler's notification wraps; an event
+nobody publishes is reported and filed under the owning module's
+`integration-events` group. Its wire is the class name on its own channel,
+`<bus>.<Event>` with `bus` from the options, `integration-events` by
+default, because the code names the class `InMemoryEventBus` and nothing
+else. Its consumers are the modules whose
+infrastructure says `SubscribeToIntegrationEvent<X>` or
+`new IntegrationEventGenericHandler<X>()`, each with the
+`INotificationHandler<X>` that hears it - `declared` when both are there,
+`unresolved` and reported when a module subscribes without a handler or
+handles without subscribing.
+
+**Channel.** The bus has no named channels - `InMemoryEventBus` routes by
+type and a module subscribes to a type - so each integration event is a
+channel of its own, `<bus>.<Event>`, of kind `event`: the module that
+publishes it sends on it, the modules that subscribe receive. Every module
+whose application layer calls `ICommandsScheduler.EnqueueAsync(new C(...))`
+has a `job` channel, `<module>.internal-commands`: the command written to
+its `InternalCommands` table in the same transaction, read by the
+ProcessInternalCommands job and handed to its handler. A command enqueued
+that no handler in the module takes is reported.
+
+**Operation.** A class under `Application/` whose base list says
+`ICommandHandler<C>` or `ICommandHandler<C, R>` or `IQueryHandler<Q, R>`; the
+message names the operation, `create-meeting` for `CreateMeetingCommand`.
+Its fields are the message's widest constructor's parameters, or its
+settable properties when it has none; its doc the handler's `<summary>`, or
+the message's; its source the handler's `Handle`. The aggregate is the
+domain directory named like the first directory under `Application/`
+(`Application/Meetings/CreateMeeting/` is `Domain/Meetings`), and a group
+with no such directory - `Countries`, `Authentication` - is a model-group
+named after it. A message extending `InternalCommandBase` is reached from
+the job channel; one implementing `IRecurringCommand` runs on a Quartz
+schedule. A handler under `Infrastructure/` is plumbing - `ProcessOutboxCommandHandler`
+- and is not read. `exposedBy` names the actions of the module's own
+controllers that new the message up; an action in another module's
+controller is a call across contexts and lives in the flow.
+
+**Store.** One per schema of the database project, owned by the module
+whose EF configurations `ToTable("X", "schema")` into it, else the module
+named like it, else the module that writes it; a read owns nothing, and a
+schema with no owner - `app`, written by the building blocks - is reported
+and not read. The module's home schema is its `db`, `meetings.module.db`;
+a second schema keeps its name. `storeKind` in the options says what the
+schemas live in, `other` for SQL Server. A table is read from its
+`CREATE TABLE`: columns with type and nullability, the primary key from the
+constraint or the column, foreign keys, and the indexes created beside it.
+A view is read from its `CREATE VIEW`: the select list's names, each typed
+from the column it selects when the alias resolves, the tables it reads,
+and the SELECT itself as the definition.
+
+An `IEntityTypeConfiguration<T>` in the module's infrastructure says which
+table holds T: the `ToTable` in `Configure` is the table, `Property<X>("_f").HasColumnName("C")`
+and `Property(x => x.P)` map its columns to T's fields, an `OwnsOne` maps
+the value object's parts to the owner's field, and an `OwnsMany` with a
+`ToTable` of its own is the child's table. The table `persists` the block
+and takes the role `aggregate-root` or `child`; a table nobody maps is
+`outbox` when it is the outbox, `projection` when the application
+layer writes it with SQL, `lookup` when it is only ever read, `other`
+otherwise. A `Messages` or `Streams` table is where an event-sourced
+module's `IAggregateStore` keeps its streams.
+
+Accesses come from two places. A class in the infrastructure implementing an
+`I*Repository` port from the domain, or `IAggregateStore`, reads and writes
+the table that holds the port's root - `write MeetingRepository.AddAsync` -
+by the method's name: `Add`, `Save`, `Update`, `Append` write, `Remove` and
+`Delete` delete, the rest read. Every string in a method of the application
+or infrastructure layer is read as SQL: `FROM`, `JOIN`, `INSERT INTO`,
+`UPDATE` and `DELETE FROM` against a schema-qualified name are accesses by
+that method; a view read is an access on the tables the view reads; a name
+the database project does not declare is reported - which is how the
+project's `v_Countriess` was found.
+
+**Flow.** One per controller action: the request in, the command or query
+the action news up, then what the handler does, followed through the
+classes it holds and the domain methods it calls, by symbol. A call on a
+port is a step to the store; a Dapper query a step to the tables its SQL
+names; `AddDomainEvent(...)` an event raised in process, drawn as a
+self-message with the event's id; `IEventsBus.Publish(...)` an event on the
+bus with a `message` handoff; `ICommandsScheduler.EnqueueAsync(...)` a `job`
+handoff to the module's internal queue; a command handed to another module's
+facade a `call` across the boundary, followed there. One flow per
+notification handler of a domain event, from the event in; one per
+subscription a module handles, from the bus in; one per internal command,
+from the queue in; one per recurring command, on its schedule. Each flow
+carries the trigger it was read from: `http`, `event`, `message`, `job` or
+`scheduled`.
+
+**HTTP.** One OpenAPI 3.1 document per module with controllers,
+`openapi.<module>.yaml` (`openapiOut` in the options), one operation per
+action: the path from `[Route]` and `[HttpGet("...")]` with `[controller]`
+filled in, the `{parameters}` typed from the action's, the `[FromBody]`
+class as the request schema one level deep, `[ProducesResponseType]` as the
+responses, `[HasPermission]` as `x-portolan-permission`, the action's
+`<summary>` or its name as the summary.
+
+## Options
+
+See `options.schema.json`. `modules`, `api` and `database` default to
+`src/Modules`, `src/API` and `src/Database`; `bus` to `integration-events`;
+`storeKind` to `other`; `repo` and `classification` to nothing.
+
+## Tests
+
+```bash
+dotnet run --project plugins/extract-csharp-ddd/test
+```
+
+`testdata/mymeetings` is a small tree in the layout: three modules, one of
+them event-sourced, a module publishing an integration event two others
+hear, an internal command enqueued from a subscription, a recurring command,
+an EF configuration with owned types and a child table, views, and a
+controller filed under a module the tree does not have. `expected.json`,
+`expected-stores.json` and the `openapi.*.yaml` beside it are what the
+extractor writes for it, and `expected-warnings.txt` what it says on the
+way; `UPDATE_GOLDEN=1` writes them again after a deliberate change, and the
+diff is the review.