@shortlink-org/portolan 0.2.4 → 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/selection/DetailPanel.tsx

@@ -1,3 +1,4 @@
+import { RelationEvidencePanel } from "../components/RelationEvidence";
 // The right rail. One panel, one selection, every page that draws a diagram.
 //
 // It renders by kind rather than by page, so an event opened from a flow reads
@@ -238,6 +239,10 @@ function ViewBody({
   return (
     <>
       {view.doc ? <p className="mt-2 text-muted">{view.doc}</p> : null}
+      <RelationEvidencePanel items={[
+        ...(view.source ? [{ kind: "contract" as const, rule: "sql-view-definition", source: view.source, symbol: view.name }] : []),
+        ...(view.persists?.evidence ?? []),
+      ]} renderSource={(source) => <SchemaEvidenceSource source={source} owner={store.owner} />} />
 
       <Label>Store</Label>
       <SelectLink id={store.id}>{store.id}</SelectLink>
@@ -344,6 +349,7 @@ function TableBody({
   return (
     <>
       {table.doc ? <p className="mt-2 text-muted">{table.doc}</p> : null}
+      <RelationEvidencePanel items={[...(table.evidence ?? []), ...(table.persists?.evidence ?? [])]} renderSource={(source) => <SchemaEvidenceSource source={source} owner={store.owner} />} />
 
       <Label>Store</Label>
       <SelectLink id={store.id}>{store.id}</SelectLink>
@@ -534,6 +540,11 @@ function ColumnBody({
   return (
     <>
       {column.doc ? <p className="mt-2 text-muted">{column.doc}</p> : null}
+      {(column.fk || column.from?.length || column.maps) ? <RelationEvidencePanel items={[
+        ...(table?.evidence ?? []),
+        ...(table?.persists?.evidence ?? []),
+        ...(view?.source ? [{ kind: "contract" as const, rule: "sql-view-definition", source: view.source, symbol: view.name }] : []),
+      ]} renderSource={(source) => <SchemaEvidenceSource source={source} owner={resolved.store.owner} />} /> : null}
 
       <Label>{view ? "View" : "Table"}</Label>
       {view ? (
@@ -1550,3 +1561,7 @@ export function WithDetail({
     </SavedGroup>
   );
 }
+
+function SchemaEvidenceSource({ source, owner }: { source: string; owner: string }) {
+  return <SourcePreviewLink location={sourceLocation(source, index.serviceById.get(owner), allRepos(catalog))} className="mono break-all text-muted hover:text-accent">{source}</SourcePreviewLink>;
+}

package/src/virtual-provenance.d.ts

@@ -0,0 +1,11 @@
+// The stamp of every catalog source, as the checkout's history says: served
+// by `scripts/provenance.mjs` at build time (portolan.0010). Keyed by the
+// path `src/data.ts` gives a source. A staged site imports its sources under
+// flattened names; `source` is then the path the file has in the workspace.
+declare module "virtual:portolan-provenance" {
+  const provenance: Record<
+    string,
+    { commit: string; generatedAt: string; source?: string }
+  >;
+  export default provenance;
+}

package/vite.config.ts

@@ -17,6 +17,10 @@ import { localApiPlugin } from "./scripts/local-api.mjs";
 // generator wrote them; the build copies the same files into dist.
 // @ts-expect-error plain JavaScript module intentionally has no browser types
 import { siteDocsPlugin } from "./scripts/site-docs.mjs";
+// When each catalog source last changed, read from git at build time and
+// served to the app as one virtual module (portolan.0010).
+// @ts-expect-error plain JavaScript module intentionally has no browser types
+import { provenancePlugin } from "./scripts/provenance.mjs";
 
 /** A git answer, or "" when there is nothing to answer with (no repo, no git). */
 function git(args: string): string {
@@ -160,6 +164,7 @@ export default defineConfig({
     // TypeScript below node_modules.
     localApiPlugin(workspace, publicSetupFrom),
     siteDocsPlugin(workspace),
+    provenancePlugin(workspace),
     react(),
     tailwindcss(),
     // The AsyncAPI reference brings a parser written for Node, and it calls

package/scripts/vendor-lock.mjs

@@ -1,58 +0,0 @@
-// The commit a vendored copy is of.
-//
-// `stampFor` dates a fragment from the last commit that touched the directory
-// it was read from, which is the right answer for code that lives here and the
-// wrong one for code that does not. A service fetched out of another
-// repository is stamped, without this, with the commit that VENDORED it: the
-// estate then reports the service as fresh because somebody re-ran the fetch,
-// and as unchanged when its own repository moved.
-//
-// The right answer is already on disk. `fetch-git` writes `git.lock.json`
-// beside each copy, naming the commit it fetched, and a copy re-fetched at the
-// same commit does not move it. Reading it here keeps the rule the host has
-// always kept - the host works out the stamp, never the plugin - while making
-// the subject of the stamp the code rather than the vendoring.
-
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-/** The file `fetch-git` writes beside every copy. Its name is that plugin's. */
-export const LOCK = "git.lock.json";
-
-/**
- * The commit `root` is a copy of, or null when it is not a copy of anything.
- *
- * Walks up from the directory the extractor was pointed at, because the lock
- * sits at the root of the repository's copy and the step reads a service some
- * way inside it: `vendor/repos/acme/shop/services/oms` is stamped by the lock
- * three levels above it. It stops at the repository root, so a run in a tree
- * with no vendored copies reads nothing and answers null.
- *
- * A lock naming other than exactly one repository is not one of these - the
- * fetcher writes one per directory - and is left to the fetcher to complain
- * about, which it does with the path and the count. Nothing here fails a run:
- * the caller has a git history to fall back on, and a stamp is not worth
- * refusing to describe an estate over.
- */
-export function vendoredCommit(root, read = readFileSync) {
-  for (let at = root; at && at !== "." && at !== "/"; at = dirname(at)) {
-    let raw;
-    try {
-      raw = read(join(at, LOCK), "utf8");
-    } catch {
-      continue; // No lock here; the copy's root may still be above.
-    }
-
-    try {
-      const lock = JSON.parse(raw);
-      const [only, ...rest] = lock.repos ?? [];
-      if (only?.commit && rest.length === 0) return only.commit;
-    } catch {
-      // Unreadable, which the fetcher reports against the copy itself.
-    }
-
-    return null;
-  }
-
-  return null;
-}

package/scripts/vendor-lock.test.mjs

@@ -1,69 +0,0 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-
-import { vendoredCommit } from "./vendor-lock.mjs";
-
-const COMMIT = "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0";
-
-describe("vendoredCommit", () => {
-  let root;
-
-  beforeEach(() => {
-    root = mkdtempSync(join(tmpdir(), "portolan-vendor-"));
-  });
-  afterEach(() => {
-    rmSync(root, { recursive: true, force: true });
-  });
-
-  const copy = (at, lock) => {
-    mkdirSync(join(root, at), { recursive: true });
-    writeFileSync(join(root, at, "git.lock.json"), JSON.stringify(lock));
-  };
-
-  // The case this exists for: the extractor is pointed at a service some way
-  // inside the copy, and the lock is at the copy's root.
-  it("reads the lock above the directory the extractor was given", () => {
-    copy("vendor/repos/acme/shop", { repos: [{ repo: "github.com/acme/shop", commit: COMMIT }] });
-    mkdirSync(join(root, "vendor/repos/acme/shop/services/oms"), { recursive: true });
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop/services/oms"))).toBe(COMMIT);
-  });
-
-  it("answers null for a directory that is nobody's copy", () => {
-    mkdirSync(join(root, "examples/shop/oms"), { recursive: true });
-
-    expect(vendoredCommit(join(root, "examples/shop/oms"))).toBeNull();
-  });
-
-  // The fetcher writes one repository per directory. Anything else is its
-  // problem to report, with the path and the count; a stamp is not worth
-  // failing a run over, so this stops rather than guessing which one won.
-  it("answers null for a lock naming more than one repository", () => {
-    copy("vendor/repos/acme/shop", {
-      repos: [
-        { repo: "github.com/acme/shop", commit: COMMIT },
-        { repo: "github.com/acme/pay", commit: "0000000" },
-      ],
-    });
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop"))).toBeNull();
-  });
-
-  it("answers null for a lock that cannot be read", () => {
-    mkdirSync(join(root, "vendor/repos/acme/shop"), { recursive: true });
-    writeFileSync(join(root, "vendor/repos/acme/shop/git.lock.json"), "{ not json");
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop"))).toBeNull();
-  });
-
-  // A copy nested inside another copy takes the innermost lock: it is the one
-  // that names the files the extractor is about to read.
-  it("takes the nearest lock", () => {
-    copy("vendor/repos/acme", { repos: [{ repo: "github.com/acme/outer", commit: "9999999" }] });
-    copy("vendor/repos/acme/shop", { repos: [{ repo: "github.com/acme/shop", commit: COMMIT }] });
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop"))).toBe(COMMIT);
-  });
-});

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;
-}