@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/pages/Overview.tsx

@@ -2,18 +2,25 @@ import { useDocumentTitle } from "../app/title";
 import { useState } from "react";
 import { Link } from "react-router";
 import { AlertTriangle } from "lucide-react";
-import { activeCatalogProfile, CATALOG_PATH, catalog, index } from "../data";
+import { activeCatalogProfile, CATALOG_PATH, catalog } from "../data";
 import { contextOwners, contextStats, widestFlows } from "../lib/derive";
 import type { ContextOwner } from "../lib/derive";
-import { allProblems } from "../lib/all-problems";
+import { bridges } from "../lib/centrality";
+import { useProblems } from "../lib/use-problems";
 import { ctxStyle } from "../lib/context-color";
 import { middleTruncate, plural } from "../lib/format";
 import { useCountUp, staggerStyle } from "../lib/motion";
 import { usePhone } from "../app/responsive";
-import { CONTEXT_ANCHOR, OVERVIEW_ANCHOR, paths } from "../routes";
+import { CONTEXT_ANCHOR, OVERVIEW_ANCHOR, paths, servicePath } from "../routes";
 import { Blank, SectionTitle } from "../components/PageHeader";
 import { C4View } from "../likec4/C4View";
-import { profileContainersViewId, profileLandscapeViewId } from "../likec4/ids";
+import {
+  deploymentViewId,
+  environmentsOf,
+  profileContainersViewId,
+  profileLandscapeViewId,
+} from "../likec4/ids";
+import { servicesDeployedIn } from "../lib/environments";
 import { LevelSwitch } from "../likec4/levels";
 import type { C4Level } from "../likec4/levels";
 import { CatalogStamp } from "../components/CatalogStamp";
@@ -28,6 +35,9 @@ import {
 /** How many problems the overview lists before pointing at the page that lists them all. */
 const OVERVIEW_PROBLEMS = 4;
 
+/** How many bridges the overview lists. Past the first few the shares are small and the list is the graph. */
+const OVERVIEW_BRIDGES = 5;
+
 /**
  * A measurement that arrives rather than appears - 200ms, linear, once - and
  * then takes you to what it measured. A number that counts something the app
@@ -96,12 +106,23 @@ export function Overview() {
   useDocumentTitle("Overview");
   const phone = usePhone();
   const [level, setLevel] = useState<C4Level>(1);
+  // Where the estate runs, one environment at a time. Production first when
+  // there is one by that name: it is the environment a reader means by
+  // "deployed" until they say otherwise.
+  const environments = environmentsOf(catalog);
+  const [environment, setEnvironment] = useState<string>(
+    () =>
+      environments.find((e) => /^prod/i.test(e)) ?? environments[0] ?? "",
+  );
+  const deployedCount = (env: string) =>
+    servicesDeployedIn(catalog, new Set([env])).size;
   const reach = widestFlows(catalog);
+  const roads = bridges(catalog);
   const services = catalog.contexts.reduce(
     (count, context) => count + context.services.length,
     0,
   );
-  const issues = allProblems(catalog, index);
+  const issues = useProblems();
   const issueCount = issues.length;
   const errorCount = issues.filter((p) => p.severity === "error").length;
 
@@ -189,6 +210,44 @@ export function Overview() {
         />
       </section>
 
+      {/* Where the estate runs, from the deployer's snapshot: the services
+          standing in one environment, in their clusters and namespaces, and
+          between them what the model declares. Absent entirely when no
+          snapshot places anything - a heading over an empty canvas would
+          claim the estate runs nowhere, and nobody made that claim. */}
+      {environments.length > 0 ? (
+        <section id={OVERVIEW_ANCHOR.deployed} className="mt-section">
+          <SectionTitle
+            anchor={OVERVIEW_ANCHOR.deployed}
+            right={
+              <div className="seg" role="group" aria-label="Environment">
+                {environments.map((env) => (
+                  <button
+                    key={env}
+                    type="button"
+                    onClick={() => setEnvironment(env)}
+                    aria-pressed={env === environment}
+                    className="flex items-center gap-1.5"
+                    title={`${plural(deployedCount(env), "service")} of the estate in ${env}`}
+                  >
+                    {env}
+                    <span className="tnum">{deployedCount(env)}</span>
+                  </button>
+                ))}
+              </div>
+            }
+          >
+            Deployed
+          </SectionTitle>
+          <C4View
+            viewId={deploymentViewId(environment)}
+            height={phone ? 320 : 480}
+            controls={phone}
+            fitViewPadding={{ x: 8, y: 8 }}
+          />
+        </section>
+      ) : null}
+
       <section id={OVERVIEW_ANCHOR.contexts} className="mt-section">
         <SectionTitle anchor={OVERVIEW_ANCHOR.contexts}>Contexts</SectionTitle>
         <div
