@shortlink-org/portolan 0.2.3 → 0.3.0

package/src/components/HTTPDestinationEvidence.test.tsx

@@ -0,0 +1,23 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { HTTPDestinationEvidence } from "./HTTPDestinationEvidence";
+
+it("shows the join and the config default behind a resolved destination", () => {
+  const html = renderToStaticMarkup(<HTTPDestinationEvidence destination={{
+    callSite: "client.go:10", endpointExpression: "c.baseURL + path", method: "POST",
+    localPath: "/get-admin-settings", fullPath: "/settings/get-admin-settings",
+    baseURL: { expression: "cfg.SettingAddr", configField: "Config.SettingAddr", environmentVariable: "SETTINGS_ADDR", kind: "config-default", value: "http://localhost:8000/settings", source: "config.go:84", optionSource: "modules_tree.go:212" },
+    join: { expression: "c.baseURL + path", source: "client.go:10" },
+    resolution: { basis: "full-path", provider: "avia.aviaadmin", route: "/settings/get-admin-settings" },
+  }} />);
+  for (const value of ["Recovered full path", "Config default (runtime may override)", "SETTINGS_ADDR", "modules_tree.go:212", "Config.SettingAddr", "/settings/get-admin-settings", "avia.aviaadmin"]) expect(html).toContain(value);
+  expect(html).not.toContain("heuristic");
+});
+
+it("labels suffix resolution as a heuristic", () => {
+  const html = renderToStaticMarkup(<HTTPDestinationEvidence destination={{
+    callSite: "client.go:10", endpointExpression: "/settings", method: "POST",
+    resolution: { basis: "unique-suffix", provider: "admin", route: "/admin/settings" },
+  }} />);
+  expect(html).toContain("Unique route suffix (heuristic)");
+});

package/src/components/HTTPDestinationEvidence.tsx

@@ -0,0 +1,31 @@
+import type { HTTPDestination } from "../catalog";
+
+/** Display the facts for this invocation, including the limits of defaults. */
+export function HTTPDestinationEvidence({ destination: d }: { destination: HTTPDestination }) {
+  const basis = d.resolution?.basis;
+  const rows = [
+    ["Linked by", basis === "full-path" ? "Recovered full path" : basis === "exact-route" ? "Exact route" : basis === "unique-suffix" ? "Unique route suffix (heuristic)" : "Unresolved"],
+    ["Call site", d.callSite],
+    ["Endpoint expression", d.endpointExpression],
+    ["Local path", d.localPath],
+    ["Base URL expression", d.baseURL?.expression],
+    ["Config field", d.baseURL?.configField],
+    ["Environment variable", d.baseURL?.environmentVariable],
+    [d.baseURL?.kind === "config-default" ? "Config default (runtime may override)" : "Base URL", d.baseURL?.value],
+    ["Config source", d.baseURL?.source],
+    ["Option call site", d.baseURL?.optionSource],
+    ["Service discovery alias", d.serviceDiscoveryAlias],
+    ["Join expression", d.join?.expression],
+    ["Join source", d.join?.source],
+    ["Full path", d.fullPath],
+    ...(d.transforms ?? []).map((transform) => ["Runtime URL modifier (not evaluated)", `${transform.expression} · ${transform.source}`]),
+    ["Provider", d.resolution?.provider],
+    ["Provider route", d.resolution?.route],
+  ].filter(([, value]) => value);
+  return <section aria-label="HTTP destination evidence" className="border-t border-line px-3 py-3">
+    <h3 className="label mb-2">HTTP destination evidence</h3>
+    <dl className="grid min-w-0 grid-cols-1 gap-y-3">
+      {rows.map(([label, value], index) => <div key={`${label}-${index}`} className="min-w-0"><dt className="text-muted">{label}</dt><dd className="mono break-all text-ink">{value}</dd></div>)}
+    </dl>
+  </section>;
+}

package/src/components/Integrations.tsx

