@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/lib/derive.ts

@@ -2,12 +2,14 @@
 // so every number a Phase 2 page shows can be asserted in a test.
 
 import type {
+  Aggregate,
   Block,
   BoundedContext,
   Catalog,
   Event,
   Field,
   Flow,
+  Operation,
   Service,
   Step,
 } from "../catalog";
@@ -185,6 +187,38 @@ export interface StepRef {
   number: number;
 }
 
+/**
+ * The flows in which an operation runs: one whose step carries the
+ * operation's own ref, `<aggregate id>/<operation id>` - a call across a
+ * boundary - or whose incoming rpc step is a method the operation says
+ * exposes it. Each flow once, at its first such step.
+ */
+export function flowsRunning(
+  catalog: Catalog,
+  service: Service,
+  aggregate: Aggregate,
+  operation: Operation,
+): StepRef[] {
+  const own = `${aggregate.id}/${operation.id}`;
+  const methods = new Set(
+    (operation.exposedBy ?? []).flatMap((method) =>
+      service.provides.map((provided) => `${provided.id}/${method}`),
+    ),
+  );
+  const out: StepRef[] = [];
+  for (const flow of catalog.flows) {
+    const steps = walkSteps(flow.steps);
+    const i = steps.findIndex(
+      (step) =>
+        step.ref !== undefined &&
+        (step.ref === own || (step.kind === "rpc" && methods.has(step.ref))),
+    );
+    const hit = steps[i];
+    if (hit) out.push({ flow, stepId: hit.id, number: i + 1 });
+  }
+  return out;
+}
+
 /** Every step across every flow that references an event, with its 1-based number. */
 export function stepsReferencing(catalog: Catalog, eventId: string): StepRef[] {
   const out: StepRef[] = [];
@@ -404,29 +438,6 @@ export function usesOfDef(catalog: Catalog, defId: string): DefUse {
 // Problems
 // ---------------------------------------------------------------------------
 
-/**
- * One edge in the estate that does not land. Two things can be wrong, and they
- * are wrong in the same way: a service calls an rpc whose provider is not in
- * the catalog, or an event names a consumer that is not either. Both mean the
- * chart draws an arrow into open water.
- */
-export type ProblemKind =
-  | "rpc"
-  | "consumer"
-  | "cross-service-fk"
-  | "cross-service-lineage"
-  | "shared-store"
-  | "persistence-drift"
-  | "column-type"
-  | "outbox-payload"
-  | "proto-missing"
-  | "proto-drift"
-  | "shared-channel"
-  | "channel-undeclared"
-  | "channel-unpublished"
-  | "message-encoding"
-  | "subscription-unresolved";
-
 /**
  * How wrong a problem is. Two values, not five: an edge either lands somewhere
  * the catalog knows about or it does not (an error), or the catalog holds two
@@ -435,26 +446,27 @@ export type ProblemKind =
  */
 export type Severity = "error" | "warning";
 
+/**
+ * One row of the Problems page: what a rule found, from the near end the
+ * reader can see. Every rule is CEL over one subject (rules/builtin.json for
+ * the ones the package ships, `problemRules` in the manifest for the estate's
+ * own), and `rule` says which; the subject says where `id` leads.
+ */
 export interface Problem {
-  kind: ProblemKind;
+  rule: string;
   severity: Severity;
   /** The context that owns the end we can see. */
   context: string;
   /** The service that owns the end we can see. */
   service: string;
-  /** The call id or the event id - what is on the near end of the edge. */
+  /** What is on the near end of the edge: the subject's id. */
   id: string;
-  /** The name that resolves to nothing. */
+  /** The far end, when the rule names one. */
   peer: string;
   note: string | undefined;
   source: string | undefined;
 }
 
-/**
- * Every unresolved edge, contexts in catalog order. Nothing is scored and
- * nothing is ranked: an unresolved consumer is exactly as broken as an
- * unresolved call, and sorting them by badness would invent a fact.
- */
 /**
  * How many edges there were to resolve at all - every rpc call a service makes
  * and every consumer an event names, whatever their status.
@@ -477,41 +489,3 @@ export function edgeCount(catalog: Catalog): number {
   return n;
 }
 
-export function problems(catalog: Catalog): 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;
-        out.push({
-          kind: "rpc",
-          severity: "error",
-          context: context.id,
-          service: service.id,
-          id: call.id,
-          peer: call.peer,
-          note: call.note,
-          source: call.source,
-        });
-      }
-      for (const aggregate of service.aggregates) {
-        for (const event of aggregate.events) {
-          for (const consumer of event.consumers) {
-            if (consumer.status !== "unresolved") continue;
-            out.push({
-              kind: "consumer",
-              severity: "error",
-              context: context.id,
-              service: service.id,
-              id: event.id,
-              peer: consumer.service,
-              note: consumer.note,
-              source: undefined,
-            });
-          }
-        }
-      }
-    }
-  }
-  return out;
-}

package/src/lib/django-aggregates.d.mts

@@ -0,0 +1,9 @@
+export interface DjangoAggregateCandidates {
+  app: string;
+  models: Array<{ name: string; path: string; line: number }>;
+}
+
+/** Evidence emitted by extract-django, carried through the warning protocol. */
+export function djangoAggregateCandidates(message: string): DjangoAggregateCandidates | null;
+
+export function djangoAggregateMessage(message: string): string;

package/src/lib/django-aggregates.mjs

@@ -0,0 +1,36 @@
+// Plain JavaScript on purpose: the CLI's `init` runs this from node_modules,
+// where Node strips no types, so the one parser the host and the browser
+// share cannot be a .ts file. Types live in django-aggregates.d.mts.
+
+const MARKER = "; aggregate candidates: ";
+
+/**
+ * Evidence emitted by extract-django, carried through the warning protocol.
+ *
+ * @param {string} message
+ * @returns {import("./django-aggregates.d.mts").DjangoAggregateCandidates | null}
+ */
+export function djangoAggregateCandidates(message) {
+  const start = message.lastIndexOf(MARKER);
+  if (start < 0) return null;
+  try {
+    const value = JSON.parse(message.slice(start + MARKER.length));
+    if (!value || typeof value.app !== "string" || !/^[\p{L}_][\p{L}\p{N}_]*(?:\.[\p{L}_][\p{L}\p{N}_]*)*$/u.test(value.app)
+      || !Array.isArray(value.models) || !value.models.length) return null;
+    const models = [];
+    for (const model of value.models) {
+      if (!model || typeof model.name !== "string" || !/^[\p{L}_][\p{L}\p{N}_]*$/u.test(model.name)
+        || typeof model.path !== "string" || !model.path || !Number.isSafeInteger(model.line) || model.line < 1) return null;
+      models.push({ name: model.name, path: model.path, line: model.line });
+    }
+    // The extractor's option accepts a class name, so duplicate names cannot
+    // be resolved safely by this picker.
+    if (new Set(models.map((model) => model.name)).size !== models.length) return null;
+    return { app: value.app, models };
+  } catch { return null; }
+}
+
+/** @param {string} message */
+export function djangoAggregateMessage(message) {
+  return djangoAggregateCandidates(message) ? message.slice(0, message.lastIndexOf(MARKER)) : message;
+}

package/src/lib/django-aggregates.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { djangoAggregateCandidates } from "./django-aggregates";
+import { warningDiagnostic } from "./warnings";
+import { publicSetupFrom } from "./setup-info";
+
+describe("Django aggregate evidence", () => {
+  const candidates = { app: "billing.records", models: Array.from({ length: 29 }, (_, index) => ({ name: `Record${index}`, path: "source/billing/records/models.py", line: index + 1 })) };
+  const message = `source/billing/records: no model called Records, and 29 models to choose from: name the root in the aggregates option; aggregate candidates: ${JSON.stringify(candidates)}`;
+
+  it("retains all candidates beyond the public warning text limit", () => {
+    const warning = warningDiagnostic({ plugin: "django-domain", message });
+    expect(warning.aggregateCandidates).toEqual(candidates);
+    expect(warning.message).not.toContain("aggregate candidates:");
+    const setup = publicSetupFrom({ sources: [], extract: [{ plugin: "django-domain", in: "source", out: "data" }] }, {
+      version: 1, manifestSha256: "current", mode: "write", status: "ok", startedAt: "2026-09-10T00:00:00Z", finishedAt: "2026-09-10T00:00:01Z", durationMs: 1000,
+      steps: [{ ordinal: 0, phase: "extract", plugin: "django-domain", input: "source", output: "data", status: "written", durationMs: 10, fileCount: 1, changedCount: 1, files: ["data/domain.json"], warnings: [message], diagnostics: [{ ...warning, message, count: 1, project: "", phase: "extract" }] }],
+    }, "current");
+    expect(setup.run?.steps[0]?.diagnostics[0]?.aggregateCandidates).toEqual(candidates);
+    expect(setup.run?.steps[0]?.diagnostics[0]?.message.length).toBeLessThan(500);
+  });
+
+  it("leaves old warnings usable and rejects malformed or duplicate choices", () => {
+    expect(djangoAggregateCandidates("legacy warning")).toBeNull();
+    expect(djangoAggregateCandidates("; aggregate candidates: {broken")).toBeNull();
+    for (const value of [{ app: "../records", models: candidates.models }, { ...candidates, models: [candidates.models[0], candidates.models[0]] }, { ...candidates, models: [{ name: "Record", path: "models.py", line: 0 }] }]) {
+      expect(djangoAggregateCandidates(`; aggregate candidates: ${JSON.stringify(value)}`)).toBeNull();
+    }
+  });
+});

package/src/lib/django-aggregates.ts

@@ -0,0 +1,5 @@
+// The parser itself is django-aggregates.mjs, which the CLI's `init` reads
+// from node_modules, where Node strips no types. This name is what the site
+// imports, so the .mjs stays the one place it is written.
+export { djangoAggregateCandidates, djangoAggregateMessage } from "./django-aggregates.mjs";
+export type { DjangoAggregateCandidates } from "./django-aggregates.mjs";

package/src/lib/environments.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import type { Catalog, Deployment } from "../catalog";
+import { narrowToEnvironments, servicesDeployedIn } from "./environments";
+
+const service = (id: string, path: string) => ({
+  id,
+  slug: id.split(".")[1] ?? id,
+  name: id,
+  repo: "github.com/acme/shop",
+  path,
+  readme: "",
+  provides: [],
+  consumes: [],
+  aggregates: [],
+});
+
+const placed = (name: string, environment: string, path: string, extra: Partial<Deployment> = {}): Deployment => ({
+  id: `argocd/${name}`,
+  name,
+  project: "shop",
+  environment,
+  cluster: "in-cluster",
+  namespace: "shop",
+  repo: "github.com/acme/shop",
+  path,
+  targetRevision: "main",
+  revision: "a".repeat(40),
+  tool: "kustomize",
+  url: `https://argocd.example.com/applications/argocd/${name}`,
+  ...extra,
+});
+
+const catalog: Catalog = {
+  generatedAt: "",
+  commit: "",
+  contexts: [
+    {
+      id: "shop",
+      slug: "shop",
+      name: "Shop",
+      summary: "",
+      services: [service("shop.cart", "services/cart"), service("shop.oms", "services/oms")],
+    },
+    {
+      id: "payments",
+      slug: "payments",
+      name: "Payments",
+      summary: "",
+      services: [service("payments.ledger", "services/ledger")],
+    },
+  ],
+  defs: {},
+  flows: [],
+  adrs: [],
+  deployments: [
+    placed("cart", "prod", "services/cart/deploy"),
+    placed("cart-staging", "staging", "services/cart/deploy"),
+    placed("oms", "prod", "services/oms/deploy"),
+    // No environment label and no cluster name: placed by the one word left.
+    placed("ledger", "", "services/ledger/deploy", { cluster: "" }),
+  ],
+};
+
+describe("the estate narrowed to an environment", () => {
+  it("names the services the snapshot places in the environments asked for", () => {
+    expect([...servicesDeployedIn(catalog, new Set(["prod"]))]).toEqual(["shop.cart", "shop.oms"]);
+    expect([...servicesDeployedIn(catalog, new Set(["staging"]))]).toEqual(["shop.cart"]);
+    expect([...servicesDeployedIn(catalog, new Set(["prod", "staging"]))]).toEqual(["shop.cart", "shop.oms"]);
+    expect([...servicesDeployedIn(catalog, new Set(["unplaced"]))]).toEqual(["payments.ledger"]);
+    expect(servicesDeployedIn(catalog, new Set(["nowhere"])).size).toBe(0);
+  });
+
+  it("keeps only the deployed services, drops a context left empty, and leaves the rest of the catalog alone", () => {
+    const staging = narrowToEnvironments(catalog, new Set(["staging"]));
+    expect(staging.contexts.map((c) => [c.id, c.services.map((s) => s.id)])).toEqual([["shop", ["shop.cart"]]]);
+    expect(staging.deployments).toBe(catalog.deployments);
+    expect(staging.flows).toBe(catalog.flows);
+  });
+
+  it("is the whole estate when no environment is chosen", () => {
+    expect(narrowToEnvironments(catalog, new Set())).toBe(catalog);
+  });
+});

package/src/lib/environments.ts

@@ -0,0 +1,57 @@
+// The estate narrowed to what runs somewhere.
+//
+// A map answers "who leans on whom"; with an environment chosen it answers
+// "who leans on whom IN STAGING" - and the honest way to answer that is to
+// take the services the snapshot does not place there out of the catalog
+// and let the same graph, map and counts run over what is left. A call to
+// a service that is not deployed there is then an edge that leaves the
+// chart, which is what it is. Nothing here is a second graph; it is the
+// first graph over a smaller estate.
+
+import type { Catalog } from "../catalog";
+import { allDeployments, deploys, environmentOf } from "../catalog";
+
+/** The ids of the services the snapshot places in any of the environments named. */
+export function servicesDeployedIn(
+  catalog: Catalog,
+  environments: ReadonlySet<string>,
+): Set<string> {
+  const placed = allDeployments(catalog).filter((deployment) =>
+    environments.has(environmentOf(deployment)),
+  );
+  const out = new Set<string>();
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      if (placed.some((deployment) => deploys(deployment, service))) {
+        out.add(service.id);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * The catalog with only the services deployed in the environments named,
+ * and only the contexts that still hold one. No environment named is the
+ * whole estate: an empty filter is no filter, as everywhere else in the app.
+ *
+ * Flows, ADRs, stores and terms are left as they are: a flow through a
+ * service that is not in staging is still the flow, and the reader asked
+ * about the map, not the archive.
+ */
+export function narrowToEnvironments(
+  catalog: Catalog,
+  environments: ReadonlySet<string>,
+): Catalog {
+  if (environments.size === 0) return catalog;
+  const kept = servicesDeployedIn(catalog, environments);
+  return {
+    ...catalog,
+    contexts: catalog.contexts
+      .map((context) => ({
+        ...context,
+        services: context.services.filter((service) => kept.has(service.id)),
+      }))
+      .filter((context) => context.services.length > 0),
+  };
+}

package/src/lib/integration-url.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { createIntegrationStore, normalizeIntegrationUrl } from "./integration-url";
+
+describe("integration URLs", () => {
+  it("accepts web URLs and rejects values that cannot be opened safely", () => {
+    expect(normalizeIntegrationUrl(" https://docs.example/ ")).toBe(
+      "https://docs.example",
+    );
+    expect(normalizeIntegrationUrl("https://docs.example/wiki#top")).toBe(
+      "https://docs.example/wiki",
+    );
+    expect(normalizeIntegrationUrl("javascript:alert(1)")).toBeNull();
+    expect(normalizeIntegrationUrl("not a URL")).toBeNull();
+    expect(normalizeIntegrationUrl("  ")).toBe("");
+  });
+
+  it("keeps a normalized value and ignores one that cannot be opened", () => {
+    // vitest runs under node, so the store keeps the value for this session
+    // only; what is asserted is the behaviour the page sees either way.
+    const store = createIntegrationStore("portolan.integrations.test");
+    store.getState().setUrl("https://docs.example/");
+    expect(store.getState().url).toBe("https://docs.example");
+
+    store.getState().setUrl("javascript:alert(1)");
+    expect(store.getState().url).toBe("https://docs.example");
+
+    store.getState().setUrl("");
+    expect(store.getState().url).toBe("");
+  });
+});

package/src/lib/integration-url.ts

@@ -0,0 +1,63 @@
+// What every reader-side integration shares: a web address the reader typed
+// in, kept in this browser and nowhere else.
+//
+// The value belongs to the reader, not to the catalog: two readers can point
+// the same generated estate at different installations. It therefore lives in
+// localStorage, like the editor and display preferences, and never reaches
+// portolan.json or a page that is committed.
+
+import { create } from "zustand";
+
+/**
+ * A trimmed http(s) URL without its fragment and trailing slash, "" for an
+ * empty value, and null for anything that cannot be opened safely - a
+ * javascript: address, or words that are not a URL at all.
+ */
+export function normalizeIntegrationUrl(value: string): string | null {
+  const clean = value.trim();
+  if (!clean) return "";
+  try {
+    const url = new URL(clean);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+export interface IntegrationState {
+  url: string;
+  setUrl: (url: string) => void;
+}
+
+/** One store per integration, read from localStorage under its own key. */
+export function createIntegrationStore(key: string) {
+  const read = (): string => {
+    try {
+      const value = localStorage.getItem(key) ?? "";
+      return normalizeIntegrationUrl(value) ?? "";
+    } catch {
+      return "";
+    }
+  };
+
+  const write = (value: string): void => {
+    try {
+      if (value) localStorage.setItem(key, value);
+      else localStorage.removeItem(key);
+    } catch {
+      /* private mode: keep the value for this session */
+    }
+  };
+
+  return create<IntegrationState>()((set) => ({
+    url: read(),
+    setUrl: (url) => {
+      const normalized = normalizeIntegrationUrl(url);
+      if (normalized === null) return;
+      write(normalized);
+      set({ url: normalized });
+    },
+  }));
+}

package/src/lib/kafka-ui.ts

@@ -7,24 +7,13 @@
 // installation URL remains useful and opens Kafka UI without inventing a
 // cluster name.
 
-import { create } from "zustand";
 import type { Catalog, Channel } from "../catalog";
 import { walkSteps } from "../catalog";
+import { createIntegrationStore, normalizeIntegrationUrl } from "./integration-url";
 
 export const KAFKA_UI_KEY = "portolan.integrations.kafka-ui";
 
-export function normalizeKafkaUiUrl(value: string): string | null {
-  const clean = value.trim();
-  if (!clean) return "";
-  try {
-    const url = new URL(clean);
-    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
-    url.hash = "";
-    return url.toString().replace(/\/$/, "");
-  } catch {
-    return null;
-  }
-}
+export const normalizeKafkaUiUrl = normalizeIntegrationUrl;
 
 /** Build Kafbat's topic route when the configured URL names a cluster. */
 export function kafkaUiTopicUrl(
@@ -71,35 +60,4 @@ export function isKafkaChannel(
     || handoffChannels.has(channel.address);
 }
 
-function read(): string {
-  try {
-    const value = localStorage.getItem(KAFKA_UI_KEY) ?? "";
-    return normalizeKafkaUiUrl(value) ?? "";
-  } catch {
-    return "";
-  }
-}
-
-function write(value: string): void {
-  try {
-    if (value) localStorage.setItem(KAFKA_UI_KEY, value);
-    else localStorage.removeItem(KAFKA_UI_KEY);
-  } catch {
-    /* private mode: keep the value for this session */
-  }
-}
-
-interface KafkaUiState {
-  url: string;
-  setUrl: (url: string) => void;
-}
-
-export const useKafkaUi = create<KafkaUiState>()((set) => ({
-  url: read(),
-  setUrl: (url) => {
-    const normalized = normalizeKafkaUiUrl(url);
-    if (normalized === null) return;
-    write(normalized);
-    set({ url: normalized });
-  },
-}));
+export const useKafkaUi = createIntegrationStore(KAFKA_UI_KEY);