@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/lib/plugins.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import {
+  CATEGORY_ORDER,
+  hasPluginLabel,
+  landingInputs,
+  pluginIcon,
+  pluginIndex,
+  pluginsByCategory,
+  runtimeLabel,
+} from "./plugins";
+import { techGlyph } from "./tech";
+
+describe("plugin index", () => {
+  it("is written by npm run schema and names every plugin once", () => {
+    expect(pluginIndex.length).toBeGreaterThan(0);
+    const names = pluginIndex.map((entry) => entry.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it("gives every plugin a category the page has a heading for and a phase to run in", () => {
+    for (const entry of pluginIndex) {
+      expect(CATEGORY_ORDER, entry.name).toContain(entry.category);
+      expect(entry.phases.length, entry.name).toBeGreaterThan(0);
+      expect(entry.summary, entry.name).not.toBe("");
+    }
+  });
+
+  // A plugin added without a display name would reach the landing page as its
+  // manifest key. This is the test that says so before a reader does.
+  it("has a display name for every plugin", () => {
+    const unnamed = pluginIndex.filter((entry) => !hasPluginLabel(entry.name)).map((entry) => entry.name);
+    expect(unnamed).toEqual([]);
+  });
+
+  // A brand named here that the mark list does not carry would draw as the
+  // generic code glyph, which is a wrong picture rather than a missing one.
+  it("resolves every brand mark it names", () => {
+    const unresolved = pluginIndex
+      .map((entry) => pluginIcon(entry.name, entry.category))
+      .filter((icon): icon is { brand: string } => "brand" in icon && techGlyph(icon.brand) === null)
+      .map((icon) => icon.brand);
+    expect(unresolved).toEqual([]);
+  });
+
+  it("falls back to the category's glyph for a plugin nobody named", () => {
+    expect(pluginIcon("something-new", "messaging")).toEqual({ lucide: "message" });
+  });
+
+  it("groups by category in reading order and drops empty groups", () => {
+    const groups = pluginsByCategory();
+    const order = groups.map((group) => group.category);
+    expect(order).toEqual(CATEGORY_ORDER.filter((category) => order.includes(category)));
+    for (const group of groups) expect(group.plugins.length).toBeGreaterThan(0);
+  });
+
+  it("lists what is read on the landing page, not what is made", () => {
+    const inputs = landingInputs();
+    expect(inputs.map((group) => group.label)).toContain("languages");
+    expect(inputs.flatMap((group) => group.items)).toContain("Go");
+    expect(inputs.flatMap((group) => group.items)).not.toContain("Markdown");
+  });
+
+  it("names the toolchain a host process asks for", () => {
+    expect(runtimeLabel({ runtime: "wasm" } as never)).toBe("WASM sandbox");
+    expect(runtimeLabel({ runtime: "host" } as never)).toBe("in the host");
+    expect(runtimeLabel({ runtime: "process", toolchain: "cargo" } as never)).toBe("host process · cargo");
+  });
+});

package/src/lib/plugins.ts

@@ -0,0 +1,264 @@
+// The plugin index: every plugin the package ships, as it describes itself.
+//
+// `src/lib/plugin-index.json` is written by `npm run schema` from the answer
+// each plugin gives to `describe` and from how portolan.json runs it. Nothing
+// here is typed by hand except the words a reader sees: the category titles,
+// and a display name per plugin, because "go-sqs" is a manifest key and "SQS"
+// is what the landing page says.
+
+import { PRODUCT_REPOSITORY } from "./product";
+import raw from "./plugin-index.json";
+
+export type PluginCategory =
+  | "code"
+  | "contracts"
+  | "messaging"
+  | "data"
+  | "infrastructure"
+  | "repository"
+  | "documents"
+  | "evidence"
+  | "sources"
+  | "exports";
+
+export type PluginPhase = "extract" | "verify" | "generate";
+
+export interface PluginOption {
+  type?: string | string[];
+  description?: string;
+}
+
+export interface PluginEntry {
+  /** The name the manifest declares it under - what a step names. */
+  name: string;
+  /** What the plugin calls itself: its directory under plugins/. */
+  plugin: string;
+  summary: string;
+  category: PluginCategory;
+  phases: PluginPhase[];
+  needs?: string[];
+  runtime: "wasm" | "process" | "host";
+  /** The command a host process asks the build for; absent for a module. */
+  toolchain?: string;
+  /** Repository-relative path to the plugin's source. */
+  source: string;
+  options: {
+    properties?: Record<string, PluginOption>;
+    required?: string[];
+  };
+}
+
+// The JSON's inferred type is the union of every plugin's option keys, which
+// is why the cast goes through unknown: the shape is what matters, not which
+// keys one file happens to have.
+export const pluginIndex: PluginEntry[] = raw as unknown as PluginEntry[];
+
+/** The order the categories read in: what is read first, then what is made. */
+export const CATEGORY_ORDER: PluginCategory[] = [
+  "code",
+  "contracts",
+  "messaging",
+  "data",
+  "infrastructure",
+  "repository",
+  "documents",
+  "evidence",
+  "sources",
+  "exports",
+];
+
+/**
+ * A glyph without a brand: one of the lucide icons PluginIcon knows to draw.
+ * Named here as words rather than components so this module stays free of
+ * React and the tests can read it.
+ */
+export type PluginGlyph =
+  | "code"
+  | "contract"
+  | "message"
+  | "database"
+  | "cloud"
+  | "repository"
+  | "pen"
+  | "shield"
+  | "fork"
+  | "share"
+  | "inbox"
+  | "file-code"
+  | "package"
+  | "waves"
+  | "workflow"
+  | "users"
+  | "globe"
+  | "terminal"
+  | "book"
+  | "spell-check"
+  | "route";
+
+/** A brand's own mark, looked up by the name `techGlyph` answers to, or a lucide glyph. */
+export type PluginIconSpec = { brand: string } | { lucide: PluginGlyph };
+
+export const CATEGORY_LABEL: Record<PluginCategory, { title: string; what: string; icon: PluginGlyph }> = {
+  code: {
+    title: "Languages",
+    what: "The aggregates, events and use cases a service declares in its source.",
+    icon: "code",
+  },
+  contracts: {
+    title: "Contracts",
+    what: "What a service provides and calls, read from the interface it publishes.",
+    icon: "contract",
+  },
+  messaging: {
+    title: "Queues and topics",
+    what: "The subjects, queues and jobs a service sends on and listens to.",
+    icon: "message",
+  },
+  data: {
+    title: "Data stores",
+    what: "The stores a service keeps, and the shape of what is in them.",
+    icon: "database",
+  },
+  infrastructure: {
+    title: "Infrastructure",
+    what: "What a service is deployed on, and the wiring between the pieces that only the infrastructure knows.",
+    icon: "cloud",
+  },
+  repository: {
+    title: "Repository",
+    what: "What the repository says about itself: its metadata and its task runners.",
+    icon: "repository",
+  },
+  documents: {
+    title: "Written by hand",
+    what: "Decisions, glossaries and flows that people wrote down.",
+    icon: "pen",
+  },
+  evidence: {
+    title: "Evidence",
+    what: "The catalog checked against something outside the code.",
+    icon: "shield",
+  },
+  sources: {
+    title: "Other repositories",
+    what: "Trees fetched from elsewhere, pinned, for the extractors to read.",
+    icon: "fork",
+  },
+  exports: {
+    title: "Exports",
+    what: "The catalog turned into something else.",
+    icon: "share",
+  },
+};
+
+/**
+ * What a plugin is called where a person reads it, and the mark beside the
+ * name, keyed by manifest name. A brand mark where the plugin reads one
+ * technology and the reader knows its logo; a lucide glyph where it reads a
+ * format or a convention that has none.
+ */
+const PLUGIN_META: Record<string, { label: string; icon: PluginIconSpec }> = {
+  project: { label: "Project metadata", icon: { lucide: "repository" } },
+  commands: { label: "Task runners", icon: { lucide: "terminal" } },
+  "go-domain": { label: "Go", icon: { brand: "Go" } },
+  "ts-domain": { label: "TypeScript", icon: { brand: "TypeScript" } },
+  "rust-domain": { label: "Rust", icon: { brand: "Rust" } },
+  "laravel-domain": { label: "Laravel", icon: { brand: "Laravel" } },
+  "php-ddd": { label: "PHP by context", icon: { brand: "Symfony" } },
+  "csharp-ddd": { label: "C# by module", icon: { brand: "C#" } },
+  "java-domain": { label: "Java", icon: { brand: "Java" } },
+  "django-domain": { label: "Django", icon: { brand: "Django" } },
+  celery: { label: "Celery", icon: { brand: "Celery" } },
+  "python-kafka": { label: "Kafka", icon: { brand: "Kafka" } },
+  openapi: { label: "OpenAPI", icon: { brand: "OpenAPI" } },
+  wsdl: { label: "WSDL", icon: { lucide: "file-code" } },
+  "http-clients": { label: "HTTP clients", icon: { lucide: "globe" } },
+  redis: { label: "Redis", icon: { brand: "Redis" } },
+  river: { label: "River", icon: { lucide: "waves" } },
+  watermill: { label: "Watermill", icon: { lucide: "workflow" } },
+  "go-nats": { label: "NATS", icon: { brand: "NATS" } },
+  "go-sqs": { label: "SQS", icon: { lucide: "inbox" } },
+  terraform: { label: "Terraform", icon: { brand: "Terraform" } },
+  k8s: { label: "Kubernetes manifests", icon: { brand: "Kubernetes" } },
+  "k8s-cluster": { label: "Kubernetes cluster", icon: { brand: "Kubernetes" } },
+  asyncapi: { label: "AsyncAPI", icon: { lucide: "file-code" } },
+  graphql: { label: "GraphQL", icon: { brand: "GraphQL" } },
+  sql: { label: "SQL", icon: { lucide: "database" } },
+  markdown: { label: "Markdown", icon: { brand: "Markdown" } },
+  mermaid: { label: "Mermaid", icon: { brand: "Mermaid" } },
+  backstage: { label: "Backstage", icon: { brand: "Backstage" } },
+  otel: { label: "OpenTelemetry", icon: { brand: "OpenTelemetry" } },
+  codeowners: { label: "CODEOWNERS", icon: { lucide: "users" } },
+  adr: { label: "Decision records", icon: { lucide: "book" } },
+  glossary: { label: "Glossary", icon: { lucide: "spell-check" } },
+  flows: { label: "Flows", icon: { lucide: "route" } },
+  bsr: { label: "Buf Schema Registry", icon: { lucide: "package" } },
+  git: { label: "Git", icon: { brand: "Git" } },
+  csr: { label: "Confluent Schema Registry", icon: { lucide: "package" } },
+  argocd: { label: "Argo CD", icon: { lucide: "cloud" } },
+  "argocd-gitops": { label: "Argo CD manifests", icon: { lucide: "cloud" } },
+  "csr-schemas": { label: "Registry schemas", icon: { lucide: "file-code" } },
+  proto: { label: "Protobuf", icon: { lucide: "file-code" } },
+};
+
+export function pluginLabel(name: string): string {
+  return PLUGIN_META[name]?.label ?? name;
+}
+
+/** True when the plugin has a name a reader would recognise, not a manifest key. */
+export function hasPluginLabel(name: string): boolean {
+  return name in PLUGIN_META;
+}
+
+/** The mark beside a plugin's name; a plugin nobody named yet gets its category's glyph. */
+export function pluginIcon(name: string, category?: PluginCategory): PluginIconSpec {
+  return PLUGIN_META[name]?.icon ?? { lucide: CATEGORY_LABEL[category ?? "code"].icon };
+}
+
+export function pluginByName(name: string): PluginEntry | undefined {
+  return pluginIndex.find((entry) => entry.name === name);
+}
+
+export interface PluginGroup {
+  category: PluginCategory;
+  title: string;
+  what: string;
+  icon: PluginGlyph;
+  plugins: PluginEntry[];
+}
+
+/** The index by category, in reading order, each group sorted by display name. */
+export function pluginsByCategory(entries: PluginEntry[] = pluginIndex): PluginGroup[] {
+  return CATEGORY_ORDER.map((category) => ({
+    category,
+    ...CATEGORY_LABEL[category],
+    plugins: entries
+      .filter((entry) => entry.category === category)
+      .sort((a, b) => pluginLabel(a.name).localeCompare(pluginLabel(b.name))),
+  })).filter((group) => group.plugins.length > 0);
+}
+
+/** The categories the landing page lists as inputs: what is read, not what is made. */
+const LANDING_CATEGORIES: PluginCategory[] = ["code", "contracts", "messaging", "data", "evidence"];
+
+/** One line per input category, the display names of what reads it. */
+export function landingInputs(entries: PluginEntry[] = pluginIndex): { label: string; items: string[] }[] {
+  return pluginsByCategory(entries)
+    .filter((group) => LANDING_CATEGORIES.includes(group.category))
+    .map((group) => ({
+      label: group.title.toLowerCase(),
+      items: group.plugins.map((entry) => pluginLabel(entry.name)),
+    }));
+}
+
+/** Where the plugin's source is read, on the public repository. */
+export function pluginSourceHref(entry: PluginEntry): string {
+  return `${PRODUCT_REPOSITORY}/tree/main/${entry.source}`;
+}
+
+/** The runtime as a reader would say it. */
+export function runtimeLabel(entry: PluginEntry): string {
+  if (entry.runtime === "wasm") return "WASM sandbox";
+  if (entry.runtime === "host") return "in the host";
+  return entry.toolchain ? `host process · ${entry.toolchain}` : "host process";
+}

package/src/lib/problem-flows.test.ts

@@ -0,0 +1,61 @@
+// A problem row leads to the step that crosses its edge, or to the flows
+// its service is on when the subject is not an edge.
+
+import { describe, expect, it } from "vitest";
+import { rawCatalog } from "../test-catalog";
+import { buildIndex, validateCatalog, walkSteps } from "../catalog";
+import type { Catalog } from "../catalog";
+import type { Problem } from "./derive";
+import { flowsOfProblem } from "./problem-flows";
+
+const catalog = validateCatalog(JSON.parse(JSON.stringify(rawCatalog)) as unknown as Catalog);
+const index = buildIndex(catalog);
+
+const problem = (id: string, service: string): Problem => ({ rule: "x", severity: "warning", context: "", service, id, peer: "", note: undefined, source: undefined });
+
+/** The first step in the estate of one kind with a ref, and its flow and number. */
+function firstStep(kind: "rpc" | "event") {
+  for (const flow of catalog.flows) {
+    const steps = walkSteps(flow.steps);
+    const at = steps.findIndex((step) => step.kind === kind && step.ref);
+    if (at >= 0) return { flow, step: steps[at]!, number: at + 1 };
+  }
+  throw new Error(`the fixture has no ${kind} step with a ref`);
+}
+
+describe("flowsOfProblem", () => {
+  it("lands a call on the step that makes it", () => {
+    const { flow, step, number } = firstStep("rpc");
+    const hits = flowsOfProblem(catalog, index, "call", problem(step.ref!, step.from));
+    expect(hits.map((hit) => hit.flow.id)).toContain(flow.id);
+    const hit = hits.find((candidate) => candidate.flow.id === flow.id)!;
+    expect(hit.stepId).toBe(step.id);
+    expect(hit.number).toBe(number);
+  });
+
+  it("lands an event on the step that carries it, once per flow", () => {
+    const { flow, step } = firstStep("event");
+    const hits = flowsOfProblem(catalog, index, "event", problem(step.ref!, step.from));
+    expect(hits.some((hit) => hit.flow.id === flow.id && hit.stepId === step.id)).toBe(true);
+    expect(new Set(hits.map((hit) => hit.flow.id)).size).toBe(hits.length);
+  });
+
+  it("lands a table on the steps that touch its store", () => {
+    const access = catalog.flows.flatMap((flow) => walkSteps(flow.steps)).find((step) => step.storeAccess);
+    if (!access?.storeAccess) return;
+    const store = index.storeById.get(access.storeAccess.store)!;
+    const table = store.tables[0]!;
+    const hits = flowsOfProblem(catalog, index, "table", problem(table.id, store.owner));
+    expect(hits.length).toBeGreaterThan(0);
+    expect(hits.every((hit) => hit.stepId !== undefined)).toBe(true);
+    expect(flowsOfProblem(catalog, index, "column", problem(`${table.id}.${table.columns[0]!.name}`, store.owner)).length).toBe(hits.length);
+  });
+
+  it("gives a service-shaped row the flows the service is on, without a step", () => {
+    const service = catalog.contexts[0]!.services[0]!;
+    const hits = flowsOfProblem(catalog, index, "service", problem(service.id, service.id));
+    expect(hits.length).toBe(catalog.flows.filter((flow) => flow.participants.some((p) => p.id === service.id)).length);
+    expect(hits.every((hit) => hit.stepId === undefined)).toBe(true);
+    expect(flowsOfProblem(catalog, index, "deployment", problem("argocd/x", ""))).toEqual([]);
+  });
+});

package/src/lib/problem-flows.ts

@@ -0,0 +1,78 @@
+// Where a problem's edge is met in the flows.
+//
+// A row on the Problems page names one end of an edge; the flows are where
+// that edge is crossed, and the flow's page is where a reader sees what
+// happens before and after it. So a row that knows its flows leads to the
+// step, not to the flow's first line - and a row whose subject is a service
+// leads to the flows the service is on, which is the best a service-shaped
+// row can do.
+
+import type { Catalog, CatalogIndex, Flow } from "../catalog";
+import { walkSteps } from "../catalog";
+import type { Problem } from "./derive";
+import type { RuleSubject } from "./problem-rules-cel.mjs";
+
+export interface FlowHit {
+  flow: Flow;
+  /** The step that crosses the edge, when one does; a flow the service is merely on has none. */
+  stepId?: string;
+  number?: number;
+}
+
+/** The store a table's or a column's id is under, by longest known prefix. */
+function storeOf(index: CatalogIndex, id: string): string | null {
+  const parts = id.split(".");
+  for (let n = parts.length - 1; n >= 1; n -= 1) {
+    const candidate = parts.slice(0, n).join(".");
+    if (index.storeById.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+function stepsWhere(catalog: Catalog, matches: (step: ReturnType<typeof walkSteps>[number]) => boolean): FlowHit[] {
+  const out: FlowHit[] = [];
+  for (const flow of catalog.flows) {
+    const steps = walkSteps(flow.steps);
+    const at = steps.findIndex(matches);
+    if (at >= 0) out.push({ flow, stepId: steps[at]!.id, number: at + 1 });
+  }
+  return out;
+}
+
+function flowsOn(catalog: Catalog, serviceId: string): FlowHit[] {
+  if (!serviceId) return [];
+  return catalog.flows.filter((flow) => flow.participants.some((participant) => participant.id === serviceId)).map((flow) => ({ flow }));
+}
+
+/**
+ * The flows a problem is met in, one hit per flow, the crossing step first
+ * when the subject is an edge and the service's flows when it is not.
+ */
+export function flowsOfProblem(catalog: Catalog, index: CatalogIndex, over: RuleSubject, problem: Problem): FlowHit[] {
+  switch (over) {
+    case "call":
+      return stepsWhere(catalog, (step) => step.ref === problem.id);
+    // A channel row is an event when the service has one on the address and
+    // the service otherwise; the second kind has no step to land on.
+    case "event":
+    case "consumer":
+    case "channel": {
+      const hits = stepsWhere(catalog, (step) => step.ref === problem.id);
+      return hits.length > 0 || index.eventById.has(problem.id) ? hits : flowsOn(catalog, problem.service);
+    }
+    case "table":
+    case "column": {
+      const store = storeOf(index, problem.id);
+      return store ? stepsWhere(catalog, (step) => step.storeAccess?.store === store) : [];
+    }
+    case "flow":
+      return catalog.flows.filter((flow) => flow.id === problem.id).map((flow) => ({ flow }));
+    case "aggregate":
+      return stepsWhere(catalog, (step) => step.ref?.startsWith(`${problem.id}.`) === true || step.ref?.startsWith(`${problem.id}/`) === true);
+    case "service":
+    case "copy":
+    case "subscription":
+    case "deployment":
+      return flowsOn(catalog, problem.service);
+  }
+}

package/src/lib/problem-rules-cel.d.mts

@@ -0,0 +1,43 @@
+export type RuleSubject =
+  | "service"
+  | "call"
+  | "copy"
+  | "event"
+  | "consumer"
+  | "channel"
+  | "subscription"
+  | "table"
+  | "column"
+  | "deployment"
+  | "flow"
+  | "aggregate";
+
+export type RuleSeverity = "error" | "warning";
+
+/** A CEL type name, as the schema spells it. */
+export type FieldType = "string" | "int" | "bool" | "list<string>";
+
+export interface SubjectDefinition {
+  description: string;
+  schema: Record<string, FieldType>;
+}
+
+export const SUBJECTS: Record<RuleSubject, SubjectDefinition>;
+export const ESTATE_SCHEMA: Record<string, FieldType>;
+export const SUBJECT_NAMES: RuleSubject[];
+export const SEVERITIES: RuleSeverity[];
+export const RULE_ID: RegExp;
+
+/** A parsed expression: call it with the context to evaluate. */
+export type CompiledExpression = (context: Record<string, unknown>) => unknown;
+
+export function environmentFor(subject: RuleSubject): unknown;
+
+export function compileExpression(subject: RuleSubject, source: string, type: "bool" | "string"): CompiledExpression;
+
+export function problemRuleProblems(entries: unknown, builtinIds: Iterable<string>, path?: string): string[];
+
+export function ruleExpressionProblems(
+  rule: { id: string; over?: string; title?: string; when?: string; message?: string; peer?: string },
+  at?: string,
+): string[];