@shortlink-org/portolan 0.1.0

package/plugins/extract-sql/view.go

@@ -0,0 +1,295 @@
+package main
+
+// Reading a view.
+//
+// A view is kept apart from a table rather than folded in behind a flag: it has
+// no key, no constraints and no rows of its own, and what it has instead is
+// what it reads. So this reads the select: which relations it draws from, what
+// each output column is called, and - the part a table cannot say - which
+// column each one was computed from.
+//
+// The type of a column is not in the statement, because a view does not declare
+// one. It is taken from the column it is computed from when there is exactly
+// one; a column summed, coalesced or joined out of several says nothing and is
+// left blank rather than guessed at.
+
+import (
+	"strings"
+
+	"github.com/pgplex/pgparser/nodes"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// view is what one CREATE VIEW says, before the store turns names into ids.
+type view struct {
+	name string
+	doc  string
+	// materialized: the database keeps the rows rather than recomputing them,
+	// which means they can be stale. A reader has to know that before believing
+	// one, so it is carried rather than inferred from the name.
+	materialized bool
+	// reads names the relations of the FROM clause, in the order written.
+	reads []string
+	// columns, in the order the select lists them.
+	columns []viewColumn
+	// definition is the statement as it was written.
+	definition string
+}
+
+type viewColumn struct {
+	name string
+	// from is "<relation>.<column>" for every column this one is computed from.
+	from []string
+}
+
+func readView(stmt *nodes.ViewStmt, sql string) view {
+	return selectInto(relationName(stmt.View), stmt.Query, false, sql)
+}
+
+// readMaterializedView reads the other spelling. The grammar calls it a CREATE
+// TABLE AS whose object type is a matview, because that is what it is: a query
+// whose rows are kept.
+func readMaterializedView(stmt *nodes.CreateTableAsStmt, sql string) (view, bool) {
+	if stmt.Objtype != nodes.OBJECT_MATVIEW || stmt.Into == nil || stmt.Into.Rel == nil {
+		return view{}, false
+	}
+	query := stmt.Query
+	if query == nil {
+		query = stmt.Into.ViewQuery
+	}
+
+	return selectInto(relationName(stmt.Into.Rel), query, true, sql), true
+}
+
+func selectInto(name string, node nodes.Node, materialized bool, sql string) view {
+	out := view{name: name, materialized: materialized}
+
+	query, ok := node.(*nodes.SelectStmt)
+	if !ok {
+		return out
+	}
+
+	// alias -> relation, so `j.id` can be read as a column of journal_entries.
+	relations := map[string]string{}
+	readFrom(query.FromClause, relations, &out.reads)
+
+	for _, item := range items(query.TargetList) {
+		target, ok := item.(*nodes.ResTarget)
+		if !ok {
+			continue
+		}
+
+		var sources []string
+		columnRefs(target.Val, relations, &sources)
+
+		name := target.Name
+		if name == "" && len(sources) == 1 {
+			// `SELECT j.state` names its column after the column it takes.
+			name = sources[0][strings.LastIndex(sources[0], ".")+1:]
+		}
+		if name == "" {
+			continue
+		}
+		out.columns = append(out.columns, viewColumn{name: name, from: sources})
+	}
+
+	out.definition = definitionOf(sql, out.name, materialized)
+
+	return out
+}
+
+// readFrom walks the FROM clause, which is a tree once anything is joined.
+func readFrom(list *nodes.List, relations map[string]string, reads *[]string) {
+	for _, item := range items(list) {
+		readFromItem(item, relations, reads)
+	}
+}
+
+func readFromItem(item nodes.Node, relations map[string]string, reads *[]string) {
+	switch node := item.(type) {
+	case *nodes.RangeVar:
+		name := relationName(node)
+		relations[node.Relname] = name
+		relations[name] = name
+		if node.Alias != nil && node.Alias.Aliasname != "" {
+			relations[node.Alias.Aliasname] = name
+		}
+		*reads = append(*reads, name)
+
+	case *nodes.JoinExpr:
+		readFromItem(node.Larg, relations, reads)
+		readFromItem(node.Rarg, relations, reads)
+	}
+}
+
+// columnRefs collects every column an expression reaches, however deep: a sum
+// of a coalesce of a column is still that column's value arriving here.
+func columnRefs(node nodes.Node, relations map[string]string, into *[]string) {
+	switch expression := node.(type) {
+	case *nodes.ColumnRef:
+		fields := stringList(expression.Fields)
+		if len(fields) == 0 {
+			return
+		}
+		column := fields[len(fields)-1]
+		relation := ""
+		if len(fields) > 1 {
+			relation = relations[fields[len(fields)-2]]
+		} else {
+			// A qualified relation has two lookup keys (base name and full
+			// name), but it is still only one FROM source.
+			for _, candidate := range relations {
+				if relation == "" {
+					relation = candidate
+				} else if relation != candidate {
+					relation = ""
+					break
+				}
+			}
+		}
+		if relation == "" || column == "*" {
+			return
+		}
+		*into = append(*into, relation+"."+column)
+
+	case *nodes.FuncCall:
+		for _, argument := range items(expression.Args) {
+			columnRefs(argument, relations, into)
+		}
+
+	case *nodes.CoalesceExpr:
+		for _, argument := range items(expression.Args) {
+			columnRefs(argument, relations, into)
+		}
+
+	case *nodes.A_Expr:
+		columnRefs(expression.Lexpr, relations, into)
+		columnRefs(expression.Rexpr, relations, into)
+
+	case *nodes.TypeCast:
+		columnRefs(expression.Arg, relations, into)
+
+	case *nodes.CaseExpr:
+		columnRefs(expression.Arg, relations, into)
+		for _, when := range items(expression.Args) {
+			if clause, ok := when.(*nodes.CaseWhen); ok {
+				columnRefs(clause.Expr, relations, into)
+				columnRefs(clause.Result, relations, into)
+			}
+		}
+		columnRefs(expression.Defresult, relations, into)
+	}
+}
+
+// definitionOf cuts the statement out of the file it was read from.
+//
+// The parse tree is not printed back: a reader comparing the page to the
+// migration wants the SQL somebody wrote, down to the line breaks they chose.
+func definitionOf(sql, name string, materialized bool) string {
+	lower := strings.ToLower(sql)
+	opening := "create view "
+	if materialized {
+		opening = "create materialized view "
+	}
+	at := strings.Index(lower, opening+strings.ToLower(name))
+	if at < 0 {
+		at = strings.Index(lower, "create or replace view "+strings.ToLower(name))
+	}
+	if at < 0 {
+		return ""
+	}
+	end := strings.Index(sql[at:], ";")
+	if end < 0 {
+		return strings.TrimSpace(sql[at:])
+	}
+
+	return strings.TrimSpace(sql[at : at+end+1])
+}
+
+// asCatalog turns the names into ids, and takes what the statement does not
+// say - a column's type, and whether it can be null - from the column it is
+// computed from.
+func (v view) asCatalog(storeID, source string, tables []catalog.Table) catalog.View {
+	out := catalog.View{
+		ID:           storeID + "." + v.name,
+		Name:         v.name,
+		Doc:          v.doc,
+		Materialized: v.materialized,
+		Definition:   v.definition,
+		Source:       source,
+	}
+	for _, relation := range v.reads {
+		out.Reads = append(out.Reads, storeID+"."+relation)
+	}
+
+	for _, column := range v.columns {
+		held := catalog.Column{Name: column.name, Nullable: true}
+		for _, from := range column.from {
+			held.From = append(held.From, storeID+"."+from)
+		}
+		if len(column.from) == 1 {
+			at := strings.LastIndex(column.from[0], ".")
+			if at < 0 {
+				continue
+			}
+			relation, name := column.from[0][:at], column.from[0][at+1:]
+			if source := columnOf(tables, storeID+"."+relation, name); source != nil {
+				held.Type = source.Type
+				held.Nullable = source.Nullable
+				held.Maps = source.Maps
+			}
+		}
+		out.Columns = append(out.Columns, held)
+	}
+
+	// What it holds is what the relation it is built on holds: a view over one
+	// aggregate's tables is another way of reading that aggregate, and a view
+	// that draws on several says nothing here rather than picking one.
+	persists := ""
+	for _, relation := range v.reads {
+		table := tableOf(tables, storeID+"."+relation)
+		if table == nil || table.Persists == nil {
+			continue
+		}
+		if persists == "" {
+			persists = table.Persists.Aggregate
+
+			continue
+		}
+		if persists != table.Persists.Aggregate {
+			persists = ""
+
+			break
+		}
+	}
+	if persists != "" {
+		out.Persists = &catalog.Persists{Aggregate: persists}
+	}
+
+	return out
+}
+
+func tableOf(tables []catalog.Table, id string) *catalog.Table {
+	for i := range tables {
+		if tables[i].ID == id {
+			return &tables[i]
+		}
+	}
+
+	return nil
+}
+
+func columnOf(tables []catalog.Table, tableID, name string) *catalog.Column {
+	table := tableOf(tables, tableID)
+	if table == nil {
+		return nil
+	}
+	for i := range table.Columns {
+		if table.Columns[i].Name == name {
+			return &table.Columns[i]
+		}
+	}
+
+	return nil
+}

package/plugins/extract-ts/README.md

@@ -0,0 +1,306 @@
+# extract-ts
+
+A TypeScript or JavaScript service in, a catalog fragment out. The TypeScript twin of
+`extract-go`: it describes one service - its aggregates, what they publish,
+what runs when somebody calls in, what the service calls - by reading the
+tree, and it reads the tree by its layout. Nothing is annotated for the
+catalog; the layout is the claim.
+
+Written in TypeScript and run as a process plugin, `node plugins/extract-ts/main.ts`,
+because the catalog's own types in `src/catalog.ts` are the fragment's types.
+The parser is oxc-parser: native, with no TypeScript inside it, handing back
+an ESTree with the TypeScript nodes typescript-eslint would give. The
+project's TypeScript is the 7 series, a compiler with no syntax tree to offer,
+and holding a second copy of 5 beside it for the parser alone was a workaround
+this replaces. The tree is read through `ast.ts`, a hand-written, minimal set
+of node shapes and predicates, so the reading does not move when the parser's
+own typings do. There is no type checker: everything is resolved by name and by import - the
+resolver is `oxc-resolver`, so a tsconfig `paths` alias and a workspace package
+resolve as they would for Node and TypeScript - which is all a layout that is
+the claim needs.
+
+## The layout it reads
+
+```
+src/
+  domain/<aggregate>/
+    <aggregate>.ts        the root: a class named like the directory, in PascalCase
+    *.ts                  entities: other classes exported from the directory's own files
+    vo/*.ts               value objects: one class per file
+    rules/*.ts            specifications; skipped, they are not shapes
+    events/*.ts           one class per event, `readonly name = "<service>.<Name>"`
+    port.ts               interfaces a use case holds: repositories, publishers
+    status.ts             optional: `export const TRANSITIONS = { open: ["checked-out"], … }`, the root's lifecycle
+    README.md             the aggregate's page, or the doc comment above the root class
+  application/<aggregate>/usecases/<name>/
+    usecase.ts            `export class UseCase` with a `handle(...)` method
+    README.md             the operation's doc, or the doc comment above the class
+  application/policy/*.ts   one class per policy, `handle(event)` reacting to one event
+  infrastructure/transport/http/
+    gen/openapi.yaml      the document; operationIds name the handlers
+    <pkg>/*.ts            handlers: `async <operationId>(...)` methods on a class holding use cases
+  schema/<module>/
+    schema.graphql        the contract, read by extract-graphql rather than here
+    resolvers/<Root>/<field>.ts
+                          one file per field of Query, Mutation or Subscription,
+                          exporting the field's own name; the third parameter is
+                          the context, and `ctx.<port>.<method>(...)` is a hop
+  <anywhere>/context.ts   `export interface GraphQLContext` - the ports every
+                          resolver may reach, which is what a use case says in
+                          its constructor
+  ports/*.ts              ports a service with no use cases declares on their own
+  infrastructure/<peer>/
+    gen/openapi.yaml + gen/types.ts     an HTTP peer: the vendored document and `openapi-typescript` output
+    proto/**/*.proto + gen/*_pb.ts       a gRPC peer: the vendored contract and Connect-ES output
+    client.ts             the adapter over the generated client, implementing a use case's port
+  infrastructure/repository/<aggregate>/
+    migrations/*.sql      read by extract-sql, with `repositories` pointed at the directory above
+  di/**/*.ts              which adapter or use case fills a port: `export function provideX(deps): Port`,
+                          or an Inversify container's `bind<Port>(TOKENS.X).to(Impl)` or
+                          `.toConstantValue(new Impl(...))`; a port bound more than once - the adapter
+                          behind a setting, a stand-in without - shows as the binding that reaches a
+                          peer; a use case's constructor may carry `@inject(TOKENS.X)`, the type
+                          beside it is still the port
+```
+
+## A service whose way in is a graph
+
+A BFF has no aggregates, no store and no use cases: it composes what other
+services decided, and there is nothing left for it to decide. Told where the
+schema is - the `graphql` option, `src/schema` by convention - this reader
+opens a flow on each resolver instead of on an HTTP or gRPC endpoint, and does
+not report the missing domain.
+
+A resolver's ports do not arrive in a constructor. The signature comes from
+the generated resolver type, so the context parameter is typed by where it
+sits rather than by anything written in the file, and the ports are read once
+from the one exported `GraphQLContext` interface - the name codegen's own
+`contextType` conventionally points at. From there everything is the same as
+inside a use case: `ctx.baskets.byId(...)` is a port call, assembly says what
+fills the port, and the adapter behind it names the peer.
+
+The field is called what `extract-graphql` calls it - `Query.basket`,
+`Mutation.checkout` - because the directory a resolver sits in is the root
+type and the file is the field. That is why nothing here parses a schema: the
+layout already says what the SDL would.
+
+An adapter over the bus is the one port call that draws no step. It calls
+nobody - it waits - and what it hears is said by the channel the service
+declares in its AsyncAPI document, not by a step in a flow.
+
+## A service written in JavaScript
+
+The same layout in `.js` (or `.mjs`, `.jsx`) reads the same way. What the
+syntax cannot say, the doc comments do, in the form `tsc --checkJs` reads:
+
+| in TypeScript | in JavaScript |
+| --- | --- |
+| `readonly items: BasketItem[] = []` | `/** @type {BasketItem[]} */ items = [];` |
+| `constructor(readonly id: string)` | `/** @param {string} id */ constructor(id) { this.id = id; }` - a field is what the constructor assigns to `this`, typed by the parameter it takes or by what it is given |
+| `handle(input: Input): Promise<void>` | `/** @param {Input} input @returns {Promise<void>} */ handle(input)` |
+| `export interface Port { save(b: Basket): Promise<void> }` | `/** @typedef {{ save(b: Basket): Promise<void> }} Port */`, or `@typedef {Object} Port` with one `@property {type} name` per member |
+| `import type { Port } from "./port.ts"` | `/** @typedef {import("./port.js").Port} Port */`, or `import("./port.js").Port` written inline in any type |
+| `bind<Port>(TOKENS.Port)` | `bind(TOKENS.Port)` - the token's name is the port's |
+| `function provideX(deps): Port` | `/** @returns {Port} */ function provideX(deps)` |
+| `gen/types.ts`, `gen/**/x_pb.ts` | `gen/types.d.ts`, `gen/**/x_pb.js` |
+
+A type expression in a comment is TypeScript's own syntax, so it is parsed
+as one - `let _: <expr>` - and read by the same code that reads an
+annotation. Closure's `?T` and `Array.<T>` are not, and read as nothing.
+`@param`, `@returns` and `@type` are read only where the syntax has no
+annotation, so a TypeScript file that leaves a field untyped and documents it
+instead reads that too. Decorators are not JavaScript; assembly in a
+JavaScript tree is the container's `bind(...)` calls or the `provideX`
+functions, which need none.
+
+`testdata/cart-js` is `testdata/cart` written in JavaScript, file for file,
+and the test is that both read to one fragment.
+
+## What a doc comment says
+
+The `/** … */` above a class, a field or a constructor parameter property is
+its doc, read the way [JSDoc](https://jsdoc.app/) and TSDoc say to: the prose
+above the first tag, then the tags. Most tags are for a type checker or a site
+generator and are dropped - `@param`, `@returns`, `@see`, `@fires` - because
+the layout and the signature already say what they would, and a tag that
+restates the code is one more place for it to go stale. Three are kept:
+
+| tag | becomes |
+| --- | --- |
+| `@remarks` | the paragraphs after the summary, in the same doc: TSDoc's long description is still the description |
+| `@example` | a fenced block in the aggregate's readme when the root has no `README.md`; elsewhere an example is code where a sentence should be, and is left out |
+| `@deprecated` | `deprecated: true` on the entity, value object, field, event version or operation, which the page strikes through and badges; the reason, when one follows the tag, is appended to the doc as "Deprecated: …" - except for an operation, whose doc stays the one paragraph its README or summary gives |
+
+An inline `{@link X}` is flattened to `X`, or to its label when it has one
+(`{@link X|label}`, `[label]{@link X}`): the catalog has no way to say from
+inside a sentence that a name is a page, so the name is kept as a word rather
+than left as a tag nobody renders.
+
+## What becomes what
+
+**Aggregate.** Every directory under `src/domain/` whose name has a root class
+in it. The root is the class whose name is the directory's in PascalCase
+(`basket` → `Basket`); a directory without one is reported and skipped. Its
+fields are the class's property declarations and constructor parameter
+properties, `readonly id: string` and `constructor(readonly id: string)` alike,
+with the type as written. Other classes exported from the directory's top-level
+files are entities; classes in `vo/` are value objects; `rules/` is skipped.
+The readme is `README.md` in the directory, or the doc comment above the root,
+its `@example`s fenced as code.
+
+**Event.** Each class in `events/` with a `name` property initialised to a
+string literal - `readonly name = "cart.BasketCheckedOut"` or `static readonly
+name` - is an event of the aggregate, its id `<service>.<aggregate>.<Class>`.
+Fields as for a root; doc from JSDoc; one version, `v1`; `consumers` empty,
+because a service does not know who listens - the merge is where the other end
+arrives, and the flows imply the rest.
+
+**Operation.** Each `application/<aggregate>/usecases/<name>/usecase.ts`
+exporting a class `UseCase` with a method `handle`. The id is the directory's
+name in PascalCase (`add_item` → `AddItem`). It is a command when `handle` -
+or a private method it calls - calls `save`, `delete`, `create`, `update` or
+`publish` on a port, else a query. The doc is the directory's `README.md`
+first paragraph, or the JSDoc above the class. `exposedBy` names the HTTP
+operations that run it, read from the handlers.
+
+**Port.** A constructor parameter of `UseCase` typed with an interface or a
+class. What it is decides what a call on it becomes:
+
+| the type is | a call on it is |
+| --- | --- |
+| an interface from `domain/<aggregate>/port.ts` | a `call` into the store lane, named by the method; an argument that holds an event is the event leaving for the bus |
+| another `UseCase` | a `call` to the service itself, and that use case's own steps, inlined two deep at most |
+| an interface bound in `di/` to a use case | the same |
+| an interface bound in `di/` to an adapter over a generated client | an `rpc` to the peer, read through the adapter's method to the client's call |
+| an interface another use case declares, imported from its `usecase.ts` | whatever that use case's binding says: the port is looked up under the use case that declares it |
+| the generated client itself | an `rpc` to the peer |
+| a function type, `() => Date` | nothing: a clock is a port with nobody at the other end |
+
+**Lifecycle.** An aggregate whose directory exports a `TRANSITIONS` table -
+an object literal, each state to the states it may become - gets a
+`lifecycle`: the states in the table's order, the first being where a new
+root starts, and one move per edge. The method of the root that assigns
+`this.status` is the mover; every public method that calls it with a literal
+(`this.moveTo("checked-out", now)`) makes the edges into that state, and
+`emits` is the event its return type names. A status assigned anywhere else,
+a move into a state the table lacks, and an edge in the table no method makes
+are each reported. A state nothing leads out of is terminal; that is derived
+on the page, never written down.
+
+**Flow, from an endpoint.** Each handler method named by an `operationId` in
+`transport/http/gen/openapi.yaml` opens a flow: `client → service : rpc
+<operationId>`, then the steps of every use case the handler runs, in the order
+it runs them. **Flow, from a policy.** Each class in `application/policy/` with
+a `handle` opens a flow on the bus: `bus → service : event <ref>`, where the
+event is what the body tests for - `event instanceof BasketCheckedOut`, `event
+.name === "cart.BasketCheckedOut"`, or a `switch` on `event.name`. An event
+imported from outside `src/domain` is another service's; with a line in the
+`events` option mapping the import to an aggregate id it resolves, without one
+the step names the type and is unresolved.
+
+**Inside a body.** Statements are read in source order. A call on a port is a
+hop; a call on `this.<method>` is followed into the method; `if` and `switch`
+become an `alt` when some arm holds a hop, an arm that `return`s or `throw`s
+is terminal; `for`, `for … of`, `while` become a note on the steps inside;
+`await` is transparent; a `.then(...)` chain is followed as a call. Every step
+is `declared`: this reads code, and code is a claim about behaviour, not a
+record of it. A call whose peer the manifest does not name is `unresolved`.
+
+**What a name holds.** A value is followed back to its type by name, without a
+checker: what a domain constructor, a domain method or a port method hands
+back, as its return type is written - `Promise<[Basket, BasketCreated]>` binds
+both by position - and what a helper function anywhere under `src/` returns
+when its return type names something of an aggregate (`holderOf(repo, id,
+token): Promise<Basket>`). `for (const basket of idle)` holds one of what
+`idle` holds; `into = created` holds what `created` held; `events.push(x)`
+collects what `x` holds, and `...events` handed to a port is each event
+collected, once. An event handed to a domain port is the event leaving for the
+bus; a field read off one is not.
+
+**HTTP peer.** A generated `openapi-fetch` client is called with the verb and
+the path in the code - `client.GET("/v1/sessions/current", …)` - and the
+document vendored beside `gen/types.ts` says which operation answers on that
+route and which interface it belongs to, spelled by `plugins/openapi` so the
+call and the method on the other side share one id: `auth.v1.Sessions/validateSession`.
+**gRPC peer.** A Connect-ES client is created from a service descriptor whose
+`typeName` is the proto service, `shop.v1.Pricing`, and a call on it is the
+method in the descriptor's own case: `client.getQuote(…)` is
+`shop.v1.Pricing/GetQuote`. The descriptor is imported from under `gen/`,
+however deep its package path put it, and the service is looked up in the
+`.proto` files vendored under `proto/` beside that `gen/`. Either way the peer is the manifest's `peers`
+entry for the api id or the proto package; without one the lane is `unknown`
+and the step unresolved, and the call is recorded on the service's `consumes`
+with the vendored document as its source.
+
+## Options
+
+```json
+{
+  "context": "shop",
+  "contextName": "Shop",
+  "service": "cart",
+  "store": "pg",
+  "peers": { "auth.v1": "auth.auth", "shop.v1": "shop.pricing" },
+  "events": { "@acme/payments-events": "payments.ledger.payment" },
+  "source": "src",
+  "out": "domain.json"
+}
+```
+
+`source` is the directory the layout starts in, `src` unless said otherwise.
+Everything else means what it means for `extract-go`.
+
+## Extraction limits
+
+These cases do not become facts in the fragment:
+
+- a domain directory with no root class of its name;
+- a use case directory with no `UseCase`, or a `UseCase` with no `handle`;
+- a port whose type is neither a domain port, a use case, nor a client, whose
+  calls are therefore left out;
+- a handler named by no `operationId`, and an `operationId` with no handler;
+- a policy whose `handle` tests for no event;
+- a peer package with no document beside it, or a route the document does not
+  declare;
+- an event no flow reaches;
+- a proto package or api id the manifest names no peer for.
+- an import of a dependency: what lands in `node_modules` is not read, so a
+  port declared by a published package is a name with nothing behind it. A
+  tsconfig `paths` alias and a workspace package are followed, because they
+  resolve to the repository's own files.
+- a file with a syntax error, past the error: the tree up to it is read, the
+  rest is not, and the warning says where.
+
+## Manifest
+
+```json
+{
+  "plugins": [{ "name": "ts-domain", "process": { "command": "node", "args": ["plugins/extract-ts/main.ts"] } }],
+  "extract": [
+    { "plugin": "ts-domain", "in": "examples/shop/cart", "out": "examples/shop/cart/portolan",
+      "options": { "context": "shop", "service": "cart", "store": "pg",
+                   "peers": { "auth.v1": "auth.auth", "shop.v1": "shop.pricing" }, "out": "domain.json" } },
+    { "plugin": "openapi", "in": "examples/shop/cart", "out": "examples/shop/cart/portolan",
+      "options": { "context": "shop", "service": "cart",
+                   "spec": "src/infrastructure/transport/http/gen/openapi.yaml", "out": "api.json" } },
+    { "plugin": "sql", "in": "examples/shop/cart", "out": "examples/shop/cart/portolan",
+      "options": { "context": "shop", "service": "cart", "store": "pg", "name": "Cart database",
+                   "repositories": "src/infrastructure/repository", "out": "stores.json" } }
+  ],
+  "verify": [
+    { "plugin": "otel", "in": "examples/shop/cart", "out": "examples/shop/cart/portolan",
+      "options": { "traces": ["telemetry/traces.jsonl"], "out": "observed.json" } }
+  ]
+}
+```
+
+`extract-sql`'s `repositories` points it at the adapters: its default is the
+Go layout, `internal/infrastructure/repository`, and a TypeScript service
+keeps the same shape one directory over, `<aggregate>/migrations` under it.
+
+## Tests
+
+The reader is held to fixtures under `testdata/`: a small service in the
+layout above, each shape it claims to read present once, and a golden
+fragment. `examples/shop/cart/portolan/domain.json` is the second golden, held
+by `gen:check` like every other fragment.