@shortlink-org/portolan 0.2.4 → 0.3.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\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.ambiguous-aggregate-root",
+    matches: /\bmodels to choose from: name the root in the aggregates option\b/i,
+    severity: "warning",
+    action: "Choose the aggregate root explicitly in the django-domain 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 .+ topic could not be resolved\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 \(offline\)\b/i,
+    severity: "info",
+    action: "Regenerate with network access when the vendored copy must be refreshed.",
+  },
+  {
+    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/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.ts

@@ -42,13 +42,14 @@ import type {
  * A catalog as a FILE may carry it, which is not quite a catalog as a reader
  * gets one: the two stamps are optional here and required downstream.
  *
- * The host stamps what it generates, from the last commit that touched the
- * input the fragment was read from. A file nobody generates - the estate's
- * hand-written facts - is stamped by nobody, and a provenance typed in by hand
- * is a claim no process keeps true: it stays where it was typed while the
- * estate moves on, and being the oldest stamp in the corpus it then dates the
- * whole merged catalog. So a source is allowed to carry no stamp at all, and
- * saying nothing is treated as what it is - an absence of evidence, which
+ * A fragment carries no stamp of its own (portolan.0010). When it last
+ * changed, and in which commit, is what the history of the checkout says,
+ * and whoever reads the file asks the history and hands the answer over
+ * beside it. A file may still say something - a fragment written before
+ * portolan.0010 does - and that is taken only when nobody read the history.
+ * A provenance typed in by hand is a claim no process keeps true, so a source
+ * that says nothing and was read outside any history is stamped by nobody,
+ * and saying nothing is treated as what it is - an absence of evidence, which
  * drops out of the merge rather than voting in it.
  */
 export type SourceCatalog = Omit<Catalog, "generatedAt" | "commit"> &
@@ -59,6 +60,12 @@ export interface CatalogSource {
   /** Where it was read from, as a reader would type it. */
   path: string;
   catalog: SourceCatalog;
+  /**
+   * When the file last changed and in which commit, as the reader found out
+   * from the history of the checkout (portolan.0010). Left out when there
+   * was no history to ask, and the file then speaks for itself.
+   */
+  stamp?: Pick<SourceStamp, "generatedAt" | "commit">;
 }
 
 /**
@@ -120,8 +127,8 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
 
   const stamps: SourceStamp[] = ordered.map((source) => ({
     path: source.path,
-    generatedAt: source.catalog.generatedAt ?? "",
-    commit: source.catalog.commit ?? "",
+    generatedAt: source.stamp?.generatedAt ?? source.catalog.generatedAt ?? "",
+    commit: source.stamp?.commit ?? source.catalog.commit ?? "",
   }));
 
   for (const { path, catalog } of ordered) {

package/src/pages/AggregatePage.tsx

@@ -77,14 +77,14 @@ function BuildingBlocks({
       </div>
       <div className="flex flex-wrap items-center gap-x-4 gap-y-2 px-4 py-3">
         <span className="mono flex items-center gap-1.5 text-muted">
-          root
+          {aggregate.kind === "model-group" ? "aggregate boundary" : "root"}
           <KindIcon kind="entity" />
           {rootTo ? (
             <Link to={rootTo} className="text-ink hover:underline">
               {aggregate.root}
             </Link>
           ) : (
-            <span className="text-ink">{aggregate.root}</span>
+            <span className="text-ink">{aggregate.kind === "model-group" ? "not specified" : aggregate.root}</span>
           )}
         </span>
         <span aria-hidden className="h-4 w-px bg-line-strong" />
@@ -385,7 +385,7 @@ export function AggregatePage() {
       <PageHeader
         kind={
           <>
-            aggregate ·{" "}
+            {aggregate.kind === "model-group" ? "model group" : "aggregate"} ·{" "}
             <Link
               to={paths.service(context.id, service.slug)}
               className="rounded-control hover:text-ink hover:underline"
@@ -410,6 +410,7 @@ export function AggregatePage() {
           />
 
           <Markdown mermaid>{aggregate.readme}</Markdown>
+          {aggregate.kind === "model-group" ? <p className="mb-section text-muted">Models discovered in this application. Their relationships are extracted from the source; aggregate boundaries have not been specified.</p> : null}
 
           <div
             className="mt-section max-w-prose"
@@ -583,14 +584,14 @@ export function AggregatePage() {
                 anchor={AGGREGATE_ANCHOR.commands}
                 right={
                   <span>
-                    they change the aggregate — one row lock each
+                    {aggregate.kind === "model-group" ? "write operations discovered in this application" : "they change the aggregate — one row lock each"}
                   </span>
                 }
               >
                 Commands
               </SectionTitle>
               {commands.length === 0 ? (
-                <Empty>nothing changes this aggregate from outside</Empty>
+                <Empty>{aggregate.kind === "model-group" ? "no application commands discovered" : "nothing changes this aggregate from outside"}</Empty>
               ) : null}
               <OperationList kind="command" operations={commands} service={service} />
             </div>
@@ -606,7 +607,7 @@ export function AggregatePage() {
                 Queries
               </SectionTitle>
               {queries.length === 0 ? (
-                <Empty>nothing reads this aggregate by name</Empty>
+                <Empty>{aggregate.kind === "model-group" ? "no application queries discovered" : "nothing reads this aggregate by name"}</Empty>
               ) : null}
               <OperationList kind="query" operations={queries} service={service} />
             </div>
@@ -750,7 +751,7 @@ export function AggregatePage() {
           />
         </div>
 
-        <Toc items={toc} label="Sections of this aggregate" title="Outline" />
+        <Toc items={toc} label={aggregate.kind === "model-group" ? "Sections of this model group" : "Sections of this aggregate"} title="Outline" />
       </div>
     </div>
   );

package/src/pages/ContextPage.tsx

@@ -37,6 +37,7 @@ export function ContextPage() {
   );
   const neutral = groupKind(context) !== "bounded-context";
   const showDomain = !neutral || aggregates.length > 0;
+  const hasModelGroups = aggregates.some(({ aggregate }) => aggregate.kind === "model-group");
   const toc: TocItem[] = [
     { id: CONTEXT_ANCHOR.services, label: neutral ? "Components" : "Services" },
     ...(showDomain
@@ -86,7 +87,7 @@ export function ContextPage() {
           {showDomain ? (
             <>
               <a href={`#${CONTEXT_ANCHOR.aggregates}`} className="rounded-control hover:text-ink">
-                <span className="tnum">{stats.aggregates}</span>{" "}{plural(stats.aggregates, "aggregate")}
+                <span className="tnum">{stats.aggregates}</span>{" "}{plural(stats.aggregates, hasModelGroups ? "group" : "aggregate")}
               </a>
               <a href={`#${CONTEXT_ANCHOR.events}`} className="rounded-control hover:text-ink">
                 <span className="tnum">{stats.events}</span>{" "}{plural(stats.events, "event")}
@@ -173,7 +174,7 @@ export function ContextPage() {
                   <div className="mono mt-4 flex flex-wrap gap-x-4 text-muted">
                     {service.aggregates.length > 0 || componentKind(service) === "service" ? (
                       <Link to={`${paths.service(context.id, service.slug)}#svc-aggregates`} className="rounded-control hover:text-ink">
-                        <span className="tnum">{service.aggregates.length}</span>{" "}{plural(service.aggregates.length, "aggregate")}
+                        <span className="tnum">{service.aggregates.length}</span>{" "}{plural(service.aggregates.length, service.aggregates.some((aggregate) => aggregate.kind === "model-group") ? "group" : "aggregate")}
                       </Link>
                     ) : null}
                     <Link
@@ -234,11 +235,11 @@ export function ContextPage() {
               anchor={CONTEXT_ANCHOR.aggregates}
               right={
                 <span>
-                  every aggregate this domain owns, whichever service holds it
+                  {hasModelGroups ? "models grouped by their source application or aggregate" : "every aggregate this domain owns, whichever service holds it"}
                 </span>
               }
             >
-              Aggregates
+              {hasModelGroups ? "Aggregates and model groups" : "Aggregates"}
             </SectionTitle>
             {aggregates.length === 0 ? (
               <Empty>this domain owns nothing yet — only services</Empty>
@@ -264,7 +265,7 @@ export function ContextPage() {
                       {aggregate.name}
                     </Link>
                     <span className="meta">{service.slug}</span>
-                    <span className="meta">root {aggregate.root}</span>
+                    <span className="meta">{aggregate.kind === "model-group" ? "model group · boundary not specified" : `root ${aggregate.root}`}</span>
                     <RowActions
                       copy={aggregate.id}
                       reveal={aggregate.id}

package/src/pages/ServicePage.tsx

@@ -130,6 +130,7 @@ export function ServicePage() {
     .find((source) => source !== undefined && hasAsyncSpec(source));
   const showDomain =
     componentKind(service) === "service" || service.aggregates.length > 0;
+  const hasModelGroups = service.aggregates.some((aggregate) => aggregate.kind === "model-group");
   const integrations = integrationsFor(service, catalog);
 
   const counts: Record<Tab, number | null> = {
@@ -219,7 +220,7 @@ export function ServicePage() {
               className="rounded-control hover:text-ink"
             >
               <span className="tnum">{service.aggregates.length}</span>{" "}
-              {plural(service.aggregates.length, "aggregate")}
+              {plural(service.aggregates.length, hasModelGroups ? "group" : "aggregate")}
             </a>
           ) : null}
           {showDomain ? (
@@ -312,7 +313,7 @@ export function ServicePage() {
                 className="mt-section max-w-table"
               >
                 <SectionTitle anchor={SERVICE_ANCHOR.aggregates}>
-                  Aggregates
+                  {hasModelGroups ? "Aggregates and model groups" : "Aggregates"}
                 </SectionTitle>
                 {/* icon, slug, name, event count, actions - one column each,
                   so the counts stack up instead of drifting with the name. */}
@@ -336,7 +337,7 @@ export function ServicePage() {
                         >
                           {aggregate.slug}
                         </Link>
-                        <span className="meta">{aggregate.name}</span>
+                        <span className="meta">{aggregate.name}{aggregate.kind === "model-group" ? " · model group" : ""}</span>
                         <Link
                           to={`${to}#bb-events`}
                           className="mono rounded-control hover:underline"