@@ -210,7 +210,7 @@ export function Integrations({ groups }: { groups: IntegrationGroup[] }) {
                         <RowActions copy={call.id} label={call.id} />
                         {method?.http ? (
                           <p className="mono w-full text-muted">
-                            {method.http.method} {method.http.path}
+                            {method.http.method ? `${method.http.method} ${method.http.path}` : method.http.path}
                           </p>
                         ) : null}
                         {call.note ? (

package/src/components/LifecycleDiagram.tsx

@@ -3,6 +3,12 @@ import type { Aggregate } from "../catalog";
 import { layoutLifecycle, METRICS } from "../lib/lifecycle";
 import { KindIcon } from "./kind";
 
+function transitionTone(on: string) {
+  if (on === "Fail") return { color: "var(--status-unresolved)", marker: "lc-arrow-fail" };
+  if (on === "Succeed") return { color: "var(--status-verified)", marker: "lc-arrow-succeed" };
+  return { color: "var(--fg-muted)", marker: "lc-arrow" };
+}
+
 /**
  * The aggregate's state machine, as the code wrote it down. Boxes and arrows
  * are SVG; the labels are HTML laid over it, because a label holds a link to
@@ -29,18 +35,27 @@ export function LifecycleDiagram({
             <marker id="lc-arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
               <path d="M 0 0 L 8 4 L 0 8 z" fill="var(--fg-muted)" />
             </marker>
+            <marker id="lc-arrow-fail" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+              <path d="M 0 0 L 8 4 L 0 8 z" fill="var(--status-unresolved)" />
+            </marker>
+            <marker id="lc-arrow-succeed" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+              <path d="M 0 0 L 8 4 L 0 8 z" fill="var(--status-verified)" />
+            </marker>
           </defs>
-          {edges.map((e) => (
-            <path
-              key={`${e.from}-${e.to}-${e.on}`}
-              d={e.path}
-              fill="none"
-              stroke="var(--fg-muted)"
-              strokeWidth={1.25}
-              strokeDasharray={e.back ? "4 3" : undefined}
-              markerEnd="url(#lc-arrow)"
-            />
-          ))}
+          {edges.map((e) => {
+            const tone = transitionTone(e.on);
+            return (
+              <path
+                key={`${e.from}-${e.to}-${e.on}`}
+                d={e.path}
+                fill="none"
+                stroke={tone.color}
+                strokeWidth={1.25}
+                strokeDasharray={e.back ? "4 3" : undefined}
+                markerEnd={`url(#${tone.marker})`}
+              />
+            );
+          })}
           {boxes.map((b) => (
             <g key={b.state}>
               <rect
@@ -80,11 +95,12 @@ export function LifecycleDiagram({
         ))}
         {edges.map((e) => {
           const to = e.emits ? eventPath(e.emits) : null;
+          const tone = transitionTone(e.on);
           return (
             <div
               key={`${e.from}-${e.to}-${e.on}-label`}
               className="mono absolute flex -translate-x-1/2 -translate-y-1/2 items-center gap-1 whitespace-nowrap rounded-control bg-bg px-1 text-muted"
-              style={{ left: e.labelX, top: e.labelY }}
+              style={{ left: e.labelX, top: e.labelY, color: tone.color }}
               title={e.source ? `made at ${e.source}` : undefined}
             >
               {e.on}

package/src/components/MachineDocs.tsx

@@ -1,5 +1,5 @@
 import { FileText } from "lucide-react";
-import { activeCatalogProfile } from "../data";
+import { activeCatalogDocs, activeCatalogProfile } from "../data";
 
 // The site as a language model reads it. The build (scripts/site-docs.mjs)
 // places the generated markdown under docs/ and llms.txt at the root, in the
@@ -10,11 +10,12 @@ import { activeCatalogProfile } from "../data";
 const base = import.meta.env.BASE_URL;
 
 const suffix = activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
-const docs = `${base}docs/${suffix}`;
 const FILES = [
-  { href: suffix ? `${docs}llms.txt` : `${base}llms.txt`, label: "llms.txt", title: "An index of every page, for a model that fetches on demand" },
-  { href: suffix ? `${docs}llms-full.txt` : `${base}llms-full.txt`, label: "llms-full.txt", title: "Every page in one file, for a model with a context window" },
-  { href: docs, label: "docs/", title: "The generated markdown, page by page" },
+  ...(activeCatalogDocs ? [
+    { href: activeCatalogDocs.index, label: "llms.txt", title: "An index of every page, for a model that fetches on demand" },
+    { href: activeCatalogDocs.full, label: "llms-full.txt", title: "Every page in one file, for a model with a context window" },
+    { href: activeCatalogDocs.pages, label: "docs/", title: "The generated markdown, page by page" },
+  ] : []),
   { href: `${base}exports/mermaid/${suffix}`, label: "Mermaid", title: "Standalone sequence diagrams for every architecture flow" },
   ...(activeCatalogProfile.id === "example"
     ? [{ href: `${base}exports/backstage/catalog-info.yaml`, label: "Backstage", title: "Components, systems, APIs and resources for a Backstage catalog" }]

package/src/components/MethodRows.tsx

@@ -167,8 +167,15 @@ export function MethodRows({
                   className={method.deprecated ? "line-through" : undefined}
                 />
                 {method.http ? (
-                  <span className="chip mono" title="the route this operation answers on">
-                    {method.http.method} {method.http.path}
+                  <span
+                    className="chip mono"
+                    title={
+                      method.http.method
+                        ? "the route this operation answers on"
+                        : "the route this operation answers on; the HTTP verb is not declared in source"
+                    }
+                  >
+                    {method.http.method ? `${method.http.method} ${method.http.path}` : method.http.path}
                   </span>
                 ) : null}
                 {method.soap ? (

package/src/components/ProblemRow.tsx

@@ -31,6 +31,7 @@ const KIND_OF: Record<Problem["kind"], "service" | "event" | "table"> = {
   "shared-channel": "event",
   "channel-undeclared": "event",
   "channel-unpublished": "service",
+  "message-encoding": "service",
   "subscription-unresolved": "service",
 };
 
@@ -50,6 +51,7 @@ const KIND_NOTE: Record<Problem["kind"], string> = {
   "channel-undeclared":
     "this event goes out on a channel the service does not declare",
   "channel-unpublished": "a declared channel no event of this service names",
+  "message-encoding": "publisher and subscriber use different payload encodings",
   "subscription-unresolved":
     "nothing in the catalog publishes what this service listens for",
 };
@@ -72,6 +74,7 @@ function nearPath(problem: Problem): string | null {
     case "shared-channel":
       return eventPath(problem.id) ?? servicePath(problem.service);
     case "channel-unpublished":
+    case "message-encoding":
     case "subscription-unresolved":
       return servicePath(problem.service);
     case "shared-store":
@@ -110,6 +113,7 @@ function peerPath(problem: Problem): string | null {
       );
     case "shared-store":
     case "shared-channel":
+    case "message-encoding":
       return servicePath(problem.peer);
     case "outbox-payload":
       return storePath(problem.peer);

package/src/components/RelationEvidence.test.tsx

@@ -0,0 +1,14 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { RelationEvidencePanel } from "./RelationEvidence";
+
+it("explains an ambiguous binding without choosing a candidate", () => {
+  const html = renderToStaticMarkup(<RelationEvidencePanel items={[
+    { kind: "binding", rule: "provider-signature", source: "di.go:12", symbol: "Build" },
+    { kind: "unresolved", rule: "ambiguous-binding", candidates: ["First", "Second"] },
+  ]} />);
+  for (const value of ["Why this relation exists", "inferred", "di.go:12", "Several implementations remain possible", "First", "Second"]) expect(html).toContain(value);
+});
+it("shows the absence of evidence explicitly", () => {
+  expect(renderToStaticMarkup(<RelationEvidencePanel items={[]} />)).toContain("No source evidence recorded");
+});

package/src/components/RelationEvidence.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+import type { RelationEvidence } from "../catalog";
+
+const labels: Record<RelationEvidence["kind"], string> = {
+  "call-site": "Call site", function: "Function", binding: "Dependency binding",
+  contract: "Contract", resolution: "Catalog resolution", unresolved: "Unresolved",
+};
+const rules: Record<string, string> = {
+  "source-expression": "Expression in source",
+  "source-function": "Enclosing source function",
+  "provider-signature": "Provider signature (inferred)",
+  "store-port-convention": "Storage field, type or package name (inferred)",
+  "domain-port-convention": "Domain port mapped to the configured store (inferred)",
+  "ambiguous-binding": "Several implementations remain possible",
+  "generated-client-method": "Method declared by generated client",
+  "http-expression": "Outbound HTTP expression",
+  "analyzed-call-path": "Static analysis path; not a runtime trace",
+  "client-contract": "Client contract",
+  "catalog-contract": "Matching interface and method",
+  "event-declaration": "Declared event",
+  "repository-sql-call": "SQL operation inside repository",
+  "full-path": "Recovered full HTTP path",
+  "exact-route": "Exact HTTP route",
+  "unique-suffix": "Unique route suffix (heuristic)",
+  "continuation-entrypoint": "Matched continuation entrypoint",
+  "response-to-request": "Response associated with request",
+  "unresolved-target": "No unique target established",
+  "sql-alter-table": "ALTER TABLE in migration",
+  "sql-view-definition": "SQL view definition",
+  "sql-create-table": "CREATE TABLE in migration",
+  "domain-root-and-repository-layout": "Domain root and repository convention (inferred)",
+  "migration-aggregate-annotation": "Explicit aggregate annotation in migration",
+};
+
+/** One explanation surface for all flow kinds and schema relationships. */
+export function RelationEvidencePanel({ items, renderSource }: {
+  items: readonly RelationEvidence[];
+  renderSource?: (source: string) => ReactNode;
+}) {
+  return <section aria-label="Why this relation exists" className="my-3 rounded-card border border-line bg-surface p-3">
+    <h3 className="label mb-2">Why this relation exists</h3>
+    {items.length === 0 ? <p className="text-muted">No source evidence recorded in this fragment.</p> :
+      <ol className="space-y-3">
+        {items.map((item, i) => <li key={`${item.kind}-${i}`} className="min-w-0 border-l-2 border-line pl-3">
+          <div className={item.kind === "unresolved" ? "text-[var(--status-unresolved)]" : "text-ink"}>{labels[item.kind]}</div>
+          <div className="text-muted">{rules[item.rule] ?? item.rule}</div>
+          {item.symbol ? <div className="mono break-all">{item.symbol}</div> : null}
+          {item.source ? <div className="mono break-all text-muted">{renderSource ? renderSource(item.source) : item.source}</div> : null}
+          {item.candidates?.length ? <div className="mt-1"><span className="text-muted">Candidates</span><ul>{item.candidates.map((candidate) => <li className="mono break-all" key={candidate}>{candidate}</li>)}</ul></div> : null}
+        </li>)}
+      </ol>}
+  </section>;
+}

package/src/components/WhatLinksHere.tsx

@@ -14,7 +14,11 @@ import { useMemo } from "react";
 import type { ReactNode } from "react";
 import { Link } from "react-router";
 import { catalog, index } from "../data";
-import { backlinkCount, backlinksFor } from "../lib/backlinks";
+import {
+  backlinkCount,
+  backlinksFor,
+  distinctBacklinks,
+} from "../lib/backlinks";
 import type { Backlink, BacklinkGroup, BacklinkTarget } from "../lib/backlinks";
 import { plural } from "../lib/format";
 import { KIND_LABEL, KIND_PLURAL } from "../lib/kinds";
@@ -163,9 +167,7 @@ export function WhatLinksHere({
         className={`mono flex flex-wrap items-center gap-1.5 text-muted ${className || "mt-2"}`}
       >
         linked from
-        {groups
-          .flatMap((g) => g.links)
-          .map((link) => {
+        {distinctBacklinks(groups).map((link) => {
             const to = backlinkPath(link);
             const body = (
               <>

package/src/data.ts

@@ -32,6 +32,11 @@ import type {
   SourceStamp,
 } from "./merge";
 import manifestJson from "../portolan.json";
+import { catalogDocs } from "./catalog-docs";
+// When each source last changed, as the checkout's history says - served by
+// scripts/provenance.mjs at build time, because a fragment carries no
+// provenance of its own (portolan.0010) and a browser cannot ask git.
+import provenance from "virtual:portolan-provenance";
 
 const manifest = manifestJson as CatalogProfileManifest & { sources: string[] };
 export const catalogProfiles: CatalogProfile[] = profilesFromManifest(manifest);
@@ -56,6 +61,8 @@ export const activeCatalogProfile = catalogProfileNamed(
   requestedProfileFromUrl(),
 );
 
+export const activeCatalogDocs = catalogDocs(manifestJson, activeCatalogProfile.id, import.meta.env.BASE_URL);
+
 /**
  * Where sources are looked for. The patterns are written out because
  * import.meta.glob resolves at build time and needs literals - and because
@@ -120,15 +127,26 @@ interface Loaded {
 
 function load(): Loaded {
   const sources: CatalogSource[] = Object.entries(modules)
-    .map(([path, catalog]) => ({
+    .map(([key, catalog]) => {
       // Vite keys a glob by its pattern-relative path; the leading ../ is an
       // artefact of this file's location, not part of where anything lives.
-      path: path.replace(/^\.\.\//, ""),
-      // A SOURCE, not a catalog: the two stamps are optional in a file, and
-      // the estate's authored facts carry neither.
-      catalog: catalog as SourceCatalog,
-    }))
-    .filter((source) => profileIncludesSource(activeCatalogProfile, source.path));
+      const imported = key.replace(/^\.\.\//, "");
+      // A SOURCE, not a catalog: a file carries no stamp of its own, and the
+      // history's travels beside it (portolan.0010).
+      const { source, ...stamp } = provenance[imported] ?? {};
+      return {
+        imported,
+        // A staged site imports a source under a flattened name; the file is
+        // still the one in the workspace, and that is the path a project's
+        // root is a prefix of and a link to the file names.
+        path: source ?? imported,
+        catalog: catalog as SourceCatalog,
+        stamp: "commit" in stamp ? stamp : undefined,
+      };
+    })
+    // The profile spells its sources the way the site imports them.
+    .filter((source) => profileIncludesSource(activeCatalogProfile, source.imported))
+    .map(({ imported: _imported, ...source }) => source);
 
   const merged = mergeCatalogs(sources);
   // Enriched before it is validated: the edges the flows imply are part of