@@ -281,6 +340,85 @@ export function Overview() {
         </div>
       </section>
 
+      {/* The services the estate's paths run through: the share of shortest
+          paths between every other pair of services that pass through this
+          one, and the pairs of contexts it is the main road between. Degree
+          is not shown - a hub is visible on the graph, a bridge is not: the
+          service with three neighbours that is the only way from auth into
+          payments looks like nothing there. Nothing is shown for an estate
+          with no such service; a heading over "none" is a dead end. */}
+      {roads.length > 0 ? (
+        <section id={OVERVIEW_ANCHOR.bridges} className="mt-section">
+          <SectionTitle
+            anchor={OVERVIEW_ANCHOR.bridges}
+            right={
+              <span className="flex items-center gap-2">
+                {roads.length > OVERVIEW_BRIDGES ? (
+                  <span className="section-aside">
+                    {OVERVIEW_BRIDGES} of {roads.length}
+                  </span>
+                ) : null}
+                <Link
+                  to={paths.graph()}
+                  className="rounded-control px-1 text-accent hover:underline"
+                >
+                  the graph →
+                </Link>
+              </span>
+            }
+          >
+            Bridges
+          </SectionTitle>
+          <div className="flex flex-col gap-2" data-nav-list>
+            {roads.slice(0, OVERVIEW_BRIDGES).map((road, i) => {
+              const to = servicePath(road.id);
+              const percent = Math.round(road.betweenness * 100);
+              return (
+                <Link
+                  key={road.id}
+                  to={to ?? paths.graph()}
+                  data-nav-item
+                  className="row stagger-in flex-wrap"
+                  style={staggerStyle(i)}
+                  title={`${percent}% of the shortest paths between other services run through ${road.id}`}
+                >
+                  {/* The share, as a bar the width of the number, so the
+                      list reads as a ranking before any number is read. */}
+                  <span className="flex w-16 shrink-0 items-center gap-1.5">
+                    <span className="h-1.5 flex-1 overflow-hidden rounded-full bg-surface">
+                      <span
+                        className="block h-full bg-accent"
+                        style={{ width: `${Math.max(percent, 2)}%` }}
+                      />
+                    </span>
+                    <span className="mono tnum w-8 text-right text-muted">
+                      {percent}%
+                    </span>
+                  </span>
+                  <span className="font-semibold" title={road.id}>
+                    {road.id}
+                  </span>
+                  <span className="mono text-muted">between</span>
+                  <div className="flex flex-wrap items-center gap-1">
+                    {road.between.map((pair) => (
+                      <span
+                        key={`${pair.a}~${pair.b}`}
+                        className="flex items-center gap-1"
+                        title={`${Math.round(pair.share * 100)}% of the shortest paths from ${pair.a} to ${pair.b} run through ${road.id}`}
+                      >
+                        <ContextPill id={pair.a} />
+                        <span className="text-muted">↔</span>
+                        <ContextPill id={pair.b} />
+                      </span>
+                    ))}
+                  </div>
+                </Link>
+              );
+            })}
+          </div>
+        </section>
+      ) : null}
+
       <section id={OVERVIEW_ANCHOR.flows} className="mt-section">
         <SectionTitle
           anchor={OVERVIEW_ANCHOR.flows}
@@ -381,13 +519,15 @@ export function Overview() {
             Problems
           </SectionTitle>
           <div className="flex max-w-table flex-col gap-2" data-nav-list>
-            {issues.slice(0, OVERVIEW_PROBLEMS).map((problem, i) => (
-              <ProblemRow
-                key={`${problem.kind}:${problem.id}:${problem.peer}`}
-                problem={problem}
-                index={i}
-              />
-            ))}
+            <div className="divide-y divide-line overflow-hidden rounded-card border border-line shadow-xs">
+              {issues.slice(0, OVERVIEW_PROBLEMS).map((problem, i) => (
+                <ProblemRow
+                  key={`${problem.rule}:${problem.id}:${problem.peer}`}
+                  problem={problem}
+                  index={i}
+                />
+              ))}
+            </div>
             {issueCount > OVERVIEW_PROBLEMS ? (
               <Link
                 to={paths.problems()}

package/src/pages/PluginIndex.tsx

@@ -0,0 +1,190 @@
+import { useDocumentTitle } from "../app/title";
+import { useEffect, useState } from "react";
+import { Link, useLocation } from "react-router";
+import { ArrowUpRight, ShieldCheck, Terminal } from "lucide-react";
+import { CatIllustration } from "../components/CatIllustration";
+import { SectionTitle } from "../components/PageHeader";
+import { PluginIcon } from "../components/PluginIcon";
+import {
+  pluginsByCategory,
+  pluginIcon,
+  pluginLabel,
+  pluginSourceHref,
+  runtimeLabel,
+} from "../lib/plugins";
+import type { PluginEntry } from "../lib/plugins";
+import { PRODUCT_REPOSITORY } from "../lib/product";
+import { paths } from "../routes";
+
+const PHASE_LABEL = { extract: "extract", verify: "verify", generate: "generate" } as const;
+
+/** Every cat the site has drawn; any of them suits a page that is a list. */
+const CAT_SCENES = ["about", "clear", "unchanged", "onboarding", "search", "trial"] as const;
+
+/**
+ * Every plugin the package ships, grouped by what it reads or what it makes.
+ *
+ * Rendered from the index `npm run schema` writes, so this page says what the
+ * plugins say about themselves and nothing else: the summary each answers to
+ * `describe`, the category it sorts itself under, the options it can be told.
+ * The Settings page shows which of these a build ran; this one shows what a
+ * build could run.
+ */
+export function PluginIndex() {
+  useDocumentTitle("Plugins");
+  const groups = pluginsByCategory();
+  const total = groups.reduce((n, group) => n + group.plugins.length, 0);
+  const { hash } = useLocation();
+  const target = hash.startsWith("#plugin-") ? hash.slice("#plugin-".length) : null;
+  // A different cat each visit, the same one for the visit: picked once, not
+  // on every render, or a hash change would swap it mid-scroll.
+  const [cat] = useState(() => CAT_SCENES[Math.floor(Math.random() * CAT_SCENES.length)] ?? "about");
+
+  // A link from Settings names one plugin. The card grid settles a frame after
+  // the route commits, so the scroll waits for it rather than landing where
+  // the card was in a layout that no longer exists.
+  useEffect(() => {
+    if (!hash) return;
+    const id = hash.slice(1);
+    const frame = requestAnimationFrame(() => {
+      document.getElementById(id)?.scrollIntoView({ block: "start" });
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [hash]);
+
+  return (
+    <div className="h-full overflow-y-auto p-gutter">
+      {/* The intro is a paragraph wide; on a wide screen the rest of the row
+          was empty, and a cat is a better use of it than nothing. */}
+      <div className="grid gap-grid xl:grid-cols-[minmax(0,1fr)_auto] xl:items-center">
+      <div>
+      <div className="flex flex-wrap items-center gap-3">
+        <h1 className="text-lg font-semibold">Plugins</h1>
+        <span className="mono text-muted">{total} shipped</span>
+      </div>
+      <p className="mt-2 max-w-prose text-muted">
+        Every fact in the catalog was read by one of these. An extractor reads a
+        tree and answers with a fragment; a verifier checks the catalog against
+        evidence; a generator turns it into something else. Each describes
+        itself, and this page is that description. Which of them a build ran is
+        on the{" "}
+        <Link to={paths.settingsPipeline()} className="text-accent hover:underline">
+          pipeline settings
+        </Link>
+        ; how to write one is in the{" "}
+        <a
+          href={`${PRODUCT_REPOSITORY}/tree/main/plugins#readme`}
+          target="_blank"
+          rel="noreferrer"
+          className="text-accent hover:underline"
+        >
+          plugin protocol
+        </a>
+        .
+      </p>
+      </div>
+      <CatIllustration scene={cat} className="hidden xl:block h-[126px] w-[180px] justify-self-end" />
+      </div>
+
+      <nav aria-label="Categories" className="mt-4 flex flex-wrap gap-1.5">
+        {groups.map((group) => (
+          <a key={group.category} href={`#${group.category}`} className="chip inline-flex items-center gap-1.5 border-line-strong hover:border-accent hover:text-accent">
+            <PluginIcon icon={{ lucide: group.icon }} size={12} />
+            {group.title} <span className="text-muted/70">{group.plugins.length}</span>
+          </a>
+        ))}
+      </nav>
+
+      <div className="mt-section space-y-section">
+        {groups.map((group) => (
+          <section key={group.category} id={group.category} className="scroll-mt-4">
+            <SectionTitle anchor={group.category} right={<span className="mono text-muted">{group.plugins.length}</span>}>
+              <span className="inline-flex items-center gap-2">
+                <PluginIcon icon={{ lucide: group.icon }} className="text-muted" />
+                {group.title}
+              </span>
+            </SectionTitle>
+            <p className="mb-3 max-w-prose text-muted">{group.what}</p>
+            <div className="grid gap-grid grid-cols-[repeat(auto-fill,minmax(340px,1fr))]">
+              {group.plugins.map((entry) => (
+                <PluginCard key={entry.name} entry={entry} highlighted={entry.name === target} />
+              ))}
+            </div>
+          </section>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function PluginCard({ entry, highlighted }: { entry: PluginEntry; highlighted: boolean }) {
+  const options = Object.entries(entry.options.properties ?? {});
+  const required = new Set(entry.options.required ?? []);
+  const RuntimeIcon = entry.runtime === "wasm" ? ShieldCheck : Terminal;
+  const runtimeTone = entry.runtime === "wasm" ? "text-verified" : "text-declared";
+
+  return (
+    <article
+      id={`plugin-${entry.name}`}
+      // The margin clears the section head, which stays stuck to the top
+      // while its cards scroll under it.
+      className={`card card-static flex scroll-mt-14 flex-col gap-3 ${highlighted ? "border-accent" : ""}`}
+    >
+      <header className="flex flex-wrap items-center gap-x-2 gap-y-1">
+        <PluginIcon icon={pluginIcon(entry.name, entry.category)} size={16} className="text-ink" />
+        <h3 className="font-semibold text-ink">{pluginLabel(entry.name)}</h3>
+        <span className="mono text-muted" title="the name a manifest step uses">{entry.name}</span>
+        {entry.plugin !== entry.name ? (
+          <span className="mono text-faint" title="the plugin's own name">{entry.plugin}</span>
+        ) : null}
+      </header>
+
+      <p className="text-muted">{entry.summary}</p>
+
+      <div className="flex flex-wrap items-center gap-1.5">
+        {entry.phases.map((phase) => (
+          <span key={phase} className="chip border-line-strong">{PHASE_LABEL[phase]}</span>
+        ))}
+        <span className={`chip inline-flex items-center gap-1 border-line-strong ${runtimeTone}`}>
+          <RuntimeIcon size={12} aria-hidden /> {runtimeLabel(entry)}
+        </span>
+        {entry.needs?.map((need) => (
+          <span key={need} className="chip border-line-strong" title="asked of the host beyond the tree">
+            needs {need}
+          </span>
+        ))}
+      </div>
+
+      {options.length > 0 ? (
+        <details className="group">
+          <summary className="mono cursor-pointer list-none text-muted hover:text-ink">
+            {options.length} option{options.length === 1 ? "" : "s"}
+            <span className="ml-1 inline-block transition-transform group-open:rotate-90">›</span>
+          </summary>
+          <dl className="mt-2 space-y-2 border-l border-line pl-3">
+            {options.map(([key, option]) => (
+              <div key={key}>
+                <dt className="mono text-ink">
+                  {key}
+                  {required.has(key) ? <span className="ml-1 text-faint" title="required">*</span> : null}
+                </dt>
+                {option.description ? <dd className="text-muted">{option.description}</dd> : null}
+              </div>
+            ))}
+          </dl>
+        </details>
+      ) : (
+        <p className="mono text-faint">takes no options</p>
+      )}
+
+      <a
+        href={pluginSourceHref(entry)}
+        target="_blank"
+        rel="noreferrer"
+        className="mono mt-auto inline-flex items-center gap-1 text-accent hover:underline"
+      >
+        {entry.source} <ArrowUpRight size={12} aria-hidden />
+      </a>
+    </article>
+  );
+}