@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/routes.test.ts

@@ -27,6 +27,13 @@ describe("routes", () => {
     expect(isRoutable("/landing/")).toBe(true);
   });
 
+  it("routes the plugin index, and one plugin on it by manifest name", () => {
+    expect(paths.plugins()).toBe("/plugins");
+    expect(isRoutable(paths.plugins())).toBe(true);
+    expect(paths.plugin("go-nats")).toBe("/plugins#plugin-go-nats");
+    expect(isRoutable(paths.plugin("go-nats"))).toBe(true);
+  });
+
   it("routes every URL the catalog can produce", () => {
     const unroutable = allCatalogPaths(catalog).filter((p) => !isRoutable(p));
     expect(unroutable).toEqual([]);
@@ -169,6 +176,8 @@ describe("routes", () => {
     expect(paths.settingsProjects()).toBe("/settings/projects");
     expect(paths.settingsPipeline()).toBe("/settings/pipeline");
     expect(paths.settingsDelivery()).toBe("/settings/delivery");
+    expect(paths.settingsRecordings()).toBe("/settings/recordings");
+    expect(isRoutable(paths.settingsRecordings())).toBe(true);
     expect(paths.settingsIntegrations()).toBe("/settings/integrations");
     expect(paths.settingsPreferences()).toBe("/settings/preferences");
     expect(paths.settingsAbout()).toBe("/settings/about");

package/src/routes.ts

@@ -39,12 +39,22 @@ export const paths = {
    * page, and the reader is told what was narrowed and offered it back.
    */
   term: (termId: string) => `/language?term=${encodeURIComponent(termId)}`,
+  /**
+   * Every plugin the package ships, as each describes itself. One page: the
+   * question a reader asks is "what can this read?", and the answer is the
+   * whole list grouped by what is read, not one plugin at a time.
+   */
+  plugins: () => "/plugins",
+  /** One plugin on that page, by the name the manifest declares it under. */
+  plugin: (name: string) => `/plugins#plugin-${name}`,
   problems: () => "/problems",
   changes: () => "/changes",
   settings: () => "/settings",
   settingsProjects: () => "/settings/projects",
   settingsPipeline: () => "/settings/pipeline",
   settingsDelivery: () => "/settings/delivery",
+  settingsRecordings: () => "/settings/recordings",
+  settingsRules: () => "/settings/rules",
   settingsIntegrations: () => "/settings/integrations",
   settingsPreferences: () => "/settings/preferences",
   settingsAbout: () => "/settings/about",
@@ -195,6 +205,7 @@ export const SERVICE_ANCHOR = {
   aggregates: "svc-aggregates",
   events: "svc-events",
   commands: "svc-commands",
+  deployments: "svc-deployments",
 } as const;
 
 /** The section anchors on the context map. */
@@ -211,7 +222,9 @@ export function relationAnchor(relationId: string): string {
 /** The section anchors on the overview, so "g d" has somewhere to land. */
 export const OVERVIEW_ANCHOR = {
   landscape: "landscape",
+  deployed: "deployed",
   contexts: "contexts",
+  bridges: "bridges",
   flows: "flows-by-reach",
   problems: "problems",
 } as const;
@@ -262,6 +275,12 @@ export function adrPath(adrId: string): string | null {
   return adr ? paths.adr(adr.slug) : null;
 }
 
+/** Path to a flow's page, or null if the id is not a catalog flow. */
+export function flowPath(flowId: string): string | null {
+  const flow = index.catalog.flows.find((candidate) => candidate.id === flowId);
+  return flow ? paths.flow(flow.slug) : null;
+}
+
 /** Path to an aggregate page, or null if the id is not a catalog aggregate. */
 export function aggregatePath(aggregateId: string): string | null {
   const aggregate = index.aggregateById.get(aggregateId);
@@ -374,9 +393,10 @@ const ROUTES: RegExp[] = [
   /^\/flows\/[^/]+$/,
   /^\/adrs$/,
   /^\/language$/,
+  /^\/plugins$/,
   /^\/problems$/,
   /^\/changes$/,
-  /^\/settings(?:\/(?:projects|pipeline|delivery|integrations|preferences|about))?$/,
+  /^\/settings(?:\/(?:projects|pipeline|delivery|recordings|rules|integrations|preferences|about))?$/,
   /^\/externals\/[^/]+$/,
   /^\/map$/,
   /^\/adrs\/[^/]+$/,
@@ -408,6 +428,7 @@ export function allCatalogPaths(catalog: Catalog): string[] {
     paths.map(),
     paths.adrs(),
     paths.language(),
+    paths.plugins(),
     paths.problems(),
     paths.changes(),
     paths.settings(),

package/src/lib/data-problems.ts

@@ -1,314 +0,0 @@
-// Where the schema and the model disagree.
-//
-// The unresolved edges in derive.ts are about arrows that land nowhere. These
-// are about arrows that land somewhere they should not, and about two claims
-// in the catalog that cannot both be current. They share one shape and one
-// page, because a reader scanning Problems asks the same question of all of
-// them: what do I have to go and look at?
-//
-// Errors are boundary leaks — one service reaching into another's schema. They
-// are errors because no amount of context makes them fine: a foreign key across
-// a service boundary is a deployment order nobody wrote down, and a second
-// writer in someone else's database is a bounded context with two owners.
-//
-// Warnings are staleness. A table that no longer carries the fields it claims,
-// a column whose type has drifted from its field's — both are ordinary during a
-// migration, so they are reported and not enforced.
-
-import type {
-  Catalog,
-  CatalogIndex,
-  Column,
-  Store,
-  Table,
-} from "../catalog";
-import {
-  aggregateBlocks,
-  blockFields,
-  mapsFieldPath,
-  relationOfColumnId,
-  storeViews,
-  viewReads,
-} from "../catalog";
-import type { Problem } from "./derive";
-import { payloadColumn, typesDisagree } from "./data-model";
-
-/** The context a store sits in, via the service that owns it. */
-function contextOf(index: CatalogIndex, serviceId: string): string {
-  return index.serviceContext.get(serviceId)?.id ?? "";
-}
-
-/**
- * Every persistence problem, stores in catalog order and tables in theirs.
- * Errors first within each store, so the boundary leaks are not buried under
- * a column-by-column type audit.
- */
-export function dataProblems(
-  catalog: Catalog,
-  index: CatalogIndex,
-): Problem[] {
-  const errors: Problem[] = [];
-  const warnings: Problem[] = [];
-
-  for (const store of catalog.stores ?? []) {
-    for (const table of store.tables) {
-      errors.push(...crossServiceKeys(index, store, table));
-      errors.push(...sharedStore(index, store, table));
-      warnings.push(...outboxWithoutPayload(index, store, table));
-      warnings.push(...drift(catalog, index, store, table));
-      warnings.push(...typeDrift(catalog, index, store, table));
-      warnings.push(
-        ...crossServiceLineage(index, store, table.id, table.columns),
-      );
-    }
-    for (const view of storeViews(store)) {
-      warnings.push(...crossServiceLineage(index, store, view.id, view.columns));
-      // A view is defined over what it reads, so a `reads` entry pointing into
-      // someone else's store is the same coupling stated one level up.
-      for (const readId of viewReads(view)) {
-        const target =
-          index.tableById.get(readId) ?? index.viewById.get(readId);
-        if (!target || target.store.owner === store.owner) continue;
-        warnings.push({
-          kind: "cross-service-lineage",
-          severity: "warning",
-          context: contextOf(index, store.owner),
-          service: store.owner,
-          id: view.id,
-          peer: readId,
-          note: `${view.id} is defined over ${readId}, which ${target.store.owner} owns; a rename over there breaks this view with no error until it is read.`,
-          source: view.source ?? store.source,
-        });
-      }
-    }
-  }
-
-  return [...errors, ...warnings];
-}
-
-/**
- * A foreign key into a table another service owns. The database will enforce
- * it, which is the problem: two services are now one schema, and neither can
- * migrate its own table without the other's release.
- */
-function crossServiceKeys(
-  index: CatalogIndex,
-  store: Store,
-  table: Table,
-): Problem[] {
-  const out: Problem[] = [];
-  for (const column of table.columns) {
-    if (!column.fk) continue;
-    const target = index.tableById.get(column.fk.table);
-    if (!target || target.store.owner === store.owner) continue;
-    out.push({
-      kind: "cross-service-fk",
-      severity: "error",
-      context: contextOf(index, store.owner),
-      service: store.owner,
-      id: `${table.id}.${column.name}`,
-      peer: column.fk.table,
-      note: `${store.owner} holds a foreign key into a table owned by ${target.store.owner}; neither service can migrate that table alone.`,
-      source: store.source,
-    });
-  }
-  return out;
-}
-
-/**
- * A column copied from another service's schema.
- *
- * Not an error: copying is how a projection is built, and the alternative — a
- * foreign key — is worse. It is a warning because the coupling is invisible
- * from the other side. Nothing in the source database records that someone
- * else's column is a copy of it, so the rename that breaks this is a rename
- * that looked safe.
- */
-function crossServiceLineage(
-  index: CatalogIndex,
-  store: Store,
-  relationId: string,
-  columns: Column[],
-): Problem[] {
-  const out: Problem[] = [];
-  const seen = new Set<string>();
-  for (const column of columns) {
-    for (const ref of column.from ?? []) {
-      const source = relationOfColumnId(ref);
-      const target =
-        index.tableById.get(source) ?? index.viewById.get(source);
-      if (!target || target.store.owner === store.owner) continue;
-      if (seen.has(ref)) continue;
-      seen.add(ref);
-      out.push({
-        kind: "cross-service-lineage",
-        severity: "warning",
-        context: contextOf(index, store.owner),
-        service: store.owner,
-        id: `${relationId}.${column.name}`,
-        peer: ref,
-        note: `${store.owner} copies this value from ${ref}, which ${target.store.owner} owns; nothing on that side records that the copy exists.`,
-        source: store.source,
-      });
-    }
-  }
-  return out;
-}
-
-/**
- * A table in one service's store that holds another service's aggregate. An
- * aggregate is written by the service that owns it, so this is a second writer
- * in someone else's database — reading is allowed and is drawn ghosted, but
- * this is not reading.
- */
-function sharedStore(
-  index: CatalogIndex,
-  store: Store,
-  table: Table,
-): Problem[] {
-  const aggregateId = table.persists?.aggregate;
-  if (!aggregateId) return [];
-  // A projection is a COPY of someone else's aggregate, maintained locally
-  // from their events. That is the pattern this rule exists to make room for,
-  // not the one it is looking for.
-  if (table.role === "projection") return [];
-  const writer = index.aggregateOwner.get(aggregateId);
-  if (!writer || writer.id === store.owner) return [];
-  return [
-    {
-      kind: "shared-store",
-      severity: "error",
-      context: contextOf(index, store.owner),
-      service: store.owner,
-      id: table.id,
-      peer: writer.id,
-      note: `${store.id} is owned by ${store.owner}, but this table holds ${aggregateId}, which ${writer.id} writes.`,
-      source: store.source,
-    },
-  ];
-}
-
-/**
- * An outbox with nothing to deliver. The whole point of the pattern is that the
- * event body is committed in the same transaction as the state change, so an
- * outbox with no payload column is either not an outbox or not finished.
- */
-function outboxWithoutPayload(
-  index: CatalogIndex,
-  store: Store,
-  table: Table,
-): Problem[] {
-  if (table.role !== "outbox" || payloadColumn(table)) return [];
-  return [
-    {
-      kind: "outbox-payload",
-      severity: "warning",
-      context: contextOf(index, store.owner),
-      service: store.owner,
-      id: table.id,
-      peer: store.id,
-      note: "an outbox carries the event body in the same transaction as the state change; this table declares no json column to hold one",
-      source: store.source,
-    },
-  ];
-}
-
-/**
- * A table that claims an aggregate none of its columns carry. Either the table
- * was relabelled and the columns were not, or the aggregate moved on without
- * it; both leave the `persists` claim asserting more than it can back up.
- */
-function drift(
-  catalog: Catalog,
-  index: CatalogIndex,
-  store: Store,
-  table: Table,
-): Problem[] {
-  const aggregateId = table.persists?.aggregate;
-  if (!aggregateId) return [];
-  // A derived table holds a copy shaped for reading, not the aggregate's own
-  // fields, so it has nothing to have drifted FROM. Only a table that claims
-  // to BE where the aggregate lives can contradict it.
-  if (table.role === "projection" || table.role === "outbox") return [];
-  const aggregate = index.aggregateById.get(aggregateId);
-  if (!aggregate) return [];
-
-  const declared = new Set<string>();
-  for (const { block } of aggregateBlocks(aggregate)) {
-    for (const field of blockFields(catalog, block)) declared.add(field.name);
-  }
-  // Nothing to drift from: an aggregate whose blocks are known by name only
-  // cannot contradict a schema.
-  if (declared.size === 0) return [];
-
-  const mapped = table.columns.filter((c) => {
-    if (!c.maps) return false;
-    const head = mapsFieldPath(c.maps).split(".")[0] ?? "";
-    return declared.has(head);
-  });
-  if (mapped.length > 0) return [];
-
-  const claimed = table.columns.filter((c) => c.maps).length;
-  return [
-    {
-      kind: "persistence-drift",
-      severity: "warning",
-      context: contextOf(index, store.owner),
-      service: store.owner,
-      id: table.id,
-      peer: aggregateId,
-      note:
-        claimed === 0
-          ? `no column of ${table.name} maps to a field of ${aggregateId}`
-          : `${claimed} column(s) of ${table.name} map to fields ${aggregateId} no longer declares`,
-      source: store.source,
-    },
-  ];
-}
-
-/**
- * A column and the field it carries that no longer agree on a type. One of the
- * two has been changed and the other has not; which one is the reader's call,
- * so the problem names both and stops there.
- */
-function typeDrift(
-  catalog: Catalog,
-  index: CatalogIndex,
-  store: Store,
-  table: Table,
-): Problem[] {
-  const out: Problem[] = [];
-  const aggregateId = table.persists?.aggregate;
-  const aggregate = aggregateId
-    ? index.aggregateById.get(aggregateId)
-    : undefined;
-  if (!aggregate) return out;
-
-  const fields = new Map<string, string>();
-  for (const { block } of aggregateBlocks(aggregate)) {
-    for (const field of blockFields(catalog, block)) {
-      // First declaration wins: two blocks of one aggregate naming the same
-      // field agree about it far more often than not, and a column mapping to
-      // "Id" is not made clearer by picking the second one.
-      if (!fields.has(field.name)) fields.set(field.name, field.type);
-    }
-  }
-
-  for (const column of table.columns) {
-    if (!column.maps) continue;
-    const head = mapsFieldPath(column.maps).split(".")[0] ?? "";
-    const domainType = fields.get(head);
-    if (!domainType || !typesDisagree(column.type, domainType)) continue;
-    out.push({
-      kind: "column-type",
-      severity: "warning",
-      context: contextOf(index, store.owner),
-      service: store.owner,
-      id: `${table.id}.${column.name}`,
-      peer: column.maps,
-      note: `column is ${column.type}, ${column.maps} is ${domainType}`,
-      source: store.source,
-    });
-  }
-  return out;
-}

package/src/lib/proto-problems.ts

@@ -1,237 +0,0 @@
-// Where a call and the interface it names disagree.
-//
-// docs/adr/org.0001.md promises this: producers publish their schema, consumers
-// keep a narrowed copy, and "a field, method or enum value that differs between
-// the two is reported against the consuming service". The extractor retains
-// those copies on the consumer; this reader compares them after every source
-// has met in the merged catalog.
-//
-// It is deliberately NOT done in the merge. src/merge.ts is documented as
-// union-by-id plus first-non-empty and nothing else, and teaching it to compare
-// shapes would put a semantic judgement in the one place that has none. The
-// comparison belongs here, over the merged catalog, on the page where the rest
-// of that judgement already lives.
-//
-// This is also NOT the same finding as derive.ts's `rpc` problem. That one is
-// about the PEER: a call whose other end is nobody the catalog knows. This one
-// is about a call whose peer is known and whose METHOD is not - the copy is
-// stale, or the producer removed something, and the two are different repairs.
-
-import type {
-  Catalog,
-  CatalogIndex,
-  RpcEnum,
-  RpcMessage,
-  RpcMethod,
-  RpcService,
-  Service,
-} from "../catalog";
-import type { Problem } from "./derive";
-
-/**
- * Every missing method and every retained consumer descriptor that disagrees
- * with the provider's method, field, or enum value.
- *
- * An unresolved call is skipped: it already has a problem of its own from
- * `problems()`, and reporting the same edge twice under two headings would make
- * the page look worse than the estate is.
- */
-export function protoProblems(
-  catalog: Catalog,
-  index: CatalogIndex,
-): Problem[] {
-  const out: Problem[] = [];
-
-  for (const context of catalog.contexts) {
-    for (const service of context.services) {
-      for (const call of service.consumes) {
-        if (call.status === "unresolved") continue;
-
-        // The peer has to be a service in the catalog before the method is
-        // worth asking about. A call to something outside the estate is a fact,
-        // not a defect.
-        if (!index.serviceById.has(call.peer)) continue;
-
-        if (index.rpcProviderByMethod.has(call.id)) continue;
-
-        out.push({
-          kind: "proto-missing",
-          // An error, not a staleness warning: the peer is in the catalog and
-          // does not answer on this. Either the copy is behind or the method is
-          // gone, and both are a call that will fail.
-          severity: "error",
-          context: context.id,
-          service: service.id,
-          id: call.id,
-          peer: call.peer,
-          note: call.note,
-          source: call.source,
-        });
-      }
-
-      for (const copy of service.copies ?? []) {
-        const drift = driftAgainstProvider(service, copy, index);
-        if (drift) out.push(drift);
-      }
-    }
-  }
-
-  return out;
-}
-
-/** Compare one consumer copy only when one of its calls resolves to a provider. */
-function driftAgainstProvider(
-  consumer: Service,
-  copy: RpcService,
-  index: CatalogIndex,
-): Problem | undefined {
-  const calls = new Map(
-    consumer.consumes
-      .filter((call) => call.id.startsWith(`${copy.id}/`))
-      .map((call) => [call.id, call]),
-  );
-  const resolved = copy.methods
-    .map((method) => calls.get(`${copy.id}/${method.name}`))
-    .find(
-      (call) =>
-        call?.status !== "unresolved" && index.serviceById.has(call?.peer ?? ""),
-    );
-  if (!resolved) return undefined;
-
-  const providerService = index.serviceById.get(resolved.peer);
-  const provider = providerService?.provides.find(
-    (candidate) => candidate.id === copy.id,
-  );
-  if (!providerService || !provider) return undefined;
-
-  const differences = compareInterfaces(copy, provider);
-  if (differences.length === 0) return undefined;
-
-  return {
-    kind: "proto-drift",
-    severity: "warning",
-    context: index.serviceContext.get(consumer.id)?.id ?? "",
-    service: consumer.id,
-    id: copy.id,
-    peer: providerService.id,
-    note: `Vendored copy differs from ${providerService.id}: ${differences.join("; ")}.`,
-    source: copy.source,
-  };
-}
-
-function compareInterfaces(copy: RpcService, provider: RpcService): string[] {
-  const out: string[] = [];
-  const methods = new Map(provider.methods.map((method) => [method.name, method]));
-
-  for (const method of copy.methods) {
-    const actual = methods.get(method.name);
-    // A missing method already has the stronger proto-missing error.
-    if (!actual) continue;
-    compareMethod(method, actual, out);
-  }
-
-  const messages = new Map(
-    (provider.messages ?? []).map((message) => [message.name, message]),
-  );
-  for (const message of copy.messages ?? []) {
-    compareMessage(message, messages.get(message.name), out);
-  }
-
-  const enums = new Map(
-    (provider.enums ?? []).map((item) => [item.name, item]),
-  );
-  for (const item of copy.enums ?? []) {
-    compareEnum(item, enums.get(item.name), out);
-  }
-
-  return out;
-}
-
-function compareMethod(
-  copy: RpcMethod,
-  provider: RpcMethod,
-  out: string[],
-): void {
-  for (const side of ["request", "response"] as const) {
-    if (copy[side] !== provider[side]) {
-      out.push(
-        `${copy.name} ${side} is ${copy[side] || "unnamed"}, provider has ${provider[side] || "unnamed"}`,
-      );
-    }
-  }
-  if (copy.streaming !== provider.streaming) {
-    out.push(
-      `${copy.name} streaming is ${copy.streaming ?? "unary"}, provider has ${provider.streaming ?? "unary"}`,
-    );
-  }
-}
-
-/**
- * A narrowed copy may omit provider fields it does not read. Every field it
- * does carry must still have the provider's type and protobuf number.
- */
-function compareMessage(
-  copy: RpcMessage,
-  provider: RpcMessage | undefined,
-  out: string[],
-): void {
-  if (!provider) {
-    out.push(`message ${copy.name} is absent from the provider`);
-    return;
-  }
-
-  const fields = new Map(provider.fields.map((field) => [field.name, field]));
-  for (const field of copy.fields) {
-    const actual = fields.get(field.name);
-    if (!actual) {
-      out.push(`${copy.name}.${field.name} is absent from the provider`);
-      continue;
-    }
-    if (field.type !== actual.type) {
-      out.push(
-        `${copy.name}.${field.name} is ${field.type}, provider has ${actual.type}`,
-      );
-    }
-    if (
-      field.number !== undefined &&
-      actual.number !== undefined &&
-      field.number !== actual.number
-    ) {
-      out.push(
-        `${copy.name}.${field.name} is field ${field.number}, provider has ${actual.number}`,
-      );
-    }
-  }
-}
-
-/** Enum names and numbers are both wire claims, so the sets must match whole. */
-function compareEnum(
-  copy: RpcEnum,
-  provider: RpcEnum | undefined,
-  out: string[],
-): void {
-  if (!provider) {
-    out.push(`enum ${copy.name} is absent from the provider`);
-    return;
-  }
-
-  const copyByName = new Map(copy.values.map((value) => [value.name, value]));
-  const providerByName = new Map(
-    provider.values.map((value) => [value.name, value]),
-  );
-  for (const value of copy.values) {
-    const actual = providerByName.get(value.name);
-    if (!actual) {
-      out.push(`${copy.name}.${value.name} is absent from the provider`);
-    } else if (value.number !== actual.number) {
-      out.push(
-        `${copy.name}.${value.name} is ${value.number}, provider has ${actual.number}`,
-      );
-    }
-  }
-  for (const value of provider.values) {
-    if (!copyByName.has(value.name)) {
-      out.push(`${copy.name}.${value.name} is missing from the copy`);
-    }
-  }
-}