@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/lib/warnings.ts

@@ -0,0 +1,260 @@
+import { djangoAggregateCandidates, djangoAggregateMessage } from "./django-aggregates";
+import type { DjangoAggregateCandidates } from "./django-aggregates";
+
+export type WarningSeverity = "error" | "warning" | "info";
+
+export interface RawWarning {
+  plugin: string;
+  message: string;
+}
+
+export interface WarningDiagnostic extends RawWarning {
+  aggregateCandidates?: DjangoAggregateCandidates;
+  rule: string;
+  severity: WarningSeverity;
+  action: string;
+  count?: number;
+  project?: string;
+  phase?: string;
+  ref?: string;
+  suppressed: boolean;
+  suppressionReason?: string;
+}
+
+export interface WarningGroup {
+  plugin: string;
+  rule: string;
+  severity: WarningSeverity;
+  action: string;
+  messages: WarningDiagnostic[];
+  count: number;
+  suppressed: boolean;
+  suppressionReason?: string;
+}
+
+interface RuleDefinition {
+  id: string;
+  matches: RegExp;
+  severity: WarningSeverity;
+  action: string;
+}
+
+// Rules describe the recurring limitation, not the source-specific value in a
+// message. Their ids are therefore stable enough to use in portolan.json.
+const RULES: RuleDefinition[] = [
+  {
+    id: "openapi.missing-operation-id",
+    matches: /\bno operationId\b/i,
+    severity: "warning",
+    action: "Add stable operationId values to the OpenAPI operations.",
+  },
+  {
+    id: "schema.duplicate-declaration",
+    matches: /\bduplicate declaration\b/i,
+    severity: "warning",
+    action: "Remove or reconcile duplicate schema declarations; Portolan currently uses the first.",
+  },
+  {
+    id: "analysis.typed-fallback",
+    matches: /\btyped call graph unavailable\b/i,
+    severity: "warning",
+    action: "Run an extractor build with typed analysis support or inspect calls found by the syntax fallback.",
+  },
+  {
+    id: "catalog.unresolved-call",
+    matches: /\bcalls .+ which nothing in this catalog resolves\b/i,
+    severity: "warning",
+    action: "Add or correct the provider contract, then regenerate to resolve the call.",
+  },
+  {
+    id: "catalog.unmapped-proto-peer",
+    matches: /\bmanifest names no peer for (?:that package|it)\b/i,
+    severity: "warning",
+    action: "Map the protobuf package under peers, or declare it under externals.",
+  },
+  {
+    id: "flow.unresolved-step",
+    matches: /\bstep .+ is unresolved\b/i,
+    severity: "warning",
+    action: "Declare the referenced endpoint, message, or store so this flow step can be joined.",
+  },
+  {
+    id: "flow.unknown-port",
+    matches: /\bis neither a domain port(?:,| nor) a use case\b/i,
+    severity: "warning",
+    action: "Model this dependency as a domain port or use case, or accept that its calls stay outside the flow.",
+  },
+  {
+    id: "flow.unreached-event",
+    matches: /\bno flow reaches this event\b/i,
+    severity: "warning",
+    action: "Connect the event to its publisher flow or remove the stale event declaration.",
+  },
+  {
+    id: "flow.unknown-event",
+    matches: /\breacts to the message named .+ which no event .+ declares is called\b/i,
+    severity: "warning",
+    action: "Declare the event name used by the handler or correct the handler mapping.",
+  },
+  {
+    id: "django.invalid-aggregate-root",
+    matches: /\baggregates names .+ and no model there is called that\b/i,
+    severity: "warning",
+    action: "Choose an existing concrete model for the application's aggregates option.",
+  },
+  {
+    id: "django.unknown-http-verb",
+    matches: /\bmounted as an HTTP view, but no HTTP verb is declared\b/i,
+    severity: "warning",
+    action: "Declare the accepted HTTP methods on the view or route.",
+  },
+  {
+    id: "river.missing-worker",
+    matches: /\bno registered Worker\b/i,
+    severity: "warning",
+    action: "Register the River worker in this component or remove the unmatched insert.",
+  },
+  {
+    id: "watermill.unresolved-topic",
+    matches: /\bWatermill .+\btopic (?:generator could not be resolved|unresolved)\b/i,
+    severity: "warning",
+    action: "Use a literal, constant, or configuration default for the Watermill topic.",
+  },
+  {
+    id: "messaging.unresolved-subject",
+    matches: /\bsubject of .+ could not be resolved\b/i,
+    severity: "warning",
+    action: "Use a literal, constant, configuration default, or visible caller argument for the subject.",
+  },
+  {
+    id: "store.external-migrations",
+    matches: /\bmigrations are applied from .+ whose schema is not in this tree\b/i,
+    severity: "warning",
+    action: "Vendor or expose the external migrations so their tables can be included in the store.",
+  },
+  {
+    id: "store.missing-foreign-table",
+    matches: /\bcolumn .+ references .+ which no migration here creates\b/i,
+    severity: "warning",
+    action: "Include the referenced table migration or correct the foreign-key target.",
+  },
+  {
+    id: "schema.unresolved-type",
+    matches: /\bis not declared in the protos read here\b/i,
+    severity: "warning",
+    action: "Include the imported protobuf declaration or map the type to an external schema.",
+  },
+  {
+    id: "source.offline-cache",
+    matches: /\bnot (?:fetched|read) \(offline\)/i,
+    severity: "info",
+    action: "Regenerate with network access when the vendored copy must be refreshed.",
+  },
+  {
+    id: "source.unreachable",
+    matches: /\bnot (?:fetched|read) \((?!offline\))/i,
+    severity: "warning",
+    action: "The far end could not be reached and the committed copy was used; check the server and the credential, then regenerate.",
+  },
+  {
+    id: "source.unpinned",
+    matches: /\bnot pinned\b/i,
+    severity: "warning",
+    action: "Pin the source to an immutable commit or schema version.",
+  },
+  {
+    id: "source.parse-failed",
+    matches: /\bcould not (?:be read|parse|be parsed|be encoded)\b/i,
+    severity: "error",
+    action: "Open the referenced source and fix the parse or read error.",
+  },
+  {
+    id: "extraction.no-match",
+    matches: /\b(?:no .+ (?:was|were) found|no .+ matched|declares no |no models in this application)\b/i,
+    severity: "info",
+    action: "Confirm this capability is absent, or point the extractor at the source that declares it.",
+  },
+];
+
+const FALLBACK_ACTION = "Inspect the referenced source and either fix the extraction gap or add a reviewed CEL policy with a reason.";
+
+export function warningDiagnostic(
+  warning: RawWarning,
+): WarningDiagnostic {
+  const definition = RULES.find((candidate) => candidate.matches.test(warning.message));
+  const rule = definition?.id ?? `plugin.${slug(warning.plugin)}.other-${fingerprint(warning.message)}`;
+  const ref = warningRef(warning.message);
+
+  return {
+    ...warning,
+    message: djangoAggregateMessage(warning.message),
+    ...(djangoAggregateCandidates(warning.message) ? { aggregateCandidates: djangoAggregateCandidates(warning.message)! } : {}),
+    rule,
+    severity: definition?.severity ?? "warning",
+    action: definition?.action ?? FALLBACK_ACTION,
+    ...(ref ? { ref } : {}),
+    suppressed: false,
+  };
+}
+
+export function groupWarnings(
+  warnings: RawWarning[],
+): WarningGroup[] {
+  return groupDiagnostics(warnings.map((warning) => warningDiagnostic(warning)));
+}
+
+export function groupDiagnostics(diagnostics: WarningDiagnostic[]): WarningGroup[] {
+  const groups = new Map<string, WarningGroup>();
+  for (const warning of diagnostics) {
+    const key = `${warning.plugin}\0${warning.rule}\0${warning.severity}\0${warning.suppressed}`;
+    const existing = groups.get(key);
+    if (existing) {
+      existing.messages.push(warning);
+      existing.count += 1;
+      continue;
+    }
+    groups.set(key, {
+      plugin: warning.plugin,
+      rule: warning.rule,
+      severity: warning.severity,
+      action: warning.action,
+      messages: [warning],
+      count: 1,
+      suppressed: warning.suppressed,
+      ...(warning.suppressionReason ? { suppressionReason: warning.suppressionReason } : {}),
+    });
+  }
+  const order: Record<WarningSeverity, number> = { error: 0, warning: 1, info: 2 };
+  return [...groups.values()].sort(
+    (left, right) => order[left.severity] - order[right.severity]
+      || Number(left.suppressed) - Number(right.suppressed)
+      || right.count - left.count
+      || left.plugin.localeCompare(right.plugin)
+      || left.rule.localeCompare(right.rule),
+  );
+}
+
+function warningRef(message: string): string | undefined {
+  const match = message.match(/^(.+?):\s+(?=[A-Za-z/])/);
+  return match?.[1]?.trim() || undefined;
+}
+
+function slug(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "unknown";
+}
+
+function fingerprint(message: string): string {
+  const ref = warningRef(message);
+  const body = (ref ? message.slice(message.indexOf(":", ref.length) + 1) : message)
+    .toLowerCase()
+    .replace(/`[^`]*`|"[^"]*"|'[^']*'/g, "<value>")
+    .replace(/\b\d+\b/g, "#")
+    .replace(/\s+/g, " ")
+    .trim();
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < body.length; index += 1) {
+    hash ^= body.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36);
+}

package/src/likec4/ids.test.ts

@@ -9,6 +9,8 @@ import {
   CONTAINERS_VIEW,
   LANDSCAPE_VIEW,
   allViewIds,
+  deployedServices,
+  environmentsOf,
   contextViewId,
   eventFqn,
   flowCrossViewId,
@@ -100,14 +102,16 @@ describe("view ids", () => {
     expect(new Set(ids).size).toBe(ids.length);
   });
 
-  it("covers the landscape, the containers, every context, both views of every service and both of every flow", () => {
+  it("covers the landscape, the containers, every context, both views of every service, both of every flow, every environment and every deployed service", () => {
     const ids = allViewIds(catalog);
     const services = catalog.contexts.flatMap((c) => c.services);
     expect(ids).toHaveLength(
       2 +
         catalog.contexts.length +
         services.length * 2 +
-        catalog.flows.length * 2,
+        catalog.flows.length * 2 +
+        environmentsOf(catalog).length +
+        deployedServices(catalog).length,
     );
     // The three C4 levels: the estate, its containers, a context, and a
     // service opened up.

package/src/likec4/ids.ts

@@ -9,6 +9,7 @@ import type {
   Participant,
   Service,
 } from "../catalog";
+import { allDeployments, deploys, environmentOf } from "../catalog";
 import reserved from "./reserved.json";
 
 /**
@@ -97,6 +98,42 @@ export const flowViewId = (flow: Flow | string): string =>
 export const flowCrossViewId = (flow: Flow | string): string =>
   `${flowViewId(flow)}_cross`;
 
+/**
+ * Where the services run, one environment at a time: the clusters and
+ * namespaces of the environment as frames, an instance of every service the
+ * snapshot places there, and between the instances what the model declares
+ * between their services (portolan.0012).
+ */
+export const deploymentViewId = (environment: string): string =>
+  `deploy_${safeId(environment)}`;
+
+/** One service, every place it runs: its instances, with the frames around each. */
+export const serviceDeployViewId = (service: Service | string): string =>
+  `deploy_svc_${safeId(typeof service === "string" ? service : service.id)}`;
+
+/**
+ * The environments the snapshot places services in, sorted. A deployment of
+ * a repository no service claims places nothing and names no environment
+ * here: an environment with nothing of the estate in it is not a picture.
+ */
+export function environmentsOf(catalog: Catalog): string[] {
+  const services = catalog.contexts.flatMap((context) => context.services);
+  const found = new Set<string>();
+  for (const deployment of allDeployments(catalog)) {
+    if (!services.some((service) => deploys(deployment, service))) continue;
+    found.add(environmentOf(deployment));
+  }
+  return [...found].sort();
+}
+
+/** The services the snapshot places somewhere, in catalog order. */
+export function deployedServices(catalog: Catalog): Service[] {
+  const deployments = allDeployments(catalog);
+  return catalog.contexts
+    .flatMap((context) => context.services)
+    .filter((service) => deployments.some((d) => deploys(d, service)));
+}
+
 /** Every view id the generator is expected to emit, in a stable order. */
 export function allViewIds(catalog: Catalog): string[] {
   const out: string[] = [LANDSCAPE_VIEW, CONTAINERS_VIEW];
@@ -111,5 +148,11 @@ export function allViewIds(catalog: Catalog): string[] {
     out.push(flowViewId(flow));
     out.push(flowCrossViewId(flow));
   }
+  for (const environment of environmentsOf(catalog)) {
+    out.push(deploymentViewId(environment));
+  }
+  for (const service of deployedServices(catalog)) {
+    out.push(serviceDeployViewId(service));
+  }
   return out;
 }

package/src/main.tsx

@@ -3,6 +3,29 @@ import { createRoot } from "react-dom/client";
 import "./index.css";
 import { App } from "./app/App";
 
+// A deploy replaces every hashed chunk at once, but a static host may keep
+// serving the old index.html from cache for a while (GitLab Pages caches every
+// file for ten minutes and lets a project set no headers of its own). A tab
+// that opened on the old page then asks for chunks that no longer exist, the
+// lazy import fails, and the reader sees an empty canvas. Vite reports that
+// failure here before it throws; one reload revalidates the document and
+// picks up the new names. The guard is keyed by the chunk that failed, so a
+// chunk that is truly missing cannot reload the page forever.
+const RELOADED = "portolan:reloaded-for";
+window.addEventListener("vite:preloadError", (event) => {
+  const failed = String((event as Event & { payload?: unknown }).payload ?? "");
+  let already = "";
+  try {
+    already = sessionStorage.getItem(RELOADED) ?? "";
+    sessionStorage.setItem(RELOADED, failed);
+  } catch {
+    // Storage may be unavailable; a single reload is still worth trying.
+  }
+  if (already === failed) return;
+  event.preventDefault();
+  window.location.reload();
+});
+
 const container = document.getElementById("root");
 if (!container) throw new Error("#root is missing from index.html");
 

package/src/map/ContextMapGraph.tsx

@@ -16,7 +16,14 @@
 // status among everything the line carries: a relationship is known no better
 // than its least-known hop.
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { useNavigate } from "react-router";
 import {
   Background,
@@ -79,6 +86,36 @@ export interface ContextMapGraphProps {
   inactiveNodeOpacity?: number;
 }
 
+// React Flow reads its parent box during mount. The page shell and embedded
+// hero can both briefly be 0×0 while their layout settles, so keep the flow
+// out of that box until a real size has been observed.
+function useMeasuredCanvas() {
+  const canvasRef = useRef<HTMLDivElement>(null);
+  const [hasSize, setHasSize] = useState(false);
+
+  useLayoutEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const measure = (): void => {
+      const next = canvas.clientWidth > 0 && canvas.clientHeight > 0;
+      setHasSize((current) => (current === next ? current : next));
+    };
+
+    measure();
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", measure);
+      return () => window.removeEventListener("resize", measure);
+    }
+
+    const observer = new ResizeObserver(measure);
+    observer.observe(canvas);
+    return () => observer.disconnect();
+  }, []);
+
+  return { canvasRef, hasSize };
+}
+
 export function ContextMapGraph({
   catalog,
   relations,
@@ -97,6 +134,7 @@ export function ContextMapGraph({
     edges: [],
     ready: false,
   });
+  const { canvasRef, hasSize } = useMeasuredCanvas();
 
   // One entry per pair the catalog has anything to say about. `back` is what
   // turns an arrow into a double-headed one; elk only ever sees a -> b, so the
@@ -257,37 +295,43 @@ export function ContextMapGraph({
   );
 
   return (
-    <div className="canvas-motion relative h-full w-full">
-      {drawn.ready ? null : <DiagramSkeleton />}
-      <ReactFlow
-        nodes={shownNodes}
-        edges={shownEdges}
-        nodeTypes={contextNodeTypes}
-        edgeTypes={mapEdgeTypes}
-        onNodeClick={onNodeClick}
-        onNodeDoubleClick={onNodeDoubleClick}
-        onPaneClick={() => clear("diagram")}
-        nodesDraggable={false}
-        nodesConnectable={false}
-        elementsSelectable
-        proOptions={{ hideAttribution: true }}
-        fitView
-        fitViewOptions={{ padding: compactLayout ? 0.06 : 0.16 }}
-        zoomOnScroll={zoomOnScroll}
-        preventScrolling={zoomOnScroll}
-        minZoom={0.2}
-        maxZoom={1.6}
-        key={fitKey}
-      >
-        <Background gap={20} size={2} />
-        {/* The map has no modes to switch, so its only control is the way
-            out: the drawing as a file, for the page that explains it. */}
-        {showExport ? (
-          <Panel position="top-right">
-            <ExportSeg name="context-map" />
-          </Panel>
-        ) : null}
-      </ReactFlow>
+    <div
+      ref={canvasRef}
+      className="canvas-motion relative h-full w-full"
+    >
+      {drawn.ready && hasSize ? (
+        <ReactFlow
+          nodes={shownNodes}
+          edges={shownEdges}
+          nodeTypes={contextNodeTypes}
+          edgeTypes={mapEdgeTypes}
+          onNodeClick={onNodeClick}
+          onNodeDoubleClick={onNodeDoubleClick}
+          onPaneClick={() => clear("diagram")}
+          nodesDraggable={false}
+          nodesConnectable={false}
+          elementsSelectable
+          proOptions={{ hideAttribution: true }}
+          fitView
+          fitViewOptions={{ padding: compactLayout ? 0.06 : 0.16 }}
+          zoomOnScroll={zoomOnScroll}
+          preventScrolling={zoomOnScroll}
+          minZoom={0.2}
+          maxZoom={1.6}
+          key={fitKey}
+        >
+          <Background gap={20} size={2} />
+          {/* The map has no modes to switch, so its only control is the way
+              out: the drawing as a file, for the page that explains it. */}
+          {showExport ? (
+            <Panel position="top-right">
+              <ExportSeg name="context-map" />
+            </Panel>
+          ) : null}
+        </ReactFlow>
+      ) : (
+        <DiagramSkeleton />
+      )}
     </div>
   );
 }

package/src/merge-deployments.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import type { Deployment } from "./catalog";
+import { mergeCatalogs } from "./merge";
+import type { CatalogSource } from "./merge";
+
+function source(path: string, deployments: Deployment[]): CatalogSource {
+  return {
+    path,
+    catalog: {
+      generatedAt: "",
+      commit: "",
+      contexts: [],
+      defs: {},
+      flows: [],
+      adrs: [],
+      deployments,
+    },
+  };
+}
+
+const manifest = (over: Partial<Deployment> = {}): Deployment => ({
+  id: "argocd/shop-cart-prod",
+  name: "shop-cart-prod",
+  project: "shop",
+  environment: "prod",
+  cluster: "in-cluster",
+  namespace: "shop",
+  repo: "github.com/acme/gitops",
+  path: "envs/prod/shop/cart",
+  targetRevision: "main",
+  revision: "",
+  tool: "kustomize",
+  url: "",
+  service: "shop.cart",
+  images: ["ghcr.io/acme/cart:2.1.0"],
+  basis: "manifest",
+  ...over,
+});
+
+const api = (over: Partial<Deployment> = {}): Deployment => ({
+  id: "argocd/shop-cart-prod",
+  name: "shop-cart-prod",
+  project: "shop",
+  environment: "prod",
+  cluster: "in-cluster",
+  namespace: "shop",
+  repo: "github.com/acme/gitops",
+  path: "envs/prod/shop/cart",
+  targetRevision: "main",
+  revision: "a".repeat(40),
+  tool: "kustomize",
+  url: "https://argocd.example.com/applications/argocd/shop-cart-prod",
+  images: ["ghcr.io/acme/cart:2.1.0", "redis:7"],
+  basis: "api",
+  ...over,
+});
+
+describe("the merge lays the tree under the deployer", () => {
+  it("folds a manifest row and an api row into one that the deployer shapes and the tree fills, with no drift when they agree", () => {
+    const { catalog, conflicts } = mergeCatalogs([
+      source("gitops/portolan/argocd.json", [manifest()]),
+      source("argocd/argocd.apps.json", [api({ service: undefined })]),
+    ]);
+    expect(conflicts).toEqual([]);
+    expect(catalog.deployments).toHaveLength(1);
+    const [row] = catalog.deployments!;
+    expect(row).toMatchObject({
+      basis: "both",
+      revision: "a".repeat(40),
+      url: "https://argocd.example.com/applications/argocd/shop-cart-prod",
+      // The labels the tree carries place the row when the deployer's did not.
+      service: "shop.cart",
+      // What runs, not what is pinned: the base's redis is running too.
+      images: ["ghcr.io/acme/cart:2.1.0", "redis:7"],
+    });
+    expect(row?.drift).toBeUndefined();
+  });
+
+  it("keeps the tree's word as drift where the deployer says otherwise, whichever arrives first", () => {
+    const tree = manifest({ targetRevision: "release-2.1", images: ["ghcr.io/acme/cart:2.1.0"], namespace: "shop" });
+    const cluster = api({ targetRevision: "main", images: ["ghcr.io/acme/cart:2.0.9"], namespace: "shop-old" });
+    for (const order of [[tree, cluster], [cluster, tree]]) {
+      const { catalog, conflicts } = mergeCatalogs([
+        source("first.json", [order[0]!]),
+        source("second.json", [order[1]!]),
+      ]);
+      expect(conflicts).toEqual([]);
+      const [row] = catalog.deployments!;
+      expect(row?.basis).toBe("both");
+      expect(row?.targetRevision).toBe("main");
+      expect(row?.namespace).toBe("shop-old");
+      expect(row?.drift).toEqual({
+        namespace: "shop",
+        targetRevision: "release-2.1",
+        images: ["ghcr.io/acme/cart:2.1.0"],
+      });
+    }
+  });
+
+  it("does not call a pinned image drift when nothing runs yet, and shows the pinned ones instead", () => {
+    const { catalog } = mergeCatalogs([
+      source("tree.json", [manifest()]),
+      source("api.json", [api({ images: undefined, revision: "" })]),
+    ]);
+    const [row] = catalog.deployments!;
+    expect(row?.images).toEqual(["ghcr.io/acme/cart:2.1.0"]);
+    expect(row?.drift).toBeUndefined();
+  });
+
+  it("leaves a row only one source spoke for as it was, and reports two of one basis as a collision", () => {
+    // Sources are read in path order, so the names say who comes first.
+    const { catalog, conflicts } = mergeCatalogs([
+      source("a-tree.json", [manifest()]),
+      source("b-tree.json", [manifest({ path: "elsewhere" })]),
+      source("c-api.json", [api()]),
+      source("d-api.json", [api({ revision: "b".repeat(40) })]),
+    ]);
+    expect(catalog.deployments).toHaveLength(1);
+    expect(catalog.deployments?.[0]?.revision).toBe("a".repeat(40));
+    expect(conflicts.map((c) => c.path)).toEqual(["b-tree.json", "d-api.json"]);
+    expect(conflicts[0]?.message).toContain("declared here and in a-tree.json");
+    expect(conflicts[1]?.message).toContain("listed here and in c-api.json");
+
+    const alone = mergeCatalogs([source("tree.json", [manifest()])]);
+    expect(alone.catalog.deployments?.[0]).toEqual(manifest());
+  });
+});